@agentswf/engine 0.1.0-beta.4 → 0.1.0

package/src/coordinator-socket.ts

@@ -1,10 +1,16 @@
 import { createHash } from "node:crypto";
 import { chmod, mkdir, realpath, rm, stat } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
-import type { ParticipantResultJson } from "@agentswf/contract/records";
-import { decodeHolderRequest, type NudgeWireResult } from "@agentswf/contract/wire";
+import { basename, dirname, isAbsolute, join } from "node:path";
+
+import {
+  decodeHolderRequest,
+  type HolderWireAnswer,
+  type NudgeWireResult,
+  WIRE_VERSION,
+} from "@agentswf/contract/wire";
 import type { CoordinatorHolder, CoordinatorPort } from "./coordinator-port";
-import { realPath } from "./files";
+import { messageOf } from "./errors";
+import { isInside, realPath } from "./files";
 import type { MessagingEventBody } from "./messaging/messaging";
 import type { RunStatus } from "./run-state";
 
@@ -51,9 +57,8 @@ export async function prepareCoordinatorDir(
       return parent === path ? path : join(await real(parent), basename(path));
     }
   };
-  const inside = relative(await real(workflowDir), await real(dir));
-  const within =
-    inside === "" || !(inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside));
+  const [root, realDir] = [await real(workflowDir), await real(dir)];
+  const within = realDir === root || isInside(root, realDir);
   if (moved && within)
     throw new Error(
       `AWF_COORDINATOR_DIR ${dir} is inside the workflow's directory, where its agents work; move it out`,
@@ -65,7 +70,7 @@ export async function prepareCoordinatorDir(
 /**
  * The socket `awf reply` and `awf send` reach a live run through. It opens once the workflow
  * connects an outside participant and goes when the run ends; each connection is one request
- * line and one `ParticipantResultJson` line back.
+ * line and one `HolderWireAnswer` line back.
  */
 export function coordinatorSocket(options: {
   dir: string;
@@ -73,7 +78,7 @@ export function coordinatorSocket(options: {
   attempt: number;
   /** Why the socket did not open: the run goes on, and no holder's command reaches it. */
   failed(reason: string): void;
-  /** A nudge: the run's mailbox has a new event. Given, the socket opens at once, for awf's nudge. */
+  /** A nudge: the run has a new event. Given, the socket opens at once, for awf's nudge. */
   nudged?(): void;
 }): CoordinatorPort & { close(): Promise<void>; readonly path: string } {
   const path = coordinatorSocketPath(options.dir, options.runDir);
@@ -83,10 +88,11 @@ export function coordinatorSocket(options: {
   let closed = false;
   const id = (n: number) => `${options.attempt}.${n}`;
 
-  /** Undefined for a request no `awf` command makes: the connection closes unanswered. */
-  const answer = async (
-    frame: string,
-  ): Promise<ParticipantResultJson | NudgeWireResult | undefined> => {
+  /**
+   * Undefined for a request no `awf` command makes: the connection closes unanswered. One of
+   * another wire version is refused naming both, which an older `awf send` or `awf reply` prints.
+   */
+  const answer = async (frame: string): Promise<HolderWireAnswer | NudgeWireResult | undefined> => {
     let parsed: unknown;
     try {
       parsed = JSON.parse(frame);
@@ -94,7 +100,13 @@ export function coordinatorSocket(options: {
       return undefined;
     }
     const decoded = decodeHolderRequest(parsed);
-    if (!decoded.ok) return undefined;
+    if (!decoded.ok)
+      return decoded.code === "unsupported-version"
+        ? refused(
+            "unsupported-version",
+            `this awf speaks wire version ${(parsed as { version: number }).version} and the run's engine ${WIRE_VERSION}: awf was installed anew while the run was live. Reach it with the awf it started with, or let it end and continue it under this one.`,
+          )
+        : undefined;
     const request = decoded.value;
     if (request.command === "nudge") {
       if (!options.nudged) return undefined;
@@ -102,13 +114,14 @@ export function coordinatorSocket(options: {
       return { v: 1, code: "nudged" };
     }
     if (!holder) return refused("no-participant", "the run has no participant connected");
-    // Another attempt's question is never open in this one: a number no message has.
-    const to =
-      request.to === undefined
-        ? undefined
-        : request.to.split(".")[0] === String(options.attempt)
-          ? Number(request.to.split(".")[1])
-          : 0;
+    const [attempt, n] = request.to?.split(".") ?? [];
+    // Another attempt's question ended with it.
+    if (request.to !== undefined && attempt !== String(options.attempt))
+      return refused(
+        "expired",
+        `${request.to} is a question of attempt ${attempt}, which has ended; the run is on attempt ${options.attempt}.`,
+      );
+    const to = n === undefined ? undefined : Number(n);
     const asked = {
       ...(request.participant === undefined ? {} : { coordinator: request.participant }),
       agent: request.agent,
@@ -119,9 +132,9 @@ export function coordinatorSocket(options: {
     const result =
       request.command === "reply" ? await holder.reply(asked) : await holder.send(asked);
     return result.code === "delivered"
-      ? { v: 1, code: "delivered", id: id(result.message) }
+      ? { v: 2, code: "delivered", id: id(result.message) }
       : {
-          v: 1,
+          v: 2,
           code: result.code,
           error: result.error,
           ...(result.choices ? { choices: result.choices } : {}),
@@ -185,10 +198,7 @@ export function coordinatorSocket(options: {
       .then((result) => socket.end(result ? `${JSON.stringify(result)}\n` : undefined));
   };
 
-  if (options.nudged)
-    opening = open().catch((error: unknown) =>
-      options.failed(error instanceof Error ? error.message : String(error)),
-    );
+  if (options.nudged) opening = open().catch((error: unknown) => options.failed(messageOf(error)));
   return {
     path,
     attach(given) {
@@ -196,9 +206,7 @@ export function coordinatorSocket(options: {
     },
     recorded(event: MessagingEventBody) {
       if (event.kind === "participant-connected" && !opening) {
-        opening = open().catch((error: unknown) =>
-          options.failed(error instanceof Error ? error.message : String(error)),
-        );
+        opening = open().catch((error: unknown) => options.failed(messageOf(error)));
       }
     },
     async close() {
@@ -211,10 +219,10 @@ export function coordinatorSocket(options: {
 }
 
 function refused(
-  code: Exclude<ParticipantResultJson["code"], "delivered">,
+  code: Exclude<HolderWireAnswer["code"], "delivered">,
   error: string,
-): ParticipantResultJson {
-  return { v: 1, code, error };
+): HolderWireAnswer {
+  return { v: 2, code, error };
 }
 
 /**

package/src/deadlines.ts

@@ -1,4 +1,9 @@
-import { type AbsoluteDeadline, DeadlineExceededError } from "@agentswf/contract/workflow";
+import {
+  type AbsoluteDeadline,
+  DeadlineExceededError,
+  positiveDurationMilliseconds,
+  type Timeout,
+} from "@agentswf/contract/workflow";
 
 export class WorkflowCancelledError extends Error {
   constructor(readonly reason: unknown) {
@@ -87,20 +92,48 @@ export function earlierDeadline(
   return left.unixMilliseconds <= right.unixMilliseconds ? left : right;
 }
 
-export function laterDeadline(left: AbsoluteDeadline, right: AbsoluteDeadline): AbsoluteDeadline {
-  return left.unixMilliseconds >= right.unixMilliseconds ? left : right;
-}
-
 export function deadlineWithin(
   milliseconds: number,
   ceiling: AbsoluteDeadline | undefined,
 ): AbsoluteDeadline {
   if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0) {
-    throw new Error("timeoutMs must be a positive safe integer");
+    throw new Error(`timeoutMs is a positive duration, in whole milliseconds: not ${milliseconds}`);
   }
   return earlierDeadline({ unixMilliseconds: Date.now() + milliseconds }, ceiling);
 }
 
+/**
+ * The deadline a call's `timeout` sets, never past `ceiling`, the deadlines around it; `ceiling`
+ * when it sets none of its own. `null` from an untyped caller is no bound.
+ */
+export function boundedDeadline(
+  timeout: Timeout | null | undefined,
+  ceiling: AbsoluteDeadline | undefined,
+): AbsoluteDeadline | undefined {
+  return timeout == null ? ceiling : timeoutDeadline(timeout, ceiling);
+}
+
+/** The deadline `timeout` sets from now, never past `ceiling`; `ceiling` for `false`. */
+function timeoutDeadline(
+  timeout: Timeout,
+  ceiling: AbsoluteDeadline | undefined,
+): AbsoluteDeadline | undefined {
+  if (timeout === false) return ceiling;
+  if (timeout instanceof Date) {
+    const at = timeout.getTime();
+    if (!Number.isSafeInteger(at) || at < 0) throw new Error("a timeout's Date is a valid time");
+    return earlierDeadline({ unixMilliseconds: at }, ceiling);
+  }
+  if (typeof timeout !== "string")
+    throw new Error(
+      `a timeout is a Duration such as "10m", a Date, or false; not ${JSON.stringify(timeout)}`,
+    );
+  return earlierDeadline(
+    { unixMilliseconds: Date.now() + positiveDurationMilliseconds(timeout, "a timeout") },
+    ceiling,
+  );
+}
+
 export function assertDeadline(deadline: AbsoluteDeadline | undefined): void {
   if (!deadline) return;
   assertDeadlineValue(deadline);
@@ -109,7 +142,7 @@ export function assertDeadline(deadline: AbsoluteDeadline | undefined): void {
   }
 }
 
-export function assertDeadlineValue(deadline: AbsoluteDeadline): void {
+function assertDeadlineValue(deadline: AbsoluteDeadline): void {
   if (!Number.isSafeInteger(deadline.unixMilliseconds) || deadline.unixMilliseconds < 0) {
     throw new Error("deadline.unixMilliseconds must be a non-negative safe integer");
   }

package/src/decisions/directory.ts

@@ -1,7 +1,11 @@
 import { createHash } from "node:crypto";
-import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import type { DecisionArtifact, Money, SettledDecision } from "@agentswf/contract/records";
+import {
+  type DecisionArtifact,
+  type Money,
+  OP_FILE_VERSIONS,
+  type SettledDecision,
+} from "@agentswf/contract/records";
 import {
   type AbsoluteDeadline,
   type Answers,
@@ -14,14 +18,10 @@ import {
   type Question,
 } from "@agentswf/contract/workflow";
 import { canonical } from "../canonical-json";
-import {
-  abortableSleep,
-  assertDeadline,
-  assertDeadlineValue,
-  earlierDeadline,
-  scheduleAt,
-} from "../deadlines";
+import { abortableSleep, assertDeadline, boundedDeadline, scheduleAt } from "../deadlines";
 import { messageOf } from "../errors";
+import { writeJson } from "../files";
+import { decisionArtifact, type OpIds } from "../ops";
 import type { RunEventBody } from "../run-event-log";
 import {
   type DecisionInstallation,
@@ -70,6 +70,8 @@ export class RunDecisions {
     private readonly options: {
       installation?: DecisionInstallation;
       runDir: string;
+      /** Numbers each asking, `{key}.{n}`, and keeps the keys apart from agents'. */
+      ops: OpIds;
       sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
       /** Writes the run's event log. */
       event?(body: RunEventBody): void;
@@ -133,22 +135,12 @@ export class RunDecisions {
       ? installed.providers[resolved.provider]
       : undefined;
     if (!provider) throw new Error(`decision provider "${resolved.provider}" is not installed`);
-    if (spec.deadline) assertDeadlineValue(spec.deadline);
-    const deadline = spec.deadline
-      ? earlierDeadline(spec.deadline, scope.deadline)
-      : scope.deadline;
+    const deadline = boundedDeadline(spec.timeout, scope.deadline);
     assertDeadline(deadline);
+    // Last: a decision refused for anything else holds no key.
+    this.options.ops.claim(spec.key, "decision");
     const slot = this.#slots.length;
     this.#slots.push(undefined);
-    this.options.event?.({
-      kind: "decision-asked",
-      decision: slot + 1,
-      ...(scope.stage === undefined ? {} : { stage: scope.stage }),
-      key: spec.key,
-      alias: spec.model,
-      provider: resolved.provider,
-      model: resolved.model,
-    });
     return { spec, ids, resolved, provider, deadline, slot };
   }
 
@@ -157,6 +149,12 @@ export class RunDecisions {
     scope: DecisionScope,
   ): Promise<{ answers: Record<string, unknown>; record: DecisionRecord }> {
     const { spec, ids, resolved, provider, deadline, slot } = call;
+    const { runDir, ops } = this.options;
+    // Its folder and op.json are written as its id is drawn, before any line names it.
+    const { id: operation, lost: opLost } = ops.draw(spec.key, {
+      kind: "decision",
+      ...(scope.stage === undefined ? {} : { stage: scope.stage }),
+    });
     const startedAt = new Date().toISOString();
     const controller = new AbortController();
     let ending: Ending | undefined;
@@ -170,17 +168,27 @@ export class RunDecisions {
       : () => undefined;
     this.#cancellers.add(cancel);
     const removeFromScope = scope.add?.(async (reason) => cancel(reason));
+    this.options.event?.({
+      kind: "decision-asked",
+      decision: slot + 1,
+      operation,
+      ...(scope.stage === undefined ? {} : { stage: scope.stage }),
+      key: spec.key,
+      alias: spec.model,
+      provider: resolved.provider,
+      model: resolved.model,
+    });
 
     let attempts = 0;
     let tokens: { input: number; output: number } | undefined;
-    let charged: Money[] = [];
+    let reportedCosts: Money[] = [];
     let requestId: string | undefined;
     let response: ProviderResponse | undefined;
     let answers: Record<string, unknown> | undefined;
     let error: string | undefined;
     const count = (spent: {
       tokens?: ProviderResponse["tokens"];
-      charged?: Money;
+      reportedCost?: Money;
       requestId?: string;
     }) => {
       if (spent.tokens) {
@@ -189,7 +197,7 @@ export class RunDecisions {
           output: (tokens?.output ?? 0) + spent.tokens.output,
         };
       }
-      if (spent.charged) charged = [...charged, spent.charged];
+      if (spent.reportedCost) reportedCosts = [...reportedCosts, spent.reportedCost];
       if (spent.requestId) requestId = spent.requestId;
     };
     const request = {
@@ -232,7 +240,7 @@ export class RunDecisions {
       this.#cancellers.delete(cancel);
     }
 
-    const artifact = join("decisions", `${slot + 1}.json`);
+    const artifact = decisionArtifact(operation);
     const outcome: DecisionRecord["outcome"] = ending
       ? ending.outcome
       : answers
@@ -263,19 +271,21 @@ export class RunDecisions {
       ...(requestId ? { requestId } : {}),
       artifact,
     };
-    const total = sumMoney(charged);
-    let settled: SettledDecision = { ...record, ...(total ? { charged: total } : {}) };
+    const total = sumMoney(reportedCosts);
+    let settled: SettledDecision = { ...record, ...(total ? { reportedCost: total } : {}) };
     const written: DecisionArtifact = {
+      version: OP_FILE_VERSIONS.decision,
       record: settled,
       request: { state: spec.state, questions: spec.questions },
       ...(answers ? { answers: answers as JsonObject } : {}),
     };
-    try {
-      await mkdir(join(this.options.runDir, "decisions"), { recursive: true });
-      await writeFile(join(this.options.runDir, artifact), `${JSON.stringify(written, null, 2)}\n`);
-    } catch (thrown) {
-      const lost = `artifact not written: ${messageOf(thrown)}`;
-      // Without its artifact an answer cannot be fitted again, so it does not count as one; any
+    const artifactLost = await writeJson(join(runDir, artifact), written).then(
+      () => undefined,
+      (thrown: unknown) => `artifact not written: ${messageOf(thrown)}`,
+    );
+    if (opLost !== undefined || artifactLost !== undefined) {
+      const lost = [opLost, artifactLost].filter((each) => each !== undefined).join("; ");
+      // Without its records an answer cannot be fitted again, so it does not count as one; any
       // other outcome stands.
       settled =
         settled.outcome === "answered"
@@ -286,11 +296,12 @@ export class RunDecisions {
     this.options.event?.({
       kind: "decision-ended",
       decision: slot + 1,
+      operation,
       ...(settled.stage === undefined ? {} : { stage: settled.stage }),
       outcome: settled.outcome,
       ...(settled.error === undefined ? {} : { error: settled.error }),
     });
-    const { charged: _charged, ...returned } = settled;
+    const { reportedCost: _reportedCost, ...returned } = settled;
 
     if (returned.outcome === "answered") return { answers: answers!, record: returned };
     if (returned.outcome === "timed-out") throw new DeadlineExceededError(deadline!);
@@ -408,11 +419,11 @@ function isProbability(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
 }
 
-/** Charges in more than one currency cannot be added without converting, so their sum is unknown. */
-function sumMoney(charges: readonly Money[]): Money | undefined {
-  const currency = charges[0]?.currency;
-  if (!currency || charges.some((charge) => charge.currency !== currency)) return undefined;
-  return { amount: charges.reduce((sum, charge) => sum + charge.amount, 0), currency };
+/** Costs in more than one currency cannot be added without converting, so their sum is unknown. */
+function sumMoney(costs: readonly Money[]): Money | undefined {
+  const currency = costs[0]?.currency;
+  if (!currency || costs.some((cost) => cost.currency !== currency)) return undefined;
+  return { amount: costs.reduce((sum, cost) => sum + cost.amount, 0), currency };
 }
 
 function untilAborted<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {

package/src/decisions/fake.ts

@@ -36,7 +36,7 @@ export function confidentResponse(request: ProviderRequest): ProviderResponse {
     snapshot: `${request.model}-20260926`,
     answers,
     tokens: { input: 1_000, output: 10 },
-    charged: { amount: 0.000042, currency: "USD" },
+    reportedCost: { amount: 0.000042, currency: "USD" },
     requestId: `request-${Object.keys(request.questions).join("-")}`,
   };
 }

package/src/decisions/openrouter.ts

@@ -130,7 +130,7 @@ function levelsOf(question: Question, probabilities: Record<string, unknown>): n
 }
 
 /** What a body says was spent, as far as it says: tokens only when both counts are reported. */
-function spendOf(body: unknown): Pick<ProviderResponse, "tokens" | "charged" | "requestId"> {
+function spendOf(body: unknown): Pick<ProviderResponse, "tokens" | "reportedCost" | "requestId"> {
   if (!isRecord(body)) return {};
   const usage = isRecord(body.usage) ? body.usage : {};
   const counted = typeof usage.input_tokens === "number" && typeof usage.output_tokens === "number";
@@ -138,7 +138,9 @@ function spendOf(body: unknown): Pick<ProviderResponse, "tokens" | "charged" | "
     ...(counted
       ? { tokens: { input: usage.input_tokens as number, output: usage.output_tokens as number } }
       : {}),
-    ...(typeof usage.cost === "number" ? { charged: { amount: usage.cost, currency: "USD" } } : {}),
+    ...(typeof usage.cost === "number"
+      ? { reportedCost: { amount: usage.cost, currency: "USD" } }
+      : {}),
     ...(typeof body.id === "string" ? { requestId: body.id } : {}),
   };
 }

package/src/decisions/seam.ts

@@ -24,7 +24,7 @@ export type ProviderResponse = {
   answers: Record<string, ProviderAnswer>;
   /** Absent when the provider did not report them: unknown, not zero. */
   tokens?: { input: number; output: number };
-  charged?: Money;
+  reportedCost?: Money;
   requestId?: string;
 };
 
@@ -40,7 +40,7 @@ export interface DecisionProvider {
 export class DecisionProviderError extends Error {
   readonly retryable: boolean;
   readonly tokens?: { input: number; output: number };
-  readonly charged?: Money;
+  readonly reportedCost?: Money;
   readonly requestId?: string;
 
   constructor(
@@ -48,7 +48,7 @@ export class DecisionProviderError extends Error {
     options: {
       retryable: boolean;
       tokens?: { input: number; output: number };
-      charged?: Money;
+      reportedCost?: Money;
       requestId?: string;
     },
   ) {
@@ -56,7 +56,7 @@ export class DecisionProviderError extends Error {
     this.name = "DecisionProviderError";
     this.retryable = options.retryable;
     if (options.tokens) this.tokens = options.tokens;
-    if (options.charged) this.charged = options.charged;
+    if (options.reportedCost) this.reportedCost = options.reportedCost;
     if (options.requestId) this.requestId = options.requestId;
   }
 }

package/src/display-path.ts

@@ -1,4 +1,5 @@
-import { isAbsolute, relative, resolve } from "node:path";
+import { relative, resolve } from "node:path";
+import { isInside } from "./files";
 
 /**
  * `path` as typed from `cwd`: relative under it, absolute elsewhere, so it works from anywhere; with
@@ -7,8 +8,7 @@ import { isAbsolute, relative, resolve } from "node:path";
  */
 export function pathFrom(cwd: string, path: string, options: { home?: string } = {}): string {
   const absolute = resolve(cwd, path);
-  const inside = relative(cwd, absolute);
-  if (inside && !inside.startsWith("..") && !isAbsolute(inside)) return inside;
+  if (isInside(cwd, absolute)) return relative(cwd, absolute);
   const { home } = options;
   return home !== undefined && absolute.startsWith(`${home}/`)
     ? `~${absolute.slice(home.length)}`

package/src/duration.ts

@@ -1,29 +1,45 @@
-/** A duration such as `500ms`, `30s`, `20m` or `2h`, in milliseconds. */
-export function parseDuration(value: string): number {
-  const matched = /^(\d+)(ms|s|m|h)$/.exec(value);
-  if (!matched) throw new Error(`invalid duration: ${value}`);
-  const amount = Number(matched[1]);
-  if (!Number.isSafeInteger(amount) || amount <= 0) throw new Error(`invalid duration: ${value}`);
-  const unit = matched[2];
-  const multiplier = unit === "ms" ? 1 : unit === "s" ? 1_000 : unit === "m" ? 60_000 : 3_600_000;
-  const milliseconds = amount * multiplier;
-  if (!Number.isSafeInteger(milliseconds)) throw new Error(`duration is too large: ${value}`);
-  return milliseconds;
+import {
+  durationMilliseconds,
+  positiveDurationMilliseconds,
+  secondsForMilliseconds,
+} from "@agentswf/contract/workflow";
+import { messageOf } from "./errors";
+
+/**
+ * A flag's duration in milliseconds, longer than none: the one grammar, `"90s"`, `"1.5h"`, `"1d"`.
+ * A number of `ms`, which the CLI took before 0.1.0-beta.6, is refused with its replacement.
+ */
+export function parseDuration(value: string, flag: string): number {
+  const seconds = secondsForMilliseconds(value);
+  if (seconds === undefined) return positiveDurationMilliseconds(value, flag);
+  throw new Error(
+    `${flag} is a duration, a decimal and s, m, h or d: give ${seconds}, not ${value}`,
+  );
 }
 
-/** `45s`, `6m40s`, `1h02m`. */
-export function duration(milliseconds: number): string {
-  const seconds = Math.max(0, Math.round(milliseconds / 1000));
-  if (seconds < 60) return `${seconds}s`;
-  const minutes = Math.floor(seconds / 60);
-  if (minutes < 60) return `${minutes}m${String(seconds % 60).padStart(2, "0")}s`;
-  return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m`;
+/**
+ * `--wait`, in seconds from none to `maxSeconds`: a duration, `"90s"`. A bare number of seconds,
+ * which it took before 0.1.0-beta.6, is refused with its replacement.
+ */
+export function parseWait(value: string, maxSeconds: number): number {
+  if (/^\d+(\.\d+)?$/.test(value))
+    throw new Error(
+      `--wait takes a duration up to ${maxSeconds}s: give --wait ${Math.min(Number(value), maxSeconds)}s`,
+    );
+  let seconds: number;
+  try {
+    seconds = durationMilliseconds(value) / 1000;
+  } catch (error) {
+    throw new Error(`--wait takes a duration up to ${maxSeconds}s: ${messageOf(error)}`);
+  }
+  if (seconds > maxSeconds) throw new Error(`--wait takes a duration up to ${maxSeconds}s`);
+  return seconds;
 }
 
 /**
  * When a timer given `when` is due, epoch ms, from `now`, and `when` as its record keeps it: a
- * duration of days, hours or minutes as given, or a `Date` as an ISO time. A workflow's grammar,
- * apart from the CLI's `parseDuration`: a wait is days long, and `1.5h` reads as written.
+ * `Duration` as given, or a `Date` as an ISO time. A workflow's grammar, apart from the CLI's
+ * `parseDuration`: a wait is days long, and `1.5h` reads as written.
  */
 export function parseWhen(when: unknown, now: number): { due: number; when: string } {
   if (when instanceof Date) {
@@ -31,11 +47,11 @@ export function parseWhen(when: unknown, now: number): { due: number; when: stri
     if (!Number.isFinite(due)) throw new Error("a timer's time is a valid Date");
     return { due, when: when.toISOString() };
   }
-  const matched = typeof when === "string" ? /^(\d+(?:\.\d+)?)(d|h|m)$/.exec(when) : null;
-  if (!matched)
-    throw new Error(
-      `a timer is due in days, hours or minutes, "14d", "4h", "1.5h", or at a Date; not ${String(when)}`,
-    );
-  const unit = matched[2] === "d" ? 86_400_000 : matched[2] === "h" ? 3_600_000 : 60_000;
-  return { due: now + Math.round(Number(matched[1]) * unit), when: when as string };
+  let milliseconds: number;
+  try {
+    milliseconds = durationMilliseconds(when);
+  } catch (error) {
+    throw new Error(`a timer is due in a duration or at a Date: ${messageOf(error)}`);
+  }
+  return { due: now + milliseconds, when: when as string };
 }