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

package/src/logs-command.ts

@@ -1,8 +1,9 @@
 import { homedir } from "node:os";
 import type { LogEventJson, LogsJson, RouteEnds, RunLogLine } from "@agentswf/contract/records";
 import type { JsonObject } from "@agentswf/contract/workflow";
-import { duration } from "./duration";
+import { formatDuration, parseWait } from "./duration";
 import { messageOf } from "./errors";
+import help from "./help/logs.txt" with { type: "text" };
 import {
   clockTime,
   command,
@@ -34,21 +35,7 @@ import {
 import { findRun, findRunByRef, type RunStatus } from "./run-state";
 import { describeActivity } from "./run-view";
 
-export const logsUsage = [
-  "usage: awf logs [<run>] [@<handle>] [--agent <key>] [--stage <name>] [--after <cursor>]",
-  "                [--limit <n>] [--wait <seconds> | --follow] [--full] [--cwd <directory>]",
-  "                [--run-root <directory>] [--json]",
-  "",
-  "What a run did and is doing: its events and what its agents did, read from their own session",
-  "files, merged by time. With no run, the newest here. Without --after, the last 40 events; with",
-  "it, what came after, oldest first. Every answer ends with the command that gets only what is",
-  "new. --wait: with nothing to show yet, wait for the first event, at most that many seconds, up",
-  "to 300; --follow prints each event as it comes until the run ends. @<handle> names one event,",
-  "and --full prints its text, with common credential shapes masked; --json carries it always.",
-  "",
-  "Exits 0 on any read that worked, 1 when there is no such run or the cursor or handle does not",
-  "fit it, 2 on a usage error, 3 when the run's files could not be read.",
-].join("\n");
+export const logsUsage = help.trimEnd();
 
 const DEFAULT_LIMIT = 40;
 /**
@@ -98,7 +85,7 @@ export async function logsCommand(
     const parsed = parsePlace(argv, shellCwd);
     place = parsed.place;
     json = parsed.json;
-    options = parseLogs(parsed.rest);
+    options = parseLogs(parsed.rest, (line) => out.stderr(line));
     if (options.follow && json) throw new Error("--follow is for reading; --json takes --wait");
   } catch (error) {
     out.stderr(`awf: ${messageOf(error)}\n\n${logsUsage}`);
@@ -135,7 +122,7 @@ export async function logsCommand(
   }
 }
 
-function parseLogs(rest: readonly string[]): LogsOptions {
+function parseLogs(rest: readonly string[], deprecated: (line: string) => void): LogsOptions {
   const options: LogsOptions = {
     limit: DEFAULT_LIMIT,
     waitSeconds: 0,
@@ -160,11 +147,7 @@ function parseLogs(rest: readonly string[]): LogsOptions {
         throw new Error("--limit needs a whole number");
       options.limit = limit;
     } else if (arg === "--wait") {
-      const seconds = Number(value());
-      if (!Number.isFinite(seconds) || seconds < 0 || seconds > MAX_WAIT_SECONDS) {
-        throw new Error(`--wait needs seconds from 0 to ${MAX_WAIT_SECONDS}`);
-      }
-      options.waitSeconds = seconds;
+      options.waitSeconds = parseWait(value(), MAX_WAIT_SECONDS, deprecated);
       waitGiven = true;
     } else if (arg === "--follow") options.follow = true;
     else if (arg === "--full") options.full = true;
@@ -524,7 +507,7 @@ function trailer(
     return `run interrupted${go ? ` · continue: ${go}` : ""}`;
   }
   const { ended, started } = span(status, Date.now());
-  const took = ended === undefined ? "" : ` in ${duration(ended - started)}`;
+  const took = ended === undefined ? "" : ` in ${formatDuration(ended - started)}`;
   return `run ended: ${status.state}${took} · result: ${shellLine(command(place, "awf", "runs", status.ref))}`;
 }
 
@@ -582,7 +565,7 @@ function describeLine(line: RunLogLine, places: Places): string {
     case "compact": {
       const took =
         line.deliveredAt && line.settledAt
-          ? `  ${duration(Date.parse(line.settledAt) - Date.parse(line.deliveredAt))}`
+          ? `  ${formatDuration(Date.parse(line.settledAt) - Date.parse(line.deliveredAt))}`
           : "";
       return `${operation(line.kind)} ended  ${line.outcome}${took}`;
     }
@@ -604,7 +587,9 @@ function describeLine(line: RunLogLine, places: Places): string {
       return `decision ${line.decision} ${line.outcome}${line.error ? `  ${said(line.error)}` : ""}`;
     case "route-opened":
       return `route ${routeEnds(line)} opened  "${said(line.purpose)}"  ${line.maxMessages} messages${
-        line.timeoutMs === undefined ? "" : `, a question closes after ${duration(line.timeoutMs)}`
+        line.timeoutMs === undefined
+          ? ""
+          : `, a question closes after ${formatDuration(line.timeoutMs)}`
       }`;
     case "route-closed":
       return `route ${routeEnds(line)} closed  ${line.reason}`;
@@ -653,7 +638,9 @@ function describeLine(line: RunLogLine, places: Places): string {
         line.tool,
         places.calls.get(line.call)?.input,
         // Most calls take under a second; a duration says something only past one.
-        line.durationMs < 1000 ? line.outcome : `${line.outcome}  ${duration(line.durationMs)}`,
+        line.durationMs < 1000
+          ? line.outcome
+          : `${line.outcome}  ${formatDuration(line.durationMs)}`,
         answered,
       );
     }

package/src/mailbox.ts

@@ -11,7 +11,6 @@ import {
   AWF_ID_PREFIX,
   type JsonValue,
   type OperationRecord,
-  type ReceiveOptions,
   type TurnOutcome,
   type WorkflowEvent,
 } from "@agentswf/contract/workflow";
@@ -26,7 +25,19 @@ export function mailboxFile(runDir: string): string {
 /** The run's mailbox in the order written, less a line a crash tore and kinds this awf doesn't know. */
 export async function readMailbox(runDir: string): Promise<MailboxRecord[]> {
   const lines = await readLines<MailboxRecord>(mailboxFile(runDir));
-  return lines.filter((line) => line.version === MAILBOX_RECORD_VERSION && KINDS.has(line.kind));
+  return lines
+    .filter((line) => line.version === MAILBOX_RECORD_VERSION && KINDS.has(line.kind))
+    .map(withAnswered);
+}
+
+/** A turn's end written before 0.1.0-beta.4 has no `answered`, which a workflow would read as false. */
+function withAnswered(line: MailboxRecord): MailboxRecord {
+  if (line.kind !== "event" || line.name !== "agent:ended") return line;
+  const end = line.data as { outcome?: { kind: string; answered?: boolean } };
+  if (end?.outcome === undefined || end.outcome.answered !== undefined) return line;
+  const answered = end.outcome.kind === "answered";
+  const data = { ...end, outcome: { ...end.outcome, answered } } as unknown as JsonValue;
+  return { ...line, data };
 }
 
 const KINDS = new Set<string>([
@@ -137,6 +148,7 @@ export async function recoverTurns(
           turn: turn.turn,
           meta: turn.meta,
           outcome: {
+            answered: false,
             kind: "failed",
             reason: `attempt ${turn.attempt} ended before this turn did; its work, if any, is in the agent's session`,
             retryable: true,
@@ -614,12 +626,11 @@ export class RunMailbox {
    * nothing.
    */
   async receive(
-    options: ReceiveOptions | undefined,
+    label: string | undefined,
     stage?: string,
     /** Rejects the wait: the run ended, or the scope it waits in was cancelled. */
     signal?: AbortSignal,
   ): Promise<WorkflowEvent<string, JsonValue>[]> {
-    const { label, take } = checked(options);
     if (stage !== undefined) {
       const batch = await this.batchOf(stage);
       if (batch) return batch;
@@ -632,7 +643,7 @@ export class RunMailbox {
     return this.#wait(
       {
         ...(label === undefined ? {} : { label }),
-        take,
+        take: "all",
         ...(stage === undefined ? {} : { stage }),
       },
       signal,
@@ -959,19 +970,3 @@ async function mailboxSize(runDir: string): Promise<number> {
     () => 0,
   );
 }
-
-/** A wait's options as given, checked: what a typed caller can't get wrong, a plain one can. */
-function checked(options: ReceiveOptions | undefined): {
-  label?: string;
-  take: "all" | "oldest";
-} {
-  if (options !== undefined && (typeof options !== "object" || options === null))
-    throw new Error("receive takes { label?, take? }");
-  const { label, take = "all" } = options ?? {};
-  if (label !== undefined && typeof label !== "string")
-    throw new Error("receive's label is a string");
-  if (take !== "all" && take !== "oldest") throw new Error('receive\'s take is "all" or "oldest"');
-  if ("until" in (options ?? {}))
-    throw new Error("receive has no until: a timer, workflow.timer(name, when), wakes it");
-  return { ...(label === undefined ? {} : { label }), take };
-}

package/src/messaging/limits.ts

@@ -12,14 +12,14 @@ export const MESSAGE_LIMITS: MessageLimits = {
 
 /**
  * Where an asker may wait for an answer, by harness and placement: on where M2 passed
- * (`docs/findings/messaging-m2.md`), off elsewhere. A pane that is `confirmed` waits only where it
- * confirms what it was sent, as `wf waiting` needs. The fake harness always may. cursor is off:
+ * (`docs/findings/messaging-m2.md`), off elsewhere. A TUI that is `confirmed` waits only where it
+ * confirms what it was sent, as `wfa waiting` needs. The fake harness always may. cursor is off:
  * its turns ran past their deadline in M2.
  */
-export const AWAIT_REPLY: Readonly<Record<string, { headless?: true; pane?: true | "confirmed" }>> =
+export const AWAIT_REPLY: Readonly<Record<string, { headless?: true; tui?: true | "confirmed" }>> =
   {
-    fake: { headless: true, pane: true },
-    claude: { headless: true, pane: "confirmed" },
+    fake: { headless: true, tui: true },
+    claude: { headless: true, tui: "confirmed" },
     codex: { headless: true },
     pi: { headless: true },
   };

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 { formatDuration } from "../duration";
 import { MESSAGE_LIMITS } from "./limits";
 import {
   directions,
@@ -47,7 +47,7 @@ export interface MessagingHost {
   agent(key: AgentKey): AgentView | undefined;
   /** Whether it may `--await-reply` where it runs. */
   canAwait(key: AgentKey): boolean;
-  /** The launcher it runs `wf` through. */
+  /** The launcher it runs `wfa` through. */
   launcher(key: AgentKey): string;
   /** Something is new for this agent: messages for it, or an end to its wait. */
   changed(key: AgentKey): void;
@@ -180,7 +180,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 };
@@ -207,7 +207,7 @@ type Operation = OperationInfo & {
 /**
  * The messaging logic of one attempt: routes, admission, inboxes and owed answers. It decides every
  * case the design lists and writes the record; it starts nothing. The runner opens and continues
- * operations when it says, and the control plane hands it `wf`'s commands.
+ * operations when it says, and the control plane hands it `wfa`'s commands.
  */
 export class Messaging {
   readonly limits: MessageLimits;
@@ -279,15 +279,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 +359,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`);
@@ -506,7 +504,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);
@@ -702,8 +700,8 @@ export class Messaging {
   }
 
   /**
-   * A refusal of `wf result` or `wf waiting` given this call id, or the acknowledgement of a
-   * `wf waiting` while an answer is awaited; null when the command goes on as before.
+   * A refusal of `wfa result` or `wfa waiting` given this call id, or the acknowledgement of a
+   * `wfa waiting` while an answer is awaited; null when the command goes on as before.
    */
   checkFinish(
     agent: AgentKey,
@@ -715,7 +713,7 @@ export class Messaging {
     | null {
     const operation = this.#operations.get(id);
     if (!operation || operation.agent !== agent) return null;
-    const wf = this.#host.launcher(agent);
+    const wfa = this.#host.launcher(agent);
     // A message operation's call takes no result, ended or not.
     if (operation.kind === "message") {
       return {
@@ -733,8 +731,8 @@ export class Messaging {
         code: "owes-reply",
         error:
           command === "result"
-            ? `you owe ${peer} a reply. Send it with ${wf} reply ${peer}, then run ${wf} result ${id} again.`
-            : `you owe ${peer} a reply; send it with ${wf} reply ${peer} first.`,
+            ? `you owe ${peer} a reply. Send it with ${wfa} reply ${peer}, then run ${wfa} result ${id} again.`
+            : `you owe ${peer} a reply; send it with ${wfa} reply ${peer} first.`,
       };
     }
     const waited = operation.awaits;
@@ -743,7 +741,7 @@ export class Messaging {
         kind: "awaiting",
         peer: waited.owedBy,
         ...(waited.until === undefined ? {} : { until: waited.until }),
-        notice: `you already await ${waited.owedBy}'s reply${waited.until === undefined ? "" : `, until ${clock(waited.until, this.#host.now())}`}. End your turn, or finish with ${wf} result ${id}.`,
+        notice: `you already await ${waited.owedBy}'s reply${waited.until === undefined ? "" : `, until ${clock(waited.until, this.#host.now())}`}. End your turn, or finish with ${wfa} result ${id}.`,
       };
     }
     return null;
@@ -815,7 +813,7 @@ export class Messaging {
   ):
     | { kind: "ok"; operation: Operation; route: Route; bytes: number }
     | { kind: "refused"; code: SendCode; error: string } {
-    const wf = this.#host.launcher(from);
+    const wfa = this.#host.launcher(from);
     const operation = this.#current.get(from);
     if (!operation) return refuse("no-operation", "this agent has no open operation.");
     const { peer } = request;
@@ -826,14 +824,14 @@ export class Messaging {
       return refuse(
         "no-route",
         owes
-          ? `your route with ${peer} only answers its requests. Answer it with ${wf} reply ${peer}.`
+          ? `your route with ${peer} only answers its requests. Answer it with ${wfa} reply ${peer}.`
           : `your route with ${peer} only answers its requests, and it asked nothing. Nothing to send; end your turn.`,
       );
     };
     if (initiating.length === 0) {
       return this.#open(peer, from)
         ? replyOnly()
-        : refuse("no-route", `no route to ${peer}. Your routes: ${wf} peers`);
+        : refuse("no-route", `no route to ${peer}. Your routes: ${wfa} peers`);
     }
     const agent = this.#outside.has(peer) ? undefined : this.#host.agent(peer);
     if (agent?.state === "stopped")
@@ -889,7 +887,7 @@ export class Messaging {
   ):
     | { kind: "ok"; operation: Operation; owed: Obligation; bytes: number }
     | { kind: "refused"; code: ReplyCode; error: string } {
-    const wf = this.#host.launcher(from);
+    const wfa = this.#host.launcher(from);
     const operation = this.#current.get(from);
     if (!operation) return refuse("no-operation", "this agent has no open operation.");
     const { peer } = request;
@@ -898,7 +896,7 @@ export class Messaging {
       (each) => each.asker === peer && each.owedBy === from && each.request.shown,
     );
     if (!latest || latest.state === "replied") {
-      return refuse("none-owed", `you owe ${peer} nothing. Send it with ${wf} send ${peer}.`);
+      return refuse("none-owed", `you owe ${peer} nothing. Send it with ${wfa} send ${peer}.`);
     }
     if (latest.state !== "open" || latest.owingOperation !== operation) {
       const agent = this.#host.agent(peer);
@@ -906,7 +904,7 @@ export class Messaging {
         "expired",
         agent?.state === "stopped"
           ? `${peer} has stopped${agent.reason ? ` (${JSON.stringify(agent.reason)})` : ""}; nothing reaches it now.`
-          : `${peer} stopped waiting at ${clock(latest.endedAt ?? this.#host.now(), this.#host.now())}. Send it with ${wf} send ${peer}.`,
+          : `${peer} stopped waiting at ${clock(latest.endedAt ?? this.#host.now(), this.#host.now())}. Send it with ${wfa} send ${peer}.`,
       );
     }
     const route = latest.request.route;
@@ -942,18 +940,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 {
-    const wf = this.#host.launcher(from);
+  ):
+    | { 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.`,
       );
     }
@@ -984,7 +984,7 @@ export class Messaging {
         return refuse(
           "cycle",
           owing
-            ? `${who}, and you owe ${last === peer ? "it" : last} a reply. Answer with ${wf} reply ${last}; it may --await-reply.`
+            ? `${who}, and you owe ${last === peer ? "it" : last} a reply. Answer with ${wfa} reply ${last}; it may --await-reply.`
             : `${who}. Send without --await-reply and end your turn; ${last}'s request reaches you then.`,
         );
       }
@@ -1045,7 +1045,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 +1069,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;
@@ -1085,7 +1085,7 @@ export class Messaging {
             obligation,
             "timed-out",
             obligation.closes?.by === "route"
-              ? `the question closed unanswered after ${duration(obligation.closes.ms)}`
+              ? `the question closed unanswered after ${formatDuration(obligation.closes.ms)}`
               : `your --timeout passed at ${clock(closesAt, this.#host.now())}`,
           );
         }
@@ -1095,7 +1095,7 @@ export class Messaging {
   }
 
   /**
-   * Durable before `wf send` returns: a failed write rejects, and `wf` says it may have been
+   * Durable before `wfa send` returns: a failed write rejects, and `wfa` says it may have been
    * queued. An outside participant's message says what it came through instead of an operation.
    * A question to one carries when it closes unanswered, if it has a limit.
    */
@@ -1134,13 +1134,13 @@ export class Messaging {
   }
 
   #awaitNotice(operation: Operation, { until }: { until?: number }): string {
-    const wf = this.#host.launcher(operation.agent);
+    const wfa = this.#host.launcher(operation.agent);
     return [
       `Its reply starts your next turn (${until === undefined ? "no deadline" : `deadline ${clock(until, this.#host.now())}`}).`,
       "Go on with work that does not need the answer, then end your turn with one line saying what you await; do not poll or sleep.",
       ...(operation.kind === "workflow"
         ? [
-            `If you find the answer first, or decide not to wait, finish with ${wf} result ${operation.id}; the wait is dropped.`,
+            `If you find the answer first, or decide not to wait, finish with ${wfa} result ${operation.id}; the wait is dropped.`,
           ]
         : []),
     ].join("\n");
@@ -1323,7 +1323,7 @@ export class Messaging {
   /**
    * What is held for an operation whose turn has ended, deciding nothing: `continues` when its turn
    * end would go on with it, `held` when messages wait for a later operation or to cut a check-in's
-   * `wf waiting` short, `none` otherwise.
+   * `wfa waiting` short, `none` otherwise.
    */
   pending(id: string): Pending {
     const operation = this.#operations.get(id);
@@ -1375,7 +1375,7 @@ export class Messaging {
         return {
           peer,
           can: this.#can(route, agent),
-          state: "outside",
+          kind: "participant",
           queued: 0,
           purpose: route.purpose,
         };
@@ -1388,8 +1388,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,
@@ -1405,7 +1410,7 @@ export class Messaging {
     };
   }
 
-  /** The line `wf` leads with while this agent's operation owes or awaits an answer. */
+  /** The line `wfa` leads with while this agent's operation owes or awaits an answer. */
   owing(agent: AgentKey): string | undefined {
     const { owes, awaits } = this.#standing(agent);
     return owingLine(owes, awaits, this.#host.launcher(agent), this.#host.now());
@@ -1476,7 +1481,7 @@ export class Messaging {
 
   /**
    * This agent's open routes, either end, in the order granted; with `stopped`, also those a peer's
-   * stop closed, so `wf peers` can say it stopped.
+   * stop closed, so `wfa peers` can say it stopped.
    */
   #routesOf(agent: AgentKey, stopped = false): Route[] {
     return [...new Set([...this.#routes.values()].flat())]

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. */
@@ -29,7 +29,7 @@ export type Route = {
   open: boolean;
   /** Why it closed. */
   closed?: "stage-ended" | "agent-stopped" | "released" | "attempt-ended";
-  /** Its place among the attempt's grants, which `wf peers` lists in. */
+  /** Its place among the attempt's grants, which `wfa peers` lists in. */
   readonly order: number;
 };
 

package/src/messaging/text.ts

@@ -4,7 +4,7 @@ import type { AgentKey } from "@agentswf/contract/workflow";
 
 /**
  * Everything an agent reads about messaging. The engine writes it all, since only it knows the
- * launcher's path, the routes' purposes and what closes a cycle; `wf` prints it as given. `wf`
+ * launcher's path, the routes' purposes and what closes a cycle; `wfa` prints it as given. `wfa`
  * here is always the launcher's full path: the command is not on the agent's PATH.
  */
 
@@ -13,7 +13,7 @@ export type Recipient = {
   launcher: string;
   /** The operation's call id. */
   callId: string;
-  /** A workflow's own operation finishes with `wf result`; a message operation ends its turn. */
+  /** A workflow's own operation finishes with `wfa result`; a message operation ends its turn. */
   kind: "workflow" | "message";
 };
 
@@ -92,7 +92,7 @@ export function envelope(
   } = {},
 ): string {
   const tag = options.tag ?? nonce();
-  const wf = to.launcher;
+  const wfa = to.launcher;
   const blocks: string[] = [];
   const owed = new Set<AgentKey>();
   for (const item of items) {
@@ -104,7 +104,7 @@ export function envelope(
     if (item.answers) {
       blocks.push(
         [
-          `The reply you were waiting for, from ${item.from}${item.asks ? `; it asks something back, so you owe it a reply: answer with ${wf} reply ${item.from}` : ""}.`,
+          `The reply you were waiting for, from ${item.from}${item.asks ? `; it asks something back, so you owe it a reply: answer with ${wfa} reply ${item.from}` : ""}.`,
           "",
           fenced("reply", item.from, item.text, tag),
         ].join("\n"),
@@ -114,13 +114,13 @@ export function envelope(
     const stop = /[.!?]$/.test(item.purpose) ? "" : ".";
     const head = `Message from ${item.from}, on the route ${quoted(item.purpose)}${stop}`;
     const lead = options.opens ? ` This is a message, not a new task (call ${to.callId}).` : "";
-    const asks = item.asks ? ` A reply is required: answer with ${wf} reply ${item.from}.` : "";
+    const asks = item.asks ? ` A reply is required: answer with ${wfa} reply ${item.from}.` : "";
     blocks.push(
       [`${head}${lead}${asks}`, "", fenced("message", item.from, item.text, tag)].join("\n"),
     );
   }
   const lines = [blocks.join("\n\n")];
-  if (options.announced?.length) lines.push(announcement(options.announced, wf));
+  if (options.announced?.length) lines.push(announcement(options.announced, wfa));
   const plain = items.some((item) => item.kind === "message" && !item.answers);
   if (plain) lines.push(GUARD);
   lines.push(next(items, to, owed));
@@ -129,7 +129,7 @@ export function envelope(
 
 /** The closing line: whether the task goes on, and how it ends. */
 function next(items: readonly Delivered[], to: Recipient, owed: ReadonlySet<AgentKey>): string {
-  const wf = to.launcher;
+  const wfa = to.launcher;
   const failed = items.some((item) => item.kind === "no-reply");
   const answered = items.some((item) => item.kind === "message" && item.answers);
   if (to.kind === "message") {
@@ -140,9 +140,9 @@ function next(items: readonly Delivered[], to: Recipient, owed: ReadonlySet<Agen
       return `Your work for call ${to.callId} continues; end your turn when it is done.`;
     return `No reply is required; end your turn once you have acted on it ${call}.`;
   }
-  const finish = `finish it with ${wf} result ${to.callId}`;
+  const finish = `finish it with ${wfa} result ${to.callId}`;
   if (owed.size > 0) return `Your task ${to.callId} goes on: once you have replied, ${finish}.`;
-  if (failed) return `Continue without it, or finish with ${wf} result ${to.callId}.`;
+  if (failed) return `Continue without it, or finish with ${wfa} result ${to.callId}.`;
   return `Your task ${to.callId} continues; ${finish}.`;
 }
 
@@ -162,12 +162,12 @@ function routeLine({ peer, can, purpose }: RouteLine): string {
 /** What an operation's prompt says about the agent's routes, once, in a few lines. */
 export function routeLesson(routes: readonly RouteLine[], launcher: string): string {
   if (routes.length === 0) return "";
-  const wf = launcher;
+  const wfa = launcher;
   return [
     "You can message other agents on these routes:",
     ...routes.map(routeLine),
-    `See them with ${wf} peers. Send with ${wf} send <peer> <<'EOF' ... EOF. To ask and wait for the answer, send with ${wf} send --await-reply <peer>; the answer starts your next turn, so end your turn then, and do not poll or sleep.`,
-    `Answer a question with ${wf} reply <peer> <<'EOF' ... EOF; only a reply counts as the answer.`,
+    `See them with ${wfa} peers. Send with ${wfa} send <peer> <<'EOF' ... EOF. To ask and wait for the answer, send with ${wfa} send --await-reply <peer>; the answer starts your next turn, so end your turn then, and do not poll or sleep.`,
+    `Answer a question with ${wfa} reply <peer> <<'EOF' ... EOF; only a reply counts as the answer.`,
   ].join("\n");
 }
 
@@ -181,14 +181,14 @@ function announcement(routes: readonly RouteLine[], launcher: string): string {
 
 /** The one reminder a turn that ends owing gets. */
 export function reminder(owed: readonly AgentKey[], to: Recipient): string {
-  const wf = to.launcher;
+  const wfa = to.launcher;
   const who = owed.join(" and ");
-  const how = owed.map((peer) => `${wf} reply ${peer}`).join(", then ");
-  const then = to.kind === "workflow" ? `then ${wf} result ${to.callId}` : "then end your turn";
+  const how = owed.map((peer) => `${wfa} reply ${peer}`).join(", then ");
+  const then = to.kind === "workflow" ? `then ${wfa} result ${to.callId}` : "then end your turn";
   return `You owe ${who} a reply; send it with ${how}, ${then}.`;
 }
 
-/** The line every `wf` command leads with while the operation owes or awaits an answer. */
+/** The line every `wfa` command leads with while the operation owes or awaits an answer. */
 export function owingLine(
   owes: readonly AgentKey[],
   awaits: { peer: AgentKey; until?: number } | undefined,
@@ -207,7 +207,7 @@ export function owingLine(
   return parts.length === 0 ? undefined : `${parts.join("; ")}.`;
 }
 
-/** `wf peers`'s table, the line about what is owed, and nothing for empty cells. */
+/** `wfa peers`'s table, the line about what is owed, and nothing for empty cells. */
 export function peersTable(
   peers: readonly PeerView[],
   awaits: { peer: AgentKey; until?: number } | undefined,
@@ -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),
   ]);