@platless/axom-cli 0.1.0 → 0.5.9

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

@@ -0,0 +1,364 @@
+/**
+ * `session/update` → journaled `agent_event`s, one record at a time, in log order (Task 17b).
+ *
+ * ## One path, in log order (replaces `draftInterceptor` + the SDK's async chain)
+ *
+ * Today a draft variant or a child session's update is diverted by `interceptDraftUpdates` and
+ * applied **synchronously** while the stream is read, and every other update travels the SDK's
+ * **asynchronous** handler chain — so the two orders depend on pipe chunking (analysis B §0.1: the
+ * same bytes, written at once or line by line, gave different event orders). Here both kinds are
+ * handled on their own record, so the order of events is the order of the log, whatever the
+ * chunking. What differs between them is only what `AcpSession` does with each, kept as it is:
+ *
+ * - **The root session's own ordinary update** is parsed with the SDK's `zSessionNotification` (as the
+ *   SDK's router does — so unknown keys are stripped and an unknown variant is dropped), mapped with
+ *   the root scope, and routed like `AcpSession.routeMappedEvent`: background-writer evidence and
+ *   message-boundary tracking for `agent_message` synthesis.
+ * - **A draft variant (any session) or any update on another session** is mapped raw, with that
+ *   session's own scope, like `AcpSession.applyDivertedUpdate` → `emitEvent`: a child's events carry
+ *   `acpSessionId`, and none of them touch the root's message boundaries.
+ *
+ * Both feed the permission-origin graph (`subagent_spawned`) and the unfinished async-task set.
+ *
+ * ## Binding, and what replaced the pre-bind buffer
+ *
+ * The root is bound by the open **response** (`control.ts`). An update that arrives before any root
+ * is bound — outside a load's history window — has no session to belong to and is dropped
+ * (`droppedUpdates`). Today's 32-entry, 5-second pre-bind buffer existed because the SDK processed
+ * the `session/new` response *after* an update the agent had written *after* it; in log order that
+ * update follows the response and is applied normally (analysis B A3/C1; the raw captures in `tmp/`
+ * show Claude's first `available_commands_update` after the response line).
+ *
+ * ## Load history
+ *
+ * Between a `session/load` request and the `historyEnd` note, every update (any session) is history — except a level update
+ * ({@link LEVEL_UPDATES}) the loaded session sends once its response is in, which is folded live (Task 21):
+ * folded with its own scopes and message boundaries exactly as `adoption.ts` `foldScopedReplayEvents`
+ * folds a finished list — incrementally here — then validated and emitted **unnumbered** as
+ * `processor.history_event` frames for the daemon's backfill, and observed for origins and
+ * background writers (`AcpSession.observeReplayEvent`).
+ *
+ * ## `agent_message` synthesis and out-of-turn chunks
+ *
+ * `AcpSession`'s rule: an `agent_message` closes the streaming assistant message when its `messageId`
+ * changes and when a turn ends (before the turn's `agent_turn_done`). One addition, decided for 17b:
+ * chunks that arrive with **no turn running** — after a prompt's response, or an agent working on its
+ * own — are emitted as they are (an `agent_event` never carries a turn id; that is what today's path
+ * does with them too), and the message they open is closed **before the next turn starts** instead
+ * of being merged into that turn's message when neither carries a `messageId`.
+ *
+ * ## The Qoder adapter boundaries (Task 17c)
+ *
+ * `AcpSession` passes events through three adapter boundaries, and so does the processor, over its
+ * checkpointed data (`state.boundaries`), at the same points:
+ * - the root's own update ({@link routeOwnEvent} = `routeMappedEvent`): the foreground-output boundary
+ *   may hold an unaddressed chunk back (certified qoder-cli), the terminal repair observes it, the
+ *   subwork boundary maps it (`supportsSubworkMeta`) — and only an unscoped mapped chunk tracks the
+ *   root's message boundary;
+ * - everything `AcpSession.emitEvent` emits ({@link emitSessionEvent}): diverted updates, cards, and the
+ *   terminal repair's own events (`sideChannel.ts`) — observed by the repair, then subwork-mapped;
+ * - load history (`observeReplayEvent`): observed by the repair.
+ */
+import { DRAFT_SESSION_UPDATE_NAMES } from '../draftSubagents.js';
+import { mapSessionUpdate, newMapperScopeData, SessionMapperState } from '../sessionUpdateMapper.js';
+import { certifiedRuntime, ForegroundOutputBoundary } from '../../qoderAdapter/foregroundOutput.js';
+import { SubworkBoundary, supportsSubworkMeta } from '../../qoderAdapter/subwork.js';
+import { TerminalRepairFold } from '../../qoderAdapter/backgroundTerminalFold.js';
+import { validateWireEvent } from '../validate.js';
+import { emitEvent, isRecord } from './emit.js';
+import { observeSubagentSpawned } from './origins.js';
+import { reportActivity } from './runtime.js';
+import { INBOUND_NOTIFICATION_SCHEMAS } from './sdkSchemas.js';
+import { ASYNC_TASK_LIMIT, getOwn, putOwn } from './state.js';
+const DRAFT_NAMES = new Set(DRAFT_SESSION_UPDATE_NAMES);
+/**
+ * Updates that state what the session **is now** (its command table, mode, config, usage, info), not what happened in it (Task 21).
+ * One the loaded session sends after the load's response — the root is bound — but before the daemon's `historyEnd` is not history:
+ * it is folded live (numbered), or a reopened session would never show its command table (Claude sends `available_commands_update`
+ * from a timer right after answering `session/load`). Before the response such an update is part of the replay and stays history.
+ */
+const LEVEL_UPDATES = new Set([
+    'available_commands_update', 'current_mode_update', 'config_option_update', 'usage_update', 'session_info_update',
+]);
+const SESSION_NOTIFICATION = INBOUND_NOTIFICATION_SCHEMAS['session/update'];
+function stringField(payload, key) {
+    const value = payload[key];
+    return typeof value === 'string' ? value : null;
+}
+/** The mapper for `nativeSessionId`, over the checkpointed scope data (created on first use). */
+function liveMapper(state, out, nativeSessionId, t) {
+    let data = getOwn(state.mapperScopes, nativeSessionId);
+    if (!data)
+        putOwn(state.mapperScopes, nativeSessionId, data = newMapperScopeData());
+    // Codex's activity rides the root's own `session_info_update` (`AcpSession.scopes`' callback).
+    return new SessionMapperState((raw) => {
+        if (nativeSessionId === state.rootSessionId)
+            reportActivity(state, out, raw, t);
+    }, data);
+}
+/** An inbound `session/update` notification (params not yet validated). */
+export function onSessionUpdate(state, params, out, t) {
+    if (!isRecord(params) || typeof params.sessionId !== 'string' || params.sessionId.length === 0 || !isRecord(params.update)) {
+        state.diagnostics.droppedUpdates += 1;
+        return;
+    }
+    const { sessionId, update } = params;
+    if (state.history && !(LEVEL_UPDATES.has(String(update.sessionUpdate)) && state.rootSessionId !== null && sessionId === state.rootSessionId)) {
+        onHistoryUpdate(state, state.history, sessionId, update, out);
+        return;
+    }
+    const root = state.rootSessionId;
+    if (root === null) {
+        state.diagnostics.droppedUpdates += 1;
+        return;
+    }
+    const variant = update.sessionUpdate;
+    const draft = typeof variant === 'string' && DRAFT_NAMES.has(variant);
+    if (!draft && sessionId === root) {
+        const parsed = SESSION_NOTIFICATION.safeParse(params);
+        if (!parsed.success) {
+            state.diagnostics.droppedUpdates += 1;
+            return;
+        }
+        const stripped = parsed.data.update;
+        for (const event of mapSessionUpdate(stripped, liveMapper(state, out, root, t)))
+            routeOwnEvent(state, out, event);
+        return;
+    }
+    let events;
+    try {
+        events = mapSessionUpdate(update, liveMapper(state, out, sessionId, t));
+    }
+    catch {
+        // `applyDivertedUpdate`: an unmapped variant on a diverted update is dropped, the session lives on.
+        state.diagnostics.droppedUpdates += 1;
+        return;
+    }
+    for (const event of events)
+        emitSessionEvent(state, out, sessionId === root ? event : { ...event, acpSessionId: sessionId });
+}
+/** The agent `initialize` named (`AcpConnection.agentInfo`), if it is ready. */
+function agentInfo(state) {
+    return state.initialize.status === 'ready' ? state.initialize.facts.agentInfo : undefined;
+}
+/** The terminal repair, once a `qoder_terminal_repair` note enabled it. */
+export function repairFold(state) {
+    return state.boundaries.repair ? new TerminalRepairFold(state.boundaries.repair) : undefined;
+}
+/** `this.subworkBoundary?.map(event) ?? [event]`. */
+function throughSubwork(state, event) {
+    const root = state.rootSessionId;
+    if (root === null || !supportsSubworkMeta(agentInfo(state)))
+        return [event];
+    return new SubworkBoundary(root, state.boundaries.subwork).map(event);
+}
+/** `this.foregroundOutput?.endTurn()` — no turn remains. */
+export function endForegroundTurn(state) {
+    state.boundaries.foreground.pending = {};
+}
+/** `AcpSession.routeMappedEvent`, Qoder boundaries included. */
+function routeOwnEvent(state, out, event) {
+    const root = state.rootSessionId;
+    if (certifiedRuntime(agentInfo(state)) && !new ForegroundOutputBoundary(root, state.boundaries.foreground).accept(event))
+        return;
+    repairFold(state)?.observe(event);
+    const subwork = supportsSubworkMeta(agentInfo(state));
+    for (const mapped of throughSubwork(state, event)) {
+        observe(state, mapped);
+        observeBackgroundWriter(state, mapped);
+        if ((!subwork || !mapped.acpSessionId || mapped.acpSessionId === root) &&
+            (mapped.eventName === 'agent_message_chunk' || mapped.eventName === 'agent_thought_chunk'))
+            trackMessageBoundary(state, out, mapped);
+        emitEvent(state, out, mapped);
+    }
+}
+/**
+ * `AcpSession.emitEvent` (minus a card's own checks, `session.ts`): a diverted update, a card, or a
+ * repair event. The repair observes it as given; a root id on `acpSessionId` is dropped; the subwork
+ * boundary maps it; each mapped event feeds the origin graph and is numbered.
+ */
+export function emitSessionEvent(state, out, event) {
+    repairFold(state)?.observe(event);
+    // Inside a load's history window the session being loaded is the root (an attached `AcpSession` knows it).
+    const normalized = event.acpSessionId === (state.rootSessionId ?? state.history?.rootSessionId)
+        ? { eventName: event.eventName, payload: event.payload }
+        : event;
+    for (const mapped of throughSubwork(state, normalized)) {
+        observe(state, mapped);
+        emitEvent(state, out, mapped);
+    }
+}
+/** What every live event feeds besides the outbox: the origin graph and the async-task set. */
+function observe(state, event) {
+    if (event.eventName === 'subagent_spawned') {
+        observeSubagentSpawned(state, event.acpSessionId ?? state.rootSessionId, event.payload.subagentSessionId);
+    }
+    trackAsyncTask(state, event);
+}
+/** `AcpSession.observeBackgroundWriter`: an explicitly detached writer blocks `executionEnded` for good. */
+function observeBackgroundWriter(state, event) {
+    const input = event.payload.rawInput;
+    if (isRecord(input) && input.run_in_background === true)
+        state.backgroundWriterUnconfirmed = true;
+    const output = event.payload.rawOutput;
+    if (isRecord(output) && output.backgrounded === true && (typeof output.taskId === 'string' || typeof output.pid === 'number')) {
+        state.backgroundWriterUnconfirmed = true;
+    }
+}
+const TERMINAL_ASYNC_STATES = new Set(['completed', 'failed', 'stopped']);
+/**
+ * The unfinished async tasks (AIR `async_task_*`), per native session: spawned → running; a state
+ * update sets the last non-terminal state or removes the task on a terminal one. Settles on the
+ * **last** state — a finished shell sends `stopped` then `completed` (`draftSubagents.ts`), and the
+ * second finds nothing left to remove.
+ */
+function trackAsyncTask(state, event) {
+    if (event.eventName !== 'async_task_spawned' && event.eventName !== 'async_task_state_update')
+        return;
+    const taskId = event.payload.asyncTaskId;
+    if (typeof taskId !== 'string' || taskId.length === 0)
+        return;
+    const owner = event.acpSessionId ?? state.rootSessionId;
+    if (owner === null)
+        return;
+    const next = event.eventName === 'async_task_spawned' ? 'running' : event.payload.state;
+    let tasks = getOwn(state.asyncTasks, owner);
+    if (typeof next === 'string' && TERMINAL_ASYNC_STATES.has(next)) {
+        if (tasks && Object.hasOwn(tasks, taskId)) {
+            delete tasks[taskId];
+            if (Object.keys(tasks).length === 0)
+                delete state.asyncTasks[owner];
+        }
+        return;
+    }
+    if (next !== 'running' && next !== 'paused')
+        return;
+    if (!(tasks && Object.hasOwn(tasks, taskId)) && unfinishedAsyncTaskCount(state) >= ASYNC_TASK_LIMIT) {
+        state.diagnostics.untrackedAsyncTasks += 1;
+        return;
+    }
+    if (!tasks)
+        putOwn(state.asyncTasks, owner, tasks = {});
+    putOwn(tasks, taskId, next);
+}
+function unfinishedAsyncTaskCount(state) {
+    let count = 0;
+    for (const tasks of Object.values(state.asyncTasks))
+        count += Object.keys(tasks).length;
+    return count;
+}
+/** Every unfinished async task, as `{nativeSessionId, asyncTaskId, state}`, in insertion order. */
+export function unfinishedAsyncTasks(state) {
+    return Object.entries(state.asyncTasks).flatMap(([nativeSessionId, tasks]) => Object.entries(tasks).map(([asyncTaskId, status]) => ({ nativeSessionId, asyncTaskId, state: status })));
+}
+// ---- agent_message synthesis --------------------------------------------------------------------
+/** `AcpSession.trackMessageBoundary`, plus remembering whether the message began outside any turn. */
+function trackMessageBoundary(state, out, event) {
+    const message = state.message;
+    const messageId = stringField(event.payload, 'messageId');
+    if (message.open && messageId !== null && message.messageId !== null && messageId !== message.messageId)
+        flushMessage(state, out);
+    if (!message.open)
+        message.outOfTurn = state.turns.length === 0;
+    message.open = true;
+    if (messageId !== null)
+        message.messageId = messageId;
+}
+/** `AcpSession.flushMessageCompleted`: close the streaming message with `agent_message` (no-op if none). */
+export function flushMessage(state, out) {
+    const message = state.message;
+    if (!message.open)
+        return;
+    emitEvent(state, out, { eventName: 'agent_message', payload: { messageId: message.messageId ?? 'turn' } });
+    message.open = false;
+    message.messageId = null;
+    message.outOfTurn = false;
+}
+/** A turn is about to start: a message that began outside any turn is closed now, never merged into it. */
+export function flushOutOfTurnMessage(state, out) {
+    if (state.message.open && state.message.outOfTurn)
+        flushMessage(state, out);
+}
+// ---- load history -----------------------------------------------------------------------------
+/** `foldScopedReplayEvents`, one update at a time. */
+function onHistoryUpdate(state, history, sessionId, update, out) {
+    let data = getOwn(history.scopes, sessionId);
+    if (!data)
+        putOwn(history.scopes, sessionId, data = newMapperScopeData());
+    let events;
+    try {
+        events = mapSessionUpdate(update, new SessionMapperState(() => { }, data));
+    }
+    catch {
+        // Today an unmappable update throws out of the whole load (`replayNativeSession`); here one
+        // update is lost and the history goes on — counted, and reported on `processor.history_end`.
+        state.diagnostics.droppedUpdates += 1;
+        history.droppedCount += 1;
+        return;
+    }
+    for (const event of events) {
+        if (event.eventName === 'user_message_chunk')
+            flushHistoryMessage(state, history, sessionId, out);
+        if (event.eventName === 'agent_message_chunk' || event.eventName === 'agent_thought_chunk') {
+            const messageId = stringField(event.payload, 'messageId');
+            const index = history.messages.findIndex((entry) => entry.nativeSessionId === sessionId);
+            const previous = index >= 0 ? history.messages[index] : undefined;
+            if (previous && messageId !== null && previous.messageId !== null && messageId !== previous.messageId) {
+                flushHistoryMessage(state, history, sessionId, out);
+                history.messages.push({ nativeSessionId: sessionId, messageId });
+            }
+            else if (previous) {
+                previous.messageId = messageId ?? previous.messageId;
+            }
+            else {
+                history.messages.push({ nativeSessionId: sessionId, messageId });
+            }
+        }
+        emitHistory(state, history, out, event, sessionId);
+    }
+}
+function flushHistoryMessage(state, history, sessionId, out) {
+    const index = history.messages.findIndex((entry) => entry.nativeSessionId === sessionId);
+    if (index < 0)
+        return;
+    const [message] = history.messages.splice(index, 1);
+    emitHistory(state, history, out, { eventName: 'agent_message', payload: { messageId: message.messageId ?? 'replay' } }, sessionId);
+}
+function emitHistory(state, history, out, event, sessionId) {
+    const scoped = sessionId === history.rootSessionId ? event : { ...event, acpSessionId: sessionId };
+    if (validateWireEvent(scoped)) {
+        state.diagnostics.invalidEvents += 1;
+        return;
+    }
+    // `AcpSession.observeReplayEvent`: history restores the repair's calls, addresses and background-writer evidence.
+    repairFold(state)?.observe(scoped);
+    if (scoped.eventName === 'subagent_spawned') {
+        observeSubagentSpawned(state, scoped.acpSessionId ?? history.rootSessionId, scoped.payload.subagentSessionId, history.rootSessionId);
+    }
+    observeBackgroundWriter(state, scoped);
+    out.unjournaled({
+        t: 'processor.history_event',
+        eventName: scoped.eventName,
+        payload: scoped.payload,
+        ...(scoped.acpSessionId ? { acpSessionId: scoped.acpSessionId } : {}),
+    });
+}
+/**
+ * Close the history window: flush the open history messages (in first-chunk order, as
+ * `foldScopedReplayEvents` does at the end of its list) and report it. `ok: false` when the load
+ * failed or the connection closed — the daemon discards what it collected, as today's load does.
+ * `droppedCount` (history updates that could not be mapped) lets the daemon report a partial
+ * backfill. The `processor.history_event`s are unjournaled: a daemon that crashes inside the window
+ * restarts the load rather than resuming from a checkpoint cut inside it.
+ */
+export function endHistory(state, out, ok) {
+    const history = state.history;
+    if (!history)
+        return;
+    if (ok) {
+        while (history.messages.length > 0)
+            flushHistoryMessage(state, history, history.messages[0].nativeSessionId, out);
+    }
+    state.history = null;
+    out.unjournaled({ t: 'processor.history_end', ok, droppedCount: history.droppedCount });
+}