@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/managedInstall.js

@@ -0,0 +1,57 @@
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { LocalControlError } from './control/protocol.js';
+const schema = z.object({ schemaVersion: z.literal(1), source: z.literal('managed'), prefix: z.string(), nodePath: z.string(), npmPath: z.string(), cliPath: z.string(), entryPath: z.string(), runtimeVersion: z.string().regex(/^24\.\d+\.\d+$/), architecture: z.enum(['arm64', 'x64']) }).strict();
+function plannedRealPath(value) {
+    try {
+        return realpathSync(value);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT' || path.dirname(value) === value)
+            throw error;
+        return path.join(plannedRealPath(path.dirname(value)), path.basename(value));
+    }
+}
+/** This synchronous variant is shared by the existing synchronous service-context constructors. */
+export function loadManagedCliInstallSync(packageRoot) {
+    let root;
+    try {
+        root = realpathSync(packageRoot);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    const prefix = path.resolve(root, '../../../..');
+    if (root !== path.join(prefix, 'lib/node_modules/@platless/axom-cli'))
+        return null;
+    const file = path.join(prefix, 'install.json');
+    let found = false;
+    try {
+        const stat = lstatSync(file);
+        found = true;
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16384 || (process.getuid && stat.uid !== process.getuid()) || (stat.mode & 0o077))
+            throw Error('Unsafe metadata');
+        const value = schema.parse(JSON.parse(readFileSync(file, 'utf8')));
+        const home = path.resolve(prefix, '../..');
+        const runtime = path.join(home, '.axom/runtime/node', `${value.runtimeVersion}-darwin-${value.architecture}`);
+        if (prefix !== path.join(home, '.axom/cli') || realpathSync(value.prefix) !== prefix || realpathSync(value.cliPath) !== path.join(root, 'dist/cli.js') || realpathSync(value.nodePath) !== path.join(runtime, 'bin/node') || realpathSync(value.npmPath) !== path.join(runtime, 'bin/npm') || plannedRealPath(value.entryPath) !== path.join(home, '.local/bin/axom'))
+            throw Error('Metadata does not describe this installation');
+        return value;
+    }
+    catch (error) {
+        if (!found && error.code === 'ENOENT')
+            return null;
+        throw new LocalControlError('UNSUPPORTED_INSTALLATION', 'The managed CLI installation needs repair');
+    }
+}
+export async function loadManagedCliInstall(packageRoot) { return loadManagedCliInstallSync(packageRoot); }
+export function npmExecutionContext(install, inherited) {
+    if (!install)
+        return { ...inherited };
+    const result = { ...inherited, NPM_CONFIG_PREFIX: install.prefix, PATH: `${path.dirname(install.nodePath)}:${inherited.PATH ?? '/usr/bin:/bin'}` };
+    delete result.npm_config_prefix;
+    return result;
+}

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,14 +1,20 @@
-import { isRuntimeDiagnostics } from '../qoderAdapter/profile.js';
+import { accountLimitsSchema } from './accountLimits.js';
+import { isRuntimeDiagnostics } from './runtimeDiagnostics.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 = 24;
+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. */
@@ -207,7 +213,7 @@ export const AGENT_WIRE_ELICITATION_VERSION = 16;
  *
  * 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
