@oh-my-pi/pi-ai 16.2.13 → 16.3.2

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [16.3.1] - 2026-07-02
+
+### Changed
+
+- Removed automated injection of reasoning suppression prompts in OpenAI responses
+
+## [16.3.0] - 2026-07-02
+
+### Added
+
+- Added opt-in support for Anthropic's server-side fallback beta (server-side-fallback-2026-06-01) on the anthropic-messages provider, including support for AnthropicOptions.fallbacks and automatic filtering of fallback blocks during cross-provider message transformations.
+
+### Changed
+
+- Improved stream healing for official first-party endpoints (Anthropic, OpenAI, and OpenAI Codex) by skipping leaked-thinking healing, preventing misfires on legitimate code blocks while maintaining healing for third-party gateways and custom base URLs.
+- Updated CoreWeave Serverless Inference login instructions to clarify persisting COREWEAVE_PROJECT in shell startup files.
+
+### Fixed
+
+- Fixed an issue where same-model Anthropic message replays incorrectly demoted unsigned thinking into textual content during API calls
+- Fixed a performance issue where broker usage fetch failures were not cached, causing redundant network requests when the broker is offline.
+- Fixed Xiaomi MiMo API key validation to use the supported mimo-v2.5 model.
+- Fixed certificate verification errors for custom gateways behind private CA bundles by ensuring NODE_EXTRA_CA_CERTS is respected across all provider fetches.
+- Fixed Claude Fable demoted-thinking replay to use markdown-italic assistant prose instead of <thinking> tags, preventing context issues after model switches.
+- Fixed OpenAI Responses replay errors (400 Bad Request) caused by missing reasoning items during history replay.
+
 ## [16.2.13] - 2026-07-01
 
 ### Fixed

package/README.md

@@ -965,7 +965,14 @@ For Cloudflare AI Gateway models, use provider base URL format
 
 For Anthropic Foundry routing, set `CLAUDE_CODE_USE_FOUNDRY=true` plus:
 `FOUNDRY_BASE_URL`, `ANTHROPIC_FOUNDRY_API_KEY`, optional `ANTHROPIC_CUSTOM_HEADERS`,
-and optional mTLS material (`CLAUDE_CODE_CLIENT_CERT`, `CLAUDE_CODE_CLIENT_KEY`, `NODE_EXTRA_CA_CERTS`).
+and optional mTLS material (`CLAUDE_CODE_CLIENT_CERT`, `CLAUDE_CODE_CLIENT_KEY`).
+
+`NODE_EXTRA_CA_CERTS` (PEM file path or inline PEM, mirroring Node's contract)
+is honoured on every provider fetch — OpenAI-compatible, Codex, Ollama, Azure
+Responses, Google, and Anthropic alike — for corporate relays or private CA
+bundles. Bun's `fetch` does not consume the env var natively, so omp injects
+the bundle into `RequestInit.tls.ca` and seeds the system root store
+alongside it.
 
 Provider endpoint defaults for the current OpenAI-compatible integrations:
 

package/dist/types/dialect/demotion.d.ts

@@ -5,13 +5,14 @@
  * replayed unsigned `thought` part is schema-accepted but silently discarded —
  * neither recalled nor influencing generation).
  *
- * The reasoning is rendered in the TARGET model's canonical inline thinking
- * delimiters so it reads as reasoning in that model's own idiom instead of bare
- * prose the model might continue. Harmony and Gemma are the exception: their
- * `renderThinking` emits chat-template control tokens (`<|channel|>analysis`,
- * `<|channel>thought`) that must not appear inside a structured native message,
- * so they fall back to a plain `<think>` block. Every other dialect's thinking
- * form is inline-safe XML tags or a markdown fence.
+ * Fable is the exception: replaying prior reasoning inside `<thinking>` /
+ * `antml:thinking`-style assistant text is treated as a reasoning-extraction
+ * attempt and can train the next turn to leak thoughts, so Fable receives the
+ * reasoning as markdown-italic assistant prose instead. Harmony and Gemma are
+ * also exceptions: their `renderThinking` emits chat-template control tokens
+ * (`<|channel|>analysis`, `<|channel>thought`) that must not appear inside a
+ * structured native message, so they fall back to a plain `<think>` block. Every
+ * other dialect's thinking form is inline-safe XML tags or a markdown fence.
  *
  * The result ends with a trailing newline so the block stays separated from the
  * turn's reply text when the wire encoder concatenates parts.

