Skip to content

Commit f47e9c9

Browse files
authored
docs(ios-runner): point RUNNER_PROTOCOL.md at the current declarations and document recovery and busy codes (#2876)
* docs(ios-runner): repoint RUNNER_PROTOCOL.md and document recovery/busy codes The command-names pointer named runner-client.ts, which now only sends commands; the RunnerCommand union moved to runner-contract.ts a while back. Add sections for commandId + the command journal + status recovery, runnerFatal/runnerMainThreadBusy response fields, and the typed runner error codes now on the wire (RUNNER_BUSY, RUNNER_WEDGED, MAIN_THREAD_TIMEOUT, APP_NOT_RUNNING, ALERT_NOT_FOUND, SCROLL_KEYBOARD_OCCLUDES_SURFACE, and the APP_SCREEN_* capture-refusal codes), each linked to its declaration site instead of copied tables. * docs(ios-runner): fix RUNNER_PROTOCOL error-code and busy-stamp claims Round 2 of adversarial review on #2797 found the round-1 doc still diverged from the code it describes: it claimed RUNNER_ERROR_RULES has a row for MAIN_THREAD_TIMEOUT (it does not - only RUNNER_BUSY and RUNNER_WEDGED have rows; MAIN_THREAD_TIMEOUT is read directly by isRunnerMainThreadOccupiedError), it still re-listed the diagnostic-only codes' owning files in prose instead of linking to the registries, it described the runnerMainThreadBusy unchanged-flag cases loosely enough to read as "any code without an occupancy match" rather than the actual two cases (an ok response with no stamp, or a non-structured transport-shaped failure), and it named runMainThreadWork/ runMainThreadWorkIfIdle plus RunnerTests+Transport.swift as the busy stamp's read/definition when the state read is actually currentMainThreadBusyState().reportsMainThreadBusy and the stamp itself is defined in RunnerTests+Models.swift (Transport.swift only calls it). Every changed sentence is re-checked against the implementation with file:line, and every code path other than RUNNER_BUSY/RUNNER_WEDGED/ MAIN_THREAD_TIMEOUT now points at DIAGNOSTIC_ONLY_RUNNER_ERROR_CODES and RUNNER_ERROR_RULES instead of restating what those registries own. * docs(ios-runner): reduce RUNNER_PROTOCOL recovery and error sections to declaration pointers * docs(ios-runner): link where the runner produces its busy stamp, runnerFatal and error codes
1 parent 57886b3 commit f47e9c9

1 file changed

Lines changed: 35 additions & 3 deletions

File tree

‎apple/runner/RUNNER_PROTOCOL.md‎

Lines changed: 35 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -62,10 +62,11 @@ than silently applied:
6262
{ "command": "rotate", "orientation": "landscape-left" }
6363
```
6464

65-
The current command names are defined in:
65+
The current command names and per-command traits are defined in:
6666

67-
- [`../../packages/platform-apple/src/runner/runner-client.ts`](../../packages/platform-apple/src/runner/runner-client.ts)
68-
- [`AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)
67+
- `RunnerCommand` in [`../../packages/platform-apple/src/runner/runner-contract.ts`](../../packages/platform-apple/src/runner/runner-contract.ts)
68+
- `RUNNER_COMMAND_TRAITS` in [`../../packages/platform-apple/src/runner/runner-command-traits.ts`](../../packages/platform-apple/src/runner/runner-command-traits.ts)
69+
- `CommandType` in [`AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)
6970

7071
## Response Shape
7172

@@ -97,3 +98,34 @@ Successful and failed responses use the same top-level envelope:
9798
- Treat the TypeScript and Swift wire models as a single contract.
9899
- When adding, removing, or renaming a command, update the protocol fixtures/tests in the same change.
99100
- Keep this file focused on the actual wire shape rather than implementation details of command execution.
101+
102+
## Recovery, Busy State, and Error Codes
103+
104+
These behaviors are owned by code. This section only says where each one is declared; read the
105+
declaration for the current rules.
106+
107+
- **Command ids and `status` recovery.** The daemon attaches a `commandId` with `withRunnerCommandId`
108+
([`runner-contract.ts`](../../packages/platform-apple/src/runner/runner-contract.ts)). The runner records commands in
109+
`RunnerCommandJournal` ([`RunnerTests+CommandJournal.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandJournal.swift)) and
110+
answers the `status` command in `executeStatus`
111+
([`RunnerTests+CommandDispatch.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift)). The daemon's recovery
112+
decisions live in [`runner-command-recovery.ts`](../../packages/platform-apple/src/runner/runner-command-recovery.ts).
113+
- **`runnerMainThreadBusy`.** The runner stamps successful responses with `stampingCurrentMainThreadBusy`
114+
([`RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)) from `currentMainThreadBusyState()`
115+
([`RunnerTests+MainThreadWork.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+MainThreadWork.swift)), applied in `jsonResponse`
116+
([`RunnerTests+Transport.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift)). The daemon reads the stamp in [`runner-session.ts`](../../packages/platform-apple/src/runner/runner-session.ts).
117+
- **`runnerFatal`.** A field of the response data (`runnerFatal` in
118+
[`RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)); for example, a sparse snapshot payload in
119+
[`RunnerTests+Snapshot.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Snapshot.swift) sets it. The daemon reads it in
120+
`resolveRunnerFatalReason` ([`runner-session.ts`](../../packages/platform-apple/src/runner/runner-session.ts)).
121+
- **Runner error codes** (for example `RUNNER_BUSY`, `RUNNER_WEDGED`, `MAIN_THREAD_TIMEOUT`). On the runner
122+
side, wire codes are declared in `RunnerWireErrorCode` ([`RunnerTests.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift));
123+
`RUNNER_BUSY` and `RUNNER_WEDGED` come from the busy gate in
124+
[`RunnerTests+CommandDispatch.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandDispatch.swift), and `MAIN_THREAD_TIMEOUT` from
125+
the main-thread watchdog in [`RunnerTests+Transport.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Transport.swift). The daemon
126+
classifies a runner-reported code in `classifyRunnerReportedError`
127+
([`runner-contract.ts`](../../packages/platform-apple/src/runner/runner-contract.ts)): codes listed in `DIAGNOSTIC_ONLY_RUNNER_ERROR_CODES`
128+
arrive as `COMMAND_FAILED` with `details.runnerErrorCode`, and other codes pass through as typed
129+
codes. How the daemon reacts to a failure (retry, resend, session-fatal) is declared in
130+
`RUNNER_ERROR_RULES` and the helpers beside it
131+
([`runner-error-classification.ts`](../../packages/platform-apple/src/runner/runner-error-classification.ts)).

0 commit comments

Comments
 (0)