allaboard 0.0.0-stage → 0.5.0

package/dist/agent/claude/translate.js

@@ -0,0 +1,581 @@
+/**
+ * Claude Code's wire records into the daemon's session events.
+ *
+ * A record is one object as the CLI wrote it, which the Agent SDK's `query()` yields unchanged.
+ * Each is read as `unknown` and narrowed field by field. What is read here is what the renderer
+ * and the session need off the SDK's messages, so the core decides from events and never from a
+ * wire record.
+ *
+ * Three things need memory across records, and `Translator` keeps them for one session: which
+ * messages a stream announced, since Claude Code sends a streamed text again whole; which
+ * prompts the daemon sent, since a prompt comes back as a user record; and whether a compaction
+ * is under way, since the status record that ends one says so only to who knows it started.
+ */
+import { strip } from "../../text.js";
+import { isRecord, records } from "../../values.js";
+import { integer, number, string, words } from "./wire.js";
+// Each task_type (measured on Claude Code 2.1.280: `local_bash` for a background command,
+// `local_agent` for a subagent). A type not listed is a task of no kind the daemon names.
+const TASK_KINDS = new Map([
+    ["local_agent", "subagent"],
+    ["local_bash", "command"],
+]);
+// The Python package's `TERMINAL_TASK_STATUSES` (claude-agent-sdk 0.2.165), which the TypeScript
+// package does not export: a task can end with a `task_updated` of one of these and no
+// notification.
+const TERMINAL_TASK_STATUSES = new Set([
+    "completed",
+    "failed",
+    "stopped",
+    "killed",
+]);
+const INTERRUPTED = new Set(["aborted_streaming", "aborted_tools"]);
+const AUTHENTICATION_FAILED = "authentication_failed";
+const SYNTHETIC_MODEL = "<synthetic>";
+// The signs a line of a `structuredPatch` hunk opens with; the backslash is
+// ``, about the line above.
+const SIGNS = new Set(["-", "+", " ", "\\"]);
+// Runs remembered for a notification that may never be folded (one a turn of its own reports).
+const RUNS_KEPT = 200;
+/**
+ * A record's kind: its `type`, with the `subtype` of a `system` record and the event type of a
+ * `stream_event`. Null for what is no record.
+ */
+export function kindOf(record) {
+    if (!isRecord(record))
+        return null;
+    const type = string(record.type);
+    if (type === null)
+        return null;
+    if (type === "system")
+        return `system:${string(record.subtype) ?? ""}`;
+    if (type === "stream_event") {
+        return `stream_event:${isRecord(record.event) ? (string(record.event.type) ?? "") : ""}`;
+    }
+    return type;
+}
+function parentOf(record) {
+    return words(record.parent_tool_use_id);
+}
+// Stream events: the Claude API's streaming events, passed through unparsed.
+function messageStart(memory, record) {
+    const event = isRecord(record.event) ? record.event : {};
+    const messageId = isRecord(event.message) ? string(event.message.id) : null;
+    const parentCallId = parentOf(record);
+    if (parentCallId === null)
+        memory.open = true;
+    if (messageId !== null)
+        memory.streamed.add(messageId);
+    else if (parentCallId === null)
+        memory.unnamed = true;
+    return [{ type: "message_started", parentCallId }];
+}
+function messageStop(memory, record) {
+    const parentCallId = parentOf(record);
+    if (parentCallId === null)
+        memory.open = false;
+    return [{ type: "message_ended", parentCallId }];
+}
+// A subagent's text never reaches a reply, so no text event carries a parent call.
+function contentBlockStart(_memory, record) {
+    const event = isRecord(record.event) ? record.event : {};
+    if (!isRecord(event.content_block) || event.content_block.type !== "text")
+        return [];
+    if (parentOf(record) !== null)
+        return [];
+    return [{ type: "text_started" }];
+}
+function contentBlockDelta(_memory, record) {
+    const event = isRecord(record.event) ? record.event : {};
+    if (!isRecord(event.delta) || event.delta.type !== "text_delta")
+        return [];
+    const text = words(event.delta.text);
+    if (text === null || parentOf(record) !== null)
+        return [];
+    return [{ type: "text_delta", text }];
+}
+// Messages.
+/** The text of a message's text blocks, joined and trimmed. */
+function wordsOf(blocks) {
+    return strip(blocks
+        .filter((block) => block.type === "text")
+        .map((block) => string(block.text) ?? "")
+        .join(""));
+}
+/**
+ * Whether a message's text reached the core through no stream event. At the top level, never
+ * while a streamed message is unfinished (its text may be this one's, sent again whole after a
+ * failed stream, which no recording shows) or once a stream named no id.
+ */
+function unannounced(memory, messageId) {
+    return !memory.streamed.has(messageId) && !memory.open && !memory.unnamed;
+}
+function callStarted(block, parentCallId) {
+    const callId = string(block.id);
+    const toolName = string(block.name);
+    if (callId === null || toolName === null)
+        return [];
+    const input = isRecord(block.input) ? block.input : {};
+    return [{ type: "call_started", callId, toolName, input, parentCallId }];
+}
+/**
+ * The text of a tool result, whatever its form: a string, the text parts of a list a line each,
+ * or the type of a single object (a server tool's result). Null for anything else.
+ */
+function resultText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return records(content)
+            .map((part) => string(part.text) ?? "")
+            .join("\n");
+    }
+    if (isRecord(content))
+        return string(content.type) ?? "";
+    return null;
+}
+function callEnded(block, parentCallId, isError, change, model = null) {
+    const callId = string(block.tool_use_id);
+    if (callId === null)
+        return [];
+    return [
+        {
+            type: "call_ended",
+            callId,
+            isError,
+            output: resultText(block.content),
+            fileChange: change,
+            model,
+            parentCallId,
+        },
+    ];
+}
+function assistant(memory, record) {
+    const message = isRecord(record.message) ? record.message : {};
+    if (!Array.isArray(message.content))
+        return [];
+    const blocks = records(message.content);
+    const parentCallId = parentOf(record);
+    const text = wordsOf(blocks);
+    if (record.error !== undefined && record.error !== null) {
+        // Claude Code wrote this message itself, about a request of its own that failed: its words
+        // name the failure and what to do next, and nothing else in it is a call or an answer. In
+        // the recorded 529 they come in this message with no stream event of their own.
+        const category = String(record.error);
+        const kind = category === AUTHENTICATION_FAILED ? "authentication" : "other";
+        return [{ type: "agent_error", kind, category, text, parentCallId }];
+    }
+    const events = [];
+    // A message Claude Code wrote itself (a local command's answer, recorded: `usage.jsonl`) names
+    // `<synthetic>`, no model the session runs on.
+    const model = words(message.model);
+    if (parentCallId === null && model !== null && model !== SYNTHETIC_MODEL) {
+        memory.mainModel = model;
+    }
+    const messageId = string(message.id);
+    if (text !== "" &&
+        parentCallId === null &&
+        messageId !== null &&
+        unannounced(memory, messageId)) {
+        // Text no stream event announced is a command's own output (`Goal set: …` before a goal's
+        // first inner turn, recorded: `goal.jsonl`). A subagent's is left out: no reply shows it.
+        events.push({ type: "text", text });
+    }
+    for (const block of blocks) {
+        if (block.type === "tool_use" || block.type === "server_tool_use") {
+            events.push(...callStarted(block, parentCallId));
+        }
+        else if (block.type === "tool_result") {
+            events.push(...callEnded(block, parentCallId, block.is_error === true, null));
+        }
+        else if (block.type === "advisor_tool_result") {
+            // The one server tool result read, as the Python SDK's `parse_message` keeps this one
+            // alone (claude-agent-sdk 0.2.165). It carries no error flag.
+            events.push(...callEnded(block, parentCallId, false, null));
+        }
+    }
+    return events;
+}
+function hunkOf(value) {
+    if (!isRecord(value))
+        return null;
+    const oldStart = integer(value.oldStart);
+    const newStart = integer(value.newStart);
+    if (oldStart === null || newStart === null || !Array.isArray(value.lines))
+        return null;
+    const lines = [];
+    for (const line of value.lines) {
+        if (typeof line !== "string" || !SIGNS.has(line.charAt(0)))
+            return null;
+        lines.push(line);
+    }
+    return { oldStart, newStart, lines };
+}
+function hunksOf(patch) {
+    if (!Array.isArray(patch))
+        return null;
+    const hunks = [];
+    for (const entry of patch) {
+        const hunk = hunkOf(entry);
+        if (hunk === null)
+            return null;
+        hunks.push(hunk);
+    }
+    return hunks;
+}
+/**
+ * What an `Edit` or a `Write` did to a file, from `tool_use_result`: a shape the SDK types as
+ * `unknown` and does not document, measured on Claude Code 2.1.283 (2026-09-27,
+ * `test/fixtures/sdk/edit-write.jsonl`). Any other shape gives null, and the core shows the
+ * call's generic line.
+ */
+export function fileChange(result) {
+    if (!isRecord(result))
+        return null;
+    const path = string(result.filePath);
+    if (path === null)
+        return null;
+    const hunks = hunksOf(result.structuredPatch);
+    if (result.type === "create") {
+        const content = string(result.content);
+        if (content === null)
+            return null;
+        return { path, kind: "created", hunks: hunks ?? [], content };
+    }
+    if (hunks === null || hunks.length === 0)
+        return null;
+    return { path, kind: "edited", hunks, content: null };
+}
+/**
+ * The model an Agent call's agent ran on, from `resolvedModel` of the call's `tool_use_result`
+ * (the SDK's `AgentOutput`, SDK 0.3.300; measured on `subagent`, `subagent-foreground` and
+ * `background-forms`), when it is not the model of the main thread's last message, which made
+ * the call: the terminal names a subagent's model only then (captured on Claude Code 2.1.300,
+ * 2026-10-15). Null for any other result and when either model is unknown.
+ */
+function agentModel(memory, result) {
+    if (!isRecord(result) || memory.mainModel === null)
+        return null;
+    const ran = words(result.resolvedModel);
+    return ran === memory.mainModel ? null : ran;
+}
+function user(memory, record) {
+    const promptId = string(record.uuid);
+    if (promptId !== null && memory.sent.has(promptId)) {
+        // The replay of a prompt this session sent (`replay-user-messages`): it shows nothing. A
+        // uuid that names no prompt of ours (a resumed session's, a command's output) is none.
+        return [{ type: "prompt_taken", promptId }];
+    }
+    // A background subagent hands its report back as a message from a peer that names its task
+    // (`SDKMessageOrigin`, kind `peer`, `senderTaskId`), and the agent answers it in a turn of
+    // its own: measured 2026-10-10 on Claude Code 2.1.294 and 2.1.296 with the owner's setting
+    // sources loaded (`test/fixtures/sdk/subagent-handback.jsonl`). A peer with no task of this
+    // session (another session's message) says nothing about a task's report.
+    const origin = isRecord(record.origin) ? record.origin : {};
+    const sender = origin.kind === "peer" ? string(origin.senderTaskId) : null;
+    if (sender !== null)
+        return [{ type: "report_started", taskId: sender }];
+    // A task's notification folded into the running turn is replayed with the run it reports
+    // (recorded 2026-10-15, `task-end-in-turn-folded`); one a turn of its own reports is not
+    // (`task-end-in-turn-unfolded`), nor is a Monitor's line, which names no run.
+    const runId = origin.kind === "task-notification" ? string(origin.runId) : null;
+    const folded = runId === null ? undefined : memory.runs.get(runId);
+    if (runId !== null && folded !== undefined) {
+        memory.runs.delete(runId);
+        return [{ type: "notification_folded", taskId: folded }];
+    }
+    const message = isRecord(record.message) ? record.message : {};
+    if (!Array.isArray(message.content))
+        return [];
+    const blocks = records(message.content);
+    const parentCallId = parentOf(record);
+    // One `tool_use_result` per message: it belongs to a result only when it is alone.
+    const results = blocks.filter((block) => block.type === "tool_result");
+    const change = results.length === 1 ? fileChange(record.tool_use_result) : null;
+    const model = results.length === 1 ? agentModel(memory, record.tool_use_result) : null;
+    const events = [];
+    for (const block of blocks) {
+        if (block.type === "tool_use")
+            events.push(...callStarted(block, parentCallId));
+        else if (block.type === "tool_result") {
+            events.push(...callEnded(block, parentCallId, block.is_error === true, change, model));
+        }
+    }
+    return events;
+}
+// System records.
+function init(_memory, record) {
+    return [
+        {
+            type: "session_started",
+            sessionId: string(record.session_id),
+            agentVersion: string(record.claude_code_version),
+        },
+    ];
+}
+function status(memory, record) {
+    const events = [];
+    // Claude Code reports the permission mode after a change (measured after each
+    // `set_permission_mode`).
+    const mode = string(record.permissionMode);
+    if (mode !== null)
+        events.push({ type: "mode_changed", mode });
+    // A compaction opens with `status` `compacting` and ends 14 to 37 seconds later in the
+    // recordings (2026-10-08, CLI 2.1.292) with a `status` record that carries `compact_result`.
+    // The record that reports a permission mode carries neither, so one that arrives meanwhile
+    // ends nothing.
+    const reported = record.status ?? null;
+    const compacting = reported === "compacting" ||
+        (memory.compacting && reported === null && !Object.hasOwn(record, "compact_result"));
+    if (compacting !== memory.compacting) {
+        memory.compacting = compacting;
+        events.push(compacting ? { type: "compaction_started" } : { type: "compaction_ended" });
+    }
+    return events;
+}
+// `running` comes 0.5 seconds after a prompt and 0.07 seconds after the notification of a
+// background command, about a second before the turn's `message_start`; `idle` right after a
+// turn's result, an interrupted one too, and only after the report of a background subagent,
+// with none in between (recorded 2026-10-14, CLI 2.1.296: `session-state-shell`,
+// `session-state-agent`, `session-state-approval`).
+const AGENT_STATES = new Map([
+    ["running", "working"],
+    ["requires_action", "waiting"],
+    ["idle", "idle"],
+]);
+function sessionState(_memory, record) {
+    const state = AGENT_STATES.get(string(record.state) ?? "");
+    return state === undefined ? [] : [{ type: "state_changed", state }];
+}
+function compactBoundary(_memory, record) {
+    const metadata = isRecord(record.compact_metadata) ? record.compact_metadata : {};
+    return [
+        {
+            type: "compacted",
+            tokensBefore: integer(metadata.pre_tokens),
+            tokensAfter: integer(metadata.post_tokens),
+        },
+    ];
+}
+function taskStarted(memory, record) {
+    const taskId = string(record.task_id);
+    const description = string(record.description);
+    if (taskId === null || description === null)
+        return [];
+    // Absent for a task this process did not register (`SDKTaskStartedMessage.run_id`).
+    const runId = string(record.run_id);
+    if (runId !== null) {
+        memory.runs.set(runId, taskId);
+        for (const kept of memory.runs.keys()) {
+            if (memory.runs.size <= RUNS_KEPT)
+                break;
+            memory.runs.delete(kept);
+        }
+    }
+    const taskType = words(record.task_type);
+    return [
+        {
+            type: "task_started",
+            taskId,
+            kind: TASK_KINDS.get(taskType ?? "") ?? "other",
+            taskType,
+            description,
+            callId: words(record.tool_use_id),
+            agentType: words(record.subagent_type),
+            background: typeof record.is_backgrounded === "boolean" ? record.is_backgrounded : null,
+            parentTaskId: words(record.parent_task_id),
+        },
+    ];
+}
+function taskProgress(_memory, record) {
+    const taskId = string(record.task_id);
+    const description = string(record.description);
+    if (taskId === null || description === null)
+        return [];
+    return [{ type: "task_progress", taskId, description, callId: words(record.tool_use_id) }];
+}
+function taskUpdated(_memory, record) {
+    // Terminal task completion sometimes arrives only as a `task_updated` patch, with no
+    // notification (Python SDK, `parse_message`): the status is the patch's, when it has one.
+    const patch = isRecord(record.patch) ? record.patch : {};
+    const reported = string(patch.status);
+    return [
+        {
+            type: "task_updated",
+            taskId: string(record.task_id) ?? "",
+            status: reported,
+            terminal: reported !== null && TERMINAL_TASK_STATUSES.has(reported),
+        },
+    ];
+}
+function taskNotification(memory, record) {
+    const taskId = string(record.task_id);
+    const reported = string(record.status);
+    const summary = string(record.summary);
+    if (taskId === null || reported === null || summary === null)
+        return [];
+    const usage = isRecord(record.usage) ? record.usage : {};
+    // The replay of a folded notification names the run, which the task's start recorded: a task
+    // whose run this process never saw cannot be named (`SDKTaskStartedMessage.run_id`).
+    const runId = string(record.run_id);
+    return [
+        {
+            type: "task_ended",
+            taskId,
+            status: reported,
+            summary,
+            durationMs: number(usage.duration_ms),
+            callId: words(record.tool_use_id),
+            foldNamed: runId !== null && memory.runs.has(runId),
+        },
+    ];
+}
+// The rest.
+function rateLimit() {
+    return [{ type: "limits_changed" }];
+}
+function tokensOf(usage) {
+    const tokens = {};
+    if (!isRecord(usage))
+        return tokens;
+    for (const [model, counts] of Object.entries(usage)) {
+        if (!isRecord(counts))
+            continue;
+        // A count a model does not report (no cache, say) counts as none.
+        tokens[model] = {
+            input: number(counts.inputTokens) ?? 0,
+            output: number(counts.outputTokens) ?? 0,
+            cacheRead: number(counts.cacheReadInputTokens) ?? 0,
+            cacheCreation: number(counts.cacheCreationInputTokens) ?? 0,
+        };
+    }
+    return tokens;
+}
+function endingOf(record) {
+    const reason = string(record.terminal_reason);
+    if (reason !== null && INTERRUPTED.has(reason))
+        return "interrupted";
+    return record.is_error === true ? "error" : "done";
+}
+// The outputs of `/effort` and `/model`, measured on Claude Code 2.1.280 (2026-09-23) and 2.1.301
+// (2026-10-16); the "with X effort" form is the one ccstatusline reads from transcripts.
+const EFFORT_OUTPUT = /^(?:Set effort level to|Effort level set to) ([a-z0-9-]+)/i;
+const MODEL_OUTPUT = /^Set model to\b(?:.*? with ([a-z0-9-]+) effort)?/is;
+/**
+ * The effort a result's command set. `/effort` and `/model` run no Stop hook (2.1.280) and no
+ * message carries the level, so it is read from the output, and only from the result that names
+ * the command in `local_command`: the text of any other turn is the model's. The result of a
+ * command that changed nothing (a failure, a read) gives no event; a model change that names no
+ * effort gives a null level.
+ */
+export function effortChanged(record) {
+    const command = string(record.local_command);
+    const output = strip(string(record.result) ?? "");
+    if (command === "effort") {
+        const set = EFFORT_OUTPUT.exec(output);
+        return set ? [{ type: "effort_changed", level: set[1].toLowerCase() }] : [];
+    }
+    if (command === "model") {
+        const set = MODEL_OUTPUT.exec(output);
+        return set ? [{ type: "effort_changed", level: set[1]?.toLowerCase() ?? null }] : [];
+    }
+    return [];
+}
+function result(memory, record) {
+    // The stream's memory is a turn's: an interrupted stream has no `message_stop`, and the next
+    // turn must not read as still inside it.
+    memory.streamed.clear();
+    memory.open = false;
+    memory.unnamed = false;
+    memory.compacting = false;
+    // Claude Code started the turn itself (a task notification, say) when the origin names
+    // anything but the owner: none or `human` is the owner's own prompt.
+    const origin = isRecord(record.origin) ? string(record.origin.kind) : null;
+    return [
+        ...effortChanged(record),
+        {
+            type: "turn_ended",
+            sessionId: words(record.session_id),
+            startedBy: origin === null || origin === "human" ? "owner" : "agent",
+            finalText: string(record.result),
+            ending: endingOf(record),
+            // 0 for the turn a task's notification gets once its report was already handed back.
+            steps: typeof record.num_turns === "number" ? record.num_turns : null,
+            tokens: tokensOf(record.modelUsage),
+        },
+    ];
+}
+const HANDLERS = {
+    assistant,
+    rate_limit_event: rateLimit,
+    result,
+    "stream_event:content_block_delta": contentBlockDelta,
+    "stream_event:content_block_start": contentBlockStart,
+    "stream_event:message_start": messageStart,
+    "stream_event:message_stop": messageStop,
+    "system:compact_boundary": compactBoundary,
+    "system:init": init,
+    "system:session_state_changed": sessionState,
+    "system:status": status,
+    "system:task_notification": taskNotification,
+    "system:task_progress": taskProgress,
+    "system:task_started": taskStarted,
+    "system:task_updated": taskUpdated,
+    user,
+};
+/** The kinds of record that can give an event. */
+export const TRANSLATED_KINDS = Object.keys(HANDLERS);
+/**
+ * The recorded kinds the daemon does not read: nothing in the reply or in the session depends
+ * on them. A kind in neither list is new, and `test/agent/claude/translate.test.ts` fails on the
+ * recording that carries it.
+ */
+export const UNREAD_KINDS = [
+    // The queue of a prompt sent while a turn runs; absent from the SDK's union of messages.
+    "command_lifecycle",
+    // `/clear`: the new session id comes with the `init` that follows.
+    "conversation_reset",
+    // The end of a content block and a message's stop reason: neither shows anything.
+    "stream_event:content_block_stop",
+    "stream_event:message_delta",
+    // A request being retried: the message about the failure follows when the retries run out.
+    "system:api_retry",
+    // The list of background tasks: the task records say the same, one task at a time.
+    "system:background_tasks_changed",
+    "system:thinking_tokens",
+    // A subagent's heartbeat while its call runs.
+    "tool_progress",
+];
+function handlerOf(kind) {
+    return kind !== null && Object.hasOwn(HANDLERS, kind)
+        ? HANDLERS[kind]
+        : null;
+}
+/**
+ * One session's translator, as a class: it has two entry points over one memory (`translate`
+ * for what arrives, `promptSent` for what leaves), and the session wrapper holds exactly one
+ * for as long as its process lives.
+ */
+export class Translator {
+    #memory = {
+        sent: new Set(),
+        mainModel: null,
+        streamed: new Set(),
+        open: false,
+        unnamed: false,
+        compacting: false,
+        runs: new Map(),
+    };
+    /** The daemon is sending a prompt under `promptId`: its replay will be `prompt_taken`. */
+    promptSent(promptId) {
+        this.#memory.sent.add(promptId);
+    }
+    /**
+     * The events one record gives, in the order the reply acts on them. A record of a kind the
+     * daemon does not read, or of none it knows, gives none.
+     */
+    translate(record) {
+        const handler = handlerOf(kindOf(record));
+        return handler !== null && isRecord(record) ? handler(this.#memory, record) : [];
+    }
+}