refactor: consolidate Apple platform internals by thymikee · Pull Request #968 · callstack/agent-device

thymikee · 2026-06-30T15:37:48Z

Summary

Move shared Apple-platform implementation into src/platforms/apple/core, retarget internal callers directly to those Apple modules, and split macOS leaf code under src/platforms/apple/os/macos.
Add visionOS runner profile/build-cache groundwork while keeping watchOS out of scope.
Remove the inert iOS runner request-count gate and its related runtime surface, including cost.runnerRoundTrips, because recent successful main runs captured zero runner round trips and the signal was not proving runner behavior.
Retire plans/apple-platform-consolidation.md; ADR-0009 now owns the decision and plans/phase3-platform-plugin-progress.md tracks the remaining follow-ups.

Rebased onto current main after #967 merged. Scope is 164 touched files across Apple platform internals, tests, runner build scripts, Fallow move metadata, CI cleanup, Xcode project metadata, request-count cleanup, and roadmap docs. Remaining Apple work is explicit follow-up: public Platform collapse, tvOS leaf, plugin facets, per-AppleOS capability table, and the watchOS unsupported sentinel.

Validation

pnpm format
pnpm check:tooling
pnpm check:quick
pnpm check:fallow --base origin/main
pnpm exec vitest run src/daemon/__tests__/request-router-cost.test.ts src/daemon/__tests__/request-router-response-level.test.ts
pnpm exec vitest run src/platforms/ios/__tests__/apple-runner-platform.test.ts src/platforms/ios/__tests__/runner-command-retry.test.ts src/platforms/ios/__tests__/runner-session.test.ts src/daemon/handlers/__tests__/session.test.ts
git diff --check
Previously on this worktree before the rebase: pnpm build, pnpm exec vitest run src/platforms/ios/__tests__, runner-focused Vitest suite, pnpm build:xcuitest, pnpm build:xcuitest:visionos, and git diff --check. visionOS runtime was installed and the XCUITest build passed, but no Vision Pro simulator instance existed for live interaction verification.

github-actions · 2026-06-30T15:38:21Z

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-30 19:31 UTC

github-actions · 2026-06-30T15:39:14Z

Size Report

Metric	Base	Current	Diff
JS raw	1.4 MB	1.4 MB	-2.0 kB
JS gzip	450.4 kB	450.2 kB	-187 B
npm tarball	549.4 kB	549.4 kB	-13 B
npm unpacked	1.9 MB	1.9 MB	-345 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.2 ms	27.3 ms	+0.1 ms
CLI --help	47.4 ms	48.0 ms	+0.6 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
`dist/src/cli.js`	-16.1 kB	-5.1 kB
`dist/src/generic.js`	+9.0 kB	+3.5 kB
`dist/src/495.js`	+5.7 kB	+2.1 kB
`dist/src/2948.js`	-9 B	-82 B
`dist/src/9722.js`	+268 B	-28 B

thymikee · 2026-06-30T16:06:27Z

Review — actionable items

