@agentswf/engine 0.1.0-beta.2 → 0.1.0-beta.4

package/src/runs.ts

@@ -14,7 +14,7 @@ import {
   type StageRecord,
   type TurnRecord,
 } from "@agentswf/contract/records";
-import type { AttemptOutcome } from "@agentswf/contract/workflow";
+import { type AttemptOutcome, nameProblem } from "@agentswf/contract/workflow";
 import { exists, isCode, linkNew, writeJson } from "./files";
 import { appendLine, endTornLine, readLines } from "./jsonl";
 import { MESSAGE_LIMITS } from "./messaging/limits";
@@ -49,22 +49,20 @@ export type Attempt = { run: Run; file: string; record: AttemptRecord };
 /** The start time of process `pid` as an ISO time to the second, or undefined when it is gone. */
 export type ProcessProbe = (pid: number) => string | undefined;
 
-const ID = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,127}$/;
+// Case is kept, as a ticket's key has it; `createRun` refuses an id differing only in case.
+const ID = /^[A-Za-z0-9][A-Za-z0-9._@-]{0,127}$/;
 
 /** Why `id` can't name a run or a workflow, or undefined when it can. */
 export function idProblem(id: string): string | undefined {
-  return ID.test(id)
+  return typeof id === "string" && ID.test(id)
     ? undefined
-    : `${JSON.stringify(id)} is not a valid id: letters, digits, '.', '_' and '-', up to 128, not starting with '.'`;
+    : `${JSON.stringify(id)} is not a valid id: letters, digits, '.', '_', '@' and '-', starting with a letter or digit, up to 128`;
 }
 
