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

package/src/stage-schema.ts

@@ -0,0 +1,88 @@
+import type { JsonSchema } from "@agentswf/contract/schema";
+import type { JsonValue } from "@agentswf/contract/workflow";
+
+/**
+ * A schema as a person reads a type: `{iid: integer, url: string}`. A top-level `anyOf` is a line
+ * per branch, the rest one line.
+ */
+export function schemaLines(schema: JsonSchema): string[] {
+  return "anyOf" in schema ? schema.anyOf.map(typeText) : [typeText(schema)];
+}
+
+function typeText(schema: JsonSchema): string {
+  if ("anyOf" in schema) return schema.anyOf.map(typeText).join(" | ");
+  if (!("type" in schema)) return schema.enum.map((value) => JSON.stringify(value)).join(" | ");
+  switch (schema.type) {
+    case "string":
+      if (schema.const !== undefined) return JSON.stringify(schema.const);
+      return schema.enum ? schema.enum.map((value) => JSON.stringify(value)).join(" | ") : "string";
+    case "number":
+    case "integer":
+      if (schema.const !== undefined) return String(schema.const);
+      return [
+        schema.type,
+        ...(schema.minimum === undefined ? [] : [`≥ ${schema.minimum}`]),
+        ...(schema.maximum === undefined ? [] : [`≤ ${schema.maximum}`]),
+      ].join(" ");
+    case "boolean":
+      return schema.const === undefined ? "boolean" : String(schema.const);
+    case "null":
+      return "null";
+    case "array": {
+      const items = typeText(schema.items);
+      const list = `${/^[\w"]+$/.test(items) || items.startsWith("{") ? items : `(${items})`}[]`;
+      return schema.minItems ? `${list} (${schema.minItems}+)` : list;
+    }
+    case "object": {
+      const required = new Set(schema.required ?? []);
+      const fields = Object.entries(schema.properties).map(
+        ([key, property]) => `${key}${required.has(key) ? "" : "?"}: ${typeText(property)}`,
+      );
+      return `{${fields.join(", ")}}`;
+    }
+  }
+}
+
+/**
+ * A value its schema accepts, standing in for one not given while an attempt looks on for the
+ * others it needs: the first branch, the least of each bound, required fields only.
+ */
+export function placeholderOf(schema: JsonSchema): JsonValue {
+  if ("anyOf" in schema) return placeholderOf(schema.anyOf[0]!);
+  if (!("type" in schema)) return schema.enum[0]!;
+  switch (schema.type) {
+    case "string": {
+      const least = schema.minLength ?? 0;
+      return (
+        schema.const ??
+        schema.enum?.find((value) => value.length >= least) ??
+        schema.enum?.[0] ??
+        "x".repeat(least)
+      );
+    }
+    case "number":
+      return schema.const ?? schema.minimum ?? schema.maximum ?? 0;
+    case "integer":
+      return (
+        schema.const ??
+        (schema.minimum !== undefined
+          ? Math.ceil(schema.minimum)
+          : schema.maximum !== undefined
+            ? Math.floor(schema.maximum)
+            : 0)
+      );
+    case "boolean":
+      return schema.const ?? false;
+    case "null":
+      return null;
+    case "array":
+      return Array.from({ length: schema.minItems ?? 0 }, () => placeholderOf(schema.items));
+    case "object":
+      return Object.fromEntries(
+        (schema.required ?? []).flatMap((key) => {
+          const property = schema.properties[key];
+          return [[key, property ? placeholderOf(property) : null]];
+        }),
+      );
+  }
+}

package/src/stopped.ts

@@ -0,0 +1,36 @@
+import type { StageNeed, StageRecord } from "@agentswf/contract/records";
+
+/**
+ * Ends an attempt `stopped`, apart from `failed`: the workflow's `stop`, or a continue that can't
+ * go on as asked. A continue picks it up from there.
+ */
+export class WorkflowStopped extends Error {
+  constructor(
+    readonly reason: string,
+    /** The stage it stopped in; absent between stages. */
+    readonly stage?: string,
+    /** Whether going on takes `--from-stage {stage}`: a record a continue can't reuse. */
+    readonly redo = false,
+    /** The stages whose values, given with `--values`, let the attempt start at a later one. */
+    readonly needs?: readonly StageNeed[],
+  ) {
+    super(reason);
+    this.name = "WorkflowStopped";
+  }
+}
+
+/** A `--from-stage` the attempt never reached: a typo, or a branch not taken. */
+export class FromStageUnreached extends WorkflowStopped {
+  constructor(
+    readonly fromStage: string,
+    /** The run's stage records, in the order they started: the stages to choose from. */
+    readonly recorded: readonly StageRecord[],
+  ) {
+    super(`never reached ${fromStage}`);
+  }
+}
+
+/** The failure that ended an attempt: an aggregate's first, ahead of what cleanup added to it. */
+export function primaryFailure(failure: unknown): unknown {
+  return failure instanceof AggregateError ? failure.errors[0] : failure;
+}

