@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/oauth/deviceAuthorization.js

@@ -2,6 +2,8 @@ import WebSocket from 'ws';
 import { RetryPolicy } from '../connection/retryPolicy.js';
 import { tryOpenAuthorizationUrl } from './browser.js';
 import { loadDeviceId } from '../../config.js';
+import { DEFAULT_CLI_SCOPES, grantedCliScopes } from '../../authScopes.js';
+import { revokeRefreshToken } from '../../credentials.js';
 export const DEVICE_CODE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
 export class DeviceAuthorizationError extends Error {
 }
@@ -87,7 +89,7 @@ function waitForNotification(socket, sessionId, notificationTicket, deadline, no
         socket.on('error', () => finish('reconnect'));
     });
 }
-async function exchangeDeviceCode(server, clientId, deviceCode, fetch_) {
+async function exchangeDeviceCode(server, clientId, deviceCode, fetch_, requestedScopes) {
     const response = await requestJson(fetch_, new URL('/oauth/token', server), {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded' },
@@ -98,14 +100,25 @@ async function exchangeDeviceCode(server, clientId, deviceCode, fetch_) {
             device_id: await loadDeviceId(),
         }),
     }, 200, 'Device token exchange');
+    return validateTokenResponse(server, response, requestedScopes, fetch_);
+}
+async function validateTokenResponse(server, response, requestedScopes, fetch_) {
     const accessToken = requireString(response.access_token, 'access_token', 'Device token response');
     const refreshToken = requireString(response.refresh_token, 'refresh_token', 'Device token response');
     if (!Number.isFinite(response.expires_in) || response.expires_in <= 0) {
         throw new DeviceAuthorizationError('Device token response has invalid expires_in');
     }
-    return { accessToken, refreshToken, expiresInSeconds: response.expires_in };
+    let scopes;
+    try {
+        scopes = grantedCliScopes(response.scope, requestedScopes);
+    }
+    catch (error) {
+        await revokeRefreshToken(server, refreshToken, fetch_);
+        throw new DeviceAuthorizationError(error instanceof Error ? error.message : 'Device token response has invalid scopes');
+    }
+    return { accessToken, refreshToken, expiresInSeconds: response.expires_in, scopes };
 }
