hyperbrane 0.1.1 → 0.2.0

package/README.md

@@ -1,14 +1,15 @@
 # hyperbrane
 
 Dimensions (containers bound to a host directory), the portal gateways they reach the outside
-through, and agents (Claude Code, Codex) running in them, on a machine reached locally, over SSH, or
-as a Boat sandbox.
+through, and agents (Claude Code, Codex) running in them, on a machine reached locally, over SSH, as
+an exe.dev VM or as a Boat sandbox.
 
 ## Requirements
 
 - The library: Node ≥ 20.11 or Bun.
 - The CLI: Bun.
-- On the machine driven: docker, and python3 for accessible endpoints.
+- On the machine driven: docker, python3, and curl (or wget) to fetch bun once for gateways' transport
+  workers, unless the machine has bun 1.4.3 already.
 
 ## CLI
 
@@ -21,23 +22,91 @@ hyperbrane dimension create --dir ~/work -m 4G --cpus 2 work
 ## Library
 
 ```ts
-import { createServices, createSshSandbox, MemoryLimit, CPULimit } from "hyperbrane";
+import { createAgentClient, createDimensionClient, createGatewayClient, createPortalClient, createSandboxClient, MemoryLimit, CPULimit } from "hyperbrane";
 
-const host = createSshSandbox("server.example.com", { user: "me", privateKey });
-const { dimensions, agents } = createServices(host);
+const host = createSandboxClient({ kind: "ssh", sshHost: "server.example.com", sshUser: "me", sshKey: privateKey });
+// A client per part, over the sandbox: making one does nothing.
+const gateways = createGatewayClient(host);
+const dimensions = createDimensionClient(host);
+const portals = createPortalClient(host);
+const agents = createAgentClient(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");
 ```
 
