@coder/ai-sdk-agent 0.1.0 → 0.2.0

package/README.md

@@ -21,6 +21,25 @@ context compaction. The Vercel AI SDK runs its loop **client‑side**. This pack
 bridges the two, so a Coder agent looks and feels like a native AI SDK agent without
 re‑implementing the loop.
 
+## Agent vs. provider — which package?
+
+Two packages, two jobs:
+
+- **`@coder/ai-sdk-agent` (this package)** — Coder's **server‑side agent**: the
+  multi‑step tool loop, built‑in tools, MCP servers, workspace‑scoped file/shell
+  tools, sub‑agents, and compaction all run on the deployment. Each `CoderAgent`
+  is one server chat ("session") and may provision a workspace. Reach for it when
+  you need **server‑side tools, MCP, or a workspace**.
+- **[`@coder/ai-sdk-provider`](../provider)** — **plain model calls** through
+  Coder's AI Gateway. A normal AI SDK provider: `generateText`, `streamText`, and
+  **`generateObject` for schema‑constrained structured output**. No chat, no
+  workspace, natively cancelable. Reach for it when you just need **a model**
+  (plan / extract / summarize / classify) with no server‑side tools.
+
+Rule of thumb: **need server‑side tools, MCP, or a workspace → Agent; need a model
+→ provider.** They compose — a multi‑step pipeline often uses the provider for its
+pure text/JSON steps and the Agent only for the steps that touch tools.
+
 ## Install
 
 ```bash
@@ -76,6 +95,7 @@ pnpm example:generate     # non-streaming generate()
 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)
 ```
 
 Each example creates a new chat and archives it when done — it never touches workspaces. See
@@ -93,6 +113,74 @@ 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.
 
+## Files
+
+There are two distinct ways to get a file to the agent, depending on whether the model should
+**read** it or **operate on** it.
+
+**Chat attachments** — content for the model to read (a PDF, image, CSV…). Drop a native AI SDK
+`file` part into a message and it's uploaded transparently:
+
+```ts
+import { readFile } from "node:fs/promises";
+
+await agent.generate({
+  messages: [
+    {
+      role: "user",
+      content: [
+        { type: "text", text: "Summarize this report." },
+        {
+          type: "file",
+          data: await readFile("report.pdf"),
+          mediaType: "application/pdf",
+          filename: "report.pdf",
+        },
+      ],
+    },
+  ],
+});
+```
+
+Or upload once and reuse across turns with `attach()` — which also accepts a `Blob`/`File` or
+stream (use `fs.openAsBlob` to avoid reading the whole file into memory):
+
+```ts
+const file = await agent.attach({
+  content: await openAsBlob("report.pdf"),
+  mediaType: "application/pdf",
+});
+await agent.generate({
+  messages: [
+    {
+      role: "user",
+      content: [
+        { type: "text", text: "List the risks." },
+        file.toFilePart(), // references the upload by id — no re-upload
+      ],
+    },
+  ],
+});
+```
+
+Attachments are capped at **10 MiB** and restricted to a narrow media‑type allowlist
+(`application/pdf`, `application/json`, `text/{plain,markdown,csv}`, `image/{png,jpeg,gif,webp}`).
+Oversized or unsupported files throw a clear error up front.
+
+**Workspace files** — material for the agent to operate on (a zip of assets, a dataset, a
+binary — anything outside the allowlist or over the cap). Write it onto the workspace filesystem
+and let the agent's tools take over. This needs a `workspaceFiles` adapter (the agent core stays
+dependency‑free; whoever holds a workspace connection supplies a few‑line adapter):
+
+```ts
+const agent = new CoderAgent({ /* … */ workspaceId: ws.id, workspaceFiles });
+const { path } = await agent.uploadToWorkspace({
+  content: await openAsBlob("assets.zip"),
+  path: "assets.zip",
+});
+// Then ask the agent to `unzip assets.zip` — uploadToWorkspace writes bytes as-is; it does not unpack.
+```
+
 ## Auth
 
 Pass a Coder **API token** or **session token** as `token`; it is sent as the
@@ -113,30 +201,131 @@ One `CoderAgent` instance maps to one chat ("session") on the Coder server. The
 created on the first turn and reused for subsequent `generate()`/`stream()` calls (multi‑turn
 conversation with server‑side history). `agent.chatId` is the current chat id.
 