package/src/test-command.ts

@@ -0,0 +1,110 @@
+import { existsSync } from "node:fs";
+import { constants } from "node:os";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseDuration } from "./duration";
+
+const PRELOAD = fileURLToPath(new URL("./workflow-test-preload.ts", import.meta.url));
+
+export const testUsage = [
+  "usage: awf test [paths...] [-t <pattern>] [--watch] [--timeout <duration>]",
+  "",
+  "Runs a workflow's tests (*.test.ts and *.spec.ts files) under the current directory, or under",
+  "each file or directory given, with agentswf/workflow, agentswf/testing and typebox served as",
+  "awf run serves them: nothing is installed. -t runs the tests whose names match the pattern;",
+  "--watch reruns them on a change; --timeout bounds each test, 5s by default.",
+  "",
+  "Exits 0 when every test passed, 1 when one failed or none was found, 2 on a usage error. What",
+  "it prints is for reading, not parsing.",
+].join("\n");
+
+export type TestCommand = { paths: string[]; bunArgs: string[] };
+
+/**
+ * Only these flags pass through, so the published command is awf's, not the whole of `bun test`'s,
+ * and a later runner can take its place. A path must exist; Bun would take it as a filter.
+ */
+export function parseTestCommand(argv: readonly string[], cwd: string): TestCommand | "help" {
+  const paths: string[] = [];
+  const bunArgs: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const option = argv[index]!;
+    const value = argv[index + 1];
+    if (option === "-h" || option === "--help") return "help";
+    if (option === "--watch") {
+      bunArgs.push("--watch");
+    } else if (option === "-t") {
+      if (value === undefined) throw new Error("-t needs a pattern");
+      bunArgs.push("-t", value);
+      index += 1;
+    } else if (option === "--timeout") {
+      if (value === undefined) throw new Error("--timeout needs a duration such as 10s");
+      bunArgs.push("--timeout", String(parseDuration(value)));
+      index += 1;
+    } else if (option.startsWith("-")) {
+      throw new Error(`unknown option: ${option}`);
+    } else {
+      const path = resolve(cwd, option);
+      if (!existsSync(path)) throw new Error(`no such file or directory: ${option}`);
+      paths.push(path);
+    }
+  }
+  return { paths, bunArgs };
+}
+
+/**
+ * Runs `bun test` in `cwd` with the author surface preloaded, and resolves to its exit code. When
+ * `signal` aborts, as on Ctrl-C to awf alone, the tests are stopped with the same signal.
+ */
+export async function runWorkflowTests(
+  command: TestCommand,
+  cwd: string,
+  options: {
+    signal?: AbortSignal;
+    output?: { stdout(text: string): void; stderr(text: string): void };
+  } = {},
+): Promise<number> {
+  const { signal, output } = options;
+  const child = Bun.spawn(
+    [
+      process.execPath,
+      // As `awf run`: a `.env` can hold a token that changes how every agent logs in.
+      "--no-env-file",
+      "test",
+      "--preload",
+      PRELOAD,
+      ...command.bunArgs,
+      ...command.paths,
+    ],
+    {
+      cwd,
+      stdin: "inherit",
+      stdout: output ? "pipe" : "inherit",
+      stderr: output ? "pipe" : "inherit",
+    },
+  );
+  const stop = () =>
+    child.kill(
+      typeof signal?.reason === "string" && signal.reason in constants.signals
+        ? (signal.reason as NodeJS.Signals)
+        : "SIGTERM",
+    );
+  if (signal?.aborted) stop();
+  signal?.addEventListener("abort", stop, { once: true });
+  try {
+    if (output) {
+      const [out, err] = await Promise.all([
+        new Response(child.stdout as ReadableStream).text(),
+        new Response(child.stderr as ReadableStream).text(),
+      ]);
+      if (out) output.stdout(out.trimEnd());
+      if (err) output.stderr(err.trimEnd());
+    }
+    const code = await child.exited;
+    // Ended by a signal, it exits as a shell reports one: 128 and the signal's number.
+    const ended = child.signalCode as keyof typeof constants.signals | null;
+    return ended ? 128 + constants.signals[ended] : code;
+  } finally {
+    signal?.removeEventListener("abort", stop);
+  }
+}

