@coder/ai-sdk-agent 0.2.0 → 0.3.0

package/README.md

@@ -43,10 +43,12 @@ pure text/JSON steps and the Agent only for the steps that touch tools.
 ## Install
 
 ```bash
-pnpm add @coder/ai-sdk-agent ai zod
+pnpm add @coder/ai-sdk-agent ai@^6 zod
 ```
 
-Requires Node ≥ 20 and `ai` v6.
+Requires Node ≥ 20 and `ai` v6 — the constructors throw an actionable error when
+another `ai` major is detected (the guard fails open when the installed version
+can't be resolved), instead of failing cryptically mid‑generation.
 
 ## Quick start
 
@@ -96,6 +98,7 @@ pnpm example:stream       # streaming via textStream
 pnpm example:tool         # custom (client-executed) tool round-trip
 pnpm example:multi-turn   # multi-turn session memory
 pnpm example:file         # attach a file to a chat (optional: pass a path)
+pnpm example:structured   # typed structured output via the structured_output tool
 ```
 
 Each example creates a new chat and archives it when done — it never touches workspaces. See
@@ -113,6 +116,12 @@ AI SDK tool loop — your `execute` runs in your process.
   appear in the transcript as `providerExecuted` tool calls/results — you observe them, you
   don't execute them.
 
+Migration note: since v0.2.1 server‑executed tools stream with `dynamic: true`
+(they aren't in your `ToolSet`, and the AI SDK only accepts unknown tool names on
+dynamic calls). In UI message streams they therefore surface as `dynamic-tool`
+parts rather than `tool-{name}` parts — key off `toolName`, not `part.type`, when
+rendering them.
+
 ## Files
 
 There are two distinct ways to get a file to the agent, depending on whether the model should
@@ -202,13 +211,81 @@ created on the first turn and reused for subsequent `generate()`/`stream()` call
 conversation with server‑side history). `agent.chatId` is the current chat id.
 
 - `agent.resetSession()` — start a fresh chat on the next turn (reuse one instance for sequential turns; you don't need a new agent per turn).
-- `agent.interrupt()` — interrupt an in‑flight generation.
-- `agent.archive()` — archive the underlying chat (cleanup; see [Cleanup](#cleanup)).
+- `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: "…" })`.
 
+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
+afterwards. The client‑level `client.interruptChat(chatId, { wait: true })` sends
+`?wait=true` to ask the server to hold the response until the run has stopped —
+current Coder servers ignore the unknown parameter and still return immediately,
+so confirm completion via the event stream (e.g. [`watchChats`](#watching-chats))
+rather than relying on it.
+
 A single instance is **single‑flight** — don't run concurrent generations against it. For concurrency, use one instance per session (and see [Workspaces & quota](#workspaces--quota)).
 
+## Rehydrating chat history
+
+Chat history lives on the server. To render an existing chat in a UI (e.g. after
+a reload), fetch its messages with the `CoderChatClient` (`agent.client`, or one
+you construct — see [Auth](#auth)) and convert them with
+`chatMessagesToUIMessages` — the mapping mirrors what a live‑streamed transcript
+of the same turn looks like:
+
+```ts
+import { chatMessagesToUIMessages } from "@coder/ai-sdk-agent";
+
+const { messages } = await client.getMessages(chatId);
+const uiMessages = chatMessagesToUIMessages(messages);
+// e.g. in React: useChat({ messages: uiMessages })
+```
+
+The converter sorts by message id, so the endpoint's newest‑first default page
+order (and any pagination order) is safe to pass straight in — `useChat` always
+receives a chronological transcript.
+
+Tool calls become `dynamic-tool` parts with their results folded in, `source`
+parts become `source-url` parts, and unknown part kinds are skipped silently, so
+history written by newer Coder servers degrades gracefully. One caveat: history
+does not record which tool names were client (`ToolSet`) tools, so _every_ tool
+call rehydrates as `dynamic-tool` — live, client tools stream as statically
+typed `tool-{name}` parts. Render tools by name (ai's
+`isToolOrDynamicToolUIPart` and `getToolOrDynamicToolName`) rather than by
+exact `part.type` and the difference disappears. Persisted `file`
+parts carry only a `file_id` (no bytes, usually no URL), so pass a `fileUrl`
+resolver to keep attachments visible — download the bytes with
+`client.getChatFile(fileId)` and return a data:/object/proxy URL; parts that end
+up without a URL are skipped:
+
+```ts
+chatMessagesToUIMessages(messages, {
+  fileUrl: (part) => (part.file_id ? `/api/files/${part.file_id}` : undefined),
+});
+```
+
+## Watching chats
+
+`client.watchChats({ signal })` yields lifecycle events (status/title changes,
+creation, deletion, …) for **every chat visible to the authenticated user** as an
+async iterable, backed by the `/api/experimental/chats/watch` WebSocket:
+
+```ts
+for await (const event of client.watchChats({ signal })) {
+  if (event.kind === "status_change") console.log(event.chat.id, event.chat.status);
+}
+```
+
+Unlike the per‑chat event stream, this is a long‑lived subscription: dropped
+connections are redialed automatically with exponential backoff (1s doubling to
+a 30s cap, reset once an event arrives). Iteration ends only when the signal
+aborts, or with a terminal `CoderApiError` when the server rejects the upgrade
+with a 4xx — bad/expired token, or an older Coder server without the endpoint
+(404). For custom plumbing (own client, browser sockets), the standalone
+`watchChatEvents({ baseUrl, token, signal, webSocketFactory })` export provides
+the same stream without a `CoderChatClient`.
+
 ## Timeouts & cancellation
 
 Pass an `abortSignal` to `generate()`/`stream()` to cancel a turn. Aborting
@@ -241,17 +318,28 @@ truncated result as if the turn had finished.
 ## Cleanup
 
 `archive()` soft‑hides the chat (it stays in listings as `archived: true`; there
-is no hard delete yet). To make cleanup ride scope exit instead of a `finally` you
-have to remember, the agent is an **async disposable**:
+is no hard delete yet). A freshly interrupted chat keeps winding down server‑side
+for a few seconds, during which archiving 409s — `archive()` retries those 409s
+(~1s apart, up to ~15s overall; tune with `settleDeadlineMs` /
+`settleRetryDelayMs`) and rethrows the last one if the chat never settles. Any
+other failure, including your own abort, rethrows immediately.
+
+To make cleanup ride scope exit instead of a `finally` you have to remember, the
+agent is an **async disposable**:
 
 ```ts
 await using agent = new CoderAgent({
   /* … */
 });
 const { text } = await agent.generate({ prompt: "…" });
