@coder/ai-sdk-agent 0.4.2 → 0.5.0

package/README.md

@@ -311,9 +311,27 @@ tools runs several segments, so it bounds each one, not the whole call. To cap t
 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.
+If the event stream drops mid‑turn, the agent redials it automatically with
+exponential backoff, replaying the turn's events from its starting cursor and
+deduplicating them on receipt — the server keeps generating during the gap, so
+a transient drop costs nothing and the run is **not** interrupted. Only when the stream cannot be re‑established (several
+consecutive failed attempts, ~15s) is the server run interrupted and the call
+rejected with a `CoderStreamError` — an AI SDK `APICallError`. When the failed
+turn had just created its chat AND had no external effects a replay would
+repeat — no `workspaceId`, no `mcpServerIds`, and no freshly uploaded inline
+attachments (pre‑uploaded `fileId` references are fine) — the dead session is
+discarded and the error is `isRetryable: true`, so `generate()` calls with
+`maxRetries` set retry the whole turn on a fresh chat automatically. Otherwise
+the error is `isRetryable: false` and retrying is the caller's deliberate
+decision: on a chat with prior state (resumed sessions, later turns,
+tool‑result segments) a re‑invocation would resubmit the same prompt as a new
+user turn, workspace/MCP tools may already have executed side effects, and
+inline attachments would upload again. (For `stream()`, a mid‑stream failure
+surfaces on the stream itself, outside the SDK's retry wrapper — handle it in
+your consumption loop.)
+A non‑transient 4xx upgrade rejection (bad/expired token,
+deleted chat) fails fast with a `CoderApiError` instead of retrying; 408/425/429
+consume the redial budget like any other transient failure.
 
 ## Cleanup
 
@@ -344,10 +362,20 @@ avoids accumulating live chats.
 
 ## Handling errors
 
-All errors extend `CoderAgentError`. Two carry structured detail you can branch on:
+All errors extend `CoderAgentError`, except `CoderStreamError` (below). 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`.
+- **`CoderStreamError`** — the event stream dropped and could not be re‑established
+  within its redial budget. Extends the AI SDK's `APICallError` (not
+  `CoderAgentError`), so `generate()`'s `maxRetries` machinery recognizes it.
+  `isRetryable` is `true` only when the failed turn created its chat (the dead
+  session is discarded, so a retry starts fresh) and had no external effects to
+  repeat (workspace/MCP tooling, fresh attachment uploads); otherwise it is
+  `false` — a retry would resubmit the prompt as a new user turn and could
+  duplicate those effects. A failure mid‑`stream()` surfaces on the stream,
+  outside the retry wrapper. The last transport failure is in `cause`.
 
 ```ts
 import { CoderApiError, CoderChatError } from "@coder/ai-sdk-agent";
