@agentswf/engine 0.1.0-beta.3 → 0.1.0-beta.5

package/src/stage-plan.ts

@@ -1,4 +1,9 @@
-import type { StageNeed, StageRecord } from "@agentswf/contract/records";
+import type {
+  AttemptRecord,
+  AttemptStage,
+  StageNeed,
+  StageRecord,
+} from "@agentswf/contract/records";
 import { type JsonSchema, type SchemaError, validate } from "@agentswf/contract/schema";
 import type { JsonValue } from "@agentswf/contract/workflow";
 
@@ -148,3 +153,34 @@ export function planStageByContent(
     ? { kind: "reuse", record, value: record.value }
     : { kind: "stop", reason: misfit };
 }
+
+/**
+ * A `--from-stage {stage}` that attempt `attempt` redid, in a run of a workflow with `events`. In
+ * that attempt and every later one, a stage first entered after `stage` whose record an earlier
+ * attempt than `attempt` wrote runs again, its record replaced: it was made against the stage
+ * before the redo. A record never entered after the stage keeps its reuse.
+ */
+export type StageRedo = { stage: string; attempt: number };
+
+/**
+ * The last `--from-stage` an earlier attempt of a run with `events` redid: the latest attempt with
+ * one that ran its stage. Its attempt record says so in `stages`, which a stop for a stage never
+ * reached, a refusal and a crash leave without it; a crash after the stage's new record was written
+ * leaves that record, the attempt's own. A redo whose stage failed and ran again on a wake is still
+ * the redo. Only attempt and stage records are read, which a continue may read.
+ */
+export function lastRedo(
+  attempts: readonly (Pick<AttemptRecord, "attempt" | "flags"> & {
+    stages?: readonly Pick<AttemptStage, "stage" | "source">[];
+  })[],
+  records: ReadonlyMap<string, StageRecord>,
+  before: number,
+): StageRedo | undefined {
+  for (const { attempt, flags, stages } of [...attempts].sort((a, b) => b.attempt - a.attempt)) {
+    const stage = flags.fromStage;
+    if (attempt >= before || stage === undefined) continue;
+    const ran = stages?.some((each) => each.stage === stage && each.source === "ran") ?? false;
+    if (ran || records.get(stage)?.attempt === attempt) return { stage, attempt };
+  }
+  return undefined;
+}

package/src/test-command.ts

@@ -4,21 +4,12 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseDuration } from "./duration";
 import { messageOf } from "./errors";
+import help from "./help/test.txt" with { type: "text" };
 import type { Out } from "./run-commands";
 
 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 const testUsage = help.trimEnd();
 
 export type TestCommand = { paths: string[]; bunArgs: string[] };
 