package/src/testing/operation-events.ts

@@ -0,0 +1,89 @@
+import { open } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  OPERATION_LIVENESS_KINDS,
+  OPERATION_LIVENESS_RECORD_VERSION,
+  type OperationLivenessRecord,
+} from "@agentswf/contract/records";
+
+type OperationEvent = Pick<
+  OperationLivenessRecord,
+  "kind" | "at" | "sequence" | "reason" | "until" | "peer"
+>;
+const MAX_BYTES = 1024 * 1024;
+function eventFile(runDir: string, operationId: string): string {
+  return join(runDir, "calls", operationId, "liveness.jsonl");
+}
+
+export async function readOperationEvents(
+  runDir: string,
+  operationId: string,
+): Promise<{
+  records: OperationLivenessRecord[];
+  incomplete: boolean;
+}> {
+  let text: string;
+  let clipped = false;
+  try {
+    const file = await open(eventFile(runDir, operationId), "r");
+    try {
+      const buffer = Buffer.alloc(MAX_BYTES + 1);
+      let size = 0;
+      while (size < buffer.length) {
+        const read = await file.read(buffer, size, buffer.length - size, null);
+        if (!read.bytesRead) break;
+        size += read.bytesRead;
+      }
+      clipped = size > MAX_BYTES;
+      text = buffer.subarray(0, Math.min(size, MAX_BYTES)).toString("utf8");
+    } finally {
+      await file.close();
+    }
+  } catch {
+    return { records: [], incomplete: true };
+  }
+  let incomplete = clipped || !text.endsWith("\n");
+  const records: OperationLivenessRecord[] = [];
+  const rows = text.split("\n");
+  rows.pop(); // An unterminated row is not a committed diagnostic frame.
+  for (const row of rows) {
+    try {
+      const value: unknown = JSON.parse(row);
+      if (!isRecord(value, operationId)) {
+        incomplete = true;
+        continue;
+      }
+      records.push(value);
+      if (value.dropped || value.truncated) incomplete = true;
+    } catch {
+      incomplete = true;
+    }
+  }
+  if (records.at(-1)?.kind !== "terminal") incomplete = true;
+  return { records, incomplete };
+}
+
+function validEvent(value: OperationEvent): boolean {
+  return (
+    typeof value.kind === "string" &&
+    (OPERATION_LIVENESS_KINDS as readonly string[]).includes(value.kind) &&
+    Number.isSafeInteger(value.at) &&
+    value.at >= 0 &&
+    Number.isSafeInteger(value.sequence) &&
+    value.sequence >= 0 &&
+    (value.reason === undefined || typeof value.reason === "string") &&
+    (value.until === undefined || (Number.isSafeInteger(value.until) && value.until >= 0)) &&
+    (value.peer === undefined || (typeof value.peer === "string" && value.peer.trim() !== ""))
+  );
+}
+function isRecord(value: unknown, operationId: string): value is OperationLivenessRecord {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const item = value as OperationLivenessRecord;
+  return (
+    item.version === OPERATION_LIVENESS_RECORD_VERSION &&
+    item.operationId === operationId &&
+    validEvent(item) &&
+    (item.dropped === undefined || (Number.isSafeInteger(item.dropped) && item.dropped >= 0)) &&
+    (item.truncated === undefined || item.truncated === true)
+  );
+}

package/src/testing.ts

