@tormentalabs/claude-code-wire-compat 0.1.0-rc.17 → 0.2.0

package/src/sha256.ts

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+const SHA256_INITIAL = new Uint32Array([
+  0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c,
+  0x1f83d9ab, 0x5be0cd19,
+]);
+const SHA256_ROUNDS = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
+  0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+  0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+  0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
+  0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+  0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+  0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+  0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+function rotateRight(value: number, count: number): number {
+  return (value >>> count) | (value << (32 - count));
+}
+
+function wordAt(words: Uint32Array, index: number): number {
+  // The fallback is unreachable at runtime because every call site indexes
+  // within the allocated array. It exists solely to satisfy
+  // noUncheckedIndexedAccess and is therefore this file's sole uncovered
+  // branch, intentionally not covered by a test.
+  return words[index] ?? 0;
+}
+
+/**
+ * Computes a digest only so the synchronous parser can verify the integrity of
+ * evidence produced by this package. The asynchronous builder path uses the
+ * injected Web Crypto implementations in `src/fingerprint.ts` and
+ * `src/redaction.ts` and MUST continue to do so. This checks non-secret,
+ * self-produced data; it is not a MAC and must not inform security decisions.
+ */
+export function sha256Hex(value: string): string {
+  const source = new TextEncoder().encode(value);
+  const paddedLength = Math.ceil((source.length + 9) / 64) * 64;
+  const padded = new Uint8Array(paddedLength);
+  padded.set(source);
+  padded[source.length] = 0x80;
+  const bitLength = source.length * 8;
+  const view = new DataView(padded.buffer);
+  view.setUint32(paddedLength - 8, Math.floor(bitLength / 0x1_0000_0000));
+  view.setUint32(paddedLength - 4, bitLength >>> 0);
+  const state = new Uint32Array(SHA256_INITIAL);
+  const words = new Uint32Array(64);
+
+  for (let offset = 0; offset < paddedLength; offset += 64) {
+    for (let index = 0; index < 16; index += 1) {
+      words[index] = view.getUint32(offset + index * 4);
+    }
+    for (let index = 16; index < 64; index += 1) {
+      const previous15 = wordAt(words, index - 15);
+      const previous2 = wordAt(words, index - 2);
+      const sigma0 =
+        rotateRight(previous15, 7) ^
+        rotateRight(previous15, 18) ^
+        (previous15 >>> 3);
+      const sigma1 =
+        rotateRight(previous2, 17) ^
+        rotateRight(previous2, 19) ^
+        (previous2 >>> 10);
+      words[index] =
+        wordAt(words, index - 16) + sigma0 + wordAt(words, index - 7) + sigma1;
+    }
+
+    let a = wordAt(state, 0);
+    let b = wordAt(state, 1);
+    let c = wordAt(state, 2);
+    let d = wordAt(state, 3);
+    let e = wordAt(state, 4);
+    let f = wordAt(state, 5);
+    let g = wordAt(state, 6);
+    let h = wordAt(state, 7);
+    for (let index = 0; index < 64; index += 1) {
+      const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+      const choice = (e & f) ^ (~e & g);
+      const temporary1 =
+        (h +
+          sum1 +
+          choice +
+          wordAt(SHA256_ROUNDS, index) +
+          wordAt(words, index)) >>>
+        0;
+      const sum0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+      const majority = (a & b) ^ (a & c) ^ (b & c);
+      const temporary2 = (sum0 + majority) >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = (d + temporary1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (temporary1 + temporary2) >>> 0;
+    }
+    state[0] = wordAt(state, 0) + a;
+    state[1] = wordAt(state, 1) + b;
+    state[2] = wordAt(state, 2) + c;
+    state[3] = wordAt(state, 3) + d;
+    state[4] = wordAt(state, 4) + e;
+    state[5] = wordAt(state, 5) + f;
+    state[6] = wordAt(state, 6) + g;
+    state[7] = wordAt(state, 7) + h;
+  }
+  return Array.from(state, (word) => word.toString(16).padStart(8, "0")).join(
+    "",
+  );
+}

package/src/system-prompt.ts

@@ -0,0 +1,222 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type {
+  ClaudeCodeRuntimeIdentity,
+  SystemInput,
+  TextBlock,
+} from "./contracts.js";
+import { ClaudeCodeWireError } from "./contracts.js";
+import { classifySurrogateAt } from "./unicode.js";
+
+/**
+ * The pinned identity text, byte-exact.
+ *
+ * It is exported because it is the byte-exact probe the parser uses to CONFIRM
+ * the canonical system prefix. A caller block equal to it is dropped by
+ * `buildCanonicalSystem` — unconditionally, even when `suppressIdentityBlock`
+ * removed the canonical one — so it appears at most once in a built body.
+ *
+ * The parser no longer INFERS the prefix length from this text's position: the
+ * root seams `suppressBillingBlock` and `suppressIdentityBlock` are recorded in
+ * `evidence.billingBlockSuppressed` / `evidence.identityBlockSuppressed`, which
+ * state which canonical blocks were emitted. This text is what the parser then
+ * checks the identity slot against, so evidence is verified structurally rather
+ * than trusted.
+ */
+export const IDENTITY_TEXT =
+  "You are Claude Code, Anthropic's official CLI for Claude.";
+const MAX_INPUT_DEPTH = 64;
+const MAX_INPUT_SIZE = 1_000_000;
+type UnknownRecord = Readonly<Record<PropertyKey, unknown>>;
+
+function fail(
+  code:
+    | "INVALID_INPUT"
+    | "INVALID_UNICODE"
+    | "INPUT_TOO_DEEP"
+    | "INPUT_TOO_LARGE"
+    | "CYCLIC_INPUT",
+): never {
+  throw new ClaudeCodeWireError(code);
+}
+
+function validateText(text: string): void {
+  for (let index = 0; index < text.length; index += 1) {
+    const codeUnit = text.charCodeAt(index);
+
+    if (
+      codeUnit === 0 ||
+      (codeUnit < 0x20 &&
+        codeUnit !== 0x09 &&
+        codeUnit !== 0x0a &&
+        codeUnit !== 0x0d) ||
+      (codeUnit >= 0x7f && codeUnit <= 0x9f)
+    ) {
+      fail("INVALID_UNICODE");
+    }
+
+    const classification = classifySurrogateAt(text, index);
+    if (classification === "loneSurrogate") fail("INVALID_UNICODE");
+    if (classification === "surrogatePair") index += 1;
+  }
+}
+
+function isUnknownRecord(value: unknown): value is UnknownRecord {
+  return value !== null && typeof value === "object";
+}
+
+function validateStructure(value: unknown): void {
+  const ancestors = new WeakSet();
+  let size = 0;
+
+  function visit(current: unknown, depth: number): void {
+    if (depth > MAX_INPUT_DEPTH) fail("INPUT_TOO_DEEP");
+
+    if (typeof current === "string") {
+      size += current.length;
+      if (size > MAX_INPUT_SIZE) fail("INPUT_TOO_LARGE");
+      validateText(current);
+      return;
+    }
+
+    if (!isUnknownRecord(current)) return;
+    if (ancestors.has(current)) fail("CYCLIC_INPUT");
+
+    ancestors.add(current);
+    for (const key of Reflect.ownKeys(current)) {
+      if (typeof key === "string") {
+        size += key.length;
+        if (size > MAX_INPUT_SIZE) fail("INPUT_TOO_LARGE");
+        validateText(key);
+      }
+      visit(current[key], depth + 1);
+    }
+    ancestors.delete(current);
+  }
+
+  visit(value, 0);
+}
+
+function cloneTextBlock(value: unknown): TextBlock {
+  if (!isUnknownRecord(value)) fail("INVALID_INPUT");
+
+  const type = value["type"];
+  const text = value["text"];
+  if (type !== "text" || typeof text !== "string") fail("INVALID_INPUT");
+
+  const cacheControl = value["cache_control"];
+  if (cacheControl === undefined) return Object.freeze({ type: "text", text });
+  if (!isUnknownRecord(cacheControl)) fail("INVALID_INPUT");
+
+  const cacheType = cacheControl["type"];
+  const ttl = cacheControl["ttl"];
+  const scope = cacheControl["scope"];
+  if (
+    cacheType !== "ephemeral" ||
+    (ttl !== undefined && ttl !== "5m" && ttl !== "1h") ||
+    (scope !== undefined && scope !== "global")
+  ) {
+    fail("INVALID_INPUT");
+  }
+
+  const clonedCacheControl: {
+    type: "ephemeral";
+    ttl?: "5m" | "1h";
+    scope?: "global";
+  } = { type: "ephemeral" };
+  if (ttl !== undefined) clonedCacheControl.ttl = ttl;
+  if (scope !== undefined) clonedCacheControl.scope = scope;
+
+  return Object.freeze({
+    type: "text",
+    text,
+    cache_control: Object.freeze(clonedCacheControl),
+  });
+}
+
+function equalCacheControl(
+  left: TextBlock["cache_control"],
+  right: TextBlock["cache_control"],
+): boolean {
+  if (left === undefined || right === undefined) return left === right;
+  if (left === null || right === null) return left === right;
+  return left.ttl === right.ttl && left.scope === right.scope;
+}
+
+function joinTextBlocks(left: TextBlock, right: TextBlock): TextBlock {
+  return Object.freeze({
+    type: "text",
+    text: `${left.text}\n${right.text}`,
+    ...(left.cache_control === undefined
+      ? {}
+      : { cache_control: left.cache_control }),
+  });
+}
+
+/** Builds the pinned Claude Code system block sequence without changing caller data. */
+export function buildCanonicalSystem(
+  input: readonly SystemInput[] | undefined,
+  billingBlock: TextBlock,
+  identity: ClaudeCodeRuntimeIdentity,
+  suppressBillingBlock = false,
+  suppressIdentityBlock = false,
+): readonly TextBlock[] {
+  validateStructure(input);
+  if (input !== undefined && !Array.isArray(input)) fail("INVALID_INPUT");
+  if (billingBlock.cache_control !== undefined) fail("INVALID_INPUT");
+
+  const clonedBilling = cloneTextBlock(billingBlock);
+  const canonicalBilling = Object.isFrozen(billingBlock)
+    ? billingBlock
+    : clonedBilling;
+
+  // The runtime identity is accepted for parity with the request builder. The
+  // pinned identity system text itself intentionally contains no identifiers.
+  void identity;
+
+  // Package extension: `suppressBillingBlock` and `suppressIdentityBlock` are
+  // the only ways to omit a canonical block. Both default to `false`, which
+  // keeps the two-block canonical prefix the genuine client always emits. With
+  // both active the canonical prefix is empty and the emitted `system` array
+  // holds caller blocks only.
+  const blocks: TextBlock[] = suppressBillingBlock ? [] : [canonicalBilling];
+  if (!suppressIdentityBlock) {
+    blocks.push(
+      Object.freeze({
+        type: "text",
+        text: IDENTITY_TEXT,
+        cache_control: Object.freeze({ type: "ephemeral", ttl: "1h" }),
+      }),
+    );
+  }
+
+  if (input !== undefined) {
+    let run: TextBlock | undefined;
+    for (const entry of input) {
+      const block: TextBlock =
+        typeof entry === "string"
+          ? Object.freeze({ type: "text" as const, text: entry })
+          : cloneTextBlock(entry);
+
+      // Upstream recognizes only the byte-for-byte identity constant. Similar
+      // caller text remains ordinary prompt content.
+      //
+      // The drop stays UNCONDITIONAL under `suppressIdentityBlock`: the genuine
+      // client drops it too, and a caller block equal to the identity text
+      // landing at the front of a suppressed prefix would defeat the parser's
+      // structural check of the canonical prefix.
+      if (block.text === IDENTITY_TEXT) continue;
+      if (run === undefined) {
+        run = block;
+      } else if (equalCacheControl(run.cache_control, block.cache_control)) {
+        run = joinTextBlocks(run, block);
+      } else {
+        blocks.push(run);
+        run = block;
+      }
+    }
+    if (run !== undefined) blocks.push(run);
+  }
+
+  return Object.freeze(blocks);
+}

package/src/thinking.ts

@@ -0,0 +1,346 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type {
+  ClaudeCodeBetaPolicy,
+  ClaudeCodeCapabilities,
+  ClaudeCodeProtocolProfile,
+} from "./contracts.js";
+import { profileBehaviors } from "./profile-behaviors.js";
+import { CLAUDE_CODE_2_1_195_PROFILE } from "./profiles/claude-code-2.1.195.js";
+
+/**
+ * Extended-thinking resolution, ported from the genuine client's request
+ * builder at byte offset 238154330.
+ *
+ * The single most surprising thing in here, and the reason this module exists
+ * rather than a handful of inline branches: **the caller does not choose
+ * between adaptive and enabled thinking — the model does.**
+ *
+ * Upstream the choice is
+ *
+ * ```
+ * cn = aSr(s.model);
+ * if (cn !== void 0 ? cn === "adaptive" : Uot(u) && !zt) { adaptive } else { enabled }
+ * ```
+ *
+ * `aSr` is `Bt.thinkingTypeOverrides.get(e)`, a host-side override map that is
+ * empty on a default install, so `cn` is undefined and the ternary falls through
+ * to `Uot(u)` — the adaptive-thinking capability predicate. `zt` additionally
+ * requires an environment variable that is unset by default.
+ *
+ * So a caller asking for `type: "enabled"` against an adaptive-capable model
+ * gets `{type:"adaptive"}` on the wire and their `budgetTokens` is discarded,
+ * and a caller asking for `type: "adaptive"` against a model without the
+ * capability gets `{type:"enabled",budget_tokens:…}`. The caller's `type` is
+ * load-bearing in exactly one way: whether or not it is `"disabled"`.
+ *
+ * This package reproduces that. Rejecting the mismatch instead — which is what
+ * it used to do — would make its traffic distinguishable from the real client's,
+ * which is the one thing it exists to avoid.
+ *
+ * This module also owns `modelOutputTokenLimits` and `clampMaxTokens`, which
+ * bound `max_tokens` rather than anything thinking-specific. They live here
+ * because upstream derives both from one table (`Xxe`) and feeds one clamped
+ * value (`Fi`) into both the emitted `max_tokens` and the thinking budget, so
+ * splitting them would separate two things that must not drift apart. If a
+ * third consumer of the limit table ever appears, extract all three into their
+ * own module at that point.
+ */
+
+/** Permitted values of the `display` property, from the schema at 241453966. */
+export type ThinkingDisplay = "summarized" | "omitted";
+
+export interface ThinkingRequest {
+  readonly type: "enabled" | "adaptive" | "disabled";
+  readonly budgetTokens?: number;
+  readonly display?: ThinkingDisplay;
+}
+
+export interface ModelOutputTokenLimits {
+  readonly default: number;
+  readonly upperLimit: number;
+}
+
+export interface ResolvedThinking {
+  /** The object to place at `body.thinking`, or undefined to omit the field. */
+  readonly emitted: Readonly<Record<string, unknown>> | undefined;
+  /**
+   * Whether the caller asked for thinking at all, regardless of whether any
+   * `thinking` object survived resolution. This — not `emitted` — is what
+   * suppresses `temperature`, matching upstream `nr`.
+   */
+  readonly requestActive: boolean;
+  /** Whether `tool_choice` of type `tool` must be demoted to `auto`. */
+  readonly extendedThinkingActive: boolean;
+}
+
+/**
+ * Per-model output token limits, ported from upstream `Xxe` at byte offset
+ * 227378240. Keyed on the NORMALISED model id.
+ *
+ * Resolution order, since Fase 1.2:
+ *
+ *   1. The pinned 2.1.195 catalogue, when the id has an entry carrying
+ *      `maxOutputTokens`. That is the single source of truth for every model
+ *      the profile knows, and `token-limits-equivalence.test.ts` pins the two
+ *      sources cell by cell.
+ *   2. Otherwise the transcribed `Xxe` table below, preserved intact as the
+ *      demarcated fallback. It is NOT dead code and must not be trimmed to
+ *      "only the ids the catalogue lacks": `claude-3-opus`, `claude-3-sonnet`
+ *      and `claude-3-haiku` are reachable through the normaliser with no
+ *      catalogue entry, `claude-mythos-5` is absent from the catalogue by
+ *      product decision D-1, and any id from a newer client lands on the
+ *      final fallback row.
+ *
+ * Both fields are load-bearing. `upperLimit` seeds the thinking budget when the
+ * caller supplies none (upstream `wvi = Xxe(e).upperLimit - 1`); `default` caps
+ * the emitted `max_tokens` (upstream `qct`, see `clampMaxTokens`).
+ *
+ * Upstream additionally consults `Vkd` and `bvi`, neither of which is modelled:
+ *
+ *   - `Vkd(e)` lowers `default` from the host config object `heather_vale`.
+ *     That object is absent on a default install, so it returns null and makes
+ *     no adjustment. Same class as `W9` in `model-capabilities.ts`: a host-side
+ *     override this package cannot observe.
+ *   - `bvi(e)` adjusts BOTH fields, but sits behind `_vi()`, which returns a
+ *     hard `false`. Dead code upstream.
+ *
+ * From 2.1.222 onward upstream grew a THIRD adjustment, this one derived from
+ * the request rather than from host state, and therefore observable: see
+ * `requestedMaxTokens` below.
+ *
+ * @param requestedMaxTokens
+ *   The caller's own `max_tokens`, when the call site has it. Modelled for
+ *   profiles from 2.1.222 onward only; see the demarcated block below.
+ */
+export function modelOutputTokenLimits(
+  normalizedId: string,
+  profile: ClaudeCodeProtocolProfile = CLAUDE_CODE_2_1_195_PROFILE,
+  requestedMaxTokens?: number,
+): ModelOutputTokenLimits {
+  const resolved = resolveDeclaredLimits(normalizedId, profile);
+
+  /*
+   * ---- Demarcated: request-derived upper bound, upstream 2.1.222+. ----
+   *
+   * Upstream raises `upperLimit` to the caller's own `max_tokens` and lowers
+   * `default` to fit under it:
+   *
+   *   upperLimit = requestedMaxTokens;
+   *   default    = Math.min(default, upperLimit);
+   *
+   * Verified byte-identical between upstream 2.1.222 and 2.1.233.
+   *
+   * The gate is STRUCTURAL, not a capability flag: this behaviour exists in
+   * upstream 2.1.222+ and 2.1.195 does not have it, so the 195 profile must
+   * never see it. Which profiles are on which side is `profile-behaviors.ts`'s
+   * question, not this module's.
+   *
+   * `Number.isSafeInteger` is deliberately stricter than upstream's truthy
+   * check. The upstream runtime only ever produces integers in this field, so
+   * the two agree on every reachable input; here a NaN or Infinity would
+   * propagate straight into `budget_tokens`, which must stay an integer.
+   */
+  if (
+    profileBehaviors(profile).requestDerivedTokenCeiling &&
+    requestedMaxTokens !== undefined &&
+    Number.isSafeInteger(requestedMaxTokens) &&
+    requestedMaxTokens >= 4096
+  ) {
+    const upperLimit = requestedMaxTokens;
+    return { default: Math.min(resolved.default, upperLimit), upperLimit };
+  }
+
+  return resolved;
+}
+
+function resolveDeclaredLimits(
+  normalizedId: string,
+  profile: ClaudeCodeProtocolProfile,
+): ModelOutputTokenLimits {
+  const declared = profile.supportedModels[normalizedId]?.maxOutputTokens;
+  if (declared !== undefined) {
+    // `upper` is the catalogue's name for what this module calls `upperLimit`;
+    // the rename happens here and nowhere else.
+    return { default: declared.default, upperLimit: declared.upper };
+  }
+
+  /*
+   * ---- Demarcated fallback: the reachable remainder of `Xxe`. ----
+   *
+   * No catalogue id reaches this point. Every entry of the 2.1.195 catalogue
+   * declares `maxOutputTokens`, and `capability-equivalence.test.ts` fails if
+   * one stops doing so, which is what keeps the rows below to the ids the
+   * catalogue genuinely cannot answer for:
+   *
+   *   - `claude-mythos-5` has no catalogue entry by product decision D-1.
+   *   - `claude-3-opus`, `claude-3-sonnet` and `claude-3-haiku` are reachable
+   *     through the normaliser and predate the catalogue.
+   *
+   * The rows for catalogued ids were deleted rather than kept "just in case":
+   * they were unreachable, so they could be neither covered nor
+   * mutation-killed, and a second copy of a limit that no longer serves any
+   * request is exactly the duplicated table
+   * `test/governance/single-source-of-truth.test.ts` exists to prevent.
+   *
+   * This mirrors upstream 2.1.222, where derivation is catalogue-first and
+   * the surviving legacy rows are the `claude-3-*` ones plus a generic tail.
+   *
+   * If a future profile omits `maxOutputTokens` for some id, that id lands on
+   * the generic tail below -- 32000/128000 -- rather than on a stale
+   * per-model row. That is deliberate: a wrong-but-loud generic limit is
+   * recoverable, a silently stale per-model limit is not. The equivalence
+   * guard fires first in any case.
+   */
+  if (normalizedId === "claude-mythos-5") {
+    return { default: 64000, upperLimit: 128000 };
+  }
+  if (normalizedId === "claude-3-opus") {
+    return { default: 4096, upperLimit: 4096 };
+  }
+  if (normalizedId === "claude-3-sonnet") {
+    return { default: 8192, upperLimit: 8192 };
+  }
+  if (normalizedId === "claude-3-haiku") {
+    return { default: 4096, upperLimit: 4096 };
+  }
+  return { default: 32000, upperLimit: 128000 };
+}
+
+/**
+ * Caps the caller's `max_tokens` at the model's default output limit, porting
+ * upstream `Fi = Math.min(En?.maxTokensOverride || s.maxOutputTokensOverride
+ * || la, la)` where `la = qct(u)`.
+ *
+ * `qct` is `Fue("CLAUDE_CODE_MAX_OUTPUT_TOKENS", <env>, t.default,
+ * t.upperLimit).effective` over `t = Xxe(model)`. `Fue` returns `t.default`
+ * untouched whenever the environment variable is unset, and only ever clamps
+ * the ENVIRONMENT value against `t.upperLimit` — never the default. This
+ * package reads no environment, so `qct` reduces to `Xxe(model).default` and
+ * `upperLimit` plays no part in this bound.
+ *
+ * The result is load-bearing twice over: it is the emitted `max_tokens`, and it
+ * is the `Fi` that `resolveThinking` clamps the thinking budget against via
+ * `Tr = Math.min(Fi - 1, Tr)`. Both call sites must receive the CLAMPED value.
+ *
+ * Upstream uses `||`, not `??`, so a zero override would fall back to the
+ * default. Unreachable here: `max_tokens` is validated as a positive integer
+ * before this runs.
+ *
+ * `requested` is forwarded as the request-derived bound so that this call site
+ * reads the same table upstream reads. It cannot change the result: the
+ * override only ever lowers `default` to `requested`, and
+ * `min(requested, min(default, requested)) === min(requested, default)`. It is
+ * passed for coherence of reading, not for effect.
+ */
+export function clampMaxTokens(
+  requested: number,
+  normalizedId: string,
+  profile: ClaudeCodeProtocolProfile = CLAUDE_CODE_2_1_195_PROFILE,
+): number {
+  return Math.min(
+    requested,
+    modelOutputTokenLimits(normalizedId, profile, requested).default,
+  );
+}
+
+/**
+ * Upstream `Yn = nr && CM() && QOt(u) ? n.display : void 0`, combined with the
+ * `if (Xn && Yn)` guard on the beta splice.
+ *
+ * This answers the splice question on its own, without consulting whether a
+ * `thinking` object was actually emitted, because the two are equivalent: a true
+ * result requires `type !== "disabled"` and `capabilities.thinking`, and those
+ * two conditions are exactly what drives `resolveThinking` into one of its two
+ * emitting branches. Upstream's `Xn` is therefore always set whenever `Yn` is.
+ *
+ * Deliberately tolerant of unvalidated input so that request assembly can ask
+ * this question before the body validator has run. Anything malformed answers
+ * false here and is rejected later by `buildCanonicalBody`.
+ */
+export function isThinkingDisplayActive(
+  request: unknown,
+  capabilities: ClaudeCodeCapabilities,
+  betaPolicy: ClaudeCodeBetaPolicy,
+): boolean {
+  if (request === null || typeof request !== "object") return false;
+  const record = request as Record<string, unknown>;
+  if (record["type"] === "disabled") return false;
+  const display = record["display"];
+  if (display !== "summarized" && display !== "omitted") return false;
+  return (
+    capabilities.thinking &&
+    capabilities.interleavedThinking &&
+    betaPolicy.experimentalBetasEnabled
+  );
+}
+
+/**
+ * Resolves the caller's thinking request into the object the genuine client
+ * would put on the wire.
+ *
+ * Key order is load-bearing. Upstream emits `{budget_tokens, type, display}`
+ * for the enabled branch — `budget_tokens` FIRST — and `{type, display}` for
+ * adaptive. Serialised bodies are compared byte for byte, so the insertion
+ * order below must not be rearranged.
+ */
+export function resolveThinking(
+  request: ThinkingRequest | undefined,
+  normalizedId: string,
+  capabilities: ClaudeCodeCapabilities,
+  betaPolicy: ClaudeCodeBetaPolicy,
+  maxTokens: number,
+  profile: ClaudeCodeProtocolProfile = CLAUDE_CODE_2_1_195_PROFILE,
+): ResolvedThinking {
+  // Upstream `nr = n.type !== "disabled" && !CLAUDE_CODE_DISABLE_THINKING`.
+  const requestActive = request !== undefined && request.type !== "disabled";
+  const displayActive = isThinkingDisplayActive(
+    request,
+    capabilities,
+    betaPolicy,
+  );
+  const display = displayActive ? request?.display : undefined;
+
+  let emitted: Record<string, unknown> | undefined;
+
+  if (requestActive && capabilities.thinking) {
+    if (capabilities.adaptiveThinking) {
+      emitted = { type: "adaptive" };
+      if (display !== undefined) emitted["display"] = display;
+    } else {
+      // Upstream: `let Tr = wvi(u)` — the model's upper limit minus one —
+      // overridden by the caller's budget when supplied, then clamped by
+      // `Tr = Math.min(Fi - 1, Tr)` where `Fi` is the emitted `max_tokens`.
+      //
+      // This is the one wire-visible consumer of the request-derived bound: on
+      // a 2.1.222+ profile a caller asking for a `max_tokens` above the
+      // catalogue's upper limit seeds the default budget from THEIR number
+      // minus one, not from the catalogue's.
+      const requested =
+        request.budgetTokens ??
+        modelOutputTokenLimits(normalizedId, profile, maxTokens).upperLimit - 1;
+      emitted = { budget_tokens: Math.min(maxTokens - 1, requested) };
+      emitted["type"] = "enabled";
+      if (display !== undefined) emitted["display"] = display;
+    }
+  } else if (
+    request?.type === "disabled" &&
+    capabilities.thinking &&
+    !capabilities.rejectsDisabledThinking
+  ) {
+    emitted = { type: "disabled" };
+  }
+
+  // Upstream `Jr = Xn?.type === "enabled" || Xn?.type === "adaptive"
+  //             || Xn === void 0 && U4e(u)`.
+  const extendedThinkingActive =
+    emitted?.["type"] === "enabled" ||
+    emitted?.["type"] === "adaptive" ||
+    (emitted === undefined && capabilities.rejectsDisabledThinking);
+
+  return Object.freeze({
+    emitted: emitted === undefined ? undefined : Object.freeze(emitted),
+    requestActive,
+    extendedThinkingActive,
+  });
+}