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

package/src/agent-cli/client.ts

@@ -0,0 +1,115 @@
+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";
+
+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,
+  request: R,
+  /** Null waits as long as the engine takes, as a tool call does: it answers once the call settles. */
+  timeoutSeconds: number | null = 30,
+  connect: (endpoint: string) => Socket = createConnection,
+): Promise<ResponseFor[R["command"]]> {
+  type Response = ResponseFor[R["command"]];
+  if (timeoutSeconds !== null && (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)) {
+    return Promise.reject(new Error("control-plane timeout must be positive"));
+  }
+  const outgoing = Buffer.from(`${JSON.stringify(request)}\n`);
+
+  return new Promise<Response>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    let settled = false;
+    let connected = false;
+    const socket = connect(endpoint);
+    const lifetime =
+      timeoutSeconds === null
+        ? undefined
+        : setTimeout(
+            () => fail(new Error("control plane response timed out")),
+            timeoutSeconds * 1000,
+          );
+
+    const fail = (error: Error): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(lifetime);
+      socket.destroy();
+      reject(error);
+    };
+
+    socket.once("connect", () => {
+      connected = true;
+      socket.end(outgoing);
+    });
+    socket.on("data", (data) => {
+      if (settled) return;
+      const chunk = typeof data === "string" ? Buffer.from(data) : data;
+      bytes += chunk.byteLength;
+      if (bytes > MAX_RESPONSE_BYTES) {
+        fail(new Error("control-plane response exceeds the size limit"));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    socket.once("end", () => {
+      if (settled) return;
+      const frame = Buffer.concat(chunks).toString("utf8");
+      if (!frame.endsWith("\n") || frame.slice(0, -1).includes("\n")) {
+        fail(new Error("control plane returned an invalid response frame"));
+        return;
+      }
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(frame.slice(0, -1));
+      } catch {
+        fail(new Error("control plane returned invalid JSON"));
+        return;
+      }
+      const decoded = decodeResponseFor<R["command"]>(request.command, parsed);
+      if (!decoded.ok) {
+        fail(new Error(decoded.error));
+        return;
+      }
+      settled = true;
+      clearTimeout(lifetime);
+      resolve(decoded.value);
+    });
+    socket.once("error", (error) =>
+      fail(connected ? error : new NotSentError(error.message, { cause: error })),
+    );
+    socket.once("close", () => {
+      if (!settled) fail(new Error("control plane closed without a response"));
+    });
+  });
+}

package/src/agent-launcher.ts

