hyperbrane 0.1.2 → 0.2.0

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

@@ -0,0 +1,17 @@
+import { existsSync } from "node:fs";
+import { installPackage, installedPackage, pinnedVersion } from "../install.js";
+export const CLAUDE_SDK_PACKAGE = "@anthropic-ai/claude-agent-sdk";
+export function claudePackage() {
+    return { pkg: CLAUDE_SDK_PACKAGE, version: pinnedVersion("claude", CLAUDE_SDK_PACKAGE), executables: `${CLAUDE_SDK_PACKAGE}-linux-*/claude` };
+}
+export function installClaude(installDir) {
+    return installPackage(installDir, CLAUDE_SDK_PACKAGE, pinnedVersion("claude", CLAUDE_SDK_PACKAGE), () => claudeExecutable(installDir));
+}
+export function installedClaude(installDir) {
+    return installedPackage(installDir, CLAUDE_SDK_PACKAGE, pinnedVersion("claude", CLAUDE_SDK_PACKAGE), () => claudeExecutable(installDir));
+}
+export function claudeExecutable(installDir) {
+    const base = `${installDir}/node_modules/${CLAUDE_SDK_PACKAGE}-linux-${process.arch}`;
+    const glibc = `${base}/claude`;
+    return existsSync(glibc) ? glibc : `${base}-musl/claude`;
+}

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

@@ -1,13 +1,8 @@
 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 function claudeSubagentTranscript(source: TranscriptSource, agentId: string, toolUseId: string): FileTranscript;
+export declare function claudeFindSubagent(source: TranscriptSource, toolUseId: string): Promise<string | null>;
 export declare const CLAUDE_TRANSCRIPT_LAYOUT: TranscriptLayout;
 export declare function claudeLineMessages(line: unknown): AgentTranscriptMessage[];

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

@@ -1,29 +1,83 @@
-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.
- */
+import { createFileTranscript, directoryNames, locateTranscript } from "../fileTranscript.js";
 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);
+    return createFileTranscript(files, () => locateTranscript(files, claudeHome(env), CLAUDE_TRANSCRIPT_LAYOUT, nativeId), claudeLineMessages, CLAUDE_TRANSCRIPT_LAYOUT);
 }
-/** projects/<cwd>/<session>.jsonl in claude's config directory. */
+export function claudeSubagentTranscript(source, agentId, toolUseId) {
+    return subagentFile(source, `agent-${agentId}.jsonl`, toolUseId);
+}
+export async function claudeFindSubagent(source, toolUseId) {
+    const isResult = (message) => message.type === "user" && Array.isArray(message.message.content) && message.message.content.some((block) => block.type === "tool_result" && block.tool_use_id === toolUseId);
+    let found = await claudeTranscript(source).find(isResult);
+    const dir = found ? null : await subagentsDirectory(source);
+    const names = dir ? ((await directoryNames(source.files, dir)) ?? []) : [];
+    for (const name of names.filter((entry) => SUBAGENT_FILE.test(entry))) {
+        found = await subagentFile(source, name, toolUseId).find(isResult);
+        if (found)
+            break;
+    }
+    const agentId = found?.tool_use_result?.agentId;
+    return typeof agentId === "string" ? agentId : null;
+}
+function subagentFile(source, name, toolUseId) {
+    async function locate() {
+        const dir = await subagentsDirectory(source);
+        if (!dir)
+            return null;
+        return (await directoryNames(source.files, dir))?.includes(name) ? `${dir}/${name}` : null;
+    }
+    return createFileTranscript(source.files, locate, (line) => lineMessages(line, toolUseId), CLAUDE_TRANSCRIPT_LAYOUT);
+}
+async function subagentsDirectory({ nativeId, env, files }) {
+    const main = await locateTranscript(files, claudeHome(env), CLAUDE_TRANSCRIPT_LAYOUT, nativeId);
+    return main ? `${main.slice(0, -".jsonl".length)}/subagents` : null;
+}
+function claudeHome(env) {
+    return env.CLAUDE_CONFIG_DIR ?? `${env.HOME}/.claude`;
+}
+const SUBAGENT_FILE = /^agent-.+\.jsonl$/;
 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) {
+    return lineMessages(line, null);
+}
+function lineMessages(line, parentToolUseId) {
     const entry = line;
+    if (entry.type === "system" && entry.subtype === "compact_boundary")
+        return compaction(entry);
     if (entry.type !== "user" && entry.type !== "assistant")
         return [];
-    if (entry.isSidechain || entry.isMeta || !entry.uuid || !entry.message)
+    if ((entry.isSidechain && parentToolUseId === null) || entry.isMeta || !entry.uuid || !entry.message)
+        return [];
+    const common = { parent_tool_use_id: parentToolUseId, uuid: entry.uuid, session_id: entry.sessionId ?? "", ...(entry.timestamp ? { timestamp: entry.timestamp } : {}) };
+    if (entry.type === "assistant")
+        return [{ type: "assistant", message: entry.message, ...common }];
+    return [{ type: "user", message: entry.message, ...common, ...(entry.toolUseResult !== undefined ? { tool_use_result: entry.toolUseResult } : {}) }];
+}
+function compaction(entry) {
+    const meta = entry.compactMetadata;
+    if (!entry.uuid || !meta?.trigger)
         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 ?? "" }];
