@agentswf/engine 0.0.0-stage → 0.1.0-beta.1

package/src/result-slots.ts

@@ -0,0 +1,325 @@
+import { acceptAny, type SemanticCheck } from "@agentswf/contract";
+import type { CandidateSource } from "@agentswf/contract/records";
+import type { JsonSchema } from "@agentswf/contract/schema";
+import type { ResultSubmitCode } from "@agentswf/contract/wire";
+import type { AbsoluteDeadline } from "@agentswf/contract/workflow";
+import { scheduleAt } from "./deadlines";
+import { evaluateResult } from "./result-validation";
+import { recordCandidate, writeAcceptedExclusive, writeCall } from "./runs";
+
+export type ResultRejectionCode = ResultSubmitCode;
+export type ResultSlotAccepted = {
+  kind: "accepted";
+  value: unknown;
+  candidateRecorded: boolean;
+  /** Eligibility was reserved at this time, before persistence began. */
+  admittedAt: number;
+  /** The exclusive result write completed at this time. */
+  acceptedAt: number;
+};
+type Rejected = { kind: "rejected"; code: ResultRejectionCode; error: string };
+export type ResultSubmission = ResultSlotAccepted | Rejected;
+export type WaitingGrant = { kind: "waiting"; waitUntil: number; deadline: number };
+export type ResultSlotSettlement =
+  | ResultSlotAccepted
+  | { kind: "closed" }
+  | { kind: "expired" }
+  | { kind: "failed"; reason: string };
+export type ResultSlotEvent =
+  | { kind: "waiting"; reason: string; waitUntil: number; at: number; revision: number }
+  | { kind: "admitted"; admittedAt: number; revision: number }
+  | { kind: "persisted"; accepted: ResultSlotAccepted; revision: number };
+export type ResultSlotBinding = { operationId: string; settled: Promise<ResultSlotSettlement> };
+export type ResultSlotSpec = {
+  operationId: string;
+  agentId: string;
+  question: string;
+  schema?: JsonSchema;
+  semantic?: SemanticCheck;
+  deadline: AbsoluteDeadline;
+  allowWaiting?: boolean;
+  onEvent?(event: ResultSlotEvent): void;
+};
+export type ResultSlotRegistryOptions = {
+  runDir: string;
+  now?: () => number;
+  schedule?: (delayMilliseconds: number, expire: () => void) => () => void;
+  persistence?: ResultSlotPersistence;
+  persistenceMs?: number;
+  auditMs?: number;
+  waitDefaultMs?: number;
+  waitMinimumMs?: number;
+};
+interface ResultSlotPersistence {
+  writeCall: typeof writeCall;
+  recordCandidate: typeof recordCandidate;
+  writeAcceptedExclusive: typeof writeAcceptedExclusive;
+}
+type SubmissionInput = {
+  operationId: string;
+  agentId: string;
+  raw: string;
+  source: CandidateSource;
+};
+export interface ResultSlotRegistry {
+  open(spec: ResultSlotSpec): Promise<ResultSlotBinding>;
+  submit(input: SubmissionInput): Promise<ResultSubmission>;
+  waiting(input: {
+    operationId: string;
+    agentId: string;
+    reason: string;
+    timeoutMs?: number;
+  }): Promise<WaitingGrant | Rejected>;
+  close(operationId: string): Promise<boolean>;
+}
+type Slot = ResultSlotSpec & {
+  state: "open" | "committing" | "accepted" | "closed" | "expired" | "failed";
+  settle(value: ResultSlotSettlement): void;
+  cancelExpiry(): void;
+  revision: number;
+};
+
+export function createResultSlotRegistry(options: ResultSlotRegistryOptions): ResultSlotRegistry {
+  const now = options.now ?? Date.now;
+  const schedule = options.schedule ?? scheduleExpiry;
+  const persistence = options.persistence ?? { writeCall, recordCandidate, writeAcceptedExclusive };
+  const persistenceMs = duration(options.persistenceMs, 5_000);
+  const auditMs = duration(options.auditMs, 1_000);
+  const waitDefaultMs = duration(options.waitDefaultMs, 120_000);
+  const waitMinimumMs = duration(options.waitMinimumMs, 30_000);
+  const slots = new Map<string, Slot>();
+  const bounded = <T>(pending: Promise<T>, milliseconds: number, reason: string): Promise<T> => {
+    let cancel = () => {};
+    const expiry = new Promise<never>((_resolve, reject) => {
+      cancel = schedule(milliseconds, () => reject(new SlotTimeoutError(reason)));
+    });
+    return Promise.race([pending, expiry]).finally(() => cancel());
+  };
+  const audit = async (
+    slot: Slot,
+    input: SubmissionInput,
+    accepted: boolean,
+    error?: string,
+  ): Promise<boolean> => {
+    try {
+      await bounded(
+        Promise.resolve().then(() =>
+          persistence.recordCandidate(options.runDir, slot.operationId, {
+            at: new Date(now()).toISOString(),
+            source: input.source,
+            raw: input.raw,
+            accepted,
+            ...(error === undefined ? {} : { error }),
+          }),
+        ),
+        auditMs,
+        "candidate recording timed out",
+      );
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const rejectKnown = async (
+    slot: Slot,
+    input: SubmissionInput,
+    code: ResultRejectionCode,
+    error: string = code,
+  ): Promise<Rejected> => {
+    await audit(slot, input, false, error);
+    return rejected(code, error);
+  };
+
+  return {
+    async open(spec) {
+      if (slots.has(spec.operationId))
+        throw new Error(`result slot already exists for operation ${spec.operationId}`);
+      let settle!: (value: ResultSlotSettlement) => void;
+      const settled = new Promise<ResultSlotSettlement>((resolve) => {
+        settle = resolve;
+      });
+      const slot: Slot = { ...spec, state: "open", settle, cancelExpiry: () => {}, revision: 0 };
+      slots.set(spec.operationId, slot);
+      try {
+        await bounded(
+          Promise.resolve().then(() =>
+            persistence.writeCall(options.runDir, {
+              callId: spec.operationId,
+              question: spec.question,
+              ...(spec.schema ? { schema: spec.schema } : {}),
+            }),
+          ),
+          persistenceMs,
+          "call persistence timed out",
+        );
+      } catch (error) {
+        if (error instanceof SlotTimeoutError) {
+          // The old write may still publish; its operation ID must never be reused.
+          slot.state = "failed";
+          slot.settle({ kind: "failed", reason: error.message });
+        } else slots.delete(spec.operationId);
+        throw error;
+      }
+      if (slot.state === "open") {
+        if (now() >= spec.deadline.unixMilliseconds) closeSlot(slot, "expired");
+        else
+          slot.cancelExpiry = schedule(spec.deadline.unixMilliseconds - now(), () => {
+            if (slot.state === "open") closeSlot(slot, "expired");
+          });
+      }
+      return { operationId: spec.operationId, settled };
+    },
+
+    async waiting(input) {
+      const slot = slots.get(input.operationId);
+      if (!slot) return rejected("unknown-operation");
+      if (input.agentId !== slot.agentId) return rejected("wrong-agent");
+      const unavailable = unavailableCode(slot, now());
+      if (unavailable) return rejected(unavailable);
+      if (!slot.allowWaiting)
+        return rejected("unsupported-command", "waiting is unavailable for this operation");
+      if (
+        typeof input.reason !== "string" ||
+        input.reason.trim() === "" ||
+        new TextEncoder().encode(input.reason).byteLength > 2048
+      )
+        return rejected("invalid-request", "waiting reason must contain 1 to 2048 UTF-8 bytes");
+      if (
+        input.timeoutMs !== undefined &&
+        (!Number.isSafeInteger(input.timeoutMs) || input.timeoutMs <= 0)
+      )
+        return rejected("invalid-request", "waiting timeout must be a positive safe integer");
+      const at = now();
+      const remaining = slot.deadline.unixMilliseconds - at;
+      if (remaining <= 0) {
+        closeSlot(slot, "expired");
+        return rejected("expired-operation");
+      }
+      const waitUntil =
+        at + Math.min(Math.max(input.timeoutMs ?? waitDefaultMs, waitMinimumMs), remaining);
+      notify(slot, {
+        kind: "waiting",
+        reason: input.reason,
+        waitUntil,
+        at,
+        revision: ++slot.revision,
+      });
+      return { kind: "waiting", waitUntil, deadline: slot.deadline.unixMilliseconds };
+    },
+
+    async submit(input) {
+      const slot = slots.get(input.operationId);
+      if (!slot) return rejected("unknown-operation");
+      if (input.agentId !== slot.agentId) return rejected("wrong-agent");
+      const unavailable = unavailableCode(slot, now());
+      if (unavailable) return rejectKnown(slot, input, unavailable);
+      const evaluated = await evaluateResult(slot, input.raw, slot.semantic ?? acceptAny);
+      const admittedAt = now();
+      const late = unavailableCode(slot, admittedAt);
+      if (late) return rejectKnown(slot, input, late);
+      if (evaluated.kind === "rejected")
+        return rejectKnown(slot, input, "invalid-result", evaluated.error);
+
+      // No await crosses admission: other commands observe the reservation before I/O starts.
+      slot.state = "committing";
+      slot.cancelExpiry();
+      notify(slot, { kind: "admitted", admittedAt, revision: ++slot.revision });
+      const writing = Promise.resolve().then(() =>
+        persistence.writeAcceptedExclusive(options.runDir, slot.operationId, evaluated.value),
+      );
+      let acceptedAt: number | undefined;
+      void writing.then(
+        (won) => {
+          if (won) acceptedAt = now();
+        },
+        () => {},
+      );
+      let won: boolean;
+      try {
+        won = await bounded(writing, persistenceMs, "result persistence timed out");
+      } catch (error) {
+        void writing.then(
+          async (saved) => {
+            if (!saved) return;
+            const accepted: ResultSlotAccepted = {
+              kind: "accepted",
+              value: evaluated.value,
+              admittedAt,
+              acceptedAt: acceptedAt ?? now(),
+              candidateRecorded: await audit(slot, input, true),
+            };
+            notify(slot, { kind: "persisted", accepted, revision: ++slot.revision });
+          },
+          () => {},
+        );
+        const reason = error instanceof Error ? error.message : String(error);
+        if (slot.state === "committing") {
+          slot.state = "failed";
+          slot.settle({ kind: "failed", reason });
+        }
+        throw error;
+      }
+      if (!won) {
+        closeSlot(slot, "closed");
+        return rejectKnown(slot, input, "closed-operation");
+      }
+      const accepted: ResultSlotAccepted = {
+        kind: "accepted",
+        value: evaluated.value,
+        admittedAt,
+        acceptedAt: acceptedAt ?? now(),
+        candidateRecorded: await audit(slot, input, true),
+      };
+      if (slot.state === "committing") {
+        slot.state = "accepted";
+        slot.settle(accepted);
+      }
+      notify(slot, { kind: "persisted", accepted, revision: ++slot.revision });
+      return accepted;
+    },
+
+    async close(operationId) {
+      const slot = slots.get(operationId);
+      if (!slot || (slot.state !== "open" && slot.state !== "committing")) return false;
+      closeSlot(slot, now() >= slot.deadline.unixMilliseconds ? "expired" : "closed");
+      return true;
+    },
+  };
+}
+
+function unavailableCode(slot: Slot, now: number): ResultRejectionCode | null {
+  if (slot.state === "expired") return "expired-operation";
+  if (slot.state !== "open") return "closed-operation";
+  if (now >= slot.deadline.unixMilliseconds) {
+    closeSlot(slot, "expired");
+    return "expired-operation";
+  }
+  return null;
+}
+function closeSlot(slot: Slot, state: "closed" | "expired"): void {
+  if (slot.state !== "open" && slot.state !== "committing") return;
+  slot.state = state;
+  slot.cancelExpiry();
+  slot.settle({ kind: state });
+}
+function notify(slot: Slot, event: ResultSlotEvent): void {
+  try {
+    slot.onEvent?.(event);
+  } catch {
+    /* An observer cannot undo admission. */
+  }
+}
+function rejected(code: ResultRejectionCode, error: string = code): Rejected {
+  return { kind: "rejected", code, error };
+}
+function duration(value: number | undefined, fallback: number): number {
+  const actual = value ?? fallback;
+  if (!Number.isSafeInteger(actual) || actual <= 0)
+    throw new Error("slot durations must be positive safe integers");
+  return actual;
+}
+function scheduleExpiry(delayMilliseconds: number, expire: () => void): () => void {
+  return scheduleAt({ unixMilliseconds: Date.now() + delayMilliseconds }, expire);
+}
+
+class SlotTimeoutError extends Error {}

package/src/result-validation.ts

@@ -0,0 +1,47 @@
+import { acceptAny, type SemanticCheck } from "@agentswf/contract";
+import type { CallSpec } from "@agentswf/contract/records";
+import { formatErrors, validate } from "@agentswf/contract/schema";
+import { messageOf } from "./errors";
+
+export type CandidateEvaluation =
+  | { kind: "accepted"; value: unknown }
+  | { kind: "rejected"; error: string };
+
+/** Validates without repairing or persisting; the result-slot transition owns acceptance. */
+export async function evaluateResult(
+  call: Pick<CallSpec, "question" | "schema">,
+  raw: string,
+  semantic: SemanticCheck = acceptAny,
+): Promise<CandidateEvaluation> {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch (error) {
+    const reason = messageOf(error);
+    return {
+      kind: "rejected",
+      error: [
+        `the value is not valid JSON: ${reason}`,
+        `expected: ${expectedShape(call)}`,
+        "send one JSON value, quoted as a single shell argument.",
+      ].join("\n"),
+    };
+  }
+
+  if (call.schema) {
+    const errors = validate(call.schema, value);
+    if (errors.length > 0) return { kind: "rejected", error: formatErrors(errors) };
+  }
+
+  const verdict = await semantic({ question: call.question, value: structuredClone(value) });
+  return verdict.kind === "accepted"
+    ? { kind: "accepted", value }
+    : {
+        kind: "rejected",
+        error: `the value does not answer what was asked: ${verdict.reason}`,
+      };
+}
+
+function expectedShape(call: Pick<CallSpec, "schema">): string {
+  return call.schema ? JSON.stringify(call.schema) : "any JSON value";
+}

package/src/run-command.ts

@@ -0,0 +1,242 @@
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import type { JsonValue } from "@agentswf/contract/workflow";
+import { parseDuration } from "./duration";
+import { messageOf } from "./errors";
+import { SESSION_CODE } from "./here";
+import { idProblem, runRootOf, stageNameProblem } from "./runs";
+
+const DEFAULT_TIMEOUT = "1h";
+
+export const usage = [
+  "usage: awf run [options] <workflow-file> [options] [-- workflow arguments...]",
+  "       awf run [options] <workflow-file> --continue <id>",
+  "       awf init [dir] [--no-install]",
+  "       awf test [paths...] [-t <pattern>] [--watch] [--timeout <duration>]",
+  "       awf allowance [harness...] [--json]",
+  "       awf runs [<run>] [--json]          (awf runs -h)",
+  "       awf logs [<run>] [--after <cursor>] [--wait <seconds>] [--json]   (awf logs -h)",
+  "       awf --version",
+  "run options: --id <id>, --continue <id>, --from-stage <stage>, --values <file>,",
+  "             --timeout <duration>, --run-root <directory>, --cwd <directory>, --sandbox <file>,",
+  "             --json, --no-watch, --here",
+  "",
+  "Each awf run is an attempt of a run: a new run, with --id's id or a generated one, or the run",
+  "--continue names, with the arguments, --cwd and --sandbox it was started with. A continue reuses",
+  "the stages that succeeded, up to the first with no record or to --from-stage, and runs the rest.",
+  "A new run with --from-stage starts there. A stage before it with no record to reuse takes its",
+  "value from --values, a JSON object by stage name, checked by its result; one that returns",
+  "nothing is passed. Without one the attempt stops, naming the stage and its schema.",
+  "A stop exits 3. A run is kept in .awf/runs/<workflow>/<id> under --cwd, unless --run-root names",
+  "another folder for .awf/runs.",
+  "The deadline defaults to 1h, per attempt.",
+  "A workflow that knows how to present its result prints that; --json prints the full result instead.",
+  "Either way the full result is kept as output.json in the run's folder, beside report.md",
+  "when the workflow writes one. A run that fails or is cancelled once its agents have started keeps",
+  "output.json too, with what it spent and why it ended; --json prints it. A second Ctrl-C stops",
+  "awf at once, without it.",
+  "--cwd sets the directory the workflow and its agents work in; it defaults to the current one.",
+  "--sandbox puts every agent of the run in one sandbox, working in --cwd; the file is a JSON spec",
+  'such as {"read": ["/data/request.md"], "srt": {}}, whose relative paths are from --cwd. A',
+  "workflow that opens a sandbox of its own is refused.",
+  "A sandbox with its own Herdr, as a docker box has, gets a tab in the run's workspace showing its",
+  "panes; --no-watch leaves it out, and awf still prints the command that shows them.",
+  "--here, run by an agent in a Herdr pane, starts the run in a new tab and has it take that agent's",
+  "session over as one of its agents, from its next turn until the run ends. It prints a line for",
+  "the agent to end its turn with, which is how the run finds the session.",
+  "",
+  "Examples:",
+  "  awf run examples/minimum-review/review-loop.ts",
+  "  awf run --timeout 20m examples/minimum-review/review-loop.ts",
+  "  awf run examples/minimum-review/review-loop.ts -- packages/engine/src",
+  "  awf run examples/minimum-review/review-loop.ts --cwd ../other-repo",
+  "",
+  "Workflow files are trusted code and run with your filesystem and process authority.",
+].join("\n");
+
+export type RunCommand = {
+  /** Where paths typed on the command line resolve. */
+  shellCwd: string;
+  /** Where the workflow and its agents work. */
+  cwd: string;
+  /** Whether `--cwd` gave it, which a continue checks against its run's. */
+  cwdGiven: boolean;
+  /** Whether `--run-root` gave the run root, which the command that goes on repeats. */
+  runRootGiven: boolean;
+  workflowFile: string;
+  workflowArgs: string[];
+  /** As typed, for the attempt's record. */
+  timeout: string;
+  timeoutMilliseconds: number;
+  runRoot: string;
+  /** A new run's id, as `--id` gave it. */
+  id?: string;
+  /** The run `--continue` adds an attempt to. */
+  continueId?: string;
+  /** The stage the attempt starts at, reusing those before it. */
+  fromStage?: string;
+  /** `--values`: its file, and each stage's value in it. */
+  values?: { file: string; stages: ReadonlyMap<string, JsonValue> };
+  json: boolean;
+  /** Whether each sandbox with its own Herdr gets a tab attached to it in the run's workspace. */
+  watch: boolean;
+  /** The sandbox every agent runs in, as `--sandbox`'s file gave it. */
+  sandbox?: unknown;
+  /** Started from an agent's shell: start the run in a tab and take that session over. */
+  here: boolean;
+  /** The code the calling session replies with, which the run finds it by. */
+  session?: string;
+};
+
+export function parseCommand(argv: readonly string[], cwd: string): RunCommand {
+  if (argv[0] !== "run") throw new Error("expected the run command");
+  let timeout = DEFAULT_TIMEOUT;
+  let timeoutMilliseconds = parseDuration(DEFAULT_TIMEOUT);
+  let runRoot: string | undefined;
+  let id: string | undefined;
+  let continueId: string | undefined;
+  let fromStage: string | undefined;
+  let values: RunCommand["values"];
+  let cwdGiven = false;
+  let json = false;
+  let watch = true;
+  let workCwd = cwd;
+  let sandbox: unknown;
+  let here = false;
+  let session: string | undefined;
+  let workflowFile: string | undefined;
+  // awf's own options may come before or after the workflow file; only `--` ends them.
+  let index = 1;
+  for (; index < argv.length && argv[index] !== "--"; index += 1) {
+    const option = argv[index]!;
+    if (!option.startsWith("--")) {
+      if (workflowFile !== undefined) throw new Error("put -- before workflow arguments");
+      workflowFile = option;
+      continue;
+    }
+    if (option === "--json") {
+      json = true;
+      continue;
+    }
+    if (option === "--no-watch") {
+      watch = false;
+      continue;
+    }
+    if (option === "--here") {
+      here = true;
+      continue;
+    }
+    const value = argv[index + 1];
+    if (option === "--timeout") {
+      if (!value) throw new Error("--timeout needs a duration such as 30m");
+      timeoutMilliseconds = parseDuration(value);
+      timeout = value;
+    } else if (option === "--run-root") {
+      if (!value) throw new Error("--run-root needs a directory");
+      runRoot = resolve(cwd, value);
+    } else if (option === "--cwd") {
+      if (!value) throw new Error("--cwd needs a directory");
+      workCwd = resolve(cwd, value);
+      cwdGiven = true;
+      if (!statSync(workCwd, { throwIfNoEntry: false })?.isDirectory()) {
+        throw new Error(`--cwd: not a directory: ${workCwd}`);
+      }
+    } else if (option === "--id" || option === "--continue") {
+      if (!value) throw new Error(`${option} needs a run's id`);
+      const problem = idProblem(value);
+      if (problem) throw new Error(`${option}: ${problem}`);
+      if (option === "--id") id = value;
+      else continueId = value;
+    } else if (option === "--from-stage") {
+      if (!value) throw new Error("--from-stage needs a stage's name");
+      const problem = stageNameProblem(value);
+      if (problem) throw new Error(`--from-stage: ${problem}`);
+      fromStage = value;
+    } else if (option === "--values") {
+      if (!value) throw new Error("--values needs a JSON file");
+      if (values !== undefined) throw new Error("--values given twice");
+      values = readValues(resolve(cwd, value));
+    } else if (option === "--session") {
+      if (!value || !SESSION_CODE.test(value))
+        throw new Error("--session needs the code --here printed");
+      session = value;
+    } else if (option === "--sandbox") {
+      if (!value) throw new Error("--sandbox needs a JSON file");
+      if (sandbox !== undefined) throw new Error("--sandbox given twice");
+      sandbox = readSandboxSpec(resolve(cwd, value));
+    } else {
+      throw new Error(`unknown option: ${option}; put workflow arguments after --`);
+    }
+    index += 1;
+  }
+  if (!workflowFile) throw new Error("run needs one workflow file");
+  if (here && session !== undefined) throw new Error("--here and --session do not go together");
+  if (id !== undefined && continueId !== undefined) {
+    throw new Error("--id names a new run and --continue an existing one; give one");
+  }
+  if (values !== undefined && fromStage === undefined) {
+    throw new Error("--values goes with --from-stage: it gives the stages before it");
+  }
+  const workflowArgs = argv.slice(index + 1);
+  return {
+    shellCwd: cwd,
+    cwd: workCwd,
+    cwdGiven,
+    runRootGiven: runRoot !== undefined,
+    workflowFile,
+    workflowArgs,
+    timeout,
+    timeoutMilliseconds,
+    runRoot: runRoot ?? runRootOf(workCwd),
+    ...(id === undefined ? {} : { id }),
+    ...(continueId === undefined ? {} : { continueId }),
+    ...(fromStage === undefined ? {} : { fromStage }),
+    ...(values === undefined ? {} : { values }),
+    json,
+    watch,
+    here,
+    ...(session === undefined ? {} : { session }),
+    ...(sandbox === undefined ? {} : { sandbox }),
+  };
+}
+
+/** `--values`'s file: a JSON object of stage values, by stage name. */
+function readValues(file: string): NonNullable<RunCommand["values"]> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new Error(`--values: ${messageOf(error)}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`--values: ${file} must hold a JSON object, each stage's value by its name`);
+  }
+  for (const stage of Object.keys(parsed)) {
+    const problem = stageNameProblem(stage);
+    if (problem) throw new Error(`--values: ${problem}`);
+  }
+  return { file, stages: new Map(Object.entries(parsed as Record<string, JsonValue>)) };
+}
+
+/** `--sandbox`'s file: an inline sandbox spec, whose working directory is the run's. */
+function readSandboxSpec(file: string): object {
+  let spec: unknown;
+  try {
+    spec = JSON.parse(readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new Error(`--sandbox: ${messageOf(error)}`);
+  }
+  if (typeof spec !== "object" || spec === null || Array.isArray(spec)) {
+    throw new Error(`--sandbox: ${file} must hold a JSON object, a sandbox spec`);
+  }
+  for (const [field, why] of Object.entries(NOT_IN_A_RUN_SANDBOX)) {
+    if (field in spec) throw new Error(`--sandbox: the run's sandbox names no ${field}; ${why}`);
+  }
+  return spec;
+}
+
+const NOT_IN_A_RUN_SANDBOX = {
+  cwd: "it works in --cwd",
+  key: 'awf keys it "run"',
+  provider: 'its provider is its setting, such as "srt": {}',
+};