@platless/axom-cli 0.1.0 → 0.5.9

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

@@ -0,0 +1,459 @@
+import { accountLimitsSchema, ACCOUNT_LIMITS_READ, ACCOUNT_LIMITS_UPDATED } from '../../protocol/accountLimits.js';
+import { initializeRequestParams, parseInitializeResult } from '../initializeResponse.js';
+import { STEER_METHOD } from '../steering.js';
+import { checkpointOf } from './checkpoint.js';
+import { failUnsentSteer, onAsyncTaskStopNote, onDelegationRefreshPendingNote, onDelegationRenewedNote, onHistoryEndNote, onInstallOutcomeNote, onOutputGapNote, onLaunch, onOpenNote, onSetConfigOptionNote, onSteerDown, onSteerNote, settleConfig, settleOpen, settleSteer, } from './control.js';
+import { CANCEL_REQUEST_METHOD, classifyLine, inboundKey, invalidParams, invalidRequest, isJsonRpcId, methodNotFound, outboundKey, parseError, settlementErrorCode, settlementOf, } from './jsonrpc.js';
+import { RecordOutput } from './output.js';
+import { INBOUND_REQUEST_SCHEMAS } from './sdkSchemas.js';
+import { BATCH_CLOSE_REASON, connected, dropCards, finishAllTurns, forgetCard, onAnswerNote, onDown, onElicitationAnswerNote, onElicitationRequest, onInboundCancelled, onInterruptNote, onPermissionRequest, onPromptFailedNote, onPromptNote, onUndeliverableNote, resetForSpawn, settlePrompt, } from './session.js';
+import { onClaudeSdkMessage, onInitialized, onProcessExit, onProfileNotification } from './runtime.js';
+import { closeRepair, onRepairNote, onSideNote } from './sideChannel.js';
+import { REPAIR_NOTE, SIDE_NOTE } from '../../qoderAdapter/backgroundTerminalFold.js';
+import { endHistory, onSessionUpdate } from './updates.js';
+import { initialState, SETTLED_HISTORY_LIMIT, } from './state.js';
+/** Serialized size above which a note is dropped (`droppedNotes`). */
+export const NOTE_MAX_BYTES = 64 * 1024;
+/** Methods `rpc.request` refuses: their params carry prompt blocks or secrets (§5.4, §13). */
+export const SEMANTIC_ONLY_METHODS = new Set([
+    'session/new', 'session/load', 'session/resume', 'session/prompt', 'authenticate', STEER_METHOD,
+]);
+export class OutOfOrderRecordError extends Error {
+}
+/** Inbound requests the session layer answers (cards); everything else is `-32601`. */
+const HELD_INBOUND_METHODS = new Set(Object.keys(INBOUND_REQUEST_SCHEMAS));
+/** A processor that threw mid-record: its state may be half-updated, so it refuses to go on. */
+export class ProcessorPoisonedError extends Error {
+}
+/**
+ * Fold one record into `state` and return what it produced. Throws {@link OutOfOrderRecordError}
+ * (state untouched) if `record` is not the next record, and `CommandBudgetExceededError` if it would
+ * send a 17th request or produce a 257th command — a bug, after which `state` must be discarded (see
+ * the file header).
+ */
+export function step(state, record) {
+    if (state.offset >= 0 && record.o !== state.offset + 1) {
+        throw new OutOfOrderRecordError(`expected record ${state.offset + 1}, got ${record.o}`);
+    }
+    const out = new RecordOutput(record.o, () => (state.process.status === 'running' ? state.process.spawn.spawnId : undefined));
+    switch (record.kind) {
+        case 'proc':
+            onProc(state, record.proc, out);
+            break;
+        case 'up':
+            onUp(state, record.line, record.o, record.t, out);
+            break;
+        case 'note':
+            onNote(state, record.note, out);
+            break;
+        case 'down':
+            onDown(state, record);
+            onSteerDown(state, record);
+            break;
+        case 'err':
+            break;
+    }
+    state.offset = record.o;
+    state.t = record.t;
+    return { frames: out.frames, commands: out.commands };
+}
+function sendRequest(state, out, method, params, kind, ctx) {
+    const { id, cause } = out.request(method, params);
+    const pending = { id, method, kind, cause, ...(ctx !== undefined ? { ctx } : {}) };
+    state.outbound[String(id)] = pending;
+    return id;
+}
+/**
+ * Close the JSON-RPC connection: unanswered cards and inbound requests are void (nothing can carry an
+ * answer any more), everything pending settles as `closed` — ending its turn — and any turn left ends
+ * `failed`.
+ */
+function closeConnection(state, reason, out) {
+    const pending = Object.values(state.outbound);
+    state.outbound = {};
+    state.inbound = {};
+    dropCards(state, out);
+    closeRepair(state);
+    state.closed = reason;
+    for (const entry of pending)
+        settle(state, entry, { outcome: 'closed', reason }, out);
+    finishAllTurns(state, out);
+    endHistory(state, out, false);
+}
+function onProc(state, event, out) {
+    if (event.type === 'spawn') {
+        if (state.process.status === 'running' && state.closed === undefined) {
+            closeConnection(state, 'replaced by a new adapter process', out);
+        }
+        state.process = { status: 'running', spawn: event };
+        delete state.closed;
+        state.outbound = {};
+        state.inbound = {};
+        resetForSpawn(state);
+        const id = sendRequest(state, out, 'initialize', initializeRequestParams(), 'initialize');
+        state.initialize = { status: 'pending', requestId: id };
+        return;
+    }
+    const current = state.process;
+    // A second `exit` (e.g. `keeper_lost` after a real one) keeps the spawn it belongs to.
+    const spawnId = current.status === 'running' ? current.spawn.spawnId : current.status === 'exited' ? current.spawnId : undefined;
+    if (state.closed === undefined && current.status === 'running')
+        closeConnection(state, 'process exited', out);
+    state.process = { status: 'exited', ...(spawnId !== undefined ? { spawnId } : {}), exit: event };
+    if (current.status === 'running')
+        onProcessExit(state, out);
+}
+function onUp(state, line, o, t, out) {
+    if (!connected(state)) {
+        state.diagnostics.ignoredLines += 1;
+        return;
+    }
+    const message = classifyLine(line);
+    switch (message.type) {
+        case 'empty':
+            return;
+        case 'parse_error':
+            state.diagnostics.protocolErrors += 1;
+            out.error(null, parseError());
+            return;
+        case 'invalid':
+            state.diagnostics.protocolErrors += 1;
+            out.error(null, invalidRequest(message.raw));
+            return;
+        case 'batch':
+            // `ClientApp` connects with `allowBatches: false`: a batch closes the connection.
+            state.diagnostics.protocolErrors += 1;
+            closeConnection(state, BATCH_CLOSE_REASON, out);
+            return;
+        case 'unaddressed':
+            state.diagnostics.protocolErrors += 1;
+            return;
+        case 'notification':
+            if (message.method === CANCEL_REQUEST_METHOD)
+                onInboundCancel(state, message.params, out);
+            else if (message.method === '_auth/status_update' && state.accountLimits) {
+                const auth = message.params?.authStatus;
+                const mode = auth?.kind ? state.accountAuthBillingModes?.[auth.kind] : undefined;
+                if (auth && mode) {
+                    state.accountLimits = { ...state.accountLimits, updateMode: 'snapshot', billingMode: mode, availability: mode === 'non_subscription' ? 'not_applicable' : 'unknown', plan: auth.account?.plan ? { id: auth.account.plan, label: auth.account.plan } : null, limits: [], balances: [], _meta: { _axom: { identityOnly: true, authKind: auth.kind } }, observedAt: new Date(t).toISOString() };
+                    out.unjournaled({ t: 'agent_account_update', snapshot: state.accountLimits });
+                }
+            }
+            else if (message.method === ACCOUNT_LIMITS_UPDATED) {
+                const result = accountLimitsSchema.safeParse(message.params);
+                if (result.success) {
+                    const snapshot = { ...result.data, updateMode: result.data.updateMode ?? 'delta' };
+                    state.accountLimits = snapshot;
+                    out.unjournaled({ t: 'agent_account_update', snapshot });
+                }
+            }
+            else if (message.method === 'session/update')
+                onSessionUpdate(state, message.params, out, t);
+            else if (message.method === '_claude/sdkMessage')
+                onClaudeSdkMessage(state, out, message.params, t);
+            else if (message.method === '_axom/qoder/profile')
+                onProfileNotification(state, out, message.params);
+            return;
+        case 'request':
+            onInboundRequest(state, message.id, message.method, message.params, o, out);
+            return;
+        case 'response': {
+            const key = outboundKey(message.id);
+            const entry = key === undefined ? undefined : state.outbound[key];
+            if (!entry) {
+                state.diagnostics.orphanResponses += 1;
+                return;
+            }
+            delete state.outbound[key];
+            settle(state, entry, settlementOf(message.raw), out);
+            return;
+        }
+    }
+}
+function onInboundCancel(state, params, out) {
+    if (typeof params !== 'object' || params === null)
+        return;
+    const requestId = params.requestId;
+    if (!isJsonRpcId(requestId))
+        return;
+    const key = inboundKey(requestId);
+    const entry = state.inbound[key];
+    if (!entry || entry.cancelRequested)
+        return;
+    entry.cancelRequested = true;
+    onInboundCancelled(state, key, out);
+}
+function onInboundRequest(state, id, method, params, o, out) {
+    if (!HELD_INBOUND_METHODS.has(method)) {
+        out.error(id, methodNotFound(method));
+        return;
+    }
+    const parsed = INBOUND_REQUEST_SCHEMAS[method].safeParse(params);
+    if (!parsed.success) {
+        out.error(id, invalidParams(parsed.error.format()));
+        return;
+    }
+    // The handler sees the SDK-stripped params, exactly as `ClientApp` hands them over.
+    const data = parsed.data;
+    const key = inboundKey(id);
+    // Same id twice replaces the earlier entry, as the SDK's `incomingRequests.set` does.
+    state.inbound[key] = { id, method, o };
+    const card = method === 'session/request_permission'
+        ? onPermissionRequest(state, id, data, out)
+        : onElicitationRequest(state, id, data, out);
+    if (card === undefined)
+        delete state.inbound[key];
+    else
+        state.inbound[key] = { id, method, o, card };
+}
+function settle(state, entry, settlement, out) {
+    switch (entry.kind) {
+        case 'initialize':
+            settleInitialize(state, entry, settlement, out);
+            return;
+        case 'prompt':
+            settlePrompt(state, entry, settlement, out);
+            return;
+        case 'open':
+            settleOpen(state, entry, settlement, out);
+            return;
+        case 'config':
+            settleConfig(state, entry, settlement, out);
+            return;
+        case 'steer':
+            settleSteer(state, entry, settlement, out);
+            return;
+        case 'account': {
+            const parsed = settlement.outcome === 'result' ? accountLimitsSchema.safeParse(settlement.result) : null;
+            out.unjournaled({ t: 'agent_account_read_result', id: entry.ctx, ok: parsed?.success === true, ...(parsed?.success ? { snapshot: parsed.data } : { error: 'Failed to fetch usage' }) });
+            return;
+        }
+        case 'rpc': {
+            const code = settlementErrorCode(settlement);
+            const settled = state.diagnostics.settled;
+            settled.push({ id: entry.id, method: entry.method, outcome: settlement.outcome, ...(code !== undefined ? { code } : {}) });
+            if (settled.length > SETTLED_HISTORY_LIMIT)
+                settled.splice(0, settled.length - SETTLED_HISTORY_LIMIT);
+            return;
+        }
+    }
+}
+function settleInitialize(state, entry, settlement, out) {
+    if (state.initialize.status !== 'pending' || state.initialize.requestId !== entry.id)
+        return;
+    if (settlement.outcome === 'closed') {
+        state.initialize = { status: 'failed', reason: 'closed', detail: settlement.reason };
+        return;
+    }
+    if (settlement.outcome === 'error') {
+        const code = settlementErrorCode(settlement);
+        state.initialize = { status: 'failed', reason: 'rpc_error', detail: settlement.error.message, ...(code !== undefined ? { code } : {}) };
+        return;
+    }
+    let reading;
+    try {
+        reading = parseInitializeResult(settlement.result);
+    }
+    catch (error) {
+        // `connectAgent` would throw here too; the processor records it instead of dying on a bad line.
+        state.initialize = { status: 'failed', reason: 'malformed', detail: error instanceof Error ? error.message : String(error) };
+        return;
+    }
+    if (!reading.protocolSupported) {
+        state.initialize = { status: 'failed', reason: 'unsupported_protocol', protocolVersion: reading.protocolVersion };
+        return;
+    }
+    const { protocolSupported: _supported, ...facts } = reading;
+    state.initialize = { status: 'ready', facts: JSON.parse(JSON.stringify(facts)) };
+    onInitialized(state, settlement.result);
+    const capability = settlement.result.agentCapabilities?._meta?.['axom/accountRateLimits'];
+    if (capability && typeof capability === 'object' && capability.read === true) {
+        const quotaCapability = capability;
+        state.accountAuthBillingModes = quotaCapability.authBillingModes;
+        state.accountLimits = { schemaVersion: 1, provider: quotaCapability.provider ?? 'external', billingMode: 'unknown', availability: 'unknown', observedAt: new Date(state.t).toISOString(), plan: null, limits: [], balances: [], _meta: { _axom: { identityOnly: true } } };
+        // Binding can precede initialize. Publish capability identity without reading any quota.
+        out.unjournaled({ t: 'agent_account_update', snapshot: state.accountLimits });
+    }
+}
+/** UTF-8 length of a string, without `Buffer` (the processor keeps to plain JS). */
+function utf8Length(text) {
+    let bytes = 0;
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        if (code < 0x80)
+            bytes += 1;
+        else if (code < 0x800)
+            bytes += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && index + 1 < text.length) {
+            bytes += 4;
+            index += 1;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
+function onNote(state, note, out) {
+    if (utf8Length(JSON.stringify(note)) > NOTE_MAX_BYTES) {
+        state.diagnostics.droppedNotes += 1;
+        return;
+    }
+    switch (note.type) {
+        case 'agent_prompt':
+            onPromptNote(state, note, out);
+            return;
+        case 'agent_prompt_failed': {
+            const entry = typeof note.requestId === 'number' ? state.outbound[String(note.requestId)] : undefined;
+            if (entry?.kind === 'steer') {
+                if (typeof note.error !== 'string' || !failUnsentSteer(state, entry, note.error, out))
+                    state.diagnostics.droppedNotes += 1;
+                return;
+            }
+            onPromptFailedNote(state, note, out);
+            return;
+        }
+        case 'agent_interrupt':
+            onInterruptNote(state, out);
+            return;
+        case 'agent_answer':
+            onAnswerNote(state, note, out);
+            return;
+        case 'agent_elicitation_answer':
+            onElicitationAnswerNote(state, note, out);
+            return;
+        case 'agent_answer_undeliverable':
+            onUndeliverableNote(state, note, out);
+            return;
+        case 'agent_session_open':
+            onOpenNote(state, note, out);
+            return;
+        case 'historyEnd':
+            onHistoryEndNote(state, out);
+            return;
+        case 'agent_set_config_option':
+            onSetConfigOptionNote(state, note, out);
+            return;
+        case 'agent_steer':
+            onSteerNote(state, note, out);
+            return;
+        case 'agent_async_task_stop':
+            onAsyncTaskStopNote(state, note, out);
+            return;
+        case 'agent_delegation_renewed':
+            onDelegationRenewedNote(state, note);
+            return;
+        case 'agent_delegation_refresh_pending':
+            onDelegationRefreshPendingNote(state);
+            return;
+        case 'agent_launch':
+            onLaunch(state, note);
+            return;
+        case 'agent_install_outcome':
+            onInstallOutcomeNote(state, note, out);
+            return;
+        case 'agent_output_gap':
+            onOutputGapNote(state, note, out);
+            return;
+        case REPAIR_NOTE:
+            onRepairNote(state, note);
+            return;
+        case SIDE_NOTE:
+            onSideNote(state, note, out);
+            return;
+        case 'agent_account_read': {
+            if (!connected(state)) {
+                out.unjournaled({ t: 'agent_account_read_result', id: note.id, ok: false, error: 'Agent is offline' });
+                return;
+            }
+            if (state.initialize.status !== 'ready' || !state.initialize.facts.supportsAccountLimits ||
+                state.accountLimits?.billingMode === 'non_subscription' ||
+                (state.accountAuthBillingModes && state.accountLimits?.billingMode !== 'subscription')) {
+                out.unjournaled({ t: 'agent_account_read_result', id: note.id, ok: false, error: 'Account usage is unavailable' });
+                return;
+            }
+            sendRequest(state, out, ACCOUNT_LIMITS_READ, { sessionId: state.rootSessionId }, 'account', note.id);
+            return;
+        }
+        case 'rpc.request': {
+            const { method, params, ctx } = note;
+            if (typeof method !== 'string' || method === '' || SEMANTIC_ONLY_METHODS.has(method) || !connected(state)) {
+                state.diagnostics.droppedNotes += 1;
+                return;
+            }
+            sendRequest(state, out, method, params, 'rpc', ctx);
+            return;
+        }
+        case 'rpc.cancel': {
+            const key = outboundKey(note.requestId);
+            const entry = key === undefined ? undefined : state.outbound[key];
+            if (!entry || entry.cancelRequested || !connected(state)) {
+                state.diagnostics.droppedNotes += 1;
+                return;
+            }
+            out.notify(CANCEL_REQUEST_METHOD, { requestId: entry.id });
+            entry.cancelRequested = true;
+            return;
+        }
+        case 'rpc.respond': {
+            const requestId = note.requestId;
+            const entry = isJsonRpcId(requestId) ? state.inbound[inboundKey(requestId)] : undefined;
+            const hasResult = Object.hasOwn(note, 'result');
+            const error = note.error;
+            const validError = typeof error === 'object' && error !== null
+                && Number.isInteger(error.code) && typeof error.message === 'string';
+            if (!entry || !connected(state) || hasResult === (error !== undefined) || (error !== undefined && !validError)) {
+                state.diagnostics.droppedNotes += 1;
+                return;
+            }
+            const key = inboundKey(entry.id);
+            delete state.inbound[key];
+            forgetCard(state, key, entry.card, out);
+            if (hasResult)
+                out.result(entry.id, note.result);
+            else
+                out.error(entry.id, error);
+            return;
+        }
+        default:
+            state.diagnostics.unknownNotes += 1;
+    }
+}
+export function createProcessor(init = {}) {
+    const state = init.state ?? initialState();
+    let poisoned;
+    const refuse = () => {
+        if (poisoned !== undefined)
+            throw new ProcessorPoisonedError(`processor state is unusable after a failed step: ${poisoned}`);
+    };
+    return {
+        step(record) {
+            refuse();
+            try {
+                return step(state, record);
+            }
+            catch (error) {
+                if (!(error instanceof OutOfOrderRecordError))
+                    poisoned = error instanceof Error ? error.message : String(error);
+                throw error;
+            }
+        },
+        snapshot() {
+            refuse();
+            return checkpointOf(state);
+        },
+        get state() {
+            return state;
+        },
+        get poisoned() {
+            return poisoned;
+        },
+    };
+}
+/**
+ * Continue from a checkpoint (already decoded by `decodeCheckpoint`). The caller compares
+ * `checkpoint.processorVersion` with `PROCESSOR_VERSION` to decide whether replay output may be
+ * compared with the outbox (spec §5.5.6).
+ */
+export function restoreProcessor(checkpoint) {
+    return createProcessor({ state: JSON.parse(JSON.stringify(checkpoint.state)) });
+}

package/dist/workstation/acp/processor/test/fixtureLog.js

@@ -0,0 +1,65 @@
+/**
+ * A representative raw log that touches every piece of processor state Tasks 16–17b keep: initialize
+ * facts and the Qoder profile, the open session bound from its response (new, then — after a respawn —
+ * load with history and `historyEnd`), delegation and launch notes, config and steering round trips,
+ * every kind of `session/update` route (root, draft, child), message synthesis including an
+ * out-of-turn trailing chunk, async tasks, activity, both card kinds and the origin graph, turns
+ * (completed, interrupted, cut by an exit), the 17a low-level notes, and the diagnostics.
+ */
+import { createProcessor } from '../step.js';
+import { append, chunk, elicitationRequest, exitEntry, initializeResult, lastPromptId, lastRequestId, newSession, note, permissionRequest, prompt, respond, run, spawnEntry, subagentSpawned, up, update, } from './harness.js';
+export const QODER_PROFILE = {
+    cliVersion: '1.1.61', sdkVersion: '0.1.0', executable: '/usr/local/bin/qodercli', persistent: true, agentMessaging: false,
+    observerHealthy: true, completedContinuationEnabled: false, sendMessageExposed: false, mode: 'sdk-adapter', transport: 'process',
+    capabilities: ['background_tasks_v1'],
+};
+export const LAUNCH = { source: 'registry', executable: '/usr/local/bin/agent', platform: 'darwin', architecture: 'arm64', transport: 'stdio' };
+export function representativeLog() {
+    const session = newSession();
+    const processor = createProcessor();
+    let next = 0;
+    const step = (...entries) => {
+        append(session, ...entries);
+        next = run(processor, session, next);
+    };
+    step(spawnEntry('spawn-a'), note('agent_launch', { launch: LAUNCH }));
+    step(respond(lastRequestId(session, 'initialize'), initializeResult({
+        agentCapabilities: { loadSession: true, sessionCapabilities: { list: {} } },
+        authMethods: [{ id: 'login', name: 'Login', type: 'terminal', args: ['login'] }, { type: 'terminal' }],
+        agentInfo: { name: '@agentclientprotocol/claude-agent-acp', version: '1.0.0' },
+        _meta: { steering: { supported: true, timings: ['next'] }, qoderProfile: QODER_PROFILE },
+    })));
+    step(
+    // Before the open response: a profile candidate (kept), an update (no root yet: dropped).
+    up({ jsonrpc: '2.0', method: '_axom/qoder/profile', params: { sessionId: 'S1', revision: 1,
+            profile: { ...QODER_PROFILE, rootSessionId: 'S1', runtimeGeneration: 'g1', rootConfirmed: true, initialized: true } } }), note('agent_session_open', {
+        mode: 'new', cwd: '/work', redact: ['secret:delegation'],
+        mcpServers: [{ type: 'http', name: 'axom-delegation', url: 'https://x.test/mcp/delegation', headers: [{ name: 'Authorization', value: 'secret:delegation' }] }],
+        delegation: { expiresAtEpochMs: 1_900_000_000_000, leaseId: 'lease-hash', bindingId: 'b-1', instanceId: 'i-1' },
+    }), update('S1', { sessionUpdate: 'available_commands_update', availableCommands: [] }));
+    step(respond(lastRequestId(session, 'session/new'), {
+        sessionId: 'S1',
+        configOptions: [{ id: 'model', name: 'Model', type: 'select', currentValue: 'a', options: [{ value: 'a', name: 'A' }, { value: 'b', name: 'B' }] }],
+        modes: { currentModeId: 'ask', availableModes: [{ id: 'ask', name: 'Ask' }, { id: 'code', name: 'Code' }] },
+    }));
+    step(update('S1', { sessionUpdate: 'available_commands_update', availableCommands: [{ name: 'init', description: 'Init' }] }), note('rpc.request', { method: '_test/probe', params: { x: 1 }, ctx: { purpose: 'probe' } }), permissionRequest(5), subagentSpawned('S1', 'C1'), subagentSpawned('ghost', 'C2'), permissionRequest(6, 'C1'), elicitationRequest(9), prompt(session, 'one', { platformTurnId: 'turn-1' }), chunk('S1', 'Hello ', 'm1'), update('S1', { sessionUpdate: 'tool_call', toolCallId: 't1', title: 'Run', kind: 'execute', status: 'pending', rawInput: { command: 'sleep 1' } }), update('S1', { sessionUpdate: 'tool_call_update', toolCallId: 't1', status: 'completed' }), chunk('C1', 'child says hi', 'cm1'), update('S1', { sessionUpdate: 'async_task_spawned', asyncTaskId: 'task-1', name: 'shell', taskType: 'shell', description: 'd', showInTranscript: false, canStop: true }), update('S1', { sessionUpdate: 'async_task_spawned', asyncTaskId: 'task-2', name: 'shell', taskType: 'shell', description: 'd', showInTranscript: false, canStop: true }), chunk('S1', 'world', 'm2'), up({ jsonrpc: '2.0', method: '_claude/sdkMessage', params: { message: { type: 'system', subtype: 'session_state_changed', state: 'running' } } }), update('S1', { sessionUpdate: 'session_info_update', title: 'T', _meta: { codex: { threadStatus: { type: 'active' } }, piAcp: { queueDepth: 2, running: true } } }), { kind: 'err', line: 'adapter: warming up' }, up({ jsonrpc: '2.0', id: 12345, result: {} }), up({ jsonrpc: '2.0', method: '$/cancel_request', params: { requestId: 5 } }), note('mystery.future.note'));
+    const probe = Object.values(processor.state.outbound).find((p) => p.method === '_test/probe').id;
+    step(respond(probe, { ok: true }), note('agent_answer', { requestId: 'perm:spawn-a:6', outcome: 'allow' }), note('agent_elicitation_answer', { requestId: '9', action: 'accept', content: { branch: 'main' } }), note('agent_set_config_option', { id: 'cfg-1', configId: 'model', value: 'b' }), note('agent_set_config_option', { id: 'cfg-2', configId: 'acp:modes', value: 'code' }));
+    step(respond(lastRequestId(session, 'session/set_config_option'), {
+        configOptions: [{ id: 'model', name: 'Model', type: 'select', currentValue: 'b', options: [{ value: 'a', name: 'A' }, { value: 'b', name: 'B' }] }],
+    }), respond(lastRequestId(session, 'session/set_mode'), null));
+    session.blocks.set('steer-1', [{ type: 'text', text: 'also this' }]);
+    step(note('agent_steer', { id: 'steer-1', blocksRef: 'steer-1', priority: 'next' }));
+    step(respond(lastRequestId(session, '_session/steering'), { outcome: 'injected' }), respond(lastPromptId(session), { stopReason: 'end_turn' }), 
+    // Trailing, after the response: out of turn, closed before the next turn starts.
+    chunk('S1', 'late words'), update('S1', { sessionUpdate: 'async_task_state_update', asyncTaskId: 'task-1', state: 'stopped' }), update('S1', { sessionUpdate: 'async_task_state_update', asyncTaskId: 'task-1', state: 'completed' }), note('agent_delegation_renewed', { expiresAtEpochMs: 1_900_000_100_000, renewalRevision: 1 }), prompt(session, 'two'), chunk('S1', 'thinking'), update('S1', { sessionUpdate: 'tool_call', toolCallId: 't2', title: 'Serve', kind: 'execute', rawInput: { command: 'serve', run_in_background: true } }), permissionRequest(10), note('agent_interrupt'));
+    step(respond(lastPromptId(session), { stopReason: 'cancelled' }), prompt(session, 'three', { platformTurnId: 'turn-3' }), note('rpc.respond', { requestId: 5, result: { outcome: { outcome: 'cancelled' } } }));
+    step(exitEntry(0), spawnEntry('spawn-b'));
+    step(respond(lastRequestId(session, 'initialize'), initializeResult({ agentInfo: { name: 'other-agent', version: '2' } })));
+    step(note('agent_launch', { launch: LAUNCH }), note('agent_session_open', { mode: 'load', cwd: '/work', sessionId: 'S1' }));
+    step(update('S1', { sessionUpdate: 'user_message_chunk', content: { type: 'text', text: 'old question' } }), chunk('S1', 'old answer', 'h1'), subagentSpawned('S1', 'C9'), chunk('C9', 'old child'));
+    step(respond(lastRequestId(session, 'session/load'), { configOptions: [] }));
+    step(chunk('S1', 'qoder replays one more old chunk after its response'), note('historyEnd'));
+    step(prompt(session, 'four'), chunk('S1', 'new'), note('historyEnd'));
+    return { session, records: session.log.read(0) };
+}

package/dist/workstation/acp/processor/test/harness.js

@@ -0,0 +1,120 @@
+/**
+ * Test harness: an in-memory session — raw log, outbox, and the record loop the daemon will run
+ * (spec 2026-10-11 §5.4/§5.5): `step` → execute the record's commands (idempotent by cause) → append
+ * its frames to the outbox.
+ */
+import { executeDownCommands } from '../commands.js';
+import { MemoryRawLog } from '../memoryLog.js';
+import { createProcessor } from '../step.js';
+export class SimulatedCrash extends Error {
+}
+export function newSession() {
+    let now = 1_000;
+    const stdin = [];
+    const log = new MemoryRawLog(() => now++, (line) => stdin.push(line));
+    return { log, stdin, outbox: [], blocks: new Map() };
+}
+/** What the executor appends when a prompt's blocks are gone (T19 does the same). */
+export const PROMPT_LOST = 'The prompt was lost before it reached the agent';
+/**
+ * Process every record from `from` to the head — including the `down` records the loop itself
+ * appends — and return the offset to continue from.
+ */
+export function run(processor, session, from, options = {}) {
+    let next = from;
+    while (next < session.log.head) {
+        const record = session.log.read(next, 1)[0];
+        const output = processor.step(record);
+        const report = executeDownCommands(session.log, output.commands, (ref) => session.blocks.get(ref));
+        for (const command of report.unresolved) {
+            const requestId = JSON.parse(command.line).id;
+            session.log.append({ kind: 'note', note: { type: 'agent_prompt_failed', requestId, error: PROMPT_LOST } });
+        }
+        options.afterCommands?.(record, output.commands);
+        session.outbox.push(...output.frames);
+        next += 1;
+    }
+    return next;
+}
+export function append(session, ...entries) {
+    for (const entry of entries)
+        session.log.append(entry);
+}
+export const spawnEntry = (spawnId = 'spawn-1') => ({ kind: 'proc', proc: { type: 'spawn', spawnId, pid: 4242, pgid: 4242, startTime: 'Sat Oct 11 10:00:00 2026' } });
+export const exitEntry = (code = 0) => ({ kind: 'proc', proc: { type: 'exit', code, signal: null, stderrTail: '' } });
+export const up = (message) => ({ kind: 'up', line: JSON.stringify(message) });
+export const note = (type, fields = {}) => ({ kind: 'note', note: { type, ...fields } });
+/** The `initialize` result a v1 agent answers with. */
+export const initializeResult = (extra = {}) => ({ protocolVersion: 1, agentCapabilities: {}, authMethods: [], ...extra });
+/** JSON-RPC requests (with ids) the processor wrote to stdin, parsed. */
+export function sentRequests(session) {
+    return session.stdin
+        .map((line) => JSON.parse(line))
+        .filter((m) => typeof m.method === 'string' && 'id' in m);
+}
+/** An `agent_prompt` note whose blocks the session holds under a fresh ref. */
+export function prompt(session, text, fields = {}) {
+    const blocksRef = `blocks-${session.blocks.size + 1}`;
+    session.blocks.set(blocksRef, [{ type: 'text', text }]);
+    return note('agent_prompt', { blocksRef, ...fields });
+}
+/** Frames in the outbox, as JSON (for byte-for-byte comparison). */
+export const framesJson = (session) => session.outbox.map((frame) => JSON.stringify(frame));
+/** The JSON-RPC response the agent writes for request `id`. */
+export const respond = (id, result = {}) => up({ jsonrpc: '2.0', id, result });
+/** The id of the last request with `method` written to stdin. */
+export const lastRequestId = (session, method) => sentRequests(session).filter((request) => request.method === method).at(-1).id;
+/**
+ * Spawn, answer `initialize`, open the session with `session/new` and answer it with `sessionId`: the
+ * response binds the root (Task 17b — no helper binds it any more). Returns the offset to continue from.
+ */
+export function openSession(session, processor = createProcessor(), sessionId = 'S1', spawnId = 'spawn-1', newResult = {}) {
+    append(session, spawnEntry(spawnId));
+    let next = run(processor, session, processor.state.offset + 1);
+    append(session, respond(lastRequestId(session, 'initialize'), initializeResult()));
+    next = run(processor, session, next);
+    append(session, note('agent_session_open', { mode: 'new', cwd: '/work' }));
+    next = run(processor, session, next);
+    append(session, respond(lastRequestId(session, 'session/new'), { sessionId, ...newResult }));
+    next = run(processor, session, next);
+    return { processor, next, sessionId };
+}
+/**
+ * Fold records `[0, until)` into a fresh processor the way recovery replays (commands go through the
+ * idempotent executor, so nothing already in raw is written again; frames are collected, not sent).
+ * The log alone is enough: the open response binds the root.
+ */
+export function replay(session, until = session.log.head) {
+    const processor = createProcessor();
+    const frames = [];
+    for (let next = 0; next < until; next += 1) {
+        const output = processor.step(session.log.read(next, 1)[0]);
+        const report = executeDownCommands(session.log, output.commands, (ref) => session.blocks.get(ref));
+        if (report.written.length > 0)
+            throw new Error(`replay wrote ${report.written.length} new command(s) at record ${next}`);
+        frames.push(...output.frames);
+    }
+    return { processor, frames };
+}
+/** The `id` of the last `session/prompt` written to stdin. */
+export const lastPromptId = (session) => sentRequests(session).filter((r) => r.method === 'session/prompt').at(-1).id;
+/** A `session/request_permission` the agent sends. */
+export const permissionRequest = (id, sessionId = 'S1', options = ['allow', 'deny'], toolCall = { toolCallId: 'call-1', title: 'Edit file' }) => up({ jsonrpc: '2.0', id, method: 'session/request_permission', params: {
+        sessionId, toolCall, options: options.map((optionId) => ({ optionId, name: optionId, kind: optionId === 'allow' ? 'allow_once' : 'reject_once' })),
+    } });
+/** A `'form'` `elicitation/create` the agent sends. */
+export const elicitationRequest = (id, message = 'Which branch?', sessionId = 'S1') => up({ jsonrpc: '2.0', id, method: 'elicitation/create', params: {
+        sessionId, mode: 'form', message, requestedSchema: { type: 'object', properties: { branch: { type: 'string', title: 'Branch' } } },
+    } });
+/** A `session/update` notification. */
+export const update = (sessionId, fields) => up({ jsonrpc: '2.0', method: 'session/update', params: { sessionId, update: fields } });
+/** An agent text chunk. */
+export const chunk = (sessionId, text, messageId) => update(sessionId, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text }, ...(messageId ? { messageId } : {}) });
+/** Journaled frames of one kind (`agent_turn_done` / `agent_event`). */
+export const framesOf = (session, t) => session.outbox.map((f) => f.frame).filter((f) => f.t === t);
+/** The last stdin line, parsed. */
+export const lastStdin = (session) => JSON.parse(session.stdin.at(-1));
+/** A draft `subagent_spawned` update: `child` was spawned under `parent`. */
+export const subagentSpawned = (parent, child) => up({ jsonrpc: '2.0', method: 'session/update', params: { sessionId: parent, update: {
+            sessionUpdate: 'subagent_spawned', subagentSessionId: child, name: child, task: 't', capabilities: {},
+        } } });