@platless/axom-cli 0.3.13 → 0.5.9

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

@@ -0,0 +1,67 @@
+/**
+ * What one record produced: its down commands (each with its `(o, i)` cause) and its frames (each with
+ * its `(o, i)` src). Shared by `step.ts` (connection layer) and `session.ts` (turns and cards).
+ */
+import { CommandBudgetExceededError, MAX_COMMANDS_PER_RECORD, errorLine, notificationLine, outboundRequestId, requestLine, resultLine, } from './jsonrpc.js';
+/** A command was produced with no running adapter process to address it to — a processor bug. */
+export class CommandWithoutSpawnError extends Error {
+}
+export class RecordOutput {
+    o;
+    spawnId;
+    commands = [];
+    frames = [];
+    /**
+     * @param spawnId the running spawn **when a command is pushed** (read then, not at construction: a
+     * `spawn` record closes the old process and addresses its `initialize` to the new one).
+     */
+    constructor(o, spawnId = () => undefined) {
+        this.o = o;
+        this.spawnId = spawnId;
+    }
+    push(line, extras = {}) {
+        const i = this.commands.length;
+        if (i >= MAX_COMMANDS_PER_RECORD) {
+            throw new CommandBudgetExceededError(`record ${this.o} produced more than ${MAX_COMMANDS_PER_RECORD} commands`);
+        }
+        const spawnId = this.spawnId();
+        if (spawnId === undefined)
+            throw new CommandWithoutSpawnError(`record ${this.o} produced a command with no running adapter process`);
+        const cause = { o: this.o, i };
+        this.commands.push({
+            cause,
+            spawnId,
+            line: line(i),
+            ...(extras.annotation !== undefined ? { annotation: extras.annotation } : {}),
+            ...(extras.fill !== undefined ? { fill: extras.fill } : {}),
+            ...(extras.redact !== undefined ? { redact: extras.redact } : {}),
+        });
+        return cause;
+    }
+    /** Throws `CommandBudgetExceededError` once this record already produced 16 commands (`outboundRequestId`). */
+    request(method, params, extras) {
+        let id = -1;
+        const cause = this.push((index) => {
+            id = outboundRequestId({ o: this.o, i: index });
+            return requestLine(id, method, params);
+        }, extras);
+        return { id, cause };
+    }
+    notify(method, params) {
+        this.push(() => notificationLine(method, params));
+    }
+    result(id, result) {
+        this.push(() => resultLine(id, result));
+    }
+    error(id, error) {
+        this.push(() => errorLine(id, error));
+    }
+    /** A journaled frame; the caller has already numbered it. */
+    frame(frame) {
+        this.frames.push({ journaled: true, frame, src: { o: this.o, i: this.frames.length } });
+    }
+    /** An unnumbered frame: a level, an RPC reply, or a `processor.*` frame for the daemon. */
+    unjournaled(frame) {
+        this.frames.push({ journaled: false, frame, src: { o: this.o, i: this.frames.length } });
+    }
+}

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

@@ -0,0 +1,42 @@
+import { AGENT_WIRE_RUNTIME_PROFILE_VERSION, AGENT_WIRE_SCOPED_ORIGIN_VERSION, AGENT_WIRE_SESSION_AUTH_METHODS_VERSION, AGENT_WIRE_SESSION_STATE_VERSION, } from '../../protocol/agent.js';
+function withSessionRef(frame, sessionRef) {
+    const { t, ...rest } = frame;
+    return { t, sessionRef, ...rest };
+}
+export function projectFrame(output, context) {
+    const frame = output.frame;
+    const t = frame.t;
+    if (typeof t !== 'string' || t.startsWith('processor.'))
+        return { frame: null };
+    const wire = context.serverAgentWire;
+    switch (t) {
+        case 'agent_event': {
+            if (frame.acpSessionId !== undefined && wire < AGENT_WIRE_SCOPED_ORIGIN_VERSION) {
+                const payload = frame.payload;
+                if (frame.eventName === 'permission_request' && typeof payload?.requestId === 'string') {
+                    return { frame: null, note: { type: 'agent_answer_undeliverable', requestId: payload.requestId } };
+                }
+                return { frame: null };
+            }
+            return { frame: withSessionRef(frame, context.sessionRef) };
+        }
+        case 'agent_turn_done': {
+            const { agentRefused, errorCode, ...rest } = frame;
+            const projected = withSessionRef(rest, context.sessionRef);
+            if (agentRefused === true && rest.status === 'failed' && wire >= AGENT_WIRE_SESSION_AUTH_METHODS_VERSION) {
+                if (context.authMethods)
+                    projected.authMethods = context.authMethods;
+                if (typeof errorCode === 'number')
+                    projected.errorCode = errorCode;
+            }
+            return { frame: projected };
+        }
+        case 'agent_session_state':
+            return { frame: wire >= AGENT_WIRE_SESSION_STATE_VERSION ? withSessionRef(frame, context.sessionRef) : null };
+        case 'agent_runtime_profile':
+            return { frame: wire >= AGENT_WIRE_RUNTIME_PROFILE_VERSION ? withSessionRef(frame, context.sessionRef) : null };
+        default:
+            // RPC replies carry the server's request `id`, not a `sessionRef`.
+            return { frame: { ...frame } };
+    }
+}

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

