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

package/src/workflow-testing/script.ts

@@ -6,6 +6,7 @@ import type {
   ToolFailure,
 } from "@agentswf/contract/wire";
 import type {
+  Duration,
   Effort,
   JsonObject,
   JsonValue,
@@ -14,6 +15,7 @@ import type {
 } from "@agentswf/contract/workflow";
 import type Type from "typebox";
 import { canonical } from "../canonical-json";
+import type { Deprecated } from "../deprecations";
 import { messageOf } from "../errors";
 
 /** One turn of a scripted agent, as the workflow wrote it. */
@@ -78,7 +80,13 @@ export type Message = {
   answers?: true;
 };
 
-export type SendOptions = { awaitReply?: boolean; timeoutMs?: number };
+export type SendOptions = {
+  awaitReply?: boolean;
+  /** How long an awaited reply is waited for, as `wfa send --timeout` gives it. */
+  timeout?: Duration;
+  /** @deprecated Give `timeout`, a `Duration` such as `"30s"`. */
+  timeoutMs?: number;
+};
 
 /** How a send or reply ended; a refusal is a value to test, not a throw. */
 export type MessageOutcome =
@@ -89,7 +97,8 @@ export type MessageOutcome =
 
 /**
  * A message that woke the agent, and what its script may do in that turn: `reply` and `send` as
- * the turn's own, or end it with `silent` or `fail`. Returning ends the turn as `silent` does.
+ * the turn's own. Returning nothing ends the turn without a reply, and one owed is reminded once,
+ * then fails; returning `noAnswer.failed(reason)` fails it as a failed harness does.
  */
 export type ReceivedMessage = Message & {
   /** The turn it woke: whether it is a reminder (`nudge`), and every message shown in it. */
@@ -97,20 +106,22 @@ export type ReceivedMessage = Message & {
   reply(text: string, options?: SendOptions): Promise<MessageOutcome>;
   send(peer: string, text: string, options?: SendOptions): Promise<MessageOutcome>;
   tool(name: string, input?: JsonObject): Promise<ToolOutcome>;
-  /** Ends the turn without a reply; one owed is reminded once, then fails. */
-  silent(): Reply;
-  /** The harness failed: the message operation fails, and the agent stops. */
-  fail(reason?: string): Reply;
+  /** @deprecated Return nothing, which ends the turn without a reply. */
+  silent(): NoAnswer;
+  /** @deprecated Return `noAnswer.failed(reason)`. */
+  fail(reason?: string): NoAnswer;
 };
 
 /**
  * A message operation's script: called with the message that woke the agent, and again with the
  * next one when held messages continue the operation, or with the same one, `turn.nudge` set, when
- * it is reminded of a reply it owes.
+ * it is reminded of a reply it owes. A `noAnswer` it returns ends the turn as that says; nothing,
+ * or what a `reply` or `send` resolved to, ends it without a reply. A throw fails the test.
  */
 export type MessageScript = (
   message: ReceivedMessage,
-) => Reply | MessageOutcome | undefined | Promise<Reply | MessageOutcome | undefined>;
+  // biome-ignore lint/suspicious/noConfusingVoidType: an async script that returns nothing is Promise<void>.
+) => void | NoAnswer | MessageOutcome | Promise<void | NoAnswer | MessageOutcome>;
 
 /**
  * How a participant's script's `reply` or `send` ended, as `awf reply --json` reports it: a reply's
@@ -157,7 +168,7 @@ export type ParticipantScript = (event: ParticipantRoute | ParticipantMessage) =
 
 const ENTRY: unique symbol = Symbol("agentswf.script-entry");
 
-type Respond = (turn: Turn) => JsonValue | Reply | Promise<JsonValue | Reply>;
+type Respond = (turn: Turn) => JsonValue | NoAnswer | Promise<JsonValue | NoAnswer>;
 
 /** An answer to a turn that asks for its schema, or for text. Made by `answer`. */
 export type Answer = {
@@ -172,11 +183,13 @@ type Ending =
   | { kind: "hang" }
   | { kind: "interrupted" };
 
-/** A turn ended without an answer. Made by `reply`. */
-export type Reply = { readonly [ENTRY]: { kind: "reply"; ending: Ending } };
+/** A turn ended without an answer. Made by `noAnswer`. */
+export type NoAnswer = {
+  readonly [ENTRY]: { kind: "no-answer"; ending: Ending; deprecated?: Deprecated };
+};
 
 /** Every turn the agent is asked, alike; or a list, one entry per turn in order. */
-export type Script = Answer | Reply | readonly (Answer | Reply)[];
+export type Script = Answer | NoAnswer | readonly (Answer | NoAnswer)[];
 
 /** What a schema's answer is: the carrier the author surface types with, else TypeBox's `Static`. */
 export type AnswerOf<S> = S extends { readonly "~output"?: infer O }
@@ -186,11 +199,11 @@ export type AnswerOf<S> = S extends { readonly "~output"?: infer O }
   : StaticOf<S>;
 type StaticOf<S> = S extends Type.TSchema ? Type.Static<S> : JsonValue;
 
-type Answering<A> = A | ((turn: Turn) => A | Reply | Promise<A | Reply>);
+type Answering<A> = A | ((turn: Turn) => A | NoAnswer | Promise<A | NoAnswer>);
 
 /**
  * An answer to a turn that asks for `schema`: a value of its type, or a function of the turn that
- * returns one or a `reply`. A function that returns a reply is asked again for the nudge, with
+ * returns one or a `noAnswer`. A function that returns no answer is asked again for the nudge, with
  * `turn.nudge` set.
  */
 export function answer<const S extends OutputSchema>(
@@ -206,46 +219,94 @@ export function answer(...args: [unknown] | [unknown, unknown]): Answer {
   return { [ENTRY]: { kind: "answer", schema: schema as OutputSchema | undefined, respond } };
 }
 
-const ending = (value: Ending): Reply => ({ [ENTRY]: { kind: "reply", ending: value } });
+const ending = (value: Ending, deprecated?: Deprecated): NoAnswer => ({
+  [ENTRY]: {
+    kind: "no-answer",
+    ending: value,
+    ...(deprecated === undefined ? {} : { deprecated }),
+  },
+});
 
-/** Ends a turn without an answer. A reply answers no question, so it takes no schema. */
-export const reply = {
-  /** Reports a cooperative wait; later check-ins invoke the same answer function again. */
-  waiting: (reason: string, timeoutMs?: number): Reply =>
-    ending({ kind: "waiting", reason, ...(timeoutMs === undefined ? {} : { timeoutMs }) }),
+/** Ends a turn without an answer, so it takes no schema. */
+export const noAnswer = {
   /** Ends without a result; recovery follows the placement's production support. */
-  silent: (): Reply => ending({ kind: "silent" }),
+  silent: (): NoAnswer => ending({ kind: "silent" }),
   /** The agent is stuck, as on a permission prompt. */
-  blocked: (reason = "waiting on a permission prompt"): Reply =>
+  blocked: (reason = "waiting on a permission prompt"): NoAnswer =>
     ending({ kind: "blocked", reason }),
   /** The harness failed. */
-  failed: (reason = "harness crashed"): Reply => ending({ kind: "failed", reason }),
+  failed: (reason = "harness crashed"): NoAnswer => ending({ kind: "failed", reason }),
   /**
    * The agent's harness cannot sign in, as with an expired login: the turn fails with `login` set,
    * naming the agent's harness, `provider` where it logs in to several, and what to run.
    */
-  needsLogin: (provider?: string): Reply =>
+  needsLogin: (provider?: string): NoAnswer =>
     ending({ kind: "needs-login", ...(provider === undefined ? {} : { provider }) }),
   /** The harness reported the turn timed out; it ends at once. */
-  timedOut: (reason = "turn timed out"): Reply => ending({ kind: "timed-out", reason }),
+  timedOut: (reason = "turn timed out"): NoAnswer => ending({ kind: "timed-out", reason }),
   /** Holds the turn until the engine cancels it. */
-  hang: (): Reply => ending({ kind: "hang" }),
+  hang: (): NoAnswer => ending({ kind: "hang" }),
   /**
    * The operator stopped the turn in their pane, as only the calling session's can be: it settles
    * `cancelled`, is never nudged, and the session takes the next turn.
    */
-  interrupted: (): Reply => ending({ kind: "interrupted" }),
+  interrupted: (): NoAnswer => ending({ kind: "interrupted" }),
+};
+
+/** What `make` ends a turn with, marked as made through a deprecated name for the run to log. */
+export function deprecatedAs<A extends unknown[]>(
+  name: Deprecated,
+  make: (...args: A) => NoAnswer,
+): (...args: A) => NoAnswer {
+  return (...args) => ending(make(...args)[ENTRY].ending, name);
+}
+
+/** @deprecated Use `noAnswer`, the same calls: a reply answers, these end a turn without one. */
+export const reply: typeof noAnswer = {
+  silent: deprecatedAs("test-reply", noAnswer.silent),
+  blocked: deprecatedAs("test-reply", noAnswer.blocked),
+  failed: deprecatedAs("test-reply", noAnswer.failed),
+  needsLogin: deprecatedAs("test-reply", noAnswer.needsLogin),
+  timedOut: deprecatedAs("test-reply", noAnswer.timedOut),
+  hang: deprecatedAs("test-reply", noAnswer.hang),
+  interrupted: deprecatedAs("test-reply", noAnswer.interrupted),
 };
 
 /**
- * How a turn ended, as `run.turns` keeps it: `awaiting-reply` when its script awaits a reply, which
- * a later turn of the same call resumes it with.
+ * Reports a cooperative wait, `wfa waiting`; later check-ins invoke the same answer function again.
+ * Only the engine's own tests use it: whether an agent may wait is its harness's, not a workflow's.
  */
-export type TurnOutcome = "answered" | Ending["kind"] | "cancelled" | "awaiting-reply";
+export const waiting = (reason: string, timeoutMs?: number): NoAnswer =>
+  ending({ kind: "waiting", reason, ...(timeoutMs === undefined ? {} : { timeoutMs }) });
+
+/**
+ * How a turn ended, as `run.turns` keeps it: the engine's word, but for `waiting`, a check-in, and
+ * `awaiting-reply`, a script awaiting a reply, which a later turn of the same call resumes it with.
+ */
+export type TestTurnOutcome =
+  | "answered"
+  | "unanswered"
+  | "blocked"
+  | "failed"
+  | "timed-out"
+  | "cancelled"
+  | "waiting"
+  | "awaiting-reply";
+
+/**
+ * A turn's outcome until the engine's record replaces it: what a turn before its operation's last,
+ * a nudged one, keeps.
+ */
+export function outcomeOf(kind: Exclude<Ending["kind"], "waiting">): TestTurnOutcome {
+  if (kind === "silent") return "unanswered";
+  if (kind === "needs-login") return "failed";
+  if (kind === "hang" || kind === "interrupted") return "cancelled";
+  return kind;
+}
 
 export type Step =
   | { kind: "answer"; value: JsonValue }
-  | { kind: "reply"; ending: Ending }
+  | { kind: "no-answer"; ending: Ending; deprecated?: Deprecated }
   /** The script cannot meet this turn: the test's mistake, not the workflow's. */
   | { kind: "script-error"; message: string };
 
@@ -333,7 +394,7 @@ class Lists<E> {
 type Of = { noun: string; option: string; whose: string; expected: string };
 
 /** Each agent's turn scripts, or its compactions'. */
-export class Scripts extends Lists<Answer | Reply> {
+export class Scripts extends Lists<Answer | NoAnswer> {
   readonly #noun: string;
 
   constructor(
@@ -345,7 +406,7 @@ export class Scripts extends Lists<Answer | Reply> {
       {
         ...of,
         whose: of.noun === "turn" ? "script" : `${of.noun} script`,
-        expected: "answer(…), reply.…()",
+        expected: "answer(…), noAnswer.…()",
       },
       isEntry,
     );
@@ -357,14 +418,14 @@ export class Scripts extends Lists<Answer | Reply> {
     const found = this.entry(turn.agent, index);
     if ("why" in found) return this.error(turn, found.why);
     const meant = found.entry[ENTRY];
-    if (meant.kind === "reply") return { kind: "reply", ending: meant.ending };
+    if (meant.kind === "no-answer") return { ...meant };
     if (!sameSchema(meant.schema, turn.schema)) {
       return this.error(
         turn,
         `it asks for ${describeSchema(turn.schema)}; its script answers ${describeSchema(meant.schema)}`,
       );
     }
-    let out: JsonValue | Reply | undefined;
+    let out: JsonValue | NoAnswer | undefined;
     try {
       out = await meant.respond(turn);
     } catch (error) {
@@ -373,7 +434,7 @@ export class Scripts extends Lists<Answer | Reply> {
     if (out === undefined) return this.error(turn, "its script returned nothing");
     if (isEntry(out)) {
       const given = out[ENTRY];
-      if (given.kind === "reply") return { kind: "reply", ending: given.ending };
+      if (given.kind === "no-answer") return { ...given };
       return this.error(turn, "its script returned answer(…); a function returns the value itself");
     }
     return { kind: "answer", value: out };
@@ -403,8 +464,8 @@ export class MessageScripts extends Lists<MessageScript> {
   }
 
   /**
-   * Runs the script for the agent's `index`th message operation with `message`; what it returns
-   * ends the turn, as `silent` unless it is a `reply`.
+   * Runs the script for the agent's `index`th message operation with `message`: what it returns
+   * ends the turn silent unless it is a `noAnswer`.
    */
   async step(message: ReceivedMessage, index: number): Promise<Step> {
     const { turn } = message;
@@ -427,13 +488,13 @@ export class MessageScripts extends Lists<MessageScript> {
     }
     if (isEntry(out)) {
       const given = out[ENTRY];
-      if (given.kind === "reply") return { kind: "reply", ending: given.ending };
+      if (given.kind === "no-answer") return { ...given };
       return {
         kind: "script-error",
         message: `${where}: a message script ends a turn, it answers no call`,
       };
     }
-    return { kind: "reply", ending: { kind: "silent" } };
+    return { kind: "no-answer", ending: { kind: "silent" } };
   }
 }
 
@@ -459,7 +520,7 @@ export function findByKey<T>(
   };
 }
 
-function isEntry(value: unknown): value is Answer | Reply {
+function isEntry(value: unknown): value is Answer | NoAnswer {
   return typeof value === "object" && value !== null && ENTRY in value;
 }
 

package/src/workflow-testing/workflow-testing.typecheck.ts

@@ -1,7 +1,7 @@
 // Checked by `tsc --noEmit`, never run: each wrong answer is refused where it is written.
 import { defineWorkflow, type OutputSchema } from "@agentswf/contract/workflow";
 import Type from "typebox";
-import { answer, reply, type Script, testWorkflow } from ".";
+import { answer, noAnswer, type Script, testWorkflow } from ".";
 
 const VERDICT = Type.Union([
   Type.Object({ kind: Type.Literal("ready"), summary: Type.String() }),
@@ -17,13 +17,15 @@ export const valid: Script[] = [
       ? { kind: "changes-requested", feedback: ["more"] }
       : { kind: "ready", summary: "ok" },
   ),
-  answer(VERDICT, async (turn) => (turn.nudge ? reply.failed() : { kind: "ready", summary: "" })),
+  answer(VERDICT, async (turn) =>
+    turn.nudge ? noAnswer.failed() : { kind: "ready", summary: "" },
+  ),
   answer(CARRIED, { count: 1 }),
   answer(CARRIED, () => ({ count: 2 })),
   answer("text"),
   answer((turn) => `turn ${turn.n}`),
-  reply.silent(),
-  [answer(VERDICT, { kind: "ready", summary: "ok" }), reply.hang(), answer("done")],
+  noAnswer.silent(),
+  [answer(VERDICT, { kind: "ready", summary: "ok" }), noAnswer.hang(), answer("done")],
 ];
 
 export const invalid: Script[] = [
@@ -37,8 +39,8 @@ export const invalid: Script[] = [
   answer(VERDICT, () => ({ kind: "approved", summary: "ok" })),
   // @ts-expect-error the carrier's type
   answer(CARRIED, { count: "one" }),
-  // @ts-expect-error a reply is a script entry of its own, not an answer's value
-  answer(VERDICT, reply.silent()),
+  // @ts-expect-error no answer is a script entry of its own, not an answer's value
+  answer(VERDICT, noAnswer.silent()),
   // @ts-expect-error text answers a turn with no schema
   answer(42),
 ];
@@ -53,12 +55,13 @@ const withEvents = defineWorkflow({
   run: async (wf) => (await wf.receive()).length,
 });
 export const tested = () => testWorkflow(withEvents, { id: "k" });
-// @ts-expect-error a workflow with events is tested from { id, event? }, never its args
+// @ts-expect-error a workflow with events takes its args among its options
 export const byArgs = () => testWorkflow(withEvents, null);
 const plain = defineWorkflow({
   meta: { name: "p", description: "p" },
   prepare: ({ argv }) => ({ n: argv.length }),
   run: async (_wf, args) => args.n,
 });
-// @ts-expect-error a workflow without events is tested from its args, not { id }
+// @ts-expect-error a workflow that takes args is given them
 export const byOptions = () => testWorkflow(plain, { id: "k" });
+export const argued = () => testWorkflow(plain, { id: "k", args: { n: 1 } });