@sanoma-ai/workflows 0.11.15 → 0.11.17

package/src/local-sandbox.ts

@@ -0,0 +1,132 @@
+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.
+ */
+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,12 @@ 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, when a coding agent's turn needs a box. It reads its
+   * credentials through `context.secrets`.
+   */
+  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/run.ts

@@ -1,7 +1,10 @@
 import type { ConnectionRef, ConnectionRegistry, ConnectionSnapshot } from "./connection.ts";
 import { AsyncLocalStorage } from "node:async_hooks";
+import type { WorkerApp } from "./app-steps.ts";
+import type { SanomaClient } from "./client.ts";
 import type { Collection } from "./collection.ts";
 import type { DeclaredObjects } from "./config.ts";
+import type { Db } from "./db.ts";
 import type { DeadlineRegistry } from "./deadlines.ts";
 import type { ApprovalState, Approver, Principal, WorkflowDefinition } from "./define.ts";
 import type { Fake } from "./fake.ts";
@@ -53,6 +56,24 @@ export interface WorkerState {
   scenarios?: URL;
   /** The worker's `source`, when it was given one. */
   source?: Source;
+  /** The app's steps (`WorkerOptions.app`): what the app's built-ins run; none without them. */
+  appSteps?: WorkerApp;
+  /**
+   * The worker's own client, connected on first use, for its version (what it starts runs on);
+   * closed when the worker stops. What the built-ins' steps tell and read through, never a run's body.
+   */
+  client(): Promise<SanomaClient>;
+  /** Runs `write` once the one before it has settled: the worker's writes to its repository, one at a time. */
+  serially<T>(write: () => Promise<T>): Promise<T>;
+  /**
+   * Fast-forwards the checkout to the host's `main` (`followBase`), one of the worker's writes
+   * (`serially`), as a change's deploy and a push to `main` do first; on a new revision, how far
+   * each app taken from a source is behind it is checked again, in the background, into the
+   * runtime's table (`recordAppsBehind` in worker.ts), as at the worker's start.
+   */
+  followMain(): Promise<{ revision: string } | { skipped: string } | { error: string }>;
+  /** The runtime's tables (`db.ts`): what the worker writes for the app to read, such as a sandbox run's checks. */
+  db(): Promise<Db>;
   types: ReadonlyMap<string, Resource>;
   /** The objects the data files declare, read at each call: a workflow's change operation may not aim at one (`refuseDeclared`). */
   declaredObjects(): Promise<DeclaredObjects>;
@@ -88,6 +109,11 @@ export interface WorkerState {
   stopped: boolean;
   /** Which of its runs are executing and which wait, until when: what the worker's `idle` reads. */
   deadlines: DeadlineRegistry;
+  /**
+   * Aborted once the worker has stopped, after DBOS is down: what work of its that outlives a DBOS
+   * call stops on (a chat turn's agent, the check of the apps behind), recorded nowhere.
+   */
+  shutdown: AbortSignal;
 }
 
 /** What a run keeps in memory. Rebuilt the same way when DBOS replays the run. */
@@ -136,3 +162,18 @@ export interface WorkflowOutline {
  * it, whether it is a sandbox run, the worker's source and policy), as no `ctx` member gives them.
  */
 export const currentRun = new AsyncLocalStorage<Run>();
+
+/** The run whose built-in step is running (`currentRun`): `what` names the step for the error when there is none. */
+export function runNow(what: string): Run {
+  const run = currentRun.getStore();
+  if (!run) throw new Error(`${what} ran outside its run`);
+  return run;
+}
+
+/**
+ * A sandbox run's checks recorded for the app (`recordChecks`, which never throws); nothing for a
+ * live run, which never loads `sandbox.ts`, and with it Cucumber.
+ */
+export async function recordSandboxChecks(run: Run): Promise<void> {
+  if (run.sandbox !== undefined) await (await import("./sandbox.ts")).recordChecks(run, run.sandbox);
+}

package/src/sandbox-contract.ts

@@ -0,0 +1,114 @@
+import type { z } from "zod";
+import { hasPath } from "./host.ts";
+import type { LoginContext } from "./op.ts";
+
+// The `Sandbox` contract: what a resource type that runs a coding agent's box (an Agent37
+// instance) declares about itself, beside `Host`, `Database` and `Wakeup`, and the backend its
+// connector attaches (`ConnectorSetup.sandbox`) to open one box per name, so boxes are swappable
+// and one conformance kit decides whether one works. Vendor- and library-neutral: web streams,
+// no AI SDK. (`sandbox.ts` is something else: a scenario's run over the fakes.)
+
+/** What a sandbox can do, for choosing one: declared, never checked at runtime. */
+export interface SandboxCapabilities {
+  /** A box's files, its home's too, survive `stop` and the next `open` of its name. */
+  snapshot: boolean;
+  /** A stopped box keeps its memory and processes, and resumes them on the next `open`. */
+  pause: boolean;
+  /** `expose` makes a port of the box reachable from outside it. */
+  port: boolean;
+}
+
+/** What a sandbox's state says of it. */
+export interface SandboxOutputs {
+  id: string;
+  healthy: boolean;
+}
+
+/**
+ * A resource type's `sandbox`: the fields its boxes' choices are in, by dotted path into its
+ * declared fields, and how its state reads. The vendor's own facts (its region, its type of
+ * machine) are fields of the resource, never read from the environment.
+ */
+export interface SandboxSpec {
+  capabilities: SandboxCapabilities;
+  inputs: {
+    /** The image a box runs. */
+    image: string;
+    /** A box's size, in vCPUs: its memory follows the vendor's shapes. */
+    size: string;
+  };
+  outputs: (state: Record<string, unknown>) => SandboxOutputs;
+}
+
+/** A process `Box.run` started: `bash -c <command>`. */
+export interface Process {
+  /** Its stdin: closed at once unless `run` was given `stdin: true`. */
+  stdin: WritableStream<Uint8Array>;
+  /** Its stdout, as it prints, ended once it has exited. */
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+  /** Resolves when it has exited: non-zero when it failed or was killed. */
+  wait(): Promise<{ exitCode: number }>;
+  /** Kills it and what it started (default `SIGKILL`). */
+  kill(signal?: NodeJS.Signals): void;
+}
+
+/**
+ * A box: a computer of its own a coding agent works in. A relative `path` or `cwd` is under the
+ * box's home (`$HOME`), which a backend with `snapshot` keeps across `stop`.
+ */
+export interface Box {
+  /** The vendor's id of it. */
+  id: string;
+  /** Runs `bash -c <command>`, in `cwd`, with `env` over the box's own. An abort kills it. */
+  run(
+    command: string,
+    opts?: { cwd?: string; env?: Record<string, string>; stdin?: boolean; signal?: AbortSignal },
+  ): Promise<Process>;
+  /** A file's bytes; null when there is none. */
+  read(path: string): Promise<Uint8Array | null>;
+  /** Writes a file, its directories made. */
+  write(path: string, bytes: Uint8Array, opts?: { mode?: number }): Promise<void>;
+  /** Where its `port` is reached from outside it, with the headers that reach it. */
+  expose(port: number): Promise<{ url: string; headers?: Record<string, string> }>;
+  /** Stops it and every process in it; the next `open` of its name finds what it kept. */
+  stop(): Promise<void>;
+}
+
+/**
+ * A connector's boxes (`ConnectorSetup.sandbox`). A box is keyed by `name`, under which the
+ * 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>;
+  /** 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">;
+
+/**
+ * Throws what is wrong with a resource type's `sandbox`: a type apply cannot change (not
+ * `writable`), a capability that is not a boolean, an input that names no field, `outputs` that
+ * is not a function.
+ */
+export function checkSandbox(
+  what: string,
+  sandbox: SandboxSpec,
+  type: { schema: z.ZodObject; writable?: boolean },
+): void {
+  const problems: string[] = [];
+  if (!type.writable) problems.push("it must be writable, so apply can create and update it");
+  const capabilities: Partial<SandboxCapabilities> = sandbox.capabilities ?? {};
+  for (const name of ["snapshot", "pause", "port"] as const) {
+    if (typeof capabilities[name] !== "boolean") problems.push(`capabilities.${name} must be true or false`);
+  }
+  for (const input of ["image", "size"] as const) {
+    const path: unknown = sandbox.inputs?.[input];
+    if (typeof path !== "string" || !hasPath(type.schema, path)) problems.push(`${input} names no field (${path})`);
+  }
+  if (typeof sandbox.outputs !== "function") problems.push("outputs must be a function of the state");
+  if (problems.length) throw new Error(`${what}: its sandbox: ${problems.join("; ")}`);
+}

package/src/sandbox.ts

@@ -9,8 +9,10 @@ import { entry, type LedgerRecord, write } from "./ledger.ts";
 import type { DriverFn } from "./op.ts";
 import type { Run } from "./run.ts";
 import { memorySecrets } from "./secret.ts";
-import { type Given, loadScenarios, type Scenario } from "./scenario.ts";
-import { errorMessage } from "./shared.ts";
+import { writeRunChecks } from "./db.ts";
+import { warn } from "./log.ts";
+import { check, type Given, loadScenarios, type RunChecks, type Scenario } from "./scenario.ts";
+import { errorMessage, notLoaded } from "./shared.ts";
 
 /*
  * What a worker does for a sandbox run, imported only when it starts one: kept apart from
@@ -125,8 +127,9 @@ export async function seedSandbox(run: Run, name: string, input: unknown): Promi
       const { scenarios, errors } = await loadScenarios(state);
       const scenario = scenarios.find((s) => s.name === name);
       if (!scenario) {
-        const why = errors.length ? `; these files did not load: ${errors.map((e) => e.message).join("; ")}` : "";
-        throw new SanomaError("invalid_input", `No scenario named "${name}"${why}`, { scenario: name });
+        throw new SanomaError("invalid_input", `No scenario named "${name}"${notLoaded(errors)}`, {
+          scenario: name,
+        });
       }
       if (scenario.workflow !== run.workflow) {
         throw new SanomaError("invalid_input", `Scenario "${name}" runs ${scenario.workflow}, not ${run.workflow}`, {
@@ -214,3 +217,37 @@ export async function seedSandbox(run: Run, name: string, input: unknown): Promi
   run.fakeSecrets = secrets;
   await write(run, entry(run, { type: "scenario.seeded", scenario: name, seeds }));
 }
+
+/**
+ * A seeded sandbox run's checks against its ledger so far, written for the app (`writeRunChecks`):
+ * Cucumber runs its scenario's Then steps over the feature file as it reads now, which the agent
+ * may have changed since. Called when the run waits and when it ends (`recordSandboxChecks`); a
+ * check met is settled when what it expects stays so (a call made, a decision recorded), and every
+ * one once the run has ended, which the app reads from the run's status. No step and no ledger
+ * record, so a replay neither depends on it nor differs by it: a failure is warned about, and the
+ * run goes on.
+ */
+export async function recordChecks(run: Run, name: string): Promise<void> {
+  if (!run.fakeDrivers) return;
+  const { state } = run;
+  try {
+    const checks = await checksOf(run, name).catch((err: unknown): RunChecks => ({ error: errorMessage(err) }));
+    await writeRunChecks(await state.db(), run.id, checks);
+  } catch (err) {
+    warn(`run ${run.id}: could not record its checks against scenario "${name}": ${errorMessage(err)}`);
+  }
+}
+
+async function checksOf({ id, state }: Run, name: string): Promise<RunChecks> {
+  const loaded = await loadScenarios(state);
+  const scenario = loaded.scenarios.find((s) => s.name === name);
+  if (!scenario) return { error: `The feature files no longer have scenario "${name}"${notLoaded(loaded.errors)}` };
+  const checks = await check(state, scenario, await state.ledger.read(id));
+  return {
+    checks: checks.map((c, i) => {
+      const e = scenario.expect[i]!;
+      // Met once: a call made, or a decision recorded, stays made. Every one is, once the run has ended (`runDetail`).
+      return { ...c, settled: c.ok && (("called" in e && e.called === true) || "decision" in e) };
+    }),
+  };
+}

package/src/scenario.ts

@@ -186,6 +186,23 @@ export interface Check {
   detail?: string;
 }
 
+/** One of a sandbox run's checks, and whether its answer is final. */
+export interface RunCheck extends Check {
+  /**
+   * True once the answer cannot change: the run has ended, or the check expects a call that
+   * has been made (or a decision recorded). Until then a check not met is not failed yet, and
+   * one met (a call not made so far) may still fail.
+   */
+  settled: boolean;
+}
+
+/**
+ * A sandbox run's checks, as the worker ran them when the run last waited or ended (`recordChecks`):
+ * each of its scenario's expectations against its ledger, or why there are none (its scenario is
+ * no longer in the feature files, with those that did not load, or they could not be read at all).
+ */
+export type RunChecks = { checks: RunCheck[] } | { error: string };
+
 /**
  * What steps can name: the config's operations, workflows, resource types and collections by id,
  * the steps its connectors (and the company) ship, where the feature files are, and the root

package/src/schedules.ts

@@ -140,23 +140,38 @@ interface TimeMatcher {
   /** The first instant strictly after `date` that matches; one that does not at the end of its search horizon. */
   nextWakeupTime(date: Date | number): Date;
 }
-type TimeMatcherClass = new (pattern: string, timezone?: string) => TimeMatcher;
+export type TimeMatcherClass = new (pattern: string, timezone?: string) => TimeMatcher;
 
 let matcherClass: TimeMatcherClass | undefined;
 
 /**
- * DBOS's `TimeMatcher`, from `dist/src/scheduler/crontab.js` beside its main module: the package's
- * exports leave it out (dbos-sdk 5.2.11), so it is loaded by path, and a test holds it there.
+ * The file DBOS's `TimeMatcher` is in, `dist/src/scheduler/crontab.js` beside its main module, as
+ * `require` resolves the package: its exports leave it out (dbos-sdk 5.2.11), so it is loaded by
+ * path, and a test holds it there.
  */
+export const timeMatcherFile = (require: NodeJS.Require): string =>
+  join(dirname(require.resolve("@dbos-inc/dbos-sdk")), "scheduler", "crontab.js");
+
+/** DBOS's `TimeMatcher`, required from its file (`timeMatcherFile`), or the one `useTimeMatcher` gave. */
 export function timeMatcher(): TimeMatcherClass {
   if (matcherClass) return matcherClass;
   const require = createRequire(import.meta.url);
-  const file = join(dirname(require.resolve("@dbos-inc/dbos-sdk")), "scheduler", "crontab.js");
+  const file = timeMatcherFile(require);
   const loaded = (require(file) as { TimeMatcher?: unknown }).TimeMatcher;
   if (typeof loaded !== "function") throw new Error(`DBOS's cron parser is not in ${file} any more`);
   return (matcherClass = loaded as TimeMatcherClass);
 }
 
+/**
+ * From now on, DBOS's cron parser is `matcher`, where it cannot be required by path: workerd,
+ * which bundles the runtime, and imports it by its file.
+ */
+export function useTimeMatcher(matcher: TimeMatcherClass): void {
+  if (typeof matcher !== "function")
+    throw new Error("DBOS's cron parser (TimeMatcher) is not in its scheduler's crontab.js any more");
+  matcherClass = matcher;
+}
+
 /**
  * When `schedule` (a cron expression read in `timezone`, UTC without one) fires next, strictly
  * after `from`: as DBOS's scheduler finds it. Throws for a schedule that never fires.

package/src/seal.ts

@@ -2,8 +2,9 @@ import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import { deriveSigningKey, signingKeyFor } from "./deployment-key.ts";
 
 // Small values sealed under a key of their own, derived from the deployment's SANOMA_SIGNING_KEY
-// for one purpose (HKDF-SHA256): a sign-in code in a `login-code` run's input, and a request for
-// an invite that a holder of the key sends to the instance (`POST /auth/invite`). AES-256-GCM, the
+// for one purpose (HKDF-SHA256): a sign-in code in a `login-code` run's input, a code a person
+// pastes back to their own agent's sign-in, in the message to their chat turn's run, and a request
+// for an invite that a holder of the key sends to the instance (`POST /auth/invite`). AES-256-GCM, the
 // purpose as its additional data, so a value sealed for one purpose never opens for another.
 
 const IV = 12;
@@ -40,6 +41,7 @@ function unseal(purpose: string, sealed: string): unknown {
 }
 
 const CODE = "login code";
+const CHAT_CODE = "chat code";
 const INVITE = "invite request";
 
 /**
@@ -57,6 +59,18 @@ export function openLoginCode(sealed: string, to: string): string {
   return opened.code;
 }
 
+/**
+ * A code a person pastes for their own agent's sign-in, sealed for the chat turn's run `runId`
+ * (`SanomaClient.turnCode`), so the run's messages, which DBOS keeps, never show it.
+ */
+export const sealChatCode = (runId: string, code: string): string => seal(CHAT_CODE, { runId, code });
+
+/** The code `sealChatCode` sealed for `runId`; undefined for anything else, a code sealed for another run among it. */
+export function openChatCode(sealed: string, runId: string): string | undefined {
+  const opened = unseal(CHAT_CODE, sealed) as { runId?: unknown; code?: unknown } | undefined;
+  return typeof opened?.code === "string" && opened.runId === runId ? opened.code : undefined;
+}
+
 /** A request for an invite (`POST /auth/invite { request }`): for whom, until when (ms since the epoch), and a nonce. */
 export interface InviteRequest {
   email: string;