@platless/axom-cli 0.1.0

package/dist/workstation/protocol/agent.js

@@ -0,0 +1,606 @@
+import { decodeChannelFrame, hasOptional, hasRequired, isBoolean, isBridgeInfoArray, isNullableAuthMethodInfoArray, isNullableString, isNumber, isObject, isString, isStringArray, isStringRecord, } from './common.js';
+/** Current version and feature floors for the independently negotiated agent protocol. */
+export const AGENT_WIRE_VERSION = 14;
+export const AGENT_WIRE_MIN_VERSION = 1;
+export const AGENT_WIRE_SESSION_LOST_VERSION = 2;
+export const AGENT_WIRE_ADOPTION_VERSION = 3;
+/** On-demand verification and authentication (`agent_verify` / `agent_authenticate`). */
+export const AGENT_WIRE_AUTH_VERSION = 4;
+/**
+ * Adapter installation (`agent_install` / `agent_installed`), and with it the roster's
+ * `cliInstalled` / `adapterInstalled`. A v4 peer answers neither, which is why the server checks
+ * this floor before sending rather than waiting out a request nothing will ever reply to.
+ */
+export const AGENT_WIRE_INSTALL_VERSION = 5;
+/**
+ * Steering (`agent_steer` / `agent_steered`). Checked before sending rather than waited out: a v5
+ * peer has no case for `agent_steer`, drops it, and the server's request dies at its own timeout
+ * with nothing said about why.
+ */
+export const AGENT_WIRE_STEER_VERSION = 6;
+/** Reconnect-time journal inventory (`agent_resume_offer`). */
+export const AGENT_WIRE_RESUME_OFFER_VERSION = 7;
+/**
+ * The same inventory carried on every `heartbeat` rather than once per connection
+ * (`heartbeat.sessions`).
+ *
+ * **Not a compatibility gate.** The server's `ChannelProtocolJson` sets `ignoreUnknownKeys`, so a v7
+ * server drops the field and acks the heartbeat exactly as it did before. The floor exists only to
+ * decide whether the bytes are worth sending: an inventory the peer will discard is pure overhead on
+ * a frame that goes out every ten seconds for the life of the daemon.
+ */
+export const AGENT_WIRE_HEARTBEAT_INVENTORY_VERSION = 8;
+/**
+ * Session config options: `agent_opened`/`agent_verified` carry the agent's `configOptions`
+ * snapshot and `agent_set_config_option` / `agent_config_option_set` round-trip
+ * `session/set_config_option` (`types.gen.d.ts:5102`). Checked before sending, like steering: a
+ * v8 peer has no branch for the request and would let it die at the server's timeout.
+ */
+export const AGENT_WIRE_CONFIG_OPTIONS_VERSION = 9;
+/**
+ * Orphan journals in `agent_resume_offer`: this client also lists refs whose journal is still on
+ * disk but whose agent is gone -- a daemon restart or a machine reboot -- as `agentAlive: false`.
+ *
+ * **A real compatibility gate, unlike AGENT_WIRE_HEARTBEAT_INVENTORY_VERSION.** That one only
+ * decided whether bytes were worth sending, because a peer that does not know the field ignores it.
+ * This one widens the meaning of an existing list whose *absence* is load-bearing: the server ends a
+ * live turn precisely because its ref is missing from the offer. A v9 server handed an orphan entry
+ * would stop ending that turn and, knowing nothing about reopening it, leave it RUNNING forever --
+ * strictly worse than today's honest failure. So orphans are withheld below this version.
+ */
+export const AGENT_WIRE_ORPHAN_OFFER_VERSION = 10;
+/**
+ * The login frames — `agent_auth_url` / `agent_auth_url_done` — and the `pending` acknowledgement on
+ * `agent_authenticated` that goes with them.
+ *
+ * **The hardest gate of the ladder so far, because getting it wrong does not cost one message.** A
+ * v10 server has no `SerialName` for `agent_auth_url`: `AgentCodec.decode` throws,
+ * `classifyUndecodableAgentFrame` files it as `Unattributable` (it has no `sessionRef` to attribute
+ * it to), and every one of those counts toward `MAX_CONSECUTIVE_UNDECODABLE_AGENT_FRAMES = 8` —
+ * which closes the agent channel **and every session multiplexed on it**. So the floor is checked
+ * before `emit`, never after, and below it `agent_authenticate` keeps its old synchronous shape:
+ * one reply, sent when the login is over, which is what a v10 server knows how to wait for.
+ */
+export const AGENT_WIRE_AUTH_URL_VERSION = 11;
+/**
+ * What the **session** path says about a refusal the agent itself produced: `authMethods` — what
+ * this process observed on that agent's `initialize` (`AcpAgents.observedAuthMethods`) — and
+ * `errorCode`, the JSON-RPC code of that refusal, on both `agent_opened` and `agent_turn_done`.
+ *
+ * A login card needs two halves — that the agent refused *for want of credentials*, and how it says
+ * to sign in. The probe reply (`agent_verified`) has carried both since v4. These two frames — the
+ * only ones by which a failed reopen and a failed prompt reach the server — carried neither, and
+ * neither could be reconstructed there: `errorMessage(err)` had already flattened ACP's
+ * `auth_required` (JSON-RPC -32000) to free text by the time a frame was built, and the
+ * `agent_hello` roster is a handshake snapshot that is empty for exactly the agent nobody has
+ * connected to yet.
+ *
+ * **Both keys ship under this one version because neither is worth a bump of its own** — not because
+ * they always arrive together. They do not: `refusalFields` spreads each on its own condition, so an
+ * agent that refused outside JSON-RPC sends the table with no code. The server requires the code
+ * regardless, and for a reason that has nothing to do with versioning: `auth_required` is a code, so
+ * a refusal carrying none is not one. ("Methods, therefore a login" was the old rule that made every
+ * refused prompt look like an expired token.)
+ *
+ * **The gentlest floor on the ladder, and deliberately not the shape of {@link
+ * AGENT_WIRE_AUTH_URL_VERSION}.** That one added whole frames, and a server without the
+ * `@SerialName` throws inside `AgentCodec.decode` — eight of those close the channel. This adds an
+ * optional key to two frames the server already decodes with `ignoreUnknownKeys`, so an older
+ * server reads them exactly as before. What is gated is therefore only whether the bytes are worth
+ * sending, like {@link AGENT_WIRE_HEARTBEAT_INVENTORY_VERSION}, and the check belongs on this side
+ * because both frames travel workstation -> server.
+ */
+export const AGENT_WIRE_SESSION_AUTH_METHODS_VERSION = 12;
+/**
+ * `agent_opened.reloaded`: whether **this open** actually performed `session/load` or
+ * `session/new`, as opposed to reusing a live session or piggybacking on another open's real
+ * result. The server needs this to settle background jobs left over from a previous agent
+ * process — those jobs live only in that process's memory, so a genuine reload is the one event
+ * that proves them gone.
+ *
+ * **Same shape as {@link AGENT_WIRE_SESSION_AUTH_METHODS_VERSION}, and for the same reason that
+ * one declares itself un-enforceable by anything mechanical**: this is an optional key on a frame
+ * the server already decodes with `ignoreUnknownKeys`, so a peer below this floor does not fail to
+ * decode — it just never sees the key. The floor exists to record the compatibility fact, not to
+ * gate a decode failure: a v12 (or older) peer never sends `reloaded` at all, and **its absence
+ * there must never be read as "this open did not reload"** — that peer cannot tell you either way.
+ * A server that settled a background job on that silence would be acting on a fact nobody
+ * observed. Below this floor the only correct read of "no `reloaded` key" is "unknown, do not
+ * settle"; at or above it, absence reverts to its ordinary meaning — `false`, like
+ * `supportsSteering`.
+ */
+export const AGENT_WIRE_RELOADED_VERSION = 13;
+/**
+ * `agent_steer` carries the **whole message** — `images` beside its `text` — and the delivery
+ * timing it is to be injected with (`priority`).
+ *
+ * **The criterion for "does an additive key need a floor?" is not "is it new" — it is: a key needs
+ * no floor only when a capability the peer must already advertise implies it can decode that key.**
+ * `ignoreUnknownKeys` means the question is never "will it throw"; it is "can the sender know the
+ * key will be understood without asking the version".
+ *
+ * `agent_prompt.images` passes that test and so has no floor: `supportsImageInput` shipped with it,
+ * so a peer advertising the capability necessarily understands the key. `agent_opened.reloaded` and
+ * the session-path `authMethods` pass a weaker version of it — they carry an *observation* a reader
+ * can simply do without — which is why theirs are "worth the bytes" floors rather than gates.
+ *
+ * These two fail on both counts. `supportsImageInput` predates them, so a peer can truthfully
+ * advertise it and still not know the keys exist; and `agent_steer` is an **RPC** — an `id`, a
+ * paired `agent_steered`, a server that acts on the answer — so the key is an instruction, not an
+ * observation. A peer below this floor decodes the frame fine, drops both keys, steers with the
+ * text alone and answers `injected` — so the reader's attached image never leaves their machine and
+ * every record on both sides says the message was delivered. Nothing observes the loss.
+ *
+ * So the server refuses to send a steer carrying either key below this floor rather than letting it
+ * degrade, and the engine's capability read reports no accepted timings at all below it, which
+ * routes the message to the queue — where it is delivered whole. A text-only steer with no priority
+ * is byte-for-byte the frame it always was and still goes out at {@link AGENT_WIRE_STEER_VERSION}.
+ */
+export const AGENT_WIRE_STEER_BLOCKS_VERSION = 14;
+/**
+ * Every agent frame's shape, as data rather than as a `switch`.
+ *
+ * Declarative on purpose: the required-field half of this table is the *only* statement anywhere of
+ * which fields the Kotlin twin will refuse to decode without, and the contract suite
+ * (`acp/contract.ts`'s `assertRequiredFieldsEnforced`) reads it directly to prove each one is really
+ * enforced. Left as inline `hasRequired({...})` calls inside a `switch`, that list is unreadable from
+ * a test, so the only way to check it would be a hand-maintained copy in the test file — which is
+ * precisely how `agent_authenticate.methodId` came to have no guard at all while a report still
+ * "decoded fine" and `authenticate(undefined)` ran all the way to the agent.
+ *
+ * `DISCRIMINATORS` is derived from the keys below for the same reason: a frame type added to the
+ * union and to this table can no longer be forgotten in a second, parallel list.
+ */
+export const AGENT_FRAME_SHAPES = {
+    agent_hello: { required: { ticket: isString }, optional: { bridges: isBridgeInfoArray } },
+    agent_ready: { required: { generation: isString, agentWire: isNumber } },
+    agent_resume_offer: {
+        required: {
+            sessions: (sessions) => Array.isArray(sessions) && sessions.every(isAgentResumeSession),
+        },
+    },
+    heartbeat: {
+        required: { seq: isNumber, sentAtEpochMs: isNumber },
+        optional: { sessions: (sessions) => Array.isArray(sessions) && sessions.every(isAgentResumeSession) },
+    },
+    heartbeat_ack: { required: { seq: isNumber } },
+    agent_open: {
+        required: {
+            id: isString, sessionRef: isString, agentKey: isString, bridge: isString, cwd: isString, shell: isString,
+        },
+        optional: {
+            env: isStringRecord, pathPrepend: isStringArray, agentEnv: isStringRecord, command: isNullableString,
+            args: isStringArray, nativeSessionId: isNullableString,
+            resumeFromSeq: isNumber, backfill: isBoolean,
+        },
+    },
+    agent_opened: {
+        required: { id: isString, ok: isBoolean },
+        // `supportsSteering` is `true` and nothing else, for `BridgeInfo.supportsSteering`'s reason: a
+        // `false` would be a second spelling of what its absence already says.
+        optional: {
+            nativeSessionId: isNullableString, error: isNullableString, supportsSteering: isVerifiedTrue,
+            // Plain strings, not a closed vocabulary: the sender already dropped everything it did not
+            // recognise, and validating the values again here would make a future timing fail the frame
+            // rather than be ignored — the opposite of what ruling N4 asks for.
+            steeringTimings: isStringArray,
+            // `reloaded` is `true`-or-absent for the same reason as `supportsSteering`: a `false` would
+            // be a second spelling of what its absence already says.
+            reloaded: isVerifiedTrue,
+            agentInfo: isAgentInfo, supportsImageInput: isVerifiedTrue, configOptions: isNullableSessionConfigOptionArray,
+            // Same guard as `agent_verified.authMethods`, and the same absent-vs-`[]` reading: a
+            // half-decoded method table is worse than none, because the reader would offer a login the
+            // agent never named.
+            authMethods: isNullableAuthMethodInfoArray,
+            errorCode: isNullableJsonRpcErrorCode,
+        },
+    },
+    agent_prompt: { required: { sessionRef: isString, text: isString }, optional: { images: isImageBlockArray } },
+    agent_answer: { required: { sessionRef: isString, requestId: isString, outcome: isString } },
+    agent_interrupt: { required: { sessionRef: isString } },
+    agent_close: { required: { sessionRef: isString } },
+    agent_event: { required: { sessionRef: isString, seq: isNumber, eventName: isString, payload: isRecord } },
+    agent_turn_done: {
+        required: { sessionRef: isString, seq: isNumber, status: isString },
+        optional: {
+            stopReason: isString, nativeSessionId: isNullableString, error: isNullableString,
+            authMethods: isNullableAuthMethodInfoArray,
+            errorCode: isNullableJsonRpcErrorCode,
+        },
+    },
+    agent_event_ack: { required: { sessionRef: isString, throughSeq: isNumber } },
+    agent_session_lost: { required: { sessionRef: isString, action: isString } },
+    // The session manager deliberately accepts malformed native-query payloads (including null)
+    // to return its protocol-level `ok: false` response. The transport only requires that the
+    // field is present; semantic validation remains at the request handler boundary.
+    agent_list_native: { required: { id: isString, bridge: isString, query: () => true } },
+    agent_native_sessions: {
+        required: { id: isString, ok: isBoolean },
+        optional: {
+            sessions: (sessions) => Array.isArray(sessions) && sessions.every(isNativeSession), error: isNullableString,
+        },
+    },
+    // Same lenience as `agent_list_native` above, for the same reason: the session manager wants to
+    // answer a malformed query with its own `ok: false` rather than have the transport drop it.
+    agent_verify: {
+        required: { id: isString, bridge: isString, query: () => true },
+        // 与 `query` 那条**刻意的宽松**相反,这里是严格的:一份畸形的 query 还有个能回
+        // `ok: false` 的接收方(会话管理器),而一个畸形的 timeoutMs 谁也接不住——`"30s"` 或 `NaN`
+        // 一路传到 setTimeout 就是"立刻超时"或"永不超时",两种都不是任何人的意思。缺席与畸形在
+        // 这里必须分得开:缺席 = 没人指定预算(用本地默认),畸形 = 对方说错了话,整帧拒掉。
+        optional: { timeoutMs: isNullableProbeTimeoutMs },
+    },
+    agent_authenticate: {
+        required: { id: isString, bridge: isString, methodId: isString, query: () => true },
+    },
+    agent_verified: {
+        required: { id: isString, ok: isBoolean },
+        optional: {
+            authMethods: isNullableAuthMethodInfoArray,
+            // Not `isBoolean`: `false` is not a value this frame has. The decoder refusing it is what
+            // stops "we could not verify" from ever reaching a UI as "you are signed out".
+            authenticated: isVerifiedTrue,
+            sessionError: isNullableString,
+            error: isNullableString,
+            availableCommands: isNullableAvailableCommandArray,
+            configOptions: isNullableSessionConfigOptionArray,
+        },
+    },
+    agent_authenticated: {
+        required: { id: isString, ok: isBoolean },
+        // `pending` is true-or-absent, the same rule as `agent_verified.authenticated` and for the same
+        // reason: absence already means "this is the final word", so a `false` on the wire would be a
+        // second spelling of it that a reader could disagree with.
+        optional: { pending: isVerifiedTrue, error: isNullableString },
+    },
+    agent_auth_url: { required: { id: isString, elicitationId: isString, url: isString } },
+    agent_auth_url_done: { required: { id: isString, elicitationId: isString } },
+    agent_install: { required: { id: isString, bridge: isString } },
+    agent_installed: {
+        required: { id: isString, ok: isBoolean },
+        optional: {
+            // Not `isBoolean`: like `agent_verified.authenticated`, this field has no `false` — an
+            // install that did not put the adapter on the machine says so by leaving the key out.
+            adapterInstalled: isVerifiedTrue,
+            alreadyInstalled: isBoolean,
+            unsupported: isBoolean,
+            error: isNullableString,
+            pinnedVersionUnavailable: isPinnedVersionUnavailable,
+        },
+    },
+    agent_steer: {
+        required: { id: isString, sessionRef: isString, text: isString },
+        optional: { images: isImageBlockArray, priority: isString },
+    },
+    agent_steered: {
+        required: { id: isString, ok: isBoolean },
+        optional: { outcome: isSteerOutcome, error: isNullableString },
+    },
+    agent_backfill_events: {
+        required: { id: isString, events: (events) => Array.isArray(events) && events.every(isEvent) },
+    },
+    agent_backfill_done: {
+        required: { id: isString, ok: isBoolean, count: isNumber },
+        optional: { error: isNullableString },
+    },
+    agent_set_config_option: {
+        required: { id: isString, sessionRef: isString, configId: isString, value: isConfigOptionValue },
+    },
+    agent_config_option_set: {
+        required: { id: isString, ok: isBoolean },
+        optional: { configOptions: isNullableSessionConfigOptionArray, error: isNullableString },
+    },
+};
+const DISCRIMINATORS = new Set(Object.keys(AGENT_FRAME_SHAPES));
+function isRecord(value) { return isObject(value); }
+function isAgentResumeSession(value) {
+    return isObject(value)
+        && hasRequired(value, { sessionRef: isString, journalMaxSeq: isNumber, agentAlive: isBoolean });
+}
+/**
+ * Accepts only the two outcomes this client can produce. `startedNewTurn` is refused on purpose: it
+ * is the extension's third outcome, and receiving one means a peer invented a disposition for a
+ * message the server has already put on its timeline — see `acpSession.ts`'s `mapSteerOutcome`.
+ */
+function isSteerOutcome(value) { return value === 'injected' || value === 'promptRequired'; }
+/** Accepts `true` and nothing else — the whole point of `authenticated` having no `false`. */
+function isVerifiedTrue(value) { return value === true; }
+/**
+ * 一个能当毫秒预算用的数,或者「没人指定」。
+ *
+ * `null` 与缺席都读作后者(服务端的 `AgentVerify.timeoutMs` 是 `Long?`,虽然它配了
+ * `EncodeDefault.NEVER` 因而不会真把 null 写上线,但守卫不该依赖发送方的编码设置)。**拒绝**
+ * `NaN` / `Infinity` / 负数 / 0 / 非数:它们全都会变成一个没有人想要的 setTimeout —— 立刻超时
+ * 或永不超时,而不是"这次多等一会儿"。上界不在这里判,在 `clampProbeTimeout` 里夹紧:一个过大
+ * 但成形的数是**可以执行**的请求(夹到上限即可),而一个畸形的数不是。
+ */
+function isNullableProbeTimeoutMs(value) {
+    if (value === undefined || value === null)
+        return true;
+    return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+/**
+ * A JSON-RPC error code, or "this failure had none".
+ *
+ * `null` and absent both read as the latter — a refusal that was not a JSON-RPC one, a workstation
+ * failure the agent never answered, or a peer that predates the field. Anything else must be an
+ * integer inside the Kotlin twin's `Int`: a fractional or out-of-range number does not merely lose
+ * precision on the way over, it fails to decode and takes the **whole frame** with it, which is
+ * exactly how `stat().mtimeMs` once cost an entire agent channel. This guard is the second of the
+ * two that stop it — `jsonRpcErrorCode` already refuses to produce one on the way out — and it is
+ * the one that also covers a peer this daemon did not write.
+ */
+function isNullableJsonRpcErrorCode(value) {
+    if (value === undefined || value === null)
+        return true;
+    return typeof value === 'number' && Number.isInteger(value)
+        && value >= -2_147_483_648 && value <= 2_147_483_647;
+}
+/**
+ * 一整份命令表,或者「没人看过」。
+ *
+ * 缺席与空表在这里必须分得开:缺席读作「问不到」,`[]` 读作「这个 agent 声明了零条命令」。
+ * 所以这个守卫接受 `undefined`(键不在)与 `[]`(键在、表空),但**拒绝**任何一条不成形的条目
+ * ——半解码的表比没有表更糟,它会让菜单列出点下去什么也不会发生的项。
+ */
+function isNullableAvailableCommandArray(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (!Array.isArray(value))
+        return false;
+    return value.every((entry) => typeof entry === 'object' && entry !== null &&
+        typeof entry.name === 'string' &&
+        typeof entry.description === 'string' &&
+        (entry.inputHint === undefined ||
+            entry.inputHint === null ||
+            typeof entry.inputHint === 'string'));
+}
+/** Guards {@link SelectOptionWire}: `value`/`name` required strings, `description` optional-and-nullable. */
+function isSelectOption(value) {
+    return isObject(value) && typeof value.value === 'string'
+        && typeof value.name === 'string'
+        && hasOptional(value, { description: isNullableString });
+}
+/** Guards {@link SelectGroupWire}: a named cluster whose `options` are all {@link SelectOptionWire}. */
+function isSelectGroup(value) {
+    return isObject(value) && typeof value.group === 'string'
+        && typeof value.name === 'string'
+        && Array.isArray(value.options) && value.options.every(isSelectOption);
+}
+/**
+ * Guards one {@link SessionConfigOptionWire}. `currentValue`'s required type follows the
+ * discriminator — a `select` option's value is the id of one of its own `options`, a `boolean`
+ * option's is the toggle state — so a mismatch here (a `select` with a boolean `currentValue`, or
+ * vice versa) is refused rather than forwarded as an option no UI can render.
+ */
+function isSessionConfigOption(value) {
+    if (!isObject(value))
+        return false;
+    const o = value;
+    if (typeof o.id !== 'string' || typeof o.name !== 'string')
+        return false;
+    if (!hasOptional(value, { description: isNullableString, category: isNullableString }))
+        return false;
+    if (o.type === 'boolean')
+        return typeof o.currentValue === 'boolean';
+    if (o.type === 'select') {
+        if (typeof o.currentValue !== 'string' || !Array.isArray(o.options))
+            return false;
+        return o.options.every(isSelectOption) || o.options.every(isSelectGroup);
+    }
+    return false;
+}
+/**
+ * 一整份配置选项快照,或者「没人看过」。同 {@link isNullableAvailableCommandArray} 的缺席/空表
+ * 约定:缺席读作「问不到」,`[]` 读作「这个 agent 声明了零个配置项」,任何一条不成形的条目都拒绝
+ * ——半解码的表比没有表更糟。
+ */
+export function isNullableSessionConfigOptionArray(value) {
+    if (value === undefined || value === null)
+        return true;
+    return Array.isArray(value) && value.every(isSessionConfigOption);
+}
+/** Guards {@link ConfigOptionValueWire}: `agent_set_config_option.value` is a select id or a boolean toggle. */
+function isConfigOptionValue(value) { return typeof value === 'string' || typeof value === 'boolean'; }
+/**
+ * Guards {@link AgentInfoWire}: `name` required, `title`/`version` optional-and-nullable.
+ *
+ * This is deliberately laxer than ACP's own `Implementation` (`types.gen.d.ts:2306-2321`), which
+ * declares `version` required and non-nullable (`title` is the one that is optional-and-nullable
+ * there). ACP requires it; this guard accepts its absence anyway, because the consequence of
+ * refusing it is disproportionate: `agent_opened` is a single reply, not a per-field message, so a
+ * decode failure here does not drop just `agentInfo` — `outboundAgentFrameRejection`'s round-trip
+ * check fails the whole frame, `agentSessions.ts` sends `{ok:false}` instead, and the session fails
+ * to open over a display-only version string. Accepting a spec-incomplete `agentInfo` costs nothing
+ * a consumer cares about; rejecting one costs the session.
+ */
+function isAgentInfo(value) {
+    return isObject(value)
+        && hasRequired(value, { name: isString })
+        && hasOptional(value, { title: isNullableString, version: isNullableString });
+}
+/** Guards `agent_installed.pinnedVersionUnavailable` — see that field's own doc comment. */
+function isPinnedVersionUnavailable(value) {
+    return isObject(value) && hasRequired(value, { pinned: isString, installedInstead: isString });
+}
+/**
+ * Guards {@link ImageBlockWire}. Strict on every field ACP declares required, and on the
+ * discriminator: a block missing `mimeType` reaches the agent as an undecodable blob, and one whose
+ * `type` is anything but `image` would be some other content variant smuggled through a field named
+ * for images. Both are refused here rather than half-forwarded -- the same rule the Kotlin side's
+ * `AcpContentBlock.fromWire` follows ("a missing required field yields null, never a partial
+ * block"), because half an image is worse than no image: the agent answers about something it could
+ * not read, and nothing on the timeline says why.
+ *
+ * `uri` is ACP's own optional-and-nullable field (`types.gen.d.ts:330-332`).
+ */
+function isImageBlock(value) {
+    return isObject(value)
+        && value.type === 'image'
+        && hasRequired(value, { data: isString, mimeType: isString })
+        && hasOptional(value, { uri: isNullableString });
+}
+function isImageBlockArray(value) {
+    return Array.isArray(value) && value.every(isImageBlock);
+}
+function isNativeSession(value) {
+    return isObject(value) && hasRequired(value, {
+        nativeSessionId: isString, title: isString, updatedAtEpochMs: isNumber, cwd: isString,
+    });
+}
+function isEvent(value) {
+    return isObject(value) && hasRequired(value, { eventName: isString, payload: isRecord });
+}
+function isAgentFrame(value) {
+    // Cast, not a narrowed lookup: `value.t` is unvetted wire input, so it may not be one of
+    // `AgentFrame['t']`'s literals at all — the `!shape` check right below is what actually handles
+    // that, exactly as it did when this table was indexed by plain `string`.
+    const shape = AGENT_FRAME_SHAPES[String(value.t)];
+    if (!shape)
+        return false;
+    return hasRequired(value, shape.required) && hasOptional(value, shape.optional ?? {});
+}
+/**
+ * Fields the Kotlin twin declares as `Long` or `Int`, per frame type.
+ *
+ * TypeScript has one number type and the shape guards above accept any finite one, so a fractional
+ * value passes every check on this side and then fails to decode on the other — the field does not
+ * lose precision, the whole frame becomes unreadable. `stat().mtimeMs` is fractional on macOS and
+ * reached the wire twice, from two different bridges, before this table existed.
+ */
+const INTEGER_FIELDS = {
+    agent_ready: ['agentWire'],
+    heartbeat: ['seq', 'sentAtEpochMs'],
+    heartbeat_ack: ['seq'],
+    agent_open: ['resumeFromSeq'],
+    agent_opened: ['errorCode'],
+    agent_event: ['seq'],
+    agent_turn_done: ['seq', 'errorCode'],
+    agent_event_ack: ['throughSeq'],
+    agent_backfill_done: ['count'],
+};
+/**
+ * Why an `authenticated` field must not go out, or null when it may.
+ *
+ * ACP v1 offers no way to ask an agent whether it is authenticated, and no way to be told that it is
+ * not: the only positive evidence is a session the agent accepted, and everything else — a
+ * subprocess that would not start, an agent we have never connected to, a `session/new` that failed
+ * for some unrelated reason — is *unknown*. Publishing unknown as `authenticated: false` would put a
+ * "sign in again" prompt in front of a user whose credentials are perfectly good, and they would
+ * have no way to tell the fabricated verdict from a real one.
+ *
+ * So the field is `true`-or-absent, and this is where that is enforced rather than merely intended.
+ * {@link isVerifiedTrue} already makes the decoder refuse a `false`, but a decode failure names only
+ * the frame; this names the field, which is what a caller needs to find the line that produced it.
+ */
+function authenticatedViolation(frame) {
+    if (frame.t !== 'agent_verified')
+        return null;
+    const value = frame.authenticated;
+    if (value === undefined || value === true)
+        return null;
+    return `${frame.t}.authenticated may only be true or absent (absent means unknown, never ` +
+        `"not authenticated"), got ${String(value)}`;
+}
+/**
+ * {@link authenticatedViolation}'s twin for `agent_installed.adapterInstalled`, and it exists for
+ * the same reason rather than out of symmetry: the settings page turns that field into the word
+ * "Configured" in front of a reader, so a `false` written where a key should simply be missing
+ * would be a claim about their machine that nothing on this side established.
+ */
+function adapterInstalledViolation(frame) {
+    if (frame.t !== 'agent_installed')
+        return null;
+    const value = frame.adapterInstalled;
+    if (value === undefined || value === true)
+        return null;
+    return `${frame.t}.adapterInstalled may only be true or absent (absent means the adapter did not ` +
+        `get onto the machine), got ${String(value)}`;
+}
+function integerViolation(frame) {
+    for (const field of INTEGER_FIELDS[frame.t] ?? []) {
+        const value = frame[field];
+        if (value !== undefined && !Number.isInteger(value)) {
+            return `${frame.t}.${field} must be a whole number, got ${String(value)}`;
+        }
+    }
+    // The one integer that does not sit at the top level, and the one that actually broke.
+    if (frame.t === 'agent_native_sessions' && Array.isArray(frame.sessions)) {
+        for (const [index, session] of frame.sessions.entries()) {
+            const value = session?.updatedAtEpochMs;
+            if (!Number.isInteger(value)) {
+                return `agent_native_sessions.sessions[${index}].updatedAtEpochMs must be a whole number, got ${String(value)}`;
+            }
+        }
+    }
+    // `journalMaxSeq` is a Kotlin `Long` on both carriers of the inventory, so both need the rule: a
+    // fractional value does not lose precision on the far side, it makes the whole frame undecodable
+    // -- and on the heartbeat that costs liveness, not just an event.
+    if (frame.t === 'agent_resume_offer' || frame.t === 'heartbeat') {
+        for (const [index, session] of (frame.sessions ?? []).entries()) {
+            if (!Number.isInteger(session.journalMaxSeq)) {
+                return `${frame.t}.sessions[${index}].journalMaxSeq must be a whole number, got ${String(session.journalMaxSeq)}`;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Why this frame must not be put on the wire, or null when it may go.
+ *
+ * Checked by round-tripping through our own decoder rather than against a second schema, so the
+ * outbound contract cannot drift from the inbound one, plus the integer rule the decoder cannot
+ * express. What the peer will read is exactly what gets checked: `JSON.stringify` drops `undefined`
+ * and applies `toJSON`, so the parsed form is the only faithful subject.
+ *
+ * Total — every failure comes back as a string, including a frame that cannot be serialized at all.
+ */
+export function outboundAgentFrameRejection(frame) {
+    // Integers first, because that check names the offending field while the decoder can only name
+    // the frame. It is also the only one that sees `NaN`: `JSON.stringify` writes NaN as `null`, so
+    // by the time the round trip runs, a timestamp that was never a number looks like a missing one.
+    const violation = integerViolation(frame) ?? authenticatedViolation(frame) ?? adapterInstalledViolation(frame);
+    if (violation)
+        return violation;
+    try {
+        decodeAgentFrame(encodeAgentFrame(frame));
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    return null;
+}
+/**
+ * A well-formed failure to send in place of a frame that answered a server request, or null when
+ * the frame answered nothing and can only be dropped.
+ *
+ * Without this the requester waits out its timeout and reports the workstation as unresponsive,
+ * which sends whoever is debugging after the network instead of after the bridge that produced the
+ * bad value. `agent_backfill_events` is not itself an answer, but losing a batch makes the backfill
+ * incomplete, so it fails as its terminator would.
+ */
+export function outboundFailureReply(frame, reason) {
+    const id = frame.id;
+    // The id is what routes the failure back. If that is the malformed part there is no one to tell.
+    if (typeof id !== 'string' || id.length === 0)
+        return null;
+    const error = `the workstation client produced a malformed ${frame.t}: ${reason}`;
+    switch (frame.t) {
+        case 'agent_opened': return { t: 'agent_opened', id, ok: false, error };
+        case 'agent_native_sessions': return { t: 'agent_native_sessions', id, ok: false, error };
+        case 'agent_verified': return { t: 'agent_verified', id, ok: false, error };
+        case 'agent_authenticated': return { t: 'agent_authenticated', id, ok: false, error };
+        case 'agent_installed': return { t: 'agent_installed', id, ok: false, error };
+        case 'agent_steered': return { t: 'agent_steered', id, ok: false, error };
+        case 'agent_config_option_set': return { t: 'agent_config_option_set', id, ok: false, error };
+        case 'agent_backfill_done':
+        case 'agent_backfill_events': return { t: 'agent_backfill_done', id, ok: false, count: 0, error };
+        default: return null;
+    }
+}
+export function encodeAgentFrame(frame) {
+    return JSON.stringify(frame);
+}
+export function decodeAgentFrame(text) {
+    return decodeChannelFrame(text, DISCRIMINATORS, isAgentFrame);
+}