hyperbrane 0.1.0 → 0.1.1

package/README.md

@@ -30,12 +30,22 @@ await agents.createAgent({ name: "dev", dimensionName: "work" });
 ```
 
 The root module exports the services, the sandboxes (`createLocalSandbox`, `createSshSandbox`,
-`createContainerSandbox`, `createBoatSandbox`), the endpoint auths and the agent client. Every module
-is also reachable by its path, e.g. `hyperbrane/sandbox/sshService`.
+`createContainerSandbox`, `createBoatSandbox`), the endpoint auths and the agent client. For a
+browser, which can't take the server side along, the package also exports each part's API
+(`hyperbrane/sandbox/api`, `hyperbrane/dimension/api`, `hyperbrane/portal-gateway/api`,
+`hyperbrane/agent/api`) and the agent's worker client (`hyperbrane/agent/client`). Nothing else is
+importable.
+
+What a client may rely on, as the types say: a `readonly` field is set by the package, for the client
+to read; a type marked `@sealed` (the services, sandboxes, clients) is made by the package, for the
+client to use, not implement. Both may gain members in any release; anything else gains only optional
+ones, until a breaking release (`bun run api:diff --breaking` shows what would break).
 
 ## Building
 
 ```sh
 bun run build          # dist/
 bun run check:package  # packs it, installs the tarball elsewhere and uses it under Node and Bun
