hyperbrane 0.1.2 → 0.2.1

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,10 +22,14 @@ 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 { gateways, dimensions, portals, agents } = createServices(host);
+import { createAgentClient, createDimensionClient, createGatewayClient, createPortalClient, createSandboxClient, listSandboxes, MemoryLimit, CPULimit } from "hyperbrane";
+
+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") });
@@ -32,19 +37,72 @@ await dimensions.createDimension({ name: "work", directory: "work", memoryLimit:
 await portals.createPortal({ name: "work-main", dimensionName: "work", gatewayName: "main" });
 await agents.createAgent({ name: "dev", dimensionName: "work" });
 await agents.install("dev", "claude");
+// A command in the dimension, as its user, in its workspace unless given a cwd.
+const { exitCode, stdout } = await dimensions.runCommand("work", ["git", "status"], { cwd: "repo" });
 ```
 
 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.
+`sshKey` is an unencrypted private key, in OpenSSH format (as `ssh-keygen` writes it), PKCS#8 (as
+Node's `crypto` exports Ed25519, RSA and ECDSA keys), PKCS#1 (RSA) or SEC1 (ECDSA).
+
+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);
+// Or found by its name, with the API key alone: every sandbox the key sees, and names can repeat.
+const [found] = (await listSandboxes({ kind: "boat" })).filter((sandbox) => sandbox.name === "box");
+```
+
+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()`.
+
+Code running in a dimension (a script a session runs, a service in the workspace) drives the
+dimension's agents over their workers' sockets, under `/run/hyperbrane`:
+
+```ts
+import { createDimensionAgentClient, currentSession } from "hyperbrane";
+
+const agents = createDimensionAgentClient();
+const me = currentSession(); // the session this code runs under ({ agentName, sessionName }), or null
+await agents.createSession(me!.agentName, { name: "helper", backend: "claude", memoryLimit: MemoryLimit("2G"), cpuLimit: CPULimit("1") });
+```
+
+It does what the agents' workers do: sessions, their streams, transcripts, permissions and the
+rest, and installing backends. Making or stopping agents, and starting their workers, take the
+machine: `listAgents()` names the agents whose workers run, and a call to an agent whose worker
+doesn't gets `AgentConflictError` until a call through the machine's `agents` starts it. Its
+`login` doesn't know whether the gateway already holds a sign-in, so it signs in as the backend
+does. Anything in the dimension can drive its agents this way, a session itself included.
 
 What lasts:
 
@@ -52,20 +110,43 @@ What lasts:
 |---|---|---|---|
 | 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 gateway's transport worker (on the machine) | kept | kept | started again by `restore` (or `gateways.restoreGateways()`) |
+| A dimension's transport worker (in it) | started again by `restartDimension` or `restore` | started by `createDimension` | started again by `restore` (or `dimensions.restoreDimensions()`) |
+| Portals | re-wired by `restartDimension` and `restartGateway`; otherwise as on the right | re-wired by the next agent call, or `portals.restorePortals()` | same |
+
+After a reboot or a Boat resume, one call starts again whatever didn't survive, in the order it
+needs: the gateways' transport workers and the dimensions' (without restarting their containers),
+then the portals, then the agents' workers. It's safe to call any time, and does nothing more where
+everything runs:
+
+```ts
+import { restore } from "hyperbrane";
+
+await sandbox.open(); // resumes a stopped Boat sandbox
+const { gateways, dimensions, agents } = await restore(sandbox); // what it started again
+```
+
+A Boat sandbox stops itself after a while; `sandbox.hasExpiration()` tells a sandbox that does, and
+`setExpiration` moves it.
 
-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).
+On Boat, `readFile`, `readFileRange`, `writeFile` and `writeFileExclusive` reach what Boat's file API
+does: files under `/home/user` and `/tmp`. Another path is a `SandboxPathError`, which says why.
 
-The root module exports the services, the sandboxes (`createLocalSandbox`, `createSshSandbox`,
-`createContainerSandbox`, `createBoatSandbox`), the endpoint auths and the agent client. For a
+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).
 
@@ -74,6 +155,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,39 +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 { PortalService } from "../portal-gateway/portalService.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. 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.
- */
-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, 
-/** Re-wires a dimension's portals: what a restart (its container's, the machine's) took. */
-restoring?: Pick<PortalService, "restorePortals">): AgentService;
+export type AgentServiceWithSockets = AgentService & {
+    workerSocket(agentName: string): Promise<string>;
+};
+export declare function createAgentService(host: Sandbox, { dataDirectory }?: {
+    dataDirectory?: string;
+}): AgentServiceWithSockets;