@coder/ai-sdk-agent 0.6.3 → 0.7.0

package/README.md

@@ -324,19 +324,19 @@ for (const ev of events) {
 `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`, `durationMs`, and: `status` + `finishReason` on a clean settle, `error` (`{name, message}`, plus `status` if the run still settled terminally) on failure, neither on a teardown |
+| 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`, `reader` (identifies the `streamChatEvents` call), `attempt` (1‑based per reader, increments per redial), `url`                                                                                                                                                         |
+| `ws:open`        | the WebSocket handshake completes                   | `chatId`, `reader`, `attempt`                                                                                                                                                                                                                                                     |
+| `ws:event`       | a decoded stream event arrives                      | `chatId`, `reader`, `attempt`, `event` (the decoded `ChatStreamEvent`, by reference — don't mutate)                                                                                                                                                                               |
+| `ws:close`       | the connection ends (exactly one per dial)          | `chatId`, `reader`, `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`, `reader`, `attempt`, `message`                                                                                                                                                                                                                                          |
+| `ws:redial`      | a dropped connection is about to be redialed        | `chatId`, `reader`, `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`, `reader` (the reader that served the segment; absent if none was acquired), `durationMs`, 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:
 
@@ -348,8 +348,18 @@ Semantics worth knowing:
   `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`)
+  replay of the in‑progress episode is visible here (correlate with `reader`/`attempt`)
   even though the reader suppresses the duplicates it forwards to the turn.
+- Every `ws:*` event carries `reader` — a monotonic id for the
+  `streamChatEvents` call (reader) behind the connection, allocated from one
+  process‑wide counter so it stays unique across model and client instances.
+  `attempt` restarts at 1 per reader, so identify a connection as
+  `(chatId, reader, attempt)`, never `(chatId, attempt)` alone: a client‑tool
+  pause the caller abandons is closed fire‑and‑forget when the next turn dials
+  its replacement, and the superseded reader's late `ws:close` (or a raced‑in
+  frame) can emit after the new reader's `ws:dial` — the reader id is what
+  tells them apart. `segment:settle` names the reader that served the segment;
+  `segment:start` predates stream acquisition and carries none.
 - 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

package/dist/index.d.ts

@@ -382,9 +382,24 @@ interface HttpErrorTransportEvent extends HttpTransportEventBase {
 }
 interface StreamTransportEventBase extends TransportEventBase {
     chatId: string;
+    /**
+     * Identifies the reader (one `streamChatEvents` call) this event belongs
+     * to: monotonically increasing, allocated per call from one module-global
+     * (process-wide) counter — NOT per model or client instance, so
+     * `(chatId, reader, attempt)` stays unique for the lifetime of any
+     * subscriber, even one shared across instances (issue #94). Readers on
+     * other chats/clients advance the same counter, so ids are ordered but not
+     * dense per chat. Use it to tell a superseded reader's late events apart
+     * from the live reader's: a client-tool pause abandoned by the caller is
+     * closed fire-and-forget when the next turn dials its replacement, and the
+     * old reader's `ws:close` (or a raced-in frame) can emit after the new
+     * reader's `ws:dial` — both would otherwise be ambiguous at `attempt` 1.
+     */
+    reader: number;
     /**
      * 1-based connection attempt within one reader (`streamChatEvents` call —
-     * with stream retention (#44), one per turn). Increments on every redial.
+     * with stream retention (#44), one per turn). Increments on every redial
+     * and restarts at 1 for each new reader.
      */
     attempt: number;
 }
@@ -446,6 +461,17 @@ interface SegmentTransportEventBase extends TransportEventBase {
     segment: number;
     /** Undefined on a first turn's start until the chat is created. */
     chatId?: string;
+    /**
+     * The reader (`streamChatEvents` call — the `reader` on `ws:*` events) that
+     * served this segment, correlating it with the connection's `ws:*` events.
+     * Absent on `segment:start`, which is emitted before the segment acquires
+     * its stream (a fresh turn dials only once the chat exists, and even a
+     * stream retained by a client-tool pause can still be replaced — stamping a
+     * predicted reader could lie), and on a settle when the segment failed
+     * before acquiring one. Segments of one turn share the reader: the stream
+     * is retained across `requires_action` pauses (#44).
+     */
+    reader?: number;
 }
 /**
  * A segment (one model round-trip: submission plus the server run until it
@@ -531,6 +557,13 @@ interface StreamChatEventsOptions {
      * listeners are registered. See {@link CoderTransportEvent}.
      */
     onTransportEvent?: TransportEventHandler;
+    /**
+     * Reader id stamped on this call's `ws:*` events, for callers that need to
+     * know it (the model records it to stamp `segment:settle` with the reader
+     * that served the segment). Must come from {@link nextStreamReaderId};
+     * allocated automatically when absent.
+     */
+    reader?: number;
 }
 /**
  * Opens the chatd `/stream` WebSocket and yields decoded {@link ChatStreamEvent}s
@@ -678,6 +711,8 @@ declare class CoderChatClient {
     streamEvents(chatId: string, opts?: {
         afterId?: number;
         signal?: AbortSignal;
+        /** Pre-allocated reader id for `ws:*` events — see {@link streamChatEvents}. */
+        reader?: number;
     }): AsyncGenerator<ChatStreamEvent, void, void>;
     /**
      * Watch lifecycle events (status/title changes, creation, deletion, …) for

package/dist/index.js

@@ -185,6 +185,11 @@ function httpToWs(baseUrl) {
   if (baseUrl.startsWith("http://")) return `ws://${baseUrl.slice("http://".length)}`;
   return baseUrl;
 }
