docs(agent): document the default pause deadline across the SDK and examples [SAP-3207]

.changeset/pause-deadline-docs.md

@@ -0,0 +1,9 @@
+---
+"@sapiom/agent": patch
+---
+
+Document the pause deadline on `pauseUntilSignal`, `PauseUntilSignalDirective.timeoutMs` and `Pause.timeoutMs`.
+
+Forthcoming behavior change on the hosted engine, not in this package: a pause that omits `timeoutMs` waits indefinitely today, and will instead carry a 7-day deadline once the engine change for SAP-3207 is deployed. Past that deadline the run is finalized as failed rather than parking silently, carrying the engine's pause-timeout error, so a run that used to hang forever will surface as a failure. Pass an explicit `timeoutMs` on a signal pause that must outlive a week, such as a human approval gate; a pause on a dispatched child agent needs none, since the engine waives the deadline while the child is alive. `run_local` is unaffected either way: it never applies or enforces a pause deadline, it auto-resumes every pause immediately.
+
+This package ships documentation only, with no type, signature or runtime change.

examples/approval-chain/AGENTS.md

@@ -11,13 +11,15 @@ went silent). Inside a step's `run`, Sapiom capabilities are pre-auth'd on
 ## The sign-off spine
 
 - **`present`** records the current gate as `pending`, emails the approver, then
