@coder/ai-sdk-agent 0.11.6 → 0.11.8

package/docs/observability.md

@@ -0,0 +1,130 @@
+# Observability: transport events
+
+`onTransportEvent` receives typed transport events: HTTP exchanges, the per‑chat
+stream's WebSocket lifecycle, and turn‑segment boundaries. Use it for timing and
+tracing without wrapping `fetch`/`webSocketFactory` or re‑parsing stream frames.
+
+Pass it on any of:
+
+- `CoderAgentSettings` — reaches both the client and the model.
+- `CoderChatClientOptions`
+- `CoderLanguageModelConfig`
+
+## Example: where did the turn spend its time?
+
+```ts
+import { CoderAgent, type CoderTransportEvent } from "@coder/ai-sdk-agent";
+
+const events: CoderTransportEvent[] = [];
+const agent = new CoderAgent({
+  baseUrl,
+  token,
+  organizationId,
+  onTransportEvent: (ev) => events.push(ev),
+});
+
+await agent.generate({ prompt: "…" });
+
+for (const ev of events) {
+  if (ev.type === "http:response")
+    console.log(
+      `${ev.op}: ${ev.method} ${ev.path} → ${ev.status} in ${ev.durationMs.toFixed(0)}ms`,
+    );
+  if (ev.type === "ws:event" && ev.event.type === "action_required")
+    console.log(`tool calls arrived at +${ev.timestamp - events[0]!.timestamp}ms`);
+  if (ev.type === "segment:settle")
+    console.log(`segment ${ev.segment}: ${ev.status} in ${ev.durationMs.toFixed(0)}ms`);
+}
+```
+
+## Event reference
+
+`CoderTransportEvent` is a discriminated union on `type`. Every event carries
+`timestamp`: `Date.now()` at observation. It is comparable to server‑side
+timestamps such as a message's `created_at`, so you can measure delivery lag.
+
+| event            | when                                                | payload (besides `timestamp`)                                                                                                                                                                                                                                                     |
+| ---------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `http:request`   | a REST request is sent                              | `id` (correlates the pair), `op` (the client operation, e.g. `"createChatMessage"`), `method`, `path`                                                                                                                                                                             |
+| `http:response`  | response headers arrive (incl. non‑2xx, `ok:false`) | `id`, `op`, `method`, `path`, `status`, `ok`, `durationMs`                                                                                                                                                                                                                        |
+| `http:error`     | the fetch itself rejects (network failure, abort)   | `id`, `op`, `method`, `path`, `message`, `durationMs`                                                                                                                                                                                                                             |
+| `ws:dial`        | a stream connection attempt starts                  | `chatId`, `reader` (identifies the `streamChatEvents` call), `attempt` (1‑based per reader, increments per redial), `url`                                                                                                                                                         |
+| `ws:open`        | the WebSocket handshake completes                   | `chatId`, `reader`, `attempt`                                                                                                                                                                                                                                                     |
+| `ws:event`       | a decoded stream event arrives                      | `chatId`, `reader`, `attempt`, `event` (the decoded `ChatStreamEvent`, by reference — don't mutate), `forwarded` (the reader's replay verdict)                                                                                                                                    |
+| `ws:close`       | the connection ends (exactly one per dial)          | `chatId`, `reader`, `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`, `reader`, `attempt`, `message`                                                                                                                                                                                                                                          |
+| `ws:redial`      | a dropped connection is about to be redialed        | `chatId`, `reader`, `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`, `reader` (the reader that served the segment; absent if none was acquired), `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 |
+
+## Guarantees
+
+- **Isolation** — exceptions thrown by the handler are swallowed. They can never
+  alter transport behavior or a turn's outcome.
+- **Zero overhead** — without a handler, no event objects are allocated and no
+  extra socket listeners are registered.
+- **No secrets** — events carry no headers and no tokens. Auth travels in the
+  `Coder-Session-Token` header, which is deliberately excluded. `path`/`url`
+  never contain credentials.
+
+## Semantics
+
+### HTTP operation names
+
+- `op` is the public `CoderChatClient` method performing the exchange
+  (`"createChat"`, `"createChatMessage"`, `"getMessages"`,
+  `"submitToolResults"`, … — the `CoderClientOperation` union). Classify per
+  operation without reverse‑engineering `path`.
+- `method`/`path` stay for generic consumers.
+- `archiveChat` stamps its own `op`, even though it issues the same `PATCH` as
+  `updateChat`.
+- WebSocket prefix‑selection preflights emit the existing `http:*` event kinds
+  with `op: "streamEvents"` or `op: "watchChats"`. There are no new event kinds.
+
+### Replay and `forwarded`
+
+- `ws:event` fires at arrival. After a redial, chatd's replay of the
+  in‑progress episode is visible here; correlate with `reader`/`attempt`.
+- Each `ws:event` is stamped with the reader's own replay verdict:
+  `forwarded: false` exactly on the duplicate deltas the reader suppresses from
+  the turn. Subscribers never re‑derive the episode filter.
+- `forwarded` does **not** reflect snapshot dedup. Repeated or revised
+  `message` snapshots are always `forwarded: true`: reconciling them is
+  deliberately the consumer's job past the transport layer. `TurnTranslator`'s
+  per‑message ledger decides what a revision re‑emits, and that disposition is
+  not stamped on transport frames.
+- Use `ws:event` for span pairing and replay accounting. If you need content
+  fidelity, consume model output (or `TurnTranslator`), not transport frames.
+
+### Identifying a connection
+
+Identify a connection as `(chatId, reader, attempt)`, never `(chatId, attempt)`
+alone.
+
+- `reader` is a monotonic id for the `streamChatEvents` call behind the
+  connection. It comes from one process‑wide counter, so it stays unique across
+  model and client instances. Every `ws:*` event carries it.
+- `attempt` restarts at 1 per reader.
+- Why it matters: a client‑tool pause the caller abandons is closed
+  fire‑and‑forget when the next turn dials its replacement. The superseded
+  reader's late `ws:close` (or a raced‑in frame) can emit after the new reader's
+  `ws:dial`. The reader id tells them apart.
+- `segment:settle` names the reader that served the segment. `segment:start`
+  predates stream acquisition and carries none.
+
+### Multi‑step turns
+
+A multi‑step turn that drives client tools emits one
+`segment:start`/`segment:settle` pair per round‑trip, all riding **one**
+`ws:dial`ed connection: the stream is retained across `requires_action` pauses.
+
+- A pause settles with `status: "requires_action"`, `finishReason: "tool-calls"`.
+- The final settle carries the terminal status (`waiting`/`completed`/`error`).
+
+### Coverage
+
+- `ws:*` events cover the per‑chat `/stream` reader (turn transport). The
+  `watchChats` subscription is not instrumented.
+- With a pre‑built `client` in `CoderAgentSettings`, HTTP/WS events come from the
+  hook given to **that client's** options. The agent‑level hook then only
+  receives `segment:*` events.

package/docs/structured-output.md

@@ -0,0 +1,134 @@
+# Structured output from an agent run
+
+Coder Agents has no server‑side `response_format`. `CoderAgent` cannot constrain
+what the model **says** to a JSON schema: a `responseFormat` /
+`experimental_output` request emits a warning and is best‑effort at most.
+
+Pick by what the step needs:
+
+| The step…                                                                       | Use                                                                                                                                                                                         |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| is pure text‑in / JSON‑out, with no server‑side tools                           | [`@coder/ai-sdk-provider`](https://github.com/coder/ai-sdk/tree/main/packages/provider) with `generateObject` / `Output.object` — schema‑constrained; requires AI Gateway on the deployment |
+| must produce its answer from an agent run (server‑side tools, MCP, a workspace) | the **`structured_output` tool pattern** below                                                                                                                                              |
+
+## The `structured_output` tool pattern
+
+What the model _says_ isn't schema‑constrained, but what it passes **into a
+tool** is typed. So have it submit its answer by calling a tool whose
+`inputSchema` is your Zod schema. The answer arrives as the tool call's typed
+`input` — no fishing JSON out of prose.
+
+```ts
+import { CoderAgent } from "@coder/ai-sdk-agent";
+import { stepCountIs, tool } from "ai";
+import { z } from "zod";
+
+const Answer = z.object({ severity: z.enum(["critical", "major", "minor"]), summary: z.string() });
+
+const agent = new CoderAgent({
+  organizationId: "your-org-uuid", // connection defaults to CODER_URL + CODER_SESSION_TOKEN
+  instructions: "… Submit your final answer by calling the structured_output tool exactly once.",
+  tools: {
+    structured_output: tool({
+      description:
+        "Submit your final structured answer as JSON. Call this exactly once, when your work is complete.",
+      inputSchema: Answer, // your schema IS the tool's input schema
+      // Ack instead of stopping the turn: the model finishes naturally and can
+      // wind down anything it still has running (dev servers, watchers, …).
+      execute: async () =>
+        "Output received. Wind down and end your turn. Do not call structured_output again.",
+    }),
+  },
+  stopWhen: stepCountIs(6), // happy path is 2 steps: file + ack, wind down
+});
+
+const result = await agent.generate({ prompt: "…" });
+// toolCalls only holds the LAST step's calls — scan all steps. Take the last call
+// that VALIDATES: a schema-invalid re-file must not shadow a valid answer (rule 2).
+const filed = result.steps
+  .flatMap((s) => s.toolCalls)
+  .filter((c) => c.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; // typed: { severity: "critical" | "major" | "minor"; summary: string }
+    break;
+  }
+}
+if (answer === undefined)
+  throw new Error("no valid structured_output call — nudge once on an idle chat (rule 3)");
+```
+
+## Rules that keep it robust
+
+Each rule guards against a failure mode observed live.
+
+### 1. Don't force `toolChoice`, and don't stop on the call
+
+- **`toolChoice`** is construction‑time and applies to _every_ segment. After the
+  ack it would force the tool again and again, up to the step ceiling. It also
+  blocks any other tools the step needs.
+- **A `hasToolCall` stop is worse.** The server only receives a client tool
+  result as a side effect of the _next_ loop segment. Ending the loop on the
+  call strands the chat in `requires_action`: follow‑up messages queue forever
+  and `archive()` 409s.
+
+Instructions plus the tool's own description are enough; models file unprompted
+most of the time.
+
+### 2. Validate client‑side
+
+The schema is not enforced server‑side. `schema.safeParse` on the tool input is
+the real gate. Schema‑invalid calls that the AI SDK catches in‑loop are
+automatically answered with a `tool-error` result the model retries against.
+
+### 3. Nudge at most once, and only an idle chat
+
+If the turn ends in prose (`finishReason: "stop"`) without a valid call, send one
+typed re‑prompt ("Call the structured_output tool now …"), then fail into your
+normal error handling.
+
+Never re‑prompt a chat that isn't idle: the message would queue behind whatever
+the server is still doing.
+
+### 4. Settle a turn that stopped on a tool call
+
+If the loop stops on a tool‑call step — e.g. your `stopWhen` ceiling lands
+exactly on the `structured_output` call (`finishReason: "tool-calls"`) — the tool
+results ran locally but never reached the server. Settle the chat before touching
+it again, or it strands as in rule 1:
+
+1. Guard on `agent.chatId`. It is `undefined` until the first turn creates the
+   chat.
+2. Read the stranded step's (`result.steps.at(-1)`) locally‑executed client
+   outcomes off its **content parts**:
+   - a `tool-result` part is a success;
+   - a `tool-error` part (the tool's `execute` threw) must be submitted with
+     `is_error: true` — mirroring what the resume path would have sent.
+3. Submit them directly:
+   `agent.client.submitToolResults(chatId, { results: [{ tool_call_id, output, is_error }] }, AbortSignal.timeout(8_000))`.
+4. If a pending call has no local outcome (or the submit fails), end the
+   stranded turn instead with
+   `agent.client.interruptChat(chatId, AbortSignal.timeout(8_000))`.
+
+**Bound every one of these recovery requests with an `AbortSignal`.** They
+target a server that may already be stalled, and the bare `agent.interrupt()` /
+`agent.archive()` helpers carry no timeout.
+
+A settled chat resumes its wind‑down server‑side for a few seconds. Retry a
+409ing archive (`agent.client.archiveChat(chatId, signal)`, per‑attempt bound)
+under a short deadline instead of giving up.
+
+## Copyable helper
+
+[`examples/06-structured-output.ts`](https://github.com/coder/ai-sdk/blob/main/packages/agent/examples/06-structured-output.ts)
+packages all four rules into a small helper:
+
+- `structuredOutput(schema)` returns `agentOpts` to spread into the constructor,
+  plus a typed `ask(agent, prompt)` that runs the settle + one‑nudge ladder and
+  returns a `z.infer<typeof schema>`.
+- Compose additional client tools through the helper:
+  `structuredOutput(schema, { tools: { myTool } })` merges them into one ToolSet.
+  Don't pass `tools:` to the constructor next to the spread — the later key
+  silently clobbers the other map.

package/docs/workspaces-and-quota.md

@@ -0,0 +1,214 @@
+# Workspaces & quota
+
+How to run fleets of agents: how a chat binds to a Coder workspace, how to size
+concurrency, what to clean up, and how to diagnose a stuck chat. Read it before
+running many `CoderAgent`s at once. Back to the [package README](../README.md).
+
+A chat may be backed by a **Coder workspace** that runs its tools, depending on
+its configuration and the deployment. 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.
+
+## How a chat binds to a workspace
+
+- **One chat, at most one workspace, fixed at creation.** `workspaceId` is sent
+  as `workspace_id` on chat creation; message and update requests carry no
+  workspace field. To move work to another workspace, start a new agent/chat.
+- **This SDK never provisions workspaces.** Pass an existing one. Provision it
+  with [`@coder/ai-sdk-sandbox`](https://github.com/coder/ai-sdk/tree/main/packages/sandbox)'s `ensureCoderWorkspace`, the
+  CLI, or the v2 API.
+- **A chat created without `workspaceId` can still be 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 (this
+  affects [retry ownership](#preventing-stuck-turns)).
+- **Chat cleanup does not release the workspace.** `archive()` soft‑hides the
+  chat only. The workspace keeps running until template autostop or an
+  explicit stop. Stopping releases only stop‑scoped quota; persistent resources
+  (disks, volumes) keep consuming their cost until the workspace is deleted.
+
+## Sizing a fleet
+
+Rule: **workspaces that must be running concurrently ≤ schedulable
+workspaces.**
+
+- **One workspace per chat** (the common shape, and what auto‑assigning
+  deployments produce): concurrent chats ≤ schedulable workspaces.
+- **Chats bound to a shared `workspaceId`** count it once, so their concurrency
+  is not quota‑bound. They share one filesystem and tool environment — only
+  acceptable within a single tenant / trust boundary.
+
+"Schedulable" is a deployment property, not an SDK knob. Whichever binds first:
+
+| Limit                                     | How it works                                                                                                                                                                                              | When exceeded                                                                                        |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| **Workspace quota** (premium deployments) | Templates declare per‑resource costs. A user's budget is the sum of their groups' quota allowances, enforced when a build starts or stops ([resource quotas](https://coder.com/docs/admin/users/quotas)). | The build **fails** (`INSUFFICIENT_QUOTA`, "insufficient quota"); the turn never gets its workspace. |
+| **Infrastructure**                        | No per‑user workspace limit by default without quotas ([workspace lifecycle](https://coder.com/docs/user-guides/workspace-lifecycle)). The bound is provisioner throughput and cluster capacity.          | Slow or failing builds, not a crisp quota error.                                                     |
+
+Practical sizing:
+
+1. **Read headroom before fanning out.**
+   `GET /api/v2/organizations/{org}/members/{user}/workspace-quota` returns
+   `{ "credits_consumed": …, "budget": … }`. Admit another workspace only while
+   `budget − credits_consumed` covers _that workspace's_ cost (the sum of its
+   template's `daily_cost` declarations).
+   <details><summary>Credits are not slots</summary>
+
+   "Free slots = headroom ÷ cost" only holds for a homogeneous fleet on one
+   template. With mixed templates, size against each planned workspace's own
+   cost.
+
+   </details>
+
+2. **Queue the rest client‑side.** An unschedulable turn does not queue
+   usefully on the server ([Preventing stuck turns](#preventing-stuck-turns)).
+3. **Reuse one bound workspace** across sequential turns and sessions. The
+   workspace is the expensive part; the chat is cheap. Reuse only **within one
+   tenant / trust boundary**: 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.
+4. **Send steps that don't need server‑side tools to the
+   [provider](https://github.com/coder/ai-sdk/tree/main/packages/provider)** — it never touches a workspace.
+
+## Autostop & cleanup
+
+Manage two lifetimes separately:
+
+- **Chats:** `archive()` / `await using` every agent
+  ([Cleanup](../README.md#cleanup)), or finished chats keep holding server
+  resources.
+- **Workspaces:** rely on template‑level scheduling, not manual hygiene.
+
+| Template setting                | What to do                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Autostop 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. [Sandbox](https://github.com/coder/ai-sdk/tree/main/packages/sandbox): `stopAfter: "8h"` sets `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 server‑side tool use keeps a workspace alive.                                                                                                                                     |
+| **Dormancy / failure cleanup**  | Reaps abandoned and repeatedly‑failing workspaces automatically ([template scheduling](https://coder.com/docs/admin/templates/managing-templates/schedule)).                                                                                                                                                                                                   |
+
+**Stopping is not enough.** A _stopped_ workspace typically still consumes its
+persistent resources' `daily_cost` (disks, volumes), so a scratch fleet that
+only ever stops converges on a full budget. Pair the TTL with dormancy
+auto‑deletion or explicit deletion.
+
+## Preventing stuck turns
+
+The signature failure of an over‑committed fleet: the chat is created, the
+stream opens, then nothing. There is **no distinct "quota exceeded" error kind
+on the chat stream.** An unschedulable chat surfaces a generic turn error or
+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. Pair it with a
+   reconciliation sweep: periodically interrupt/archive non‑terminal chats
+   older than your budget.
+   <details><summary>Why the run is not guaranteed released on timeout</summary>
+
+   The timeout fires a server‑side interrupt **best‑effort**: fire‑and‑forget,
+   and unreachable when the timeout lands before chat creation returned an id.
+   The run usually stops, but is not guaranteed released
+   ([Timeouts](../README.md#timeouts--cancellation)).
+
+   </details>
+
+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**: a
+   stream‑loss error is `isRetryable` only when the failed turn created its
+   chat _and_ had no workspace, no MCP servers, and no fresh uploads
+   ([Timeouts](../README.md#timeouts--cancellation)). Re‑check quota headroom
+   before retrying, or you re‑queue into the same wall.
+4. **Watch the fleet.** [`watchChats`](../README.md#watching-chats) yields
+   status changes for every chat **visible to the authenticated user** — run
+   one watcher per identity for per‑tenant credentials, or use a credential
+   that sees them all. Alert on chats in a non‑terminal status (e.g. `pending`)
+   longer than your `requestTimeoutMs`. Seed and periodically reconcile against
+   `GET /api/v2/chats`; don't trust the event stream alone.
+   <details><summary>Why events alone miss stuck chats</summary>
+
+   Reconnects resubscribe fresh (no cursor or replay). A chat already stuck
+   before the watcher started — or one that transitioned during a gap — never
+   emits an event to start your timer from.
+
+   </details>
+
+## Troubleshooting: unschedulable & stuck chats
+
+Wire [`onTransportEvent`](../README.md#observability) into fleet telemetry; the
+event sequence pinpoints _where_ a turn died. Expand the symptom you see.
+
+<details><summary><code>segment:start</code> and <code>ws:open</code> fired, initial status events, then silence</summary>
+
+No `message_part`, no `segment:settle`.
+
+- **Likely cause:** 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.
+- **Fix:** 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.
+  Set `requestTimeoutMs` so this fails loudly next time.
+
+</details>
+
+<details><summary><code>segment:settle</code> carries a <code>CoderChatError</code> mentioning the <code>requestTimeoutMs</code> budget</summary>
+
+The event looks like
+`error: { name: "CoderChatError", message: "…requestTimeoutMs budget…" }`.
+
+- **Likely cause:** the per‑segment bound expired — wedged server, slow model,
+  or an unschedulable workspace.
+- **Fix:** inspect the workspace via the v2 API/UI. A `pending`/`failed` build
+  means the previous symptom; `running` means the turn was genuinely slow —
+  raise `requestTimeoutMs` for long tool work.
+
+</details>
+
+<details><summary>Repeated <code>ws:redial</code>, then a <code>CoderStreamError</code></summary>
+
+`consecutiveFailures` climbs toward `maxConsecutiveFailures` (5; backoff
+1 s → 2 s → 4 s → 8 s, ≈15 s of redialing without forward progress).
+
+- **Likely cause:** the network path to the deployment is failing — not
+  workspace scheduling (the server keeps generating through short gaps).
+- **Fix:** fix connectivity. Mind [retry ownership](#preventing-stuck-turns):
+  on workspace‑backed chats the error is `isRetryable: false`, so the replay
+  decision is yours.
+
+</details>
+
+<details><summary><code>segment:settle</code> with <code>status: "error"</code> and an <code>error</code> payload</summary>
+
+- **Likely cause:** 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.
+- **Fix:** the settle event's `error` carries only `{ name, message }`. To
+  branch on `kind` / `retryable` / `statusCode`, catch 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](../README.md#handling-errors)).
+  Check the workspace build state to rule scheduling in or out.
+
+</details>
+
+<details><summary>Turn settled <code>status: "requires_action"</code>; follow‑up messages queue forever</summary>
+
+- **Likely cause:** the loop ended on an unanswered client tool call.
+- **Fix:** submit the stranded results or interrupt — see [rule 4 of the structured-output guide](./structured-output.md#4-settle-a-turn-that-stopped-on-a-tool-call). If a crash left the
+  pause behind, reconcile effects first
+  ([Make client tools crash-safe](./durable-workflows.md#make-client-tools-crash-safe)).
+
+</details>
+
+<details><summary><code>archive()</code> keeps returning 409 and rethrows after ~15 s</summary>
+
+- **Likely cause:** the chat never settled server‑side — usually a stuck run
+  still holding its workspace.
+- **Fix:** `interrupt()` with a bounded signal, then re‑archive. If the run
+  stays wedged, stop the workspace itself.
+
+</details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coder/ai-sdk-agent",
-  "version": "0.11.6",
+  "version": "0.11.8",
   "description": "A Vercel AI SDK-compliant agent backed by Coder Agents, Coder's server-side agent runtime. `new CoderAgent()` returns a real AI SDK Agent (generate/stream).",
   "keywords": [
     "agent",
@@ -25,6 +25,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
   "type": "module",
@@ -46,10 +47,10 @@
     "ws": "^8.21.3"
   },
   "devDependencies": {
-    "@ai-sdk/react": "4.0.111",
+    "@ai-sdk/react": "4.0.114",
     "@types/node": "^26.6.2",
     "@types/ws": "^8.18.1",
-    "ai": "^7.0.108",
+    "ai": "^7.0.111",
     "tsup": "^8.5.1",
     "tsx": "^4.23.15",
     "typescript": "^6.0.3",