callstack__agent-device/AGENTS.md

# AGENTS.md

`agent-device` is a CLI and daemon for automating Apple, Android, HarmonyOS, Vega, Linux, and web
targets. A long-lived daemon owns sessions; registry-derived commands route to platform runtimes.

## Task routing

Load only the procedures relevant to the task:

| When the task involves | Read |
| --- | --- |
| Domain vocabulary | `CONTEXT.md`, `docs/agents/domain.md` |
| Architecture decisions | `docs/adr/README.md` |
| Tests or gate selection | `docs/agents/testing.md` |
| Selector capture, polling, or interaction fast paths | `docs/agents/selector-capture.md` |
| Adding or changing a CLI flag | `docs/agents/cli-flags.md` |
| Opening or reviewing a PR | `docs/agents/pull-requests.md` |
| Apple runner changes or manual device verification | `docs/agents/device-verification.md` |
| Writing issues or PRDs, and triage labels | `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md` |
| Web backend setup or diagnostics | `docs/agents/web-backend.md` |

Versioned CLI help owns command semantics. Read the relevant topic when behavior is unclear;
normal app-driving startup follows the skill's routing card.

## Incident-derived principles

- Classify interaction dispatch paths in `packages/contracts/src/interaction-guarantees.ts` and
  verify each claim against the native implementation.
- Delegation on error proves no success-path parity. A fast path may succeed on a candidate the
  shared rules would refuse.
- Prove both paths are reachable before measuring a fast path against its baseline.
- Repair recurring failures at the owning type, registry, or construction path; do not add guards
  that reconstruct another source of truth.
- Keep control-flow narration and review history out of implementation comments. Encode invariants
  in names, types, boundaries, and tests; reserve comments for public API docs, tool directives,
  and non-obvious constraints that cannot be encoded.
- Key behavior on typed reasons and details, never error text; do not copy existing message sniffs.
- Keep metadata at response level when it applies to the whole snapshot. Append warnings through
  the shared response builder; never replace prior warnings.
- Before preserving a compatibility shape, run `git tag --contains <commit>`. Unreleased API has no
  external compatibility obligation.

## Declaration sites and enforcement

Read the declaration rather than maintaining a prose copy:

- commands and their surface, runtime-use, batch, and timeout traits:
  `packages/command-registry/src/registry.ts`
- daemon route ownership and request-policy traits: `src/daemon/daemon-command-registry.ts`
- interaction paths and guarantees: `packages/contracts/src/interaction-guarantees.ts`
- canonical command names: `packages/command-registry/src/catalog.ts`
- device runtime-use declarations and fact admission:
  `packages/command-registry/src/registry.ts`, `src/daemon/runtime-admission.ts`, and
  `src/platform-runtime-gateway.ts`
- common command input fields, and which surface may write an input key (model, operator, retired):
  `src/commands/common-input-fields.ts` and `src/commands/input-audience.ts`

Shared selector parsing and matching belongs in `@agent-device/selectors`; request cancellation
and progress in `@agent-device/host-kit/request`; cross-layer contracts in `packages/contracts/src`;
CLI flags in `src/commands/cli-grammar`; cross-surface schema composition in `src/cli-schema`.

Resolve registry completeness failures at the missing declaration. Diagnose other gate failures
at their reported invariant; do not suppress them or add an allowlist to get a pass. Build interaction
responses through `buildInteractionResponseData`; change cross-language rules through golden tables
under `contracts/fixtures/`.

## Hard repository rules

- Plain `.mjs` packaging fixtures that cannot import TypeScript execution helpers keep child-process
  use local and prefer `execFile`.
- Apple target changes keep the kernel device model, runtime-fact admission, dispatch resolution,
  Apple discovery, and xctestrun preparation in sync.
- iOS simulator-set scoping must never hide the host macOS desktop target.
- Skills stay minimal routing cards.
- Add compatibility or fallback behavior only when explicitly requested or approved. Otherwise,
  complete the migration and remove superseded paths.
- Keep changes within one command family or module group unless the task explicitly crosses a
  boundary. Platform-neutral work does not license inspecting every platform implementation.

## Module and test topology

- Name modules for the domain question they answer and colocate machine-readable claims with their
  enforcement. Internal barrels are legacy; add barrels only at package boundaries.
- Implementation files target at most 300 lines. Extract before adding behavior past 500 lines;
  files past 1,000 lines are architecture debt unless generated or fixture data.
- Tests mirror source topology one-to-one. Split a source module and its test together; do not add to
  the legacy `interaction.test.ts` or platform `index.test.ts` aggregations. Pure moves carry their
  tests unchanged; rename-only hunks owe no new coverage.

## Toolchain and worktree traps

- Use `pnpm`; never add `package-lock.json`. OXC owns lint and format. Run `pnpm format`
  repository-wide, not path-scoped.
- A fresh worktree requires `pnpm install --frozen-lockfile && pnpm build`. Until then package and
  optional-peer resolution may point at another checkout and produce false failures.
- Parallel work needs disjoint edit ownership and distinct devices. Run one full gate per host;
  concurrent subprocess-backed suites can produce contention timeouts.
- The layering scan reads tracked files only. Stage a new module before trusting its result.
- Fallow baselines are path-keyed. Move the matching baseline entry when renaming a file; never bulk
  regenerate baselines to accept unrelated findings.

## Runtime and diagnostics seams

Diagnostics use `@agent-device/host-kit/diagnostics`. Request diagnostics belong in the session request log;
session artifact paths come from `src/daemon/session-artifact-paths.ts`. App/device logs remain in `app.log`;
Apple runner and xcodebuild output remains in `runner.log`.

Normalize failures with `normalizeError` and preserve `hint`, `diagnosticId`, `logPath`, and typed
`details`. An interaction taking five seconds or more is a daemon-log question: inspect runner
restart, stale-session recovery, accessibility failure, transport retry, and timeout evidence.

Optional probes and caches are best-effort only when the feature contract says so. Their budgets
must be shorter than the required operation they precede.

## Selector and replay invariants

Element interactions support selector and `@ref`, then record a selector chain after resolution.
Replay failures may re-resolve that chain only to produce a ranked divergence suggestion; ADR 0012
retired silent script rewriting.

Selector keys stay centralized in `@agent-device/selectors`; `is` predicates use
`evaluateIsPredicate`. On macOS, snapshot rectangles are absolute in window space and point actions
translate through the interaction root frame. Prefer selector or ref tests over raw coordinates.

## Documentation ownership

Keep this file to repository traps and routing. Put task procedures in `docs/agents/`, decisions in
ADRs, and command semantics in versioned help. Link to executable registries instead of duplicating
their rules. `CONTEXT.md` is glossary-only: no implementation paths, decisions, or migration status.

Behavior changes update owning help/metadata and user docs. Report docs or skill changes when relevant.