@coder/ai-sdk-agent 0.5.0 → 0.6.0

package/README.md

@@ -286,6 +286,79 @@ with a 4xx — bad/expired token, or an older Coder server without the endpoint
 `watchChatEvents({ baseUrl, token, signal, webSocketFactory })` export provides
 the same stream without a `CoderChatClient`.
 
+## Observability
+
+`onTransportEvent` receives typed transport events — HTTP exchanges, the
+per‑chat stream's WebSocket lifecycle, and turn‑segment boundaries — so timing
+and tracing need no `fetch`/`webSocketFactory` wrapping and no re‑parsing of
+stream frames. Pass it on `CoderAgentSettings` (it reaches both the client and
+the model), on `CoderChatClientOptions`, or on `CoderLanguageModelConfig`:
+
+```ts
+import { CoderAgent, type CoderTransportEvent } from "@coder/ai-sdk-agent";
+
+const events: CoderTransportEvent[] = [];
+const agent = new CoderAgent({
+  baseUrl,
+  token,
+  organizationId,
+  onTransportEvent: (ev) => events.push(ev),
+});
+
+await agent.generate({ prompt: "…" });
+
+// e.g. attribute where the turn spent its time:
+for (const ev of events) {
+  if (ev.type === "http:response")
+    console.log(`${ev.method} ${ev.path} → ${ev.status} in ${ev.durationMs.toFixed(0)}ms`);
+  if (ev.type === "ws:event" && ev.event.type === "action_required")
+    console.log(`tool calls arrived at +${ev.timestamp - events[0]!.timestamp}ms`);
+  if (ev.type === "segment:settle")
+    console.log(`segment ${ev.segment}: ${ev.status} in ${ev.durationMs.toFixed(0)}ms`);
+}
+```
+
+`CoderTransportEvent` is a discriminated union on `type`. Every event carries
+`timestamp` (`Date.now()` at observation — comparable to server‑side timestamps
+such as a message's `created_at`, for delivery‑lag measurements):
+
+| event            | when                                                | payload (besides `timestamp`)                                                                                                                                                           |
+| ---------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `http:request`   | a REST request is sent                              | `id` (correlates the pair), `method`, `path`                                                                                                                                            |
+| `http:response`  | response headers arrive (incl. non‑2xx, `ok:false`) | `id`, `method`, `path`, `status`, `ok`, `durationMs`                                                                                                                                    |
+| `http:error`     | the fetch itself rejects (network failure, abort)   | `id`, `method`, `path`, `message`, `durationMs`                                                                                                                                         |
+| `ws:dial`        | a stream connection attempt starts                  | `chatId`, `attempt` (1‑based, increments per redial), `url`                                                                                                                             |
+| `ws:open`        | the WebSocket handshake completes                   | `chatId`, `attempt`                                                                                                                                                                     |
+| `ws:event`       | a decoded stream event arrives                      | `chatId`, `attempt`, `event` (the decoded `ChatStreamEvent`, by reference — don't mutate)                                                                                               |
+| `ws:close`       | the connection ends (exactly one per dial)          | `chatId`, `attempt`, `code`/`reason` when the server/network closed it; absent when the reader closed it (settle, teardown, redial)                                                     |
+| `ws:error`       | a socket error or unparseable frame                 | `chatId`, `attempt`, `message`                                                                                                                                                          |
+| `ws:redial`      | a dropped connection is about to be redialed        | `chatId`, `attempt` (the ended connection), `consecutiveFailures`, `maxConsecutiveFailures`, `backoffMs`                                                                                |
+| `segment:start`  | a turn segment (one model round‑trip) starts        | `segment` (1‑based per model instance), `chatId` (absent before the first turn creates the chat)                                                                                        |
+| `segment:settle` | the segment ends (exactly one per start)            | `segment`, `chatId`, and: `status` + `finishReason` on a clean settle, `error` (`{name, message}`, plus `status` if the run still settled terminally) on failure, neither on a teardown |
+
+Semantics worth knowing:
+
+- **Isolation** — exceptions thrown by the handler are swallowed; they can never
+  alter transport behavior or a turn's outcome.
+- **Zero overhead** — without a handler, no event objects are allocated and no
+  extra socket listeners are registered.
+- **No secrets** — events carry no headers and no tokens (auth travels in the
+  `Coder-Session-Token` header, which is deliberately excluded); `path`/`url`
+  never contain credentials.
+- `ws:event` fires at arrival, **before** replay dedup: after a redial, chatd's
+  replay of the in‑progress episode is visible here (correlate with `attempt`)
+  even though the reader suppresses the duplicates it forwards to the turn.
+- A multi‑step turn that drives client tools emits one `segment:start`/
+  `segment:settle` pair per round‑trip, all riding **one** `ws:dial`ed
+  connection — the stream is retained across `requires_action` pauses. A pause
+  settles with `status: "requires_action"`, `finishReason: "tool-calls"`; the
+  final settle carries the terminal status (`waiting`/`completed`/`error`).
+- `ws:*` events cover the per‑chat `/stream` reader (turn transport). The
+  `watchChats` subscription is not instrumented.
+- With a pre‑built `client` in `CoderAgentSettings`, HTTP/WS events come from
+  the hook given to **that client's** options; the agent‑level hook then only
+  receives `segment:*` events.
+
 ## Timeouts & cancellation
 
 Pass an `abortSignal` to `generate()`/`stream()` to cancel a turn. Aborting
@@ -624,6 +697,7 @@ running many agents at once:
 | `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 |
+| `onTransportEvent`                | observability hook for typed transport events (see [Observability](#observability))              |
 | `settleDeadlineMs`                | overall deadline for bounded cleanup (`archive()` 409 retries, disposal); default 15 000         |
 | `settleRetryDelayMs`              | pause between `archive()` retries while the chat settles; default 1000                           |
 | `chatId`                          | resume an existing chat                                                                          |

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, APICallError } from '@ai-sdk/provider';
+import { SharedV4FileData, LanguageModelV4FinishReason, LanguageModelV4, LanguageModelV4CallOptions, LanguageModelV4StreamResult, LanguageModelV4GenerateResult, LanguageModelV4StreamPart, LanguageModelV4Message, LanguageModelV4Prompt, APICallError } from '@ai-sdk/provider';
 
 /**
  * Bytes to upload, in any convenient shape.
@@ -317,6 +317,174 @@ interface ChatWatchEvent {
     tool_calls?: ChatStreamToolCall[];
 }
 
+/**
+ * Typed transport observability events (issue #45).
+ *
+ * A single optional `onTransportEvent` hook — on {@link CoderChatClientOptions},
+ * {@link CoderLanguageModelConfig}, and {@link CoderAgentSettings} — receives
+ * these events so consumers can build traces and timings from a stable event
+ * vocabulary instead of wrapping `fetch`/`webSocketFactory` and re-parsing
+ * every stream frame.
+ *
+ * Contract:
+ * - **Isolation** — exceptions thrown by a subscriber are swallowed; they can
+ *   never alter transport behavior or a turn's outcome.
+ * - **Zero overhead** — without a subscriber, no event objects are allocated
+ *   and no extra listeners are registered.
+ * - **No secrets** — events carry no headers and no tokens. Authentication
+ *   travels exclusively in the `Coder-Session-Token` request header, which is
+ *   deliberately excluded; the `path`/`url` fields never contain credentials.
+ * - **Observation, not interception** — events are emitted synchronously at
+ *   observation time (`timestamp` is `Date.now()`, comparable to server-side
+ *   timestamps such as a message's `created_at`); handlers cannot modify what
+ *   the transport does. Payloads referenced by an event (`ws:event`'s decoded
+ *   stream event) are shared with the pipeline — treat them as read-only.
+ */
+interface TransportEventBase {
+    /** Wall-clock observation time in ms since epoch (`Date.now()`). */
+    timestamp: number;
+}
+interface HttpTransportEventBase extends TransportEventBase {
+    /**
+     * Correlates a request with its response/error. Monotonically increasing
+     * per client instance.
+     */
+    id: number;
+    /** HTTP method, e.g. `POST`. */
+    method: string;
+    /**
+     * Path + query relative to the client's `baseUrl`, e.g.
+     * `/api/experimental/chats/{id}/tool-results`. Never carries credentials.
+     */
+    path: string;
+}
+/** A request is about to be sent. */
+interface HttpRequestTransportEvent extends HttpTransportEventBase {
+    type: "http:request";
+}
+/**
+ * Response headers arrived (before the body is read). Emitted for every
+ * completed exchange, including non-2xx responses (`ok: false`) that the
+ * client subsequently surfaces as a `CoderApiError`.
+ */
+interface HttpResponseTransportEvent extends HttpTransportEventBase {
+    type: "http:response";
+    status: number;
+    ok: boolean;
+    /** Time from request start to response headers, in milliseconds. */
+    durationMs: number;
+}
+/** The fetch itself rejected (network failure, abort) — no response arrived. */
+interface HttpErrorTransportEvent extends HttpTransportEventBase {
+    type: "http:error";
+    message: string;
+    durationMs: number;
+}
+interface StreamTransportEventBase extends TransportEventBase {
+    chatId: string;
+    /**
+     * 1-based connection attempt within one reader (`streamChatEvents` call —
+     * with stream retention (#44), one per turn). Increments on every redial.
+     */
+    attempt: number;
+}
+/** A connection attempt is starting (socket constructed). */
+interface StreamDialTransportEvent extends StreamTransportEventBase {
+    type: "ws:dial";
+    /** The `wss://…/stream[?after_id=N]` URL. Never carries credentials. */
+    url: string;
+}
+/** The WebSocket handshake completed. */
+interface StreamOpenTransportEvent extends StreamTransportEventBase {
+    type: "ws:open";
+}
+/**
+ * A decoded stream event arrived on the wire. Emitted at arrival time for
+ * every event in a frame batch, BEFORE replay dedup — after a redial, chatd's
+ * replay of the in-progress episode is visible here even though the reader
+ * suppresses the duplicates it forwards. `event` is the decoded object by
+ * reference (no copy): do not mutate it.
+ */
+interface StreamEventTransportEvent extends StreamTransportEventBase {
+    type: "ws:event";
+    event: ChatStreamEvent;
+}
+/**
+ * The connection ended. Exactly one per dial: carries `code`/`reason` when
+ * the server or network closed the socket; both are absent when the reader
+ * tore the connection down itself (turn settled, redial teardown, abort).
+ */
+interface StreamCloseTransportEvent extends StreamTransportEventBase {
+    type: "ws:close";
+    code?: number;
+    reason?: string;
+}
+/**
+ * An error was observed on the connection: a socket `error` event (including
+ * rejected upgrades) or an unparseable frame. The reader's own terminal
+ * classification still surfaces through the turn (see `segment:settle`).
+ */
+interface StreamErrorTransportEvent extends StreamTransportEventBase {
+    type: "ws:error";
+    message: string;
+}
+/**
+ * A dropped connection is about to be redialed after `backoffMs`. Carries the
+ * redial budget state: the reader gives up (failing the turn) when
+ * `consecutiveFailures` — connection endings without forward progress —
+ * reaches `maxConsecutiveFailures`; any forward progress resets the count.
+ * `attempt` is the connection that just ended; the next dial is `attempt + 1`.
+ */
+interface StreamRedialTransportEvent extends StreamTransportEventBase {
+    type: "ws:redial";
+    consecutiveFailures: number;
+    maxConsecutiveFailures: number;
+    backoffMs: number;
+}
+interface SegmentTransportEventBase extends TransportEventBase {
+    /** 1-based segment counter per model instance. */
+    segment: number;
+    /** Undefined on a first turn's start until the chat is created. */
+    chatId?: string;
+}
+/**
+ * A segment (one model round-trip: submission plus the server run until it
+ * settles or pauses for a client tool) started. A turn that drives client
+ * tools spans several segments.
+ */
+interface SegmentStartTransportEvent extends SegmentTransportEventBase {
+    type: "segment:start";
+}
+/**
+ * The segment ended. Exactly one per start:
+ * - settled cleanly → `status` is the turn's terminal chat status and
+ *   `finishReason` the unified AI SDK finish reason (`tool-calls` marks a
+ *   client-tool pause; the turn continues with a resume segment);
+ * - failed (abort, timeout, transport failure, server error) → `error`,
+ *   plus `status` when the server run itself still settled terminally
+ *   (e.g. `status: "error"` streamed alongside the error);
+ * - torn down before settling (consumer canceled the stream) → neither.
+ */
+interface SegmentSettleTransportEvent extends SegmentTransportEventBase {
+    type: "segment:settle";
+    status?: ChatStatus;
+    finishReason?: LanguageModelV4FinishReason["unified"];
+    error?: {
+        name: string;
+        message: string;
+    };
+    durationMs: number;
+}
+/** Every transport observability event, discriminated on `type`. */
+type CoderTransportEvent = HttpRequestTransportEvent | HttpResponseTransportEvent | HttpErrorTransportEvent | StreamDialTransportEvent | StreamOpenTransportEvent | StreamEventTransportEvent | StreamCloseTransportEvent | StreamErrorTransportEvent | StreamRedialTransportEvent | SegmentStartTransportEvent | SegmentSettleTransportEvent;
+/**
+ * Subscriber for {@link CoderTransportEvent}s. Exceptions are swallowed —
+ * including an `async` handler's rejection (a function returning a promise is
+ * assignable to this void-returning signature, and its rejection must not
+ * become an unhandled rejection either).
+ */
+type TransportEventHandler = (event: CoderTransportEvent) => void;
+
 /**
  * A minimal WebSocket factory abstraction so the stream reader can run on
  * Node (via the `ws` package, with header auth) or in environments that
@@ -356,6 +524,13 @@ interface StreamChatEventsOptions {
     afterId?: number;
     signal?: AbortSignal;
     webSocketFactory?: WebSocketFactory;
+    /**
+     * Observability hook: receives the reader's `ws:*` transport events (dial,
+     * open, decoded events, close, error, redial). Exceptions it throws are
+     * swallowed; without it, no event objects are allocated and no extra socket
+     * listeners are registered. See {@link CoderTransportEvent}.
+     */
+    onTransportEvent?: TransportEventHandler;
 }
 /**
  * Opens the chatd `/stream` WebSocket and yields decoded {@link ChatStreamEvent}s
@@ -439,6 +614,13 @@ interface CoderChatClientOptions {
     fetch?: typeof globalThis.fetch;
     /** Custom WebSocket factory (defaults to the `ws` package on Node). */
     webSocketFactory?: WebSocketFactory;
