@tormentalabs/claude-code-wire-compat 0.1.0 → 0.2.0

package/src/betas.ts

@@ -10,7 +10,9 @@ import {
   supportsMidConversationSystem,
   supportsStructuredOutputs,
 } from "./model-capabilities.js";
+import { BETA_REGISTRY_2_1_233 } from "./profiles/beta-registry-2.1.233.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";
 
 /*
  * Provenance. The emitted order is a port of the genuine client's base beta set
@@ -22,7 +24,73 @@ import { CLAUDE_CODE_2_1_195_PROFILE } from "./profiles/claude-code-2.1.195.js";
  * 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".
+ *
+ * The push SITES are shared across profiles; the identifiers they push are not.
+ * A profile therefore selects its registry (see `resolveBetaRegistry`) and the
+ * sequence of sites stays fixed, which is what keeps a registry change from
+ * silently becoming an ordering change.
+ */
+
+/** Structural shape of a registry entry, shared by every registry version. */
+interface BetaRegistryEntry {
+  readonly featureKey: string;
+  readonly header: string;
+}
+
+/**
+ * The entries the push sites below require, as a structural contract rather
+ * than a reference to one concrete registry.
+ *
+ * Registry versions have different key sets. Every key here except
+ * `NARRATION_SUMMARIES` is present in all of them, so those push sites index
+ * directly. `NARRATION_SUMMARIES` is optional because upstream removed it after
+ * 2.1.195 (see `src/profiles/beta-registry-2.1.233.ts`): its push site survives
+ * and becomes inert when the resolved registry has no entry to push. Making the
+ * optionality part of the TYPE is what forces every future registry to be
+ * checked against the push sites at compile time instead of at runtime.
+ */
+export interface ComposableBetaRegistry {
+  readonly CLAUDE_CODE: BetaRegistryEntry;
+  readonly OAUTH_AUTH: BetaRegistryEntry;
+  readonly LONG_CONTEXT: BetaRegistryEntry;
+  readonly INTERLEAVED_THINKING: BetaRegistryEntry;
+  readonly REDACT_THINKING: BetaRegistryEntry;
+  readonly THINKING_TOKEN_COUNT: BetaRegistryEntry;
+  readonly CONTEXT_MANAGEMENT: BetaRegistryEntry;
+  readonly STRUCTURED_OUTPUTS: BetaRegistryEntry;
+  readonly PROMPT_CACHING_SCOPE: BetaRegistryEntry;
+  readonly MID_CONVERSATION_SYSTEM: BetaRegistryEntry;
+  readonly EFFORT: BetaRegistryEntry;
+  readonly SPEED: BetaRegistryEntry;
+  readonly AFK_MODE: BetaRegistryEntry;
+  readonly EXTENDED_CACHE_TTL: BetaRegistryEntry;
+  readonly CONTEXT_HINT: BetaRegistryEntry;
+  readonly CACHE_DIAGNOSIS: BetaRegistryEntry;
+  readonly NARRATION_SUMMARIES?: BetaRegistryEntry;
+}
+
+const PROFILE_BETA_REGISTRIES: ReadonlyMap<string, ComposableBetaRegistry> =
+  new Map<string, ComposableBetaRegistry>([
+    [CLAUDE_CODE_2_1_195_PROFILE.id, BETA_REGISTRY],
+    [CLAUDE_CODE_2_1_233_PROFILE.id, BETA_REGISTRY_2_1_233],
+  ]);
+
+/**
+ * Selects the registry a profile composes against.
+ *
+ * An unrecognised id falls back to the 2.1.195 registry rather than throwing.
+ * Rejecting unknown profiles is the request builder's job -- it validates the
+ * profile before any of this runs -- and duplicating that rejection here would
+ * give `composeBetas` a second, differently-worded opinion about profile
+ * validity. Standalone callers keep the 2.1.195 behaviour they had before
+ * profiles were a parameter.
  */
