@coder/ai-sdk-agent 0.6.1 → 0.6.3

package/README.md

@@ -214,7 +214,9 @@ conversation with server‑side history). `agent.chatId` is the current chat id.
 - `agent.interrupt({ signal? })` — interrupt an in‑flight generation.
 - `agent.archive({ signal? })` — archive the underlying chat (cleanup; see [Cleanup](#cleanup)).
 - `agent.listModels()` — list the deployment's model configs, so you don't have to guess the `model` hint.
-- Resume a prior chat: `new CoderAgent({ …, chatId: "…" })`.
+- Resume a prior chat: `new CoderAgent({ …, chatId: "…" })` — see
+  [Durable workflows](#durable-workflows-persist-resume-recover) for the full
+  resumption how‑to.
 
 Interrupting is asynchronous on the server: `interrupt()` resolves as soon as the
 interrupt is acknowledged, and the run keeps winding down for a few seconds
@@ -322,19 +324,19 @@ for (const ev of events) {
 `timestamp` (`Date.now()` at observation — comparable to server‑side timestamps
 such as a message's `created_at`, for delivery‑lag measurements):
 
-| event            | when                                                | payload (besides `timestamp`)                                                                                                                                                           |
-| ---------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `http:request`   | a REST request is sent                              | `id` (correlates the pair), `method`, `path`                                                                                                                                            |
-| `http:response`  | response headers arrive (incl. non‑2xx, `ok:false`) | `id`, `method`, `path`, `status`, `ok`, `durationMs`                                                                                                                                    |
-| `http:error`     | the fetch itself rejects (network failure, abort)   | `id`, `method`, `path`, `message`, `durationMs`                                                                                                                                         |
-| `ws:dial`        | a stream connection attempt starts                  | `chatId`, `attempt` (1‑based, increments per redial), `url`                                                                                                                             |
-| `ws:open`        | the WebSocket handshake completes                   | `chatId`, `attempt`                                                                                                                                                                     |
-| `ws:event`       | a decoded stream event arrives                      | `chatId`, `attempt`, `event` (the decoded `ChatStreamEvent`, by reference — don't mutate)                                                                                               |
-| `ws:close`       | the connection ends (exactly one per dial)          | `chatId`, `attempt`, `code`/`reason` when the server/network closed it; absent when the reader closed it (settle, teardown, redial)                                                     |
-| `ws:error`       | a socket error or unparseable frame                 | `chatId`, `attempt`, `message`                                                                                                                                                          |
-| `ws:redial`      | a dropped connection is about to be redialed        | `chatId`, `attempt` (the ended connection), `consecutiveFailures`, `maxConsecutiveFailures`, `backoffMs`                                                                                |
-| `segment:start`  | a turn segment (one model round‑trip) starts        | `segment` (1‑based per model instance), `chatId` (absent before the first turn creates the chat)                                                                                        |
-| `segment:settle` | the segment ends (exactly one per start)            | `segment`, `chatId`, and: `status` + `finishReason` on a clean settle, `error` (`{name, message}`, plus `status` if the run still settled terminally) on failure, neither on a teardown |
+| event            | when                                                | payload (besides `timestamp`)                                                                                                                                                                         |
+| ---------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `http:request`   | a REST request is sent                              | `id` (correlates the pair), `method`, `path`                                                                                                                                                          |
+| `http:response`  | response headers arrive (incl. non‑2xx, `ok:false`) | `id`, `method`, `path`, `status`, `ok`, `durationMs`                                                                                                                                                  |
+| `http:error`     | the fetch itself rejects (network failure, abort)   | `id`, `method`, `path`, `message`, `durationMs`                                                                                                                                                       |
+| `ws:dial`        | a stream connection attempt starts                  | `chatId`, `attempt` (1‑based, increments per redial), `url`                                                                                                                                           |
+| `ws:open`        | the WebSocket handshake completes                   | `chatId`, `attempt`                                                                                                                                                                                   |
+| `ws:event`       | a decoded stream event arrives                      | `chatId`, `attempt`, `event` (the decoded `ChatStreamEvent`, by reference — don't mutate)                                                                                                             |
+| `ws:close`       | the connection ends (exactly one per dial)          | `chatId`, `attempt`, `code`/`reason` when the server/network closed it; absent when the reader closed it (settle, teardown, redial)                                                                   |
+| `ws:error`       | a socket error or unparseable frame                 | `chatId`, `attempt`, `message`                                                                                                                                                                        |
+| `ws:redial`      | a dropped connection is about to be redialed        | `chatId`, `attempt` (the ended connection), `consecutiveFailures`, `maxConsecutiveFailures`, `backoffMs`                                                                                              |
+| `segment:start`  | a turn segment (one model round‑trip) starts        | `segment` (1‑based per model instance), `chatId` (absent before the first turn creates the chat)                                                                                                      |
+| `segment:settle` | the segment ends (exactly one per start)            | `segment`, `chatId`, `durationMs`, and: `status` + `finishReason` on a clean settle, `error` (`{name, message}`, plus `status` if the run still settled terminally) on failure, neither on a teardown |
 
 Semantics worth knowing:
 
@@ -668,16 +670,154 @@ credentials — pass them alongside `client` if you construct one yourself.
 ## Workspaces & quota
 
 A `CoderAgent` is one server‑side chat, and — depending on its configuration and
-the deployment — a chat may provision a **Coder workspace** to run its tools. A
-deployment caps how many workspaces an account may run at once, so **N agents
-running concurrently can need N free workspace slots.** Past the cap, a turn can
-sit unscheduled and never settle. This is the most important operational fact when
-running many agents at once:
-
-- Keep your own concurrency below the deployment's workspace limit.
-- Set `requestTimeoutMs` so an unschedulable turn fails loudly instead of hanging.
-- `archive()` / `await using` each agent so finished chats stop holding resources.
-- For steps that don't need server‑side tools, prefer the provider — it never touches a workspace.
+the deployment — a chat may be backed by a **Coder workspace** that runs its
+tools. Workspaces are the scarce resource: a deployment budgets how many an
+account may run at once, so **N agents running concurrently can need N
+schedulable workspaces.** Past that bound, a turn can sit unscheduled and never
+settle. This section is the operational guide for running fleets of agents:
+how the binding works, how to size concurrency, what to clean up, and how to
+diagnose a chat that is stuck.
+
+### How a chat binds to a workspace
+
+- **One chat, at most one workspace, fixed at creation.** `workspaceId` is sent
+  as `workspace_id` when the chat is created; nothing can rebind it afterwards —
+  message and update requests carry no workspace field. To move work to another
+  workspace, start a new agent/chat.
+- **This SDK never provisions workspaces.** A `workspaceId` you pass must be an
+  existing workspace (provision one with
+  [`@coder/ai-sdk-sandbox`](../sandbox)'s `ensureCoderWorkspace`, the CLI, or
+  the v2 API). A chat created _without_ `workspaceId` can still come back
+  workspace‑backed — deployments may assign one server‑side; the SDK reads the
+  created chat's `workspace_id` and treats the chat as workspace‑backed from
+  then on (which matters for retry ownership, below).
+- **Chat cleanup does not release the workspace.** `archive()` soft‑hides the
+  chat only; the workspace keeps running until template autostop or an explicit
+  stop — and stopping releases only stop‑scoped quota; persistent resources
+  (disks, volumes) keep consuming their cost until the workspace is deleted.
+
+### Sizing a fleet
+
+The structural rule: **workspaces that must be running concurrently ≤
+schedulable workspaces.** With one workspace per chat — the common fleet shape,
+and what a deployment that auto‑assigns workspaces produces — that means
+concurrent chats ≤ schedulable workspaces. Chats explicitly bound to a shared
+`workspaceId` count that workspace once, so their concurrency is not
+quota‑bound — at the price of sharing one filesystem and tool environment,
+which is only acceptable within a single tenant / trust boundary.
+What counts as "schedulable" is a deployment property, not an SDK knob —
+whichever of these binds first:
+
+- **Workspace quota (premium deployments).** Templates declare per‑resource
+  costs; a user's budget is the sum of their groups' quota allowances, enforced
+  when a workspace build starts or stops. A start that would exceed the budget
+  **fails the build** (error code `INSUFFICIENT_QUOTA`, "insufficient quota"),
+  so the turn never gets its workspace — see
+  [resource quotas](https://coder.com/docs/admin/users/quotas). Note that a
+  _stopped_ workspace typically still consumes its persistent resources' cost,
+  so a fleet that only ever stops (never deletes) scratch workspaces converges
+  on a full budget.
+- **Infrastructure.** Without quotas there is no per‑user workspace limit by
+  default ([workspace lifecycle](https://coder.com/docs/user-guides/workspace-lifecycle)) —
+  the bound is provisioner throughput and cluster capacity, and exceeding it
+  looks like slow or failing builds rather than a crisp quota error.
+
+Practical sizing:
+
+- Read headroom before fanning out:
+  `GET /api/v2/organizations/{org}/members/{user}/workspace-quota` returns
+  `{ "credits_consumed": …, "budget": … }`. Quota is denominated in credits,
+  not slots: admit another workspace only while `budget − credits_consumed`
+  covers _that workspace's_ cost (the sum of its template's `daily_cost`
+  declarations). "Free slots = headroom ÷ cost" only holds for a homogeneous
+  fleet on one template; with mixed templates, size against each planned
+  workspace's own cost.
+- Keep fan‑out width within that headroom and queue the rest client‑side — an
+  unschedulable turn does not queue usefully on the server (see
+  [Preventing stuck turns](#preventing-stuck-turns)).
+- Reuse one bound workspace across sequential turns and sessions instead of
+  provisioning per request — the workspace is the expensive part, the chat is
+  cheap. Reuse only **within one tenant / trust boundary**: workspace‑bound
+  agents have file and shell tools, so a reused filesystem carries one
+  session's artifacts (and secrets) into the next — provision per tenant, or
+  securely reset a workspace before reassigning it.
+- Steps that don't need server‑side tools belong on the
+  [provider](../provider) — it never touches a workspace.
+
+### Autostop & cleanup
+
+Two lifetimes to manage, separately:
+
+- **Chats** — `archive()` / `await using` every agent ([Cleanup](#cleanup)), or
+  finished chats keep holding server resources.
+- **Workspaces** — rely on template‑level scheduling rather than manual
+  hygiene:
+  - **Autostop TTL.** Give fleet templates a default TTL long enough to survive
+    a normal session (including idle gaps between turns), short enough that a
+    leaked workspace stops burning running‑cost within hours — without
+    autostop, a leaked workspace pins its full quota until someone notices.
+    Note that stopping only releases the quota of resources that go away on
+    stop; persistent resources (disks, volumes) keep consuming their
+    `daily_cost`, so a scratch fleet that only ever stops still converges on a
+    full budget — pair the TTL with dormancy auto‑deletion or explicit
+    deletion. With [`@coder/ai-sdk-sandbox`](../sandbox), `stopAfter: "8h"`
+    sets the TTL (`ttl_ms`) at creation.
+  - **Activity bump** (default 1 h) extends a running workspace's deadline when
+    Coder detects sessions — check
+    [what counts as activity](https://coder.com/docs/user-guides/workspace-scheduling)
+    before assuming an agent's server‑side tool use keeps its workspace alive.
+  - **Dormancy / failure cleanup** reap abandoned and repeatedly‑failing
+    workspaces automatically — see
+    [template scheduling](https://coder.com/docs/admin/templates/managing-templates/schedule).
+
+### Preventing stuck turns
+
+The signature failure mode of an over‑committed fleet: the chat is created, the
+stream opens, and then — nothing. There is **no distinct "quota exceeded" error
+kind on the chat stream**; a chat whose workspace can't be scheduled surfaces
+either a generic turn error or, worse, a chat that sits in a non‑terminal
+status indefinitely. Defend in this order:
+
+1. **Set `requestTimeoutMs` — always, in fleets.** It is unbounded by default.
+   On expiry the call rejects with a `CoderChatError` (`kind: "timeout"`,
+   `retryable: true`) so your dispatcher gets its slot back, and a server‑side
+   interrupt is fired **best‑effort** — fire‑and‑forget, and unreachable when
+   the timeout lands before chat creation returned an id — so the run usually
+   stops, but is not guaranteed released ([Timeouts](#timeouts--cancellation)).
+   Pair it with reconciliation: periodically sweep for non‑terminal chats older
+   than your budget and interrupt/archive them.
+2. **Cap total wall‑clock** with `abortSignal: AbortSignal.timeout(…)` —
+   `requestTimeoutMs` bounds each segment, not a whole multi‑tool call.
+3. **Own the retries.** Workspace‑backed turns are **never auto‑retried**: the
+   SDK marks a stream‑loss error `isRetryable` only when the failed turn
+   created its chat _and_ had no workspace, no MCP servers, and no fresh
+   uploads ([Timeouts](#timeouts--cancellation)). Your dispatcher owns the
+   retry decision — and should re‑check quota headroom first, or it re‑queues
+   into the same wall.
+4. **Watch the fleet.** [`watchChats`](#watching-chats) yields status changes
+   for every chat **visible to the authenticated user** — with chats spread
+   across per‑tenant credentials, run one watcher per identity (or watch with
+   a credential that can see them all). Alert on chats sitting in a
+   non‑terminal status (e.g. `pending`) longer than your `requestTimeoutMs`.
+   Events alone aren't a complete monitor: reconnects resubscribe fresh (no
+   cursor or replay), so a chat already stuck before the watcher started — or
+   one that transitioned during a gap — never emits an event to start your
+   timer from. Seed and periodically reconcile against a chat listing
+   (`GET /api/experimental/chats`) instead of trusting the event stream alone.
+
+### Troubleshooting: unschedulable & stuck chats
+
+Wire [`onTransportEvent`](#observability) into fleet telemetry — the event
+sequence pinpoints _where_ a turn died:
+
+| symptom (transport events)                                                                                                                                                                          | likely cause                                                                                                                                                                                                                                                                                                 | fix                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `segment:start` and `ws:open` fired, initial status events, then silence — no `message_part`, no `segment:settle`                                                                                   | if the chat's status is `pending` (or its workspace build is `pending`/`failed`): the workspace can't be scheduled — quota exhausted, no free provisioner, failing template. If the status is `running` with a healthy build, it may just be a slow model/tool step — silence alone doesn't prove scheduling | check quota headroom (`workspace-quota` endpoint) and the workspace's build — a quota failure logs `INSUFFICIENT_QUOTA`; reclaim enough _credits_ for the planned build (stopping helps only for stop‑scoped costs — delete workspaces to reclaim persistent costs, or raise the group allowance) and set `requestTimeoutMs` so this fails loudly next time                                                               |
+| `segment:settle` carries `error: { name: "CoderChatError", message: "…requestTimeoutMs budget…" }`                                                                                                  | the per‑segment bound expired — wedged server, slow model, or an unschedulable workspace                                                                                                                                                                                                                     | inspect the workspace via the v2 API/UI: a `pending`/`failed` build means the row above; `running` means the turn was genuinely slow — raise `requestTimeoutMs` for long tool work                                                                                                                                                                                                                                        |
+| repeated `ws:redial` with `consecutiveFailures` climbing toward `maxConsecutiveFailures` (5; backoff 1 s → 2 s → 4 s → 8 s, ≈15 s of redialing without forward progress), then a `CoderStreamError` | the network path to the deployment is failing — not workspace scheduling (the server keeps generating through short gaps)                                                                                                                                                                                    | fix connectivity; mind retry ownership above — on workspace‑backed chats the error is `isRetryable: false`, so the replay decision is yours                                                                                                                                                                                                                                                                               |
+| `segment:settle` with `status: "error"` and an `error` payload                                                                                                                                      | the turn failed server‑side — a provider/model error, a tool failure, or a scheduling/build failure that terminated the turn instead of leaving it pending                                                                                                                                                   | the settle event's `error` carries only `{ name, message }` — branch on `kind` / `retryable` / `statusCode` by catching the thrown `CoderChatError`: at the `generate()` call site, or — for `stream()` — around stream consumption, since mid‑stream failures surface on the stream, not from `await agent.stream()` ([Handling errors](#handling-errors)); check the workspace build state to rule scheduling in or out |
+| turn settled `status: "requires_action"`, follow‑up messages queue forever                                                                                                                          | the loop ended on an unanswered client tool call                                                                                                                                                                                                                                                             | submit the stranded results or interrupt — see rule 4 under [Structured output](#structured-output); if a crash left the pause behind, reconcile effects first ([Make client tools crash-safe](#make-client-tools-crash-safe))                                                                                                                                                                                            |
+| `archive()` keeps returning 409 and rethrows after ~15 s                                                                                                                                            | the chat never settled server‑side — usually a stuck run still holding its workspace                                                                                                                                                                                                                         | `interrupt()` with a bounded signal, then re‑archive; if the run stays wedged, stop the workspace itself                                                                                                                                                                                                                                                                                                                  |
 
 ## Configuration
 
@@ -730,27 +870,710 @@ CoderAgent  (implements ai.Agent)
   revision that appends to an earlier message yields the appended suffix (rewrites that
   can't be expressed as deltas are safely suppressed).
 
-## Durable workflows (Vercel Workflow, step functions, …)
-
-`CoderAgent` talks to Coder over its own REST + WebSocket client, so it can't ride
-a `fetch`‑shim durability layer — each turn must run **inside** a durable step. A
-few rules keep it well‑behaved across replays:
-
-- **One turn per step.** Create the agent, run a single `generate()` (not
-  `stream()`, so the checkpointed value is the finished result), return.
-- **Don't persist the instance across steps.** Persist `agent.chatId` (a string)
-  and resume with `new CoderAgent({ …, chatId })` in the next step. Never persist
-  or log the token — read it from the environment in each step.
-- **Clean up in the step.** `await using` the agent (or `await agent.archive()` in
-  a `finally`) so a step that returns early doesn't abandon the chat.
-- **Bound each step.** Set `requestTimeoutMs` so a wedged turn fails the step (and
-  lets the workflow retry) instead of hanging the whole run.
-- **Mind concurrency vs. workspaces.** Keep fan‑out width under the deployment's
-  workspace cap — see [Workspaces & quota](#workspaces--quota).
-- **Use the provider for pure steps.** Steps that don't need server‑side tools
-  (plan / extract / synthesize) are cheaper and natively structured through
+## Durable workflows: persist, resume, recover
+
+How to run **one agent session across process boundaries** — queue jobs,
+durable‑workflow steps (Vercel Workflow, step functions, Temporal, …), cron
+ticks — and survive the crashes, stream drops, and timeouts in between. The
+mechanics this how‑to leans on are specified in [Sessions](#sessions),
+[Timeouts & cancellation](#timeouts--cancellation),
+[Handling errors](#handling-errors), and [Observability](#observability).
+
+Two facts make the pattern work:
+
+- **All chat state lives on the Coder server.** Messages, tool activity, the
+  run itself — none of it is in your process. The only durable thing a
+  workflow has to carry between steps is **`agent.chatId`: a string.**
+- **`CoderAgent` can't ride a `fetch`‑shim durability layer** (it talks REST +
+  WebSocket through its own client), so each turn runs **inside** a durable
+  step — and the checkpointed chat id is the thread between steps.
+
+Running example: a pipeline whose steps each run as their own job — possibly
+on another machine, hours apart, retried after failures.
+
+### Shape each step: one turn, then checkpoint
+
+```ts
+import { CoderAgent, type CoderTransportEvent } from "@coder/ai-sdk-agent";
+
+// Any durable KV your engine gives you: step state, a job row, a DB table.
+declare const checkpoints: {
+  get(workflowId: string): Promise<string | undefined>;
+  set(workflowId: string, chatId: string): Promise<void>;
+};
+
+export async function runTurn(workflowId: string, prompt: string): Promise<string> {
+  const agent = new CoderAgent({
+    baseUrl: process.env.CODER_URL!,
+    token: process.env.CODER_SESSION_TOKEN!, // read per step — never checkpoint or log it
+    organizationId: process.env.CODER_ORG_ID!,
+    chatId: await checkpoints.get(workflowId), // undefined on the first step → the turn creates the chat
+    requestTimeoutMs: 300_000, // always bound workflow steps — see below
+    onTransportEvent: observe, // per-step telemetry — see below
+  });
+
+  try {
+    const { text } = await agent.generate({
+      prompt,
+      // Total wall-clock for the step: requestTimeoutMs bounds each segment,
+      // not a whole multi-segment (client-tool) turn — see "Bound every step".
+      abortSignal: AbortSignal.timeout(600_000),
+    });
+    return text;
+  } finally {
+    // The durable resume handle — written even when the turn failed: a first
+    // step that fails AFTER creating its chat (timeout, stream loss) must
+    // still persist the id, or the retried step orphans a live chat and its
+    // partial effects. Exception: after an exhausted stream failure on a
+    // chat this very call created, the SDK has already discarded the dead
+    // session (agent.chatId is undefined) and nothing is written — see the
+    // CoderStreamError notes below for what retrying means then.
+    if (agent.chatId) await checkpoints.set(workflowId, agent.chatId);
+  }
+}
+```
+
+The shape matters:
+
+- **One turn per step, `generate()` not `stream()`.** The checkpointed unit is
+  a finished result — and a mid‑`stream()` failure surfaces on the stream,
+  outside `generate()`'s error contract, which complicates step retry logic.
+- **Persist the id, not the instance** (and never the token — read it from
+  each step's environment).
+- **Checkpoint in `finally`, not only on success**, so failed-but-alive chats
+  stay reachable. What remains is the hard-crash window between chat creation
+  and the checkpoint write (below).
+- **No `await using` here.** The chat outlives the step; disposal archives it
+  and archiving ends resumability (below).
+
+### Resume in the next step — any process, any machine
+
+```ts
+// Step 1 — a queue job on machine A:
+await runTurn("wf-1042", "Investigate the failing nightly build and propose a fix.");
+
+// Step 2 — hours later, on machine B: same chat, full server-side history.
+await runTurn("wf-1042", "Apply the fix you proposed and summarize what changed.");
+
+// Final step — cleanup belongs to the workflow, not to each step (see below).
+await archiveWorkflowChat("wf-1042");
+```
+
+What resuming does (and doesn't do):
+
+- **Construction is free.** `new CoderAgent({ …, chatId })` performs no I/O
+  and no validation — a bad or archived id fails the _turn_, not the
+  constructor.
+- **The first resumed turn seeds its cursor** from the chat's newest message
+  (one single‑message history probe), so it streams only its own events —
+  it never re‑absorbs earlier turns' content or usage.
+- **Re‑supply process‑local configuration.** Client `tools` live in your
+  process, not on the server, so each step that expects tool calls must pass
+  them again. The workspace binding is the opposite: fixed at creation,
+  carried by the chat, unchangeable on resume.
+- **Sessions stay single‑flight across the whole system**, not just within one
+  process: run steps strictly sequentially per chat. A second job posting to
+  the same chat queues behind the live run and burns its own
+  `requestTimeoutMs` waiting.
+
+### Let the SDK absorb drops — and handle what it re‑throws
+
+Self‑healed, invisible to the step (the run is **not** interrupted):
+
+- **Transient stream drops.** The server keeps generating through the gap; the
+  SDK redials with backoff and replays what it missed — committed messages
+  past the turn's cursor plus the in‑progress message's deltas — deduplicating
+  on receipt. A message that committed _while the connection was down_ arrives
+  as exactly its missing tail. Drops cost latency, never content, and never
+  duplicate content.
+- **Client‑tool pauses ride one connection.** A multi‑segment turn keeps its
+  stream across `requires_action` pauses, and a drop while your tool executes
+  redials in the background.
+- **A lost tool‑call event.** If a turn pauses for client tools but the pause's
+  tool‑call event doesn't arrive within ~2 s, the SDK recovers the pending
+  calls from committed history over REST and the turn continues.
+
+Surfaced to the step once self‑healing is exhausted:
+
+```ts
+import { CoderApiError, CoderChatError, CoderStreamError } from "@coder/ai-sdk-agent";
+
+try {
+  await runTurn(workflowId, prompt);
+} catch (err) {
+  if (err instanceof CoderChatError && err.retryable) {
+    // Timeout or transient turn failure. The run was interrupted (best-effort)
+    // and the chat survives — but a re-run resubmits the prompt as a new user
+    // turn: retry only steps designed to tolerate that (below).
+  } else if (err instanceof CoderStreamError) {
+    // Redial budget exhausted (~15s without forward progress). On a resumed
+    // chat this is never auto-retried — the retry decision is yours (below).
+  } else if (err instanceof CoderApiError) {
+    // Branch on err.status: back off and retry 408/425/429/5xx; fail the workflow
+    // on the rest (expired token, archived/deleted chat, …).
+  }
+  throw err;
+}
+```
+
+- **`CoderChatError` with `retryable: true`** — the segment's
+  `requestTimeoutMs` expired (`kind: "timeout"`) or the turn failed
+  transiently (`kind: "stream_closed"`, an upstream 5xx). `retryable`
+  classifies the _failure_ as transient — it does not make a re‑run free.
+  Unlike the guarded `CoderStreamError` path below, the session is **not**
+  discarded: the retried step reloads the checkpointed chat id (the `finally`
+  checkpoint above is what makes this hold even when the _first_ step fails
+  after creating its chat) and resubmits the same prompt as a new user turn,
+  with the aborted attempt's partial output in history and any tool effects
+  that ran before the failure not undone. The same idempotency judgment as
+  below applies — retry steps designed to tolerate re‑submission; reconcile
+  first when they aren't. And don't resubmit _immediately_: the expiry's
+  server interrupt is asynchronous and best‑effort, so the timed‑out run may
+  still be committing — run the same interrupt‑and‑wait‑for‑terminal‑status
+  recovery as after a crash (below) before the retry, or its trailing output
+  is absorbed into the retried turn. A timed‑out run can also have _finished_
+  before that interrupt landed — but because the interrupt was already fired,
+  the recovery's [result check](#recover-the-result-before-resubmitting)
+  must treat the attempt as cut short (pin `cutShort` there) rather than
+  trusting its own 409.
+- **`CoderStreamError`** (an AI SDK `APICallError`) — the stream could not be
+  re‑established. `isRetryable: true` only when the failed turn had just
+  created its chat _and_ had no external effects a replay would repeat (no
+  workspace, no MCP servers, no fresh inline uploads); the SDK then discards
+  the dead session so a retry — `maxRetries` or a re‑run step — starts clean
+  on a fresh chat. The discard happens for _every_ chat the failed turn
+  itself created — **including the effectful, `isRetryable: false` case**:
+  the id is gone, the `finally` checkpoint writes nothing, and the
+  interrupted chat — whose workspace/MCP tools may already have acted —
+  becomes an unacknowledged orphan for the reconciliation sweep (below). A
+  retried step then starts a fresh chat that has _not_ seen the orphan's
+  effects: gate that retry on the same idempotency judgment as any
+  re‑submission. **On a resumed chat it is always `isRetryable: false`:**
+  re‑running the step resubmits the same prompt as a _new user turn_, with the
+  failed attempt's partial output still in history (usually fine — the model
+  sees its own aborted attempt), and any workspace/MCP tool effects that ran
+  before the drop are not undone. That judgment call belongs to your workflow,
+  which is exactly why it isn't automatic.
+- **`CoderApiError`** — an HTTP request failed; every non‑2xx wraps in this
+  error, so branch on `status` before deciding. Rate limiting and transient
+  server failures (408, 425, 429, 5xx) deserve backoff and a step retry (with
+  the same re‑submission caveat as above). Auth failures and archived/deleted
+  chats (401/403/404, the archived‑chat 400) hit the same wall on every
+  attempt — fail the workflow.
+
+### Recover after a crash
+
+A hard crash (OOM kill, host loss) runs no `finally` blocks. Reason from the
+checkpoint:
+
+- **Crashed with an empty checkpoint** — usually nothing exists server‑side
+  and the retried step just creates a fresh chat. But an empty checkpoint is
+  not proof of nothing: a crash or `requestTimeoutMs` expiry while the create
+  request was _in flight_ can leave a chat the server committed but whose id
+  never arrived — unreachable even by the SDK's own interrupt. Treat "no
+  checkpoint" as _up to one unacknowledged chat per attempt may exist_ — not
+  as a clean slate, and automatic step retries can stack several. The
+  reconciliation sweep below must therefore retire _every_ matching orphan
+  (and its workspace/MCP effects, if the deployment auto‑attached any), not
+  stop at the first.
+- **Crashed after creation, before the checkpoint** — the chat is orphaned:
+  its run keeps generating until it settles on its own — or, if the crash hit
+  one of your client tools, never settles: it stays paused in
+  `requires_action`, holding its workspace, invisible to the retried step
+  (which has no id to interrupt). Either way the retried step starts a fresh
+  chat, so orphans are found only by the reconciliation sweep from
+  [Preventing stuck turns](#preventing-stuck-turns) — that sweep is not
+  optional in this pattern, and it needs a **wider filter** here: the fleet
+  sweep watches for _non‑terminal_ chats stuck past their budget, but an
+  orphaned first turn may settle terminally on its own and then sit as a
+  live, unarchived chat forever. Sweep every chat no checkpoint accounts
+  for — regardless of status — and interrupt/archive it. (To shrink the window, checkpoint eagerly from the
+  first `ws:dial` transport event — it carries the chat id as soon as the chat
+  exists — but then the checkpoint's lifecycle is yours too: the retried step
+  resumes a chat holding a dead half‑turn, and whenever a `CoderStreamError`
+  killed a chat this step created — retryable or not: the SDK discards every
+  such session, but only in memory — you must clear the eagerly checkpointed
+  id yourself before any retry, or "starts fresh after a discard" silently
+  turns into resuming the dead chat.)
+- **Crashed after the checkpoint** — the chat is resumable, but don't just
+  resubmit. The crashed attempt's run may still be live server‑side, and a
+  resumed turn seeds its message cursor _before_ submitting — whatever the
+  old run commits after that point would be absorbed into the resumed turn's
+  output and usage. A crash _inside one of your client tools_ is worse: the
+  chat is paused in `requires_action`, where new messages wait forever — and
+  if the tool's external effect committed before the crash, that pause is the
+  only pending record of it, so reconcile the tool ledger **before** any
+  interrupt ([Make client tools crash-safe](#make-client-tools-crash-safe)).
+  Both cases have one remedy — stop what the crash left behind and **wait
+  until the chat actually settles** before deciding: a client‑tool pause is
+  reconciled, never interrupted away; anything else is interrupted:
+  `interrupt()` resolves on acknowledgment while the run keeps winding down
+  (and committing) for a few more seconds, so poll the chat's status to a
+  terminal one first. On a chat with no live run the interrupt rejects with a
+  409 `CoderApiError`; that's the good case — ignore it:
+
+  ```ts
+  // Both shared with "Make client tools crash-safe" (below): the ledger
+  // reconciliation resolves to its `unstarted` — true only when it fell back
+  // to interrupting — and journals each action write-ahead, so a recovery
+  // pass that dies mid-recovery is visible — and classifiable — to the next.
+  declare function reconcileClientTools(): Promise<boolean>;
+  // Entries are per-ATTEMPT: clear/supersede them transactionally with
+  // recording the attempt's result, or a stale verdict misclassifies the
+  // next attempt on this chat — attempt-scoped journal keys close the
+  // remaining double-crash window (see
+  // https://github.com/coder/ai-sdk/issues/92).
+  declare const journal: {
+    get(chatId: string): Promise<"resumed" | "cut-short" | undefined>;
+    set(chatId: string, state: "resumed" | "cut-short"): Promise<void>;
+  };
+
+  // Bounded: a stalled deployment must fail the step, not hang it.
+  const deadline = AbortSignal.timeout(15_000);
+  // Whether an interrupt stopped a live run drives the resubmit decision
+  // below: a 409 means there was nothing to stop.
+  let cutShort = true;
+  let { status } = await agent.client.getChat(agent.chatId!, deadline);
+  const journaled = await journal.get(agent.chatId!);
+  if (status === "requires_action") {
+    // The crash hit a client tool mid-execution: this pause is the only
+    // pending record of its committed effects. Never interrupt it away —
+    // reconcile the ledger instead (below): it submits recorded results
+    // (reviving the run — nothing was cut short) or interrupts itself only
+    // when nothing committed.
+    cutShort = await reconcileClientTools();
+  } else if (journaled) {
+    // A previous recovery pass acted on this chat, then died before the
+    // step's result was recorded. Its journaled state is the verdict:
+    // "resumed" — it revived the run by submitting recorded results;
+    // interrupting now would cut down a run doing the step's work, and the
+    // resubmitted prompt would mint NEW tool-call ids, sidestepping the
+    // idempotency keys. Let it finish; nothing was cut short.
+    // "cut-short" — it went on to interrupt (an unstarted sibling in the
+    // batch); the attempt is truncated, so the check below must resubmit.
+    cutShort = journaled === "cut-short";
+    if (cutShort) {
+      // The journal records write-ahead INTENT, not a landed interrupt: the
+      // pass may have died in between, leaving the revived run working.
+      // Re-drive the interrupt to make the intent true — a 409 means the
+      // chat already settled; the cut-short verdict stands either way.
+      await agent.interrupt({ signal: deadline }).catch((err) => {
+        if (!(err instanceof CoderApiError && err.status === 409)) throw err;
+      });
+    }
+  } else {
+    await agent.interrupt({ signal: deadline }).catch((err) => {
+      // A 409 proves nothing is stoppable NOW — that means "never cut short"
+      // only if the probe saw no interrupt already in flight. A probed
+      // "interrupting" is an earlier interrupt (a timeout's best-effort one,
+      // a sweeper) already truncating the attempt; this 409 just says it
+      // landed. Keep cutShort = true then.
+      if (err instanceof CoderApiError && err.status === 409) cutShort = status === "interrupting";
+      else throw err;
+    });
+  }
+  // The 15 s interrupt bound must not cap what follows: a reconciled pause
+  // revives a full model/tool continuation. Budget the settle poll — and the
+  // history reads after it — on the turn scale, like the step itself.
+  const settle = AbortSignal.timeout(600_000);
+  do {
+    ({ status } = await agent.client.getChat(agent.chatId!, settle));
+    if (status === "waiting" || status === "completed" || status === "error") break;
+    // With no accepted interrupt racing to clear it, requires_action is a
+    // STABLE pause: a run resumed by submitted tool results called a NEW
+    // client tool. Exit and reconcile the ledger again (below) instead of
+    // polling out the deadline.
+    if (status === "requires_action" && !cutShort) break;
+    await new Promise((r) => setTimeout(r, 1_000)); // acknowledged ≠ settled — wait it out
+  } while (true);
+  ```
+
+  Settled is necessary, not sufficient: a terminal status doesn't say whether
+  the crashed attempt already _finished the step's work_ — check history
+  before resubmitting
+  ([Recover the result before resubmitting](#recover-the-result-before-resubmitting)).
+
+### Make client tools crash-safe
+
+Interrupting un‑strands a `requires_action` pause — but if the crashed
+process died _between_ a non‑idempotent client tool committing its external
+effect (a payment, a deploy, an email) and that result reaching the server,
+the pause is the **only pending record of the execution**. Interrupt it away
+and the resubmitted prompt is free to call the tool again — and duplicate the
+effect. Close the window with a tool‑invocation ledger in the same durable
+store as the `chatId` checkpoint, keyed by **chat id + `toolCallId`** — the
+server assigns the call id and commits it to history, so both sides of the
+reconciliation survive the crash. The chat id must be part of the key (and
+of the idempotency key handed to the external system): call ids are only
+unique _within_ a chat, and a store shared across workflows must never let
+one chat's `done` entry answer — or deduplicate — another chat's call. In
+multi‑tenant stores, fold the tenant in too:
+
+```ts
+import { tool } from "ai";
+import { z } from "zod";
+import { CoderAgent } from "@coder/ai-sdk-agent";
+
+type LedgerEntry = { state: "committing" } | { state: "done"; output: string };
+declare const ledger: {
+  get(key: string): Promise<LedgerEntry | undefined>;
+  set(key: string, entry: LedgerEntry): Promise<void>;
+};
+declare const payments: {
+  charge(amountCents: number, opts: { idempotencyKey: string }): Promise<{ receiptId: string }>;
+};
+
+const ledgerKey = (chatId: string, toolCallId: string) => `${chatId}/${toolCallId}`;
+const ChargeArgs = z.object({ amountCents: z.number().int() });
+
+// A factory taking a getter, not an id: the chat may not exist until the
+// turn creates it, so the id must be read lazily — it is set before any
+// tool runs.
+const chargeCard = (chatId: () => string) =>
+  tool({
+    description: "Charge the customer's card.",
+    inputSchema: ChargeArgs, // shared with recovery's re-drive dispatch below
+    execute: async ({ amountCents }, { toolCallId }) => {
+      const key = ledgerKey(chatId(), toolCallId);
+      // Write-ahead, BEFORE the effect: a crash between the two writes leaves
+      // "committing" (ambiguous, but resolvable below); no entry at all proves
+      // the effect never started.
+      await ledger.set(key, { state: "committing" });
+      // Hand the external system the SAME key as its idempotency key, so
+      // re-driving this exact call can never double-charge.
+      const { receiptId } = await payments.charge(amountCents, { idempotencyKey: key });
+      await ledger.set(key, { state: "done", output: `charged: receipt ${receiptId}` });
+      return `charged: receipt ${receiptId}`;
+    },
+  });
+
+// Wire-up: a direct self-reference in the constructor call is circular for
+// the type checker — defer it through a box assigned right after.
+let self: { chatId?: string } | undefined;
+const agent = new CoderAgent({
+  /* …base options as in runTurn… */
+  tools: { charge_card: chargeCard(() => self!.chatId!) },
+});
+self = agent;
+```
+
+On crash recovery, when the checkpointed chat is paused in `requires_action`,
+reconcile _before_ any interrupt. The pending calls are in committed history —
+the same derivation the SDK itself uses to recover a lost `action_required`
+event — and the ledger holds the verdict on each:
+
+```ts
+// The step's configured ToolSet names: history does not record which calls
+// were client tools (see [Rehydrating chat history]), so — like the SDK's
+// own derivation — restrict to the names this step registers; a server/MCP
+// call must never reach the ledger as "unstarted".
+const clientTools = new Set(["charge_card"]);
+
+// Pending = the last assistant message's client (non-provider-executed,
+// ToolSet-named) tool calls, minus ids answered by a later message's tool
+// result.
+const { messages } = await agent.client.getMessages(agent.chatId!, { limit: 200 }, deadline);
+const ordered = [...messages].sort((a, b) => a.id - b.id);
+const lastAssistant = ordered.findLast((m) => m.role === "assistant");
+const handled = new Set(
+  ordered
+    .filter((m) => m.id > (lastAssistant?.id ?? 0))
+    .flatMap((m) => m.content ?? [])
+    .filter((p) => p.type === "tool-result")
+    .map((p) => p.tool_call_id),
+);
+const pending = (lastAssistant?.content ?? []).filter(
+  (p) =>
+    p.type === "tool-call" &&
+    !p.provider_executed &&
+    clientTools.has(p.tool_name!) &&
+    !handled.has(p.tool_call_id),
+);
+
+const results: { tool_call_id: string; output: unknown }[] = [];
+let unstarted = false;
+for (const call of pending) {
+  const key = ledgerKey(agent.chatId!, call.tool_call_id!);
+  const entry = await ledger.get(key);
+  if (entry?.state === "done") {
+    // Effect committed, result stranded: submit the record — the pause is
+    // answered and nothing re-executes.
+    results.push({ tool_call_id: call.tool_call_id!, output: entry.output });
+  } else if (entry) {
+    // "committing" is ambiguous — the crash hit between the write-ahead and
+    // "done". Safe to re-drive: the SAME idempotency key makes a committed
+    // effect replay as a no-op, and the call's args are committed in history.
+    // Dispatch by tool name — every ledgered tool needs its own re-drive
+    // path, its args validated exactly as the live loop would have.
+    if (call.tool_name !== "charge_card")
+      throw new Error(`no re-drive path for tool ${call.tool_name}`);
+    const { amountCents } = ChargeArgs.parse(call.args);
+    const { receiptId } = await payments.charge(amountCents, { idempotencyKey: key });
+    const output = `charged: receipt ${receiptId}`;
+    await ledger.set(key, { state: "done", output });
+    results.push({ tool_call_id: call.tool_call_id!, output });
+  } else {
+    unstarted = true; // the tool never ran — interrupting loses nothing
+  }
+}
+if (results.length > 0 || unstarted) {
+  // ONE write-ahead with the batch's FINAL verdict, before any network
+  // call — a mixed batch journals "cut-short" before even its submission,
+  // so no crash point can leave a stale "resumed" masking the pending
+  // interrupt. Every crash then either re-reconciles the stable pause or
+  // re-drives the journaled intent. Clear the entry only once the step's
+  // result is finally recorded.
+  await journal.set(agent.chatId!, unstarted ? "cut-short" : "resumed");
+}
+if (results.length > 0) await agent.client.submitToolResults(agent.chatId!, { results }, deadline);
+if (unstarted) await agent.client.interruptChat(agent.chatId!, deadline);
+// As `reconcileClientTools()` in the settle-wait snippet above: resolve to
+// `unstarted` — cutShort is true only when this fell back to interrupting.
+```
+
+- **Only interrupt when the ledger shows no committed effect.** Submitted
+  results are committed to chat history, so even when a mixed batch (one call
+  done, a sibling never started) still ends in an interrupt, the effect's
+  recorded outcome survives for the resubmitted turn to see.
+- **Submitting answers the pause; it does not revive your tool loop.** Once
+  every pending call is answered, the turn resumes **server‑side** with no
+  process streaming it. That is why the settle‑wait's reconcile branch never
+  interrupts a pause — nothing stranded is left to stop, and an interrupt
+  now would cut down the very run the submission revived — and why the
+  resolved `unstarted` leaves **`cutShort = false`** after a submission:
+  nothing was cut short, and the next section's `!cutShort` check must
+  classify the resumed run's finish as a completed attempt, not resubmit
+  it. Give the poll a turn‑scale deadline rather than the 15 s interrupt
+  bound; it exits on `requires_action` (stable here, with no accepted
+  interrupt clearing it), which means the resumed run called a _new_ tool —
+  reconcile again; a call with no ledger entry is safe to interrupt.
+- **The finished run's output lands only in history** — recover it like any
+  completed‑but‑unrecorded attempt (next section) instead of resubmitting.
+
+### Recover the result before resubmitting
+
+The settle‑wait resolves overlap with a still‑live run, but not the last
+crash window: **the server finished the turn, and the process died before the
+step's return value was recorded.** History now holds a perfectly good
+result; a retried step that blindly resubmits runs the whole turn again —
+duplicated output, repeated workspace/MCP/tool effects. This is the
+at‑least‑once boundary every durable engine has around external effects, and
+the chat itself is the record that closes it. Make attempts matchable first —
+the server stores the prompt verbatim, so embed a step‑scoped marker:
+
+```ts
+const marker = `[${workflowId}/step-2]`; // stable across this step's retries
+const { text } = await agent.generate({ prompt: `${marker} ${prompt}` });
+```
+
+Then, after the settle‑wait, three states are distinguishable — and only one
+of them resubmits:
+
+```ts
+import { chatMessagesToUIMessages } from "@coder/ai-sdk-agent";
+
+// A long turn can commit more than a page of messages after the prompt —
+// page newest-first (the endpoint's default order) until the turn's user
+// message is on hand; "never submitted" must never be concluded from a
+// truncated read, or this recovery resubmits exactly the turn it was meant
+// to deduplicate.
+const fetched = [];
+let page = await agent.client.getMessages(agent.chatId!, { limit: 200 }, settle);
+fetched.push(...page.messages);
+while (!fetched.some((m) => m.role === "user") && page.has_more) {
+  const oldestId = Math.min(...fetched.map((m) => m.id));
+  page = await agent.client.getMessages(agent.chatId!, { before_id: oldestId, limit: 200 }, settle);
+  fetched.push(...page.messages);
+}
+const transcript = chatMessagesToUIMessages(fetched); // chronological
+const lastUser = transcript.findLast((m) => m.role === "user");
+const submitted = lastUser?.parts.some((p) => p.type === "text" && p.text.includes(marker));
+
+if (submitted && !cutShort && (status === "waiting" || status === "completed")) {
+  // The attempt finished; only the recording was lost. Recover what
+  // `generate().text` would have returned — the FINAL step's text. A turn
+  // that crossed tool calls commits narration between them too, so cut the
+  // turn's parts after the last tool part and join the text that follows.
+  const parts = transcript
+    .slice(transcript.indexOf(lastUser!) + 1)
+    .filter((m) => m.role === "assistant")
+    .flatMap((m) => m.parts);
+  return parts
+    .slice(parts.findLastIndex((p) => p.type === "dynamic-tool") + 1)
+    .filter((p) => p.type === "text")
+    .map((p) => p.text)
+    .join("");
+}
+// Resubmit only what never finished: the prompt never reached the server
+// (!submitted), the turn failed (status "error" — normal retry judgment
+// applies), or the interrupt cut a live run short (cutShort — the model sees
+// its own aborted attempt in history and continues from it). One exit is
+// neither: a requires_action settle goes back to ledger reconciliation
+// (previous section) — never to recovery or resubmission.
+```
+
+- **`cutShort` is the completed/interrupted discriminator — but a 409 only
+  proves nothing is running _now_.** An interrupted attempt leaves the same
+  marker and a truncated answer in history, so history alone can't tell
+  "finished" from "stopped"; what can is whether any interrupt stopped the
+  run. The inference "409 ⇒ the attempt finished" is therefore sound only
+  when recovery's interrupt is the _first_ one that could have: true after a
+  hard crash, false after a `requestTimeoutMs` expiry — the expiry already
+  fired the SDK's own best‑effort interrupt, which may have stopped the run
+  before recovery ever looked. Carry the reason recovery ran: when it follows
+  a known timeout or abort — or a journaled earlier interrupt (write‑ahead,
+  like the tool ledger, if the recovery pass can itself crash between its
+  interrupt and the resubmit) — pin `cutShort` to `true` and let only the
+  hard‑crash path trust the 409.
+- **The cut lands after the last tool part of _either_ kind.** History does
+  not mark which tool calls were client tools
+  ([Rehydrating chat history](#rehydrating-chat-history)), so when a final
+  step narrates _before_ a server‑side tool call, that preamble is dropped
+  too — the recovered text is the answer following the turn's last tool
+  activity.
+- **Steps with structured results recover the call's input, not the text.**
+  A [structured output](#structured-output) step's answer is the
+  `structured_output` call's typed input, which rehydrates as a
+  `dynamic-tool` part on the recovered turn
+  ([Rehydrating chat history](#rehydrating-chat-history)) — the text join
+  above would slice it away and return only the ack prose that follows.
+  Recover the filed call instead — this scan replaces the text join
+  _inside_ the recovery branch above, reusing its `parts` — validated
+  client‑side exactly like the live path (rule 2 there — the schema is the
+  real gate):
+
+  ```ts
+  // Scan backward to the last call that VALIDATES, as in the live path — a
+  // schema-invalid re-file must not shadow a valid answer.
+  const filed = parts
+    .filter((p) => p.type === "dynamic-tool")
+    .filter((p) => p.toolName === "structured_output");
+  let answer: z.infer<typeof Answer> | undefined;
+  for (const call of filed.reverse()) {
+    const parsed = Answer.safeParse(call.input);
+    if (parsed.success) {
+      answer = parsed.data;
+      break;
+    }
+  }
+  // recovered ⇔ answer !== undefined
+  ```
+
+### Watch turn health from inside the step
+
+[Transport events](#observability) classify how each segment ended without
+parsing errors or stream frames — emit them as step metrics/traces:
+
+```ts
+declare const metrics: {
+  ok(segment: number, status: string, ms: number): void;
+  fail(segment: number, error: string, detail: string): void;
+  teardown(segment: number): void;
+};
+
+function observe(ev: CoderTransportEvent): void {
+  if (ev.type === "ws:redial") {
+    // Early warning: the stream dropped and is reconnecting. The server keeps
+    // generating — nothing is lost yet; the turn fails if this hits the cap.
+    console.warn(
+      `redial ${ev.consecutiveFailures}/${ev.maxConsecutiveFailures}, next in ${ev.backoffMs}ms`,
+    );
+  } else if (ev.type === "segment:settle") {
+    if (ev.finishReason) metrics.ok(ev.segment, ev.status!, ev.durationMs);
+    else if (ev.error) metrics.fail(ev.segment, ev.error.name, ev.error.message);
+    else metrics.teardown(ev.segment);
+  }
+}
+```
+
+`segment:settle` fires exactly once per `segment:start` and separates the
+three endings a workflow cares about:
+
+- **Clean settle** — `status` + `finishReason` present. `finishReason:
+"tool-calls"` (status `requires_action`) is a healthy mid‑turn pause for
+  your client tools; terminal statuses end the turn.
+- **Failure** — `error: { name, message }` present (plus `status` when the
+  server run itself still settled terminally): server‑side turn errors,
+  transport failure after redials were exhausted, `requestTimeoutMs` expiry
+  (`error.name: "CoderChatError"`), and caller aborts — which settle as
+  failures carrying the abort reason's name, never as teardowns:
+  `"TimeoutError"` for an `AbortSignal.timeout(…)` deadline (the running
+  example), `"AbortError"` for an explicit abort.
+- **Teardown** — neither: the stream consumer itself cancelled the turn
+  (`stream()`'s `ReadableStream.cancel()` with no abort of its own) — rare in
+  `generate()`‑shaped steps.
+
+The hook is observability‑only — handler exceptions are swallowed and can't
+disturb the turn, and an unset hook costs nothing. For monitoring _across_
+steps (chats stuck before a watcher started, fleet‑level sweeps), see
+[Preventing stuck turns](#preventing-stuck-turns).
+
+### Bound every step
+
+`requestTimeoutMs` arms **one timer per segment** covering everything the
+segment does: the REST phase (chat creation, message/tool‑result submission,
+uploads), the stream — and, the part that matters here, **any redial backoff
+inside the segment**. A segment that spends 12 s reconnecting has 12 s less
+budget; redials never reset the clock, so a flaky network can't stretch a step
+past its bound. On expiry the call rejects with `CoderChatError`
+(`kind: "timeout"`, `retryable: true`) and the server run is interrupted
+best‑effort.
+
+Two workflow‑specific notes:
+
+- A turn that times out (or crashes) before its chat id arrived leaves nothing
+  to _resume_ — the checkpoint stays empty and the retried step starts fresh —
+  but possibly an unacknowledged chat to sweep (see
+  [Recover after a crash](#recover-after-a-crash)).
+- `requestTimeoutMs` bounds each _segment_; a turn driving client tools runs
+  several. Cap a step's total wall‑clock with
+  `abortSignal: AbortSignal.timeout(…)` —
+  [Timeouts & cancellation](#timeouts--cancellation).
+
+### Archive at the end — and only at the end
+
+**An archived chat cannot be resumed:** the server rejects new messages on it
+(400, `Cannot send messages to an archived chat`). The per‑request habits from
+[Cleanup](#cleanup) — `await using`, `archive()` in a `finally` — would
+destroy the session from inside an intermediate step, so here the _workflow_
+owns the chat's end of life: archive once, in the final step, and in the
+workflow's failure/compensation handler so abandoned runs don't accumulate
+live chats.
+
+```ts
+export async function archiveWorkflowChat(workflowId: string): Promise<void> {
+  const chatId = await checkpoints.get(workflowId);
+  if (!chatId) return; // the workflow died before its first turn created a chat
+  const agent = new CoderAgent({
+    baseUrl: process.env.CODER_URL!,
+    token: process.env.CODER_SESSION_TOKEN!,
+    organizationId: process.env.CODER_ORG_ID!,
+    chatId,
+  });
+  // A crashed step may have left a run live — stop it first, bounded. On an
+  // already-settled chat the interrupt rejects with a 409; ignore it.
+  await agent.interrupt({ signal: AbortSignal.timeout(15_000) }).catch(() => {});
+  await agent.archive(); // retries 409s while the interrupted run winds down (~15s)
+}
+```
+
+### Checklist
+
+- One turn per durable step; `generate()`, not `stream()`.
+- Persist `agent.chatId` (a string) — never the instance, never the token.
+- Bound every step: `requestTimeoutMs` per segment, an abort deadline for
+  total wall‑clock.
+- Let redials self‑heal; own every retry decision — a re‑run step resubmits
+  its prompt as a new user turn.
+- Before resubmitting after a crash: reconcile the tool ledger before any
+  interrupt, and recover a finished attempt's result from history.
+- Keep concurrent steps' fan‑out within workspace quota —
+  [Workspaces & quota](#workspaces--quota).
+- Steps that don't need server‑side tools (plan / extract / synthesize) are
+  cheaper and natively structured through
   [`@coder/ai-sdk-provider`](../provider) + `generateObject` — no chat, no
   workspace, no cleanup.
+- Archive in the final step / failure handler — never per step.
 
 ## Testing