@@ -33,7 +24,7 @@ export async function testCommand(
 ): Promise<number> {
   let tests: TestCommand | "help";
   try {
-    tests = parseTestCommand(argv, cwd);
+    tests = parseTestCommand(argv, cwd, (line) => io.stderr(line));
   } catch (error) {
     io.stderr(`awf: ${messageOf(error)}\n\n${testUsage}`);
     return 2;
@@ -52,7 +43,11 @@ export async function testCommand(
  * 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" {
+export function parseTestCommand(
+  argv: readonly string[],
+  cwd: string,
+  deprecated: (line: string) => void = () => {},
+): TestCommand | "help" {
   const paths: string[] = [];
   const bunArgs: string[] = [];
   for (let index = 0; index < argv.length; index += 1) {
@@ -67,7 +62,7 @@ export function parseTestCommand(argv: readonly string[], cwd: string): TestComm
       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)));
+      bunArgs.push("--timeout", String(parseDuration(value, "--timeout", deprecated)));
       index += 1;
     } else if (option.startsWith("-")) {
       throw new Error(`unknown option: ${option}`);

package/src/testing.ts

@@ -6,11 +6,9 @@ import type { AttemptRecord } from "@agentswf/contract/records";
 import { type ResultSubmitResponse, WIRE_VERSION } from "@agentswf/contract/wire";
 import {
   defineWorkflow,
-  type EventWorkflowContext,
   type JsonValue,
   type OutputSchema,
   type WorkflowContext,
-  type WorkflowDefinition,
 } from "@agentswf/contract/workflow";
 import { createSingleSessionHostFactory } from "@agentswf/harness";
 import type { AgentSessionAdapter } from "@agentswf/harness/adapter";
@@ -19,6 +17,7 @@ import Type from "typebox";
 import { writeJson } from "./files";
 import { OPERATOR_ALIASES } from "./operator-aliases";
 import { createRun, openRun, type Run, readAttempts } from "./runs";
+import type { RunnableWorkflow } from "./workflow-runner";
 import { type RunWorkflowOptions, runWorkflow, startWorkflow } from "./workflow-runner";
 
 export function createTempRunDirs(): {
@@ -81,11 +80,11 @@ const Changes: OutputSchema<{ case: string }> = {
   properties: { case: { type: "string" } },
   required: ["case"],
 };
-const caseEvents = { "dd.changes": Changes };
+export const caseEvents = { "dd.changes": Changes };
 
 /** A workflow with one event, `dd.changes`, keyed by its case, whose body is `run`. */
 export const caseRun = (
-  run: (workflow: EventWorkflowContext<typeof caseEvents>) => Promise<JsonValue>,
+  run: (workflow: WorkflowContext<typeof caseEvents>) => Promise<JsonValue>,
 ) =>
   defineWorkflow({
     meta: { name: "dd-case", description: "A case." },
@@ -104,7 +103,7 @@ 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. */
+/** Answers a call the way an agent's `wfa` does: one framed request over its own socket. */
 export async function submit(
   binding: { endpoint: string; operationId: string },
   value: unknown,
@@ -140,7 +139,7 @@ export const DOC = Type.Object({ path: Type.String() }, { additionalProperties:
 export function workflowOf<Result extends JsonValue>(
   run: (workflow: WorkflowContext) => Promise<Result>,
   meta: { name?: string; version?: string } = {},
-): WorkflowDefinition<null, Result> {
+): RunnableWorkflow<null, Result> {
   const { name = "staged", version } = meta;
   return {
     meta: { name, description: name, ...(version === undefined ? {} : { version }) },
@@ -168,7 +167,7 @@ export function answering(): AgentSessionAdapter {
  * `answering()`. Its folder is `{runRoot}/{workflow}/r1`.
  */
 export async function runAttempt<Result extends JsonValue>(
-  workflow: WorkflowDefinition<null, Result>,
+  workflow: RunnableWorkflow<null, Result>,
   options: {
     runRoot: string;
     attempt?: number;
@@ -206,7 +205,7 @@ export async function runAttempt<Result extends JsonValue>(
 
 /** `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>,
+  definition: RunnableWorkflow<Args, Result>,
   args: Args,
   options: Omit<RunWorkflowOptions, "run">,
 ) {
@@ -224,7 +223,7 @@ export async function startNew<Args extends JsonValue, Result extends JsonValue>
 
 /** `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>,
+  definition: RunnableWorkflow<Args, Result>,
   args: Args,
   options: Omit<RunWorkflowOptions, "run">,
 ) {

package/src/tick-command.ts

@@ -1,6 +1,7 @@
 import type { TickResultJson } from "@agentswf/contract/records";
 import { messageOf } from "./errors";
 import { exists } from "./files";
+import help from "./help/tick.txt" with { type: "text" };
 import { listProjects, projectRunRoot } from "./projects";
 import type { Out } from "./run-commands";
 import { parsePlace } from "./run-commands";
@@ -8,19 +9,7 @@ import { runLockFile, withRunLock } from "./run-lock";
 import { listRuns } from "./run-state";
 import { type Launch, wake } from "./wake";
 
-export const tickUsage = [
-  "usage: awf tick [--cwd <directory>] [--run-root <directory>] [--json]",
-  "       awf tick --all [--json]",
-  "",
-  "Wakes every run of a workflow with events under --cwd's .awf/runs, or --run-root, the runs awf",
-  "runs lists there, as an event would: continues a parked run whose wait's timer is due, and a",
-  "crashed or failed one until it has failed three times in a row. Runs of other workflows are left",
-  "as they are. --all wakes them in every project awf has started one in, as ~/.awf/projects lists",
-  "them. Run it on any schedule; a run is continued once however many wakers come at once.",
-  "",
-  "Prints a line for each run it woke, and nothing when it woke none. --json prints one document.",
-  "Exits 0, or 1 when a project is gone or a run could not be woken; the others are still woken.",
-].join("\n");
+export const tickUsage = help.trimEnd();
 
 export async function tickCommand(
   argv: readonly string[],

package/src/tools.ts

@@ -7,6 +7,7 @@ import {
   type AgentTools,
   isJsonValue,
   type JsonValue,
+  positiveDurationMilliseconds,
   TOOL_LIMITS,
   type ToolSpec,
 } from "@agentswf/contract/workflow";
@@ -14,7 +15,14 @@ import { canonical } from "./canonical-json";
 import { scheduleAt } from "./deadlines";
 import { messageOf } from "./errors";
 import type { RunEventBody } from "./run-event-log";
-import { checkGiven, QUOTING_RULE, readGiven, simpleInput, usageLine } from "./simple-input";
+import {
+  checkGiven,
+  QUOTING_RULE,
+  readGiven,
+  simpleInput,
+  takesText,
+  usageLine,
+} from "./simple-input";
 
 /** How long a handler that ignores its aborted signal is waited for before its call is settled. */
 export const TOOL_SETTLE_MS = 5_000;
@@ -51,6 +59,8 @@ export type ToolHost<Scope> = {
   /** Runs `fn` in the operation's scope, or in none. */
   runIn<T>(scope: Scope | undefined, fn: () => T): T;
   now?(): number;
+  /** A tool given its deprecated `timeoutMs`. */
+  deprecated?(name: "timeout-ms", call: string): void;
 };
 
 /** An operation as tool calls bind to it. */
@@ -69,7 +79,14 @@ export type ToolAnswer =
   | { kind: "tool-failed"; outcome: ToolFailure; error: string }
   | { kind: "refused"; code: ToolCode | "internal-error"; error: string };
 
-type Held = { specs: AgentTools; schemas: Map<string, JsonSchema | undefined> };
+/** A call's budget: milliseconds from its start, or none of its own. */
+type Budget = number | false;
+
+type Held = {
+  specs: AgentTools;
+  schemas: Map<string, JsonSchema | undefined>;
+  budgets: Map<string, Budget>;
+};
 
 type Running = {
   tool: string;
@@ -108,7 +125,7 @@ export class ToolCalls<Scope> {
 
   /** An agent opened or forked with these tools; checked against the limits first. */
   give(agent: AgentKey, tools: AgentTools): void {
-    this.#held.set(agent, held(agent, tools));
+    this.#held.set(agent, held(agent, tools, this.#host.deprecated));
   }
 
   /**
@@ -117,7 +134,7 @@ export class ToolCalls<Scope> {
    */
   reopen(agent: AgentKey, tools: AgentTools | undefined): void {
     if (tools === undefined) return;
-    const next = held(agent, tools);
+    const next = held(agent, tools, this.#host.deprecated);
     const existing = this.#held.get(agent);
     if (!existing || !sameTools(existing, next)) {
       throw new Error(`agent ${agent} is already open with different tools`);
@@ -195,7 +212,7 @@ export class ToolCalls<Scope> {
     if (operation) operation.deadline = () => deadline;
   }
 
-  /** The call this agent has running, which holds back its `wf result` and `wf waiting`. */
+  /** The call this agent has running, which holds back its `wfa result` and `wfa waiting`. */
   running(agent: AgentKey): { tool: string; settledBy?: number } | undefined {
     const running = this.#current.get(agent)?.running;
     return running && { tool: running.tool, ...optional("settledBy", running.settledBy) };
@@ -204,7 +221,7 @@ export class ToolCalls<Scope> {
   // Calls
 
   /**
-   * `wf tool`'s request from `agent`'s socket. `lifetime` sets how long its connection may stay
+   * `wfa tool`'s request from `agent`'s socket. `lifetime` sets how long its connection may stay
    * open, from now: undefined for as long as the call takes.
    */
   async call(
@@ -282,12 +299,11 @@ export class ToolCalls<Scope> {
     const controller = new AbortController();
     let cause: ToolFailure | undefined;
     let handlerEnded = false;
-    const timeoutMs = spec.timeoutMs === undefined ? TOOL_LIMITS.defaultTimeoutMs : spec.timeoutMs;
+    const budget = tools.budgets.get(request.tool)!;
     const deadline = operation.deadline();
     const startedAt = this.#now();
-    const budgetEnd = minimum(timeoutMs === false ? undefined : startedAt + timeoutMs, deadline);
-    const bound =
-      deadline !== undefined && budgetEnd === deadline ? ("deadline" as const) : timeoutMs;
+    const budgetEnd = minimum(budget === false ? undefined : startedAt + budget, deadline);
+    const bound = deadline !== undefined && budgetEnd === deadline ? ("deadline" as const) : budget;
     const { promise: settled, resolve: settle } = Promise.withResolvers<void>();
     const { promise: answered, resolve: answer } = Promise.withResolvers<ToolAnswer>();
     const running: Running = {
@@ -472,7 +488,7 @@ function aborted(
   tool: string,
   cause: ToolFailure,
   /** What bounded it: its own budget, or the turn's deadline. */
-  bound: number | false | "deadline",
+  bound: Budget | "deadline",
 ): { kind: "tool-failed"; outcome: ToolFailure; error: string } {
   const what =
     cause === "cancelled"
@@ -519,8 +535,8 @@ function readInput(
 
 /**
  * The tools block of an operation's prompt: how to call one, then each tool's name and description
- * and its usage line, or the schema for an input that isn't simple. The quoting rule comes with it
- * unless the result block above already said it; none for an agent without tools.
+ * and its usage line, or the schema for an input that isn't simple. The quoting rule comes with a
+ * free-text flag unless the result block above already said it; none for an agent without tools.
  */
 export function toolsLesson(
   tools: readonly { name: string; description: string; input?: JsonSchema }[],
@@ -533,9 +549,11 @@ export function toolsLesson(
     return { ...each, simple };
   });
   const flags = taught.some((each) => each.simple && each.simple.length > 0);
+  const text = taught.some((each) => each.simple && takesText(each.simple));
   const json = taught.some((each) => !each.simple);
+  const value = text ? "'<value>'" : "<value>";
   const forms = [
-    flags ? `${launcher} tool <name> --<option> '<value>' ...` : `${launcher} tool <name>`,
+    flags ? `${launcher} tool <name> --<option> ${value} ...` : `${launcher} tool <name>`,
     ...(json ? [`${launcher} tool <name> <<'WF_JSON'`, "<json>", "WF_JSON"] : []),
   ];
   const entries = taught.map(({ name, description, input, simple }) => {
@@ -549,13 +567,17 @@ export function toolsLesson(
     "You have tools the workflow runs for you. Call one with:",
     "",
     ...forms,
-    ...(flags && !quotingSaid ? ["", QUOTING_RULE] : []),
+    ...(text && !quotingSaid ? ["", QUOTING_RULE] : []),
     "",
     ...entries,
   ].join("\n");
 }
 
-function held(agent: AgentKey, tools: AgentTools): Held {
+function held(
+  agent: AgentKey,
+  tools: AgentTools,
+  deprecated: ToolHost<unknown>["deprecated"],
+): Held {
   if (typeof tools !== "object" || tools === null || Array.isArray(tools)) {
     throw new Error(`agent ${agent}'s tools are an object of tools by name`);
   }
@@ -564,6 +586,7 @@ function held(agent: AgentKey, tools: AgentTools): Held {
     throw new Error(`agent ${agent} has ${names.length} tools; at most ${TOOL_LIMITS.tools}`);
   }
   const schemas = new Map<string, JsonSchema | undefined>();
+  const budgets = new Map<string, Budget>();
   for (const name of names) {
     const spec = tools[name]!;
     const where = `agent ${agent}'s tool ${JSON.stringify(name)}`;
@@ -577,14 +600,7 @@ function held(agent: AgentKey, tools: AgentTools): Held {
     if (Buffer.byteLength(spec.description) > TOOL_LIMITS.descriptionBytes) {
       throw new Error(`${where}: its description is over ${TOOL_LIMITS.descriptionBytes} bytes`);
     }
-    const timeout = spec.timeoutMs;
-    if (
-      timeout !== undefined &&
-      timeout !== false &&
-      !(Number.isSafeInteger(timeout) && timeout > 0)
-    ) {
-      throw new Error(`${where}: timeoutMs is a positive integer, or false for none`);
-    }
+    budgets.set(name, budgetOf(where, spec, deprecated));
     if (spec.input === undefined) {
       schemas.set(name, undefined);
       continue;
@@ -610,7 +626,28 @@ function held(agent: AgentKey, tools: AgentTools): Held {
     // Its JSON, in the author's order for the lesson, without TypeBox's own keys.
     schemas.set(name, JSON.parse(JSON.stringify(input)) as JsonSchema);
   }
-  return { specs: { ...tools }, schemas };
+  return { specs: { ...tools }, schemas, budgets };
+}
+
+/** A tool's `timeout`, or its deprecated `timeoutMs`, checked; absent, the default. */
+function budgetOf(
+  where: string,
+  spec: ToolSpec,
+  deprecated: ToolHost<unknown>["deprecated"],
+): Budget {
+  const { timeout, timeoutMs } = spec;
+  if (timeout != null) {
+    if (timeoutMs != null)
+      throw new Error(`${where}: give timeout alone: timeoutMs is its deprecated form`);
+    if (timeout === false) return false;
+    return positiveDurationMilliseconds(timeout, `${where}: its timeout`);
+  }
+  if (timeoutMs == null) return TOOL_LIMITS.defaultTimeoutMs;
+  if (timeoutMs !== false && !(Number.isSafeInteger(timeoutMs) && timeoutMs > 0)) {
+    throw new Error(`${where}: timeoutMs is a positive integer, or false for none`);
+  }
+  deprecated?.("timeout-ms", "on a tool");
+  return timeoutMs;
 }
 
 function sameTools(a: Held, b: Held): boolean {

package/src/workflow-loader.ts

@@ -1,7 +1,7 @@
 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 * as workflowSurface from "@agentswf/contract/author";
 import {
   type EventSchemas,
   eventWorkflowProblem,
@@ -85,7 +85,10 @@ export async function loadWorkflowFile(file: string, cwd: string): Promise<Loade
     // As `tsc` would have checked them, for a file it never saw.
     const eventProblem = eventWorkflowProblem(given);
     if (eventProblem) throw new Error(eventProblem);
-    if (realPath(given.file as string) !== realPath(absolute))
+    if (given.file === undefined)
+      // Found by the path it was loaded from, which is all a sender with that path needs.
+      return { file: absolute, workflow: { ...given, file: absolute } as AnyWorkflow };
+    if (realPath(given.file) !== realPath(absolute))
       throw new Error(
         `file is ${JSON.stringify(given.file)}; a workflow with events gives file: import.meta.path, ${absolute}`,
       );