@coder/ai-sdk-agent 0.5.0 → 0.6.0

package/dist/index.js

@@ -163,6 +163,20 @@ var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
 
 // src/coder/ws.ts
 import NodeWebSocket from "ws";
+
+// src/transport-events.ts
+function safeTransportEmitter(handler) {
+  if (!handler) return void 0;
+  return (event) => {
+    try {
+      void Promise.resolve(handler(event)).catch(() => {
+      });
+    } catch {
+    }
+  };
+}
+
+// src/coder/ws.ts
 var defaultFactory = (url, { headers }) => {
   return new NodeWebSocket(url, { headers });
 };
@@ -228,6 +242,8 @@ function streamChatEvents(options) {
 async function* streamChatEventsLoop(options) {
   const { baseUrl, token, chatId, signal } = options;
   const factory = options.webSocketFactory ?? defaultFactory;
+  const emit = safeTransportEmitter(options.onTransportEvent);
+  let attempt = 0;
   const wsBase = httpToWs(baseUrl);
   const path = `/api/experimental/chats/${chatId}/stream`;
   const query = options.afterId !== void 0 ? `?after_id=${options.afterId}` : "";
@@ -246,11 +262,24 @@ async function* streamChatEventsLoop(options) {
     let finished = false;
     let failure;
     let parseFailure = false;
+    let closeEmitted = false;
     const wake = () => {
       resolveNext?.();
       resolveNext = void 0;
     };
-    const ws = factory(url, { headers: { "Coder-Session-Token": token } });
+    attempt += 1;
+    emit?.({ type: "ws:dial", chatId, attempt, url, timestamp: Date.now() });
+    let ws;
+    try {
+      ws = factory(url, { headers: { "Coder-Session-Token": token } });
+    } catch (err) {
+      if (emit) {
+        const message = err instanceof Error ? err.message : String(err);
+        emit({ type: "ws:error", chatId, attempt, message, timestamp: Date.now() });
+        emit({ type: "ws:close", chatId, attempt, timestamp: Date.now() });
+      }
+      throw err;
+    }
     const onAbort = () => {
       finished = true;
       try {
@@ -274,6 +303,13 @@ async function* streamChatEventsLoop(options) {
         const data = typeof ev.data === "string" ? ev.data : String(ev.data);
         batch = JSON.parse(data);
       } catch (err) {
+        emit?.({
+          type: "ws:error",
+          chatId,
+          attempt,
+          message: "failed to parse chat stream frame",
+          timestamp: Date.now()
+        });
         failure = new CoderAgentError("failed to parse chat stream frame", { cause: err });
         parseFailure = true;
         finished = true;
@@ -281,24 +317,55 @@ async function* streamChatEventsLoop(options) {
         return;
       }
       if (Array.isArray(batch)) {
-        for (const e of batch) queue.push(e);
+        for (const e of batch) {
+          queue.push(e);
+          emit?.({
+            type: "ws:event",
+            chatId,
+            attempt,
+            event: e,
+            timestamp: Date.now()
+          });
+        }
       } else if (batch && typeof batch === "object") {
         queue.push(batch);
+        emit?.({
+          type: "ws:event",
+          chatId,
+          attempt,
+          event: batch,
+          timestamp: Date.now()
+        });
       }
       wake();
     };
     const onError = (ev) => {
       if (finished) return;
       const message = ev && typeof ev === "object" && "message" in ev ? String(ev.message) : "chat stream socket error";
+      emit?.({ type: "ws:error", chatId, attempt, message, timestamp: Date.now() });
       const status = upgradeStatus(message);
       failure = status !== void 0 && status >= 400 && status < 500 && !TRANSIENT_UPGRADE_STATUSES.has(status) ? new CoderApiError({ status, method: "GET", path, message }) : new CoderAgentError(message);
       finished = true;
       wake();
     };
-    const onClose = () => {
+    const onClose = (ev) => {
+      if (emit && !closeEmitted) {
+        closeEmitted = true;
+        const closeEvent = {
+          type: "ws:close",
+          chatId,
+          attempt,
+          timestamp: Date.now()
+        };
+        if (ev?.code !== void 0) closeEvent.code = ev.code;
+        if (ev?.reason !== void 0 && ev.reason !== "") closeEvent.reason = ev.reason;
+        emit(closeEvent);
+      }
       finished = true;
       wake();
     };
+    const onOpen = emit ? () => emit({ type: "ws:open", chatId, attempt, timestamp: Date.now() }) : void 0;
+    if (onOpen) ws.addEventListener("open", onOpen);
     ws.addEventListener("message", onMessage);
     ws.addEventListener("error", onError);
     ws.addEventListener("close", onClose);
@@ -344,6 +411,7 @@ async function* streamChatEventsLoop(options) {
     } finally {
       finished = true;
       if (signal && abortListenerAdded) signal.removeEventListener("abort", onAbort);
+      if (onOpen) ws.removeEventListener("open", onOpen);
       ws.removeEventListener("message", onMessage);
       ws.removeEventListener("error", onError);
       ws.removeEventListener("close", onClose);
@@ -351,6 +419,10 @@ async function* streamChatEventsLoop(options) {
         ws.close(1e3);
       } catch {
       }
+      if (emit && !closeEmitted) {
+        closeEmitted = true;
+        emit({ type: "ws:close", chatId, attempt, timestamp: Date.now() });
+      }
     }
     if (signal?.aborted) return;
     if (failure instanceof CoderApiError) throw failure;
@@ -371,6 +443,15 @@ async function* streamChatEventsLoop(options) {
         cause: lastFailure
       });
     }
+    emit?.({
+      type: "ws:redial",
+      chatId,
+      attempt,
+      consecutiveFailures: failures,
+      maxConsecutiveFailures: STREAM_MAX_CONSECUTIVE_FAILURES,
+      backoffMs,
+      timestamp: Date.now()
+    });
     await sleep(backoffMs, signal);
     if (signal?.aborted) return;
     backoffMs = Math.min(backoffMs * 2, STREAM_BACKOFF_CAP_MS);
@@ -554,11 +635,18 @@ var CoderChatClient = class {
   #token;
   #fetch;
   #webSocketFactory;
+  /** The raw subscriber, forwarded to stream readers (which wrap it themselves). */
+  #onTransportEvent;
+  /** Exception-isolated emitter for this client's own HTTP events. */
+  #emitTransportEvent;
+  #httpSeq = 0;
   constructor(options) {
     this.baseUrl = options.baseUrl.replace(/\/$/, "");
     this.#token = options.token;
     this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
     this.#webSocketFactory = options.webSocketFactory;
+    this.#onTransportEvent = options.onTransportEvent;
+    this.#emitTransportEvent = safeTransportEmitter(options.onTransportEvent);
   }
   /**
    * Issue a request and return the raw `Response` on success (body unread). On a
@@ -574,7 +662,39 @@ var CoderChatClient = class {
     if (typeof ReadableStream !== "undefined" && opts?.body instanceof ReadableStream) {
       init.duplex = "half";
     }
-    const res = await this.#fetch(`${this.baseUrl}${path}`, init);
+    const emit = this.#emitTransportEvent;
+    let requestId = 0;
+    let startedAt = 0;
+    if (emit) {
+      requestId = ++this.#httpSeq;
+      startedAt = performance.now();
+      emit({ type: "http:request", id: requestId, method, path, timestamp: Date.now() });
+    }
+    let res;
+    try {
+      res = await this.#fetch(`${this.baseUrl}${path}`, init);
+    } catch (err) {
+      emit?.({
+        type: "http:error",
+        id: requestId,
+        method,
+        path,
+        message: err instanceof Error ? err.message : String(err),
+        durationMs: performance.now() - startedAt,
+        timestamp: Date.now()
+      });
+      throw err;
+    }
+    emit?.({
+      type: "http:response",
+      id: requestId,
+      method,
+      path,
+      status: res.status,
+      ok: res.ok,
+      durationMs: performance.now() - startedAt,
+      timestamp: Date.now()
+    });
     if (!res.ok) {
       const errObj = await this.#json(res) ?? {};
       throw new CoderApiError({
@@ -742,7 +862,8 @@ var CoderChatClient = class {
       chatId,
       afterId: opts?.afterId,
       signal: opts?.signal,
-      webSocketFactory: this.#webSocketFactory
+      webSocketFactory: this.#webSocketFactory,
+      onTransportEvent: this.#onTransportEvent
     });
   }
   /**
@@ -1543,11 +1664,15 @@ var CoderLanguageModel = class {
   #inFlight = false;
   /** The turn-lifetime event stream, retained across client-tool pauses. */
   #retainedStream;
+  /** Exception-isolated observability emitter for `segment:*` events. */
+  #emitTransportEvent;
+  #segmentSeq = 0;
   constructor(config) {
     assertSupportedAiVersion();
     this.#config = config;
     this.modelId = config.model ?? "chatd";
     this.#chatId = config.chatId;
+    this.#emitTransportEvent = safeTransportEmitter(config.onTransportEvent);
   }
   get chatId() {
     return this.#chatId;
@@ -1707,7 +1832,93 @@ var CoderLanguageModel = class {
     });
     return events;
   }
-  async *#runTurn(options) {
+  /**
+   * Wraps {@link #runTurnInner} with `segment:start`/`segment:settle`
+   * observability events. A pure pass-through without a subscriber — no
+   * counters, clocks, or event objects on the unobserved path. The settle
+   * event is emitted in a `finally`, so every started segment settles exactly
+   * once: cleanly (with the terminal status carried by the `finish` part that
+   * streamed through), with an `error` summary, or — when the consumer tears
+   * the stream down mid-segment — with neither. Consumer teardown has two
+   * shapes: a plain generator return (no catch runs), and a
+   * `ReadableStream.cancel()` that {@link doStream} routes through an abort to
+   * unblock a pending socket read — the latter surfaces here as an abort
+   * throw, so `isConsumerCancel` (supplied by `doStream`) reclassifies it as
+   * teardown rather than a failed segment.
+   *
+   * Two more classification wrinkles (review findings):
+   * - a streamed server `error` part is captured BEFORE being yielded —
+   *   `doGenerate()` throws on receiving it and closes this generator without
+   *   another pull, so the catch below never sees that failure;
+   * - the segment's chat id is tracked in `segmentChat` (written by
+   *   {@link #runTurnInner} once known) — a retry-safe stream failure on a
+   *   freshly created chat discards the session (clearing `this.#chatId`)
+   *   before the finally runs, and the settle must still name the chat that
+   *   the preceding `ws:*`/`http:*` events identified.
+   */
+  async *#runTurn(options, isConsumerCancel) {
+    const emit = this.#emitTransportEvent;
+    if (!emit) {
+      yield* this.#runTurnInner(options);
+      return;
+    }
+    const segment = ++this.#segmentSeq;
+    const startedAt = performance.now();
+    const startEvent = {
+      type: "segment:start",
+      segment,
+      timestamp: Date.now()
+    };
+    if (this.#chatId !== void 0) startEvent.chatId = this.#chatId;
+    emit(startEvent);
+    const segmentChat = {};
+    let finishReason;
+    let failure;
+    let failed = false;
+    try {
+      for await (const part of this.#runTurnInner(options, segmentChat)) {
+        if (part.type === "finish") finishReason = part.finishReason;
+        else if (part.type === "error" && !failed) {
+          failure = part.error;
+          failed = true;
+        }
+        yield part;
+      }
+    } catch (err) {
+      if (!isConsumerCancel?.()) {
+        failure = err;
+        failed = true;
+      }
+      throw err;
+    } finally {
+      const settleEvent = {
+        type: "segment:settle",
+        segment,
+        durationMs: performance.now() - startedAt,
+        timestamp: Date.now()
+      };
+      const chatId = segmentChat.chatId ?? this.#chatId;
+      if (chatId !== void 0) settleEvent.chatId = chatId;
+      if (!failed && finishReason === void 0 && options.abortSignal?.aborted) {
+        if (!isConsumerCancel?.()) {
+          failure = options.abortSignal.reason;
+          failed = true;
+        }
+      }
+      if (failed) {
+        settleEvent.error = {
+          name: failure instanceof Error ? failure.name : "Error",
+          message: failure instanceof Error ? failure.message : String(failure)
+        };
+      }
+      if (finishReason !== void 0) {
+        if (finishReason.raw !== void 0) settleEvent.status = finishReason.raw;
+        if (!failed) settleEvent.finishReason = finishReason.unified;
+      }
+      emit(settleEvent);
+    }
+  }
+  async *#runTurnInner(options, segmentChat) {
     if (this.#inFlight) {
       throw new CoderAgentError(
         "A generation is already in flight on this CoderAgent (single-flight). Use a separate CoderAgent instance for concurrent sessions."
@@ -1826,6 +2037,7 @@ var CoderLanguageModel = class {
       }
       const chatId = this.#chatId;
       turnChatId = chatId;
+      if (segmentChat) segmentChat.chatId = chatId;
       const dynamicNames = dynamicToolNames(options.tools);
       translator = new TurnTranslator({
         dynamicToolNames: dynamicNames,
@@ -1968,7 +2180,8 @@ var CoderLanguageModel = class {
   async doStream(options) {
     const cancelController = new AbortController();
     const abortSignal = options.abortSignal ? AbortSignal.any([options.abortSignal, cancelController.signal]) : cancelController.signal;
-    const gen = this.#runTurn({ ...options, abortSignal });
+    let consumerCancelled = false;
+    const gen = this.#runTurn({ ...options, abortSignal }, () => consumerCancelled);
     const stream = new ReadableStream({
       async pull(controller) {
         try {
@@ -1981,6 +2194,7 @@ var CoderLanguageModel = class {
         }
       },
       async cancel() {
+        consumerCancelled = !options.abortSignal?.aborted;
         cancelController.abort();
         await gen.return().catch(() => {
         });
@@ -2131,7 +2345,8 @@ var CoderAgent = class {
         baseUrl: settings.baseUrl,
         token: settings.token,
         fetch: settings.fetch,
-        webSocketFactory: settings.webSocketFactory
+        webSocketFactory: settings.webSocketFactory,
+        onTransportEvent: settings.onTransportEvent
       });
     } else {
       throw new CoderAgentError(
@@ -2157,7 +2372,8 @@ var CoderAgent = class {
       mcpServerIds: settings.mcpServerIds,
       planMode: settings.planMode,
       chatId: settings.chatId,
-      requestTimeoutMs: settings.requestTimeoutMs
+      requestTimeoutMs: settings.requestTimeoutMs,
+      onTransportEvent: settings.onTransportEvent
     });
     this.#inner = new ToolLoopAgent({
       model: this.#model,