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

package/src/count-tokens.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { COUNT_TOKENS_BETAS } from "./beta-registry.js";
+import type { Message, ToolDefinition } from "./contracts.js";
+
+/** Upstream SDK `countTokens` endpoint at byte offset 224471633. */
+export const COUNT_TOKENS_ENDPOINT =
+  "https://api.anthropic.com/v1/messages/count_tokens?beta=true" as const;
+
+/** Upstream SDK `countTokens` beta at byte offset 224471633. */
+export const TOKEN_COUNTING_BETA = "token-counting-2024-11-01" as const;
+
+/** Upstream `PMo` used by `P5e` at byte offset 235439559. */
+export const COUNT_TOKENS_THINKING_BUDGET = 1024 as const;
+
+/** Upstream `P5e` empty-message fallback at byte offset 235439559. */
+export const COUNT_TOKENS_EMPTY_MESSAGES = Object.freeze([
+  Object.freeze({ role: "user", content: "foo" }),
+]);
+
+/**
+ * Upstream `Bkl` at byte offset 235438568.
+ *
+ * Decides whether the count-tokens body carries a `thinking` field. Note the
+ * two conjuncts upstream requires and this port preserves: the message role
+ * must be `assistant`, and its content must be an ARRAY. A thinking block on a
+ * user message, or an assistant message whose content is a plain string, does
+ * not qualify.
+ *
+ * Upstream additionally guards each message and block against being a
+ * non-object, because it runs on loosely typed internal history. This port is
+ * reached only through `canonicalCountTokensLists`, which has already proven
+ * every element well formed, so those guards would be unreachable branches.
+ * Restore them only if a caller path is ever added that bypasses that
+ * canonicaliser.
+ */
+export function containsThinkingBlock(messages: readonly Message[]): boolean {
+  return messages.some(
+    (message) =>
+      message.role === "assistant" &&
+      typeof message.content !== "string" &&
+      message.content.some(
+        (block) =>
+          block.type === "thinking" || block.type === "redacted_thinking",
+      ),
+  );
+}
+
+/** Upstream `E2r` filtering in `P5e` at byte offset 235439559. */
+export function filterCountTokensBetas(
+  composedBetas: readonly string[],
+): readonly string[] {
+  return Object.freeze(
+    composedBetas.filter((beta) => COUNT_TOKENS_BETAS.has(beta)),
+  );
+}
+
+/**
+ * Upstream `P5e` wire-body construction at byte offset 235439559.
+ *
+ * Both list arguments MUST already have been canonicalised by
+ * `canonicalCountTokensLists`. Key order is load-bearing: the vendored SDK
+ * destructures `betas` out of the body and object rest preserves the
+ * declaration order of the survivors, leaving `model`, `messages`, `tools`,
+ * then an optional `thinking` on the wire.
+ */
+export function buildCountTokensBody(
+  model: string,
+  messages: readonly Message[],
+  tools: readonly ToolDefinition[],
+): Readonly<Record<string, unknown>> {
+  const body: Record<string, unknown> = {
+    model,
+    messages: messages.length > 0 ? messages : COUNT_TOKENS_EMPTY_MESSAGES,
+    tools,
+  };
+  if (containsThinkingBlock(messages)) {
+    body["thinking"] = {
+      type: "enabled",
+      budget_tokens: COUNT_TOKENS_THINKING_BUDGET,
+    };
+  }
+  return Object.freeze(body);
+}

