hyperbrane 0.1.0 → 0.1.1

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;