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

package/src/anti-verbosity.ts

@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type {
+  AntiVerbosityPolicy,
+  AntiVerbositySection,
+  ClaudeCodeProtocolProfile,
+} from "./contracts.js";
+import { ClaudeCodeWireError } from "./contracts.js";
+import { normalizeModelId } from "./model-identity.js";
+import { CLAUDE_CODE_2_1_195_PROFILE } from "./profiles/claude-code-2.1.195.js";
+
+/**
+ * The genuine client's anti-verbosity system-prompt section, and the three-way
+ * selector that chooses between its variants.
+ *
+ * Upstream this is `ytm(e)` at byte offset 238083640 of the
+ * pinned client build. The four strings below were not transcribed by hand: they
+ * were produced by executing the client's own template literals against stubbed
+ * predicates. The forensic dump tooling collapses non-printable runs and so
+ * cannot be trusted for whitespace inside a template literal; the branch-3
+ * heading in particular is followed by a newline, not a space, which a
+ * dump-based reading got wrong.
+ *
+ * The package EXPOSES this text and never injects it. `buildClaudeCodeRequest`
+ * does not consult this module. The genuine client assembles a large system
+ * prompt from many sections and this package models only the protocol envelope,
+ * so silently adding one section would produce a body matching neither the
+ * client nor the caller's intent. This is the same boundary already settled for
+ * `defaultEffort` and for cache-breakpoint placement: expose, let the caller
+ * decide.
+ */
+
+/** Mirrors upstream defaults: a stock first-party install reports both false. */
+export const DEFAULT_ANTI_VERBOSITY_POLICY: AntiVerbosityPolicy = Object.freeze(
+  {
+    briefModeEnabled: false,
+    pewterOwlToolEnabled: false,
+  },
+);
+
+/**
+ * Branch 1 with upstream `htm` true, which is the default because `htm` is
+ * `!(isBriefEnabled() || pewterOwlTool())`. Carries the extra paragraph about
+ * text written between tool calls.
+ */
+export const COMMUNICATING_WITH_THE_USER_FULL =
+  "# Communicating with the user\n" +
+  "\n" +
+  "Your text output is what the user reads; they usually can't see your thinking or the raw tool results. Write it for a teammate who stepped away and is catching up, not for a log file: they don't know the codenames or shorthand you created along the way, and they didn't watch your process unfold. Before your first tool call, say in a sentence what you're about to do; while working, give brief updates when you find something load-bearing or change direction.\n" +
+  "\n" +
+  "Text you write between tool calls may not be shown to the user. Everything the user needs from this turn — answers, summaries, findings, conclusions, deliverables — must be in the final text message of your turn, with no tool calls after it. Keep text between tool calls to brief status notes. If something important appeared only mid-turn or in your thinking, restate it in that final message.\n" +
+  "\n" +
+  'Lead with the outcome. Your first sentence after finishing should answer "what happened" or "what did you find" — the thing the user would ask for if they said "just give me the TLDR." Supporting detail and reasoning come after, for readers who want them.\n' +
+  "\n" +
+  "Being readable and being concise are different things, and readable matters more. If the user has to reread your summary or ask you to explain, any time saved by brevity is gone. The way to keep output short is to be selective about what you include (drop details that don't change what the reader would do next), not to compress the writing into fragments, abbreviations, arrow chains like `A → B → fails`, or jargon. What you do include, write in complete sentences with the technical terms spelled out. Don't make the reader cross-reference labels or numbering you invented earlier; say what you mean in place.\n" +
+  "\n" +
+  "Match the response to the question: a simple question gets a direct answer in prose, not headers and sections. Use tables only for short enumerable facts, with explanations in the surrounding prose rather than the cells. Calibrate to the user — a bit tighter for an expert, more explanatory for someone newer.\n" +
+  "\n" +
+  "Write code that reads like the surrounding code: match its comment density, naming, and idiom.\n" +
+  "Only write a code comment to state a constraint the code itself can't show — never to say where it came from, what the next line does, or why your change is correct; that's you talking to the reviewer, not the next reader, and it's noise the moment the PR merges.";
+
+/** Branch 1 with upstream `htm` false: brief mode or the pewter-owl tool is on. */
+export const COMMUNICATING_WITH_THE_USER_CONDENSED =
+  "# Communicating with the user\n" +
+  "\n" +
+  "Your text output is what the user reads between tool calls; they usually can't see your thinking or the raw tool results. Write it for a teammate who stepped away and is catching up, not for a log file: they don't know the codenames or shorthand you created along the way, and they didn't watch your process unfold. Before your first tool call, say in a sentence what you're about to do; while working, give brief updates when you find something load-bearing or change direction.\n" +
+  "\n" +
+  'Lead with the outcome. Your first sentence after finishing should answer "what happened" or "what did you find" — the thing the user would ask for if they said "just give me the TLDR." Supporting detail and reasoning come after, for readers who want them.\n' +
+  "\n" +
+  "Being readable and being concise are different things, and readable matters more. If the user has to reread your summary or ask you to explain, any time saved by brevity is gone. The way to keep output short is to be selective about what you include (drop details that don't change what the reader would do next), not to compress the writing into fragments, abbreviations, arrow chains like `A → B → fails`, or jargon. What you do include, write in complete sentences with the technical terms spelled out. Don't make the reader cross-reference labels or numbering you invented earlier; say what you mean in place.\n" +
+  "\n" +
+  "Match the response to the question: a simple question gets a direct answer in prose, not headers and sections. Use tables only for short enumerable facts, with explanations in the surrounding prose rather than the cells. Calibrate to the user — a bit tighter for an expert, more explanatory for someone newer.\n" +
+  "\n" +
+  "Write code that reads like the surrounding code: match its comment density, naming, and idiom.\n" +
+  "Only write a code comment to state a constraint the code itself can't show — never to say where it came from, what the next line does, or why your change is correct; that's you talking to the reviewer, not the next reader, and it's noise the moment the PR merges.";
+
+/** Branch 2, upstream `ph(e)` true. A single sentence. */
+export const LEAN_SECTION =
+  "Write code that reads like the surrounding code: match its comment density, naming, and idiom.";
+
+/** Branch 3, the fallthrough. */
+export const TEXT_OUTPUT_SECTION =
+  "# Text output (does not apply to tool calls)\n" +
+  "Assume users can't see most tool calls or thinking — only your text output. Before your first tool call, state in one sentence what you're about to do. While working, give short updates at key moments: when you find something, when you change direction, or when you hit a blocker. Brief is good — silent is not. One sentence per update is almost always enough.\n" +
+  "\n" +
+  "Don't narrate your internal deliberation. User-facing text should be relevant communication to the user, not a running commentary on your thought process. State results and decisions directly, and focus user-facing text on relevant updates for the user.\n" +
+  "\n" +
+  "When you do write updates, write so the reader can pick up cold: complete sentences, no unexplained jargon or shorthand from earlier in the session. But keep it tight — a clear sentence is better than a clear paragraph.\n" +
+  "\n" +
+  "End-of-turn summary: one or two sentences. What changed and what's next. Nothing else.\n" +
+  "\n" +
+  "Match responses to the task: a simple question gets a direct answer, not headers and sections.\n" +
+  "\n" +
+  "In code: default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max. Don't create planning, decision, or analysis documents unless the user asks for them — work from conversation context, not intermediate files.";
+
+/**
+ * SHA-256 of each constant as executed from the genuine client. A test pins
+ * these so any edit to the text above fails loudly rather than silently
+ * shipping a divergent prompt.
+ */
+export const ANTI_VERBOSITY_DIGESTS = Object.freeze({
+  communicatingWithTheUserFull:
+    "41a8a87303e6f6f8224906daf9741fd6be495b79400854d92078991d15e9c56c",
+  communicatingWithTheUserCondensed:
+    "7028dc6d1492b7616b9b5f2f58416c09a0db5cd671f1032fbaeb9120ad51437b",
+  lean: "ee43af37398581e92bde06d341c98c7b7a9ff6c56023c2bc17b9feaf2d6e31ea",
+  textOutput:
+    "c184a5d4b4b6a0fc374a37c69f72937abf38bcccaa2d0cce0427968fcda3ccc7",
+});
+
+/** Upstream `i_e`, deliberately applied to the RAW caller string. */
+const EAP_PATTERN = /-eap($|\[)/iu;
+
+function catalogueCapability(
+  normalizedId: string,
+  capability: string,
+  profile: ClaudeCodeProtocolProfile,
+): boolean {
+  if (!Object.hasOwn(profile.supportedModels, normalizedId)) return false;
+  return (
+    profile.supportedModels[normalizedId]?.capabilities.includes(capability) ===
+    true
+  );
+}
+
+/**
+ * Upstream `Mte`. This is one of the few places where the catalogue capability
+ * array is genuinely load-bearing: unlike the nine model-capability predicates,
+ * `Mte` has no provider fallback, so the membership test decides the result.
+ */
+function hasFableMitigations(
+  normalizedId: string,
+  profile: ClaudeCodeProtocolProfile,
+): boolean {
+  return (
+    catalogueCapability(normalizedId, "fable_5_mitigations", profile) ||
+    normalizedId === "claude-mythos-5"
+  );
+}
+
+/**
+ * Upstream `Kkd`. Its trailing `return !td()` is false on the first-party
+ * provider this profile pins, so an unrecognised identifier falls through to
+ * the lean branch rather than the text-output branch.
+ *
+ * Upstream also carries `|| t === "claude-mythos-5"` beside the
+ * `lean_prompt` test. It is omitted here because it is unreachable: the only
+ * caller tests `hasFableMitigations` first, which already claims mythos-5 for
+ * the communicating-with-the-user branch. Upstream shares `Kkd` with other
+ * call sites and so still needs it. Restore it if this helper ever gains a
+ * second caller.
+ */
+function usesTextOutputSection(
+  rawModel: string,
+  profile: ClaudeCodeProtocolProfile,
+): boolean {
+  if (EAP_PATTERN.test(rawModel)) return false;
+  const id = normalizeModelId(rawModel);
+  if (catalogueCapability(id, "lean_prompt", profile)) return false;
+  return (
+    id.includes("claude-3-") ||
+    id.includes("haiku") ||
+    id.includes("sonnet") ||
+    id === "claude-opus-4-0" ||
+    id === "claude-opus-4-1" ||
+    id === "claude-opus-4-5" ||
+    id === "claude-opus-4-6" ||
+    id === "claude-opus-4-7"
+  );
+}
+
+/**
+ * Reports which branch of upstream `ytm` a model selects.
+ *
+ * Upstream `gtm` is `return !1`, so branch 1 is gated on `Mte` alone. Note
+ * that `ytm` passes the NORMALISED id to `Mte` but the RAW caller string to
+ * `ph`, because `ph` reaches `i_e`, which must see an unnormalised
+ * `-eap` suffix. That asymmetry is reproduced here.
+ */
+export function selectAntiVerbositySection(
+  rawModel: string,
+  profile: ClaudeCodeProtocolProfile = CLAUDE_CODE_2_1_195_PROFILE,
+): AntiVerbositySection {
+  if (typeof rawModel !== "string" || rawModel.length === 0) {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  if (hasFableMitigations(normalizeModelId(rawModel), profile)) {
+    return "communicating-with-the-user";
+  }
+  return usesTextOutputSection(rawModel, profile) ? "text-output" : "lean";
+}
+
+/** Returns the exact section text the genuine client would emit for a model. */
+export function antiVerbosityText(
+  rawModel: string,
+  policy: AntiVerbosityPolicy = DEFAULT_ANTI_VERBOSITY_POLICY,
+  profile: ClaudeCodeProtocolProfile = CLAUDE_CODE_2_1_195_PROFILE,
+): string {
+  // Validated eagerly, and for every section rather than only the one that
+  // reads it, so a malformed policy fails the same way regardless of which
+  // model it is paired with. `selectAntiVerbositySection` validates its own
+  // argument the same way despite the declared types, because callers reach
+  // this module across an untyped boundary.
+  const candidate: unknown = policy;
+  if (candidate === null || typeof candidate !== "object") {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  const brief: unknown = Reflect.get(candidate, "briefModeEnabled");
+  const pewterOwl: unknown = Reflect.get(candidate, "pewterOwlToolEnabled");
+  if (typeof brief !== "boolean" || typeof pewterOwl !== "boolean") {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  const section = selectAntiVerbositySection(rawModel, profile);
+  if (section === "lean") return LEAN_SECTION;
+  if (section === "text-output") return TEXT_OUTPUT_SECTION;
+  return brief || pewterOwl
+    ? COMMUNICATING_WITH_THE_USER_CONDENSED
+    : COMMUNICATING_WITH_THE_USER_FULL;
+}

package/src/beta-registry.ts

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+interface BetaRegistryEntry {
+  readonly featureKey: string;
+  readonly header: string;
+}
+
+function deepFreeze<T>(value: T): T {
+  if (value !== null && typeof value === "object") {
+    for (const key of Reflect.ownKeys(value)) {
+      deepFreeze(Reflect.get(value, key));
+    }
+    Object.freeze(value);
+  }
+  return value;
+}
+
+/** Genuine-client beta registry, upstream `Udd`. */
+export const BETA_REGISTRY = deepFreeze({
+  CLAUDE_CODE: { featureKey: "claude_code", header: "claude-code-20250219" }, // Y2e
+  OAUTH_AUTH: { featureKey: "oauth_auth", header: "oauth-2025-04-20" }, // qIe
+  INTERLEAVED_THINKING: {
+    featureKey: "interleaved_thinking",
+    header: "interleaved-thinking-2025-05-14",
+  }, // Gnt
+  LONG_CONTEXT: { featureKey: "long_context", header: "context-1m-2025-08-07" }, // FY
+  CONTEXT_MANAGEMENT: {
+    featureKey: "context_management",
+    header: "context-management-2025-06-27",
+  }, // X2e
+  STRUCTURED_OUTPUTS: {
+    featureKey: "structured_outputs",
+    header: "structured-outputs-2025-12-15",
+  }, // lte
+  WEB_SEARCH: { featureKey: "web_search", header: "web-search-2025-03-05" }, // IPt
+  ADVANCED_TOOL_USE: {
+    featureKey: "tool_search",
+    header: "advanced-tool-use-2025-11-20",
+  }, // p2r
+  TOOL_SEARCH: {
+    featureKey: "tool_search",
+    header: "tool-search-tool-2025-10-19",
+  }, // xPt
+  EFFORT: { featureKey: "effort", header: "effort-2025-11-24" }, // Wnt
+  TASK_BUDGETS: {
+    featureKey: "task_budgets",
+    header: "task-budgets-2026-03-13",
+  }, // lAn
+  PROMPT_CACHING_SCOPE: {
+    featureKey: "prompt_caching_scope",
+    header: "prompt-caching-scope-2026-01-05",
+  }, // qnt
+  EXTENDED_CACHE_TTL: {
+    featureKey: "extended_cache_ttl",
+    header: "extended-cache-ttl-2025-04-11",
+  }, // J2e
+  SPEED: { featureKey: "speed", header: "fast-mode-2026-02-01" }, // Vnt
+  REDACT_THINKING: {
+    featureKey: "redact_thinking",
+    header: "redact-thinking-2026-02-12",
+  }, // kPt
+  THINKING_TOKEN_COUNT: {
+    featureKey: "thinking_token_count",
+    header: "thinking-token-count-2026-05-13",
+  }, // cAn
+  NARRATION_SUMMARIES: {
+    featureKey: "narration_summaries",
+    header: "summarize-connector-text-2026-03-13",
+  }, // RPt
+  AFK_MODE: { featureKey: "afk_mode", header: "afk-mode-2026-01-31" }, // T0
+  ADVISOR_TOOL: {
+    featureKey: "advisor_tool",
+    header: "advisor-tool-2026-03-01",
+  }, // f2r
+  CACHE_DIAGNOSIS: {
+    featureKey: "cache_diagnosis",
+    header: "cache-diagnosis-2026-04-07",
+  }, // fye
+  CONTEXT_HINT: {
+    featureKey: "context_hint",
+    header: "context-hint-2026-04-09",
+  }, // m2r
+  MCP_SERVERS: {
+    featureKey: "mcp_servers",
+    header: "mcp-servers-2025-12-04",
+  }, // g2r
+  FILES_API: { featureKey: "files_api", header: "files-api-2025-04-14" }, // h2r
+  ENVIRONMENTS: {
+    featureKey: "environments",
+    header: "environments-2025-11-01",
+  }, // y2r
+  CCR_BYOC: { featureKey: "ccr_byoc", header: "ccr-byoc-2025-07-29" }, // _2r
+  MID_CONVERSATION_SYSTEM: {
+    featureKey: "mid_conversation_system",
+    header: "mid-conversation-system-2026-04-07",
+  }, // jY
+  SERVER_SIDE_FALLBACK: {
+    featureKey: "server_side_fallback",
+    header: "server-side-fallback-2026-06-01",
+  }, // r1
+  FALLBACK_CREDIT: {
+    featureKey: "fallback_credit",
+    header: "fallback-credit-2026-06-01",
+  }, // o1
+} satisfies Record<string, BetaRegistryEntry>);
+
+// Reserved for later work packages; upstream `Pvi` third-party filtering.
+export const THIRD_PARTY_ALLOWED_BETAS: ReadonlySet<string> = Object.freeze(
+  new Set([
+    BETA_REGISTRY.CLAUDE_CODE.header,
+    BETA_REGISTRY.INTERLEAVED_THINKING.header,
+    BETA_REGISTRY.LONG_CONTEXT.header,
+    BETA_REGISTRY.CONTEXT_MANAGEMENT.header,
+    BETA_REGISTRY.STRUCTURED_OUTPUTS.header,
+    BETA_REGISTRY.WEB_SEARCH.header,
+    BETA_REGISTRY.EFFORT.header,
+    BETA_REGISTRY.TOOL_SEARCH.header,
+    BETA_REGISTRY.AFK_MODE.header,
+    BETA_REGISTRY.FALLBACK_CREDIT.header,
+  ]),
+);
+
+// Reserved for later work packages; upstream `S2r` provider filtering.
+export const BEDROCK_UNSUPPORTED_BETAS: ReadonlySet<string> = Object.freeze(
+  new Set([
+    BETA_REGISTRY.INTERLEAVED_THINKING.header,
+    BETA_REGISTRY.LONG_CONTEXT.header,
+    BETA_REGISTRY.TOOL_SEARCH.header,
+  ]),
+);
+
+// Reserved for later work packages; upstream `E2r` count-tokens selection.
+export const COUNT_TOKENS_BETAS: ReadonlySet<string> = Object.freeze(
+  new Set([
+    BETA_REGISTRY.CLAUDE_CODE.header,
+    BETA_REGISTRY.INTERLEAVED_THINKING.header,
+    BETA_REGISTRY.CONTEXT_MANAGEMENT.header,
+    BETA_REGISTRY.OAUTH_AUTH.header,
+  ]),
+);

package/src/betas.ts

@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { BETA_REGISTRY } from "./beta-registry.js";
+import type {
+  ClaudeCodeCapabilities,
+  ClaudeCodeProtocolProfile,
+} from "./contracts.js";
+import { ClaudeCodeWireError } from "./contracts.js";
+import {
+  supportsMidConversationSystem,
+  supportsStructuredOutputs,
+} from "./model-capabilities.js";
+import { CLAUDE_CODE_2_1_195_PROFILE } from "./profiles/claude-code-2.1.195.js";
+
+/*
+ * Provenance. The emitted order is a port of the genuine client's base beta set
+ * `$9r` (byte offset 227387921), followed by the gated pushes the request
+ * builder performs afterwards (bytes 238153535-238155672). The identifiers
+ * themselves come from registry `Udd`, ported verbatim as `BETA_REGISTRY`.
+ *
+ * The order is EMERGENT, not declared: upstream neither sorts the array nor
+ * keeps a canonical list, so the sequence below is load-bearing and must not be
+ * reordered for tidiness. `docs/source-trace.md` records the same fact under
+ * "Beta registry and push order".
+ */
+export interface ComposeBetasInput {
+  readonly rawModel: string;
+  readonly normalizedId: string;
+  readonly capabilities: ClaudeCodeCapabilities;
+  readonly thinkingDisplayActive: boolean;
+  readonly cacheTtl?: "5m" | "1h" | null;
+  readonly speed?: "standard" | "fast" | null;
+  /**
+   * Package extension, not observed upstream behaviour. Consumer-supplied beta
+   * identifiers appended AFTER the derived canonical set. See
+   * `docs/source-trace.md`, governance ledger L10.
+   */
+  readonly additionalBetas?: readonly string[];
+  /**
+   * Package extension, not observed upstream behaviour. Beta identifiers
+   * removed from the emitted set AFTER composition and AFTER the
+   * `additionalBetas` merge, so suppression beats addition. An identifier that
+   * is not in the composed set is a silent no-op. See `docs/source-trace.md`,
+   * governance ledger L14.
+   */
+  readonly suppressBetas?: readonly string[];
+  /**
+   * Package extension, not observed upstream behaviour. Forces (`true`) or
+   * suppresses (`false`) the 1M-context beta for this request, overriding the
+   * `[1m]` model marker. See `docs/source-trace.md`, governance ledger L10.
+   */
+  readonly use1MContextOverride?: boolean;
+}
+
+/**
+ * Reports the emitted beta set together with the identifiers `suppressBetas`
+ * actually removed. `suppressedBetaNames` is empty when the seam is unused or
+ * matched nothing, which is what keeps the evidence key absent for every
+ * request built before the seam existed.
+ */
+export interface ComposedBetas {
+  readonly betas: readonly string[];
+  readonly suppressedBetaNames: readonly string[];
+}
+
+/**
+ * Bounds a caller-supplied beta list (`additionalBetas` and `suppressBetas`
+ * share these rules verbatim). The header is a comma-joined single
+ * field, so a comma, control character, or whitespace in an entry would let a
+ * caller synthesize extra beta values (or, with CR/LF, an entirely separate
+ * header). The allowlist below is deliberately narrower than the observed
+ * upstream identifiers require, because every genuine beta name in
+ * `BETA_REGISTRY` matches it.
+ */
+const ADDITIONAL_BETA_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const MAX_ADDITIONAL_BETA_LENGTH = 128;
+const MAX_ADDITIONAL_BETAS = 32;
+
+function validateAdditionalBetas(value: unknown): readonly string[] {
+  if (!Array.isArray(value) || value.length > MAX_ADDITIONAL_BETAS) {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  return value.map((entry: unknown): string => {
+    if (
+      typeof entry !== "string" ||
+      entry.length === 0 ||
+      entry.length > MAX_ADDITIONAL_BETA_LENGTH ||
+      !ADDITIONAL_BETA_PATTERN.test(entry)
+    ) {
+      throw new ClaudeCodeWireError("INVALID_INPUT");
+    }
+    return entry;
+  });
+}
+
+const NO_SUPPRESSED_BETAS: readonly string[] = Object.freeze([]);
+
+export function composeBetas(
+  input: ComposeBetasInput,
+  profile: ClaudeCodeProtocolProfile = CLAUDE_CODE_2_1_195_PROFILE,
+): readonly string[] {
+  return composeBetasWithAudit(input, profile).betas;
+}
+
+export function composeBetasWithAudit(
+  input: ComposeBetasInput,
+  profile: ClaudeCodeProtocolProfile = CLAUDE_CODE_2_1_195_PROFILE,
+): ComposedBetas {
+  const out: string[] = [];
+  const policy = profile.betaPolicy;
+  const experimental = policy.experimentalBetasEnabled;
+
+  if (!input.normalizedId.includes("haiku"))
+    out.push(BETA_REGISTRY.CLAUDE_CODE.header);
+  if (policy.oauthAuthenticated) out.push(BETA_REGISTRY.OAUTH_AUTH.header);
+  // Package extension: `use1MContextOverride` replaces the model-marker gate
+  // for this request. The profile gate still applies, so an override cannot
+  // enable a beta the pinned profile declares unavailable.
+  const oneMillionRequested =
+    input.use1MContextOverride ?? /\[1m\]/iu.test(input.rawModel);
+  if (policy.oneMillionContextEnabled && oneMillionRequested) {
+    out.push(BETA_REGISTRY.LONG_CONTEXT.header);
+  }
+  if (
+    policy.interleavedThinkingEnabled &&
+    input.capabilities.interleavedThinking
+  ) {
+    out.push(BETA_REGISTRY.INTERLEAVED_THINKING.header);
+  }
+  if (
+    experimental &&
+    input.capabilities.interleavedThinking &&
+    policy.interactive &&
+    !policy.thinkingSummariesShown &&
+    !input.thinkingDisplayActive
+  ) {
+    out.push(BETA_REGISTRY.REDACT_THINKING.header);
+  }
+  if (
+    policy.thinkingTokenCountEnabled &&
+    experimental &&
+    input.capabilities.interleavedThinking
+  ) {
+    out.push(BETA_REGISTRY.THINKING_TOKEN_COUNT.header);
+  }
+  if (experimental && policy.narrationSummariesEnabled)
+    out.push(BETA_REGISTRY.NARRATION_SUMMARIES.header);
+  if (experimental && input.capabilities.contextManagement)
+    out.push(BETA_REGISTRY.CONTEXT_MANAGEMENT.header);
+  if (
+    experimental &&
+    supportsStructuredOutputs(input.normalizedId) &&
+    policy.structuredOutputsEnabled
+  ) {
+    out.push(BETA_REGISTRY.STRUCTURED_OUTPUTS.header);
+  }
+
+  // No web-search beta: upstream pushes it only for vertex and foundry.
+  if (experimental) out.push(BETA_REGISTRY.PROMPT_CACHING_SCOPE.header);
+  if (supportsMidConversationSystem(input.normalizedId))
+    out.push(BETA_REGISTRY.MID_CONVERSATION_SYSTEM.header);
+  if (input.capabilities.effort) out.push(BETA_REGISTRY.EFFORT.header);
+
+  if (input.speed === "fast" && !out.includes(BETA_REGISTRY.SPEED.header)) {
+    out.push(BETA_REGISTRY.SPEED.header);
+  }
+  if (policy.afkModeEnabled && !out.includes(BETA_REGISTRY.AFK_MODE.header)) {
+    out.push(BETA_REGISTRY.AFK_MODE.header);
+  }
+  if (
+    input.cacheTtl === "1h" &&
+    experimental &&
+    !out.includes(BETA_REGISTRY.EXTENDED_CACHE_TTL.header)
+  ) {
+    out.push(BETA_REGISTRY.EXTENDED_CACHE_TTL.header);
+  }
+  if (profile.contextHintEnabled) out.push(BETA_REGISTRY.CONTEXT_HINT.header);
+  if (
+    policy.cacheDiagnosisEnabled &&
+    !out.includes(BETA_REGISTRY.CACHE_DIAGNOSIS.header)
+  ) {
+    out.push(BETA_REGISTRY.CACHE_DIAGNOSIS.header);
+  }
+
+  // No advisor-tool beta: upstream has no observed unconditional push site.
+
+  // Package extension. Canonical, upstream-derived identifiers always precede
+  // caller-supplied ones, and a caller entry that duplicates an already-emitted
+  // identifier is dropped rather than reordering the canonical prefix.
+  if (input.additionalBetas !== undefined) {
+    for (const beta of validateAdditionalBetas(input.additionalBetas)) {
+      if (!out.includes(beta)) out.push(beta);
+    }
+  }
+
+  // Package extension. The suppression filter is deliberately LAST: it runs
+  // after the canonical composition and after the `additionalBetas` merge, so
+  // an identifier named by both seams does not reach the wire. Removal is
+  // reported in composed order, never in caller order, and an identifier that
+  // was never composed is a silent no-op because a consumer cannot know which
+  // betas this package derives for a given model.
+  if (input.suppressBetas === undefined) {
+    return Object.freeze({
+      betas: Object.freeze(out),
+      suppressedBetaNames: NO_SUPPRESSED_BETAS,
+    });
+  }
+  const suppressed = new Set(validateAdditionalBetas(input.suppressBetas));
+  const kept: string[] = [];
+  const removed: string[] = [];
+  for (const beta of out) {
+    if (suppressed.has(beta)) removed.push(beta);
+    else kept.push(beta);
+  }
+  return Object.freeze({
+    betas: Object.freeze(kept),
+    suppressedBetaNames: Object.freeze(removed),
+  });
+}