@nylorun/runtime 0.52.0-beta → 0.53.1-beta

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.53.1-beta
+
+### Patch Changes
+
+- 7c9a325: The Runtime's Helm chart, as tested on GKE with Cloud SQL and GCS: tokens and the admin key as 32
+  bytes of hex (a kept value in another form is replaced); the Restate worker and the Harness API
+  through `<name>-runtime-internal`, which publishes the runtime before it is ready; probes with a
+  loopback `Host`; Studio's image by its own version (`nylorun.com/studio-version`, kept by the
+  release); an external Postgres needs no C-collation database.
+
+## 0.53.0-beta
+
+### Minor Changes
+
+- 5b49361: A pod Agent on an Agent Substrate cluster can be a computer (ADR-149, ADR-150): with `NYLORUN_SANDBOX_GATEWAY_URL` and `NYLORUN_COMPUTER_TICKET_KEY_FILE` set (the Runtime's Helm chart sets both), its sessions' runs go to the harness container, and their sandbox tools, file reads and writes, skill folders and disk versions reach the Agent's actor through the sandbox gateway and `atenet-router`, with a ticket core signs (Ed25519). The engine's `--service computer` runs no loop: it serves commands (a start and attaches, each under 50 s) and files on port 8080, checks each ticket against the key its template carries, and answers the wake-up probe on `/ready`. A harness opens a computer with `computer.open`; core wakes it, waits until it is ready, writes a seed onto a new disk, runs the disk's setup through it and passes a version's start check. The tools, `runtime.json` and every other backend are unchanged.
+
+  - `@nylorun/core`: Harness API 5.6 (`harness-api/v5.6.json`): `routing.sandbox.computer` and the request `computer.open`.
+  - `@nylorun/runtime`: `--service computer`; the `computer` sandbox backend; `NYLORUN_SANDBOX_GATEWAY_URL` and `NYLORUN_COMPUTER_TICKET_KEY_FILE`.
+
+- 0cb752d: The Runtime's Helm chart, `charts/nylorun-runtime` (ADR-147, the Runtime on Kubernetes plan): the Runtime on an Agent Substrate cluster, with computers. It installs core, the gateway, the harness, Studio, the sandboxes service in the cluster, the sandbox gateway (atenet-router's client), Restate on a disk and s2-lite with its streams in the object store; Postgres and the object store are an external URL and S3 endpoint, or bundled (Postgres, RustFS). It makes the Runtime's secrets once and keeps them, and optionally pre-pulls images on worker nodes and makes the Tenant's atespace. Its README says what Substrate needs (the router's allowlist, the atespace) and has a GCP example.
+- f2ef233: The sandboxes service runs in the cluster it drives, and Agent Substrate sandboxes can be computers (ADR-149, the Runtime on Kubernetes plan). `cluster.json`'s `inCluster: true` uses the pod's ServiceAccount and reaches Substrate's API by its Service with a projected token; `substrate.computer` renders every sandbox as a computer: its engine runs `--service computer`, with no join token, edge or edge rule, a wake-up probe on `/ready`, and the ticket key's public half. `sandboxes gateway` is the sandbox gateway (ADR-148): it checks a computer ticket and proxies to the computer through an mTLS CONNECT tunnel to `atenet-router`.
+
+### Patch Changes
+
+- becf6a2: A computer runs our engine whatever harness drives its Agent: an Agent with a custom harness runs it through the Harness API, and its image is its computer. The chart sets numeric users for `runAsNonRoot`, uses the sandboxes service's `/health` for readiness (its `/ready` waits for the atespace the post-install Job makes), and says that Substrate's API admits only namespaces labelled `ate.dev/api-access=true`. Docs: Harness API §9b (computers), Kubernetes in SELF_HOSTING.md, and a MIGRATION entry.
+- Pin core to the tested release.
+- Pin harness to the tested release.
+- Updated dependencies [5b49361]
+- Updated dependencies
+  - @nylorun/core@0.46.0-beta
+  - @nylorun/harness@0.36.6-beta
+
 ## 0.52.0-beta
 
 ### Minor Changes

package/dist/adapters/sandbox/computer.d.ts

@@ -0,0 +1,28 @@
+import { type SandboxBackend } from "../../sandbox/types.js";
+/** What `open` answers: where this computer is, and the ticket for it. */
+export interface ComputerAccess {
+    /** The gateway's URL for this computer, `<gateway>/<sandbox>`. */
+    readonly url: string;
+    readonly ticket: string;
+    /** When the ticket expires (ms since the epoch). */
+    readonly expiresAt: number;
+}
+export interface ComputerBackendOptions {
+    readonly open: (signal?: AbortSignal) => Promise<ComputerAccess>;
+    readonly fetch?: typeof fetch;
+    readonly now?: () => number;
+    /** How long a dropped request is asked again for, past the command's own timeout. */
+    readonly retryMs?: number;
+}
+/** A computer refused or failed an operation. */
+export declare class ComputerError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+/** The disk roots of every computer (R9, ADR-150). */
+export declare const COMPUTER_DISK_ROOTS: {
+    readonly workspace: "/workspace";
+    readonly harness: "/harness";
+};
+export declare function computerBackend(options: ComputerBackendOptions): SandboxBackend;

package/dist/adapters/sandbox/computer.js

@@ -0,0 +1,184 @@
+/**
+ * Computer backend (ADR-149, ADR-150): a pod Agent's sandbox on Agent Substrate, reached through
+ * the sandbox gateway and Substrate's router (ADR-148). Its handle sends each operation to the
+ * computer's engine (`harness/computer.ts`) with a ticket core signs: `open` (a harness asks core
+ * with `computer.open`; core in process) wakes the computer, runs its disk's setup, and answers
+ * the gateway URL for this computer, the ticket and when it expires. A ticket is asked for again
+ * a minute before it expires.
+ *
+ * A command is a start and attaches, each answered within 50 s, under the command's own timeout:
+ * a gateway or router that drops a request (a rollout, a drain) is asked again with the same id,
+ * and the computer joins the command it already runs. One the computer no longer knows (lost with
+ * a crash or a revert) fails the call, saying so.
+ *
+ * One computer holds one sandbox: every key opens the same handle. Removing it is the Agent's reset
+ * or delete (core's pod lifecycle), so `remove` and `list` do nothing here; `stop` does nothing
+ * either, as core suspends an idle computer.
+ */
+import { randomUUID } from "node:crypto";
+import { SANDBOX_WORKSPACE } from "@nylorun/core/define";
+import { SandboxFileTooLargeError, wholeBytes, } from "../../sandbox/types.js";
+/** A computer refused or failed an operation. */
+export class ComputerError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "ComputerError";
+    }
+}
+const WAIT_MS = 50_000;
+const RENEW_MS = 60_000;
+/** The disk roots of every computer (R9, ADR-150). */
+export const COMPUTER_DISK_ROOTS = { workspace: SANDBOX_WORKSPACE, harness: "/harness" };
+export function computerBackend(options) {
+    const http = options.fetch ?? fetch;
+    const now = options.now ?? Date.now;
+    const retryMs = options.retryMs ?? 3 * 60_000;
+    let access;
+    let opening;
+    const current = async (signal) => {
+        if (access && access.expiresAt - now() > RENEW_MS)
+            return access;
+        opening ??= options.open(signal).finally(() => (opening = undefined));
+        access = await opening;
+        return access;
+    };
+    const call = async (method, path, init = {}) => {
+        const at = await current(init.signal);
+        const headers = { "x-nylorun-ticket": at.ticket };
+        let body = init.body;
+        if (init.json !== undefined) {
+            headers["content-type"] = "application/json";
+            body = JSON.stringify(init.json);
+        }
+        const response = await http(`${at.url}${path}`, {
+            method,
+            headers,
+            ...(body === undefined ? {} : { body }),
+            ...(body !== undefined && typeof body !== "string" && !(body instanceof Uint8Array) ? { duplex: "half" } : {}),
+            ...(init.signal ? { signal: init.signal } : {}),
+        });
+        if (response.status === 401)
+            access = undefined; // a new ticket next time
+        return response;
+    };
+    const failed = async (response) => {
+        let code = "computer_error";
+        let message = `The computer answered ${response.status}`;
+        try {
+            const parsed = (await response.json());
+            code = parsed.error?.code ?? code;
+            message = parsed.error?.message ?? message;
+        }
+        catch {
+            // not JSON
+        }
+        return new ComputerError(response.status, code, message);
+    };
+    /** Whether a failure is the way's (gateway, router, a computer moving), worth asking again. */
+    const transient = (error) => error instanceof ComputerError ? error.status === 401 || error.status >= 500 : !(error instanceof DOMException && error.name === "AbortError");
+    const exec = async (request, signal) => {
+        const id = randomUUID();
+        const deadline = now() + request.timeoutMs + retryMs;
+        let started = false;
+        const cancel = () => void call("POST", `/v1/exec/${encodeURIComponent(id)}/cancel`).catch(() => undefined);
+        signal.addEventListener("abort", cancel, { once: true });
+        try {
+            for (let attempt = 0;; attempt++) {
+                if (signal.aborted)
+                    throw signal.reason ?? new Error("Turn cancelled");
+                try {
+                    const response = started
+                        ? await call("POST", `/v1/exec/${encodeURIComponent(id)}/attach`, { json: { waitMs: WAIT_MS }, signal })
+                        : await call("POST", "/v1/exec", {
+                            json: { id, command: request.command, cwd: request.cwd, timeoutMs: request.timeoutMs, env: request.env ?? {}, waitMs: WAIT_MS },
+                            signal,
+                        });
+                    if (response.status === 404 && started)
+                        return {
+                            exitCode: 1,
+                            stdout: "",
+                            stderr: "The computer lost this command (it was restarted from its last snapshot).",
+                            killed: true,
+                            timedOut: false,
+                        };
+                    if (!response.ok)
+                        throw await failed(response);
+                    started = true;
+                    attempt = 0;
+                    const answer = (await response.json());
+                    if (answer.state === "done")
+                        return answer.result;
+                    if (answer.state === "failed")
+                        throw new ComputerError(500, "command_failed", answer.message);
+                }
+                catch (error) {
+                    if (!transient(error) || now() > deadline)
+                        throw error;
+                    await new Promise((resolve) => setTimeout(resolve, Math.min(5_000, 250 * 2 ** attempt)));
+                }
+            }
+        }
+        finally {
+            signal.removeEventListener("abort", cancel);
+        }
+    };
+    const readBytes = async (path, maxBytes) => {
+        const response = await call("GET", `/v1/files?path=${encodeURIComponent(path)}&maxBytes=${maxBytes}`);
+        if (response.status === 404)
+            return undefined;
+        if (response.status === 413) {
+            const error = await failed(response);
+            const size = Number(/is (\d+) bytes/.exec(error.message)?.[1] ?? maxBytes + 1);
+            throw new SandboxFileTooLargeError(path, size, maxBytes);
+        }
+        if (!response.ok)
+            throw await failed(response);
+        return new Uint8Array(await response.arrayBuffer());
+    };
+    const handle = {
+        workspace: SANDBOX_WORKSPACE,
+        diskRoots: COMPUTER_DISK_ROOTS,
+        exec,
+        async readFile(path) {
+            const bytes = await readBytes(path, Number.MAX_SAFE_INTEGER);
+            return bytes === undefined ? undefined : Buffer.from(bytes).toString("utf8");
+        },
+        readBytes,
+        async listFiles(dir, maxEntries) {
+            const response = await call("GET", `/v1/list?dir=${encodeURIComponent(dir)}&maxEntries=${maxEntries}`);
+            if (response.status === 404)
+                return undefined;
+            if (!response.ok)
+                throw await failed(response);
+            return (await response.json());
+        },
+        async writeFile(path, content) {
+            // A file's chunks are gathered: a skill's file is at most a few megabytes.
+            const body = (typeof content === "string" ? content : Buffer.from(await wholeBytes(content)));
+            const response = await call("PUT", `/v1/files?path=${encodeURIComponent(path)}`, { body });
+            if (!response.ok)
+                throw await failed(response);
+        },
+        async stop() { },
+    };
+    return {
+        name: "computer",
+        isolation: "container",
+        async probe() {
+            return { name: "computer", isolation: "container", available: true, reason: "an Agent Substrate computer" };
+        },
+        unmet: () => undefined,
+        open: async () => {
+            await current();
+            return handle;
+        },
+        async remove() { },
+        async list() {
+            return [];
+        },
+    };
+}