-  returns `pauseUntilSignal({ signal: "approval.decision", resumeStep: "decide", correlationId: ctx.executionId })`.
-  It carries a static `pause: { signal, resumeStep: "decide" }` annotation — the
-  build-time graph edge that must match the directive. **No `timeoutMs`:** the
-  engine's paused-run reaper *terminates* a lapsed pause (`PauseTimeoutError`)
-  instead of resuming it, so a gate deadline would hard-fail a slow approval and
-  skip `escalate`. The gates wait indefinitely; the reminder/escalation cadence
-  comes from the signal (see below), never the engine deadline.
+  returns `pauseUntilSignal({ signal: "approval.decision", resumeStep: "decide", correlationId: ctx.executionId, timeoutMs: GATE_PAUSE_TIMEOUT_MS })`.
+  It carries a static `pause: { signal, resumeStep: "decide" }` annotation, the
+  build-time graph edge that must match the directive. **A one-year `timeoutMs`
+  (`GATE_PAUSE_TIMEOUT_MS`):** the engine's paused-run reaper *terminates* a lapsed
+  pause (`PauseTimeoutError`) instead of resuming it, so a short gate deadline would
+  hard-fail a slow approval and skip `escalate`. Omitting `timeoutMs` does not avoid
+  that: a pause with no deadline inherits the engine's 7-day default. The year is an
+  explicit backstop; the reminder/escalation cadence comes from the signal (see
+  below), never from the deadline.
 - **`decide`** reads the approval payload **directly as its `run` input**. Safe
   default: only an explicit `{ decision: "approve" }` advances; `reject`
   compensates; `timeout` escalates; anything else (including a `run_local` resume

examples/approval-chain/README.md

@@ -52,13 +52,20 @@ The canonical chain state lives in `ctx.shared` (it survives every pause). When
 Postgres table (`approval_chain_ledger`) via `ctx.sapiom.database` — a best-effort
 external audit copy that never blocks the chain.
 
-## Reminders, escalation, and why the gates wait forever
+## Reminders, escalation, and why the gates wait a year
 
-Each gate pauses **indefinitely** at $0 — it carries no pause `timeoutMs`. That is
-deliberate: the engine has a paused-run reaper that *terminates* a lapsed pause
-with a `PauseTimeoutError` (it does not resume the step), so a deadline here would
-silently fail any approval slower than the deadline and never run the graceful
-`escalate` step. A legitimately slow approver must not lose the run.
+Each gate pauses at $0 under a deliberately long deadline: `GATE_PAUSE_TIMEOUT_MS`,
+one year. The engine has a paused-run reaper that *terminates* a lapsed pause with a
+`PauseTimeoutError` (it does not resume the step), so a short deadline here would
+silently fail any approval slower than it and never run the graceful `escalate` step.
+A legitimately slow approver must not lose the run.
+
+Omitting `timeoutMs` is not the way to get that. A pause with no deadline inherits the
+engine's 7-day default, which hard-fails a two-week approval exactly the same way. One
+year is the explicit opt-out, and it stays a terminal deadline: an approval that
+outlives it is failed by the sweep like any other, not resumed. The year is picked so
+no realistic approver reaches it, while an abandoned chain still lands in a terminal
+state instead of parking in the paused table forever.
 
 Reminders and escalation are therefore driven entirely by the `approval.decision`
 signal, not by an engine deadline:
@@ -70,9 +77,10 @@ signal, not by an engine deadline:
   walks `remind` → … → `escalate` for free.
 
 `maxReminders` (default 2) bounds how many reminder ticks a gate takes before it
-escalates. (The mirror template `wait-for-webhook` *wants* the terminal timeout and
-so opts into `timeoutMs`; this chain wants a reminder, so it must not — don't add a
-gate `timeoutMs` back without switching to that terminal model.)
+escalates. (The mirror template `wait-for-webhook` *wants* a short terminal timeout and
+sizes `timeoutMs` to the callback window; this chain wants a reminder loop, so its
+deadline is a backstop, not a cadence. Don't shorten the gate `timeoutMs` toward the
+reminder interval without switching to that terminal model.)
 
 Input:
 

examples/approval-chain/index.ts

@@ -50,18 +50,25 @@ import { z } from "zod/v4";
  * approver and re-pause, up to `maxReminders`, after which the gate escalates. An
  * explicit `{ decision: "timeout" }` escalates immediately.
  *
- * The gates pause **indefinitely** (no `timeoutMs`) on purpose. The engine has a
- * paused-run reaper: a `timeoutMs` sets `pausedUntil`, and a background sweep
- * *terminates* the run with a `PauseTimeoutError` once it lapses — it does NOT
- * resume the step, so it would never reach `decide`/`remind`/`escalate`. Handing a
- * signal pause a `reminderMs`-sized `timeoutMs` (as an earlier version did) would
- * therefore hard-fail any approval slower than the reminder interval, bypassing
- * the graceful `escalate` step entirely. So reminders/escalation are driven purely
- * by the signal convention: the run-detail one-click Approve/Reject, a cron that
- * fires `remind`/`timeout` on a schedule, or a `run_local` auto-resume — never the
- * engine's pause deadline. (`wait-for-webhook` is the mirror image: it *wants* that
- * terminal timeout, so it opts into `timeoutMs`; this chain wants a reminder, so it
- * must not.) Do not add `timeoutMs` here without moving to that terminal model.
+ * The gates carry a deliberately long `GATE_PAUSE_TIMEOUT_MS` (one year), and the
+ * value is load-bearing. The engine has a paused-run reaper: `timeoutMs` sets
+ * `pausedUntil`, and a background sweep *terminates* the run with a
+ * `PauseTimeoutError` once it lapses. It does NOT resume the step, so a lapsed
+ * gate never reaches `decide`/`remind`/`escalate`. Handing a signal pause a
+ * `reminderMs`-sized `timeoutMs` (as an earlier version did) would hard-fail any
+ * approval slower than the reminder interval, bypassing the graceful `escalate`
+ * step entirely, and omitting `timeoutMs` is no longer an escape: a pause with no
+ * deadline now inherits the engine's 7-day default, which does the same damage on
+ * a one-week horizon. One year is the explicit opt-out, and it is still a terminal
+ * deadline: an approval that outlives it is failed by the sweep like any other,
+ * not resumed. The year is picked so no realistic approver reaches it, while an
+ * abandoned chain still lands in a terminal state instead of parking forever. Reminders and escalation stay driven purely by the signal
+ * convention: the run-detail one-click Approve/Reject, a cron that fires
+ * `remind`/`timeout` on a schedule, or a `run_local` auto-resume, never the pause
+ * deadline. (`wait-for-webhook` is the mirror image: it *wants* a short terminal
+ * timeout and opts into one; this chain wants a reminder loop, so its deadline is
+ * a backstop rather than a cadence.) Do not shorten it toward the reminder
+ * interval without moving to that terminal model.
  *
  * ── Chain state ────────────────────────────────────────────────────────────────
  * The canonical chain state — which gate we're on, who has approved, the full