package/dist/types/providers/anthropic-wire.d.ts

@@ -66,7 +66,22 @@ export type RedactedThinkingBlockParam = {
     type: "redacted_thinking";
     data: string;
 };
-export type ContentBlockParam = TextBlockParam | ImageBlockParam | ToolUseBlockParam | ToolResultBlockParam | ThinkingBlockParam | RedactedThinkingBlockParam;
+/**
+ * Server-side fallback beta boundary marker (server-side-fallback-2026-06-01).
+ * Emitted by the API mid-stream when a classifier block on the requested
+ * model is retried on a fallback model. Only the official Anthropic
+ * endpoint accepts this block on replay — cross-provider hops MUST strip it.
+ */
+export type FallbackBlockParam = {
+    type: "fallback";
+    from: {
+        model: string;
+    };
+    to: {
+        model: string;
+    };
+};
+export type ContentBlockParam = TextBlockParam | ImageBlockParam | ToolUseBlockParam | ToolResultBlockParam | ThinkingBlockParam | RedactedThinkingBlockParam | FallbackBlockParam;
 /**
  * A single conversation turn.
  *
@@ -135,6 +150,18 @@ export type OutputConfig = {
     /** Task-budgets beta. */
     task_budget?: TokenTaskBudget | null;
 };
+/**
+ * Per-attempt override entry in `MessageCreateParams.fallbacks`
+ * (server-side-fallback-2026-06-01 beta). Every field except `model`
+ * mirrors a top-level control the beta allows re-specifying per attempt.
+ */
+export type FallbackParam = {
+    model: string;
+    max_tokens?: number;
+    thinking?: ThinkingConfigParam;
+    output_config?: OutputConfig;
+    speed?: "fast";
+};
 /** Claude Code context-management beta payload. */
 export type ContextManagement = {
     edits: Array<{
@@ -161,6 +188,12 @@ export type MessageCreateParams = {
     speed?: "fast";
     /** Claude Code context-management beta. */
     context_management?: ContextManagement;
+    /**
+     * Server-side fallback beta chain — up to three fallback models the API
+     * retries when a classifier blocks the primary. Required companion beta
+     * header: `server-side-fallback-2026-06-01`.
+     */
+    fallbacks?: FallbackParam[];
 };
 export type MessageCreateParamsStreaming = MessageCreateParams & {
     stream: true;
@@ -174,6 +207,20 @@ export type ServerToolUsage = {
     web_search_requests?: number | null;
     web_fetch_requests?: number | null;
 };
+/**
+ * Per-attempt token accounting inside a multi-run turn
+ * (server-side-fallback-2026-06-01). Populated whenever a fallback chain
+ * ran, including sticky-served turns with no `fallback` content block.
+ * A `fallback_message` entry is the definitive "served by fallback" signal.
+ */
+export type UsageIteration = {
+    type?: "message" | "fallback_message" | string;
+    model?: string | null;
+    input_tokens?: number | null;
+    output_tokens?: number | null;
+    cache_read_input_tokens?: number | null;
+    cache_creation_input_tokens?: number | null;
+};
 export type Usage = {
     input_tokens?: number | null;
     output_tokens?: number | null;
@@ -181,6 +228,7 @@ export type Usage = {
     cache_creation_input_tokens?: number | null;
     cache_creation?: CacheCreation | null;
     server_tool_use?: ServerToolUsage | null;
+    iterations?: UsageIteration[] | null;
 };
 /** The `message` envelope carried by `message_start`. */
 export type ResponseMessage = {
@@ -209,6 +257,14 @@ export type ResponseContentBlock = {
     id: string;
     name: string;
     input?: Record<string, unknown> | null;
+} | {
+    type: "fallback";
+    from: {
+        model: string;
+    };
+    to: {
+        model: string;
+    };
 };
 export type ContentBlockDelta = {
     type: "text_delta";

package/dist/types/providers/anthropic.d.ts

@@ -1,6 +1,6 @@
 import type { FetchImpl, Message, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, StreamFunction, StreamOptions, Usage } from "../types";
 import { type AnthropicFetchOptions, type AnthropicMessagesClientLike } from "./anthropic-client";
-import type { MessageParam, TextBlockParam } from "./anthropic-wire";
+import type { FallbackParam, MessageParam, TextBlockParam } from "./anthropic-wire";
 export type AnthropicHeaderOptions = {
     apiKey: string;
     baseUrl?: string;
@@ -135,6 +135,15 @@ export interface AnthropicOptions extends StreamOptions {
      * including SDK clients such as `AnthropicVertex`.
      */
     client?: AnthropicMessagesClientLike;
+    /**
+     * Server-side fallback beta chain (`server-side-fallback-2026-06-01`).
+     * When set, `fallbacks` is forwarded on the request body and the beta
+     * header is auto-attached; the response parser then honors mid-stream
+     * `fallback` content blocks and `usage.iterations` for served-model
+     * promotion and per-attempt pricing. Opt-in ONLY — leaving this
+     * undefined preserves the pre-fallback behavior on every code path.
+     */
+    fallbacks?: FallbackParam[];
 }
 export type AnthropicClientOptionsArgs = {
     model: Model<"anthropic-messages">;
@@ -223,6 +232,17 @@ export declare function buildAnthropicClientOptions(args: AnthropicClientOptions
  * `system` role (Opus 4.8+ and Fable/Mythos 5).
  */
 export type AnthropicMessageParam = MessageParam;
-export declare function convertAnthropicMessages(messages: Message[], model: Model<"anthropic-messages">, isOAuthToken: boolean): AnthropicMessageParam[];
+/**
+ * Serialize omp {@link Message}s to Anthropic wire messages.
+ *
+ * `opts.serverSideFallbackEnabled` — when the CURRENT request itself
+ * opts into the server-side-fallback beta chain. Only then may a persisted
+ * `fallback` content block from a prior turn be replayed on the wire;
+ * otherwise the block is dropped to avoid a 400 on non-fallback requests
+ * that don't send the beta.
+ */
+export declare function convertAnthropicMessages(messages: Message[], model: Model<"anthropic-messages">, isOAuthToken: boolean, opts?: {
+    serverSideFallbackEnabled?: boolean;
+}): AnthropicMessageParam[];
 export declare function normalizeAnthropicToolSchema(schema: unknown): unknown;
 export {};

package/dist/types/providers/openai-responses.d.ts

@@ -64,8 +64,8 @@ interface OpenAIResponsesProviderSessionState extends ProviderSessionState, Open
 }
 interface OpenAIResponsesChainState {
     /**
-     * Wire params of the last successful turn, with per-turn trailing
-     * scaffolding stripped from `input` (never carries previous_response_id).
+     * Wire params of the last successful turn; never carries
+     * `previous_response_id`.
      */
     lastParams?: OpenAIResponsesSamplingParams;
     lastResponseId?: string;
@@ -108,7 +108,6 @@ type OpenAIResponsesSamplingParams = ResponseCreateParamsStreaming & {
 export declare const streamOpenAIResponses: StreamFunction<"openai-responses">;
 export declare function buildParams(model: Model<"openai-responses">, context: Context, options: OpenAIResponsesOptions | undefined, providerSessionState: OpenAIResponsesProviderSessionState | undefined, strictToolsScope?: OpenAIStrictToolsScope, disableStrictToolsOverride?: boolean): {
     params: OpenAIResponsesSamplingParams;
-    trailingScaffoldingItems: number;
     strictToolsApplied: boolean;
 };
 /**

package/dist/types/providers/openai-shared.d.ts

@@ -359,9 +359,11 @@ export interface BuildResponsesInputOptions<TApi extends Api> {
     includeThinkingSignatures?: boolean;
     developerStringContent?: boolean;
     repairOrphanOutputs?: boolean;
+    /** Preserve assistant message item IDs from text signatures during fallback replay. */
+    preserveAssistantMessageIds?: boolean;
 }
 export declare function buildResponsesInput<TApi extends Api>(options: BuildResponsesInputOptions<TApi>): ResponseInput;
-export declare function convertResponsesAssistantMessage<TApi extends Api>(assistantMsg: AssistantMessage, model: Model<TApi>, msgIndex: number, knownCallIds: Set<string>, includeThinkingSignatures?: boolean, customCallIds?: Set<string>): ResponseInput;
+export declare function convertResponsesAssistantMessage<TApi extends Api>(assistantMsg: AssistantMessage, model: Model<TApi>, msgIndex: number, knownCallIds: Set<string>, includeThinkingSignatures?: boolean, customCallIds?: Set<string>, preserveMessageIds?: boolean): ResponseInput;
 export declare function appendResponsesToolResultMessages<TApi extends Api>(messages: ResponseInput, toolResult: ToolResultMessage, model: Model<TApi>, strictResponsesPairing: boolean, supportsImageDetailOriginal: boolean, knownCallIds: ReadonlySet<string>, customCallIds?: ReadonlySet<string>): void;
 /**
  * Per-block accumulation helpers shared by the two Responses decode loops —
@@ -463,12 +465,12 @@ export interface ApplyResponsesCompatPolicyOptions {
     reasoningSummary?: "auto" | "detailed" | "concise" | null;
     mapEffort?: (effort: string) => string;
 }
-export declare function applyResponsesCompatPolicy<P extends ResponseCreateParamsStreaming>(params: P, messages: ResponseInput, policy: OpenAICompatPolicy, options: ApplyResponsesCompatPolicyOptions | undefined): number;
+export declare function applyResponsesCompatPolicy<P extends ResponseCreateParamsStreaming>(params: P, policy: OpenAICompatPolicy, options: ApplyResponsesCompatPolicyOptions | undefined): void;
 /**
  * Apply reasoning-related Responses parameters. Default behavior comes from
  * catalog compat; include/omit arguments are explicit adapter-wrapper overrides.
  */
-export declare function applyResponsesReasoningParams<P extends ResponseCreateParamsStreaming>(params: P, model: Model<"openai-responses" | "azure-openai-responses" | "openai-codex-responses">, options: ReasoningOptions | undefined, messages: ResponseInput, mapEffort?: (effort: string) => string, includeEncryptedReasoning?: boolean, omitReasoningEffort?: boolean): number;
+export declare function applyResponsesReasoningParams<P extends ResponseCreateParamsStreaming>(params: P, model: Model<"openai-responses" | "azure-openai-responses" | "openai-codex-responses">, options: ReasoningOptions | undefined, mapEffort?: (effort: string) => string, includeEncryptedReasoning?: boolean, omitReasoningEffort?: boolean): void;
 /** Populate `output.usage` from a Responses-API `response.usage` payload. Does not invoke `calculateCost`. */
 export declare function populateResponsesUsageFromResponse(output: AssistantMessage, usage: {
     input_tokens?: number | null;

package/dist/types/types.d.ts

@@ -8,7 +8,7 @@ import type { ZodType, z } from "zod/v4";
 import type { ApiKey } from "./auth-retry";
 import type { BedrockOptions } from "./providers/amazon-bedrock";
 import type { AnthropicOptions } from "./providers/anthropic";
-import type { StopDetails } from "./providers/anthropic-wire";
+import type { FallbackParam, StopDetails } from "./providers/anthropic-wire";
 import type { AzureOpenAIResponsesOptions } from "./providers/azure-openai-responses";
 import type { CursorOptions } from "./providers/cursor";
 import type { DevinOptions } from "./providers/devin";
@@ -384,6 +384,13 @@ export interface SimpleStreamOptions extends Omit<StreamOptions, "apiKey"> {
     openrouterVariant?: string;
     /** Antigravity endpoint routing mode: "auto" (default with failover), "production", "sandbox". */
     antigravityEndpointMode?: "auto" | "production" | "sandbox";
+    /**
+     * Anthropic `server-side-fallback-2026-06-01` fallback chain (top-level
+     * `fallbacks` request field). Opt-in ONLY — leaving this undefined is
+     * the default and preserves the pre-fallback behavior on every
+     * provider. Non-Anthropic providers ignore the field.
+     */
+    fallbacks?: FallbackParam[];
 }
 export type StreamFunction<TApi extends Api> = (model: Model<TApi>, context: Context, options: OptionsForApi<TApi>) => AssistantMessageEventStream;
 export interface TextSignatureV1 {
@@ -406,6 +413,23 @@ export interface RedactedThinkingContent {
     type: "redactedThinking";
     data: string;
 }
+/**
+ * Anthropic server-side-fallback boundary marker persisted on assistant
+ * turns whose provider request opted into
+ * `AnthropicOptions.fallbacks`. Consumers other than the Anthropic
+ * provider MUST ignore it — `transformMessages` strips the block on any
+ * cross-provider hop and on non-official Anthropic replays, so downstream
+ * converters never see it.
+ */
+export interface AnthropicFallbackContent {
+    type: "fallback";
+    from: {
+        model: string;
+    };
+    to: {
+        model: string;
+    };
+}
 export interface ImageContent {
     type: "image";
     data: string;
@@ -476,7 +500,7 @@ export interface ContextSnapshot {
 }
 export interface AssistantMessage {
     role: "assistant";
-    content: (TextContent | ThinkingContent | RedactedThinkingContent | ToolCall)[];
+    content: (TextContent | ThinkingContent | RedactedThinkingContent | AnthropicFallbackContent | ToolCall)[];
     api: Api;
     provider: Provider;
     model: string;

package/dist/types/utils/leaked-thinking-stream.d.ts

@@ -3,11 +3,15 @@
  *
  * Some providers emit their canonical reasoning idioms (` ```thinking `,
  * `<think>`, Gemma/Harmony channels, …) into the *visible* text stream instead
- * of a structured thinking part. {@link wrapLeakedThinkingStream} re-projects any
+ * of a structured thinking part. {@link wrapLeakedThinkingStream} re-projects a
  * provider stream into a fresh {@link AssistantMessageEventStream}, splitting the
- * leaked fences out into proper `thinking` blocks *live* as deltas arrive — so
- * every provider gets the same healing, not just the three with provider-local
- * {@link StreamMarkupHealing} loops.
+ * leaked fences out into proper `thinking` blocks *live* as deltas arrive.
+ *
+ * Applied to every provider stream *except* official first-party endpoints
+ * (the official Anthropic API and the official OpenAI / OpenAI-Codex endpoints),
+ * which return structured thinking and never leak — `healLeakedThinking` in
+ * `../stream.ts` gates the wrap so the healer cannot misfire on legitimate
+ * fenced content those models emit as visible text.
  *
  * The healing is idempotent: a second pass over already-clean text finds no
  * fences, so wrapping a provider that already heals (or wrapping twice) is a

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "16.2.13",
+	"version": "16.3.2",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,9 +38,9 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.0",
-		"@oh-my-pi/pi-catalog": "16.2.13",
-		"@oh-my-pi/pi-utils": "16.2.13",
-		"@oh-my-pi/pi-wire": "16.2.13",
+		"@oh-my-pi/pi-catalog": "16.3.2",
+		"@oh-my-pi/pi-utils": "16.3.2",
+		"@oh-my-pi/pi-wire": "16.3.2",
 		"arktype": "^2.2.0",
 		"zod": "^4"
 	},

package/src/auth-broker/remote-store.ts

@@ -58,7 +58,13 @@ interface CacheEntry {
 }
 
 interface UsageCacheEntry {
-	reports: UsageReport[];
+	/**
+	 * `null` means the last aggregate `/v1/usage` fetch failed. Callers treat
+	 * this the same as a successful empty-report response ("no usage signal
+	 * for this cycle"), and the same 15s TTL applies so transient broker
+	 * outages don't turn every ranking pass into a broker retry storm.
+	 */
+	reports: UsageReport[] | null;
 	fetchedAt: number;
 }
 
@@ -573,6 +579,10 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 			})
 			.catch(error => {
 				logger.warn("auth-broker usage fetch failed", { error: String(error) });
+				// Documented 15s TTL fallback: cache the null so sequential callers
+				// don't re-hit the broker while it's still down. See
+				// docs/auth-broker-gateway.md § "Client-side single-flight".
+				this.#usageCache = { reports: null, fetchedAt: Date.now() };
 				return null;
 			})
 			.finally(() => {

package/src/dialect/demotion.ts

@@ -1,6 +1,8 @@
-import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";
+import { bareModelId, preferredDialect } from "@oh-my-pi/pi-catalog/identity";
 import { getDialectDefinition } from "./factory";
 
+const CLAUDE_FABLE_ID = /(?:^|[./])claude[-.]fable(?:[-.]|$)/i;
+
 /**
  * Wrap a prior-turn reasoning string for demotion into native conversation
  * history — the cross-provider / cross-model case where the target cannot replay
@@ -8,13 +10,14 @@ import { getDialectDefinition } from "./factory";
  * replayed unsigned `thought` part is schema-accepted but silently discarded —
  * neither recalled nor influencing generation).
  *
- * The reasoning is rendered in the TARGET model's canonical inline thinking
- * delimiters so it reads as reasoning in that model's own idiom instead of bare
- * prose the model might continue. Harmony and Gemma are the exception: their
- * `renderThinking` emits chat-template control tokens (`<|channel|>analysis`,
- * `<|channel>thought`) that must not appear inside a structured native message,
- * so they fall back to a plain `<think>` block. Every other dialect's thinking
- * form is inline-safe XML tags or a markdown fence.
+ * Fable is the exception: replaying prior reasoning inside `<thinking>` /
+ * `antml:thinking`-style assistant text is treated as a reasoning-extraction
+ * attempt and can train the next turn to leak thoughts, so Fable receives the
+ * reasoning as markdown-italic assistant prose instead. Harmony and Gemma are
+ * also exceptions: their `renderThinking` emits chat-template control tokens
+ * (`<|channel|>analysis`, `<|channel>thought`) that must not appear inside a
+ * structured native message, so they fall back to a plain `<think>` block. Every
+ * other dialect's thinking form is inline-safe XML tags or a markdown fence.
  *
  * The result ends with a trailing newline so the block stays separated from the
  * turn's reply text when the wire encoder concatenates parts.
@@ -25,7 +28,9 @@ import { getDialectDefinition } from "./factory";
 export function renderDemotedThinking(modelId: string, text: string): string {
 	if (!text) return "";
 	text = text.toWellFormed();
+	const canonicalId = bareModelId(modelId);
 	const dialect = preferredDialect(modelId);
+	if (CLAUDE_FABLE_ID.test(canonicalId)) return `_Hmm. ${text}_\n`;
 	if (dialect === "harmony" || dialect === "gemma") return `<think>\n${text}\n</think>\n`;
 	return `${getDialectDefinition(dialect).renderThinking(text)}\n`;
 }

package/src/providers/anthropic-wire.ts

@@ -76,13 +76,26 @@ export type RedactedThinkingBlockParam = {
 	data: string;
 };
 
+/**
+ * Server-side fallback beta boundary marker (server-side-fallback-2026-06-01).
+ * Emitted by the API mid-stream when a classifier block on the requested
+ * model is retried on a fallback model. Only the official Anthropic
+ * endpoint accepts this block on replay — cross-provider hops MUST strip it.
+ */
+export type FallbackBlockParam = {
+	type: "fallback";
+	from: { model: string };
+	to: { model: string };
+};
+
 export type ContentBlockParam =
 	| TextBlockParam
 	| ImageBlockParam
 	| ToolUseBlockParam
 	| ToolResultBlockParam
 	| ThinkingBlockParam
-	| RedactedThinkingBlockParam;
+	| RedactedThinkingBlockParam
+	| FallbackBlockParam;
 
 /**
  * A single conversation turn.
@@ -151,6 +164,19 @@ export type OutputConfig = {
 	task_budget?: TokenTaskBudget | null;
 };
 
+/**
+ * Per-attempt override entry in `MessageCreateParams.fallbacks`
+ * (server-side-fallback-2026-06-01 beta). Every field except `model`
+ * mirrors a top-level control the beta allows re-specifying per attempt.
+ */
+export type FallbackParam = {
+	model: string;
+	max_tokens?: number;
+	thinking?: ThinkingConfigParam;
+	output_config?: OutputConfig;
+	speed?: "fast";
+};
+
 /** Claude Code context-management beta payload. */
 export type ContextManagement = {
 	edits: Array<{ type: "clear_thinking_20251015"; keep: "all" }>;
@@ -175,6 +201,12 @@ export type MessageCreateParams = {
 	speed?: "fast";
 	/** Claude Code context-management beta. */
 	context_management?: ContextManagement;
+	/**
+	 * Server-side fallback beta chain — up to three fallback models the API
+	 * retries when a classifier blocks the primary. Required companion beta
+	 * header: `server-side-fallback-2026-06-01`.
+	 */
+	fallbacks?: FallbackParam[];
 };
 
 export type MessageCreateParamsStreaming = MessageCreateParams & { stream: true };
@@ -201,6 +233,21 @@ export type ServerToolUsage = {
 	web_fetch_requests?: number | null;
 };
 
+/**
+ * Per-attempt token accounting inside a multi-run turn
+ * (server-side-fallback-2026-06-01). Populated whenever a fallback chain
+ * ran, including sticky-served turns with no `fallback` content block.
+ * A `fallback_message` entry is the definitive "served by fallback" signal.
+ */
+export type UsageIteration = {
+	type?: "message" | "fallback_message" | string;
+	model?: string | null;
+	input_tokens?: number | null;
+	output_tokens?: number | null;
+	cache_read_input_tokens?: number | null;
+	cache_creation_input_tokens?: number | null;
+};
+
 export type Usage = {
 	input_tokens?: number | null;
 	output_tokens?: number | null;
@@ -208,6 +255,7 @@ export type Usage = {
 	cache_creation_input_tokens?: number | null;
 	cache_creation?: CacheCreation | null;
 	server_tool_use?: ServerToolUsage | null;
+	iterations?: UsageIteration[] | null;
 };
 
 /** The `message` envelope carried by `message_start`. */
@@ -229,7 +277,8 @@ export type ResponseContentBlock =
 	| { type: "text"; text: string }
 	| { type: "thinking"; thinking: string; signature?: string }
 	| { type: "redacted_thinking"; data: string }
-	| { type: "tool_use"; id: string; name: string; input?: Record<string, unknown> | null };
+	| { type: "tool_use"; id: string; name: string; input?: Record<string, unknown> | null }
+	| { type: "fallback"; from: { model: string }; to: { model: string } };
 
 export type ContentBlockDelta =
 	| { type: "text_delta"; text: string }