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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentswf/engine",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.5",
   "description": "agents.wf: the engine that runs workflows made of coding agents",
   "license": "MIT",
   "homepage": "https://agents.wf",
@@ -29,9 +29,9 @@
     "!src/**/fixtures"
   ],
   "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-beta.5",
+    "@agentswf/harness": "0.1.0-beta.5",
+    "@agentswf/sandbox": "0.1.0-beta.5",
     "typebox": "^1.3.34"
   },
   "publishConfig": {

package/src/agent-cli/cli.ts

@@ -5,6 +5,7 @@ import {
   validWaitingReason,
   WIRE_VERSION,
 } from "@agentswf/contract/wire";
+import { durationMilliseconds } 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. */
@@ -73,21 +74,36 @@ 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 "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));
   }
 }
 
+/** 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,
@@ -208,6 +224,7 @@ async function runWaiting(
   session: string | undefined,
   args: readonly string[],
   submit: Submit,
+  said: Said,
 ): Promise<CliOutcome> {
   const [operationId, ...flags] = args;
   if (!operationId?.trim() || operationId.startsWith("--"))
@@ -226,9 +243,10 @@ 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 (!read) return usageError(`wfa waiting --timeout ${DURATION_GRAMMAR}`);
+    timeoutMs = read.milliseconds;
+    said.notice = read.notice;
   }
   let response: ControlResponse;
   try {
@@ -313,12 +331,14 @@ 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");
@@ -364,9 +384,12 @@ async function runMessage(
  */
 function messageArgs(
   args: readonly string[],
-): { peer: string; message?: string; awaitReply: boolean; timeoutMs?: number } | { error: string } {
+):
+  | { peer: string; message?: string; awaitReply: boolean; timeoutMs?: number; notice?: string }
+  | { 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]!;
@@ -377,9 +400,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 (!read) return { error: `--timeout ${DURATION_GRAMMAR}` };
+      ({ milliseconds: timeoutMs, notice } = 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` };
@@ -395,15 +418,32 @@ function messageArgs(
     ...(rest[0] === undefined ? {} : { message: rest[0] }),
     awaitReply,
     ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    ...(notice === undefined ? {} : { notice }),
   };
 }
 
-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"';
+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);
+  let milliseconds: number;
+  try {
+    milliseconds = legacy ? Number(legacy[1]) : durationMilliseconds(text);
+  } catch {
+    return undefined;
+  }
+  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 };
 }
 
 /** What is owed leads, so it comes back after a harness compacts; then the acknowledgement. */

package/src/attempt-ending.ts

@@ -1,5 +1,5 @@
 import { constants } from "node:os";
-import type { StageNeed, StageRecord } from "@agentswf/contract/records";
+import type { StageRecord } from "@agentswf/contract/records";
 import {
   type AbsoluteDeadline,
   type AttemptOutcome,
@@ -37,8 +37,6 @@ export type AttemptEnd = {
    * the run's stages to choose from.
    */
   choose?: readonly StageRecord[];
-  /** The stages whose values `--values` gives, to start at a later one. */
-  needs?: readonly StageNeed[];
 };
 
 /** What a started run came to: the result it returned, or what it threw. */
@@ -107,12 +105,12 @@ export function decideEnding(
       reason: stop?.reason ?? errorDetail(error),
       stages,
       continue: goOn(stop, stages),
+      ...(stop?.needs ? { needs: [...stop.needs] } : {}),
     },
     ...(settled ? { settled } : {}),
     exitCode: cancellation ? signalExitCode(cancellation.reason) : OUTCOMES[kind].exitCode!,
     ...(beside ? { alsoFailed: beside } : {}),
     ...(stop instanceof FromStageUnreached ? { choose: stop.recorded } : {}),
-    ...(stop?.needs ? { needs: stop.needs } : {}),
   };
 }
 

package/src/attempt-output.ts

@@ -58,7 +58,7 @@ export async function keepRecords(
             outcome: ending.kind,
             reason: ending.reason,
             ...at,
-            ...(end.needs ? { needs: [...end.needs] } : {}),
+            ...(ending.needs ? { needs: ending.needs } : {}),
           };
   const kept: Kept = report ? { report } : {};
   const output = outputFile(dir);
@@ -70,6 +70,7 @@ export async function keepRecords(
   } else {
     const record: OutputRecord = {
       version: OUTPUT_RECORD_VERSION,
+      ref: `${context.loaded.workflow.meta.name}/${settled.runId}`,
       runId: settled.runId,
       attempt: attempt.record.attempt,
       workflow: { name: context.loaded.workflow.meta.name, file: context.loaded.file },

package/src/attempt-view.ts

@@ -71,7 +71,7 @@ export function printEnding(
     records: pathFrom(shellCwd, context.run.dir, { home: context.home }),
     ...(kept.report ? { report: pathFrom(shellCwd, kept.report, { home: context.home }) } : {}),
     ...(end.choose?.length ? { choose: listRecorded(end.choose, context.now) } : {}),
-    ...(end.needs ? { needs: end.needs } : {}),
+    ...("needs" in end.ending && end.ending.needs ? { needs: end.ending.needs } : {}),
     ...(settled?.panes ? { panes: settled.panes } : {}),
     // As the run's Herdr workspace is labelled.
     runWorkspace: `awf ${context.workflow.meta.name} ${context.run.id} #${context.n}`,

package/src/control-plane.ts

@@ -321,16 +321,17 @@ type Handlers = {
   lifetime: (milliseconds: number | undefined) => void;
 };
 
-async function handleFrame(frame: string, handlers: Handlers): Promise<ControlResponse> {
+async function handleFrame(frame: string, handlers: Handlers): Promise<Answer> {
   const { messaging, agentId } = handlers;
   const response = await answerFrame(frame, handlers);
+  if (inOtherVersion(response)) return response;
   // Leads every response, so what is owed comes back after a compaction; not one that already
   // says it, about the wait it began or the answer it is refused for.
   const repeats =
     response.kind === "awaiting-reply" ||
     (response.kind === "sent" && response.until !== undefined) ||
     (response.kind === "rejected" &&
-      (response.code === "owes-reply" || response.code === "awaiting"));
+      (response.code === "owes-reply" || response.code === "already-awaiting"));
   const owing = repeats ? undefined : messaging?.owing(agentId);
   return owing ? { ...response, owing } : response;
 }
@@ -338,7 +339,7 @@ async function handleFrame(frame: string, handlers: Handlers): Promise<ControlRe
 async function answerFrame(
   frame: string,
   { slots, messaging, tools, agentId, onSession, lifetime }: Handlers,
-): Promise<ControlResponse> {
+): Promise<Answer> {
   if (!frame.endsWith("\n") || frame.slice(0, -1).includes("\n")) {
     return rejected("invalid-request", "expected exactly one newline-delimited JSON request");
   }
@@ -350,7 +351,10 @@ async function answerFrame(
     return rejected("invalid-request", "request is not valid JSON");
   }
   const decoded = decodeControlRequest(parsed);
-  if (!decoded.ok) return rejected(decoded.code, decoded.error);
+  if (!decoded.ok)
+    return decoded.code === "unsupported-version"
+      ? otherVersion((parsed as { version: number }).version)
+      : rejected(decoded.code, decoded.error);
   // Before the result is judged: a rejected submission still proves which session sent it.
   if (decoded.value.session) onSession?.(decoded.value.session);
 
@@ -447,7 +451,35 @@ function rejected(
   return { version: WIRE_VERSION, kind: "rejected", code, error };
 }
 
-function queueResponse(socket: Bun.Socket<ConnectionState>, response: ControlResponse): void {
+/** A refusal in another wire version than this engine's: the one answer not a `ControlResponse`. */
+type OtherVersion = {
+  version: number;
+  kind: "rejected";
+  code: "unsupported-version";
+  error: string;
+};
+type Answer = ControlResponse | OtherVersion;
+
+function inOtherVersion(answer: Answer): answer is OtherVersion {
+  return answer.version !== WIRE_VERSION;
+}
+
+/**
+ * Refused in the version the request gave: a `wfa` of version 4 or 5 decodes a rejection of that
+ * shape and prints its error, where it would refuse this engine's version unread. They meet when
+ * awf is installed anew in place while a run is live: a launcher runs the `wfa` on disk, which is
+ * no longer the one the engine in memory shipped with.
+ */
+function otherVersion(version: number): OtherVersion {
+  return {
+    version,
+    kind: "rejected",
+    code: "unsupported-version",
+    error: `this wfa speaks wire version ${version} and the workflow engine ${WIRE_VERSION}: awf was installed anew while the run was live. Nothing was done; the run must go on under one version of awf.`,
+  };
+}
+
+function queueResponse(socket: Bun.Socket<ConnectionState>, response: Answer): void {
   socket.data.outgoing = Buffer.from(`${JSON.stringify(response)}\n`);
   socket.data.written = 0;
   flushResponse(socket);

package/src/coordinator-socket.ts

@@ -2,7 +2,7 @@ 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 { decodeHolderRequest, type NudgeWireResult, WIRE_VERSION } from "@agentswf/contract/wire";
 import type { CoordinatorHolder, CoordinatorPort } from "./coordinator-port";
 import { realPath } from "./files";
 import type { MessagingEventBody } from "./messaging/messaging";
@@ -83,7 +83,10 @@ 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. */
+  /**
+   * 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<ParticipantResultJson | NudgeWireResult | undefined> => {
@@ -94,7 +97,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;
@@ -119,9 +128,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 } : {}),
@@ -214,7 +223,7 @@ function refused(
   code: Exclude<ParticipantResultJson["code"], "delivered">,
   error: string,
 ): ParticipantResultJson {
-  return { v: 1, code, error };
+  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) {
@@ -96,11 +101,73 @@ export function deadlineWithin(
   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);
 }
 
+/** A call's bound as a workflow gives it: `timeout`, or the deprecated `deadline` or `timeoutMs`. */
+export type GivenBound = {
+  timeout?: Timeout;
+  deadline?: AbsoluteDeadline;
+  timeoutMs?: number;
+};
+
+/**
+ * The deadline a call's bound sets, never past `ceiling`, the deadlines around it; `ceiling` when it
+ * sets none of its own. A deprecated form is checked, then reported under `call`, the call it was
+ * given to, and refused beside `timeout`. `null` from an untyped caller is no bound, as it was.
+ */
+export function boundedDeadline(
+  given: GivenBound,
+  ceiling: AbsoluteDeadline | undefined,
+  deprecated: (name: "timeout-ms" | "deadline-option", call: string) => void,
+  call: string,
+): AbsoluteDeadline | undefined {
+  const { timeout, deadline, timeoutMs } = given;
+  if (timeout != null) {
+    if (deadline != null || timeoutMs != null)
+      throw new Error(
+        "give timeout alone: deadline and timeoutMs are its deprecated forms, not limits beside it",
+      );
+    return timeoutDeadline(timeout, ceiling);
+  }
+  if (deadline != null && timeoutMs != null)
+    throw new Error("an operation cannot specify both deadline and timeoutMs");
+  if (timeoutMs != null) {
+    const bounded = deadlineWithin(timeoutMs, ceiling);
+    deprecated("timeout-ms", call);
+    return bounded;
+  }
+  if (deadline == null) return ceiling;
+  // A copy: the object given may be `wf.deadline`, whose `unixMilliseconds` reports each read.
+  const own = { unixMilliseconds: deadline.unixMilliseconds };
+  assertDeadlineValue(own);
+  deprecated("deadline-option", call);
+  return earlierDeadline(own, ceiling);
+}
+
+/** The deadline `timeout` sets from now, never past `ceiling`; `ceiling` for `false`. */
+export 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);

package/src/decisions/directory.ts

@@ -14,13 +14,7 @@ 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 type { RunEventBody } from "../run-event-log";
 import {
@@ -41,6 +35,8 @@ export type DecisionScope = {
   add?(cancel: (reason: string) => Promise<unknown>): () => void;
   /** The workflow stage it is asked in. */
   stage?: string;
+  /** The spec gave a deprecated form of `timeout`. */
+  deprecated?(name: "timeout-ms" | "deadline-option", call: string): void;
 };
 
 type PreparedCall = {
@@ -133,10 +129,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(
+      { timeout: spec.timeout, deadline: spec.deadline },
+      scope.deadline,
+      (name, call) => scope.deprecated?.(name, call),
+      "on decide",
+    );
     assertDeadline(deadline);
     const slot = this.#slots.length;
     this.#slots.push(undefined);

package/src/deprecations.ts

@@ -0,0 +1,177 @@
+/**
+ * Every name deprecated before 0.1.0, with what replaces it: each is logged once per attempt it is
+ * used in, so a continued or woken run logs it again, and removed one beta after the beta that
+ * deprecated it (story 039).
+ */
+export const DEPRECATIONS = {
+  labels: {
+    old: "an agent's labels option",
+    instead: "drop them: nothing reads an agent's labels",
+  },
+  whenToUse: { old: "meta.whenToUse", instead: "drop it: nothing reads it" },
+  "stage-receive": {
+    old: "a stage around wf.receive()",
+    instead: "wait with wf.race(name, …), which is recorded under its name, outside a stage",
+  },
+  isAnswered: { old: "isAnswered(outcome)", instead: "check outcome.answered" },
+  defineExecutableWorkflow: {
+    old: "defineExecutableWorkflow",
+    instead: "use defineWorkflow, with meta and run beside prepare",
+  },
+  "call-id": {
+    old: "the id of one run, start, compact or set",
+    instead:
+      "drop it: a later attempt doesn't know it, and a stage keeps a call from running twice",
+  },
+  "turn-source": {
+    old: "a started turn as a wait's branch",
+    instead: "name the agent, { done: agent }, which has at most one started turn",
+  },
+  "turn-is": { old: "turn.is(e)", instead: "use agent.is(e)" },
+  "test-reply": {
+    old: "reply.… in a test's script",
+    instead: "use noAnswer.…, the same calls: a reply answers, these end a turn without an answer",
+  },
+  "message-silent": {
+    old: "message.silent() in a test's message script",
+    instead: "return nothing, which ends the turn without a reply",
+  },
+  "message-fail": {
+    old: "message.fail() in a test's message script",
+    instead: "return noAnswer.failed(reason), which fails the turn as a failed harness does",
+  },
+  "test-event-id": {
+    old: "an event's id in a test",
+    instead: "give it as eventId, as awf emit --event-id does",
+  },
+  "run-stopped": { old: "run.stopped", instead: 'read run.ending, whose kind is "stopped"' },
+  "run-parked": { old: "run.parked", instead: 'read run.ending, whose kind is "parked"' },
+  "colon-key": {
+    old: "a key with a colon",
+    instead: (key: string) =>
+      `${key === "" ? "use - in its place" : `name it ${key.replaceAll(":", "-")}`}: a colon is kept for awf's own event names`,
+  },
+  "agents-stop": {
+    old: "wf.agents.stop(key)",
+    instead: "call close(reason?) on the agent's ref",
+  },
+  "fork-runtime": {
+    old: "a fork's own placement, metered or effort",
+    instead:
+      "give them in its runtime, as open does: fork({ key, runtime: { placement, metered, effort } })",
+  },
+  "timeout-ms": {
+    old: "timeoutMs",
+    instead: 'give timeout, a Duration such as "90s" or "10m"',
+  },
+  "deadline-option": {
+    old: "a deadline: { unixMilliseconds } option",
+    instead: 'give timeout: a Date, or a Duration such as "20m"',
+  },
+  "nudge-deadline": {
+    old: "nudge.deadline",
+    instead: "drop it: the turn's timeout bounds its check-ins",
+  },
+  "keep-alive-timeout-ms": {
+    old: "keepAlive.timeoutMs",
+    instead: 'give keepAlive.window, a Duration such as "90s"',
+  },
+  "run-deadline-ms": {
+    old: "wf.deadline.unixMilliseconds",
+    instead: "wf.deadline is a Date: read wf.deadline.getTime()",
+  },
+  "stall-ms": { old: "a test's stallMs", instead: 'give stall, a Duration such as "2s"' },
+  "test-args": {
+    old: "testWorkflow(workflow, args, options)",
+    instead: "give args among the options: testWorkflow(workflow, { args, … })",
+  },
+  "test-recorded": { old: "a test's recorded", instead: "give it as earlier: { stages }" },
+  "test-mailbox": { old: "a test's mailbox", instead: "give it as earlier: { mailbox }" },
+  "to-code": {
+    old: 'to: "code"',
+    instead: (key: string) =>
+      `declare "${key}:reply": ParticipantReply in events and connect it without to: the code takes its messages as ${key}:reply`,
+  },
+  "undeclared-ended": {
+    old: "start() for an agent whose end isn't declared",
+    instead: (key: string) => {
+      const named = key.replaceAll(":", "-");
+      const declare = `declare "${named}:ended": AgentEnded in events: its end then arrives as ${named}:ended, not agent:ended`;
+      return key.includes(":")
+        ? `rename the key ${named}, which can name its end, and ${declare}`
+        : declare;
+    },
+  },
+  "participant-is": {
+    old: "is(e) on a participant",
+    instead: 'read e.name === "{key}:reply", declared in events',
+  },
+  "test-participant-reply": {
+    old: 'a scripted { name: "participant:reply", from } in a test',
+    instead: 'name the declared event, { name: "{key}:reply", data }',
+  },
+  "send-event-id": {
+    old: "awf send --event-id",
+    instead:
+      'use awf emit {run} {key}:reply \'{"text":…,"author":…}\' --event-id {id}, with {key}:reply declared in the workflow\'s events',
+  },
+  "pane-layout": {
+    old: "an agent's layout",
+    instead:
+      "give pane: { tab, front } or pane: { beside, side, front }; the workspace is the operator's, awf run --workspace, and the session AWF_HERDR_SESSION",
+  },
+  "keep-pane": {
+    old: "an agent's keepPane",
+    instead: "drop it: keeping panes is the operator's, awf run --keep-panes",
+  },
+  "duration-ms": {
+    old: "a duration in ms",
+    instead: (value: string) =>
+      `give ${Number.parseInt(value, 10) / 1000}s: a duration is a decimal and s, m, h or d`,
+  },
+  "wait-seconds": {
+    old: "a bare number for --wait",
+    instead: (value: string) => `give a duration, --wait ${value}s`,
+  },
+} as const satisfies Record<
+  string,
+  { old: string; instead: string | ((subject: string) => string) }
+>;
+
+export type Deprecated = keyof typeof DEPRECATIONS;
+
+/** One attempt's deprecated uses: each name said once, as a warning in the run's log. */
+export class RunDeprecations {
+  /** Each name said, with its subject where it has one: each key with a colon is named. */
+  readonly #said = new Set<string>();
+  /** The attempt has ended: an outcome kept past it reports to no log. */
+  #settled = false;
+
+  constructor(private readonly warn: (text: string) => void) {}
+
+  /** `subject`, where given, is what was used, and each subject is said once. */
+  used(name: Deprecated, subject?: string): void {
+    const said = subject === undefined ? name : `${name}\0${subject}`;
+    if (this.#said.has(said)) return;
+    this.#said.add(said);
+    this.warn(deprecationLine(name, subject));
+  }
+
+  settle(): void {
+    this.#settled = true;
+  }
+
+  /** As `used`, for a name the contract reports by its own spelling; one not listed is ignored. */
+  reported = (name: unknown): void => {
+    if (this.#settled) return;
+    if (typeof name === "string" && Object.hasOwn(DEPRECATIONS, name))
+      this.used(name as Deprecated);
+  };
+}
+
+/** The line a deprecated use logs. */
+export function deprecationLine(name: Deprecated, subject = ""): string {
+  const { old, instead } = DEPRECATIONS[name];
+  const named = subject === "" ? "" : `, ${subject},`;
+  return `awf: ${old}${named} is deprecated; ${typeof instead === "function" ? instead(subject) : instead}`;
+}