+    /**
+     * Observability hook: receives typed transport events (HTTP request/response
+     * timings, per-chat stream WebSocket lifecycle). Exceptions it throws are
+     * swallowed; without it, no event objects are allocated. See
+     * {@link CoderTransportEvent}.
+     */
+    onTransportEvent?: TransportEventHandler;
 }
 /**
  * A thin, typed client for Coder's experimental `chatd` API. This is a
@@ -613,6 +795,17 @@ interface CoderAgentSettings<TOOLS extends ToolSet = {}> {
     token?: string;
     fetch?: CoderChatClientOptions["fetch"];
     webSocketFactory?: CoderChatClientOptions["webSocketFactory"];
+    /**
+     * Observability hook: receives typed transport events — HTTP request/
+     * response timings, the per-chat stream's WebSocket lifecycle (dial/open/
+     * events/close/redial), and turn-segment start/settle — so timing and
+     * tracing need no `fetch`/`webSocketFactory` wrapping. Exceptions it throws
+     * are swallowed; without it, no event objects are allocated. NOTE: when a
+     * pre-built `client` is supplied, its own `onTransportEvent` (set at client
+     * construction) emits the HTTP/WebSocket events — this setting then only
+     * receives the `segment:*` events. See {@link CoderTransportEvent}.
+     */
+    onTransportEvent?: TransportEventHandler;
     /** Organization UUID that owns the chat (required). */
     organizationId: string;
     /** Model hint: UUID, `provider:model`, model id, or display-name substring. */