package/src/fingerprint.ts

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type { ClaudeCodeProtocolProfile, TextBlock } from "./contracts.js";
+import { ClaudeCodeWireError } from "./contracts.js";
+import { profileBehaviors } from "./profile-behaviors.js";
+
+const FINGERPRINT_PREFIX = "59cf53e54c78";
+
+/**
+ * Upstream guard on `cc_prev_req`, transcribed verbatim from the 2.1.233
+ * billing-header builder: the segment is emitted only when the value is
+ * defined AND matches this pattern AND the request is first-party.
+ */
+const PREVIOUS_REQUEST_ID_PATTERN = /^req_[A-Za-z0-9_-]{1,36}$/;
+
+/**
+ * Upstream guard on `cc_prompt_id`, transcribed verbatim from the same builder.
+ * The `i` flag is upstream's, not a relaxation: an upper-case UUID IS emitted.
+ */
+const PROMPT_ID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * The conversation-chaining inputs of the 2.1.233 billing block. Both are the
+ * caller's to supply; see `ClaudeCodeRequestInput.previousRequestId`.
+ */
+export interface BillingChain {
+  readonly previousRequestId?: string;
+  readonly promptId?: string;
+}
+
+function isCryptoProvider(value: unknown): value is Pick<Crypto, "subtle"> {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const subtle: unknown = Reflect.get(value, "subtle");
+  return (
+    typeof subtle === "object" &&
+    subtle !== null &&
+    typeof Reflect.get(subtle, "digest") === "function"
+  );
+}
+
+function getDefaultCrypto(): Pick<Crypto, "subtle"> {
+  const value: unknown = Reflect.get(globalThis, "crypto");
+  if (!isCryptoProvider(value)) {
+    throw new ClaudeCodeWireError("CRYPTO_UNAVAILABLE");
+  }
+  return value;
+}
+
+export async function createBillingFingerprint(
+  firstUserText: string,
+  cliVersion: string,
+  crypto?: Pick<Crypto, "subtle">,
+): Promise<string> {
+  const cryptoProvider = crypto ?? getDefaultCrypto();
+  const material = `${FINGERPRINT_PREFIX}${firstUserText[4] ?? "0"}${firstUserText[7] ?? "0"}${firstUserText[20] ?? "0"}${cliVersion}`;
+  const bytes = new TextEncoder().encode(material);
+
+  let digest: unknown;
+  // Keep this try deliberately narrow so our validation errors are not self-masked.
+  try {
+    digest = await cryptoProvider.subtle.digest("SHA-256", bytes);
+  } catch {
+    throw new ClaudeCodeWireError("CRYPTO_UNAVAILABLE");
+  }
+
+  let digestBytes: Uint8Array;
+  if (digest instanceof ArrayBuffer) {
+    digestBytes = new Uint8Array(digest);
+  } else if (ArrayBuffer.isView(digest)) {
+    digestBytes = new Uint8Array(
+      digest.buffer,
+      digest.byteOffset,
+      digest.byteLength,
+    );
+  } else {
+    // Unvalidated digests silently corrupt billing fingerprints as "" or "000".
+    throw new ClaudeCodeWireError("CRYPTO_UNAVAILABLE");
+  }
+  if (digestBytes.byteLength !== 32) {
+    throw new ClaudeCodeWireError("CRYPTO_UNAVAILABLE");
+  }
+
+  return Array.from(digestBytes, (byte) => byte.toString(16).padStart(2, "0"))
+    .join("")
+    .slice(0, 3);
+}
+
+/**
+ * Builds the canonical billing block (system index 0).
+ *
+ * The upstream 2.1.233 builder assembles a fixed prefix followed by five
+ * optional segments, each one space-prefixed and semicolon-terminated, in this
+ * order: `cch`, `cc_workload`, `cc_is_subagent`, `cc_prev_req`, `cc_prompt_id`.
+ *
+ * Three of those five are settled for every request this package emits:
+ *
+ *   - `cch=00000;` is always present. Its gate is the first-party predicate,
+ *     which is true for the Anthropic provider this package targets, and its
+ *     value is static — the upstream hashed-cache path is dead code.
+ *   - `cc_workload` and `cc_is_subagent` are never emitted. They describe a
+ *     background workload and a sub-agent session respectively; this package
+ *     models the CLI's main session, which has neither. Same position as
+ *     2.1.195, which has no such segments at all.
+ *
+ * The remaining two are conversation state and are the caller's to supply.
+ */
+export async function createBillingBlock(
+  firstUserText: string,
+  profile: ClaudeCodeProtocolProfile,
+  crypto?: Pick<Crypto, "subtle">,
+  chain?: BillingChain,
+): Promise<TextBlock> {
+  const { cliVersion, entrypoint } = profile;
+  const fingerprint = await createBillingFingerprint(
+    firstUserText,
+    cliVersion,
+    crypto,
+  );
+
+  let text = `x-anthropic-billing-header: cc_version=${cliVersion}.${fingerprint}; cc_entrypoint=${entrypoint}; cch=00000;`;
+
+  /*
+   * ---- Demarcated: conversation chaining, upstream 2.1.233. ----
+   *
+   * The gate is STRUCTURAL, not a capability flag: the 2.1.233 builder takes
+   * these two values, the 2.1.195 builder has no parameter for them, so the
+   * 195 profile must never emit either segment even when a caller supplies
+   * both. They are dropped silently there, exactly as a client without the
+   * feature would drop them. Which profiles are on which side is
+   * `profile-behaviors.ts`'s question, not this module's.
+   *
+   * A malformed value is dropped silently too, and never interpolated: these
+   * segments are the only caller-controlled bytes in the block, so a value
+   * failing its pattern must not reach the wire in any form.
+   */
+  if (profileBehaviors(profile).billingChainSegments) {
+    const previousRequestId = chain?.previousRequestId;
+    if (
+      previousRequestId !== undefined &&
+      PREVIOUS_REQUEST_ID_PATTERN.test(previousRequestId)
+    ) {
+      text += ` cc_prev_req=${previousRequestId};`;
+    }
+    const promptId = chain?.promptId;
+    if (promptId !== undefined && PROMPT_ID_PATTERN.test(promptId)) {
+      text += ` cc_prompt_id=${promptId};`;
+    }
+  }
+
+  return { type: "text", text };
+}

