@agentswf/engine 0.1.0-beta.4 → 0.1.0

package/src/messaging/messaging.ts

@@ -9,7 +9,7 @@ import type {
 import type { ParticipantCode, PeerView, ReplyCode, SendCode } from "@agentswf/contract/wire";
 import type { AgentKey, JsonObject } from "@agentswf/contract/workflow";
 import type { AuthoredMessage } from "@agentswf/harness/adapter";
-import { duration } from "../duration";
+import { duration } from "../accounting/format";
 import { MESSAGE_LIMITS } from "./limits";
 import {
   directions,
@@ -53,6 +53,8 @@ export interface MessagingHost {
   changed(key: AgentKey): void;
   schedule(at: number, action: () => void): () => void;
   now(): number;
+  /** Question `n`'s id as `awf inbox` prints it, the attempt before it: what a refusal names. */
+  question(n: number): string;
   /** Written to the run's event log; `message-sent` is awaited before a send is acknowledged. */
   record(event: MessagingEventBody): Promise<void>;
 }
@@ -117,7 +119,7 @@ export type HolderRequest = {
 /** A holder's result: a reply's `message` is the question's number, a send's the new message's. */
 export type HolderResult =
   | { code: "delivered"; message: number }
-  | { code: Exclude<ParticipantCode, "not-found">; error: string; choices?: string[] };
+  | { code: ParticipantCode; error: string; choices?: string[] };
 
 /** A question open to an outside participant, and when it closes unanswered if it has a limit. */
 export type OpenQuestion = {
@@ -180,7 +182,7 @@ type Obligation = {
   /** It has a `--timeout` of its own, which only that fails it at. */
   readonly timed: boolean;
   /**
-   * When it closes unanswered, on an outside participant: the route's `timeoutMs` or the asker's
+   * When it closes unanswered: the route's `timeoutMs` or the asker's
    * shorter `--timeout`, and which of the two.
    */
   readonly closes?: { at: number; by: "route" | "own"; ms: number };
@@ -279,15 +281,13 @@ export class Messaging {
       }
     }
     const timeoutMs = options.timeoutMs;
-    if (timeoutMs !== undefined) {
-      if (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
-        throw new Error("a route's timeoutMs is a positive whole number of milliseconds");
-      // Only where an agent can ask an outside participant: nothing else needs it yet.
-      if (!pairs.some(([, to]) => this.#outside.has(to)))
-        throw new Error(
-          "timeoutMs is only for a route an agent asks an outside participant over: between them, or to it",
-        );
-    }
+    if (
+      timeoutMs !== undefined &&
+      (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
+    )
+      throw new Error(
+        `a route's timeoutMs is a positive whole number of milliseconds: not ${timeoutMs}`,
+      );
     const open = pairs.map(([from, to]) => this.#open(from, to));
     if (open.some(Boolean)) {
       if (
@@ -361,7 +361,7 @@ export class Messaging {
     });
   }
 
-  /** Writes `text` to a participant routed to the code, without a turn: an inbox item for it. */
+  /** Writes `text` to a participant, without a turn: an inbox item for it. */
   async post(key: AgentKey, text: string): Promise<string> {
     if (this.#closed) throw new Error("the attempt has ended; nothing more is posted");
     if (!this.#outside.has(key)) throw new Error(`${key} is not connected`);
@@ -446,7 +446,7 @@ export class Messaging {
         return holderRefusal(
           "ambiguous",
           `${agent} has ${open.length} questions open to ${as.key}; name one with --to.`,
-          open.map((each) => String(each.request.n)),
+          open.map((each) => this.#host.question(each.request.n)),
         );
       owed = open[0];
       if (!owed) return holderRefusal("expired", `${agent} has no question open to ${as.key}.`);
@@ -461,7 +461,7 @@ export class Messaging {
       if (!owed)
         return holderRefusal(
           "expired",
-          `${request.to} is not a question open from ${agent}${as.key === undefined ? "" : ` to ${as.key}`}.`,
+          `${this.#host.question(request.to)} is not a question open from ${agent}${as.key === undefined ? "" : ` to ${as.key}`}.`,
         );
     }
     const route = owed.request.route;
@@ -506,7 +506,7 @@ export class Messaging {
       return holderRefusal("no-route", `the workflow allows no route from ${from} to ${agent}.`);
     if (view.state === "stopped")
       return holderRefusal(
-        "stopped",
+        "peer-stopped",
         `${agent} has stopped${view.reason ? ` (${JSON.stringify(view.reason)})` : ""}.`,
       );
     const route = initiating.find((each) => each.open);
@@ -942,18 +942,20 @@ export class Messaging {
     return { kind: "ok", operation, owed: latest, bytes };
   }
 
-  /** `awaiting`, `unsupported` and `cycle`, checked for any question. */
+  /** `already-awaiting`, `unsupported` and `cycle`, checked for any question. */
   #checkAsk(
     from: AgentKey,
     peer: AgentKey,
     operation: Operation,
     /** The question a reply answers, which counts as answered here. */
     answering?: Obligation,
-  ): { kind: "refused"; code: "awaiting" | "unsupported" | "cycle"; error: string } | undefined {
+  ):
+    | { kind: "refused"; code: "already-awaiting" | "unsupported" | "cycle"; error: string }
+    | undefined {
     const wfa = this.#host.launcher(from);
     if (operation.awaits?.state === "open") {
       return refuse(
-        "awaiting",
+        "already-awaiting",
         `you already await ${operation.awaits.owedBy}. End your turn, or send without --await-reply.`,
       );
     }
@@ -1045,7 +1047,7 @@ export class Messaging {
   #ask(message: Message, operation: Operation, timeoutMs?: number): { until?: number } {
     message.route.count += 1;
     const now = this.#host.now();
-    const routeMs = this.#outside.has(message.to) ? message.route.timeoutMs : undefined;
+    const routeMs = message.route.timeoutMs;
     // The route's limit, or the asker's own when shorter: the shorter wins.
     const limit =
       routeMs !== undefined && (timeoutMs === undefined || routeMs <= timeoutMs)
@@ -1069,7 +1071,7 @@ export class Messaging {
       owedBy: message.to,
       ...(until === undefined ? {} : { until }),
       timed: limitAt < (outside ? Infinity : (operation.deadline ?? Infinity)),
-      ...(limit && outside ? { closes: { ...limit, at: limitAt } } : {}),
+      ...(limit ? { closes: { ...limit, at: limitAt } } : {}),
       state: "open",
     };
     message.asks = obligation;
@@ -1375,7 +1377,7 @@ export class Messaging {
         return {
           peer,
           can: this.#can(route, agent),
-          state: "outside",
+          kind: "participant",
           queued: 0,
           purpose: route.purpose,
         };
@@ -1388,8 +1390,13 @@ export class Messaging {
       return {
         peer,
         can: this.#can(route, agent),
+        kind: "agent",
         state:
-          view?.state === "stopped" ? "stopped" : awaiting ? "awaiting" : (view?.state ?? "idle"),
+          view?.state === "stopped"
+            ? "stopped"
+            : awaiting
+              ? "awaiting-reply"
+              : (view?.state ?? "idle"),
         ...(awaiting && view?.state !== "stopped" ? { awaits: awaiting } : {}),
         ...(view?.state === "stopped" && view.reason ? { reason: view.reason } : {}),
         queued,
@@ -1676,11 +1683,7 @@ function refuse<C extends SendCode | ReplyCode>(code: C, error: string) {
   return { kind: "refused" as const, code, error };
 }
 
-function holderRefusal(
-  code: Exclude<ParticipantCode, "not-found">,
-  error: string,
-  choices?: string[],
-): HolderResult {
+function holderRefusal(code: ParticipantCode, error: string, choices?: string[]): HolderResult {
   return { code, error, ...(choices ? { choices } : {}) };
 }
 

package/src/messaging/routes.ts

@@ -21,7 +21,7 @@ export type Route = {
   readonly asked?: number;
   /** As the workflow gave it, for telling an identical grant from a conflicting one. */
   readonly requested?: number;
-  /** On a route an agent asks an outside participant over: how long a question on it waits. */
+  /** How long a question on the route waits, to an agent or an outside participant. */
   readonly timeoutMs?: number;
   readonly scope: Scope;
   /** Messages counted against it, answers reserved for included. */

package/src/messaging/text.ts

@@ -31,7 +31,7 @@ export type Delivered =
     }
   | { kind: "no-reply"; from: AgentKey; reason: string };
 
-export function quoted(purpose: string): string {
+function quoted(purpose: string): string {
   return `“${purpose}”`;
 }
 
@@ -53,7 +53,7 @@ export function clock(at: number, now: number): string {
 }
 
 /** At least eight hex characters, as the design asks; a fresh one per delivery. */
-export function nonce(): string {
+function nonce(): string {
   return randomBytes(4).toString("hex");
 }
 
@@ -228,11 +228,13 @@ export function peersTable(
   const rows = peers.map((peer) => [
     peer.peer,
     peer.can,
-    peer.state === "awaiting"
-      ? `awaiting ${peer.awaits === viewer ? "you" : peer.awaits}`
-      : peer.state === "stopped" && peer.reason
-        ? `stopped (${peer.reason})`
-        : peer.state,
+    peer.kind === "participant"
+      ? "participant"
+      : peer.state === "awaiting-reply"
+        ? `awaiting-reply from ${peer.awaits === viewer ? "you" : peer.awaits}`
+        : peer.state === "stopped" && peer.reason
+          ? `stopped (${peer.reason})`
+          : peer.state,
     peer.queued > 0 ? String(peer.queued) : "",
     quoted(peer.purpose),
   ]);