Imported from hearnadam/remote-control (AGENTS.md). Install upstream with npx skills add hearnadam/remote-control. Copyright stays with the author.

AGENTS.md

Project Shape

• This is an Xcode-only iOS app; the project is RemoteControl/RemoteControl.xcodeproj and the only scheme is RemoteControl. The app's bundle ID is ai.hearn.RemoteControl.
• App sources live in RemoteControl/RemoteControl/; unit tests live in RemoteControl/OpenCodeTests/ (target RemoteControlTests); there is no Swift Package manifest.
• Build settings enable SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor; be explicit before moving work off the main actor.

Commands

• List schemes/destinations: xcodebuild -project "RemoteControl/RemoteControl.xcodeproj" -list and xcodebuild -project "RemoteControl/RemoteControl.xcodeproj" -scheme RemoteControl -showdestinations.
• Simulator unit tests: xcodebuild -project "RemoteControl/RemoteControl.xcodeproj" -scheme RemoteControl -destination 'platform=iOS Simulator,name=iPhone 17 Pro' -only-testing:RemoteControlTests test.
• Device build: xcodebuild -project "RemoteControl/RemoteControl.xcodeproj" -scheme RemoteControl -destination 'platform=iOS,id=00008150-000C70D03A40401C' -derivedDataPath "RemoteControl/DerivedDataDevice" build.
• Deploy to the connected phone after building: xcrun devicectl device install app --device 00008150-000C70D03A40401C "RemoteControl/DerivedDataDevice/Build/Products/Debug-iphoneos/RemoteControl.app" then xcrun devicectl device process launch --device 00008150-000C70D03A40401C ai.hearn.RemoteControl.
• Xcode may report the same phone as 00008150-000C70D03A40401C even if devicectl list devices shows a different CoreDevice UDID; prefer the ID from xcodebuild -showdestinations for xcodebuild.
• Lint: swiftlint from the repo root (config in .swiftlint.yml). swiftlint --fix autocorrects safe style violations (opening-brace spacing, trailing commas, colon spacing, etc.). Install via brew install swiftlint.

Build Artifacts

• Do not commit RemoteControl/DerivedData* or RemoteControl/build/; remove ad-hoc device derived data before committing if it appears in git status.
• Root .gitignore ignores root DerivedData/ and build/, but nested derived-data directories can still show up if created under RemoteControl/ with nonstandard names.

Chat Scroll Behavior

• The message list should use defaultScrollAnchor(.bottom) plus one derived isPinnedToBottom state from onScrollGeometryChange; do not replace this with send-specific state machines or repeated delayed animated scrollTo calls.
• Initial transcript hydration must not run animated scrollTo or whole-list message animations. Let the default bottom anchor position the first non-empty load, then enable pinned-bottom corrections only after the initial messages have rendered.
• Auto-follow is only appropriate while pinned to bottom. Update isPinnedToBottom from user scroll geometry, keep it true when the user taps the down button, and avoid fighting user scroll gestures.
• Keyboard/safe-area changes can require a non-animated bottom correction after the first render; animated corrections during load or keyboard resize can cause jumps, black overscroll, or apparent freezes.
• Composer send should keep focus active so the keyboard stays up after sending; this is independent from transcript scroll state.

OpenCode Server API Contracts

• The iOS API model is in RemoteControl/RemoteControl/OpenCodeAPI.swift; compare it against the sibling server repo ../opencode before changing wire models.
• Server SSE /event streams objects shaped as { "type": ..., "properties": ... } from ../opencode/packages/opencode/src/server/routes/instance/event.ts; do not assume a nested payload wrapper is the only format.
• Permission events are permission.asked with Permission.Request fields and permission.replied with { sessionID, requestID, reply }; they are not permission.updated, permissionID, or response.
• Permission replies should use /permission/:requestID/reply with body { reply, message? }; avoid the deprecated session endpoint /session/:sessionID/permissions/:permissionID with { response }.
• Prompt input parts sent by iOS are server MessageV2.*PartInput drafts: file attachments use { type: "file", mime, filename?, url }, where url is a data:<mime>;base64,... URL.

Event Decoding

