@coder/ai-sdk-agent 0.1.0 → 0.2.1

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 };