+var readerSeq = 0;
+function nextStreamReaderId() {
+  readerSeq += 1;
+  return readerSeq;
+}
 var STREAM_BACKOFF_INITIAL_MS = 1e3;
 var STREAM_BACKOFF_CAP_MS = 3e4;
 var STREAM_MAX_CONSECUTIVE_FAILURES = 5;
@@ -197,7 +202,8 @@ function streamChatEvents(options) {
     if (external.aborted) chain();
     else external.addEventListener("abort", chain, { once: true });
   }
-  const inner = streamChatEventsLoop({ ...options, signal: controller.signal });
+  const reader = options.reader ?? nextStreamReaderId();
+  const inner = streamChatEventsLoop({ ...options, reader, signal: controller.signal });
   const detach = () => external?.removeEventListener("abort", chain);
   const finish = async () => {
     controller.abort();
@@ -240,7 +246,7 @@ function streamChatEvents(options) {
   };
 }
 async function* streamChatEventsLoop(options) {
-  const { baseUrl, token, chatId, signal } = options;
+  const { baseUrl, token, chatId, signal, reader } = options;
   const factory = options.webSocketFactory ?? defaultFactory;
   const emit = safeTransportEmitter(options.onTransportEvent);
   let attempt = 0;
@@ -269,15 +275,15 @@ async function* streamChatEventsLoop(options) {
       resolveNext = void 0;
     };
     attempt += 1;
-    emit?.({ type: "ws:dial", chatId, attempt, url, timestamp: Date.now() });
+    emit?.({ type: "ws:dial", chatId, reader, 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() });
+        emit({ type: "ws:error", chatId, reader, attempt, message, timestamp: Date.now() });
+        emit({ type: "ws:close", chatId, reader, attempt, timestamp: Date.now() });
       }
       throw err;
     }
