@agentswf/engine 0.1.0-beta.4 → 0.1.0

package/src/workflow-testing/script.ts

@@ -6,6 +6,7 @@ import type {
   ToolFailure,
 } from "@agentswf/contract/wire";
 import type {
+  Duration,
   Effort,
   JsonObject,
   JsonValue,
@@ -78,7 +79,11 @@ 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;
+};
 
 /** How a send or reply ended; a refusal is a value to test, not a throw. */
 export type MessageOutcome =
@@ -89,7 +94,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,26 +103,24 @@ 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;
 };
 
 /**
  * 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
- * `id` is the question's, a send's the new message's.
+ * How a participant's script's `reply` or `send` ended, as `awf reply --json` prints it without the
+ * `v`: delivered, `id` a reply's question or a send's new message, or refused with its `code`.
  */
-export type ParticipantOutcome = { code: "delivered"; id: string } | { code: ParticipantCode };
+export type ParticipantOutcome = { id: string } | { code: ParticipantCode };
 
 /**
  * A message an agent sent a participant, and what the participant's script may do about it, as
@@ -157,7 +161,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 +176,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 };
+};
 
 /** 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 +192,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 +212,69 @@ 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): NoAnswer => ({ [ENTRY]: { kind: "no-answer", ending: value } });
 
-/** 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" }),
 };
 
 /**
- * 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 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 TurnOutcome = "answered" | Ending["kind"] | "cancelled" | "awaiting-reply";
+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 }
   /** The script cannot meet this turn: the test's mistake, not the workflow's. */
   | { kind: "script-error"; message: string };
 
@@ -333,7 +362,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 +374,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 +386,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 +402,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 +432,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 +456,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 +488,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;
 }
 
@@ -489,7 +518,7 @@ function globMatches(pattern: string, key: string): boolean {
   return new RegExp(`^${escaped.join(".*")}$`).test(key);
 }
 
-export function firstLine(text: string): string {
+function firstLine(text: string): string {
   const line = text.split("\n", 1)[0]!;
   return line.length > 100 ? `${line.slice(0, 100)}…` : line;
 }

package/src/hold-run-lock.fixture.ts

@@ -1,8 +0,0 @@
-// Holds a run's lock from another process for `emit.test.ts`: `bun hold-run-lock.fixture.ts {file} {ms}`.
-import { withRunLock } from "./run-lock";
-
-const [file, ms] = process.argv.slice(2);
-await withRunLock(file!, async () => {
-  console.log("held");
-  await Bun.sleep(Number(ms));
-});