@oh-my-pi/pi-ai 16.1.15 → 16.1.17

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [16.1.17] - 2026-06-24
+
+### Added
+
+- Added provider-level `notes?: string[]` field to `UsageReport` for disclaimers that apply to every limit (e.g. "OMP-observed spend only"). The field is declared in both the `usage.ts` schema and the auth-broker wire schema copy so it survives the `"+": "reject"` deserialization gate. ([#3268](https://github.com/can1357/oh-my-pi/issues/3268))
+
+### Fixed
+
+- Moved the OpenCode Go "OMP-observed spend only" disclaimer from per-limit `notes` to provider-level `notes`, so it renders once per provider instead of duplicating across every account × window. ([#3268](https://github.com/can1357/oh-my-pi/issues/3268))
+- Fixed Anthropic rate-limit header usage cache entries retaining legacy missing account metadata after refresh.
+- Fixed Anthropic-compatible budget-effort models dropping the selected effort before request serialization, so `output_config.effort` is emitted alongside `thinking.budget_tokens` when model metadata declares `mode: "anthropic-budget-effort"`.
+- Fixed `anthropic-messages` silently dropping caller-supplied `Authorization` / `X-Api-Key` from `model.headers` and `ANTHROPIC_CUSTOM_HEADERS`, blocking custom proxy auth schemes. Non-OAuth requests now honor the caller's value (matching `openai-responses`); the lower-level client also suppresses its `X-Api-Key` add when a custom `Authorization` is supplied for a non-official endpoint so the proxy receives a single credential. OAuth bearer + Cloudflare AI Gateway keep their pre-existing enforced auth headers. ([#3391](https://github.com/can1357/oh-my-pi/issues/3391))
+- Fixed Ollama Cloud `num_predict` ignoring the provider's 65536 output-token cap so stale `models.db` rows (or custom `modelOverrides` re-enabling output caps) that carried `maxTokens: 1048576` from a pre-omitMaxOutputTokens catalog 400'd every request with `max_tokens (1048576) exceeds model's maximum output tokens (65536) for model deepseek-v4-pro`. The Ollama provider now clamps `num_predict` for any `ollama-cloud` request at the documented 65536 cap before sending, independent of the cached spec's `maxTokens` and on top of the existing `omitMaxOutputTokens` policy — so the request stays valid even when the load-time policy never normalized the spec. Self-hosted `ollama` traffic is unaffected. ([#3392](https://github.com/can1357/oh-my-pi/issues/3392))
+- Fixed OpenRouter Anthropic models on the Responses path omitting `cache_control`, so prompt caching engages without forcing Chat Completions. ([#3397](https://github.com/can1357/oh-my-pi/issues/3397))
+- Fixed OpenRouter Anthropic Responses follow-up requests replaying prior reasoning items with stale signatures, which caused HTTP 400 `Invalid signature in thinking block` errors after a thinking turn. ([#3399](https://github.com/can1357/oh-my-pi/issues/3399))
+- Fixed OpenRouter Anthropic models on the Responses path omitting `cache_control`, so prompt caching engages without forcing Chat Completions. `cacheRetention: "long"` now upgrades the breakpoint to `ttl: "1h"`. ([#3397](https://github.com/can1357/oh-my-pi/issues/3397))
+
+## [16.1.16] - 2026-06-23
+
+### Fixed
+
+- Fixed Anthropic-compatible thinking requests sending replayed thinking blocks without `context_management.keep: "all"`, preserving multi-turn reasoning context for API-key providers. API-key requests now also advertise the required `context-management-2025-06-27` beta header so the field is honored instead of rejected. Injected SDK clients, GitHub Copilot's Anthropic proxy, and Vertex rawPredict are excluded because this code path cannot add the beta to caller-owned clients, Copilot strips Anthropic betas and demotes thinking blocks to text upstream, and Vertex expects betas in the JSON body rather than the Anthropic HTTP beta header. ([#3288](https://github.com/can1357/oh-my-pi/issues/3288))
+- Fixed OpenRouter Responses native history replay leaking Gemini reasoning item `format` metadata back into follow-up requests, which caused HTTP 400 rejections while preserving encrypted reasoning replay.
+
 ## [16.1.15] - 2026-06-22
 
 ### Fixed

package/dist/types/auth-broker/wire-schemas.d.ts

@@ -332,6 +332,7 @@ export declare const usageResponseSchema: import("arktype/internal/variants/obje
         resetCredits?: {
             availableCount: number;
         } | undefined;
+        notes?: string[] | undefined;
         metadata?: {
             [x: string]: unknown;
         } | undefined;

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

@@ -76,6 +76,10 @@ interface OpenAIResponsesChainState {
     /** Set once chaining is judged unsupported for this session (circuit breaker). */
     disabled: boolean;
 }
+type OpenRouterAnthropicCacheControl = {
+    type: "ephemeral";
+    ttl?: "1h";
+};
 type OpenAIResponsesSamplingParams = ResponseCreateParamsStreaming & {
     top_p?: number;
     top_k?: number;
@@ -92,6 +96,7 @@ type OpenAIResponsesSamplingParams = ResponseCreateParamsStreaming & {
     } | {
         enabled: false;
     };
+    cache_control?: OpenRouterAnthropicCacheControl;
 };
 /**
  * Public entry: wrap the single-attempt Responses streamer with bounded

package/dist/types/usage.d.ts

@@ -68,6 +68,13 @@ export interface UsageReport {
     limits: UsageLimit[];
     /** Saved rate-limit resets the account can redeem, when the provider reports them. */
     resetCredits?: UsageResetCredits;
+    /**
+     * Provider-wide disclaimers shown once above per-account sections.
+     * Use this for caveats that apply to every limit (e.g. "OMP-observed
+     * spend only"). Per-limit notes that differ per window (e.g. "Overage
+     * requests: N") stay on {@link UsageLimit.notes}.
+     */
+    notes?: string[];
     metadata?: Record<string, unknown>;
     raw?: unknown;
 }
@@ -220,6 +227,7 @@ export declare const usageReportSchema: import("arktype/internal/variants/object
     resetCredits?: {
         availableCount: number;
     } | undefined;
+    notes?: string[] | undefined;
     metadata?: {
         [x: string]: unknown;
     } | undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "16.1.15",
+	"version": "16.1.17",
 	"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.1.15",
-		"@oh-my-pi/pi-utils": "16.1.15",
-		"@oh-my-pi/pi-wire": "16.1.15",
+		"@oh-my-pi/pi-catalog": "16.1.17",
+		"@oh-my-pi/pi-utils": "16.1.17",
+		"@oh-my-pi/pi-wire": "16.1.17",
 		"arktype": "^2.2.0",
 		"zod": "^4"
 	},

package/src/auth-broker/wire-schemas.ts

@@ -192,6 +192,7 @@ const arkUsageReportSchema = type({
 	fetchedAt: "number",
 	limits: usageLimitSchema.array(),
 	"resetCredits?": usageResetCreditsSchema,
+	"notes?": "string[]",
 	"metadata?": { "[string]": "unknown" },
 	"raw?": "unknown",
 });

package/src/auth-storage.ts

@@ -2326,8 +2326,13 @@ export class AuthStorage {
 		const last = this.#usageHeaderIngestAt.get(cacheKey);
 		if (last !== undefined && now - last < USAGE_HEADER_INGEST_INTERVAL_MS) return false;
 
-		const report = this.#usageProviderResolver?.(provider)?.parseRateLimitHeaders?.(headers, now);
-		if (!report) return false;
+		const parsedReport = this.#usageProviderResolver?.(provider)?.parseRateLimitHeaders?.(headers, now);
+		if (!parsedReport) return false;
+		const metadata: Record<string, unknown> = { ...(parsedReport.metadata ?? {}) };
+		if (credential.accountId && metadata.accountId === undefined) metadata.accountId = credential.accountId;
+		if (credential.email && metadata.email === undefined) metadata.email = credential.email;
+		if (credential.projectId && metadata.projectId === undefined) metadata.projectId = credential.projectId;
+		const report: UsageReport = { ...parsedReport, metadata };
 
 		const prior = this.#usageCache.getStale<UsageReport | null>(cacheKey)?.value;
 		let merged = report;
@@ -2351,6 +2356,7 @@ export class AuthStorage {
 				fetchedAt: now,
 				limits,
 				metadata: {
+					...(report.metadata ?? {}),
 					...(prior.metadata ?? {}),
 					headersUpdatedAt: now,
 				},

package/src/providers/anthropic.ts

@@ -120,10 +120,11 @@ export function buildBetaHeader(baseBetas: readonly string[], extraBetas: readon
 }
 
 const midConversationSystemBeta = "mid-conversation-system-2026-04-07";
+const contextManagementBeta = "context-management-2025-06-27";
 const claudeCodeUtilityBetaDefaults = [
 	"oauth-2025-04-20",
 	"interleaved-thinking-2025-05-14",
-	"context-management-2025-06-27",
+	contextManagementBeta,
 	"prompt-caching-scope-2026-01-05",
 	"structured-outputs-2025-12-15",
 ] as const;
@@ -131,7 +132,7 @@ const claudeCodeAgentBetaDefaults = [
 	"claude-code-20250219",
 	"oauth-2025-04-20",
 	"interleaved-thinking-2025-05-14",
-	"context-management-2025-06-27",
+	contextManagementBeta,
 	"prompt-caching-scope-2026-01-05",
 	midConversationSystemBeta,
 	"advanced-tool-use-2025-11-20",
@@ -192,10 +193,18 @@ export function buildAnthropicHeaders(options: AnthropicHeaderOptions): Record<s
 	const oauthToken = options.isOAuth ?? isAnthropicOAuthToken(options.apiKey);
 	const extraBetas = options.extraBetas ?? [];
 	const stream = options.stream ?? false;
-	// `enforcedHeaderKeys` strips User-Agent out of modelHeaders so a spread can't
-	// produce case-duplicate keys; re-add the caller's value explicitly per branch
-	// (OAuth replaces non-claude-cli values, the other branches forward verbatim).
+	// `enforcedHeaderKeys` strips User-Agent / X-Api-Key / Authorization out of
+	// modelHeaders so a case-insensitive spread can't produce duplicate keys; each
+	// branch re-adds the caller's value explicitly. User-Agent and X-Api-Key are
+	// always honored (with branch-specific defaults filling in when absent), while
+	// Authorization is honored for every non-OAuth, non-Cloudflare-gateway branch —
+	// OAuth requests MUST carry `Authorization: Bearer <oauth-token>` (the OAuth
+	// credential itself) and Cloudflare AI Gateway authenticates via
+	// `cf-aig-authorization`, so user-supplied auth there would just leak. Both of
+	// those cases drop + log the caller value (#3391).
 	const incomingUserAgent = getHeaderCaseInsensitive(options.modelHeaders, "User-Agent");
+	const incomingAuthorization = getHeaderCaseInsensitive(options.modelHeaders, "Authorization");
+	const incomingApiKey = getHeaderCaseInsensitive(options.modelHeaders, "X-Api-Key");
 	// Claude Code betas (oauth-2025-04-20, claude-code-20250219, …) are part of
 	// the OAuth fingerprint; API-key requests default to extras only, matching
 	// the streaming path (buildAnthropicClientOptions passes [] for non-OAuth).
@@ -204,14 +213,21 @@ export function buildAnthropicHeaders(options: AnthropicHeaderOptions): Record<s
 		extraBetas,
 	);
 	const acceptHeader = oauthToken ? "application/json" : stream ? "text/event-stream" : "application/json";
+	const isCloudflare = options.isCloudflareAiGateway ?? false;
+	const honorAuthorization = !oauthToken && !isCloudflare;
+	const honorApiKey = !isCloudflare;
 	const modelHeaders: Record<string, string> = {};
 	const filteredEnforcedKeys: string[] = [];
 	for (const [key, value] of Object.entries(options.modelHeaders ?? {})) {
 		const lowerKey = key.toLowerCase();
 		if (enforcedHeaderKeys.has(lowerKey)) {
-			// User-Agent is filtered only to dedup the spread; every branch re-adds
-			// the caller's value explicitly, so it is not "ignored".
-			if (lowerKey !== "user-agent") filteredEnforcedKeys.push(key);
+			// user-agent is always re-applied explicitly. authorization / x-api-key
+			// are silently re-applied in honoring branches and dropped + logged
+			// where the branch enforces its own credential.
+			if (lowerKey === "user-agent") continue;
+			if (lowerKey === "authorization" && honorAuthorization) continue;
+			if (lowerKey === "x-api-key" && honorApiKey) continue;
+			filteredEnforcedKeys.push(key);
 			continue;
 		}
 		modelHeaders[key] = value;
@@ -225,7 +241,7 @@ export function buildAnthropicHeaders(options: AnthropicHeaderOptions): Record<s
 		});
 	}
 
-	if (options.isCloudflareAiGateway) {
+	if (isCloudflare) {
 		return {
 			...modelHeaders,
 			Accept: acceptHeader,
@@ -250,15 +266,17 @@ export function buildAnthropicHeaders(options: AnthropicHeaderOptions): Record<s
 			...(options.claudeCodeSessionId ? { "X-Claude-Code-Session-Id": options.claudeCodeSessionId } : {}),
 			"x-client-request-id": nodeCrypto.randomUUID(),
 			"User-Agent": userAgent,
+			...(incomingApiKey ? { "X-Api-Key": incomingApiKey } : {}),
 		};
 	} else if (!isOfficialAnthropicApiUrl(options.baseUrl)) {
 		return {
 			...modelHeaders,
 			Accept: acceptHeader,
-			Authorization: `Bearer ${options.apiKey}`,
+			Authorization: incomingAuthorization ?? `Bearer ${options.apiKey}`,
 			...sharedHeaders,
 			...(incomingUserAgent ? { "User-Agent": incomingUserAgent } : {}),
 			...(betaHeader ? { "anthropic-beta": betaHeader } : {}),
+			...(incomingApiKey ? { "X-Api-Key": incomingApiKey } : {}),
 		};
 	} else {
 		return {
@@ -267,7 +285,8 @@ export function buildAnthropicHeaders(options: AnthropicHeaderOptions): Record<s
 			...sharedHeaders,
 			...(incomingUserAgent ? { "User-Agent": incomingUserAgent } : {}),
 			...(betaHeader ? { "anthropic-beta": betaHeader } : {}),
-			"X-Api-Key": options.apiKey,
+			...(incomingAuthorization ? { Authorization: incomingAuthorization } : {}),
+			"X-Api-Key": incomingApiKey ?? options.apiKey,
 		};
 	}
 }
@@ -1680,6 +1699,22 @@ const streamAnthropicOnce = (
 					// carry it in the Claude Code list).
 					extraBetas.push(midConversationSystemBeta);
 				}
+				// `context_management.clear_thinking_20251015` requires this beta. OAuth
+				// requests carry it in `claudeCodeAgentBetaDefaults`; API-key requests
+				// need it added explicitly so the field is honored instead of rejected
+				// (#3288). Skip transports where this package cannot deliver the beta
+				// in the form their adapter accepts: Copilot strips Anthropic betas,
+				// and Vertex rawPredict needs betas in the body (`anthropic_beta`),
+				// not as an `anthropic-beta` HTTP header.
+				if (
+					model.reasoning &&
+					options?.thinkingEnabled &&
+					model.provider !== "github-copilot" &&
+					model.provider !== "google-vertex" &&
+					!extraBetas.includes(contextManagementBeta)
+				) {
+					extraBetas.push(contextManagementBeta);
+				}
 
 				const created = createClient(model, {
 					model,
@@ -2530,12 +2565,15 @@ export function buildAnthropicClientOptions(args: AnthropicClientOptionsArgs): A
 		};
 	}
 
+	// Suppress the client-level `X-Api-Key` whenever an `Authorization` header
+	// already sits in `defaultHeaders` for a non-official, non-OAuth endpoint —
+	// either our auto-built `Bearer <apiKey>` or a caller-supplied custom auth
+	// scheme via `model.headers` (#3391). Adding a bonus `X-Api-Key` would force
+	// the proxy to deal with two competing credentials when the user explicitly
+	// asked for one.
 	const authorizationHeader = getHeaderCaseInsensitive(defaultHeaders, "Authorization");
 	const shouldSuppressClientApiKey =
-		!oauthToken &&
-		!model.compat.officialEndpoint &&
-		typeof authorizationHeader === "string" &&
-		/^Bearer\s+/i.test(authorizationHeader);
+		!oauthToken && !model.compat.officialEndpoint && typeof authorizationHeader === "string";
 
 	return {
 		isOAuthToken: oauthToken,
@@ -2944,11 +2982,28 @@ function buildParams(
 		}
 	}
 
-	// Pre-compute context_management (depends on thinking).
-	const contextManagement =
-		isOAuthToken && thinking?.type === "adaptive"
-			? { edits: [{ type: "clear_thinking_20251015" as const, keep: "all" as const }] }
-			: undefined;
+	// Pre-compute context_management. Send keep: "all" for every enabled or
+	// adaptive thinking request (OAuth + API-key) — not just OAuth. Without
+	// this directive Anthropic-compatible backends (Z.AI, Kimi, DeepSeek, …)
+	// strip the replayed thinking blocks `replayUnsignedThinking` puts back
+	// on the wire, so the model loses the prior reasoning chain across turns
+	// and the KV cache misses every turn (#3288). Narrowing this guard back
+	// to `isOAuthToken` regresses every API-key thinking provider. Skip
+	// injected clients because this code cannot add the required
+	// `context-management-2025-06-27` beta to caller-owned SDK clients. Skip
+	// Copilot because its proxy strips Anthropic betas and demotes thinking
+	// blocks to text upstream, so `keep: "all"` is a no-op that risks proxy
+	// rejection of an unrecognized field. Skip Vertex rawPredict because that
+	// adapter requires betas in the JSON body (`anthropic_beta`) instead of the
+	// Anthropic HTTP beta header this code can add.
+	const shouldKeepThinkingContext =
+		!options?.client &&
+		model.provider !== "github-copilot" &&
+		model.provider !== "google-vertex" &&
+		(thinking?.type === "adaptive" || thinking?.type === "enabled");
+	const contextManagement = shouldKeepThinkingContext
+		? { edits: [{ type: "clear_thinking_20251015" as const, keep: "all" as const }] }
+		: undefined;
 
 	// Pre-compute output_config.
 	const outputConfigEntries: AnthropicOutputConfig = {};

package/src/providers/ollama.ts

@@ -282,6 +282,26 @@ function convertTools(tools: Tool[] | undefined): OllamaFunctionTool[] | undefin
 	}));
 }
 
+/**
+ * Ollama Cloud rejects `num_predict` above this value with HTTP 400
+ * (`max_tokens (...) exceeds model's maximum output tokens (65536)`).
+ * The cap currently applies uniformly to cloud-served models; the cloud-side
+ * limit was confirmed empirically against `deepseek-v4-pro`/`-flash` and is
+ * the same cap surfaced for every other Ollama Cloud model we've probed.
+ *
+ * Acts as a wire-level safety net so stale `models.db` rows (or custom
+ * `modelOverrides` re-enabling `num_predict`) cannot 400 the request — even
+ * when `model.omitMaxOutputTokens` was never applied. See #3392.
+ */
+const OLLAMA_CLOUD_NUM_PREDICT_CAP = 65_536;
+
+function resolveNumPredict(model: Model<"ollama-chat">, requested: number): number {
+	if (model.provider === "ollama-cloud") {
+		return Math.min(requested, OLLAMA_CLOUD_NUM_PREDICT_CAP);
+	}
+	return requested;
+}
+
 function createChatBody(model: Model<"ollama-chat">, context: Context, options: OllamaChatOptions | undefined) {
 	const think = mapReasoning(model, options?.reasoning, options?.disableReasoning);
 	const toolChoice = mapToolChoice(options?.toolChoice);
@@ -294,7 +314,7 @@ function createChatBody(model: Model<"ollama-chat">, context: Context, options:
 		...(think !== undefined ? { think } : {}),
 		...(toolChoice !== undefined ? { tool_choice: toolChoice } : {}),
 		...(options?.maxTokens !== undefined && !model.omitMaxOutputTokens
-			? { options: { num_predict: options.maxTokens } }
+			? { options: { num_predict: resolveNumPredict(model, options.maxTokens) } }
 			: {}),
 		stream: true,
 	};

package/src/providers/openai-responses.ts

@@ -3,6 +3,7 @@ import { $flag, extractHttpStatusFromError, logger, structuredCloneJSON } from "
 import { getEnvApiKey } from "../stream";
 import type {
 	AssistantMessage,
+	CacheRetention,
 	Context,
 	Model,
 	OpenAICompat,
@@ -324,6 +325,8 @@ function markOpenAIResponsesChainZeroDataRetention(chain: OpenAIResponsesChainSt
 	});
 }
 
+type OpenRouterAnthropicCacheControl = { type: "ephemeral"; ttl?: "1h" };
+
 type OpenAIResponsesSamplingParams = ResponseCreateParamsStreaming & {
 	top_p?: number;
 	top_k?: number;
@@ -334,8 +337,19 @@ type OpenAIResponsesSamplingParams = ResponseCreateParamsStreaming & {
 	stream_options?: { include_obfuscation?: boolean };
 	provider?: OpenAICompat["openRouterRouting"];
 	reasoning?: { effort?: string } | { enabled: false };
+	cache_control?: OpenRouterAnthropicCacheControl;
 };
 
+function maybeAddOpenRouterAnthropicCacheControl(
+	params: OpenAIResponsesSamplingParams,
+	model: Model<"openai-responses">,
+	cacheRetention: CacheRetention,
+): void {
+	if (cacheRetention === "none" || !isOpenRouterAnthropicModel(model)) return;
+	if (params.cache_control != null) return;
+	params.cache_control = cacheRetention === "long" ? { type: "ephemeral", ttl: "1h" } : { type: "ephemeral" };
+}
+
 /**
  * Generate function for OpenAI Responses API
  */
@@ -777,7 +791,7 @@ export function buildParams(
 			replay: shouldReplayNativeHistory,
 			filterReasoning: policy.reasoning.filterReasoningHistory,
 		},
-		includeThinkingSignatures: shouldReplayNativeHistory,
+		includeThinkingSignatures: shouldReplayNativeHistory && !policy.reasoning.filterReasoningHistory,
 		repairOrphanOutputs: true,
 	});
 
@@ -823,6 +837,7 @@ export function buildParams(
 		store: false,
 		stream_options: model.compat.supportsObfuscationOptOut ? { include_obfuscation: false } : undefined,
 	};
+	maybeAddOpenRouterAnthropicCacheControl(params, model, cacheRetention);
 	const outputToken = resolveOpenAIOutputTokenParam({
 		field: "max_output_tokens",
 		maxTokens: options?.maxTokens,

package/src/stream.ts

@@ -847,10 +847,15 @@ function mapOptionsForApi<TApi extends Api>(
 				});
 			}
 
+			const thinkingMode = model.thinking?.mode;
+			const effort =
+				thinkingMode === "anthropic-adaptive" || thinkingMode === "anthropic-budget-effort"
+					? mapEffortToAnthropicAdaptiveEffort(model, reasoning)
+					: undefined;
+
 			// For Opus 4.6+ and Sonnet 4.6+: use adaptive thinking with effort level
 			// For older models: use budget-based thinking
-			if (model.thinking?.mode === "anthropic-adaptive") {
-				const effort = mapEffortToAnthropicAdaptiveEffort(model, reasoning);
+			if (thinkingMode === "anthropic-adaptive") {
 				return castApi<"anthropic-messages">({
 					...base,
 					requestModelId: resolveWireModelId(model, reasoning),
@@ -868,6 +873,7 @@ function mapOptionsForApi<TApi extends Api>(
 					requestModelId: resolveWireModelId(model, reasoning),
 					thinkingEnabled: true,
 					thinkingBudgetTokens: thinkingBudget,
+					effort,
 					toolChoice: mapAnthropicToolChoice(options?.toolChoice),
 					thinkingDisplay: options?.hideThinkingSummary ? "omitted" : undefined,
 					serviceTier: options?.serviceTier,
@@ -899,6 +905,7 @@ function mapOptionsForApi<TApi extends Api>(
 					requestModelId: resolveWireModelId(model, reasoning),
 					thinkingEnabled: true,
 					thinkingBudgetTokens: thinkingBudget,
+					effort,
 					toolChoice: mapAnthropicToolChoice(options?.toolChoice),
 					thinkingDisplay: options?.hideThinkingSummary ? "omitted" : undefined,
 					serviceTier: options?.serviceTier,

package/src/usage/opencode-go.ts

@@ -62,7 +62,6 @@ function buildWindowLimit(
 			unit: "usd",
 		},
 		status: resolveStatus(usedFraction),
-		notes: ["OMP-observed spend only; OpenCode usage outside OMP is not included."],
 	};
 }
 
@@ -80,6 +79,7 @@ export const opencodeGoUsageProvider: UsageProvider = {
 			provider: OPENCODE_GO_PROVIDER,
 			fetchedAt: nowMs,
 			limits: OPENCODE_GO_LIMITS.map(limit => buildWindowLimit(limit, entries, nowMs)),
+			notes: ["OMP-observed spend only; OpenCode usage outside OMP is not included."],
 			metadata: {
 				planType: "OpenCode Go",
 				source: "omp-observed-request-costs",

package/src/usage.ts

@@ -82,6 +82,13 @@ export interface UsageReport {
 	limits: UsageLimit[];
 	/** Saved rate-limit resets the account can redeem, when the provider reports them. */
 	resetCredits?: UsageResetCredits;
+	/**
+	 * Provider-wide disclaimers shown once above per-account sections.
+	 * Use this for caveats that apply to every limit (e.g. "OMP-observed
+	 * spend only"). Per-limit notes that differ per window (e.g. "Overage
+	 * requests: N") stay on {@link UsageLimit.notes}.
+	 */
+	notes?: string[];
 	metadata?: Record<string, unknown>;
 	raw?: unknown;
 }
@@ -204,6 +211,7 @@ export const usageReportSchema = type({
 	fetchedAt: "number",
 	limits: usageLimitSchema.array(),
 	"resetCredits?": usageResetCreditsSchema,
+	"notes?": "string[]",
 	"metadata?": { "[string]": "unknown" },
 	// `raw` is provider-specific and may be anything; the broker strips it before
 	// sending the report over the wire, so accept-but-ignore here.

package/src/utils.ts

@@ -78,6 +78,7 @@ function sanitizeOpenAIResponsesHistoryItemForReplay(
 ): OpenAIResponsesReplayItem | undefined {
 	if (item.type === "item_reference") return undefined;
 	if (item.type === "image_generation_call") return sanitizeOpenAIResponsesImageGenerationCallForReplay(item);
+	if (item.type === "reasoning") return sanitizeOpenAIResponsesReasoningItemForReplay(item);
 
 	// providerPayload stores raw output items; replay strips item ids and keeps only normalized call_id.
 	const { id: _id, ...sanitizedItem } = item;
@@ -88,6 +89,19 @@ function sanitizeOpenAIResponsesHistoryItemForReplay(
 	return sanitizedItem as unknown as OpenAIResponsesReplayItem;
 }
 
+function sanitizeOpenAIResponsesReasoningItemForReplay(item: Record<string, unknown>): OpenAIResponsesReplayItem {
+	const sanitizedItem: Record<string, unknown> = { type: "reasoning" };
+	if (Array.isArray(item.summary)) sanitizedItem.summary = item.summary;
+	if (Array.isArray(item.content)) sanitizedItem.content = item.content;
+	if (typeof item.encrypted_content === "string" || item.encrypted_content === null) {
+		sanitizedItem.encrypted_content = item.encrypted_content;
+	}
+	if (item.status === "in_progress" || item.status === "completed" || item.status === "incomplete") {
+		sanitizedItem.status = item.status;
+	}
+	return sanitizedItem as unknown as OpenAIResponsesReplayItem;
+}
+
 function sanitizeOpenAIResponsesImageGenerationCallForReplay(
 	item: Record<string, unknown>,
 ): ResponseInputItem.ImageGenerationCall | undefined {