@sanoma-ai/workflows 0.11.17 → 0.11.18

package/src/grid.ts

@@ -7,6 +7,7 @@ import {
   ANONYMOUS,
   ANONYMOUS_PRINCIPAL,
   groupNamesOf,
+  isBatch,
   previewRequests,
   VISITORS,
   visitorPrincipal,
@@ -71,7 +72,8 @@ export function permissionsGrid(
   ];
   const opsById = new Map(description.ops.map((op) => [op.id, op]));
   const workflows = description.workflows.filter((w) => !w.builtin);
-  const direct = description.ops.filter((op) => op.direct).toSorted((a, b) => a.id.localeCompare(b.id));
+  // A batch has no row: the policy decides its entries, the save and the delete, which have theirs.
+  const direct = description.ops.filter((op) => op.direct && !isBatch(op)).toSorted((a, b) => a.id.localeCompare(b.id));
   // Every row's question, in the grid's order: each workflow's start, then the operations it may
   // call, as the run form asks them; then each direct operation.
   const asked = workflows.map((w) => previewRequests(w, opsById));

package/src/host-derive.ts

@@ -11,6 +11,7 @@ import { runtimeImage, sourceKeyId } from "./host.ts";
 import type { Bindings } from "./lockfile.ts";
 import { type Resource, valueAt } from "./resource.ts";
 import { secret, type Secret, type Secrets } from "./secret.ts";
+import type { SecretConfiguration } from "./secret-store.ts";
 import { sourceKeyPair, sshPublicKey } from "./ssh-key.ts";
 import { mintInstanceToken, WAKEUP_TOKEN } from "./wakeup-service.ts";
 
@@ -78,8 +79,10 @@ export interface HostFacts {
   unbound?: ReadonlyMap<string, readonly string[]>;
   /** True when the config binds `SANOMA_SIGNING_KEY`: the host is given that key, else its own (`HOST_SIGNING_KEY`). */
   signingKeyBound?: boolean;
-  /** Explicit environment delivery: destination variable to logical secret name, never values. */
+  /** Explicit environment delivery (`host: true`): destination variable to logical secret name, never values. */
   hostEnvironment?: Readonly<Record<string, string>>;
+  /** Of `hostEnvironment`'s logical names, those with no value where apply runs: the host cannot be given them. */
+  hostEnvironmentUnset?: readonly string[];
   /**
    * While the config has no deploy-key type, the GitHub repositories a host may clone (`origin`'s,
    * a declared `source`'s) that GitHub shows to no one: private (or not there). One GitHub does
@@ -227,8 +230,8 @@ const nameOf = (repository: string) =>
  * the caller leaves out, with what names them, so apply changes nothing it cannot give all it needs.
  * Problems: a host with no `database`, a name (none to tell, or another host's), an image or a
  * source that cannot be told, a credential its vendor's driver reads from this machine's
- * environment that nothing binds, a private repository it has no deploy key for, two hosts that
- * would attach the sites' domains.
+ * environment that nothing binds, a binding given to it (`host: true`) with no value where apply
+ * runs, a private repository it has no deploy key for, two hosts that would attach the sites' domains.
  */
 export function deriveHosts(
   resources: DeclaredResource[],
@@ -355,10 +358,16 @@ export function deriveHosts(
     const carried = [...vendors].flatMap((vendor) => facts.carried.get(vendor) ?? []);
     for (const name of [...carried, ...facts.githubApp]) secrets[name] = secret(name);
     for (const [environment, name] of Object.entries(facts.hostEnvironment ?? {})) {
-      if (Object.hasOwn(secrets, environment) && secrets[environment]!.$secret !== name)
+      const derived = Object.hasOwn(secrets, environment);
+      if (derived && secrets[environment]!.$secret !== name)
         problem(`${environment} has a derived host binding and cannot be replaced by ${name}`);
-      else if (!Object.hasOwn(secrets, environment))
-        Object.defineProperty(secrets, environment, { value: secret(name), enumerable: true });
+      // Its binding is `{ env }` (`host` takes no other, and none is generated): the variable it is
+      // read from where apply runs. Unset, it fails the host's update, a derived one's too.
+      else if (facts.hostEnvironmentUnset?.includes(name))
+        problem(
+          `${name} (\`host: true\`) has no value where apply runs, so the host cannot be given it: set ${environment}, which its binding in sanoma.config.ts reads, or take \`host: true\` off that binding`,
+        );
+      else if (!derived) Object.defineProperty(secrets, environment, { value: secret(name), enumerable: true });
     }
     // One the driver reads here from the environment alone would be left off the host, and a
     // Worker updated without it would lose it.
@@ -440,8 +449,9 @@ export async function hostRootFacts(root: string): Promise<HostRootFacts> {
  * What the declared hosts that derive (`deriveHosts`) are filled from: the root's facts
  * (`rootFacts`, asked only when a declared host derives: `hostRootFacts`, or a snapshot's), and of
  * `secrets` (none outside a run) which
- * optional credentials, App keys and source key are stored, and which credentials the drivers
- * read from this machine's environment alone (`unbound`). With `mint` (apply, never drift or a
+ * optional credentials, App keys and source key are stored, which credentials the drivers
+ * read from this machine's environment alone (`unbound`), and which bindings given to the hosts
+ * (`host: true`) have no value (`hostEnvironmentUnset`). With `mint` (apply, never drift or a
  * sandbox run), the source key (where the config has the deploy-key type) and, when a wakeup is
  * declared, the wakeup's token are minted first when none is stored, so the host is given them
  * from its first apply. With no deploy-key type, GitHub is asked which repositories a host may clone are private.
@@ -454,32 +464,41 @@ export async function hostFacts(options: {
   drivers: ReadonlyMap<string, Driver>;
   secrets?: Secrets;
   builtInStore: boolean;
-  /** True when the config binds `SANOMA_SIGNING_KEY` (`{ env }` or `{ bootstrap }`). */
-  signingKeyBound?: boolean;
-  hostEnvironment?: Readonly<Record<string, string>>;
+  /** The config's secret bindings: whether it binds `SANOMA_SIGNING_KEY`, and those given to the hosts (`host: true`). */
+  bindings?: SecretConfiguration["bindings"];
   sender?: string;
   mint: boolean;
+  /** A sandbox run's: its calls resolve no stored value, so a binding given to the hosts with none is no problem. */
+  sandbox?: boolean;
 }): Promise<HostFacts | undefined> {
   const { rootFacts, resources, types, drivers, secrets, mint } = options;
   const typeOf = (r: DeclaredResource) => types.get(`${r.vendor}.${r.type}`);
   const deriving = resources.filter((r) => typeOf(r)?.host?.derives);
   if (!deriving.length) return undefined;
   const hosts = deriving.filter((r) => !typeOf(r)?.host?.bindsBootstrap);
-  // Which optional credentials and App keys are stored: read at once, and only for a host given secrets.
+  // The store is read only in a run, and only for a host given secrets.
+  const reading = secrets !== undefined && hosts.length > 0;
+  // Which optional credentials and App keys are stored: read at once.
   const stored = async (names: readonly string[]) =>
-    secrets && hosts.length
+    reading
       ? new Set((await Promise.all(names.map(async (n) => ((await secrets.get(n)) === undefined ? [] : [n])))).flat())
       : new Set<string>();
   const statuses = [...drivers].flatMap(([vendor, { env }]) =>
     env ? statusesOf(env, () => undefined).map((c) => ({ vendor, ...c })) : [],
   );
+  const bindings = options.bindings ?? {};
+  const hostEnvironment: Record<string, string> = Object.fromEntries(
+    Object.entries(bindings).flatMap(([name, b]) => (b.host && b.env !== undefined ? [[b.env, name]] : [])),
+  );
+  const delivered = Object.values(hostEnvironment);
   // Only what the store holds: a marker for a name it does not would fail the host's deploy.
-  const held = await stored(statuses.map((c) => c.name));
+  const held = await stored([...statuses.map((c) => c.name), ...delivered]);
+  const hostEnvironmentUnset = reading && !options.sandbox ? delivered.filter((name) => !held.has(name)) : [];
   const carried = new Map<string, string[]>();
   const unbound = new Map<string, string[]>();
   for (const c of statuses) {
     // The driver reads the environment first: set there alone, it runs here and the host is not given it.
-    const into = held.has(c.name) ? carried : secrets && hosts.length && process.env[c.name] ? unbound : undefined;
+    const into = held.has(c.name) ? carried : reading && process.env[c.name] ? unbound : undefined;
     into?.set(c.vendor, [...(into.get(c.vendor) ?? []), c.name]);
   }
   const githubApp = [...(await stored(Object.values(GITHUB_APP)))];
@@ -487,7 +506,7 @@ export async function hostFacts(options: {
   const keyed = types.has(DEPLOY_KEY_TYPE);
   const [{ version, origin, domains }, sourceKey] = await Promise.all([
     rootFacts(),
-    secrets && hosts.length && keyed ? sourceKeyOf(secrets, mint) : undefined,
+    reading && keyed ? sourceKeyOf(secrets, mint) : undefined,
   ]);
   // What a host may clone: `origin`, else the `source` it declares (with no deploy-key type, no
   // GitHub repository is declared to be one).
@@ -510,8 +529,9 @@ export async function hostFacts(options: {
     builtInStore: options.builtInStore,
     carried,
     ...(unbound.size > 0 && { unbound }),
-    ...(options.signingKeyBound && { signingKeyBound: true }),
-    ...(options.hostEnvironment && { hostEnvironment: options.hostEnvironment }),
+    ...(bindings.SANOMA_SIGNING_KEY !== undefined && { signingKeyBound: true }),
+    ...(delivered.length > 0 && { hostEnvironment }),
+    ...(hostEnvironmentUnset.length > 0 && { hostEnvironmentUnset }),
     ...(options.sender !== undefined && { sender: options.sender }),
     githubApp,
     ...(sourceKey !== undefined && { sourceKey }),

package/src/index.ts

@@ -263,6 +263,8 @@ export {
   type SandboxSpec,
 } from "./sandbox-contract.ts";
 export { LOCAL_SANDBOX, localBackend } from "./local-sandbox.ts";
+export { runnerBox, runnerHealth, runnerScript } from "./runner-box.ts";
+export { RUNNER_HEALTH, RUNNER_PORT, RUNNER_PROTOCOL, type RunnerHealth } from "./runner-protocol.ts";
 export type { Chat, Chats } from "./chats.ts";
 export type { Tokens } from "./tokens.ts";
 export { type InviteRequest, openInvite, sealInvite, sealLoginCode } from "./seal.ts";

package/src/ledger.ts

@@ -1,9 +1,9 @@
 import type { ConnectionSnapshot } from "./connection.ts";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
-import { appendFile, mkdir, readFile, truncate } from "node:fs/promises";
+import { appendFile, mkdir, readdir, readFile, truncate } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { eq, sql } from "drizzle-orm";
+import { desc, eq, sql } from "drizzle-orm";
 import { setTimeout as delay } from "node:timers/promises";
 import { isDeepStrictEqual } from "node:util";
 import { type Db, lazyDb, pgCode } from "./db.ts";
@@ -48,6 +48,11 @@ export type LedgerRecord = {
       type: "op.called";
       connection?: ConnectionSnapshot;
       op: string;
+      /**
+       * The instance the call acted on (`data:outbound/Acme`), from the operation's `target`: what
+       * `readByTarget` finds the record by. Absent for an operation that declares none.
+       */
+      target?: string;
       /**
        * The outline node of the call that made it (`OutlineNode.path`): where the step is in the
        * code. Absent in records written before the worker placed calls (ledgers from 0.1).
@@ -234,6 +239,8 @@ export interface LedgerStore {
   append(record: LedgerRecord): Promise<void>;
   /** A run's records in `seq` order. */
   read(runId: string): Promise<LedgerRecord[]>;
+  /** The `op.called` records whose `target` it is, across every run, newest first, at most `limit`: a record's history. */
+  readByTarget(target: string, limit: number): Promise<LedgerRecord[]>;
   /**
    * Releases what the store holds (a connection pool), for good. Called by the one owner of the
    * store: the worker's `stop` and `SanomaClient.close` close the Postgres store each made for a
@@ -261,6 +268,13 @@ export function ownedLedger(config: { ledger?: LedgerStore; databaseUrl: string
 
 const bySeq = (a: LedgerRecord, b: LedgerRecord) => a.seq - b.seq;
 
+/** The calls among `records` that acted on `target`, as `readByTarget` reads them: newest first, by `at`, then `seq`. */
+const actedOn = (records: LedgerRecord[], target: string, limit: number): LedgerRecord[] =>
+  records
+    .filter((r) => r.type === "op.called" && r.target === target)
+    .toSorted((a, b) => b.at - a.at || b.seq - a.seq)
+    .slice(0, limit);
+
 /** An error that trying again would only repeat. */
 const final = (message: string, cause: unknown) => Object.assign(new Error(message, { cause }), { retryable: false });
 
@@ -364,6 +378,16 @@ export function jsonlLedger(dir: string): LedgerStore {
       // A case-insensitive file system can map two run ids to one file.
       return (await load(path)).records.filter((r) => r.runId === runId).toSorted(bySeq);
     },
+    async readByTarget(target, limit) {
+      await Promise.all([...queues.values()].map((pending) => pending.catch(() => {})));
+      const files = await readdir(root).catch((err: NodeJS.ErrnoException) => {
+        if (err.code === "ENOENT") return [];
+        throw err;
+      });
+      const runs = await Promise.all(files.filter((f) => f.endsWith(".jsonl")).map((f) => load(join(root, f))));
+      const records = runs.flatMap((run) => run.records);
+      return actedOn(records, target, limit);
+    },
   };
 }
 
@@ -398,6 +422,18 @@ export function postgresLedger(databaseUrl: string): LedgerStore & { close(): Pr
       // In seq order, as the other stores read; two records of one seq in write order.
       return rows.map((r) => r.record);
     },
+    async readByTarget(target, limit) {
+      const rows = await (
+        await store.db()
+      )
+        .select({ record: ledger.record })
+        .from(ledger)
+        .where(eq(ledger.target, target))
+        // Newest first, as the other stores read; two records of one `at` and `seq` in write order.
+        .orderBy(desc(sql`(${ledger.record} ->> 'at')::bigint`), desc(ledger.seq), desc(ledger.n))
+        .limit(limit);
+      return rows.map((r) => r.record);
+    },
     close: store.close,
   };
 }
@@ -438,6 +474,10 @@ export function memoryLedger(): LedgerStore {
     async read(runId) {
       return [...(runs.get(runId)?.values() ?? [])].map((r) => structuredClone(r)).toSorted(bySeq);
     },
+    async readByTarget(target, limit) {
+      const records = [...runs.values()].flatMap((run) => [...run.values()]);
+      return actedOn(records, target, limit).map((r) => structuredClone(r));
+    },
   };
 }
 

package/src/local-sandbox.ts

@@ -40,9 +40,10 @@ function boxDir(dir: string, name: string): string {
 /**
  * The box at `home`, over `node:child_process` and `node:fs`: a command is `bash -c` in a process
  * group of its own (killed whole by `kill`, and by `stop`), with `base` under the caller's `env`;
- * a relative path or `cwd` is under `home`, any other this machine's.
+ * a relative path or `cwd` is under `home`, any other this machine's. The runner in a remote box
+ * (`sandbox-runner.ts`) serves its own machine's.
  */
-function localBox(id: string, home: string, base: Record<string, string>): Box {
+export function localBox(id: string, home: string, base: Record<string, string>): Box {
   /** The process groups its commands lead, killed by `stop` whether or not their leader has exited. */
   const groups = new Set<number>();
   const at = (path: string) => resolve(home, path);

package/src/op.ts

@@ -365,8 +365,9 @@ export interface ConnectorSetup {
   remote?: () => RemoteHalf;
   /**
    * Makes the connector's sandbox backend, which opens the boxes of the type that meets the
-   * `Sandbox` contract by name: by the app, when a coding agent's turn needs a box. It reads its
-   * credentials through `context.secrets`.
+   * `Sandbox` contract by name: by the app, once per declared resource of that type, when a coding
+   * agent's turn needs a box. It reads its credentials through `context.secrets` and the
+   * resource's fields from `context.declared`.
    */
   sandbox?: (context: SandboxContext) => SandboxBackend | Promise<SandboxBackend>;
 }

package/src/resources.ts

@@ -203,7 +203,7 @@ export function admit(
  * Each declaration is joined to its binding in the lockfile (`readLockfile`) by its key,
  * `<file>#<export>`; a binding no export declares is an orphan, unless its file failed to load.
  * Problems: the lockfile's, a binding of another type than its declaration's, two declarations
- * bound to one object, and several wakeups.
+ * bound to one object, and several wakeups or sandboxes.
  */
 export function loadDataFiles(
   root: string | undefined,
@@ -367,13 +367,15 @@ function declarationsOf(
     if (why === undefined) boundBy.set(object, id);
     else leaveOut(id, why);
   }
-  // An instance registers with one wakeup: several are each a problem, and left out, as is any that names one.
-  const wakeups = [...declarations.keys()].filter((id) => types.get(declarations.get(id)!.value[DECLARED])?.wakeup);
-  if (wakeups.length > 1) {
-    for (const id of wakeups) {
+  // An instance registers with one wakeup, and opens its coding agents' boxes in one sandbox: several
+  // of either are each a problem, and left out, as is any that names one.
+  for (const contract of ["wakeup", "sandbox"] as const) {
+    const ids = [...declarations.keys()].filter((id) => types.get(declarations.get(id)!.value[DECLARED])?.[contract]);
+    if (ids.length < 2) continue;
+    for (const id of ids) {
       leaveOut(
         id,
-        `an instance has one wakeup: leave out this one or ${wakeups.filter((other) => other !== id).join(", ")}`,
+        `an instance has one ${contract}: leave out this one or ${ids.filter((other) => other !== id).join(", ")}`,
       );
     }
   }

package/src/runner-box.ts

@@ -0,0 +1,218 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import {
+  FILE,
+  frame,
+  RUNNER_HEALTH,
+  type RunnerAnswer,
+  type RunnerHealth,
+  type RunnerRequest,
+  STDERR,
+  STDIN,
+  unframe,
+} from "./runner-protocol.ts";
+import type { Box, Process } from "./sandbox-contract.ts";
+
+// A box whose commands and files go through the runner (`sandbox-runner.ts`), a small server of
+// ours a backend starts inside a remote box, over one WebSocket: so every vendor's backend is
+// "open the box, start the runner, talk to it", whatever the vendor's own exec can or cannot
+// stream. The protocol is in `runner-protocol.ts`. One connection carries many processes; a
+// dropped one ends them here (exit 255) but kills nothing in the box.
+
+/**
+ * The runner as one file (`dist/sandbox-runner.cjs`, its dependencies bundled in), which a
+ * backend writes into a box and starts with the box's `node` (22 or later).
+ */
+export async function runnerScript(): Promise<Uint8Array> {
+  // `../dist/` from `src/` (the tests) and from `dist/` alike.
+  const at = new URL("../dist/sandbox-runner.cjs", import.meta.url);
+  return readFile(at).catch(() => {
+    throw new Error(`${fileURLToPath(at)} is missing: build @sanoma-ai/workflows`);
+  });
+}
+
+/**
+ * What the runner at `url` (asked with `headers`) answers at `RUNNER_HEALTH`, or undefined when nothing
+ * answers as a runner: a backend starts one then, and replaces one of another `protocol`.
+ */
+export const runnerHealth = (url: string, headers?: Record<string, string>): Promise<RunnerHealth | undefined> =>
+  fetch(`${url}${RUNNER_HEALTH}`, { headers, signal: AbortSignal.timeout(5_000) })
+    .then(async (res) => {
+      const health = res.ok ? ((await res.json()) as Partial<RunnerHealth> | null) : null;
+      return typeof health?.protocol === "number" && typeof health.pid === "number"
+        ? { protocol: health.protocol, pid: health.pid }
+        : undefined;
+    })
+    .catch(() => undefined);
+
+const encoder = new TextEncoder();
+
+/** Drops a write or close the reader no longer wants (it cancelled). */
+const ignore = () => {};
+
+/** What an id of the connection waits for: a process's output and exit, or a request's answer. */
+interface Waiter {
+  bytes(stream: number, bytes: Uint8Array): void;
+  answer(answer: RunnerAnswer): void;
+  /** The connection dropped. */
+  lost(): void;
+}
+
+/** An open connection to the runner, and what its ids wait for. */
+interface Connection {
+  ws: WebSocket;
+  waiting: Map<number, Waiter>;
+}
+
+/** How long the runner's WebSocket may take to open, in ms. */
+const OPEN_MS = 30_000;
+
+/**
+ * The box `id` whose runner is at `url` (`http(s)://`, the WebSocket's upgrade sent with
+ * `headers`): its commands, files and `stop` (which kills every command in it and closes the
+ * connection). Connects at the first call, and again at the next call after a drop or a `stop`.
+ * How its ports are reached is the vendor's, so the backend adds `expose`.
+ */
+export function runnerBox({
+  url,
+  headers,
+  id,
+}: {
+  url: string;
+  headers?: Record<string, string>;
+  id: string;
+}): Omit<Box, "expose"> {
+  const where = `the runner at ${new URL(url).host}`;
+  let current: Promise<Connection> | undefined;
+  let last = 0;
+
+  const connect = () => (current ??= open());
+  function open(): Promise<Connection> {
+    const opening = new Promise<Connection>((resolve, reject) => {
+      // Node's WebSocket (undici) takes `headers` beside the standard's protocols.
+      const ws = new WebSocket(url.replace(/^http/, "ws"), { headers } as unknown as string[]);
+      ws.binaryType = "arraybuffer";
+      const connection: Connection = { ws, waiting: new Map() };
+      const late = setTimeout(() => ws.close(), OPEN_MS);
+      ws.addEventListener("open", () => {
+        clearTimeout(late);
+        resolve(connection);
+      });
+      ws.addEventListener("message", ({ data }: { data: string | ArrayBuffer }) => {
+        try {
+          if (typeof data !== "string") {
+            const { id: of, stream, bytes } = unframe(new Uint8Array(data));
+            return connection.waiting.get(of)?.bytes(stream, bytes);
+          }
+          const answer = JSON.parse(data) as RunnerAnswer;
+          if (answer.id !== undefined) connection.waiting.get(answer.id)?.answer(answer);
+        } catch {
+          // A frame that is not the protocol's (another runner's) is dropped.
+        }
+      });
+      ws.addEventListener("close", ({ code, reason }) => {
+        clearTimeout(late);
+        if (current === opening) current = undefined;
+        reject(new Error(`${where} closed the connection (${reason || code})`));
+        for (const waiter of connection.waiting.values()) waiter.lost();
+        connection.waiting.clear();
+      });
+    });
+    return opening;
+  }
+
+  /** Sends `request` (and `bytes` after it): resolves with the file it answers, null for none, or nothing for `ok`. */
+  async function ask(
+    request: { op: "read"; path: string } | { op: "write"; path: string; mode?: number } | { op: "stop" },
+    bytes?: Uint8Array,
+  ): Promise<Uint8Array | null | undefined> {
+    const { ws, waiting } = await connect();
+    const n = ++last;
+    return new Promise((resolve, reject) => {
+      const settle = (done: () => void) => {
+        waiting.delete(n);
+        done();
+      };
+      waiting.set(n, {
+        bytes: (_, file) => settle(() => resolve(file)),
+        answer: (answer) =>
+          settle(() =>
+            answer.op === "error"
+              ? reject(new Error(`${where}: ${answer.message}`))
+              : resolve(answer.op === "absent" ? null : undefined),
+          ),
+        lost: () => reject(new Error(`${where} closed the connection`)),
+      });
+      ws.send(JSON.stringify({ ...request, id: n }));
+      if (bytes) ws.send(frame(n, FILE, bytes));
+    });
+  }
+
+  return {
+    id,
+    async run(command, { cwd, env, stdin = false, signal } = {}): Promise<Process> {
+      const { ws, waiting } = await connect();
+      const n = ++last;
+      const stdout = new TransformStream<Uint8Array, Uint8Array>();
+      const stderr = new TransformStream<Uint8Array, Uint8Array>();
+      const out = stdout.writable.getWriter();
+      const err = stderr.writable.getWriter();
+      const exited = new Promise<{ exitCode: number }>((done) => {
+        const end = (exitCode: number) => {
+          waiting.delete(n);
+          out.close().catch(ignore);
+          err.close().catch(ignore);
+          done({ exitCode });
+        };
+        waiting.set(n, {
+          bytes: (stream, bytes) => void (stream === STDERR ? err : out).write(bytes).catch(ignore),
+          answer(answer) {
+            if (answer.op === "exit") return end(answer.code);
+            if (answer.op !== "error") return;
+            err.write(encoder.encode(`${where}: ${answer.message}\n`)).catch(ignore);
+            end(127);
+          },
+          lost: () => end(255),
+        });
+      });
+      ws.send(JSON.stringify({ op: "run", id: n, command, cwd, env, stdin } satisfies RunnerRequest));
+      const kill = (sig: NodeJS.Signals = "SIGKILL") => {
+        if (waiting.has(n)) ws.send(JSON.stringify({ op: "kill", id: n, signal: sig } satisfies RunnerRequest));
+      };
+      const onAbort = () => kill();
+      if (signal?.aborted) onAbort();
+      signal?.addEventListener("abort", onAbort, { once: true });
+      void exited.then(() => signal?.removeEventListener("abort", onAbort));
+      const endInput = () => void ws.send(JSON.stringify({ op: "stdin-end", id: n } satisfies RunnerRequest));
+      return {
+        stdin: new WritableStream<Uint8Array>({
+          write(bytes) {
+            if (!stdin) throw new Error("its stdin is closed: run it with stdin: true");
+            ws.send(frame(n, STDIN, bytes));
+          },
+          close: endInput,
+          abort: endInput,
+        }),
+        stdout: stdout.readable,
+        stderr: stderr.readable,
+        wait: () => exited,
+        kill,
+      };
+    },
+    read: async (path) => (await ask({ op: "read", path })) ?? null,
+    async write(path, bytes, { mode } = {}) {
+      await ask({ op: "write", path, mode }, bytes);
+    },
+    async stop() {
+      // This connection, not one a call opens meanwhile after a drop.
+      const closing = connect();
+      try {
+        await ask({ op: "stop" });
+      } finally {
+        // The next call opens a new connection, not this closing one.
+        if (current === closing) current = undefined;
+        (await closing.catch(() => undefined))?.ws.close();
+      }
+    },
+  };
+}

package/src/runner-protocol.ts

@@ -0,0 +1,61 @@
+// The runner's protocol, over one WebSocket per box, shared by the runner (`sandbox-runner.ts`)
+// and its client (`runner-box.ts`): text frames for control, as JSON, each carrying the `id` of
+// the process or the request it is about; binary frames for bytes, `frame(id, stream, bytes)`.
+
+/** The port the runner listens on in a box. */
+export const RUNNER_PORT = 7700;
+
+/**
+ * Where the runner answers its health: not `/health`, which Agent37's edge answers itself on
+ * every port, so that path never reaches what listens there.
+ */
+export const RUNNER_HEALTH = "/runner/health";
+
+/**
+ * The protocol's version, which the runner's health answers: a backend replaces a runner
+ * that answers another, one an earlier release started in a box that slept.
+ */
+export const RUNNER_PROTOCOL = 2;
+
+/** What the runner's health (`RUNNER_HEALTH`) answers: its protocol, and its pid, which a backend replacing it ends. */
+export interface RunnerHealth {
+  protocol: number;
+  pid: number;
+}
+
+/** What a binary frame's bytes are: a process's stdin, stdout or stderr, or a file read or written. */
+export const STDIN = 0;
+export const STDOUT = 1;
+export const STDERR = 2;
+export const FILE = 3;
+
+/** What the client says, as text. A `write`'s bytes follow it as the frame `(id, FILE)`. */
+export type RunnerRequest =
+  | { op: "run"; id: number; command: string; cwd?: string; env?: Record<string, string>; stdin: boolean }
+  | { op: "stdin-end"; id: number }
+  | { op: "kill"; id: number; signal: NodeJS.Signals }
+  | { op: "read"; id: number; path: string }
+  | { op: "write"; id: number; path: string; mode?: number }
+  | { op: "stop"; id: number };
+
+/** What the runner answers, as text. A `read` that finds a file answers the frame `(id, FILE)`. */
+export type RunnerAnswer =
+  | { op: "exit"; id: number; code: number }
+  | { op: "absent"; id: number }
+  | { op: "ok"; id: number }
+  | { op: "error"; id?: number; message: string };
+
+/** A binary frame: `id` (4 bytes), `stream` (1 byte), then `bytes`. */
+export function frame(id: number, stream: number, bytes: Uint8Array): Uint8Array<ArrayBuffer> {
+  const framed = new Uint8Array(5 + bytes.length);
+  new DataView(framed.buffer).setUint32(0, id);
+  framed[4] = stream;
+  framed.set(bytes, 5);
+  return framed;
+}
+
+export const unframe = (framed: Uint8Array) => ({
+  id: new DataView(framed.buffer, framed.byteOffset, framed.byteLength).getUint32(0),
+  stream: framed[4]!,
+  bytes: framed.subarray(5),
+});

package/src/sandbox-contract.ts

@@ -80,14 +80,21 @@ export interface Box {
  * vendor keeps its state, so no snapshot handle crosses the contract.
  */
 export interface SandboxBackend {
-  /** The box `name`, made from `image` with `size` vCPUs when there is none, woken or started when stopped. */
-  open(opts: { name: string; image: string; size: number }): Promise<Box>;
+  /**
+   * The box `name`, made from `image` with `size` vCPUs when there is none (left out, the backend's
+   * own), woken or started when stopped.
+   */
+  open(opts: { name: string; image?: string; size?: number }): Promise<Box>;
   /** Deletes the box `name` and whatever the vendor kept of it: the next `open` finds it empty. */
   discard(opts: { name: string }): Promise<void>;
 }
 
-/** What the app gives a connector's sandbox half (`ConnectorSetup.sandbox`): the secrets, as a model half reads them. */
-export type SandboxContext = Pick<LoginContext, "secrets">;
+/**
+ * What the app gives a connector's sandbox half (`ConnectorSetup.sandbox`): the secrets, as a model
+ * half reads them, and the declared fields of the resource whose boxes it opens, which hold the
+ * vendor's facts (its region, its type of machine) beside the image and size `open` takes.
+ */
+export type SandboxContext = Pick<LoginContext, "secrets"> & { declared: Record<string, unknown> };
 
 /**
  * Throws what is wrong with a resource type's `sandbox`: a type apply cannot change (not