@@ -307,6 +313,7 @@ async function* streamChatEventsLoop(options) {
         emit?.({
           type: "ws:error",
           chatId,
+          reader,
           attempt,
           message: "failed to parse chat stream frame",
           timestamp: Date.now()
@@ -323,6 +330,7 @@ async function* streamChatEventsLoop(options) {
           emit?.({
             type: "ws:event",
             chatId,
+            reader,
             attempt,
             event: e,
             timestamp: Date.now()
@@ -333,6 +341,7 @@ async function* streamChatEventsLoop(options) {
         emit?.({
           type: "ws:event",
           chatId,
+          reader,
           attempt,
           event: batch,
           timestamp: Date.now()
@@ -343,7 +352,7 @@ async function* streamChatEventsLoop(options) {
     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() });
+      emit?.({ type: "ws:error", chatId, reader, 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;
@@ -355,6 +364,7 @@ async function* streamChatEventsLoop(options) {
         const closeEvent = {
           type: "ws:close",
           chatId,
+          reader,
           attempt,
           timestamp: Date.now()
         };
@@ -365,7 +375,7 @@ async function* streamChatEventsLoop(options) {
       finished = true;
       wake();
     };
-    const onOpen = emit ? () => emit({ type: "ws:open", chatId, attempt, timestamp: Date.now() }) : void 0;
+    const onOpen = emit ? () => emit({ type: "ws:open", chatId, reader, attempt, timestamp: Date.now() }) : void 0;
     if (onOpen) ws.addEventListener("open", onOpen);
     ws.addEventListener("message", onMessage);
     ws.addEventListener("error", onError);
@@ -426,7 +436,7 @@ async function* streamChatEventsLoop(options) {
       }
       if (emit && !closeEmitted) {
         closeEmitted = true;
-        emit({ type: "ws:close", chatId, attempt, timestamp: Date.now() });
+        emit({ type: "ws:close", chatId, reader, attempt, timestamp: Date.now() });
       }
     }
     if (signal?.aborted) return;
@@ -451,6 +461,7 @@ async function* streamChatEventsLoop(options) {
     emit?.({
       type: "ws:redial",
       chatId,
+      reader,
       attempt,
       consecutiveFailures: failures,
       maxConsecutiveFailures: STREAM_MAX_CONSECUTIVE_FAILURES,
@@ -867,6 +878,7 @@ var CoderChatClient = class {
       chatId,
       afterId: opts?.afterId,
       signal: opts?.signal,
+      reader: opts?.reader,
       webSocketFactory: this.#webSocketFactory,
       onTransportEvent: this.#onTransportEvent
     });
@@ -1145,6 +1157,12 @@ function dynamicToolNames(tools) {
 // src/model/session-stream.ts
 var SessionChatStream = class {
   chatId;
+  /**
+   * The reader id stamped on the wrapped reader's `ws:*` transport events —
+   * the model stamps it on `segment:settle` so segments correlate with the
+   * connection that served them (issue #94).
+   */
+  reader;
   #events;
   #controller = new AbortController();
   #pending;
@@ -1153,6 +1171,7 @@ var SessionChatStream = class {
   #closePromise;
   constructor(opts) {
     this.chatId = opts.chatId;
+    this.reader = opts.reader;
     this.#events = opts.open(this.#controller.signal);
   }
   get closed() {
@@ -1811,9 +1830,11 @@ var CoderLanguageModel = class {
     }
     this.#retainedStream = void 0;
     if (retained) void retained.close();
+    const reader = nextStreamReaderId();
     const created = new SessionChatStream({
       chatId,
-      open: (streamSignal) => this.#config.client.streamEvents(chatId, { afterId, signal: streamSignal })
+      reader,
+      open: (streamSignal) => this.#config.client.streamEvents(chatId, { afterId, signal: streamSignal, reader })
     });
     this.#retainedStream = created;
     return created;
@@ -1977,6 +1998,7 @@ var CoderLanguageModel = class {
       };
       const chatId = segmentChat.chatId ?? this.#chatId;
       if (chatId !== void 0) settleEvent.chatId = chatId;
+      if (segmentChat.reader !== void 0) settleEvent.reader = segmentChat.reader;
       if (!failed && finishReason === void 0) {
         if (segmentChat.timeoutError) {
           failure = segmentChat.timeoutError;
@@ -2140,6 +2162,7 @@ var CoderLanguageModel = class {
       let recoveryAttempted = false;
       const stream = this.#acquireStream(action.kind === "resume", chatId, afterId);
       streamAcquired = true;
+      if (segmentChat) segmentChat.reader = stream.reader;
       let onSegmentAbort;
       const segmentAborted = signal ? new Promise((resolve) => {
         onSegmentAbort = () => resolve(SEGMENT_ABORTED);