cartethyia 2.7.8 → 2.8.0

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/reasoning.ts

@@ -34,7 +34,7 @@ export function applyOpenAIReasoning(payload: Record<string, unknown>, request:
   payload["reasoning_effort"] = effort;
 }
 
-/** Applies the DeepSeek chat contract shared by CodeBuddy and WorkBuddy. */
+/** Applies the DeepSeek chat contract shared by CodeBuddy. */
 export function applyDeepSeekReasoning(payload: Record<string, unknown>): void {
   const model = typeof payload["model"] === "string" ? payload["model"].trim().toLowerCase() : "";
   if (!model.startsWith("deepseek")) return;

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")
@@ -248,19 +256,15 @@ export function canonicalToChatPayload(
       // to be replayed, and the tool-call turn is exactly where a thinking
       // model emits it — dropping it here made the next request fail with
       // "the reasoning content from the previous turn must be passed back in
-      // thinking mode" (WorkBuddy/CodeBuddy 400). Chat Completions has no
+      // 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",
       );
@@ -365,7 +365,7 @@ export function canonicalToChatPayload(
         // nothing left to say: emitting it as an empty-content `user` message
         // right after the tool results breaks strict upstreams (a bare `user`
         // turn between a result and the next assistant turn reads as a broken
-        // tool sequence — WorkBuddy/CodeBuddy `11148`). Fold the leftover
+        // tool sequence — CodeBuddy `11148`). Fold the leftover
         // reasoning into the last tool message's side channel when one was
         // just emitted, and skip the turn otherwise; a turn that still
         // carries text or rich parts emits below as usual.
@@ -382,7 +382,7 @@ export function canonicalToChatPayload(
           // or a non-empty serialised payload. Pushing `{content:"",
           // reasoning_content:""}` is the opposite of load-bearing — the
           // upstream reads it as "thinking mode with the reasoning stripped"
-          // and rejects the whole request (`WorkBuddy/CodeBuddy 11151 "history
+          // and rejects the whole request (`CodeBuddy 11151 "history
           // not found"`). The canonical form that reaches this branch with no
           // trace is an input `reasoning` item whose `summary` was absent and
           // whose `payload` was `null` — a signature-less thinking block
@@ -570,7 +570,7 @@ export function canonicalToChatPayload(
   // Resolved unconditionally, not only when the caller sent a value: the bound
   // table now carries a `defaultMaxTokens` for this wire, and an omitted limit
   // must reach the upstream as a real number. Upstreams that require the field
-  // reject a large prompt whose `max_tokens` is absent outright (WorkBuddy
+  // reject a large prompt whose `max_tokens` is absent outright (CodeBuddy
   // `400 model_param_invalid`, reproduced through the gateway).
   const bounded = resolveWireMaxTokens("chat", { max_tokens: requestedMaxTokens }, {
     ...(options.maxOutputTokens === undefined ? {} : { maxOutputTokens: options.maxOutputTokens }),

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";
@@ -39,7 +40,7 @@ import { claudeResponseToEvents, parseClaudeSseStream } from "../response/messag
  * Gateway default when the caller sent no max_tokens (Anthropic requires
  * the field). Explicit and warned at the call site — never silent.
  */
-const ANTHROPIC_DEFAULT_MAX_TOKENS = WIRE_TOKEN_BOUNDS["messages"]?.defaultMaxTokens ?? 4_096;
+export const ANTHROPIC_DEFAULT_MAX_TOKENS = WIRE_TOKEN_BOUNDS["messages"]?.defaultMaxTokens ?? 4_096;
 
 /** Anthropic Messages' documented base64-image media-type allowlist. */
 const ANTHROPIC_IMAGE_MEDIA_TYPES = new Set([
@@ -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/gemini.ts

@@ -38,15 +38,20 @@ export function responseParts(parts: readonly Record<string, unknown>[]): {
   readonly text: string;
   readonly calls: readonly { readonly id: string; readonly name: string; readonly args: Record<string, unknown> }[];
   readonly thought: string;
+  readonly thoughtSignature: string;
 } {
   const text: string[] = [];
   const thought: string[] = [];
+  let thoughtSignature = "";
   const calls: Array<{ id: string; name: string; args: Record<string, unknown> }> = [];
   let callIndex = 0;
   for (const part of parts) {
     if (typeof part["text"] === "string") {
       if (part["thought"] === true) {
         thought.push(part["text"] as string);
+        if (thoughtSignature.length === 0 && typeof part["thoughtSignature"] === "string") {
+          thoughtSignature = part["thoughtSignature"] as string;
+        }
       } else text.push(part["text"] as string);
     }
     if (isRecord(part["functionCall"]) && typeof (part["functionCall"] as Record<string, unknown>)["name"] === "string") {
@@ -58,7 +63,7 @@ export function responseParts(parts: readonly Record<string, unknown>[]): {
       });
     }
   }
-  return { text: text.join(""), calls, thought: thought.join("") };
+  return { text: text.join(""), calls, thought: thought.join(""), thoughtSignature };
 }
 
 export function mapGeminiUsage(body: Record<string, unknown>): Record<string, unknown> {

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/sse-decoder.ts

@@ -93,8 +93,19 @@ function isCompleteJsonValue(data: string): boolean {
 // invited a retry of the identical request against a broken upstream. The
 // `upstream` origin keeps the public envelope from prefixing it
 // a gateway-branded message, which blamed the gateway for the provider's bytes.
-function oversized(what: string): GatewayError {
-  return new GatewayError("platform_unavailable", 502, `SSE ${what} exceeds size bound (request {requestId}). The upstream sent more than we can hold — retry 🌙`, {}, "upstream");
+// The message quotes the offending line (bounded) so the client and operator
+// see the actual bytes the upstream sent rather than a generic sentence.
+const MAX_SSE_SNIPPET = 160;
+function snippet(line: string): string {
+  const collapsed = line.replace(/[\r\n]+/g, " ").trim();
+  if (collapsed.length === 0) return "<empty line>";
+  return collapsed.length > MAX_SSE_SNIPPET
+    ? `${collapsed.slice(0, MAX_SSE_SNIPPET)}…`
+    : collapsed;
+}
+function oversized(what: string, line?: string): GatewayError {
+  const quote = line === undefined ? "" : `: ${snippet(line)}`;
+  return new GatewayError("platform_unavailable", 502, `SSE ${what} exceeds size bound${quote} (request {requestId}). The upstream sent more than we can hold — retry 🌙`, {}, "upstream");
 }
 
 export async function* decodeSseEvents(
@@ -161,7 +172,7 @@ export async function* decodeSseEvents(
     const rest = last.subarray(newlineAt + 1);
     if (rest.byteLength > 0) pending.unshift(rest);
     const line = decoder.decode(lineBytes).replace(/\r$/, "");
-    if (line.length > maxLineBytes) throw oversized("line");
+    if (line.length > maxLineBytes) throw oversized("line", line);
     return line;
   }
   function* dispatchEvent(): Iterable<SseEvent> {
@@ -188,7 +199,7 @@ export async function* decodeSseEvents(
       const piece = line.slice(5).trimStart();
       dataLines.push(piece);
       eventBytes += piece.length;
-      if (eventBytes > maxEventBytes) throw oversized("event");
+      if (eventBytes > maxEventBytes) throw oversized("event", line);
       return;
     }
     if (line.startsWith("id:") || line.startsWith("retry:")) return;
@@ -220,10 +231,10 @@ export async function* decodeSseEvents(
     if (dataLines.length > 0) {
       dataLines.push(line);
       eventBytes += line.length;
-      if (eventBytes > maxEventBytes) throw oversized("event");
+      if (eventBytes > maxEventBytes) throw oversized("event", line);
       return;
     }
-    throw new GatewayError("platform_unavailable", 502, "Malformed SSE line (request {requestId}). The upstream sent something we can't read — retry 🌙", {}, "upstream");
+    throw new GatewayError("platform_unavailable", 502, `Malformed SSE line: ${snippet(line)} (request {requestId}). The upstream sent something we can't read — retry 🌙`, {}, "upstream");
   }
 
   try {
@@ -233,7 +244,10 @@ export async function* decodeSseEvents(
       if (chunk.value && chunk.value.byteLength > 0) {
         pending.push(chunk.value);
         pendingBytes += chunk.value.byteLength;
-        if (!hasPendingNewline() && pendingBytes > maxLineBytes) throw oversized("line");
+        if (!hasPendingNewline() && pendingBytes > maxLineBytes) {
+          const partial = decoder.decode(new Uint8Array(pendingBytes)).slice(0, MAX_SSE_SNIPPET);
+          throw oversized("line", partial);
+        }
       }
       let line = takeLine();
       while (line !== undefined) {
@@ -243,7 +257,10 @@ export async function* decodeSseEvents(
       if (chunk.done) break;
     }
     if (pendingBytes > 0) {
-      if (pendingBytes > maxLineBytes) throw oversized("line");
+      if (pendingBytes > maxLineBytes) {
+        const partial = decoder.decode(new Uint8Array(pendingBytes)).slice(0, MAX_SSE_SNIPPET);
+        throw oversized("line", partial);
+      }
       const total = new Uint8Array(pendingBytes);
       let offset = 0;
       for (const chunk of pending.splice(0, pending.length)) {

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");

package/src/protocol/stream-error-frames.ts

@@ -17,7 +17,11 @@
  * which is honest: the upstream failed and we do not know more.
  */
 import { GatewayError } from "./gateway-error";
-import { classifyUpstreamError, extractUpstreamMessage, upstreamErrorIdentifier } from "../transport/failure-policy";
+import {
+  classifyUpstreamError,
+  upstreamErrorIdentifier,
+  extractUpstreamMessageText,
+} from "../transport/failure-policy";
 import { isRecord } from "./codecs";
 
 
@@ -54,19 +58,25 @@ export function gatewayErrorFromStreamError(
   }
   if (!isRecord(error)) return undefined;
 
-  const message = extractUpstreamMessage(error);
   const identifier = upstreamErrorIdentifier(error);
   const explicitStatus = numericStatus(error["status"], error["statusCode"], error["status_code"]);
   const classification = classifyUpstreamError(explicitStatus, identifier);
   const raw = JSON.stringify(error, null, 2).slice(0, 16_384);
+  // Only genuine prose (`message`/`msg`/`error` fields) counts as upstream
+  // passthrough text. A `code`/identifier is a classification key, not prose —
+  // it still serves as the message fallback when no text exists, but it must
+  // not set `upstreamMessageAsIs`.
+  const prose = extractUpstreamMessageText(error);
+  const message = prose.slice(0, 500) || identifier || label;
   return new GatewayError(
     classification.code,
     classification.status,
-    message || label,
+    message,
     {
       ...(explicitStatus === undefined ? {} : { providerStatus: explicitStatus }),
       ...(identifier ? { providerCode: identifier } : {}),
       raw,
+      ...(prose ? { upstreamMessageAsIs: true } : {}),
       ...(classification.credentialEvidence ? { credentialEvidence: true } : {}),
       ...(classification.rateLimitScope
         ? { rateLimitScope: classification.rateLimitScope }