cartethyia 2.7.9 → 2.8.0

package/src/protocol/markup-stream-parser.ts

@@ -0,0 +1,195 @@
+/**
+ * Generic streaming prefix-buffer parser for in-band tool-call markup.
+ *
+ * Three grammars (DSML blocks, OMP `<tool_calls:8hex>` envelopes, Qwen
+ * `<tool_call>` JSON blocks) share one stateful loop: append chunks to a
+ * pending buffer, scan for the earliest opener, settle visible text up to a
+ * safe end that holds back a possible trailing opener fragment, parse a
+ * complete block when its closer appears, fail open past a block-size cap, and
+ * flush the tail. The grammar-specific parts are supplied as configuration:
+ * opener strings, an opener classifier (some grammars must validate beyond the
+ * bare prefix, e.g. OMP's hex marker), closer/parse functions, an unclosed
+ * block policy (hold vs fail-open pass-through), a flush policy (pass through
+ * vs discard an unterminated envelope), and a call-id factory. Each parser
+ * instance keeps its own buffer; nothing is shared.
+ */
+
+/** Result of one push/flush pass: text that settled plus recovered calls. */
+export interface MarkupStreamParseResult<Call extends { readonly id: string }> {
+  readonly text: string;
+  readonly calls: readonly Call[];
+}
+
+/** Raw call shape produced by a grammar's block parser, without its id. */
+export type MarkupRawCall<Call extends { readonly id: string }> = Omit<Call, "id">;
+
+/** Builds a complete call (id included) from a parsed raw call. */
+export type MarkupCallFactory<Call extends { readonly id: string }> = (
+  call: MarkupRawCall<Call>,
+  index: number,
+  seq: number,
+) => Call;
+
+/** Classification of one opener candidate occurrence. */
+export type MarkupOpenerClassification<Call extends { readonly id: string }> =
+  | {
+      /**
+       * The candidate may be the start of a real opener (e.g. a partial hex
+       * marker): hold everything from the candidate until a later chunk
+       * completes or disproves it.
+       */
+      readonly kind: "hold";
+    }
+  | {
+      /**
+       * The candidate is definitely not an opener: emit it as literal text
+       * (one character) and rescan after it.
+       */
+      readonly kind: "literal";
+    }
+  | {
+      readonly kind: "found";
+      /** Tag that closes the block opened at this position. */
+      readonly closer: string;
+      /**
+       * Parses one complete block (opener through closer). `undefined` means
+       * the block is not valid markup and is passed through as text verbatim.
+       */
+      readonly parse: (block: string) => readonly MarkupRawCall<Call>[] | undefined;
+      /**
+       * Call factory for the calls recovered from this block; defaults to the
+       * parser-level `callId`. Some grammars derive ids from block-local state
+       * (e.g. OMP embeds the envelope marker).
+       */
+      readonly callId?: MarkupCallFactory<Call>;
+    };
+
+export interface MarkupStreamParserOptions<Call extends { readonly id: string }> {
+  /**
+   * Opener frontier. The earliest occurrence wins; trailing fragments that
+   * could start one are held back from settled text.
+   */
+  readonly openers: readonly string[];
+  /** Classifies an opener candidate found at a scan position. */
+  readonly classifyOpener: (
+    pending: string,
+    index: number,
+    opener: string,
+  ) => MarkupOpenerClassification<Call>;
+  /**
+   * Policy when a block's closer has not arrived yet. Default `"hold"`: keep
+   * the whole pending buffer from the opener until a later chunk completes or
+   * disproves the block. Returning `{ kind: "passThrough" }` fails open:
+   * everything from the opener is emitted as text immediately (the DSML
+   * block-size cap).
+   */
+  readonly onUnclosed?: (
+    pending: string,
+    openIndex: number,
+  ) => "hold" | { readonly kind: "passThrough" };
+  /**
+   * Tail policy at flush. Returns the text to emit for whatever remains in the
+   * buffer (default: everything, i.e. pass through). A grammar that discards
+   * unterminated envelopes returns `""` when the tail looks like an opener.
+   */
+  readonly flush?: (pending: string) => string;
+  /** Call factory for recovered calls, unless a block overrides it. */
+  readonly callId?: MarkupCallFactory<Call>;
+}
+
+export class MarkupStreamParser<Call extends { readonly id: string }> {
+  readonly #options: MarkupStreamParserOptions<Call>;
+  #pending = "";
+  #callSequence = 0;
+
+  constructor(options: MarkupStreamParserOptions<Call>) {
+    this.#options = options;
+  }
+
+  /** Feeds one chunk and returns only settled text and complete calls. */
+  push(chunk: string): MarkupStreamParseResult<Call> {
+    this.#pending += chunk;
+    let cursor = 0;
+    let visible = "";
+    const calls: Call[] = [];
+    for (;;) {
+      let openIndex = -1;
+      let opener = "";
+      for (const candidate of this.#options.openers) {
+        const index = this.#pending.indexOf(candidate, cursor);
+        if (index >= 0 && (openIndex < 0 || index < openIndex)) {
+          openIndex = index;
+          opener = candidate;
+        }
+      }
+      if (openIndex < 0) {
+        const safeEnd = this.#settledEnd(cursor);
+        visible += this.#pending.slice(cursor, safeEnd);
+        cursor = safeEnd;
+        break;
+      }
+      visible += this.#pending.slice(cursor, openIndex);
+      const classified = this.#options.classifyOpener(this.#pending, openIndex, opener);
+      if (classified.kind === "literal") {
+        visible += "<";
+        cursor = openIndex + 1;
+        continue;
+      }
+      if (classified.kind === "hold") {
+        cursor = openIndex;
+        break;
+      }
+      const closeIndex = this.#pending.indexOf(classified.closer, openIndex + opener.length);
+      if (closeIndex < 0) {
+        const decision = this.#options.onUnclosed?.(this.#pending, openIndex) ?? "hold";
+        if (decision === "hold") {
+          cursor = openIndex;
+          break;
+        }
+        visible += this.#pending.slice(openIndex);
+        cursor = this.#pending.length;
+        break;
+      }
+      const end = closeIndex + classified.closer.length;
+      const block = this.#pending.slice(openIndex, end);
+      const parsed = classified.parse(block);
+      if (parsed === undefined) {
+        visible += block;
+      } else {
+        const callFor = classified.callId ?? this.#options.callId;
+        if (callFor === undefined) {
+          throw new Error("MarkupStreamParser: no call factory configured");
+        }
+        parsed.forEach((call, index) => {
+          calls.push(callFor(call, index, this.#callSequence++));
+        });
+      }
+      cursor = end;
+    }
+    this.#pending = this.#pending.slice(cursor);
+    return { text: visible, calls };
+  }
+
+  /** Settles trailing text per the configured flush policy. */
+  flush(): MarkupStreamParseResult<Call> {
+    const text = this.#options.flush?.(this.#pending) ?? this.#pending;
+    this.#pending = "";
+    return { text, calls: [] };
+  }
+
+  /** Holds back a trailing fragment that could be the start of an opener. */
+  #settledEnd(start: number): number {
+    const remaining = this.#pending.slice(start);
+    const maxOpener = this.#options.openers.reduce(
+      (max, open) => Math.max(max, open.length - 1),
+      0,
+    );
+    for (let length = Math.min(maxOpener, remaining.length); length > 0; length -= 1) {
+      const suffix = remaining.slice(-length);
+      if (this.#options.openers.some((open) => open.startsWith(suffix))) {
+        return this.#pending.length - length;
+      }
+    }
+    return this.#pending.length;
+  }
+}