@@ -229,6 +235,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,
@@ -237,9 +244,6 @@ export const AGENT_FRAME_SHAPES = {
             env: isStringRecord, pathPrepend: isStringArray, agentEnv: isStringRecord, command: isNullableString,
             args: isStringArray, nativeSessionId: isNullableString,
             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: {
@@ -256,9 +260,6 @@ 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
@@ -272,13 +273,11 @@ export const AGENT_FRAME_SHAPES = {
             // 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, 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.
@@ -319,6 +318,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 还有个能回
@@ -398,8 +400,35 @@ export const AGENT_FRAME_SHAPES = {
     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 &&
@@ -422,12 +451,13 @@ function isProviderStopState(value) {
 }
 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`. */
@@ -729,8 +759,9 @@ export function outboundFailureReply(frame, reason) {
         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 };
@@ -746,7 +777,7 @@ export function decodeAgentFrame(text) {
         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)))
+            (frame.status !== frame.state || !['completed', 'failed', 'stopped'].some(status => status === 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');

package/dist/workstation/protocol/common.js

@@ -26,6 +26,18 @@ export const isNullableAuthMethodInfoArray = (value) => value === null || (Array
 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 })
@@ -66,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) {
@@ -103,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 {

package/dist/workstation/protocol/computer.js

@@ -6,6 +6,7 @@ const DISCRIMINATORS = new Set([
     'desktop_capability', 'desktop_open', 'desktop_opened', 'desktop_data', 'desktop_credit', 'desktop_close',
     'computer_hello', 'computer_ready', 'heartbeat', 'heartbeat_ack',
     'exec_request', 'exec_output', 'exec_exit', 'exec_cancel', 'tool_request', 'tool_result',
+    'exec_started', 'exec_ack', 'exec_attach', 'exec_status',
     'file_read_request', 'file_read_result', 'file_write_request', 'file_write_result',
     'file_ls_request', 'file_ls_result', 'file_mkdir_request', 'file_mkdir_result',
 ]);
@@ -16,6 +17,9 @@ const fileErrorCodes = new Set([
 ]);
 const isNonnegativeInteger = (value) => Number.isSafeInteger(value) && value >= 0;
 const isPositiveInteger = (value) => Number.isSafeInteger(value) && value >= 1;
+/** A record offset, or -1 for "none" (exec_status / exec_ack). */
+const isOffsetOrNone = (value) => Number.isSafeInteger(value) && value >= -1;
+const EXEC_STATES = new Set(['running', 'exited', 'unknown']);
 const isSha256 = (value) => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);
 const onlyKeys = (value, keys) => Object.keys(value).every(key => keys.includes(key));
 function isFileError(value) {
@@ -66,12 +70,19 @@ function isComputerFrame(value) {
         case 'exec_request': return hasRequired(value, {
             id: isString, command: isString, shell: isString, cwd: isString, env: isStringRecord,
             pathPrepend: isStringArray, streaming: isBoolean,
-        }) && hasOptional(value, { timeoutSeconds: isNullableNumber });
-        case 'exec_output': return hasRequired(value, { id: isString, stream: isString, chunk: isString });
+        }) && hasOptional(value, { timeoutSeconds: isNullableNumber, label: isString, jobId: isString });
+        case 'exec_started': return hasRequired(value, { id: isString, durable: isBoolean, startedAtMs: isNumber })
+            && hasOptional(value, { pid: isNonnegativeInteger });
+        case 'exec_output': return hasRequired(value, { id: isString, stream: isString, chunk: isString })
+            && hasOptional(value, { offset: isNonnegativeInteger, recvAtMs: isNumber });
+        case 'exec_ack': return hasRequired(value, { id: isString, throughOffset: isOffsetOrNone });
         case 'exec_exit': return hasRequired(value, {
             id: isString, exitCode: isNullableNumber, stdout: isString, stderr: isString,
             timedOut: isBoolean, truncated: isBoolean,
-        });
+        }) && hasOptional(value, { signal: isString, cancelled: isBoolean, gaps: isNonnegativeInteger });
+        case 'exec_attach': return hasRequired(value, { id: isString, fromOffset: isNonnegativeInteger });
+        case 'exec_status': return hasRequired(value, { id: isString, state: isString, headOffset: isOffsetOrNone, committedOffset: isOffsetOrNone })
+            && EXEC_STATES.has(value.state);
         case 'tool_request': return hasRequired(value, { id: isString, method: isString, params: isObject })
             && value.id.length > 0 && value.id.length <= 128
             && value.method.length > 0 && value.method.length <= 64
@@ -82,7 +93,7 @@ function isComputerFrame(value) {
             && (value.ok ? value.error === null : typeof value.error === 'string' && value.error.length > 0)
             && Buffer.byteLength(JSON.stringify(value)) <= TOOL_RESULT_BYTES
             && onlyKeys(value, ['t', 'id', 'ok', 'result', 'error']);
-        case 'exec_cancel': return hasRequired(value, { id: isString });
+        case 'exec_cancel': return hasRequired(value, { id: isString }) && hasOptional(value, { signal: isString });
         case 'file_read_request': return hasRequired(value, {
             id: isString, root: isString, path: isString, startLine: isPositiveInteger, maxLines: isPositiveInteger,
         }) && value.maxLines <= 2000 && onlyKeys(value, ['t', 'id', 'root', 'path', 'startLine', 'maxLines']);

package/dist/workstation/protocol/management.js

@@ -1,3 +1,4 @@
+import { decodeDesktopManagementFrame, parseDesktopJson, DesktopProtocolError } from '../desktopControl/protocol.js';
 import { decodeChannelFrame, hasOptional, hasRequired, isBoolean, isBridgeInfoArray, isNullableString, isNumber, isObject, isString, } from './common.js';
 export const MANAGEMENT_WIRE_MIN_VERSION = 1;
 /** Adds the `DRAINING` value to ClientUpdatePhase. */
@@ -8,11 +9,21 @@ export const MANAGEMENT_WIRE_METRICS_VERSION = 4;
 export const MANAGEMENT_WIRE_PRESSURE_VERSION = 5;
 /** Replaces normalized CPU load with raw 1/5/15-minute load averages and CPU capacity. */
 export const MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION = 6;
-export const MANAGEMENT_WIRE_VERSION = MANAGEMENT_WIRE_LOAD_AVERAGES_VERSION;
+/** Adds per-GPU utilization and GPU memory to heartbeat metrics. */
+export const MANAGEMENT_WIRE_GPU_VERSION = 7;
+/** Adds `keepers` to heartbeats and the `keeper_control` / `keeper_control_result` pair (spec §8.1, Task 26). */
+export const MANAGEMENT_WIRE_KEEPERS_VERSION = 8;
+export const MANAGEMENT_WIRE_DESKTOP_VERSION = 9;
+export const MANAGEMENT_WIRE_VERSION = MANAGEMENT_WIRE_DESKTOP_VERSION;
+/** Bounds of one heartbeat's `keepers` (spec §8.1). */
+export const KEEPER_STATUS_MAX_ITEMS = 32;
+export const KEEPER_LABEL_MAX_CHARS = 64;
+export const KEEPER_STATUS_MAX_ENTRIES = 16;
+export const KEEPER_AFFECTED_MAX_ITEMS = 256;
 const DISCRIMINATORS = new Set([
     'management_hello', 'management_ready', 'heartbeat', 'heartbeat_ack',
     'channel_ticket_request', 'channel_ticket', 'client_update', 'client_update_status',
-    'external_agents_scan', 'external_agents_scan_result',
+    'external_agents_scan', 'external_agents_scan_result', 'keeper_control', 'keeper_control_result',
 ]);
 const CHANNEL_KINDS = new Set(['MANAGEMENT', 'COMPUTER', 'AGENT']);
 const CHANNEL_STATES = new Set(['DISCONNECTED', 'CONNECTING', 'CONNECTED', 'RECONNECTING']);
@@ -63,6 +74,15 @@ function isStoragePoolMetrics(value) {
         availableBytes: isNumber,
     });
 }
+function isGpuMetrics(value) {
+    return isObject(value) && hasRequired(value, { id: isString, name: isString })
+        && hasOptional(value, {
+            utilization: isNullable(isNumber),
+            memoryTotalBytes: isNullable(isNumber),
+            memoryUsedBytes: isNullable(isNumber),
+            coreCount: isNullable(isNumber),
+        });
+}
 function isWorkstationMetrics(value) {
     return isObject(value) && hasRequired(value, {
         cpuUtilization: isNullable(isNumber),
@@ -76,8 +96,31 @@ function isWorkstationMetrics(value) {
         cpuLoad15: isNullable(isNumber),
         cpuLogicalCount: isNullable(isNumber),
         memoryPressure: isNullable(isNumber),
+        gpus: isNullable((gpus) => Array.isArray(gpus) && gpus.every(isGpuMetrics)),
     });
 }
+const KEEPER_KINDS = new Set(['terminal', 'acp']);
+const KEEPER_STATES = new Set(['running', 'starting', 'stopped', 'unavailable']);
+const KEEPER_REPLACEMENTS = new Set(['none', 'available', 'required', 'mandatory']);
+const KEEPER_ITEM_TYPES = new Set(['pty', 'exec', 'session']);
+const KEEPER_ACTIONS = new Set(['replace-when-idle', 'replace-now', 'cancel']);
+const oneOf = (set) => (value) => typeof value === 'string' && set.has(value);
+const isPending = (value) => value === null || value === 'when-idle';
+function isKeeperItem(value) {
+    return isObject(value) && hasRequired(value, { type: oneOf(KEEPER_ITEM_TYPES), id: isString, label: isString, state: isString, sinceEpochMs: isNumber })
+        && hasOptional(value, { jobId: isString });
+}
+function isKeeperStatus(value) {
+    return isObject(value) && hasRequired(value, {
+        kind: oneOf(KEEPER_KINDS), gen: isString, state: oneOf(KEEPER_STATES), protocolVersion: isNumber, buildVersion: isString,
+        replacement: oneOf(KEEPER_REPLACEMENTS),
+        metrics: (metrics) => isObject(metrics) && Object.values(metrics).every(isNumber),
+        items: (items) => Array.isArray(items) && items.length <= KEEPER_STATUS_MAX_ITEMS && items.every(isKeeperItem),
+    }) && hasOptional(value, { legacy: isBoolean, pending: isPending });
+}
+function isKeeperAffected(value) {
+    return isObject(value) && hasRequired(value, { type: oneOf(KEEPER_ITEM_TYPES), id: isString, label: isString, gen: isString });
+}
 function isManagementFrame(value) {
     switch (value.t) {
         case 'management_hello': return hasRequired(value, {
@@ -93,10 +136,14 @@ function isManagementFrame(value) {
             channels: (channels) => isObject(channels) && Object.entries(channels).every(([kind, state]) => CHANNEL_KINDS.has(kind) && isChannelState(state)),
             activeShellTasks: isNumber, activeAgentTasks: isNumber,
         }) && hasOptional(value, {
+            playgroundCwd: isString,
             protocols: (protocols) => isProtocolRangeMap(protocols, false),
             os: isNullable(isOsInfo),
+            toolchain: (toolchain) => isObject(toolchain) && hasRequired(toolchain, { python: isNullableString, node: isNullableString }),
             update: isNullable(isUpdateStatus),
             metrics: isNullable(isWorkstationMetrics),
+            keepers: isNullable((keepers) => Array.isArray(keepers) && keepers.every(isKeeperStatus)),
+            capabilitiesRevision: value => Number.isSafeInteger(value) && value > 0,
         });
         case 'heartbeat_ack': return hasRequired(value, { seq: isNumber });
         case 'channel_ticket_request': return hasRequired(value, { channel: isChannelKind });
@@ -105,12 +152,102 @@ function isManagementFrame(value) {
         case 'client_update_status': return hasRequired(value, { status: isUpdateStatus });
         case 'external_agents_scan': return hasRequired(value, { commandId: isString });
         case 'external_agents_scan_result': return hasRequired(value, { commandId: isString, bridges: isBridgeInfoArray });
+        case 'keeper_control': return hasRequired(value, { commandId: isString, kind: oneOf(KEEPER_KINDS), action: oneOf(KEEPER_ACTIONS) });
+        case 'keeper_control_result': return hasRequired(value, {
+            commandId: isString, kind: oneOf(KEEPER_KINDS), action: oneOf(KEEPER_ACTIONS), ok: isBoolean,
+            affected: (affected) => Array.isArray(affected) && affected.every(isKeeperAffected),
+        }) && hasOptional(value, { pending: isPending, error: isString, affectedIncomplete: (flag) => flag === true });
         default: return false;
     }
 }
 export function encodeManagementFrame(frame) {
-    return JSON.stringify(frame);
+    const text = JSON.stringify(frame);
+    if (isDesktopManagementType(frame.t))
+        decodeDesktopManagementFrame(text);
+    return text;
 }
-export function decodeManagementFrame(text) {
+export function decodeManagementFrame(source) {
+    const text = typeof source === 'string' ? source : new TextDecoder('utf-8', { fatal: true }).decode(source);
+    // Desktop extensions get the strict lexical/shape guard before any lossy object parsing.
+    const parsed = JSON.parse(text);
+    if (isObject(parsed) && isDesktopManagementType(parsed.t))
+        return decodeDesktopManagementFrame(text);
+    if (isObject(parsed) && parsed.t === 'heartbeat' && Object.hasOwn(parsed, 'capabilitiesRevision'))
+        validateHeartbeatRevision(text);
     return decodeChannelFrame(text, DISCRIMINATORS, isManagementFrame);
 }
+/** Select only the new root field. JSON.parse already validates syntax; legacy nesting, size,
+ * unknown fields and duplicate legacy keys keep their established decoder behavior. */
+function validateHeartbeatRevision(text) {
+    let depth = 0, count = 0;
+    for (let offset = 0; offset < text.length; offset++) {
+        const char = text[offset];
+        if (char === '"') {
+            const start = offset++;
+            while (offset < text.length) {
+                if (text[offset] === '\\')
+                    offset += 2;
+                else if (text[offset++] === '"')
+                    break;
+            }
+            const end = offset--;
+            if (depth !== 1 || JSON.parse(text.slice(start, end)) !== 'capabilitiesRevision')
+                continue;
+            let tokenStart = end;
+            while (/\s/.test(text[tokenStart] ?? ''))
+                tokenStart++;
+            if (text[tokenStart] !== ':')
+                continue; // This string was a legacy field's value.
+            let tokenEnd = ++tokenStart;
+            while (tokenEnd < text.length && text[tokenEnd] !== ',' && text[tokenEnd] !== '}')
+                tokenEnd++;
+            const token = text.slice(tokenStart, tokenEnd).trim();
+            if (++count !== 1 || !/^[1-9][0-9]*$/.test(token) || !Number.isSafeInteger(Number(token))) {
+                throw new DesktopProtocolError('Invalid capabilities revision');
+            }
+            parseDesktopJson(`{"capabilitiesRevision":${token}}`);
+        }
+        else if (char === '{' || char === '[')
+            depth++;
+        else if (char === '}' || char === ']')
+            depth--;
+    }
+}
+function isDesktopManagementType(type) {
+    return typeof type === 'string' && ['desktop_background', 'desktop_lobby', 'desktop_lobby_result', 'workstation_capabilities', 'workstation_capabilities_request', 'desktop_prepare',
+        'desktop_prepare_result', 'desktop_cancel', 'desktop_session_state'].includes(type);
+}
+export class ManagementFrameAdmission {
+    isCurrent;
+    ready;
+    disposed = false;
+    constructor(isCurrent = () => true) {
+        this.isCurrent = isCurrent;
+    }
+    admit(frame) {
+        if (this.disposed || !this.isCurrent())
+            return false;
+        if (frame.t === 'management_ready') {
+            if (this.ready || !Number.isInteger(frame.protocols.MANAGEMENT) || frame.protocols.MANAGEMENT < MANAGEMENT_WIRE_MIN_VERSION
+                || frame.protocols.MANAGEMENT > MANAGEMENT_WIRE_VERSION || !frame.generation)
+                return false;
+            this.ready = frame;
+            return true;
+        }
+        if (frame.t === 'heartbeat' && frame.capabilitiesRevision !== undefined)
+            return false;
+        if (!isDesktopManagementType(frame.t))
+            return true;
+        if (!this.ready || this.ready.protocols.MANAGEMENT < MANAGEMENT_WIRE_DESKTOP_VERSION)
+            return false;
+        switch (frame.t) {
+            case 'workstation_capabilities_request': return frame.generation === this.ready.generation;
+            case 'desktop_lobby':
+            case 'desktop_background':
+            case 'desktop_prepare': return frame.deviceGeneration === this.ready.generation;
+            case 'desktop_cancel': return true; // Current socket binding; T10 additionally fences its session/control generation.
+            default: return false; // Device-authored reports/results/states cannot be echoed as server activity.
+        }
+    }
+    dispose() { this.disposed = true; }
+}

package/dist/workstation/protocol/runtimeDiagnostics.js

@@ -0,0 +1,15 @@
+export function isRuntimeDiagnostics(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const input = value;
+    const bounded = (value, max) => typeof value === 'string' &&
+        value.trim().length > 0 && value.length <= max && !/[\x00-\x1f\x7f]/.test(value);
+    if (!bounded(input.generation, 256) || !Number.isSafeInteger(input.revision) ||
+        input.revision < 0 || typeof input.available !== 'boolean' ||
+        !input.launch || typeof input.launch !== 'object')
+        return false;
+    const launch = input.launch;
+    return ['command-override', 'registry', 'registry-fallback', 'direct'].includes(launch.source) &&
+        bounded(launch.executable, 4096) && bounded(launch.platform, 64) && bounded(launch.architecture, 64) &&
+        launch.transport === 'stdio' && (input.profile === undefined || (typeof input.profile === 'object' && input.profile !== null && !Array.isArray(input.profile)));
+}