hyperbrane 0.1.0 → 0.1.2

package/README.md

@@ -24,18 +24,56 @@ hyperbrane dimension create --dir ~/work -m 4G --cpus 2 work
 import { createServices, createSshSandbox, MemoryLimit, CPULimit } from "hyperbrane";
 
 const host = createSshSandbox("server.example.com", { user: "me", privateKey });
-const { dimensions, agents } = createServices(host);
+const { gateways, dimensions, portals, agents } = createServices(host);
+// The gateway keeps the sign-ins, under its name: a gateway by another name starts with none.
+await gateways.createGateway({ name: "main" });
 await dimensions.createDimension({ name: "work", directory: "work", memoryLimit: MemoryLimit("4G"), cpuLimit: CPULimit("2") });
+// A dimension's only way out: before installing anything in it.
+await portals.createPortal({ name: "work-main", dimensionName: "work", gatewayName: "main" });
 await agents.createAgent({ name: "dev", dimensionName: "work" });
+await agents.install("dev", "claude");
 ```
 
+Each call resolves once what it made is usable: a gateway once it intercepts, a portal once traffic
+flows through it, an install once the backend runs. Re-running any of them converges.
+
+hyperbrane runs where the application does and drives the machine from there: over SSH, or for Boat
+through Boat's API, so the application needs nothing from the machine's own network or DNS. A
+browser reaches an agent through `agents.exposeAgent`'s endpoint, and give it the page's origin:
+origins add up, so a call without one removes nothing. The endpoint's URL lasts, but its proxy stops
+with a reboot or Boat archive, and a page connecting then sees a CORS error. `exposeAgent` starts it
+again, at the same URL: give `workerSseConnector` a function that calls it (through the page's server),
+and it does so again whenever a connection fails to open, then throws `EndpointUnreachableError` if
+that didn't help.
+
+What lasts:
+
+| | Container restart | Container recreated | Machine reboot, Boat resume |
+|---|---|---|---|
+| Workspace, sessions, sign-ins, installed backends | kept | kept | kept |
+| Agent workers | started again by the next call (or `agents.restoreAgents()`) | same | same |
+| Portals | re-wired by `restartDimension` and `restartGateway`; otherwise as on the right | re-wired by the next agent call, `portals.restorePortals()`, or `createPortalWatcher` (running) | same |
+
+A Boat sandbox stops itself after a while; `hasExpiration(sandbox)` tells a sandbox that does, and
+`setExpiration` moves it (`createBoatSandbox`'s own type has both).
+
 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,12 +3,18 @@ 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";
+import type { PortalService } from "../portal-gateway/portalService.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[]>;
 }
-/** In the dimension: where the backends are installed (a package with its node_modules). Shared by agents. */
-export declare const WORKER_DIR = "/opt/hyperbrane/worker";
+/**
+ * In the dimension: where the backends are installed (a package with its node_modules). Shared by
+ * agents. In the state directory, so they last as long as the dimension: a container recreated (or a
+ * machine whose docker kept nothing) doesn't take them, and nothing is installed twice.
+ */
+export declare const WORKER_DIR = "/var/lib/hyperbrane/worker";
 /**
  * In the dimension: the worker's script. Outside WORKER_DIR on purpose: bun caches the listing of the
  * directory a script is loaded from, and packages installed there afterwards didn't resolve.
@@ -28,4 +34,6 @@ export declare const WORKER_SCRIPT = "/opt/hyperbrane/worker.js";
  * `host` is the machine docker runs on: workers' sockets and logs are reached through it, and agents
  * are exposed through its endpoints when it declares them.
  */
-export declare function createAgentService(storage: AgentStorage, docker: DockerClient, host: Sandbox | (Sandbox & SandboxAccessibleEndpoint), gatewaySignIns?: GatewaySignIns): AgentService;
+export declare function createAgentService(storage: AgentStorage, docker: DockerClient, host: Sandbox | (Sandbox & SandboxAccessibleEndpoint), gatewaySignIns?: GatewaySignIns, 
+/** Re-wires a dimension's portals: what a restart (its container's, the machine's) took. */
+restoring?: Pick<PortalService, "restorePortals">): AgentService;

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,10 +7,18 @@ 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";
+/**
+ * In the dimension: where the backends are installed (a package with its node_modules). Shared by
+ * agents. In the state directory, so they last as long as the dimension: a container recreated (or a
+ * machine whose docker kept nothing) doesn't take them, and nothing is installed twice.
+ */
+export const WORKER_DIR = `${STATE_PATH}/worker`;
+/** Where they were before: moved to WORKER_DIR when a worker starts (ensureWorker). */
+const OLD_WORKER_DIR = "/opt/hyperbrane/worker";
 /**
  * In the dimension: the worker's script. Outside WORKER_DIR on purpose: bun caches the listing of the
  * directory a script is loaded from, and packages installed there afterwards didn't resolve.
@@ -50,7 +59,9 @@ done
  * `host` is the machine docker runs on: workers' sockets and logs are reached through it, and agents
  * are exposed through its endpoints when it declares them.
  */
-export function createAgentService(storage, docker, host, gatewaySignIns) {
+export function createAgentService(storage, docker, host, gatewaySignIns, 
+/** Re-wires a dimension's portals: what a restart (its container's, the machine's) took. */
+restoring) {
     const endpoints = "exposeEndpoint" in host ? host : null;
     async function runningDimension(dimensionName) {
         const container = dimensionContainerName(dimensionName);
@@ -65,7 +76,7 @@ export function createAgentService(storage, docker, host, gatewaySignIns) {
         if (!runDirectory || !hasState) {
             throw new AgentConflictError(`dimension ${dimensionName} lacks the ${RUN_PATH} and ${STATE_PATH} mounts agents need (it predates them); recreate it`);
         }
-        return { container, owner: inspected.Config.User || "0:0", runDirectory };
+        return { name: dimensionName, container, owner: inspected.Config.User || "0:0", runDirectory };
     }
     /** The worker as it is: for starting, stopping and checking on it. */
     function rawWorkerClient(dimension, agentName) {
@@ -94,11 +105,16 @@ export function createAgentService(storage, docker, host, gatewaySignIns) {
     function reviveWorker(agentName, dimension) {
         let started = reviving.get(agentName);
         if (!started) {
-            started = ensureWorker(agentName, dimension)
+            // Whatever took the worker down (a restart, a reboot, a Boat resume) took the dimension's
+            // portals too: without them the worker, and the backends it installs, can't reach anything.
+            const restorePortals = () => restoring?.restorePortals({ dimensionName: dimension.name });
+            started = Promise.resolve(restorePortals())
+                .then(() => ensureWorker(agentName, dimension))
                 .catch(async () => {
                 // Unreachable even freshly started: the container's mounts may no longer be the host's
                 // directories (it started while they were something else). A restart binds them again.
                 await docker.restartContainer(dimension.container);
+                await restorePortals();
                 await ensureWorker(agentName, dimension);
             })
                 .finally(() => reviving.delete(agentName));
@@ -160,9 +176,13 @@ export function createAgentService(storage, docker, host, gatewaySignIns) {
             return;
         const root = createContainerSandbox(docker, container, { user: "root" });
         // The run and state directories too: the host created them, possibly as another user than the dimension's.
-        const setup = await root.runCommand(["sh", "-c", 'mkdir -p "$W" && chown "$OWNER" "$(dirname "$W")" "$W" "$R" "$S"'], {
-            env: { W: WORKER_DIR, R: RUN_PATH, S: STATE_PATH, OWNER: owner },
-        });
+        // Backends installed where they used to be move along, once.
+        const setup = await root.runCommand([
+            "sh",
+            "-c",
+            'mkdir -p "$W" "$(dirname "$SCRIPT")" && chown "$OWNER" "$(dirname "$SCRIPT")" "$W" "$R" "$S" && ' +
+                '{ [ -e "$W/node_modules" ] || [ ! -d "$OLD/node_modules" ] || { cp -a "$OLD/." "$W/" && rm -rf "$OLD"; }; }',
+        ], { env: { W: WORKER_DIR, SCRIPT: WORKER_SCRIPT, OLD: OLD_WORKER_DIR, R: RUN_PATH, S: STATE_PATH, OWNER: owner } });
         if (setup.exitCode !== 0)
             throw new Error(`preparing ${container} for agent ${agentName} failed: ${setup.stderr.trim()}`);
         const sandbox = createContainerSandbox(docker, container);
@@ -275,23 +295,34 @@ export function createAgentService(storage, docker, host, gatewaySignIns) {
     // Lazy: the stored endpoint is served again if its proxy stopped (a reboot), with the same URL and
     // credentials. The proxy connects to the worker's socket per stream, so a worker restart is fine.
     // Each way the host is reached (its accessible host) has an endpoint of its own: several server
-    // records may drive the same machine.
+    // records may drive the same machine. Origins only add up: the endpoint is shared, and one caller's
+    // origins must not cut off another's pages (a narrower set closes nothing). What can run at once does.
     async function exposeAgent(agentName, scheme, allowedOrigins = []) {
-        const agent = await requireAgent(agentName);
         if (!endpoints)
             throw new AgentInvalidError("this host doesn't declare accessible endpoints");
+        const key = endpoints.accessibleHost;
+        const [agent, stored] = await Promise.all([requireAgent(agentName), storage.readEndpoints(agentName).then((all) => all[key])]);
         const dimension = await runningDimension(agent.dimensionName);
+        const [healthy, served] = await Promise.all([
+            rawWorkerClient(dimension, agentName).call("worker/health", {}).then(() => true, () => false),
+            stored && stored.credentials.scheme === scheme ? endpoints.ensureEndpoint(stored.id) : false,
+        ]);
         // The client connects to the worker's socket through the endpoint: nothing on its way could start
         // a worker a restart took down, so it's started here.
-        if (!(await rawWorkerClient(dimension, agentName).call("worker/health", {}).then(() => true, () => false))) {
+        if (!healthy)
             await reviveWorker(agentName, dimension);
+        const origins = [...new Set([...(stored?.allowedOrigins ?? []), ...allowedOrigins])];
+        if (stored && served) {
+            if (origins.every((origin) => stored.allowedOrigins.includes(origin)))
+                return stored;
+            // Same URL and credentials, so pages already connected stay connected.
+            if (await endpoints.updateEndpoint(stored.id, { allowedOrigins: origins })) {
+                const updated = { ...stored, allowedOrigins: origins };
+                await storage.saveEndpoint(agentName, key, updated);
+                return updated;
+            }
         }
-        const key = endpoints.accessibleHost;
-        const stored = (await storage.readEndpoints(agentName))[key];
-        const sameOrigins = (origins) => [...(origins ?? [])].sort().join("\n") === [...allowedOrigins].sort().join("\n");
-        if (stored && stored.credentials.scheme === scheme && sameOrigins(stored.allowedOrigins) && (await endpoints.ensureEndpoint(stored.id))) {
-            return stored;
-        }
+        // Another scheme, or it can't be served as it was given out (closed, its port taken).
         if (stored) {
             await endpoints.closeEndpoint(stored.id);
             await storage.removeEndpoint(agentName, key);
@@ -300,7 +331,7 @@ export function createAgentService(storage, docker, host, gatewaySignIns) {
             target: { unix: workerSocketPath(dimension.runDirectory, agentName) },
             scheme,
             transport: "sse",
-            allowedOrigins,
+            allowedOrigins: origins,
         });
         await storage.saveEndpoint(agentName, key, endpoint);
         return endpoint;
@@ -320,6 +351,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) => {
@@ -356,10 +399,11 @@ export function createAgentService(storage, docker, host, gatewaySignIns) {
         exposeAgent,
         restoreAgents,
         install: async (agentName, backend) => void (await (await clientFor(agentName)).call("backend/install", { backend })),
+        listBackends: async (agentName) => (await clientFor(agentName)).call("backend/list", {}),
         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,31 +149,54 @@ 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;
+};
+/**
+ * A backend in an agent's dimension: the version installed (null: none), and whether it's ready to
+ * run, i.e. this release's version, complete. Kept in the dimension's state directory, so it lasts as
+ * long as the dimension, its container recreated or not.
+ */
+export type AgentBackendInfo = {
+    readonly backend: AgentBackend;
+    readonly version: string | null;
+    readonly ready: boolean;
 };
+/** @sealed */
 export interface AgentProvision {
-    /** POST /v1/agents/:agentName/backends/:backend/install — installs the backend in the dimension, or updates it. */
+    /**
+     * POST /v1/agents/:agentName/backends/:backend/install — installs the backend in the dimension, or
+     * updates it, or completes it; nothing to do when it's ready. Downloads through the dimension's portals.
+     */
     install(agentName: string, backend: AgentBackend): Promise<void>;
+    /** GET /v1/agents/:agentName/backends — each backend, as installed in the agent's dimension. */
+    listBackends(agentName: string): Promise<AgentBackendInfo[]>;
 }
+/** @sealed */
 export interface AgentEndpoint {
     /**
      * POST /v1/agents/:agentName/endpoint — the agent's worker, reachable from the client over the
      * network (workerSseConnector speaks to it), authenticated by `scheme`, callable from pages of
-     * `allowedOrigins`. Call it before each connection: it starts the endpoint's proxy again if that
-     * stopped, keeping the same URL and credentials; a new endpoint only for another scheme or origins,
-     * or once the old one can't be served (closed, its port taken). Closed with the agent. Needs a host
-     * that declares endpoints.
+     * `allowedOrigins`. Its URL lasts, but the proxy behind it doesn't: an archived and resumed Boat
+     * sandbox, or a reboot, stops it, and a page connecting then gets what a browser reports as a CORS
+     * error. This call (three round trips to the host when nothing changed) starts the agent's worker
+     * and the endpoint's proxy again if they stopped, keeping the same URL and credentials: give
+     * workerSseConnector a function that calls it, and it calls it again whenever a connection fails
+     * to open; an endpoint kept elsewhere goes stale. Origins add up: those given join the endpoint's own, in place, so
+     * pages already connected stay connected, and a call with fewer (or none) removes nothing. A new
+     * endpoint only for another scheme, or once the old one can't be served (its port taken); the old
+     * one's connections end then. Closed with the agent. Needs a host that declares endpoints.
      */
     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 +206,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 +229,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 +244,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 +279,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 +290,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 {
@@ -261,4 +305,11 @@ export declare class AgentNotFoundError extends Error {
 export declare class AgentConflictError extends Error {
     name: string;
 }
+/**
+ * The session's backend isn't installed in its dimension, or not completely (AgentBackendInfo.ready):
+ * AgentProvision.install puts it there. A conflict with the dimension's state, so caught as one too.
+ */
+export declare class AgentBackendNotInstalledError extends AgentConflictError {
+    name: string;
+}
 export {};

package/dist/agent/api.js

@@ -12,3 +12,10 @@ export class AgentNotFoundError extends Error {
 export class AgentConflictError extends Error {
     name = "AgentConflictError";
 }
+/**
+ * The session's backend isn't installed in its dimension, or not completely (AgentBackendInfo.ready):
+ * AgentProvision.install puts it there. A conflict with the dimension's state, so caught as one too.
+ */
+export class AgentBackendNotInstalledError extends AgentConflictError {
+    name = "AgentBackendNotInstalledError";
+}

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, EndpointUnreachableError, 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, EndpointUnreachableError, 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>;