@coder/ai-sdk-agent 0.9.0 → 0.9.2

package/dist/index.js

@@ -824,6 +824,23 @@ var CoderChatClient = class {
       opts?.signal
     );
   }
+  /**
+   * Withdraw a QUEUED (not yet materialized) message from the chat's
+   * submission queue (`DELETE /queue/{id}`). `queuedMessageId` is the
+   * queue-entry id from `CreateChatMessageResponse.queued_message` — a
+   * different id space from committed chat message ids. Rejects with a
+   * {@link CoderApiError}: 404 when the entry no longer exists (already
+   * promoted into history, or deleted), 409 when the chat has no queue.
+   */
+  deleteQueuedMessage(chatId, queuedMessageId, signal) {
+    return this.#request(
+      "deleteQueuedMessage",
+      "DELETE",
+      `${API_PREFIX}/${chatId}/queue/${queuedMessageId}`,
+      void 0,
+      signal
+    );
+  }
   updateChat(chatId, req, signal) {
     return this.#request("updateChat", "PATCH", `${API_PREFIX}/${chatId}`, req, signal);
   }
@@ -1348,6 +1365,16 @@ function joinContent(content, kind) {
   for (const p of content) if (p.type === kind) full += p.text ?? "";
   return full;
 }
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value);
+    entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    const body = entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`);
+    return `{${body.join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
 var TurnTranslator = class {
   #dynamicToolNames;
   #submittedToolCallIds;
@@ -1398,13 +1425,30 @@ var TurnTranslator = class {
    * to a segment that already streamed) — they arrive only as replays: the
    * initial sync when resuming a chat, or a mid-turn `history_reset` re-send
    * of the full history. Ingest skips them entirely so a replay can neither
-   * re-emit earlier turns' content nor inflate this turn's usage.
+   * re-emit earlier turns' content nor inflate this turn's usage. Mutable for
+   * exactly one transition: a QUEUED submission starts at the pre-turn cursor
+   * and advances to the materialized user message's id when the gate anchors
+   * (see {@link QueuedSubmissionGate}) — replayed pre-anchor tail messages
+   * then stay filtered on every redial, which reuses the turn's ORIGINAL
+   * `after_id` and therefore re-delivers them.
    */
   #turnCursor;
+  /** The queued-submission attribution gate; undefined once anchored (#114). */
+  #queuedGate;
   constructor(opts) {
     this.#dynamicToolNames = opts.dynamicToolNames;
     this.#turnCursor = opts.turnCursor ?? 0;
     this.#submittedToolCallIds = opts.submittedToolCallIds ?? /* @__PURE__ */ new Set();
+    const queued = opts.queuedSubmission;
+    if (queued) {
+      this.#queuedGate = {
+        queuedId: queued.id,
+        expected: queued.content !== void 0 ? canonicalJson(queued.content) : void 0,
+        candidateId: void 0,
+        buffered: [],
+        deadEnd: void 0
+      };
+    }
   }
   get terminalStatus() {
     return this.#terminalStatus;
@@ -1419,6 +1463,32 @@ var TurnTranslator = class {
   get error() {
     return this.#error;
   }
+  /**
+   * The turn's EFFECTIVE attribution cursor: the constructor's `turnCursor`
+   * until a queued submission anchors, the materialized user message's id
+   * after. Distinct from the stream's redial cursor, which deliberately stays
+   * the turn's original `after_id` (see `streamChatEvents`).
+   */
+  get turnCursor() {
+    return this.#turnCursor;
+  }
+  /**
+   * Whether a queued submission is still awaiting its own user-message
+   * snapshot (#114). While true, nothing is attributed to this turn — no
+   * content, usage, tool calls, or settle statuses — because the stream
+   * window still belongs to the chat's concurrent run.
+   */
+  get awaitingQueuedSubmission() {
+    return this.#queuedGate !== void 0;
+  }
+  /**
+   * Set when a queued submission's wait can never complete (see
+   * {@link QueuedSubmissionGate}); the model layer throws it so the turn
+   * fails fast instead of hanging until timeout/abort.
+   */
+  get queuedSubmissionDeadEnd() {
+    return this.#queuedGate?.deadEnd;
+  }
   // --- block helpers --------------------------------------------------------
   #openText(out) {
     if (this.#reasoning.id) this.#closeReasoning(out);
@@ -1561,6 +1631,8 @@ var TurnTranslator = class {
   }
   // --- ingest ---------------------------------------------------------------
   ingest(ev) {
+    const gate = this.#queuedGate;
+    if (gate) return this.#ingestGated(gate, ev);
     const out = [];
     switch (ev.type) {
       case "message_part":
@@ -1609,6 +1681,82 @@ var TurnTranslator = class {
     }
     return out;
   }
+  /**
+   * Ingest while the queued-submission gate is up (#114): the stream window
+   * still belongs to the chat's concurrent run, so nothing is attributed —
+   * this only advances cursor bookkeeping, runs the anchor correlation
+   * protocol (see {@link QueuedSubmissionGate}), and detects dead ends.
+   * Returns parts only at the anchoring transition, when buffered snapshots
+   * of this turn's own already-committed messages are replayed through the
+   * normal path.
+   */
+  #ingestGated(gate, ev) {
+    switch (ev.type) {
+      case "message": {
+        const message = ev.message;
+        if (!message) break;
+        if (message.id > this.#maxMessageId) this.#maxMessageId = message.id;
+        if (message.id <= this.#turnCursor) break;
+        if (message.role === "user" && this.#matchesQueuedContent(gate, message)) {
+          if (gate.queuedId === void 0) return this.#anchorQueuedTurn(message.id);
+          gate.candidateId = message.id;
+          gate.buffered = [];
+        } else if (gate.candidateId !== void 0) {
+          gate.buffered.push(message);
+        }
+        break;
+      }
+      case "queue_update": {
+        if (gate.queuedId === void 0) break;
+        const queue = ev.queued_messages ?? [];
+        if (queue.some((entry) => entry.id === gate.queuedId)) {
+          gate.candidateId = void 0;
+          gate.buffered = [];
+          break;
+        }
+        if (gate.candidateId !== void 0) {
+          const buffered = gate.buffered;
+          const out = this.#anchorQueuedTurn(gate.candidateId);
+          for (const message of buffered) this.#ingestMessage(out, message);
+          return out;
+        }
+        gate.deadEnd = {
+          message: "The queued submission left the chat's queue without materializing as this turn's user message (deleted externally, or its materialized form could not be correlated); this turn never started.",
+          kind: "queued_submission_lost",
+          retryable: false
+        };
+        break;
+      }
+      case "error": {
+        if (!ev.error) break;
+        gate.deadEnd = {
+          message: "The chat's active run failed while this turn's submission was queued behind it; the queued message never materialized, so this turn never started.",
+          detail: ev.error.detail ? `${ev.error.message}: ${ev.error.detail}` : ev.error.message,
+          kind: "queued_submission_lost",
+          retryable: false
+        };
+        break;
+      }
+      default:
+        break;
+    }
+    return [];
+  }
+  /** Whether a user-message snapshot's content matches the queued entry's. */
+  #matchesQueuedContent(gate, message) {
+    if (gate.expected === void 0) return true;
+    return canonicalJson(message.content ?? []) === gate.expected;
+  }
+  /**
+   * Opens the turn's attribution window at `anchorId` — this turn's own user
+   * message — and drops the gate. Replays of the pre-anchor tail (redials
+   * reuse the turn's ORIGINAL cursor) stay filtered by the advanced cursor.
+   */
+  #anchorQueuedTurn(anchorId) {
+    this.#turnCursor = anchorId;
+    this.#queuedGate = void 0;
+    return [];
+  }
   #ingestMessagePart(out, ev) {
     const mp = ev.message_part;
     if (!mp || mp.role !== "assistant" && mp.role !== "tool") return;
@@ -1823,11 +1971,36 @@ var CoderLanguageModel = class {
     this.modelId = config.model ?? "chatd";
     this.#chatId = config.chatId;
     this.#lastKnownChatId = config.chatId;
+    if (config.lastSeenMessageId !== void 0) {
+      if (!Number.isSafeInteger(config.lastSeenMessageId) || config.lastSeenMessageId <= 0) {
+        throw new CoderAgentError(
+          `lastSeenMessageId must be a positive integer (got ${config.lastSeenMessageId}); persist the value of the lastSeenMessageId getter and supply it verbatim.`
+        );
+      }
+      if (!config.chatId) {
+        throw new CoderAgentError(
+          "lastSeenMessageId requires chatId: a resume cursor is meaningless without the chat it belongs to."
+        );
+      }
+      this.#lastSeenMessageId = config.lastSeenMessageId;
+    }
     this.#emitTransportEvent = safeTransportEmitter(config.onTransportEvent);
   }
   get chatId() {
     return this.#chatId;
   }
+  /**
+   * The resume cursor: the newest chat message id this session has observed,
+   * or `undefined` before any turn has streamed (nothing to persist then —
+   * a fresh instance seeds from history instead). Persist it alongside
+   * {@link chatId} once a turn settles and supply both to a future instance
+   * ({@link CoderLanguageModelConfig.lastSeenMessageId}) to skip the resumed
+   * turn's pre-prompt seed GET. Read it between turns, not mid-generation:
+   * the cursor advances when a segment ends.
+   */
+  get lastSeenMessageId() {
+    return this.#lastSeenMessageId > 0 ? this.#lastSeenMessageId : void 0;
+  }
   /**
    * The last chat id this model created or attached to, for CLEANUP targeting
    * only — generation always targets {@link chatId}. It survives
@@ -1981,9 +2154,9 @@ var CoderLanguageModel = class {
    * pending calls — nothing to recover, the caller keeps waiting on the
    * stream, bounded by `requestTimeoutMs`/abort.
    */
-  async #recoverRequiresAction(chatId, dynamicNames, afterId, signal) {
+  async #recoverRequiresAction(chatId, dynamicNames, turnCursor, 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 turnMessages = messages.filter((m) => m.id > turnCursor).sort((a, b) => a.id - b.id);
     const lastAssistant = turnMessages.findLast((m) => m.role === "assistant");
     if (!lastAssistant) return [];
     const handled = /* @__PURE__ */ new Set();
@@ -2137,10 +2310,20 @@ var CoderLanguageModel = class {
     let discardSession = false;
     let interruptSent = false;
     let turnChatId;
+    let queuedTurn = false;
+    let queuedEntry;
     const interrupt = () => {
       const id = turnChatId ?? this.#chatId;
       if (interruptSent || !id) return;
       interruptSent = true;
+      if (queuedTurn && (translator === void 0 || translator.awaitingQueuedSubmission)) {
+        const entryId = queuedEntry?.id;
+        if (entryId !== void 0) {
+          void this.#config.client.deleteQueuedMessage(id, entryId).catch(() => {
+          });
+        }
+        return;
+      }
       void this.#config.client.interruptChat(id).catch(() => {
       });
     };
@@ -2224,7 +2407,15 @@ var CoderLanguageModel = class {
             },
             signal
           );
-          afterId = resp.message?.id ?? this.#lastSeenMessageId;
+          if (resp.message) {
+            afterId = resp.message.id;
+          } else if (resp.queued) {
+            afterId = this.#lastSeenMessageId;
+            queuedTurn = true;
+            queuedEntry = resp.queued_message;
+          } else {
+            afterId = this.#lastSeenMessageId;
+          }
         }
       } else {
         if (!this.#chatId)
@@ -2243,14 +2434,21 @@ var CoderLanguageModel = class {
       this.#lastKnownChatId = chatId;
       if (segmentChat) segmentChat.chatId = chatId;
       const dynamicNames = dynamicToolNames(options.tools);
-      translator = new TurnTranslator({
+      const translatorOptions = {
         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
-      });
+      };
+      if (queuedTurn) {
+        const queuedSubmission = {};
+        if (queuedEntry?.id !== void 0) queuedSubmission.id = queuedEntry.id;
+        if (queuedEntry?.content !== void 0) queuedSubmission.content = queuedEntry.content;
+        translatorOptions.queuedSubmission = queuedSubmission;
+      }
+      translator = new TurnTranslator(translatorOptions);
       let sinceRequiresAction = 0;
       let grace;
       let recovery;
@@ -2291,7 +2489,11 @@ var CoderLanguageModel = class {
               recovery = this.#recoverRequiresAction(
                 chatId,
                 dynamicNames,
-                afterId,
+                // The turn's EFFECTIVE cursor: for a queued submission it has
+                // advanced past the materialized user message (a pause can
+                // only arm after the gate anchored), so the derivation never
+                // sees the concurrent predecessor run's tail (#114).
+                translator.turnCursor,
                 signal ? AbortSignal.any([signal, recoveryAbort.signal]) : recoveryAbort.signal
               ).catch(() => []);
               continue;
@@ -2315,6 +2517,8 @@ var CoderLanguageModel = class {
           stream.consumed(next);
           if (raced.done) break;
           const parts = translator.ingest(raced.value);
+          const deadEnd = translator.queuedSubmissionDeadEnd;
+          if (deadEnd) throw new CoderChatError(deadEnd);
           if (raced.value.type === "error" && translator.error && !translator.terminalStatus) {
             const peek = stream.read();
             const bound = startGraceTimer(0);
@@ -2604,6 +2808,7 @@ var CoderAgent = class {
       mcpServerIds: settings.mcpServerIds,
       planMode: settings.planMode,
       chatId: settings.chatId,
+      lastSeenMessageId: settings.lastSeenMessageId,
       requestTimeoutMs: settings.requestTimeoutMs,
       onTransportEvent: settings.onTransportEvent
     });
@@ -2632,6 +2837,16 @@ var CoderAgent = class {
   get chatId() {
     return this.#model.chatId;
   }
+  /**
+   * The session's resume cursor: the newest chat message id observed, or
+   * `undefined` before any turn has streamed. Persist it alongside
+   * {@link chatId} when a turn ends and supply both to a future instance
+   * ({@link CoderAgentSettings.lastSeenMessageId}) to skip the resumed turn's
+   * pre-prompt seed GET. Read it between turns, not mid-generation.
+   */
+  get lastSeenMessageId() {
+    return this.#model.lastSeenMessageId;
+  }
   /**
    * The last chat id this agent created or attached to, retained for CLEANUP
    * even after the session was dropped — a fresh-chat stream failure discards