hyperbrane 0.1.1 → 0.1.2

package/README.md

@@ -24,11 +24,39 @@ 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. For a
 browser, which can't take the server side along, the package also exports each part's API

package/dist/agent/agentService.d.ts

@@ -3,13 +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.
@@ -29,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

@@ -11,8 +11,14 @@ 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.
@@ -53,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);
@@ -68,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) {
@@ -97,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));
@@ -163,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);
@@ -278,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);
@@ -303,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;
@@ -371,6 +399,7 @@ 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 })),

package/dist/agent/api.d.ts

@@ -159,20 +159,40 @@ export type AgentAuthStatus = {
     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>;
 }
@@ -285,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

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

package/dist/agent/client.js

@@ -2,4 +2,4 @@
 // import (hyperbrane/agent/client), since the root module brings the server side with it.
 export { createWorkerClient } from "./session/client.js";
 export { sharedConnector } from "./session/sharedConnection.js";
-export { EndpointLoginRequiredError, exeDevLoginUrl, workerSseConnector } from "./session/workerSseConnection.js";
+export { EndpointLoginRequiredError, EndpointUnreachableError, exeDevLoginUrl, workerSseConnector } from "./session/workerSseConnection.js";

package/dist/agent/session/backend.d.ts

@@ -1,4 +1,4 @@
-import type { AgentBackgroundTasks, AgentInput, AgentInterrupt, AgentMessageQueue, AgentModels, AgentPermissionRequest, AgentPermissionResult, AgentQuestionRequest, AgentQuestionResponse, AgentSession, AgentSessionStatus, AgentStreamingMessage, SessionRef } from "../api.ts";
+import type { AgentBackendInfo, AgentBackgroundTasks, AgentInput, AgentInterrupt, AgentMessageQueue, AgentModels, AgentPermissionRequest, AgentPermissionResult, AgentQuestionRequest, AgentQuestionResponse, AgentSession, AgentSessionStatus, AgentStreamingMessage, SessionRef } from "../api.ts";
 import type { FileTranscript, TranscriptFiles } from "./fileTranscript.ts";
 /** A capability's calls for one session: those of api.ts, with the session already chosen. */
 export type ForSession<Capability> = {
@@ -71,6 +71,8 @@ export type TranscriptSource = {
 export type SessionBackend = {
     /** Installs the backend under `installDir`, or updates it to the pinned version. Runs in the dimension. */
     install(installDir: string): Promise<void>;
+    /** What's installed under `installDir`, and whether it's what install leaves: this release's version, complete. */
+    installed(installDir: string): Promise<Pick<AgentBackendInfo, "version" | "ready">>;
     start(context: SessionContext): Promise<RunningSession>;
     auth: BackendAuth;
     /** The conversation `nativeId` in the backend's own storage, which needs no CLI running. */

package/dist/agent/session/worker/protocol.d.ts

@@ -1,10 +1,12 @@
-import { type AgentAuthStatus, type AgentBackend, type AgentBackgroundTask, type AgentLastUserMessage, type AgentModelInfo, type AgentPermissionRequest, type AgentPermissionResult, type AgentQuestionRequest, type AgentQuestionResponse, type AgentSession, type AgentSessionInfo, type AgentSessionLimits, type AgentSessionState, type AgentStreamingMessage, type AgentTranscriptPage, type UserMessage } from "../../api.ts";
+import { type AgentAuthStatus, type AgentBackend, type AgentBackendInfo, type AgentBackgroundTask, type AgentLastUserMessage, type AgentModelInfo, type AgentPermissionRequest, type AgentPermissionResult, type AgentQuestionRequest, type AgentQuestionResponse, type AgentSession, type AgentSessionInfo, type AgentSessionLimits, type AgentSessionState, type AgentStreamingMessage, type AgentTranscriptPage, type UserMessage } from "../../api.ts";
 import type { JsonRpcErrorObject } from "./jsonRpc.ts";
 /**
  * The worker's JSON-RPC protocol, spoken over its unix socket (see createWorkerServer): method ->
  * [params, result]. Sessions are named by `session`; everything answers `null` unless it says.
  * worker/health and worker/shutdown are how the host tells a worker's build and replaces it: they
  * never change.
+ *
+ * @sealed
  */
 export type WorkerRequests = {
     "worker/health": [Record<string, never>, WorkerHealth];
@@ -13,6 +15,7 @@ export type WorkerRequests = {
     "backend/install": [{
         backend: AgentBackend;
     }, null];
+    "backend/list": [Record<string, never>, AgentBackendInfo[]];
     "session/create": [{
         session: AgentSession;
     }, AgentSessionInfo];

package/dist/agent/session/worker/protocol.js

@@ -1,10 +1,11 @@
-import { AgentConflictError, AgentInvalidError, AgentNotFoundError, } from "../../api.js";
+import { AgentBackendNotInstalledError, AgentConflictError, AgentInvalidError, AgentNotFoundError, } from "../../api.js";
 const METHOD_NOT_FOUND = -32601;
 const INVALID_PARAMS = -32602;
 const INTERNAL_ERROR = -32603;
 // Server-defined codes, for the Agent*Errors that aren't bad params.
 const NOT_FOUND = -32004;
 const CONFLICT = -32009;
+const BACKEND_NOT_INSTALLED = -32010;
 export class WorkerMethodNotFoundError extends Error {
     name = "WorkerMethodNotFoundError";
 }
@@ -15,6 +16,8 @@ export function encodeWorkerError(error) {
         return { code: INVALID_PARAMS, message };
     if (error instanceof AgentNotFoundError)
         return { code: NOT_FOUND, message };
+    if (error instanceof AgentBackendNotInstalledError)
+        return { code: BACKEND_NOT_INSTALLED, message };
     if (error instanceof AgentConflictError)
         return { code: CONFLICT, message };
     if (error instanceof WorkerMethodNotFoundError)
@@ -28,5 +31,7 @@ export function decodeWorkerError({ code, message }) {
         return new AgentNotFoundError(message);
     if (code === CONFLICT)
         return new AgentConflictError(message);
+    if (code === BACKEND_NOT_INSTALLED)
+        return new AgentBackendNotInstalledError(message);
     return new Error(`worker: ${message}`);
 }

package/dist/agent/session/worker/workerParams.js

@@ -8,6 +8,7 @@ export const WORKER_PARAMS = {
     "worker/health": () => ({}),
     "worker/shutdown": () => ({}),
     "backend/install": (params) => ({ backend: backend(params.backend) }),
+    "backend/list": () => ({}),
     "session/create": (params) => ({ session: session(object(params.session, "session")) }),
     "session/list": () => ({}),
     "session/update": (params) => ({ session: name(params), limits: limits(object(params.limits, "limits")) }),

package/dist/agent/session/workerSseConnection.d.ts

@@ -5,11 +5,27 @@ export { EndpointLoginRequiredError, exeDevLoginUrl, sseEvents } from "../../san
 export type WorkerEndpoint = Pick<SandboxEndpoint, "url" | "credentials">;
 /**
  * Connects to a worker through its accessible endpoint (AgentService.exposeAgent: the endpoint
- * proxy's "sse" transport), each connection an openSseConnection. Given a function, it asks it for
- * the endpoint before every connection, so a proxy that stopped is started again (exposeAgent does
- * that) before the client needs it. Runs in a browser as well as on a server. Aborting `signal`
- * closes every connection it opened (a stream waiting for the next message included).
+ * proxy's "sse" transport), each connection an openSseConnection. Runs in a browser as well as on a
+ * server. Aborting `signal` closes every connection it opened (a stream waiting for the next message
+ * included).
+ *
+ * Given a function (one that calls exposeAgent, through the page's server), it asks it once and
+ * keeps the endpoint; when a connection fails to open it asks again, which starts a proxy that
+ * stopped (an archived and resumed Boat sandbox, a reboot) at the same URL, and retries once. If that
+ * fails too it throws EndpointUnreachableError (or EndpointLoginRequiredError, for an exe.dev
+ * endpoint). Given an endpoint, it uses it as it is: one that stopped being served just fails.
  */
 export declare function workerSseConnector(endpoint: WorkerEndpoint | (() => Promise<WorkerEndpoint>), { signal }?: {
     signal?: AbortSignal;
 }): ConnectWorker;
+/**
+ * The worker's endpoint didn't answer, even once exposed again. A browser reports that as a CORS
+ * error whatever the cause: the page's origin isn't among the endpoint's allowedOrigins (give it to
+ * exposeAgent), or nothing answers at the endpoint's URL (the machine is unreachable, or the
+ * endpoint was closed).
+ */
+export declare class EndpointUnreachableError extends Error {
+    readonly url: string;
+    name: string;
+    constructor(url: string, cause?: unknown);
+}

package/dist/agent/session/workerSseConnection.js

@@ -1,18 +1,53 @@
-import { openSseConnection } from "../../sandbox/sseConnection.js";
+import { EndpointLoginRequiredError, openSseConnection } from "../../sandbox/sseConnection.js";
 import { workerConnectionOver } from "./workerConnection.js";
 export { EndpointLoginRequiredError, exeDevLoginUrl, sseEvents } from "../../sandbox/sseConnection.js";
 /**
  * Connects to a worker through its accessible endpoint (AgentService.exposeAgent: the endpoint
- * proxy's "sse" transport), each connection an openSseConnection. Given a function, it asks it for
- * the endpoint before every connection, so a proxy that stopped is started again (exposeAgent does
- * that) before the client needs it. Runs in a browser as well as on a server. Aborting `signal`
- * closes every connection it opened (a stream waiting for the next message included).
+ * proxy's "sse" transport), each connection an openSseConnection. Runs in a browser as well as on a
+ * server. Aborting `signal` closes every connection it opened (a stream waiting for the next message
+ * included).
+ *
+ * Given a function (one that calls exposeAgent, through the page's server), it asks it once and
+ * keeps the endpoint; when a connection fails to open it asks again, which starts a proxy that
+ * stopped (an archived and resumed Boat sandbox, a reboot) at the same URL, and retries once. If that
+ * fails too it throws EndpointUnreachableError (or EndpointLoginRequiredError, for an exe.dev
+ * endpoint). Given an endpoint, it uses it as it is: one that stopped being served just fails.
  */
 export function workerSseConnector(endpoint, { signal } = {}) {
+    let kept = null;
+    const current = (fresh) => {
+        if (typeof endpoint !== "function")
+            return Promise.resolve(endpoint);
+        if (fresh || !kept) {
+            const asked = endpoint();
+            kept = asked;
+            asked.catch(() => kept === asked && (kept = null));
+        }
+        return kept;
+    };
+    async function open() {
+        const first = await current(false);
+        try {
+            return [first, await openSseConnection(first, { signal })];
+        }
+        catch (error) {
+            if (typeof endpoint !== "function" || signal?.aborted)
+                throw error;
+        }
+        // Asked again unless another connection already did since.
+        const access = kept && (await kept) !== first ? await kept : await current(true);
+        try {
+            return [access, await openSseConnection(access, { signal })];
+        }
+        catch (error) {
+            if (signal?.aborted || error instanceof EndpointLoginRequiredError)
+                throw error;
+            throw new EndpointUnreachableError(access.url, error);
+        }
+    }
     return async (onNotification) => {
         signal?.throwIfAborted();
-        const access = typeof endpoint === "function" ? await endpoint() : endpoint;
-        const connection = await openSseConnection(access, { signal });
+        const [access, connection] = await open();
         const decoder = new TextDecoder();
         const encoder = new TextEncoder();
         const transport = {
@@ -24,3 +59,18 @@ export function workerSseConnector(endpoint, { signal } = {}) {
         return workerConnectionOver(transport, access.url.replace(/\/+$/, ""), onNotification);
     };
 }
+/**
+ * The worker's endpoint didn't answer, even once exposed again. A browser reports that as a CORS
+ * error whatever the cause: the page's origin isn't among the endpoint's allowedOrigins (give it to
+ * exposeAgent), or nothing answers at the endpoint's URL (the machine is unreachable, or the
+ * endpoint was closed).
+ */
+export class EndpointUnreachableError extends Error {
+    url;
+    name = "EndpointUnreachableError";
+    constructor(url, cause) {
+        super(`the agent's endpoint ${url} didn't answer, even once exposed again (a browser reports this as a CORS error): ` +
+            "is the page's origin among its allowedOrigins, and is the machine reachable?", { cause });
+        this.url = url;
+    }
+}