@@ -86,6 +93,15 @@ const APPROVAL_SIGNAL = "approval.decision";
 /** Reminders sent before a silent gate escalates. */
 const DEFAULT_MAX_REMINDERS = 2;
 
+// An explicit, deliberately long gate deadline. A pause with no `timeoutMs` gets
+// the hosted engine's 7-day default, and a lapsed deadline *terminates* the run
+// instead of resuming the step, which would hard-fail any approval slower than a
+// week and skip `escalate` entirely. One year is the opt-out, and it is still
+// terminal: an approval that outlives it is failed too. The year is picked so no
+// realistic approver reaches it, while an abandoned chain still lands in a
+// terminal state. Reminders and escalation come from the signal, not this value.
+const GATE_PAUSE_TIMEOUT_MS = 365 * 24 * 60 * 60 * 1000;
+
 /** Postgres table the durable ledger appends to. */
 const LEDGER_TABLE = "approval_chain_ledger";
 
@@ -498,17 +514,18 @@ const present = defineStep({
     // pause is kept on purpose: an approver IS assigned, so somebody can resume
     // it, and the run detail ships one-click Approve/Reject.
     //
-    // NO `timeoutMs`: the engine's paused-run reaper *terminates* a lapsed pause
-    // (PauseTimeoutError) rather than resuming it, so a deadline here would
-    // silently fail any approval slower than the deadline and skip `escalate`
-    // entirely. The reminder/escalation loop is driven by the `approval.decision`
-    // signal (one-click UI, a cron firing `remind`/`timeout`, or a `run_local`
-    // auto-resume) — never the engine deadline. See the header note before adding
-    // one back.
+    // `GATE_PAUSE_TIMEOUT_MS` is load-bearing, not decoration: a lapsed deadline
+    // *terminates* the run (PauseTimeoutError) rather than resuming it, so the
+    // engine's 7-day default would silently fail any approval slower than a week
+    // and skip `escalate`. The reminder/escalation loop is driven by the
+    // `approval.decision` signal (one-click UI, a cron firing `remind`/`timeout`,
+    // or a `run_local` auto-resume), never by the deadline. Read the header note
+    // before shortening it or dropping it.
     return pauseUntilSignal({
       signal: APPROVAL_SIGNAL,
       resumeStep: "decide",
       correlationId: ctx.executionId,
+      timeoutMs: GATE_PAUSE_TIMEOUT_MS,
     });
   },
 });
@@ -517,8 +534,8 @@ const decide = defineStep({
   name: "decide",
   next: ["present", "remind", "finalize", "compensate", "escalate"],
   // `payload` IS the approval signal body (or empty on a `remind` / `run_local`
-  // auto-resume — the gates never carry a pause `timeoutMs`, so the engine reaper
-  // never lands here; see `present`).
+  // auto-resume). The gates carry a one-year `timeoutMs`, so in practice the
+  // deadline sweep never lands here; see `present`.
   async run(payload: ApprovalDecision, ctx: Ctx) {
     const approvers = must(ctx.shared.get("approvers"), "approvers");
     const gateIndex = must(ctx.shared.get("gateIndex"), "gateIndex");
@@ -614,12 +631,13 @@ const remind = defineStep({
     });
 
     // Re-suspend on the same gate until a decision (or the next reminder tick).
-    // As in `present`, no `timeoutMs` — the reminder cadence comes from the signal
-    // convention, not the engine's (terminal) pause deadline.
+    // As in `present`, the same one-year backstop: the reminder cadence comes from
+    // the signal convention, not from the engine's (terminal) pause deadline.
     return pauseUntilSignal({
       signal: APPROVAL_SIGNAL,
       resumeStep: "decide",
       correlationId: ctx.executionId,
+      timeoutMs: GATE_PAUSE_TIMEOUT_MS,
     });
   },
 });

examples/durable-backfill/index.ts

@@ -514,6 +514,9 @@ const processStep = defineStep({
       });
       return goto("process", {});
     }
