@agentswf/engine 0.1.0-beta.5 → 0.1.0

package/src/jsonl.ts

@@ -1,16 +1,20 @@
 import { open, readFile } from "node:fs/promises";
 import { isCode } from "./files";
 
-const appendQueues = new Map<string, Promise<void>>();
+const queues = new Map<string, Promise<void>>();
 
-export async function appendLine(path: string, line: string): Promise<void> {
-  const previous = appendQueues.get(path) ?? Promise.resolve();
-  const current = previous.catch(() => undefined).then(() => appendCompleteLine(path, line));
-  appendQueues.set(path, current);
+export function appendLine(path: string, line: string): Promise<void> {
+  return queued(path, () => appendCompleteLine(path, line));
+}
+
+/** Runs `work` once every earlier write queued on `path` has settled, failed or not. */
+export async function queued(path: string, work: () => Promise<void>): Promise<void> {
+  const current = (queues.get(path) ?? Promise.resolve()).catch(() => undefined).then(work);
+  queues.set(path, current);
   try {
     await current;
   } finally {
-    if (appendQueues.get(path) === current) appendQueues.delete(path);
+    if (queues.get(path) === current) queues.delete(path);
   }
 }
 

package/src/keep-alive.ts

@@ -24,27 +24,15 @@ export function asTimeoutHandler<T>(fn: () => T): T {
   return inHandler.run(true, fn);
 }
 
-/**
- * `keepAlive` as an open gave it, checked: what a typed caller can't get wrong, a plain one can.
- * Its deprecated `timeoutMs` is reported, and refused beside `window`.
- */
-export function checkedKeepAlive(key: string, given: unknown, deprecated: () => void): KeepAlive {
+/** `keepAlive` as an open gave it, checked: a plain caller can get wrong what a typed one can't. */
+export function checkedKeepAlive(key: string, given: unknown): KeepAlive {
   if (typeof given !== "object" || given === null)
     throw new Error(`agent ${key}: keepAlive is { window?, onTimeout? }`);
-  const { window, timeoutMs, onTimeout } = given as Record<string, unknown>;
-  let windowMs: number | undefined;
-  if (window != null) {
-    if (timeoutMs != null)
-      throw new Error(
-        `agent ${key}: keepAlive's window is given alone: timeoutMs is its deprecated form`,
-      );
-    windowMs = positiveDurationMilliseconds(window, `agent ${key}: keepAlive's window`);
-  } else if (timeoutMs != null) {
-    if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0)
-      throw new Error(`agent ${key}: keepAlive's timeoutMs is a positive number of milliseconds`);
-    deprecated();
-    windowMs = timeoutMs;
-  }
+  const { window, onTimeout } = given as Record<string, unknown>;
+  const windowMs =
+    window == null
+      ? undefined
+      : positiveDurationMilliseconds(window, `agent ${key}: keepAlive's window`);
   if (onTimeout !== undefined && typeof onTimeout !== "function")
     throw new Error(`agent ${key}: keepAlive's onTimeout is a function`);
   // A copy: a later change to the caller's object would skip this check.

package/src/logs-command.ts

@@ -1,22 +1,21 @@
 import { homedir } from "node:os";
 import type { LogEventJson, LogsJson, RouteEnds, RunLogLine } from "@agentswf/contract/records";
 import type { JsonObject } from "@agentswf/contract/workflow";
-import { formatDuration, parseWait } from "./duration";
+import { duration } from "./accounting/format";
+import { command, type Out, parsePlace, type ReadPlace, shellLine } from "./command-line";
+import { parseWait } from "./duration";
 import { messageOf } from "./errors";
+import { exists } from "./files";
 import help from "./help/logs.txt" with { type: "text" };
+import { screenFile } from "./ops";
+import { asksJson, printRefusal, refusalLine } from "./refusals";
 import {
-  clockTime,
-  command,
   continueOf,
   currentStage,
   failed,
-  masked,
+  MAX_WAIT_SECONDS,
   nextLogs,
-  type Out,
-  parsePlace,
-  type ReadPlace,
-  said,
-  shellLine,
+  POLL_MS,
   span,
   stateWord,
 } from "./run-commands";
@@ -30,11 +29,16 @@ import {
   type FileCache,
   type ReadEvent,
   readRun,
+  START,
   timeOf,
 } from "./run-read";
-import { findRun, findRunByRef, type RunStatus } from "./run-state";
+import { checkRunEngine, findRun, findRunByRef, type RunStatus } from "./run-state";
+import { clockTime, masked, said } from "./run-text";
 import { describeActivity } from "./run-view";
 
+/** `awf logs --json`'s `"v"`, which its refusals carry too. */
+export const LOGS_V = 1 satisfies LogsJson["v"];
+
 export const logsUsage = help.trimEnd();
 
 const DEFAULT_LIMIT = 40;
@@ -43,10 +47,8 @@ const DEFAULT_LIMIT = 40;
  * result or a message whole, short of a dumped file. `@{handle}` gives it whole.
  */
 const PAGE_TEXT = 50_000;
-const MAX_WAIT_SECONDS = 300;
 /** After a first new event, how long to wait for the rest of its burst. */
 const SETTLE_MS = 1_000;
-const POLL_MS = 1_000;
 
 type LogsOptions = {
   ref?: string;
@@ -74,10 +76,6 @@ export async function logsCommand(
   clock: LogsClock = REAL_CLOCK,
   home: string = homedir(),
 ): Promise<number> {
-  if (argv.includes("-h") || argv.includes("--help")) {
-    out.stdout(logsUsage);
-    return 0;
-  }
   let place: ReadPlace;
   let json: boolean;
   let options: LogsOptions;
@@ -85,10 +83,10 @@ export async function logsCommand(
     const parsed = parsePlace(argv, shellCwd);
     place = parsed.place;
     json = parsed.json;
-    options = parseLogs(parsed.rest, (line) => out.stderr(line));
+    options = parseLogs(parsed.rest);
     if (options.follow && json) throw new Error("--follow is for reading; --json takes --wait");
   } catch (error) {
-    out.stderr(`awf: ${messageOf(error)}\n\n${logsUsage}`);
+    printRefusal(out, { json: asksJson(argv), v: LOGS_V }, error, "usage", logsUsage);
     return 2;
   }
   try {
@@ -96,6 +94,7 @@ export async function logsCommand(
       options.ref === undefined
         ? await findRun(place.runRoot, undefined)
         : { status: await findRunByRef(options.ref, place, home), alsoRunning: [] };
+    await checkRunEngine(status, home);
     const again = shellLine(command(place, "awf", "logs", status.ref));
     let after: Cursor | undefined;
     if (options.after !== undefined) {
@@ -107,22 +106,29 @@ export async function logsCommand(
     }
     const read = new Reader(status, after, clock, options.limit * 2, json);
     // Lines are numbered by their place in the file, past any that were skipped.
-    if (after && after.log > ((await read.next()).log.lines.at(-1)?.number ?? 0)) {
-      throw new DoesNotFit(`cursor ${options.after} does not fit this run; start again: ${again}`);
+    if (after) {
+      const { log } = await read.next();
+      const past = after.run > log.runLines && log.unreadSessions === undefined;
+      if (after.log > (log.lines.at(-1)?.number ?? 0) || past) {
+        throw new DoesNotFit(
+          `cursor ${options.after} does not fit this run; start again: ${again}`,
+        );
+      }
     }
     if (options.handle !== undefined) return await oneEvent(status, options, json, out, again);
     if (options.follow) return await follow(read, options, place, out, clock);
     return await page(read, alsoRunning, options, place, json, out, clock);
   } catch (error) {
     if (error instanceof DoesNotFit) {
+      if (json) out.stdout(refusalLine(LOGS_V, "cursor", error.message));
       out.stderr(error.message);
       return 1;
     }
-    return failed(error, place, out, messageOf(error));
+    return failed(error, place, out, messageOf(error), { json, v: LOGS_V });
   }
 }
 
-function parseLogs(rest: readonly string[], deprecated: (line: string) => void): LogsOptions {
+function parseLogs(rest: readonly string[]): LogsOptions {
   const options: LogsOptions = {
     limit: DEFAULT_LIMIT,
     waitSeconds: 0,
@@ -147,7 +153,7 @@ function parseLogs(rest: readonly string[], deprecated: (line: string) => void):
         throw new Error("--limit needs a whole number");
       options.limit = limit;
     } else if (arg === "--wait") {
-      options.waitSeconds = parseWait(value(), MAX_WAIT_SECONDS, deprecated);
+      options.waitSeconds = parseWait(value(), MAX_WAIT_SECONDS);
       waitGiven = true;
     } else if (arg === "--follow") options.follow = true;
     else if (arg === "--full") options.full = true;
@@ -224,8 +230,9 @@ function operationPlaces(lines: readonly { line: RunLogLine }[]): Places {
 
 function agentOf(event: ReadEvent, places: Places): string | undefined {
   if (event.source === "activity") return event.agent;
+  if (event.source === "run") return event.line.agent;
   if ("agent" in event.line && event.line.agent) return event.line.agent;
-  // A session a headless turn named names its operation, and so its agent.
+  // A line that names only its operation, such as a message's delivery, is its operation's agent's.
   return "operationId" in event.line && event.line.operationId
     ? places.agent.get(event.line.operationId)
     : undefined;
@@ -235,12 +242,15 @@ function stageOf(event: ReadEvent, places: Places): string | undefined {
   if (event.source === "activity") {
     return event.operation ? places.stage.get(event.operation) : undefined;
   }
+  if (event.source === "run") {
+    return event.line.operation ? places.stage.get(event.line.operation) : undefined;
+  }
   return "stage" in event.line ? event.line.stage : undefined;
 }
 
 /** The agents a messaging line is between, so `--agent` follows it from either side. */
 function sidesOf(event: ReadEvent): readonly string[] {
-  if (event.source === "activity") return [];
+  if (event.source !== "log") return [];
   const { line } = event;
   switch (line.kind) {
     case "route-opened":
@@ -258,14 +268,32 @@ function sidesOf(event: ReadEvent): readonly string[] {
   }
 }
 
+/**
+ * The `run.jsonl` lines text leaves out: an agent's first session, which its opening and first turn
+ * already stand for, unless it is a fork's, made apart from any turn.
+ */
+function quietSessions(read: Read): Set<number> {
+  const forked = new Set<string>();
+  for (const { line } of read.log.lines) if (line.kind === "agent-forked") forked.add(line.agent);
+  const quiet = new Set<number>();
+  const seen = new Set<string>();
+  for (const { number, line } of read.log.named) {
+    if (!seen.has(line.agent) && !forked.has(line.agent)) quiet.add(number);
+    seen.add(line.agent);
+  }
+  return quiet;
+}
+
 function kept(read: Read, options: LogsOptions, json = false) {
   const stages = operationPlaces(read.log.lines);
+  const quiet = json ? new Set<number>() : quietSessions(read);
   const events = read.events.filter(
     (event) =>
+      !(event.source === "run" && quiet.has(decodeHandleLine(event.handle))) &&
       // A call that has ended shows on its end's line, with its input; `--json` keeps both.
       !(
         !json &&
-        event.source !== "activity" &&
+        event.source === "log" &&
         event.line.kind === "tool-called" &&
         stages.calls.get(event.line.call)?.ended
       ) &&
@@ -277,6 +305,11 @@ function kept(read: Read, options: LogsOptions, json = false) {
   return { events, stages };
 }
 
+function decodeHandleLine(handle: string): number {
+  const decoded = decodeHandle(handle);
+  return decoded?.kind === "run" ? decoded.line : 0;
+}
+
 function sameLine(a: ReadEvent, b: ReadEvent): boolean {
   const first = decodeHandle(a.handle);
   const second = decodeHandle(b.handle);
@@ -344,6 +377,7 @@ async function page(
     }
   }
   const stage = currentStage(status, read.log.lines);
+  const screens = await keptScreens(status.run.dir, shown);
   const filters = [
     ...(options.agent ? ["--agent", options.agent] : []),
     ...(options.stage ? ["--stage", options.stage] : []),
@@ -355,7 +389,7 @@ async function page(
   if (json) {
     const { started, ended } = span(status, clock.now());
     const document: LogsJson = {
-      v: 1,
+      v: LOGS_V,
       run: {
         ref: status.ref,
         state: status.state,
@@ -364,7 +398,7 @@ async function page(
         ambiguous: alsoRunning.length > 0,
         ...(status.state !== "running" && ended !== undefined ? { duration: ended - started } : {}),
       },
-      events: shown.map((event) => publish(event, stages, PAGE_TEXT)),
+      events: shown.map((event) => publish(event, stages, screens, PAGE_TEXT)),
       cursor: encodeCursor(cursor),
       more: { ...(older ? { older: true } : {}), ...(newer ? { newer: true } : {}) },
       ...(next ? { next } : {}),
@@ -376,6 +410,11 @@ async function page(
   const lines: string[] = [
     header(status, stage, lastAt ? Date.parse(timeOf(lastAt.line)) : undefined),
   ];
+  if (read.log.unreadSessions !== undefined) {
+    lines.push(
+      `note: run.jsonl could not be read, so no agent's activity shows: ${said(read.log.unreadSessions)}`,
+    );
+  }
   if (alsoRunning.length > 0) {
     const count = alsoRunning.length + (status.state === "running" ? 1 : 0);
     lines.push(`note: ${count} runs running; also ${alsoRunning.join(", ")}`);
@@ -384,12 +423,12 @@ async function page(
     const of = options.agent ? ` for ${options.agent}` : "";
     // A cut read has more than any --limit reaches: paging from the start reads it all.
     const more = read.cut
-      ? `from the start: ${shellLine([...command(place, "awf", "logs", status.ref), ...filters, "--after", encodeCursor({ log: 0, files: {} })])}`
+      ? `from the start: ${shellLine([...command(place, "awf", "logs", status.ref), ...filters, "--after", encodeCursor(START)])}`
       : "raise --limit for more";
     const total = read.cut ? `the last ${events.length} read` : `${events.length}`;
     lines.push(`(showing ${shown.length} of ${total}${of}; ${more})`);
   }
-  lines.push(...shown.map((event) => describeEvent(event, stages)));
+  lines.push(...shown.map((event) => describeEvent(event, stages, screens)));
   lines.push(
     trailer(
       status,
@@ -418,7 +457,8 @@ async function follow(
     const { events, stages } = kept(read, options);
     // Without a cursor it starts from the last `--limit`, as a page would.
     const shown = first && !reader.from ? events.slice(-options.limit) : events;
-    for (const event of shown) out.stdout(describeEvent(event, stages));
+    const screens = await keptScreens(reader.status.run.dir, shown);
+    for (const event of shown) out.stdout(describeEvent(event, stages, screens));
     cursor = read.cursor;
     // A read that stopped short goes on at once.
     if (!read.more) {
@@ -445,34 +485,38 @@ async function oneEvent(
   const handle = decodeHandle(options.handle!);
   if (!handle) throw missing;
   // Read from where the handle points, and only its file.
+  const none = Number.MAX_SAFE_INTEGER;
   const read = await readRun(
     status.run.dir,
     status.run.record.cwd,
     handle.kind === "event"
-      ? { log: handle.line - 1, files: {} }
-      : { log: Number.MAX_SAFE_INTEGER, files: { [handle.file]: handle.offset } },
+      ? { log: handle.line - 1, run: none, files: {} }
+      : handle.kind === "run"
+        ? { log: none, run: handle.line - 1, files: {} }
+        : { log: none, run: none, files: { [handle.file]: handle.offset } },
     {
       ended: status.state !== "running",
       full: options.full || json,
-      only: handle.kind === "event" ? "" : handle.file,
+      only: handle.kind === "activity" ? handle.file : "",
     },
   );
   const stages = operationPlaces(read.log.lines);
   const event = read.events.find((each) => each.handle === encodeHandle(handle));
   if (!event) throw missing;
+  const screens = await keptScreens(status.run.dir, [event]);
   if (json) {
     const document: LogsJson = {
-      v: 1,
+      v: LOGS_V,
       run: { ref: status.ref, state: status.state, checked: status.checked },
-      events: [publish(event, stages)],
+      events: [publish(event, stages, screens)],
     };
     out.stdout(JSON.stringify(document, null, 2));
     return 0;
   }
-  const lines = [describeEvent(event, stages)];
+  const lines = [describeEvent(event, stages, screens)];
   if (options.full) {
     lines.unshift(
-      `(${event.source === "activity" ? "native text" : "the log's line"}; common credential shapes are masked)`,
+      `(${{ activity: "native text", log: "the log's line", run: "run.jsonl's line" }[event.source]}; common credential shapes are masked)`,
     );
     const text =
       event.source === "activity" ? event.text : JSON.stringify(masked(event.line), null, 2);
@@ -507,12 +551,17 @@ function trailer(
     return `run interrupted${go ? ` · continue: ${go}` : ""}`;
   }
   const { ended, started } = span(status, Date.now());
-  const took = ended === undefined ? "" : ` in ${formatDuration(ended - started)}`;
+  const took = ended === undefined ? "" : ` in ${duration(ended - started)}`;
   return `run ended: ${status.state}${took} · result: ${shellLine(command(place, "awf", "runs", status.ref))}`;
 }
 
 /** An event as `--json` publishes it: the line's own fields, or the activity, with its keys. */
-function publish(event: ReadEvent, stages: Places, limit = Number.POSITIVE_INFINITY): LogEventJson {
+function publish(
+  event: ReadEvent,
+  stages: Places,
+  screens: Screens,
+  limit = Number.POSITIVE_INFINITY,
+): LogEventJson {
   if (event.source === "activity") {
     const stage = event.operation ? stages.stage.get(event.operation) : undefined;
     return {
@@ -526,24 +575,60 @@ function publish(event: ReadEvent, stages: Places, limit = Number.POSITIVE_INFIN
       ...(event.text === undefined ? {} : { text: masked(event.text, limit) as string }),
     };
   }
+  if (event.source === "run") {
+    return { handle: event.handle, ...(masked(event.line, limit) as typeof event.line) };
+  }
   const { version: _version, ...fields } = event.line;
   return {
     handle: event.handle,
     at: event.at,
     ...(masked(fields, limit) as typeof fields),
     ...("operationId" in fields ? { operation: fields.operationId } : {}),
+    ...screenOf(event, screens),
   };
 }
 
-/** `@e216 09:27:02 fix  fixer  turn ended  answered  1m48s`. */
-function describeEvent(event: ReadEvent, stages: Places): string {
+/** The screens kept for the operations of the events shown, by operation id. */
+type Screens = ReadonlyMap<string, string>;
+
+/** A turn or compaction that ended without an answer, and the file its screen would be kept in. */
+function screenOf(event: ReadEvent, screens: Screens): { screen?: string } {
+  if (event.source !== "log") return {};
+  const { line } = event;
+  if (line.kind !== "turn" && line.kind !== "compact") return {};
+  const screen = screens.get(line.operationId);
+  return screen ? { screen } : {};
+}
+
+async function keptScreens(runDir: string, events: readonly ReadEvent[]): Promise<Screens> {
+  const screens = new Map<string, string>();
+  await Promise.all(
+    events.map(async (event) => {
+      if (event.source !== "log") return;
+      const { line } = event;
+      if (line.kind !== "turn" && line.kind !== "compact") return;
+      if (line.outcome === "answered" || line.outcome === "cancelled") return;
+      const file = screenFile(runDir, line.operationId);
+      if (await exists(file)) screens.set(line.operationId, file);
+    }),
+  );
+  return screens;
+}
+
+/** `@e216 09:27:02 fix  fixer  turn ended  answered  1m 48s`. */
+function describeEvent(event: ReadEvent, stages: Places, screens: Screens): string {
   const agent = agentOf(event, stages);
   const where = [stageOf(event, stages), agent && said(agent, 60)].filter(Boolean).join("  ");
   const what =
     event.source === "activity"
       ? describeActivity(event.activity)
-      : describeLine(event.line, stages);
-  return `@${event.handle} ${clockTime(event.at)} ${where ? `${where}  ` : ""}${what}`;
+      : event.source === "run"
+        ? `session ${event.line.harness} ${event.line.session}`
+        : describeLine(event.line, stages);
+  const { screen } = screenOf(event, screens);
+  return `@${event.handle} ${clockTime(event.at)} ${where ? `${where}  ` : ""}${what}${
+    screen ? `  screen: ${screen}` : ""
+  }`;
 }
 
 function describeLine(line: RunLogLine, places: Places): string {
@@ -565,12 +650,12 @@ function describeLine(line: RunLogLine, places: Places): string {
     case "compact": {
       const took =
         line.deliveredAt && line.settledAt
-          ? `  ${formatDuration(Date.parse(line.settledAt) - Date.parse(line.deliveredAt))}`
+          ? `  ${duration(Date.parse(line.settledAt) - Date.parse(line.deliveredAt))}`
           : "";
       return `${operation(line.kind)} ended  ${line.outcome}${took}`;
     }
-    case "session-known":
-      return `session ${line.session.harness} ${line.session.id}`;
+    case "sandbox-opened":
+      return `sandbox ${said(line.key, 60)} opened  ${line.provider}`;
     case "agent-opened":
       return `opened  ${line.harness}${line.caller ? "  (the calling session)" : ""}`;
     case "agent-stopped":
@@ -587,9 +672,7 @@ 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 ${formatDuration(line.timeoutMs)}`
+        line.timeoutMs === undefined ? "" : `, a question closes after ${duration(line.timeoutMs)}`
       }`;
     case "route-closed":
       return `route ${routeEnds(line)} closed  ${line.reason}`;
@@ -638,9 +721,7 @@ 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}  ${formatDuration(line.durationMs)}`,
+        line.durationMs < 1000 ? line.outcome : `${line.outcome}  ${duration(line.durationMs)}`,
         answered,
       );
     }

package/src/message-operation.ts

@@ -31,12 +31,14 @@ export async function superviseMessageOperation(options: {
   event?(event: LivenessEvent): void;
   phase?(phase: OperationPhase, reason?: string, until?: number): void;
   delivered?(at: number): void;
+  /** Keeps what its turn shows when it ends without an answer, before the turn is released. */
+  keepScreen?(turn: HarnessTurn): Promise<void>;
   policy?: LivenessPolicy;
   now?: () => number;
 }): Promise<SupervisedOutcome> {
   const now = options.now ?? Date.now;
   const policy = options.policy ?? DEFAULT_LIVENESS_POLICY;
-  const charges: number[] = [];
+  const reportedCosts: number[] = [];
   let sequence = 0;
   let deliveredAt: number | undefined;
   let stop: OperationStop | undefined;
@@ -63,7 +65,7 @@ export async function superviseMessageOperation(options: {
     kind,
     reason,
     cleanupUnresolved: false,
-    charges,
+    reportedCosts,
     ...(deliveredAt === undefined ? {} : { deliveredAt }),
     settledAt:
       kind === "timed-out"
@@ -139,7 +141,7 @@ export async function superviseMessageOperation(options: {
     void turn.settled.then(
       (value) => {
         outcome = value;
-        charges.push(...value.chargesUsd);
+        reportedCosts.push(...value.reportedCostsUsd);
         changed();
       },
       (error: unknown) => {
@@ -251,6 +253,7 @@ export async function superviseMessageOperation(options: {
   emit("releasing");
   if (turn) {
     const answered = result.kind === "answered";
+    if (!answered && result.kind !== "cancelled") await options.keepScreen?.(turn);
     const until = bound(answered);
     const release = await Promise.race([
       turn.release(stop?.reason ?? result.reason, until, { answered }).catch(() => undefined),

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 { formatDuration } 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 = {
@@ -444,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}.`);
@@ -459,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;
@@ -1085,7 +1087,7 @@ export class Messaging {
             obligation,
             "timed-out",
             obligation.closes?.by === "route"
-              ? `the question closed unanswered after ${formatDuration(obligation.closes.ms)}`
+              ? `the question closed unanswered after ${duration(obligation.closes.ms)}`
               : `your --timeout passed at ${clock(closesAt, this.#host.now())}`,
           );
         }
@@ -1681,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/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");
 }