@smthrs/harness 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/ExternalTranscript.js

@@ -0,0 +1,987 @@
+/**
+ * The conversations of agents a person runs beside Smithers, decoded from the agent's own transcript file
+ * into ordered, read-only entries (mvp.md M-38, ui-components.md T-UI-07 S2).
+ *
+ * Every entry carries its origin, agent kind, format version, session, source record identity and
+ * `read_only: true`; who the owner and the agent participant are is the caller's to say, never the
+ * transcript's. Decoding is pure: the caller supplies bytes in any chunking and keeps the returned state,
+ * so a growing file is tailed by decoding only what was appended. An incomplete last line waits for more
+ * bytes. A complete line that is not a record, a transcript without a version, a version this module does
+ * not support, and a record, event, item or content block this module does not name are tagged errors,
+ * never a guess: every skipped kind is listed below by name.
+ *
+ * Codex: `rollout-*.jsonl` files under `$CODEX_HOME/sessions`, profile `codex-rollout/<major.minor>` from
+ * the CLI release in `session_meta`. Items come from `event_msg` `item_completed` rows. `response_item` rows
+ * repeat them for the model and are skipped, except three the items leave out: a message between agents
+ * (`agent_message`), whose encrypted body is one placeholder; a code-mode script that failed
+ * (`custom_tool_call_output`), with the request that started it; and nothing else.
+ *
+ * Claude Code: `<session>.jsonl` files under `~/.claude/projects/<project>`, profile `claude-code/<major.minor>`
+ * from the `version` every conversation record carries. A tool call becomes one entry when its result arrives;
+ * the named bookkeeping rows outside the conversation chain (no `uuid`) are skipped.
+ *
+ * @since 1.0.0-rc.1
+ */
+import * as Fault from "@smthrs/flow/Fault";
+import { Result, Schema } from "effect";
+/**
+ * The agents whose transcripts decode here.
+ *
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export const AgentKind = Schema.Literals(["codex", "claude-code"]);
+/**
+ * One edited file as the agent reported it: its path, the kind of change and the unified diff.
+ *
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export const EditedFile = Schema.Struct({
+    path: Schema.String,
+    change: Schema.Literals(["added", "modified", "deleted", "renamed"]),
+    renamed_to: Schema.optional(Schema.String),
+    diff: Schema.String
+});
+/**
+ * What one entry says. Tool parts keep the agent's correlation id; edits keep the path and the reported
+ * outcome; a body the agent encrypted is a placeholder in its place, never dropped.
+ *
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export const Part = Schema.Union([
+    Schema.Struct({ type: Schema.Literal("prompt"), text: Schema.String }),
+    Schema.Struct({ type: Schema.Literal("goal"), objective: Schema.String, status: Schema.String }),
+    Schema.Struct({ type: Schema.Literal("text"), text: Schema.String, final: Schema.Boolean }),
+    Schema.Struct({ type: Schema.Literal("reasoning"), text: Schema.String }),
+    Schema.Struct({ type: Schema.Literal("encrypted") }),
+    Schema.Struct({
+        type: Schema.Literal("tool"),
+        call_id: Schema.String,
+        command: Schema.String,
+        /** Set when every part of the command only reads, searches or lists: "Read mvp.md". */
+        reads: Schema.Array(Schema.String),
+        status: Schema.Literals(["ok", "error", "running"]),
+        exit_code: Schema.optional(Schema.Number),
+        output: Schema.String,
+        duration_ms: Schema.Number
+    }),
+    Schema.Struct({
+        type: Schema.Literal("edit"),
+        call_id: Schema.String,
+        files: Schema.Array(EditedFile),
+        outcome: Schema.Literals(["applied", "failed"])
+    }),
+    Schema.Struct({ type: Schema.Literal("search"), call_id: Schema.String, query: Schema.String }),
+    Schema.Struct({
+        type: Schema.Literal("helper"),
+        call_id: Schema.String,
+        agent: Schema.String,
+        activity: Schema.String
+    }),
+    Schema.Struct({ type: Schema.Literal("compaction") }),
+    Schema.Struct({ type: Schema.Literal("error"), message: Schema.String })
+]);
+/**
+ * One read-only entry of an external conversation, in source order.
+ *
+ * @category models
+ * @since 1.0.0-rc.1
+ */
+export const Entry = Schema.Struct({
+    origin: Schema.Literal("external"),
+    agent_kind: AgentKind,
+    format_version: Schema.String,
+    session_id: Schema.String,
+    /**
+     * The record this entry came from: `<session>:<line>`. A record that yields several entries numbers the later
+     * ones `<session>:<line>#<n>`.
+     */
+    source_id: Schema.String,
+    read_only: Schema.Literal(true),
+    seq: Schema.Number,
+    /** Milliseconds since the epoch, from the record. */
+    at: Schema.Number,
+    turn_id: Schema.optional(Schema.String),
+    /** `user` entries are the owner's; `assistant` entries are the agent's. */
+    role: Schema.Literals(["user", "assistant"]),
+    part: Part
+});
+/**
+ * Why a transcript did not decode.
+ *
+ * @category errors
+ * @since 1.0.0-rc.1
+ */
+export const ExternalTranscriptErrorCode = Schema.Literals([
+    "missing_version",
+    "unsupported_version",
+    "unsupported_record",
+    "malformed_record"
+]);
+/**
+ * A transcript this module refuses to read, with the line it stopped at.
+ *
+ * @category errors
+ * @since 1.0.0-rc.1
+ */
+export class ExternalTranscriptError extends Schema.TaggedError()("harness/ExternalTranscriptError", {
+    code: ExternalTranscriptErrorCode,
+    message: Schema.String,
+    line: Schema.Number
+}) {
+}
+Fault.register("harness/ExternalTranscriptError", {
+    // The agent wrote a transcript this release cannot read: a format change outside Smithers.
+    missing_version: "dependency",
+    unsupported_version: "dependency",
+    unsupported_record: "dependency",
+    malformed_record: "dependency"
+});
+/**
+ * The Codex CLI releases whose rollout shape this module reads, by `major.minor`.
+ *
+ * @category constants
+ * @since 1.0.0-rc.1
+ */
+export const codexReleases = ["0.159", "0.160"];
+/**
+ * The state before the first byte.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.1
+ */
+export const codexStart = { pending: "", line: 0, seq: 0 };
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+const text = (value) => typeof value === "string" ? value : "";
+const list = (value) => Array.isArray(value) ? value : [];
+const basename = (path) => path.split("/").filter(Boolean).at(-1) ?? path;
+/** One complete line as a JSON record, or `undefined` when it is not one. */
+const parseRow = (raw) => {
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const helperName = (path) => basename(text(path)) || "helper";
+const reads = (parsed) => {
+    const parts = list(parsed).map(record);
+    if (parts.length === 0 || parts.some((part) => !["read", "search", "list_files"].includes(text(part["type"])))) {
+        return [];
+    }
+    return parts.map((part) => part["type"] === "read"
+        ? `Read ${text(part["name"]) || basename(text(part["path"]))}`
+        : part["type"] === "search"
+            ? `Searched ${JSON.stringify(text(part["query"]))}${part["path"] ? ` in ${basename(text(part["path"]))}` : ""}`
+            : `Listed ${basename(text(part["path"])) || "files"}`);
+};
+/** Lines of an edit string, without the newline that ends the last one. */
+const linesOf = (value) => value === "" ? [] : value.replace(/\n$/, "").split("\n");
+/** An added or deleted file reports its content, not a diff: one hunk of the whole file, all `+` or all `-`. */
+const wholeFile = (content, op) => {
+    const lines = linesOf(content);
+    if (lines.length === 0)
+        return "";
+    return `@@ ${op === "+" ? `-0,0 +1,${lines.length}` : `-1,${lines.length} +0,0`} @@\n${lines.map((line) => `${op}${line}`).join("\n")}\n`;
+};
+const changeOf = (change) => typeof change["move_path"] === "string"
+    ? "renamed"
+    : change["type"] === "add"
+        ? "added"
+        : change["type"] === "delete"
+            ? "deleted"
+            : "modified";
+/**
+ * The Codex record, event and item kinds this module names. Each list is closed: a kind outside it is a tagged
+ * `unsupported_record`, so a new kind stops the import where a person can see it instead of vanishing.
+ */
+const codexSkippedRows = [
+    "turn_context",
+    "world_state",
+    "token_usage_record",
+    "compacted",
+    "inter_agent_communication_metadata"
+];
+const codexResponseItems = [
+    "message",
+    "reasoning",
+    "custom_tool_call",
+    "custom_tool_call_output",
+    "function_call",
+    "function_call_output",
+    "agent_message"
+];
+const codexSkippedEvents = ["task_started", "token_count", "thread_settings_applied"];
+const codexItems = [
+    "UserMessage",
+    "AgentMessage",
+    "Reasoning",
+    "CommandExecution",
+    "FileChange",
+    "ContextCompaction",
+    "SubAgentActivity",
+    "CollabAgentToolCall",
+    "Extension",
+    "McpToolCall",
+    "FunctionCallOutput",
+    "ImageView"
+];
+/** The text of a list of `{type, text}` parts, as Codex and MCP servers write tool output. */
+const partsText = (value) => typeof value === "string" ? value : list(value).map((each) => text(record(each)["text"])).filter(Boolean).join("\n");
+/**
+ * One completed Codex item as the part it reports, or `undefined` for items with nothing to show. `took` is the
+ * wall time Codex recorded around the item (`completed_at_ms - started_at_ms`). The caller has checked the item's
+ * type against `codexItems`.
+ */
+const itemPart = (item, took) => {
+    switch (item["type"]) {
+        case "UserMessage":
+            return {
+                role: "user",
+                part: { type: "prompt", text: list(item["content"]).map((each) => text(record(each)["text"])).join("\n") }
+            };
+        case "AgentMessage": {
+            const content = list(item["content"]).map(record);
+            const said = content.map((each) => text(each["text"])).filter(Boolean).join("\n");
+            if (content.some((each) => each["type"] === "encrypted_content")) {
+                return { role: "assistant", part: { type: "encrypted" } };
+            }
+            return { role: "assistant", part: { type: "text", text: said, final: item["phase"] === "final_answer" } };
+        }
+        case "Reasoning": {
+            // Codex keeps reasoning encrypted; only a summary it chose to write is readable.
+            const summary = list(item["summary_text"]).map(text).filter(Boolean).join("\n");
+            return summary === ""
+                ? (item["encrypted_content"] ? { role: "assistant", part: { type: "encrypted" } } : undefined)
+                : { role: "assistant", part: { type: "reasoning", text: summary } };
+        }
+        case "CommandExecution": {
+            const exit = typeof item["exit_code"] === "number" ? item["exit_code"] : undefined;
+            // Codex reports in_progress, completed, failed and declined; only a clean completion is ok.
+            const status = item["status"] === "in_progress"
+                ? "running"
+                : item["status"] === "completed" && (exit ?? 0) === 0
+                    ? "ok"
+                    : "error";
+            return {
+                role: "assistant",
+                part: {
+                    type: "tool",
+                    call_id: text(item["id"]),
+                    command: list(item["command"]).map(text).at(-1) ?? "",
+                    reads: reads(item["parsed_cmd"]),
+                    status,
+                    ...(exit === undefined ? {} : { exit_code: exit }),
+                    output: text(item["aggregated_output"]) || text(item["formatted_output"]),
+                    duration_ms: took
+                }
+            };
+        }
+        case "FileChange":
+            return {
+                role: "assistant",
+                part: {
+                    type: "edit",
+                    call_id: text(item["id"]),
+                    outcome: item["status"] === "completed" ? "applied" : "failed",
+                    files: Object.entries(record(item["changes"])).map(([path, value]) => {
+                        const change = record(value);
+                        return {
+                            path,
+                            change: changeOf(change),
+                            ...(typeof change["move_path"] === "string" ? { renamed_to: change["move_path"] } : {}),
+                            diff: text(change["unified_diff"]) ||
+                                wholeFile(text(change["content"]), change["type"] === "delete" ? "-" : "+")
+                        };
+                    })
+                }
+            };
+        case "ContextCompaction":
+            return { role: "assistant", part: { type: "compaction" } };
+        case "SubAgentActivity":
+            return {
+                role: "assistant",
+                part: {
+                    type: "helper",
+                    call_id: text(item["id"]),
+                    agent: helperName(item["agent_path"]),
+                    activity: text(item["kind"])
+                }
+            };
+        case "CollabAgentToolCall": {
+            const agents = list(item["receiver_agents"]).map((each) => helperName(record(each)["agent_path"] ?? each));
+            return {
+                role: "assistant",
+                part: {
+                    type: "helper",
+                    call_id: text(item["id"]),
+                    agent: agents.join(", ") || "helpers",
+                    activity: text(item["tool"])
+                }
+            };
+        }
+        case "Extension": {
+            const action = record(item["action"]);
+            const query = text(item["query"]) || text(action["query"]) || text(action["pattern"]) || text(action["url"]);
+            return { role: "assistant", part: { type: "search", call_id: text(item["id"]), query } };
+        }
+        case "McpToolCall": {
+            // A tool another server ran for the agent: its request and the result the server reported.
+            const result = record(item["result"]);
+            const args = record(item["arguments"]);
+            const name = [text(item["server"]), text(item["tool"])].filter(Boolean).join(".");
+            const failed = item["status"] !== "completed" || result["isError"] === true;
+            return {
+                role: "assistant",
+                part: {
+                    type: "tool",
+                    call_id: text(item["id"]),
+                    command: Object.keys(args).length === 0 ? name : `${name} ${JSON.stringify(args)}`,
+                    reads: [],
+                    status: item["status"] === "in_progress" ? "running" : failed ? "error" : "ok",
+                    output: partsText(result["content"]) || text(record(item["error"])["message"]),
+                    duration_ms: took
+                }
+            };
+        }
+        case "FunctionCallOutput":
+            return {
+                role: "assistant",
+                part: {
+                    type: "tool",
+                    call_id: text(item["id"]),
+                    command: [text(item["namespace"]), text(item["name"])].filter(Boolean).join("."),
+                    reads: [],
+                    status: "ok",
+                    output: partsText(item["output"]),
+                    duration_ms: took
+                }
+            };
+        default:
+            // ImageView, the one kind of `codexItems` left: an image the agent looked at.
+            return {
+                role: "assistant",
+                part: {
+                    type: "tool",
+                    call_id: text(item["id"]),
+                    command: `view_image ${text(item["path"])}`,
+                    reads: [`Read ${basename(text(item["path"]))}`],
+                    status: "ok",
+                    output: "",
+                    duration_ms: took
+                }
+            };
+    }
+};
+/**
+ * The first line of a code-mode output says how the script ended. A script that finished, or one still running in
+ * a cell, repeats what completed items already report; any other ending is a failure only this row records.
+ */
+const scriptFailed = (output) => !/^Script (?:completed|running)\b/.test(output);
+/** The file a failed `apply_patch` names, when the report is that failure. */
+const failedPatchPath = (output) => /apply_patch verification failed: Failed to find expected lines in ([^\n]+):\n/.exec(output)?.[1];
+/** The adapter profile `<profile>/<major.minor>` for a supported release, or `undefined`. */
+const profileOf = (profile, releases, release) => {
+    const minor = /^(\d+\.\d+)\./.exec(release)?.[1];
+    return minor !== undefined && releases.includes(minor) ? `${profile}/${minor}` : undefined;
+};
+/**
+ * Decode the next chunk of a Codex rollout. Pass `codexStart` with the first chunk and the returned state
+ * with each following one; any partition of the same bytes yields the same entries.
+ *
+ * @category decoding
+ * @since 1.0.0-rc.1
+ */
+export const decodeCodex = (state, chunk) => {
+    const lines = (state.pending + chunk).split("\n");
+    const pending = lines.pop();
+    let { line, seq, session, goal } = state;
+    const calls = new Map(Object.entries(state.calls ?? {}));
+    const entries = [];
+    const fail = (code, message) => Result.fail(new ExternalTranscriptError({ code, message, line }));
+    /** A kind outside the named lists; a kind that is not even a string is a record of another shape. */
+    const unread = (what, type) => typeof type === "string" && type !== ""
+        ? fail("unsupported_record", `Codex wrote ${what} this release does not read: ${type}`)
+        : fail("malformed_record", `Codex rollout line ${line} names no ${what.replace(/^an? /, "")} type.`);
+    for (const raw of lines) {
+        line++;
+        if (raw.trim() === "")
+            continue;
+        const row = parseRow(raw);
+        if (row === undefined)
+            return fail("malformed_record", `Codex rollout line ${line} is not a JSON record.`);
+        const payload = record(row["payload"]);
+        if (row["type"] === "session_meta") {
+            const release = text(payload["cli_version"]);
+            const format_version = profileOf("codex-rollout", codexReleases, release);
+            if (format_version === undefined) {
+                return fail("unsupported_version", `Codex ${release || "(no release)"} wrote this rollout; supported: ${codexReleases.join(", ")}.`);
+            }
+            session = { id: text(payload["id"]) || text(payload["session_id"]), format_version, cwd: text(payload["cwd"]) };
+            continue;
+        }
+        if (session === undefined) {
+            return fail("missing_version", `Codex rollout line ${line} comes before its session record.`);
+        }
+        const found = [];
+        if (row["type"] === "response_item") {
+            if (!codexResponseItems.includes(text(payload["type"])))
+                return unread("a response item", payload["type"]);
+            switch (payload["type"]) {
+                case "custom_tool_call": {
+                    const id = payload["call_id"], name = payload["name"], input = payload["input"];
+                    if (typeof id !== "string" || id === "" || typeof name !== "string" || typeof input !== "string") {
+                        return fail("malformed_record", `Codex tool request on line ${line} names no call, tool or input.`);
+                    }
+                    calls.set(id, { name, input });
+                    break;
+                }
+                case "custom_tool_call_output": {
+                    const id = text(payload["call_id"]);
+                    const call = calls.get(id);
+                    calls.delete(id);
+                    const output = partsText(payload["output"]);
+                    // A script that finished repeats its completed items. One that failed has no item: keep its report with
+                    // the request that started it, so a failed edit is never silently missing.
+                    if (!scriptFailed(output))
+                        break;
+                    found.push({
+                        role: "assistant",
+                        part: {
+                            type: "tool",
+                            call_id: id,
+                            command: call?.input ?? "",
+                            reads: [],
+                            status: "error",
+                            output,
+                            duration_ms: 0
+                        }
+                    });
+                    const path = failedPatchPath(output);
+                    if (path !== undefined) {
+                        // The report names the file and no change: the diff is empty because nothing was observed to change.
+                        found.push({
+                            role: "assistant",
+                            part: { type: "edit", call_id: id, files: [{ path, change: "modified", diff: "" }], outcome: "failed" }
+                        });
+                    }
+                    break;
+                }
+                case "agent_message": {
+                    // A message between this agent and one it works with. Codex encrypts the body; the header beside it
+                    // names agents, and a name in a transcript confers nothing.
+                    const content = payload["content"];
+                    if (!Array.isArray(content)) {
+                        return fail("malformed_record", `Codex agent message on line ${line} has no content list.`);
+                    }
+                    let encrypted = false;
+                    const said = [];
+                    for (const each of content) {
+                        const block = record(each);
+                        if (block["type"] === "encrypted_content") {
+                            if (typeof block["encrypted_content"] !== "string" || block["encrypted_content"] === "") {
+                                return fail("malformed_record", `Codex encrypted body on line ${line} is empty.`);
+                            }
+                            encrypted = true;
+                        }
+                        else if (block["type"] === "input_text" || block["type"] === "output_text") {
+                            if (typeof block["text"] !== "string") {
+                                return fail("malformed_record", `Codex agent message on line ${line} has a text part without text.`);
+                            }
+                            said.push(block["text"]);
+                        }
+                        else {
+                            return unread("a message part", block["type"]);
+                        }
+                    }
+                    const turn = text(record(payload["internal_chat_message_metadata_passthrough"])["turn_id"]);
+                    // One placeholder stands for the whole body, header included: nothing readable is shown beside it.
+                    if (encrypted)
+                        found.push({ role: "assistant", part: { type: "encrypted" }, turn });
+                    else if (said.join("\n") !== "") {
+                        found.push({ role: "assistant", part: { type: "text", text: said.join("\n"), final: false }, turn });
+                    }
+                    break;
+                }
+                // message, reasoning, function_call, function_call_output: the model-facing copy of completed items.
+            }
+        }
+        else if (row["type"] === "event_msg") {
+            switch (payload["type"]) {
+                case "item_completed": {
+                    const started = payload["started_at_ms"], completed = payload["completed_at_ms"];
+                    const took = typeof started === "number" && typeof completed === "number" ? completed - started : 0;
+                    const item = record(payload["item"]);
+                    if (!codexItems.includes(text(item["type"])))
+                        return unread("an item", item["type"]);
+                    if (item["type"] === "UserMessage" || item["type"] === "AgentMessage") {
+                        const content = item["content"];
+                        if (!Array.isArray(content)) {
+                            return fail("malformed_record", `Codex message on line ${line} has no content list.`);
+                        }
+                        // Ciphertext stands for the whole body, so the parts beside it are not read.
+                        if (!content.some((each) => record(each)["type"] === "encrypted_content")) {
+                            for (const each of content) {
+                                const block = record(each);
+                                if (block["type"] !== (item["type"] === "UserMessage" ? "text" : "Text")) {
+                                    return unread("a message part", block["type"]);
+                                }
+                                if (typeof block["text"] !== "string") {
+                                    return fail("malformed_record", `Codex message on line ${line} has a text part without text.`);
+                                }
+                            }
+                        }
+                    }
+                    const part = itemPart(item, Number.isFinite(took) && took > 0 ? took : 0);
+                    if (part !== undefined)
+                        found.push({ ...part, turn: text(payload["turn_id"]) });
+                    break;
+                }
+                case "thread_goal_updated": {
+                    const update = record(payload["goal"]);
+                    const key = `${text(update["status"])}:${text(update["objective"])}`;
+                    // Codex repeats a goal on every usage update; only a new objective or status is news.
+                    if (key !== goal) {
+                        found.push({
+                            role: "user",
+                            part: { type: "goal", objective: text(update["objective"]), status: text(update["status"]) }
+                        });
+                    }
+                    goal = key;
+                    break;
+                }
+                case "task_complete": {
+                    // A turn's end repeats its last message, and carries the failure when the turn ended in one: a usage
+                    // limit, a model at capacity, a refused request.
+                    if (payload["error"] === undefined || payload["error"] === null)
+                        break;
+                    const message = text(record(payload["error"])["message"]);
+                    if (message === "")
+                        return fail("malformed_record", `Codex failure on line ${line} gives no message.`);
+                    found.push({ role: "assistant", part: { type: "error", message }, turn: text(payload["turn_id"]) });
+                    break;
+                }
+                case "error":
+                case "turn_aborted": {
+                    // What Codex said went wrong, or why the turn stopped ("interrupted").
+                    const message = text(payload["message"]) || text(payload["reason"]);
+                    if (message === "") {
+                        return fail("malformed_record", `Codex failure on line ${line} gives no message or reason.`);
+                    }
+                    found.push({ role: "assistant", part: { type: "error", message }, turn: text(payload["turn_id"]) });
+                    break;
+                }
+                default:
+                    if (!codexSkippedEvents.includes(text(payload["type"])))
+                        return unread("an event", payload["type"]);
+            }
+        }
+        else if (!codexSkippedRows.includes(text(row["type"]))) {
+            return unread("a record", row["type"]);
+        }
+        const at = Date.parse(text(row["timestamp"])) || 0;
+        const sessionId = session.id, format_version = session.format_version;
+        found.forEach(({ part, role, turn }, index) => {
+            entries.push({
+                origin: "external",
+                agent_kind: "codex",
+                format_version,
+                session_id: sessionId,
+                source_id: index === 0 ? `${sessionId}:${line}` : `${sessionId}:${line}#${index}`,
+                read_only: true,
+                seq: seq++,
+                at,
+                ...(turn ? { turn_id: turn } : {}),
+                role,
+                part
+            });
+        });
+    }
+    return Result.succeed({
+        state: { pending, line, seq, session, goal, ...(calls.size === 0 ? {} : { calls: Object.fromEntries(calls) }) },
+        entries
+    });
+};
+/**
+ * The Claude Code release lines whose transcript shape this module reads, by `major.minor`.
+ *
+ * @category constants
+ * @since 1.0.0-rc.1
+ */
+export const claudeReleases = ["2.1"];
+/**
+ * The state before the first byte.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.1
+ */
+export const claudeStart = { pending: "", line: 0, seq: 0, calls: {} };
+/** Content as blocks: Claude Code writes a plain prompt as a string and everything else as a block list. */
+const blocksOf = (content) => typeof content === "string" ? [{ type: "text", text: content }] : list(content).map(record);
+const textOf = (blocks) => blocks.filter((block) => block["type"] === "text").map((block) => text(block["text"])).join("\n");
+/** A user turn is the owner's when Claude Code classified it human or did not classify it. */
+const byOwner = (origin) => origin === undefined || origin === null || record(origin)["kind"] === "human";
+/**
+ * A requested replacement as one hunk. Claude Code reports no position for a replacement it did not apply, so the
+ * hunk starts at line 1.
+ */
+const replacement = (before, after) => {
+    const removed = linesOf(before), added = linesOf(after);
+    if (removed.length + added.length === 0)
+        return "";
+    return `@@ -1,${removed.length} +1,${added.length} @@\n${[...removed.map((line) => `-${line}`), ...added.map((line) => `+${line}`)].join("\n")}\n`;
+};
+const count = (value) => typeof value === "number" ? value : 0;
+/** The hunks Claude Code reported for an applied edit (`toolUseResult.structuredPatch`). */
+const reportedPatch = (patch) => list(patch).map(record).map((hunk) => `@@ -${count(hunk["oldStart"])},${count(hunk["oldLines"])} +${count(hunk["newStart"])},${count(hunk["newLines"])} @@\n${list(hunk["lines"]).map(text).join("\n")}\n`).join("");
+/** The edit the agent asked for, from the tool input, when Claude Code reported no hunks. */
+const requestedPatch = (name, input) => {
+    switch (name) {
+        case "Write":
+            return wholeFile(text(input["content"]), "+");
+        case "NotebookEdit":
+            return wholeFile(text(input["new_source"]), "+");
+        case "MultiEdit":
+            return list(input["edits"]).map(record).map((edit) => replacement(text(edit["old_string"]), text(edit["new_string"]))).join("");
+        default:
+            return replacement(text(input["old_string"]), text(input["new_string"]));
+    }
+};
+/** The reads label of a tool that only reads, searches or lists, or none. */
+const claudeReads = (name, input) => {
+    const path = text(input["path"]);
+    switch (name) {
+        case "Read":
+            return [`Read ${basename(text(input["file_path"]))}`];
+        case "Grep":
+        case "Glob":
+            return [`Searched ${JSON.stringify(text(input["pattern"]))}${path ? ` in ${basename(path)}` : ""}`];
+        case "LS":
+            return [`Listed ${basename(path) || "files"}`];
+        default:
+            return [];
+    }
+};
+/** One finished tool call: its `tool_use` (when this transcript holds it) and the `tool_result` that ended it. */
+const claudeToolPart = (id, call, result) => {
+    const name = call?.name ?? "";
+    const input = record(call?.input);
+    switch (name) {
+        case "Edit":
+        case "Write":
+        case "MultiEdit":
+        case "NotebookEdit":
+            return {
+                type: "edit",
+                call_id: id,
+                files: [{
+                        path: text(input["file_path"]) || text(input["notebook_path"]),
+                        change: name === "Write" && result.report["type"] === "create" ? "added" : "modified",
+                        diff: reportedPatch(result.report["structuredPatch"]) || requestedPatch(name, input)
+                    }],
+                outcome: result.failed ? "failed" : "applied"
+            };
+        case "WebSearch":
+            return { type: "search", call_id: id, query: text(input["query"]) };
+        case "WebFetch":
+            return { type: "search", call_id: id, query: text(input["url"]) };
+        case "Task":
+        case "Agent":
+            return {
+                type: "helper",
+                call_id: id,
+                agent: text(input["subagent_type"]) || "general-purpose",
+                activity: text(input["description"])
+            };
+    }
+    const exit = result.failed ? /^Exit code (\d+)/.exec(result.output)?.[1] : undefined;
+    return {
+        type: "tool",
+        call_id: id,
+        command: name === "Bash"
+            ? text(input["command"])
+            : Object.keys(input).length === 0
+                ? name
+                : `${name} ${JSON.stringify(input)}`,
+        reads: claudeReads(name, input),
+        status: result.failed ? "error" : "ok",
+        ...(exit === undefined ? {} : { exit_code: Number(exit) }),
+        output: result.output,
+        duration_ms: result.took
+    };
+};
+/**
+ * The Claude Code record, status, attachment and block kinds this module names. Each list is closed: a kind
+ * outside it is a tagged `unsupported_record`, so a new kind stops the import where a person can see it.
+ */
+/** Rows outside the conversation chain: session bookkeeping that names no speaker and says nothing. */
+const claudeSkippedRows = [
+    "mode",
+    "permission-mode",
+    "atis-latch",
+    "last-prompt",
+    "ai-title",
+    "custom-title",
+    "agent-name",
+    "queue-operation",
+    "file-history-snapshot",
+    "file-history-delta",
+    "cost-state",
+    "pr-link",
+    "bridge-session"
+];
+/** Status lines: turn timing, hook summaries, retries, model fallback and scheduled-task notices. */
+const claudeSkippedStatus = [
+    "turn_duration",
+    "informational",
+    "stop_hook_summary",
+    "away_summary",
+    "api_error",
+    "local_command",
+    "scheduled_task_fire",
+    "agents_killed",
+    "model_refusal_fallback"
+];
+/** Context Claude Code attaches for the model; `queued_command` alone can carry the owner's words. */
+const claudeSkippedAttachments = [
+    "agent_listing_delta",
+    "auto_mode",
+    "bash_output_audience_note",
+    "batching_reminder_sent",
+    "budget_usd",
+    "command_permissions",
+    "compact_file_reference",
+    "credential_org",
+    "date",
+    "deferred_tools_delta",
+    "deferred_tools_record",
+    "diagnostics",
+    "directory",
+    "edited_text_file",
+    "environment",
+    "file",
+    "goal_status",
+    "hook_additional_context",
+    "hook_cancelled",
+    "hook_non_blocking_error",
+    "hook_system_message",
+    "instructions",
+    "invoked_skills",
+    "max_turns_reached",
+    "mcp_instructions_delta",
+    "model",
+    "nested_memory",
+    "plan_mode",
+    "prompt_snapshot",
+    "read_truncation_notice",
+    "remote_session_change",
+    "sandbox_instructions",
+    "session_context",
+    "silent_turn_reminder",
+    "skill_listing",
+    "skill_mention",
+    "task_reminder",
+    "task_status",
+    "thinking_drop",
+    "thinking_stripped",
+    "total_tokens_reminder",
+    "ultra_effort_enter",
+    "ultra_effort_exit",
+    "workflow_keyword_request"
+];
+/** The owner's words in a user record, or `undefined` for Claude Code's own output of a local command. */
+const ownerText = (said) => {
+    if (/^\[Request interrupted by user[^\]]*\]$/.test(said))
+        return { type: "error", message: said };
+    if (/^<(?:local-command-std(?:out|err)|bash-std(?:out|err))>/.test(said))
+        return undefined;
+    // Claude Code writes a slash command as tags that open the record; a prompt that mentions them stays as typed.
+    const command = /^<command-(?:name|message)>/.test(said)
+        ? /<command-name>([^<]*)<\/command-name>/.exec(said)?.[1]
+        : undefined;
+    if (command !== undefined) {
+        const args = /<command-args>([\s\S]*?)<\/command-args>/.exec(said)?.[1]?.trim();
+        return { type: "prompt", text: args ? `${command} ${args}` : command };
+    }
+    const shell = /^<bash-input>([\s\S]*)<\/bash-input>$/.exec(said)?.[1];
+    return { type: "prompt", text: shell === undefined ? said : `!${shell.trim()}` };
+};
+/**
+ * Decode the next chunk of a Claude Code session transcript. Pass `claudeStart` with the first chunk and the
+ * returned state with each following one; any partition of the same bytes yields the same entries.
+ *
+ * Entries follow the order of the records that complete them. A tool call is held in `state.calls` from its
+ * `tool_use` record until the `tool_result` with the same id arrives, and becomes one entry at the result's line;
+ * a call whose result never arrives emits nothing.
+ *
+ * @category decoding
+ * @since 1.0.0-rc.1
+ */
+export const decodeClaude = (state, chunk) => {
+    const lines = (state.pending + chunk).split("\n");
+    const pending = lines.pop();
+    let { line, seq, session, turn } = state;
+    const calls = new Map(Object.entries(state.calls));
+    const entries = [];
+    const fail = (code, message) => Result.fail(new ExternalTranscriptError({ code, message, line }));
+    /** A kind outside the named lists; a kind that is not even a string is a record of another shape. */
+    const unread = (what, type) => typeof type === "string" && type !== ""
+        ? fail("unsupported_record", `Claude Code wrote ${what} this release does not read: ${type}`)
+        : fail("malformed_record", `Claude Code transcript line ${line} names no ${what.replace(/^an? /, "")} type.`);
+    for (const raw of lines) {
+        line++;
+        if (raw.trim() === "")
+            continue;
+        const row = parseRow(raw);
+        if (row === undefined)
+            return fail("malformed_record", `Claude Code transcript line ${line} is not a JSON record.`);
+        // Bookkeeping rows say nothing in the conversation, whether or not a release gives them a uuid.
+        if (claudeSkippedRows.includes(text(row["type"])))
+            continue;
+        if (!["user", "assistant", "system", "attachment"].includes(text(row["type"]))) {
+            return unread("a record", row["type"]);
+        }
+        // Conversation records chain by uuid: one without it is not the shape this profile reads.
+        if (typeof row["uuid"] !== "string") {
+            return fail("malformed_record", `Claude Code transcript line ${line} is a conversation record without a uuid.`);
+        }
+        const release = text(row["version"]);
+        if (release === "")
+            return fail("missing_version", `Claude Code transcript line ${line} names no release.`);
+        const format_version = profileOf("claude-code", claudeReleases, release);
+        if (format_version === undefined) {
+            return fail("unsupported_version", `Claude Code ${release} wrote this transcript; supported: ${claudeReleases.join(", ")}.`);
+        }
+        session ??= text(row["sessionId"]) || undefined;
+        if (session === undefined) {
+            return fail("malformed_record", `Claude Code transcript line ${line} names no session.`);
+        }
+        const sessionId = session;
+        // A subagent's records belong to its own transcript; the main one shows the call as a helper.
+        if (row["isSidechain"] === true)
+            continue;
+        const at = Date.parse(text(row["timestamp"])) || 0;
+        if (row["type"] === "user" && typeof row["promptId"] === "string" && row["promptId"] !== "") {
+            turn = row["promptId"];
+        }
+        const found = [];
+        const said = (part) => found.push({ role: "assistant", part });
+        const message = record(row["message"]);
+        if ((row["type"] === "user" || row["type"] === "assistant") && typeof message["content"] !== "string" &&
+            !Array.isArray(message["content"])) {
+            return fail("malformed_record", `Claude Code transcript line ${line} has no message content.`);
+        }
+        switch (row["type"]) {
+            case "user": {
+                const blocks = blocksOf(message["content"]);
+                for (const block of blocks) {
+                    if (block["type"] === "tool_result") {
+                        const callId = text(block["tool_use_id"]);
+                        const call = calls.get(callId);
+                        calls.delete(callId);
+                        const content = block["content"];
+                        said(claudeToolPart(callId, call, {
+                            failed: block["is_error"] === true,
+                            output: typeof content === "string" ? content : textOf(list(content).map(record)),
+                            report: record(row["toolUseResult"]),
+                            took: call !== undefined && call.at > 0 && at > call.at ? at - call.at : 0
+                        }));
+                    }
+                    else if (block["type"] !== "text" && block["type"] !== "image") {
+                        return unread("a content block", block["type"]);
+                    }
+                }
+                const words = textOf(blocks);
+                // Skill bodies, caveats and summaries Claude Code injects are not the owner's; nor are task notifications
+                // or messages from other sessions.
+                if (words === "" || row["isMeta"] === true || row["isCompactSummary"] === true || !byOwner(row["origin"]))
+                    break;
+                const part = ownerText(words);
+                if (part !== undefined)
+                    found.push({ role: part.type === "prompt" ? "user" : "assistant", part });
+                break;
+            }
+            case "assistant": {
+                const blocks = blocksOf(message["content"]);
+                if (row["isApiErrorMessage"] === true) {
+                    said({ type: "error", message: textOf(blocks) || text(row["error"]) });
+                    break;
+                }
+                for (const block of blocks) {
+                    switch (block["type"]) {
+                        case "text":
+                            if (text(block["text"]) !== "") {
+                                said({ type: "text", text: text(block["text"]), final: message["stop_reason"] === "end_turn" });
+                            }
+                            break;
+                        case "thinking":
+                            // Claude Code keeps only the signature of most thinking; an empty body has nothing to show.
+                            if (text(block["thinking"]) !== "")
+                                said({ type: "reasoning", text: text(block["thinking"]) });
+                            break;
+                        case "redacted_thinking":
+                            break;
+                        case "fallback":
+                            // A notice that Claude Code answered with another model: a status line, not something it said.
+                            break;
+                        case "tool_use":
+                            if (typeof block["id"] !== "string" || block["id"] === "") {
+                                return fail("malformed_record", `Claude Code tool request on line ${line} names no call.`);
+                            }
+                            calls.set(block["id"], { name: text(block["name"]), input: block["input"] ?? {}, at });
+                            break;
+                        default:
+                            return unread("a content block", block["type"]);
+                    }
+                }
+                break;
+            }
+            case "system":
+                if (row["subtype"] === "compact_boundary")
+                    said({ type: "compaction" });
+                else if (!claudeSkippedStatus.includes(text(row["subtype"])))
+                    return unread("a status record", row["subtype"]);
+                break;
+            case "attachment": {
+                // Context Claude Code attaches for the model, except a prompt the owner queued while the agent worked.
+                const attachment = record(row["attachment"]);
+                if (attachment["type"] !== "queued_command") {
+                    if (!claudeSkippedAttachments.includes(text(attachment["type"]))) {
+                        return unread("an attachment", attachment["type"]);
+                    }
+                    break;
+                }
+                if (attachment["commandMode"] === "prompt" && attachment["isMeta"] !== true && byOwner(attachment["origin"])) {
+                    const words = textOf(blocksOf(attachment["prompt"]));
+                    if (words !== "")
+                        found.push({ role: "user", part: { type: "prompt", text: words } });
+                }
+                break;
+            }
+        }
+        found.forEach(({ part, role }, index) => {
+            entries.push({
+                origin: "external",
+                agent_kind: "claude-code",
+                format_version,
+                session_id: sessionId,
+                source_id: index === 0 ? `${sessionId}:${line}` : `${sessionId}:${line}#${index}`,
+                read_only: true,
+                seq: seq++,
+                at,
+                ...(turn === undefined ? {} : { turn_id: turn }),
+                role,
+                part
+            });
+        });
+    }
+    return Result.succeed({
+        state: { pending, line, seq, session, turn, calls: Object.fromEntries(calls) },
+        entries
+    });
+};
+//# sourceMappingURL=ExternalTranscript.js.map