@@ -0,0 +1,164 @@
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { createConnection } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type ResultSubmitResponse, WIRE_VERSION } from "@agentswf/contract/wire";
+import type { JsonValue, WorkflowContext, WorkflowDefinition } from "@agentswf/contract/workflow";
+import { createSingleSessionHostFactory } from "@agentswf/harness";
+import type { AgentSessionAdapter } from "@agentswf/harness/adapter";
+import { createFakeAdapter } from "@agentswf/harness/testing";
+import Type from "typebox";
+import { OPERATOR_ALIASES } from "./operator-aliases";
+import { createRun, openRun } from "./runs";
+import { type RunWorkflowOptions, runWorkflow, startWorkflow } from "./workflow-runner";
+
+export function createTempRunDirs(): {
+  tempRunDir(): string;
+  cleanup(): void;
+} {
+  const paths = new Set<string>();
+  return {
+    tempRunDir() {
+      const path = mkdtempSync(join(tmpdir(), "wf-"));
+      paths.add(path);
+      return path;
+    },
+    cleanup() {
+      for (const path of paths) rmSync(path, { recursive: true, force: true });
+      paths.clear();
+    },
+  };
+}
+
+export { COUNT_SCHEMA } from "@agentswf/contract/testing";
+
+export function future(milliseconds = 60_000): { unixMilliseconds: number } {
+  return { unixMilliseconds: Date.now() + milliseconds };
+}
+
+/** Answers a call the way an agent's `wf` does: one framed request over its own socket. */
+export async function submit(
+  binding: { endpoint: string; operationId: string },
+  value: unknown,
+  session?: string,
+): Promise<ResultSubmitResponse> {
+  const response = await exchange(
+    binding.endpoint,
+    `${JSON.stringify({
+      version: WIRE_VERSION,
+      command: "result",
+      operationId: binding.operationId,
+      raw: JSON.stringify(value),
+      ...(session ? { session } : {}),
+    })}\n`,
+  );
+  return JSON.parse(response) as ResultSubmitResponse;
+}
+
+export function exchange(endpoint: string, frame: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(endpoint);
+    const chunks: Buffer[] = [];
+    socket.once("connect", () => socket.end(frame));
+    socket.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+    socket.once("end", () => resolve(Buffer.concat(chunks).toString("utf8").trim()));
+    socket.once("error", reject);
+  });
+}
+
+export const DOC = Type.Object({ path: Type.String() }, { additionalProperties: false });
+
+/** A workflow of no arguments, named `staged` unless `meta` names it. */
+export function workflowOf<Result extends JsonValue>(
+  run: (workflow: WorkflowContext) => Promise<Result>,
+  meta: { name?: string; version?: string } = {},
+): WorkflowDefinition<null, Result> {
+  const { name = "staged", version } = meta;
+  return {
+    meta: { name, description: name, ...(version === undefined ? {} : { version }) },
+    run: (workflow) => run(workflow),
+  };
+}
+
+/** Answers every turn with a `DOC`, and every compaction with a summary. */
+export function answering(): AgentSessionAdapter {
+  return createFakeAdapter({
+    harnesses: ["codex"],
+    script: (context) =>
+      context.kind === "compact"
+        ? { summary: "kept" }
+        : {
+            act: async () => {
+              await submit(context.binding!, { path: "x" });
+            },
+          },
+  });
+}
+
+/**
+ * One attempt of run r1 of `workflow` under `runRoot`, created by the first, its agents answered by
+ * `answering()`. Its folder is `{runRoot}/{workflow}/r1`.
+ */
+export async function runAttempt<Result extends JsonValue>(
+  workflow: WorkflowDefinition<null, Result>,
+  options: {
+    runRoot: string;
+    attempt?: number;
+    fromStage?: string;
+    values?: Record<string, JsonValue>;
+    adapter?: AgentSessionAdapter;
+    signal?: AbortSignal;
+  },
+) {
+  const { runRoot, attempt = 1, fromStage, values, adapter = answering(), signal } = options;
+  const name = workflow.meta.name;
+  const run = existsSync(join(runRoot, name, "r1"))
+    ? await openRun(runRoot, name, "r1")
+    : await createRun(runRoot, {
+        id: "r1",
+        workflow: name,
+        argv: [],
+        cwd: process.cwd(),
+        sandbox: null,
+      });
+  return runWorkflow(workflow, null, {
+    runRoot,
+    run: {
+      dir: run.dir,
+      id: run.record.id,
+      attempt,
+      ...(fromStage === undefined ? {} : { fromStage }),
+      ...(values === undefined ? {} : { values: new Map(Object.entries(values)) }),
+    },
+    runtime: { aliases: OPERATOR_ALIASES, host: createSingleSessionHostFactory(adapter) },
+    deadline: future(),
+    ...(signal === undefined ? {} : { signal }),
+  });
+}
+
+/** `startWorkflow` as the first attempt of a new run of the workflow under `options.runRoot`. */
+export async function startNew<Args extends JsonValue, Result extends JsonValue>(
+  definition: WorkflowDefinition<Args, Result>,
+  args: Args,
+  options: Omit<RunWorkflowOptions, "run">,
+) {
+  const run = await createRun(options.runRoot, {
+    workflow: definition.meta.name,
+    argv: [],
+    cwd: options.cwd ?? process.cwd(),
+    sandbox: null,
+  });
+  return startWorkflow(definition, args, {
+    ...options,
+    run: { dir: run.dir, id: run.record.id, attempt: 1 },
+  });
+}
+
+/** `runWorkflow` as the first attempt of a new run of the workflow under `options.runRoot`. */
+export async function runNew<Args extends JsonValue, Result extends JsonValue>(
+  definition: WorkflowDefinition<Args, Result>,
+  args: Args,
+  options: Omit<RunWorkflowOptions, "run">,
+) {
+  return (await startNew(definition, args, options)).result;
+}