package/src/headers.ts

@@ -0,0 +1,448 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type {
+  ClaudeCodeExtraHeaderPolicy,
+  ClaudeCodeProtocolProfile,
+  HeaderPair,
+} from "./contracts.js";
+import { ClaudeCodeWireError } from "./contracts.js";
+import { CLAUDE_CODE_2_1_195_PROFILE } from "./profiles/claude-code-2.1.195.js";
+import { CLAUDE_CODE_2_1_233_PROFILE } from "./profiles/claude-code-2.1.233.js";
+
+const HEADER_NAMES = Object.freeze({
+  anthropicBeta: "anthropic-beta",
+  browserAccess: "anthropic-dangerous-direct-browser-access",
+  anthropicVersion: "anthropic-version",
+  authorization: "authorization",
+  contentType: "content-type",
+  userAgent: "user-agent",
+  app: "x-app",
+  sessionId: "x-claude-code-session-id",
+  clientRequestId: "x-client-request-id",
+  arch: "x-stainless-arch",
+  lang: "x-stainless-lang",
+  os: "x-stainless-os",
+  packageVersion: "x-stainless-package-version",
+  retryCount: "x-stainless-retry-count",
+  runtime: "x-stainless-runtime",
+  runtimeVersion: "x-stainless-runtime-version",
+  timeout: "x-stainless-timeout",
+  stainlessHelper: "x-stainless-helper",
+  remoteContainerId: "x-claude-remote-container-id",
+  remoteSessionId: "x-claude-remote-session-id",
+  clientApp: "x-client-app",
+  additionalProtection: "x-anthropic-additional-protection",
+} as const);
+
+const CANONICAL_NAMES: ReadonlySet<string> = new Set(
+  Object.values(HEADER_NAMES),
+);
+
+interface HeaderRuntime {
+  readonly sessionId: string;
+  readonly runtime: string;
+  readonly runtimeVersion: string;
+  readonly os: string;
+  readonly arch: string;
+}
+
+interface ValidatedInput {
+  readonly accessToken: string;
+  readonly runtime: HeaderRuntime;
+  readonly clientRequestId: string;
+  readonly betaFeatures: readonly string[];
+  readonly app: "cli" | "cli-bg";
+  readonly stainlessRetryCount: number;
+  readonly stainlessHelper?: string;
+  readonly claudeRemoteContainerId?: string;
+  readonly claudeRemoteSessionId?: string;
+  readonly clientApp?: string;
+  readonly anthropicAdditionalProtection?: string;
+  readonly extraHeaders: readonly HeaderPair[];
+  readonly extraHeaderPolicy: ClaudeCodeExtraHeaderPolicy;
+  readonly profile: ClaudeCodeProtocolProfile;
+}
+
+/** Reports the headers placed on the wire plus what the policy discarded. */
+export interface OrderedHeaderPlan {
+  readonly headers: readonly HeaderPair[];
+  /**
+   * Lists the lowercased names `dropConflicting` discarded, in caller order.
+   *
+   * Always empty under `strict`, which throws instead of dropping.
+   */
+  readonly droppedExtraHeaderNames: readonly string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasControlCharacter(value: string): boolean {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0);
+    if (
+      codePoint !== undefined &&
+      (codePoint <= 31 || (codePoint >= 127 && codePoint <= 159))
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function assertHeaderText(name: string, value: string): void {
+  if (hasControlCharacter(name) || hasControlCharacter(value)) {
+    throw new ClaudeCodeWireError("HEADER_INJECTION");
+  }
+}
+
+function requiredString(
+  record: Readonly<Record<string, unknown>>,
+  key: string,
+): string {
+  const value = record[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  return value;
+}
+
+function parseRuntime(value: unknown): HeaderRuntime {
+  if (!isRecord(value)) {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  return {
+    sessionId: requiredString(value, "sessionId"),
+    runtime: requiredString(value, "runtime"),
+    runtimeVersion: requiredString(value, "runtimeVersion"),
+    os: requiredString(value, "os"),
+    arch: requiredString(value, "arch"),
+  };
+}
+
+function parseBetaFeatures(value: unknown): readonly string[] {
+  if (!Array.isArray(value)) {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  const features: string[] = [];
+  for (const feature of value) {
+    if (typeof feature !== "string" || feature.length === 0) {
+      throw new ClaudeCodeWireError("INVALID_INPUT");
+    }
+    features.push(feature);
+  }
+  return features;
+}
+
+function parseExtraHeaders(value: unknown): readonly HeaderPair[] {
+  if (!Array.isArray(value)) {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  const headers: HeaderPair[] = [];
+  for (const candidate of value) {
+    if (
+      !Array.isArray(candidate) ||
+      candidate.length !== 2 ||
+      typeof candidate[0] !== "string" ||
+      typeof candidate[1] !== "string"
+    ) {
+      throw new ClaudeCodeWireError("INVALID_INPUT");
+    }
+    headers.push([candidate[0], candidate[1]]);
+  }
+  return headers;
+}
+
+function parseExtraHeaderPolicy(value: unknown): ClaudeCodeExtraHeaderPolicy {
+  if (value !== "strict" && value !== "dropConflicting") {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  return value;
+}
+
+/**
+ * Accepts a pinned profile by REFERENCE, never by shape, and returns the
+ * singleton itself so nothing downstream can be handed a look-alike. Adding
+ * the second pinned profile widens the accepted set by exactly one object;
+ * anything else, including a structural clone, still fails closed.
+ */
+function parseProfile(value: unknown): ClaudeCodeProtocolProfile {
+  if (value === CLAUDE_CODE_2_1_195_PROFILE) return CLAUDE_CODE_2_1_195_PROFILE;
+  if (value === CLAUDE_CODE_2_1_233_PROFILE) return CLAUDE_CODE_2_1_233_PROFILE;
+  throw new ClaudeCodeWireError("INVALID_INPUT");
+}
+
+function parseApp(value: unknown): "cli" | "cli-bg" {
+  if (value !== "cli" && value !== "cli-bg") {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  return value;
+}
+
+function parseRetryCount(value: unknown): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  return value;
+}
+
+function optionalHeaderString(
+  input: Readonly<Record<string, unknown>>,
+  key: string,
+): string | undefined {
+  const value = input[key];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  return value;
+}
+
+function parseInput(input: unknown): ValidatedInput {
+  if (!isRecord(input)) {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  const stainlessHelper = optionalHeaderString(input, "stainlessHelper");
+  const claudeRemoteContainerId = optionalHeaderString(
+    input,
+    "claudeRemoteContainerId",
+  );
+  const claudeRemoteSessionId = optionalHeaderString(
+    input,
+    "claudeRemoteSessionId",
+  );
+  const clientApp = optionalHeaderString(input, "clientApp");
+  const anthropicAdditionalProtection = optionalHeaderString(
+    input,
+    "anthropicAdditionalProtection",
+  );
+  return {
+    accessToken: requiredString(input, "accessToken"),
+    runtime: parseRuntime(input["runtime"]),
+    clientRequestId: requiredString(input, "clientRequestId"),
+    betaFeatures: parseBetaFeatures(input["betaFeatures"]),
+    app: parseApp(input["app"] === undefined ? "cli" : input["app"]),
+    stainlessRetryCount: parseRetryCount(
+      input["stainlessRetryCount"] === undefined
+        ? 0
+        : input["stainlessRetryCount"],
+    ),
+    extraHeaders: parseExtraHeaders(input["extraHeaders"] ?? []),
+    extraHeaderPolicy: parseExtraHeaderPolicy(
+      input["extraHeaderPolicy"] ?? "strict",
+    ),
+    profile: parseProfile(input["profile"]),
+    ...(stainlessHelper === undefined ? {} : { stainlessHelper }),
+    ...(claudeRemoteContainerId === undefined
+      ? {}
+      : { claudeRemoteContainerId }),
+    ...(claudeRemoteSessionId === undefined ? {} : { claudeRemoteSessionId }),
+    ...(clientApp === undefined ? {} : { clientApp }),
+    ...(anthropicAdditionalProtection === undefined
+      ? {}
+      : { anthropicAdditionalProtection }),
+  };
+}
+
+/**
+ * Names a caller may never place on the wire through `extraHeaders`.
+ *
+ * Two disjoint reasons, both non-negotiable.
+ *
+ * CREDENTIAL AND ROUTING DISCLOSURE. `x-api-key`, `cookie`, `set-cookie`,
+ * `proxy-*`, `forwarded` and `x-forwarded-*` carry authentication that would
+ * contradict the OAuth bearer this package emits, or disclose the caller's
+ * network topology upstream.
+ *
+ * HOP-BY-HOP AND ENTITY HEADERS (RFC 9110 section 7.6.1). `connection`,
+ * `transfer-encoding`, `te`, `upgrade`, `keep-alive` and `host` govern a single
+ * connection and belong to the transport, not to the caller. `content-length`
+ * is the worst of them: this package RECONSTRUCTS the request body canonically,
+ * so a length copied from an inbound request describes a different byte string.
+ * A wrong `content-length` corrupts the request SILENTLY — no local error is
+ * raised, the peer truncates or stalls. Blocking these is a defect fix, valid
+ * independently of any consumer.
+ */
+const FORBIDDEN_HEADER_NAMES: ReadonlySet<string> = new Set([
+  "x-api-key",
+  "cookie",
+  "set-cookie",
+  "forwarded",
+  "content-length",
+  "host",
+  "connection",
+  "transfer-encoding",
+  "te",
+  "upgrade",
+  "keep-alive",
+]);
+
+function isForbiddenHeader(name: string): boolean {
+  return (
+    FORBIDDEN_HEADER_NAMES.has(name) ||
+    name.startsWith("proxy-") ||
+    name.startsWith("x-forwarded-")
+  );
+}
+
+function safeDiagnosticName(name: string, accessToken: string): string {
+  return name.includes(accessToken) ? "[redacted]" : name;
+}
+
+interface ResolvedExtraHeaders {
+  readonly kept: readonly HeaderPair[];
+  readonly droppedNames: readonly string[];
+}
+
+/**
+ * Applies the caller policy to the supplied extra headers.
+ *
+ * `strict` is the original behaviour, unchanged: the first conflict throws, and
+ * nothing reaches the wire. `dropConflicting` discards the offending pair and
+ * records its lowercased name, so a consumer forwarding a heterogeneous host
+ * header map is not defeated by a single header this package owns.
+ *
+ * The relaxation covers OWNERSHIP conflicts only — a canonical name or a
+ * denylisted name. Two guarantees survive in both policies:
+ *
+ * - Header syntax is validated FIRST and never relaxed. A control character in
+ *   a name or a value raises `HEADER_INJECTION` whatever the policy says;
+ *   smuggling is never silently tolerated.
+ * - A caller that duplicates one of ITS OWN extra headers still gets
+ *   `DUPLICATE_HEADER`. That collision is a caller bug, not an ownership
+ *   conflict this package is entitled to resolve on the caller's behalf.
+ */
+function resolveExtraHeaders(
+  extraHeaders: readonly HeaderPair[],
+  accessToken: string,
+  policy: ClaudeCodeExtraHeaderPolicy,
+): ResolvedExtraHeaders {
+  const seenExtras = new Set<string>();
+  const kept: HeaderPair[] = [];
+  const droppedNames: string[] = [];
+  for (const [name, value] of extraHeaders) {
+    assertHeaderText(name, value);
+    const normalizedName = name.toLowerCase();
+    const safeName = safeDiagnosticName(normalizedName, accessToken);
+    const ownershipConflict = isForbiddenHeader(normalizedName)
+      ? "FORBIDDEN_HEADER"
+      : CANONICAL_NAMES.has(normalizedName)
+        ? "DUPLICATE_HEADER"
+        : undefined;
+    if (ownershipConflict !== undefined) {
+      if (policy === "strict") {
+        throw new ClaudeCodeWireError(ownershipConflict, {
+          headerName: safeName,
+        });
+      }
+      droppedNames.push(normalizedName);
+      continue;
+    }
+    if (seenExtras.has(normalizedName)) {
+      throw new ClaudeCodeWireError("DUPLICATE_HEADER", {
+        headerName: safeName,
+      });
+    }
+    seenExtras.add(normalizedName);
+    kept.push([name, value]);
+  }
+  return { kept, droppedNames };
+}
+
+function freezePair(name: string, value: string): HeaderPair {
+  const pair: HeaderPair = [name, value];
+  return Object.freeze(pair);
+}
+
+function assertTokenIsolation(
+  pairs: readonly HeaderPair[],
+  accessToken: string,
+): void {
+  for (const [name, value] of pairs) {
+    if (name !== HEADER_NAMES.authorization && value.includes(accessToken)) {
+      throw new ClaudeCodeWireError("INVALID_INPUT");
+    }
+  }
+}
+
+/**
+ * Builds the pinned canonical logical header list together with the audit of
+ * whatever the extra-header policy discarded.
+ *
+ * Transport order is not guaranteed.
+ */
+export function buildOrderedHeaderPlan(input: unknown): OrderedHeaderPlan {
+  const appendExtraHeaders =
+    isRecord(input) &&
+    (Object.hasOwn(input, "app") ||
+      Object.hasOwn(input, "stainlessRetryCount") ||
+      Object.hasOwn(input, "stainlessHelper") ||
+      Object.hasOwn(input, "claudeRemoteContainerId") ||
+      Object.hasOwn(input, "claudeRemoteSessionId") ||
+      Object.hasOwn(input, "clientApp") ||
+      Object.hasOwn(input, "anthropicAdditionalProtection"));
+  const validated = parseInput(input);
+  const resolvedExtras = resolveExtraHeaders(
+    validated.extraHeaders,
+    validated.accessToken,
+    validated.extraHeaderPolicy,
+  );
+
+  const beta = validated.betaFeatures.join(",");
+  const values = [
+    [HEADER_NAMES.anthropicBeta, beta],
+    [HEADER_NAMES.browserAccess, "true"],
+    [HEADER_NAMES.anthropicVersion, validated.profile.anthropicVersion],
+    [HEADER_NAMES.authorization, `Bearer ${validated.accessToken}`],
+    [HEADER_NAMES.contentType, "application/json"],
+    [HEADER_NAMES.userAgent, validated.profile.userAgent],
+    [HEADER_NAMES.app, validated.app],
+    [HEADER_NAMES.sessionId, validated.runtime.sessionId],
+    [HEADER_NAMES.clientRequestId, validated.clientRequestId],
+    [HEADER_NAMES.arch, validated.runtime.arch],
+    [HEADER_NAMES.lang, "js"],
+    [HEADER_NAMES.os, validated.runtime.os],
+    [HEADER_NAMES.packageVersion, validated.profile.sdkVersion],
+    [HEADER_NAMES.retryCount, String(validated.stainlessRetryCount)],
+    [HEADER_NAMES.runtime, validated.runtime.runtime],
+    [HEADER_NAMES.runtimeVersion, validated.runtime.runtimeVersion],
+    [HEADER_NAMES.timeout, "600"],
+  ] as const;
+
+  const pairs: HeaderPair[] = [];
+  for (const [name, value] of values) {
+    assertHeaderText(name, value);
+    pairs.push(freezePair(name, value));
+  }
+  const dynamicValues = [
+    [HEADER_NAMES.stainlessHelper, validated.stainlessHelper],
+    [HEADER_NAMES.remoteContainerId, validated.claudeRemoteContainerId],
+    [HEADER_NAMES.remoteSessionId, validated.claudeRemoteSessionId],
+    [HEADER_NAMES.clientApp, validated.clientApp],
+    [
+      HEADER_NAMES.additionalProtection,
+      validated.anthropicAdditionalProtection,
+    ],
+  ] as const;
+  for (const [name, value] of dynamicValues) {
+    if (value === undefined) continue;
+    assertHeaderText(name, value);
+    pairs.push(freezePair(name, value));
+  }
+  if (appendExtraHeaders) {
+    for (const [name, value] of resolvedExtras.kept) {
+      pairs.push(freezePair(name, value));
+    }
+  }
+  assertTokenIsolation(pairs, validated.accessToken);
+  return Object.freeze({
+    headers: Object.freeze(pairs),
+    droppedExtraHeaderNames: Object.freeze([...resolvedExtras.droppedNames]),
+  });
+}
+
+/** Builds the pinned canonical logical header list. Transport order is not guaranteed. */
+export function buildOrderedHeaders(input: unknown): readonly HeaderPair[] {
+  return buildOrderedHeaderPlan(input).headers;
+}