@coder/ai-sdk-agent 0.4.3 → 0.5.0

package/dist/index.d.ts

@@ -873,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;
@@ -882,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>;
 }
@@ -911,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. */

package/dist/index.js

@@ -1016,6 +1016,95 @@ function dynamicToolNames(tools) {
   return names;
 }
 
+// src/model/session-stream.ts
+var SessionChatStream = class {
+  chatId;
+  #events;
+  #controller = new AbortController();
+  #pending;
+  #attached = true;
+  #reusable = false;
+  #closePromise;
+  constructor(opts) {
+    this.chatId = opts.chatId;
+    this.#events = opts.open(this.#controller.signal);
+  }
+  get closed() {
+    return this.#closePromise !== void 0;
+  }
+  /** Whether a segment is currently consuming this stream. */
+  get attached() {
+    return this.#attached;
+  }
+  /** Whether a resume segment for `chatId` may {@link attach}. */
+  canAttach(chatId) {
+    return !this.closed && this.#reusable && this.chatId === chatId;
+  }
+  /**
+   * The next event, memoized: repeated calls return the SAME promise until
+   * {@link consumed} acknowledges delivery, so a read abandoned by one segment
+   * is handed to the next instead of losing its event.
+   */
+  read() {
+    if (!this.#pending) {
+      if (!this.#attached && !this.closed) {
+        throw new CoderAgentError("SessionChatStream.read() without an attached segment");
+      }
+      this.#pending = this.#events.next();
+      this.#pending.catch(() => {
+      });
+    }
+    return this.#pending;
+  }
+  /**
+   * Acknowledge that the segment received `p`'s result and the next
+   * {@link read} should issue a fresh read. A no-op unless `p` is the
+   * outstanding read — a raced-out segment never consumes.
+   */
+  consumed(p) {
+    if (this.#pending === p) this.#pending = void 0;
+  }
+  /** Attach the resume segment to a stream paused at `requires_action`. */
+  attach() {
+    if (!this.canAttach(this.chatId) || this.#attached) {
+      throw new CoderAgentError("SessionChatStream.attach() on a non-reusable stream");
+    }
+    this.#attached = true;
+    this.#reusable = false;
+  }
+  /**
+   * Segment settled at a healthy `requires_action` pause: keep the stream for
+   * the tool-result resume, with a read outstanding so the reader's redial
+   * machinery stays live while the client tools execute.
+   */
+  pause() {
+    this.#attached = false;
+    if (this.closed) return;
+    this.#reusable = true;
+    if (!this.#pending) {
+      this.#pending = this.#events.next();
+      this.#pending.catch(() => {
+      });
+    }
+  }
+  /**
+   * Close the underlying reader (and socket). Idempotent; safe on a stream
+   * whose generator already ended or threw.
+   */
+  close() {
+    this.#closePromise ??= (async () => {
+      this.#attached = false;
+      this.#reusable = false;
+      this.#controller.abort();
+      try {
+        await this.#events.return(void 0);
+      } catch {
+      }
+    })();
+    return this.#closePromise;
+  }
+};
+
 // src/model/translate.ts
 function addDefined(a, b) {
   if (b === void 0) return a;
@@ -1075,6 +1164,7 @@ function jsonResult(value) {
 }
 var TurnTranslator = class {
   #dynamicToolNames;
+  #submittedToolCallIds;
   #seq = 0;
   #text = { id: void 0, len: 0, sawDelta: false };
   #reasoning = { id: void 0, len: 0, sawDelta: false };
@@ -1111,6 +1201,7 @@ var TurnTranslator = class {
   constructor(opts) {
     this.#dynamicToolNames = opts.dynamicToolNames;
     this.#turnCursor = opts.turnCursor ?? 0;
+    this.#submittedToolCallIds = opts.submittedToolCallIds ?? /* @__PURE__ */ new Set();
   }
   get terminalStatus() {
     return this.#terminalStatus;
@@ -1260,6 +1351,7 @@ var TurnTranslator = class {
       case "action_required":
         for (const tc of ev.action_required?.tool_calls ?? []) {
           if (this.#clientToolCalls.has(tc.tool_call_id)) continue;
+          if (this.#submittedToolCallIds.has(tc.tool_call_id)) continue;
           this.#closeText(out);
           this.#closeReasoning(out);
           this.#clientToolCalls.add(tc.tool_call_id);
@@ -1281,8 +1373,12 @@ var TurnTranslator = class {
         }
         break;
       case "status":
-        if (ev.status && TERMINAL_STATUSES.has(ev.status.status)) {
-          this.#terminalStatus = ev.status.status;
+        if (ev.status) {
+          if (TERMINAL_STATUSES.has(ev.status.status)) {
+            this.#terminalStatus = ev.status.status;
+          } else {
+            this.#terminalStatus = void 0;
+          }
         }
         break;
       default:
@@ -1416,6 +1512,7 @@ var TurnTranslator = class {
 // src/model/language-model.ts
 var ACTION_REQUIRED_GRACE_MS = 2e3;
 var GRACE_EXPIRED = /* @__PURE__ */ Symbol("action-required-grace-expired");
+var SEGMENT_ABORTED = /* @__PURE__ */ Symbol("segment-aborted");
 function startGraceTimer(ms) {
   let timer;
   const expired = new Promise((resolve) => {
@@ -1444,6 +1541,8 @@ var CoderLanguageModel = class {
   #modelResolved = false;
   #submittedToolCallIds = /* @__PURE__ */ new Set();
   #inFlight = false;
+  /** The turn-lifetime event stream, retained across client-tool pauses. */
+  #retainedStream;
   constructor(config) {
     assertSupportedAiVersion();
     this.#config = config;
@@ -1453,11 +1552,75 @@ var CoderLanguageModel = class {
   get chatId() {
     return this.#chatId;
   }
-  /** 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() {
     this.#chatId = void 0;
     this.#lastSeenMessageId = 0;
     this.#submittedToolCallIds.clear();
+    const stream = this.#retainedStream;
+    this.#retainedStream = void 0;
+    if (stream) void stream.close();
+  }
+  /**
+   * 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.
+   */
+  async [Symbol.asyncDispose]() {
+    const stream = this.#retainedStream;
+    this.#retainedStream = void 0;
+    if (stream) await stream.close();
+  }
+  /**
+   * 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.
+   */
+  async closePausedStream() {
+    const stream = this.#retainedStream;
+    if (!stream || stream.attached) return;
+    this.#retainedStream = void 0;
+    await stream.close();
+  }
+  /**
+   * The stream a segment reads: a resume segment re-attaches to the stream
+   * its predecessor left paused at `requires_action` (the whole point of
+   * retention — no re-dial per tool round trip); everything else — a new
+   * turn, or a pause the caller abandoned — replaces it with a fresh dial,
+   * because a stale buffer from a settle this client never observed must not
+   * leak into the new turn.
+   */
+  #acquireStream(resume, chatId, afterId) {
+    const retained = this.#retainedStream;
+    if (resume && retained?.canAttach(chatId)) {
+      retained.attach();
+      return retained;
+    }
+    this.#retainedStream = void 0;
+    if (retained) void retained.close();
+    const created = new SessionChatStream({
+      chatId,
+      open: (streamSignal) => this.#config.client.streamEvents(chatId, { afterId, signal: streamSignal })
+    });
+    this.#retainedStream = created;
+    return created;
+  }
+  /** Close `stream` and drop the retention slot if it still holds it. */
+  async #closeStream(stream) {
+    if (this.#retainedStream === stream) this.#retainedStream = void 0;
+    await stream.close();
   }
   async #resolveModelConfigId(signal) {
     if (this.#modelResolved) return this.#resolvedModelConfigId;
@@ -1559,10 +1722,12 @@ var CoderLanguageModel = class {
     );
     const signal = sources.length > 0 ? AbortSignal.any(sources) : void 0;
     let translator;
+    let streamAcquired = false;
     let discardSession = false;
     let interruptSent = false;
+    let turnChatId;
     const interrupt = () => {
-      const id = this.#chatId;
+      const id = turnChatId ?? this.#chatId;
       if (interruptSent || !id) return;
       interruptSent = true;
       void this.#config.client.interruptChat(id).catch(() => {
@@ -1660,25 +1825,48 @@ var CoderLanguageModel = class {
         afterId = this.#lastSeenMessageId;
       }
       const chatId = this.#chatId;
+      turnChatId = chatId;
       const dynamicNames = dynamicToolNames(options.tools);
       translator = new TurnTranslator({
         dynamicToolNames: dynamicNames,
-        turnCursor: afterId ?? 0
+        turnCursor: afterId ?? 0,
+        // The retained stream redials with the TURN's original cursor, so a
+        // reconnect can replay an earlier segment's `action_required`
+        // snapshot; calls this session already answered must not run again.
+        submittedToolCallIds: this.#submittedToolCallIds
       });
       let sinceRequiresAction = 0;
       let grace;
       let recovery;
       let recoveryAbort;
       let recoveryAttempted = false;
-      const stream = this.#config.client.streamEvents(chatId, { afterId, signal });
+      const stream = this.#acquireStream(action.kind === "resume", chatId, afterId);
+      streamAcquired = true;
+      let onSegmentAbort;
+      const segmentAborted = signal ? new Promise((resolve) => {
+        onSegmentAbort = () => resolve(SEGMENT_ABORTED);
+        if (signal.aborted) onSegmentAbort();
+        else signal.addEventListener("abort", onSegmentAbort, { once: true });
+      }) : void 0;
+      const raceSegment = (p) => segmentAborted ? Promise.race([p, segmentAborted]) : p;
+      let retainStream = false;
       try {
-        let next = stream.next();
         for (; ; ) {
-          let result;
+          const next = stream.read();
           const awaitingActionRequired = translator.terminalStatus === "requires_action" && !translator.clientToolCallSeen;
+          if (!awaitingActionRequired && (grace !== void 0 || recoveryAttempted)) {
+            grace?.cancel();
+            grace = void 0;
+            recoveryAbort?.abort();
+            recoveryAbort = void 0;
+            recovery = void 0;
+            recoveryAttempted = false;
+            sinceRequiresAction = 0;
+          }
+          let raced;
           if (awaitingActionRequired && !recoveryAttempted) {
             grace ??= startGraceTimer(ACTION_REQUIRED_GRACE_MS);
-            const raced = await Promise.race([next, grace.expired]);
+            raced = await raceSegment(Promise.race([next, grace.expired]));
             if (raced === GRACE_EXPIRED) {
               recoveryAttempted = true;
               throwIfAborted();
@@ -1691,27 +1879,25 @@ var CoderLanguageModel = class {
               ).catch(() => []);
               continue;
             }
-            result = raced;
           } else if (awaitingActionRequired && recovery) {
-            const raced = await Promise.race([next, recovery]);
+            raced = await raceSegment(Promise.race([next, recovery]));
             if (Array.isArray(raced)) {
               recovery = void 0;
               throwIfAborted();
               for (const ev of raced) for (const part of translator.ingest(ev)) yield part;
-              if (translator.clientToolCallSeen) {
-                void next.catch(() => {
-                });
-                break;
-              }
+              if (translator.clientToolCallSeen) break;
               continue;
             }
-            result = raced;
           } else {
-            result = await next;
+            raced = await raceSegment(next);
+          }
+          if (raced === SEGMENT_ABORTED) {
+            throwIfAborted();
+            throw new CoderAgentError("segment abort sentinel resolved without an abort");
           }
-          if (result.done) break;
-          next = stream.next();
-          for (const part of translator.ingest(result.value)) yield part;
+          stream.consumed(next);
+          if (raced.done) break;
+          for (const part of translator.ingest(raced.value)) yield part;
           const status = translator.terminalStatus;
           if (status) {
             if (status !== "requires_action") break;
@@ -1719,6 +1905,7 @@ var CoderLanguageModel = class {
             if (++sinceRequiresAction > 200) break;
           }
         }
+        retainStream = !signal?.aborted && translator.terminalStatus === "requires_action" && translator.clientToolCallSeen && !translator.error;
       } catch (err) {
         throwIfAborted();
         if (err instanceof CoderStreamError) {
@@ -1745,8 +1932,12 @@ var CoderLanguageModel = class {
       } finally {
         grace?.cancel();
         recoveryAbort?.abort();
-        await stream.return(void 0).catch(() => {
-        });
+        if (signal && onSegmentAbort) signal.removeEventListener("abort", onSegmentAbort);
+        if (retainStream && !signal?.aborted && !stream.closed) {
+          stream.pause();
+        } else {
+          await this.#closeStream(stream);
+        }
       }
       throwIfAborted();
       if (!translator.terminalStatus && !translator.error) {
@@ -1765,6 +1956,11 @@ var CoderLanguageModel = class {
         this.#lastSeenMessageId = translator.maxMessageId;
       signal?.removeEventListener("abort", interrupt);
       if (!translator?.terminalStatus) interrupt();
+      if (!streamAcquired && this.#retainedStream) {
+        const stale = this.#retainedStream;
+        this.#retainedStream = void 0;
+        void stale.close();
+      }
       if (discardSession) this.resetSession();
       this.#inFlight = false;
     }
@@ -2014,7 +2210,9 @@ var CoderAgent = class {
    */
   async interrupt(opts) {
     const id = this.#model.chatId;
-    if (id) await this.#client.interruptChat(id, opts?.signal);
+    if (!id) return;
+    await this.#model.closePausedStream();
+    await this.#client.interruptChat(id, opts?.signal);
   }
   /**
    * Archive the underlying chat (safe cleanup; hides it from listings).
@@ -2028,6 +2226,7 @@ var CoderAgent = class {
   async archive(opts) {
     const id = this.#model.chatId;
     if (!id) return;
+    await this.#model.closePausedStream();
     await archiveWhenSettled(this.#client, id, {
       deadlineMs: this.#settleDeadlineMs,
       retryDelayMs: this.#settleRetryDelayMs,
@@ -2051,6 +2250,10 @@ var CoderAgent = class {
    * ```
    */
   async [Symbol.asyncDispose]() {
+    try {
+      await this.#model[Symbol.asyncDispose]();
+    } catch {
+    }
     const deadline = AbortSignal.timeout(this.#settleDeadlineMs);
     try {
       await this.interrupt({ signal: deadline });