Verified the relocation is a clean byte-identical move (runner stack + ~46 apple/core files are import-path-only; all ios/* are one-line shims; no phase strings / command names / runner round-trip logic changed; tsc + lint + runner/apple unit tests pass; full-suite failures are only the known Android fillAndroid timeout flakes, which pass in isolation). Action items:

Resolve the src/daemon/request-router.ts conflict with main toward the import. This PR reintroduces the local const RUNNER_ROUND_TRIP_PHASES = [...] that ci: automate iOS runner request-count gate for the Apple runner unwind (Phase 3 step c prep) #966 removed; main now does import { RUNNER_ROUND_TRIP_PHASES } from './runner-request-count.ts'. On retarget to main, keep main's import (single source of truth), drop the reintroduced local const.
Arm the runner request-count gate so this PR is proven byte-identical, not just asserted. The baseline (scripts/runner-request-count/expected-counts.json) is still established: false, so the gate is inert. The relocation is gate-friendly (phase strings + skip logic moved unchanged; the gate counts by phase from daemon.log), so after rebasing onto main: arm the baseline from a pre-move count, then let smoke-ios confirm the count is unchanged.
src/platforms/apple/core/apple-runner-platform.ts: confirm the disallowed SDK-list edits to existing rows are safe. The iOS/tvOS/macOS profile disallowed lists each gained 'xros'/'xrsimulator' — not additive. Verify this can't reject an xctestrun product those platforms previously accepted.
src/kernel/device.ts: fix the stale comment. It still says watchOS/visionOS default to the iOS profile, which is no longer true after resolveRunnerPlatformNameForAppleOs added the visionos case.
Rewire apple/core intra-package imports to siblings (follow-up OK). Moved files import their siblings via the old ios/ shims (e.g. apple/core/runner/runner-session.ts → ../../../ios/runner-contract.ts), so apple/core still depends backward on the layer it supersedes. Functional, but a tightening pass should point intra-core imports at siblings and keep ios/ shims only for external callers.
Confirm the fix: respect prepare timeout for runner health checks #967 health-timeout change (session.ts resolvePrepareIosRunnerHealthTimeoutMs) is meant to land via this PR. It's a real runner health-timeout behavior change unrelated to the consolidation, riding along from the stacked base.

thymikee · 2026-06-30T16:36:19Z

Addressed the review items after rebasing onto current main:

Rebased refactor: consolidate Apple platform internals #968 onto origin/main; fix: respect prepare timeout for runner health checks #967 is now in main, so the PR is back to one commit on top of main.
src/daemon/request-router.ts now keeps main’s RUNNER_ROUND_TRIP_PHASES import; the local const is not in this PR.
The fix: respect prepare timeout for runner health checks #967 health-timeout behavior is no longer riding as a stacked commit; it is only present through main.
Fixed the stale src/kernel/device.ts comment so visionOS is no longer described as defaulting to iOS.
Removed the xros/xrsimulator additions from existing iOS/tvOS/macOS disallowed hint lists, keeping those profiles byte-identical. Added a focused test asserting existing disallowed hints remain unchanged and visionOS owns the xros/xrsimulator exclusions.

Request-count gate note: I did not arm scripts/runner-request-count/expected-counts.json with zeroes. The latest successful main iOS workflow (28455877600) logged runnerRoundTrips=0 and marked the gate inconclusive, so there is no usable pre-move non-zero baseline to commit from CI. Local validation for this update:

pnpm format
pnpm check:quick
pnpm check:fallow --base origin/main
pnpm exec vitest run src/platforms/ios/__tests__/apple-runner-platform.test.ts
pnpm exec vitest run src/platforms/ios/__tests__/runner-command-retry.test.ts src/platforms/ios/__tests__/runner-session.test.ts src/daemon/handlers/__tests__/session.test.ts

thymikee · 2026-06-30T16:57:02Z

Re-reviewed the current clean #968 head (8ca1ca5) against the prior actionable items, plans/perfect-shape.md, and ADR-0003 boundaries.

The PR is now based on main; src/daemon/request-router.ts uses the mainline RUNNER_ROUND_TRIP_PHASES import, the #967 health-timeout change is no longer part of this branch, the src/kernel/device.ts visionOS/watchOS comment is corrected, and the existing iOS/tvOS/macOS xctestrun disallowed hints are preserved with a focused test while visionOS owns xros/xrsimulator. The remaining apple/core imports through iOS shim paths are the already-called-out follow-up tightening, not a behavior blocker.

The runner request-count gate is still not armed, but the follow-up note explains why: latest successful main iOS workflow had runnerRoundTrips=0, so there is no useful non-zero baseline to commit. Given the move keeps runner phase strings and request-router counting source on main, I would treat that as residual risk rather than blocking this consolidation.

Checks are green, including Typecheck, Unit Tests, Integration Tests, Smoke Tests, Fallow Code Quality, Lint & Format, Swift Runner Unit Compile, Web Platform Smoke, iOS Runner Swift Compatibility, and deploy-preview. I do not see an actionable blocker; ready for maintainer review.

thymikee · 2026-06-30T17:20:52Z

Follow-up on the request-count gate: removed it instead of trying to arm it with zero.

The latest two successful main iOS workflow runs both observed runnerRoundTrips=0 and marked the gate inconclusive, so the gate was not proving runner behavior. This update removes:

the iOS workflow Assert iOS runner request count step
validate:runner-count
scripts/runner-request-count/*
the harness-only src/daemon/runner-request-count.ts module and tests

The runtime cost.runnerRoundTrips response field remains intact and covered by focused request-router tests; only the broken CI harness is gone.

thymikee · 2026-06-30T17:30:16Z

Dropped the request-count gate and the related runtime surface instead of carrying a half-working signal.

What it was trying to catch: accidental runner behavior drift, mainly extra XCTest runner round trips per logical command, duplicate sends after fallback/retry changes, or a refactor accidentally bypassing the runner for an action that should use it.

Why I removed it: the latest successful main evidence captured runnerRoundTrips=0, so the gate could not distinguish good behavior from broken instrumentation. Keeping cost.runnerRoundTrips would expose an unreliable number in the daemon contract.

Replacement direction: rely on focused live e2e/smoke verification for the user-visible paths (open/snapshot/click/wait/close) plus request diagnostics artifacts when debugging performance. If we bring a count gate back, it should first prove non-zero runner events in a live e2e path and fail when capture is zero; otherwise it is only checking plumbing.

thymikee · 2026-06-30T17:35:51Z

Head changed after the prior readiness review (now at 415672e), and the iOS smoke check is still in progress. I removed ready-for-human for now; please wait for checks to settle and re-review this head before restoring the label.

thymikee · 2026-06-30T17:57:45Z

Re-reviewed current clean head 415672e against plans/perfect-shape.md and ADR 0003.

The only delta since my prior clean review is removal of the runner request-count gate and cost.runnerRoundTrips surface. That cleanup is consistent: request-router no longer computes the metric, the public ResponseCost type and cost tests no longer expose it, package/workflow hooks are removed, and checks are green. This also avoids preserving an inconclusive gate whose recent main baseline reported zero runner round trips.

Residual risk remains as previously noted: the Apple core move still has compatibility shim imports through src/platforms/ios, and visionOS has build-cache groundwork without live Vision Pro simulator interaction evidence. I do not see an actionable blocker on this head; ready for maintainer review.

thymikee · 2026-06-30T18:36:16Z

Re-checked current clean head 44c76dd. The delta from the previously reviewed 415672e head is docs/plans only: ADR 0009 now records the shipped/deferred Apple consolidation status, the obsolete standalone Apple plan was removed, and perfect-shape/phase3 progress links now point at ADR 0009 plus phase3-platform-plugin-progress.md.

No code, routing, runner, command-surface, or platform backend behavior changed in this head. Checks remain green, and the existing ready-for-human label is still appropriate.

…) (#969) Post-#968 follow-up: the OS-agnostic Apple runner engine moved from src/platforms/ios/ to src/platforms/apple/core/, but several docs/config still pointed at the old locations, misleading agents that grep those paths. - AGENTS.md: repoint the runner-seam map, the Apple-family sync rule, the record/trace seam, the search-roots hint, and the platform-backends list at src/platforms/apple/core/...; rename "iOS Runner Seams" -> "Apple Runner Seams". - .fallowrc.json: drop the two stale ignoreExports entries for the removed src/platforms/ios/apps.ts and src/platforms/ios/index.ts (the live src/platforms/apple/core/apps.ts entry already covers those test-only exports). - ios-runner/{README,RUNNER_PROTOCOL}.md: point the TypeScript-client links at src/platforms/apple/core/runner/runner-client.ts. Docs/config only; no behavior change. fallow audit + build/lint stay green, and a live iOS simulator replay suite (6/6) confirms the consolidated runner works.

PR #968 (apple-platform-consolidation) accidentally dropped the runnerRoundTrips field from the agent-cost block during an over-broad conflict resolution. This restores the shipped Phase-4 feature: - src/kernel/contracts.ts: re-add ResponseCost.runnerRoundTrips: number - src/utils/diagnostics.ts: restore the countDiagnosticEventsByPhase() accessor over the flush-surviving phaseCounts tally (the tally itself survived #968; only the accessor was removed) - src/daemon/request-router.ts: repopulate runnerRoundTrips in the cost graft by counting the two real round-trip diagnostic phases (ios_runner_command_send + ios_runner_readiness_preflight). The RUNNER_ROUND_TRIP_PHASES constant is now defined locally (its former home, the dev-only runner-request-count.ts, was removed in #968 and is out of scope to restore) - request-router-cost.test.ts: restore the round-trip counting test and the runnerRoundTrips:0 assertion Byte-identical-default invariant preserved: with --cost OFF or on an error response the serialized payload is unchanged.

…n Phase 3 plan (#971) The Step (c) request-count bullet claimed both the dev-only CI gate AND the runtime `cost.runnerRoundTrips` surface were removed in #968. #970 restored the public agent-cost field, so the bullet is stale/misleading for the next Apple/agent-cost worker. Split the bullet: the dev-only request-count CI gate (the #966 --debug ndjson counter + smoke-ios assertion) stays removed (zero runner events on main runs); the runtime `cost.runnerRoundTrips` agent-cost field (ResponseCost / buildResponseCost over RUNNER_ROUND_TRIP_PHASES) is a separate pre-existing surface, restored in #970, and remains part of the agent-cost contract.

…s/apple/core (#980) (#983) After #968 moved the OS-agnostic Apple engine to src/platforms/apple/core/, its tests still lived in src/platforms/ios/__tests__/. Move the 19 that test Apple engine code into src/platforms/apple/core/__tests__/ so tests sit beside their source, re-relativizing every import / dynamic import / vi.mock / vi.importActual specifier to the new depth. Deferred (still in src/platforms/ios/__tests__/): recording-scripts.test.ts and runner-client.test.ts — both compute runtime fs paths (__dirname / fileURLToPath) to ios-runner artifacts, so they need path-string fixes, not just specifier re-relativization. Tracked under #980. Pure test relocation — no source or behavior change. tsc + oxlint + oxfmt green; the moved suites pass (384 tests across the apple + deferred dirs).

thymikee force-pushed the refactor/apple-platform-consolidation branch from 6e2e73e to 3162a65 Compare June 30, 2026 15:54

Base automatically changed from fix/prepare-runner-health-timeout to main June 30, 2026 16:27

thymikee force-pushed the refactor/apple-platform-consolidation branch from 3162a65 to 8ca1ca5 Compare June 30, 2026 16:35

thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Jun 30, 2026

thymikee force-pushed the refactor/apple-platform-consolidation branch from 8ca1ca5 to 8510875 Compare June 30, 2026 17:20

thymikee force-pushed the refactor/apple-platform-consolidation branch from 8510875 to 415672e Compare June 30, 2026 17:29

thymikee removed the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Jun 30, 2026

thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Jun 30, 2026

thymikee force-pushed the refactor/apple-platform-consolidation branch from 415672e to 44c76dd Compare June 30, 2026 18:17

refactor: consolidate Apple platform internals

171f4d0

thymikee force-pushed the refactor/apple-platform-consolidation branch from 44c76dd to 171f4d0 Compare June 30, 2026 19:17

thymikee merged commit 26ac865 into main Jun 30, 2026
22 checks passed

thymikee deleted the refactor/apple-platform-consolidation branch June 30, 2026 19:30

This was referenced Jun 30, 2026

feat: add hosted WebDriver provider support #948

Merged

docs: fix stale platforms/ios paths after Apple consolidation (#968) + remaining-work plan #969

Merged

fix: restore runnerRoundTrips agent-cost field dropped in #968 #970

Merged

thymikee mentioned this pull request Jul 1, 2026

docs: distinguish removed request-count CI gate from restored cost.runnerRoundTrips (Phase 3 plan) #971

Merged

This was referenced Jul 1, 2026

Phase 3 — finish the Apple PlatformPlugin model (steps b + d) #972

Open

cleanup: relocate Apple unit tests out of src/platforms/ios/__tests__ #980

Closed

test: relocate Apple engine unit tests into platforms/apple/core (#980) #983

Merged

thymikee mentioned this pull request Jul 1, 2026

test: relocate remaining Apple-engine unit tests to apple/core (#980) #989

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor: consolidate Apple platform internals#968

refactor: consolidate Apple platform internals#968
thymikee merged 1 commit into
mainfrom
refactor/apple-platform-consolidation

thymikee commented Jun 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

thymikee commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Uh oh!

github-actions Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Size Report

Uh oh!

thymikee commented Jun 30, 2026

Review — actionable items

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

thymikee commented Jun 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

thymikee commented Jun 30, 2026 •

edited

Loading

github-actions Bot commented Jun 30, 2026 •

edited

Loading

github-actions Bot commented Jun 30, 2026 •

edited

Loading