callstack / callstack/agent-device

iOS snapshot backend convergence and fast Simulator observation

Aperta
#2,188 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub
enhancement
Lingua principale
TypeScript
Stelle
4.6k
Fork
299
Merge medio
10h 17m
PR unite (30g)
544

Descrizione

## 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.

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Leggi prima il grafo delle dipendenze e l’issue figlia non spuntata #2199; il tracker indica che le altre issue figlie sono chiuse, ma richiede prove esatte dello stato dell’implementazione. Usa i criteri di accettazione elencati nel tracker come checklist di completamento, incluse le evidenze di regressione, conformità, fallback, parità del proxy, latenza, dimensione del pacchetto e del gate finale.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
ios, swift, typescript
Ambito
mobile, performance, testing
Tipo di issue
Funzionalità
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Attiva
Chiarezza
Abbastanza chiara
Idoneità per principianti
25/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.