callstack / callstack/agent-device

iOS snapshot backend convergence and fast Simulator observation

Open
#2,188 2 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
4.6k
Forks
299
Avg merge
10h 17m
Merged PRs (30d)
515

Description

## Outcome

Converge iOS snapshot acquisition behind one host presentation interface while adding a fast local
Simulator observation path. Every producer reports facts; one engine owns projection, geometry,
scope, depth, actionability narrowing, semantic compaction, invariants, and publication.

This tracker deliberately separates issues (durable outcomes) from PRs (narrow review slices).
Children may use stacked PRs, but every PR must preserve the dependency and proof requirements of
its owning issue.

## What success changes

- Local Simulator observation no longer waits for XCTest runner readiness when the bridge is eligible.
- XCTest remains the interaction and typed-fallback path.
- Simulator bridge, XCTest, Appium/WebDriver, and Limrun use one meaning for regular/raw,
interactive-only, depth, and scope to the extent their declared acquisition evidence permits.
- Swift and TypeScript geometric presentation stay consistent through independent goldens,
differential fuzzing, and structural invariants.
- `agent-device proxy` performs acquisition and presentation on the daemon host and transfers only
the published response, with explicit remote latency and lease-isolation acceptance.
- Superseded backend-name policy and duplicate orchestration become deletion-ready.

## Non-goals

- Physical-iPhone startup, signing, installation, transport, or runner retention.
- Replacing XCTest interactions or custom-action invocation.
- Redesigning Android acquisition.
- A generated presentation-rule language, shared C++/Rust/WASM implementation, or new public
backend-selection flag.
- Closing or silently absorbing #1626 before its separate product decision.

## Invariants

1. Acquisition and presentation remain separate concepts.
2. Geometric presentation occurs exactly once.
3. `interactive ⊆ regular ⊆ raw` is asserted over one acquisition.
4. Raw depth is acquisition traversal depth; regular depth is the presented frontier.
5. Missing evidence is never upgraded, especially hittability and viewport evidence.
6. Producer differences enter through typed capabilities and residue, never producer-name branches.
7. Bridge fallback is typed, attempted at most once, and shares the original request deadline.
8. Runner-presented output still crosses implementation-independent host invariants.
9. Internal stage, hint, lineage, generation, and quality contracts do not become required RPC fields.
10. Physical-device behavior and performance remain unchanged.

## Related work

- #1797 is closed architectural groundwork; this tracker does not reopen it.
- #1626 remains held and separate. Its deep-button false-failure reproduction becomes permanent
evidence without changing that issue's status or proposed product behavior.
- #2177 → #2178 is a hard prerequisite chain for the later comparison/re-baselining work. No child
may recreate the retired `src/daemon/handlers/interaction-*` paths from an older base.
- #1571 is related cold-open evidence, not automatically a blocker; benchmark and bridge work must
distinguish app-mount unreadability from bridge failure.

## Children and dependency graph

### Foundation

- [x] #2189 — reproducible local/proxy/package baselines and permanent regression evidence
- [x] #2190 — acquisition/presentation vocabulary, capabilities, intent, residue, and engine interface

### Convergence and bridge decision

- [x] #2191 — Swift/TypeScript engine implementation, independent conformance, current-runner
integration, and ADR 0004 amendment
- [x] #2195 — Appium/WebDriver and Limrun acquisition-adapter convergence
- [x] #2192 — bounded Simulator AX bridge spike with explicit GO/NO-GO
- [x] #2196 — production native bridge plus private Apple host adapter/lifecycle

### Routing, latency, remote acceptance, and deletion

- [x] #2197 — bridge routing, generation circuit, shared-deadline fallback, and comparison re-baseline
- [x] #2198 — runner-demand/open/relaunch optimization plus proxy acceptance
- [ ] #2199 — final pruning, no-regrowth enforcement, size report, and release evidence

```text
#2189 ─────────► #2192
└──────────────────────────────► #2198

#2190 ─► #2191 ─► #2195 ─────────────────► #2199
│ └──────────────► #2197
└──────► #2192 ─► #2196 ─► #2197 ─► #2198 ─► #2199

#2177 ─► #2178 ─────────────────────► #2197
```

Only #2189 and #2190 are initially unblocked and `ready-for-agent`. Blocked children remain
`needs-triage` until every `Blocked by:` prerequisite lands and the issue is re-audited against its
exact head. #2196 additionally requires #2192 to close with GO; a NO-GO stops the bridge branch.

## Tracker acceptance

Close this tracker only after every child is closed and the exact implementation heads prove:

- local cold-cold, cold, warm, and relaunch targets;
- Swift/TypeScript conformance with reproducible failures and planted-red proof;
- provider option consistency and typed fidelity residue;
- stale-generation, cancellation, crash, timeout, and fallback behavior;
- direct-daemon/proxy semantic parity, lease isolation, supported version skew, and controlled-RTT
measurements;
- packed, installed, and bundled package-size deltas;
- final provider, macOS, Simulator, affected, and structural gates.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.