hyperbrane 0.1.2 → 0.2.1

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

@@ -1,82 +1,68 @@
-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. */
+import type { AgentBackendInfo, AgentBackgroundTasks, AgentInput, AgentInterrupt, AgentMessageQueue, AgentModels, AgentPermissionMode, AgentPermissionModes, AgentPermissionRequest, AgentPermissionResult, AgentQuestionRequest, AgentQuestionResponse, AgentSession, AgentStreamingMessage, AgentTurnUsage, SessionRef } from "../api.ts";
+import type { Transcript, TranscriptFiles } from "./fileTranscript.ts";
 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). */
+    permissionMode: AgentPermissionMode;
     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;
+    exited(exit: CliExit | null, error?: Error): void;
+    activeChanged(): void;
+    subagentStarted(toolUseId: string, subagentId: string): void;
+};
+export type CliExit = {
+    code: number | null;
+    signal: string | null;
 };
 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> & {
+export type RunningSession = ForSession<AgentInput & AgentInterrupt & AgentMessageQueue & AgentModels & AgentPermissionModes & AgentBackgroundTasks> & {
+    active(): boolean;
     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;
+    installDir: string;
 };
-/** 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">>;
+    installed(installDir: string): Promise<Omit<AgentBackendInfo, "backend">>;
     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). */
+    transcript(source: TranscriptSource): Transcript;
+    findSubagent(source: TranscriptSource, toolUseId: string): Promise<string | null>;
+    subagentTranscript(source: TranscriptSource, subagentId: string, toolUseId: string): Transcript;
+    usage(source: TranscriptSource): Promise<AgentTurnUsage[]>;
     homeEnvironment(home: string): Record<string, string>;
 };

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

@@ -1,2 +1 @@
-/** 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

@@ -1,4 +1,3 @@
-/** 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/provision.d.ts

@@ -0,0 +1,10 @@
+import type { AgentBackendInfo } from "../../api.ts";
+export declare const CLAUDE_SDK_PACKAGE = "../../../vendor-types/claude/agent-sdk/sdk.js";
+export declare function claudePackage(): {
+    pkg: string;
+    version: string;
+    executables: string;
+};
+export declare function installClaude(installDir: string): Promise<void>;
+export declare function installedClaude(installDir: string): Promise<Omit<AgentBackendInfo, "backend">>;
+export declare function claudeExecutable(installDir: string): string;

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,9 @@
 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 function claudeHome(env: Record<string, string>): string;
 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;
+}
+export 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;