@sanoma-ai/workflows 0.11.16 → 0.11.17

package/src/config.ts

@@ -231,6 +231,12 @@ export interface ResolvedConfig {
    * declares a host type.
    */
   hosts(): Promise<string[]>;
+  /**
+   * The resources the data files under `root` declare whose type is a sandbox (`<file>#<export>`),
+   * read at each call: where a coding agent's boxes are opened. None when no connector declares a
+   * sandbox type.
+   */
+  sandboxes(): Promise<string[]>;
   /**
    * The objects the data files under `root` declare, read at each call: what a workflow's change
    * operation may not aim at, since only apply changes a declared object.
@@ -289,6 +295,47 @@ export function defineConfig(config: SanomaConfig): SanomaConfig {
   return { ...config, file: config.file ?? callerFile() };
 }
 
+/**
+ * Joins the declaration files' modules (`declarationFiles`, each by its path) to `config`, as
+ * `sanoma` loads it and the Worker's bundle composes it: a workflow file's default export is a
+ * workflow (`defineWorkflow`), a file without one a helper; each export of a data file is a
+ * collection. One the config lists already is kept, once. A `workflows` or `collections` that is
+ * no list is left for `resolveConfig` to explain. Throws naming the file for an export that is
+ * neither.
+ */
+export function joinDeclarations(
+  config: SanomaConfig,
+  modules: { workflows: [path: string, module: { default?: unknown }][]; data: [path: string, module: object][] },
+): void {
+  if (config.workflows === undefined || Array.isArray(config.workflows)) {
+    const workflows = new Set(config.workflows);
+    for (const [path, { default: wf }] of modules.workflows) {
+      if (wf === undefined) continue;
+      if ((wf as { kind?: unknown } | null)?.kind !== "workflow") {
+        throw new Error(
+          `${path}'s default export is not a workflow: a file of workflows/ exports one, \`export default defineWorkflow({ … })\`, or none (a helper the workflows import)`,
+        );
+      }
+      workflows.add(wf as WorkflowDefinition<any, any>);
+    }
+    if (workflows.size > 0) config.workflows = [...workflows];
+  }
+  if (config.collections === undefined || Array.isArray(config.collections)) {
+    const collections = new Set(config.collections);
+    for (const [path, module] of modules.data) {
+      for (const [name, value] of Object.entries(module)) {
+        if (!isCollection(value)) {
+          throw new Error(
+            `${path} exports ${name}, which is not a collection: resources/data.ts holds collections only, each \`export const ${name} = collection({ name, key, fields })\` with collection from "sanoma/data"`,
+          );
+        }
+        collections.add(value);
+      }
+    }
+    if (collections.size > 0) config.collections = [...collections];
+  }
+}
+
 export function resolveDatabaseUrl(config: { databaseUrl?: string }, env: NodeJS.ProcessEnv = process.env): string {
   return config.databaseUrl ?? env.SANOMA_DATABASE_URL ?? DEFAULT_DATABASE_URL;
 }
@@ -445,13 +492,14 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     names.set(APPLY_WORKFLOW, applyWorkflow(types, ops, drivers, applySteps(appName, root, read)));
   }
   // Built-in, in every config: the life of a change, which deploys to the declared hosts after its merge.
-  // The declared hosts' ids, as the files say them: nothing derived, nothing minted.
-  const hosts = async () => {
+  // The declared hosts' (and sandboxes') ids, as the files say them: nothing derived, nothing minted.
+  const declaredOf = (contract: "host" | "sandbox") => async () => {
     const { loadDataFiles } = await import("./resources.ts");
     return loadDataFiles(root, connectors, declarable)
-      .resources.filter((r) => types.get(`${r.vendor}.${r.type}`)?.host)
+      .resources.filter((r) => types.get(`${r.vendor}.${r.type}`)?.[contract])
       .map((r) => r.id);
   };
+  const hosts = declaredOf("host");
   names.set(CHANGE_WORKFLOW, changeWorkflow(changeOps, changeSteps({ remotes, hosts })));
   // Built-in, in every config: what a git host's webhook says happened, which the worker with the checkout follows.
   names.set(FOLLOW_WORKFLOW, followWorkflow(followSteps({ remotes, hosts })));
@@ -494,6 +542,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     models: makersOf(config.connectors, "model"),
     remotes,
     hosts,
+    sandboxes: declaredOf("sandbox"),
     declaredObjects,
     ...(scenarios && { scenarios }),
     types,

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({

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,16 @@ 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 type { Chat, Chats } from "./chats.ts";
 export type { Tokens } from "./tokens.ts";
 export { type InviteRequest, openInvite, sealInvite, sealLoginCode } from "./seal.ts";

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/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/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.