refactor(contracts): move the command-runtime contracts the daemon reads into @agent-device/contracts

[thymikee]

Summary

Daemon-extraction PR 4a. Moves the pure command-runtime contracts the daemon reads out of the root command-runtime zone into @agent-device/contracts (new narrow subpaths ./backend, ./runtime-contract, ./artifact-adapter, ./backend-snapshot-options, ./command-policy), so no daemon file keeps a type edge into src/ command runtime. Value imports of createCommandSurfaceAgentDevice stay for PR 4b.

Moved declarations (no behavior change): the backend surface (src/backend.ts, R093 rename), the runtime vocabulary (src/runtime-contract.ts, R097), the artifact-adapter vocabulary split from src/io.ts (the node:fs implementation stays; the published agent-device/io surface is unchanged via the public src/sdk/io.ts entry), snapshotOptionsToFlags (src/backend-snapshot-options.ts, R100, test included), and the CommandPolicy presets (from src/command-runtime/runtime-factory.ts, test added at the new owner). 78 consumer files repointed: 66 under src/ outside the daemon, 11 daemon files, 1 test/ harness.

Owner rationale: R18 holds contracts to vocabulary free of host/process/timer mechanics — these declarations are pure types plus literal/pure functions (contracts already carries pure functions like screenshotFlagsFromOptions and depends only on kernel), and contracts sits below the daemon on the spine, so no new package is justified. No existing contracts export changed shape; only five subpaths were added (export snapshot pinned via generate-contracts-exports-snapshot.ts). Known debt the move makes visible: BackendSnapshotResult here vs snapshot-types.ts (different producer/client shapes; unifying is behavior change, not a move).

Remaining daemon → command-runtime edges (pnpm depgraph): exactly 4 value edges, all createCommandSurfaceAgentDevice → command-runtime/runtime-command-surface.ts, from interaction/internal/interaction-runtime.ts, screenshot-runtime.ts, selector-runtime-backend.ts, snapshot-command-runtime.ts.

Validation

Tested commit 8b8f1714e. Serially, all pass: pnpm install --frozen-lockfile && pnpm build, pnpm format, pnpm check:quick, pnpm check:layering, pnpm check:di-seams, pnpm build, plus pnpm check:daemon-wire-compat, pnpm check:gate-manifest, pnpm check:production-exports, and pnpm check:affected --run (449 related test files passed, including the moved backend-snapshot-options.test.ts and the new command-policy.test.ts at their paths).

depgraph summary diff: 1817→1819 files, 9721→9730 edges; R4 0→0, R5 0→0, R6 11→11; src/daemon.ts eager closure 650→651 (ADR 0027 pure-split tolerance; eager-closure gate green); zone SCCs 0→0. Unresolved risks: none local; provider-integration/coverage lanes are CI-owned and were selected by check:affected.

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.16 MB	5.16 MB	-67 B
Package (unpacked)	5.16 MB	5.16 MB	-67 B
Package (download)	1.55 MB	1.55 MB	+15 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	28.1 ms	28.9 ms	+0.9 ms
CLI --help	77.3 ms	81.3 ms	+4.0 ms

[cubic-dev-ai]

All reported issues were addressed across 92 files

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

I found no code problems in 8b8f171, and all 19 checks pass at that head, including the layering and eager-closure gates this move exercises. There are no conflicts, and nothing blocks merge.

Not blocking: the three-line header comment in https://github.com/callstack/agent-device/blob/8b8f171/src/sdk/io.ts#L1 narrates the move, which AGENTS.md keeps out of implementation comments. You can drop it or cut it to one line saying the entry re-exports the contracts artifact-adapter vocabulary. Take it or leave it.

Could this be smaller? I looked and found nothing. The production change is net +33 lines, mostly import repointing, and the move is the smallest way to remove the daemon's type edges into the command-runtime code in src/. The only extra seam is the sdk/io.ts re-export, which the public entry needs.

One open thread still applies: the cubic-dev-ai P2 on command-policy.test.ts (#3394 (comment)). The test never asserts restrictedCommandPolicy().allowLocalOutputPaths === false. The gap came from the deleted runtime-public.test.ts, so it predates this PR. One added assertion closes it, and it does not block merge.

I did not run pnpm depgraph or the eager-closure budget locally. The 650 to 651 closure figure and the claim of exactly 4 remaining daemon value edges come from the PR body and green CI. I also did not build or inspect the emitted dist/src/io.d.ts. Surface parity rests on a source-level comparison of exports and on contracts being bundled.

[thymikee]

Rebased onto main (picks up #3393/#3373; eager-closure budgets, layering and the size ratchet pass on the rebased tree) and addressed the review in 8b1743c:

• cubic P2: command-policy.test.ts now pins restrictedCommandPolicy().allowLocalOutputPaths === false; thread resolved.
• src/sdk/io.ts header cut to one line naming what the entry exports, without the move narration.

[thymikee]

The code looks good at aa31c38, and both items from the earlier review (#3394 (comment)) are fixed. The change since 8b8f171 is one test assertion and a one-line comment. All 19 of 19 checks pass at this commit, and I know of no conflicts. I did not run the layering, eager-closure or size gates locally, so for the rebased tree I rely on your statement and the green CI. I also did not build or inspect the emitted dist io.d.ts. The one cubic-dev-ai P2 thread is fixed at head, since packages/contracts/src/command-policy.test.ts:8 now asserts that restrictedCommandPolicy().allowLocalOutputPaths is false, so you can resolve it: #3394 (comment). Nothing else stands between this PR and merge.

[thymikee]

Closing verification at head aa31c3810:

• Review items: cubic P2 (restricted-preset output denial) pinned at packages/contracts/src/command-policy.test.ts:8, thread resolved; src/sdk/io.ts header is the single-line form. No unresolved threads remain.
• Mergeability: MERGEABLE, merge state CLEAN, ready for review (not draft). Checks: 18/18 pass, 1 skipping (manual device lane).
• Acceptance re-verified on the current tree: grep over src/daemon/** shows zero imports of backend.ts, runtime-contract.ts, io.ts, backend-snapshot-options.ts, or runtime-factory.ts; the only daemon → command-runtime imports left are the 4 createCommandSurfaceAgentDevice value edges (PR 4b).
• Local pnpm install --frozen-lockfile && pnpm build && pnpm format && pnpm check:quick && pnpm check:di-seams && pnpm build pass on this head.

Heads-up (not this PR): scripts/layering/daemon-layers.test.ts (R81) is red on plain origin/main 59d00bed3 — src/daemon/platform-services.ts (#3403) and src/daemon/device/claim-recovery-gateway.ts (#3404) are production daemon files absent from daemon-layer-manifest.json. Reproduced on a clean main worktree, independent of this diff, so a rebase onto today's main would inherit that failure while the PR base itself is green. The manifest's rows belong to the daemon-layer worker, not here.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-11 10:45 UTC