-- `agent.resetSession()` — start a fresh chat on the next turn.
+- `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).
+- `agent.archive()` — 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: "…" })`.
 
-A single instance is **single‑flight** — don't run concurrent generations against 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)).
+
+## Timeouts & cancellation
+
+Pass an `abortSignal` to `generate()`/`stream()` to cancel a turn. Aborting
+**interrupts the server‑side run** (not just the local socket), so the chat stops
+generating and releases its resources instead of running on, orphaned. Tearing
+down a `stream()` early (cancelling the stream) interrupts the run too.
+
+For a hard ceiling, set `requestTimeoutMs`. If a segment runs longer (e.g. the
+server is wedged, or a workspace can't be scheduled), the run is interrupted and
+the call rejects with a retryable `CoderChatError` (`kind: "timeout"`) instead of
+hanging:
+
+```ts
+const agent = new CoderAgent({ /* … */ requestTimeoutMs: 120_000 });
+```
+
+`requestTimeoutMs` bounds **each server segment** — one model round‑trip until it
+settles or pauses for a client tool. A multi‑step `generate()` that drives client
+tools runs several segments, so it bounds each one, not the whole call. To cap the
+**total** wall‑clock of a multi‑step call, pass a deadline as the signal instead:
+
+```ts
+await agent.generate({ prompt: "…", abortSignal: AbortSignal.timeout(120_000) });
+```
+
+If the event stream drops before the turn settles, the call rejects with
+`CoderChatError` (`kind: "stream_closed"`, retryable) rather than returning a
+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**:
+
+```ts
+await using agent = new CoderAgent({
+  /* … */
+});
+const { text } = await agent.generate({ prompt: "…" });
+// agent.archive() runs automatically when the scope exits (best‑effort).
+```
+
+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.
+
+## Handling errors
+
+All errors extend `CoderAgentError`. Two carry structured detail you can branch on:
+
+- **`CoderApiError`** — an HTTP request failed. Fields: `status`, `method`, `path`, `detail`.
+- **`CoderChatError`** — a turn ended in an error, timed out, or lost its stream. Fields: `kind`, `retryable`, `statusCode`, `provider`.
+
+```ts
+import { CoderApiError, CoderChatError } from "@coder/ai-sdk-agent";
+
+try {
+  await agent.generate({ prompt: "…" });
+} catch (err) {
+  if (err instanceof CoderChatError && err.retryable) {
+    // transient (timeout, stream_closed, an upstream 5xx) — back off and retry
+  } else if (err instanceof CoderApiError && err.status === 429) {
+    // rate limited
+  } else {
+    throw err;
+  }
+}
+```
+
+`maxRetries` defaults to `0`: this agent owns server‑side chat state, so an
+SDK‑level retry could duplicate a turn. Prefer catching `retryable` errors and
+retrying the whole step deliberately.
+
+## 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.
+
+## 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.
 
 ## Configuration
 
 `CoderAgentSettings`:
 
-| field                             | description                                                                   |
-| --------------------------------- | ----------------------------------------------------------------------------- |
-| `client` \| (`baseUrl` + `token`) | connection (one or the other)                                                 |
-| `organizationId`                  | org UUID that owns the chat (required)                                        |
-| `model`                           | model hint: UUID, `provider:model`, model id, or display‑name substring       |
-| `instructions`                    | system prompt                                                                 |
-| `tools`                           | AI SDK `ToolSet` (client‑executed)                                            |
-| `workspaceId`                     | bind the chat to a Coder workspace (enables workspace‑scoped tools)           |
-| `mcpServerIds`                    | server‑side MCP servers to enable                                             |
-| `planMode`                        | enable plan mode (`"plan"`)                                                   |
-| `stopWhen`                        | AI SDK stop condition(s); default `stepCountIs(64)`                           |
-| `maxRetries`                      | default `0` — SDK retries can duplicate server‑side turns; override with care |
-| `chatId`                          | resume an existing chat                                                       |
+| field                             | description                                                                                      |
+| --------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `client` \| (`baseUrl` + `token`) | connection (one or the other)                                                                    |
+| `organizationId`                  | org UUID that owns the chat (required)                                                           |
+| `model`                           | model hint: UUID, `provider:model`, model id, or display‑name substring                          |
+| `instructions`                    | system prompt                                                                                    |
+| `tools`                           | AI SDK `ToolSet` (client‑executed)                                                               |
+| `workspaceId`                     | bind the chat to a Coder workspace (enables workspace‑scoped tools)                              |
+| `workspaceFiles`                  | adapter enabling `uploadToWorkspace()` (write files to the workspace FS)                         |
+| `mcpServerIds`                    | server‑side MCP servers to enable                                                                |
+| `planMode`                        | enable plan mode (`"plan"`)                                                                      |
+| `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 |
+| `chatId`                          | resume an existing chat                                                                          |
 
 ## How it works
 
@@ -154,6 +343,28 @@ CoderAgent  (implements ai.Agent)
 - Streaming text is emitted from `message_part` deltas; fast turns that only produce a full
   `message` snapshot are diffed against an emitted‑length cursor — so neither double‑counts.
 
+## 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
+  [`@coder/ai-sdk-provider`](../provider) + `generateObject` — no chat, no
+  workspace, no cleanup.
+
 ## Testing
 
 ```bash
@@ -178,7 +389,6 @@ The e2e suite creates **new chats only** (no workspaces) and archives them after
 ## Limitations
 
 - The Coder chat API is experimental (`/api/experimental/chats`); wire types may change.
-- File/image **inputs** are not yet forwarded to the server (text prompts only).
 - Designed for Node (WebSocket via `ws`); a browser build can inject a `webSocketFactory`.
 - A v7 `@ai-sdk/harness` adapter (the conceptually exact fit) is a future direction once that
   experimental API stabilizes.

package/dist/index.d.ts

@@ -1,5 +1,49 @@
-import { ToolSet, Agent, SystemModelMessage, ToolChoice, StopCondition, ToolLoopAgent } from 'ai';
-import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3StreamResult, LanguageModelV3GenerateResult, LanguageModelV3StreamPart, LanguageModelV3Prompt } from '@ai-sdk/provider';
+import { FilePart, ToolSet, Agent, SystemModelMessage, ToolChoice, StopCondition, ToolLoopAgent } from 'ai';
+import { LanguageModelV3DataContent, LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3StreamResult, LanguageModelV3GenerateResult, LanguageModelV3StreamPart, LanguageModelV3Message, LanguageModelV3Prompt } from '@ai-sdk/provider';
+
+/**
+ * Bytes to upload, in any convenient shape.
+ *
+ * `Blob`/`File` is the recommended form: it is lazy (not forced fully into
+ * memory), carries its own size (so the 10 MiB chat cap can fail fast and a
+ * `Content-Length` can be sent), is re-readable (so a failed upload can be
+ * retried), and works both in Node (`fs.openAsBlob("./x.pdf")`) and the browser
+ * (an `<input type=file>` yields a `File`). A `ReadableStream` is accepted for
+ * genuinely unbounded sources, but its size is unknown up front — the chat size
+ * cap can then only be enforced server-side.
+ */
+type FileContent = Blob | ReadableStream<Uint8Array> | Uint8Array | ArrayBuffer;
+/** A {@link FileContent} normalized for upload: a fetch-ready body plus derived metadata. */
+interface ResolvedFile {
+    /**
+     * Body to hand to `fetch`. Raw bytes are wrapped in a `Blob` so the body is
+     * always a clean `BodyInit` (and bytes get a `Content-Length` for free).
+     */
+    body: Blob | ReadableStream<Uint8Array>;
+    /** Resolved IANA media type. */
+    mediaType: string;
+    /** Original filename, if known. */
+    name: string | undefined;
+    /** Byte length, if known up front (undefined for streams). */
+    size: number | undefined;
+}
+/**
+ * Normalize {@link FileContent} into a fetch-ready body and derive its media
+ * type, name, and (when known) size. `Blob`/`File` supply their own
+ * `type`/`name`/`size`; for raw bytes or a stream, `mediaType` must be provided
+ * by the caller. Explicit `opts.mediaType`/`opts.name` always win.
+ */
+declare function resolveFileContent(content: FileContent, opts?: {
+    mediaType?: string;
+    name?: string;
+}): ResolvedFile;
+/**
+ * Convert an AI SDK file-part `data` value into {@link FileContent} for upload.
+ * The provider receives bytes or a base64 string (and, rarely, a URL). URLs are
+ * not expected: this model declares no `supportedUrls`, so the SDK downloads
+ * them to bytes before calling us — a URL here is therefore an error.
+ */
+declare function dataContentToFileContent(data: LanguageModelV3DataContent): FileContent;
 
 /**
  * Wire types for Coder's experimental `chatd` chat API
@@ -19,6 +63,18 @@ interface ChatInputPart {
     end_line?: number;
     content?: string;
 }
+/**
+ * Media types accepted by the chat-file upload endpoint
+ * (`POST /api/experimental/chats/files`). The server allowlist is intentionally
+ * narrow — anything else (zip, tarball, binaries, …) is not a chat attachment
+ * and belongs on the workspace filesystem instead. Mirrors
+ * `codersdk.AllChatAttachmentMediaTypes`.
+ */
+type ChatAttachmentMediaType = "application/json" | "application/pdf" | "image/gif" | "image/jpeg" | "image/png" | "image/webp" | "text/csv" | "text/markdown" | "text/plain";
+/** The chat-attachment media-type allowlist, as a runtime-checkable set. */
+declare const CHAT_ATTACHMENT_MEDIA_TYPES: ReadonlySet<string>;
+/** Per-file size cap enforced by the chat-file upload endpoint (10 MiB). */
+declare const MAX_CHAT_FILE_SIZE_BYTES: number;
 type ChatClientType = "ui" | "api";
 type ChatPlanMode = "" | "plan";
 type ChatBusyBehavior = "queue" | "interrupt";