@@ -613,7 +641,7 @@ what's available.
 ```
 CoderAgent  (implements ai.Agent)
   └─ ToolLoopAgent (ai)            ← inherits generate()/stream(), loop control
-       └─ CoderLanguageModel       ← implements @ai-sdk/provider LanguageModelV3
+       └─ CoderLanguageModel       ← implements @ai-sdk/provider LanguageModelV4
             └─ CoderChatClient      ← REST + WebSocket to /api/experimental/chats
                  └─ Coder Agents     ← runs the agent loop SERVER-side
 ```

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { FilePart, ToolSet, Agent, SystemModelMessage, ToolLoopAgentSettings, ToolChoice, StopCondition, ToolLoopAgent, UIMessage } from 'ai';
-import { SharedV4FileData, LanguageModelV4, LanguageModelV4CallOptions, LanguageModelV4StreamResult, LanguageModelV4GenerateResult, LanguageModelV4StreamPart, LanguageModelV4Message, LanguageModelV4Prompt } from '@ai-sdk/provider';
+import { SharedV4FileData, LanguageModelV4, LanguageModelV4CallOptions, LanguageModelV4StreamResult, LanguageModelV4GenerateResult, LanguageModelV4StreamPart, LanguageModelV4Message, LanguageModelV4Prompt, APICallError } from '@ai-sdk/provider';
 
 /**
  * Bytes to upload, in any convenient shape.
@@ -365,6 +365,29 @@ interface StreamChatEventsOptions {
  * The chat stream is a live subscription that stays open after a turn settles,
  * so callers should `break` out of the loop once they observe a terminal status
  * — that triggers generator cleanup, which closes the socket.
+ *
+ * Dropped connections are redialed with exponential backoff (like
+ * {@link watchChatEvents}), replaying from the turn's ORIGINAL `after_id`. The
+ * cursor is deliberately NOT advanced past messages already yielded: chatd's
+ * initial sync filters out ids at or below `after_id`, so an advanced cursor
+ * would silently lose same-id REVISION snapshots (updated content, tool
+ * results, usage) committed while the connection was down. Consumers must
+ * dedupe repeated `message` snapshots — the wire contract demands that anyway,
+ * since chatd re-sends full snapshots on revision bumps even without a
+ * reconnect (TurnTranslator does). On reconnect chatd also replays the
+ * in-progress generation attempt's `message_part` deltas from `seq` 1, so
+ * parts of an episode
+ * (`history_version`, `generation_attempt`) at or below the last yielded `seq`
+ * are suppressed here rather than double-yielded. The iteration ends in five
+ * ways: `signal` aborting (clean return), a non-transient 4xx upgrade
+ * rejection (terminal {@link CoderApiError} — bad/expired token or a deleted
+ * chat cannot succeed on retry, while 408/425/429 consume the redial budget),
+ * an unparseable frame (terminal {@link CoderAgentError} — a redial would
+ * replay the same frame forever), a drop while deltas WITHOUT episode
+ * coordinates are outstanding (older chatd; a {@link CoderStreamError},
+ * because a delta replay could not be deduped and would double-emit — a NEW
+ * committed `message` finalizes them into dedupable snapshots and re-enables
+ * redial), or the redial budget running out (also a {@link CoderStreamError}).
  */
 declare function streamChatEvents(options: StreamChatEventsOptions): AsyncGenerator<ChatStreamEvent, void, void>;
 interface WatchChatEventsOptions {
@@ -518,7 +541,9 @@ type PreviewShareLevel = Exclude<PortShareLevel, "owner">;
  * 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.
+ * (e.g. a `CoderWorkspaceSession` from `@coder/ai-sdk-sandbox`) supplies a
+ * few-line adapter. Note the session does not report the workspace UUID —
+ * retain it from `ensureCoderWorkspace(...).id` (same package).
  *
  * 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`/
@@ -526,8 +551,10 @@ type PreviewShareLevel = Exclude<PortShareLevel, "owner">;
  *
  * @example
  * ```ts
+ * // UUID via `ensureCoderWorkspace`; bytes over a `CoderWorkspaceSession`.
+ * const ws = await ensureCoderWorkspace({ workspace: "my-ws" });
  * const store: WorkspaceFileStore = {
- *   workspaceId: session.workspaceId,
+ *   workspaceId: ws.id!, // workspace UUID (reported by the CLI/native transports)
  *   write: async ({ content, path, signal }) => {
  *     await session.writeFile({ path, content: toStream(content), abortSignal: signal });
  *     return { path };
@@ -595,7 +622,7 @@ interface CoderAgentSettings<TOOLS extends ToolSet = {}> {
     /**
      * 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).
+     * connection (e.g. a `CoderWorkspaceSession` from `@coder/ai-sdk-sandbox`).
      */
     workspaceFiles?: WorkspaceFileStore;
     /** chatd-side MCP servers to enable for this chat. */
@@ -846,6 +873,15 @@ interface CoderLanguageModelConfig {
  *
  * NOTE: a single model instance is single-flight — do not run concurrent
  * generations against the same instance/session.
+ *
+ * The session retains ONE event stream per turn (issue #44): a segment that
+ * pauses for client tools leaves the WebSocket open, and the tool-result
+ * resume segment keeps reading it — no re-dial per tool round trip. The
+ * socket closes when its segment ends any other way (terminal settle, error,
+ * abort, timeout), when the next turn replaces it, or on session teardown
+ * (`resetSession()` / `[Symbol.asyncDispose]()`). A turn that pauses for
+ * client tools but never resumes leaves the socket open until teardown, so
+ * dispose or reset sessions you abandon mid-turn.
  */
 declare class CoderLanguageModel implements LanguageModelV4 {
     #private;
@@ -855,8 +891,32 @@ declare class CoderLanguageModel implements LanguageModelV4 {
     readonly supportedUrls: Record<string, RegExp[]>;
     constructor(config: CoderLanguageModelConfig);
     get chatId(): string | undefined;
-    /** Drops the current session so the next turn creates a fresh chat. */
+    /**
+     * Drops the current session so the next turn creates a fresh chat. Also
+     * closes the retained event stream, if any (fire-and-forget — a sync reset
+     * must not wait on socket teardown, and `close()` never rejects).
+     */
     resetSession(): void;
+    /**
+     * Closes the retained event stream, if any. The stream otherwise closes
+     * when its turn settles or fails, or when the next turn replaces it — but a
+     * turn that pauses for client tools and never resumes (e.g. the caller
+     * stopped the tool loop, or aborted between segments) leaves the socket
+     * open, so dispose (`await using`) or {@link resetSession} sessions you
+     * abandon mid-turn.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Closes a stream retained by a client-tool pause. Called on explicit
+     * interrupts ({@link CoderAgent.interrupt}): an interrupted pause is dead —
+     * its buffer would otherwise collect the interrupt's own settle events,
+     * which a later tool-result resume would consume as if they were the
+     * resumed generation's (truncating the turn), and if the tool loop never
+     * resumes the socket would outlive the explicit interrupt. A stream a
+     * segment is actively reading is left alone: that segment observes the
+     * settle the interrupt produces and closes the stream itself.
+     */
+    closePausedStream(): Promise<void>;
     doStream(options: LanguageModelV4CallOptions): Promise<LanguageModelV4StreamResult>;
     doGenerate(options: LanguageModelV4CallOptions): Promise<LanguageModelV4GenerateResult>;
 }
@@ -884,6 +944,15 @@ declare class TurnTranslator {
     constructor(opts: {
         dynamicToolNames: ReadonlySet<string>;
         turnCursor?: number;
+        /**
+         * Tool-call ids whose results the session already submitted. With the
+         * stream retained across segments (and redialed with the turn's original
+         * cursor), a reconnect can replay a previous segment's `action_required`
+         * snapshot; re-emitting an already-answered call would make the AI SDK
+         * execute the tool a second time. A live reference — the set grows as
+         * later segments submit results.
+         */
+        submittedToolCallIds?: ReadonlySet<string>;
     });
     get terminalStatus(): ChatStatus | undefined;
     /** Whether a client (custom) tool call has been emitted this turn. */
@@ -1015,6 +1084,29 @@ declare class CoderApiError extends CoderAgentError {
         detail?: string;
     });
 }
+/**
+ * The per-chat event stream dropped and could not be re-established within its
+ * redial budget (or could not be safely resumed — see `streamChatEvents` on
+ * servers without delta coordinates). Extends the AI SDK's {@link APICallError} with
+ * `isRetryable: true` because the `ai` package's retry machinery (`maxRetries`)
+ * only honors `APICallError`/`GatewayError`-branded errors — plain `Error`
+ * subclasses are never retried no matter what they claim. Note the retry
+ * wrapper only sees errors that reject the model call itself (`generate()`);
+ * a failure mid-`stream()` surfaces on the stream, past that wrapper. The last
+ * underlying transport failure is preserved as `cause`.
+ *
+ * NOTE: this is deliberately NOT a {@link CoderAgentError} (single
+ * inheritance); match it with `APICallError.isInstance(err)` or `err.name`.
+ */
+declare class CoderStreamError extends APICallError {
+    name: string;
+    constructor(args: {
+        message: string;
+        url: string;
+        cause?: unknown;
+        isRetryable?: boolean;
+    });
+}
 /** A chat generation ended in an error status. */
 declare class CoderChatError extends CoderAgentError {
     name: string;
@@ -1025,4 +1117,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 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 };
+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, CoderStreamError, 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 };