+    const { preservedSegment: segment, preservedMessages: preserved } = meta;
+    return [
+        {
+            type: "system",
+            subtype: "compact_boundary",
+            compact_metadata: {
+                trigger: meta.trigger,
+                pre_tokens: meta.preTokens ?? 0,
+                ...(meta.postTokens !== undefined ? { post_tokens: meta.postTokens } : {}),
+                ...(meta.durationMs !== undefined ? { duration_ms: meta.durationMs } : {}),
+                ...(segment ? { preserved_segment: { head_uuid: segment.headUuid, anchor_uuid: segment.anchorUuid, tail_uuid: segment.tailUuid } } : {}),
+                ...(preserved ? { preserved_messages: { anchor_uuid: preserved.anchorUuid, uuids: preserved.uuids } } : {}),
+            },
+            uuid: entry.uuid,
+            session_id: entry.sessionId ?? "",
+            ...(entry.timestamp ? { timestamp: entry.timestamp } : {}),
+        },
+    ];
 }

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

@@ -1,18 +1,9 @@
 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.
- *
- * @sealed
- */
+/** @sealed */
 export type WorkerClient = {
     call<M extends WorkerMethod>(method: M, params: WorkerRequests[M][0]): Promise<WorkerRequests[M][1]>;
-    /**
-     * The session's messages after `afterId`, then each one as the worker produces it, over a
-     * connection held open while the caller reads. Throws once the worker goes away.
-     */
     stream(sessionName: string, afterId: string | undefined): AsyncGenerator<AgentStreamingMessage>;
 };
-/** Calls the worker over the connections `connect` opens (workerSocketConnector: its unix socket). */
 export declare function createWorkerClient(connect: ConnectWorker): WorkerClient;

package/dist/agent/session/client.js