@@ -175,6 +231,10 @@ interface ChatMessagesResponse {
     queued_messages: ChatQueuedMessage[];
     has_more: boolean;
 }
+/** Response from `POST /api/experimental/chats/files`: the uploaded file's id. */
+interface UploadChatFileResponse {
+    id: string;
+}
 interface ChatModelConfig {
     id: string;
     provider: string;
@@ -280,6 +340,24 @@ interface StreamChatEventsOptions {
  */
 declare function streamChatEvents(options: StreamChatEventsOptions): AsyncGenerator<ChatStreamEvent, void, void>;
 
+/** A file to upload as a chat attachment. */
+interface ChatFileInput {
+    content: FileContent;
+    /**
+     * Media type. Required unless `content` is a Blob/File with a non-empty `type`
+     * — note `fs.openAsBlob()` returns a Blob with no type, so pass it explicitly there.
+     */
+    mediaType?: string;
+    /** Original filename, surfaced to the model and UI. Defaults to a File's `name`. */
+    name?: string;
+}
+/** A file that has been uploaded to chat-file storage. */
+interface UploadedChatFile {
+    /** Server-assigned file id, referenced from message content via a `file` part. */
+    id: string;
+    mediaType: string;
+    name?: string;
+}
 interface CoderChatClientOptions {
     /** Base URL of the Coder deployment, e.g. `https://dev.coder.com`. */
     baseUrl: string;
@@ -312,6 +390,21 @@ declare class CoderChatClient {
     updateChat(chatId: string, req: UpdateChatRequest, signal?: AbortSignal): Promise<void>;
     /** Convenience: archive a chat (soft-hide; safe for cleanup). */
     archiveChat(chatId: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Upload a file as a durable chat attachment, returning its id (referenced
+     * from message content via a `file` input part). The server enforces a narrow
+     * media-type allowlist and a 10 MiB cap; both are checked client-side first so
+     * unsupported files fail fast with a clear error instead of an opaque 4xx.
+     *
+     * The body is sent raw (not multipart): `Content-Type` carries the media type
+     * and `Content-Disposition` the filename, mirroring `codersdk`.
+     */
+    uploadChatFile(organizationId: string, file: ChatFileInput, signal?: AbortSignal): Promise<UploadedChatFile>;
+    /** Download a chat file's bytes and media type by id. */
+    getChatFile(fileId: string, signal?: AbortSignal): Promise<{
+        bytes: Uint8Array;
+        mediaType: string;
+    }>;
     streamEvents(chatId: string, opts?: {
         afterId?: number;
         signal?: AbortSignal;
@@ -327,7 +420,67 @@ declare class CoderChatClient {
     resolveModelConfigId(hint: string, signal?: AbortSignal): Promise<string | undefined>;
 }
 
+/**
+ * Adapter that writes bytes onto a Coder workspace's filesystem, injected into
+ * a {@link CoderAgent} to enable {@link CoderAgent.uploadToWorkspace}.
+ *
+ * This is the "operate on this material" path — for archives, datasets,
+ * binaries, oversized files, or anything outside the narrow chat-attachment
+ * allowlist. It is intentionally NOT bundled into the agent package: the agent
+ * core stays dependency-free, and whoever already holds a workspace connection
+ * (e.g. a `@coder/ai-sdk-eve-sandbox` session) supplies a few-line adapter.
+ *
+ * The store does one thing — write bytes to a path. It deliberately does not
+ * unpack archives or mutate the working tree: instruct the agent to `unzip`/
+ * `tar -x`, or do it over your own connection.
+ *
+ * @example
+ * ```ts
+ * const store: WorkspaceFileStore = {
+ *   workspaceId: session.workspaceId,
+ *   write: async ({ content, path, signal }) => {
+ *     await session.writeFile({ path, content: toStream(content), abortSignal: signal });
+ *     return { path };
+ *   },
+ * };
+ * ```
+ */
+interface WorkspaceFileStore {
+    /** The workspace these writes land in. Should match the agent's bound `workspaceId`. */
+    readonly workspaceId: string;
+    /**
+     * Write `content` to `path` inside the workspace and return the absolute path
+     * it landed at (the adapter may resolve a relative path against a working dir).
+     */
+    write(file: {
+        content: FileContent;
+        path: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        path: string;
+    }>;
+}
+/** Where an uploaded file ended up after {@link CoderAgent.uploadToWorkspace}. */
+interface WorkspacePlacement {
+    workspaceId: string;
+    /** Absolute path of the file inside the workspace. */
+    path: string;
+}
+
 type InnerAgent<TOOLS extends ToolSet> = ToolLoopAgent<never, TOOLS, never>;
+/** A handle to a file uploaded as a chat attachment (see {@link CoderAgent.attach}). */
+interface ChatAttachment extends UploadedChatFile {
+    /**
+     * A native AI SDK `file` part that references this upload by id. Drop it into
+     * a user message's `content` to reuse the file across turns without
+     * re-uploading — the agent recognizes the id and skips the upload.
+     *
+     * The reference travels in `providerOptions.coder.fileId`; if you persist the
+     * part through a store that strips `providerOptions`, the reference is lost
+     * (re-`attach()` instead of persisting the handle).
+     */
+    toFilePart(): FilePart;
+}
 interface CoderAgentSettings<TOOLS extends ToolSet = {}> {
     /** A pre-built {@link CoderChatClient}. Mutually exclusive with baseUrl/token. */
     client?: CoderChatClient;
@@ -343,6 +496,12 @@ interface CoderAgentSettings<TOOLS extends ToolSet = {}> {
     model?: string;
     /** Bind the chat to a Coder workspace (enables workspace-scoped tools). */
     workspaceId?: string;
+    /**
+     * Adapter for writing files onto a workspace filesystem, enabling
+     * {@link CoderAgent.uploadToWorkspace}. Supply one backed by a workspace
+     * connection (e.g. a `@coder/ai-sdk-eve-sandbox` session).
+     */
+    workspaceFiles?: WorkspaceFileStore;
     /** chatd-side MCP servers to enable for this chat. */
     mcpServerIds?: string[];
     /** chatd plan mode. */
@@ -363,6 +522,18 @@ interface CoderAgentSettings<TOOLS extends ToolSet = {}> {
      * SDK retries could duplicate a turn. Override with care.
      */
     maxRetries?: number;
+    /**
+     * Per-segment time budget in milliseconds, applied to each model round-trip
+     * (chat creation / message / tool-result submission plus the server run until
+     * it settles). If a segment runs longer (e.g. the server is wedged or a
+     * workspace can't be scheduled), the run is interrupted server-side and the
+     * call rejects with a retryable {@link CoderChatError} (`kind: "timeout"`)
+     * instead of hanging. A multi-step `generate()` driving client tools makes
+     * several segments, so this bounds each one — to cap total wall-clock for the
+     * whole call, pass `abortSignal: AbortSignal.timeout(ms)`. Unset or
+     * non-positive means no limit.
+     */
+    requestTimeoutMs?: number;
 }
 /**
  * An AI SDK-compliant agent backed by a remote Coder `chatd` agent runtime.
@@ -388,12 +559,62 @@ declare class CoderAgent<TOOLS extends ToolSet = {}> implements Agent<never, TOO
     get chatId(): string | undefined;
     generate(options: Parameters<InnerAgent<TOOLS>["generate"]>[0]): ReturnType<InnerAgent<TOOLS>["generate"]>;
     stream(options: Parameters<InnerAgent<TOOLS>["stream"]>[0]): ReturnType<InnerAgent<TOOLS>["stream"]>;
+    /**
+     * List the model configs available on the deployment. Use this to discover
+     * valid values for the `model` hint instead of guessing ids — match on
+     * `id`, `provider`/`model`, or `display_name`.
+     */
+    listModels(signal?: AbortSignal): Promise<ChatModelConfig[]>;
     /** Start a fresh chatd chat on the next turn. */
     resetSession(): void;
     /** Interrupt the in-flight generation, if any. */
     interrupt(): Promise<void>;
     /** Archive the underlying chat (safe cleanup; hides it from listings). */
     archive(): Promise<void>;
+    /**
+     * Clean up the chat when the agent leaves an `await using` scope, so cleanup
+     * rides scope exit instead of a separate call you have to remember in a
+     * `finally`. Interrupts any in-flight server run, then archives the chat.
+     * Best-effort: disposal errors are swallowed so they can't mask the scope's
+     * own error.
+     *
+     * @example
+     * ```ts
+     * await using agent = new CoderAgent({ ... });
+     * const { text } = await agent.generate({ prompt: "…" });
+     * // agent.interrupt() + agent.archive() run automatically here.
+     * ```
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Upload a file as a chat attachment — content for the model to *read* (a PDF,
+     * image, CSV, …). Returns a handle you can reference from a later turn via
+     * {@link ChatAttachment.toFilePart} (no re-upload). Validated against the chat
+     * allowlist and 10 MiB cap up front.
+     *
+     * You usually don't need this: a native AI SDK `file` part dropped into a
+     * message's `content` is uploaded transparently. Reach for `attach()` to
+     * pre-upload, to reuse one file across turns, or to validate before sending.
+     *
+     * For large or non-allowlisted files (zips, datasets, binaries) — material for
+     * the agent to *operate on* — use {@link CoderAgent.uploadToWorkspace}.
+     */
+    attach(file: ChatFileInput, signal?: AbortSignal): Promise<ChatAttachment>;
+    /**
+     * Write a file onto the bound workspace's filesystem for the agent to operate
+     * on (extract, build, read with its tools). Requires a {@link WorkspaceFileStore}
+     * via the `workspaceFiles` setting. The file is written as-is — no unpacking;
+     * instruct the agent to `unzip`/`tar -x`, or extract over your own connection.
+     *
+     * The chat should be bound to the same workspace (`workspaceId`) so the agent's
+     * server-side tools can see the file.
+     */
+    uploadToWorkspace(file: {
+        content: FileContent;
+        /** Destination path inside the workspace (the adapter may resolve relatives). */
+        path: string;
+        signal?: AbortSignal;
+    }): Promise<WorkspacePlacement>;
 }
 
 interface CoderLanguageModelConfig {
@@ -408,6 +629,17 @@ interface CoderLanguageModelConfig {
     planMode?: "" | "plan";
     /** Resume an existing chat instead of creating a new one. */
     chatId?: string;
+    /**
+     * Per-segment time budget in milliseconds, applied to each model round-trip
+     * (one `doStream`/`doGenerate` call: chat creation or message/tool-result
+     * submission, plus the server-side run until it settles or pauses for a client
+     * tool). If exceeded, the run is interrupted server-side and the call rejects
+     * with a retryable {@link CoderChatError} (`kind: "timeout"`). A multi-step
+     * `generate()` that drives client tools makes several segments, so this bounds
+     * each segment, not the whole call — to cap total wall-clock, pass
+     * `abortSignal: AbortSignal.timeout(ms)`. Unset or non-positive means no limit.
+     */
+    requestTimeoutMs?: number;
 }
 /**
  * A {@link LanguageModelV3} that is backed by a remote Coder `chatd` agent
@@ -468,11 +700,39 @@ declare class TurnTranslator {
     finish(): LanguageModelV3StreamPart[];
 }
 
+/** Namespace key for this package's options on AI SDK message-part `providerOptions`. */
+declare const CODER_PROVIDER_OPTIONS = "coder";
+/** Shape of this package's `providerOptions.coder` payload on a file part. */
+interface CoderFileProviderOptions {
+    /** A pre-uploaded chat-file id to reuse instead of uploading the part's bytes. */
+    fileId?: string;
+}
 /** Concatenated system messages, mapped to chatd's `system_prompt`. */
 declare function extractSystemPrompt(prompt: LanguageModelV3Prompt): string | undefined;
+/** The content array of a user message (text and file parts). */
+type UserContent = Extract<LanguageModelV3Message, {
+    role: "user";
+}>["content"];
+/**
+ * Uploads a file part's bytes and resolves to its chatd file id. Supplied by
+ * the language model (which holds the client + organization id); kept abstract
+ * here so {@link userContentToInputParts} stays pure and testable.
+ */
+type FilePartUploader = (file: {
+    data: LanguageModelV3DataContent;
+    mediaType: string;
+    filename?: string;
+}) => Promise<string>;
+/**
+ * Maps a user message's content to chatd input parts. Text passes through;
+ * file parts are turned into `file` parts referencing an uploaded file id —
+ * either reused from `providerOptions.coder.fileId` (a pre-uploaded handle) or
+ * uploaded on the fly via {@link FilePartUploader}.
+ */
+declare function userContentToInputParts(content: UserContent, uploadFile: FilePartUploader): Promise<ChatInputPart[]>;
 type TurnAction = {
     kind: "new-turn";
-    content: ChatInputPart[];
+    content: UserContent;
 } | {
     kind: "resume";
     toolResults: ToolResult[];
@@ -523,4 +783,4 @@ declare class CoderChatError extends CoderAgentError {
     constructor(payload: ChatErrorPayload);
 }
 
-export { type Chat, type ChatBusyBehavior, type ChatClientType, type ChatErrorPayload, type ChatInputPart, type ChatInputPartType, type ChatMessage, type ChatMessagePart, type ChatMessagePartType, type ChatMessageRole, type ChatMessageUsage, type ChatMessagesResponse, type ChatModelConfig, type ChatPlanMode, type ChatQueuedMessage, type ChatStatus, type ChatStreamActionRequired, type ChatStreamEvent, type ChatStreamEventType, type ChatStreamMessagePart, type ChatStreamRetry, type ChatStreamStatus, type ChatStreamToolCall, CoderAgent, CoderAgentError, type CoderAgentSettings, CoderApiError, CoderChatClient, type CoderChatClientOptions, CoderChatError, CoderLanguageModel, type CoderLanguageModelConfig, type CreateChatMessageRequest, type CreateChatMessageResponse, type CreateChatRequest, type DynamicTool, type SubmitToolResultsRequest, TERMINAL_STATUSES, type ToolResult, type TurnAction, TurnTranslator, type UpdateChatRequest, type WebSocketFactory, type WebSocketLike, classifyTurnAction, dynamicToolNames, extractSystemPrompt, streamChatEvents, toolsToDynamicTools };
+export { CHAT_ATTACHMENT_MEDIA_TYPES, CODER_PROVIDER_OPTIONS, type Chat, type ChatAttachment, type ChatAttachmentMediaType, type ChatBusyBehavior, type ChatClientType, type ChatErrorPayload, type ChatFileInput, type ChatInputPart, type ChatInputPartType, type ChatMessage, type ChatMessagePart, type ChatMessagePartType, type ChatMessageRole, type ChatMessageUsage, type ChatMessagesResponse, type ChatModelConfig, type ChatPlanMode, type ChatQueuedMessage, type ChatStatus, type ChatStreamActionRequired, type ChatStreamEvent, type ChatStreamEventType, type ChatStreamMessagePart, type ChatStreamRetry, type ChatStreamStatus, type ChatStreamToolCall, CoderAgent, CoderAgentError, type CoderAgentSettings, CoderApiError, CoderChatClient, type CoderChatClientOptions, CoderChatError, type CoderFileProviderOptions, CoderLanguageModel, type CoderLanguageModelConfig, type CreateChatMessageRequest, type CreateChatMessageResponse, type CreateChatRequest, type DynamicTool, type FileContent, type FilePartUploader, MAX_CHAT_FILE_SIZE_BYTES, type ResolvedFile, type SubmitToolResultsRequest, TERMINAL_STATUSES, type ToolResult, type TurnAction, TurnTranslator, type UpdateChatRequest, type UploadChatFileResponse, type UploadedChatFile, type UserContent, type WebSocketFactory, type WebSocketLike, type WorkspaceFileStore, type WorkspacePlacement, classifyTurnAction, dataContentToFileContent, dynamicToolNames, extractSystemPrompt, resolveFileContent, streamChatEvents, toolsToDynamicTools, userContentToInputParts };