@@ -857,6 +1050,15 @@ interface CoderLanguageModelConfig {
      * `abortSignal: AbortSignal.timeout(ms)`. Unset or non-positive means no limit.
      */
     requestTimeoutMs?: number;
+    /**
+     * Observability hook: receives this model's `segment:*` transport events
+     * (turn-segment start/settle with terminal status and timing). HTTP and
+     * WebSocket events are emitted by the {@link CoderChatClient} — pass the
+     * hook to its options too (CoderAgent wires both from one setting).
+     * Exceptions it throws are swallowed; without it, no event objects are
+     * allocated. See {@link CoderTransportEvent}.
+     */
+    onTransportEvent?: TransportEventHandler;
 }
 /**
  * A {@link LanguageModelV4} that is backed by a remote Coder `chatd` agent
@@ -1117,4 +1319,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, 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 };
+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 CoderTransportEvent, type CreateChatMessageRequest, type CreateChatMessageResponse, type CreateChatRequest, type DynamicTool, type FileContent, type FilePartUploader, type HttpErrorTransportEvent, type HttpRequestTransportEvent, type HttpResponseTransportEvent, MAX_CHAT_FILE_SIZE_BYTES, type PreviewShareLevel, type ResolvedFile, type SegmentSettleTransportEvent, type SegmentStartTransportEvent, type SharePreviewOptions, type SharedWorkspacePreview, type StreamCloseTransportEvent, type StreamDialTransportEvent, type StreamErrorTransportEvent, type StreamEventTransportEvent, type StreamOpenTransportEvent, type StreamRedialTransportEvent, type SubmitToolResultsRequest, TERMINAL_STATUSES, type ToolResult, type TransportEventHandler, 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 };