hyperbrane 0.1.0 → 0.1.2

package/dist/agent/hostTranscript.js

@@ -0,0 +1,190 @@
+import { AgentNotFoundError } from "./api.js";
+import { CHUNK_BYTES, PROBE_BYTES, PROBE_LINES, TIME_SLACK_MS, createFileTranscript, prefetchedFiles, sandboxFiles, transcriptPage, transcriptTime, } from "./session/fileTranscript.js";
+import { backendHomePath, sessionRecordPath } from "./session/sessionStorage.js";
+import { STORED_TRANSCRIPTS } from "./session/storedTranscripts.js";
+/**
+ * In one round trip: the session's record, its backend's file (found as the backend lays them out),
+ * the stretches written again in it, where the page starts (for a time, by bisecting the rest of the
+ * file as FileTranscript.page does) and what comes before that (PREFETCH_BYTES of it). The same
+ * searches as fileTranscript.ts, here where the file is. Args: a JSON object, see readHostTranscript.
+ */
+const READ_SCRIPT = String.raw `
+import base64, datetime, fnmatch, glob, json, mmap, os, sys
+args = json.loads(sys.argv[1])
+CHUNK, SLACK, PROBE_LINES, PROBE_BYTES = args["chunk"], args["slack"], args["probeLines"], args["probeBytes"]
+try:
+    with open(args["record"], "rb") as f:
+        record = json.load(f)
+except FileNotFoundError:
+    print("{}")
+    sys.exit(0)
+out = {"record": record}
+backend = record.get("spec", {}).get("backend")
+native_id = record.get("nativeId")
+layout = args["layouts"].get(backend)
+
+def entries(path):
+    try:
+        return sorted(os.listdir(path), reverse=True)
+    except OSError:
+        return []
+
+def line_time(raw):
+    try:
+        value = json.loads(raw).get(layout["time"])
+        return datetime.datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp() * 1000
+    except Exception:
+        return None
+
+def kept(start, end, skips):
+    parts = []
+    for a, b in sorted(skips):
+        if b <= start or a >= end:
+            continue
+        if a > start:
+            parts.append((start, a))
+        start = max(start, b)
+    if start < end:
+        parts.append((start, end))
+    return parts
+
+def forward(m, start, end, skips):
+    for a, b in kept(start, end, skips):
+        position = a
+        for raw in m[a:b].split(b"\n"):
+            if raw:
+                yield position, raw
+            position += len(raw) + 1
+
+def probe(m, start, limit, skips):
+    first, times = None, []
+    for line_start, raw in forward(m, start, min(limit, start + PROBE_BYTES), skips):
+        if line_start == start and start > 0:
+            continue
+        if line_start >= limit:
+            break
+        if first is None:
+            first = line_start
+        found = line_time(raw)
+        if found is None:
+            continue
+        times.append(found)
+        if len(times) == PROBE_LINES:
+            break
+    return None if first is None or not times else (first, min(times))
+
+def seek(m, low, high, target, skips):
+    return narrow(m, low, high, target, skips)[1]
+
+def narrow(m, low, high, target, skips):
+    while high - low > CHUNK:
+        middle = (low + high) // 2
+        inside = next((s for s in skips if s[0] <= middle < s[1]), None)
+        if inside:
+            if inside[1] >= high:
+                high = max(low, inside[0])
+                continue
+            middle = inside[1]
+        found = probe(m, middle, high, skips)
+        if not found:
+            break
+        if found[1] >= target:
+            high = found[0]
+        else:
+            low = found[0]
+    return low, high
+
+def copies_of(m, size, marker):
+    copies, found, position = [], [], 0
+    while True:
+        at = m.find(marker.encode(), position)
+        if at < 0:
+            break
+        found.append(at)
+        position = at + 1
+    for index, at in enumerate(found):
+        start = m.rfind(b"\n", 0, at) + 1
+        if any(a <= start < b for a, b in copies):
+            continue
+        earlier, end = None, start - 1
+        while end > 0 and earlier is None:
+            begin = m.rfind(b"\n", 0, end) + 1
+            earlier = line_time(m[begin:end])
+            end = begin - 1
+        line_end = m.find(b"\n", start)
+        time = line_time(m[start : line_end if line_end >= 0 else size])
+        if earlier is None or time is None or time >= earlier:
+            continue
+        high = m.rfind(b"\n", 0, found[index + 1]) + 1 if index + 1 < len(found) else size
+        low, high = narrow(m, start + 1, high, earlier + 1, [])
+        end = next((s for s, raw in forward(m, low, high, []) if s > start and (line_time(raw) or -1) > earlier), high)
+        copies.append((start, end))
+    return copies
+
+if native_id and layout:
+    name = layout["name"].replace("{id}", glob.escape(native_id))
+    dirs = [os.path.join(args["homes"][backend], layout["dir"])]
+    for _ in range(layout["depth"] - 1):
+        dirs = [os.path.join(d, e) for d in dirs for e in entries(d) if os.path.isdir(os.path.join(d, e))]
+    path = next((os.path.join(d, e) for d in dirs for e in entries(d) if fnmatch.fnmatchcase(e, name)), None)
+    size = os.path.getsize(path) if path else 0
+    if path and size == 0:
+        out.update(path=path, size=0, end=0, after=None, copies=[], pieces=[])
+    elif path:
+        with open(path, "rb") as f:
+            m = mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ)
+            copies = copies_of(m, size, layout["copies"]) if layout.get("copies") else []
+            end = size if args["before"] is None else seek(m, 0, size, args["before"] + SLACK, copies)
+            after = next((t for t in (line_time(raw) for _, raw in forward(m, end, min(size, end + PROBE_BYTES), copies)) if t is not None), None)
+            pieces, left = [], args["prefetch"]
+            for a, b in reversed(kept(0, end, copies)):
+                if left <= 0:
+                    break
+                start = max(a, b - left)
+                pieces.append({"start": start, "bytes": base64.b64encode(m[start:b]).decode()})
+                left -= b - start
+            out.update(path=path, size=size, end=end, after=after, copies=[[a, b] for a, b in copies], pieces=pieces)
+print(json.dumps(out))
+`;
+/** What's sent of the file with the record: a page and the slack around it, mostly, so it takes no more reads. */
+const PREFETCH_BYTES = 8 * CHUNK_BYTES;
+/**
+ * A page of the session's transcript, read on `host` from the dimension's state directory (its host
+ * side) by the backend's own layout and parsing, so nothing has to run: one command, plus a read
+ * for each further chunk the rare page that needs more takes. Null for a session whose env moves the backend's home
+ * elsewhere (into the container, where only its worker reaches it).
+ */
+export async function readHostTranscript(host, { stateDirectory, agentName, sessionName }, { limit, before, cursor }) {
+    before ??= cursor; // its old name
+    const args = {
+        record: sessionRecordPath(stateDirectory, agentName, sessionName),
+        homes: Object.fromEntries(Object.keys(STORED_TRANSCRIPTS).map((backend) => [backend, backendHomePath(stateDirectory, backend)])),
+        layouts: Object.fromEntries(Object.entries(STORED_TRANSCRIPTS).map(([backend, stored]) => [backend, stored.layout])),
+        before: transcriptTime(before),
+        chunk: CHUNK_BYTES,
+        prefetch: PREFETCH_BYTES,
+        slack: TIME_SLACK_MS,
+        probeLines: PROBE_LINES,
+        probeBytes: PROBE_BYTES,
+    };
+    const result = await host.runCommand(["python3", "-c", READ_SCRIPT, JSON.stringify(args)]);
+    if (result.exitCode !== 0)
+        throw new Error(`reading session ${sessionName}'s transcript failed: ${result.stderr.trim() || `exit ${result.exitCode}`}`);
+    const { record, path, size, end, after, copies, pieces } = JSON.parse(result.stdout);
+    if (!record)
+        throw new AgentNotFoundError(`session ${sessionName} does not exist`);
+    const stored = STORED_TRANSCRIPTS[record.spec.backend];
+    if (Object.keys(stored.homeEnvironment("")).some((name) => record.spec.env?.[name] !== undefined))
+        return null;
+    if (!record.nativeId)
+        return transcriptPage(null, { limit, before });
+    let files = sandboxFiles(host);
+    let found;
+    if (path !== undefined && size !== undefined && end !== undefined) {
+        const fetched = (pieces ?? []).map((piece) => ({ start: piece.start, bytes: new Uint8Array(Buffer.from(piece.bytes, "base64")) }));
+        files = prefetchedFiles(files, path, size, fetched);
+        found = { end, after: after ?? null, copies: (copies ?? []).map(([start, stop]) => ({ start, end: stop })) };
+    }
+    const transcript = createFileTranscript(files, async () => path ?? null, stored.lineMessages(record.nativeId), stored.layout);
+    return transcriptPage(transcript, { limit, before }, found);
+}

