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

package/src/workflow-testing/script.ts

@@ -1,5 +1,17 @@
-import type { ReplyCode, SendCode } from "@agentswf/contract/wire";
-import type { Effort, JsonValue, OperationCause, OutputSchema } from "@agentswf/contract/workflow";
+import type {
+  ParticipantCode,
+  ReplyCode,
+  SendCode,
+  ToolCode,
+  ToolFailure,
+} from "@agentswf/contract/wire";
+import type {
+  Effort,
+  JsonObject,
+  JsonValue,
+  OperationCause,
+  OutputSchema,
+} from "@agentswf/contract/workflow";
 import type Type from "typebox";
 import { canonical } from "../canonical-json";
 import { messageOf } from "../errors";
@@ -30,18 +42,32 @@ export type Turn = {
    */
   readonly messages: readonly Message[];
   /**
-   * `wf send`: resolves once admitted, `sent`; or, with `awaitReply`, with the reply, which arrives
+   * `wfa send`: resolves once admitted, `sent`; or, with `awaitReply`, with the reply, which arrives
    * in a later turn of the same call. Returning a result without awaiting it drops the wait, and it
    * resolves `failed` with reason `dropped`. While a reply is awaited the script awaits only the
    * host's calls: once it is still, its turn ends.
    */
   send(peer: string, text: string, options?: SendOptions): Promise<MessageOutcome>;
-  /** `wf reply`: answers the question `peer` asked. A result is refused while one is owed. */
+  /** `wfa reply`: answers the question `peer` asked. A result is refused while one is owed. */
   reply(peer: string, text: string, options?: SendOptions): Promise<MessageOutcome>;
+  /**
+   * `wfa tool`: calls the agent's tool `name` with `input` as its JSON, or none, through the run's
+   * real checks and handler; resolves with what the agent would read.
+   */
+  tool(name: string, input?: JsonObject): Promise<ToolOutcome>;
   /** Fires when the engine cancels the turn. */
   signal: AbortSignal;
 };
 
+/**
+ * How a tool call ended, as `wfa tool` reports it; a failure or a refusal is a value to test. A
+ * refusal carries what the agent is told, which for `invalid-input` is what it corrects from.
+ */
+export type ToolOutcome =
+  | { kind: "result"; output?: string }
+  | { kind: "failed"; outcome: ToolFailure; error: string }
+  | { kind: "refused"; code: ToolCode; error: string };
+
 /** A message as the agent was shown it. */
 export type Message = {
   from: string;
@@ -70,6 +96,7 @@ export type ReceivedMessage = Message & {
   turn: Turn;
   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. */
@@ -85,6 +112,49 @@ export type MessageScript = (
   message: ReceivedMessage,
 ) => Reply | MessageOutcome | undefined | Promise<Reply | MessageOutcome | undefined>;
 
+/**
+ * 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.
+ */
+export type ParticipantOutcome = { code: "delivered"; id: string } | { code: ParticipantCode };
+
+/**
+ * A message an agent sent a participant, and what the participant's script may do about it, as
+ * whoever answers for it would with `awf reply` and `awf send`. An answer is recorded as coming through `test`.
+ */
+export type ParticipantMessage = {
+  kind: "message";
+  /** `{attempt}.{n}`, as `awf inbox` prints it. */
+  id: string;
+  /** The agent's peer address. */
+  from: string;
+  text: string;
+  /** A question: it stays open until the script answers it, or it expires. */
+  asks?: true;
+  /** Answers this question, as `awf reply --to` does. */
+  reply(text: string): Promise<ParticipantOutcome>;
+  /** Messages an agent over a route the workflow allowed, as `awf send` does. */
+  send(agent: string, text: string): Promise<ParticipantOutcome>;
+};
+
+/** A route to or from a participant, as it opens: where a script that speaks first starts. */
+export type ParticipantRoute = {
+  kind: "route";
+  /** The agent's peer address. */
+  agent: string;
+  direction: "both" | "to-participant" | "from-participant";
+  purpose: string;
+  /** Messages the agent, as `awf send` does. */
+  send(text: string): Promise<ParticipantOutcome>;
+};
+
+/**
+ * A participant's script: called with each route to it as it opens, and each message an agent sends
+ * it, once recorded; the `awf inbox` items whoever answers for it would act on. What it returns is awaited and
+ * otherwise ignored: a question it does not answer stays open, and a throw fails the test.
+ */
+export type ParticipantScript = (event: ParticipantRoute | ParticipantMessage) => unknown;
+
 const ENTRY: unique symbol = Symbol("agentswf.script-entry");
 
 type Respond = (turn: Turn) => JsonValue | Reply | Promise<JsonValue | Reply>;

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 type { OutputSchema } from "@agentswf/contract/workflow";
+import { defineWorkflow, type OutputSchema } from "@agentswf/contract/workflow";
 import Type from "typebox";
-import { answer, reply, type Script } from ".";
+import { answer, reply, type Script, testWorkflow } from ".";
 
 const VERDICT = Type.Union([
   Type.Object({ kind: Type.Literal("ready"), summary: Type.String() }),
@@ -45,3 +45,20 @@ export const invalid: Script[] = [
 
 // @ts-expect-error raw JSON where a script expects answer(…)
 export const raw: Script = { kind: "ready", summary: "ok" };
+
+const withEvents = defineWorkflow({
+  meta: { name: "w", description: "w" },
+  file: import.meta.path,
+  events: { ping: { type: "object" } as OutputSchema<{ n: number }> },
+  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
+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 }
+export const byOptions = () => testWorkflow(plain, { id: "k" });