-The root module exports the services, the sandboxes (`createLocalSandbox`, `createSshSandbox`,
-`createContainerSandbox`, `createBoatSandbox`), the endpoint auths and the agent client. For a
+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, each call over a
+connection of its own (SSH, Boat's API): nothing is kept between calls, so it runs in serverless
+functions too. A browser reaches the machine through data endpoints instead: ports the sandbox makes
+reachable, one per gateway, each served by its gateway's transport worker. Where they're reached is
+given when the sandbox is created:
+
+```ts
+// Data endpoints at server.example.com, on ports 8443-8542, each opened in ufw.
+await host.create({ name: "server", dataEndpointOptions: { url: "https://server.example.com", ports: { from: 8443, to: 8542 }, needsFirewall: true } });
+// An exe.dev VM, over exe.dev's SSH with a key added to the account; its endpoints behind exe.dev's proxy.
+const vm = createSandboxClient({ kind: "exe.dev", id: "bloggy", sshKey });
+// Boat's machine is the SDK's, created with its state saved in it.
+const boat = createSandboxClient({ kind: "boat", sshKey }); // BOAT_API_KEY; reaches nothing yet
+const [ctx] = await boat.create({ name: "box" }); // ctx, now with the sandbox's id, is what's kept
+// Elsewhere, with ctx alone: its operations read its state; open() resumes it first.
+const again = createSandboxClient(ctx);
+```
+
+Under a `url` with a root path, every endpoint is at `<url>/<name>` (with
+`dataEndpointOptions: { url: "https://server.example.com/hyb" }`, the gateway `main`'s is at
+`https://server.example.com/hyb/gateway-main`): whatever serves that path routes it to the endpoint's
+port, which `listEndpoints()` gives.
+
+A browser streams an agent through the gateway its dimension is wired to: hand the page
+`await gateways.endpoint("main")` (the gateway's URL and credentials, which expire in 12 hours) and
+the dimension's name, and it connects with
+`createWorkerClient(workerGatewayConnector(access, { dimensionName, agentName }))` from
+`hyperbrane/agent/client`. The agent's worker must be running (any call through `agents` starts it).
+On exe.dev the credentials carry a VM token, sent in `X-Exedev-Authorization` as exe.dev documents
+([HTTPS tokens for VMs](https://exe.dev/docs/https-tokens-for-vms.md)). A browser on another site
+can't get through to a private port: exe.dev answers the header's CORS preflight with a redirect to
+its login. There, give the endpoints a `url` with a root path on the VM's public port (the
+`https://<vm>.exe.xyz/hyb` of a server routing `/hyb/<name>` to each endpoint's port). A page
+can be told `EndpointUnreachableError` or `EndpointCredentialsError` (get new ones). Clients of one
+agent can share one connection: `sharedConnector(workerGatewayConnector(...))` opens it on first use
+and keeps it until `close()`.
+
+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 |
+| A gateway's transport worker (on the machine) | kept | kept | started again by `restartGateway` |
+| A dimension's transport worker (in it) | started again by `restartDimension` | started by `createDimension` | started again by `restartDimension` |
+| Portals | re-wired by `restartDimension` and `restartGateway`; otherwise as on the right | re-wired by the next agent call, or `portals.restorePortals()` | same |
+
+A Boat sandbox stops itself after a while; `sandbox.hasExpiration()` tells a sandbox that does, and
+`setExpiration` moves it.
+
+The root module exports the clients (`createDimensionClient`, `createGatewayClient`,
+`createPortalClient`, `createAgentClient`), the sandbox of any kind (`createSandboxClient`) and the
+agent's worker client. An upstream of your own is a `defineUpstream({ name, modes })`, given to a
+gateway with `registerUpstream` (the built-in ones are `BUILTIN_UPSTREAMS`). `dimensionLayout` says
+where a dimension keeps things: its workspace, run and state paths and CA bundle in the container,
+its directories and transport worker's socket on the machine, and its container's name.
+A client is an interface (`DimensionClient`, ...); these drive the machine from this process, through
+the services behind them, and another transport may implement the same interfaces. 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
+to read; a type marked `@sealed` (the clients, sandboxes, services) 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).
 
@@ -46,6 +115,7 @@ ones, until a breaking release (`bun run api:diff --breaking` shows what would b
 ```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
+bun run api:diff [FROM [TO]]  # how the public interface changed from FROM (HEAD) to TO (the working tree): git diff of just that
+bun run api:diff FROM..TO  # the same over a range of commits, e.g. v0.1.2..HEAD
+bun run api:diff --breaking [FROM [TO] | FROM..TO]  # only its breaking changes: removed, renamed, newly required, retyped
 ```

package/dist/agent/agentClient.d.ts

@@ -0,0 +1,5 @@
+import type { Sandbox } from "../sandbox/api.ts";
+import type { AgentClient, AgentProvision, AgentSessionCapabilities } from "./api.ts";
+export declare function createAgentClient(sandbox: Sandbox, options?: {
+    dataDirectory?: string;
+}): AgentClient & AgentProvision & AgentSessionCapabilities;

package/dist/agent/agentClient.js

@@ -0,0 +1,4 @@
+import { createAgentService } from "./agentService.js";
+export function createAgentClient(sandbox, options = {}) {
+    return createAgentService(sandbox, options);
+}

package/dist/agent/agentService.d.ts

@@ -1,32 +1,11 @@
-import type { DockerClient } from "../lib/docker.ts";
-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 { Sandbox } from "../sandbox/api.ts";
+import { type AgentClient, 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[]>;
+export interface AgentService extends AgentClient, AgentProvision, AgentSessionCapabilities {
 }
-/** 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: 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.
- */
-export declare const WORKER_SCRIPT = "/opt/hyperbrane/worker.js";
-/**
- * Runs each agent as a session worker inside its dimension (agent/session/main.ts) and talks
- * JSON-RPC to it over the worker's unix socket, which the host reaches through the dimension's
- * mounted run directory (through `host`). Keeps no state between calls beyond the agent records: every call finds
- * the worker again.
- */
-/**
- * `gatewaySignIns` tells whether a dimension's gateway already holds a backend's sign-in, so a
- * session's login can complete without anyone; without it every login waits for the user.
- */
-/**
- * `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 type AgentServiceWithSockets = AgentService & {
+    workerSocket(agentName: string): Promise<string>;
+};
+export declare function createAgentService(host: Sandbox, { dataDirectory }?: {
+    dataDirectory?: string;
+}): AgentServiceWithSockets;

package/dist/agent/agentService.js

@@ -1,127 +1,61 @@
-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 { dimensionLayout } from "../dimension/api.js";
+import { createDockerClient } from "../lib/docker.js";
 import { InvalidNameError, checkName } from "../lib/jsonDirectory.js";
-import { sleep } from "../lib/sleep.js";
-import { OS_CA_BUNDLE } from "../portal-gateway/portalService.js";
+import { createAgentStorage } from "./agentStorage.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_PROTOCOL } from "./session/worker/protocol.js";
+import { replacingWorkerClient } from "./workerReplacement.js";
+import { agentsDownScript, createAgentScript, installScript, listAgentsScript, listBackendsScript, workerSocketScript, listSessionsScript, loginStateScript, stopAgentScript, } from "./control.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: 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.
- */
-export const WORKER_SCRIPT = "/opt/hyperbrane/worker.js";
-const START_TIMEOUT_MS = 30_000;
-const STOP_TIMEOUT_MS = 10_000;
-/** The gateway upstream each backend's CLI signs in to (upstreams/). */
-const AUTH_UPSTREAMS = { claude: "anthropic", codex: "openai" };
-/** The worker's log in the dimension's run directory (RUN_PATH or its host side), next to its socket. */
-function workerLogPath(runDirectory, agentName) {
-    return `${runDirectory}/${agentName}.log`;
-}
-// Runs as the dimension's user and returns at once: the worker is detached from the exec, so it
-// outlives it (and every later command), until the container stops.
-const START_WORKER_SCRIPT = `set -eu
-nohup setsid bun "$HYB_WORKER_SCRIPT" >> "$HYB_LOG" 2>&1 < /dev/null &
-`;
-// Run when a worker won't stop, as the dimension's user, whom the worker and the CLIs it started run
-// as: they carry its agent in their environment, which root can't read in a container (docker gives
-// it no ptrace capability, and reading another user's environ takes one). The name comes in as
-// AGENT: this script itself mustn't match.
-const KILL_WORKER_SCRIPT = `for process in /proc/[0-9]*; do
-  if tr '\\0' '\\n' < "$process/environ" 2>/dev/null | grep -qx "HYB_AGENT=$AGENT"; then kill -9 "\${process#/proc/}" 2>/dev/null || true; fi
-done
-`;
-/**
- * Runs each agent as a session worker inside its dimension (agent/session/main.ts) and talks
- * JSON-RPC to it over the worker's unix socket, which the host reaches through the dimension's
- * mounted run directory (through `host`). Keeps no state between calls beyond the agent records: every call finds
- * the worker again.
- */
-/**
- * `gatewaySignIns` tells whether a dimension's gateway already holds a backend's sign-in, so a
- * session's login can complete without anyone; without it every login waits for the user.
- */
-/**
- * `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) {
-    const endpoints = "exposeEndpoint" in host ? host : null;
+import { createPortalClient } from "../portal-gateway/portalClient.js";
+export function createAgentService(host, { dataDirectory } = {}) {
+    const storage = createAgentStorage(host, dataDirectory);
+    const docker = createDockerClient(host);
+    const restoring = createPortalClient(host, { dataDirectory });
+    const controlOptions = { dataDirectory };
     async function runningDimension(dimensionName) {
-        const container = dimensionContainerName(dimensionName);
+        const container = dimensionLayout.containerName(dimensionName);
         const inspected = await docker.inspectContainer(container);
         if (inspected?.Config?.Labels?.["hyperbrane.dimension"] !== dimensionName) {
             throw new AgentNotFoundError(`dimension ${dimensionName} does not exist`);
         }
         if (!inspected.State?.Running)
             throw new AgentConflictError(`dimension ${dimensionName} is not running`);
-        const runDirectory = inspected.Mounts?.find((mount) => mount.Destination === RUN_PATH)?.Source;
-        const hasState = inspected.Mounts?.some((mount) => mount.Destination === STATE_PATH);
+        const runDirectory = inspected.Mounts?.find((mount) => mount.Destination === dimensionLayout.runPath())?.Source;
+        const hasState = inspected.Mounts?.some((mount) => mount.Destination === dimensionLayout.statePath());
         if (!runDirectory || !hasState) {
-            throw new AgentConflictError(`dimension ${dimensionName} lacks the ${RUN_PATH} and ${STATE_PATH} mounts agents need (it predates them); recreate it`);
+            throw new AgentConflictError(`dimension ${dimensionName} lacks the ${dimensionLayout.runPath()} and ${dimensionLayout.statePath()} 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) {
         return createWorkerClient(workerSocketConnector(host, workerSocketPath(dimension.runDirectory, agentName)));
     }
-    /**
-     * The worker, started again first if it isn't running: it doesn't come back with its container
-     * (a restart, a host reboot, a Boat sandbox resumed after its auto-stop). A connection that can't
-     * be made starts it, once, and is tried again.
-     */
-    function workerClient(dimension, agentName) {
-        const connect = workerSocketConnector(host, workerSocketPath(dimension.runDirectory, agentName));
-        const reviving = async (onNotification) => {
-            try {
-                return await connect(onNotification);
-            }
-            catch {
-                await reviveWorker(agentName, dimension);
-                return connect(onNotification);
-            }
-        };
-        return createWorkerClient(reviving);
-    }
-    // One start at a time per agent, however many calls find its worker gone.
     const reviving = new Map();
-    function reviveWorker(agentName, dimension) {
+    function reviveWorker(agentName, dimensionName, { replaceBuild = false } = {}) {
         let started = reviving.get(agentName);
         if (!started) {
-            started = ensureWorker(agentName, dimension)
+            const restorePortals = async () => restoring.restorePortals({ dimensionName });
+            const start = () => createAgentScript(host, { name: agentName, dimensionName }, { ...controlOptions, replaceBuild });
+            started = Promise.all([restorePortals(), start()])
+                .then(() => { })
                 .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 ensureWorker(agentName, dimension);
+                await docker.restartContainer(dimensionLayout.containerName(dimensionName));
+                await Promise.all([restorePortals(), start()]);
             })
                 .finally(() => reviving.delete(agentName));
             reviving.set(agentName, started);
         }
         return started;
     }
-    /**
-     * Starts the worker of every agent whose dimension runs but whose worker doesn't answer (after a
-     * restart took them down); returns their names. Agents whose dimension isn't running are left.
-     */
     async function restoreAgents() {
-        const restored = await Promise.all((await storage.listAgents()).map(async ({ name, dimensionName }) => {
-            const dimension = await runningDimension(dimensionName).catch(() => null);
-            if (!dimension)
-                return null;
-            if (await rawWorkerClient(dimension, name).call("worker/health", {}).then(() => true, () => false))
-                return null;
+        const restored = await Promise.all((await agentsDownScript(host, controlOptions)).map(async ({ name, dimensionName }) => {
             try {
-                await reviveWorker(name, dimension);
+                await reviveWorker(name, dimensionName);
                 return name;
             }
             catch (error) {
@@ -139,238 +73,72 @@ export function createAgentService(storage, docker, host, gatewaySignIns) {
         return agent;
     }
     async function clientFor(agentName) {
-        const agent = await requireAgent(agentName);
-        return workerClient(await runningDimension(agent.dimensionName), agentName);
+        assertValidName("agent", agentName);
+        const { dimensionName, socket } = await workerSocketScript(host, agentName, controlOptions);
+        return replacingWorkerClient(workerSocketConnector(host, socket), async (replaceBuild) => {
+            await runningDimension(dimensionName);
+            await reviveWorker(agentName, dimensionName, { replaceBuild });
+        });
     }
-    // Re-running replaces a worker running older code, and starts one that stopped with its container.
     async function createAgent(agent) {
         assertValidName("agent", agent.name);
         assertValidName("dimension", agent.dimensionName);
-        const dimension = await runningDimension(agent.dimensionName);
-        const record = await storage.insertAgent({ name: agent.name, dimensionName: agent.dimensionName });
-        if (record.dimensionName !== agent.dimensionName) {
-            throw new AgentConflictError(`agent ${agent.name} already exists in dimension ${record.dimensionName}`);
-        }
-        await ensureWorker(agent.name, dimension);
+        await createAgentScript(host, agent, controlOptions);
         return { name: agent.name, dimensionName: agent.dimensionName };
     }
-    async function ensureWorker(agentName, dimension) {
-        const { container, owner } = dimension;
-        const bundle = await workerBundle();
-        const client = rawWorkerClient(dimension, agentName);
-        const health = await client.call("worker/health", {}).catch(() => null);
-        if (health?.build === bundle.build)
-            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 },
-        });
-        if (setup.exitCode !== 0)
-            throw new Error(`preparing ${container} for agent ${agentName} failed: ${setup.stderr.trim()}`);
-        const sandbox = createContainerSandbox(docker, container);
-        await sandbox.writeFile(WORKER_SCRIPT, bundle.source);
-        await sandbox.writeFileExclusive(`${WORKER_DIR}/package.json`, JSON.stringify({ name: "hyperbrane-worker", private: true }, null, 2) + "\n");
-        // The gateway intercepts every connection, so installs must trust the bundle portals put its CA in.
-        await sandbox.writeFile(`${WORKER_DIR}/bunfig.toml`, `[install]\ncafile = "${OS_CA_BUNDLE}"\n`);
-        if (health)
-            await stopWorker(agentName, dimension);
-        // One that doesn't answer may still run (unreachable): it goes, rather than piling up.
-        else
-            await killWorker(agentName, dimension);
-        await startWorker(agentName, dimension, bundle, await socketOwner(agentName, dimension));
-    }
-    // The host user (uid:gid on the machine), asked once: it connects to workers' sockets.
-    let hostUser = null;
-    function hostUserIds() {
-        hostUser ??= host.runCommand(["sh", "-c", 'printf "%s:%s" "$(id -u)" "$(id -g)"']).then((result) => {
-            const [uid, gid] = result.stdout.trim().split(":").map(Number);
-            if (result.exitCode !== 0 || !Number.isInteger(uid) || !Number.isInteger(gid)) {
-                throw new Error(`reading the host user's ids failed: ${result.stderr.trim() || result.stdout.trim()}`);
-            }
-            return { uid: uid, gid: gid };
-        });
-        hostUser.catch(() => (hostUser = null));
-        return hostUser;
-    }
-    /**
-     * Who the worker's socket must belong to for the host user to connect (a unix socket takes write
-     * permission): no one else when the dimension runs as the host user; the host user when it runs
-     * as root (its directory belongs to root), which the worker then hands the socket to. A dimension
-     * of a third user can't be reached.
-     */
-    async function socketOwner(agentName, dimension) {
-        const runsAs = Number(dimension.owner.split(":")[0]);
-        const { uid, gid } = await hostUserIds();
-        if (runsAs === uid)
-            return undefined;
-        if (runsAs === 0)
-            return `${uid}:${gid}`;
-        throw new AgentConflictError(`agent ${agentName}'s worker would run as uid ${runsAs} (its dimension's directory belongs to that user), whose socket the host user (uid ${uid}) can't connect to; use a directory owned by uid ${uid} or root`);
-    }
-    async function startWorker(agentName, dimension, bundle, socketOwnerIds) {
-        const sandbox = createContainerSandbox(docker, dimension.container);
-        const home = await sandbox.homeDirectory();
-        const started = await sandbox.runCommand(["sh", "-c", START_WORKER_SCRIPT], {
-            cwd: home,
-            env: {
-                HOME: home,
-                HYB_AGENT: agentName,
-                HYB_LOG: workerLogPath(RUN_PATH, agentName),
-                HYB_INSTALL_DIR: WORKER_DIR,
-                HYB_WORKER_SCRIPT: WORKER_SCRIPT,
-                HYB_WORKER_BUILD: bundle.build,
-                ...(socketOwnerIds ? { HYB_SOCKET_OWNER: socketOwnerIds } : {}),
-                NODE_EXTRA_CA_CERTS: OS_CA_BUNDLE,
-                SSL_CERT_FILE: OS_CA_BUNDLE,
-            },
-        });
-        if (started.exitCode !== 0)
-            throw new Error(`starting agent ${agentName}'s worker failed: ${started.stderr.trim()}`);
-        const client = rawWorkerClient(dimension, agentName);
-        const deadline = Date.now() + START_TIMEOUT_MS;
-        let lastError = "";
-        while (Date.now() < deadline) {
-            const health = await client.call("worker/health", {}).catch((error) => {
-                lastError = error.message;
-                return null;
-            });
-            if (health?.build === bundle.build)
-                return;
-            await sleep(250);
-        }
-        const log = await host
-            .readFile(workerLogPath(dimension.runDirectory, agentName))
-            .then((bytes) => new TextDecoder().decode(bytes))
-            .catch(() => "");
-        // A socket the host user can't write to refuses it; Bun reports that as ENOENT, so say who owns it.
-        const socket = await host.stat(workerSocketPath(dimension.runDirectory, agentName)).catch(() => null);
-        const { uid } = await hostUserIds();
-        const owner = socket && socket.uid !== uid ? `; its socket belongs to uid ${socket.uid}, not the host user's ${uid}` : "";
-        throw new Error(`agent ${agentName}'s worker did not come up${lastError ? ` (reaching it: ${lastError}${owner})` : owner}:\n${log.slice(-2000)}`);
-    }
-    // Asked first, so sessions end cleanly; killed if it doesn't go.
-    async function stopWorker(agentName, dimension) {
-        const client = rawWorkerClient(dimension, agentName);
-        await client.call("worker/shutdown", {}).catch(() => { });
-        const deadline = Date.now() + STOP_TIMEOUT_MS;
-        while (Date.now() < deadline) {
-            if ((await client.call("worker/health", {}).catch(() => null)) === null)
-                return;
-            await sleep(250);
-        }
-        await killWorker(agentName, dimension);
-    }
-    async function killWorker(agentName, dimension) {
-        await createContainerSandbox(docker, dimension.container).runCommand(["sh", "-c", KILL_WORKER_SCRIPT], { env: { AGENT: agentName } });
-    }
     async function stopAgent(agentName) {
         assertValidName("agent", agentName);
-        const agent = await storage.readAgent(agentName);
-        if (!agent)
-            return;
-        await closeAgentEndpoints(agentName);
-        const dimension = await runningDimension(agent.dimensionName).catch(() => null);
-        if (dimension)
-            await stopWorker(agentName, dimension);
-        await storage.removeAgent(agentName);
+        await stopAgentScript(host, agentName, controlOptions);
     }
-    // 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.
-    async function exposeAgent(agentName, scheme, allowedOrigins = []) {
+    async function workerSocket(agentName) {
         const agent = await requireAgent(agentName);
-        if (!endpoints)
-            throw new AgentInvalidError("this host doesn't declare accessible endpoints");
         const dimension = await runningDimension(agent.dimensionName);
-        // 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))) {
-            await reviveWorker(agentName, dimension);
-        }
-        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;
-        }
-        if (stored) {
-            await endpoints.closeEndpoint(stored.id);
-            await storage.removeEndpoint(agentName, key);
-        }
-        const endpoint = await endpoints.exposeEndpoint({
-            target: { unix: workerSocketPath(dimension.runDirectory, agentName) },
-            scheme,
-            transport: "sse",
-            allowedOrigins,
-        });
-        await storage.saveEndpoint(agentName, key, endpoint);
-        return endpoint;
-    }
-    // Every way the host is reached: any sandbox on the machine can close them.
-    async function closeAgentEndpoints(agentName) {
-        const stored = Object.values(await storage.readEndpoints(agentName));
-        if (endpoints)
-            for (const endpoint of stored)
-                await endpoints.closeEndpoint(endpoint.id);
-        await storage.removeEndpoints(agentName);
+        const health = await rawWorkerClient(dimension, agentName).call("worker/health", {}).catch(() => null);
+        if (health?.protocol !== WORKER_PROTOCOL)
+            await reviveWorker(agentName, dimension.name);
+        return workerSocketPath(dimension.runDirectory, agentName);
     }
     async function listAgents() {
-        return (await storage.listAgents()).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        return (await listAgentsScript(host, controlOptions)).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     }
-    /** The client of the worker running `ref`'s agent. */
     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 { toolUseId } = 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) => {
-            try {
-                return await (await clientFor(agent.name)).call("session/list", {});
-            }
-            catch (error) {
-                console.warn(`listing agent ${agent.name}'s sessions failed:`, error.message);
-                return [];
-            }
-        }));
-        return perAgent.flat();
+        const stateDirectory = dimensionLayout.stateDirectory(await storage.dataDirectory(), agent.dimensionName);
+        const page = toolUseId === undefined ? await readHostTranscript(host, { stateDirectory, agentName: agent.name, sessionName: session }, { limit, before }) : null;
+        if (page)
+            return page;
+        const worker = await sessionClient(ref);
+        if (toolUseId !== undefined)
+            return worker.call("session/subagentTranscript", { session, toolUseId, limit, before });
+        return worker.call("session/transcript", { session, limit, before });
+    }
+    function listSessions() {
+        return listSessionsScript(host, controlOptions);
     }
     async function* getStream(ref, request) {
         yield* (await sessionClient(ref)).stream(ref.sessionName, request.after_id);
     }
-    // Only the host knows whether the dimension's gateway is signed in.
     async function login(ref) {
-        const agent = await requireAgent(ref.agentName);
-        const client = workerClient(await runningDimension(agent.dimensionName), ref.agentName);
-        const session = (await client.call("session/list", {})).find((candidate) => candidate.name === ref.sessionName);
-        if (!session)
-            throw new AgentNotFoundError(`session ${ref.sessionName} does not exist`);
-        const gatewaySignedIn = (await gatewaySignIns?.(agent.dimensionName, AUTH_UPSTREAMS[session.backend])) ?? false;
-        return client.call("auth/login", { session: ref.sessionName, gatewaySignedIn });
+        assertValidName("session", ref.sessionName);
+        const { gatewaySignedIn } = await loginStateScript(host, ref, controlOptions);
+        return (await clientFor(ref.agentName)).call("auth/login", { session: ref.sessionName, gatewaySignedIn });
     }
     return {
-        createAgent,
-        stopAgent,
+        createAgent: (agent) => createAgent(agent),
+        stopAgent: (agentName) => stopAgent(agentName),
         listAgents,
         listSessions,
         getStream,
-        login,
-        exposeAgent,
+        login: (ref) => login(ref),
+        workerSocket,
         restoreAgents,
-        install: async (agentName, backend) => void (await (await clientFor(agentName)).call("backend/install", { backend })),
+        install: (agentName, backend) => installScript(host, agentName, backend, controlOptions),
+        listBackends: (agentName) => listBackendsScript(host, agentName, controlOptions),
         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 })),
@@ -385,6 +153,7 @@ export function createAgentService(storage, docker, host, gatewaySignIns) {
         respondQuestionRequest: async (ref, request, response) => void (await (await sessionClient(ref)).call("question/respond", { session: ref.sessionName, request, response })),
         listModels: async (ref) => (await sessionClient(ref)).call("model/list", { session: ref.sessionName }),
         setModel: async (ref, model) => void (await (await sessionClient(ref)).call("model/set", { session: ref.sessionName, model })),
+        setPermissionMode: async (ref, mode) => void (await (await sessionClient(ref)).call("permission/mode", { session: ref.sessionName, mode })),
         listBackgroundTasks: async (ref) => (await sessionClient(ref)).call("task/list", { session: ref.sessionName }),
         stopTask: async (ref, task) => void (await (await sessionClient(ref)).call("task/stop", { session: ref.sessionName, task })),
         getAuthStatus: async (ref) => (await sessionClient(ref)).call("auth/status", { session: ref.sessionName }),