package/dist/agent/session/backend.d.ts

@@ -0,0 +1,82 @@
+import type { AgentBackendInfo, AgentBackgroundTasks, AgentInput, AgentInterrupt, AgentMessageQueue, AgentModels, AgentPermissionRequest, AgentPermissionResult, AgentQuestionRequest, AgentQuestionResponse, AgentSession, AgentSessionStatus, AgentStreamingMessage, SessionRef } from "../api.ts";
+import type { FileTranscript, TranscriptFiles } from "./fileTranscript.ts";
+/** A capability's calls for one session: those of api.ts, with the session already chosen. */
+export type ForSession<Capability> = {
+    [K in keyof Capability]: Capability[K] extends (ref: SessionRef, ...args: infer Args) => infer Result ? (...args: Args) => Result : never;
+};
+/** What one session's CLI runs with. */
+export type SessionLaunch = {
+    spec: AgentSession;
+    /** The backend's id for the conversation, from an earlier run, to resume it; null for a new one. */
+    nativeId: string | null;
+    cwd: string;
+    /** The model chosen through AgentModels; null for the backend's default. */
+    model: string | null;
+    /** Where backends are installed (see SessionBackend.install). */
+    installDir: string;
+    /** The worker's own environment, the CLI pointed at its home, and the session's. */
+    env: Record<string, string>;
+};
+/** What the CLI reports to, and asks of, the worker. */
+export type SessionCallbacks = {
+    /** Appends to the session's stream. */
+    emit(message: AgentStreamingMessage): void;
+    /** Records the backend's conversation id, so a later run can resume it. */
+    setNativeId(id: string): void;
+    /** The decision on a tool call: someone's answer, or a denial once the turn is interrupted, the session stops, or `signal` aborts. */
+    requestPermission(request: Omit<AgentPermissionRequest, "id">, signal?: AbortSignal): Promise<AgentPermissionResult>;
+    /** The user's answers, or null once the turn is interrupted, the session stops, or `signal` aborts. */
+    askQuestions(request: Omit<AgentQuestionRequest, "id">, signal?: AbortSignal): Promise<AgentQuestionResponse | null>;
+    /** The CLI is gone (crashed, or closed); the next message starts it again. */
+    exited(error?: Error): void;
+};
+export type SessionContext = SessionLaunch & SessionCallbacks;
+/** One session's running CLI: the capabilities it serves itself. */
+export type RunningSession = ForSession<AgentInput & AgentInterrupt & AgentSessionStatus & AgentMessageQueue & AgentModels & AgentBackgroundTasks> & {
+    close(): Promise<void>;
+};
+/** What a CLI's sign-in commands run with. */
+export type AuthEnvironment = {
+    installDir: string;
+    env: Record<string, string>;
+    cwd: string;
+};
+/** A sign-in in progress: the CLI's own login command. */
+export interface LoginProcess {
+    /** Resolves once the CLI has shown where to sign in. */
+    prompt: Promise<{
+        url: string;
+        userCode?: string;
+        needsCode: boolean;
+    }>;
+    /** Resolves when the CLI signed in; rejects with why it didn't. */
+    done: Promise<void>;
+    /** Gives the CLI the code the sign-in page showed. */
+    submitCode(code: string): void;
+    cancel(): void;
+}
+/** A CLI's sign-in, through its own commands. The credentials it saves are fakes when a gateway holds the real ones. */
+export type BackendAuth = {
+    signedIn(environment: AuthEnvironment): Promise<boolean>;
+    /** With `gatewaySignedIn` (the dimension's gateway holds the upstream's credential) it completes by itself: the gateway answers. */
+    login(environment: AuthEnvironment, gatewaySignedIn: boolean): LoginProcess;
+};
+/** What finds a session's conversation in its backend's storage, read through `files`. */
+export type TranscriptSource = {
+    nativeId: string;
+    env: Record<string, string>;
+    files: TranscriptFiles;
+};
+/** An agent CLI, wired in agent/session/<backend>/: one file per capability. */
+export type SessionBackend = {
+    /** Installs the backend under `installDir`, or updates it to the pinned version. Runs in the dimension. */
+    install(installDir: string): Promise<void>;
+    /** What's installed under `installDir`, and whether it's what install leaves: this release's version, complete. */
+    installed(installDir: string): Promise<Pick<AgentBackendInfo, "version" | "ready">>;
+    start(context: SessionContext): Promise<RunningSession>;
+    auth: BackendAuth;
+    /** The conversation `nativeId` in the backend's own storage, which needs no CLI running. */
+    transcript(source: TranscriptSource): FileTranscript;
+    /** The environment that points the CLI at `home` for everything it keeps (see SessionStorage.backendHome). */
+    homeEnvironment(home: string): Record<string, string>;
+};

