@coder/ai-sdk-agent 0.4.1 → 0.4.3

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";
@@ -371,14 +399,31 @@ retrying the whole step deliberately.
 
 ## Usage & cost
 
-Results carry normalized token usage in `usage`, plus the verbatim snake_case
-wire usage in `usage.raw` for fields the normalized shape has no slot for
-(`context_limit`, cost, runtime, …). When the server reports them,
-`total_cost_micros` (micro‑USD) and `total_runtime_ms` are also mirrored under
-`providerMetadata.coder` on finish. Both are **absence‑tolerant mirrors**:
-today's Coder servers only expose cost on the aggregate cost endpoints
-(`/api/experimental/chats/cost/*`), so expect these fields to be absent —
-nothing is emitted when the server sends neither.
+Results carry normalized token usage in `usage`. A chatd turn runs several
+model steps server‑side (one per server tool round), each reporting its own
+usage — the SDK **sums every step**, and the AI SDK adds up the steps of a
+turn that paused for client tools, so `result.usage` reflects what the whole
+turn actually consumed. `inputTokens` is the full prompt size: Coder
+normalizes the wire `input_tokens` to the _uncached_ count (cache reads/writes
+are separate fields), so the SDK adds them back into the total and exposes the
+split via `inputTokenDetails` (`noCacheTokens`, `cacheReadTokens`,
+`cacheWriteTokens`).
+
+The snake_case wire usage lives **per step** at `result.steps[i].usage.raw`
+(the AI SDK does not carry `raw` onto the summed `result.usage`) for fields
+the normalized shape has no slot for (`context_limit`, cost, runtime, and any
+newer wire fields, which pass through newest‑value‑wins). `raw` keeps the wire
+convention (`input_tokens` = uncached only) with counters summed over that
+step's server‑side model steps and `context_limit` from the newest one — so
+don't divide `raw`'s summed counters by `context_limit` to estimate context
+fullness; they are turn consumption, not a prompt‑size snapshot. When the
+server reports them, `total_cost_micros` (micro‑USD) and `total_runtime_ms`
+are mirrored the same way under each step's `providerMetadata.coder`
+(`result.providerMetadata` reflects only the final step — sum
+`result.steps[*].providerMetadata.coder` for whole‑turn cost when client tools
+ran). Both are **absence‑tolerant mirrors**: on servers that don't send them
+(cost is otherwise only on the aggregate cost endpoints,
+`/api/experimental/chats/cost/*`), nothing is emitted.
 
 Forward usage to a UI via message metadata:
 
@@ -596,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. */
@@ -883,6 +910,7 @@ declare class TurnTranslator {
     #private;
     constructor(opts: {
         dynamicToolNames: ReadonlySet<string>;
+        turnCursor?: number;
     });
     get terminalStatus(): ChatStatus | undefined;
     /** Whether a client (custom) tool call has been emitted this turn. */
@@ -1014,6 +1042,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;
@@ -1024,4 +1075,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 };