-async function pollDeviceCode(server, clientId, deviceCode, fetch_) {
+async function pollDeviceCode(server, clientId, deviceCode, fetch_, requestedScopes) {
     const response = await fetch_(new URL('/oauth/token', server), {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded' },
@@ -128,17 +141,13 @@ async function pollDeviceCode(server, clientId, deviceCode, fetch_) {
     if (response.status !== 200)
         throw new DeviceAuthorizationError(`Device token polling failed: ${response.status}`);
     const token = await response.json();
-    return {
-        accessToken: requireString(token.access_token, 'access_token', 'Device token response'),
-        refreshToken: requireString(token.refresh_token, 'refresh_token', 'Device token response'),
-        expiresInSeconds: token.expires_in,
-    };
+    return validateTokenResponse(server, token, requestedScopes, fetch_);
 }
 /**
  * Uses OAuth Device Authorization for both desktop and headless clients. The notification socket
  * only carries state; the tokens exist only in this call's return value.
  */
-export async function authorizeDevice(server, clientName, hostname, deps = {}) {
+export async function authorizeDevice(server, clientName, hostname, deps = {}, requestedScopes = DEFAULT_CLI_SCOPES) {
     const baseUrl = normalizedServer(server);
     const fetch_ = deps.fetch ?? globalThis.fetch;
     const print = deps.print ?? console.log;
@@ -151,7 +160,7 @@ export async function authorizeDevice(server, clientName, hostname, deps = {}) {
     const authorization = await requestJson(fetch_, new URL('/oauth/device_authorization', baseUrl), {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded' },
-        body: new URLSearchParams({ client_id: clientId, hostname }),
+        body: new URLSearchParams({ client_id: clientId, hostname, scope: requestedScopes.join(' ') }),
     }, 200, 'Device authorization request');
     const deviceCode = requireString(authorization.device_code, 'device_code', 'Device authorization response');
     const verificationUrl = requireString(authorization.verification_uri_complete, 'verification_uri_complete', 'Device authorization response');
@@ -178,14 +187,14 @@ export async function authorizeDevice(server, clientName, hostname, deps = {}) {
         }
         const status = await waitForNotification(socket, sessionId, notificationTicket, deadline, now, () => retry.recordSuccess());
         if (status === 'approved') {
-            const tokens = await exchangeDeviceCode(baseUrl, clientId, deviceCode, fetch_);
+            const tokens = await exchangeDeviceCode(baseUrl, clientId, deviceCode, fetch_, requestedScopes);
             return { clientId, ...tokens };
         }
         if (status === 'denied')
             throw new DeviceAuthorizationError('Device authorization was denied');
         if (status === 'expired')
             break;
-        const polled = await pollDeviceCode(baseUrl, clientId, deviceCode, fetch_);
+        const polled = await pollDeviceCode(baseUrl, clientId, deviceCode, fetch_, requestedScopes);
         if (polled)
             return { clientId, ...polled };
         const pollingFloor = Math.max(1, authorization.interval ?? 5) * 1_000;

package/dist/workstation/protocol/accountLimits.js

@@ -0,0 +1,47 @@
+/** Bounded, plain-JS wire validation: usable inside the deterministic ACP processor. */
+export const ACCOUNT_LIMITS_READ_TIMEOUT_MS = 180_000;
+const object = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const text = (v, min = 0, max = 160) => typeof v === 'string' && v.length >= min && v.length <= max;
+const time = (v) => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(v) && Number.isFinite(new Date(v).getTime());
+const oneOf = (v, values) => typeof v === 'string' && values.includes(v);
+function parse(value) {
+    const valid = object(value) && value.schemaVersion === 1 && text(value.provider, 1, 64)
+        && (value.updateMode === undefined || oneOf(value.updateMode, ['snapshot', 'delta']))
+        && oneOf(value.billingMode, ['subscription', 'non_subscription', 'unknown'])
+        && oneOf(value.availability, ['available', 'unavailable', 'unknown', 'not_applicable']) && time(value.observedAt)
+        && (value.plan === null || object(value.plan) && text(value.plan.id) && text(value.plan.label))
+        && (value.accountKey === undefined || text(value.accountKey, 0, 128))
+        && Array.isArray(value.limits) && value.limits.length <= 32 && value.limits.every(row => object(row)
+        && text(row.id, 1) && text(row.label) && oneOf(row.kind, ['subscription', 'spend', 'rate'])
+        && (row.windowSeconds === null || typeof row.windowSeconds === 'number' && Number.isInteger(row.windowSeconds) && row.windowSeconds > 0)
+        && (row.period == null || text(row.period))
+        && (row.key === undefined || row.key === null || text(row.key, 1, 64))
+        && (row.usedPercent === null || typeof row.usedPercent === 'number' && Number.isFinite(row.usedPercent) && row.usedPercent >= 0 && row.usedPercent <= 100)
+        && (row.resetsAt === null || time(row.resetsAt)) && oneOf(row.status, ['allowed', 'warning', 'blocked', 'unknown'])
+        && (row.active == null || typeof row.active === 'boolean') && (row.scope == null || object(row.scope))
+        && ['used', 'limit', 'unit', 'currency'].every(key => row[key] === undefined || text(row[key]))
+        && (row.exponent === undefined || typeof row.exponent === 'number' && Number.isInteger(row.exponent) && row.exponent >= 0 && row.exponent <= 12))
+        && new Set(value.limits.map(row => row.id)).size === value.limits.length
+        && Array.isArray(value.balances) && value.balances.length <= 16 && value.balances.every(row => object(row)
+        && text(row.id, 1) && text(row.label) && text(row.unit) && (row.remaining === null || text(row.remaining))
+        && (row.currency === undefined || text(row.currency)) && (row.unlimited === undefined || typeof row.unlimited === 'boolean')
+        && (row.exponent === undefined || typeof row.exponent === 'number' && Number.isInteger(row.exponent) && row.exponent >= 0 && row.exponent <= 12))
+        && new Set(value.balances.map(row => row.id)).size === value.balances.length
+        && (value._meta === undefined || object(value._meta)) && JSON.stringify(value).length <= 65_536;
+    if (!valid)
+        throw new Error('Invalid account quota snapshot');
+    return { ...value, _meta: value._meta ?? {} };
+}
+export const accountLimitsSchema = {
+    parse,
+    safeParse(value) {
+        try {
+            return { success: true, data: parse(value) };
+        }
+        catch {
+            return { success: false, error: new Error('Invalid account quota snapshot') };
+        }
+    },
+};
+export const ACCOUNT_LIMITS_READ = '_axom/account/rateLimits/read';
+export const ACCOUNT_LIMITS_UPDATED = '_axom/account/rateLimits/updated';

package/dist/workstation/protocol/agent.js

@@ -1,6 +1,26 @@
+import { accountLimitsSchema } from './accountLimits.js';
+import { isRuntimeDiagnostics } from '../qoderAdapter/profile.js';
 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_VERSION = 27;
+/**
+ * `agent_switch_idle` / `agent_switch_idle_result` (spec 2026-10-11 §6.4, Task 25): "move idle sessions" of one agent to another
+ * adapter build. A server-to-client request: the server sends it only to a client advertising this version (an older one has no
+ * case for it and the request would only die at its timeout).
+ */
+export const AGENT_WIRE_ACCOUNT_LIMITS_VERSION = 27;
+export const AGENT_WIRE_SWITCH_IDLE_VERSION = 26;
+/** `agent_delete_native` / `agent_native_deleted`: purge a session Axom created on an external agent. */
+export const AGENT_WIRE_NATIVE_DELETE_VERSION = 24;
+export const AGENT_WIRE_PROVIDER_TASK_VERSION = 23;
+export const AGENT_WIRE_RUNTIME_PROFILE_VERSION = 22;
+export const AGENT_WIRE_DELEGATION_RENEW_VERSION = 21;
+export const AGENT_WIRE_TURN_IDENTITY_VERSION = 20;
+export const AGENT_WIRE_DELEGATION_MCP_VERSION = 19;
+/** Scoped replay/history is enabled only when both peers preserve native origin. */
+export const AGENT_WIRE_SCOPED_ORIGIN_VERSION = 18;
+/** agent_open.requireSessionLoad: reject unsupported/failed load without session/new fallback. */
+export const AGENT_WIRE_STRICT_LOAD_VERSION = 17;
 export const AGENT_WIRE_MIN_VERSION = 1;
 export const AGENT_WIRE_SESSION_LOST_VERSION = 2;
 export const AGENT_WIRE_ADOPTION_VERSION = 3;
@@ -137,12 +157,65 @@ export const AGENT_WIRE_RELOADED_VERSION = 13;
  * 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;
+/**
+ * The session activity-state push (`agent_session_state`) and the single-background-task stop
+ * request (`agent_async_task_stop`). **Both must be checked before sending — the check just lives
+ * in a different process for each, because the two frames do not share a sender.**
+ *
+ * ## Why both need a floor, not just one
+ *
+ * A version floor answers one question: *before sending, does the peer understand this frame?*
+ * These two frames travel opposite directions, so the check lives on opposite sides:
+ *
+ * - `agent_async_task_stop` is the **server's** request to this client. A v14 *client* has no case
+ *   for it in `AGENT_FRAME_SHAPES` — the same shape as {@link AGENT_WIRE_STEER_VERSION} and
+ *   {@link AGENT_WIRE_INSTALL_VERSION} — so the check lives on the Kotlin server (this constant's
+ *   twin, `AgentChannelSession`, a later task), before every `agent_async_task_stop` it sends. There
+ *   is nothing for this file to check on receipt: this daemon only ever handles the frame, never
+ *   sends it.
+ * - `agent_session_state` is the **client's** push to the server, and getting this half wrong is
+ *   what an earlier revision of this comment did — it argued "an old server just never sees the
+ *   frame" was enough, which is only half the compatibility matrix and not the dangerous half. The
+ *   dangerous direction is **a newer client talking to an older server**: this daemon is a
+ *   separately-installed npm package on the user's machine, so the client upgrading ahead of the
+ *   server is the ordinary update order here, not an edge case. A v15 client sending
+ *   `agent_session_state` to a v14 server hits a decoder that throws on the unrecognised
+ *   discriminator, and because the frame carries a top-level `sessionRef` and no `id`, the server's
+ *   own recovery (`classifyUndecodableAgentFrame`) charges it to `FailSession` — declaring that
+ *   session lost and forcing a reopen. This frame exists to be sent over and over, so on an
+ *   unupgraded server every single push would force a session loss, and a run of them closes the
+ *   whole agent channel — worse than the `agent_auth_url` incident this file already documents,
+ *   since that frame carries no `sessionRef` and only ever reaches `Unattributable`.
+ *
+ *   The correct precedent is {@link AGENT_WIRE_AUTH_URL_VERSION}, not
+ *   {@link AGENT_WIRE_RELOADED_VERSION}: `agent_opened.reloaded` is an **optional key on a frame the
+ *   peer already decodes**, safely absorbed by `ignoreUnknownKeys`, so nothing on the sending side
+ *   needs to check anything. `agent_session_state` is a **new discriminator**, and a decoder throws
+ *   on an unrecognised one before `ignoreUnknownKeys` ever gets a say — the same shape
+ *   `agent_auth_url` is, and that constant's own floor is checked client-side (`serverAgentWire <
+ *   AGENT_WIRE_AUTH_URL_VERSION`, see `agentSessions.ts`'s `onAuthenticate`/`present`/`dismiss`) for
+ *   exactly this reason. `agent_session_state` follows the same rule: the client checks
+ *   `this.serverAgentWire` before sending and **discards** the push below this floor, rather than
+ *   erroring — a level nobody downstream can read is no worse than one that was never collected.
+ *
+ * So both frames are gated, on opposite sides: this file's own send path (a later task) must check
+ * `serverAgentWire` before every `agent_session_state`, and the Kotlin twin must check
+ * `clientAgentWire` before every `agent_async_task_stop`.
+ */
+export const AGENT_WIRE_SESSION_STATE_VERSION = 15;
+/**
+ * Elicitation answers (`agent_elicitation_answer`). Checked before sending, like
+ * {@link AGENT_WIRE_INSTALL_VERSION} and {@link AGENT_WIRE_CONFIG_OPTIONS_VERSION}: a peer below
+ * this floor has no case for the frame at all and would drop it, leaving the agent process blocked
+ * inside `elicitation/create` rather than ever reaching the user's answer.
+ */
+export const AGENT_WIRE_ELICITATION_VERSION = 16;
 /**
  * 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
+ * (`protocol/agentRequiredFields.test.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
@@ -164,6 +237,7 @@ export const AGENT_FRAME_SHAPES = {
         optional: { sessions: (sessions) => Array.isArray(sessions) && sessions.every(isAgentResumeSession) },
     },
     heartbeat_ack: { required: { seq: isNumber } },
+    agent_reopen_request: { required: { sessionRef: isString, reason: isString } },
     agent_open: {
         required: {
             id: isString, sessionRef: isString, agentKey: isString, bridge: isString, cwd: isString, shell: isString,
@@ -171,7 +245,10 @@ export const AGENT_FRAME_SHAPES = {
         optional: {
             env: isStringRecord, pathPrepend: isStringArray, agentEnv: isStringRecord, command: isNullableString,
             args: isStringArray, nativeSessionId: isNullableString,
-            resumeFromSeq: isNumber, backfill: isBoolean,
+            resumeFromSeq: isNumber, backfill: isBoolean, requireSessionLoad: isBoolean,
+            delegationMcp: (value) => isObject(value) &&
+                isString(value.url) && isStringRecord(value.headers) && isNumber(value.expiresAtEpochMs) &&
+                (value.bindingId === undefined || isString(value.bindingId)),
         },
     },
     agent_opened: {
@@ -180,6 +257,7 @@ export const AGENT_FRAME_SHAPES = {
         // `false` would be a second spelling of what its absence already says.
         optional: {
             nativeSessionId: isNullableString, error: isNullableString, supportsSteering: isVerifiedTrue,
+            runtimeDiagnostics: isRuntimeDiagnostics,
             // 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.
@@ -187,16 +265,38 @@ export const AGENT_FRAME_SHAPES = {
             // `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,
+            delegationExpiresAtEpochMs: isNumber,
+            delegationRefreshPending: isVerifiedTrue,
+            delegationInstanceId: isString, delegationBindingId: isString, delegationRenewalRevision: isNumber,
             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,
+            // `true`-or-absent, the same rule as `supportsSteering` above: absence already means "no
+            // collector wired up", so a `false` would be a second spelling of it.
+            reportsActivity: isVerifiedTrue,
+            supportsAsyncTaskStop: isVerifiedTrue,
+            // Vendor-verbatim and uninterpreted here (decision L1) -- any object shape is accepted, the
+            // same lenience `agent_event.payload` gets via `isRecord`.
+            activityRaw: isRecord,
+            // Task 21 (spec §5.5.4): `true`-or-absent, and the two id lists.
+            durable: isVerifiedTrue, pendingRequestIds: isStringArray, steeredIds: isStringArray,
         },
     },
-    agent_prompt: { required: { sessionRef: isString, text: isString }, optional: { images: isImageBlockArray } },
+    agent_prompt: { required: { sessionRef: isString, text: isString }, optional: { images: isImageBlockArray, platformTurnId: isString } },
+    agent_delegation_renew: { required: { id: isString, sessionRef: isString, nativeSessionId: isString,
+            instanceId: isString, bindingId: isString, renewalRevision: isNumber, expiresAtEpochMs: isNumber } },
+    agent_delegation_renewed: { required: { id: isString, ok: isBoolean }, optional: { error: isString,
+            nativeSessionId: isString, instanceId: isString, bindingId: isString, renewalRevision: isNumber, expiresAtEpochMs: isNumber } },
     agent_answer: { required: { sessionRef: isString, requestId: isString, outcome: isString } },
+    // `content`'s interior is never validated here -- it is ACP's free-form elicitation payload, and
+    // this table is transport, not translator. `isRecord` only rejects a non-object.
+    agent_elicitation_answer: {
+        required: { sessionRef: isString, requestId: isString, action: isString },
+        optional: { content: isRecord },
+    },
     agent_interrupt: { required: { sessionRef: isString } },
     agent_close: { required: { sessionRef: isString } },
     agent_event: { required: { sessionRef: isString, seq: isNumber, eventName: isString, payload: isRecord } },
@@ -206,6 +306,8 @@ export const AGENT_FRAME_SHAPES = {
             stopReason: isString, nativeSessionId: isNullableString, error: isNullableString,
             authMethods: isNullableAuthMethodInfoArray,
             errorCode: isNullableJsonRpcErrorCode,
+            platformTurnId: isString,
+            executionEnded: isVerifiedTrue,
         },
     },
     agent_event_ack: { required: { sessionRef: isString, throughSeq: isNumber } },
@@ -214,6 +316,12 @@ export const AGENT_FRAME_SHAPES = {
     // 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 } },
+    // `query` is as lenient as `agent_list_native`'s, for the same reason.
+    agent_delete_native: { required: { id: isString, bridge: isString, query: () => true, nativeSessionIds: isStringArray } },
+    agent_native_deleted: {
+        required: { id: isString, ok: isBoolean },
+        optional: { results: isNativeDeleteResults, error: isNullableString },
+    },
     agent_native_sessions: {
         required: { id: isString, ok: isBoolean },
         optional: {
@@ -222,6 +330,9 @@ export const AGENT_FRAME_SHAPES = {
     },
     // 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_account_read: { required: { id: isString, bridge: isString, agentKey: isString, query: () => true } },
+    agent_account_read_result: { required: { id: isString, ok: isBoolean }, optional: { snapshot: (value) => accountLimitsSchema.safeParse(value).success, error: isString } },
+    agent_account_update: { required: { agentKey: isString, snapshot: (value) => accountLimitsSchema.safeParse(value).success } },
     agent_verify: {
         required: { id: isString, bridge: isString, query: () => true },
         // 与 `query` 那条**刻意的宽松**相反,这里是严格的:一份畸形的 query 还有个能回
@@ -290,17 +401,75 @@ export const AGENT_FRAME_SHAPES = {
         required: { id: isString, ok: isBoolean },
         optional: { configOptions: isNullableSessionConfigOptionArray, error: isNullableString },
     },
+    agent_session_state: { required: { sessionRef: isString, vendor: isString, raw: isRecord } },
+    agent_runtime_profile: { required: { sessionRef: isString, diagnostics: isRuntimeDiagnostics } },
+    agent_provider_task_event: { required: { sessionRef: isString, rootSessionId: isTaskId,
+            runtimeGeneration: isTaskId, taskId: isTaskId, uuid: isTaskId, state: isProviderTaskState,
+            live: isBoolean, stale: isBoolean }, optional: { taskType: isTaskType, background: isBoolean,
+            agentId: isTaskId, launchingToolUseId: isTaskId, status: isProviderTerminalState, summary: isTaskSummary } },
+    agent_provider_task_stop: { required: { id: isTaskId, sessionRef: isTaskId, rootSessionId: isTaskId,
+            runtimeGeneration: isTaskId, taskId: isTaskId, requestId: isTaskId } },
+    agent_provider_task_stopped: { required: { id: isTaskId, state: isProviderStopState },
+        optional: { error: isTaskSummary } },
+    agent_async_task_stop: { required: { sessionRef: isString, asyncTaskId: isString } },
+    agent_switch_idle: { required: { id: isString, bridge: isString }, optional: { toBuild: isString } },
+    agent_switch_idle_result: {
+        required: { id: isString, ok: isBoolean },
+        optional: { registered: isCount, immediate: isCount, unmovable: isSwitchIdleUnmovableArray, error: isNullableString },
+    },
 };
 const DISCRIMINATORS = new Set(Object.keys(AGENT_FRAME_SHAPES));
+/**
+ * `agent_reopen_request{sessionRef, reason}` (spec 2026-10-11 §6.3, C→S): a session that is idle and has a pending switch (an adapter
+ * update, a keeper-acp generation change) asks the server to send `agent_open{requireSessionLoad:true}` with the session's fresh
+ * environment — a switch needs the spawn secrets only an `agent_open` carries. Task 24 decides when; the manager's
+ * `requestReopen` sends it, and only to a server advertising {@link AGENT_WIRE_REOPEN_REQUEST_VERSION}: an older server cannot
+ * decode it, and eight undecodable frames in a row close the agent channel (spec §10: there the switch waits for a natural reopen).
+ */
+export const AGENT_WIRE_REOPEN_REQUEST_VERSION = 25;
+/**
+ * The same version (Task 22): the server acknowledges as soon as a subagent relation releases the watermark it capped, and stops
+ * wasting its 32-event ack count on capped attempts — so a sent relation-pinned outbox entry may count against the sending
+ * window again (`SessionOutbox.inflight`). Below it the entries keep not counting once sent (fix round 1 of Task 20).
+ */
+export const AGENT_WIRE_RELATION_ACK_VERSION = 25;
+export const AGENT_REOPEN_REQUEST_SHAPE = AGENT_FRAME_SHAPES.agent_reopen_request;
+export function agentReopenRequest(sessionRef, reason) {
+    return { t: 'agent_reopen_request', sessionRef, reason };
+}
+function isCount(value) { return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0; }
+function isSwitchIdleUnmovableArray(value) {
+    return Array.isArray(value) && value.every((entry) => isObject(entry) && isString(entry.sessionRef) && isString(entry.reason));
+}
 function isRecord(value) { return isObject(value); }
+function isTaskId(value) {
+    return typeof value === 'string' && value.length > 0 &&
+        Buffer.byteLength(value, 'utf8') <= 256 && !/[\x00-\x1f\x7f]/.test(value);
+}
+function isTaskType(value) { return isTaskId(value) && Buffer.byteLength(value, 'utf8') <= 128; }
+function isTaskSummary(value) {
+    return typeof value === 'string' &&
+        Buffer.byteLength(value, 'utf8') <= 8192;
+}
+function isProviderTaskState(value) {
+    return value === 'pending' || value === 'paused' || value === 'running' || value === 'completed' ||
+        value === 'stopped' || value === 'failed' || value === 'unknown';
+}
+function isProviderTerminalState(value) {
+    return value === 'completed' || value === 'failed' || value === 'stopped';
+}
+function isProviderStopState(value) {
+    return value === 'accepted' || value === 'unknown' || value === 'rejected';
+}
 function isAgentResumeSession(value) {
     return isObject(value)
-        && hasRequired(value, { sessionRef: isString, journalMaxSeq: isNumber, agentAlive: isBoolean });
+        && hasRequired(value, { sessionRef: isString, journalMaxSeq: isNumber, agentAlive: isBoolean })
+        && (value.pendingRequestIds === undefined || isStringArray(value.pendingRequestIds));
 }
 /**
  * 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`.
+ * message the server has already put on its timeline — see `acp/steering.ts`'s `mapSteerOutcome`.
  */
 function isSteerOutcome(value) { return value === 'injected' || value === 'promptRequired'; }
 /** Accepts `true` and nothing else — the whole point of `authenticated` having no `false`. */
@@ -448,8 +617,17 @@ function isNativeSession(value) {
         nativeSessionId: isString, title: isString, updatedAtEpochMs: isNumber, cwd: isString,
     });
 }
+function isNativeDeleteResult(value) {
+    return isObject(value)
+        && hasRequired(value, { nativeSessionId: isString, outcome: (o) => o === 'deleted' || o === 'unsupported' || o === 'failed' })
+        && hasOptional(value, { error: isNullableString });
+}
+function isNativeDeleteResults(value) {
+    return Array.isArray(value) && value.every(isNativeDeleteResult);
+}
 function isEvent(value) {
-    return isObject(value) && hasRequired(value, { eventName: isString, payload: isRecord });
+    return isObject(value) && hasRequired(value, { eventName: isString, payload: isRecord })
+        && hasOptional(value, { acpSessionId: isNullableString });
 }
 function isAgentFrame(value) {
     // Cast, not a narrowed lookup: `value.t` is unvetted wire input, so it may not be one of
@@ -588,11 +766,16 @@ export function outboundFailureReply(frame, 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_native_deleted': return { t: 'agent_native_deleted', 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_account_read_result': return { t: 'agent_account_read_result', id, ok: false, error };
         case 'agent_config_option_set': return { t: 'agent_config_option_set', id, ok: false, error };
+        case 'agent_delegation_renewed': return { t: 'agent_delegation_renewed', id, ok: false, error };
+        case 'agent_switch_idle_result': return { t: 'agent_switch_idle_result', id, ok: false, error };
+        case 'agent_provider_task_stopped': return { t: 'agent_provider_task_stopped', id, state: 'unknown', error };
         case 'agent_backfill_done':
         case 'agent_backfill_events': return { t: 'agent_backfill_done', id, ok: false, count: 0, error };
         default: return null;
@@ -602,5 +785,15 @@ export function encodeAgentFrame(frame) {
     return JSON.stringify(frame);
 }
 export function decodeAgentFrame(text) {
-    return decodeChannelFrame(text, DISCRIMINATORS, isAgentFrame);
+    const frame = decodeChannelFrame(text, DISCRIMINATORS, isAgentFrame);
+    if (frame.t === 'agent_provider_task_event') {
+        if ((frame.state === 'completed' || frame.state === 'failed' || frame.state === 'stopped') && frame.live)
+            throw new TypeError('Invalid provider task terminal live state');
+        if (frame.status !== undefined &&
+            (frame.status !== frame.state || !['completed', 'failed', 'stopped'].includes(frame.status)))
+            throw new TypeError('Invalid provider task terminal status');
+        if (frame.summary !== undefined && frame.status === undefined)
+            throw new TypeError('Provider task summary requires terminal status');
+    }
+    return frame;
 }

package/dist/workstation/protocol/common.js

@@ -23,6 +23,21 @@ export function isAuthMethodInfo(value) {
         && hasOptional(value, { type: isNullableString, description: isNullableString, args: isNullableStringArray });
 }
 export const isNullableAuthMethodInfoArray = (value) => value === null || (Array.isArray(value) && value.every(isAuthMethodInfo));
+export function isMissingPrerequisite(value) {
+    return isObject(value) && hasRequired(value, { label: isString }) && hasOptional(value, { hint: isString });
+}
+const isCount = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+export function isBridgeCurrentBuild(value) {
+    return isObject(value) && hasRequired(value, { id: isString, version: isString }) && hasOptional(value, { patched: isTrueOnly });
+}
+export function isBridgeBuild(value) {
+    return isObject(value)
+        && hasRequired(value, { id: isString, version: isString, sessions: isCount, idle: isCount, busy: isCount, unmovable: isCount })
+        && hasOptional(value, { patched: isTrueOnly, current: isTrueOnly, busyReasons: isStringArray, unmovableReasons: isStringArray });
+}
+export function isBridgeSwitchPending(value) {
+    return isObject(value) && hasRequired(value, { remaining: isCount }) && hasOptional(value, { toBuild: isString });
+}
 export function isBridgeInfo(value) {
     return isObject(value)
         && hasRequired(value, { type: isString })
@@ -49,7 +64,10 @@ export function isBridgeInfo(value) {
             // string is all a peer sending it without the flag is asked to satisfy.
             platformTriple: isString,
             // `true` and nothing else, like `supportsSteering`: see `BridgeInfo.recommended`.
+            curated: isTrueOnly,
             recommended: isTrueOnly,
+            detected: isTrueOnly,
+            missingPrerequisite: isMissingPrerequisite,
             defaultName: isNullableString,
             defaultLabel: isNullableString,
             // Optional on purpose: see BridgeInfo's doc comment — absent is "unknown", and a guard that
@@ -60,6 +78,11 @@ export function isBridgeInfo(value) {
             // A peer that sent one would be publishing "we looked and it cannot steer" through a key
             // whose absence already says exactly that, so refusing it keeps one spelling per fact.
             supportsSteering: isTrueOnly,
+            supportsAccountLimits: isTrueOnly,
+            // Task 25 (spec §6.4): scan-time build data. Optional: absent is "not looked at".
+            currentBuild: isBridgeCurrentBuild,
+            builds: (value) => Array.isArray(value) && value.every(isBridgeBuild),
+            switchPending: isBridgeSwitchPending,
         });
 }
 export function isBridgeInfoArray(value) {
@@ -97,6 +120,19 @@ export function bridgesForWire(bridges, frame) {
     }
     return kept;
 }
+/**
+ * The roster as a hello carries it: without the scan-only build fields (`currentBuild`/`builds`/`switchPending`, spec §6.4). The
+ * daemon keeps one cached roster, which a scan refreshes with those fields; a later reconnect's hello would otherwise carry a
+ * snapshot of sessions and pending moves that is stale by then. Only the scan answers them, fresh.
+ */
+export function helloRoster(bridges) {
+    return bridges.map((bridge) => {
+        if (bridge.currentBuild === undefined && bridge.builds === undefined && bridge.switchPending === undefined)
+            return bridge;
+        const { currentBuild: _current, builds: _builds, switchPending: _pending, ...rest } = bridge;
+        return rest;
+    });
+}
 function partitionWireSafeBridges(bridges) {
     let parsed;
     try {