package/dist/agent/session/backend.js

@@ -0,0 +1 @@
+export {};

package/dist/agent/session/claude/home.d.ts

@@ -0,0 +1,2 @@
+/** Points claude at `home` for everything it keeps: its .claude.json too, which otherwise sits in the home directory. */
+export declare function claudeHomeEnvironment(home: string): Record<string, string>;

package/dist/agent/session/claude/home.js

@@ -0,0 +1,4 @@
+/** Points claude at `home` for everything it keeps: its .claude.json too, which otherwise sits in the home directory. */
+export function claudeHomeEnvironment(home) {
+    return { CLAUDE_CONFIG_DIR: home };
+}

package/dist/agent/session/claude/transcript.d.ts

@@ -0,0 +1,13 @@
+import type { AgentTranscriptMessage } from "../../api.ts";
+import type { TranscriptSource } from "../backend.ts";
+import { type FileTranscript, type TranscriptLayout } from "../fileTranscript.ts";
+/**
+ * The conversation from claude's own session file, <config>/projects/<cwd>/<session>.jsonl. Its user
+ * and assistant entries are the messages the stream carried, with their uuids (claude keeps the one
+ * a prompt was sent with); the rest (attachments, queue bookkeeping, a subagent's sidechain, meta
+ * notes) isn't the conversation.
+ */
+export declare function claudeTranscript({ nativeId, env, files }: TranscriptSource): FileTranscript;
+/** projects/<cwd>/<session>.jsonl in claude's config directory. */
+export declare const CLAUDE_TRANSCRIPT_LAYOUT: TranscriptLayout;
+export declare function claudeLineMessages(line: unknown): AgentTranscriptMessage[];

