PocketKernel: Apple on-device agent foundation

[NightVibes33]

What changed

• adds Apple On-Device as a first-class AI provider
• makes Apple’s system language model the default routing target
• implements a Foundation Models action planner with structured JSON proposals
• routes eligible composer text through the on-device agent
• renders a dedicated proposal, approval, execution, and result sheet
• executes approved actions through Litter’s existing IshFS / persistent iSH runtime
• supports approved command, file read, file write, and directory listing actions
• persists Apple-local user turns, answers, proposals, approvals, results, and errors per conversation thread
• projects persisted local events into Litter’s native ConversationItem transcript rows
• exposes a confirmed, destructive control for clearing all Apple-local agent history
• keeps OpenAI and OpenAI-compatible servers as optional routes
• preserves the original conversation path for attachments, active turns, and non-Apple providers

Safety boundary

The model only proposes actions. Every command or filesystem action is forced through explicit user approval, including reads and directory listings. Commands, paths, proposal sizes, and write payloads are validated before execution. The exact proposed command, path, and content are shown before approval.

Local transcript behavior

• local events are stored on-device in a versioned compact event format
• transcript history survives view recreation and app relaunches
• each async turn remains permanently bound to its originating thread, even if the user switches conversations while an action is running
• native user, assistant, note, error, command, and file-change rows are reused instead of creating a second fake chat UI
• local user rows are display-only and cannot invoke remote edit/fork behavior
• history is capped per thread to prevent unbounded local storage growth
• clearing history removes all persisted local events and invalidates prior turn bindings so late async results cannot repopulate the wiped timeline

Privacy boundary

• Apple-routed prompts never call the Matrix/server send path
• Apple-local transcript rows are excluded from pinned context and other server-bound context features
• the minigame request path reads only the remote transcript, preventing accidental upload of private local turns
• approval and runtime results remain local unless the user separately sends them through a network provider
• the built-in Apple provider page includes a confirmation-protected Clear On-Device Agent History action
• remote conversations are never touched by the local-history wipe

Runtime behavior

• plain answers remain local and require no execution approval
• relative paths resolve against the active Litter working directory
• command and filesystem output is capped before display
• failed commands surface their exit status and output
• rejecting a proposal executes nothing

CI

• pushes to the feature branch dispatch the real unsigned iOS IPA workflow
• superseded queued or running branch builds are cancelled before the current head is dispatched
• child build logs and diagnostics are mirrored back to the dispatcher workflow

Summary

PocketKernel now has a functioning Apple on-device prompt-to-action path connected to Litter’s real local runtime, with mandatory human approval, persistent native conversation history, strict local/remote isolation, user-controlled local-history deletion, and optional network-provider fallbacks.

[sourcery-ai]

Reviewer's Guide

Adds Apple’s on-device Foundation Models as the default AI provider, introduces a structured local agent proposal/approval pipeline, and keeps network-based OpenAI-compatible providers as optional fallbacks, while tightening JSON validation and persistence behavior.

Sequence diagram for Apple on-device proposal and approval flow

sequenceDiagram
    actor User
    participant AppleOnDeviceAgent
    participant LocalActionApprovalCoordinator
    participant LocalRuntimeCaller

    User->>AppleOnDeviceAgent: propose(userRequest, context)
    AppleOnDeviceAgent-->>User: LocalAgentProposal

    User->>LocalActionApprovalCoordinator: present(proposal)
    LocalActionApprovalCoordinator-->>User: pendingProposal set

    User->>LocalActionApprovalCoordinator: approve(execute)
    alt [proposal.requiresApproval]
        LocalActionApprovalCoordinator->>LocalRuntimeCaller: execute(proposal)
        LocalRuntimeCaller-->>LocalActionApprovalCoordinator: (completion or error)
        LocalActionApprovalCoordinator-->>User: pendingProposal cleared / lastError set
    else [!proposal.requiresApproval]
        LocalActionApprovalCoordinator-->>User: pendingProposal cleared, no execute
    end

Loading

File-Level Changes

Change	Details	Files
Introduce Apple on-device provider as a first-class, default AI backend with routing and persistence support.	Add appleOnDevice provider kind, capabilities, and static profile factory with fixed UUID and default system-language-model Ensure built-in providers include an enabled Apple on-device profile and an OpenAI fallback when loading provider state Default global routing to Apple on-device and use the Apple on-device provider as the preferred provider when the prior preferred provider becomes unavailable Prevent deletion of the Apple on-device provider and disable keychain/secret handling for non-network providers	apps/ios/Sources/Litter/Models/AIProviderModels.swift apps/ios/Sources/Litter/Models/AIProviderStore.swift
Add Apple on-device agent that turns user requests into validated, structured local action proposals and introduce a centralized approval coordinator before executing local actions.	Define LocalAgentProposal type with explicit action kinds, risk, and requiresApproval flag, plus strict decoding and validation of model-produced JSON Implement AppleOnDeviceAgent actor that uses SystemLanguageModel (FoundationModels) to generate proposals with guardrails and robust availability/error handling Add LocalActionApprovalCoordinator to present, approve, or reject proposals and enforce that execution only occurs via an explicit approval callback	apps/ios/Sources/Litter/Models/AppleOnDeviceAgent.swift
Support health-checking Apple on-device provider and refine provider/network behavior and status messaging.	Short-circuit provider health checks for appleOnDevice by consulting AppleOnDeviceAgent availability and returning a healthy report with the default model when available Guard normalizedBaseURL and secret storage/loading on requiresNetwork capability to avoid treating local providers as networked Adjust AIProviderHealthReport summary wording from Reachable to Ready and perform minor refactors/compactions in AIProviderStore networking and persistence helpers	apps/ios/Sources/Litter/Models/AIProviderStore.swift apps/ios/Sources/Litter/Models/AIProviderModels.swift

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.