-const STAGE_NAME = /^[a-z][a-z0-9-]*$/;
-
 /** Why `name` can't name a stage, which is a file in the run's `stages/`; undefined when it can. */
 export function stageNameProblem(name: string): string | undefined {
-  return typeof name === "string" && STAGE_NAME.test(name)
-    ? undefined
-    : `${JSON.stringify(name)} is not a stage's name: lowercase letters, digits and '-', starting with a letter`;
+  const problem = typeof name === "string" ? nameProblem(name) : "a string";
+  return problem && `${JSON.stringify(name)} is not a stage's name: ${problem}`;
 }
 
 function checkIds(...ids: string[]): void {
@@ -138,7 +136,7 @@ async function claimRun(
 }
 
 function takenMessage(id: string): string {
-  return `${id} exists; --continue it, or --id another to start over`;
+  return `${id} exists; --continue goes on with it, or --id another id starts over`;
 }
 
 /** Another run whose id differs from `id` only in case; the same id is the rename's to refuse. */
@@ -218,7 +216,7 @@ export function checkContinue(
  */
 export async function readAttempts(run: Run): Promise<AttemptRecord[]> {
   const dir = attemptsDir(run.dir);
-  const numbered = (await entries(dir)).filter((name) => /^[1-9]\d*\.json$/.test(name));
+  const numbered = await attemptNames(run);
   const records = await Promise.all(
     numbered.map((name) =>
       readRecord<AttemptRecord>(join(dir, name), ATTEMPT_RECORD_VERSION, { missing: true }),
@@ -345,12 +343,12 @@ export async function claimAttempt(
 /** Writes the attempt's ending into its file, whole. */
 export async function endAttempt(
   attempt: Attempt,
-  ending: Pick<AttemptRecord, "stage" | "reason" | "stages" | "accounting"> & {
+  ending: Pick<AttemptRecord, "stage" | "reason" | "stages" | "accounting" | "unacknowledged"> & {
     outcome: AttemptOutcome;
   },
   now: Date = new Date(),
 ): Promise<AttemptRecord> {
-  const { stage, reason, stages, accounting } = ending;
+  const { stage, reason, stages, accounting, unacknowledged } = ending;
   const record: AttemptRecord = {
     ...attempt.record,
     ended: now.toISOString(),
@@ -359,6 +357,7 @@ export async function endAttempt(
     ...(reason === undefined ? {} : { reason }),
     ...(stages === undefined ? {} : { stages }),
     ...(accounting === undefined ? {} : { accounting }),
+    ...(unacknowledged === undefined ? {} : { unacknowledged }),
   };
   await writeJson(attempt.file, record);
   attempt.record = record;
@@ -403,13 +402,21 @@ export async function replaceStale(
   return stale;
 }
 
-/** Moves a stage's record, unchanged, to `replaced/{stage}.{attempt}.json`. */
+/**
+ * Moves a stage's record, unchanged, to `replaced/{stage}.{attempt}.json`, or, for a stage by
+ * content replaced again in the same attempt, `{stage}.{attempt}+{n}.json` from 2: no name has a
+ * `+`, so neither reads as another stage's.
+ */
 export async function replaceRecord(runDir: string, stage: string): Promise<void> {
   const file = join(stagesDir(runDir), `${stage}.json`);
   const record = await readRecord<StageRecord>(file, STAGE_RECORD_VERSION);
   const replaced = join(runDir, "replaced");
   await mkdir(replaced, { recursive: true, mode: 0o700 });
-  await rename(file, join(replaced, `${stage}.${record.attempt}.json`));
+  let target = join(replaced, `${stage}.${record.attempt}.json`);
+  for (let n = 2; await exists(target); n++) {
+    target = join(replaced, `${stage}.${record.attempt}+${n}.json`);
+  }
+  await rename(file, target);
 }
 
 /** Appends a line to the run's event log, `turns.jsonl`, which only the live attempt writes. */
@@ -434,22 +441,86 @@ export async function readEvents(runDir: string): Promise<RunLogLine[]> {
 export async function readNumberedEvents(
   runDir: string,
 ): Promise<{ number: number; line: RunLogLine }[]> {
-  const text = await readFile(turnsFile(runDir), "utf8").catch((error) => {
-    if (isCode(error, "ENOENT")) return "";
-    throw error;
-  });
-  const lines = text.split("\n");
+  return (await readEventsFrom(runDir, { offset: 0, count: 0 })).lines;
+}
+
+/** Where a read of the event log stopped: the bytes up to its last ended line, and the lines in them. */
+export type LogMark = { offset: number; count: number };
+
+/**
+ * The event log's lines past `from`, numbered on from it, and where this read stopped: what was
+ * appended since a read that stopped at `from`.
+ */
+export async function readEventsFrom(
+  runDir: string,
+  from: LogMark,
+): Promise<{ lines: { number: number; line: RunLogLine }[]; mark: LogMark }> {
+  let bytes: Buffer;
+  try {
+    const file = await open(turnsFile(runDir), "r");
+    try {
+      const { size } = await file.stat();
+      bytes = Buffer.alloc(Math.max(0, size - from.offset));
+      let read = 0;
+      while (read < bytes.length) {
+        const { bytesRead } = await file.read(bytes, read, bytes.length - read, from.offset + read);
+        if (bytesRead === 0) break;
+        read += bytesRead;
+      }
+      bytes = bytes.subarray(0, read);
+    } finally {
+      await file.close();
+    }
+  } catch (error) {
+    if (!isCode(error, "ENOENT")) throw error;
+    bytes = Buffer.alloc(0);
+  }
   // A last line not yet ended is still being written.
-  lines.pop();
-  return lines.flatMap((json, index) => {
+  const end = bytes.lastIndexOf(0x0a) + 1;
+  const texts =
+    end === 0
+      ? []
+      : bytes
+          .subarray(0, end - 1)
+          .toString("utf8")
+          .split("\n");
+  const lines = texts.flatMap((json, index) => {
     try {
       const value: unknown = JSON.parse(json);
       const line = typeof value === "object" && value !== null ? runLogLine(value) : undefined;
-      return line ? [{ number: index + 1, line }] : [];
+      return line ? [{ number: from.count + index + 1, line }] : [];
     } catch {
       return [];
     }
   });
+  return { lines, mark: { offset: from.offset + end, count: from.count + texts.length } };
+}
+
+/** The event log's size in bytes, 0 before it is written. */
+export async function logSize(runDir: string): Promise<number> {
+  return (await stat(turnsFile(runDir)).catch(() => undefined))?.size ?? 0;
+}
+
+async function attemptNames(run: Run): Promise<string[]> {
+  return (await entries(attemptsDir(run.dir))).filter((name) => /^[1-9]\d*\.json$/.test(name));
+}
+
+/**
+ * A token that changes when the run's attempt records do: one added, removed, or rewritten, as an
+ * attempt's end is.
+ */
+export async function attemptsToken(run: Run): Promise<string> {
+  const dir = attemptsDir(run.dir);
+  const names = await attemptNames(run);
+  const stats = await Promise.all(
+    names.map((name) => stat(join(dir, name)).catch(() => undefined)),
+  );
+  return names
+    .map((name, index) => {
+      const info = stats[index];
+      return info ? `${name}:${info.ino}:${info.size}:${info.mtimeMs}` : `${name}:-`;
+    })
+    .join(",");
 }
 
 /** Every turn of the run, in the order they settled. */
@@ -643,3 +714,51 @@ const runPs: Ps = (pid) => {
     exitCode: done.exitCode,
   };
 };
+
+/** How long a continue waits for the attempt before it to exit before it stops that process. */
+const PREVIOUS_GONE_MS = 5 * 60_000;
+
+/**
+ * Waits until the attempt before `n`, a parked one closing its agents or one that crashed with
+ * its process left, is gone; past five minutes, cancels it, then kills it if it ignores that.
+ * Its agents' sessions are then this attempt's.
+ */
+export async function previousGone(
+  run: Run,
+  n: number,
+  notice: (text: string) => void,
+): Promise<void> {
+  const previous = (await readAttempts(run)).find((each) => each.attempt === n - 1);
+  if (!previous) return;
+  const alive = () => sameProcess(previous.pid, previous.processStart, processStart);
+  const started = Date.now();
+  const giveUp = started + PREVIOUS_GONE_MS;
+  let said = false;
+  while (alive()) {
+    if (!said && Date.now() > started + 10_000) {
+      said = true;
+      notice(
+        `awf: waiting for attempt ${previous.attempt} (pid ${previous.pid}) to finish closing`,
+      );
+    }
+    if (Date.now() > giveUp) {
+      notice(
+        `awf: attempt ${previous.attempt} (pid ${previous.pid}) is still running; stopping it`,
+      );
+      // A cancel first, which closes its agents and sandboxes; only a process that ignores it is killed.
+      const signal = (name: NodeJS.Signals) => {
+        try {
+          process.kill(previous.pid, name);
+        } catch {
+          // Gone between the look and the signal.
+        }
+      };
+      signal("SIGTERM");
+      const killAt = Date.now() + 30_000;
+      while (alive() && Date.now() < killAt) await Bun.sleep(200);
+      if (alive()) signal("SIGKILL");
+      return;
+    }
+    await Bun.sleep(100);
+  }
+}

package/src/sandboxes.ts

@@ -7,6 +7,7 @@ import type { SandboxRecord } from "@agentswf/contract/records";
 import type {
   AbsoluteDeadline,
   AgentExecution,
+  SandboxEnvironment,
   SandboxEnvironmentKey,
   SandboxRef,
 } from "@agentswf/contract/workflow";
@@ -23,6 +24,7 @@ import {
   withinReach,
 } from "@agentswf/sandbox";
 import { CONTROL_PLANE_ROOT } from "./control-plane";
+import { harnessDeadline } from "./deadlines";
 import { messageOf } from "./errors";
 import { machinePaths } from "./machine";
 import { type CredentialLocks, placeCarried, type SeededHome, seedHome } from "./sandbox-homes";
@@ -38,6 +40,8 @@ export type RunSandboxOptions = {
   sandboxesDir: string;
   /** The operator's `~/.awf`, which no sandbox reaches. */
   machineRoot: string;
+  /** Where holders reach live runs' coordinators, `AWF_COORDINATOR_DIR` if it moved; no sandbox reaches it. */
+  coordinatorRoot?: string;
   /**
    * The operator's environment, which says where each harness keeps its state, the `PATH` an
    * agent's harness is found on and claude's token. Defaults to the engine's.
@@ -123,7 +127,7 @@ export class RunSandboxes {
       sandboxes?: RunSandboxOptions;
       runRoot: string;
       cwd: string;
-      deadline: AbsoluteDeadline;
+      deadline?: AbsoluteDeadline;
       /** The run's credential write-backs, which a host agent's own home shares. */
       locks: CredentialLocks;
       log(message: string): void;
@@ -138,7 +142,7 @@ export class RunSandboxes {
     return this.options.sandboxes?.run !== undefined;
   }
 
-  /** `workflow.sandboxes.open`. */
+  /** `wf.sandboxes.open`. */
   async open(spec: unknown): Promise<SandboxRef> {
     if (this.hasRunSandbox) throw new Error(RUN_SANDBOX_ONLY);
     const key = (spec as { key?: unknown } | null)?.key;
@@ -303,7 +307,7 @@ export class RunSandboxes {
           network: [...resolved.network],
           ...(resolved.sockets.length > 0 ? { sockets: [...resolved.sockets] } : {}),
           ...(resolved.webSearch ? { webSearch: true } : {}),
-          [provider]: resolved.environment,
+          ...({ [provider]: resolved.environment } as SandboxEnvironment),
         },
         directory,
         gitdirs: resolved.gitdirs.map((gitdir) => ({ ...gitdir })),
@@ -396,7 +400,7 @@ export class RunSandboxes {
     const opened = await installed.open(resolved, {
       runRoot: options.runRoot,
       directory,
-      deadline: this.options.deadline,
+      deadline: harnessDeadline(this.options.deadline),
     });
     return { key, provider, resolved, directory, opened, admitting: Promise.resolve(), agents: [] };
   }
@@ -411,6 +415,9 @@ export class RunSandboxes {
       providers: this.#providers,
       harnessState: Object.values(harnessState(this.#environment)),
       controlRoot: CONTROL_PLANE_ROOT,
+      ...(this.options.sandboxes?.coordinatorRoot === undefined
+        ? {}
+        : { coordinatorRoot: this.options.sandboxes.coordinatorRoot }),
       inline,
     };
   }

package/src/simple-input.ts

@@ -0,0 +1,268 @@
+import {
+  ANNOTATION_KEYS,
+  formatErrors,
+  type JsonSchema,
+  validate,
+} from "@agentswf/contract/schema";
+import type { GivenInput } from "@agentswf/contract/wire";
+import type { JsonObject } from "@agentswf/contract/workflow";
+import { messageOf } from "./errors";
+
+/**
+ * An input simple enough to give as flags, `--name 'value'`: an object of a few strings, numbers,
+ * booleans and enums, constrained only by what the usage line can say. Any other is given as JSON.
+ */
+type Simple = { name: string; required: boolean; kind: Kind }[];
+type Kind =
+  | { type: "string"; minLength?: number }
+  | { type: "number" | "integer"; minimum?: number; maximum?: number }
+  | { type: "boolean" }
+  | { type: "enum"; values: string[] };
+
+/**
+ * Said once in a prompt, under the first block with a free-text flag, and with every refusal of
+ * flags that take text. Enum, number and boolean values are shell words as they stand.
+ */
+export const QUOTING_RULE =
+  "Put every value in single quotes; a ' inside a value is written '\\''.";
+
+/** Whether a flag takes free text, the only value the shell can break. */
+export function takesText(simple: Simple): boolean {
+  return simple.some(({ kind }) => kind.type === "string");
+}
+
+const MAX_PROPERTIES = 6;
+const NAME = /^[a-z][a-z0-9_]*$/;
+/** An enum value the usage line can show between `|`s and the agent can type as it stands. */
+const WORD = /^[A-Za-z0-9_.:-]+$/;
+const HEREDOC = "send it as JSON on standard input, in a quoted heredoc (<<'WF_JSON' … WF_JSON)";
+const ANNOTATIONS = new Set<string>(ANNOTATION_KEYS);
+
+export function simpleInput(schema: JsonSchema): Simple | undefined {
+  if (!("type" in schema) || schema.type !== "object") return undefined;
+  const entries = Object.entries(schema.properties);
+  // No properties is an open object or nothing at all; neither reads as flags.
+  if (entries.length === 0 || entries.length > MAX_PROPERTIES) return undefined;
+  const required = new Set(schema.required ?? []);
+  if ([...required].some((name) => !Object.hasOwn(schema.properties, name))) return undefined;
+  const simple: Simple = [];
+  for (const [name, property] of entries) {
+    const kind = NAME.test(name) ? kindOf(property) : undefined;
+    if (!kind) return undefined;
+    simple.push({ name, required: required.has(name), kind });
+  }
+  return simple;
+}
+
+function kindOf(schema: JsonSchema): Kind | undefined {
+  const kind = anyKindOf(schema);
+  return kind?.type === "enum" && !kind.values.every((value) => WORD.test(value))
+    ? undefined
+    : kind;
+}
+
+function anyKindOf(schema: JsonSchema): Kind | undefined {
+  const keys = Object.keys(schema).filter((key) => !ANNOTATIONS.has(key));
+  const only = (...allowed: string[]) => keys.every((key) => allowed.includes(key));
+  if ("anyOf" in schema) {
+    if (!only("anyOf")) return undefined;
+    const values = schema.anyOf.map((each) =>
+      "type" in each && each.type === "string" ? stringConst(each) : undefined,
+    );
+    return values.every((value) => value !== undefined)
+      ? { type: "enum", values: values as string[] }
+      : undefined;
+  }
+  if (!("type" in schema)) {
+    return only("enum") && schema.enum.every((value) => typeof value === "string")
+      ? { type: "enum", values: schema.enum as string[] }
+      : undefined;
+  }
+  switch (schema.type) {
+    case "string": {
+      const constant = stringConst(schema);
+      if (constant !== undefined) return { type: "enum", values: [constant] };
+      if (schema.enum)
+        return only("type", "enum") ? { type: "enum", values: schema.enum } : undefined;
+      if (!only("type", "minLength")) return undefined;
+      return { type: "string", ...(schema.minLength ? { minLength: schema.minLength } : {}) };
+    }
+    case "number":
+    case "integer":
+      if (!only("type", "minimum", "maximum")) return undefined;
+      return {
+        type: schema.type,
+        ...(schema.minimum === undefined ? {} : { minimum: schema.minimum }),
+        ...(schema.maximum === undefined ? {} : { maximum: schema.maximum }),
+      };
+    case "boolean":
+      return only("type") ? { type: "boolean" } : undefined;
+    default:
+      return undefined;
+  }
+}
+
+/** A string schema that is one constant and nothing else, as TypeBox writes a literal. */
+function stringConst(schema: JsonSchema): string | undefined {
+  if (!("type" in schema) || schema.type !== "string" || schema.const === undefined) return;
+  const keys = Object.keys(schema).filter((key) => !ANNOTATIONS.has(key));
+  return keys.every((key) => key === "type" || key === "const") ? schema.const : undefined;
+}
+
+/** The flags as the prompt teaches them: `--verdict noise|real --confidence <integer, 1 to 5>`. */
+export function usageLine(simple: Simple): string {
+  return simple
+    .map(({ name, required, kind }) => {
+      const flag = `--${name} ${placeholder(kind)}`;
+      return required ? flag : `[${flag}]`;
+    })
+    .join(" ");
+}
+
+function placeholder(kind: Kind): string {
+  switch (kind.type) {
+    case "enum":
+      return kind.values.join("|");
+    case "boolean":
+      return "true|false";
+    case "string":
+      return kind.minLength
+        ? `<text, at least ${kind.minLength} character${kind.minLength === 1 ? "" : "s"}>`
+        : "<text>";
+    case "number":
+    case "integer": {
+      const { minimum, maximum } = kind;
+      if (minimum !== undefined && maximum !== undefined)
+        return `<${kind.type}, ${minimum} to ${maximum}>`;
+      if (minimum !== undefined) return `<${kind.type}, at least ${minimum}>`;
+      if (maximum !== undefined) return `<${kind.type}, at most ${maximum}>`;
+      return `<${kind.type}>`;
+    }
+  }
+}
+
+export type ReadFlags = { ok: true; value: JsonObject } | { ok: false; error: string };
+export type ReadGiven = { ok: true; value: unknown } | { ok: false; error: string };
+
+/**
+ * An input as `wfa` sent it, as a value: JSON parsed, flags read by the schema, nothing as `{}`.
+ * The schema's own check comes after, in `checkGiven`.
+ */
+export function readGiven(schema: JsonSchema | undefined, given: GivenInput): ReadGiven {
+  if (given.raw !== undefined) {
+    try {
+      return { ok: true, value: JSON.parse(given.raw) };
+    } catch (error) {
+      const shape = schema ? JSON.stringify(schema) : "any JSON value";
+      return {
+        ok: false,
+        error: `the value is not valid JSON: ${messageOf(error)}\nexpected: ${shape}`,
+      };
+    }
+  }
+  if (given.args === undefined) {
+    // Nothing given is `{}` only where an object is wanted, so a text answer isn't told it's one.
+    return schema && "type" in schema && schema.type === "object"
+      ? { ok: true, value: {} }
+      : { ok: false, error: `nothing was given; ${HEREDOC}` };
+  }
+  if (!schema) return { ok: false, error: `this isn't taken as flags; ${HEREDOC}` };
+  return readFlags(schema, given.args);
+}
+
+/**
+ * The schema's errors on a value `readGiven` returned, with the usage line when it came as flags or
+ * as nothing and could have come as flags: a missing required flag names its property.
+ */
+export function checkGiven(
+  schema: JsonSchema,
+  given: GivenInput,
+  value: unknown,
+): string | undefined {
+  const errors = validate(schema, value);
+  if (errors.length === 0) return undefined;
+  if (given.raw !== undefined) return formatErrors(errors);
+  const simple = simpleInput(schema);
+  if (simple) return `${formatErrors(errors)}\n${expected(simple)}`;
+  // Nothing given to a schema that takes JSON only: a lost heredoc, as likely as not.
+  return `${formatErrors(errors)}\n${HEREDOC}, matching this schema:\n${JSON.stringify(schema)}`;
+}
+
+function expected(simple: Simple): string {
+  return [`expected: ${usageLine(simple)}`, ...(takesText(simple) ? [QUOTING_RULE] : [])].join(
+    "\n",
+  );
+}
+
+/**
+ * Reads `--name 'value'` and `--name=value` by the schema, a number or boolean converted by its
+ * type. The word after a flag is always its value, so a value may start with `--`. A value the
+ * usage line rules out is refused with it; a missing required flag is left to the schema's check,
+ * which names the property.
+ */
+export function readFlags(schema: JsonSchema, args: readonly string[]): ReadFlags {
+  const simple = simpleInput(schema);
+  if (!simple) {
+    return {
+      ok: false,
+      error: `this isn't taken as flags; ${HEREDOC}, matching this schema:\n${JSON.stringify(schema)}`,
+    };
+  }
+  const refuse = (problem: string): ReadFlags => ({
+    ok: false,
+    error: `${problem}\n${expected(simple)}`,
+  });
+  const value: JsonObject = {};
+  for (let i = 0; i < args.length; i++) {
+    const word = args[i]!;
+    if (!word.startsWith("--")) {
+      const brackets = word.startsWith("[") || word.endsWith("]");
+      return refuse(
+        brackets
+          ? `${JSON.stringify(word)} is not a flag: leave out the brackets around an optional flag`
+          : `${JSON.stringify(word)} is not a flag: each value goes right after its flag, in single quotes`,
+      );
+    }
+    const equals = word.indexOf("=");
+    const name = equals === -1 ? word.slice(2) : word.slice(2, equals);
+    const property = simple.find((each) => each.name === name);
+    if (!property) return refuse(`--${name} is not a flag this takes`);
+    if (Object.hasOwn(value, name)) return refuse(`--${name} is given twice`);
+    let text: string;
+    if (equals !== -1) text = word.slice(equals + 1);
+    else {
+      const next = args[i + 1];
+      if (next === undefined) return refuse(`--${name} needs a value`);
+      text = next;
+      i++;
+    }
+    const converted = convert(property.kind, text);
+    if (converted === undefined)
+      return refuse(`--${name} takes ${placeholder(property.kind)}; got ${JSON.stringify(text)}`);
+    value[name] = converted;
+  }
+  return { ok: true, value };
+}
+
+/** The value, or undefined when the usage line says it can't be, bounds included. */
+function convert(kind: Kind, text: string): string | number | boolean | undefined {
+  switch (kind.type) {
+    case "string":
+      return text.length >= (kind.minLength ?? 0) ? text : undefined;
+    case "enum":
+      return kind.values.includes(text) ? text : undefined;
+    case "boolean":
+      return text === "true" ? true : text === "false" ? false : undefined;
+    case "number":
+    case "integer": {
+      const trimmed = text.trim();
+      if (!/^-?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(trimmed)) return undefined;
+      const number = Number(trimmed);
+      if (!Number.isFinite(number) || (kind.type === "integer" && !Number.isInteger(number)))
+        return undefined;
+      if (kind.minimum !== undefined && number < kind.minimum) return undefined;
+      if (kind.maximum !== undefined && number > kind.maximum) return undefined;
+      return number;
+    }
+  }
+}

package/src/socket-exchange.ts

@@ -0,0 +1,26 @@
+import { createConnection } from "node:net";
+
+/**
+ * One request line to a Unix socket, and what comes back until the other side closes: empty when
+ * it closed without a word. Bounded, so a run that stopped answering does not hang a holder.
+ */
+export function exchange(endpoint: string, frame: string, timeoutMs = 30_000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(endpoint);
+    const chunks: Buffer[] = [];
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(new Error(`no answer within ${timeoutMs / 1000}s`));
+    }, timeoutMs);
+    socket.once("connect", () => socket.end(frame));
+    socket.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+    socket.once("end", () => {
+      clearTimeout(timer);
+      resolve(Buffer.concat(chunks).toString("utf8").trim());
+    });
+    socket.once("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}

package/src/sources.ts

@@ -0,0 +1,70 @@
+import type { WaitTake } from "@agentswf/contract/records";
+import type { JsonValue, WorkflowEvent } from "@agentswf/contract/workflow";
+
+/** What each source the run issued takes: only awf makes a source, so only these are. */
+const takes = new WeakMap<object, WaitTake>();
+
+/** Marks `value` as a source that takes `take`, and returns it. */
+export function asSource<T extends object>(value: T, take: WaitTake): T {
+  takes.set(value, take);
+  return value;
+}
+
+/** A source of `fields` that takes `take`, its `is(e)` the test its waits use. */
+export function source<T extends object>(
+  fields: T,
+  take: WaitTake,
+): T & { is(event: Looked): boolean } {
+  return asSource(Object.freeze({ ...fields, is: (event: Looked) => matches(event, take) }), take);
+}
+
+type Looked = { name: string; from: string; data?: unknown };
+
+/** The first of `branches` that takes `event`. */
+export function branchOf(
+  branches: readonly (readonly [string, WaitTake])[],
+  event: Looked,
+): string | undefined {
+  return branches.find(([, take]) => matches(event, take))?.[0];
+}
+
+/** What a source takes; undefined for anything the run didn't issue as one. */
+export function takeOf(value: unknown): WaitTake | undefined {
+  return typeof value === "object" && value !== null ? takes.get(value) : undefined;
+}
+
+/** Whether a wait that takes `take` takes `event`. */
+export function matches(
+  event: { name: string; from: string; data?: unknown },
+  take: WaitTake,
+): boolean {
+  if (event.name !== take.name) return false;
+  if (take.from !== undefined && event.from !== take.from) return false;
+  if (take.turn === undefined) return true;
+  const data = event.data as { turn?: unknown } | null | undefined;
+  return typeof data === "object" && data !== null && data.turn === take.turn;
+}
+
+/** Whether a wait taking `wanted`, or everything when it names nothing, takes `event`. */
+export function wouldTake(
+  event: { name: string; from: string; data?: unknown },
+  wanted: readonly WaitTake[] | undefined,
+): boolean {
+  return wanted === undefined || wanted.some((take) => matches(event, take));
+}
+
+/**
+ * What a branch hands back of the event it took: awf's own events as their data with the event's id
+ * and arrival, and a workflow's own event whole.
+ */
+export function branchValue(event: WorkflowEvent<string, JsonValue>): unknown {
+  switch (event.name) {
+    case "timer:due":
+    case "at:due":
+    case "participant:reply":
+    case "agent:ended":
+      return Object.freeze({ ...(event.data as object), id: event.id, at: event.at });
+    default:
+      return event;
+  }
+}