@coder/ai-sdk-agent 0.4.2 → 0.5.0

package/dist/index.js

@@ -5,6 +5,7 @@ import {
 } from "ai";
 
 // src/errors.ts
+import { APICallError } from "@ai-sdk/provider";
 var CoderAgentError = class extends Error {
   name = "CoderAgentError";
   constructor(message, options) {
@@ -27,6 +28,22 @@ var CoderApiError = class extends CoderAgentError {
     this.path = args.path;
   }
 };
+var CoderStreamError = class extends APICallError {
+  name = "CoderStreamError";
+  constructor(args) {
+    super({
+      message: args.message,
+      url: args.url,
+      requestBodyValues: void 0,
+      // Retries re-invoke the model with the SAME prompt, so the model layer
+      // downgrades this to false whenever the failed chat has prior state a
+      // re-submission would corrupt, or server-side tooling (workspace/MCP)
+      // whose effects a replay would duplicate (see #runTurn).
+      isRetryable: args.isRetryable ?? true,
+      cause: args.cause
+    });
+  }
+};
 var CoderChatError = class extends CoderAgentError {
   name = "CoderChatError";
   kind;
@@ -154,92 +171,209 @@ function httpToWs(baseUrl) {
   if (baseUrl.startsWith("http://")) return `ws://${baseUrl.slice("http://".length)}`;
   return baseUrl;
 }
-async function* streamChatEvents(options) {
-  const { baseUrl, token, chatId, afterId, signal } = options;
-  const factory = options.webSocketFactory ?? defaultFactory;
-  const wsBase = httpToWs(baseUrl);
-  const query = afterId !== void 0 ? `?after_id=${afterId}` : "";
-  const url = `${wsBase}/api/experimental/chats/${chatId}/stream${query}`;
-  const queue = [];
-  let resolveNext;
-  let finished = false;
-  let failure;
-  const wake = () => {
-    resolveNext?.();
-    resolveNext = void 0;
-  };
-  const ws = factory(url, { headers: { "Coder-Session-Token": token } });
-  const onAbort = () => {
-    finished = true;
+var STREAM_BACKOFF_INITIAL_MS = 1e3;
+var STREAM_BACKOFF_CAP_MS = 3e4;
+var STREAM_MAX_CONSECUTIVE_FAILURES = 5;
+var TRANSIENT_UPGRADE_STATUSES = /* @__PURE__ */ new Set([408, 425, 429]);
+function streamChatEvents(options) {
+  const controller = new AbortController();
+  const external = options.signal;
+  const chain = () => controller.abort(external?.reason);
+  if (external) {
+    if (external.aborted) chain();
+    else external.addEventListener("abort", chain, { once: true });
+  }
+  const inner = streamChatEventsLoop({ ...options, signal: controller.signal });
+  const detach = () => external?.removeEventListener("abort", chain);
+  const finish = async () => {
+    controller.abort();
+    detach();
     try {
-      ws.close(1e3);
+      await inner.return();
     } catch {
     }
-    wake();
   };
-  let abortListenerAdded = false;
-  if (signal) {
-    if (signal.aborted) onAbort();
-    else {
-      signal.addEventListener("abort", onAbort, { once: true });
-      abortListenerAdded = true;
+  return {
+    // Detach the signal chain once the loop settles for good (done, or a
+    // terminal failure) — the iteration protocol never calls return() on a
+    // failed iterator, and the {once} listener would otherwise pile up on a
+    // long-lived signal across re-created readers.
+    async next() {
+      try {
+        const result = await inner.next();
+        if (result.done) detach();
+        return result;
+      } catch (err) {
+        detach();
+        throw err;
+      }
+    },
+    async return() {
+      await finish();
+      return { done: true, value: void 0 };
+    },
+    async throw(err) {
+      await finish();
+      throw err;
+    },
+    [Symbol.asyncIterator]() {
+      return this;
+    },
+    // Native async generators are async-disposable; the wrapper must be too.
+    async [Symbol.asyncDispose]() {
+      await finish();
     }
-  }
-  const onMessage = (ev) => {
-    if (finished) return;
-    let batch;
-    try {
-      const data = typeof ev.data === "string" ? ev.data : String(ev.data);
-      batch = JSON.parse(data);
-    } catch (err) {
-      failure = new CoderAgentError("failed to parse chat stream frame", { cause: err });
+  };
+}
+async function* streamChatEventsLoop(options) {
+  const { baseUrl, token, chatId, signal } = options;
+  const factory = options.webSocketFactory ?? defaultFactory;
+  const wsBase = httpToWs(baseUrl);
+  const path = `/api/experimental/chats/${chatId}/stream`;
+  const query = options.afterId !== void 0 ? `?after_id=${options.afterId}` : "";
+  const url = `${wsBase}${path}${query}`;
+  let maxCommittedId = options.afterId;
+  let lastHistoryVersion;
+  let lastGenerationAttempt;
+  let lastSeq;
+  let sawUntrackableDelta = false;
+  let backoffMs = STREAM_BACKOFF_INITIAL_MS;
+  let failures = 0;
+  let lastFailure;
+  while (!signal?.aborted) {
+    const queue = [];
+    let resolveNext;
+    let finished = false;
+    let failure;
+    let parseFailure = false;
+    const wake = () => {
+      resolveNext?.();
+      resolveNext = void 0;
+    };
+    const ws = factory(url, { headers: { "Coder-Session-Token": token } });
+    const onAbort = () => {
       finished = true;
+      try {
+        ws.close(1e3);
+      } catch {
+      }
       wake();
-      return;
-    }
-    if (Array.isArray(batch)) {
-      for (const e of batch) queue.push(e);
-    } else if (batch && typeof batch === "object") {
-      queue.push(batch);
+    };
+    let abortListenerAdded = false;
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else {
+        signal.addEventListener("abort", onAbort, { once: true });
+        abortListenerAdded = true;
+      }
     }
-    wake();
-  };
-  const onError = (ev) => {
-    if (finished) return;
-    const message = ev && typeof ev === "object" && "message" in ev ? String(ev.message) : "chat stream socket error";
-    failure = new CoderAgentError(message);
-    finished = true;
-    wake();
-  };
-  const onClose = () => {
-    finished = true;
-    wake();
-  };
-  ws.addEventListener("message", onMessage);
-  ws.addEventListener("error", onError);
-  ws.addEventListener("close", onClose);
-  try {
-    while (true) {
-      while (queue.length > 0) {
-        const next = queue.shift();
-        yield next;
+    const onMessage = (ev) => {
+      if (finished) return;
+      let batch;
+      try {
+        const data = typeof ev.data === "string" ? ev.data : String(ev.data);
+        batch = JSON.parse(data);
+      } catch (err) {
+        failure = new CoderAgentError("failed to parse chat stream frame", { cause: err });
+        parseFailure = true;
+        finished = true;
+        wake();
+        return;
+      }
+      if (Array.isArray(batch)) {
+        for (const e of batch) queue.push(e);
+      } else if (batch && typeof batch === "object") {
+        queue.push(batch);
       }
-      if (failure) throw failure;
+      wake();
+    };
+    const onError = (ev) => {
       if (finished) return;
-      await new Promise((resolve) => {
-        resolveNext = resolve;
+      const message = ev && typeof ev === "object" && "message" in ev ? String(ev.message) : "chat stream socket error";
+      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 = () => {
+      finished = true;
+      wake();
+    };
+    ws.addEventListener("message", onMessage);
+    ws.addEventListener("error", onError);
+    ws.addEventListener("close", onClose);
+    try {
+      while (true) {
+        while (queue.length > 0) {
+          const next = queue.shift();
+          let progress = false;
+          if (next.type === "message_part") {
+            const mp = next.message_part;
+            const hv = mp?.history_version;
+            const ga = mp?.generation_attempt;
+            const seq = mp?.seq;
+            if (hv !== void 0 && ga !== void 0 && seq !== void 0) {
+              if (hv === lastHistoryVersion && ga === lastGenerationAttempt && lastSeq !== void 0 && seq <= lastSeq) {
+                continue;
+              }
+              lastHistoryVersion = hv;
+              lastGenerationAttempt = ga;
+              lastSeq = seq;
+              progress = true;
+            } else {
+              sawUntrackableDelta = true;
+            }
+          } else if (next.type === "message" && next.message) {
+            if (maxCommittedId === void 0 || next.message.id > maxCommittedId) {
+              maxCommittedId = next.message.id;
+              progress = true;
+              sawUntrackableDelta = false;
+            }
+          }
+          if (progress) {
+            failures = 0;
+            backoffMs = STREAM_BACKOFF_INITIAL_MS;
+          }
+          yield next;
+        }
+        if (finished) break;
+        await new Promise((resolve) => {
+          resolveNext = resolve;
+        });
+      }
+    } finally {
+      finished = true;
+      if (signal && abortListenerAdded) signal.removeEventListener("abort", onAbort);
+      ws.removeEventListener("message", onMessage);
+      ws.removeEventListener("error", onError);
+      ws.removeEventListener("close", onClose);
+      try {
+        ws.close(1e3);
+      } catch {
+      }
+    }
+    if (signal?.aborted) return;
+    if (failure instanceof CoderApiError) throw failure;
+    if (parseFailure && failure) throw failure;
+    if (sawUntrackableDelta) {
+      throw new CoderStreamError({
+        message: "chat stream dropped mid-turn and cannot be resumed: this server does not stamp deltas with history_version/generation_attempt/seq, so a redial would replay them",
+        url,
+        cause: failure
       });
     }
-  } finally {
-    finished = true;
-    if (signal && abortListenerAdded) signal.removeEventListener("abort", onAbort);
-    ws.removeEventListener("message", onMessage);
-    ws.removeEventListener("error", onError);
-    ws.removeEventListener("close", onClose);
-    try {
-      ws.close(1e3);
-    } catch {
+    if (failure) lastFailure = failure;
+    failures += 1;
+    if (failures >= STREAM_MAX_CONSECUTIVE_FAILURES) {
+      throw new CoderStreamError({
+        message: `Coder chat stream ${path} could not be (re-)established after ${failures} consecutive connection failures without progress`,
+        url,
+        cause: lastFailure
+      });
     }
+    await sleep(backoffMs, signal);
+    if (signal?.aborted) return;
+    backoffMs = Math.min(backoffMs * 2, STREAM_BACKOFF_CAP_MS);
   }
 }
 var WATCH_PATH = "/api/experimental/chats/watch";
@@ -882,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;
@@ -941,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 };
@@ -958,6 +1182,11 @@ var TurnTranslator = class {
   // the same message replaces its earlier entry instead of double-counting
   // (chatd re-sends full snapshots on revision bumps and history resets).
   #usageByMessageId = /* @__PURE__ */ new Map();
+  // Assistant snapshots already processed once. A redial replays the turn
+  // from its original cursor, so earlier messages arrive again — without this,
+  // re-running the boundary logic on them would reset the emitted-length
+  // cursors and re-emit their entire text (see #ingestMessage).
+  #snapshotSeen = /* @__PURE__ */ new Set();
   #error;
   #terminalStatus;
   #maxMessageId = 0;
@@ -972,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;
@@ -1121,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);
@@ -1142,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:
@@ -1197,6 +1432,17 @@ var TurnTranslator = class {
     }
     const content = message.content ?? [];
     if (message.role === "assistant") {
+      if (this.#snapshotSeen.has(message.id) && (message.id !== this.#currentAssistantId || this.#deltasSinceSnapshot)) {
+        for (const part of content) {
+          if (part.type === "tool-call" && !this.#isClientTool(part.tool_name))
+            this.#emitServerToolCall(out, part);
+          else if (part.type === "tool-result" && !this.#isClientTool(part.tool_name))
+            this.#emitServerToolResult(out, part);
+          else if (part.type === "source") this.#emitSource(out, part);
+        }
+        return;
+      }
+      this.#snapshotSeen.add(message.id);
       if (this.#currentAssistantId !== void 0 && this.#currentAssistantId !== message.id && !this.#deltasSinceSnapshot) {
         this.#closeText(out);
         this.#closeReasoning(out);
@@ -1204,13 +1450,24 @@ var TurnTranslator = class {
         this.#reasoning.sawDelta = false;
       }
       this.#currentAssistantId = message.id;
-      if (!this.#text.sawDelta) {
-        const full = content.filter((p) => p.type === "text").map((p) => p.text ?? "").join("");
-        if (full.length > 0) this.#emitTextUpTo(out, full);
-      }
-      if (!this.#reasoning.sawDelta) {
-        const full = content.filter((p) => p.type === "reasoning").map((p) => p.text ?? "").join("");
-        if (full.length > 0) this.#emitReasoningUpTo(out, full);
+      const emitSnapshotText = () => {
+        if (!this.#text.sawDelta || this.#text.id) {
+          const full = content.filter((p) => p.type === "text").map((p) => p.text ?? "").join("");
+          if (full.length > 0) this.#emitTextUpTo(out, full);
+        }
+      };
+      const emitSnapshotReasoning = () => {
+        if (!this.#reasoning.sawDelta || this.#reasoning.id) {
+          const full = content.filter((p) => p.type === "reasoning").map((p) => p.text ?? "").join("");
+          if (full.length > 0) this.#emitReasoningUpTo(out, full);
+        }
+      };
+      if (this.#reasoning.id) {
+        emitSnapshotReasoning();
+        emitSnapshotText();
+      } else {
+        emitSnapshotText();
+        emitSnapshotReasoning();
       }
       for (const part of content) {
         if (part.type === "tool-call" && !this.#isClientTool(part.tool_name))
@@ -1253,6 +1510,16 @@ 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) => {
+    timer = setTimeout(() => resolve(GRACE_EXPIRED), ms);
+  });
+  return { expired, cancel: () => clearTimeout(timer) };
+}
 var EMPTY_USAGE = {
   inputTokens: {
     total: void 0,
@@ -1274,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;
@@ -1283,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;
@@ -1306,17 +1639,74 @@ var CoderLanguageModel = class {
    * id, so this runs before the chat exists). Pre-uploaded files carried via
    * `providerOptions.coder.fileId` are referenced without re-uploading.
    */
-  #buildContent(content, signal) {
+  #buildContent(content, signal, onUpload) {
     const uploadFile = async (f) => {
       const uploaded = await this.#config.client.uploadChatFile(
         this.#config.organizationId,
         { content: dataContentToFileContent(f.data), mediaType: f.mediaType, name: f.filename },
         signal
       );
+      onUpload?.();
       return uploaded.id;
     };
     return userContentToInputParts(content, uploadFile);
   }
+  /**
+   * REST fallback for a `requires_action` segment whose `action_required`
+   * event never arrived: recover the turn's pending client tool calls from
+   * committed chat history (`GET /chats/{id}/messages`) — the same history
+   * chatd itself derives `action_required` from server-side. Returns synthetic
+   * stream events for the translator: the turn's message snapshots first (so
+   * text, usage, and the message cursor stay consistent even if the stream
+   * also missed a commit — the translator's id-keyed dedup makes re-ingesting
+   * already-delivered ones a no-op), then one `action_required` event carrying
+   * the unresolved dynamic tool calls. Returns `[]` when history shows no
+   * pending calls — nothing to recover, the caller keeps waiting on the
+   * stream, bounded by `requestTimeoutMs`/abort.
+   */
+  async #recoverRequiresAction(chatId, dynamicNames, afterId, signal) {
+    const { messages } = await this.#config.client.getMessages(chatId, { limit: 200 }, signal);
+    const turnMessages = messages.filter((m) => m.id > (afterId ?? 0)).sort((a, b) => a.id - b.id);
+    const lastAssistant = turnMessages.findLast((m) => m.role === "assistant");
+    if (!lastAssistant) return [];
+    const handled = /* @__PURE__ */ new Set();
+    for (const message of turnMessages) {
+      if (message.id <= lastAssistant.id) continue;
+      for (const part of message.content ?? []) {
+        if (part.type === "tool-result" && part.tool_call_id) handled.add(part.tool_call_id);
+      }
+    }
+    const toolCalls = [];
+    for (const part of lastAssistant.content ?? []) {
+      if (part.type !== "tool-call" || part.provider_executed) continue;
+      if (!part.tool_call_id || !part.tool_name) continue;
+      if (!dynamicNames.has(part.tool_name)) continue;
+      if (handled.has(part.tool_call_id)) continue;
+      if (this.#submittedToolCallIds.has(part.tool_call_id)) continue;
+      toolCalls.push({
+        tool_call_id: part.tool_call_id,
+        tool_name: part.tool_name,
+        // `action_required` carries args as their raw JSON text (chatd sends
+        // `string(part.Args)` of the history part's json.RawMessage);
+        // re-encoding the snapshot's parsed JSON value reconstructs it. A
+        // JSON `null` is a legitimate argument value and must survive; only
+        // an ABSENT args field falls back to empty-object args.
+        args: JSON.stringify(part.args === void 0 ? {} : part.args)
+      });
+    }
+    if (toolCalls.length === 0) return [];
+    const events = turnMessages.map((message) => ({
+      type: "message",
+      chat_id: chatId,
+      message
+    }));
+    events.push({
+      type: "action_required",
+      chat_id: chatId,
+      action_required: { tool_calls: toolCalls }
+    });
+    return events;
+  }
   async *#runTurn(options) {
     if (this.#inFlight) {
       throw new CoderAgentError(
@@ -1332,9 +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(() => {
@@ -1371,6 +1764,9 @@ var CoderLanguageModel = class {
         );
       }
       let afterId;
+      let turnCreatedChat = false;
+      let uploadedAttachment = false;
+      let chatHasWorkspace = Boolean(this.#config.workspaceId);
       if (this.#chatId && this.#lastSeenMessageId === 0) {
         const { messages } = await this.#config.client.getMessages(
           this.#chatId,
@@ -1382,7 +1778,9 @@ var CoderLanguageModel = class {
       if (action.kind === "new-turn") {
         const [modelConfigId, content] = await Promise.all([
           this.#resolveModelConfigId(signal),
-          this.#buildContent(action.content, signal)
+          this.#buildContent(action.content, signal, () => {
+            uploadedAttachment = true;
+          })
         ]);
         if (!this.#chatId) {
           const req = {
@@ -1400,6 +1798,8 @@ var CoderLanguageModel = class {
           if (this.#config.planMode) req.plan_mode = this.#config.planMode;
           const chat = await this.#config.client.createChat(req, signal);
           this.#chatId = chat.id;
+          turnCreatedChat = true;
+          if (chat.workspace_id) chatHasWorkspace = true;
           afterId = this.#lastSeenMessageId > 0 ? this.#lastSeenMessageId : void 0;
         } else {
           const resp = await this.#config.client.createChatMessage(
@@ -1425,14 +1825,79 @@ var CoderLanguageModel = class {
         afterId = this.#lastSeenMessageId;
       }
       const chatId = this.#chatId;
+      turnChatId = chatId;
+      const dynamicNames = dynamicToolNames(options.tools);
       translator = new TurnTranslator({
-        dynamicToolNames: dynamicToolNames(options.tools),
-        turnCursor: afterId ?? 0
+        dynamicToolNames: dynamicNames,
+        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.#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 {
-        for await (const ev of this.#config.client.streamEvents(chatId, { afterId, signal })) {
-          for (const part of translator.ingest(ev)) yield part;
+        for (; ; ) {
+          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);
+            raced = await raceSegment(Promise.race([next, grace.expired]));
+            if (raced === GRACE_EXPIRED) {
+              recoveryAttempted = true;
+              throwIfAborted();
+              recoveryAbort = new AbortController();
+              recovery = this.#recoverRequiresAction(
+                chatId,
+                dynamicNames,
+                afterId,
+                signal ? AbortSignal.any([signal, recoveryAbort.signal]) : recoveryAbort.signal
+              ).catch(() => []);
+              continue;
+            }
+          } else if (awaitingActionRequired && 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) break;
+              continue;
+            }
+          } else {
+            raced = await raceSegment(next);
+          }
+          if (raced === SEGMENT_ABORTED) {
+            throwIfAborted();
+            throw new CoderAgentError("segment abort sentinel resolved without an abort");
+          }
+          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;
@@ -1440,8 +1905,22 @@ 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) {
+          if (turnCreatedChat) {
+            discardSession = true;
+          }
+          const effectful = chatHasWorkspace || Boolean(this.#config.mcpServerIds?.length) || uploadedAttachment;
+          if (turnCreatedChat && !effectful) throw err;
+          throw new CoderStreamError({
+            message: `${err.message}; automatic retry is disabled because ${turnCreatedChat ? "the turn has server-side effects a replay would repeat (workspace/MCP tools that may have executed, or freshly uploaded attachments)" : "the chat has prior state (a retry would resubmit this turn's prompt as a new user turn)"}`,
+            url: err.url,
+            cause: err,
+            isRetryable: false
+          });
+        }
         if (err instanceof CoderAgentError && !(err instanceof CoderApiError) && !(err instanceof CoderChatError)) {
           throw new CoderChatError({
             message: `Coder chat stream failed mid-turn: ${err.message}`,
@@ -1450,6 +1929,15 @@ var CoderLanguageModel = class {
           });
         }
         throw err;
+      } finally {
+        grace?.cancel();
+        recoveryAbort?.abort();
+        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) {
@@ -1468,6 +1956,12 @@ 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;
     }
   }
@@ -1716,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).
@@ -1730,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,
@@ -1753,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 });
@@ -1793,7 +2294,7 @@ var CoderAgent = class {
   async uploadToWorkspace(file) {
     if (!this.#workspaceFiles) {
       throw new CoderAgentError(
-        "uploadToWorkspace requires a `workspaceFiles` adapter. Construct the agent with `workspaceFiles` (e.g. backed by a @coder/ai-sdk-eve-sandbox session) to enable it."
+        "uploadToWorkspace requires a `workspaceFiles` adapter. Construct the agent with `workspaceFiles` (e.g. backed by a @coder/ai-sdk-sandbox workspace session) to enable it."
       );
     }
     const { path } = await this.#workspaceFiles.write({
@@ -1964,7 +2465,9 @@ export {
   CoderChatClient,
   CoderChatError,
   CoderLanguageModel,
+  CoderStreamError,
   MAX_CHAT_FILE_SIZE_BYTES,
+  TERMINAL_STATUSES,
   TurnTranslator,
   chatMessagesToUIMessages,
   classifyTurnAction,