@tapflowio/protocol 0.17.0 → 0.19.0

package/dist/index.d.ts

@@ -19,16 +19,45 @@ export interface DeviceReport {
 }
 /** A device as the relay lists it, after adding what only the relay knows. Named `DeviceSummary`
  *  rather than `DeviceInfo` because both packages already used that name for different shapes:
- *  the relay for this, the dashboard for the `session:deviceInfo` payload (`DeviceDetails`). */
+ *  the relay for this, and `DeviceDetails` is the `session:deviceInfo` payload. */
 export interface DeviceSummary extends DeviceReport {
     sessionId: string;
     busy: boolean;
 }
-/** The `session:deviceInfo` payload — what the viewer shows in its info card. */
+/** The `session:deviceInfo` payload.
+ *
+ *  **Nothing reads it.** Both agents send it and the relay caches and replays it on join, but no consumer
+ *  in this repo takes the value — the dashboard shows device name and OS from `agents:listed`
+ *  (`DeviceSummary`) instead. This comment used to claim "what the viewer shows in its info card", which
+ *  was the kind of false statement about a consumer that this package exists to remove; L6 found it while
+ *  classifying every browser-inbound message. Kept on the wire because third-party agents send it. */
 export interface DeviceDetails {
     deviceName: string;
     osVersion: string;
 }