package/dist/agent/session/claude/transcript.js

@@ -0,0 +1,29 @@
+import { createFileTranscript, locateTranscript } from "../fileTranscript.js";
+/**
+ * The conversation from claude's own session file, <config>/projects/<cwd>/<session>.jsonl. Its user
+ * and assistant entries are the messages the stream carried, with their uuids (claude keeps the one
+ * a prompt was sent with); the rest (attachments, queue bookkeeping, a subagent's sidechain, meta
+ * notes) isn't the conversation.
+ */
+export function claudeTranscript({ nativeId, env, files }) {
+    const home = env.CLAUDE_CONFIG_DIR ?? `${env.HOME}/.claude`;
+    return createFileTranscript(files, () => locateTranscript(files, home, CLAUDE_TRANSCRIPT_LAYOUT, nativeId), claudeLineMessages, CLAUDE_TRANSCRIPT_LAYOUT);
+}
+/** projects/<cwd>/<session>.jsonl in claude's config directory. */
+export const CLAUDE_TRANSCRIPT_LAYOUT = {
+    dir: "projects",
+    depth: 2,
+    name: "{id}.jsonl",
+    time: "timestamp",
+    // Resuming a session, claude writes what it said since its last compaction again, from that compaction's line.
+    copies: '"subtype":"compact_boundary"',
+};
+export function claudeLineMessages(line) {
+    const entry = line;
+    if (entry.type !== "user" && entry.type !== "assistant")
+        return [];
+    if (entry.isSidechain || entry.isMeta || !entry.uuid || !entry.message)
+        return [];
+    // type-bypass: claude stores the message the stream carried; its type is the SDK's.
+    return [{ type: entry.type, message: entry.message, parent_tool_use_id: null, uuid: entry.uuid, session_id: entry.sessionId ?? "" }];
+}

