@tormentalabs/claude-code-wire-compat 0.5.0 → 0.7.0-rc.1

package/src/thinking.ts

@@ -70,7 +70,12 @@ export interface ResolvedThinking {
    * suppresses `temperature`, matching upstream `nr`.
    */
   readonly requestActive: boolean;
-  /** Whether `tool_choice` of type `tool` must be demoted to `auto`. */
+  /**
+   * Whether a forced `tool_choice` (type `tool` or `any`) must be demoted to
+   * `auto`. Upstream demotes only `tool`; demoting `any` as well is a
+   * deliberate divergence, because the API rejects any forced tool choice
+   * while extended thinking is on (see `MEMORY.md`, 2026-09-24).
+   */
   readonly extendedThinkingActive: boolean;
 }
 
@@ -275,6 +280,92 @@ export function isThinkingDisplayActive(
   );
 }
 
+/**
+ * The three thinking types the resolver can emit, or `undefined` when no
+ * `thinking` object reaches the wire at all.
+ */
+export type ResolvedThinkingType = "adaptive" | "enabled" | "disabled";
+
+/**
+ * Narrows an unvalidated caller `thinking` value to its `type` literal.
+ *
+ * Deliberately tolerant of unvalidated input for the same reason
+ * `isThinkingDisplayActive` is: beta composition asks this question before
+ * `buildCanonicalBody` has validated the shape. Anything malformed answers
+ * `undefined` here and is rejected later by the body validator.
+ */
+function thinkingRequestType(
+  request: unknown,
+): ThinkingRequest["type"] | undefined {
+  if (request === null || typeof request !== "object") return undefined;
+  const type = (request as Record<string, unknown>)["type"];
+  if (type === "enabled" || type === "adaptive" || type === "disabled") {
+    return type;
+  }
+  return undefined;
+}
+
+/**
+ * Decides WHICH thinking object `resolveThinking` will emit, without building
+ * it.
+ *
+ * Split out of `resolveThinking` so that beta composition and body emission
+ * answer the same question from one place. A second, independently written
+ * copy of this predicate is exactly how a beta header and the body field it
+ * is coupled to drift apart.
+ */
+export function resolveThinkingType(
+  requestType: ThinkingRequest["type"] | undefined,
+  capabilities: ClaudeCodeCapabilities,
+): ResolvedThinkingType | undefined {
+  const requestActive = requestType !== undefined && requestType !== "disabled";
+  if (requestActive && capabilities.thinking) {
+    return capabilities.adaptiveThinking ? "adaptive" : "enabled";
+  }
+  if (
+    requestType === "disabled" &&
+    capabilities.thinking &&
+    !capabilities.rejectsDisabledThinking
+  ) {
+    return "disabled";
+  }
+  return undefined;
+}
+
+/**
+ * Upstream `ac = Kg && Fg() && iQt(model)`, the predicate the 2.1.280 thinking
+ * push sites gate on, with `Fg()` (`experimentalBetasEnabled`) factored OUT.
+ *
+ * Every push site conjoins the experimental gate itself, so folding it in here
+ * would count it twice and make the one site that legitimately does not want it
+ * impossible to express. `Kg`'s environment-disable term is not modelled: this
+ * package reads no environment.
+ *
+ * This is deliberately NOT `ResolvedThinking.requestActive`. That one is true
+ * whenever the caller asked for thinking at all, including for a model whose
+ * capabilities emit no thinking object — which would ship a thinking beta
+ * header for a body that carries no thinking block.
+ *
+ * Upstream `ac` conjoins only the interleaved predicate `iQt`; requiring a
+ * resolved `"adaptive"`/`"enabled"` type additionally requires
+ * `capabilities.thinking`, one conjunct more than upstream. That extra term is
+ * unobservable in practice: `supportsThinking` and `supportsInterleavedThinking`
+ * in `model-capabilities.ts` are the same expression, so no derived capability
+ * set separates them. Only an explicit caller capability override can, and then
+ * the package declines to announce a thinking beta for a request whose body
+ * will carry no thinking object.
+ */
+export function isThinkingActive(
+  request: unknown,
+  capabilities: ClaudeCodeCapabilities,
+): boolean {
+  const type = resolveThinkingType(thinkingRequestType(request), capabilities);
+  return (
+    (type === "adaptive" || type === "enabled") &&
+    capabilities.interleavedThinking
+  );
+}
+
 /**
  * Resolves the caller's thinking request into the object the genuine client
  * would put on the wire.
@@ -283,6 +374,13 @@ export function isThinkingDisplayActive(
  * 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.
+ *
+ * `displayOverride` is the body-side half of beta push site 12b
+ * (`thinkingDisplayOverride` from `composeBetasWithAudit`); it is not
+ * caller-facing, which is why `ThinkingDisplay` stays unwidened. When both it
+ * and a caller display are present the override wins -- a combination the
+ * composition guard makes unreachable, since site 12b requires that the caller
+ * supplied no display.
  */
 export function resolveThinking(
   request: ThinkingRequest | undefined,
@@ -291,6 +389,7 @@ export function resolveThinking(
   betaPolicy: ClaudeCodeBetaPolicy,
   maxTokens: number,
   profile: ClaudeCodeProtocolProfile = CLAUDE_CODE_2_1_195_PROFILE,
+  displayOverride?: "updates",
 ): ResolvedThinking {
   // Upstream `nr = n.type !== "disabled" && !CLAUDE_CODE_DISABLE_THINKING`.
   const requestActive = request !== undefined && request.type !== "disabled";
@@ -301,38 +400,61 @@ export function resolveThinking(
   );
   const display = displayActive ? request?.display : undefined;
 
+  const resolvedType = resolveThinkingType(request?.type, capabilities);
+
   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
-  ) {
+  if (resolvedType === "adaptive") {
+    emitted = { type: "adaptive" };
+    if (display !== undefined) emitted["display"] = display;
+    // Assignment, not reconstruction: an existing key keeps its position and a
+    // new one appends last, matching upstream `{...yc, display: "updates"}`.
+    if (displayOverride !== undefined) emitted["display"] = displayOverride;
+  } else if (resolvedType === "enabled") {
+    // Transcribed from the 2.1.280 analysis document:
+    //   let hf = mlo(_e);
+    //   if (r.type === "enabled" && r.budgetTokens !== void 0) hf = r.budgetTokens;
+    //   hf = Math.max(1024, Math.min(Rv - 1, hf));
+    // The default budget is the model's upper limit minus one. The caller's
+    // `budgetTokens` replaces it only when the caller itself declared an
+    // `enabled` request -- the guard reads the caller's raw `type`, not the
+    // resolved one, so an `adaptive` request downgraded to `enabled` on a
+    // model without adaptive thinking ignores its budget. The result is
+    // clamped to the emitted `max_tokens` minus one, and the floor of 1024 is
+    // applied after that clamp, so the floor wins when the two conflict.
+    //
+    // No older analysis document in this repository transcribes this
+    // computation at all, so the floor and the type guard are evidenced for
+    // 2.1.280 only. They are applied to every profile as one shared
+    // behaviour -- the same deliberate choice already made for the model-id
+    // normalizer ladder -- and nothing here asserts whether older clients
+    // had them.
+    //
+    // 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 callerBudget =
+      request?.type === "enabled" ? request.budgetTokens : undefined;
+    const requested =
+      callerBudget ??
+      modelOutputTokenLimits(normalizedId, profile, maxTokens).upperLimit - 1;
+    emitted = {
+      budget_tokens: Math.max(1024, Math.min(maxTokens - 1, requested)),
+    };
+    emitted["type"] = "enabled";
+    if (display !== undefined) emitted["display"] = display;
+    // Same in-place assignment as the adaptive arm: order stays
+    // `budget_tokens, type, display`.
+    if (displayOverride !== undefined) emitted["display"] = displayOverride;
+  } else if (resolvedType === "disabled") {
     emitted = { type: "disabled" };
   }
 
   // Upstream `Jr = Xn?.type === "enabled" || Xn?.type === "adaptive"
   //             || Xn === void 0 && U4e(u)`.
+  // Upstream uses this to demote `tool_choice` of type `tool`; the
+  // request body also demotes type `any` on it, a documented divergence.
   const extendedThinkingActive =
     emitted?.["type"] === "enabled" ||
     emitted?.["type"] === "adaptive" ||

package/src/unicode.ts

@@ -22,3 +22,74 @@ export function classifySurrogateAt(
   if (unit >= 0xdc00 && unit <= 0xdfff) return "loneSurrogate";
   return "notSurrogate";
 }
+
+export type TextViolationReason = "control-char" | "lone-surrogate";
+
+/**
+ * One character-level policy violation found while screening a string.
+ *
+ * `offset` is the UTF-16 code-unit index of the offending unit and `codeUnit`
+ * is the unit itself. Both are safe diagnostics: offsets are numbers and the
+ * only code units ever reported are control characters or surrogate halves,
+ * never prose content.
+ */
+export interface TextViolation {
+  readonly reason: TextViolationReason;
+  readonly offset: number;
+  readonly codeUnit: number;
+}
+
+/**
+ * Character-level acceptance policy for one string lane.
+ *
+ * `rejectControls` rejects every C0 control except TAB (0x09), LF (0x0A) and
+ * CR (0x0D), plus DEL (0x7F). Lone surrogates are always rejected, rather than
+ * depending on whether a caller serializes or directly encodes the string.
+ */
+export interface TextPolicy {
+  readonly rejectControls: boolean;
+}
+
+/** Body prose: every well-formed UTF-16 string is accepted. */
+export const TEXT_POLICY_PROSE: TextPolicy = Object.freeze({
+  rejectControls: false,
+});
+
+/**
+ * Identifier graph screening: C0 except TAB/LF/CR, plus DEL, plus lone
+ * surrogates. This is exactly the set the graph inspectors rejected before the
+ * shared validator existed.
+ */
+export const TEXT_POLICY_IDENTIFIER: TextPolicy = Object.freeze({
+  rejectControls: true,
+});
+
+/**
+ * Screens one string under `policy`, returning the first violation or null.
+ *
+ * The walk order matches the historical per-module inspectors: at each index
+ * the control check runs before the surrogate check, and a well-formed pair
+ * consumes two code units. `classifySurrogateAt` is the single surrogate
+ * authority; this function never re-implements it.
+ */
+export function inspectText(
+  value: string,
+  policy: TextPolicy,
+): TextViolation | null {
+  for (let index = 0; index < value.length; index += 1) {
+    const unit = value.charCodeAt(index);
+    if (
+      policy.rejectControls &&
+      ((unit <= 0x1f && unit !== 0x09 && unit !== 0x0a && unit !== 0x0d) ||
+        unit === 0x7f)
+    ) {
+      return { reason: "control-char", offset: index, codeUnit: unit };
+    }
+    const classification = classifySurrogateAt(value, index);
+    if (classification === "loneSurrogate") {
+      return { reason: "lone-surrogate", offset: index, codeUnit: unit };
+    }
+    if (classification === "surrogatePair") index += 1;
+  }
+  return null;
+}

package/src/violation.ts

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type { TextViolation } from "./unicode.js";
+
+/*
+ * Safe validation-failure diagnostics (decision P1.T1, D4).
+ *
+ * Every value produced here is safe by construction: reasons come from a
+ * closed set, path segments from a closed vocabulary of schema-defined keys
+ * plus numeric indices and the `*` placeholder for user-controlled keys, and
+ * reported code units only ever come from control or surrogate ranges. No
+ * caller text, key name or excerpt can leak through these fields.
+ */
+
+export const VIOLATION_REASONS: ReadonlySet<string> = new Set([
+  "lone-surrogate",
+  "control-char",
+]);
+
+/**
+ * Schema-defined keys allowed verbatim in a violation path. Any other object
+ * key (tool input names, `input_schema` property names, arbitrary metadata
+ * members) is user-controlled text and is reported as `*`.
+ */
+const PATH_KEY_VOCABULARY: ReadonlySet<string> = new Set([
+  "$schema",
+  "accept",
+  "additionalBetas",
+  "additionalProperties",
+  "anthropicAdditionalProtection",
+  "app",
+  "arch",
+  "accountUuid",
+  "body",
+  "cache_control",
+  "citations",
+  "clientApp",
+  "clientRequestId",
+  "claudeRemoteContainerId",
+  "claudeRemoteSessionId",
+  "content",
+  "context",
+  "crypto",
+  "data",
+  "default",
+  "defer_loading",
+  "description",
+  "deviceId",
+  "document",
+  "effort",
+  "enum",
+  "evidence",
+  "examples",
+  "extraHeaderPolicy",
+  "extraHeaders",
+  "headers",
+  "id",
+  "image",
+  "input",
+  "input_schema",
+  "input_examples",
+  "items",
+  "max_tokens",
+  "maxTokens",
+  "media_type",
+  "messages",
+  "metadata",
+  "metadataOverrides",
+  "method",
+  "model",
+  "name",
+  "os",
+  "output_config",
+  "profileOverride",
+  "properties",
+  "redacted_thinking",
+  "required",
+  "role",
+  "runtime",
+  "runtimeVersion",
+  "search_results",
+  "sessionId",
+  "signature",
+  "source",
+  "stainlessHelper",
+  "stainlessRetryCount",
+  "stop_sequences",
+  "stream",
+  "strict",
+  "system",
+  "text",
+  "thinking",
+  "timing",
+  "title",
+  "tool_name",
+  "tool_reference",
+  "tool_result",
+  "tool_use",
+  "tool_use_id",
+  "tools",
+  "type",
+  "url",
+  "user_id",
+  "userId",
+  "userIdFields",
+]);
+
+const MAX_PATH_SEGMENTS = 16;
+const MAX_PATH_LENGTH = 256;
+const TRUNCATION_MARKER = "...";
+const OPAQUE_SUBTREES: ReadonlySet<string> = new Set([
+  "headers",
+  "input",
+  "input_schema",
+  "input_examples",
+  "metadata",
+  "metadataOverrides",
+  "userIdFields",
+  "extraHeaders",
+  "data",
+  "default",
+  "examples",
+]);
+
+export type ViolationPathSegment = string | number;
+
+function mapSegment(segment: ViolationPathSegment, opaque: boolean): string {
+  if (typeof segment === "number") {
+    return Number.isSafeInteger(segment) &&
+      !Object.is(segment, -0) &&
+      segment >= 0 &&
+      segment <= 999_999
+      ? String(segment)
+      : "*";
+  }
+  return !opaque && PATH_KEY_VOCABULARY.has(segment) ? segment : "*";
+}
+
+/**
+ * Renders a pointer-like path (`/messages/0/content`) from walk segments.
+ * At most 16 segments, then a trailing `/...`; at most 256 characters.
+ */
+export function formatViolationPath(
+  segments: readonly ViolationPathSegment[],
+): string {
+  let path = "";
+  let opaque = false;
+  for (let index = 0; index < segments.length; index += 1) {
+    const segment = mapSegment(segments[index] ?? "*", opaque);
+    const tailLength = index < segments.length - 1 ? 4 : 0;
+    if (
+      index >= MAX_PATH_SEGMENTS ||
+      path.length + 1 + segment.length + tailLength > MAX_PATH_LENGTH
+    ) {
+      return `${path}/${TRUNCATION_MARKER}`;
+    }
+    path += `/${segment}`;
+    opaque ||= segment === "*" || OPAQUE_SUBTREES.has(segment);
+  }
+  return path || "/";
+}
+
+export function isValidViolationReason(value: string): boolean {
+  return VIOLATION_REASONS.has(value);
+}
+
+const PATH_INDEX_SEGMENT = /^(?:0|[1-9]\d{0,5})$/u;
+
+/**
+ * Revalidates a formatted violation path for the redaction allowlist. Every
+ * segment must be a vocabulary key, a decimal index of at most 6 digits, `*`,
+ * or the single trailing truncation marker; the whole string is capped.
+ */
+export function isValidViolationPath(value: string): boolean {
+  if (value.length === 0 || value.length > MAX_PATH_LENGTH) return false;
+  if (!value.startsWith("/")) return false;
+  if (value === "/") return true;
+  const segments = value.slice(1).split("/");
+  if (segments.length > MAX_PATH_SEGMENTS + 1) return false;
+  let opaque = false;
+  for (let index = 0; index < segments.length; index += 1) {
+    const segment = segments[index];
+    if (segment === undefined) return false;
+    if (segment === TRUNCATION_MARKER) return index === segments.length - 1;
+    if (index >= MAX_PATH_SEGMENTS) return false;
+    if (segment === "*") {
+      opaque = true;
+      continue;
+    }
+    if (PATH_INDEX_SEGMENT.test(segment)) continue;
+    if (opaque || !PATH_KEY_VOCABULARY.has(segment)) return false;
+    opaque ||= OPAQUE_SUBTREES.has(segment);
+  }
+  return true;
+}
+
+/** Numeric range guard for `violationCodeUnit`: controls or surrogates only. */
+export function isValidViolationCodeUnit(value: number): boolean {
+  if (!Number.isInteger(value) || Object.is(value, -0) || value < 0)
+    return false;
+  return (
+    value <= 0x1f ||
+    (value >= 0x7f && value <= 0x9f) ||
+    (value >= 0xd800 && value <= 0xdfff)
+  );
+}
+
+/**
+ * Builds the safeDetails record for one text violation found at `path`.
+ * `inKey` distinguishes an offending object key from an offending value.
+ */
+export function violationDetails(
+  violation: TextViolation,
+  path: readonly ViolationPathSegment[],
+  textLength: number,
+  inKey: boolean,
+): Readonly<Record<string, string | number | boolean>> {
+  return {
+    violationReason: violation.reason,
+    violationPath: formatViolationPath(path),
+    violationOffset: violation.offset,
+    violationCodeUnit: violation.codeUnit,
+    violationTextLength: textLength,
+    violationInKey: inKey,
+  };
+}