@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/acp/patchAssets.js

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import semver from 'semver';
+import { assertSafePackageName } from './builds/model.js';
 // Production reads only assets shipped in this CLI. The .ts path is for source-based tests.
 export const patchAssetRoot = new URL(import.meta.url.endsWith('.ts') ? '../../../../axom-patch/cli/' : '../../axom-patch/cli/', import.meta.url);
 const runtime = JSON.parse(readFileSync(new URL('runtime.json', patchAssetRoot), 'utf8'));
@@ -20,9 +21,16 @@ function validateCondition(id, when, until, whenKey, untilKey) {
 export function validateOverride(entry) {
     validateCondition(entry.id, entry.when_registry_version, entry.until_registry_version, 'when_registry_version', 'until_registry_version');
     const until = entry.until_registry_version;
-    // A pin at or past its own bound would be replaced by the registry the moment it applied.
-    if (until !== undefined && entry.distribution && !(semver.valid(entry.distribution.version) && semver.lt(entry.distribution.version, until))) {
-        throw new Error(`Axom patch ${entry.id}: pinned ${entry.distribution.version} must sort below ${until}`);
+    // A catch-up pin may equal its bound: use it until the registry publishes that release.
+    // A pin above the bound would instead let the registry replace it with an older release.
+    if (until !== undefined && entry.distribution && !(semver.valid(entry.distribution.version) && semver.lte(entry.distribution.version, until))) {
+        throw new Error(`Axom patch ${entry.id}: pinned ${entry.distribution.version} must not sort above ${until}`);
+    }
+}
+/** Portable relative paths only: no platform-specific interpretation or normalization. */
+export function validatePatchPath(value) {
+    if (typeof value !== 'string' || !value || /[\\:\0]/.test(value) || value.split('/').some(part => !part || part === '.' || part === '..')) {
+        throw new Error('Axom patch path escapes its root or is not a portable relative path');
     }
 }
 export function validatePackagePatch(recipe) {
@@ -30,6 +38,16 @@ export function validatePackagePatch(recipe) {
     if (recipe.versions === undefined && recipe.until_version === undefined) {
         throw new Error(`Axom patch ${recipe.id}: needs versions or until_version`);
     }
+    for (const edit of recipe.edits)
+        validatePatchPath(edit.file);
+    if (recipe.assets !== undefined && !Array.isArray(recipe.assets))
+        throw new Error('Axom patch assets must be an array');
+    for (const asset of recipe.assets ?? []) {
+        validatePatchPath(asset.source);
+        validatePatchPath(asset.target);
+        if (!/^[a-f0-9]{64}$/.test(asset.sha256))
+            throw new Error('Axom patch asset sha256 must be a lowercase SHA-256 digest');
+    }
 }
 function inRange(version, when, until) {
     if (when)
@@ -61,3 +79,42 @@ export const packagePatches = runtime.package_patches.map((file) => {
     validatePackagePatch(recipe);
     return recipe;
 });
+/** The declared native wrappers, for the catalog↔patch consistency guard in `catalog.test.ts`. */
+export const nativeExtensions = runtime.native_extensions ?? [];
+/** The bundled overrides, for the same catalog↔patch consistency guard. */
+export const runtimeOverrides = runtime.overrides;
+/** Native wrappers are declared in the patch inventory, never selected by agent-specific launch branches. */
+export function nativeExtensionFor(agent, version) {
+    const extension = runtime.native_extensions?.find(entry => entry.agent === agent && entry.versions.includes(version));
+    if (!extension)
+        return undefined;
+    if (extension.entry.startsWith('/') || extension.entry.split('/').includes('..'))
+        throw new Error('Invalid native extension path');
+    return new URL(extension.entry, patchAssetRoot);
+}
+export function nativeAccountLimitsVersionFor(agent, version) {
+    return runtime.native_extensions?.find(entry => entry.agent === agent && entry.versions.includes(version))?.accountLimitsVersion ?? 2;
+}
+/** One entry per package; the only policy is skipping npm lifecycle scripts a package would run in the user's HOME. */
+export function validateInstallPolicies(policies) {
+    if (!Array.isArray(policies))
+        throw new Error('Axom install_policies must be an array');
+    const seen = new Set();
+    for (const policy of policies) {
+        if (typeof policy?.package !== 'string')
+            throw new Error('Axom install policy needs a package name');
+        assertSafePackageName(policy.package);
+        if (seen.has(policy.package))
+            throw new Error(`Axom install policy for ${policy.package} is duplicated`);
+        if (policy.ignore_scripts !== true)
+            throw new Error(`Axom install policy for ${policy.package} must set ignore_scripts: true`);
+        seen.add(policy.package);
+    }
+    return policies;
+}
+export const installPolicies = validateInstallPolicies(runtime.install_policies ?? []);
+export function installPolicyFor(name, policies = installPolicies) {
+    return policies.find((policy) => policy.package === name);
+}
+/** Optional strict release policies; activation is an explicit bundled manifest change. */
+export const managedRuntimePolicies = runtime.managed_runtimes ?? [];

package/dist/workstation/acp/permission.js

@@ -78,7 +78,6 @@
  * complete it, so `authenticate` remembers every id it handed out and retracts what is left when
  * the login settles.
  */
-import { randomUUID } from 'node:crypto';
 import { methods } from '@agentclientprotocol/sdk';
 import { validateWireEvent } from './validate.js';
 /** A value guaranteed not to equal any real `optionId` in `input.options` for a given call — used to purge a pending entry without accidentally supplying a matchable answer. Regenerated per call rather than a fixed literal, for the same anti-collision reasoning as `AcpSession`'s own abandonment sentinel (review finding, task-5 item 6). */
@@ -123,8 +122,9 @@ function toolCallPayload(toolCall) {
  * ACP `RequestPermissionRequest` (`types.gen.d.ts:108`) on Axom's wire: `{toolCall, options}` plus
  * `requestId`.
  *
- * `requestId` is a host-generated resolver token. The raw JSON-RPC ID stays local to its
- * connection; exact `sessionId` travels in the wire event's `acpSessionId` origin field.
+ * `requestId` is a host-derived resolver token — {@link permissionRequestId}, the same on the live
+ * path and in the ACP processor. The raw JSON-RPC ID stays local to its connection; exact `sessionId`
+ * travels in the wire event's `acpSessionId` origin field.
  *
  * **`toolCall` is nested, not flattened.** The flattened version lifted the tool's
  * `name`/`title`/`kind`/`arguments` to the top level, which put `name` (the tool's programmatic name,
@@ -135,7 +135,7 @@ function toolCallPayload(toolCall) {
  * `toolCall.title`, and the renderer computes it from the same field now
  * (`WorkTimelineInteractions.foldPermission`) instead of storing a second, drifting copy.
  */
-function buildPermissionRequestedEvent(input) {
+export function buildPermissionRequestedEvent(input) {
     return {
         eventName: 'permission_request',
         ...(input.sessionId !== undefined ? { acpSessionId: input.sessionId } : {}),
@@ -164,7 +164,7 @@ function buildPermissionRequestedEvent(input) {
  * `sink.answer` — the agent gave up on this specific request, so nothing should still expect an
  * answer for it. Session-level abandonment (the session closing, or the connection dying) is instead
  * `AcpSession`'s own job (`registerPendingApproval` resolving immediately when already closed, and
- * `runReadLoop` draining on an aborted connection) — see `acpSession.ts`.
+ * `runReadLoop` draining on an aborted connection) — see the old `acpSession.ts` (deleted in Task 29).
  *
  * The eventual answer is whatever string reaches `sink`'s registered resolver: normally one of
  * `input.options`' own `optionId`s (relayed from the user through `AcpSession.answer`), but both
@@ -320,7 +320,7 @@ function isFoldedCompanionKey(key, properties) {
  * each return `null` from `elicitationRequestFromPayload`, because `MODE_FORM` requires
  * `fields.isNotEmpty()`. Everything else it now decodes (see {@link handleFormElicitation}).
  */
-function elicitationFieldKeys(requestedSchema) {
+export function elicitationFieldKeys(requestedSchema) {
     const properties = requestedSchema?.properties;
     if (properties === null || typeof properties !== 'object' || Array.isArray(properties))
         return [];
@@ -336,7 +336,7 @@ function elicitationFieldKeys(requestedSchema) {
  * request is dropped server-side, which is why this check survived Task 9's removal of the
  * per-property profile predicate (see the ruling-R24 block below).
  */
-function isBlank(value) {
+export function isBlank(value) {
     return value.trim().length === 0;
 }
 /**
@@ -406,7 +406,7 @@ function isBlank(value) {
  * event always carries exactly what the agent asked; {@link handleFormElicitation} is what decides,
  * from that same schema, whether to wait for an answer or decline right after raising the card.
  */
-function buildElicitationRequestedEvent(request, requestId) {
+export function buildElicitationRequestedEvent(request, requestId) {
     return {
         eventName: 'elicitation_request',
         payload: {
@@ -521,6 +521,35 @@ async function handleFormElicitation(request, ctx, sink) {
 export function handleElicitationComplete(notification, deps) {
     deps.dismiss(notification.elicitationId);
 }
+/**
+ * The card id of one `session/request_permission`: `perm:<hostGeneration>:<JSON agent id>` (spec
+ * 2026-10-11 §5.4).
+ *
+ * ## Why derived, not random
+ *
+ * It used to be `randomUUID()` per invocation. A card id the server is already showing must still
+ * resolve after the daemon restarts underneath a live adapter, and a random id cannot: the re-presented
+ * request would get a new one, `settleApproval` ignores unknown ids, and the user's answer to the
+ * visible card would be lost (analysis A §4). Derived from the request itself, the same request gets
+ * the same id in every daemon generation, and the ACP processor — which may not draw randomness at
+ * all (`processor/guard.test.ts`) — computes it with this very function.
+ *
+ * ## Why it is still unique
+ *
+ * - `hostGeneration` identifies one adapter process: the keeper's `spawnId` on the processor path,
+ *   `AgentRuntimeDiagnostics.generation` (fresh per `connectAgent`) on today's live path — the same
+ *   value published as `callbackContext.hostGeneration`. A reconnect is a new process, so a new
+ *   generation: the agent's ids restart at 0 there without colliding with an earlier card.
+ * - Within one process the agent never reuses a pending JSON-RPC id. `JSON.stringify` keeps the
+ *   number `1` and the string `"1"` apart.
+ *
+ * Kept short enough for `AcpSession.registerPendingApproval`'s 256-byte rule for every id a real
+ * adapter sends; a pathological id longer than ~200 bytes is refused there, as an overlong
+ * `rpcRequestId` already was.
+ */
+export function permissionRequestId(hostGeneration, agentRequestId) {
+    return `perm:${hostGeneration}:${JSON.stringify(agentRequestId)}`;
+}
 /**
  * Register this module's three handlers onto `app`. Must run inside `connectAgent`'s `configure`
  * hook — see the file doc comment for why a post-connect `.onRequest`/`.onNotification` would compile
@@ -534,15 +563,18 @@ export function handleElicitationComplete(notification, deps) {
  * the call site instead. Its own `present` may still be omitted (see {@link PresentElicitationUrl}) —
  * that is `acpAgents.ts`'s session connection saying, on purpose, that a `url` elicitation raised
  * outside a login has nowhere to go, and it declines rather than accepting into nothing.
+ *
+ * `connection.generation` is the adapter process's generation — `connectAgent` hands it to its
+ * `configure` hook — and scopes the card ids {@link permissionRequestId} derives.
  */
-export function registerPermissionHandlers(app, sink, elicitationDeps) {
+export function registerPermissionHandlers(app, sink, elicitationDeps, connection) {
     app
         .onRequest(methods.client.session.requestPermission, async (ctx) => {
         if (typeof ctx.params.sessionId !== 'string' || !ctx.params.sessionId.trim()) {
             console.error(JSON.stringify({ component: 'acp', error: 'invalid_permission_origin', rpcRequestId: String(ctx.requestId) }));
             return { outcome: { outcome: 'cancelled' } };
         }
-        const decision = await handleRequestPermission({ requestId: randomUUID(), rpcRequestId: String(ctx.requestId), sessionId: ctx.params.sessionId, toolCall: ctx.params.toolCall, options: ctx.params.options, signal: ctx.signal }, sink);
+        const decision = await handleRequestPermission({ requestId: permissionRequestId(connection.generation, ctx.requestId), rpcRequestId: String(ctx.requestId), sessionId: ctx.params.sessionId, toolCall: ctx.params.toolCall, options: ctx.params.options, signal: ctx.signal }, sink);
         return {
             outcome: decision.outcome === 'answered' ? { outcome: 'selected', optionId: decision.optionId } : { outcome: 'cancelled' },
         };

package/dist/workstation/acp/processor/checkpoint.js

@@ -0,0 +1,78 @@
+/** Checkpoint schema answers whether state is readable; processorVersion identifies output semantics. Readable older processor versions remain restorable; replay differences across versions do not count as divergence. Version 9 moves adapter-specific compatibility folds out and removes retired optional state. */
+import { initialState, PROCESSOR_STATE_SCHEMA } from './state.js';
+/**
+ * Output history: 2 — turns, cards, seq and semantic-only request checks;
+ * 3 — session updates, binding, config, steering and validated events;
+ * 4 — spawn-bound commands and history dropped counts; prompt closes history;
+ * 5 — callback snapshots, runtime revisions and adapter compatibility folds;
+ * 6 — child status precedes process results; ended calls release data;
+ * 7 — install outcomes become step events;
+ * 8 — loaded-session levels fold live; output gaps become steps;
+ * 9 — adapter compatibility folds moved out and retired optional state removed.
+ */
+export const PROCESSOR_VERSION = 9;
+export const CHECKPOINT_SCHEMA = 1;
+export class CheckpointUnreadableError extends Error {
+}
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/** A detached copy of `state`, so later steps cannot reach into a checkpoint already handed out. */
+export function checkpointOf(state) {
+    return { schema: CHECKPOINT_SCHEMA, processorVersion: PROCESSOR_VERSION, offset: state.offset, state: clone(state) };
+}
+export function encodeCheckpoint(checkpoint) {
+    return JSON.stringify(checkpoint);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Parse and check a checkpoint blob (string or already-parsed JSON). */
+export function decodeCheckpoint(blob) {
+    let value = blob;
+    if (typeof blob === 'string') {
+        try {
+            value = JSON.parse(blob);
+        }
+        catch {
+            throw new CheckpointUnreadableError('checkpoint is not JSON');
+        }
+    }
+    if (!isRecord(value))
+        throw new CheckpointUnreadableError('checkpoint is not an object');
+    if (value.schema !== CHECKPOINT_SCHEMA)
+        throw new CheckpointUnreadableError(`unknown checkpoint schema ${JSON.stringify(value.schema)}`);
+    const { processorVersion, offset, state } = value;
+    if (typeof processorVersion !== 'number' || !Number.isInteger(processorVersion))
+        throw new CheckpointUnreadableError('checkpoint has no processorVersion');
+    if (typeof offset !== 'number' || !Number.isSafeInteger(offset) || offset < -1)
+        throw new CheckpointUnreadableError('checkpoint offset is invalid');
+    if (!isRecord(state) || (state.schema !== 4 && state.schema !== PROCESSOR_STATE_SCHEMA))
+        throw new CheckpointUnreadableError('checkpoint state schema is unknown');
+    if (state.offset !== offset)
+        throw new CheckpointUnreadableError('checkpoint offset disagrees with its state');
+    for (const key of ['process', 'initialize', 'outbound', 'inbound', 'diagnostics', 'permissions', 'elicitations',
+        'permissionOrigins', 'permissionParents', 'unresolvedPermissionOrigins', 'open', 'mapperScopes', 'message', 'steers',
+        'asyncTasks', 'runtime', 'callbacks']) {
+        if (!isRecord(state[key]))
+            throw new CheckpointUnreadableError(`checkpoint state has no ${key}`);
+    }
+    if (typeof state.seq !== 'number' || !Array.isArray(state.turns) || !Array.isArray(state.settledPermissions)) {
+        throw new CheckpointUnreadableError('checkpoint state has no session layer (seq/turns)');
+    }
+    if (!Array.isArray(state.steered) || !('configOptions' in state) || !('history' in state)
+        || !('activity' in state)) {
+        throw new CheckpointUnreadableError('checkpoint state has no open-session layer (Task 17b)');
+    }
+    return { schema: CHECKPOINT_SCHEMA, processorVersion, offset, state: clone({ ...(state.schema === 4 ? upgradeStateFromSchema4(state) : state), ...(!Object.hasOwn(state, 'draftSubagents') ? { draftSubagents: { children: {}, overflow: false } } : {}) }) };
+}
+/** Read only the current neutral keys; retired adapter state is deliberately not copied. */
+function upgradeStateFromSchema4(state) {
+    const keys = [...Object.keys(initialState()), 'closed', 'accountAuthBillingModes', 'accountLimits'];
+    const current = Object.fromEntries(keys.filter((key) => Object.hasOwn(state, key)).map((key) => [key, state[key]]));
+    const runtime = state.runtime;
+    return { ...current, schema: PROCESSOR_STATE_SCHEMA, runtime: {
+            revision: runtime.revision, available: runtime.available,
+            ...(Object.hasOwn(runtime, 'launch') ? { launch: runtime.launch } : {}),
+        } };
+}

package/dist/workstation/acp/processor/commands.js

@@ -0,0 +1,35 @@
+/** The line to write for `command`: `fill`ed from `resolve`, or `undefined` if its blocks are gone. */
+export function materializeLine(command, resolve) {
+    if (command.fill === undefined)
+        return command.line;
+    const blocks = resolve?.(command.fill.blocksRef);
+    if (blocks === undefined)
+        return undefined;
+    const message = JSON.parse(command.line);
+    // Assigning an existing key keeps its position: the line keeps the SDK's key order.
+    message.params.prompt = blocks;
+    return JSON.stringify(message);
+}
+export function executeDownCommands(sink, commands, resolve) {
+    const written = [];
+    const dropped = [];
+    const refused = [];
+    const unresolved = [];
+    for (const command of commands) {
+        if (sink.hasDown(command.cause)) {
+            dropped.push(command);
+            continue;
+        }
+        const line = materializeLine(command, resolve);
+        if (line === undefined) {
+            unresolved.push(command);
+            continue;
+        }
+        const { fill: _fill, ...rest } = command;
+        if (sink.writeDown({ ...rest, line }) === 'refused')
+            refused.push(command);
+        else
+            written.push(command);
+    }
+    return { written, dropped, refused, unresolved };
+}

package/dist/workstation/acp/processor/control.js

@@ -0,0 +1,282 @@
+/** Open-session binding, configuration, steering and launch notes. A response binds the native root; a failed load never silently creates another session here. The daemon supplies the finished MCP list with secrets replaced by references. */
+import { newSessionMetaFor } from '../activityReporting.js';
+import { flatChoicesOf, modesAlreadyRepresented, modelsAlreadyRepresented, normalizeConfigOptions, SYNTHESIZED_MODES_CONFIG_ID, SYNTHESIZED_MODEL_CONFIG_ID } from '../configOptions.js';
+import { ASYNC_TASK_STOP_METHOD, mapSteerOutcome, STEER_METHOD } from '../steering.js';
+import { emitEvent, isRecord } from './emit.js';
+import { settlementErrorCode } from './jsonrpc.js';
+import { sameCause } from './record.js';
+import { onLaunchNote } from './runtime.js';
+import { bindRootSession, closeErrorText, connected } from './session.js';
+import { getOwn, putOwn, STEERED_HISTORY_LIMIT, } from './state.js';
+import { endHistory } from './updates.js';
+const OPEN_METHODS = { new: 'session/new', load: 'session/load', resume: 'session/resume' };
+export const NOT_INITIALIZED = 'The ACP connection has not finished initialize';
+export const ALREADY_OPEN = 'An ACP session is already open on this connection';
+export const NOT_OPEN = 'No ACP session is open on this connection';
+function request(state, out, method, params, kind, ctx, extras = {}) {
+    const { id, cause } = out.request(method, params, extras);
+    const pending = { id, method, kind, cause, ...(ctx !== undefined ? { ctx } : {}) };
+    state.outbound[String(id)] = pending;
+    return pending;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+// ---- open ---------------------------------------------------------------------------------------
+export function onOpenNote(state, note, out) {
+    const { mode, cwd, sessionId, mcpServers, redact } = note;
+    if ((mode !== 'new' && mode !== 'load' && mode !== 'resume') || typeof cwd !== 'string' || cwd === ''
+        || (mode === 'new' ? sessionId !== undefined : typeof sessionId !== 'string' || sessionId === '')
+        || (mcpServers !== undefined && !Array.isArray(mcpServers)) || (redact !== undefined && !isStringArray(redact))) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    const refuse = (error) => out.unjournaled({ t: 'processor.open_result', ok: false, mode, error });
+    if (!connected(state))
+        return refuse(closeErrorText(state));
+    if (state.initialize.status !== 'ready')
+        return refuse(NOT_INITIALIZED);
+    if (state.open.status === 'pending' || state.open.status === 'open')
+        return refuse(ALREADY_OPEN);
+    const meta = mode === 'resume' ? undefined : newSessionMetaFor(state.initialize.facts.agentInfo?.name);
+    const servers = mcpServers ?? [];
+    const params = mode === 'new'
+        ? { cwd, mcpServers: servers, ...(meta ? { _meta: meta } : {}) }
+        : mode === 'load'
+            ? { sessionId, cwd, mcpServers: servers, ...(meta ? { _meta: meta } : {}) }
+            : { sessionId, cwd, mcpServers: servers };
+    const pending = request(state, out, OPEN_METHODS[mode], params, 'open', { mode, ...(sessionId !== undefined ? { sessionId } : {}) }, redact !== undefined && redact.length > 0 ? { redact } : {});
+    state.open = { status: 'pending', requestId: pending.id, mode };
+    if (mode === 'load')
+        state.history = { rootSessionId: sessionId, scopes: {}, messages: [], droppedCount: 0 };
+}
+/** The open request settled: on success the response binds the root session, now. */
+export function settleOpen(state, entry, settlement, out) {
+    const ctx = entry.ctx;
+    if (state.open.status !== 'pending' || state.open.requestId !== entry.id)
+        return;
+    const { mode } = ctx;
+    if (settlement.outcome !== 'result') {
+        const code = settlementErrorCode(settlement);
+        const error = settlement.outcome === 'error' ? settlement.error.message : closeErrorText(state);
+        state.open = { status: 'failed', mode, error, ...(code !== undefined ? { code } : {}) };
+        endHistory(state, out, false);
+        // A failed open closes the attached session, and its repair with it (`AcpSession.close`).
+        out.unjournaled({ t: 'processor.open_result', ok: false, mode, error, ...(code !== undefined ? { code } : {}) });
+        return;
+    }
+    const result = isRecord(settlement.result) ? settlement.result : {};
+    const nativeSessionId = mode === 'new' ? (typeof result.sessionId === 'string' ? result.sessionId : '') : ctx.sessionId;
+    if (nativeSessionId.length > 0) {
+        bindRootSession(state, nativeSessionId);
+    }
+    state.configOptions = normalizeConfigOptions(result.configOptions, result.modes, result.models);
+    state.open = { status: 'open', mode };
+    out.unjournaled({
+        t: 'processor.open_result', ok: true, mode,
+        nativeSessionId: nativeSessionId.length > 0 ? nativeSessionId : null,
+        configOptions: state.configOptions,
+    });
+}
+/** `historyEnd{}` — the daemon's decision that a load's history is over (analysis B A4). */
+export function onHistoryEndNote(state, out) {
+    if (!state.history) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    endHistory(state, out, true);
+}
+/** Usable for a session request: connected, and the open succeeded with a root. */
+function sessionReady(state) {
+    if (!connected(state))
+        return closeErrorText(state);
+    if (state.open.status !== 'open' || state.rootSessionId === null)
+        return NOT_OPEN;
+    return undefined;
+}
+/** `agent_set_config_option{id, configId, value}` — `setConfigOptionRequest`'s request half. */
+export function onSetConfigOptionNote(state, note, out) {
+    const { id, configId, value } = note;
+    if (typeof id !== 'string' || typeof configId !== 'string' || (typeof value !== 'string' && typeof value !== 'boolean')) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    const fail = (error) => out.unjournaled({ t: 'agent_config_option_set', id, ok: false, error });
+    const unusable = sessionReady(state);
+    if (unusable !== undefined)
+        return fail(unusable);
+    const sessionId = state.rootSessionId;
+    const ctx = { id, configId, value };
+    if (configId === SYNTHESIZED_MODES_CONFIG_ID) {
+        if (typeof value !== 'string')
+            return fail(`[acp] ${SYNTHESIZED_MODES_CONFIG_ID} takes a mode id (a string), got ${typeof value}`);
+        request(state, out, 'session/set_mode', { sessionId, modeId: value }, 'config', ctx);
+        return;
+    }
+    // 合成的模型控件走 unstable 的专用 RPC，与 set_mode 同一条保留 id 的路由规则。hermes 回合进行中
+    // 会拒绝（"Session is busy"），那正是 settle 的错误支要说的话。
+    if (configId === SYNTHESIZED_MODEL_CONFIG_ID) {
+        if (typeof value !== 'string')
+            return fail(`[acp] ${SYNTHESIZED_MODEL_CONFIG_ID} takes a model id (a string), got ${typeof value}`);
+        request(state, out, 'session/set_model', { sessionId, modelId: value }, 'config', ctx);
+        return;
+    }
+    request(state, out, 'session/set_config_option', typeof value === 'boolean' ? { sessionId, configId, type: 'boolean', value } : { sessionId, configId, value }, 'config', ctx);
+}
+/** The set settled — `setConfigOptionRequest`'s snapshot rules, then `agent_config_option_set`. */
+export function settleConfig(state, entry, settlement, out) {
+    const { id, configId, value } = entry.ctx;
+    if (settlement.outcome !== 'result') {
+        out.unjournaled({ t: 'agent_config_option_set', id, ok: false,
+            error: settlement.outcome === 'error' ? settlement.error.message : closeErrorText(state) });
+        return;
+    }
+    const current = state.configOptions ?? [];
+    let next;
+    if (entry.method === 'session/set_mode') {
+        next = current.map((option) => (option.id === configId && option.type === 'select' ? { ...option, currentValue: value } : option));
+    }
+    else if (entry.method === 'session/set_model') {
+        // hermes 的 SetSessionModelResponse 是空对象（切完不回快照、也不推更新），与 set_mode 同款：
+        // 本地把 currentValue 换成刚设的值；agent 若将来回了新状态，也只会被下一次 open 快照纠回真相。
+        next = current.map((option) => (option.id === configId && option.type === 'select' ? { ...option, currentValue: value } : option));
+    }
+    else {
+        const result = isRecord(settlement.result) ? settlement.result : {};
+        const reNormalized = normalizeConfigOptions(result.configOptions, null);
+        // 两个合成控件（modes、model）都不在 agent 自己的 configOptions 里，re-normalize 会把它们丢掉；
+        // 只要 agent 的新快照里还没有能替代它们的控件，就原样携带。
+        next = reNormalized.concat(current.filter((option) => (option.id === SYNTHESIZED_MODES_CONFIG_ID
+            && !modesAlreadyRepresented(reNormalized, flatChoicesOf(option) ?? []))
+            || (option.id === SYNTHESIZED_MODEL_CONFIG_ID && !modelsAlreadyRepresented(reNormalized))));
+    }
+    state.configOptions = next;
+    out.unjournaled({ t: 'agent_config_option_set', id, ok: true, configOptions: next });
+}
+// ---- steering -----------------------------------------------------------------------------------
+/** `agent_steer{id, blocksRef, priority?}` — `steerRequest`, blocks filled by the executor. */
+export function onSteerNote(state, note, out) {
+    const { id, blocksRef, priority } = note;
+    if (typeof id !== 'string' || id === '' || typeof blocksRef !== 'string' || blocksRef === ''
+        || (priority !== undefined && typeof priority !== 'string')) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    const unusable = sessionReady(state);
+    if (unusable !== undefined) {
+        out.unjournaled({ t: 'agent_steered', id, ok: false, error: unusable });
+        return;
+    }
+    if (getOwn(state.steers, id)) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    const pending = request(state, out, STEER_METHOD, {
+        sessionId: state.rootSessionId,
+        prompt: [],
+        _meta: { steering: { idleBehavior: 'promptRequired', ...(priority === undefined ? {} : { priority }) } },
+    }, 'steer', { id }, { fill: { blocksRef } });
+    putOwn(state.steers, id, { requestId: pending.id, cause: pending.cause, sent: false });
+}
+/** A `down` record: a queued steer's line reached the agent. */
+export function onSteerDown(state, record) {
+    const cause = record.annotation?.cause;
+    if (!cause)
+        return;
+    for (const steer of Object.values(state.steers)) {
+        if (!steer.sent && sameCause(cause, steer.cause))
+            steer.sent = true;
+    }
+}
+function rememberSteered(state, id) {
+    state.steered.push(id);
+    if (state.steered.length > STEERED_HISTORY_LIMIT)
+        state.steered.splice(0, state.steered.length - STEERED_HISTORY_LIMIT);
+}
+/** The steer settled: `agent_steered`, with `mapSteerOutcome`'s narrowing (a throw is a failed reply). */
+export function settleSteer(state, entry, settlement, out) {
+    const { id } = entry.ctx;
+    delete state.steers[id];
+    if (settlement.outcome !== 'result') {
+        out.unjournaled({ t: 'agent_steered', id, ok: false,
+            error: settlement.outcome === 'error' ? settlement.error.message : closeErrorText(state) });
+        return;
+    }
+    let outcome;
+    try {
+        outcome = mapSteerOutcome(settlement.result);
+    }
+    catch (error) {
+        out.unjournaled({ t: 'agent_steered', id, ok: false, error: error instanceof Error ? error.message : String(error) });
+        return;
+    }
+    if (outcome === 'injected')
+        rememberSteered(state, id);
+    out.unjournaled({ t: 'agent_steered', id, ok: true, outcome });
+}
+/** `agent_prompt_failed` for a steer whose blocks were gone: it never reached the agent. */
+export function failUnsentSteer(state, entry, error, out) {
+    const { id } = entry.ctx;
+    const steer = getOwn(state.steers, id);
+    if (!steer || steer.sent)
+        return false;
+    delete state.outbound[String(entry.id)];
+    delete state.steers[id];
+    out.unjournaled({ t: 'agent_steered', id, ok: false, error });
+    return true;
+}
+/** `agent_opened.steeredIds` (spec §5.5.4): see the file header. */
+export function steeredIds(state) {
+    const inFlight = Object.entries(state.steers).filter(([, steer]) => steer.sent).map(([id]) => id);
+    return [...state.steered, ...inFlight];
+}
+// ---- background tasks, launch -------------------------------------------------------
+/** `agent_async_task_stop{asyncTaskId}` — `asyncTaskStopRequest`; its answer is diagnostics only. */
+export function onAsyncTaskStopNote(state, note, out) {
+    const { asyncTaskId } = note;
+    if (typeof asyncTaskId !== 'string' || !asyncTaskId.trim() || sessionReady(state) !== undefined) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    request(state, out, ASYNC_TASK_STOP_METHOD, { sessionId: state.rootSessionId, asyncTaskId }, 'rpc', undefined);
+}
+/** `agent_launch{launch}` (see `runtime.ts`). */
+export function onLaunch(state, note) {
+    if (!onLaunchNote(state, note.launch))
+        state.diagnostics.droppedNotes += 1;
+}
+/**
+ * `agent_install_outcome{ok, agentName, version, error?}` (Task 20): the adapter install an open had to run first finished within
+ * the open's budget (spec §6.2). The daemon writes it right after `agent_launch`; it becomes one past-tense `step` on the session's
+ * timeline, numbered like any other event — the words the manager used to journal itself (interface-contracts, 15a/15c).
+ */
+export function onInstallOutcomeNote(state, note, out) {
+    const { ok, agentName, version, error } = note;
+    if (typeof ok !== 'boolean' || typeof agentName !== 'string' || typeof version !== 'string' || (!ok && typeof error !== 'string')) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    emitEvent(state, out, {
+        eventName: 'step',
+        payload: ok
+            ? { title: 'Agent adapter', message: `Installed ${agentName} adapter ${version}`, tone: 'neutral' }
+            : { title: 'Agent adapter', message: `Could not install ${agentName} adapter ${version}`, detail: error, tone: 'error' },
+    });
+}
+/**
+ * `agent_output_gap{detail}` (Task 21): this session numbers on in a transport other than the one an earlier life of the ref ran in,
+ * and that life's unacknowledged output could not be read (keeper-acp unreachable while the session runs in the daemon) — its frames
+ * may never reach the server. The daemon seeded the seq above everything that life may have numbered (spec §5.5), so nothing is
+ * reused; this past-tense `step` says that output may be missing.
+ */
+export function onOutputGapNote(state, note, out) {
+    const { detail } = note;
+    if (typeof detail !== 'string' || detail.length === 0) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    emitEvent(state, out, {
+        eventName: 'step',
+        payload: { title: 'Agent session', message: 'Earlier output of this session could not be recovered', detail, tone: 'error' },
+    });
+}

package/dist/workstation/acp/processor/emit.js

@@ -0,0 +1,26 @@
+import { validateWireEvent } from '../validate.js';
+export function nextSeq(state) {
+    state.seq += 1;
+    return state.seq;
+}
+/**
+ * A journaled `agent_event` (the wire frame minus `sessionRef`, which the projection adds). Returns
+ * whether it was emitted.
+ */
+export function emitEvent(state, out, event) {
+    if (validateWireEvent(event)) {
+        state.diagnostics.invalidEvents += 1;
+        return false;
+    }
+    out.frame({
+        t: 'agent_event',
+        seq: nextSeq(state),
+        eventName: event.eventName,
+        payload: event.payload,
+        ...(event.acpSessionId ? { acpSessionId: event.acpSessionId } : {}),
+    });
+    return true;
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}