+function resolveBetaRegistry(
+  profile: ClaudeCodeProtocolProfile,
+): ComposableBetaRegistry {
+  return PROFILE_BETA_REGISTRIES.get(profile.id) ?? BETA_REGISTRY;
+}
+
 export interface ComposeBetasInput {
   readonly rawModel: string;
   readonly normalizedId: string;
@@ -109,23 +177,24 @@ export function composeBetasWithAudit(
   const out: string[] = [];
   const policy = profile.betaPolicy;
   const experimental = policy.experimentalBetasEnabled;
+  const registry = resolveBetaRegistry(profile);
 
   if (!input.normalizedId.includes("haiku"))
-    out.push(BETA_REGISTRY.CLAUDE_CODE.header);
-  if (policy.oauthAuthenticated) out.push(BETA_REGISTRY.OAUTH_AUTH.header);
+    out.push(registry.CLAUDE_CODE.header);
+  if (policy.oauthAuthenticated) out.push(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);
+    out.push(registry.LONG_CONTEXT.header);
   }
   if (
     policy.interleavedThinkingEnabled &&
     input.capabilities.interleavedThinking
   ) {
-    out.push(BETA_REGISTRY.INTERLEAVED_THINKING.header);
+    out.push(registry.INTERLEAVED_THINKING.header);
   }
   if (
     experimental &&
@@ -134,52 +203,66 @@ export function composeBetasWithAudit(
     !policy.thinkingSummariesShown &&
     !input.thinkingDisplayActive
   ) {
-    out.push(BETA_REGISTRY.REDACT_THINKING.header);
+    out.push(registry.REDACT_THINKING.header);
   }
   if (
     policy.thinkingTokenCountEnabled &&
     experimental &&
     input.capabilities.interleavedThinking
   ) {
-    out.push(BETA_REGISTRY.THINKING_TOKEN_COUNT.header);
+    out.push(registry.THINKING_TOKEN_COUNT.header);
+  }
+  /*
+   * The narration push site keeps its position in the sequence even when the
+   * resolved registry dropped the entry. Upstream removed the beta after
+   * 2.1.195, so a registry without it emits nothing here and the surrounding
+   * order closes up with no gap; the gates are still evaluated first so a
+   * profile that enables narration against a registry that has it behaves
+   * exactly as it did before.
+   */
+  const narrationSummaries = registry.NARRATION_SUMMARIES;
+  if (
+    experimental &&
+    policy.narrationSummariesEnabled &&
+    narrationSummaries !== undefined
+  ) {
+    out.push(narrationSummaries.header);
   }
-  if (experimental && policy.narrationSummariesEnabled)
-    out.push(BETA_REGISTRY.NARRATION_SUMMARIES.header);
   if (experimental && input.capabilities.contextManagement)
-    out.push(BETA_REGISTRY.CONTEXT_MANAGEMENT.header);
+    out.push(registry.CONTEXT_MANAGEMENT.header);
   if (
     experimental &&
     supportsStructuredOutputs(input.normalizedId) &&
     policy.structuredOutputsEnabled
   ) {
-    out.push(BETA_REGISTRY.STRUCTURED_OUTPUTS.header);
+    out.push(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 (experimental) out.push(registry.PROMPT_CACHING_SCOPE.header);
+  if (supportsMidConversationSystem(input.normalizedId, profile))
+    out.push(registry.MID_CONVERSATION_SYSTEM.header);
+  if (input.capabilities.effort) out.push(registry.EFFORT.header);
 
-  if (input.speed === "fast" && !out.includes(BETA_REGISTRY.SPEED.header)) {
-    out.push(BETA_REGISTRY.SPEED.header);
+  if (input.speed === "fast" && !out.includes(registry.SPEED.header)) {
+    out.push(registry.SPEED.header);
   }
-  if (policy.afkModeEnabled && !out.includes(BETA_REGISTRY.AFK_MODE.header)) {
-    out.push(BETA_REGISTRY.AFK_MODE.header);
+  if (policy.afkModeEnabled && !out.includes(registry.AFK_MODE.header)) {
+    out.push(registry.AFK_MODE.header);
   }
   if (
     input.cacheTtl === "1h" &&
     experimental &&
-    !out.includes(BETA_REGISTRY.EXTENDED_CACHE_TTL.header)
+    !out.includes(registry.EXTENDED_CACHE_TTL.header)
   ) {
-    out.push(BETA_REGISTRY.EXTENDED_CACHE_TTL.header);
+    out.push(registry.EXTENDED_CACHE_TTL.header);
   }
-  if (profile.contextHintEnabled) out.push(BETA_REGISTRY.CONTEXT_HINT.header);
+  if (profile.contextHintEnabled) out.push(registry.CONTEXT_HINT.header);
   if (
     policy.cacheDiagnosisEnabled &&
-    !out.includes(BETA_REGISTRY.CACHE_DIAGNOSIS.header)
+    !out.includes(registry.CACHE_DIAGNOSIS.header)
   ) {
-    out.push(BETA_REGISTRY.CACHE_DIAGNOSIS.header);
+    out.push(registry.CACHE_DIAGNOSIS.header);
   }
 
   // No advisor-tool beta: upstream has no observed unconditional push site.

package/src/build-request.ts

@@ -29,6 +29,7 @@ import {
 } from "./metadata.js";
 import { resolveModel } from "./models.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";
 import type { NormalizedRequestInput } from "./redaction.js";
 import { buildRedactedEvidence, toSafeErrorDetails } from "./redaction.js";
 import {
@@ -87,6 +88,8 @@ const INPUT_KEYS = new Set([
   "metadataOverrides",
   "extraHeaders",
   "extraHeaderPolicy",
+  "previousRequestId",
+  "promptId",
   "crypto",
 ]);
 const BETA_OVERRIDE_KEYS = new Set(["use1MContext"]);
@@ -172,6 +175,7 @@ const MODEL_KEYS = new Set([
   "family",
   "context",
   "capabilities",
+  "maxOutputTokens",
   "defaultEffort",
 ]);
 const BETA_POLICY_KEYS = new Set([
@@ -313,10 +317,46 @@ function containsString(value: unknown, target: string): boolean {
   );
 }
 
+/**
+ * The profiles this package will assemble a request for. Two entries: the
+ * 2.1.195 default and the 2.1.233 profile, which callers must pass
+ * explicitly. Admitting a profile is exactly this list -- `validateProfile`
+ * did not change to accept the second one.
+ *
+ * Membership is by REFERENCE, deliberately. A structural check would accept a
+ * caller-built object that merely looks like a pinned profile, and every wire
+ * guarantee this package makes -- the sealed golden fixtures, the packed
+ * consumer digests -- is a statement about the exact frozen singletons, not
+ * about anything shaped like them. `Set.prototype.has` uses SameValueZero, so
+ * `{ ...CLAUDE_CODE_2_1_195_PROFILE }` is rejected exactly as it was by the
+ * `!==` this replaced.
+ *
+ * Not exported and not frozen-with-teeth: `Object.freeze` on a `Set` blocks
+ * property assignment but NOT `add`, so freezing it would advertise a
+ * guarantee it cannot keep. Module scope is the real protection.
+ */
+const ACCEPTED_PROFILES: ReadonlySet<ClaudeCodeProtocolProfile> = new Set([
+  CLAUDE_CODE_2_1_195_PROFILE,
+  CLAUDE_CODE_2_1_233_PROFILE,
+]);
+
+/**
+ * The profile every public entry point resolves to when the caller supplies
+ * none. Declared once so that the default is a single, greppable seam: a test
+ * that means "whatever the default is" reads THIS instead of naming a
+ * version, which keeps a default switch to a one-line diff and keeps tests
+ * that genuinely mean 2.1.195 honest about saying so.
+ *
+ * Exported for tests, which deep-import it. It is deliberately NOT re-exported
+ * from `src/index.ts`: the public runtime surface stays closed.
+ */
+export const DEFAULT_PROFILE: ClaudeCodeProtocolProfile =
+  CLAUDE_CODE_2_1_233_PROFILE;
+
 function validateProfile(
   profile: ClaudeCodeProtocolProfile,
 ): ClaudeCodeProtocolProfile {
-  if (profile !== CLAUDE_CODE_2_1_195_PROFILE) fail();
+  if (!ACCEPTED_PROFILES.has(profile)) fail();
   return profile;
 }
 
@@ -362,6 +402,43 @@ function parseCatalogueCapabilities(value: unknown): readonly string[] {
   return Object.freeze([...value]);
 }
 
+/**
+ * Validates a catalogue entry's `maxOutputTokens`. Both fields are required
+ * when the object is present: a half-populated entry would silently fall back
+ * to the legacy limit table for the missing half, which is exactly the drift
+ * `modelOutputTokenLimits` is structured to prevent.
+ */
+function parseCatalogueMaxOutputTokens(value: unknown): Readonly<{
+  readonly default: number;
+  readonly upper: number;
+}> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  const keys = Reflect.ownKeys(value);
+  if (
+    keys.some(
+      (key) =>
+        typeof key !== "string" || (key !== "default" && key !== "upper"),
+    )
+  ) {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  const defaultLimit: unknown = Reflect.get(value, "default");
+  const upper: unknown = Reflect.get(value, "upper");
+  if (
+    typeof defaultLimit !== "number" ||
+    !Number.isSafeInteger(defaultLimit) ||
+    defaultLimit <= 0 ||
+    typeof upper !== "number" ||
+    !Number.isSafeInteger(upper) ||
+    upper <= 0
+  ) {
+    throw new ClaudeCodeWireError("INVALID_INPUT");
+  }
+  return Object.freeze({ default: defaultLimit, upper });
+}
+
 function parseCatalogueContext(value: unknown): Readonly<{
   readonly window: number;
   readonly native1m?: boolean;
@@ -487,6 +564,13 @@ function parseSupportedModels(
         ? { context: parseCatalogueContext(ownValue(model, "context")) }
         : {}),
       capabilities: parseCatalogueCapabilities(ownValue(model, "capabilities")),
+      ...(Object.hasOwn(model, "maxOutputTokens")
+        ? {
+            maxOutputTokens: parseCatalogueMaxOutputTokens(
+              ownValue(model, "maxOutputTokens"),
+            ),
+          }
+        : {}),
       ...(Object.hasOwn(model, "defaultEffort")
         ? {
             defaultEffort: parseDefaultEffort(ownValue(model, "defaultEffort")),
@@ -681,6 +765,8 @@ function validateInput(input: ClaudeCodeRequestInput): {
   readonly suppressBillingBlock: boolean;
   readonly suppressIdentityBlock: boolean;
   readonly preserveThinkingBlockCacheControl: boolean;
+  readonly previousRequestId: string | undefined;
+  readonly promptId: string | undefined;
 } {
   if (!isRecord(input)) fail();
   assertExactKeys(input, INPUT_KEYS);
@@ -741,6 +827,12 @@ function validateInput(input: ClaudeCodeRequestInput): {
         ownValue(input, "preserveThinkingBlockCacheControl"),
       )
     : false;
+  const previousRequestId = Object.hasOwn(input, "previousRequestId")
+    ? validateBillingChainId(ownValue(input, "previousRequestId"))
+    : undefined;
+  const promptId = Object.hasOwn(input, "promptId")
+    ? validateBillingChainId(ownValue(input, "promptId"))
+    : undefined;
   return {
     source: input,
     clientRequestId,
@@ -751,9 +843,31 @@ function validateInput(input: ClaudeCodeRequestInput): {
     suppressBillingBlock,
     suppressIdentityBlock,
     preserveThinkingBlockCacheControl,
+    previousRequestId,
+    promptId,
   };
 }
 
+/**
+ * Type check only. The FORMAT of these two ids is deliberately not checked
+ * here: upstream guards them at the point of emission and drops a value it
+ * cannot vouch for, silently, so rejecting one here would make this package
+ * fail where the genuine client succeeds. `createBillingBlock` owns the
+ * patterns. A non-string is still a caller bug and fails like every other
+ * mistyped field.
+ *
+ * There is deliberately no `undefined` arm: `inspectGraph` has already rejected
+ * an explicitly-undefined value for every key but `crypto` by the time this
+ * runs, so such an arm would be unreachable. An explicitly-undefined id is
+ * therefore `INVALID_INPUT` here, as it is for every other field, and is NOT
+ * equivalent to omitting the key — unlike at the `createBillingBlock` seam,
+ * which does treat the two alike. `billing-prev-req.test.ts` pins both halves.
+ */
+function validateBillingChainId(value: unknown): string {
+  if (typeof value !== "string") fail();
+  return value;
+}
+
 function validateCountTokensInput(input: ClaudeCodeCountTokensInput): {
   readonly source: ClaudeCodeCountTokensInput;
   readonly clientRequestId: string;
@@ -947,7 +1061,19 @@ function parseCapabilityDecisions(
   };
 }
 
-function parseEvidence(value: unknown): RedactedRequestEvidence {
+/**
+ * Validates evidence against the profile the request was parsed under, not
+ * against a hardcoded singleton. `parseBuiltClaudeCodeRequest` already
+ * validates `url` against `pinnedProfile.endpoint`; the profile id is the one
+ * remaining field where the two pinned profiles differ, so it has to follow
+ * the same source or a request built with a non-default profile could never
+ * be re-parsed. Still fail-closed: the profile reaching here has already
+ * passed `validateProfile`.
+ */
+function parseEvidence(
+  value: unknown,
+  pinnedProfile: ClaudeCodeProtocolProfile,
+): RedactedRequestEvidence {
   if (!isRecord(value)) fail();
   assertExactKeys(value, EVIDENCE_KEYS);
   const modelFamily = ownValue(value, "modelFamily");
@@ -966,8 +1092,8 @@ function parseEvidence(value: unknown): RedactedRequestEvidence {
   const messageCount = ownValue(value, "messageCount");
   const systemBlockCount = ownValue(value, "systemBlockCount");
   if (
-    ownValue(value, "profileId") !== CLAUDE_CODE_2_1_195_PROFILE.id ||
-    ownValue(value, "url") !== CLAUDE_CODE_2_1_195_PROFILE.endpoint ||
+    ownValue(value, "profileId") !== pinnedProfile.id ||
+    ownValue(value, "url") !== pinnedProfile.endpoint ||
     ownValue(value, "method") !== METHOD ||
     typeof bodySha256 !== "string" ||
     !/^[0-9a-f]{64}$/u.test(bodySha256) ||
@@ -981,8 +1107,8 @@ function parseEvidence(value: unknown): RedactedRequestEvidence {
     fail();
   }
   return {
-    profileId: CLAUDE_CODE_2_1_195_PROFILE.id,
-    url: CLAUDE_CODE_2_1_195_PROFILE.endpoint,
+    profileId: pinnedProfile.id,
+    url: pinnedProfile.endpoint,
     method: METHOD,
     modelFamily,
     logicalHeaderNames: parseStringArray(ownValue(value, "logicalHeaderNames")),
@@ -1289,7 +1415,7 @@ function countTokensEvidenceRequest(
 /** Builds a canonical Claude Code count-tokens request. */
 export async function buildClaudeCodeCountTokensRequest(
   input: ClaudeCodeCountTokensInput,
-  profile: ClaudeCodeProtocolProfile = CLAUDE_CODE_2_1_195_PROFILE,
+  profile: ClaudeCodeProtocolProfile = DEFAULT_PROFILE,
 ): Promise<BuiltClaudeCodeCountTokensRequest> {
   try {
     const pinnedProfile = validateProfile(profile);
@@ -1384,7 +1510,7 @@ export async function buildClaudeCodeCountTokensRequest(
  */
 export async function buildClaudeCodeRequest(
   input: ClaudeCodeRequestInput,
-  profile: ClaudeCodeProtocolProfile = CLAUDE_CODE_2_1_195_PROFILE,
+  profile: ClaudeCodeProtocolProfile = DEFAULT_PROFILE,
 ): Promise<BuiltClaudeCodeRequest> {
   try {
     const pinnedProfile = validateProfile(profile);
@@ -1406,10 +1532,28 @@ export async function buildClaudeCodeRequest(
       ...resolvedModel,
       capabilities,
     });
+    /*
+     * The previous turn's request id is the CALLER's to supply. Upstream
+     * derives it by scanning the conversation for the last assistant message
+     * and reading a `requestId` it stored alongside it — a field of the
+     * client's own transcript, not of the Messages API wire format. Modelling
+     * that would mean adding a non-wire property to `Message` and having this
+     * package infer conversation state it does not own. A documented
+     * divergence of convenience: the value is the same, the plumbing is the
+     * consumer's.
+     */
     const billing = await createBillingBlock(
       fingerprintText(validated.source),
-      effectiveProfile.cliVersion,
+      effectiveProfile,
       validated.crypto,
+      {
+        ...(validated.previousRequestId !== undefined && {
+          previousRequestId: validated.previousRequestId,
+        }),
+        ...(validated.promptId !== undefined && {
+          promptId: validated.promptId,
+        }),
+      },
     );
     const metadata = buildCorrelatedMetadata(
       identity,
@@ -1556,7 +1700,7 @@ export async function buildClaudeCodeRequest(
  */
 export function parseBuiltClaudeCodeRequest(
   value: unknown,
-  profile: ClaudeCodeProtocolProfile = CLAUDE_CODE_2_1_195_PROFILE,
+  profile: ClaudeCodeProtocolProfile = DEFAULT_PROFILE,
 ): BuiltClaudeCodeRequest {
   try {
     const pinnedProfile = validateProfile(profile);
@@ -1573,7 +1717,7 @@ export function parseBuiltClaudeCodeRequest(
     if (typeof body !== "string") fail();
     const parsedBody = parseBody(body);
     const headers = parseHeaders(ownValue(value, "headers"));
-    const evidence = parseEvidence(ownValue(value, "evidence"));
+    const evidence = parseEvidence(ownValue(value, "evidence"), pinnedProfile);
     // Reading evidence is not trusting evidence. A claim that the seam
     // preserved a marker is confirmed against the body, and it is confirmed
     // HERE — before the byte-length and digest checks — so that a forgery which

package/src/contracts.ts

@@ -33,6 +33,22 @@ export interface ClaudeCodeCatalogueEntry {
   }>;
   /** Verbatim upstream capability keys; compared by the ported predicates. */
   readonly capabilities: readonly string[];
+  /**
+   * Per-model output token limits. `default` caps the emitted `max_tokens`;
+   * `upper` seeds the thinking budget when the caller supplies none. The
+   * field names mirror the upstream 2.1.222 catalogue, where these limits
+   * became catalogue data; `modelOutputTokenLimits` keeps returning
+   * `{ default, upperLimit }`, so the `upper` -> `upperLimit` rename happens
+   * at that one call site in `thinking.ts`.
+   *
+   * Optional on the type because profiles ported from clients that predate
+   * the catalogue limits cannot supply it. Every entry of the 2.1.195
+   * catalogue does supply it, and a test enforces that.
+   */
+  readonly maxOutputTokens?: Readonly<{
+    readonly default: number;
+    readonly upper: number;
+  }>;
   readonly defaultEffort?: ClaudeCodeEffort;
 }
 
@@ -1006,6 +1022,43 @@ export interface ClaudeCodeRequestInput {
    * `"dropConflicting"`.
    */
   readonly extraHeaderPolicy?: ClaudeCodeExtraHeaderPolicy;
+  /**
+   * Supplies the `cc_prev_req` segment of the canonical billing block.
+   *
+   * This is the value of the `request-id` RESPONSE header the API returned for
+   * the PREVIOUS turn of this conversation — not this request's
+   * `clientRequestId`, and not anything derivable from `messages`. The genuine
+   * 2.1.233 client carries it forward so that a multi-turn conversation is
+   * linked request to request on the billing header.
+   *
+   * OMITTING IT IS OBSERVABLE. On the 2.1.233 profile, a second or later turn
+   * built without this field emits a billing block that the genuine client
+   * would not emit, and the request is therefore distinguishable from real CLI
+   * traffic from the second turn onward. The first turn has no previous
+   * request, so omitting it there is correct.
+   *
+   * Ignored entirely by the 2.1.195 profile, which has no such segment.
+   *
+   * A value that does not match `/^req_[A-Za-z0-9_-]{1,36}$/` is SILENTLY
+   * omitted from the block rather than rejected, mirroring upstream: the
+   * genuine client guards the segment and drops a value it cannot vouch for.
+   * A non-string value is still `INVALID_INPUT`, like every other field here.
+   */
+  readonly previousRequestId?: string;
+  /**
+   * Supplies the `cc_prompt_id` segment of the canonical billing block.
+   *
+   * A host-supplied prompt UUID. This package cannot derive one — upstream
+   * reads it from host state — so it is the caller's to provide, and omitting
+   * it is the modelled default for a session that has none.
+   *
+   * Ignored entirely by the 2.1.195 profile, which has no such segment.
+   *
+   * A value that does not match the canonical 8-4-4-4-12 hexadecimal UUID shape
+   * (case-insensitive) is SILENTLY omitted from the block rather than rejected,
+   * mirroring upstream. A non-string value is still `INVALID_INPUT`.
+   */
+  readonly promptId?: string;
   /** Injects the Web Crypto provider used to hash the request body. */
   readonly crypto?: Pick<Crypto, "subtle">;
 }

package/src/fingerprint.ts

@@ -1,11 +1,34 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-import type { TextBlock } from "./contracts.js";
+import type { ClaudeCodeProtocolProfile, TextBlock } from "./contracts.js";
 import { ClaudeCodeWireError } from "./contracts.js";
-import { CLAUDE_CODE_2_1_195_PROFILE } from "./profiles/claude-code-2.1.195.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;
@@ -66,20 +89,67 @@ export async function createBillingFingerprint(
     .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,
-  cliVersion: string,
+  profile: ClaudeCodeProtocolProfile,
   crypto?: Pick<Crypto, "subtle">,
+  chain?: BillingChain,
 ): Promise<TextBlock> {
+  const { cliVersion, entrypoint } = profile;
   const fingerprint = await createBillingFingerprint(
     firstUserText,
     cliVersion,
     crypto,
   );
-  const { entrypoint } = CLAUDE_CODE_2_1_195_PROFILE;
 
-  return {
-    type: "text",
-    text: `x-anthropic-billing-header: cc_version=${cliVersion}.${fingerprint}; cc_entrypoint=${entrypoint}; cch=00000;`,
-  };
+  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 };
 }