-// agent.archive() runs automatically when the scope exits (best‑effort).
+// agent.interrupt() + agent.archive() run automatically when the scope exits.
 ```
 
+Disposal interrupts any in‑flight run, then archives. It is **bounded and never
+throws** (~15s overall, best‑effort): disposal errors are swallowed so they can't
+mask the scope's own error. Call `archive()` directly when you need guaranteed
+cleanup.
+
 In a request handler that returns before a fire‑and‑forget `archive()` settles, the
 archive can be abandoned — `await using` (or an awaited `archive()` in `finally`)
 avoids accumulating live chats.
@@ -283,15 +371,183 @@ try {
 SDK‑level retry could duplicate a turn. Prefer catching `retryable` errors and
 retrying the whole step deliberately.
 
+## Usage & cost
+
+Results carry normalized token usage in `usage`, plus the verbatim snake_case
+wire usage in `usage.raw` for fields the normalized shape has no slot for
+(`context_limit`, cost, runtime, …). When the server reports them,
+`total_cost_micros` (micro‑USD) and `total_runtime_ms` are also mirrored under
+`providerMetadata.coder` on finish. Both are **absence‑tolerant mirrors**:
+today's Coder servers only expose cost on the aggregate cost endpoints
+(`/api/experimental/chats/cost/*`), so expect these fields to be absent —
+nothing is emitted when the server sends neither.
+
+Forward usage to a UI via message metadata:
+
+```ts
+const result = await agent.stream({ prompt: "…" });
+return result.toUIMessageStream({
+  messageMetadata: ({ part }) =>
+    part.type === "finish-step"
+      ? { usage: part.usage, coder: part.providerMetadata?.coder }
+      : undefined,
+});
+```
+
+## Sources
+
+Model configs with web search enabled emit `source` parts. These flow through to
+`result.sources` and, in UI message streams, `source-url` parts (pass
+`sendSources: true` to `toUIMessageStream` — the AI SDK omits them by default).
+Earlier releases dropped them.
+
 ## Structured output
 
-`CoderAgent` does **not** constrain output to a JSON schema — chatd has no
-server‑side `response_format`, so a `responseFormat` / `experimental_output`
-request emits a warning and is best‑effort at most. For reliable
-schema‑constrained output, use **[`@coder/ai-sdk-provider`](../provider)** with
-`generateObject` / `Output.object` (requires AI Gateway enabled on the
-deployment). Use the Agent for the steps that need server‑side tools; use the
-provider for pure text‑in / JSON‑out steps.
+Coder Agents has no server‑side `response_format`, so `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:
+
+- **Pure text‑in / JSON‑out, no server‑side tools** → use
+  **[`@coder/ai-sdk-provider`](../provider)** with `generateObject` /
+  `Output.object` (schema‑constrained; requires AI Gateway on the deployment).
+- **The answer must come out of an agent run** (server‑side tools, MCP, a
+  workspace) → use the **`structured_output` tool pattern** below. 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 { 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({
+  /* … */
+  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 guards against a failure mode observed live:
+
+1. **Don't force `toolChoice`, don't stop on the call.** `toolChoice` is
+   construction‑time and applies to _every_ segment, so after the ack it would
+   force the tool again and again up to the step ceiling (and it 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,
+   so 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. Guard on `agent.chatId` (it is
+   `undefined` until the first turn creates the chat), then submit the
+   stranded step's (`result.steps.at(-1)`) locally‑executed client outcomes
+   directly via
+   `agent.client.submitToolResults(chatId, { results: [{ tool_call_id, output, is_error }] }, AbortSignal.timeout(8_000))`
+   before touching the chat again, or it strands as in rule 1. Read the
+   outcomes off the step's **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. If
+   a pending call has no local outcome (or the submit fails), end the stranded
+   turn with `agent.client.interruptChat(chatId, AbortSignal.timeout(8_000))`
+   instead. **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, so retry
+   a 409ing archive (`agent.client.archiveChat(chatId, signal)`, per‑attempt
+   bound) under a short deadline instead of giving up.
+
+[`examples/06-structured-output.ts`](./examples/06-structured-output.ts) packages
+all four rules into a small copyable 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 —
+rather than passing `tools:` to the constructor next to the spread, where the
+later key silently clobbers the other map.
+
+## Workspace previews
+
+When the agent is bound to a workspace (the `workspaceId` setting), you can
+resolve — and share — the browser URL where a port on that workspace is served,
+e.g. the dev server the agent just started:
+
+```ts
+const { url } = await agent.getPreview({ port: 3000 });
+// → https://3000--main--dev--alice.apps.example.com (private to the workspace owner)
+
+const shared = await agent.sharePreview({ port: 3000, shareLevel: "authenticated" });
+// shared.url is now reachable by any logged-in user; shared.shareLevel is the level in effect
+```
+
+Both are built on the stable v2 workspace APIs (workspace lookup + the wildcard
+apps host; `sharePreview` adds a port‑share upsert), so they work against old
+Coder servers — no experimental endpoints.
+
+- `getPreview({ port, agentName?, protocol?, signal? })` composes the subdomain
+  URL. The URL honors the port's current share level — private to the workspace
+  owner unless shared. `agentName` is optional when the workspace has exactly one
+  agent (with several, the error lists the candidates); `protocol: "https"` means
+  the app speaks TLS _inside the workspace_ (it adds the `s` label suffix,
+  `3000s--…`) and does not affect the browser scheme.
+- `sharePreview({ port, shareLevel?, … })` additionally upserts the port's share
+  level (re‑invoking updates it in place) and returns the level in effect.
+  `shareLevel` is `"authenticated"` (any logged‑in user; the default),
+  `"organization"` (members of the workspace's organization; requires a newer
+  Coder server), or `"public"` (no auth at all — mind what the port serves).
+  Reverting to owner‑only means deleting the share; `"owner"` is not accepted on
+  upsert.
+- Clear failures instead of broken URLs: a deployment without a wildcard access
+  URL (`--wildcard-access-url`) yields an explanatory error, and a server that
+  predates port sharing (< Coder v2.9) yields a 404 `CoderApiError` saying so.
+  Ports below 1000 are rejected up front for the same reason — Coder subdomain
+  URLs only encode 4–5 digit ports, so `80--agent--…` would be parsed as an app
+  named "80" and never resolve; serve the preview on a higher port.
+
+The preview helpers call non‑chat endpoints, so they need `baseUrl` + `token`
+credentials — pass them alongside `client` if you construct one yourself.
 
 ## Workspaces & quota
 
@@ -325,8 +581,18 @@ running many agents at once:
 | `stopWhen`                        | AI SDK stop condition(s); default `stepCountIs(64)`                                              |
 | `maxRetries`                      | default `0` — SDK retries can duplicate server‑side turns; override with care                    |
 | `requestTimeoutMs`                | per‑turn time budget (ms); interrupts the run and rejects (`kind: "timeout"`) instead of hanging |
+| `settleDeadlineMs`                | overall deadline for bounded cleanup (`archive()` 409 retries, disposal); default 15 000         |
+| `settleRetryDelayMs`              | pause between `archive()` retries while the chat settles; default 1000                           |
 | `chatId`                          | resume an existing chat                                                                          |
 
+The `model` hint resolves against the deployment's model configs in order: a
+config UUID is used as‑is, then an exact `provider:model` match, an exact model
+id, a display‑name substring (case‑insensitive), and finally a model‑id
+substring. Partial payloads from older/newer servers are tolerated (entries
+match on the fields they carry), and an unresolvable hint falls back to the
+server's default model instead of failing. Use `agent.listModels()` to see
+what's available.
+
 ## How it works
 
 ```