refactor(platform-apple): derive the runner host port instead of mirroring host-kit by thymikee · Pull Request #2689 · callstack/agent-device

thymikee · 2026-09-19T13:46:48Z

Summary

runner/host.ts was a hand-maintained mirror of host-kit. It is now derived from the modules it fronts, keeping the R77 seam and the eager-closure property. Closes #2658. 34 files touched.

Types. The ~100-line copied block is gone. The 23 runner files that used those types take them from the owning package with import type (R77 exempts type-only imports). DefinedEnvMap was never a host capability — it moves to its only caller.
Interface. AppleRunnerHost is Picks over import type * as namespaces of host-kit, kernel, provision-kit and the Apple-owned core modules. No signature is written here.
Delegators. The 41 named exports stay, typed by derivation through delegate(name); the 28 importers are unchanged. The Deadline object shim stays.
Binding. core/runner-host.ts keeps naming each import rather than spreading the modules whole — see Rejected below. It holds names only; it re-types nothing.

Host-kit gains three type exports the port needs by name and no behavior change: ExecStreamOptions, DiagnosticEventInput, and DeadlineClock — the read side of Deadline, which the class now implements and which RetryOptions.deadline accepts, so a test host can keep substituting its own clock now that the port no longer declares a structural copy.

The runner-facing slice of physical-device control moves to core/physical-device-routing.ts, below both sides. Without it the port reaches physical-device-control.ts, whose launch/terminate members are typed against the runner's own command executor — a 19-file type cycle that fails R9/R10.

Replay. #2599 (ExecBackgroundOptions = Omit<ExecOptions, 'timeoutMs'>) becomes a zero-line change here. #2598 and #2595 each drop from 11 and 3 lines in host.ts to 2: their type and signature changes are free, and what remains is the new capability itself — one Pick name plus one delegate line, as the issue predicts.

host.ts: 403 → 187 LOC (≈137 code, ≈50 doc). The issue's ≈120 estimate did not count the preserved R77 header.

Known consequence. Deriving from typeof HostCommand drops the old ExecOptions narrowing, so cwd, binaryStdout and stdin are now reachable through the port. That narrowing existed to keep the mirror small ("narrowed to what the runner uses"), and restoring it means re-declaring the exec signatures by hand — exactly what this PR deletes. The runner modules now import ExecOptions from host-kit directly anyway, so the port could not enforce it either.

Rejected. The issue's binding spreads the modules whole. Measured, that puts every export of all sixteen on the host object (41 members → 128), ships +1.8 kB including the vitest-only resetAllProcessMemosForTests, and makes a name shared by any two of them silently rebind a capability — a tripwire across four packages, catchable only at runtime. The issue's caveat licenses the named binding; tsc stays the sole enforcer of completeness.

Validation

Tested at 5b29c32 (pre-push amend of the pushed head; tree identical).

Green: pnpm typecheck, pnpm check:layering (R77 and R13 untouched; R9 back to the merge-base's 6-file max), pnpm check:production-exports, pnpm check:fallow (no issues in 35 changed files), pnpm lint, pnpm format:check, pnpm build, pnpm check:package, pnpm check:bundle-owner-files, pnpm check:gate-manifest, pnpm depgraph:test, the apple-runner project (49 files / 480 tests), and the eager-closure budget suite (666 tests) — the seven Apple façade closures do not grow.

pnpm check:affected --run fails only its vitest lane, on three tests that fail identically on a clean origin/main checkout in this container (root user, so their chmod-based unwritable-path setup is a no-op): app-log-session-resource.test.ts > unwritable tombstone plus rejecting cleanup blocks same-process replacement, capture-kit durable-capture/adoption.test.ts > a failed terminal transition…, capture-kit durable-capture-resource.test.ts > an unconfirmed failed-adoption cleanup…. Everything else in pnpm test:unit passes (10470 tests). CI on Linux runners is the authority here.

No device-facing behavior changes: the port's runtime shape is the same object bound to the same functions.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PPceQTJdXsEJaZsBM8ycek

Generated by Claude Code

…oring host-kit `runner/host.ts` was a hand-maintained mirror of host-kit: ~100 lines of copied type declarations, a 50-member interface re-declaring every signature, and 50 delegators, so every host-kit change was re-typed here by hand. The port now derives from the modules it fronts. `AppleRunnerHost` is a set of `Pick`s over `import type * as` namespaces -- type-only declarations R77 and the eager-closure gate see nothing of -- so a host-kit signature change reaches the runner with no edit here, and the `Pick` list is the single place that says what the runner may reach. Delegators keep their names through a `delegate(name)` helper typed by derivation, so the 28 importers are unchanged. `core/runner-host.ts` keeps naming each import rather than spreading the modules whole: spreading drops its list but puts every export of all sixteen modules on the host object (41 members to 128, +1.8 kB shipped including a vitest-only memo reset) and lets a name shared by two of them silently rebind a capability. The binding holds names only; it re-types nothing. The runner modules take the types they use straight from the owning package with `import type`. `DefinedEnvMap` was never a host capability and moves to its only caller. Host-kit gains three type exports the port needs by name -- `ExecStreamOptions`, `DiagnosticEventInput`, and `DeadlineClock`, the read side of `Deadline` that a test host substitutes a clock for -- and no behavior change. The runner-facing slice of physical-device control moves to `core/physical-device-routing.ts`, below both sides, so the port does not reach the control module, whose launch and terminate members are typed against the runner's own command executor (R9/R10 type cycle). `host.ts`: 403 -> 187 LOC. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PPceQTJdXsEJaZsBM8ycek

github-actions · 2026-09-19T13:48:19Z

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	4.64 MB	4.61 MB	-21.9 kB
Package (unpacked)	4.64 MB	4.61 MB	-21.9 kB
Package (download)	1.38 MB	1.37 MB	-8.8 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.4 ms	27.1 ms	-0.2 ms
CLI --help	77.9 ms	79.3 ms	+1.4 ms

thymikee · 2026-09-19T14:30:33Z

Reviewed at 172f58e. No blocking findings: the port is now derived from the modules it fronts, the mirror is gone, and the change removes about 175 net production lines. The whole-module spread binding from the issue was measured and rejected in the PR body (41 to 128 members, +1.8 kB, and silent rebinding when two modules export the same name), and that reason holds. Not blocking: delegate() casts through unknown[], so forwarded arity is checked only at call sites, which tsc already covers. CI is green.

github-actions · 2026-09-19T18:40:23Z

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-19 18:40 UTC

The #2689 host port derives its types from host-kit namespaces and no longer mirrors them, so the adoption test imports DiagnosticEventInput from @agent-device/host-kit/diagnostics like every other runner test.

…ure assertion body #2689 derived the runner host port from the modules it fronts, so `ExecResult` is read from `@agent-device/host-kit/command` now rather than restated in `runner/host.ts`. The per-fixture assertion body had grown past the complexity the Fallow audit allows a changed file: the envelope checks move into `assertFailureEnvelope` and the tool-output check into `assertToolOutputReachable`, so each recorded shape is still asserted through the same path and the test body reads as one call.

… host port #2689 rewrote the runner host port to derive its types from host-kit and the owning core modules instead of mirroring them, which left this branch naming types that no longer exist there: - Derive `IosDeviceRunnerReadiness` from the control port's own return type rather than restating the device's states and remedies beside them. - Take `IosPhysicalDeviceRunnerControl` from `core/physical-device-routing.ts` and `ExecResult` from `@agent-device/host-kit/command`, which is where the port now points callers.