@agentswf/engine 0.1.0-beta.5 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the agents.wf authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @agentswf/engine
+
+The runtime behind `awf`: it runs a workflow, keeps its record in `.awf/runs`, and serves its agents' `wfa` command.
+
+This package is internal to [agents.wf](https://agents.wf). It is published so that
+[`agentswf`](https://www.npmjs.com/package/agentswf) can depend on it, and its exports change
+without notice between versions. Install `agentswf` instead:
+
+```sh
+bun add -g agentswf
+```
+
+A workflow imports `agentswf/workflow`, its tests `agentswf/testing`, and a program that drives
+runs `agentswf/client`. The [guide](https://agents.wf/guide/) starts there.
+
+MIT licensed. Source: [github.com/romanlv/agentswf](https://github.com/romanlv/agentswf/tree/main/packages/engine).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentswf/engine",
-  "version": "0.1.0-beta.5",
+  "version": "0.1.0",
   "description": "agents.wf: the engine that runs workflows made of coding agents",
   "license": "MIT",
   "homepage": "https://agents.wf",
@@ -13,25 +13,29 @@
   "engines": {
     "bun": ">=1.4.0"
   },
-  "bin": {
-    "awf": "./src/operator-cli.ts"
-  },
   "exports": {
     ".": "./src/index.ts",
     "./testing": "./src/testing.ts",
+    "./typebox": "./src/author-typebox.ts",
     "./workflow-testing": "./src/workflow-testing/index.ts",
-    "./cli": "./src/operator-cli.ts"
+    "./cli": "./src/operator-cli.ts",
+    "./hand-over": "./src/hand-over.ts",
+    "./client": "./src/client/published.ts"
   },
   "files": [
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.eval.ts",
-    "!src/**/fixtures"
+    "!src/**/*.typecheck.ts",
+    "!src/**/*.fixture.ts",
+    "!src/**/fixtures",
+    "README.md",
+    "LICENSE"
   ],
   "dependencies": {
-    "@agentswf/contract": "0.1.0-beta.5",
-    "@agentswf/harness": "0.1.0-beta.5",
-    "@agentswf/sandbox": "0.1.0-beta.5",
+    "@agentswf/contract": "0.1.0",
+    "@agentswf/harness": "0.1.0",
+    "@agentswf/sandbox": "0.1.0",
     "typebox": "^1.3.34"
   },
   "publishConfig": {

package/src/accounting/format.ts

@@ -50,7 +50,7 @@ function describeTotals(accounting: AttemptAccounting): string {
     took,
     tokensOf(totals),
     ...(totals.estimate === undefined ? [] : [`${estimate(totals.estimate)} at ${basis}`]),
-    ...(totals.charged === undefined ? [] : [`${usd(totals.charged)} charged`]),
+    ...(totals.reportedCost === undefined ? [] : [`${usd(totals.reportedCost)} reported`]),
     accounting.billing,
     ...(totals.billed < totals.agents ? [`billing known ${totals.billed}/${totals.agents}`] : []),
     ...usageGap(totals),
@@ -182,7 +182,7 @@ function describeDecisions(decisions: DecisionFigures, basis: string): string {
     ...(decisions.attempts > decisions.calls ? [plural(decisions.attempts, "request")] : []),
     decisions.known === 0 ? "no usage known" : plural(tokens, "token", count),
     ...(decisions.estimate === undefined ? [] : [`${estimate(decisions.estimate)} at ${basis}`]),
-    ...(decisions.charged === undefined ? [] : [`${usd(decisions.charged)} charged`]),
+    ...(decisions.reportedCost === undefined ? [] : [`${usd(decisions.reportedCost)} reported`]),
     ...decisionGaps(decisions),
   ].join(" · ");
 }
@@ -237,7 +237,8 @@ function count(tokens: number): string {
   return String(tokens);
 }
 
-function usd(amount: number): string {
+/** `$6.10`, or `<$0.01` for a cost too small to show in cents. */
+export function usd(amount: number): string {
   return belowCent(amount) ? "<$0.01" : `$${amount.toFixed(2)}`;
 }
 

package/src/accounting/spent.ts

@@ -0,0 +1,128 @@
+import type {
+  AttemptAccounting,
+  ClaimedAttempt,
+  OpRecord,
+  RunAccounting,
+  SettledDecision,
+  SpendRecord,
+} from "@agentswf/contract/records";
+import type { PriceTable } from "./prices";
+import { attemptAccounting, type PricedOperation, sumAttempts, summarizeRun } from "./summary";
+
+/** An operation as its folder records it: `op.json`, and its `spend.json` or decision's record. */
+export type RecordedOp = { op: OpRecord; spend?: SpendRecord; decision?: SettledDecision };
+
+/** What one attempt's operations recorded, priced now. */
+export type AttemptSpent = {
+  attempt: number;
+  accounting: RunAccounting;
+  /** Its agent operations with no `spend.json` yet: their usage is unknown, not zero. */
+  unsettled: number;
+  /** Its agent operations settled without their usage: their sessions could not be read. */
+  unread: number;
+};
+
+/**
+ * Each attempt's accounting, summed from its operations' records and priced with `prices`: a run is
+ * priced when it is summed, never when it is written. An attempt still running, or one interrupted
+ * and not yet settled by the next, has `unsettled` operations. One with no `ended` is timed to the
+ * last of its operations to start or settle.
+ */
+export function attemptsSpent(
+  ops: readonly RecordedOp[],
+  attempts: readonly Pick<ClaimedAttempt, "attempt" | "started" | "ended">[],
+  prices: PriceTable,
+): AttemptSpent[] {
+  return attempts.map(({ attempt, started, ended }) => {
+    const own = ops.filter(({ op }) => op.attempt === attempt);
+    const usage = own.flatMap(({ op, spend }) =>
+      op.kind === "decision" || !spend ? [] : [settledOf(op, spend)],
+    );
+    const decisions = own.flatMap(({ decision }) => (decision ? [decision] : []));
+    const agentOps = own.filter(({ op }) => op.kind !== "decision");
+    const finishedAt =
+      ended ??
+      [
+        started,
+        ...own.map(({ op }) => op.at),
+        ...usage.flatMap((record) => record.settledAt ?? []),
+        ...decisions.map((record) => record.settledAt),
+      ].reduce((last, at) => (Date.parse(at) > Date.parse(last) ? at : last));
+    return {
+      attempt,
+      accounting: summarizeRun(usage, prices, { startedAt: started, finishedAt }, decisions),
+      unsettled: agentOps.filter(({ spend }) => !spend).length,
+      unread: agentOps.filter(({ spend }) => spend && spend.spend === undefined).length,
+    };
+  });
+}
+
+/**
+ * The attempts before one, for a run's total: each one's accounting as far as it is known, and how
+ * many have an operation whose usage isn't, by whether they ended.
+ */
+export type EarlierSpent = { recorded: AttemptAccounting[]; interrupted: number; ended: number };
+
+/** The attempts before `current` summed, for a run's total beside `current`'s own. */
+export function earlierSpent(
+  spent: readonly AttemptSpent[],
+  attempts: readonly Pick<ClaimedAttempt, "attempt" | "ended">[],
+  current: number,
+): EarlierSpent {
+  const before = spent.filter(({ attempt }) => attempt < current);
+  const unknown = before.filter(costUnknown);
+  const interrupted = unknown.filter(
+    ({ attempt }) => attempts.find((each) => each.attempt === attempt)?.ended === undefined,
+  ).length;
+  return {
+    recorded: before.map(({ accounting }) => attemptAccounting(accounting)),
+    interrupted,
+    ended: unknown.length - interrupted,
+  };
+}
+
+/** The attempts that ran, when `awf run` can't read what they spent: each of unknown cost. */
+export function unreadEarlier(
+  attempts: readonly Pick<ClaimedAttempt, "attempt" | "ended">[],
+  current: number,
+): EarlierSpent {
+  const before = attempts.filter(({ attempt }) => attempt < current);
+  const interrupted = before.filter(({ ended }) => ended === undefined).length;
+  return { recorded: [], interrupted, ended: before.length - interrupted };
+}
+
+/** A run's estimate at list prices, over its attempts: never what was billed. */
+export function runEstimate(spent: readonly AttemptSpent[]): number | undefined {
+  if (spent.length === 0) return undefined;
+  return sumAttempts(spent.map(({ accounting }) => attemptAccounting(accounting))).totals.estimate;
+}
+
+/** How many of a run's agent operations have a usage not known, so its estimate is a floor. */
+export function unknownOps(spent: readonly AttemptSpent[]): number {
+  return spent.reduce((total, each) => total + each.unsettled + each.unread, 0);
+}
+
+function costUnknown({ unsettled, unread }: AttemptSpent): boolean {
+  return unsettled + unread > 0;
+}
+
+function settledOf(op: Extract<OpRecord, { agent: string }>, spend: SpendRecord): PricedOperation {
+  return {
+    callPath: [],
+    agent: op.agent,
+    operationId: op.id,
+    execution: op.execution,
+    sessions: [],
+    ...(op.stage === undefined ? {} : { stage: op.stage }),
+    ...(spend.deliveredAt === undefined ? {} : { deliveredAt: spend.deliveredAt }),
+    ...(spend.settledAt === undefined ? {} : { settledAt: spend.settledAt }),
+    billing: spend.billing,
+    ...(spend.spend === undefined ? {} : { spend: spend.spend }),
+    ...(spend.reportedCost === undefined ? {} : { reportedCost: spend.reportedCost }),
+    // A metered turn's cost is printed as it ends, never after: read by the next attempt, its
+    // reported cost is unknown.
+    ...(spend.settledBy !== undefined && spend.billing === "metered"
+      ? { reportedCostUnread: true as const }
+      : {}),
+  };
+}

package/src/accounting/summary.ts

@@ -13,6 +13,9 @@ import { addTokens } from "./tokens";
 
 const NONE: TokenUsage = { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 };
 
+/** An operation as priced: `reportedCostUnread` when what its harness reported can't be known. */
+export type PricedOperation = SettledOperation & { reportedCostUnread?: true };
+
 /** What ran between a run's stages, as a row of `byStage`. */
 export const NO_STAGE = "(no stage)";
 
@@ -20,10 +23,10 @@ export const NO_STAGE = "(no stage)";
  * What a run cost and how long it took, from its usage and decision records alone, so a finished
  * run can be priced again with another table. `entered` are the workflow stages entered, in order:
  * each is a row timed by its own span, a reused one at zero; without them, a row per call path and
- * key prefix, timed by what ran in it.
+ * agent or decision key, timed by what ran in it.
  */
 export function summarizeRun(
-  usage: readonly SettledOperation[],
+  usage: readonly PricedOperation[],
   prices: PriceTable,
   times: { startedAt: string; finishedAt: string },
   decisions: readonly SettledDecision[],
@@ -38,8 +41,8 @@ export function summarizeRun(
     entered.length > 0 ||
     usage.some((record) => record.stage !== undefined) ||
     decisions.some((record) => record.stage !== undefined);
-  const stageOf = staged ? workflowStageOf : prefixStageOf;
-  const decisionStageOf = staged ? workflowStageOf : decisionPrefixStageOf;
+  const stageOf = staged ? workflowStageOf : agentStageOf;
+  const decisionStageOf = staged ? workflowStageOf : decisionKeyStageOf;
   const stages = unique([
     ...entered.map(({ stage }) => stage),
     ...usage.map(stageOf),
@@ -49,7 +52,7 @@ export function summarizeRun(
     (billing) => billing !== "unknown",
   );
   const figures = (
-    records: readonly SettledOperation[],
+    records: readonly PricedOperation[],
     asked: readonly SettledDecision[] = [],
   ): AccountingFigures => {
     const agents = figuresOf(records, prices);
@@ -61,7 +64,7 @@ export function summarizeRun(
     startedAt: times.startedAt,
     finishedAt: times.finishedAt,
     wallMs: Date.parse(times.finishedAt) - Date.parse(times.startedAt),
-    grouping: staged ? "stages" : "prefix",
+    grouping: staged ? "stages" : "agents",
     billing: billings.length === 0 ? "unknown" : billings.length === 1 ? billings[0]! : "mixed",
     totals: figures(usage, decisions),
     byStage: stages.map((stage) => {
@@ -92,10 +95,10 @@ export function summarizeRun(
   };
 }
 
-function figuresOf(records: readonly SettledOperation[], prices: PriceTable): AccountingFigures {
+function figuresOf(records: readonly PricedOperation[], prices: PriceTable): AccountingFigures {
   let tokens = NONE;
   let delegated = NONE;
-  let charged: number | undefined;
+  let reportedCost: number | undefined;
   let agentMs = 0;
   const agents = new Map<
     string,
@@ -113,9 +116,11 @@ function figuresOf(records: readonly SettledOperation[], prices: PriceTable): Ac
     if (record.deliveredAt !== undefined && record.settledAt !== undefined) {
       agentMs += Date.parse(record.settledAt) - Date.parse(record.deliveredAt);
     }
-    // Another currency would need converting first; until then its charge is an unknown one.
-    if (record.charged?.currency === "USD") charged = (charged ?? 0) + record.charged.amount;
-    else if (record.charged) agent.billed = false;
+    // Another currency would need converting first; until then its reported cost is an unknown one.
+    if (record.reportedCost?.currency === "USD")
+      reportedCost = (reportedCost ?? 0) + record.reportedCost.amount;
+    else if (record.reportedCost) agent.billed = false;
+    if (record.reportedCostUnread) agent.billed = false;
     if (!record.spend) {
       agent.known = false;
       agent.priced = false;
@@ -141,7 +146,7 @@ function figuresOf(records: readonly SettledOperation[], prices: PriceTable): Ac
     tokens,
     delegated,
     ...(estimate === undefined ? {} : { estimate }),
-    ...(charged === undefined ? {} : { charged }),
+    ...(reportedCost === undefined ? {} : { reportedCost }),
     known: counts.filter((agent) => agent.known).length,
     priced: counts.filter((agent) => agent.priced).length,
     billed: counts.filter((agent) => agent.billed).length,
@@ -152,14 +157,15 @@ function decisionFigures(records: readonly SettledDecision[], prices: PriceTable
   let input = 0;
   let output = 0;
   let estimate: number | undefined;
-  let charged: number | undefined;
+  let reportedCost: number | undefined;
   let known = 0;
   let priced = 0;
   let attempts = 0;
   for (const record of records) {
     attempts += record.attempts;
-    // Another currency would need converting first; until then its charge is not counted.
-    if (record.charged?.currency === "USD") charged = (charged ?? 0) + record.charged.amount;
+    // Another currency would need converting first; until then its reported cost is not counted.
+    if (record.reportedCost?.currency === "USD")
+      reportedCost = (reportedCost ?? 0) + record.reportedCost.amount;
     if (!record.tokens) continue;
     known += 1;
     input += record.tokens.input;
@@ -174,7 +180,7 @@ function decisionFigures(records: readonly SettledDecision[], prices: PriceTable
     attempts,
     tokens: { input, output },
     ...(estimate === undefined ? {} : { estimate }),
-    ...(charged === undefined ? {} : { charged }),
+    ...(reportedCost === undefined ? {} : { reportedCost }),
     known,
     priced,
   };
@@ -205,8 +211,8 @@ function decisionModelOf(record: SettledDecision): string {
   return record.snapshot ?? record.model;
 }
 
-function decisionPrefixStageOf(record: SettledDecision): string {
-  return [...record.callPath, prefixOf(record.key)].join("/");
+function decisionKeyStageOf(record: SettledDecision): string {
+  return [...record.callPath, record.key].join("/");
 }
 
 function modelFigures(
@@ -249,13 +255,8 @@ function noStageLast(a: string, b: string): number {
   return Number(a === NO_STAGE) - Number(b === NO_STAGE);
 }
 
-function prefixStageOf(record: SettledOperation): string {
-  return [...record.callPath, prefixOf(record.agent)].join("/");
-}
-
-function prefixOf(key: string): string {
-  const separator = key.indexOf(":");
-  return separator === -1 ? key : key.slice(0, separator);
+function agentStageOf(record: SettledOperation): string {
+  return [...record.callPath, record.agent].join("/");
 }
 
 function spanOf(
@@ -298,15 +299,22 @@ export function attemptAccounting({
 
 /**
  * A run's attempts summed, each estimate as its attempt recorded it, under the last one's basis:
- * its total, and each stage's across the attempts that ran it. Once any attempt grouped by stages, what another grouped by prefix, having failed
- * before it entered one, ran between stages.
+ * its total, and each stage's across the attempts that ran it. Once any attempt grouped by stages,
+ * what another grouped by agent, having failed before it entered one, ran between stages. An older
+ * attempt's `prefix` rows, by a key's part before `:`, sum with `agents` rows by name: a key
+ * without a colon is both.
  */
 export function sumAttempts(attempts: readonly AttemptAccounting[]): AttemptAccounting {
-  const grouping = attempts.some((attempt) => attempt.grouping === "stages") ? "stages" : "prefix";
+  const grouping = attempts.some((attempt) => attempt.grouping === "stages")
+    ? "stages"
+    : attempts.some((attempt) => attempt.grouping === "agents")
+      ? "agents"
+      : "prefix";
   const byStage = new Map<string, RunAccounting["byStage"][number]>();
   for (const attempt of attempts) {
     for (const row of attempt.byStage) {
-      const stage = grouping === attempt.grouping ? row.stage : NO_STAGE;
+      const stage =
+        (grouping === "stages") === (attempt.grouping === "stages") ? row.stage : NO_STAGE;
       const before = byStage.get(stage);
       byStage.set(
         stage,
@@ -351,7 +359,7 @@ function addFigures(left: AccountingFigures, right: AccountingFigures): Accounti
     tokens: addTokens(left.tokens, right.tokens),
     delegated: addTokens(left.delegated, right.delegated),
     ...addOptional("estimate", left, right),
-    ...addOptional("charged", left, right),
+    ...addOptional("reportedCost", left, right),
     known: left.known + right.known,
     priced: left.priced + right.priced,
     billed: left.billed + right.billed,
@@ -368,14 +376,14 @@ function addDecisions(left: DecisionFigures, right: DecisionFigures): DecisionFi
       output: left.tokens.output + right.tokens.output,
     },
     ...addOptional("estimate", left, right),
-    ...addOptional("charged", left, right),
+    ...addOptional("reportedCost", left, right),
     known: left.known + right.known,
     priced: left.priced + right.priced,
   };
 }
 
 /** A sum of what either side knows; absent only when neither does. */
-function addOptional<K extends "estimate" | "charged">(
+function addOptional<K extends "estimate" | "reportedCost">(
   field: K,
   left: { [P in K]?: number },
   right: { [P in K]?: number },

package/src/agent-cli/cli.ts

@@ -5,7 +5,7 @@ import {
   validWaitingReason,
   WIRE_VERSION,
 } from "@agentswf/contract/wire";
-import { durationMilliseconds } from "@agentswf/contract/workflow";
+import { durationMilliseconds, secondsForMilliseconds } from "@agentswf/contract/workflow";
 import { NotSentError, submitControl } from "./client";
 
 /** `wfa` is its launcher's full path, as an agent must type it; `wfa` alone when it is not known. */
@@ -46,9 +46,14 @@ function messageUsage(wfa: string, indent = "usage: "): string[] {
   ];
 }
 const MAX_STDIN_BYTES = 1024 * 1024;
+
+/** An error's message, or the thrown value as text: the engine's `messageOf`, which wfa can't import. */
+function reasonOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
 const STDIN_TIMEOUT_MS = 30_000;
 
-export type CliOutcome = { exitCode: number; stdout: string; stderr: string };
+type CliOutcome = { exitCode: number; stdout: string; stderr: string };
 
 type Submit = (
   endpoint: string,
@@ -74,15 +79,10 @@ export async function runCli(
   }
   switch (command) {
     case "waiting":
+      return runWaiting(endpoint, session, args, submit);
     case "send":
-    case "reply": {
-      const said: Said = {};
-      const outcome =
-        command === "waiting"
-          ? await runWaiting(endpoint, session, args, submit, said)
-          : await runMessage(endpoint, session, command, args, stdin, wfa, submit, said);
-      return noticed(outcome, said.notice);
-    }
+    case "reply":
+      return runMessage(endpoint, session, command, args, stdin, wfa, submit);
     case "result":
       return runResult(endpoint, session, args, stdin, submit);
     case "tool":
@@ -94,16 +94,6 @@ export async function runCli(
   }
 }
 
-/** What a command accepted in a deprecated form, said beside its outcome. */
-type Said = { notice?: string };
-
-/** Never beside a usage error: the form said was not taken then. */
-function noticed(outcome: CliOutcome, notice: string | undefined): CliOutcome {
-  return notice && outcome.exitCode !== 2
-    ? { ...outcome, stderr: outcome.stderr ? `${notice}\n${outcome.stderr}` : notice }
-    : outcome;
-}
-
 async function runResult(
   endpoint: string,
   session: string | undefined,
@@ -128,7 +118,7 @@ async function runResult(
       ...(session ? { session } : {}),
     });
   } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
+    const reason = reasonOf(error);
     return { exitCode: 1, stdout: "", stderr: `wfa: result submission failed.\n${reason}` };
   }
 
@@ -180,7 +170,7 @@ async function runTool(
       null,
     );
   } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
+    const reason = reasonOf(error);
     return error instanceof NotSentError
       ? {
           exitCode: 3,
@@ -224,7 +214,6 @@ async function runWaiting(
   session: string | undefined,
   args: readonly string[],
   submit: Submit,
-  said: Said,
 ): Promise<CliOutcome> {
   const [operationId, ...flags] = args;
   if (!operationId?.trim() || operationId.startsWith("--"))
@@ -244,9 +233,8 @@ async function runWaiting(
   let timeoutMs: number | undefined;
   if (duration !== undefined) {
     const read = durationOf(duration);
-    if (!read) return usageError(`wfa waiting --timeout ${DURATION_GRAMMAR}`);
-    timeoutMs = read.milliseconds;
-    said.notice = read.notice;
+    if (typeof read === "string") return usageError(`wfa waiting --timeout ${read}`);
+    timeoutMs = read;
   }
   let response: ControlResponse;
   try {
@@ -259,7 +247,7 @@ async function runWaiting(
       ...(session ? { session } : {}),
     });
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+    const detail = reasonOf(error);
     return {
       exitCode: 1,
       stdout: "",
@@ -304,7 +292,7 @@ async function runPeers(
       ...(session ? { session } : {}),
     });
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+    const detail = reasonOf(error);
     return { exitCode: 1, stdout: "", stderr: `wfa: peers failed; nothing changed.\n${detail}` };
   }
   if (response.kind === "rejected")
@@ -331,14 +319,12 @@ async function runMessage(
   stdin: string | null,
   wfa: string,
   submit: Submit,
-  said: Said,
 ): Promise<CliOutcome> {
   const parsed = messageArgs(args);
   const wrong = (problem: string) =>
     usageError(`wfa: ${command}: ${problem}\n\n${messageUsage(wfa).join("\n")}`);
   if ("error" in parsed) return wrong(parsed.error);
   const { peer, message, awaitReply, timeoutMs } = parsed;
-  said.notice = parsed.notice;
   // A heredoc ends with a newline the agent did not mean as part of the message.
   const text = message ?? stdin?.replace(/\r?\n$/, "") ?? null;
   if (text === null || text.trim() === "") return wrong("it needs a message");
@@ -355,7 +341,7 @@ async function runMessage(
   try {
     response = await submit(endpoint, request);
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+    const detail = reasonOf(error);
     const what = command === "send" ? "message" : "reply";
     // Refused at the connection, nothing reached the engine; after, it may have been admitted.
     if (error instanceof NotSentError) {
@@ -384,12 +370,9 @@ async function runMessage(
  */
 function messageArgs(
   args: readonly string[],
-):
-  | { peer: string; message?: string; awaitReply: boolean; timeoutMs?: number; notice?: string }
-  | { error: string } {
+): { peer: string; message?: string; awaitReply: boolean; timeoutMs?: number } | { error: string } {
   let awaitReply = false;
   let timeoutMs: number | undefined;
-  let notice: string | undefined;
   const positional: string[] = [];
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i]!;
@@ -401,8 +384,8 @@ function messageArgs(
     if (arg === "--await-reply" && !awaitReply) awaitReply = true;
     else if (arg === "--timeout" && timeoutMs === undefined) {
       const read = durationOf(args[i + 1] ?? "");
-      if (!read) return { error: `--timeout ${DURATION_GRAMMAR}` };
-      ({ milliseconds: timeoutMs, notice } = read);
+      if (typeof read === "string") return { error: `--timeout ${read}` };
+      timeoutMs = read;
       i += 1;
     } else if (positional.length === 1 && arg !== "--await-reply" && arg !== "--timeout") {
       return { error: `${arg} is not a flag; a message that starts with -- goes in a heredoc` };
@@ -418,32 +401,22 @@ function messageArgs(
     ...(rest[0] === undefined ? {} : { message: rest[0] }),
     awaitReply,
     ...(timeoutMs === undefined ? {} : { timeoutMs }),
-    ...(notice === undefined ? {} : { notice }),
   };
 }
 
 const DURATION_GRAMMAR = 'takes a duration, a decimal and s, m, h or d, such as "5m"';
-const LEGACY_MS = /^([0-9]+)ms$/;
 
-/**
- * The one grammar's, longer than none. A whole number of `ms` is read until 0.1.0, with the line
- * `wfa` says beside its outcome.
- */
-function durationOf(text: string): { milliseconds: number; notice?: string } | undefined {
-  const legacy = LEGACY_MS.exec(text);
+/** The one grammar's milliseconds, longer than none; else why not, `ms` named in `s`. */
+function durationOf(text: string): number | string {
+  const seconds = secondsForMilliseconds(text);
+  if (seconds !== undefined) return `${DURATION_GRAMMAR}: give ${seconds}`;
   let milliseconds: number;
   try {
-    milliseconds = legacy ? Number(legacy[1]) : durationMilliseconds(text);
+    milliseconds = durationMilliseconds(text);
   } catch {
-    return undefined;
+    return DURATION_GRAMMAR;
   }
-  if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0) return undefined;
-  return legacy
-    ? {
-        milliseconds,
-        notice: `wfa: --timeout ${text} is deprecated; give ${milliseconds / 1000}s: a duration is a decimal and s, m, h or d`,
-      }
-    : { milliseconds };
+  return milliseconds > 0 ? milliseconds : DURATION_GRAMMAR;
 }
 
 /** What is owed leads, so it comes back after a harness compacts; then the acknowledgement. */
@@ -536,7 +509,7 @@ if (import.meta.main) {
       Bun.stdin.stream(),
     );
   } catch (error) {
-    console.error(`wfa: ${error instanceof Error ? error.message : String(error)}`);
+    console.error(`wfa: ${reasonOf(error)}`);
     process.exit(2);
   }
   const outcome = await runCli(process.argv.slice(2), stdinText);