package/src/workflow-loader.ts

@@ -0,0 +1,113 @@
+import { stat } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import * as workflowSurface from "@agentswf/contract/workflow";
+import {
+  EXECUTABLE_WORKFLOW_KIND,
+  type ExecutableWorkflow,
+  isJsonValue,
+  type JsonValue,
+} from "@agentswf/contract/workflow";
+import { plugin } from "bun";
+import * as typebox from "typebox";
+import * as typeboxValue from "typebox/value";
+import { idProblem } from "./runs";
+
+/**
+ * What a workflow in any folder imports without installing it, served from the engine's own
+ * copies, so its schemas are the ones results are checked with. Part of the author surface:
+ * adding a name is cheap, removing one breaks workflows.
+ */
+const AUTHOR_SURFACE: Record<string, Record<string, unknown>> = {
+  "agentswf/workflow": workflowSurface,
+  typebox,
+  "typebox/value": typeboxValue,
+};
+
+let surfaceServed = false;
+
+/** Serves the author surface to whatever this process imports next. */
+export function serveAuthorSurface(): void {
+  if (surfaceServed) return;
+  surfaceServed = true;
+  plugin({
+    name: "agentswf author surface",
+    setup(build) {
+      for (const [name, exports] of Object.entries(AUTHOR_SURFACE)) {
+        build.module(name, () => ({ exports, loader: "object" }));
+      }
+    },
+  });
+}
+
+const WORKFLOW_EXTENSIONS = new Set([".ts", ".mts", ".js", ".mjs"]);
+
+export type LoadedWorkflow = {
+  file: string;
+  executable: ExecutableWorkflow<JsonValue, JsonValue>;
+};
+
+export async function loadWorkflowFile(file: string, cwd: string): Promise<LoadedWorkflow> {
+  if (file.includes("://") || file.startsWith("file:")) {
+    throw new Error("workflow must be an explicit local file path");
+  }
+  const absolute = resolve(cwd, file);
+  if (!WORKFLOW_EXTENSIONS.has(extname(absolute))) {
+    throw new Error("workflow file must end in .ts, .mts, .js, or .mjs");
+  }
+  let info: Awaited<ReturnType<typeof stat>>;
+  try {
+    info = await stat(absolute);
+  } catch {
+    throw new Error(`workflow file not found: ${absolute}`);
+  }
+  if (!info.isFile()) throw new Error(`workflow path is not a file: ${absolute}`);
+
+  serveAuthorSurface();
+  const namespace: unknown = await import(pathToFileURL(absolute).href);
+  const exported = record(namespace)?.default;
+  if (!isExecutableWorkflow(exported)) {
+    throw new Error(`default export must be an ${EXECUTABLE_WORKFLOW_KIND} executable workflow`);
+  }
+  const { name, version } = exported.definition.meta;
+  // The name is a folder its runs are kept in, and the version's major decides which records a
+  // continue may reuse.
+  const problem = idProblem(name);
+  if (problem) throw new Error(`meta.name: ${problem}`);
+  if (version !== undefined && (typeof version !== "string" || !SEMVER.test(version))) {
+    throw new Error(
+      `meta.version: ${JSON.stringify(version)} is not a semver version such as 1.2.0`,
+    );
+  }
+  return { file: absolute, executable: exported };
+}
+
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+export function assertJsonValue(value: unknown, label: string): asserts value is JsonValue {
+  if (!isJsonValue(value)) throw new Error(`${label} must contain only JSON values`);
+}
+
+function isExecutableWorkflow(value: unknown): value is ExecutableWorkflow<JsonValue, JsonValue> {
+  const executable = record(value);
+  const definition = record(executable?.definition);
+  const meta = record(definition?.meta);
+  return (
+    executable?.kind === EXECUTABLE_WORKFLOW_KIND &&
+    typeof executable.prepare === "function" &&
+    (executable.present === undefined || typeof executable.present === "function") &&
+    (executable.report === undefined || typeof executable.report === "function") &&
+    (executable.id === undefined || typeof executable.id === "function") &&
+    typeof definition?.run === "function" &&
+    typeof meta?.name === "string" &&
+    meta.name.trim() !== "" &&
+    typeof meta.description === "string" &&
+    meta.description.trim() !== ""
+  );
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : undefined;
+}