hyperbrane 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# 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.
+
+## Requirements
+
+- The library: Node ≥ 20.11 or Bun.
+- The CLI: Bun.
+- On the machine driven: docker, and python3 for accessible endpoints.
+
+## CLI
+
+```sh
+bun add -g hyperbrane
+hyperbrane --help
+hyperbrane dimension create --dir ~/work -m 4G --cpus 2 work
+```
+
+## Library
+
+```ts
+import { createServices, createSshSandbox, MemoryLimit, CPULimit } from "hyperbrane";
+
+const host = createSshSandbox("server.example.com", { user: "me", privateKey });
+const { dimensions, agents } = createServices(host);
+await dimensions.createDimension({ name: "work", directory: "work", memoryLimit: MemoryLimit("4G"), cpuLimit: CPULimit("2") });
+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`.
+
+## Building
+
+```sh
+bun run build          # dist/
+bun run check:package  # packs it, installs the tarball elsewhere and uses it under Node and Bun
+```

package/dist/agent/agentService.d.ts

@@ -0,0 +1,31 @@
+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";
+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: 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;

package/dist/agent/agentService.js

@@ -0,0 +1,388 @@
+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";
+import { sleep } from "../lib/sleep.js";
+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 { workerSocketPath } from "./session/sessionStorage.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;
+    async function runningDimension(dimensionName) {
+        const container = dimensionContainerName(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);
+        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 };
+    }
+    /** 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) {
+        let started = reviving.get(agentName);
+        if (!started) {
+            started = 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 ensureWorker(agentName, dimension);
+            })
+                .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;
+            try {
+                await reviveWorker(name, dimension);
+                return name;
+            }
+            catch (error) {
+                console.warn(`starting agent ${name}'s worker failed:`, error.message);
+                return null;
+            }
+        }));
+        return restored.filter((name) => name !== null);
+    }
+    async function requireAgent(agentName) {
+        assertValidName("agent", agentName);
+        const agent = await storage.readAgent(agentName);
+        if (!agent)
+            throw new AgentNotFoundError(`agent ${agentName} does not exist`);
+        return agent;
+    }
+    async function clientFor(agentName) {
+        const agent = await requireAgent(agentName);
+        return workerClient(await runningDimension(agent.dimensionName), agentName);
+    }
+    // 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);
+        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);
+    }
+    // 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 = []) {
+        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);
+    }
+    async function listAgents() {
+        return (await storage.listAgents()).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);
+    }
+    // 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();
+    }
+    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 });
+    }
+    return {
+        createAgent,
+        stopAgent,
+        listAgents,
+        listSessions,
+        getStream,
+        login,
+        exposeAgent,
+        restoreAgents,
+        install: async (agentName, backend) => void (await (await clientFor(agentName)).call("backend/install", { backend })),
+        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 }),
+        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 }),
+        getLastUserMessages: async (ref) => (await sessionClient(ref)).call("session/lastUserMessages", { session: ref.sessionName }),
+        listPermissionRequests: async (ref) => (await sessionClient(ref)).call("permission/list", { session: ref.sessionName }),
+        respondPermissionRequest: async (ref, request, result) => void (await (await sessionClient(ref)).call("permission/respond", { session: ref.sessionName, request, result })),
+        listQuestionRequests: async (ref) => (await sessionClient(ref)).call("question/list", { session: ref.sessionName }),
+        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 })),
+        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 }),
+        submitAuthCode: async (ref, code) => (await sessionClient(ref)).call("auth/code", { session: ref.sessionName, code }),
+    };
+}
+function assertValidName(kind, name) {
+    try {
+        checkName(name);
+    }
+    catch (error) {
+        if (error instanceof InvalidNameError)
+            throw new AgentInvalidError(`invalid ${kind} name: ${error.message}`);
+        throw error;
+    }
+}

package/dist/agent/agentStorage.d.ts

@@ -0,0 +1,27 @@
+import type { Sandbox, SandboxEndpoint } from "../sandbox/api.ts";
+import type { Agent } from "./api.ts";
+/** Every name must pass checkName; operations throw InvalidNameError otherwise. */
+export interface AgentStorage {
+    /** Stores the record unless one with that name exists; returns whichever record is stored afterwards. */
+    insertAgent(agent: Agent): Promise<Agent>;
+    /** Null if missing. */
+    readAgent(agentName: string): Promise<Agent | null>;
+    /** No-op if missing. */
+    removeAgent(agentName: string): Promise<void>;
+    listAgents(): Promise<Agent[]>;
+    /**
+     * The agent's accessible endpoints (AgentService.exposeAgent), credentials included, by the
+     * accessible host each was exposed for: one per way the machine is reached.
+     */
+    readEndpoints(agentName: string): Promise<Record<string, SandboxEndpoint>>;
+    saveEndpoint(agentName: string, accessibleHost: string, endpoint: SandboxEndpoint): Promise<void>;
+    /** No-op if missing. */
+    removeEndpoint(agentName: string, accessibleHost: string): Promise<void>;
+    /** All of them. No-op if none. */
+    removeEndpoints(agentName: string): Promise<void>;
+}
+/**
+ * `dir` is a sandbox path; defaults to ~/.local/share/hyperbrane of the sandbox's user. Layout:
+ * agents/<agent>.json, agent-endpoints/<agent>.json.
+ */
+export declare function createAgentStorage(sandbox: Sandbox, dir?: string): AgentStorage;

package/dist/agent/agentStorage.js

@@ -0,0 +1,52 @@
+import { createJsonDirectory, defaultDataDir } from "../lib/jsonDirectory.js";
+/**
+ * `dir` is a sandbox path; defaults to ~/.local/share/hyperbrane of the sandbox's user. Layout:
+ * agents/<agent>.json, agent-endpoints/<agent>.json.
+ */
+export function createAgentStorage(sandbox, dir) {
+    const agents = createJsonDirectory(sandbox, async () => `${dir ?? (await defaultDataDir(sandbox))}/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`);
+    async function readEndpoints(agentName) {
+        const record = await endpoints.read(agentName);
+        if (!record)
+            return {};
+        if (typeof record.id === "string")
+            return { [new URL(record.url).host]: record };
+        return record;
+    }
+    async function saveEndpoint(agentName, accessibleHost, endpoint) {
+        await endpoints.save(agentName, { ...(await readEndpoints(agentName)), [accessibleHost]: endpoint });
+    }
+    async function removeEndpoint(agentName, accessibleHost) {
+        const { [accessibleHost]: removed, ...rest } = await readEndpoints(agentName);
+        if (!removed)
+            return;
+        if (Object.keys(rest).length === 0)
+            await endpoints.remove(agentName);
+        else
+            await endpoints.save(agentName, rest);
+    }
+    async function insertAgent(agent) {
+        return agents.insert(agent.name, agent);
+    }
+    async function readAgent(agentName) {
+        return agents.read(agentName);
+    }
+    async function removeAgent(agentName) {
+        await agents.remove(agentName);
+    }
+    async function listAgents() {
+        return agents.list();
+    }
+    return {
+        insertAgent,
+        readAgent,
+        removeAgent,
+        listAgents,
+        readEndpoints,
+        saveEndpoint,
+        removeEndpoint,
+        removeEndpoints: (agentName) => endpoints.remove(agentName),
+    };
+}