+    // No `timeoutMs` on purpose: the engine's 7-day default is the right ceiling
+    // for a heartbeat. A schedule that has not ticked in a week has stopped, and
+    // failing the backfill loudly beats leaving it parked mid-cursor forever.
     return pauseUntilSignal({
       signal: HEARTBEAT,
       resumeStep: "process",

examples/human-in-the-loop/index.ts

@@ -54,6 +54,15 @@ const APPROVAL_SIGNAL = "approval.decision";
 /** The signal a candidate fires to accept or decline a provisional offer. */
 const CONFIRM_SIGNAL = "candidate.confirm";
 
+/**
+ * Explicit deadline for a human gate, one year. A pause with no `timeoutMs`
+ * inherits the engine's 7-day default, and a lapsed deadline *terminates* the
+ * run rather than resuming it, so the default would hard-fail any approval
+ * slower than a week. Long enough that a slow approver never loses the run,
+ * finite enough that an abandoned one still reaches a terminal state.
+ */
+const GATE_PAUSE_TIMEOUT_MS = 365 * 24 * 60 * 60 * 1000;
+
 // ─────────────────────────────────────────────────────────────── shapes ──
 /** String-only config bag (matches how templates receive their `config`). */
 type Config = Record<string, string>;
@@ -417,6 +426,7 @@ const notifyApprover = defineStep({
       signal: APPROVAL_SIGNAL,
       resumeStep: "onDecision",
       correlationId: ctx.executionId,
+      timeoutMs: GATE_PAUSE_TIMEOUT_MS,
     });
   },
 });
@@ -500,6 +510,7 @@ const offer = defineStep({
       signal: CONFIRM_SIGNAL,
       resumeStep: "resolve",
       correlationId: ctx.executionId,
+      timeoutMs: GATE_PAUSE_TIMEOUT_MS,
     });
   },
 });

examples/pr-review-bot/index.ts

@@ -383,6 +383,9 @@ const watch = defineStep({
     }
 
     // Suspend at $0 until the webhook fires SIGNAL for this correlationId.
+    // No `timeoutMs` on purpose: the engine's 7-day default is the right ceiling
+    // here. A PR event that has not arrived in a week is not coming, and a
+    // terminal PauseTimeoutError beats a run parked on a dead webhook.
     return pauseUntilSignal({
       signal: SIGNAL,
       resumeStep: "review",

examples/proposal-generator/index.ts

@@ -66,6 +66,15 @@ import { z } from "zod/v4";
 /** The signal a human fires to approve or reject the drafted proposal. */
 const DECISION_SIGNAL = "proposal.decision";
 
+/**
+ * Explicit deadline for a human gate, one year. A pause with no `timeoutMs`
+ * inherits the engine's 7-day default, and a lapsed deadline *terminates* the
+ * run rather than resuming it, so the default would hard-fail any approval
+ * slower than a week. Long enough that a slow approver never loses the run,
+ * finite enough that an abandoned one still reaches a terminal state.
+ */
+const GATE_PAUSE_TIMEOUT_MS = 365 * 24 * 60 * 60 * 1000;
+
 /** Package the sandbox installs to lay out the PDF (pure JS, no native deps). */
 const PDF_PACKAGE = "pdf-lib@1.17.1";
 
@@ -612,6 +621,7 @@ const review = defineStep({
       signal: DECISION_SIGNAL,
       resumeStep: "onDecision",
       correlationId: ctx.executionId,
+      timeoutMs: GATE_PAUSE_TIMEOUT_MS,
     });
   },
 });

examples/scheduled-compliance-audit/index.ts

@@ -58,6 +58,15 @@ const MAX_BODY_CHARS = 2000;
 /** The signal a human fires to approve or reject the attestation. */
 const SIGNOFF_SIGNAL = "attestation.signoff";
 
+/**
+ * Explicit deadline for a human gate, one year. A pause with no `timeoutMs`
+ * inherits the engine's 7-day default, and a lapsed deadline *terminates* the
+ * run rather than resuming it, so the default would hard-fail any approval
+ * slower than a week. Long enough that a slow approver never loses the run,
+ * finite enough that an abandoned one still reaches a terminal state.
+ */
+const GATE_PAUSE_TIMEOUT_MS = 365 * 24 * 60 * 60 * 1000;
+
 // ─────────────────────────────────────────────────────────────── shapes ──
 /** A resource whose current state should be audited against the policy. */
 interface ResourceRef {
@@ -397,6 +406,7 @@ const review = defineStep({
       signal: SIGNOFF_SIGNAL,
       resumeStep: "onSignoff",
       correlationId: ctx.executionId,
+      timeoutMs: GATE_PAUSE_TIMEOUT_MS,
     });
   },
 });