package/dist/artifacts/disk.js

@@ -20,6 +20,7 @@
  * Nothing here runs inside a transaction but the lease and the commit. No event type is new:
  * a restore or recovery is `agent.reset` with `reason` and `from`.
  */
+import { computerAccess } from "../sandbox/computer.js";
 import { createHash, randomUUID } from "node:crypto";
 import { newArtifactId } from "@nylorun/core/compatibility";
 import { FOLDER_CONTENT_TYPE, FOLDER_MANIFEST_FORMAT_V2, } from "@nylorun/core/contracts";
@@ -137,6 +138,11 @@ function heartbeat(ctx, id, limits, ms = limits.leaseMs) {
 }
 /** Waits until the engine of pod Environment `id` is connected, starting the pod when it is stopped. */
 async function awaitEngine(ctx, id, waitMs) {
+    // A computer (ADR-149) has no engine connection: it is ready once it answers through the gateway.
+    if (ctx.pods?.computer) {
+        await computerAccess(ctx, id);
+        return;
+    }
     await wakePod(ctx, id);
     const deadline = Date.now() + waitMs;
     while (!ctx.harness.hosting(id)) {
@@ -459,7 +465,9 @@ export async function runPendingSeed(ctx, id) {
         if (!environment || !seed || seed.written)
             return;
         const limits = await copyLimits(ctx, environment);
-        if (environment.kind === "pod") {
+        if (environment.kind === "pod" && ctx.pods?.computer)
+            await computerAccess(ctx, id);
+        else if (environment.kind === "pod") {
             const deadline = Date.now() + limits.podWaitMs;
             // The engine on the new volume: the old one's connection may still be open.
             while (!ctx.harness.hosting(id, environment.pod?.hostEpoch)) {
@@ -494,7 +502,7 @@ export async function runPendingSeed(ctx, id) {
 export async function sweepPendingSeeds(ctx) {
     const pending = (await ctx.store.tx((t) => t.listEnvironments())).filter((environment) => environment.diskSeed !== undefined && !environment.diskSeed.written && environment.pod?.desired !== "deleted");
     for (const environment of pending)
-        if (environment.kind !== "pod" || ctx.harness.hosting(environment.id, environment.pod?.hostEpoch))
+        if (environment.kind !== "pod" || ctx.pods?.computer || ctx.harness.hosting(environment.id, environment.pod?.hostEpoch))
             void runPendingSeed(ctx, environment.id);
 }
 /**

package/dist/harness/computer.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The computer (`--service computer`, ADR-149): the engine in an Agent Substrate actor when every
+ * harness runs outside the sandbox. It runs no loop, joins nothing and dials nothing to the
+ * Runtime. It serves the sandbox handle (`SandboxHandle`: commands, files, listings) on
+ * `NYLORUN_COMPUTER_PORT` (8080), which the sandbox gateway reaches through Substrate's router
+ * (ADR-148), and runs each command as the `local` backend does: the image's shell in `/workspace`,
+ * its own process group, the trust variables pointing at a bundle with Substrate's egress CA.
+ *
+ * Every route but `GET /ready` (the template's wake-up probe) needs `x-nylorun-ticket`: a compact
+ * JWS core signs with Ed25519, checked against `NYLORUN_COMPUTER_TICKET_KEY` (the public half the
+ * template carries), with `aud: "nylorun-computer"`, `exp` ahead, and `sub` this actor's name
+ * (`NYLORUN_COMPUTER_NAME_FILE`), so a router client other than the gateway can't command it.
+ *
+ * Commands are a start and attaches (ADR-148 decision 5): `POST /v1/exec` starts command `id`, or
+ * joins it while it runs, and answers within `waitMs` (at most 50 s) with `{state: "running"}` or
+ * `{state: "done", result}`; `POST /v1/exec/{id}/attach` waits again. A command's result is kept 10
+ * minutes after it ends. After a drain, the next attach reaches this process on the new worker, its
+ * commands moved with the memory snapshot. SIGTERM on Substrate means the worker is stopping: the
+ * engine keeps running, so the sandboxes service can suspend it.
+ */
+import { type KeyObject } from "node:crypto";
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { type ExecResult, type SandboxHandle } from "../sandbox/types.js";
+export interface ComputerServiceConfig {
+    readonly port: number;
+    /** The ticket key's public half, SPKI PEM. */
+    readonly ticketKey: string;
+    /** The file holding this actor's name (Substrate's actorMetadata). */
+    readonly nameFile: string;
+    /** The engine's own dir on the durable disk (`/harness`). */
+    readonly root: string;
+    /** Substrate's egress CA, which commands trust for hosts whose keys the egress adds. */
+    readonly egressCaFile?: string;
+    /** On Agent Substrate: SIGTERM means the worker is stopping, not that the engine should. */
+    readonly substrate: boolean;
+}
+/** The ticket audience. */
+export declare const COMPUTER_AUDIENCE = "nylorun-computer";
+/** The longest a start or an attach waits before it answers `running`. */
+export declare const MAX_WAIT_MS = 50000;
+/** Checks a ticket; the claims, or why it fails. */
+export declare function checkTicket(token: string | undefined, key: KeyObject, subject: string, now?: number): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface ComputerExecRequest {
+    readonly id: string;
+    readonly command: string;
+    readonly cwd: string;
+    readonly timeoutMs: number;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly waitMs?: number;
+}
+export type ComputerExecAnswer = {
+    readonly state: "running";
+} | {
+    readonly state: "done";
+    readonly result: ExecResult;
+} | {
+    readonly state: "failed";
+    readonly message: string;
+};
+/** The commands a computer runs, by id: start, join, attach, cancel. */
+export declare class ComputerCommands {
+    private readonly handle;
+    private readonly commands;
+    constructor(handle: Pick<SandboxHandle, "exec">);
+    start(request: ComputerExecRequest): Promise<ComputerExecAnswer>;
+    /** Undefined when the computer doesn't know the command. */
+    attach(id: string, waitMs?: number): Promise<ComputerExecAnswer> | undefined;
+    cancel(id: string): boolean;
+    private wait;
+    private prune;
+}
+/** The routes, on a handle (tests give their own). */
+export declare function computerHandler(options: {
+    readonly handle: SandboxHandle;
+    readonly key: KeyObject;
+    readonly name: string;
+    readonly ready: () => boolean;
+    readonly now?: () => number;
+}): (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+/** Runs the computer until the process ends. */
+export declare function runComputer(config: ComputerServiceConfig, baseline: Readonly<Record<string, string>>): Promise<void>;

package/dist/harness/computer.js

@@ -0,0 +1,273 @@
+/**
+ * The computer (`--service computer`, ADR-149): the engine in an Agent Substrate actor when every
+ * harness runs outside the sandbox. It runs no loop, joins nothing and dials nothing to the
+ * Runtime. It serves the sandbox handle (`SandboxHandle`: commands, files, listings) on
+ * `NYLORUN_COMPUTER_PORT` (8080), which the sandbox gateway reaches through Substrate's router
+ * (ADR-148), and runs each command as the `local` backend does: the image's shell in `/workspace`,
+ * its own process group, the trust variables pointing at a bundle with Substrate's egress CA.
+ *
+ * Every route but `GET /ready` (the template's wake-up probe) needs `x-nylorun-ticket`: a compact
+ * JWS core signs with Ed25519, checked against `NYLORUN_COMPUTER_TICKET_KEY` (the public half the
+ * template carries), with `aud: "nylorun-computer"`, `exp` ahead, and `sub` this actor's name
+ * (`NYLORUN_COMPUTER_NAME_FILE`), so a router client other than the gateway can't command it.
+ *
+ * Commands are a start and attaches (ADR-148 decision 5): `POST /v1/exec` starts command `id`, or
+ * joins it while it runs, and answers within `waitMs` (at most 50 s) with `{state: "running"}` or
+ * `{state: "done", result}`; `POST /v1/exec/{id}/attach` waits again. A command's result is kept 10
+ * minutes after it ends. After a drain, the next attach reaches this process on the new worker, its
+ * commands moved with the memory snapshot. SIGTERM on Substrate means the worker is stopping: the
+ * engine keeps running, so the sandboxes service can suspend it.
+ */
+import { createPublicKey, verify } from "node:crypto";
+import { accessSync, constants, readFileSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { rootCertificates } from "node:tls";
+import { join } from "node:path";
+import { SANDBOX_WORKSPACE } from "@nylorun/core/define";
+import { createHostLogger } from "../host/logger.js";
+import { localBackend } from "../adapters/sandbox/local.js";
+import { SandboxFileTooLargeError } from "../sandbox/types.js";
+import { TRUST_VARIABLES } from "./pod.js";
+import { RUNTIME_VERSION } from "../version.js";
+/** The ticket audience. */
+export const COMPUTER_AUDIENCE = "nylorun-computer";
+/** The longest a start or an attach waits before it answers `running`. */
+export const MAX_WAIT_MS = 50_000;
+/** How long a command's result is kept after it ends. */
+const KEEP_MS = 10 * 60_000;
+/** Checks a ticket; the claims, or why it fails. */
+export function checkTicket(token, key, subject, now = Date.now()) {
+    const parts = (token ?? "").split(".");
+    if (parts.length !== 3)
+        return { ok: false, reason: "no ticket" };
+    try {
+        const header = JSON.parse(Buffer.from(parts[0], "base64url").toString("utf8"));
+        if (header.alg !== "EdDSA")
+            return { ok: false, reason: "alg" };
+        const signed = verify(null, Buffer.from(`${parts[0]}.${parts[1]}`), key, Buffer.from(parts[2], "base64url"));
+        if (!signed)
+            return { ok: false, reason: "signature" };
+        const claims = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+        if (claims.aud !== COMPUTER_AUDIENCE)
+            return { ok: false, reason: "audience" };
+        if (claims.sub !== subject)
+            return { ok: false, reason: "subject" };
+        if (typeof claims.exp !== "number" || now / 1000 >= claims.exp)
+            return { ok: false, reason: "expired" };
+        return { ok: true };
+    }
+    catch {
+        return { ok: false, reason: "malformed" };
+    }
+}
+/** The commands a computer runs, by id: start, join, attach, cancel. */
+export class ComputerCommands {
+    handle;
+    commands = new Map();
+    constructor(handle) {
+        this.handle = handle;
+    }
+    start(request) {
+        this.prune();
+        let command = this.commands.get(request.id);
+        if (!command) {
+            const controller = new AbortController();
+            const done = this.handle.exec({
+                command: request.command,
+                cwd: request.cwd,
+                timeoutMs: request.timeoutMs,
+                ...(request.env ? { env: request.env } : {}),
+            }, controller.signal);
+            const created = { done, controller };
+            done.then((result) => {
+                created.result = result;
+                created.endedAt = Date.now();
+            }, (error) => {
+                created.error = error instanceof Error ? error.message : String(error);
+                created.endedAt = Date.now();
+            });
+            this.commands.set(request.id, created);
+            command = created;
+        }
+        return this.wait(command, request.waitMs);
+    }
+    /** Undefined when the computer doesn't know the command. */
+    attach(id, waitMs) {
+        const command = this.commands.get(id);
+        return command ? this.wait(command, waitMs) : undefined;
+    }
+    cancel(id) {
+        const command = this.commands.get(id);
+        command?.controller.abort(new Error("Cancelled"));
+        return command !== undefined;
+    }
+    async wait(command, waitMs = MAX_WAIT_MS) {
+        const ms = Math.max(0, Math.min(waitMs, MAX_WAIT_MS));
+        let timer;
+        const late = new Promise((resolve) => (timer = setTimeout(() => resolve("late"), ms)));
+        try {
+            await Promise.race([command.done.catch(() => undefined), late]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (command.result)
+            return { state: "done", result: command.result };
+        if (command.error !== undefined)
+            return { state: "failed", message: command.error };
+        return { state: "running" };
+    }
+    prune(now = Date.now()) {
+        for (const [id, command] of this.commands)
+            if (command.endedAt !== undefined && now - command.endedAt > KEEP_MS)
+                this.commands.delete(id);
+    }
+}
+/** Writes the trust bundle commands use (the public roots, then Substrate's egress CA). */
+function trustEnvironment(root, egressCaFile) {
+    if (!egressCaFile)
+        return {};
+    let ca;
+    try {
+        ca = readFileSync(egressCaFile, "utf8");
+    }
+    catch {
+        return {};
+    }
+    const bundle = join(root, "egress-ca-bundle.pem");
+    writeFileSync(bundle, `${rootCertificates.join("\n")}\n${ca}\n`, { mode: 0o644 });
+    return Object.fromEntries(TRUST_VARIABLES.map((name) => [name, bundle]));
+}
+async function body(request) {
+    const chunks = [];
+    for await (const chunk of request)
+        chunks.push(chunk);
+    return chunks.length === 0 ? {} : JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+function send(response, status, value) {
+    response.writeHead(status, { "content-type": "application/json" });
+    response.end(JSON.stringify(value));
+}
+function failure(response, status, code, message) {
+    send(response, status, { error: { code, message } });
+}
+/** The routes, on a handle (tests give their own). */
+export function computerHandler(options) {
+    const commands = new ComputerCommands(options.handle);
+    const workspace = options.handle.workspace ?? SANDBOX_WORKSPACE;
+    return async (request, response) => {
+        const url = new URL(request.url ?? "/", "http://computer");
+        try {
+            if (request.method === "GET" && url.pathname === "/ready") {
+                if (options.ready())
+                    send(response, 200, { status: "ok", version: RUNTIME_VERSION });
+                else
+                    failure(response, 503, "not_ready", `${workspace} is not writable`);
+                return;
+            }
+            const ticket = request.headers["x-nylorun-ticket"];
+            const checked = checkTicket(Array.isArray(ticket) ? ticket[0] : ticket, options.key, options.name, options.now?.() ?? Date.now());
+            if (!checked.ok)
+                return failure(response, 401, "unauthorized", `Ticket refused: ${checked.reason}`);
+            const path = url.searchParams.get("path") ?? "";
+            if (request.method === "GET" && url.pathname === "/v1/info")
+                return send(response, 200, { workspace, diskRoots: options.handle.diskRoots ?? { workspace }, version: RUNTIME_VERSION });
+            if (request.method === "POST" && url.pathname === "/v1/exec") {
+                const exec = (await body(request));
+                if (typeof exec.id !== "string" || typeof exec.command !== "string" || typeof exec.timeoutMs !== "number")
+                    return failure(response, 400, "invalid_request", "id, command and timeoutMs are required");
+                return send(response, 200, await commands.start({ ...exec, cwd: exec.cwd || workspace }));
+            }
+            const attach = /^\/v1\/exec\/([^/]+)\/(attach|cancel)$/.exec(url.pathname);
+            if (request.method === "POST" && attach) {
+                const id = decodeURIComponent(attach[1]);
+                if (attach[2] === "cancel")
+                    return send(response, commands.cancel(id) ? 200 : 404, { cancelled: true });
+                const { waitMs } = (await body(request));
+                const answer = commands.attach(id, waitMs);
+                if (!answer)
+                    return failure(response, 404, "unknown_command", `This computer doesn't know command ${id}`);
+                return send(response, 200, await answer);
+            }
+            if (url.pathname === "/v1/files") {
+                if (!path.startsWith("/"))
+                    return failure(response, 400, "invalid_request", "path must be absolute");
+                if (request.method === "GET") {
+                    const max = Number(url.searchParams.get("maxBytes") ?? "0") || Number.MAX_SAFE_INTEGER;
+                    const bytes = await options.handle.readBytes(path, max);
+                    if (bytes === undefined)
+                        return failure(response, 404, "not_found", `${path} does not exist`);
+                    response.writeHead(200, { "content-type": "application/octet-stream", "content-length": bytes.length });
+                    response.end(bytes);
+                    return;
+                }
+                if (request.method === "PUT") {
+                    await options.handle.writeFile(path, request);
+                    return send(response, 200, { written: true });
+                }
+            }
+            if (request.method === "GET" && url.pathname === "/v1/list") {
+                const dir = url.searchParams.get("dir") ?? "";
+                const max = Number(url.searchParams.get("maxEntries") ?? "10000");
+                const listed = await options.handle.listFiles(dir, max);
+                if (!listed)
+                    return failure(response, 404, "not_found", `${dir} is not a directory`);
+                return send(response, 200, listed);
+            }
+            failure(response, 404, "not_found", `No route ${request.method} ${url.pathname}`);
+        }
+        catch (error) {
+            if (error instanceof SandboxFileTooLargeError)
+                return failure(response, 413, "too_large", error.message);
+            if (response.headersSent)
+                return void response.destroy();
+            failure(response, 500, "computer_error", error instanceof Error ? error.message : String(error));
+        }
+    };
+}
+/** Runs the computer until the process ends. */
+export async function runComputer(config, baseline) {
+    const logger = createHostLogger();
+    const trust = trustEnvironment(config.root, config.egressCaFile);
+    const backend = localBackend({ env: baseline, proxyEnv: () => trust, harnessRoot: config.root });
+    const handle = await backend.open({
+        key: "computer",
+        cpus: 1,
+        memoryMiB: 1024,
+        network: { preset: "none", hosts: [], suffixes: [] },
+    });
+    const name = readFileSync(config.nameFile, "utf8").trim();
+    const key = createPublicKey(config.ticketKey);
+    const ready = () => {
+        try {
+            accessSync(handle.workspace ?? SANDBOX_WORKSPACE, constants.W_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const server = createServer((request, response) => void computerHandler({ handle, key, name, ready })(request, response));
+    server.requestTimeout = 0;
+    server.headersTimeout = 30_000;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(config.port, "0.0.0.0", () => resolve());
+    });
+    logger.info("computer_ready", { name, port: config.port, version: RUNTIME_VERSION });
+    let stopping = false;
+    for (const signal of ["SIGINT", "SIGTERM"])
+        process.on(signal, () => {
+            // On Agent Substrate, SIGTERM means the worker pod is stopping: the actor has 30 minutes to
+            // be suspended, and the sandboxes service suspends it (Substrate's eviction contract).
+            if (signal === "SIGTERM" && config.substrate) {
+                logger.info("computer_worker_stopping", { name });
+                return;
+            }
+            if (stopping)
+                return;
+            stopping = true;
+            server.close();
+            process.exit(0);
+        });
+}

package/dist/harness/executors.d.ts

@@ -11,6 +11,11 @@ export interface HarnessExecutorsOptions {
     readonly mcp: McpPool;
     /** The SandboxManager; a harness process creates it once `hello` names the Tenant. */
     readonly sandbox: () => SandboxManager;
+    /**
+     * The manager of a run whose sandbox is a computer (`routing.sandbox.computer`, ADR-149): one on
+     * the computer backend, opened with `computer.open`. Absent: such a run's sandbox calls fail.
+     */
+    readonly computer?: (run: HarnessRun) => SandboxManager;
     /**
      * The sandbox tools' limits the calls run with: the harness's configuration, the same it gives
      * `createHarness({ sandboxTools })`. Each left out is its default.