@sanoma-ai/workflows 0.11.16 → 0.11.18

package/src/describe.ts

@@ -205,7 +205,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
       key: c.key,
       fields: c.fields,
       record: { $id: `sanoma:collection/${c.name}`, ...toJsonSchema(recordSchemaOf(c), `${c.name} record`, "input") },
-      ops: [c.get, c.list, c.save, c.delete].map((op) => op.id),
+      ops: [c.get, c.list, c.count, c.save, c.saveMany, c.delete].map((op) => op.id),
       ...(declared.has(c.name) && { declared: declared.get(c.name) }),
     }))
     .toSorted((a, b) => a.name.localeCompare(b.name));

package/src/description.ts

@@ -298,10 +298,11 @@ export const VendorEntrySchema = z.strictObject({
 export type VendorEntry = z.infer<typeof VendorEntrySchema>;
 
 /**
- * The contracts a resource type meets, from its spec: `host`, `database` and `wakeup` (`Host`,
- * `Database`, `Wakeup`), and `source` for a type a host's `source` names (the repository it clones).
+ * The contracts a resource type meets, from its spec: `host`, `database`, `wakeup` and `sandbox`
+ * (`Host`, `Database`, `Wakeup`, `Sandbox`), and `source` for a type a host's `source` names (the
+ * repository it clones).
  */
-export const CAPABILITIES = ["host", "database", "wakeup", "source"] as const;
+export const CAPABILITIES = ["host", "database", "wakeup", "sandbox", "source"] as const;
 
 /** A resource type a connector declares with `defineResource`. */
 export const ResourceTypeEntrySchema = z.strictObject({
@@ -348,7 +349,7 @@ export const CollectionEntrySchema = z.strictObject({
   fields: z.record(z.string(), FieldSchema),
   /** What `save` accepts, as JSON Schema, with `$id` `sanoma:collection/<name>`. */
   record: JsonSchema,
-  /** Its operations' ids: `data.<name>.get`, `.list`, `.save` and `.delete`. */
+  /** Its operations' ids: `data.<name>.get`, `.list`, `.count`, `.save`, `.saveMany` and `.delete`. */
   ops: z.array(z.string()),
   /** Where `resources/data.ts` declares it, read as the data files are; absent for one declared elsewhere. */
   declared: DeclaredCollectionSchema.optional(),

package/src/errors.ts

@@ -79,8 +79,9 @@ export const isRunControlError = (err: unknown): boolean =>
 
 /** Thrown into the run when the policy denies an operation call. The run fails with it. */
 export class PolicyDeniedError extends SanomaError {
-  constructor(op: string, reason: string) {
-    super("policy_denied", `${op} was denied by policy: ${reason}`, { op, reason });
+  /** `data` adds to the error's: a batch's `denied` keys. */
+  constructor(op: string, reason: string, data: Record<string, unknown> = {}) {
+    super("policy_denied", `${op} was denied by policy: ${reason}`, { op, reason, ...data });
     this.name = "PolicyDeniedError";
   }
 }

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

@@ -69,6 +69,7 @@ export {
   declaredWakeup,
   defineConfig,
   envWakeup,
+  joinDeclarations,
   type Login,
   readRootSnapshot,
   resolveConfig,
@@ -79,7 +80,7 @@ export {
 // An app's `app.ts` (`defineApp`), and where the launcher finds an app's workflows and data file.
 export { type AppEntry, appSourceOf, readApps } from "./apps.ts";
 export { type AppDefinition, defineApp } from "./definitions.ts";
-export { appFolders, APPS_DIR, filesUnder, kindDirs } from "./paths.ts";
+export { appFolders, APPS_DIR, declarationFiles, filesUnder, kindDirs } from "./paths.ts";
 // `sanoma` itself (the people types' constructors) is at `@sanoma-ai/workflows/resources`, for data files.
 // `collection()` itself is at `@sanoma-ai/workflows/data`, for `resources/data.ts`; this tells one apart, as the launcher does.
 export { isCollection } from "./collection.ts";
@@ -193,7 +194,7 @@ export type { RunArgs } from "./run.ts";
 export { startWorker, type Worker, type WorkerOptions } from "./worker.ts";
 export { superviseWorker, type Supervisor, type SupervisorOptions } from "./supervisor.ts";
 export type { DeadlineSource, Deadlines, SelfStop, Wait } from "./deadlines.ts";
-export { nextFire, nextScheduledFire } from "./schedules.ts";
+export { nextFire, nextScheduledFire, timeMatcherFile, type TimeMatcherClass, useTimeMatcher } from "./schedules.ts";
 // `secret` itself is at `@sanoma-ai/workflows/resources`, for data files; this is the drivers' side.
 export {
   generateSecret,
@@ -252,6 +253,18 @@ export {
   databaseUrlSecret,
   storeDatabaseUrl,
 } from "./database.ts";
+export {
+  type Box,
+  type Process,
+  type SandboxBackend,
+  type SandboxCapabilities,
+  type SandboxContext,
+  type SandboxOutputs,
+  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

@@ -0,0 +1,133 @@
+import { spawn } from "node:child_process";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { Readable, Writable } from "node:stream";
+import type { Box, Process, SandboxBackend, SandboxCapabilities } from "./sandbox-contract.ts";
+
+// The local backend of the `Sandbox` contract: boxes on this machine, the app's for a coding agent
+// on a laptop and the testing package's fake. A box is a directory, its home, kept across stops;
+// its commands are child processes, each in a process group of its own; its ports are loopback's.
+
+/** What the local backend can do: its boxes are this machine's directories, which `stop` leaves. */
+export const LOCAL_SANDBOX: SandboxCapabilities = { snapshot: true, pause: false, port: true };
+
+/**
+ * The boxes under `dir`: the box `name` is the directory `<dir>/<name>`, its home, made on its
+ * first `open`, deleted by `discard`. This machine is its image and its size, so it takes neither.
+ * A command's environment is `env(home)` (default: this Node and this process's `PATH`, and
+ * `HOME`), never this process's, under the caller's `env`.
+ */
+export const localBackend = (
+  dir: string,
+  env: (home: string) => Record<string, string> = (home) => ({
+    PATH: [dirname(process.execPath), process.env.PATH || "/usr/bin:/bin"].join(":"),
+    HOME: home,
+  }),
+): SandboxBackend => ({
+  async open({ name }) {
+    const home = boxDir(dir, name);
+    await mkdir(home, { recursive: true });
+    return localBox(name, home, env(home));
+  },
+  discard: ({ name }) => rm(boxDir(dir, name), { recursive: true, force: true }),
+});
+
+function boxDir(dir: string, name: string): string {
+  if (!name || name !== basename(name) || name.startsWith(".")) throw new Error(`${name} is no box's name`);
+  return join(dir, name);
+}
+
+/**
+ * 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. The runner in a remote box
+ * (`sandbox-runner.ts`) serves its own machine's.
+ */
+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);
+  return {
+    id,
+    async run(command, { cwd, env, stdin, signal } = {}): Promise<Process> {
+      const child = spawn("bash", ["-c", command], {
+        cwd: at(cwd ?? "."),
+        env: { ...base, ...env },
+        stdio: "pipe",
+        // Its own process group, so a bridge and what it starts are killed together.
+        detached: true,
+      });
+      const group = child.pid;
+      if (group !== undefined) groups.add(group);
+      child.stdin.on("error", () => {});
+      if (!stdin) child.stdin.end();
+      let ended = false;
+      const exited = new Promise<{ exitCode: number }>((done) => {
+        child.on("error", () => done({ exitCode: 127 }));
+        // Exited when it exits, not when its pipes close: what it left running may hold them. What
+        // it printed last still arrives, so the end waits a moment for that.
+        child.on("exit", (code) => {
+          ended = true;
+          // Forgotten once none of its group is left, so `stop` kills no group its pid leads later.
+          if (group !== undefined && !groupAlive(group)) groups.delete(group);
+          const end = () => done({ exitCode: code ?? 1 });
+          child.on("close", end);
+          setTimeout(end, PIPES_WAIT).unref();
+        });
+      });
+      const kill = (sig: NodeJS.Signals = "SIGKILL") => {
+        // Once it has ended, only while its group is left, so a reused pid is never hit.
+        if (group !== undefined && (!ended || groupAlive(group))) killGroup(group, sig);
+      };
+      const onAbort = () => kill();
+      if (signal?.aborted) onAbort();
+      signal?.addEventListener("abort", onAbort, { once: true });
+      void exited.then(() => signal?.removeEventListener("abort", onAbort));
+      return {
+        stdin: Writable.toWeb(child.stdin) as WritableStream<Uint8Array>,
+        stdout: web(child.stdout),
+        stderr: web(child.stderr),
+        wait: () => exited,
+        kill,
+      };
+    },
+    // A Buffer is a Uint8Array: no copy.
+    read: (path) => readFile(at(path)).catch(() => null),
+    async write(path, bytes, { mode } = {}) {
+      await mkdir(dirname(at(path)), { recursive: true });
+      await writeFile(at(path), bytes);
+      if (mode !== undefined) await chmod(at(path), mode);
+    },
+    /** A port on loopback. */
+    expose: async (port) => ({ url: `http://127.0.0.1:${port}` }),
+    /** Kills every command's process group: what a bridge started too. */
+    async stop() {
+      for (const group of groups) killGroup(group);
+      groups.clear();
+    },
+  };
+}
+
+/** How long a command's last output may take to arrive after it exits, in ms. */
+const PIPES_WAIT = 200;
+
+const web = (stream: Readable) => Readable.toWeb(stream) as ReadableStream<Uint8Array>;
+
+/** Whether any process of the group `group` is left. */
+function groupAlive(group: number): boolean {
+  try {
+    process.kill(-group, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Kills the process group `group` (a `detached` child's pid). */
+function killGroup(group: number, signal: NodeJS.Signals = "SIGKILL") {
+  try {
+    process.kill(-group, signal);
+  } catch {
+    // Gone already.
+  }
+}

package/src/op.ts

@@ -5,6 +5,7 @@ import type { ConnectionSnapshot } from "./connection.ts";
 import type { ProviderV4 } from "@ai-sdk/provider";
 import type { z } from "zod";
 import type { Fake } from "./fake.ts";
+import type { SandboxBackend, SandboxContext } from "./sandbox-contract.ts";
 import type { Secrets } from "./secret.ts";
 import type { RemoteHalf } from "./source.ts";
 import type { Steps } from "./steps.ts";
@@ -325,8 +326,8 @@ export interface Driver {
  * to call: the config then names the connector alone, and never a driver, a fake, steps or a
  * login. Any may be missing: a workflow using an operation of a connector with no driver is
  * refused, a connector with no fake has none for sandbox runs, one with no login half signs no
- * visitor in, one with no model half gives the app no models, and one with no remote half hosts
- * no repository a change is reviewed on.
+ * visitor in, one with no model half gives the app no models, one with no remote half hosts
+ * no repository a change is reviewed on, and one with no sandbox half opens no box.
  */
 export interface ConnectorSetup {
   /** Auth methods available to named connections; login identity is separate. */
@@ -362,6 +363,13 @@ export interface ConnectorSetup {
    * resolved config (`ResolvedConfig.remotes`). It reads its credentials when called.
    */
   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, 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>;
 }
 
 /** What the app gives a connector's model half (`ConnectorSetup.model`): the secrets, as a login half reads them. */

package/src/paths.ts

@@ -1,10 +1,11 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { rootSnapshot } from "./bundled.ts";
 import { APP_NAME, APPS_DIR, appOfPath } from "./shared.ts";
 
 // Where an import may reach, as the lints and the data-file reader all decide it, the one walk up
-// the directories and the one walk down (`filesUnder`). Node's `path` and `fs` only, no parser:
-// the oxlint plugin loads it.
+// the directories and the one walk down (`filesUnder`). Node's `path` and `fs` only (and a
+// bundle's registered roots, plain data), no parser: the oxlint plugin loads it.
 
 /**
  * Where a data file imports `secret` from, and `sanoma`, the runtime's own resource constructors
@@ -70,8 +71,8 @@ export { APPS_DIR, appOfPath };
 /** Each directory's company root (the nearest one with a `sanoma.config.ts`, short of a `node_modules`), once found. */
 const roots = new Map<string, string>();
 
-/** Whether `dir` is a company's root: it holds a `sanoma.config.ts`. */
-const isCompany = (dir: string) => existsSync(join(dir, "sanoma.config.ts"));
+/** Whether `dir` is a company's root: it holds a `sanoma.config.ts`, or a bundle registered its snapshot (`useRootSnapshot`). */
+const isCompany = (dir: string) => rootSnapshot(dir) !== undefined || existsSync(join(dir, "sanoma.config.ts"));
 
 /**
  * The app a file is in: `<app>` for a file under `<root>/apps/<app>/`, where the root is the
@@ -113,5 +114,22 @@ export const kindDirs = (root: string, kind: string): string[] => [
   ...appFolders(root).map((app) => join(app, kind)),
 ];
 
+/**
+ * The files whose declarations join the config's, as `sanoma` loads it and the Worker's bundle
+ * imports them: each workflow source under `workflows/` and each app's (a test or a declaration
+ * file aside), then each `resources/data.ts` there is.
+ */
+export function declarationFiles(root: string): { workflows: string[]; data: string[] } {
+  return {
+    workflows: kindDirs(root, "workflows").flatMap((dir) => filesUnder(dir, isWorkflowSource)),
+    data: kindDirs(root, "resources")
+      .map((dir) => join(dir, COLLECTIONS_FILE))
+      .filter((path) => existsSync(path)),
+  };
+}
+
+/** A workflow file's name: `.ts`, but a test (`.test.ts`, `.spec.ts`) or a declaration. */
+const isWorkflowSource = (name: string) => name.endsWith(".ts") && !/\.(test|spec|d)\.ts$/.test(name);
+
 /** Where a company's scenarios are, under its root and each app's folder. */
 export const SCENARIOS_DIR = "scenarios";

package/src/resource.ts

@@ -4,6 +4,7 @@ import { checkDatabase, type DatabaseSpec } from "./database.ts";
 import { isRunControlError } from "./errors.ts";
 import { checkHost, hasPath, type HostSpec } from "./host.ts";
 import { type Connector, type OpSpec, RESOURCE, VENDOR } from "./op.ts";
+import { checkSandbox, type SandboxSpec } from "./sandbox-contract.ts";
 import { isSanomaSecret, isSecret, type Secret } from "./secret.ts";
 import { errorMessage } from "./shared.ts";
 import { checkWakeup, type WakeupSpec } from "./wakeup.ts";
@@ -114,6 +115,11 @@ export interface ResourceSpec<S extends z.ZodObject = z.ZodObject> {
    * is `writable`, not `stateless`, and its `afterCreate` calls the operation `storeUrl` names.
    */
   database?: DatabaseSpec;
+  /**
+   * Set when the type meets the `Sandbox` contract: it runs a coding agent's boxes, which its
+   * connector's backend (`ConnectorSetup.sandbox`) opens. Such a type is `writable`.
+   */
+  sandbox?: SandboxSpec;
   /**
    * True when its objects hold no data, so one gone at the vendor is created again by apply
    * without asking (a host running the company's code); otherwise apply asks first, as a
@@ -366,6 +372,7 @@ export interface Resource<
           | "host"
           | "wakeup"
           | "database"
+          | "sandbox"
           | "stateless"
           | "afterCreate"
           | "vendorless"
@@ -373,7 +380,12 @@ export interface Resource<
         >
       >
     >,
-    Readonly<Pick<ResourceSpec<S>, "identity" | "find" | "host" | "wakeup" | "database" | "afterCreate" | "formerly">> {
+    Readonly<
+      Pick<
+        ResourceSpec<S>,
+        "identity" | "find" | "host" | "wakeup" | "database" | "sandbox" | "afterCreate" | "formerly"
+      >
+    > {
   (
     desired: Declaring<z.input<S>, R>,
     options?: { connection?: ConnectionRef<Id extends `${infer V}.${string}` ? V : string> },
@@ -710,12 +722,13 @@ export function defineResource<
 >(
   spec: ResourceSpec<S> & { vendor: V; type: T; fields: { references?: R }; writable?: W },
 ): Resource<S, `${V}.${T}`, R, W> {
-  const { vendor, type, schema, fields, find, identity, host, wakeup, database } = spec;
+  const { vendor, type, schema, fields, find, identity, host, wakeup, database, sandbox } = spec;
   const writable = (spec.writable ?? false) as W;
   const what: `${V}.${T}` = `${vendor}.${type}`;
   if (host) checkHost(what, host, spec);
   if (wakeup) checkWakeup(what, wakeup, spec);
   if (database) checkDatabase(what, database, spec);
+  if (sandbox) checkSandbox(what, sandbox, spec);
   if (spec.vendorless && (writable || host))
     throw new Error(`${what}: a vendorless type has no object to change or host`);
   const title = spec.title.toLowerCase();
@@ -908,6 +921,7 @@ export function defineResource<
     ...(host && { host }),
     ...(wakeup && { wakeup }),
     ...(database && { database }),
+    ...(sandbox && { sandbox }),
     stateless: spec.stateless ?? host !== undefined,
     vendorless: spec.vendorless ?? false,
     ...(spec.afterCreate && { afterCreate: spec.afterCreate }),

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(", ")}`,
       );
     }
   }