examples/wait-for-webhook/AGENTS.md

@@ -7,7 +7,7 @@ This project defines exactly one Sapiom agent in `index.ts` — **Wait-for-Webho
 - **`kickoff`** registers `{ executionId, signal, correlationId: ctx.executionId }` with the external job, then returns `pauseUntilSignal({ signal, resumeStep: "decide", correlationId: ctx.executionId })`. It also carries a static `pause: { signal, resumeStep: "decide" }` annotation — the build-time graph edge that must match the directive.
 - **`decide`** reads the callback payload **directly as its `run` input** — that's the signal payload the external world delivered. Everything else (config, job params, ids) is read back from `ctx.shared`, which survives the pause.
 - `pauseUntilSignal` is a **runtime primitive, not a metered capability**. The only billed call is the model summary in `decide` (`ctx.sapiom.llm.run`, the live x402 path).
-- **Optional deadline.** The pause waits indefinitely by default. Passing `timeoutMs` caps it: with no callback in that window, the engine's deadline sweep fails the run (a pause-timeout terminal state) instead of parking it forever. `kickoff` reads it from `config.CALLBACK_TIMEOUT_MS` via `parseTimeoutMs` — absent ⇒ indefinite wait; invalid ⇒ a loud throw at `kickoff` (a silently-dropped cap would defeat the point).
+- **Optional deadline.** Passing `timeoutMs` sizes the wait to the callback window: with no callback in it, the engine's deadline sweep fails the run (a pause-timeout terminal state). Omitting it does not mean waiting forever, it means inheriting the engine's 7-day default, which is the same terminal state on a slower horizon. `kickoff` reads the value from `config.CALLBACK_TIMEOUT_MS` via `parseTimeoutMs` — absent ⇒ the engine default; invalid ⇒ a loud throw at `kickoff` (a silently-dropped cap would defeat the point).
 
 ## Authoring
 

examples/wait-for-webhook/README.md

@@ -1,7 +1,7 @@
 # Wait-for-Webhook
 
 Durable pause/resume around any slow external callback. The run starts a slow
-external async job, then **suspends indefinitely at $0** until a webhook/callback
+external async job, then **suspends at $0** until a webhook/callback
 fires — no polling loop, no held worker, no billed idle time — and resumes
 exactly where it left off when the external world is ready.
 
@@ -31,8 +31,9 @@ With no `CALLBACK_REGISTER_URL` (or `DRY_RUN` set), `kickoff` runs offline via i
 
 ## Capping the wait (optional deadline)
 
-By default the pause waits **indefinitely** at $0 — that's the whole point. But a
-callback that never arrives would park the run forever. To bound it, set
+The pause costs $0 for as long as it lasts, which is the whole point, but it is not
+unbounded: a pause with no `timeoutMs` inherits the engine's **7-day default**
+deadline. To size the wait to your callback window instead, set
 `config.CALLBACK_TIMEOUT_MS` to a positive number of milliseconds:
 
 ```json
@@ -41,10 +42,11 @@ callback that never arrives would park the run forever. To bound it, set
 
 If no callback fires within that window, the engine's deadline sweep ends the run
 with a pause-timeout failure — an honest terminal state ("no callback within N")
-instead of a run parked forever. Leave `CALLBACK_TIMEOUT_MS` unset to keep the
-default indefinite wait. A non-numeric or non-positive value is rejected at
-`kickoff` (a silently-ignored cap would just reintroduce the forever-park it's
-meant to prevent).
+instead of a run parked forever. Leave `CALLBACK_TIMEOUT_MS` unset to fall back on
+the engine's 7-day default, which produces the same terminal state on a slower
+horizon. A non-numeric or non-positive value is rejected at `kickoff` (a
+silently-ignored cap would just reintroduce the forever-park it's meant to
+prevent).
 
 ## Run it with Claude + the Sapiom MCP