+bun run api:diff [REF]  # how the public interface changed since REF (HEAD): git diff of just that
+bun run api:diff --breaking [REF]  # only its breaking changes: removed, renamed, newly required, retyped
 ```

package/dist/agent/agentService.d.ts

@@ -3,6 +3,7 @@ import type { Sandbox, SandboxAccessibleEndpoint } from "../sandbox/api.ts";
 import type { AgentStorage } from "./agentStorage.ts";
 import type { GatewaySignIns } from "./gatewaySignIns.ts";
 import { type AgentClient, type AgentEndpoint, type AgentProvision, type AgentSessionCapabilities } from "./api.ts";
+/** @sealed */
 export interface AgentService extends AgentClient, AgentProvision, AgentSessionCapabilities, AgentEndpoint {
     /** Starts the workers that a restart took down (their dimension runs again); returns their agents' names. */
     restoreAgents(): Promise<string[]>;

package/dist/agent/agentService.js

@@ -1,3 +1,4 @@
+import { dimensionStateDirectory } from "../dimension/paths.js";
 import { RUN_PATH, STATE_PATH, containerName as dimensionContainerName } from "../dimension/service.js";
 import { createContainerSandbox } from "../sandbox/containerService.js";
 import { InvalidNameError, checkName } from "../lib/jsonDirectory.js";
@@ -6,7 +7,9 @@ import { OS_CA_BUNDLE } from "../portal-gateway/portalService.js";
 import { AgentConflictError, AgentInvalidError, AgentNotFoundError, } from "./api.js";
 import { createWorkerClient } from "./session/client.js";
 import { workerSocketConnector } from "./session/workerConnection.js";
+import { readHostTranscript } from "./hostTranscript.js";
 import { workerSocketPath } from "./session/sessionStorage.js";
+import { WORKER_PARAMS } from "./session/worker/workerParams.js";
 import { workerBundle } from "./workerBundle.js";
 /** In the dimension: where the backends are installed (a package with its node_modules). Shared by agents. */
 export const WORKER_DIR = "/opt/hyperbrane/worker";
@@ -320,6 +323,18 @@ export function createAgentService(storage, docker, host, gatewaySignIns) {
     async function sessionClient({ agentName }) {
         return clientFor(agentName);
     }
+    /**
+     * Read on the host from the dimension's state directory (hostTranscript.ts), so nothing has to run,
+     * neither the worker nor the dimension; only a session whose backend's home is elsewhere asks its
+     * worker.
+     */
+    async function getTranscript(ref, request = {}) {
+        const { session, limit, before } = WORKER_PARAMS["session/transcript"]({ session: ref.sessionName, ...request });
+        const agent = await requireAgent(ref.agentName);
+        const stateDirectory = dimensionStateDirectory(await storage.dataDirectory(), agent.dimensionName);
+        const page = await readHostTranscript(host, { stateDirectory, agentName: agent.name, sessionName: session }, { limit, before });
+        return page ?? (await sessionClient(ref)).call("session/transcript", { session, limit, before });
+    }
     // Agents whose dimension or worker is down have no sessions to show right now.
     async function listSessions() {
         const perAgent = await Promise.all((await storage.listAgents()).map(async (agent) => {
@@ -359,7 +374,7 @@ export function createAgentService(storage, docker, host, gatewaySignIns) {
         createSession: async (agentName, session) => (await clientFor(agentName)).call("session/create", { session }),
         updateSession: async (ref, limits) => (await sessionClient(ref)).call("session/update", { session: ref.sessionName, limits }),
         stopSession: async (ref) => void (await (await sessionClient(ref)).call("session/stop", { session: ref.sessionName })),
-        getTranscript: async (ref, request = {}) => (await sessionClient(ref)).call("session/transcript", { session: ref.sessionName, ...request }),
+        getTranscript,
         cancel: async (ref) => void (await (await sessionClient(ref)).call("session/interrupt", { session: ref.sessionName })),
         sendMessage: async (ref, message) => void (await (await sessionClient(ref)).call("session/send", { session: ref.sessionName, message })),
         getSessionStatus: async (ref) => (await sessionClient(ref)).call("session/status", { session: ref.sessionName }),

package/dist/agent/agentStorage.d.ts

@@ -9,6 +9,8 @@ export interface AgentStorage {
     /** No-op if missing. */
     removeAgent(agentName: string): Promise<void>;
     listAgents(): Promise<Agent[]>;
+    /** Hyperbrane's data directory these are kept in, with the dimensions' (see dimension/paths.ts). */
+    dataDirectory(): Promise<string>;
     /**
      * The agent's accessible endpoints (AgentService.exposeAgent), credentials included, by the
      * accessible host each was exposed for: one per way the machine is reached.

package/dist/agent/agentStorage.js

@@ -4,9 +4,10 @@ import { createJsonDirectory, defaultDataDir } from "../lib/jsonDirectory.js";
  * agents/<agent>.json, agent-endpoints/<agent>.json.
  */
 export function createAgentStorage(sandbox, dir) {
-    const agents = createJsonDirectory(sandbox, async () => `${dir ?? (await defaultDataDir(sandbox))}/agents`);
+    const dataDirectory = async () => dir ?? (await defaultDataDir(sandbox));
+    const agents = createJsonDirectory(sandbox, async () => `${await dataDirectory()}/agents`);
     // A record used to hold one endpoint; it is read as the entry for its URL's host:port.
-    const endpoints = createJsonDirectory(sandbox, async () => `${dir ?? (await defaultDataDir(sandbox))}/agent-endpoints`);
+    const endpoints = createJsonDirectory(sandbox, async () => `${await dataDirectory()}/agent-endpoints`);
     async function readEndpoints(agentName) {
         const record = await endpoints.read(agentName);
         if (!record)
@@ -44,6 +45,7 @@ export function createAgentStorage(sandbox, dir) {
         readAgent,
         removeAgent,
         listAgents,
+        dataDirectory,
         readEndpoints,
         saveEndpoint,
         removeEndpoint,

package/dist/agent/api.d.ts

@@ -30,18 +30,19 @@ export type AgentSessionLimits = Partial<Pick<AgentSession, "memoryLimit" | "cpu
  */
 export type AgentSessionState = "stopped" | "starting" | "idle" | "running" | "waiting" | "error";
 export type AgentSessionInfo = AgentSession & {
-    agentName: string;
-    status: AgentSessionState;
+    readonly agentName: string;
+    readonly status: AgentSessionState;
     /** The backend's own id for the conversation (claude's session id, codex's thread id), once known. */
-    nativeId: string | null;
+    readonly nativeId: string | null;
     /** Chosen through AgentModels; null for the backend's default. */
-    model: string | null;
+    readonly model: string | null;
 };
 /** Where a session lives: sessions are named per agent. */
 export type SessionRef = {
     agentName: string;
     sessionName: string;
 };
+/** @sealed */
 export interface AgentClient {
     /** PUT /v1/agents/:agentName — starts (or updates) the worker in the dimension. */
     createAgent(agent: Agent): Promise<Agent>;
@@ -83,13 +84,23 @@ export type AgentTranscriptMessage = Extract<AgentStreamingMessage, {
 export type AgentTranscriptRequest = {
     /** How many messages a page holds, about (a tool call and its result share a page); default 50, at most 500. */
     limit?: number;
-    /** A page's `nextCursor`, for the page before it; omitted for the newest page. */
+    /**
+     * An ISO 8601 time: the page holds the newest messages from before it (a page's `nextBefore`, for
+     * the page before that one); omitted for the newest page.
+     */
+    before?: string;
+    /** @deprecated `before` by its old name: a page's `nextCursor` is its `nextBefore`. */
     cursor?: string;
 };
-/** Newest pages first; each page's messages oldest first. */
+/**
+ * Newest pages first; each page's messages oldest first. `nextBefore` is the time of its oldest
+ * message, when there are older ones: every message of that time is on this page.
+ */
 export type AgentTranscriptPage = {
-    messages: AgentTranscriptMessage[];
-    nextCursor: string | null;
+    readonly messages: AgentTranscriptMessage[];
+    readonly nextBefore: string | null;
+    /** @deprecated `nextBefore` by its old name, for requests that give it as `cursor`. */
+    readonly nextCursor: string | null;
 };
 export type UserMessage = SDKUserMessage;
 /**
@@ -97,24 +108,24 @@ export type UserMessage = SDKUserMessage;
  * `can_use_tool` control request) isn't exported, so this mirrors it.
  */
 export type AgentPermissionRequest = {
-    id: string;
-    tool_name: string;
-    input: Record<string, unknown>;
-    tool_use_id: string;
+    readonly id: string;
+    readonly tool_name: string;
+    readonly input: Record<string, unknown>;
+    readonly tool_use_id: string;
     /** Why the agent asks, when it says (e.g. codex's reason for wanting network access). */
-    decision_reason?: string;
+    readonly decision_reason?: string;
 };
 export type AgentPermissionResult = PermissionResult;
 type AskUserQuestion = AskUserQuestionInput["questions"][number];
 /** A question of claude's AskUserQuestion tool; codex's may come with any number of options. */
 export type AgentQuestion = Omit<AskUserQuestion, "options"> & {
-    options: AskUserQuestion["options"][number][];
+    readonly options: AskUserQuestion["options"][number][];
 };
 /** The agent asking the user something (claude's AskUserQuestion, codex's request_user_input). */
 export type AgentQuestionRequest = {
-    id: string;
-    tool_use_id: string;
-    questions: AgentQuestion[];
+    readonly id: string;
+    readonly tool_use_id: string;
+    readonly questions: AgentQuestion[];
 };
 /**
  * AskUserQuestion's own answer: question text -> the chosen label (labels joined with ", " for a
@@ -138,20 +149,22 @@ export type AgentBackgroundTask = SDKBackgroundTasksChangedMessage["tasks"][numb
  * the code the page shows, when `needsCode`).
  */
 export type AgentAuthStatus = {
-    state: "signedIn";
+    readonly state: "signedIn";
 } | {
-    state: "signedOut"; /** Why the last sign-in failed, if one did. */
-    error?: string;
+    readonly state: "signedOut"; /** Why the last sign-in failed, if one did. */
+    readonly error?: string;
 } | {
-    state: "pending";
-    url: string;
-    userCode?: string;
-    needsCode: boolean;
+    readonly state: "pending";
+    readonly url: string;
+    readonly userCode?: string;
+    readonly needsCode: boolean;
 };
+/** @sealed */
 export interface AgentProvision {
     /** POST /v1/agents/:agentName/backends/:backend/install — installs the backend in the dimension, or updates it. */
     install(agentName: string, backend: AgentBackend): Promise<void>;
 }
+/** @sealed */
 export interface AgentEndpoint {
     /**
      * POST /v1/agents/:agentName/endpoint — the agent's worker, reachable from the client over the
@@ -163,6 +176,7 @@ export interface AgentEndpoint {
      */
     exposeAgent(agentName: string, scheme: SandboxEndpointScheme, allowedOrigins?: string[]): Promise<SandboxEndpoint>;
 }
+/** @sealed */
 export interface AgentStream {
     /**
      * GET /v1/agents/:agentName/sessions/:sessionName/stream?after_id= — the complete messages after
@@ -172,18 +186,21 @@ export interface AgentStream {
      */
     getStream(ref: SessionRef, req: AgentStreamingRequest): AsyncGenerator<AgentStreamingMessage>;
 }
+/** @sealed */
 export interface AgentTranscript {
     /**
-     * GET /v1/agents/:agentName/sessions/:sessionName/transcript?limit=&cursor= — a page of the
+     * GET /v1/agents/:agentName/sessions/:sessionName/transcript?limit=&before= (or &cursor=, its old name) — a page of the
      * conversation, read from the backend's own storage a piece at a time, so a conversation of any
      * length can be paged through.
      */
     getTranscript(ref: SessionRef, req?: AgentTranscriptRequest): Promise<AgentTranscriptPage>;
 }
+/** @sealed */
 export interface AgentInterrupt {
     /** POST /v1/agents/:agentName/sessions/:sessionName/interrupt — ends the current turn; pending permission requests are denied and questions dropped. */
     cancel(ref: SessionRef): Promise<void>;
 }
+/** @sealed */
 export interface AgentInput {
     /**
      * POST /v1/agents/:agentName/sessions/:sessionName/messages — resolves once the agent confirms it
@@ -192,10 +209,12 @@ export interface AgentInput {
      */
     sendMessage(ref: SessionRef, message: UserMessage): Promise<void>;
 }
+/** @sealed */
 export interface AgentSessionStatus {
     /** GET /v1/agents/:agentName/sessions/:sessionName/status */
     getSessionStatus(ref: SessionRef): Promise<AgentSessionState>;
 }
+/** @sealed */
 export interface AgentMessageQueue {
     /**
      * GET /v1/agents/:agentName/sessions/:sessionName/queue — from the agent (claude's command
@@ -205,24 +224,28 @@ export interface AgentMessageQueue {
      */
     getLastUserMessages(ref: SessionRef): Promise<AgentLastUserMessage[]>;
 }
+/** @sealed */
 export interface AgentPermissions {
     /** GET /v1/agents/:agentName/sessions/:sessionName/permission-requests — the ones still waiting. */
     listPermissionRequests(ref: SessionRef): Promise<AgentPermissionRequest[]>;
     /** POST /v1/agents/:agentName/sessions/:sessionName/permission-requests/:requestId */
     respondPermissionRequest(ref: SessionRef, requestId: string, result: AgentPermissionResult): Promise<void>;
 }
+/** @sealed */
 export interface AgentQuestions {
     /** GET /v1/agents/:agentName/sessions/:sessionName/question-requests — the ones still waiting. */
     listQuestionRequests(ref: SessionRef): Promise<AgentQuestionRequest[]>;
     /** POST /v1/agents/:agentName/sessions/:sessionName/question-requests/:requestId */
     respondQuestionRequest(ref: SessionRef, requestId: string, response: AgentQuestionResponse): Promise<void>;
 }
+/** @sealed */
 export interface AgentBackgroundTasks {
     /** GET /v1/agents/:agentName/sessions/:sessionName/background-tasks — those still running; none while the CLI isn't. */
     listBackgroundTasks(ref: SessionRef): Promise<AgentBackgroundTask[]>;
     /** POST /v1/agents/:agentName/sessions/:sessionName/background-tasks/:taskId/stop — ends the task. */
     stopTask(ref: SessionRef, taskId: string): Promise<void>;
 }
+/** @sealed */
 export interface AgentAuth {
     /** GET /v1/agents/:agentName/sessions/:sessionName/auth */
     getAuthStatus(ref: SessionRef): Promise<AgentAuthStatus>;
@@ -236,6 +259,7 @@ export interface AgentAuth {
     /** POST /v1/agents/:agentName/sessions/:sessionName/auth/code — finishes a pending sign-in that needs the page's code. */
     submitAuthCode(ref: SessionRef, code: string): Promise<AgentAuthStatus>;
 }
+/** @sealed */
 export interface AgentModels {
     /** GET /v1/agents/:agentName/sessions/:sessionName/models — starts the CLI if it isn't running. */
     listModels(ref: SessionRef): Promise<AgentModelInfo[]>;
@@ -246,8 +270,8 @@ export interface AgentModels {
 export type AgentSessionCapabilities = AgentStream & AgentTranscript & AgentInterrupt & AgentInput & AgentSessionStatus & AgentMessageQueue & AgentPermissions & AgentQuestions & AgentBackgroundTasks & AgentAuth & AgentModels;
 /** A message sent to a session, and whether its agent still holds it queued (not yet taken into a turn). */
 export type AgentLastUserMessage = {
-    message: UserMessage;
-    queued: boolean;
+    readonly message: UserMessage;
+    readonly queued: boolean;
 };
 /** The request can't be satisfied as sent (bad name, unknown backend, unknown after_id, ...). */
 export declare class AgentInvalidError extends Error {

package/dist/agent/client.d.ts

@@ -0,0 +1,3 @@
+export { createWorkerClient, type WorkerClient } from "./session/client.ts";
+export { sharedConnector, type SharedConnector } from "./session/sharedConnection.ts";
+export { EndpointLoginRequiredError, exeDevLoginUrl, workerSseConnector, type WorkerEndpoint } from "./session/workerSseConnection.ts";

package/dist/agent/client.js

@@ -0,0 +1,5 @@
+// An agent's worker, reached through its endpoint (AgentService.exposeAgent): what a browser can
+// import (hyperbrane/agent/client), since the root module brings the server side with it.
+export { createWorkerClient } from "./session/client.js";
+export { sharedConnector } from "./session/sharedConnection.js";
+export { EndpointLoginRequiredError, exeDevLoginUrl, workerSseConnector } from "./session/workerSseConnection.js";

package/dist/agent/hostTranscript.d.ts

@@ -0,0 +1,13 @@
+import type { Sandbox } from "../sandbox/api.ts";
+import { type AgentTranscriptPage, type AgentTranscriptRequest } from "./api.ts";
+/**
+ * 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 declare function readHostTranscript(host: Sandbox, { stateDirectory, agentName, sessionName }: {
+    stateDirectory: string;
+    agentName: string;
+    sessionName: string;
+}, { limit, before, cursor }: AgentTranscriptRequest): Promise<AgentTranscriptPage | null>;

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,80 @@
+import type { 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>;
+    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[];