package/dist/agent/session/client.d.ts

@@ -1,7 +1,11 @@
 import type { AgentStreamingMessage } from "../api.ts";
 import type { WorkerMethod, WorkerRequests } from "./worker/protocol.ts";
 import type { ConnectWorker } from "./workerConnection.ts";
-/** The worker's protocol (protocol.ts). Errors come back as the Agent*Error they were. */
+/**
+ * The worker's protocol (protocol.ts). Errors come back as the Agent*Error they were.
+ *
+ * @sealed
+ */
 export type WorkerClient = {
     call<M extends WorkerMethod>(method: M, params: WorkerRequests[M][0]): Promise<WorkerRequests[M][1]>;
     /**

package/dist/agent/session/codex/home.d.ts

@@ -0,0 +1,2 @@
+/** Points codex at `home` for everything it keeps. */
+export declare function codexHomeEnvironment(home: string): Record<string, string>;

package/dist/agent/session/codex/home.js

@@ -0,0 +1,4 @@
+/** Points codex at `home` for everything it keeps. */
+export function codexHomeEnvironment(home) {
+    return { CODEX_HOME: home };
+}

package/dist/agent/session/codex/messages.d.ts

@@ -0,0 +1,30 @@
+import type { ThreadItem } from "../../vendor-types/codex/app-server/v2/ThreadItem.ts";
+import type { AgentTranscriptMessage as TranscriptMessage } from "../../api.ts";
+import { type AssistantContentBlock } from "../sdkMessages.ts";
+/** The uuid of the result message of tool item `itemId`; the call's is the item id itself. */
+export declare function toolResultId(itemId: string): string;
+export declare function assistantMessage(uuid: string, content: AssistantContentBlock[], threadId: string, model: string): TranscriptMessage;
+export declare function toolResultMessage(itemId: string, content: string, isError: boolean, threadId: string): TranscriptMessage;
+/**
+ * The messages a finished item stands for, as the transcript shows them. A user message keeps the
+ * id it was sent with (codex records it as the item's clientId).
+ */
+export declare function itemMessages(item: ThreadItem, threadId: string, model: string): TranscriptMessage[];
+/**
+ * The messages a rollout item stands for, the same (ids included) as the stream carried live. Items
+ * other than messages and commands (file changes, MCP calls, ...) aren't mapped from the rollout yet.
+ */
+export declare function rolloutItemMessages(stored: unknown, threadId: string): TranscriptMessage[];
+/** The claude-style tool call a codex item stands for, if it is one. */
+export declare function toolUseOf(item: ThreadItem): {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+} | null;
+export declare function toolResultOf(item: ThreadItem): {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+    is_error: boolean;
+} | null;

package/dist/agent/session/codex/messages.js

@@ -0,0 +1,135 @@
+import { resultUsage } from "../sdkMessages.js";
+// codex's thread items as the stream's SDK messages, the same live (stream.ts) and read back from
+// codex's storage (transcript.ts), ids included: a message's uuid is its item's id, which is what
+// after_id finds again. One tool item is two messages, the call and its result.
+/** An id codex chose, in the SDK's uuid slot. type-bypass: codex's ids ("msg_…") aren't UUID-shaped; the SDK types the slot as one, but only ever compares it. */
+function backendId(id) {
+    return id;
+}
+/** The uuid of the result message of tool item `itemId`; the call's is the item id itself. */
+export function toolResultId(itemId) {
+    return `${itemId}:result`;
+}
+export function assistantMessage(uuid, content, threadId, model) {
+    const usage = { ...resultUsage(), cache_creation: null, server_tool_use: null, service_tier: null };
+    return {
+        type: "assistant",
+        message: {
+            id: uuid,
+            type: "message",
+            role: "assistant",
+            model,
+            content,
+            container: null,
+            context_management: null,
+            stop_reason: null,
+            stop_sequence: null,
+            usage,
+        },
+        parent_tool_use_id: null,
+        uuid: backendId(uuid),
+        session_id: threadId,
+    };
+}
+export function toolResultMessage(itemId, content, isError, threadId) {
+    return {
+        type: "user",
+        message: { role: "user", content: [{ type: "tool_result", tool_use_id: itemId, content, is_error: isError }] },
+        parent_tool_use_id: null,
+        uuid: backendId(toolResultId(itemId)),
+        session_id: threadId,
+    };
+}
+/**
+ * The messages a finished item stands for, as the transcript shows them. A user message keeps the
+ * id it was sent with (codex records it as the item's clientId).
+ */
+export function itemMessages(item, threadId, model) {
+    if (item.type === "userMessage") {
+        const text = item.content.map((input) => (input.type === "text" ? input.text : "")).join("");
+        return [{ type: "user", message: { role: "user", content: text }, parent_tool_use_id: null, uuid: backendId(item.clientId ?? item.id), session_id: threadId }];
+    }
+    if (item.type === "agentMessage")
+        return [assistantMessage(item.id, [{ type: "text", text: item.text, citations: null }], threadId, model)];
+    const toolUse = toolUseOf(item);
+    const toolResult = toolResultOf(item);
+    if (!toolUse)
+        return [];
+    const messages = [assistantMessage(item.id, [toolUse], threadId, model)];
+    if (toolResult)
+        messages.push(toolResultMessage(item.id, toolResult.content, toolResult.is_error, threadId));
+    return messages;
+}
+/** How codex shows a command it ran through a shell: `/bin/bash -lc '<script>'`. */
+function shownCommand(argv) {
+    return argv.map((arg) => (/^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`)).join(" ");
+}
+/**
+ * The messages a rollout item stands for, the same (ids included) as the stream carried live. Items
+ * other than messages and commands (file changes, MCP calls, ...) aren't mapped from the rollout yet.
+ */
+export function rolloutItemMessages(stored, threadId) {
+    const item = stored;
+    const text = (content) => (content ?? []).map((part) => part.text ?? "").join("");
+    if (item.type === "UserMessage" && "content" in item) {
+        const user = item;
+        return [{ type: "user", message: { role: "user", content: text(user.content) }, parent_tool_use_id: null, uuid: backendId(user.client_id ?? user.id), session_id: threadId }];
+    }
+    if (item.type === "AgentMessage" && item.id) {
+        const agent = item;
+        return [assistantMessage(agent.id, [{ type: "text", text: text(agent.content), citations: null }], threadId, "")];
+    }
+    if (item.type === "CommandExecution" && item.id) {
+        const command = item;
+        const input = { command: shownCommand(command.command ?? []), cwd: (command.cwd ?? "").replace(/^file:\/\//, "") };
+        return [
+            assistantMessage(command.id, [{ type: "tool_use", id: command.id, name: "Bash", input }], threadId, ""),
+            toolResultMessage(command.id, command.aggregated_output ?? "", command.status !== "completed" || (command.exit_code ?? 0) !== 0, threadId),
+        ];
+    }
+    return [];
+}
+/** The claude-style tool call a codex item stands for, if it is one. */
+export function toolUseOf(item) {
+    switch (item.type) {
+        case "commandExecution":
+            return { type: "tool_use", id: item.id, name: "Bash", input: { command: item.command, cwd: item.cwd } };
+        case "fileChange":
+            return { type: "tool_use", id: item.id, name: "ApplyPatch", input: { changes: item.changes } };
+        case "mcpToolCall":
+            return { type: "tool_use", id: item.id, name: `mcp__${item.server}__${item.tool}`, input: item.arguments };
+        case "dynamicToolCall":
+            return { type: "tool_use", id: item.id, name: item.tool, input: item.arguments };
+        default:
+            return null;
+    }
+}
+export function toolResultOf(item) {
+    switch (item.type) {
+        case "commandExecution":
+            return {
+                type: "tool_result",
+                tool_use_id: item.id,
+                content: item.aggregatedOutput ?? "",
+                is_error: item.status !== "completed" || (item.exitCode ?? 0) !== 0,
+            };
+        case "fileChange":
+            return { type: "tool_result", tool_use_id: item.id, content: item.status, is_error: item.status !== "completed" };
+        case "mcpToolCall":
+            return {
+                type: "tool_result",
+                tool_use_id: item.id,
+                content: JSON.stringify(item.error ?? item.result?.content ?? null),
+                is_error: item.status !== "completed",
+            };
+        case "dynamicToolCall":
+            return {
+                type: "tool_result",
+                tool_use_id: item.id,
+                content: JSON.stringify(item.contentItems ?? null),
+                is_error: item.success === false,
+            };
+        default:
+            return null;
+    }
+}

package/dist/agent/session/codex/transcript.d.ts

@@ -0,0 +1,12 @@
+import type { TranscriptSource } from "../backend.ts";
+import { type FileTranscript, type LineMessages, type TranscriptLayout } from "../fileTranscript.ts";
+/**
+ * The conversation from codex's own rollout, <codex home>/sessions/<date>/rollout-<time>-<thread>.jsonl:
+ * each finished item is an item_completed event there, as the messages the stream carried for it.
+ * Read directly: the app-server's thread/read loads the whole thread, and its paged
+ * thread/turns/list isn't implemented in codex 0.157.
+ */
+export declare function codexTranscript({ nativeId, env, files }: TranscriptSource): FileTranscript;
+/** sessions/YYYY/MM/DD/rollout-<time>-<thread>.jsonl in codex's home. */
+export declare const CODEX_TRANSCRIPT_LAYOUT: TranscriptLayout;
+export declare function codexLineMessages(threadId: string): LineMessages;

package/dist/agent/session/codex/transcript.js

@@ -0,0 +1,22 @@
+import { createFileTranscript, locateTranscript } from "../fileTranscript.js";
+import { rolloutItemMessages } from "./messages.js";
+/**
+ * The conversation from codex's own rollout, <codex home>/sessions/<date>/rollout-<time>-<thread>.jsonl:
+ * each finished item is an item_completed event there, as the messages the stream carried for it.
+ * Read directly: the app-server's thread/read loads the whole thread, and its paged
+ * thread/turns/list isn't implemented in codex 0.157.
+ */
+export function codexTranscript({ nativeId, env, files }) {
+    const home = env.CODEX_HOME ?? `${env.HOME}/.codex`;
+    return createFileTranscript(files, () => locateTranscript(files, home, CODEX_TRANSCRIPT_LAYOUT, nativeId), codexLineMessages(nativeId), CODEX_TRANSCRIPT_LAYOUT);
+}
+/** sessions/YYYY/MM/DD/rollout-<time>-<thread>.jsonl in codex's home. */
+export const CODEX_TRANSCRIPT_LAYOUT = { dir: "sessions", depth: 4, name: "rollout-*-{id}.jsonl", time: "timestamp" };
+export function codexLineMessages(threadId) {
+    return (line) => {
+        const { type, payload } = line;
+        if (type !== "event_msg" || payload?.type !== "item_completed" || !payload.item)
+            return [];
+        return rolloutItemMessages(payload.item, threadId);
+    };
+}

package/dist/agent/session/fileTranscript.d.ts

@@ -0,0 +1,92 @@
+import { type SandboxFileOperations } from "../../sandbox/api.ts";
+import { type AgentTranscriptMessage as TranscriptMessage, type AgentTranscriptPage, type AgentTranscriptRequest } from "../api.ts";
+/** One page of a transcript: its messages oldest first, and the time the next (older) page is before. */
+export type TranscriptPage = {
+    messages: TranscriptMessage[];
+    nextBefore: string | null;
+};
+/**
+ * A backend's transcript, read from its own JSONL file a chunk at a time, so a long conversation (a
+ * file of hundreds of MB) never has to be in memory: a page holds its messages and a few chunks, and
+ * a replay streams. Pages go by the time on each line: the file is in conversation order, its times
+ * nearly so (a line is written when its message completes, so parallel branches land seconds out of
+ * order), which lets a time be found by bisecting the file.
+ */
+export interface FileTranscript {
+    /**
+     * The newest `limit` or so messages from before `before` (epoch ms; null for the newest), by their
+     * times, with every other message of the oldest one's time, so the page before it is exactly those
+     * before that time. `found`: what a search of the file found beforehand.
+     */
+    page(before: number | null, limit: number, found?: TranscriptFound): Promise<TranscriptPage>;
+    /**
+     * Hands `emit` every message after the one whose uuid is `afterId` (all of them when undefined), in
+     * order, as far as the file went when the replay began. False when `afterId` isn't in the file.
+     */
+    replay(afterId: string | undefined, emit: (message: TranscriptMessage) => void): Promise<boolean>;
+}
+/** What a transcript is read through: the worker's own files (sandboxFiles), or what the host fetched of them. */
+export type TranscriptFiles = {
+    size(path: string): Promise<number>;
+    readFileRange(path: string, start: number, end: number): Promise<Uint8Array>;
+    listDirectory(path: string): Promise<string[]>;
+};
+export declare function sandboxFiles(sandbox: SandboxFileOperations): TranscriptFiles;
+/**
+ * Where a backend keeps its conversations, under its home: in `dir`, `depth` levels down (1: in
+ * `dir` itself), a file named `name`, where `*` is any characters and `{id}` the conversation's id.
+ * Each line of it is a JSON object with its ISO 8601 time in the field `time`. `copies`: what's in
+ * the line that starts a stretch the backend writes again (claude, resuming a session, writes what
+ * it said since its last compaction again, under the same ids and times), as it's written.
+ */
+export type TranscriptLayout = {
+    dir: string;
+    depth: number;
+    name: string;
+    time: string;
+    copies?: string;
+};
+/** A stretch of the file a reader passes over, from one line's start to another's. */
+export type Skip = {
+    start: number;
+    end: number;
+};
+/** What a search of the file found beforehand (the host's, in the same round trip as the record). */
+export type TranscriptFound = {
+    /** Where the page starts: FileTranscript.page's `before`, found. */
+    end: number;
+    /** The time of the first timed line from `end` on, if any. */
+    after: number | null;
+    /** The stretches written again. */
+    copies: Skip[];
+};
+/** The file of conversation `nativeId` laid out as `layout` under `home`; null when there's none yet. */
+export declare function locateTranscript(files: TranscriptFiles, home: string, layout: TranscriptLayout, nativeId: string): Promise<string | null>;
+/** The messages one line of the file stands for, oldest first (none for bookkeeping lines). */
+export type LineMessages = (entry: unknown) => TranscriptMessage[];
+/** How much of the file is read at a time. */
+export declare const CHUNK_BYTES: number;
+/**
+ * How far out of time order lines get, nearly always (parallel branches completing; in long claude
+ * sessions half are within 2s, 99% within a minute): searches allow for this much.
+ */
+export declare const TIME_SLACK_MS = 60000;
+/** How many timed lines a probe of the bisection looks at: the earliest wins, so one odd line can't mislead it. */
+export declare const PROBE_LINES = 3;
+/** How much a probe reads, at most, before it gives up on finding a timed line (huge tool outputs). */
+export declare const PROBE_BYTES: number;
+/** `locate` finds the file; null when there's none yet (nothing stored). */
+export declare function createFileTranscript(files: TranscriptFiles, locate: () => Promise<string | null>, lineMessages: LineMessages, layout: Pick<TranscriptLayout, "time" | "copies">): FileTranscript;
+/** A page of the API's transcript (AgentTranscript.getTranscript); none stored for a session that never ran. */
+export declare function transcriptPage(transcript: FileTranscript | null, { limit, before, cursor }?: AgentTranscriptRequest, found?: TranscriptFound): Promise<AgentTranscriptPage>;
+/** AgentTranscriptRequest.before as epoch ms; null for none. */
+export declare function transcriptTime(before: string | undefined): number | null;
+/**
+ * `files` with what was already fetched of the file at `path` in the same round trip: its size, and
+ * pieces of it (what a page reads, mostly). Reading back beyond them (a page across huge tool
+ * outputs) fetches twice as much as the time before, so it takes a few more reads, not one per chunk.
+ */
+export declare function prefetchedFiles(files: TranscriptFiles, path: string, size: number, pieces: {
+    start: number;
+    bytes: Uint8Array;
+}[]): TranscriptFiles;