@@ -1,6 +1,4 @@
-/** Calls the worker over the connections `connect` opens (workerSocketConnector: its unix socket). */
 export function createWorkerClient(connect) {
-    /** One request on a connection of its own. */
     async function call(method, params) {
         const connection = await connect();
         try {
@@ -37,7 +35,6 @@ export function createWorkerClient(connect) {
             }
         }
         finally {
-            // On a shared connection (sharedConnector) the worker would go on sending to it otherwise.
             if (!ended)
                 connection.request("session/unsubscribe", { subscription }).catch(() => { });
             connection.close();

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

@@ -0,0 +1,14 @@
+import type { AgentBackendInfo } from "../../api.ts";
+export declare const CODEX_PACKAGE = "@openai/codex";
+export declare function codexPackage(): {
+    pkg: string;
+    version: string;
+    executables: string;
+};
+export declare function installCodex(installDir: string): Promise<void>;
+export declare function installedCodex(installDir: string): Promise<Omit<AgentBackendInfo, "backend">>;
+export type CodexExecutable = {
+    path: string;
+    env: Record<string, string>;
+};
+export declare function codexExecutable(installDir: string): CodexExecutable;

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

@@ -0,0 +1,25 @@
+import { installPackage, installedPackage, pinnedVersion } from "../install.js";
+export const CODEX_PACKAGE = "@openai/codex";
+const CODEX_VERSION = () => pinnedVersion("codex", CODEX_PACKAGE, "@openai/codex-sdk");
+export function codexPackage() {
+    return { pkg: CODEX_PACKAGE, version: CODEX_VERSION(), executables: "@openai/codex-linux-*/vendor/*/bin/codex" };
+}
+export function installCodex(installDir) {
+    return installPackage(installDir, CODEX_PACKAGE, CODEX_VERSION(), () => codexExecutable(installDir).path);
+}
+export function installedCodex(installDir) {
+    return installedPackage(installDir, CODEX_PACKAGE, CODEX_VERSION(), () => codexExecutable(installDir).path);
+}
+const LINUX_TARGETS = {
+    x64: { pkg: "@openai/codex-linux-x64", triple: "x86_64-unknown-linux-musl" },
+    arm64: { pkg: "@openai/codex-linux-arm64", triple: "aarch64-unknown-linux-musl" },
+};
+export function codexExecutable(installDir) {
+    const target = LINUX_TARGETS[process.arch];
+    if (process.platform !== "linux" || !target)
+        throw new Error(`codex: unsupported platform ${process.platform}/${process.arch}`);
+    return {
+        path: `${installDir}/node_modules/${target.pkg}/vendor/${target.triple}/bin/codex`,
+        env: { CODEX_MANAGED_PACKAGE_ROOT: `${installDir}/node_modules/${CODEX_PACKAGE}`, CODEX_MANAGED_BY_BUN: "1" },
+    };
+}

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

@@ -1,44 +1,22 @@
 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.
-     */
+export interface Transcript {
     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 FileTranscript = Transcript & {
+    find(match: (message: TranscriptMessage) => boolean): Promise<TranscriptMessage | null>;
+};
 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;
@@ -46,46 +24,25 @@ export type TranscriptLayout = {
     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 transcriptPage(transcript: Transcript | null, { limit, before, cursor }?: AgentTranscriptRequest, found?: TranscriptFound): Promise<AgentTranscriptPage>;
 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 directoryNames(files: TranscriptFiles, dir: string): Promise<string[] | null>;
 export declare function prefetchedFiles(files: TranscriptFiles, path: string, size: number, pieces: {
     start: number;
     bytes: Uint8Array;

package/dist/agent/session/fileTranscript.js

@@ -7,40 +7,25 @@ export function sandboxFiles(sandbox) {
         listDirectory: (path) => sandbox.listDirectory(path),
     };
 }
-/** The file of conversation `nativeId` laid out as `layout` under `home`; null when there's none yet. */
 export function locateTranscript(files, home, layout, nativeId) {
     const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const [before = "", after = ""] = layout.name.split("{id}").map((part) => part.split("*").map(escape).join(".*"));
     const name = new RegExp(`^${before}${escape(nativeId)}${after}$`);
     return findFile(files, `${home}/${layout.dir}`, layout.depth, (entry) => name.test(entry));
 }
-/** How much of the file is read at a time. */
 export const CHUNK_BYTES = 64 * 1024;
-/**
- * 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 const TIME_SLACK_MS = 60_000;
-/** How many timed lines a probe of the bisection looks at: the earliest wins, so one odd line can't mislead it. */
 export const PROBE_LINES = 3;
-/** How much a probe reads, at most, before it gives up on finding a timed line (huge tool outputs). */
 export const PROBE_BYTES = 4 * CHUNK_BYTES;
 const NEWLINE = 0x0a;
-/** A line's time (epoch ms) from its `field`, null without a valid one. */
 function lineTime(entry, field) {
     const value = entry?.[field];
     const time = typeof value === "string" ? Date.parse(value) : NaN;
     return Number.isNaN(time) ? null : time;
 }
-/** How much is read at a time when searching the whole file for where stretches were written again. */
 const SCAN_BYTES = 1024 * 1024;
-/**
- * The stretches written again in the files searched last, by path and size: a search reads the whole
- * file, and a file the backend only appends to that hasn't grown has the same ones.
- */
 const searchedCopies = new Map();
 const SEARCHED_FILES = 16;
-/** `locate` finds the file; null when there's none yet (nothing stored). */
 export function createFileTranscript(files, locate, lineMessages, layout) {
     function parse(bytes, start) {
         try {
@@ -48,11 +33,9 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
             return { start, time: lineTime(entry, layout.time), messages: lineMessages(entry) };
         }
         catch {
-            // A line still being written (the last one), or one this reader doesn't know: nothing in it.
             return { start, time: null, messages: [] };
         }
     }
-    /** The stretches between `from` and `to` that aren't skipped, in order. */
     function kept(from, to, skip) {
         const parts = [];
         let start = from;
@@ -67,14 +50,12 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
             parts.push({ start, end: to });
         return parts;
     }
-    /** The file's lines before byte `end`, last first, read a chunk at a time, passing over `skip`. */
     async function* backward(path, end, skip = []) {
         for (const part of kept(0, end, skip).reverse())
             yield* backwardIn(path, part.start, part.end);
     }
     async function* backwardIn(path, floor, end) {
         let position = end;
-        // Bytes of a line that runs on into what was read before (later in the file).
         let carry = new Uint8Array(0);
         while (position > floor) {
             const from = Math.max(floor, position - CHUNK_BYTES);
@@ -94,7 +75,6 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
         if (carry.length > 0)
             yield parse(carry, floor);
     }
-    /** The file's lines from byte `start` to byte `end`, in order, read a chunk at a time, passing over `skip`. */
     async function* forward(path, start, end, skip = []) {
         for (const part of kept(start, end, skip))
             yield* forwardIn(path, part.start, part.end);
@@ -121,15 +101,9 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
         if (carry.length > 0)
             yield parse(carry, carryStart);
     }
-    /**
-     * Where the lines from time `target` on start, about, between `low` and `high`: the start of a line
-     * (or `high`) with only lines from before it, allowing for the slack, ahead of it. Bisects, each
-     * probe reading the times of the first few lines after its middle, passing over `skip`.
-     */
     async function seek(path, low, high, target, skip) {
         return (await narrow(path, low, high, target, skip)).high;
     }
-    /** seek's bisection: where it got, from both sides. */
     async function narrow(path, low, high, target, skip) {
         while (high - low > CHUNK_BYTES) {
             let middle = Math.floor((low + high) / 2);
@@ -143,7 +117,7 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
             }
             const probe = await probeTime(path, middle, high, skip);
             if (!probe)
-                break; // one line spans it all: start from where the search got
+                break;
             if (probe.time >= target)
                 high = probe.start;
             else
@@ -151,14 +125,13 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
         }
         return { low, high };
     }
-    /** The first line starting after `from` (before `limit`), with the earliest time of the next few timed lines. */
     async function probeTime(path, from, limit, skip) {
         let start = -1;
         let time = Infinity;
         let timed = 0;
         for await (const line of forward(path, from, Math.min(limit, from + PROBE_BYTES), skip)) {
             if (line.start === from && from > 0)
-                continue; // the middle of a line: only its end was read
+                continue;
             if (line.start >= limit)
                 break;
             if (start < 0)
@@ -171,25 +144,17 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
         }
         return start < 0 || timed === 0 ? null : { start, time };
     }
-    /** The time of the first timed line from `from` on (a line start), if there's one in reach. */
     async function timeAt(path, from, size, skip) {
         for await (const line of forward(path, from, Math.min(size, from + PROBE_BYTES), skip))
             if (line.time !== null)
                 return line.time;
         return null;
     }
-    /** Where the line holding byte `at` starts. */
     async function lineStart(path, at) {
         for await (const line of backward(path, at + 1))
             return line.start;
         return 0;
     }
-    /**
-     * The stretches the backend wrote again (TranscriptLayout.copies): each starts at a line with the
-     * marker whose time goes back from the timed line before it, and runs until a line is newer than
-     * that one. Found by searching the whole file for the marker; the rest only
-     * reads around what's found.
-     */
     function copiesOf(path, size) {
         if (!layout.copies)
             return Promise.resolve([]);
@@ -199,7 +164,6 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
             copies = findCopies(path, size, layout.copies);
             copies.catch(() => searchedCopies.delete(key));
             searchedCopies.set(key, copies);
-            // A few files' worth: a worker serves an agent's sessions.
             if (searchedCopies.size > SEARCHED_FILES)
                 searchedCopies.delete(searchedCopies.keys().next().value);
         }
@@ -209,7 +173,6 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
         const needle = Buffer.from(marker);
         const found = [];
         for (let position = 0; position < size; position += SCAN_BYTES) {
-            // Overlapping by the marker's length, so one across two reads is found.
             const from = Math.max(0, position - needle.length + 1);
             const bytes = Buffer.from(await files.readFileRange(path, from, Math.min(size, position + SCAN_BYTES)));
             for (let index = bytes.indexOf(needle); index >= 0; index = bytes.indexOf(needle, index + 1)) {
@@ -219,7 +182,6 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
         }
         const copies = [];
         for (const [index, at] of found.entries()) {
-            // The marker's line, and the timed line before it.
             const start = await lineStart(path, at);
             let earlier = null;
             for await (const before of backward(path, start)) {
@@ -235,13 +197,8 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
                 time = line.time;
                 break;
             }
-            // A compaction as it happened comes after what's before it (compacting takes a while: 25s and
-            // more); a copy starts back at its time.
             if (time === null || time >= earlier)
                 continue;
-            // It runs up to what was written before it, and ends with the first line newer than that. It
-            // holds what was said since a compaction, so it ends by the next marker: the rest of the file
-            // (other copies) can't mislead the search.
             const next = found[index + 1];
             const near = await narrow(path, start + 1, next === undefined ? size : await lineStart(path, next), earlier + 1, []);
             let end = near.high;
@@ -255,17 +212,9 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
         }
         return copies;
     }
-    /**
-     * The file's lines before `end`, last first, each with the time it's paged by: its own, unless it's
-     * odd, more than the slack away from both the timed lines around it in the same direction (a
-     * background task's result written minutes after it began, a note dated ahead), when it's the one
-     * before it's; a line without a time goes with the timed line after it. These times follow the file
-     * order to within the slack, so the late result is paged where it is in the conversation.
-     * `after`: the time of the first timed line from `end` on.
-     */
     async function* pagedBackward(path, end, after, skip) {
-        let next = after; // the time of the timed line after the one waiting
-        let waiting = []; // a timed line and the untimed ones before it, until the one before it is read
+        let next = after;
+        let waiting = [];
         const settle = function* (before) {
             const [timed, ...untimed] = waiting;
             if (!timed)
@@ -282,7 +231,6 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
         };
         for await (const line of backward(path, end, skip)) {
             if (line.time === null) {
-                // Before any timed line: it goes with the line after the end, or is the newest.
                 if (waiting.length === 0)
                     yield { ...line, time: next ?? Infinity };
                 else
@@ -302,11 +250,9 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
         const copies = found?.copies ?? (await copiesOf(path, size));
         const from = Math.min(found?.end ?? (before === null ? size : await seek(path, 0, size, before + TIME_SLACK_MS, copies)), size);
         const after = found ? found.after : from < size ? await timeAt(path, from, size, copies) : null;
-        // Read back until the page is full and a line is older than its oldest by more than the slack:
-        // nothing before it can belong on the page.
         const taken = [];
         let count = 0;
-        let oldest = Infinity; // the time of the page's limit-th newest message, once it's full
+        let oldest = Infinity;
         let older = false;
         for await (const line of pagedBackward(path, from, after, copies)) {
             if (count >= limit && line.time < oldest - TIME_SLACK_MS) {
@@ -320,8 +266,6 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
             if (count >= limit)
                 oldest = oldestOnPage(taken, limit);
         }
-        // The page: its newest messages by time, ties with the oldest of them included. A line's messages
-        // stay together, so a page can hold a message or so more than the limit.
         const kept = count >= limit ? taken.filter((line) => line.time >= oldest) : taken;
         if (kept.length < taken.length)
             older = true;
@@ -330,7 +274,6 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
             nextBefore: older && Number.isFinite(oldest) ? new Date(oldest).toISOString() : null,
         };
     }
-    // Passing over the copies too: a resumed session's stretch written again isn't replayed twice.
     async function replay(afterId, emit) {
         const path = await locate();
         if (!path)
@@ -361,9 +304,20 @@ export function createFileTranscript(files, locate, lineMessages, layout) {
         }
         return true;
     }
-    return { page, replay };
+    async function find(match) {
+        const path = await locate();
+        if (!path)
+            return null;
+        const end = await files.size(path);
+        for await (const line of backward(path, end, await copiesOf(path, end))) {
+            const found = line.messages.find(match);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    return { page, replay, find };
 }
-/** The time of the `limit`-th newest message of `lines`. */
 function oldestOnPage(lines, limit) {
     const newestFirst = [...lines].sort((a, b) => b.time - a.time);
     let count = 0;
@@ -386,7 +340,6 @@ function joined(first, second) {
 }
 const DEFAULT_PAGE_SIZE = 50;
 const MAX_PAGE_SIZE = 500;
-/** A page of the API's transcript (AgentTranscript.getTranscript); none stored for a session that never ran. */
 export async function transcriptPage(transcript, { limit, before, cursor } = {}, found) {
     const time = transcriptTime(before ?? cursor);
     if (!transcript)
@@ -395,7 +348,6 @@ export async function transcriptPage(transcript, { limit, before, cursor } = {},
     const page = await transcript.page(time, size, found);
     return { ...page, nextCursor: page.nextBefore };
 }
-/** AgentTranscriptRequest.before as epoch ms; null for none. */
 export function transcriptTime(before) {
     if (before === undefined)
         return null;
@@ -404,35 +356,27 @@ export function transcriptTime(before) {
         throw new AgentInvalidError(`invalid time ${before}: give an ISO 8601 time`);
     return time;
 }
-/**
- * The first file `depth` levels under `dir` whose name `matches` (the backends' own layouts, like
- * projects/<project>/<id>.jsonl), each level listed at once; null when there's none, or no `dir`.
- */
-async function findFile(files, dir, depth, matches) {
-    let names;
+export async function directoryNames(files, dir) {
     try {
-        names = await files.listDirectory(dir);
+        return await files.listDirectory(dir);
     }
     catch (error) {
         if (error instanceof SandboxNotFoundError)
             return null;
         throw error;
     }
+}
+async function findFile(files, dir, depth, matches) {
+    const names = await directoryNames(files, dir);
+    if (!names)
+        return null;
     if (depth <= 1) {
         const name = names.find(matches);
         return name === undefined ? null : `${dir}/${name}`;
     }
-    // Newest first, where names sort by date (codex's YYYY/MM/DD): a recent conversation is the likely one.
-    const found = await Promise.all(names.sort().reverse().map((name) => 
-    // One that isn't a directory has nothing below it.
-    findFile(files, `${dir}/${name}`, depth - 1, matches).catch(() => null)));
+    const found = await Promise.all(names.sort().reverse().map((name) => findFile(files, `${dir}/${name}`, depth - 1, matches).catch(() => null)));
     return found.find((path) => path !== null) ?? 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 function prefetchedFiles(files, path, size, pieces) {
     let more = Math.max(CHUNK_BYTES, ...pieces.map(({ bytes }) => bytes.length));
     return {

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

@@ -0,0 +1,5 @@
+import manifest from "../vendor-types/manifest.json";
+import type { AgentBackendInfo } from "../api.ts";
+export declare function pinnedVersion(vendor: keyof typeof manifest, pkg: string, sourcePackage?: string): string;
+export declare function installedPackage(installDir: string, pkg: string, version: string, executable: () => string): Promise<Omit<AgentBackendInfo, "backend">>;
+export declare function installPackage(installDir: string, pkg: string, version: string, executable: () => string): Promise<void>;