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

package/src/messaging/messaging.ts

@@ -1,13 +1,15 @@
 import type {
   MessageLimits,
   MessagingEvent,
+  OutsideVia,
   RequestEnd,
   RouteEnds,
   UndeliveredReason,
 } from "@agentswf/contract/records";
-import type { PeerView, ReplyCode, SendCode } from "@agentswf/contract/wire";
-import type { AgentKey } from "@agentswf/contract/workflow";
+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 { MESSAGE_LIMITS } from "./limits";
 import {
   directions,
@@ -45,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;
@@ -65,10 +67,10 @@ export type OperationInfo = {
   agent: AgentKey;
   /** A workflow's own `run`, or one a message opened. */
   kind: "workflow" | "message";
-  /** Unix milliseconds; a message operation's may move later. */
-  deadline: number;
-  /** The latest its deadline may move to: the run's. */
-  ceiling: number;
+  /** Unix milliseconds, absent when nothing bounds it; a message operation's may move later. */
+  deadline?: number;
+  /** The latest its deadline may move to: the deadlines around it, absent when there are none. */
+  ceiling?: number;
   /** The scope it runs in: its route's for a message operation, the stage's for a `run`. */
   scope: Scope;
 };
@@ -100,6 +102,31 @@ export type Delivery = {
   deadline?: number;
 };
 
+/**
+ * What a holder asks for, as `awf reply` and `awf send` do: `coordinator` is `--as`, `to` the
+ * question's number within the attempt.
+ */
+export type HolderRequest = {
+  coordinator?: AgentKey;
+  agent: AgentKey;
+  to?: number;
+  text: string;
+  via: OutsideVia;
+};
+
+/** 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[] };
+
+/** A question open to an outside participant, and when it closes unanswered if it has a limit. */
+export type OpenQuestion = {
+  coordinator: AgentKey;
+  message: number;
+  asker: AgentKey;
+  closesAt?: number;
+};
+
 /** What is held for an operation whose turn has ended, without deciding anything. */
 export type Pending = "continues" | "held" | "none";
 
@@ -107,8 +134,11 @@ export type Pending = "continues" | "held" | "none";
 export type TurnEnd =
   /** Something continues it now: an answer, a failure, a question, or held messages. */
   | { kind: "continue" }
-  /** It awaits `peer`'s answer until `until`: nothing runs, a pane stays, a headless process exits. */
-  | { kind: "wait"; peer: AgentKey; until: number }
+  /**
+   * It awaits `peer`'s answer, until `until` if the wait has a limit: nothing runs, a pane stays, a
+   * headless process exits.
+   */
+  | { kind: "wait"; peer: AgentKey; until?: number }
   /** It owes answers: the one reminder, as its next prompt. */
   | { kind: "remind"; text: string }
   /** A workflow's operation with nothing owed or held: 021's check-in. */
@@ -142,10 +172,18 @@ type Obligation = {
   owingOperation?: Operation;
   /** Its owing operation was reminded of it once; the next turn's end that still owes fails it. */
   reminded?: true;
-  /** The asker waits until then: its `--timeout`, or its operation's deadline as that moves. */
-  until: number;
+  /**
+   * The asker waits until then: its `--timeout`, or its operation's deadline as that moves; absent
+   * when nothing limits it. On an outside participant, only its limit: the deadline does not count.
+   */
+  until?: number;
   /** 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
+   * shorter `--timeout`, and which of the two.
+   */
+  readonly closes?: { at: number; by: "route" | "own"; ms: number };
   state: "open" | RequestEnd;
   /** Its end, set once; a reply after it is refused `expired`. */
   endedAt?: number;
@@ -155,6 +193,9 @@ type Obligation = {
 type Failure = { kind: "no-reply"; for: Operation; from: AgentKey; reason: string };
 type Held = Message | Failure;
 
+/** A participant outside the run, which the workflow connected: it has no operation and no inbox. */
+type Outside = { readonly key: AgentKey; released: boolean };
+
 type Operation = OperationInfo & {
   awaits?: Obligation;
   readonly owes: Set<Obligation>;
@@ -166,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;
@@ -184,6 +225,8 @@ export class Messaging {
   readonly #obligations: Obligation[] = [];
   /** Every message admitted, by its number. */
   readonly #sentBy = new Map<number, Message>();
+  /** Outside participants connected in the attempt, released ones included, whose keys stay taken. */
+  readonly #outside = new Map<AgentKey, Outside>();
   #closed = false;
 
   constructor(host: MessagingHost, limits: MessageLimits = MESSAGE_LIMITS) {
@@ -201,7 +244,10 @@ export class Messaging {
    * Grants a route in `scope`, atomically: anything invalid rejects with nothing granted. Granting
    * the same route again does nothing; another route over an open pair rejects.
    */
-  grant(ends: RouteEnds, options: { purpose: unknown; maxMessages?: unknown; scope: Scope }): void {
+  grant(
+    ends: RouteEnds,
+    options: { purpose: unknown; maxMessages?: unknown; timeoutMs?: unknown; scope: Scope },
+  ): void {
     const { scope } = options;
     if (this.#closed || scope.state !== "open")
       throw new Error("routes are granted only while a scope is open");
@@ -217,7 +263,14 @@ export class Messaging {
     const pairs = directions(ends);
     for (const [from, to] of pairs) {
       if (from === to) throw new Error(`a route from ${from} to itself is not allowed`);
+      if (this.#outside.has(from) && this.#outside.has(to))
+        throw new Error(`${from} and ${to} are both outside the run: nothing would run`);
       for (const key of [from, to]) {
+        const outside = this.#outside.get(key);
+        if (outside) {
+          if (outside.released) throw new Error(`${key} has been released`);
+          continue;
+        }
         const agent = this.#host.agent(key);
         if (!agent) throw new Error(`${key} is not an agent this workflow opened`);
         if (agent.caller)
@@ -225,12 +278,30 @@ export class Messaging {
         if (agent.state === "stopped") throw new Error(`${key} has stopped`);
       }
     }
+    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",
+        );
+    }
     const open = pairs.map(([from, to]) => this.#open(from, to));
     if (open.some(Boolean)) {
       if (
         open.every(
           (route) =>
-            route && sameGrant(route, ends, purpose, requested as number | undefined, scope),
+            route &&
+            sameGrant(
+              route,
+              ends,
+              purpose,
+              requested as number | undefined,
+              timeoutMs as number | undefined,
+              scope,
+            ),
         ) &&
         new Set(open).size === 1
       )
@@ -248,6 +319,7 @@ export class Messaging {
       maxMessages,
       ...(asked !== undefined && asked > maxMessages ? { asked } : {}),
       ...(asked === undefined ? {} : { requested: asked }),
+      ...(timeoutMs === undefined ? {} : { timeoutMs: timeoutMs as number }),
       scope,
       count: 0,
       open: true,
@@ -263,9 +335,242 @@ export class Messaging {
       purpose,
       maxMessages,
       ...(route.asked === undefined ? {} : { asked: route.asked }),
+      ...(route.timeoutMs === undefined ? {} : { timeoutMs: route.timeoutMs }),
       ...(scope.stage === undefined ? {} : { stage: scope.stage }),
     });
-    for (const agent of new Set(pairs.flat())) this.#host.changed(agent);
+    for (const agent of new Set(pairs.flat())) {
+      if (!this.#outside.has(agent)) this.#host.changed(agent);
+    }
+  }
+
+  // Outside participants
+
+  /**
+   * Connects a participant outside the run under `key`, which the runner has checked no agent
+   * holds and is not reserved. A key connected before in the attempt, released or not, rejects.
+   */
+  connect(key: AgentKey, labels?: JsonObject, to?: "code"): void {
+    if (this.#closed) throw new Error("participants connect only while the attempt runs");
+    if (this.#outside.has(key)) throw new Error(`${key} is already connected`);
+    this.#outside.set(key, { key, released: false });
+    void this.#record({
+      kind: "participant-connected",
+      participant: key,
+      ...(labels === undefined ? {} : { labels }),
+      ...(to === undefined ? {} : { to }),
+    });
+  }
+
+  /** Writes `text` to a participant routed to the code, 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`);
+    if (this.#outside.get(key)?.released)
+      throw new Error(`${key} was released; nothing is posted to it`);
+    // Numbered within the attempt; `awf inbox` puts the attempt before it.
+    this.#posts += 1;
+    const id = `p${this.#posts}`;
+    await this.#host.record({ kind: "participant-post", participant: key, id, text });
+    return id;
+  }
+  #posts = 0;
+
+  /** Whether `key` is an outside participant's, connected in this attempt. */
+  isOutside(key: AgentKey): boolean {
+    return this.#outside.has(key);
+  }
+
+  /** Outside participants connected and not released, in the order connected. */
+  connected(): AgentKey[] {
+    return [...this.#outside.values()].filter((each) => !each.released).map((each) => each.key);
+  }
+
+  /**
+   * Releases an outside participant: its routes close and every question open to it ends
+   * `released`, its asker told. False when it was released already.
+   */
+  release(key: AgentKey, reason?: string): boolean {
+    const outside = this.#outside.get(key);
+    if (!outside || outside.released) return false;
+    outside.released = true;
+    const why = reason ? ` (${JSON.stringify(reason)})` : "";
+    for (const owed of this.#obligations) {
+      if (owed.owedBy === key && owed.state === "open") {
+        this.#end(owed, "released", `it was released${why} before replying`, { tell: true });
+      }
+    }
+    for (const route of this.#openRoutes()) {
+      if (directions(route.ends).some((pair) => pair.includes(key)))
+        this.#closeRoute(route, "released");
+    }
+    return true;
+  }
+
+  /** Questions open to outside participants now, oldest first. */
+  openQuestions(): OpenQuestion[] {
+    return this.#obligations
+      .filter((owed) => owed.state === "open" && this.#outside.has(owed.owedBy))
+      .map((owed) => ({
+        coordinator: owed.owedBy,
+        message: owed.request.n,
+        asker: owed.asker,
+        ...(owed.closes ? { closesAt: owed.closes.at } : {}),
+      }));
+  }
+
+  /**
+   * A holder answers a question, as `awf reply` does: the first answer wins. Refusals come in
+   * `PARTICIPANT_CODES`' order, a question's own state before its route's.
+   */
+  async holderReply(request: HolderRequest): Promise<HolderResult> {
+    if (this.#closed) return holderRefusal("ended", "the run has ended.");
+    const named =
+      request.to === undefined || request.coordinator !== undefined
+        ? undefined
+        : this.#obligations.find(
+            (owed) => owed.request.n === request.to && this.#outside.has(owed.owedBy),
+          )?.owedBy;
+    const as = this.#holderAs(request.coordinator ?? named);
+    if (as.kind === "refused") return as.result;
+    const { agent } = request;
+    if (!this.#host.agent(agent)) return unknownAgent(agent);
+    const asked = (coordinator: AgentKey) =>
+      this.#obligations.filter(
+        (owed) => owed.asker === agent && owed.owedBy === coordinator && owed.state === "open",
+      );
+    let owed: Obligation | undefined;
+    if (request.to === undefined) {
+      if (as.key === undefined) return as.ambiguous();
+      const open = asked(as.key);
+      if (open.length > 1)
+        return holderRefusal(
+          "ambiguous",
+          `${agent} has ${open.length} questions open to ${as.key}; name one with --to.`,
+          open.map((each) => String(each.request.n)),
+        );
+      owed = open[0];
+      if (!owed) return holderRefusal("expired", `${agent} has no question open to ${as.key}.`);
+    } else {
+      owed = this.#obligations.find(
+        (each) =>
+          each.request.n === request.to &&
+          each.asker === agent &&
+          each.state === "open" &&
+          (as.key === undefined ? this.#outside.has(each.owedBy) : each.owedBy === as.key),
+      );
+      if (!owed)
+        return holderRefusal(
+          "expired",
+          `${request.to} is not a question open from ${agent}${as.key === undefined ? "" : ` to ${as.key}`}.`,
+        );
+    }
+    const route = owed.request.route;
+    if (!route.open) return holderRefusal("closed", `the route with ${agent} has closed.`);
+    const bytes = Buffer.byteLength(request.text);
+    if (bytes > this.limits.bytes) return tooLarge(bytes, this.limits.bytes);
+    owed.state = "replied";
+    owed.endedAt = this.#host.now();
+    owed.cancelTimer?.();
+    if (owed.askerOperation.awaits === owed) owed.askerOperation.awaits = undefined;
+    const message = this.#admit(owed.owedBy, agent, request.text, bytes, route, owed);
+    const sent = this.#sent(message, request.via);
+    void this.#record({
+      kind: "request-ended",
+      message: owed.request.n,
+      owedBy: owed.owedBy,
+      asker: owed.asker,
+      end: "replied",
+      reply: message.n,
+    });
+    try {
+      await sent;
+    } finally {
+      this.#host.changed(agent);
+    }
+    return { code: "delivered", message: owed.request.n };
+  }
+
+  /** A holder messages an agent first, as `awf send` does, over a route the workflow allowed. */
+  async holderSend(request: HolderRequest): Promise<HolderResult> {
+    if (this.#closed || this.attempt.state !== "open")
+      return holderRefusal("ended", "the workflow has returned; it takes no new messages.");
+    const as = this.#holderAs(request.coordinator);
+    if (as.kind === "refused") return as.result;
+    const { agent } = request;
+    const view = this.#host.agent(agent);
+    if (!view) return unknownAgent(agent);
+    if (as.key === undefined) return as.ambiguous();
+    const from = as.key;
+    const initiating = this.#routes.get(pairKey(from, agent)) ?? [];
+    if (initiating.length === 0)
+      return holderRefusal("no-route", `the workflow allows no route from ${from} to ${agent}.`);
+    if (view.state === "stopped")
+      return holderRefusal(
+        "stopped",
+        `${agent} has stopped${view.reason ? ` (${JSON.stringify(view.reason)})` : ""}.`,
+      );
+    const route = initiating.find((each) => each.open);
+    if (route?.scope.state !== "open")
+      return holderRefusal(
+        "closed",
+        `the route to ${agent} has closed${route?.scope.stage ? `: its stage ${route.scope.stage} is finishing` : ""}.`,
+      );
+    const bytes = Buffer.byteLength(request.text);
+    if (bytes > this.limits.bytes) return tooLarge(bytes, this.limits.bytes);
+    if (route.count + 1 > route.maxMessages)
+      return holderRefusal(
+        "limit",
+        `${route.maxMessages} messages with ${agent}, this route's limit for the attempt.`,
+      );
+    const unread = this.#unread(agent);
+    if (unread >= this.limits.unread)
+      return holderRefusal(
+        "inbox-full",
+        `${agent} has ${unread} unread messages; try again later.`,
+      );
+    const message = this.#admit(from, agent, request.text, bytes, route);
+    try {
+      await this.#sent(message, request.via);
+    } finally {
+      this.#host.changed(agent);
+    }
+    return { code: "delivered", message: message.n };
+  }
+
+  /**
+   * The outside participant a holder speaks as: `--as`, or the only one connected. Undefined when
+   * several are: `ambiguous` once the agent is known, unless a `--to` names the question.
+   */
+  #holderAs(
+    key: AgentKey | undefined,
+  ):
+    | { kind: "refused"; result: HolderResult }
+    | { kind: "ok"; key: AgentKey | undefined; ambiguous: () => HolderResult } {
+    const connected = this.connected();
+    const ambiguous = () =>
+      holderRefusal(
+        "ambiguous",
+        `the workflow connects ${connected.length} coordinators; say which with --as.`,
+        connected,
+      );
+    if (key !== undefined && !connected.includes(key))
+      return {
+        kind: "refused",
+        result: holderRefusal(
+          "no-participant",
+          `no coordinator ${key} is connected${this.#outside.has(key) ? ": it was released" : ""}.`,
+        ),
+      };
+    if (connected.length === 0)
+      return {
+        kind: "refused",
+        result: holderRefusal("no-participant", "the run has no coordinator connected."),
+      };
+    return {
+      kind: "ok",
+      key: key ?? (connected.length === 1 ? connected[0] : undefined),
+      ambiguous,
+    };
   }
 
   /**
@@ -330,13 +635,15 @@ export class Messaging {
     this.#current.set(info.agent, operation);
   }
 
-  /** A message operation's deadline moved later, and with it any wait it has no `--timeout` for. */
+  /** An operation's deadline moved later, and with it any wait on an agent it has no `--timeout` for. */
   extended(id: string, deadline: number): void {
     const operation = this.#operations.get(id);
-    if (!operation || deadline <= operation.deadline) return;
+    if (!operation || deadline <= (operation.deadline ?? Infinity)) return;
     operation.deadline = deadline;
     const waited = operation.awaits;
-    if (waited?.state === "open" && !waited.timed) waited.until = deadline;
+    // A wait on an outside participant is not bounded by the deadline at all.
+    if (waited?.state === "open" && !waited.timed && !this.#outside.has(waited.owedBy))
+      waited.until = deadline;
   }
 
   /**
@@ -351,10 +658,15 @@ export class Messaging {
     const waited = operation.awaits;
     operation.awaits = undefined;
     if (waited?.state === "open") {
+      // On an outside participant, the asker timing out or being cancelled is `cancelled`; an
+      // attempt's end closes it `attempt-ended` before its operations stop.
+      const cut = this.#outside.has(waited.owedBy) && (how === "timed-out" || how === "cancelled");
       this.#end(
         waited,
-        waited.request.shown ? "released" : "withdrawn",
-        `${operation.agent} finished first`,
+        cut ? "cancelled" : waited.request.shown ? "released" : "withdrawn",
+        cut
+          ? `${operation.agent}'s operation ${how === "timed-out" ? "timed out" : "was cancelled"}`
+          : `${operation.agent} finished first`,
       );
     }
     // An answer accepted but not yet shown is withdrawn with it.
@@ -370,10 +682,18 @@ export class Messaging {
     }
   }
 
-  /** The answer this operation awaits, while it does. */
-  awaiting(id: string): { peer: AgentKey; until: number } | undefined {
+  /**
+   * The answer this operation awaits, while it does; `outside` when an outside participant owes it,
+   * whose wait its deadline does not count.
+   */
+  awaiting(id: string): { peer: AgentKey; until?: number; outside?: true } | undefined {
     const waited = this.#operations.get(id)?.awaits;
-    return waited?.state === "open" ? { peer: waited.owedBy, until: waited.until } : undefined;
+    if (waited?.state !== "open") return undefined;
+    return {
+      peer: waited.owedBy,
+      ...(waited.until === undefined ? {} : { until: waited.until }),
+      ...(this.#outside.has(waited.owedBy) ? { outside: true as const } : {}),
+    };
   }
 
   /** The operation open on this agent, if any. */
@@ -382,8 +702,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,
@@ -391,11 +711,11 @@ export class Messaging {
     command: "result" | "waiting",
   ):
     | { kind: "refused"; code: "owes-reply" | "no-result"; error: string }
-    | { kind: "awaiting"; peer: AgentKey; until: number; notice: string }
+    | { kind: "awaiting"; peer: AgentKey; until?: number; notice: string }
     | 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 {
@@ -413,8 +733,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;
@@ -422,8 +742,8 @@ export class Messaging {
       return {
         kind: "awaiting",
         peer: waited.owedBy,
-        until: waited.until,
-        notice: `you already await ${waited.owedBy}'s reply, until ${clock(waited.until, this.#host.now())}. End your turn, or finish with ${wf} result ${id}.`,
+        ...(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 ${wfa} result ${id}.`,
       };
     }
     return null;
@@ -436,7 +756,7 @@ export class Messaging {
     if (checked.kind === "refused") return this.#refused(from, request, "send", checked);
     const { operation, route, bytes } = checked;
     const message = this.#admit(from, request.peer, request.text, bytes, route);
-    const until = request.awaitReply ? this.#ask(message, operation, request.timeoutMs) : undefined;
+    const asked = request.awaitReply ? this.#ask(message, operation, request.timeoutMs) : undefined;
     // Admitted whatever the record says: its recipient is woken even if the write fails.
     try {
       await this.#sent(message, operation);
@@ -446,8 +766,8 @@ export class Messaging {
     return {
       kind: "sent",
       message: message.n,
-      ...(until === undefined ? {} : { until }),
-      notice: this.#sentNotice(request.peer, operation, until),
+      ...(asked?.until === undefined ? {} : { until: asked.until }),
+      notice: this.#sentNotice(request.peer, operation, asked),
     };
   }
 
@@ -462,7 +782,9 @@ export class Messaging {
     owed.owingOperation?.owes.delete(owed);
     if (owed.askerOperation.awaits === owed) owed.askerOperation.awaits = undefined;
     const message = this.#admit(from, owed.asker, request.text, bytes, owed.request.route, owed);
-    const until = request.awaitReply ? this.#ask(message, operation, request.timeoutMs) : undefined;
+    const asking = request.awaitReply
+      ? this.#ask(message, operation, request.timeoutMs)
+      : undefined;
     // Its line first, then the question's end, in the log's order; the end is written either way.
     const sent = this.#sent(message, operation);
     void this.#record({
@@ -478,11 +800,11 @@ export class Messaging {
     } finally {
       this.#host.changed(owed.asker);
     }
-    const asked = until === undefined ? "" : ` ${this.#awaitNotice(operation, until)}`;
+    const asked = asking ? ` ${this.#awaitNotice(operation, asking)}` : "";
     return {
       kind: "sent",
       message: message.n,
-      ...(until === undefined ? {} : { until }),
+      ...(asking?.until === undefined ? {} : { until: asking.until }),
       notice: `replied to ${request.peer}.${asked}`,
     };
   }
@@ -493,7 +815,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;
@@ -504,16 +826,16 @@ 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.#host.agent(peer);
+    const agent = this.#outside.has(peer) ? undefined : this.#host.agent(peer);
     if (agent?.state === "stopped")
       return refuse(
         "peer-stopped",
@@ -567,7 +889,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;
@@ -576,7 +898,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);
@@ -584,7 +906,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;
@@ -628,7 +950,7 @@ export class Messaging {
     /** 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);
+    const wfa = this.#host.launcher(from);
     if (operation.awaits?.state === "open") {
       return refuse(
         "awaiting",
@@ -662,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.`,
         );
       }
@@ -712,65 +1034,93 @@ export class Messaging {
     };
     // An answer's room was reserved when it was asked.
     if (!answers) route.count += 1;
-    this.#inbox(to).push(message);
+    // An outside participant reads the run log: a message to it is shown once recorded.
+    if (this.#outside.has(to)) message.shown = true;
+    else this.#inbox(to).push(message);
     this.#sentBy.set(message.n, message);
     return message;
   }
 
   /** Makes `message` a question its recipient owes an answer to, and its sender's wait. */
-  #ask(message: Message, operation: Operation, timeoutMs?: number): number {
+  #ask(message: Message, operation: Operation, timeoutMs?: number): { until?: number } {
     message.route.count += 1;
     const now = this.#host.now();
-    const until = Math.min(
-      operation.deadline,
-      timeoutMs === undefined ? Infinity : now + timeoutMs,
+    const routeMs = this.#outside.has(message.to) ? message.route.timeoutMs : undefined;
+    // The route's limit, or the asker's own when shorter: the shorter wins.
+    const limit =
+      routeMs !== undefined && (timeoutMs === undefined || routeMs <= timeoutMs)
+        ? { by: "route" as const, ms: routeMs }
+        : timeoutMs === undefined
+          ? undefined
+          : { by: "own" as const, ms: timeoutMs };
+    const outside = this.#outside.has(message.to);
+    const limitAt = limit ? now + limit.ms : Infinity;
+    // Waiting on an outside participant is not work: its deadline does not cut the wait, though
+    // the deadlines around it do.
+    const waitEnd = Math.min(
+      outside ? (operation.ceiling ?? Infinity) : (operation.deadline ?? Infinity),
+      limitAt,
     );
+    const until = Number.isFinite(waitEnd) ? waitEnd : undefined;
     const obligation: Obligation = {
       request: message,
       asker: message.from,
       askerOperation: operation,
       owedBy: message.to,
-      until,
-      timed: until < operation.deadline,
+      ...(until === undefined ? {} : { until }),
+      timed: limitAt < (outside ? Infinity : (operation.deadline ?? Infinity)),
+      ...(limit && outside ? { closes: { ...limit, at: limitAt } } : {}),
       state: "open",
     };
     message.asks = obligation;
     operation.awaits = obligation;
     this.#obligations.push(obligation);
     // Only `--timeout` fails a question: reaching the operation's own deadline times it out.
-    if (obligation.timed) {
-      obligation.cancelTimer = this.#host.schedule(until, () => {
+    // Only its limit closes it; a deadline ends the operation, and the wait with it.
+    const closesAt = obligation.timed ? limitAt : undefined;
+    if (closesAt !== undefined) {
+      obligation.cancelTimer = this.#host.schedule(closesAt, () => {
         if (obligation.state === "open") {
           this.#end(
             obligation,
             "timed-out",
-            `your --timeout passed at ${clock(until, this.#host.now())}`,
+            obligation.closes?.by === "route"
+              ? `the question closed unanswered after ${duration(obligation.closes.ms)}`
+              : `your --timeout passed at ${clock(closesAt, this.#host.now())}`,
           );
         }
       });
     }
-    return until;
+    return until === undefined ? {} : { until };
   }
 
-  /** Durable before `wf send` returns: a failed write rejects, and `wf` says it may have been queued. */
-  async #sent(message: Message, operation: Operation): Promise<void> {
+  /**
+   * 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.
+   */
+  async #sent(message: Message, by: Operation | OutsideVia): Promise<void> {
+    const asks = message.asks;
+    // To an outside participant, when it closes unanswered: its limit, not the asker's wait.
+    const until = asks && this.#outside.has(asks.owedBy) ? asks.closes?.at : asks?.until;
     await this.#host.record({
       kind: "message-sent",
       message: message.n,
       from: message.from,
       to: message.to,
-      operationId: operation.id,
+      ...(typeof by === "string" ? { via: by } : { operationId: by.id }),
       text: message.text,
       bytes: message.bytes,
-      ...(message.asks
-        ? { awaitsReply: { until: new Date(message.asks.until).toISOString() } }
+      ...(asks
+        ? { awaitsReply: until === undefined ? {} : { until: new Date(until).toISOString() } }
         : {}),
       ...(message.answers ? { replyTo: message.answers.request.n } : {}),
     });
   }
 
-  #sentNotice(peer: AgentKey, operation: Operation, until?: number): string {
-    if (until !== undefined) return `sent to ${peer}. ${this.#awaitNotice(operation, until)}`;
+  #sentNotice(peer: AgentKey, operation: Operation, asked?: { until?: number }): string {
+    if (asked) return `sent to ${peer}. ${this.#awaitNotice(operation, asked)}`;
+    if (this.#outside.has(peer)) return `sent to ${peer}, outside the run; it reads it from there.`;
     const state = this.#host.agent(peer)?.state;
     const when =
       this.#current.get(peer)?.awaits?.state === "open"
@@ -783,14 +1133,14 @@ export class Messaging {
     return `sent to ${peer}; ${when}.`;
   }
 
-  #awaitNotice(operation: Operation, until: number): string {
-    const wf = this.#host.launcher(operation.agent);
+  #awaitNotice(operation: Operation, { until }: { until?: number }): string {
+    const wfa = this.#host.launcher(operation.agent);
     return [
-      `Its reply starts your next turn (deadline ${clock(until, this.#host.now())}).`,
+      `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");
@@ -896,14 +1246,13 @@ export class Messaging {
    */
   #deadlineFor(operation: Operation): number | undefined {
     if (operation.kind !== "message") return undefined;
+    const own = operation.deadline ?? Infinity;
+    // An asker with no deadline adds none.
     const wanted = Math.min(
-      operation.ceiling,
-      Math.max(
-        operation.deadline,
-        ...[...operation.owes].map((owed) => owed.askerOperation.deadline),
-      ),
+      operation.ceiling ?? Infinity,
+      Math.max(own, ...[...operation.owes].map((owed) => owed.askerOperation.deadline ?? own)),
     );
-    return wanted > operation.deadline ? wanted : undefined;
+    return wanted > own && Number.isFinite(wanted) ? wanted : undefined;
   }
 
   /** What the harness confirmed of a delivery: the model read it, or nothing says it did. */
@@ -935,7 +1284,12 @@ export class Messaging {
       return { kind: operation?.kind === "message" ? "settle" : "check-in" };
     if (this.#pending(operation) === "continues") return { kind: "continue" };
     const waited = operation.awaits;
-    if (waited?.state === "open") return { kind: "wait", peer: waited.owedBy, until: waited.until };
+    if (waited?.state === "open")
+      return {
+        kind: "wait",
+        peer: waited.owedBy,
+        ...(waited.until === undefined ? {} : { until: waited.until }),
+      };
     // Each question gets one reminder; a turn that ends still owing one it was reminded of fails it.
     for (const owed of [...operation.owes]) {
       if (owed.reminded) this.#end(owed, "failed", "it did not reply after a reminder");
@@ -969,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);
@@ -1012,11 +1366,19 @@ export class Messaging {
   peers(agent: AgentKey): {
     peers: PeerView[];
     owes: AgentKey[];
-    awaits?: { peer: AgentKey; until: number };
+    awaits?: { peer: AgentKey; until?: number };
     text: string;
   } {
     const peers = this.#routesOf(agent, true).map((route): PeerView => {
       const peer = peerOf(route, agent);
+      if (this.#outside.has(peer))
+        return {
+          peer,
+          can: this.#can(route, agent),
+          state: "outside",
+          queued: 0,
+          purpose: route.purpose,
+        };
       const view = this.#host.agent(peer);
       const waited = this.#current.get(peer)?.awaits;
       const awaiting = waited?.state === "open" ? waited.owedBy : undefined;
@@ -1043,7 +1405,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());
@@ -1081,7 +1443,7 @@ export class Messaging {
     this.#closed = true;
     for (const owed of this.#obligations) {
       if (owed.state === "open")
-        this.#end(owed, "failed", "the attempt ended", {
+        this.#end(owed, "attempt-ended", "the attempt ended", {
           undelivered: "attempt-ended",
           tell: false,
         });
@@ -1114,7 +1476,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())]
@@ -1146,13 +1508,20 @@ export class Messaging {
     return [...operation.owes].filter((each) => each.state === "open").map((each) => each.asker);
   }
 
-  #standing(agent: AgentKey): { owes: AgentKey[]; awaits?: { peer: AgentKey; until: number } } {
+  #standing(agent: AgentKey): { owes: AgentKey[]; awaits?: { peer: AgentKey; until?: number } } {
     const operation = this.#current.get(agent);
     if (!operation) return { owes: [] };
     const waited = operation.awaits?.state === "open" ? operation.awaits : undefined;
     return {
       owes: this.#owes(operation),
-      ...(waited ? { awaits: { peer: waited.owedBy, until: waited.until } } : {}),
+      ...(waited
+        ? {
+            awaits: {
+              peer: waited.owedBy,
+              ...(waited.until === undefined ? {} : { until: waited.until }),
+            },
+          }
+        : {}),
     };
   }
 
@@ -1185,7 +1554,8 @@ export class Messaging {
     owed: Obligation,
     end: Exclude<RequestEnd, "replied">,
     reason: string,
-    options: { gone?: true; undelivered?: UndeliveredReason; tell?: false } = {},
+    /** `tell`: whether its asker is told, beside a failure or a timeout, which always are. */
+    options: { gone?: true; undelivered?: UndeliveredReason; tell?: boolean } = {},
   ): void {
     if (owed.state !== "open") return;
     owed.state = end;
@@ -1219,7 +1589,8 @@ export class Messaging {
     });
     const operation = owed.askerOperation;
     if (operation.awaits === owed) operation.awaits = undefined;
-    if (options.tell !== false && !operation.ended && (end === "failed" || end === "timed-out")) {
+    const told = options.tell ?? (end === "failed" || end === "timed-out");
+    if (told && !operation.ended) {
       this.#inbox(owed.asker).push({ kind: "no-reply", for: operation, from: owed.owedBy, reason });
       this.#host.changed(owed.asker);
     }
@@ -1265,7 +1636,10 @@ export class Messaging {
     }
   }
 
-  #closeRoute(route: Route, reason: "stage-ended" | "agent-stopped" | "attempt-ended"): void {
+  #closeRoute(
+    route: Route,
+    reason: "stage-ended" | "agent-stopped" | "released" | "attempt-ended",
+  ): void {
     if (!route.open) return;
     route.open = false;
     route.closed = reason;
@@ -1301,3 +1675,22 @@ export class Messaging {
 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 {
+  return { code, error, ...(choices ? { choices } : {}) };
+}
+
+function unknownAgent(agent: AgentKey): HolderResult {
+  return holderRefusal("unknown-agent", `the run has no agent ${agent}.`);
+}
+
+function tooLarge(bytes: number, limit: number): HolderResult {
+  return holderRefusal(
+    "too-large",
+    `${Math.ceil(bytes / 1024)} KB; the limit is ${limit / 1024} KB. Put it in a file and send its path.`,
+  );
+}