• OpenCodeEvent is a discriminated enum with one case per Event.<type> in ../opencode/packages/sdk/openapi.json (components.schemas.Event). The wire→case mapping lives in OpenCodeEvent.init(from:) in OpenCodeAPI.swift.
• Payload structs match each schema's properties field-for-field (required vs optional from the spec). When adding a new server event: add the case, the payload struct, and the switch arm; pull a representative JSON fixture from openapi.json for the test.
• Forward-compat: unknown type values decode as .unknown(type:properties:) rather than throwing — adding a server event no longer breaks the client; we just don't react to it until we add a case.
• Both flat ({type, properties}) and nested ({payload: {type, properties}}) wrappers are accepted; the server uses both depending on which route emitted the event.
• Decoder tests live in RemoteControl/OpenCodeTests/OpenCodeTests.swift. Reducer tests for state transitions live in SessionReducerTests.swift.

Session State Architecture

• Session-scoped state is modeled as SessionState (a value type in RemoteControl/RemoteControl/SessionState.swift) and transitioned by SessionReducer.reduce(_:_:sessionID:) (in SessionReducer.swift).
• The reducer is pure: imports only Foundation, no URLSession, no Task, no @Published, no logging. House rules are documented at the top of SessionReducer.swift — keep them.
• The view model holds private var sessionStates: [String: SessionState] keyed by session ID. Reducer-modeled session projection events route through event.targetSessionID(selected:) regardless of which session is currently selected, so background sessions stay current. Do not route session events the reducer does not handle just to create empty cache entries.
• The VM's @Published var messages / pendingPermission / sessionStatus / hasMoreMessages / abortedMessages are mirrors of sessionStates[selectedSession?.id], refreshed by syncFromState(). Mutations should go through updateState(for:_:) (or the reducer directly) — never assign to the published mirrors directly, or the cache and UI drift.
• SessionStatus mirrors server session.status (idle / busy / retry) plus synthetic .error from session.error. Connection state is not a SessionStatus; sessionStatus: String is only the legacy bridge that overlays disconnected/reconnecting for old views. Do not set it to connected directly.
• Local optimistic user messages have SessionState.localSendStatus: queued means local-only and not visible to the server/model yet, sending means the POST is in flight, accepted means the server accepted but events/REST have not reconciled, and failed means not confirmed by the server. The original payload (text, attachments, model, provider, directory) is mirrored in SessionState.pendingSends so reconnect/retry can replay the request without re-reading the composer. Both maps are cleared by the reducer when the server echoes the message back (real ID swap) or removes it.
• Queued messages auto-flush on every successful connect via OpenCodeViewModel.flushQueuedMessages — one drain task per session, FIFO by transcript order, guarded by flushingSessions so concurrent reconnects don't double-send. A hard send failure stops that session's flush (so we don't hammer a dead server) and the offending message lands in .failed; the user can long-press the bubble to Retry (returns it to .queued and re-kicks the loop) or Delete (purges from cache without a server call). .sending/.accepted are mid-flight and intentionally not user-actionable from the context menu — wait for the SSE swap.
• When fetching messages for a background session (for example after an orphan message.part.updated), resolve that session's directory override or stored session.directory; do not use activeDirectory, which belongs to the selected session.
• Per-session caches survive session switches: select() restores from sessionStates[id] synchronously then merges the latest page in the background. Switching sessions no longer wipes transcripts.

Session / Message Wire Contract

The server stores sessions and messages in SQLite with event-sourced projections. The iOS client should treat local caches as mutable projections, not append-only logs.

Mutability

• message.updated and message.part.updated are upserts: existing rows are replaced by matching id.
• message.removed and message.part.removed delete rows permanently.
• iOS must handle removals or reconcile with the server’s latest page to avoid stale UI.

Forking

• POST /session/:sessionID/fork clones messages/parts up to an optional messageID into a new child session.
• Forks get new message/part IDs and set parentID on the new session.
• They are not branches inside the same session.

Revert

• Revert prunes messages/parts after a target point and restores a snapshot.
• It emits removal sync events, shrinking visible history.
• After a revert, new prompts continue in the same session.

Pagination

• GET /session/:sessionID/message?limit=&before= loads older messages with an opaque cursor.
• There is no after cursor for “newer than cached.”
• Refresh strategy: fetch the latest page, upsert matching IDs, append new IDs, and prune stale entries only when a removal/revert is known or after a full authoritative refresh.

Storage schema (source of truth)

• SessionTable: id, project_id, workspace_id, parent_id, slug, directory, path, title, version, share_url, summary_*, revert, permission, timestamps
• MessageTable: id, session_id, time_created, data (JSON blob of MessageV2.Info minus id/sessionID)
• PartTable: id, message_id, session_id, time_created, data (JSON blob of MessageV2.Part minus id/sessionID/messageID)
• TodoTable: session_id, content, status, priority, position
• Messages/parts reference sessions with onDelete: cascade