@coder/ai-sdk-agent 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { FilePart, ToolSet, Agent, SystemModelMessage, ToolChoice, StopCondition, ToolLoopAgent } from 'ai';
+import { FilePart, ToolSet, Agent, SystemModelMessage, ToolChoice, StopCondition, ToolLoopAgent, UIMessage } from 'ai';
 import { LanguageModelV3DataContent, LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3StreamResult, LanguageModelV3GenerateResult, LanguageModelV3StreamPart, LanguageModelV3Message, LanguageModelV3Prompt } from '@ai-sdk/provider';
 
 /**
@@ -175,6 +175,13 @@ interface ChatMessageUsage {
     cache_creation_tokens?: number;
     cache_read_tokens?: number;
     context_limit?: number;
+    /**
+     * Cost in micro-USD, when the server prices usage. Optional: servers that
+     * don't price usage (or predate cost reporting) omit it.
+     */
+    total_cost_micros?: number;
+    /** Model runtime in milliseconds, when the server reports it. */
+    total_runtime_ms?: number;
 }
 interface ChatMessage {
     id: number;
@@ -235,12 +242,18 @@ interface ChatMessagesResponse {
 interface UploadChatFileResponse {
     id: string;
 }
+/**
+ * A configured model (`GET /api/experimental/chats/model-configs`). Depending
+ * on the server version and how a config was created, `provider`, `model`, and
+ * `display_name` may be absent on individual entries, so treat them as
+ * optional and guard reads.
+ */
 interface ChatModelConfig {
     id: string;
-    provider: string;
+    provider?: string;
     ai_provider_id?: string;
-    model: string;
-    display_name: string;
+    model?: string;
+    display_name?: string;
     enabled?: boolean;
     is_default?: boolean;
     context_limit?: number;
@@ -288,6 +301,19 @@ interface ChatStreamEvent {
 }
 /** Terminal statuses: the chat has stopped generating for this turn. */
 declare const TERMINAL_STATUSES: ReadonlySet<ChatStatus>;
+/** Kinds of chat lifecycle events emitted on the per-user watch socket. */
+type ChatWatchEventKind = "status_change" | "summary_change" | "title_change" | "created" | "deleted" | "diff_status_change" | "action_required" | "context_dirty";
+/**
+ * An event from `GET /api/experimental/chats/watch`, which covers every chat
+ * visible to the authenticated user (not a single chat). Mirrors
+ * `codersdk.ChatWatchEvent`.
+ */
+interface ChatWatchEvent {
+    kind: ChatWatchEventKind;
+    chat: Chat;
+    /** Pending client-executed tool calls; sent with `action_required` events. */
+    tool_calls?: ChatStreamToolCall[];
+}
 
 /**
  * A minimal WebSocket factory abstraction so the stream reader can run on
@@ -339,6 +365,27 @@ interface StreamChatEventsOptions {
  * — that triggers generator cleanup, which closes the socket.
  */
 declare function streamChatEvents(options: StreamChatEventsOptions): AsyncGenerator<ChatStreamEvent, void, void>;
+interface WatchChatEventsOptions {
+    baseUrl: string;
+    token: string;
+    signal?: AbortSignal;
+    webSocketFactory?: WebSocketFactory;
+}
+/**
+ * Opens the chatd `/watch` WebSocket — lifecycle events for every chat visible
+ * to the authenticated user — and yields decoded {@link ChatWatchEvent}s as an
+ * async iterable.
+ *
+ * Unlike the per-chat `/stream`, this is a long-lived subscription, so dropped
+ * connections are redialed automatically with exponential backoff (1s doubling
+ * to a 30s cap, reset once an event arrives). It ends in exactly three ways:
+ * `signal` aborting, the consumer ending iteration (`break` from `for await`,
+ * `iterator.return()`) — both tear the socket down promptly even while a read
+ * is pending — or the server rejecting the upgrade with a 4xx — bad/expired
+ * token, or an older Coder server without the endpoint (404) — which throws a
+ * terminal {@link CoderApiError} instead of retrying forever.
+ */
+declare function watchChatEvents(options: WatchChatEventsOptions): AsyncGenerator<ChatWatchEvent, void, void>;
 
 /** A file to upload as a chat attachment. */
 interface ChatFileInput {
@@ -386,7 +433,23 @@ declare class CoderChatClient {
         limit?: number;
     }, signal?: AbortSignal): Promise<ChatMessagesResponse>;
     submitToolResults(chatId: string, req: SubmitToolResultsRequest, signal?: AbortSignal): Promise<void>;
-    interruptChat(chatId: string, signal?: AbortSignal): Promise<Chat>;
+    /**
+     * Interrupt the chat's in-flight run (`POST /interrupt`). The server flips
+     * an active run to `interrupting` and responds immediately with the updated
+     * chat — it does not wait for the run to actually stop.
+     *
+     * Pass `{ wait: true }` to send `?wait=true`, asking the server to hold the
+     * response until the run has stopped. Coder servers without that param
+     * ignore the unknown query harmlessly and still return immediately, so
+     * callers should be prepared to confirm completion via the event stream.
+     *
+     * The second parameter also accepts a bare `AbortSignal` (the historical
+     * signature).
+     */
+    interruptChat(chatId: string, optsOrSignal?: AbortSignal | {
+        wait?: boolean;
+        signal?: AbortSignal;
+    }): Promise<Chat>;
     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>;
@@ -409,6 +472,17 @@ declare class CoderChatClient {
         afterId?: number;
         signal?: AbortSignal;
     }): AsyncGenerator<ChatStreamEvent, void, void>;
+    /**
+     * Watch lifecycle events (status/title changes, creation, deletion, …) for
+     * every chat visible to the authenticated user via the `/chats/watch`
+     * WebSocket. Dropped connections are redialed with exponential backoff; the
+     * iteration ends only when `opts.signal` aborts, or with a terminal
+     * {@link CoderApiError} when the server rejects the upgrade with a 4xx
+     * (bad/expired token, or an older Coder server without the endpoint → 404).
+     */
+    watchChats(opts?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<ChatWatchEvent, void, void>;
     /**
      * Resolves a user-friendly model hint to a model-config UUID.
      *
@@ -416,10 +490,24 @@ declare class CoderChatClient {
      * (e.g. `anthropic:claude-haiku-4-5-20251001`), a bare model id, or a
      * display-name substring (case-insensitive). Returns `undefined` if no
      * match is found, in which case the caller should let chatd pick the default.
+     *
+     * Tolerates partial payloads from older/newer servers: a malformed listing
+     * (empty body, non-array JSON, null entries) resolves as no match, and
+     * entries missing `provider`, `model`, or `display_name` are matched on the
+     * fields they do carry — an entry without `provider` still matches by its
+     * model id, one without `model` only by display name.
      */
     resolveModelConfigId(hint: string, signal?: AbortSignal): Promise<string | undefined>;
 }
 
+/** Share levels a port can be in; `owner` is the implicit default when no share exists. */
+type PortShareLevel = "owner" | "authenticated" | "organization" | "public";
+/**
+ * Share levels the upsert endpoint accepts. `owner` is rejected server-side —
+ * reverting to owner-only is done by deleting the share, not setting it.
+ */
+type PreviewShareLevel = Exclude<PortShareLevel, "owner">;
+
 /**
  * Adapter that writes bytes onto a Coder workspace's filesystem, injected into
  * a {@link CoderAgent} to enable {@link CoderAgent.uploadToWorkspace}.
@@ -482,7 +570,13 @@ interface ChatAttachment extends UploadedChatFile {
     toFilePart(): FilePart;
 }
 interface CoderAgentSettings<TOOLS extends ToolSet = {}> {
-    /** A pre-built {@link CoderChatClient}. Mutually exclusive with baseUrl/token. */
+    /**
+     * A pre-built {@link CoderChatClient}, used instead of constructing one from
+     * `baseUrl`/`token`. The preview helpers ({@link CoderAgent.getPreview},
+     * {@link CoderAgent.sharePreview}) call non-chat endpoints and therefore
+     * still need credentials — pass `baseUrl` + `token` alongside `client` to
+     * enable them.
+     */
     client?: CoderChatClient;
     /** Coder deployment base URL, e.g. `https://dev.coder.com`. */
     baseUrl?: string;
@@ -534,6 +628,56 @@ interface CoderAgentSettings<TOOLS extends ToolSet = {}> {
      * non-positive means no limit.
      */
     requestTimeoutMs?: number;
+    /**
+     * Overall deadline in milliseconds for bounded cleanup: how long
+     * {@link CoderAgent.archive} keeps retrying while a freshly interrupted chat
+     * settles server-side, and how long `[Symbol.asyncDispose]` may take in
+     * total. Default 15 000. Primarily a test/tuning knob.
+     */
+    settleDeadlineMs?: number;
+    /**
+     * Pause in milliseconds between {@link CoderAgent.archive} retries while the
+     * chat settles. Default 1000. Primarily a test/tuning knob.
+     */
+    settleRetryDelayMs?: number;
+}
+/** Options for {@link CoderAgent.getPreview}. */
+interface WorkspacePreviewOptions {
+    /** Workspace port the app listens on (4–5 digit ports parse most reliably). */
+    port: number;
+    /**
+     * Agent that serves the port. Optional when the workspace has exactly one
+     * agent; required when it has several (the error lists the candidates).
+     */
+    agentName?: string;
+    /**
+     * Protocol the app speaks *inside the workspace* on that port — `https` adds
+     * the `s` suffix (`3000s--…`) so the proxy connects over TLS. This is not
+     * the browser scheme, which follows the deployment's access URL.
+     * Default `"http"`.
+     */
+    protocol?: "http" | "https";
+    signal?: AbortSignal;
+}
+/** A resolved workspace preview URL (see {@link CoderAgent.getPreview}). */
+interface WorkspacePreview {
+    /** Browser-openable subdomain app URL, e.g. `https://3000--main--dev--alice.apps.example.com`. */
+    url: string;
+}
+/** Options for {@link CoderAgent.sharePreview}. */
+interface SharePreviewOptions extends WorkspacePreviewOptions {
+    /**
+     * Who may open the preview: `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).
+     */
+    shareLevel?: PreviewShareLevel;
+}
+/** A shared workspace preview (see {@link CoderAgent.sharePreview}). */
+interface SharedWorkspacePreview extends WorkspacePreview {
+    /** The share level now in effect for the port. */
+    shareLevel: PreviewShareLevel;
 }
 /**
  * An AI SDK-compliant agent backed by a remote Coder `chatd` agent runtime.
@@ -567,16 +711,34 @@ declare class CoderAgent<TOOLS extends ToolSet = {}> implements Agent<never, TOO
     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>;
+    /**
+     * Interrupt the in-flight generation, if any. Resolves as soon as the server
+     * acknowledges the interrupt — the run keeps winding down asynchronously for
+     * a few seconds afterwards (see {@link CoderAgent.archive}).
+     */
+    interrupt(opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Archive the underlying chat (safe cleanup; hides it from listings).
+     *
+     * A freshly interrupted/settled chat can keep winding down server-side for a
+     * few seconds, during which the server rejects archiving with a 409. Those
+     * 409s are retried (~1s apart, ~15s overall — see `settleDeadlineMs` /
+     * `settleRetryDelayMs`) and the last one is rethrown if the chat never
+     * settles; any other failure, including a caller abort, rethrows immediately.
+     */
+    archive(opts?: {
+        signal?: AbortSignal;
+    }): 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.
+     * `finally`. Interrupts any in-flight server run, then archives the chat
+     * (retrying while the interrupted run settles). Best-effort and bounded
+     * (~15s overall): disposal errors are swallowed after the bounded attempts
+     * so they can't mask the scope's own error — call {@link CoderAgent.archive}
+     * directly when you need guaranteed cleanup.
      *
      * @example
      * ```ts
@@ -615,6 +777,26 @@ declare class CoderAgent<TOOLS extends ToolSet = {}> implements Agent<never, TOO
         path: string;
         signal?: AbortSignal;
     }): Promise<WorkspacePlacement>;
+    /**
+     * Resolve the browser URL where a port on the bound workspace can be
+     * previewed, e.g. `https://3000--main--dev--alice.apps.example.com`.
+     * Composed from stable v2 endpoints (workspace lookup + wildcard app host),
+     * so it works against old Coder servers. Requires the `workspaceId` setting,
+     * `baseUrl`/`token` credentials, and a deployment with a wildcard access URL
+     * configured.
+     *
+     * The URL honors the port's current share level — private to the workspace
+     * owner unless shared (see {@link CoderAgent.sharePreview}).
+     */
+    getPreview(opts: WorkspacePreviewOptions): Promise<WorkspacePreview>;
+    /**
+     * Share a port on the bound workspace and return its preview URL. Upserts
+     * the port's share level — `authenticated` by default — so teammates (or,
+     * with `public`, anyone) can open what the agent is serving; re-invoking
+     * updates the level in place. On Coder servers that predate port sharing
+     * (< v2.9) this fails with a 404 {@link CoderApiError} saying so.
+     */
+    sharePreview(opts: SharePreviewOptions): Promise<SharedWorkspacePreview>;
 }
 
 interface CoderLanguageModelConfig {
@@ -675,9 +857,12 @@ declare class CoderLanguageModel implements LanguageModelV3 {
  * Translates one chatd turn's {@link ChatStreamEvent} stream into a sequence of
  * `LanguageModelV3StreamPart`s for the AI SDK.
  *
- * Two text/reasoning modes, decided per turn from the wire behavior:
+ * Two text/reasoning modes, decided per assistant message from the wire
+ * behavior:
  *  - **delta mode** — chatd streamed `message_part` deltas; we emit those and
- *    treat the trailing full `message` snapshot as a no-op for text/reasoning.
+ *    treat the message's trailing full `message` snapshot as a no-op for
+ *    text/reasoning. Deltas carry no message id, so "deltas arrived since the
+ *    last assistant snapshot" is what marks a snapshot as trailing.
  *  - **snapshot mode** — fast turns where only full `message` snapshots arrive;
  *    we diff each snapshot's full text against what we've already emitted.
  * Both paths track an emitted-length cursor, so neither double-counts.
@@ -700,6 +885,54 @@ declare class TurnTranslator {
     finish(): LanguageModelV3StreamPart[];
 }
 
+/** Options for {@link chatMessagesToUIMessages}. */
+interface ChatMessagesToUIMessagesOptions {
+    /**
+     * Resolves a persisted `file` part to a URL for its `FileUIPart`. Persisted
+     * file parts carry only a `file_id` (no bytes, and usually no `url`), so
+     * without a URL there is nothing for the UI to render and the part is
+     * skipped. Download the bytes with `CoderChatClient.getChatFile(fileId)`
+     * and return a data:/object/proxy URL here to keep attachments visible.
+     * Returning `undefined` falls back to the part's own `url`, if any.
+     */
+    fileUrl?: (part: ChatMessagePart) => string | undefined;
+}
+/**
+ * Converts persisted chat history (`CoderChatClient.getMessages`) into AI SDK
+ * v6 `UIMessage`s, e.g. to rehydrate `useChat({ messages })` for an existing
+ * chat. Pure and side-effect free.
+ *
+ * The mapping mirrors what a live-streamed transcript of the same turn looks
+ * like, with one caveat around client-tool typing (below):
+ * - One `ChatMessage` becomes one `UIMessage` (ids stringified), sorted
+ *   chronologically by id regardless of input order — the messages endpoint
+ *   pages newest-first by default, while `useChat` needs oldest-first. The
+ *   exception is `role: "tool"` messages: their `tool-result` parts are
+ *   folded into the originating assistant `dynamic-tool` part and the message
+ *   itself is dropped.
+ * - `text`/`reasoning` parts map to their UI counterparts with
+ *   `state: "done"` (history is complete, never streaming).
+ * - Every `tool-call` part becomes a `dynamic-tool` part, in state
+ *   `"output-available"` once a result exists (`"output-error"` when it is
+ *   marked `is_error`), or `"input-available"` while no result has been
+ *   persisted yet. For server-executed tools this matches the live stream
+ *   (they stream with `dynamic: true`); client (`ToolSet`) tools stream live
+ *   as statically-typed `tool-{name}` parts, but persisted history does not
+ *   record which names were client tools, so they rehydrate as `dynamic-tool`
+ *   too. Render tools by name — ai's `isToolOrDynamicToolUIPart` +
+ *   `getToolOrDynamicToolName` — rather than exact `part.type` matches and
+ *   both shapes look identical.
+ * - `source` parts become `source-url` parts; skipped when the wire part has
+ *   no `url`.
+ * - `file` parts become `file` UI parts only when a URL is available (see
+ *   {@link ChatMessagesToUIMessagesOptions.fileUrl}): persisted file parts
+ *   carry only a `file_id`, and `FileUIPart` requires a `url`. Parts without
+ *   one are skipped.
+ * - `file-reference` / `context-file` / `skill` / unknown part kinds have no
+ *   UI equivalent and are skipped silently (forward compatible).
+ */
+declare function chatMessagesToUIMessages(messages: ChatMessage[], opts?: ChatMessagesToUIMessagesOptions): UIMessage[];
+
 /** 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. */
@@ -783,4 +1016,4 @@ declare class CoderChatError extends CoderAgentError {
     constructor(payload: ChatErrorPayload);
 }
 
-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 };
+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 ChatMessagesToUIMessagesOptions, type ChatModelConfig, type ChatPlanMode, type ChatQueuedMessage, type ChatStatus, type ChatStreamActionRequired, type ChatStreamEvent, type ChatStreamEventType, type ChatStreamMessagePart, type ChatStreamRetry, type ChatStreamStatus, type ChatStreamToolCall, type ChatWatchEvent, type ChatWatchEventKind, 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 PreviewShareLevel, type ResolvedFile, type SharePreviewOptions, type SharedWorkspacePreview, type SubmitToolResultsRequest, TERMINAL_STATUSES, type ToolResult, type TurnAction, TurnTranslator, type UpdateChatRequest, type UploadChatFileResponse, type UploadedChatFile, type UserContent, type WatchChatEventsOptions, type WebSocketFactory, type WebSocketLike, type WorkspaceFileStore, type WorkspacePlacement, type WorkspacePreview, type WorkspacePreviewOptions, chatMessagesToUIMessages, classifyTurnAction, dataContentToFileContent, dynamicToolNames, extractSystemPrompt, resolveFileContent, streamChatEvents, toolsToDynamicTools, userContentToInputParts, watchChatEvents };