cartethyia 2.7.3 → 2.7.5

package/src/protocol/think-split.ts

@@ -0,0 +1,347 @@
+/**
+ * Canonical inline-thinking split.
+ *
+ * Some upstream models write their reasoning into the *text* stream wrapped in
+ * `<think>…</think>` (or `<thinking>…</thinking>`) instead of a dedicated
+ * reasoning field. This module recovers that reasoning — statefully, so a tag
+ * split across two chunks is still recognized — and lives in the canonical
+ * protocol layer because it serves every wire: the chat decoder, provider
+ * decoders (CommandCode, Xiaomi MiMo Studio), and nothing else is per-provider
+ * about it.
+ *
+ * Two safety rules keep the classification honest (mirroring the DSML parser's
+ * fail-open behavior):
+ *
+ * - Only a *paired* span — an opening tag followed by its matching closing tag,
+ *   outside a code span — is treated as reasoning. An opening tag that never
+ *   closes at end-of-stream is almost certainly literal output (docs, a code
+ *   sample, a model reciting the syntax), so it is released as plain text
+ *   rather than swallowing the tail of the answer into the thinking pane.
+ * - A stray closing tag with no opener is likewise preserved verbatim.
+ *
+ * The splitter is stateful because a tag can straddle two SSE frames: the
+ * `<thi` of one chunk and the `nk>` of the next are one opening tag, and a
+ * stateless regex would emit the fragment as text. It therefore holds back a
+ * trailing run that could still become a tag until the next chunk settles it.
+ *
+ * Two further quirks are handled here rather than at each call site:
+ * - NUL bytes (`\u0000`) are injected by the MiMo Studio upstream between
+ *   thought tokens; forwarded verbatim they break JSON encoders and terminal
+ *   renderers.
+ * - Text before an opening tag is the answer (some models answer first and
+ *   reason afterwards), so it stays content; only the enclosed span becomes
+ *   reasoning.
+ */
+
+/** Tags whose enclosed span is reasoning, longest-first so `</thinking>` is never split as `<t`. */
+const OPEN_TAGS = ["<thinking>", "<think>"] as const;
+const CLOSE_TAGS = ["</thinking>", "</think>"] as const;
+
+/** An opening tag, with optional attributes between the name and the `>`. */
+const THINK_OPEN_RE = /^<think(?:ing)?\b[^>]*>/;
+
+/**
+ * Fail-open cap for an unclosed thinking span. Past it the span is treated as
+ * plain text instead of being buffered indefinitely — same rule as DSML's
+ * `maxBlockBytes` reference guard.
+ */
+const MAX_THINK_BLOCK_BYTES = 64 * 1024;
+
+/**
+ * Removes visible thinking tags, leaving any that sit inside a code span or
+ * fence alone — and leaving any tag that is not part of a complete pair alone
+ * too, since an unpaired tag is the subject of the answer rather than markup
+ * the upstream leaked.
+ *
+ * A tag inside backticks is the *subject* of the answer — documentation or a
+ * code sample showing the tag — not markup the upstream leaked, so stripping it
+ * would silently rewrite the answer. The same goes for an opening tag whose
+ * closing tag never arrived or a closing tag with no opener.
+ */
+export function stripThinkingTags(value: string): string {
+  if (!value.includes("<")) return value;
+  let out = "";
+  let i = 0;
+  let ticks = 0;
+  let fenced = false;
+  while (i < value.length) {
+    const char = value[i];
+    if (char === "`") {
+      let run = 1;
+      while (value[i + run] === "`") run++;
+      if (ticks === 0) {
+        ticks = run;
+        fenced = run >= 3;
+      } else if (run === ticks) {
+        ticks = 0;
+        fenced = false;
+      }
+      out += value.slice(i, i + run);
+      i += run;
+      continue;
+    }
+    // A newline closes an inline span that never closed on its own line; a
+    // fence runs to a closing line instead.
+    if (char === "\n" && ticks > 0 && !fenced) ticks = 0;
+    if (char !== "<" || ticks > 0) {
+      out += char;
+      i += 1;
+      continue;
+    }
+    const opened = THINK_OPEN_RE.exec(value.slice(i))?.[0];
+    if (opened === undefined) {
+      out += char;
+      i += 1;
+      continue;
+    }
+    const innerStart = i + opened.length;
+    const closed = pairedClose(value, innerStart, ticks, fenced);
+    if (closed === undefined) {
+      // No matching close: the opening tag is literal output, keep it.
+      out += char;
+      i += 1;
+      continue;
+    }
+    // A complete paired span is reasoning markup: keep the inner text, drop
+    // the tag bytes.
+    out += value.slice(innerStart, closed.index);
+    i = closed.index + closed.length;
+  }
+  return out;
+}
+
+interface PairedClose {
+  readonly index: number;
+  readonly length: number;
+}
+
+/** The first closing tag at or after `from`, outside any code span/fence. */
+function pairedClose(
+  value: string,
+  from: number,
+  ticksIn: number,
+  fencedIn: boolean,
+): PairedClose | undefined {
+  let ticks = ticksIn;
+  let fenced = fencedIn;
+  for (let i = from; i < value.length; i++) {
+    const char = value[i];
+    if (char === "`") {
+      let run = 1;
+      while (value[i + run] === "`") run++;
+      if (ticks === 0) {
+        ticks = run;
+        fenced = run >= 3;
+      } else if (run === ticks) {
+        ticks = 0;
+        fenced = false;
+      }
+      i += run - 1;
+      continue;
+    }
+    if (char === "\n" && ticks > 0 && !fenced) ticks = 0;
+    if (char !== "<" || ticks > 0) continue;
+    for (const tag of CLOSE_TAGS) {
+      if (value.startsWith(tag, i)) return { index: i, length: tag.length };
+    }
+    // `</think >` / `</thinking >`: whitespace before the closing `>` is
+    // accepted, same as the historical regex-backed strip.
+    const relaxed = /^<\/(?:think|thinking)\s*>/.exec(value.slice(i));
+    if (relaxed !== null) return { index: i, length: relaxed[0].length };
+  }
+  return undefined;
+}
+
+/** The longest suffix of `text` that is a proper prefix of any tag. */
+function danglingTagPrefix(text: string): string {
+  const tags = [...OPEN_TAGS, ...CLOSE_TAGS];
+  const maxLength = Math.max(...tags.map((tag) => tag.length)) - 1;
+  const limit = Math.min(maxLength, text.length);
+  for (let length = limit; length > 0; length -= 1) {
+    const suffix = text.slice(-length);
+    if (tags.some((tag) => tag.startsWith(suffix))) return suffix;
+  }
+  return "";
+}
+
+/** Strips the NUL padding MiMo Studio injects into thought streams. */
+function stripNul(text: string): string {
+  return text.includes("\u0000") ? text.replace(/\u0000/g, "") : text;
+}
+
+export interface ThinkSplit {
+  /** Answer text, with all reasoning spans removed. */
+  readonly text: string;
+  /** Reasoning text, tag-free. Empty when the chunk carried no thought. */
+  readonly reasoning: string;
+  /**
+   * Content that landed inside a span that is still open at the end of this
+   * chunk. It is not yet classified — the span has not closed — so callers
+   * that render must not emit it; a loop guard may still watch it.
+   */
+  readonly pendingReasoning: string;
+}
+
+/** A tag match plus the code state at the match, so the caller commits it. */
+interface TagMatch {
+  readonly index: number;
+  readonly length: number;
+  readonly codeTicks: number;
+  readonly codeFenced: boolean;
+}
+
+/**
+ * Splits one upstream text chunk into answer text and reasoning text.
+ *
+ * Only a pair of matching tags resolves to reasoning: the text inside stays
+ * buffered until the closing tag arrives, so the split is never decided before
+ * the span is known to be complete. If the stream ends (or the buffer exceeds
+ * `MAX_THINK_BLOCK_BYTES`) with the span still open, the whole thing is
+ * released as plain text.
+ *
+ * Call `flush()` once the upstream stream ends to release any text the splitter
+ * held back while it waited for a possible tag to complete.
+ */
+export class ThinkSplitter {
+  #buffer = "";
+  #inReasoning = false;
+  /** The opening tag of the span currently being scanned; restored on fail-open. */
+  #openMarker = "";
+  /** Backtick run that opened the code span/fence we are inside; 0 when not in
+   *  code. A tag inside a code span is the *subject* of the answer — a doc or a
+   *  code sample mentioning `<think>` — not a delimiter, so it must survive
+   *  verbatim instead of splitting the stream. */
+  #codeTicks = 0;
+  /** Whether `#codeTicks` opened a fenced block (closes on its own line) rather
+   *  than an inline span. */
+  #codeFenced = false;
+  /** Span characters already reported as `pendingReasoning`; only the fresh
+   *  tail of the open span is reported per chunk. */
+  #reportedSpanLen = 0;
+
+  /** Feeds a chunk; returns the text/reasoning split for everything settled. */
+  push(chunk: string): ThinkSplit {
+    this.#buffer += stripNul(chunk);
+    let text = "";
+    let reasoning = "";
+
+    for (;;) {
+      if (!this.#inReasoning) {
+        const opened = this.#findOpen();
+        if (opened === undefined) break;
+        text += this.#consumeUpTo(opened);
+        const openTag = this.#buffer.slice(opened.index, opened.index + opened.length);
+        this.#buffer = this.#buffer.slice(opened.index + opened.length);
+        this.#inReasoning = true;
+        this.#openMarker = openTag;
+        continue;
+      }
+      const closed = this.#findClose();
+      if (closed === undefined) break;
+      reasoning += this.#consumeUpTo(closed);
+      this.#buffer = this.#buffer.slice(closed.index + closed.length);
+      this.#inReasoning = false;
+      this.#openMarker = "";
+      this.#reportedSpanLen = 0;
+    }
+
+    // Hold back a suffix that could still grow into a tag; the rest is settled.
+    const held = danglingTagPrefix(this.#buffer);
+    const settled = held.length > 0 ? this.#buffer.slice(0, -held.length) : this.#buffer;
+    let pendingReasoning = "";
+    if (this.#inReasoning) {
+      // The closing tag has not arrived: do not classify any of this as
+      // reasoning yet. Keep it buffered so a later close can resolve it, but
+      // fail open past the cap so a runaway cannot buffer forever.
+      if (settled.length > MAX_THINK_BLOCK_BYTES) {
+        text += this.#openMarker + settled;
+        this.#buffer = held;
+        this.#inReasoning = false;
+        this.#openMarker = "";
+        this.#reportedSpanLen = 0;
+      } else {
+        this.#buffer = settled + held;
+        // Fresh span content this chunk added — visible to a loop guard, never
+        // to a renderer (the span has not closed).
+        pendingReasoning = this.#buffer.slice(this.#reportedSpanLen);
+        this.#reportedSpanLen = this.#buffer.length;
+        return { text, reasoning, pendingReasoning };
+      }
+    } else {
+      text += stripThinkingTags(settled);
+      this.#buffer = held;
+    }
+    return { text, reasoning, pendingReasoning };
+  }
+
+  /** Releases text held back for a tag that never completed. */
+  flush(): ThinkSplit {
+    const rest = this.#buffer;
+    this.#buffer = "";
+    this.#codeTicks = 0;
+    this.#codeFenced = false;
+    this.#reportedSpanLen = 0;
+    if (this.#inReasoning) {
+      // An open tag that never closed is not evidence of reasoning — restore it
+      // byte-for-byte and release the whole tail as text.
+      this.#inReasoning = false;
+      const marker = this.#openMarker;
+      this.#openMarker = "";
+      return { text: marker + stripThinkingTags(rest), reasoning: "", pendingReasoning: "" };
+    }
+    return { text: stripThinkingTags(rest), reasoning: "", pendingReasoning: "" };
+  }
+
+  /** Returns the text before a tag and commits the code state at it. */
+  #consumeUpTo(match: TagMatch): string {
+    this.#codeTicks = match.codeTicks;
+    this.#codeFenced = match.codeFenced;
+    return this.#buffer.slice(0, match.index);
+  }
+
+  #findOpen(): TagMatch | undefined {
+    return this.#findTag(OPEN_TAGS);
+  }
+
+  #findClose(): TagMatch | undefined {
+    return this.#findTag(CLOSE_TAGS);
+  }
+
+  /**
+   * The earliest occurrence of any of `tags` that is *not* inside a code span
+   * or fence, scanning left to right so code state is tracked exactly once per
+   * position. Returns the match and the code state at it, so `push` can commit
+   * that state when it consumes the tag.
+   */
+  #findTag(tags: readonly string[]): TagMatch | undefined {
+    const buffer = this.#buffer;
+    let ticks = this.#codeTicks;
+    let fenced = this.#codeFenced;
+    for (let i = 0; i < buffer.length; i++) {
+      const char = buffer[i];
+      if (char === "`") {
+        let run = 1;
+        while (buffer[i + run] === "`") run++;
+        if (ticks === 0) {
+          ticks = run;
+          // Three or more backticks open a fence rather than an inline span.
+          fenced = run >= 3;
+        } else if (run === ticks) {
+          ticks = 0;
+          fenced = false;
+        }
+        i += run - 1;
+        continue;
+      }
+      // A newline closes an inline span that never closed on its own line; a
+      // fence runs to a closing line instead.
+      if (char === "\n" && ticks > 0 && !fenced) ticks = 0;
+      if (char !== "<" || ticks > 0) continue;
+      for (const tag of tags) {
+        if (!buffer.startsWith(tag, i)) continue;
+        return { index: i, length: tag.length, codeTicks: ticks, codeFenced: fenced };
+      }
+    }
+    return undefined;
+  }
+}