package/src/protocol/reasoning-text.ts

@@ -28,3 +28,22 @@ export function reasoningTextOf(part: ReasoningTextSource): string | undefined {
   if (typeof summary === "string" && summary.length > 0) return summary;
   return undefined;
 }
+
+/**
+ * The one reader for reasoning text replayed to upstream providers.
+ *
+ * Request builders echo the previous turn's reasoning back to a provider, and
+ * they deliberately prefer `summary` (the digest) ahead of `payload` (the
+ * stream) — the opposite of `reasoningTextOf`, which is for display. Returning
+ * `undefined` when neither field is a string lets each call site keep its exact
+ * fallback ("" for the chat/messages/gemini builders, the raw payload for
+ * Qoder's echo), so upstream-visible bytes do not change. Opaque parts are not
+ * special-cased here: the replay readers never consulted `opaque` either.
+ */
+export function reasoningTextForReplay(part: ReasoningTextSource): string | undefined {
+  const summary = part.summary;
+  if (typeof summary === "string") return summary;
+  const payload = part.payload;
+  if (typeof payload === "string") return payload;
+  return undefined;
+}

package/src/protocol/request/chat.ts

@@ -16,6 +16,7 @@ import { clampThinkingLevelForModel } from "../../protocol/translation/dialect/m
 import { isClaudeBillingHeaderText, resolveImageSource } from "../codecs";
 import { resolvePromptCacheKey } from "../../providers/operations/session-resolution";
 import { reasoningEffortFromIntent } from "../../protocol/reasoning";
