@agentswf/engine 0.1.0-beta.4 → 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.4",
+  "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.4",
-    "@agentswf/harness": "0.1.0-beta.4",
-    "@agentswf/sandbox": "0.1.0-beta.4",
+    "@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,6 +5,7 @@ import {
   validWaitingReason,
   WIRE_VERSION,
 } from "@agentswf/contract/wire";
+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. */
@@ -45,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 +80,15 @@ export async function runCli(
   switch (command) {
     case "waiting":
       return runWaiting(endpoint, session, args, submit);
+    case "send":
+    case "reply":
+      return runMessage(endpoint, session, command, args, stdin, wfa, submit);
     case "result":
       return runResult(endpoint, session, args, stdin, submit);
     case "tool":
       return runTool(endpoint, session, args, stdin, submit);
     case "peers":
       return runPeers(endpoint, session, args, submit);
-    case "send":
-    case "reply":
-      return runMessage(endpoint, session, command, args, stdin, wfa, submit);
     default:
       return usageError(usage(wfa));
   }
@@ -112,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}` };
   }
 
@@ -164,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,
@@ -226,9 +232,9 @@ async function runWaiting(
   const duration = values.get("--timeout");
   let timeoutMs: number | undefined;
   if (duration !== undefined) {
-    timeoutMs = durationOf(duration);
-    if (timeoutMs === undefined)
-      return usageError("wfa waiting --timeout must be a positive integer with ms, s, m or h");
+    const read = durationOf(duration);
+    if (typeof read === "string") return usageError(`wfa waiting --timeout ${read}`);
+    timeoutMs = read;
   }
   let response: ControlResponse;
   try {
@@ -241,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: "",
@@ -286,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")
@@ -335,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) {
@@ -377,9 +383,9 @@ function messageArgs(
     if (positional.length > 1) return { error: "flags go before the message" };
     if (arg === "--await-reply" && !awaitReply) awaitReply = true;
     else if (arg === "--timeout" && timeoutMs === undefined) {
-      timeoutMs = durationOf(args[i + 1] ?? "");
-      if (timeoutMs === undefined)
-        return { error: "--timeout takes a positive integer with ms, s, m or h, such as 5m" };
+      const read = durationOf(args[i + 1] ?? "");
+      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` };
@@ -398,12 +404,19 @@ function messageArgs(
   };
 }
 
-function durationOf(text: string): number | undefined {
-  const match = /^([0-9]+)(ms|s|m|h)$/.exec(text);
-  if (!match) return undefined;
-  const factor = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[match[2]!]!;
-  const value = Number(match[1]) * factor;
-  return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+const DURATION_GRAMMAR = 'takes a duration, a decimal and s, m, h or d, such as "5m"';
+
+/** 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 = durationMilliseconds(text);
+  } catch {
+    return DURATION_GRAMMAR;
+  }
+  return milliseconds > 0 ? milliseconds : DURATION_GRAMMAR;
 }
 
 /** What is owed leads, so it comes back after a harness compacts; then the acknowledgement. */
@@ -496,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);

package/src/agent-cli/client.ts

@@ -1,37 +1,11 @@
 import { createConnection, type Socket } from "node:net";
-import {
-  type ControlRequest,
-  decodeResponseFor,
-  type ResponseFor,
-  type ResultSubmitRequest,
-  type ResultSubmitResponse,
-  type WaitingRequest,
-  type WaitingResponse,
-} from "@agentswf/contract/wire";
+import { type ControlRequest, decodeResponseFor, type ResponseFor } from "@agentswf/contract/wire";
 
 const MAX_RESPONSE_BYTES = 256 * 1024;
 
 /** The connection never opened: nothing was written, so nothing reached the engine. */
 export class NotSentError extends Error {}
 
-export function submitResult(
-  endpoint: string,
-  request: ResultSubmitRequest,
-  timeoutSeconds = 30,
-  connect: (endpoint: string) => Socket = createConnection,
-): Promise<ResultSubmitResponse> {
-  return submitControl(endpoint, request, timeoutSeconds, connect);
-}
-
-export function submitWaiting(
-  endpoint: string,
-  request: WaitingRequest,
-  timeoutSeconds = 30,
-  connect: (endpoint: string) => Socket = createConnection,
-): Promise<WaitingResponse> {
-  return submitControl(endpoint, request, timeoutSeconds, connect);
-}
-
 /** Sends one request and resolves with a response that answers its command. */
 export function submitControl<R extends ControlRequest>(
   endpoint: string,

package/src/allowance-command.ts

@@ -5,19 +5,21 @@ import type {
 } from "@agentswf/contract/records";
 import { HARNESS_NAMES, type Harness } from "@agentswf/harness";
 import { planPrice } from "./accounting/plans";
-import { messageOf } from "./errors";
+import type { Out } from "./command-line";
 import help from "./help/allowance.txt" with { type: "text" };
-import type { Out } from "./run-commands";
+import { asksJson, printRefusal } from "./refusals";
+
+/** `awf allowance --json`'s `"v"`, which its refusals carry too. */
+export const ALLOWANCE_V = 1 satisfies AllowanceReport["v"];
 
 export const allowanceUsage = help.trimEnd();
 
-export type AllowanceCommand = { harnesses: Harness[]; json: boolean } | "help";
+type AllowanceCommand = { harnesses: Harness[]; json: boolean };
 
 export function parseAllowanceCommand(argv: readonly string[]): AllowanceCommand {
   const harnesses: Harness[] = [];
   let json = false;
   for (const arg of argv) {
-    if (arg === "-h" || arg === "--help") return "help";
     if (arg === "--json") json = true;
     else if ((HARNESS_NAMES as readonly string[]).includes(arg)) {
       if (!harnesses.includes(arg as Harness)) harnesses.push(arg as Harness);
@@ -35,13 +37,9 @@ export async function allowanceCommand(
   try {
     command = parseAllowanceCommand(argv);
   } catch (error) {
-    io.stderr(`awf: ${messageOf(error)}\n\n${allowanceUsage}`);
+    printRefusal(io, { json: asksJson(argv), v: ALLOWANCE_V }, error, "usage", allowanceUsage);
     return 2;
   }
-  if (command === "help") {
-    io.stdout(allowanceUsage);
-    return 0;
-  }
   const report = await readReport(command.harnesses, io.read, io.now());
   io.stdout(command.json ? JSON.stringify(report, null, 2) : describeReport(report));
   return 0;
@@ -54,7 +52,7 @@ export async function readReport(
   now: number,
 ): Promise<AllowanceReport> {
   return {
-    v: 1,
+    v: ALLOWANCE_V,
     readAt: new Date(now).toISOString(),
     harnesses: await Promise.all(harnesses.map(read)),
   };