+/** Closed role vocabulary shared by all platforms. An unmappable native role becomes `'other'` and the
+ *  platform-native string is preserved in `rawRole`, so a consumer can still branch on it without the
+ *  vocabulary having to grow for every platform. */
+export type UIElementRole = 'button' | 'text' | 'input' | 'image' | 'checkbox' | 'switch' | 'slider' | 'list' | 'cell' | 'tab' | 'other';
+/** Normalized to 0–1 in the same coordinate space the touch input path consumes, so a frame centre can
+ *  be fed straight into a tap without conversion. */
+export interface UIElementFrame {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** One node of `ui:tree:response`. Lived in `agent-core` until L4a needed it to type that message —
+ *  protocol is a leaf and cannot import agent-core, and the alternative was a copy. There was already
+ *  one: `mcp-server` carried a hand-written mirror, which is the drift this package exists to remove. */
+export interface UIElement {
+    role: UIElementRole;
+    label: string;
+    identifier?: string;
+    frame: UIElementFrame;
+    enabled: boolean;
+    rawRole?: string;
+}
 /** `agents:listed` groups devices by agent machine. */
 export interface SessionInfo {
     agentName?: string;
@@ -48,17 +77,19 @@ export interface ChromeButton {
     anchor: string;
     /** true = button is above the device frame (e.g. home button) */
     onTop: boolean;
-    /** button center at retracted/default position, in 2× composite px */
+    /** button center in the **expanded composite** space at 2× px (retracted/default) */
     normalOffset: {
         x: number;
         y: number;
     };
-    /** button center at extended/hover position, in 2× composite px */
+    /** button center at the rollover (extended/hover) position, same space */
     rolloverOffset: {
         x: number;
         y: number;
     };
+    /** button width in 2× composite px */
     buttonW: number;
+    /** button height in 2× composite px */
     buttonH: number;
     /** HID usage page for SimulatorKit injection (0 = unknown) */
     usagePage: number;
@@ -68,6 +99,7 @@ export interface ChromeButton {
     buttonPng?: string;
     /** base64 PNG of the pressed state (imageDown asset) */
     pressedPng?: string;
+    /** position + size in the **expanded composite** space at 2× px */
     pressedRect?: ChromeRect;
 }
 export interface AndroidButton {
@@ -75,25 +107,59 @@ export interface AndroidButton {
     accessibilityTitle: string;
     keyCode: number;
 }
-/** iOS device chrome — the bezel artwork and hit regions the viewer composites around the screen. */
+/** Payload on every `clipboard:error` from a read. `sentinelParked` answers the one question the
+ *  viewer needs to decide its fallback: is a marker still sitting on the device clipboard?
+ *
+ *  If it is, the agent's restore is about to overwrite whatever the device copies next, so
+ *  pressing the plain chord as a fallback would hand the user a stale value — the exact bug the
+ *  sentinel exists to prevent. If it is not, the chord is safe and is the only way the copy
+ *  happens at all. Absent means "assume parked": an agent from before this field cannot tell us,
+ *  and the silent-stale-paste failure is worse than a copy that did not happen.
+ *
+ *  `unsupported` is narrower — this backend has no clipboard channel whatsoever — and drives the
+ *  paste fallback and the wording of the toast. */
+export interface ClipboardErrorPayload {
+    unsupported?: boolean;
+    sentinelParked?: boolean;
+}
+/**
+ * iOS device chrome — the bezel artwork and hit regions the viewer composites around the screen.
+ *
+ * **Two coordinate spaces exist here and the field names do not distinguish them.** The composite
+ * PDF is the device frame; the *expanded* composite is that canvas grown by the button margins, and
+ * it is the space the viewer lays out against. `compositeWidth`/`Height`, `screenRect` and every
+ * `ChromeButton` offset are in the **expanded** space; `padding` is the device's own padding inside
+ * the un-expanded one. Getting this wrong puts buttons at an offset that looks almost right.
+ *
+ * These descriptions come from the producer (`ios-agent`'s `DeviceChromeLoader`, which computes
+ * `expandedW = pdfSize.width + buttonMargins`). They were previously accurate only in that file —
+ * this declaration said `compositeWidth` was "full PDF width including devicePadding", a different
+ * quantity — so they moved here with the type rather than being lost with it.
+ */
 export interface ChromeData {
-    /** full composite PDF at 2× — device frame visible, screen hole transparent */
+    /** composite with buttons baked in, at 2× — screen hole transparent */
     framePng: string;
+    /** composite minus devicePadding, at 2× px */
     bezelWidth: number;
     bezelHeight: number;
-    /** full PDF width including devicePadding, at 2× px */
+    /** **expanded** canvas width — composite + button margins — at 2× px */
     compositeWidth: number;
+    /** **expanded** canvas height, at 2× px */
     compositeHeight: number;
+    /** devicePadding at 2× px, inside the un-expanded composite */
     padding: {
         left: number;
         right: number;
         top: number;
         bottom: number;
     };
+    /** screen position in the **expanded** composite space, at 2× px */
     screenRect: ChromeRect;
     /** screen corner radius in 2× px (0 if the device has no rounded corners) */
     screenCornerRadius: number;
+    /** screen width in iOS logical pixels (pt) */
     logicalWidth: number;
+    /** screen height in iOS logical pixels (pt) */
     logicalHeight: number;
     buttons: ChromeButton[];
 }
@@ -109,120 +175,625 @@ export interface AndroidChrome {
  *  contract still states the shape, because the viewer parses it. A new platform adds its variant
  *  here; relay and dashboard code stay unchanged, which is what the OCP rule asks for. */
 export type ChromePayload = ChromeData | AndroidChrome;
-export type RelayToAgent = {
+export interface AgentRegistered {
     type: 'agent:registered';
     registeredSessions: Array<{
         deviceId: string;
         sessionId: string;
     }>;
-} | {
+}
+export interface StreamRequestIdr {
     type: 'stream:request-idr';
     sessionId: string;
-} | {
+}
+export interface DeviceShutdown {
     type: 'device:shutdown';
     sessionId: string;
+    requestId?: string;
     payload: {
         deviceId: string;
     };
-} | {
+}
+export interface AppInstallToAgent {
     type: 'app:install';
     sessionId: string;
+    requestId: string;
     payload: {
         filePath: string;
         bundleId: string | null;
     };
-} | {
+}
+export interface AppLaunchToAgent {
     type: 'app:launch';
     sessionId: string;
+    requestId: string;
     payload: {
         bundleId: string;
     };
-} | {
+}
+export interface ScreenshotRequest {
     type: 'screenshot:request';
     sessionId: string;
     requestId: string;
+    /**
+     * A **preference, not a requirement.** An agent may produce something else, and says what it
+     * produced in `ScreenshotDone.format`.
+     *
+     * That asymmetry is not slack, it is the platform contract: `DeviceAgent.screenshot()` takes no
+     * format argument at all, so no agent has ever been asked to honour this — iOS happens to
+     * (`simctl io … --type`), Android cannot (`screencap -p` produces PNG and takes no format), and a
+     * third-party platform registered through `AgentRegistry.register()` is free to produce whatever
+     * it can. Required here only because every in-repo sender supplies one; absence would have to mean
+     * "no preference", which is what `'png'` already means.
+     *
+     * A consumer that needs to know what it is holding reads the **bytes**, not this field and not the
+     * reply's echo of it — #508 was this field being read as an outcome.
+     */
     format: 'png' | 'jpeg';
-} | {
+}
+export interface UiTreeRequest {
     type: 'ui:tree:request';
     sessionId: string;
     requestId: string;
-};
+}
+export type RelayToAgent = AgentRegistered | StreamRequestIdr | DeviceShutdown | AppInstallToAgent | AppLaunchToAgent | ScreenshotRequest | UiTreeRequest;
+export type SessionTerminatedReason = 'agent-disconnected';
 /**
- * Why a session stopped existing, server-side. A literal union rather than a string so that adding
- * a case is a compile-time event for every consumer that switches on it.
+ * Why a terminal input was not delivered — the machine-readable half of `input:error`.
  *
- * Named `session:terminated`, not `session:ended`: `session:end` is already a message the *browser*
- * sends to ask for shutdown, and the two would sit one letter apart in the same switch. This one
- * travels the other way and is not an acknowledgement of that request.
+ * The set is derived from **what a consumer has to do differently**, not from how many internal
+ * states an agent has. Those differ per platform (one HID helper on iOS; a scrcpy socket, an
+ * emulator gRPC channel and `adb shell input` on Android) and each agent maps its own states onto
+ * these. A closed set that is smaller than either agent's internals is the point.
+ *
+ * | reason | consumer should |
+ * |---|---|
+ * | `not-booted` | boot the device |
+ * | `channel-unavailable` | reconnect or rebind; do not blindly retry |
+ * | `channel-starting` | **retry shortly** — the channel exists and is coming up |
+ * | `dispatch-failed` | may retry once |
+ * | `unsupported` | never retry; this agent does not implement it |
+ * | `malformed` | fix the call; never retry |
+ * | `no-gesture` | **open a new gesture** — retrying this frame can never land |
+ *
+ * `channel-starting` is the one that had no name. On iOS the input helper needs a measured
+ * 186–247ms after spawn before an injected frame reaches the device, and `device:ready` can arrive
+ * inside that window — so a caller that taps as soon as a boot returns was being told the channel
+ * was gone when it was merely coming up.
+ *
+ * **A consumer that meets a reason it does not know must treat it as `channel-unavailable`** — the
+ * conservative reading. The field is optional precisely so an older agent can omit it, so absence
+ * means "unknown", never "fine".
+ *
+ * A string literal union rather than an enum, per this package's HOW NOT: it must erase under
+ * `import type` so it never lands in the dashboard's bundle.
  */
-export type SessionTerminatedReason = 'agent-disconnected';
-export type RelayToBrowser = {
+export type InputErrorReason = 'not-booted' | 'channel-unavailable' | 'channel-starting' | 'dispatch-failed' | 'unsupported' | 'malformed'
+/**
+ * A frame that only means something as part of a gesture arrived with no gesture behind it — the
+ * opening frame never landed, or the process serving it was replaced. Distinct from `malformed`
+ * because the advice differs: the message was well-formed and the channel may be perfectly
+ * healthy, but *this* frame can never be delivered, so the caller re-opens the gesture rather than
+ * giving up. Distinct from `channel-starting` for the same reason — waiting does not help.
+ */
+ | 'no-gesture'
+/**
+ * The sender does not hold the session it addressed. The relay forwards a browser-role input after
+ * resolving the session and, until this existed, without checking that the socket asking is the one the
+ * session is bound to — so any authenticated client could drive a device another tester was looking at,
+ * and the agent's ack went to the session holder rather than to whoever asked.
+ *
+ * **Not folded into `channel-unavailable`**, on that set's own rule — a reason exists per thing a consumer
+ * must do differently. `channel-unavailable` means reconnect or re-join *this* session; this means the
+ * caller never held it, so the move is to join first, and it may find someone else holding it.
+ *
+ * And it is the **only** reason that guarantees nothing reached the device. Every other one leaves partial
+ * delivery open — `no-gesture` most sharply, which is why nothing retries on it (#491). Here the frame was
+ * refused at the relay's door, so a retry after joining is safe, and that makes this the first member
+ * whose advice can say so.
+ */
+ | 'not-session-owner';
+/** Browser-inbound messages with **two** producers: an agent sends it and the relay also originates
+ *  its own copy — replaying session state to a re-joining viewer, or failing fast when it cannot
+ *  reach the agent at all.
+ *
+ *  Declared once here and referenced by both directions rather than written into each, because two
+ *  copies of one message drift. That is not hypothetical: the dashboard kept a hand-copy of this
+ *  whole surface and four members had diverged from it, with nothing reporting the difference. */
+export interface SessionChrome {
+    type: 'session:chrome';
+    sessionId: string;
+    payload: ChromePayload;
+}
+export interface SessionDeviceInfo {
+    type: 'session:deviceInfo';
+    sessionId: string;
+    payload: DeviceDetails;
+}
+export interface DeviceReady {
+    type: 'device:ready';
+    sessionId?: string;
+    /** Absent = this is not the answer to a `device:boot`. See 「Lifecycle correlation」 in AGENTS.md. */
+    requestId?: string;
+    payload: {
+        deviceId: string;
+    };
+}
+/**
+ * `sessionId` is what makes a failure findable. An MCP caller waits for the reply that carries its own
+ * sessionId, and without one it waits out the deadline instead (#445).
+ *
+ * **This is now a description of the wire, and for two releases it was a specification the relay did not
+ * meet.** Nothing validated inbound messages, so a client sending `{"type":"input:touch:end"}` with no
+ * sessionId reached `sessions.get(undefined)`, missed, and was answered through `msg.sessionId!` —
+ * `JSON.stringify` then dropped the key, shipping a frame whose required field this declaration claimed
+ * was there. `sessionId: ''` was the sharper half: it type-checks, and `mcp-server`'s tool schemas are
+ * bare `z.string()`, so an LLM could produce one.
+ *
+ * #444 closed it at the door. `@tapflowio/protocol/validate` parses an inbound frame against these
+ * declarations before the relay routes it, with `.min(1)` on this field so the empty string is refused
+ * too — and **`RelayServer.ts` now contains no `msg.sessionId!` at all**, where it once held eleven.
+ * There is no count left to keep current here, which is the point: the assertion is gone rather than
+ * enumerated, and a stale number in this paragraph is what taught that lesson.
+ *
+ * One member still declares `sessionId?` — `DeviceReady`, and its own note says why. That is a reasoned
+ * deferral about a correlator, not a gap in this one.
+ *
+ * Optional would have described the old wire accurately and still been the wrong contract: an MCP caller
+ * that receives an uncorrelatable `input:error` has nothing it can do with it and waits out the deadline
+ * either way. An earlier version of this note said the producer should "send `error` instead", pointing at
+ * `GenericError` below as an escape hatch for a failure with no session. **That escape is gone**:
+ * `GenericError` requires `sessionId` since L5d, and a request naming no session is refused at the door
+ * rather than answered, because a reply carrying no `requestId` cannot be attributed and costs the caller
+ * the same deadline silence would.
+ */
+export interface SessionScoped {
+    sessionId: string;
+}
+export interface AppInstallError extends SessionScoped {
+    type: 'app:install-error';
+    message: string;
+    requestId: string;
+}
+export interface AppLaunchError extends SessionScoped {
+    type: 'app:launch-error';
+    message: string;
+    requestId: string;
+}
+export interface DeviceBootError extends SessionScoped {
+    type: 'device:boot-error';
+    message: string;
+    requestId?: string;
+}
+export interface OpenUrlError extends SessionScoped {
+    type: 'open-url:error';
+    message: string;
+    requestId: string;
+}
+export interface AppClearStateError extends SessionScoped {
+    type: 'app:clear-state-error';
+    message: string;
+    requestId: string;
+}
+/**
+ * **The guaranteed half is now the half that is a contract** (#491).
+ *
+ * `message` used to be required and `reason` optional, which is the inversion this message could least
+ * afford: `packages/protocol/AGENTS.md` states the split on purpose — `message` is free prose each agent
+ * owns, `reason` is the closed union consumers branch on — so the field a consumer was guaranteed to
+ * receive was the one it must not depend on, and the one it should depend on could be absent.
+ *
+ * That was the correct way to *ship* it (#490): an agent predating the field omitted it and nothing broke.
+ * It is not a correct end state, because every consumer carries an unknown-reason branch for as long as it
+ * holds, and "absence means unknown" has to be re-derived by each new one.
+ *
+ * **Measured before flipping it: all six in-repo producers already send a reason**, two of them with
+ * `satisfies InputErrorReason` on the literal — `IOSAgent.ts` (three sites), `AndroidAgent.ts` (two) and
+ * `RelayServer.refuseInput`. The prerequisite was the relay, which used to send prose alone (#492, closed).
+ * So this costs no in-repo change; what it buys is that an agent outside this repo cannot omit it, and that
+ * a consumer written tomorrow cannot be handed an unanswerable failure.
+ *
+ * **`message` is optional rather than removed.** It still carries parameterised detail a closed union
+ * cannot — `unknown key code: KeyFoo` — which is a debug and forward-compatibility field, and a debug field
+ * should not be required. Display copy belongs to the presentation layer: agent-authored English cannot be
+ * localised, and this product's audience is PO, PM, designers and QA. A structured `params` field is the
+ * honest way to keep `KeyFoo` once prose is demoted, and it is deliberately **not** added here — #485 is
+ * what will say whether a rendered UI misses the variable, and adding it now means guessing a schema from
+ * no requirement.
+ *
+ * `InputTypeError` keeps `reason?` and that asymmetry is deliberate, not an oversight: its agent-side
+ * producers answer with prose from a rejected `adb` or pasteboard write and have no reason to give. Only
+ * the relay sets one. The field's own doc there records it.
+ */
+export interface InputError extends SessionScoped {
+    type: 'input:error';
+    /** Required — see `InputDone`. The relay produces this message too, so omission is a compile error there
+     *  rather than something only a test could hold. */
+    requestId: string;
+    reason: InputErrorReason;
+    message?: string;
+}
+export interface ClipboardError extends SessionScoped {
+    type: 'clipboard:error';
+    message: string;
+    requestId: string;
+    payload?: ClipboardErrorPayload;
+}
+export type RelayOrAgentToBrowser = SessionChrome | SessionDeviceInfo | DeviceReady | AppInstallError | AppLaunchError | DeviceBootError | OpenUrlError | AppClearStateError | InputError | InputTypeError | ClipboardError;
+export interface AgentsListed {
     type: 'agents:listed';
     sessions: SessionInfo[];
-} | {
-    type: 'stream:registered';
-} | {
+}
+export interface SessionJoined {
     type: 'session:joined';
     sessionId: string;
     capabilities: string[];
-} | {
+}
+export interface SessionTerminated {
     type: 'session:terminated';
     sessionId: string;
     reason: SessionTerminatedReason;
-} | {
+}
+export interface SessionAgentAway {
     type: 'session:agent-away';
     sessionId: string;
-} | {
+}
+export interface SessionRebound {
     type: 'session:rebound';
     sessionId: string;
     capabilities: string[];
-} | {
-    type: 'session:chrome';
-    payload: ChromePayload;
-} | {
-    type: 'session:deviceInfo';
-    payload: DeviceDetails;
-} | {
-    type: 'device:ready';
+}
+/**
+ * Why a `session:start` could not be honoured. The same split as `InputErrorReason`: `message` stays
+ * free prose the producer owns, and the machine field is closed.
+ *
+ * It exists because the dashboard was branching on the prose. Three wordings were sent and two were
+ * handled, so `Session busy` — the reply a second tester gets when someone else already holds the
+ * device — reached the viewer and did nothing at all, leaving the tab waiting on a `session:joined`
+ * that cannot arrive. Nothing reported it, because from the outside the type *was* handled.
+ *
+ * **Required, unlike `InputErrorReason`.** That one is permanently optional because its producer set is
+ * open by design — a third-party platform registers through `AgentRegistry.register()` and may predate
+ * the field. This one has a single producer: the relay, at three sites in `handleSessionStart`. So the
+ * compiler can insist, and it does — `sendTo` takes `RelayOutbound`.
+ */
+export type SessionStartFailure = 
+/** No such session. Nothing else is ever coming for it. */
+'session-not-found'
+/** The session exists and another browser socket holds it. It is alive; this viewer cannot have it. */
+ | 'session-busy'
+/** The Mac is over its resource ceiling and refused to take another session. */
+ | 'agent-resources-exhausted';
+/**
+ * The answer to a `session:start` the relay refused. **Not a general escape hatch**, which is what this
+ * comment used to claim — and the claim could not coexist with `SessionStartFailure`'s, one screen up, that
+ * the reason has a single producer inside `handleSessionStart`. Both were in HEAD at once for two months.
+ *
+ * L5c settled it by removing the general role rather than the specific one: a request that names no session
+ * is now **dropped at the relay's door** — by the inbound schema since #444 — because answering it would ship a frame whose own
+ * required `sessionId` `JSON.stringify` erases, and `error` has no `requestId` either — so a caller could not
+ * attribute the answer and would wait out the same deadline silence costs. With nothing left needing an
+ * unaddressed failure, every producer of this message answers one specific join.
+ *
+ * **So it extends `SessionScoped`**, and that is the honest form rather than a field bolted on: the base's
+ * own definition — a failure a *session* is waiting on — is now exactly what this is.
+ * `protocolMessageNames.test.mjs` enforces that membership, and its note saying `error` "cannot be a
+ * `SessionError`" described a nature that argument replaced. The base was called `SessionError` and carried
+ * `message` until #491 demoted prose on `input:error`; `message` now sits on each member that requires it,
+ * and what the base states is the one thing all nine share — the failure is addressed to a session.
+ *
+ * What the address buys: the join waiters in `mcp-server` and `flow-runner` matched
+ * `sessionId === undefined || sessionId === mine`, and with no such key the left half was **always true**, so
+ * any `error` resolved any pending join. Two concurrent `connect_device` calls and the first refusal woke the
+ * wrong one — reported as a failure the other session never had, while the one that did fail waited out its
+ * deadline. `dispatch` resolves only the first matching waiter, so that is one wrong answer and one timeout.
+ *
+ * The name stays `GenericError` despite the narrowed role. The derivation rule would give `Error`, which
+ * shadows the global, so the exception exists for the literal rather than the role — renaming to
+ * `SessionStartError` needs an exception entry just the same, and removing it needs a new wire literal.
+ */
+export interface GenericError extends SessionScoped {
+    type: 'error';
+    message: string;
+    reason: SessionStartFailure;
+}
+/**
+ * A `device:shutdown` the relay could not deliver.
+ *
+ * **The pair's error member, added late and by a different producer than its `-done`.** Every other
+ * browser-originated command answers when the relay cannot dispatch it; this one resolved its session
+ * inline and dropped the frame in silence, so `mcp-server`'s `shutdownDevice` burned a 30s deadline and
+ * reported `Request timed out` with no cause (#542). There was no shape to answer *with*, which is why
+ * fixing it was a protocol change rather than a relay one.
+ *
+ * **`RelayToBrowser`, not `RelayOrAgentToBrowser`**, unlike `DeviceBootError` beside it. Both agents ack
+ * a shutdown they cannot perform by simply not sending `device:shutdown-done`; neither has a failure
+ * path that produces a message. Declaring it in the shared union would claim a producer that does not
+ * exist, and would add an `AgentToBrowser` member with no forwarding case — which is exactly what
+ * `browserInboundRouting.test.mjs`'s second assertion exists to report. If an agent later grows one,
+ * moving the member is one line and that check enforces the case at the same time.
+ *
+ * `requestId` is optional because **the request's is** — the relay originates `device:shutdown` from its
+ * own idle timer, so a reply cannot demand a field the request need not carry. Absent here means the
+ * same thing it means on `DeviceShutdownDone`: this frame answers no request.
+ */
+export interface DeviceShutdownError extends SessionScoped {
+    type: 'device:shutdown-error';
+    message: string;
+    requestId?: string;
+}
+/** Messages the relay originates and no agent sends. */
+export type RelayToBrowser = RelayOrAgentToBrowser | AgentsListed | SessionJoined | SessionTerminated | SessionAgentAway | SessionRebound | DeviceShutdownError | GenericError;
+export interface DeviceBooting {
+    type: 'device:booting';
+    sessionId: string;
+}
+export interface DeviceShutdownDone {
+    type: 'device:shutdown-done';
+    /** Absent = this shutdown was not requested by a browser — the relay's idle timer ran. */
+    requestId?: string;
+    sessionId: string;
     payload: {
         deviceId: string;
     };
-} | {
-    type: 'error';
-    message: string;
-} | {
-    type: 'app:install-error';
+}
+export interface AppInstallDone {
+    type: 'app:install-done';
     sessionId: string;
-    message: string;
-} | {
-    type: 'app:launch-error';
+    requestId: string;
+}
+export interface AppLaunchDone {
+    type: 'app:launch-done';
     sessionId: string;
-    message: string;
-} | {
-    type: 'device:boot-error';
+    requestId: string;
+}
+export interface AppClearStateDone {
+    type: 'app:clear-state-done';
     sessionId: string;
-    message: string;
-} | {
-    type: 'open-url:error';
+    requestId: string;
+}
+export interface OpenUrlDone {
+    type: 'open-url:done';
     sessionId: string;
-    message: string;
-} | {
-    type: 'app:clear-state-error';
+    requestId: string;
+}
+export interface InputDone {
+    type: 'input:done';
+    sessionId: string;
+    /**
+     * Required, and this is the pair where an absent correlator costs the most. The four already correlated
+     * arrive at the speed a person clicks a button; a swipe is dozens of frames, so a late ack landing in the
+     * next input's waiter is not a corner case — it is #499.
+     *
+     * There is no unsolicited producer to make this optional (the discriminator this repo uses): `ackInput`
+     * on both agents is the only sender, and it fires on terminal outcomes only. Contrast the lifecycle pair,
+     * where an Android stream dying mid-session produces a `device:boot-error` answering nothing.
+     */
+    requestId: string;
+}
+export interface InputTypeDone {
+    type: 'input:type-done';
     sessionId: string;
+    requestId: string;
+}
+export interface InputTypeError extends SessionScoped {
+    type: 'input:type-error';
     message: string;
-} | {
-    type: 'input:error';
+    requestId: string;
+    /**
+     * Optional because the agents' own failures carry none — they answer with prose from a rejected `adb` or
+     * pasteboard write. The **relay** sets it, and without this field one of the five requests it can refuse
+     * had no machine-readable answer at all: `not-session-owner`'s whole value is the promise that nothing
+     * reached the device, and a consumer that can only read `message` cannot act on it. Branching on prose is
+     * the thing #492 legislated against.
+     */
+    reason?: InputErrorReason;
+}
+export interface KeyboardToggled {
+    type: 'keyboard:toggled';
     sessionId: string;
-    message: string;
-} | {
-    type: 'clipboard:error';
+    payload: {
+        visible: boolean;
+    };
+}
+export interface ClipboardData {
+    type: 'clipboard:data';
     sessionId: string;
     requestId: string;
-    message: string;
-};
+    payload: {
+        text: string;
+    };
+}
+export interface ClipboardWriteDone {
+    type: 'clipboard:write-done';
+    sessionId: string;
+    requestId: string;
+}
+/** Messages an agent produces. The relay forwards them byte-for-byte (`JSON.stringify(raw)`, the frame
+ *  exactly as it arrived, so a field a newer agent adds is not stripped by a relay that does not know it) rather
+ *  than re-creating them, so it never constructs one — which is exactly why they were missing from
+ *  this file until L3: nothing on the relay's own send path referenced them.
+ *
+ *  The twelve declared below carry `sessionId` as required, on two independent grounds: both agents
+ *  include it in every send literal, and the relay's forward gate resolves `sessions.get(msg.sessionId)`
+ *  before forwarding, so a message with no sessionId never reaches a browser by this path.
+ *
+ *  Nine of the ten inherited from `RelayOrAgentToBrowser` now carry it too. Three of them
+ *  (`session:chrome`, `session:deviceInfo`, `device:ready`) were `sessionId?` for as long as the relay's
+ *  replay omitted what both agents stamped. Two ways to tighten the *declaration* were weighed and
+ *  rejected — declaring the three twice (drift, which is the finding this surface exists to remove), and
+ *  mapping the union through `Omit<T,'sessionId'> & { sessionId: string }`.
+ *
+ *  The recorded reason for rejecting the second one does not survive checking, and it is worth saying so
+ *  rather than deleting it: it claimed the mapping breaks `useClipboardBridge`, which reads its replies
+ *  through `Extract<>`. It does not — that hook takes the three replies as **named members**
+ *  (`ClipboardData | ClipboardWriteDone | ClipboardError`) and says so in its own comment, and its only
+ *  `Extract` is over `ClipboardRequest`, an outbound union this mapping would never touch.
+ *
+ *  It does not change the outcome, because both alternatives are ways to make one declaration describe
+ *  two producers that disagree, and the disagreement was the defect. The relay stamps the first two now.
+ *  `device:ready` stays optional for a different reason — see the note above the declarations. */
+export type AgentToBrowser = RelayOrAgentToBrowser | DeviceBooting | DeviceShutdownDone | AppInstallDone | AppLaunchDone | AppClearStateDone | OpenUrlDone | InputDone | InputTypeDone | KeyboardToggled | ClipboardData | ClipboardWriteDone;
+/** Everything a browser socket can receive, whoever produced it. This is what a viewer's message
+ *  handler should be typed with — the two unions above answer "who sends this", which matters to
+ *  the relay and not to the consumer. */
+export type BrowserInbound = RelayToBrowser | AgentToBrowser;
+/** The agent's *stream* socket, not a browser. Its own direction because it has its own audience:
+ *  the consumer is `agent-core`'s stream registration, and nothing in a browser reads it. */
+export interface StreamRegistered {
+    type: 'stream:registered';
+}
+export type RelayToStream = StreamRegistered;
 /** Everything the relay originates. Messages it merely forwards keep their inbound type — they are
  *  not re-created, so they are not checked against this union. */
-export type RelayOutbound = RelayToAgent | RelayToBrowser;
+export type RelayOutbound = RelayToAgent | RelayToBrowser | RelayToStream;
+/** The agent's opening message on its control socket, sent from inside `onopen`. */
+export interface AgentRegister {
+    type: 'agent:register';
+    /** Open on purpose — **not** `'ios' | 'android'`. A third-party platform registers through
+     *  `AgentRegistry.register()` (root AGENTS.md, OCP), and narrowing this would stop it producing a
+     *  valid registration. `agent-core`'s own `Platform` is `string` for the same reason. */
+    platform: string;
+    /** What this agent implements, as plain strings on the wire. `agent-core`'s `AgentCapability` is
+     *  assignable to it; the wire does not close the set. */
+    capabilities: string[];
+    /** Stable per-machine id (macOS IOPlatformUUID). **Optional because `getMachineId()` returns
+     *  `undefined` off darwin**, and the relay falls back to `agentName` for dedup. */
+    agentId?: string;
+    agentName: string;
+    devices: DeviceReport[];
+}
+/** Periodic load report. The relay gates new sessions on it. */
+export interface AgentResourceReport {
+    type: 'agent:resources';
+    resources: AgentResources;
+}
+export interface ScreenshotDone {
+    type: 'screenshot:done';
+    sessionId: string;
+    requestId: string;
+    /**
+     * What the agent produced — the relay turns this into the HTTP `Content-Type`.
+     *
+     * The **only** field on this pair that describes an outcome; the request's `format` is a
+     * preference (see `ScreenshotRequest`). Android echoed the request here while always producing
+     * PNG, so a JPEG request came back as PNG bytes labelled `image/jpeg` (#508).
+     *
+     * Still a claim rather than a guarantee: it is what the agent *says*, and an agent older than the
+     * fix says the wrong thing. The relay logs a mismatch against the bytes but does not overwrite
+     * this — a consumer whose behaviour depends on the real format sniffs the bytes itself.
+     */
+    format: 'png' | 'jpeg';
+    /** base64. */
+    data: string;
+}
+/** A screenshot that failed.
+ *
+ *  **Does not extend `SessionScoped`**, unlike every other `*-error`, because it is not addressed to a
+ *  session: the relay resolves the pending promise by `requestId` alone. The base is for a failure a
+ *  *session* is waiting on, and drawing that line is what keeps it meaningful.
+ *
+ *  `sessionId` is still **required**, because every producer has one. An earlier draft made it optional
+ *  on the grounds that the agents pass through an optional id — true when written, and false by the end
+ *  of the same change, which required it on both dispatchers. A field weaker than every producer
+ *  describes a message nobody sends, and here it would also remove the one field a symmetric ownership
+ *  check could read: the clipboard replies beside these verify `session.agentSocket === ws` before
+ *  resolving, and these two do not. */
+export interface ScreenshotError {
+    type: 'screenshot:error';
+    sessionId: string;
+    requestId: string;
+    message: string;
+}
+export interface UiTreeResponse {
+    type: 'ui:tree:response';
+    sessionId: string;
+    requestId: string;
+    elements: UIElement[];
+}
+/** Request-scoped, for the same reasons as `ScreenshotError`. */
+export interface UiTreeError {
+    type: 'ui:tree:error';
+    sessionId: string;
+    requestId: string;
+    message: string;
+}
+export type AgentToRelay = AgentRegister | AgentResourceReport | ScreenshotDone | ScreenshotError | UiTreeResponse | UiTreeError;
+/** Its own direction, mirroring `RelayToStream`. The relay assigns the role `'stream'` from this
+ *  message rather than `'agent'` (`RelayServer.ts:554-557`), so putting it in `AgentToRelay` would make
+ *  that union's name disagree with the runtime role — and would let a control socket claim to be a
+ *  session's stream socket once L4b narrows inbound by role. */
+export interface StreamRegister {
+    type: 'stream:register';
+    sessionId: string;
+}
+export type StreamToRelay = StreamRegister;
+/** The three replies a clipboard request can get. Both agents build these through a local `respond`
+ *  helper that merges the correlation ids, and that helper took `object` — so the replies were the last
+ *  send path in the clipboard code that nothing checked. The consumer side names the same set
+ *  (`useClipboardBridge`), so it lives here rather than in either. */
+export type ClipboardReply = ClipboardData | ClipboardWriteDone | ClipboardError;
+/** A `ClipboardReply` minus the ids the sender merges in. Distributive, so each member keeps its own
+ *  payload — a plain `Omit` would collapse them into one shape and stop checking which goes with which. */
+export type ClipboardReplyBody<T = ClipboardReply> = T extends unknown ? Omit<T, 'sessionId' | 'requestId'> : never;
+/** The replies an `open-url` request can get. */
+export type OpenUrlReply = OpenUrlDone | OpenUrlError;
+/** An `OpenUrlReply` minus the ids the sender merges in — the `ClipboardReplyBody` shape.
+ *
+ *  **What it buys, exactly.** A first draft of this comment claimed it made the echo obligation
+ *  unstateable-otherwise and therefore removed the need for any check. Review measured that against 13
+ *  attacks and it is false: `sendMsg` takes `AgentControlOutbound`, whose `OpenUrlDone`/`OpenUrlError`
+ *  members declare `requestId: string`, so any site with any string in scope emits a fully-typed, fully
+ *  wrong reply without going through the helper at all. The helper is convention, not a type boundary.
+ *
+ *  What it does buy is one thing worth having: at a `respond({ … })` call, a **freshly minted id written
+ *  as a literal** is an excess property. It does not survive a body *variable* — excess-property checking
+ *  does not fire on those — which is why the agents spread `...body` **first** and put the ids last, so a
+ *  variable that carries one cannot override the real one.
+ *
+ *  Omission is caught, but by `requestId: string` being required on the reply interfaces rather than by
+ *  this type. The rest is carried by each agent's echo tests, and each remaining correlation pair needs
+ *  its own pair of them. A check can see that a field is present; it cannot see that the value came from
+ *  the request, which is the actual property — that part of the original reasoning stands, and it is why
+ *  the answer is tests at the sites rather than a cleverer checker. */
+export type OpenUrlReplyBody<T = OpenUrlReply> = T extends unknown ? Omit<T, 'sessionId' | 'requestId'> : never;
+/** The app-command pairs, same shape as `OpenUrlReplyBody` and for the same reason — see the note there
+ *  for exactly what it buys and what it does not.
+ *
+ *  There is deliberately **no request-direction counterpart.** One was designed and measured: a branded
+ *  correlator is laundered by any cast to the brand, because a brand names a *kind* while provenance is a
+ *  property of the *instance* and TypeScript has no value-dependent types; and a generic `Omit`-body
+ *  helper does not compile without a cast of its own, which is worse than the literal it replaces since a
+ *  literal at least gets its whole shape checked. The reply side is worth the type because there are
+ *  ~20 literal sites; the request side has one per pair, on the line below the helper that builds it. So
+ *  the relay's "carries the request's id" is held by tests, not by a type. */
+export type AppInstallReply = AppInstallDone | AppInstallError;
+export type AppInstallReplyBody<T = AppInstallReply> = T extends unknown ? Omit<T, 'sessionId' | 'requestId'> : never;
+export type AppLaunchReply = AppLaunchDone | AppLaunchError;
+export type AppLaunchReplyBody<T = AppLaunchReply> = T extends unknown ? Omit<T, 'sessionId' | 'requestId'> : never;
+export type AppClearStateReply = AppClearStateDone | AppClearStateError;
+export type AppClearStateReplyBody<T = AppClearStateReply> = T extends unknown ? Omit<T, 'sessionId' | 'requestId'> : never;
+/** What an agent's **control** socket carries. This is what the agents' send helpers take.
+ *
+ *  `StreamToRelay` is deliberately *not* in it. Splitting `stream:register` into its own direction was
+ *  justified above by the hazard of a control socket claiming to be a session's stream socket — and a
+ *  union that re-merged them would have handed that hazard straight back, since `case 'stream:register'`
+ *  calls `setStreamSocket(session.id, ws)` with no role gate. The stream socket's one message is typed
+ *  at its own send site in `agent-core/src/utils/stream.ts`. */
+export type AgentControlOutbound = AgentToRelay | AgentToBrowser;
+/**
+ * Every message this protocol declares, reached through the seven directions.
+ *
+ * Not a fourteenth union for its own sake: it is what lets a consumer assert that its own list of
+ * literals is *complete* rather than merely correct so far. `relay/src/types.ts` keeps such a list —
+ * hand-maintained, 62 entries, and missing `stream:request-idr` until this change, which is the exact
+ * drift this package was created to end (see AGENTS.md).
+ *
+ * The fact it restates is small and stable — **which directions exist** — not the 63 literals inside
+ * them. A message added to a direction flows in here for free; a message added to *no* direction does
+ * not, and nothing here can see that. That gap is real and is not this union's to close.
+ */
+export type AnyWireMessage = BrowserToRelay | RelayToBrowser | AgentToRelay | AgentToBrowser | RelayToAgent | StreamToRelay | RelayToStream;
 /** Key input. The payload carries `code` — a `KeyboardEvent.code` name — and `modifiers` as a
  *  **bitmap**, not a list and not `key`.
  *
@@ -234,6 +805,16 @@ export type RelayOutbound = RelayToAgent | RelayToBrowser;
 export interface InputKey {
     type: 'input:key';
     sessionId: string;
+    /**
+     * Required. A terminal input is the only kind that gets an ack, and #499 is what an unattributed one
+     * costs: an ack that arrives after its own deadline is consumed by the **next** input's waiter, which
+     * then reports the previous input's outcome — including reporting an unanswered input as landed.
+     *
+     * Opening and move frames deliberately do **not** carry this. They get no reply
+     * (`ios-agent/AGENTS.md`: "Opening frames stay silent: they carry no ack obligation"), so an id there
+     * would be minted for a waiter that does not exist. Nor does `input:rotate`, for the same reason.
+     */
+    requestId: string;
     payload: {
         code: string;
         modifiers?: number;
@@ -245,14 +826,15 @@ export interface Point {
 }
 /** The two clipboard requests a viewer can make. Kept as its own union because the bridge sends
  *  them through one call that takes the type as an argument. */
-export type ClipboardRequest = {
+export interface ClipboardRead {
     type: 'clipboard:read';
     sessionId: string;
     requestId: string;
     payload?: {
         press?: 'copy' | 'cut';
     };
-} | {
+}
+export interface ClipboardWrite {
     type: 'clipboard:write';
     sessionId: string;
     requestId: string;
@@ -260,100 +842,174 @@ export type ClipboardRequest = {
         text: string;
         pasteAfter?: boolean;
     };
-};
-export type BrowserToRelay = {
+}
+export type ClipboardRequest = ClipboardRead | ClipboardWrite;
+export interface AgentsList {
     type: 'agents:list';
-} | {
+}
+export interface SessionStart {
     type: 'session:start';
     sessionId: string;
-} | {
+}
+export interface SessionEnd {
     type: 'session:end';
     sessionId: string;
-} | {
+}
+export interface SessionLeave {
     type: 'session:leave';
     sessionId: string;
-} | {
+}
+export interface DeviceBoot {
     type: 'device:boot';
     sessionId: string;
+    /**
+     * Required, unlike every reply in this pair. Absence has no legitimate meaning on the request side —
+     * nothing originates a boot but a browser, so there is no producer for an id-less one to belong to.
+     * This is what puts `device:boot` inside 「No fallback, and one policy at the door」: required is what
+     * `correlatedRequestsGated` derives its set from, and what makes the relay's door gate reachable.
+     *
+     * `device:shutdown` below stays optional for the opposite reason — the relay sends that one itself.
+     */
+    requestId: string;
     payload: {
         deviceId: string;
         resetMode?: 'app-only' | 'full-erase';
         acceptH264?: boolean;
         secureContext?: boolean;
     };
-} | {
-    type: 'device:shutdown';
-    sessionId: string;
-    payload: {
-        deviceId: string;
-    };
-} | {
+}
+export interface AppInstallToRelay {
     type: 'app:install';
     sessionId: string;
+    requestId: string;
     buildId: number;
-} | {
+}
+export interface AppLaunchToRelay {
     type: 'app:launch';
     sessionId: string;
+    requestId: string;
     buildId: number;
-} | {
+}
+/** Wipe an installed app's data.
+ *
+ *  `bundleId` is **required, twice over** — the field and the payload. It was `payload?: { bundleId?: string }`,
+ *  which was looser than every producer *and* every consumer: `mcp-server` and `flow-runner` are its only
+ *  senders (the dashboard resets through `device:boot` instead) and both supply a string, and both agents answer
+ *  `app:clear-state-error` with `'bundleId missing'` when it is absent. A field weaker than every producer
+ *  describes a message nobody sends.
+ *
+ *  What required buys is a **compile error for a future sender**, no more. The agents keep that branch and
+ *  should: `bundleId: ''` type-checks — the door checks the *shape*, and an empty string is a valid one
+ *  everywhere but the two correlation fields, which carry `.min(1)`. So this is the same
+ *  argument as `sessionId` below, not a stronger one.
+ *
+ *  Unlike `app:install` / `app:launch`, which carry a `buildId` the relay resolves into a bundle id from the
+ *  builds table, this message is passed through untouched. That is an **absence of relay-side resolution, not a
+ *  design** — the machinery exists next door. It stays client-supplied because clearing a *different* app is a
+ *  documented flow step (`clearState: com.other.app`), so the field has to be expressible either way; adding a
+ *  relay-filled form would be a new feature, not a contract alignment. */
+export interface AppClearState {
     type: 'app:clear-state';
     sessionId: string;
-    payload?: {
-        bundleId?: string;
+    requestId: string;
+    payload: {
+        bundleId: string;
     };
-} | {
+}
+/** First message of the correlation work (L5). `requestId` is **required on the request and on both
+ *  replies**, which is the same shape the three pairs that already work use — `screenshot`, `ui:tree`
+ *  and `clipboard` all declare it required on the reply too, including the four an *agent* produces.
+ *
+ *  The alternative considered was optional-on-the-reply, so that an agent predating the field would not
+ *  make the declaration false. It was rejected on measurement rather than taste:
+ *
+ *  - Required yields **complete, precise** in-repo compile errors — seven, at exactly the seven
+ *    production sites for this pair, nothing else. The write side is fully covered because L4a routed
+ *    every agent send through a typed helper.
+ *  - Optional needs a static check to replace the compiler, and that check **cannot exist.** Presence is
+ *    checkable; the property is *provenance* — that the id is the request's. A check built and run
+ *    against the clipboard family (100% correlated today) produced seven false positives, because
+ *    `respond({ sessionId, requestId, ...body })` puts the `type` literal and the id in different object
+ *    literals; and it passed when an echo was replaced with a freshly minted id.
+ *  - Absence would carry **two** meanings that want opposite handling: "an old agent" and "not a reply at
+ *    all". The relay's `device:ready` replay is a permanent in-repo producer of the second, and treating
+ *    it as the first is the `{booted: true}` for a boot that never happened that #516 measured and
+ *    refused to ship. Required makes absence mean "not a reply", unambiguously — which is what makes
+ *    that message tightenable at all.
+ *
+ *  There is deliberately **no fallback** to the old `sessionId` + type matching. The `fixed` version
+ *  group in `.changeset/config.json` locks protocol, agent-core, both agents and the relay together, so
+ *  the in-repo skew window is zero; a third-party agent predating this is a release-note matter. A
+ *  permanent fallback would be a fifth correlation strategy in the layer whose goal is to have one. */
+export interface OpenUrl {
     type: 'open-url';
     sessionId: string;
+    requestId: string;
     payload: {
         url: string;
     };
-} | {
+}
+export interface InputTouchStart {
     type: 'input:touch:start';
     sessionId: string;
     payload: Point;
-} | {
+}
+export interface InputTouchMove {
     type: 'input:touch:move';
     sessionId: string;
     payload: Point;
-} | {
+}
+export interface InputTouchEnd {
     type: 'input:touch:end';
     sessionId: string;
+    requestId: string;
     payload?: Point;
-} | {
+}
+export interface InputPinchStart {
     type: 'input:pinch:start';
     sessionId: string;
     payload: {
         f0: Point;
         f1: Point;
     };
-} | {
+}
+export interface InputPinchMove {
     type: 'input:pinch:move';
     sessionId: string;
     payload: {
         f0: Point;
         f1: Point;
     };
-} | {
+}
+export interface InputPinchEnd {
     type: 'input:pinch:end';
     sessionId: string;
-} | InputKey | {
+    requestId: string;
+}
+export interface InputType {
     type: 'input:type';
     sessionId: string;
+    requestId: string;
     payload: {
         text: string;
     };
-} | {
+}
+export interface InputButton {
     type: 'input:button';
     sessionId: string;
+    requestId: string;
     payload: {
         name: string;
         phase?: 'down' | 'up';
     };
-} | {
+}
+export interface InputRotate {
     type: 'input:rotate';
     sessionId: string;
-} | {
+}
+export interface InputKeyboardToggle {
     type: 'input:keyboard:toggle';
     sessionId: string;
-} | ClipboardRequest;
+}
+export type BrowserToRelay = AgentsList | SessionStart | SessionEnd | SessionLeave | DeviceBoot | DeviceShutdown | AppInstallToRelay | AppLaunchToRelay | AppClearState | OpenUrl | InputTouchStart | InputTouchMove | InputTouchEnd | InputPinchStart | InputPinchMove | InputPinchEnd | InputKey | InputType | InputButton | InputRotate | InputKeyboardToggle | ClipboardRequest;
 //# sourceMappingURL=index.d.ts.map