+import { reasoningTextForReplay } from "../reasoning-text";
 import { parseChatResponseToEvents, decodeChatSseStream } from "../response/chat";
 
 /** Fallback when no resolved policy is supplied — today's exact behavior. */
@@ -220,6 +221,13 @@ export function canonicalToChatPayload(
     }
   }
   for (const m of request.messages) {
+    // Reasoning parts and their presence are computed once per message and
+    // shared by every branch below; the presence gate is on the *existence* of
+    // a reasoning part, not on non-empty text (see the comment at the first use).
+    const reasoningParts = m.content.filter(
+      (c): c is Extract<typeof c, { kind: "reasoning" }> => c.kind === "reasoning",
+    );
+    const hasReasoning = reasoningParts.length > 0;
     if (m.role === "assistant" && m.content.some((c) => c.kind === "toolCall")) {
       const toolCalls = m.content
         .filter((c): c is Extract<typeof c, { kind: "toolCall" }> => c.kind === "toolCall")
@@ -251,16 +259,12 @@ export function canonicalToChatPayload(
       // thinking mode" (CodeBuddy 400). Chat Completions has no
       // reasoning content part, so it travels in the provider-native
       // `reasoning_content` side channel, same as the branches below.
-      const reasoningContent = m.content
-        .filter((c): c is Extract<typeof c, { kind: "reasoning" }> => c.kind === "reasoning")
-        .map((c) => c.summary ?? (typeof c.payload === "string" ? c.payload : ""))
-        .join("\n");
+      const reasoningContent = reasoningParts.map((c) => reasoningTextForReplay(c) ?? "").join("\n");
       // Gated on the *presence* of a reasoning part, not on non-empty text:
       // with `display: "omitted"` the provider emits a thinking block whose
       // text is empty but whose signature marks the turn as a thinking turn,
       // and the upstream still demands the field back. Omitting it there
       // reproduces the same 400, so an empty string is the correct value.
-      const hasReasoning = m.content.some((c) => c.kind === "reasoning");
       messages.push({
         role: "assistant",
         content: effectiveContent,
@@ -295,13 +299,9 @@ export function canonicalToChatPayload(
           content: p.is_error === true ? `[tool_error] ${resultContent}` : resultContent,
         });
       }
-      const reasoningContent = m.content
-        .filter((c): c is Extract<typeof c, { kind: "reasoning" }> => c.kind === "reasoning")
-        .map((c) => c.summary ?? (typeof c.payload === "string" ? c.payload : ""))
-        .join("\n");
+      const reasoningContent = reasoningParts.map((c) => reasoningTextForReplay(c) ?? "").join("\n");
       // Presence, not length: an `omitted`-display thinking block carries an
       // empty text with a signature, and the field is still required back.
-      const hasReasoning = m.content.some((c) => c.kind === "reasoning");
       const hasRichContent = m.content.some(
         (c) => c.kind === "image" || c.kind === "file" || c.kind === "audio" || c.kind === "document",
       );

package/src/protocol/request/gemini.ts

@@ -15,6 +15,7 @@ import {
   type RewriteWalk,
 } from "../codecs";
 import { geminiThinkingOutputFloor } from "../../protocol/reasoning";
+import { reasoningTextForReplay } from "../reasoning-text";
 import { base64DecodedByteLength, clampImage } from "../image-clamp";
 
 export function geminiModelUrl(base: string, model: string, action: string): string {
@@ -151,8 +152,13 @@ function toGeminiPart(
 ): Record<string, unknown>[] {
   if (part.kind === "text") return [{ text: part.text }];
   if (part.kind === "reasoning") {
-    const summary = part.summary ?? (typeof part.payload === "string" ? part.payload : "");
-    return [{ text: summary, thought: true, ...(part.signature ? { thoughtSignature: part.signature } : {}) }];
+    // A `thinking` part must carry a non-empty signature, or Gemini-family
+    // upstreams reject the whole request with `400 ... thinking.signature:
+    // Field required`. Drop unsigned reasoning blocks (missing *or* empty
+    // signature) so the conversation replays cleanly.
+    if (typeof part.signature !== "string" || part.signature.length === 0) return [];
+    const summary = reasoningTextForReplay(part) ?? "";
+    return [{ text: summary, thought: true, thoughtSignature: part.signature }];
   }
   if (part.kind === "image") {
     // Resolution goes through the shared `resolveImageSource` primitive rather

package/src/protocol/request/messages.ts

@@ -27,6 +27,7 @@ import {
   splitDataUrl,
   finiteNumber,
 } from "../codecs";
+import { reasoningTextForReplay } from "../reasoning-text";
 import { log } from "../../observability/logger";
 import { base64DecodedByteLength, clampImage } from "../image-clamp";
 import { LEVEL_TO_BUDGET } from "../../protocol/translation/thinking";
@@ -374,7 +375,7 @@ function partToClaudeBlock(
         !part.opaque &&
         (typeof part.signature !== "string" || part.signature.trim().length === 0)
       ) {
-        const text = part.summary ?? (stringValue(part.payload) ? part.payload : "");
+        const text = reasoningTextForReplay(part) ?? "";
         return text.length > 0 ? { type: "text", text: toWellFormedString(text) } : undefined;
       }
       if (part.opaque) {
@@ -384,9 +385,7 @@ function partToClaudeBlock(
       }
       return {
         type: "thinking",
-        thinking: toWellFormedString(
-          part.summary ?? (stringValue(part.payload) ? part.payload : ""),
-        ),
+        thinking: toWellFormedString(reasoningTextForReplay(part) ?? ""),
         ...(part.signature === undefined
           ? {}
           : { signature: toWellFormedString(part.signature) }),

package/src/protocol/response/chat.ts

@@ -9,7 +9,7 @@ import { gatewayErrorFromStreamError } from "../stream-error-frames";
 import { mergeResponsesUsage } from "./responses";
 import { usageFromProvider, readReasoningText } from "../../providers/provider-usage";
 import { createToolEmitLedger } from "../tool-identity";
-import { ThinkSplitter, stripThinkingTags } from "../think-split";
+import { ThinkingTagStripper, ThinkSplitter, stripThinkingTags } from "../think-split";
 import { DsmlStreamParser, parseDsmlToolCalls } from "../dsml";
 import {
   OmpToolCallMarkupParser,
@@ -267,10 +267,13 @@ export async function* decodeChatSseStream(
   // Single emission ledger: one entry per logical call.
   const ledger = createToolEmitLedger();
   const think = new ThinkSplitter();
-  // Separate splitter for the reasoning channel: `reasoning_content` is its own
+  // Separate stripper for the reasoning channel: `reasoning_content` is its own
   // stream, and interleaving it into the answer splitter would let a tag in one
-  // channel swallow the other's text.
-  const reasoningThink = new ThinkSplitter();
+  // channel swallow the other's text. The reasoning channel is thought in its
+  // entirety — untagged prose included — so it strips paired tags statefully
+  // while preserving source order instead of splitting into text/reasoning
+  // buckets that a `${reasoning}${text}` join would reorder.
+  const reasoningThink = new ThinkingTagStripper();
   const declaredToolNames = declaredToolNamesForRequest(request);
   const callableToolNames = callableToolNamesForRequest(request);
   const contentMarkup =
@@ -364,21 +367,13 @@ export async function* decodeChatSseStream(
           typeof reasoningRaw === "string" ? reasoningMarkup?.push(reasoningRaw) : undefined;
         // Strip stray `<think>` tags the upstream double-wrapped inside its own
         // reasoning stream (buddy's hy4-preview-f leaks them per-delta). This
-        // is the splitter's job, not `stripThinkingTags`'s: a stateless strip
+        // is the stripper's job, not `stripThinkingTags`'s: a stateless strip
         // cannot see a tag split across two deltas, so `"<thi"` was emitted
         // verbatim and only the following `</think>` removed.
-        const reasoningSplit =
+        const reasoningText =
           typeof reasoningRaw === "string"
             ? reasoningThink.push(reasoningMarkupResult?.text ?? reasoningRaw)
             : undefined;
-        // Both sides are reasoning. The splitter routes text outside a
-        // `<think>` span to its `.text` side, but this field is the reasoning
-        // stream in its entirety: untagged prose here is still thought, not
-        // answer. Taking only `.reasoning` dropped every un-tagged delta.
-        const reasoningText =
-          reasoningSplit === undefined
-            ? undefined
-            : `${reasoningSplit.reasoning}${reasoningSplit.text}`;
         if (typeof reasoningText === "string" && reasoningText.length > 0) {
           yield {
             type: "content_delta",
@@ -538,9 +533,7 @@ export async function* decodeChatSseStream(
   }
   const reasoningMarkupTail = reasoningMarkup?.flush();
   if (reasoningMarkupTail?.text) {
-    const split = reasoningThink.push(reasoningMarkupTail.text);
-    // Both sides are reasoning: see the per-delta branch above.
-    const reasoningText = `${split.reasoning}${split.text}`;
+    const reasoningText = reasoningThink.push(reasoningMarkupTail.text);
     if (reasoningText.length > 0) {
       yield {
         type: "content_delta",
@@ -549,10 +542,9 @@ export async function* decodeChatSseStream(
       } as CanonicalEvent;
     }
   }
-  // Release anything the reasoning splitter held for a tag that never
+  // Release anything the reasoning stripper held for a tag that never
   // completed, before `think.flush()` and the terminal.
-  const reasoningRest = reasoningThink.flush();
-  const reasoningTail = `${reasoningRest.reasoning}${reasoningRest.text}`;
+  const reasoningTail = reasoningThink.flush();
   if (reasoningTail.length > 0) {
     yield {
       type: "content_delta",

package/src/protocol/response/omp-tool-call-markup.ts

@@ -7,6 +7,7 @@
  * interpreted. Calls are returned only when their names were declared on the
  * request; an undeclared name is never promoted into executable tool input.
  */
+import { MarkupStreamParser } from "../markup-stream-parser";
 export interface OmpTextToolCall {
   readonly id: string;
   readonly name: string;
@@ -29,77 +30,49 @@ const TOOL_NAME_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_.:-]{0,63}$/;
  * The parser holds a possible envelope across SSE deltas, so a split opening
  * tag, argument tag, or closing tag is never emitted as visible prose. At
  * end-of-stream an unterminated envelope is dropped, not executed or leaked.
+ *
+ * The stateful prefix-buffer loop is the shared {@link MarkupStreamParser}
+ * scaffold; this class supplies the OMP grammar as a thin configuration.
  */
 export class OmpToolCallMarkupParser {
-  readonly #allowedNames: ReadonlySet<string>;
-  #pending = "";
-  #callSequence = 0;
+  readonly #parser: MarkupStreamParser<OmpTextToolCall>;
 
   constructor(allowedNames: ReadonlySet<string>) {
-    this.#allowedNames = allowedNames;
+    this.#parser = new MarkupStreamParser<OmpTextToolCall>({
+      openers: [OPEN_PREFIX],
+      classifyOpener: (pending, openIndex) => {
+        const remainder = pending.slice(openIndex);
+        const opening = OPEN_PATTERN.exec(remainder);
+        if (opening === null || opening[1] === undefined) {
+          if (couldBeOpening(remainder)) return { kind: "hold" };
+          return { kind: "literal" };
+        }
+        const marker = opening[1];
+        const closeTag = `</tool_calls:${marker}>`;
+        return {
+          kind: "found",
+          closer: closeTag,
+          parse: (block) => {
+            const parsed = parseEnvelope(block, marker);
+            if (parsed === undefined) return undefined;
+            if (parsed.some((call) => !allowedNames.has(call.name))) {
+              // A syntactically valid call to an undeclared tool is model
+              // text, not authority to invoke a tool the client did not offer.
+              return undefined;
+            }
+            return parsed;
+          },
+          callId: (call, _index, seq) => ({ ...call, id: `call_omp_${marker}_${seq}` }),
+        };
+      },
+      flush: (pending) =>
+        couldBeOpening(pending) || OPEN_PATTERN.test(pending) ? "" : pending,
+    });
   }
 
   /** Feeds one content or reasoning delta and returns only settled text. */
   push(chunk: string): OmpTextToolCallResult {
-    this.#pending += chunk;
-    let cursor = 0;
-    let text = "";
-    const calls: OmpTextToolCall[] = [];
-
-    for (;;) {
-      const openIndex = this.#pending.indexOf(OPEN_PREFIX, cursor);
-      if (openIndex < 0) {
-        const safeEnd = this.#settledEnd(cursor);
-        text += this.#pending.slice(cursor, safeEnd);
-        cursor = safeEnd;
-        break;
-      }
-
-      text += this.#pending.slice(cursor, openIndex);
-      const remainder = this.#pending.slice(openIndex);
-      const opening = OPEN_PATTERN.exec(remainder);
-      if (opening === null || opening[1] === undefined) {
-        if (this.#couldBeOpening(remainder)) {
-          cursor = openIndex;
-          break;
-        }
-        text += "<";
-        cursor = openIndex + 1;
-        continue;
-      }
-
-      const marker = opening[1];
-      const openTag = opening[0];
-      const closeTag = `</tool_calls:${marker}>`;
-      const closeIndex = this.#pending.indexOf(closeTag, openIndex + openTag.length);
-      if (closeIndex < 0) {
-        cursor = openIndex;
-        break;
-      }
-
-      const envelopeEnd = closeIndex + closeTag.length;
-      const block = this.#pending.slice(openIndex, envelopeEnd);
-      const parsed = parseEnvelope(block, marker);
-      if (parsed === undefined) {
-        text += block;
-      } else if (parsed.some((call) => !this.#allowedNames.has(call.name))) {
-        // A syntactically valid call to an undeclared tool is model text, not
-        // authority to invoke a tool the client did not offer.
-        text += block;
-      } else {
-        for (const call of parsed) {
-          calls.push({
-            id: `call_omp_${marker}_${this.#callSequence++}`,
-            name: call.name,
-            arguments: call.arguments,
-          });
-        }
-      }
-      cursor = envelopeEnd;
-    }
-
-    this.#pending = this.#pending.slice(cursor);
-    return { text, calls };
+    return this.#parser.push(chunk);
   }
 
   /**
@@ -107,31 +80,15 @@ export class OmpToolCallMarkupParser {
    * an unfinished envelope is deliberately discarded rather than leaked.
    */
   flush(): OmpTextToolCallResult {
-    const pending = this.#pending;
-    this.#pending = "";
-    if (this.#couldBeOpening(pending) || OPEN_PATTERN.test(pending)) {
-      return { text: "", calls: [] };
-    }
-    return { text: pending, calls: [] };
-  }
-
-  #settledEnd(start: number): number {
-    const remaining = this.#pending.slice(start);
-    const maxPrefixLength = Math.min(OPEN_PREFIX.length - 1, remaining.length);
-    for (let length = maxPrefixLength; length > 0; length -= 1) {
-      if (OPEN_PREFIX.startsWith(remaining.slice(-length))) {
-        return this.#pending.length - length;
-      }
-    }
-    return this.#pending.length;
+    return this.#parser.flush();
   }
+}
 
-  #couldBeOpening(value: string): boolean {
-    if (value.length < OPEN_PREFIX.length) return OPEN_PREFIX.startsWith(value);
-    if (!value.startsWith(OPEN_PREFIX)) return false;
-    const suffix = value.slice(OPEN_PREFIX.length);
-    return /^[0-9a-f]{0,8}$/.test(suffix) || /^[0-9a-f]{8}$/.test(suffix) && !value.endsWith(">");
-  }
+function couldBeOpening(value: string): boolean {
+  if (value.length < OPEN_PREFIX.length) return OPEN_PREFIX.startsWith(value);
+  if (!value.startsWith(OPEN_PREFIX)) return false;
+  const suffix = value.slice(OPEN_PREFIX.length);
+  return /^[0-9a-f]{0,8}$/.test(suffix) || /^[0-9a-f]{8}$/.test(suffix) && !value.endsWith(">");
 }
 
 /**

package/src/protocol/response/responses.ts

@@ -274,7 +274,16 @@ export function parseResponsesResponseToEvents(
     canonicalTerminal({
       sequenceNumber: events.length + 1,
       responseId: id,
-      state: status === "cancelled" ? "aborted" : status === "failed" ? "failed" : "complete",
+      // `incomplete` maps to `aborted` (not `complete`): the surface encoder
+      // turns `aborted` into `response.incomplete`, while `complete` would
+      // emit `response.completed` for a response the upstream declared
+      // unfinished (max output tokens / content filter).
+      state:
+        status === "cancelled" || status === "incomplete"
+          ? "aborted"
+          : status === "failed"
+            ? "failed"
+            : "complete",
       stopReason: respJsonStopReason,
       providerStopReason: respJsonProviderStopReason,
       usage: usageFromProvider(usage),
@@ -740,8 +749,15 @@ export async function* decodeResponsesSseStream(
   const truncated = status === undefined;
   yield canonicalTerminal({
     sequenceNumber: seq++,
+    // `incomplete` maps to `aborted` (not `complete`): the surface encoder
+    // turns `aborted` into `response.incomplete`, while `complete` would
+    // emit `response.completed` for a stream the upstream declared unfinished.
     state:
-      status === "cancelled" ? "aborted" : status === "failed" || truncated ? "failed" : "complete",
+      status === "cancelled" || status === "incomplete"
+        ? "aborted"
+        : status === "failed" || truncated
+          ? "failed"
+          : "complete",
     stopReason: responsesStopReason,
     providerStopReason: responsesProviderStopReason,
     usage: usageFromProvider(rawUsage),

package/src/protocol/stop-reason.ts

@@ -1,4 +1,4 @@
-import type { CanonicalStopReason } from "./canonical-model";
+import type { CanonicalStopReason, CanonicalTerminalEvent } from "./canonical-model";
 
 /**
  * Canonical stop reason mapped onto each surface's wire vocabulary.
@@ -56,6 +56,28 @@ export function chatFinishReason(reason: CanonicalStopReason | undefined): strin
   return canonicalStopReasonToWire("chat", reason, "stop");
 }
 
+/**
+ * Completion's finish_reason, or `null` when the terminal recorded none.
+ *
+ * Completion inherits chat's wire vocabulary (`length`, `content_filter`,
+ * `stop`) but keeps its own convention: a terminal that is not complete
+ * (failed/aborted) already surfaced its failure elsewhere, so it yields
+ * `null` rather than a stop word, and a complete terminal flattens every
+ * reason other than `length`/`content_filter` to `stop`. The sync adapter and
+ * the streaming encoder both derive through this function so the two halves
+ * of the completion surface cannot drift.
+ */
+export function completionFinishReason(
+  reason: CanonicalStopReason | undefined,
+  state: CanonicalTerminalEvent["state"],
+): string | null {
+  if (state !== "complete") return null;
+  if (reason === "length" || reason === "content_filter") {
+    return canonicalStopReasonToWire("chat", reason, "stop");
+  }
+  return "stop";
+}
+
 /** Messages' stop_reason, or `null` when the terminal recorded none. */
 export function messagesStopReason(reason: CanonicalStopReason | undefined): string | null {
   return reason === undefined ? null : canonicalStopReasonToWire("messages", reason, "end_turn");