package/src/protocol/translation/attachment-integrity.ts

@@ -9,7 +9,7 @@ import { log } from "../../observability/logger";
  * and in the placeholder text the model sees, so each one has to be readable
  * on its own.
  */
-export type AttachmentDefect =
+type AttachmentDefect =
   /** The base64 payload is not a whole number of 4-char groups. */
   | "truncated_base64"
   /** Base64 is well-formed but the bytes behind it are not a decodable image. */
@@ -26,13 +26,13 @@ export type AttachmentDefect =
   | "unrecognized_signature";
 
 /** One attachment dropped from a request, and why. */
-export interface DroppedAttachment {
+interface DroppedAttachment {
   readonly defect: AttachmentDefect;
   /** Index of the message the part lived in, for the log line. */
   readonly messageIndex: number;
 }
 
-export interface AttachmentIntegrityResult {
+interface AttachmentIntegrityResult {
   /** The request with every defective inline attachment replaced by a note. */
   readonly request: CanonicalRequest;
   /** Non-empty only when something was actually dropped. */

package/src/protocol/translation/cache-controls.ts

@@ -74,13 +74,13 @@ export function markLatestBreakpoint(
 // Anthropic Cache Control (Messages API)
 // ============================================================================
 
-export interface AnthropicCacheControl {
+interface AnthropicCacheControl {
   type: "ephemeral";
   /** Real Anthropic Messages wire field — NOT `budget_tokens` (that belongs only to `thinking`). */
   ttl?: AnthropicCacheTtl;
 }
 
-export type AnthropicCacheTtl = "5m" | "1h";
+type AnthropicCacheTtl = "5m" | "1h";
 
 interface AnthropicCacheControlOptions {
   ttl?: AnthropicCacheTtl;
@@ -93,27 +93,15 @@ interface AnthropicCacheControlOptions {
  * No invented minimum prefix length.
  */
 export function anthropicCacheControl(
-  hint: CacheHint | undefined,
+  _hint: CacheHint | undefined,
   options: AnthropicCacheControlOptions = {},
-): Record<string, unknown> {
+): { cache_control: AnthropicCacheControl } {
   const control: AnthropicCacheControl = { type: "ephemeral" };
   if (options.ttl) control.ttl = options.ttl;
 
-  if (!hint || hint === "stable_prefix") {
-    // Stable prefix: emit automatic top-level cache_control at last cacheable block
-    return { cache_control: control };
-  }
-
-  if (hint.kind === "breakpoint") {
-    // Per-content-block cache control for explicitly marked breakpoints
-    // The breakpoint list indicates positions where cache boundaries should be
-    // applied (in top-level request builder when flattening to Messages format)
-    return {
-      // Caller-marked breakpoints handled by surface adapter
-      // per_block_cache: hint.list, // not exposed to API, managed by adapter
-      cache_control: control,
-    };
-  }
-
+  // Every hint shape maps to the same top-level control: stable_prefix emits
+  // it at the last cacheable block, breakpoint hints are handled per-block by
+  // the surface adapter, and no hint still gets Anthropic's automatic cache
+  // control. The (unused) hint parameter is kept so call sites document intent.
   return { cache_control: control };
 }

package/src/protocol/translation/capabilities.ts

@@ -9,7 +9,7 @@ import {
 } from "../canonical-model";
 
 /** Capabilities declared by one resolved provider/model/route candidate. */
-export interface RouteCapabilities {
+interface RouteCapabilities {
   readonly text: true;
   readonly image: boolean;
   /** Accepts non-image document payloads (PDF, plain files). */
@@ -45,7 +45,7 @@ export interface RouteCapabilities {
  * A bespoke adapter is not in this matrix at all — see
  * `BESPOKE_GENERATION_CONTROLS` for why it receives every control.
  */
-export const GENERATION_CONTROL_MATRIX: Readonly<
+const GENERATION_CONTROL_MATRIX: Readonly<
   Record<WireFamily, ReadonlySet<keyof GenerationControls>>
 > = {
   chat: new Set([
@@ -98,7 +98,7 @@ const BESPOKE_GENERATION_CONTROLS: ReadonlySet<keyof GenerationControls> = new S
  * and `web_search_tool_result` are Anthropic Messages blocks, so only the
  * Messages wire re-encodes them (`protocol/request/messages.ts`).
  */
-export const EXTENSION_MATRIX: Readonly<Record<WireFamily, ReadonlySet<string>>> = {
+const EXTENSION_MATRIX: Readonly<Record<WireFamily, ReadonlySet<string>>> = {
   chat: new Set(),
   responses: new Set(),
   messages: new Set(["server_tool_use", "search_result", "web_search_tool_result"]),
@@ -155,7 +155,7 @@ export function pickWireSupportedControls(
  * both the router (`routing/router.ts`) and the planner share one predicate
  * without a layering cycle.
  */
-export interface CapabilityProfileHolder {
+interface CapabilityProfileHolder {
   readonly capability_profile: Readonly<Record<string, boolean>>;
   readonly wire_family: WireFamily;
 }
@@ -259,7 +259,7 @@ export function ensureMaxTokensForThinking(
     throw new GatewayError(
       "invalid_request",
       400,
-      `Anthropic thinking budget requires max_tokens greater than ${buffer}; got ${currentMax} with budget ${budget}`,
+      `Anthropic thinking budget requires max_tokens greater than ${buffer}; got ${currentMax} with budget ${budget} (request {requestId}). Check the shape of what you sent — then resend 🪞`,
       { budget_tokens: budget, max_tokens: currentMax },
     );
   }
@@ -288,7 +288,7 @@ export type RequiredCapability =
  * No field is silently removed: every unsupported semantic requirement has
  * already produced a typed rejection before this result exists.
  */
-export interface ProjectedRequest extends CanonicalRequest {
+interface ProjectedRequest extends CanonicalRequest {
   readonly requiredCapabilities: readonly RequiredCapability[];
 }
 
@@ -347,7 +347,7 @@ export function deriveRequiredCapabilities(
 }
 
 /** Anthropic and OpenAI 5.6+ both cap explicit cache breakpoints per request. */
-export const MAX_CACHE_BREAKPOINTS = 4;
+const MAX_CACHE_BREAKPOINTS = 4;
 
 /**
  * Validates the cache-breakpoint count at the preflight boundary — before
@@ -364,7 +364,7 @@ function validateCacheBreakpoints(hint: CacheHint | undefined): void {
     throw new GatewayError(
       "invalid_request",
       400,
-      `cache_hint declares ${hint.list.length} breakpoints; at most ${MAX_CACHE_BREAKPOINTS} are supported`,
+      `cache_hint declares ${hint.list.length} breakpoints; at most ${MAX_CACHE_BREAKPOINTS} are supported (request {requestId}). Check the shape of what you sent — then resend 🪞`,
       { breakpoint_count: hint.list.length, max_breakpoints: MAX_CACHE_BREAKPOINTS },
     );
   }

package/src/protocol/translation/dialect/deepseek.ts

@@ -0,0 +1,10 @@
+/**
+ * DeepSeek wire dialect: DSML in-band tool calls.
+ *
+ * The engine (`DsmlStreamParser`) lives in `src/protocol/dsml.ts` and is shared
+ * with the CodeBuddy/Qoder families. This module owns the DeepSeek dialect
+ * facade used by the in-band scanner factory.
+ */
+import { DsmlStreamParser } from "../../dsml";
+
+export { DsmlStreamParser };

package/src/protocol/translation/dialect/inband.ts

@@ -0,0 +1,39 @@
+/**
+ * In-band tool-call scanner interface + factory.
+ *
+ * Some model families emit tool calls as markup inside the text stream instead
+ * of structured `tool_calls`: DeepSeek DSML, Qwen `<tool_call>` JSON, OMP
+ * `<tool_calls:8hex>`. Each is a pluggable codec; the codecs select one by
+ * dialect id.
+ */
+import { DsmlStreamParser } from "./deepseek";
+import { QwenToolCallScanner } from "./qwen";
+import type { DialectId } from "./types";
+
+interface InbandToolCall {
+  readonly id: string;
+  readonly name: string;
+  readonly arguments: string;
+}
+
+export interface InbandScanResult {
+  readonly text: string;
+  readonly calls: readonly InbandToolCall[];
+}
+
+export interface InbandScanner {
+  push(chunk: string): InbandScanResult;
+  flush(): InbandScanResult;
+}
+
+/** Creates the scanner for a dialect, or undefined for structured-only dialects. */
+export function createInbandScanner(
+  dialect: DialectId | null | undefined,
+  allowedNames: ReadonlySet<string>,
+): InbandScanner | undefined {
+  if (dialect === "qwen") return new QwenToolCallScanner(allowedNames);
+  if (dialect === "deepseek") return new DsmlStreamParser({ allowedNames });
+  return undefined;
+}
+
+export type { DsmlToolCall } from "../../dsml";

package/src/protocol/translation/dialect/model-thinking.ts

@@ -0,0 +1,89 @@
+/**
+ * Canonical thinking clamp + output-floor helpers, shared by every wire codec.
+ *
+ * `clampThinkingLevelForModel` is the single clamp: it steps a requested
+ * effort down to the highest supported level ≤ the request, or up to the
+ * model's floor when the request is below it. It replaces the old
+ * `clampReasoningEffort` with the same semantics, driven by the data-driven
+ * `ThinkingConfig` from `thinking-ladder.ts`.
+ *
+ * `outputFloorFor` is the clamped-effort output floor (previously
+ * `clampedEffortOutputFloor` in `protocol/reasoning.ts`): when the applied
+ * effort differs from the requested one, the caller sized `max_tokens` for the
+ * effort it asked for, and the applied level spends its budget on reasoning
+ * before writing the answer — so raise the output budget to the model's
+ * catalog ceiling rather than let the answer truncate.
+ */
+import {
+  REASONING_EFFORT_LADDER,
+  type ReasoningEffortLevel,
+} from "../thinking";
+import type { ThinkingConfig } from "./thinking-ladder";
+
+/**
+ * Clamps a requested reasoning effort against a model/wire's resolved
+ * `ThinkingConfig`. Same semantics as the removed `clampReasoningEffort`:
+ * synonyms normalize (`ultra` → `max`, `off` → `none`), unknown strings drop
+ * (no invented fallback), and a request below the floor uses the floor.
+ */
+export function clampThinkingLevelForModel(
+  thinking: ThinkingConfig | undefined,
+  requested: string | undefined,
+): ReasoningEffortLevel | undefined {
+  if (requested === undefined || typeof requested !== "string") return undefined;
+  const raw = requested.toLowerCase().trim();
+  const normalized = raw === "ultra" ? "max" : raw === "off" ? "none" : raw;
+  if (normalized === "none") return undefined;
+  if (thinking === undefined) return normalized as ReasoningEffortLevel;
+
+  const supported = thinking.efforts;
+  if (supported.includes(normalized as ReasoningEffortLevel)) {
+    return normalized as ReasoningEffortLevel;
+  }
+  const requestedIndex = REASONING_EFFORT_LADDER.indexOf(normalized as ReasoningEffortLevel);
+  if (requestedIndex === -1) return undefined;
+
+  let clamped: ReasoningEffortLevel | undefined;
+  for (const level of supported) {
+    if (REASONING_EFFORT_LADDER.indexOf(level) > requestedIndex) break;
+    clamped = level;
+  }
+  // No smaller supported level exists (caller asked below floor): use floor.
+  return clamped ?? supported[0];
+}
+
+const CLAMPED_EFFORT_MIN_OUTPUT_TOKENS = 16_384;
+
+const EFFORT_LEVEL_RANK: Readonly<Record<string, number>> = {
+  off: 0,
+  none: 0,
+  instant: 1,
+  minimal: 2,
+  low: 3,
+  medium: 4,
+  high: 5,
+  xhigh: 6,
+  max: 7,
+};
+
+/**
+ * Minimum output budget for a caller whose requested effort the ladder could
+ * not serve as asked. See the module doc for why both clamp directions need it.
+ * Only ever raises, and only to the model's own catalog limit.
+ */
+export function outputFloorFor(
+  requested: string | undefined,
+  applied: string | undefined,
+  modelOutputLimit: number | undefined,
+): number | undefined {
+  if (requested === undefined || applied === undefined) return undefined;
+  const from = EFFORT_LEVEL_RANK[requested.trim().toLowerCase()];
+  const to = EFFORT_LEVEL_RANK[applied.trim().toLowerCase()];
+  if (from === undefined || to === undefined || from === to) return undefined;
+  if (modelOutputLimit === undefined || !Number.isFinite(modelOutputLimit) || modelOutputLimit <= 0)
+    return undefined;
+  // Leave headroom instead of claiming the whole catalog limit: the caller's
+  // number was a real preference about answer size, and the goal is to stop
+  // truncating, not to spend the model's ceiling on every turn.
+  return Math.max(CLAMPED_EFFORT_MIN_OUTPUT_TOKENS, Math.floor(modelOutputLimit / 2));
+}