@gajae-code/ai 0.11.7 → 0.11.8

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [0.11.8] - 2026-07-23
+
+### Fixed
+
+- OpenAI Responses / Codex native history replay no longer submits missing resident-image placeholders as `input_image.image_url`. Invalid values (including `[Session resident imageUrl blob missing: …]`) are dropped, or retained as `file_id`-only parts when a non-empty `file_id` is present, so a single unavailable historical image cannot brick `/retry` (#2924).
+- Raised the first-event stream timeout floor to five minutes for `alibaba-token-plan` models using the OpenAI Completions and Responses APIs, while preserving caller and environment overrides and the existing inter-event idle timeout.
+- OAuth refresh peer-rotation recovery now runs before failure classification instead of only on the definitive-failure path, and the definitive matcher recognizes the "grant is invalid" phrasing. Providers whose invalid-grant response does not contain the literal `invalid_grant` (e.g. Kimi's 400 "The provided authorization grant is invalid") previously had rotation races misclassified as transient, temp-blocking a healthy credential for five minutes on every race; with Kimi's ~12-minute access tokens and multiple processes sharing the credential store this surfaced as repeated logouts. Genuine revocations are now disabled with a cause instead of looping temp-blocks.
+- Anthropic 400 `Invalid \`signature\` in \`thinking\` block` responses now trigger the one-shot thinking replay repair instead of failing the turn. The existing repair matcher only recognized the "latest assistant message ... cannot be modified" wording, so the signature-validation variant — which can cite a `thinking`/`redacted_thinking` block anywhere in the replayed history (e.g. after compaction/pruning rewrote an earlier turn) — was treated as a fatal request error. The retry now rebuilds the request with thinking blocks dropped from every replayed assistant message (`repairAllAssistantThinking`), while the latest-message mutation variant keeps the targeted latest-only repair.
+
+### Changed
+
+- Raw tool-argument rejection hooks can now select from bounded, authority-controlled correction codes. Unknown or extension-supplied values retain the byte-for-byte generic rejection instead of reaching model-visible validation errors.
+
 ## [0.11.7] - 2026-07-22
 
 ### Changed

package/dist/types/auth-broker/client.d.ts

@@ -1,5 +1,5 @@
 import type { AuthCredential } from "../auth-storage";
-import type { CredentialDisableResponse, CredentialIfAbsentUploadResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageResponse } from "./types";
+import type { CredentialDisableResponse, CredentialIfAbsentUploadResponse, CredentialRefreshRequest, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageResponse } from "./types";
 export interface AuthBrokerClientOptions {
     /** Base URL (e.g. `https://broker.tailnet:8765`). Trailing slashes are trimmed. */
     url: string;
@@ -61,6 +61,7 @@ export declare class AuthBrokerClient {
     }): AsyncGenerator<SnapshotStreamEvent>;
     fetchUsage(signal?: AbortSignal): Promise<UsageResponse>;
     refreshCredential(id: number, signal?: AbortSignal): Promise<CredentialRefreshResponse>;
+    refreshMCPCredential(id: number, body: CredentialRefreshRequest, signal?: AbortSignal): Promise<CredentialRefreshResponse>;
     disableCredential(id: number, cause: string, signal?: AbortSignal): Promise<CredentialDisableResponse>;
     uploadCredential(provider: string, credential: AuthCredential, signal?: AbortSignal): Promise<CredentialUploadResponse>;
     uploadCredentialIfAbsent(provider: string, credential: AuthCredential, signal?: AbortSignal): Promise<CredentialIfAbsentUploadResponse>;

package/dist/types/auth-broker/remote-store.d.ts

@@ -1,4 +1,4 @@
-import { type AuthCredential, type AuthCredentialIfAbsentResult, type AuthCredentialStore, type OAuthCredential, type StoredAuthCredential } from "../auth-storage";
+import { type AuthCredential, type AuthCredentialIfAbsentResult, type AuthCredentialStore, type MCPOAuthRefreshClient, type OAuthCredential, type StoredAuthCredential } from "../auth-storage";
 import type { Provider } from "../types";
 import type { UsageReport } from "../usage";
 import type { OAuthCredentials } from "../utils/oauth/types";
@@ -78,6 +78,7 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
      * the `refresh` slot.
      */
     refreshOAuthCredential(_provider: Provider, credentialId: number, _credential: OAuthCredential, signal?: AbortSignal): Promise<OAuthCredentials>;
+    refreshMCPOAuthCredential(credentialId: number, credential: OAuthCredential, client: MCPOAuthRefreshClient, signal?: AbortSignal): Promise<OAuthCredential>;
     /**
      * Store-level hook consumed by `AuthStorage.fetchUsageReports()` — proxies
      * to the broker's `/v1/usage` endpoint. The broker's egress IP isn't

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

@@ -5,7 +5,7 @@
  * clients use `access` tokens directly and call back to the broker when a
  * credential expires or a 401 surfaces on a supposedly-fresh credential.
  */
-import type { AuthCredential, AuthCredentialIfAbsentReason, AuthCredentialSnapshot, AuthCredentialSnapshotEntry } from "../auth-storage";
+import type { AuthCredential, AuthCredentialIfAbsentReason, AuthCredentialSnapshot, AuthCredentialSnapshotEntry, MCPOAuthRefreshClient } from "../auth-storage";
 import type { UsageReport } from "../usage";
 /** GET /v1/healthz response body. */
 export interface HealthzResponse {
@@ -36,6 +36,8 @@ export interface UsageResponse {
 export interface CredentialRefreshResponse {
     entry: AuthCredentialSnapshotEntry;
 }
+/** Optional MCP client metadata; the broker still selects the stored token endpoint. */
+export type CredentialRefreshRequest = MCPOAuthRefreshClient;
 /** POST /v1/credential/:id/disable request body. */
 export interface CredentialDisableRequest {
     cause: string;

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

@@ -11,6 +11,10 @@
  * `hasOnlyFields` allowlist for the same effect.
  */
 import * as z from "zod/v4";
+export declare const mcpOAuthBindingSchema: z.ZodObject<{
+    resourceOrigin: z.ZodString;
+    tokenEndpoint: z.ZodString;
+}, z.core.$strict>;
 /** Real OAuth credential (broker-side) — refresh token is the actual upstream value. */
 export declare const oauthCredentialSchema: z.ZodObject<{
     type: z.ZodLiteral<"oauth">;
@@ -21,6 +25,10 @@ export declare const oauthCredentialSchema: z.ZodObject<{
     projectId: z.ZodOptional<z.ZodString>;
     email: z.ZodOptional<z.ZodString>;
     accountId: z.ZodOptional<z.ZodString>;
+    mcpBinding: z.ZodOptional<z.ZodObject<{
+        resourceOrigin: z.ZodString;
+        tokenEndpoint: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 /** OAuth credential as it appears in broker snapshots — refresh replaced with sentinel. */
 export declare const remoteOauthCredentialSchema: z.ZodObject<{
@@ -31,6 +39,10 @@ export declare const remoteOauthCredentialSchema: z.ZodObject<{
     projectId: z.ZodOptional<z.ZodString>;
     email: z.ZodOptional<z.ZodString>;
     accountId: z.ZodOptional<z.ZodString>;
+    mcpBinding: z.ZodOptional<z.ZodObject<{
+        resourceOrigin: z.ZodString;
+        tokenEndpoint: z.ZodString;
+    }, z.core.$strict>>;
     refresh: z.ZodLiteral<"__remote__">;
 }, z.core.$strict>;
 export declare const apiKeyCredentialSchema: z.ZodObject<{
@@ -47,6 +59,10 @@ export declare const writableAuthCredentialSchema: z.ZodDiscriminatedUnion<[z.Zo
     projectId: z.ZodOptional<z.ZodString>;
     email: z.ZodOptional<z.ZodString>;
     accountId: z.ZodOptional<z.ZodString>;
+    mcpBinding: z.ZodOptional<z.ZodObject<{
+        resourceOrigin: z.ZodString;
+        tokenEndpoint: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"api_key">;
     key: z.ZodString;
@@ -60,6 +76,10 @@ export declare const snapshotCredentialSchema: z.ZodDiscriminatedUnion<[z.ZodObj
     projectId: z.ZodOptional<z.ZodString>;
     email: z.ZodOptional<z.ZodString>;
     accountId: z.ZodOptional<z.ZodString>;
+    mcpBinding: z.ZodOptional<z.ZodObject<{
+        resourceOrigin: z.ZodString;
+        tokenEndpoint: z.ZodString;
+    }, z.core.$strict>>;
     refresh: z.ZodLiteral<"__remote__">;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"api_key">;
@@ -76,6 +96,10 @@ export declare const credentialSnapshotEntrySchema: z.ZodObject<{
         projectId: z.ZodOptional<z.ZodString>;
         email: z.ZodOptional<z.ZodString>;
         accountId: z.ZodOptional<z.ZodString>;
+        mcpBinding: z.ZodOptional<z.ZodObject<{
+            resourceOrigin: z.ZodString;
+            tokenEndpoint: z.ZodString;
+        }, z.core.$strict>>;
         refresh: z.ZodLiteral<"__remote__">;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"api_key">;
@@ -94,6 +118,10 @@ export declare const snapshotEntrySchema: z.ZodObject<{
         projectId: z.ZodOptional<z.ZodString>;
         email: z.ZodOptional<z.ZodString>;
         accountId: z.ZodOptional<z.ZodString>;
+        mcpBinding: z.ZodOptional<z.ZodObject<{
+            resourceOrigin: z.ZodString;
+            tokenEndpoint: z.ZodString;
+        }, z.core.$strict>>;
         refresh: z.ZodLiteral<"__remote__">;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"api_key">;
@@ -129,6 +157,10 @@ export declare const snapshotResponseSchema: z.ZodObject<{
             projectId: z.ZodOptional<z.ZodString>;
             email: z.ZodOptional<z.ZodString>;
             accountId: z.ZodOptional<z.ZodString>;
+            mcpBinding: z.ZodOptional<z.ZodObject<{
+                resourceOrigin: z.ZodString;
+                tokenEndpoint: z.ZodString;
+            }, z.core.$strict>>;
             refresh: z.ZodLiteral<"__remote__">;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"api_key">;
@@ -160,6 +192,10 @@ export declare const snapshotStreamSnapshotEventSchema: z.ZodObject<{
             projectId: z.ZodOptional<z.ZodString>;
             email: z.ZodOptional<z.ZodString>;
             accountId: z.ZodOptional<z.ZodString>;
+            mcpBinding: z.ZodOptional<z.ZodObject<{
+                resourceOrigin: z.ZodString;
+                tokenEndpoint: z.ZodString;
+            }, z.core.$strict>>;
             refresh: z.ZodLiteral<"__remote__">;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"api_key">;
@@ -192,6 +228,10 @@ export declare const snapshotStreamEntryEventSchema: z.ZodObject<{
             projectId: z.ZodOptional<z.ZodString>;
             email: z.ZodOptional<z.ZodString>;
             accountId: z.ZodOptional<z.ZodString>;
+            mcpBinding: z.ZodOptional<z.ZodObject<{
+                resourceOrigin: z.ZodString;
+                tokenEndpoint: z.ZodString;
+            }, z.core.$strict>>;
             refresh: z.ZodLiteral<"__remote__">;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"api_key">;
@@ -236,6 +276,10 @@ export declare const snapshotStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
             projectId: z.ZodOptional<z.ZodString>;
             email: z.ZodOptional<z.ZodString>;
             accountId: z.ZodOptional<z.ZodString>;
+            mcpBinding: z.ZodOptional<z.ZodObject<{
+                resourceOrigin: z.ZodString;
+                tokenEndpoint: z.ZodString;
+            }, z.core.$strict>>;
             refresh: z.ZodLiteral<"__remote__">;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"api_key">;
@@ -266,6 +310,10 @@ export declare const snapshotStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
             projectId: z.ZodOptional<z.ZodString>;
             email: z.ZodOptional<z.ZodString>;
             accountId: z.ZodOptional<z.ZodString>;
+            mcpBinding: z.ZodOptional<z.ZodObject<{
+                resourceOrigin: z.ZodString;
+                tokenEndpoint: z.ZodString;
+            }, z.core.$strict>>;
             refresh: z.ZodLiteral<"__remote__">;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"api_key">;
@@ -348,6 +396,10 @@ export declare const usageResponseSchema: z.ZodObject<{
         raw: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>>;
 }, z.core.$strict>;
+export declare const credentialRefreshRequestSchema: z.ZodObject<{
+    clientId: z.ZodOptional<z.ZodString>;
+    clientSecret: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 export declare const credentialRefreshResponseSchema: z.ZodObject<{
     entry: z.ZodObject<{
         id: z.ZodNumber;
@@ -360,6 +412,10 @@ export declare const credentialRefreshResponseSchema: z.ZodObject<{
             projectId: z.ZodOptional<z.ZodString>;
             email: z.ZodOptional<z.ZodString>;
             accountId: z.ZodOptional<z.ZodString>;
+            mcpBinding: z.ZodOptional<z.ZodObject<{
+                resourceOrigin: z.ZodString;
+                tokenEndpoint: z.ZodString;
+            }, z.core.$strict>>;
             refresh: z.ZodLiteral<"__remote__">;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"api_key">;
@@ -385,6 +441,10 @@ export declare const credentialUploadRequestSchema: z.ZodObject<{
         projectId: z.ZodOptional<z.ZodString>;
         email: z.ZodOptional<z.ZodString>;
         accountId: z.ZodOptional<z.ZodString>;
+        mcpBinding: z.ZodOptional<z.ZodObject<{
+            resourceOrigin: z.ZodString;
+            tokenEndpoint: z.ZodString;
+        }, z.core.$strict>>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"api_key">;
         key: z.ZodString;
@@ -402,6 +462,10 @@ export declare const credentialUploadResponseSchema: z.ZodObject<{
             projectId: z.ZodOptional<z.ZodString>;
             email: z.ZodOptional<z.ZodString>;
             accountId: z.ZodOptional<z.ZodString>;
+            mcpBinding: z.ZodOptional<z.ZodObject<{
+                resourceOrigin: z.ZodString;
+                tokenEndpoint: z.ZodString;
+            }, z.core.$strict>>;
             refresh: z.ZodLiteral<"__remote__">;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"api_key">;
@@ -433,6 +497,10 @@ export declare const credentialIfAbsentUploadResponseSchema: z.ZodObject<{
             projectId: z.ZodOptional<z.ZodString>;
             email: z.ZodOptional<z.ZodString>;
             accountId: z.ZodOptional<z.ZodString>;
+            mcpBinding: z.ZodOptional<z.ZodObject<{
+                resourceOrigin: z.ZodString;
+                tokenEndpoint: z.ZodString;
+            }, z.core.$strict>>;
             refresh: z.ZodLiteral<"__remote__">;
         }, z.core.$strict>, z.ZodObject<{
             type: z.ZodLiteral<"api_key">;

package/dist/types/auth-storage.d.ts

@@ -15,10 +15,26 @@ export type ApiKeyCredential = {
     type: "api_key";
     key: string;
 };
+export interface MCPOAuthBinding {
+    /** Exact HTTP(S) origin of the MCP resource endpoint. */
+    resourceOrigin: string;
+    /** Exact canonical HTTP(S) token endpoint used to create and refresh the credential. */
+    tokenEndpoint: string;
+}
+export declare function resolveMCPOAuthResourceOrigin(value: string): string | undefined;
+export declare function resolveMCPOAuthTokenEndpoint(value: string): string | undefined;
+export declare function isCanonicalMCPOAuthBinding(binding: MCPOAuthBinding): boolean;
+export declare function assertCanonicalMCPOAuthBinding(binding: MCPOAuthBinding | undefined): asserts binding is MCPOAuthBinding;
 export type OAuthCredential = {
     type: "oauth";
+    /** Present only for credentials created by runtime MCP OAuth. */
+    mcpBinding?: MCPOAuthBinding;
 } & OAuthCredentials;
 export type AuthCredential = ApiKeyCredential | OAuthCredential;
+export interface MCPOAuthRefreshClient {
+    clientId?: string;
+    clientSecret?: string;
+}
 export type AuthCredentialEntry = AuthCredential | AuthCredential[];
 export type AuthStorageData = Record<string, AuthCredentialEntry>;
 /**
@@ -161,6 +177,8 @@ export interface AuthCredentialStore {
      * for `timeoutMs * (maxRetries + 1)`.
      */
     refreshOAuthCredential?(provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal): Promise<OAuthCredentials>;
+    /** Broker-backed MCP refresh using the broker's stored token endpoint and refresh secret. */
+    refreshMCPOAuthCredential?(credentialId: number, credential: OAuthCredential, client: MCPOAuthRefreshClient, signal?: AbortSignal): Promise<OAuthCredential>;
     /**
      * Optional async pre-read hook invoked after AuthStorage selects a stored
      * credential but before it returns that credential for an outbound request.
@@ -597,7 +615,7 @@ export declare class AuthStorage {
      * refresh attempt, which is required for providers that rotate refresh tokens
      * on every successful refresh.
      */
-    refreshCredentialById(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry>;
+    refreshCredentialById(id: number, signal?: AbortSignal, mcpClient?: MCPOAuthRefreshClient): Promise<AuthCredentialSnapshotEntry>;
     /**
      * Force-refresh the OAuth credential with the given id, bypassing the
      * not-yet-expired guard. Used by the auth-broker server to honour
@@ -607,6 +625,8 @@ export declare class AuthStorage {
      * Throws when no OAuth credential with that id is loaded.
      */
     forceRefreshCredentialById(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry>;
+    /** Force-refresh the first OAuth credential stored for a provider. */
+    forceRefreshOAuthCredential(provider: string, expected: OAuthCredential, client?: MCPOAuthRefreshClient, signal?: AbortSignal): Promise<OAuthCredential>;
     /**
      * Disable the credential with the given id and emit a
      * {@link CredentialDisabledEvent}. Used by the auth-broker server to honour

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

@@ -42,6 +42,14 @@ type AnthropicCacheControl = {
 export declare function clearAnthropicFastModeFallback(providerSessionState: Map<string, ProviderSessionState> | undefined): void;
 export declare function isAnthropicFastModeUnsupportedError(error: unknown): boolean;
 export declare function isAnthropicThinkingBlockMutationError(error: unknown): boolean;
+/**
+ * 400 shape where a replayed `thinking`/`redacted_thinking` block fails signature
+ * validation, e.g. `messages.5.content.24: Invalid \`signature\` in \`thinking\` block`.
+ * Unlike the latest-assistant mutation error above, the cited block can sit anywhere
+ * in the replayed history, so recovery must repair every assistant message rather
+ * than only the latest one.
+ */
+export declare function isAnthropicThinkingSignatureInvalidError(error: unknown): boolean;
 export declare const claudeCodeVersion = "2.1.63";
 export declare const claudeToolPrefix: string;
 export declare const claudeCodeSystemInstruction = "You are a Claude agent, built on Anthropic's Claude Agent SDK.";
@@ -184,6 +192,7 @@ export declare function buildAnthropicClientOptions(args: AnthropicClientOptions
 export declare function normalizeCacheControlTtlOrdering(params: MessageCreateParamsStreaming): void;
 export declare function convertAnthropicMessages(messages: Message[], model: Model<"anthropic-messages">, isOAuthToken: boolean, options?: {
     repairLatestAssistantThinking?: boolean;
+    repairAllAssistantThinking?: boolean;
 }): MessageParam[];
 /**
  * Normalize a JSON Schema node for Anthropic tool `input_schema`.

package/dist/types/providers/transform-messages.d.ts

@@ -11,4 +11,5 @@ import type { Api, AssistantMessage, Message, Model } from "../types";
  */
 export declare function transformMessages<TApi extends Api>(messages: Message[], model: Model<TApi>, normalizeToolCallId?: (id: string, model: Model<TApi>, source: AssistantMessage) => string, options?: {
     repairLatestAssistantThinking?: boolean;
+    repairAllAssistantThinking?: boolean;
 }): Message[];

package/dist/types/types.d.ts

@@ -519,6 +519,7 @@ export type TSchema = ZodType | TJsonSchema;
 export type Static<S> = S extends ZodType ? z.infer<S> : S extends {
     static: infer T;
 } ? T : unknown;
+export type RawArgumentRejectionCode = "ask-intent-review-requires-positive-round" | "ask-intent-contract-requires-non-empty-authority" | "ask-deep-interview-metadata-requires-deep-interview-gate";
 export type RawArgumentValidationResult = {
     outcome: "passthrough";
 } | {
@@ -526,6 +527,7 @@ export type RawArgumentValidationResult = {
     arguments: ToolCall["arguments"];
 } | {
     outcome: "reject";
+    code?: RawArgumentRejectionCode;
 };
 export interface Tool<TParameters extends TSchema = TSchema> {
     name: string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/ai",
-	"version": "0.11.7",
+	"version": "0.11.8",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -40,7 +40,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@gajae-code/utils": "0.11.7",
+		"@gajae-code/utils": "0.11.8",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/auth-broker/client.ts

@@ -12,6 +12,7 @@ import type {
 	CredentialDisableRequest,
 	CredentialDisableResponse,
 	CredentialIfAbsentUploadResponse,
+	CredentialRefreshRequest,
 	CredentialRefreshResponse,
 	CredentialUploadRequest,
 	CredentialUploadResponse,
@@ -242,6 +243,18 @@ export class AuthBrokerClient {
 		}) as Promise<CredentialRefreshResponse>;
 	}
 
+	async refreshMCPCredential(
+		id: number,
+		body: CredentialRefreshRequest,
+		signal?: AbortSignal,
+	): Promise<CredentialRefreshResponse> {
+		return this.#request("POST", `/v1/credential/${id}/refresh`, {
+			body,
+			schema: credentialRefreshResponseSchema,
+			signal,
+		}) as Promise<CredentialRefreshResponse>;
+	}
+
 	async disableCredential(id: number, cause: string, signal?: AbortSignal): Promise<CredentialDisableResponse> {
 		const body: CredentialDisableRequest = { cause };
 		return this.#request("POST", `/v1/credential/${id}/disable`, {

package/src/auth-broker/refresher.ts

@@ -96,6 +96,7 @@ export class AuthBrokerRefresher {
 			const targets: number[] = [];
 			for (const entry of snapshot.credentials) {
 				if (entry.credential.type !== "oauth") continue;
+				if (entry.credential.mcpBinding) continue;
 				const expires = entry.credential.expires;
 				if (typeof expires !== "number" || !Number.isFinite(expires)) continue;
 				if (expires > deadline) continue;

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

@@ -14,6 +14,8 @@ import {
 	type AuthCredentialIfAbsentResult,
 	type AuthCredentialSnapshotEntry,
 	type AuthCredentialStore,
+	assertCanonicalMCPOAuthBinding,
+	type MCPOAuthRefreshClient,
 	type OAuthCredential,
 	REMOTE_REFRESH_SENTINEL,
 	type StoredAuthCredential,
@@ -512,6 +514,29 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		};
 	}
 
+	async refreshMCPOAuthCredential(
+		credentialId: number,
+		credential: OAuthCredential,
+		client: MCPOAuthRefreshClient,
+		signal?: AbortSignal,
+	): Promise<OAuthCredential> {
+		const { entry } = await this.#client.refreshMCPCredential(credentialId, client, signal);
+		if (entry.credential.type !== "oauth") {
+			throw new Error(`Broker returned non-OAuth credential for id=${credentialId}`);
+		}
+		assertCanonicalMCPOAuthBinding(credential.mcpBinding);
+		assertCanonicalMCPOAuthBinding(entry.credential.mcpBinding);
+		if (
+			entry.credential.mcpBinding.resourceOrigin !== credential.mcpBinding.resourceOrigin ||
+			entry.credential.mcpBinding.tokenEndpoint !== credential.mcpBinding.tokenEndpoint
+		) {
+			throw new Error("Broker returned mismatched MCP OAuth credential binding");
+		}
+		this.#applyCredentialEntry(entry);
+		this.#maybeRefreshSnapshot("MCP credential refresh");
+		return entry.credential;
+	}
+
 	/**
 	 * Store-level hook consumed by `AuthStorage.fetchUsageReports()` — proxies
 	 * to the broker's `/v1/usage` endpoint. The broker's egress IP isn't

package/src/auth-broker/server.ts

@@ -16,6 +16,7 @@ import { AuthBrokerRefresher, type AuthBrokerRefresherSchedule } from "./refresh
 import type {
 	CredentialDisableResponse,
 	CredentialIfAbsentUploadResponse,
+	CredentialRefreshRequest,
 	CredentialRefreshResponse,
 	CredentialUploadResponse,
 	HealthzResponse,
@@ -33,7 +34,11 @@ import {
 	DEFAULT_SERVER_IDLE_TIMEOUT_S,
 	DEFAULT_STREAM_KEEPALIVE_MS,
 } from "./types";
-import { credentialDisableRequestSchema, credentialUploadRequestSchema } from "./wire-schemas";
+import {
+	credentialDisableRequestSchema,
+	credentialRefreshRequestSchema,
+	credentialUploadRequestSchema,
+} from "./wire-schemas";
 
 export interface AuthBrokerServerOptions {
 	/** Underlying credential storage (wraps the local SQLite store on the broker). */
@@ -561,7 +566,10 @@ export function startAuthBroker(opts: AuthBrokerServerOptions): AuthBrokerServer
 				if (refreshMatch) {
 					const id = Number.parseInt(refreshMatch[1], 10);
 					try {
-						const entry = await opts.storage.refreshCredentialById(id, req.signal);
+						const parsed = await parseBody(req, credentialRefreshRequestSchema, { allowEmpty: true });
+						if (!parsed.ok) return parsed.response;
+						const refreshRequest: CredentialRefreshRequest = parsed.data;
+						const entry = await opts.storage.refreshCredentialById(id, req.signal, refreshRequest);
 						const body: CredentialRefreshResponse = { entry };
 						logger.info("auth-broker credential refreshed", {
 							id,

package/src/auth-broker/types.ts

@@ -11,6 +11,7 @@ import type {
 	AuthCredentialIfAbsentReason,
 	AuthCredentialSnapshot,
 	AuthCredentialSnapshotEntry,
+	MCPOAuthRefreshClient,
 } from "../auth-storage";
 import type { UsageReport } from "../usage";
 
@@ -49,6 +50,9 @@ export interface CredentialRefreshResponse {
 	entry: AuthCredentialSnapshotEntry;
 }
 
+/** Optional MCP client metadata; the broker still selects the stored token endpoint. */
+export type CredentialRefreshRequest = MCPOAuthRefreshClient;
+
 /** POST /v1/credential/:id/disable request body. */
 export interface CredentialDisableRequest {
 	cause: string;

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

@@ -11,11 +11,19 @@
  * `hasOnlyFields` allowlist for the same effect.
  */
 import * as z from "zod/v4";
-import { REMOTE_REFRESH_SENTINEL } from "../auth-storage";
+import { isCanonicalMCPOAuthBinding, REMOTE_REFRESH_SENTINEL } from "../auth-storage";
 import { usageReportSchema } from "../usage";
 
 // ─── Credential payloads ───────────────────────────────────────────────────
 
+export const mcpOAuthBindingSchema = z
+	.object({
+		resourceOrigin: z.string().min(1),
+		tokenEndpoint: z.string().min(1),
+	})
+	.strict()
+	.refine(isCanonicalMCPOAuthBinding, { message: "MCP OAuth binding must use canonical HTTP(S) URLs" });
+
 /** Real OAuth credential (broker-side) — refresh token is the actual upstream value. */
 export const oauthCredentialSchema = z
 	.object({
@@ -37,6 +45,7 @@ export const oauthCredentialSchema = z
 		projectId: z.string().optional(),
 		email: z.string().optional(),
 		accountId: z.string().optional(),
+		mcpBinding: mcpOAuthBindingSchema.optional(),
 	})
 	.strict();
 
@@ -164,6 +173,13 @@ export const usageResponseSchema = z
 
 // ─── Refresh ───────────────────────────────────────────────────────────────
 
+export const credentialRefreshRequestSchema = z
+	.object({
+		clientId: z.string().optional(),
+		clientSecret: z.string().optional(),
+	})
+	.strict();
+
 export const credentialRefreshResponseSchema = z
 	.object({
 		entry: credentialSnapshotEntrySchema,

package/src/auth-storage.ts

@@ -46,12 +46,113 @@ export type ApiKeyCredential = {
 	key: string;
 };
 
+export interface MCPOAuthBinding {
+	/** Exact HTTP(S) origin of the MCP resource endpoint. */
+	resourceOrigin: string;
+	/** Exact canonical HTTP(S) token endpoint used to create and refresh the credential. */
+	tokenEndpoint: string;
+}
+
+function resolveCanonicalHttpUrl(value: string): URL | undefined {
+	try {
+		const parsed = new URL(value);
+		if (
+			(parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+			parsed.username !== "" ||
+			parsed.password !== "" ||
+			parsed.hash !== ""
+		) {
+			return undefined;
+		}
+		return parsed;
+	} catch {
+		return undefined;
+	}
+}
+
+export function resolveMCPOAuthResourceOrigin(value: string): string | undefined {
+	return resolveCanonicalHttpUrl(value)?.origin;
+}
+
+export function resolveMCPOAuthTokenEndpoint(value: string): string | undefined {
+	return resolveCanonicalHttpUrl(value)?.href;
+}
+
+export function isCanonicalMCPOAuthBinding(binding: MCPOAuthBinding): boolean {
+	return (
+		resolveMCPOAuthResourceOrigin(binding.resourceOrigin) === binding.resourceOrigin &&
+		resolveMCPOAuthTokenEndpoint(binding.tokenEndpoint) === binding.tokenEndpoint
+	);
+}
+
+export function assertCanonicalMCPOAuthBinding(
+	binding: MCPOAuthBinding | undefined,
+): asserts binding is MCPOAuthBinding {
+	if (!binding || !isCanonicalMCPOAuthBinding(binding)) {
+		throw new Error("Invalid MCP OAuth credential binding");
+	}
+}
+
 export type OAuthCredential = {
 	type: "oauth";
+	/** Present only for credentials created by runtime MCP OAuth. */
+	mcpBinding?: MCPOAuthBinding;
 } & OAuthCredentials;
 
 export type AuthCredential = ApiKeyCredential | OAuthCredential;
 
+export interface MCPOAuthRefreshClient {
+	clientId?: string;
+	clientSecret?: string;
+}
+
+async function refreshBoundMCPOAuthCredential(
+	credential: OAuthCredential,
+	client: MCPOAuthRefreshClient = {},
+	signal?: AbortSignal,
+): Promise<OAuthCredentials> {
+	const binding = credential.mcpBinding;
+	assertCanonicalMCPOAuthBinding(binding);
+	const params = new URLSearchParams({
+		grant_type: "refresh_token",
+		refresh_token: credential.refresh,
+	});
+	if (client.clientId) params.set("client_id", client.clientId);
+	if (client.clientSecret) params.set("client_secret", client.clientSecret);
+
+	const response = await fetch(binding.tokenEndpoint, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: params.toString(),
+		redirect: "manual",
+		signal,
+	});
+	if (response.status >= 300 && response.status < 400) {
+		throw new Error(`MCP OAuth refresh rejected redirect response (${response.status})`);
+	}
+	if (!response.ok) throw new Error(`MCP OAuth refresh failed (${response.status})`);
+	const payload: unknown = await response.json();
+	if (!payload || typeof payload !== "object") throw new Error("MCP OAuth refresh returned an invalid payload");
+	const data = payload as { access_token?: unknown; refresh_token?: unknown; expires_in?: unknown };
+	if (typeof data.access_token !== "string" || data.access_token.length === 0) {
+		throw new Error("MCP OAuth refresh returned an invalid access token");
+	}
+	if (data.refresh_token !== undefined && typeof data.refresh_token !== "string") {
+		throw new Error("MCP OAuth refresh returned an invalid refresh token");
+	}
+	if (
+		data.expires_in !== undefined &&
+		(typeof data.expires_in !== "number" || !Number.isFinite(data.expires_in) || data.expires_in < 0)
+	) {
+		throw new Error("MCP OAuth refresh returned an invalid expiry");
+	}
+	return {
+		access: data.access_token,
+		refresh: data.refresh_token || credential.refresh,
+		expires: Date.now() + (data.expires_in ?? 3600) * 1000,
+	};
+}
+
 export type AuthCredentialEntry = AuthCredential | AuthCredential[];
 
 export type AuthStorageData = Record<string, AuthCredentialEntry>;
@@ -230,6 +331,13 @@ export interface AuthCredentialStore {
 		credential: OAuthCredential,
 		signal?: AbortSignal,
 	): Promise<OAuthCredentials>;
+	/** Broker-backed MCP refresh using the broker's stored token endpoint and refresh secret. */
+	refreshMCPOAuthCredential?(
+		credentialId: number,
+		credential: OAuthCredential,
+		client: MCPOAuthRefreshClient,
+		signal?: AbortSignal,
+	): Promise<OAuthCredential>;
 	/**
 	 * Optional async pre-read hook invoked after AuthStorage selects a stored
 	 * credential but before it returns that credential for an outbound request.
@@ -632,7 +740,9 @@ function authCredentialEquals(left: AuthCredential, right: AuthCredential): bool
 		left.accountId === right.accountId &&
 		left.email === right.email &&
 		left.projectId === right.projectId &&
-		left.enterpriseUrl === right.enterpriseUrl
+		left.enterpriseUrl === right.enterpriseUrl &&
+		left.mcpBinding?.resourceOrigin === right.mcpBinding?.resourceOrigin &&
+		left.mcpBinding?.tokenEndpoint === right.mcpBinding?.tokenEndpoint
 	);
 }
 
@@ -3009,6 +3119,8 @@ export class AuthStorage {
 		const overrideRefresh = this.#refreshOAuthCredentialOverride ?? storeRefresh;
 		if (overrideRefresh && credentialId !== undefined) {
 			refreshPromise = overrideRefresh(provider, credentialId, credential, signal);
+		} else if (credential.mcpBinding) {
+			refreshPromise = refreshBoundMCPOAuthCredential(credential, {}, signal);
 		} else {
 			const customProvider = getOAuthProvider(provider);
 			if (customProvider) {
@@ -3202,10 +3314,38 @@ export class AuthStorage {
 			return { apiKey: result.apiKey, credential: updated };
 		} catch (error) {
 			const errorMsg = String(error);
+			// Peer-rotation recovery runs before ANY failure classification: a
+			// concurrent process may have rotated the refresh token, which
+			// invalidates the snapshot token we just attempted. Re-read the row —
+			// if the persisted refresh token changed, the peer's rotation succeeded
+			// and we pick up the fresh credential instead of disabling (definitive
+			// path) or temp-blocking (transient path) a row that is actually
+			// healthy. This matters for providers whose invalid-grant response does
+			// not match the definitive regex below (e.g. Kimi's 400 "The provided
+			// authorization grant is invalid"): with short-lived access tokens and
+			// multiple gjc processes sharing the store, the stale-snapshot failure
+			// would otherwise be misclassified as transient and the credential
+			// temp-blocked on every rotation race.
+			const attemptedCredentialId = this.#getStoredCredentials(provider)[selection.index]?.id;
+			if (attemptedCredentialId !== undefined) {
+				const latestRow = this.#store.listAuthCredentials(provider).find(row => row.id === attemptedCredentialId);
+				const latestCredential = latestRow?.credential;
+				if (latestCredential?.type === "oauth" && latestCredential.refresh !== selection.credential.refresh) {
+					logger.debug("OAuth refresh race detected; another process rotated token first", {
+						provider,
+						index: selection.index,
+						credentialId: attemptedCredentialId,
+					});
+					await this.reload();
+					return this.#resolveOAuthSelection(provider, sessionId, options);
+				}
+			}
 			// Only remove credentials for definitive auth failures
 			// Keep credentials for transient errors (network, 5xx) and block temporarily
 			const isDefinitiveFailure =
-				/invalid_grant|invalid_token|revoked|unauthorized|expired.*refresh|refresh.*expired/i.test(errorMsg) ||
+				/invalid_grant|grant is invalid|invalid_token|revoked|unauthorized|expired.*refresh|refresh.*expired/i.test(
+					errorMsg,
+				) ||
 				(/\b(401|403)\b/.test(errorMsg) && !/timeout|network|fetch failed|ECONNREFUSED/i.test(errorMsg));
 
 			logger.warn("OAuth token refresh failed", {
@@ -3216,27 +3356,6 @@ export class AuthStorage {
 			});
 
 			if (isDefinitiveFailure) {
-				// The credential at this index may have been rotated by another process between
-				// our in-memory snapshot and the refresh attempt: Anthropic rotates refresh
-				// tokens on every use, so the peer's success leaves our stored token invalid.
-				// Re-read the row from disk before marking it disabled — if the persisted
-				// refresh token has changed, the peer rotation succeeded and we should pick
-				// up the new credential instead of soft-deleting the row that the peer just
-				// updated.
-				const credentialId = this.#getStoredCredentials(provider)[selection.index]?.id;
-				if (credentialId !== undefined) {
-					const latestRow = this.#store.listAuthCredentials(provider).find(row => row.id === credentialId);
-					const latestCredential = latestRow?.credential;
-					if (latestCredential?.type === "oauth" && latestCredential.refresh !== selection.credential.refresh) {
-						logger.debug("OAuth refresh race detected; another process rotated token first", {
-							provider,
-							index: selection.index,
-							credentialId,
-						});
-						await this.reload();
-						return this.#resolveOAuthSelection(provider, sessionId, options);
-					}
-				}
 				// Permanently disable invalid credentials with an explicit cause for inspection/debugging.
 				// Use a CAS-style disable conditioned on the row still containing the stale credential
 				// we tried to refresh, so a peer rotation that lands between the pre-check above and
@@ -3518,14 +3637,18 @@ export class AuthStorage {
 	 * refresh attempt, which is required for providers that rotate refresh tokens
 	 * on every successful refresh.
 	 */
-	async refreshCredentialById(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry> {
+	async refreshCredentialById(
+		id: number,
+		signal?: AbortSignal,
+		mcpClient: MCPOAuthRefreshClient = {},
+	): Promise<AuthCredentialSnapshotEntry> {
 		const existing = this.#oauthRefreshInFlight.get(id);
 		if (existing) return raceCredentialRefreshWithSignal(existing, signal);
 
 		const promise = (async () => {
 			this.#bumpGeneration("credential-refresh-start");
 			try {
-				return await this.#forceRefreshCredentialByIdUnshared(id, signal);
+				return await this.#forceRefreshCredentialByIdUnshared(id, signal, mcpClient);
 			} catch (error) {
 				this.#bumpGeneration("credential-refresh-failure");
 				throw error;
@@ -3549,7 +3672,32 @@ export class AuthStorage {
 		return this.refreshCredentialById(id, signal);
 	}
 
-	async #forceRefreshCredentialByIdUnshared(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry> {
+	/** Force-refresh the first OAuth credential stored for a provider. */
+	async forceRefreshOAuthCredential(
+		provider: string,
+		expected: OAuthCredential,
+		client: MCPOAuthRefreshClient = {},
+		signal?: AbortSignal,
+	): Promise<OAuthCredential> {
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		const target = this.#getStoredCredentials(storageProvider).find(
+			entry => entry.credential === expected || authCredentialEquals(entry.credential, expected),
+		);
+		if (target?.credential.type !== "oauth") {
+			throw new Error(`No OAuth credential found for provider=${storageProvider}`);
+		}
+		const entry = await this.refreshCredentialById(target.id, signal, client);
+		if (entry.credential.type !== "oauth") {
+			throw new Error(`Credential ${target.id} is not OAuth`);
+		}
+		return entry.credential;
+	}
+
+	async #forceRefreshCredentialByIdUnshared(
+		id: number,
+		signal?: AbortSignal,
+		mcpClient: MCPOAuthRefreshClient = {},
+	): Promise<AuthCredentialSnapshotEntry> {
 		for (const [provider, entries] of this.#data) {
 			const index = entries.findIndex(entry => entry.id === id);
 			if (index === -1) continue;
@@ -3560,7 +3708,27 @@ export class AuthStorage {
 			// Pass a clone with expires=0 so the cached not-yet-expired short-circuit
 			// in #refreshOAuthCredential doesn't suppress the requested refresh.
 			const stale: OAuthCredential = { ...target.credential, expires: 0 };
-			const refreshed = await this.#refreshOAuthCredential(provider as Provider, stale, id, signal);
+			let refreshed: OAuthCredentials;
+			if (target.credential.mcpBinding) {
+				assertCanonicalMCPOAuthBinding(target.credential.mcpBinding);
+				const remoteRefresh = this.#store.refreshMCPOAuthCredential?.bind(this.#store);
+				const refreshedCredential = remoteRefresh
+					? await remoteRefresh(id, stale, mcpClient, signal)
+					: {
+							type: "oauth" as const,
+							...(await refreshBoundMCPOAuthCredential(stale, mcpClient, signal)),
+							mcpBinding: target.credential.mcpBinding,
+						};
+				if (
+					refreshedCredential.mcpBinding?.resourceOrigin !== target.credential.mcpBinding.resourceOrigin ||
+					refreshedCredential.mcpBinding.tokenEndpoint !== target.credential.mcpBinding.tokenEndpoint
+				) {
+					throw new Error("Refreshed MCP OAuth credential binding mismatch");
+				}
+				refreshed = refreshedCredential;
+			} else {
+				refreshed = await this.#refreshOAuthCredential(provider as Provider, stale, id, signal);
+			}
 			const updated: OAuthCredential = {
 				type: "oauth",
 				access: refreshed.access,
@@ -3570,6 +3738,7 @@ export class AuthStorage {
 				email: refreshed.email ?? target.credential.email,
 				projectId: refreshed.projectId ?? target.credential.projectId,
 				enterpriseUrl: refreshed.enterpriseUrl ?? target.credential.enterpriseUrl,
+				mcpBinding: target.credential.mcpBinding,
 			};
 			this.#replaceCredentialAt(provider, index, updated);
 			return {

package/src/providers/anthropic.ts

@@ -411,6 +411,23 @@ export function isAnthropicThinkingBlockMutationError(error: unknown): boolean {
 	);
 }
 
+/**
+ * 400 shape where a replayed `thinking`/`redacted_thinking` block fails signature
+ * validation, e.g. `messages.5.content.24: Invalid \`signature\` in \`thinking\` block`.
+ * Unlike the latest-assistant mutation error above, the cited block can sit anywhere
+ * in the replayed history, so recovery must repair every assistant message rather
+ * than only the latest one.
+ */
+export function isAnthropicThinkingSignatureInvalidError(error: unknown): boolean {
+	if (extractHttpStatusFromError(error) !== 400) return false;
+	const message = error instanceof Error ? error.message : String(error);
+	return (
+		/invalid_request_error/i.test(message) &&
+		/thinking|redacted_thinking/i.test(message) &&
+		/invalid\s+`?signature`?/i.test(message)
+	);
+}
+
 function hasStrictAnthropicTools(params: MessageCreateParamsStreaming): boolean {
 	const tools = params.tools as Array<{ strict?: unknown }> | undefined;
 	return tools?.some(tool => tool.strict === true) ?? false;
@@ -1316,20 +1333,19 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 			let strictFallbackErrorMessage: string | undefined;
 			let dropFastMode = providerSessionState?.fastModeDisabled ?? false;
 			let droppedForcedToolChoice = false;
-			const prepareParams = async (paramsOptions?: {
-				repairLatestAssistantThinking?: boolean;
-				dropForcedToolChoice?: boolean;
-			}): Promise<MessageCreateParamsStreaming> => {
-				let nextParams = buildParams(
-					model,
-					baseUrl,
-					context,
-					isOAuthToken,
-					options,
-					disableStrictTools,
-					paramsOptions?.repairLatestAssistantThinking === true,
-				);
-				if (paramsOptions?.dropForcedToolChoice === true) {
+			let repairLatestAssistantThinking = false;
+			let repairAllAssistantThinking = false;
+			const prepareParams = async (): Promise<MessageCreateParamsStreaming> => {
+				// Degradation state is cumulative: every fallback rebuild must merge all
+				// repairs activated so far. Rebuilding from only the immediate call lets
+				// a later strict/forced-tool/fast-mode fallback reintroduce the rejected
+				// shape (e.g. invalid thinking signatures or forced tool_choice), and
+				// the one-shot thinking-repair guard then blocks recovery.
+				let nextParams = buildParams(model, baseUrl, context, isOAuthToken, options, disableStrictTools, {
+					repairLatestAssistantThinking,
+					repairAllAssistantThinking,
+				});
+				if (droppedForcedToolChoice) {
 					delete nextParams.tool_choice;
 				}
 				if (disableStrictTools) {
@@ -1763,23 +1779,30 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 							registryKey: resolveToolChoice(model, options?.toolChoice).registryKey,
 						});
 						droppedForcedToolChoice = true;
-						params = await prepareParams({ dropForcedToolChoice: true });
+						params = await prepareParams();
 						providerRetryAttempt = 0;
 						resetOutputForRetry();
 						continue;
 					}
+					const thinkingSignatureInvalid = isAnthropicThinkingSignatureInvalidError(streamFailure);
 					if (
 						!options?.fallbackManaged &&
 						!thinkingRepairAttempted &&
 						firstTokenTime === undefined &&
-						isAnthropicThinkingBlockMutationError(streamFailure)
+						(thinkingSignatureInvalid || isAnthropicThinkingBlockMutationError(streamFailure))
 					) {
-						logger.debug("anthropic: repairing latest assistant thinking replay after provider rejection", {
+						logger.debug("anthropic: repairing assistant thinking replay after provider rejection", {
 							model: model.id,
+							scope: thinkingSignatureInvalid ? "all" : "latest",
 							error: streamFailure instanceof Error ? streamFailure.message : String(streamFailure),
 						});
 						thinkingRepairAttempted = true;
-						params = await prepareParams({ repairLatestAssistantThinking: true });
+						if (thinkingSignatureInvalid) {
+							repairAllAssistantThinking = true;
+						} else {
+							repairLatestAssistantThinking = true;
+						}
+						params = await prepareParams();
 						providerRetryAttempt = 0;
 						resetOutputForRetry();
 						continue;
@@ -2243,13 +2266,13 @@ function buildParams(
 	isOAuthToken: boolean,
 	options?: AnthropicOptions,
 	disableStrictTools = false,
-	repairLatestAssistantThinking = false,
+	thinkingRepair?: { repairLatestAssistantThinking?: boolean; repairAllAssistantThinking?: boolean },
 ): MessageCreateParamsStreaming {
 	const { mode: cacheMode, cacheControl } = getCacheControl(model, baseUrl, options?.cacheRetention);
 
 	const params: AnthropicSamplingParams = {
 		model: model.id,
-		messages: convertAnthropicMessages(context.messages, model, isOAuthToken, { repairLatestAssistantThinking }),
+		messages: convertAnthropicMessages(context.messages, model, isOAuthToken, thinkingRepair),
 		max_tokens: options?.maxTokens || (model.maxTokens / 3) | 0,
 		stream: true,
 	};
@@ -2440,7 +2463,7 @@ export function convertAnthropicMessages(
 	messages: Message[],
 	model: Model<"anthropic-messages">,
 	isOAuthToken: boolean,
-	options?: { repairLatestAssistantThinking?: boolean },
+	options?: { repairLatestAssistantThinking?: boolean; repairAllAssistantThinking?: boolean },
 ): MessageParam[] {
 	const params: MessageParam[] = [];
 

package/src/providers/openai-completions.ts

@@ -426,6 +426,7 @@ function getTrailingPartialDeepseekToken(text: string): string {
 	return tail;
 }
 
+const ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MS = 300_000;
 const OPENAI_COMPLETIONS_FIRST_EVENT_TIMEOUT_MESSAGE =
 	"OpenAI completions stream timed out while waiting for the first event";
 
@@ -562,8 +563,10 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 					openaiStream = await createCompletionsStream("none");
 				}
 			}
+			const firstEventFallbackMs =
+				model.provider === "alibaba-token-plan" ? ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MS : undefined;
 			const firstEventWatchdog = createWatchdog(
-				options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs),
+				options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs, firstEventFallbackMs),
 				() => abortTracker.abortLocally(firstEventTimeoutAbortError),
 			);
 			if (premiumRequestsTotal !== undefined) {

package/src/providers/openai-responses.ts

@@ -130,6 +130,7 @@ export interface OpenAIResponsesOptions extends StreamOptions {
 }
 
 const OPENAI_RESPONSES_PROVIDER_SESSION_STATE_PREFIX = "openai-responses:";
+const ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MS = 300_000;
 const OPENAI_RESPONSES_FIRST_EVENT_TIMEOUT_MESSAGE =
 	"OpenAI responses stream timed out while waiting for the first event";
 const OPENAI_DEFAULT_BASE_URL = "https://api.openai.com/v1";
@@ -330,8 +331,10 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 				await notifyProviderResponse(options, response, model, request_id);
 				return data;
 			});
+			const firstEventFallbackMs =
+				model.provider === "alibaba-token-plan" ? ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MS : undefined;
 			const firstEventWatchdog = createWatchdog(
-				options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs),
+				options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs, firstEventFallbackMs),
 				() => abortTracker.abortLocally(firstEventTimeoutAbortError),
 			);
 			if (premiumRequestsTotal !== undefined) output.usage.premiumRequests = premiumRequestsTotal;

package/src/providers/transform-messages.ts

@@ -31,7 +31,7 @@ export function transformMessages<TApi extends Api>(
 	messages: Message[],
 	model: Model<TApi>,
 	normalizeToolCallId?: (id: string, model: Model<TApi>, source: AssistantMessage) => string,
-	options?: { repairLatestAssistantThinking?: boolean },
+	options?: { repairLatestAssistantThinking?: boolean; repairAllAssistantThinking?: boolean },
 ): Message[] {
 	// Build a map of original tool call IDs to normalized IDs
 	const toolCallIdMap = new Map<string, string>();
@@ -73,16 +73,29 @@ export function transformMessages<TApi extends Api>(
 			// are kept so the second pass can either preserve real results or synthesize
 			// an explicit aborted result without leaving dangling tool_use blocks.
 			const hasPartialThinking = assistantMsg.stopReason === "aborted" || assistantMsg.stopReason === "error";
-			const dropLatestAssistantThinking =
-				options?.repairLatestAssistantThinking === true &&
-				index === latestAssistantIndex &&
+			// One-shot Anthropic replay repair. `repairLatestAssistantThinking` targets the
+			// "latest assistant message ... cannot be modified" 400; `repairAllAssistantThinking`
+			// targets the "Invalid `signature` in `thinking` block" 400, which can cite a block
+			// anywhere in the replayed history (e.g. after compaction/pruning rewrote an earlier
+			// turn), so the drop must apply to every assistant message. Within each
+			// message only blocks that would replay as native thinking/redacted_thinking
+			// are dropped; cross-model reasoning degrades to text and is preserved.
+			const dropAssistantThinkingForRepair =
+				(options?.repairAllAssistantThinking === true ||
+					(options?.repairLatestAssistantThinking === true && index === latestAssistantIndex)) &&
 				model.api === "anthropic-messages" &&
 				assistantMsg.api === "anthropic-messages";
 
 			const transformedContent = assistantMsg.content.flatMap(block => {
 				if (block.type === "thinking") {
-					if (hasPartialThinking || dropLatestAssistantThinking) return [];
+					if (hasPartialThinking) return [];
 					const sanitized = block;
+					// Repair must only drop blocks that would otherwise replay as native
+					// thinking. Cross-model/provider reasoning degrades to unsigned text
+					// below and was never replayed as a signed block, so it cannot be the
+					// signature failure — dropping it would silently lose valid context.
+					const replaysAsNativeThinking = mustPreserveLatestAnthropicThinking || isSameModel;
+					if (dropAssistantThinkingForRepair && replaysAsNativeThinking) return [];
 					if (mustPreserveLatestAnthropicThinking) return sanitized;
 					// For same model: keep thinking blocks with signatures (needed for replay)
 					// even if the thinking text is empty (OpenAI encrypted reasoning)
@@ -97,7 +110,13 @@ export function transformMessages<TApi extends Api>(
 				}
 
 				if (block.type === "redactedThinking") {
-					if (hasPartialThinking || dropLatestAssistantThinking) return [];
+					if (hasPartialThinking) return [];
+					// Same restriction as thinking blocks: cross-model/provider redacted
+					// blocks already drop below, so repair only needs to cover blocks that
+					// would replay as native redacted_thinking.
+					if (dropAssistantThinkingForRepair && (mustPreserveLatestAnthropicThinking || isSameModel)) {
+						return [];
+					}
 					if (mustPreserveLatestAnthropicThinking) return block;
 					if (isSameModel) return block;
 					return [];

package/src/types.ts

@@ -709,10 +709,15 @@ export type TSchema = ZodType | TJsonSchema;
 /** Resolve parameter types for tool execution / handlers. */
 export type Static<S> = S extends ZodType ? z.infer<S> : S extends { static: infer T } ? T : unknown;
 
+export type RawArgumentRejectionCode =
+	| "ask-intent-review-requires-positive-round"
+	| "ask-intent-contract-requires-non-empty-authority"
+	| "ask-deep-interview-metadata-requires-deep-interview-gate";
+
 export type RawArgumentValidationResult =
 	| { outcome: "passthrough" }
 	| { outcome: "accept"; arguments: ToolCall["arguments"] }
-	| { outcome: "reject" };
+	| { outcome: "reject"; code?: RawArgumentRejectionCode };
 
 export interface Tool<TParameters extends TSchema = TSchema> {
 	name: string;

package/src/utils/validation.ts

@@ -25,7 +25,7 @@
 import { structuredCloneJSON } from "@gajae-code/utils";
 import type { ZodType } from "zod/v4";
 import type { $ZodIssue as ZodIssue } from "zod/v4/core";
-import type { Tool, ToolCall } from "../types";
+import type { RawArgumentRejectionCode, Tool, ToolCall } from "../types";
 import { upgradeJsonSchemaTo202012 } from "./schema/draft";
 import {
 	isJsonSchemaValueValid,
@@ -958,6 +958,15 @@ export function validateToolCall(tools: Tool[], toolCall: ToolCall): ToolCall["a
 	return validateToolArguments(tool, toolCall);
 }
 
+const RAW_ARGUMENT_REJECTION_MESSAGES: Record<RawArgumentRejectionCode, string> = {
+	"ask-intent-review-requires-positive-round":
+		"deepInterview.intent_review is post-Round-0 only and requires a positive round",
+	"ask-intent-contract-requires-non-empty-authority":
+		"deepInterview.intent_contract requires non-empty items and confirmation_options",
+	"ask-deep-interview-metadata-requires-deep-interview-gate":
+		"deepInterview metadata cannot be combined with a non-deep-interview workflowGate",
+};
+
 /**
  * Validates tool call arguments against the tool's schema (Zod or plain JSON
  * Schema). Applies LLM-quirk coercions (numeric strings, JSON-string
@@ -969,7 +978,13 @@ export function validateToolArguments(tool: Tool, toolCall: ToolCall): ToolCall[
 	const originalArgs = toolCall.arguments;
 	const rawValidation = tool.rawArgumentValidation?.(originalArgs);
 	if (rawValidation?.outcome === "reject") {
-		throw new Error(`Validation failed for tool "${toolCall.name}": raw arguments rejected before coercion`);
+		const base = `Validation failed for tool "${toolCall.name}": raw arguments rejected before coercion`;
+		const code = rawValidation.code;
+		const correction =
+			typeof code === "string" && Object.hasOwn(RAW_ARGUMENT_REJECTION_MESSAGES, code)
+				? RAW_ARGUMENT_REJECTION_MESSAGES[code as RawArgumentRejectionCode]
+				: undefined;
+		throw new Error(correction ? `${base}; ${correction}` : base);
 	}
 	const rawArgs = rawValidation?.outcome === "accept" ? rawValidation.arguments : originalArgs;
 	const ctx = getValidationContext(tool);

package/src/utils.ts

@@ -271,17 +271,53 @@ function normalizeResponsesImageUrlForReplay(value: unknown): NormalizedResponse
 	return { imageUrl: stringifyResponsesStringParamForReplay(value) };
 }
 
+/**
+ * OpenAI Responses `input_image.image_url` must be a fetchable HTTP(S) URL or an
+ * image data URI. Session resident-blob materialization may leave a human-readable
+ * placeholder like `[Session resident imageUrl blob missing: sha256:…; …]` in this
+ * field; replaying that string as `image_url` makes Codex reject the entire turn
+ * with `invalid_value` (#2924).
+ */
+function isProviderSafeResponsesImageUrl(value: string): boolean {
+	const url = value.trim();
+	if (url.length === 0) return false;
+	if (url.startsWith("https://") || url.startsWith("http://")) return true;
+	// Accept only image data URIs — other data: schemes are not valid image inputs.
+	if (url.startsWith("data:image/")) return true;
+	return false;
+}
+
+function hasNonEmptyResponsesFileId(part: Record<string, unknown>): boolean {
+	return typeof part.file_id === "string" && part.file_id.trim().length > 0;
+}
+
 function sanitizeResponsesMessageContentForReplay(content: unknown): unknown {
 	if (typeof content === "string") return neutralizeReservedControlTokens(content.toWellFormed());
 	if (!Array.isArray(content)) return content;
-	return content.map(part => {
-		if (!part || typeof part !== "object") return part;
+	const sanitizedContent: unknown[] = [];
+	for (const part of content) {
+		if (!part || typeof part !== "object") {
+			sanitizedContent.push(part);
+			continue;
+		}
 		const sanitizedPart = { ...(part as Record<string, unknown>) };
 		if ("text" in sanitizedPart) {
 			sanitizedPart.text = normalizeResponsesMessageTextForReplay(sanitizedPart.text);
 		}
 		if ("image_url" in sanitizedPart) {
 			const normalizedImageUrl = normalizeResponsesImageUrlForReplay(sanitizedPart.image_url);
+			if (!isProviderSafeResponsesImageUrl(normalizedImageUrl.imageUrl)) {
+				// Keep the part when a provider file_id can stand alone; otherwise drop
+				// only this image part so neighboring text/history still replays.
+				if (!hasNonEmptyResponsesFileId(sanitizedPart)) continue;
+				delete sanitizedPart.image_url;
+				if (sanitizedPart.type === "image_url") sanitizedPart.type = "input_image";
+				if ("detail" in sanitizedPart && !isResponsesImageDetail(sanitizedPart.detail)) {
+					delete sanitizedPart.detail;
+				}
+				sanitizedContent.push(sanitizedPart);
+				continue;
+			}
 			sanitizedPart.image_url = normalizedImageUrl.imageUrl;
 			if (sanitizedPart.type === "image_url") {
 				sanitizedPart.type = "input_image";
@@ -292,8 +328,9 @@ function sanitizeResponsesMessageContentForReplay(content: unknown): unknown {
 				delete sanitizedPart.detail;
 			}
 		}
-		return sanitizedPart;
-	});
+		sanitizedContent.push(sanitizedPart);
+	}
+	return sanitizedContent;
 }
 
 function sanitizeResponsesStringFieldsForReplay(item: Record<string, unknown>): void {