@@ -1,9 +1,11 @@
-import { chmod, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
-import { createRequire } from "node:module";
-import { basename, dirname, join, resolve } from "node:path";
+import { chmod, mkdir, realpath, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { type AgentDoor, shellQuote } from "@agentswf/sandbox";
 
-/** bun loads the `.env` of the directory it starts in: an agent's, which is none of `wf`'s. */
+const AGENT_CLI = fileURLToPath(new URL("./agent-cli/cli.ts", import.meta.url));
+
+/** bun loads the `.env` of the directory it starts in: an agent's, which is none of `wfa`'s. */
 const NO_ENV = "--no-env-file";
 
 /**
@@ -27,19 +29,18 @@ export async function installAgentLauncher(
    */
   sessionEnv?: string,
 ): Promise<string> {
-  const command = await resolveAgentCommand();
-  return writeLauncher(directory, [process.execPath, NO_ENV, command], endpoint, sessionEnv);
+  return writeLauncher(directory, [process.execPath, NO_ENV, AGENT_CLI], endpoint, sessionEnv);
 }
 
 /**
- * A sandboxed agent's door: the same launcher, running the bundled `wf` with the host's bun by
+ * A sandboxed agent's door: the same launcher, running the bundled `wfa` with the host's bun by
  * its real path, since a sandbox reads neither the workspace's sources nor bun's links under `~`.
  * A box copies `boxScript` to the launcher's path, which runs the bundle with the box's own bun.
  */
 export async function installSandboxedDoor(
   directory: string,
   endpoint: string,
-  /** The bundled `wf`'s source, written beside the launcher. */
+  /** The bundled `wfa`'s source, written beside the launcher. */
   source: string,
   sessionEnv?: string,
 ): Promise<AgentDoor> {
@@ -50,7 +51,7 @@ export async function installSandboxedDoor(
   const socket = join(real, basename(endpoint));
   // In the agent's own directory: bun will not load a module from the control plane's, which is
   // not listable so that no agent can find another's socket.
-  const bundle = join(real, "wf.js");
+  const bundle = join(real, "wfa.js");
   await writeFile(bundle, source, { mode: 0o500 });
   const launcher = await writeLauncher(real, [bun, NO_ENV, bundle], socket, sessionEnv);
   return {
@@ -64,12 +65,12 @@ export async function installSandboxedDoor(
 }
 
 /**
- * `wf` as one file's source, which a sandbox can read where it cannot read this workspace. Built by
+ * `wfa` as one file's source, which a sandbox can read where it cannot read this workspace. Built by
  * a `bun build` of its own: in process, the bundler resolved packages against the test runner's
  * state and missed the workspace's links.
  */
 export async function buildAgentBundle(): Promise<string> {
-  const entry = await resolveAgentCommand();
+  const entry = AGENT_CLI;
   const built = Bun.spawn({
     cmd: [process.execPath, "build", entry, "--target=bun"],
     cwd: dirname(entry),
@@ -81,7 +82,7 @@ export async function buildAgentBundle(): Promise<string> {
     new Response(built.stdout).text(),
     new Response(built.stderr).text(),
   ]);
-  if (code !== 0) throw new Error(`could not bundle wf: ${stderr.trim().slice(0, 400)}`);
+  if (code !== 0) throw new Error(`could not bundle wfa: ${stderr.trim().slice(0, 400)}`);
   return bundle;
 }
 
@@ -93,7 +94,7 @@ async function writeLauncher(
 ): Promise<string> {
   await mkdir(directory, { recursive: true });
   await chmod(directory, 0o700);
-  const path = join(directory, "wf");
+  const path = join(directory, "wfa");
   // Not writable, so an agent that redirects into its own launcher fails rather than replacing its
   // only way to answer. A `chmod` still gets past it; a sandbox denies the write outright.
   await writeFile(path, launcherScript(command, endpoint, sessionEnv, path), { mode: 0o500 });
@@ -105,7 +106,7 @@ function launcherScript(
   command: readonly string[],
   endpoint: string,
   sessionEnv: string | undefined,
-  /** Its own path, which `wf` names in what it prints, as an agent must type it. */
+  /** Its own path, which `wfa` names in what it prints, as an agent must type it. */
   path: string,
 ): string {
   if (sessionEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(sessionEnv)) {
@@ -114,14 +115,3 @@ function launcherScript(
   const session = sessionEnv ? ` --session "\${${sessionEnv}:-}"` : "";
   return `#!/bin/sh\nexec ${command.map(shellQuote).join(" ")} --at ${shellQuote(endpoint)} --as ${shellQuote(path)}${session} "$@"\n`;
 }
-
-async function resolveAgentCommand(): Promise<string> {
-  const require = createRequire(import.meta.url);
-  const manifestPath = require.resolve("@agentswf/wf/package.json");
-  const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as {
-    bin?: string | Record<string, string>;
-  };
-  const relative = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.wf;
-  if (!relative) throw new Error("@agentswf/wf does not publish the wf command");
-  return resolve(dirname(manifestPath), relative);
-}

package/src/allowance-command.ts

@@ -4,24 +4,12 @@ import type {
   HarnessAllowance,
 } from "@agentswf/contract/records";
 import { HARNESS_NAMES, type Harness } from "@agentswf/harness";
-import { PLAN_BASIS, planPrice } from "./accounting/plans";
+import { planPrice } from "./accounting/plans";
 import { messageOf } from "./errors";
+import help from "./help/allowance.txt" with { type: "text" };
 import type { Out } from "./run-commands";
 
-export const allowanceUsage = [
-  "usage: awf allowance [harness...] [--json]",
-  "",
-  "What is left of each harness's plan, as the harness itself shows it: claude's /usage, codex's",
-  "/status, and cursor's /usage, read in a Herdr pane. Nothing asks a model. Every harness when",
-  `none is named: ${HARNESS_NAMES.join(", ")}.`,
-  "",
-  "A plan's monthly price is the vendor's list price as of the table's date, not what was",
-  `charged: ${PLAN_BASIS}.`,
-  "",
-  `--json prints one document, the interface for scripts, with the plan as the`,
-  "harness names it and no price; what it prints otherwise is for reading. A harness that could",
-  "not be read says why. Exits 0 once every harness was asked, 2 on a usage error.",
-].join("\n");
+export const allowanceUsage = help.trimEnd();
 
 export type AllowanceCommand = { harnesses: Harness[]; json: boolean } | "help";
 

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 },
@@ -107,7 +108,7 @@ export async function keepRecords(
     const unacknowledged =
       ending.kind === "completed" && attempt.run.record.events
         ? await readMailbox(dir).then(
-            // The event that started the run is `workflow.started`'s, taken or not.
+            // The event that started the run is `wf.started`'s, taken or not.
             (records) => {
               const state = foldMailbox(records);
               return state.unacknowledged.filter((id) => id !== state.started?.id).length;

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

@@ -21,7 +21,7 @@ export type MessagingHandler = Pick<
   "checkFinish" | "peers" | "send" | "reply" | "owing"
 >;
 
-/** `wf` accepts a 1 MiB value; escaped into the request's JSON it can double, plus the envelope. */
+/** `wfa` accepts a 1 MiB value; escaped into the request's JSON it can double, plus the envelope. */
 const MAX_RESULT_REQUEST_BYTES = 2 * 1024 * 1024 + 4 * 1024;
 const MAX_CONTROL_CONNECTIONS = 64;
 const CONNECTION_TIMEOUT_SECONDS = 30;
@@ -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);