@@ -0,0 +1,128 @@
+/**
+ * The raw records the ACP processor folds over (spec 2026-10-11 §5.3), and their on-stream spelling.
+ *
+ * ## Two spellings, one record
+ *
+ * keeper-acp stores each record as one line of a kit stream (`{o, t, k, …}`, §3.4) with short keys
+ * (`up{l}`, `down{l, a, redact?}`, `proc{kind, …}`, `note{n}`, `err{l}` — the names in
+ * interface-contracts). The processor works on the long, typed spelling below. {@link encodeStreamRecord}
+ * and {@link decodeStreamRecord} are the only bridge, so neither side has to know the other's names.
+ *
+ * ## What each kind is
+ *
+ * - `up`: one line the adapter wrote to stdout — a JSON-RPC message, verbatim.
+ * - `down`: one line written to the adapter's stdin. `annotation.cause = {o, i}` names the record
+ *   (and the command index within it) whose processing produced the line; that is what makes
+ *   commands idempotent (`commands.ts`). `annotation` is otherwise opaque to the keeper. `redact`
+ *   lists the `secretRef`s whose values were replaced in the *logged* copy of the line — stdin got
+ *   the real value, the log never does (§13). It names refs, never secrets.
+ * - `proc`: keeper-synthesised process events — `spawn{spawnId, pid, pgid, startTime}` and
+ *   `exit{code, signal, stderrTail, reason?}`.
+ * - `note`: an opaque record the daemon wrote (server commands, its own decisions). Notes carry no
+ *   secrets and no large payloads (§5.4): secrets by `secretRef`, large blocks by reference to the
+ *   one `down` record that carries them.
+ * - `err`: one already-redacted stderr line.
+ *
+ * `o` is the record's offset in the session's raw stream (monotonic, gap-free per stream) and `t` is
+ * the keeper's receive time in epoch ms — the **only** clock the processor may read.
+ */
+export function sameCause(a, b) {
+    return a !== undefined && a.o === b.o && a.i === b.i;
+}
+/** The map key for a cause; `o` and `i` are integers so this is injective. */
+export function causeKey(cause) {
+    return `${cause.o}:${cause.i}`;
+}
+export class MalformedRecordError extends Error {
+}
+export function encodeStreamRecord(record) {
+    const { o, t } = record;
+    switch (record.kind) {
+        case 'up':
+            return { o, t, k: 'up', l: record.line };
+        case 'down':
+            return {
+                o, t, k: 'down', l: record.line,
+                ...(record.annotation !== undefined ? { a: record.annotation } : {}),
+                ...(record.redact !== undefined ? { redact: record.redact } : {}),
+            };
+        case 'proc': {
+            const { type, ...rest } = record.proc;
+            return { o, t, k: 'proc', kind: type, ...rest };
+        }
+        case 'note':
+            return { o, t, k: 'note', n: record.note };
+        case 'err':
+            return { o, t, k: 'err', l: record.line };
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function str(value, what) {
+    if (typeof value !== 'string')
+        throw new MalformedRecordError(`${what} is not a string`);
+    return value;
+}
+/** Inverse of {@link encodeStreamRecord}. Throws {@link MalformedRecordError} on anything else. */
+export function decodeStreamRecord(value) {
+    if (!isRecord(value))
+        throw new MalformedRecordError('record is not an object');
+    const { o, t, k } = value;
+    if (typeof o !== 'number' || !Number.isSafeInteger(o) || o < 0)
+        throw new MalformedRecordError('record offset is not a non-negative integer');
+    if (typeof t !== 'number' || !Number.isFinite(t))
+        throw new MalformedRecordError('record time is not a number');
+    switch (k) {
+        case 'up':
+            return { o, t, kind: 'up', line: str(value.l, 'up.l') };
+        case 'err':
+            return { o, t, kind: 'err', line: str(value.l, 'err.l') };
+        case 'down': {
+            const a = value.a;
+            let annotation;
+            if (a !== undefined) {
+                if (!isRecord(a) || !isRecord(a.cause) || !Number.isSafeInteger(a.cause.o) || !Number.isSafeInteger(a.cause.i)) {
+                    throw new MalformedRecordError('down.a.cause is not {o, i}');
+                }
+                annotation = a;
+            }
+            const redact = value.redact;
+            if (redact !== undefined && !(Array.isArray(redact) && redact.every((r) => typeof r === 'string'))) {
+                throw new MalformedRecordError('down.redact is not a string array');
+            }
+            return {
+                o, t, kind: 'down', line: str(value.l, 'down.l'),
+                ...(annotation !== undefined ? { annotation } : {}),
+                ...(redact !== undefined ? { redact: redact } : {}),
+            };
+        }
+        case 'proc': {
+            if (value.kind === 'spawn') {
+                const { spawnId, pid, pgid, startTime } = value;
+                if (typeof spawnId !== 'string' || typeof pid !== 'number' || typeof pgid !== 'number'
+                    || (typeof startTime !== 'string' && typeof startTime !== 'number')) {
+                    throw new MalformedRecordError('proc spawn is missing spawnId/pid/pgid/startTime');
+                }
+                return { o, t, kind: 'proc', proc: { type: 'spawn', spawnId, pid, pgid, startTime } };
+            }
+            if (value.kind === 'exit') {
+                const { code, signal, stderrTail, reason } = value;
+                if ((code !== null && typeof code !== 'number') || (signal !== null && typeof signal !== 'string')
+                    || typeof stderrTail !== 'string' || (reason !== undefined && typeof reason !== 'string')) {
+                    throw new MalformedRecordError('proc exit is missing code/signal/stderrTail');
+                }
+                return { o, t, kind: 'proc', proc: { type: 'exit', code, signal, stderrTail, ...(reason !== undefined ? { reason } : {}) } };
+            }
+            throw new MalformedRecordError(`unknown proc kind ${JSON.stringify(value.kind)}`);
+        }
+        case 'note': {
+            const n = value.n;
+            if (!isRecord(n) || typeof n.type !== 'string')
+                throw new MalformedRecordError('note.n has no string type');
+            return { o, t, kind: 'note', note: n };
+        }
+        default:
+            throw new MalformedRecordError(`unknown record kind ${JSON.stringify(k)}`);
+    }
+}

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

@@ -0,0 +1,181 @@
+/**
+ * The two level signals (spec §5.4: "电平类帧从状态现算"): the agent's self-reported activity
+ * (`agent_session_state`) and the runtime diagnostics (`agent_runtime_profile`). Neither is numbered
+ * or journaled (analysis B §5); both are folded into state from the log, so after a restart they are
+ * recomputed by replay and re-sent with `agent_opened` ({@link activityRaw}, {@link runtimeDiagnostics}).
+ *
+ * - **Activity** — `connectAgent`'s `_claude/sdkMessage` handler (`claudeActivityRaw`) and the mapper's
+ *   `codexActivityRaw` on the root session's `session_info_update`, as `AcpSession.reportActivity`
+ *   joins them. Both sinks are bound only once the session is open, so earlier pushes are dropped,
+ *   as today.
+ * - **Diagnostics** — `generation` is the keeper's `spawnId` (analysis B B2: no `randomUUID`), and
+ *   `revision` is a fold: +1 on process exit and on every applied Qoder profile (the `connectAgent`
+ *   closure, `acpClient.ts`). `launch` arrives in an `agent_launch` note the daemon writes after the
+ *   spawn (analysis B D5: computed once, at spawn). Task 17c: the permission callback snapshot
+ *   (`callbacks`, {@link callbackSnapshot}) — published, and the revision bumped, on every change to the
+ *   session's pending/settled permission cards, as `AcpSession.publishCallbacks` does for every agent.
+ */
+import { claudeActivityRaw } from '../activityReporting.js';
+import { parseQoderProfile, sameProfileIdentity } from '../../qoderAdapter/profile.js';
+import { connectionGenerationOf } from '../../qoderAdapter/callbackContext.js';
+import { isRecord } from './emit.js';
+import { getOwn, initialRuntime, PENDING_PROFILE_LIMIT, putOwn } from './state.js';
+function opened(state) {
+    return state.open.status === 'open';
+}
+/** One agent-reported activity push (vendor-verbatim): a level, never numbered. */
+export function reportActivity(state, out, raw, t) {
+    if (!opened(state))
+        return;
+    state.activity = { raw, t };
+    out.unjournaled({ t: 'agent_session_state', vendor: vendorOf(state), raw });
+}
+/** `InitializeResponse.agentInfo.name` (`agentSessions.ts`'s `vendor`), `''` when the agent named none. */
+export function vendorOf(state) {
+    return state.initialize.status === 'ready' ? state.initialize.facts.agentInfo?.name ?? '' : '';
+}
+/** `_claude/sdkMessage` — only the `session_state_changed` system message is activity. */
+export function onClaudeSdkMessage(state, out, params, t) {
+    const raw = claudeActivityRaw(isRecord(params) ? params : {});
+    if (raw)
+        reportActivity(state, out, raw, t);
+}
+/** `agent_opened.activityRaw`: the last push, if any. */
+export function activityRaw(state) {
+    return state.activity?.raw;
+}
+/** The current adapter process's `spawnId` (running, or the one that exited). */
+export function currentSpawnId(state) {
+    return state.process.status === 'running' ? state.process.spawn.spawnId
+        : state.process.status === 'exited' ? state.process.spawnId : undefined;
+}
+/**
+ * `AgentRuntimeDiagnostics.callbacks` — the snapshot `AcpSession.publishCallbacks` last published,
+ * recomputed from state (every change to the cards it lists publishes, so the two are the same), or
+ * `undefined` before the first publish. Pending and settled are listed only while `complete`.
+ */
+export function callbackSnapshot(state) {
+    const { complete, rootSessionId } = state.callbacks;
+    const spawnId = currentSpawnId(state);
+    if (rootSessionId === null || spawnId === undefined)
+        return undefined;
+    return {
+        rootSessionId, connectionGeneration: connectionGenerationOf(spawnId), complete,
+        pending: complete ? Object.values(state.permissions).map((card) => ({
+            requestId: card.requestId, originNativeSessionId: card.origin, rpcRequestId: card.rpcRequestId,
+        })) : [],
+        settled: complete ? state.settledPermissions.map(({ requestId, reason }) => ({ requestId, reason })) : [],
+    };
+}
+/** The diagnostics as `agent_runtime_profile`/`agent_opened.runtimeDiagnostics` carry them, or `undefined` before a spawn and its `agent_launch` note. */
+export function runtimeDiagnostics(state) {
+    const spawnId = currentSpawnId(state);
+    const { revision, available, launch, profile } = state.runtime;
+    if (spawnId === undefined || launch === undefined)
+        return undefined;
+    const callbacks = callbackSnapshot(state);
+    return { generation: spawnId, revision, available, launch, ...(profile !== undefined ? { profile } : {}),
+        ...(callbacks !== undefined ? { callbacks } : {}) };
+}
+/**
+ * `AcpSession.publishCallbacks` → `connectAgent`'s `publishCallbacks`: the snapshot changed, the
+ * revision goes up and the level is re-sent. Ignored before a root is known (today: a snapshot for a
+ * session the connection has not bound). Callers change the cards first, then publish.
+ */
+export function publishCallbacks(state, out) {
+    const root = state.rootSessionId ?? state.history?.rootSessionId ?? null;
+    if (root === null)
+        return;
+    state.callbacks.rootSessionId = root;
+    state.runtime.revision += 1;
+    changed(state, out);
+}
+/** A diagnostics change: published (unnumbered) once the session is open, as `onRuntimeDiagnostics` is. */
+function changed(state, out) {
+    if (!opened(state))
+        return;
+    const diagnostics = runtimeDiagnostics(state);
+    if (diagnostics)
+        out.unjournaled({ t: 'agent_runtime_profile', diagnostics: JSON.parse(JSON.stringify(diagnostics)) });
+}
+export function resetRuntime(state) {
+    state.runtime = initialRuntime();
+    state.activity = null;
+}
+/** `agent_launch{launch}` — what `connectAgent` computes at spawn (`launchSource`, `findOnPath`, platform). */
+export function onLaunchNote(state, launch) {
+    if (!isRecord(launch) || state.process.status !== 'running')
+        return false;
+    const { source, executable, platform, architecture, transport } = launch;
+    if (!['command-override', 'registry', 'registry-fallback', 'direct'].includes(source) || typeof executable !== 'string'
+        || typeof platform !== 'string' || typeof architecture !== 'string' || transport !== 'stdio')
+        return false;
+    state.runtime.launch = { source: source, executable: executable.slice(0, 4096), platform, architecture, transport };
+    return true;
+}
+/** The `initialize` result's `_meta.qoderProfile` (`connectAgent`, right after the handshake). */
+export function onInitialized(state, result) {
+    const meta = isRecord(result) && isRecord(result._meta) ? result._meta : undefined;
+    const profile = parseQoderProfile(meta?.qoderProfile);
+    if (profile)
+        state.runtime.profile = profile;
+    else
+        delete state.runtime.profile;
+}
+/** The child exited: unavailable, profile no longer observed (`child.once('exit')` in `connectAgent`). */
+export function onProcessExit(state, out) {
+    const runtime = state.runtime;
+    runtime.revision += 1;
+    runtime.available = false;
+    if (runtime.profile)
+        runtime.profile = { ...runtime.profile, observerHealthy: false, rootConfirmed: false };
+    changed(state, out);
+}
+function applyProfile(state, out, sessionId, revision, profile) {
+    const runtime = state.runtime;
+    const previous = runtime.profile;
+    if (!previous || !runtime.available || sessionId !== state.rootSessionId || revision <= runtime.adapterRevision
+        || !sameProfileIdentity(previous, profile) || profile.rootSessionId !== state.rootSessionId
+        || (previous.runtimeGeneration !== undefined && profile.runtimeGeneration !== previous.runtimeGeneration)
+        || (profile.rootConfirmed === true && !profile.runtimeGeneration))
+        return;
+    runtime.adapterRevision = revision;
+    runtime.revision += 1;
+    runtime.profile = profile;
+    changed(state, out);
+}
+/** `_axom/qoder/profile{sessionId, revision, profile}` — the `connectAgent` handler, over state. */
+export function onProfileNotification(state, out, params) {
+    if (!isRecord(params))
+        return;
+    const profile = parseQoderProfile(params.profile);
+    const { sessionId, revision } = params;
+    if (!state.runtime.profile || !profile || typeof sessionId !== 'string' || profile.rootSessionId !== sessionId
+        || !Number.isSafeInteger(revision) || revision <= 0 || !sameProfileIdentity(state.runtime.profile, profile))
+        return;
+    if (state.rootSessionId !== null) {
+        applyProfile(state, out, sessionId, revision, profile);
+        return;
+    }
+    // ACP may notify before its new/load reply: bounded candidates, evidence only once the reply binds.
+    const pending = state.runtime.pendingProfiles;
+    const previous = getOwn(pending, sessionId);
+    if (previous && (revision <= previous.revision || profile.runtimeGeneration !== previous.profile.runtimeGeneration))
+        return;
+    if (!previous && Object.keys(pending).length >= PENDING_PROFILE_LIMIT)
+        return;
+    putOwn(pending, sessionId, { revision: revision, profile });
+}
+/** The root just bound (`bindDraftUpdates`' diagnostics half): drop a profile for another root, apply a pending one. */
+export function onRootBound(state, out, sessionId) {
+    const runtime = state.runtime;
+    const current = runtime.profile;
+    if (current?.rootSessionId && current.rootSessionId !== sessionId) {
+        const { rootSessionId: _root, runtimeGeneration: _generation, ...rest } = current;
+        runtime.profile = { ...rest, rootConfirmed: false, initialized: false, observerHealthy: false };
+    }
+    const pending = getOwn(runtime.pendingProfiles, sessionId);
+    runtime.pendingProfiles = {};
+    if (pending)
+        applyProfile(state, out, sessionId, pending.revision, pending.profile);
+}

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

@@ -0,0 +1,61 @@
+/**
+ * The ACP SDK's own zod schemas, used synchronously as a schema library (spec 2026-10-11 §5.4: "SDK
+ * 只作 schema 库（同步 zod 校验/剥离）").
+ *
+ * ## Why these schemas, and why loaded this way
+ *
+ * The live path validates and strips every inbound message with the SDK's generated schemas
+ * (`dist/schema/zod.gen.js` — e.g. `ClientApp` parses `session/update` through `zSessionNotification`,
+ * `session/request_permission` through `zRequestPermissionRequest`). The processor has to apply the
+ * **same** schemas or moving a session onto it changes payload bytes (analysis B F2). Copying them
+ * would drift on the next SDK bump; importing them is the only honest option.
+ *
+ * The package's `exports` map does not expose `zod.gen.js`, so a bare subpath import is refused. It is
+ * reached instead by resolving the package entry and taking its sibling — a plain file path, which
+ * `exports` does not police — and loaded with `require` (synchronous `require(esm)`, Node ≥ 22.12;
+ * `engines.node` is `>=24`). This happens once, at module load: nothing here runs inside `step`.
+ * `guard.test.ts` allows exactly this file to import `node:module`.
+ *
+ * ## The pin
+ *
+ * `dist/schema/zod.gen.js` is the SDK's **private** layout, so `package.json` pins the SDK to one
+ * exact version (no range) and `sdkSchemas.test.ts` checks the installed version is that pin and the
+ * file resolves — an SDK bump has to be a deliberate change that re-runs that test.
+ */
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+/** The absolute path of the SDK's generated zod module (a sibling of its `acp.js` entry). */
+export function sdkZodGenPath(resolve = require.resolve) {
+    const entry = resolve('@agentclientprotocol/sdk');
+    const suffix = 'acp.js';
+    if (!entry.endsWith(suffix)) {
+        throw new Error(`Unexpected @agentclientprotocol/sdk entry point ${entry}: the processor reads the SDK's private dist/schema/zod.gen.js next to dist/acp.js; re-check the pinned SDK version`);
+    }
+    return `${entry.slice(0, -suffix.length)}schema/zod.gen.js`;
+}
+function loadZodGen() {
+    const path = sdkZodGenPath();
+    try {
+        return require(path);
+    }
+    catch (error) {
+        throw new Error(`Cannot load the ACP SDK's zod schemas from ${path} (private SDK layout; re-check the pinned SDK version): ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+const zodGen = loadZodGen();
+function schema(name) {
+    const found = zodGen[name];
+    if (!found || typeof found.safeParse !== 'function')
+        throw new Error(`@agentclientprotocol/sdk has no schema ${name}`);
+    return found;
+}
+/** Inbound (agent → client) request params, by method — the schemas `clientRequestSpecs` uses. */
+export const INBOUND_REQUEST_SCHEMAS = {
+    'session/request_permission': schema('zRequestPermissionRequest'),
+    'elicitation/create': schema('zCreateElicitationRequest'),
+};
+/** Inbound notification params, by method — the schemas `clientNotificationSpecs` uses. */
+export const INBOUND_NOTIFICATION_SCHEMAS = {
+    'session/update': schema('zSessionNotification'),
+    'elicitation/complete': schema('zCompleteElicitationNotification'),
+};