@gajae-code/ai 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-07-15
+### Added
+
+- Exported the canonical thinking-control mode runtime vocabulary so packed SDK consumers can validate provider metadata against the same public `@gajae-code/ai` contract.
+
+### Fixed
+
+- Fixed frequent `Request blocked (code=invalid_prompt)` failures on gpt-5.6 (Sol/Terra/Luna) subagent, default-agent, and compaction turns (ref openai/codex#32028, oh-my-pi#5184). Leaked Harmony control-token markers (e.g. `<|channel|>analysis`) were only neutralized on the replayed-history payload path, so markers in assistant reasoning summaries, live-converted message/tool-output text, and user-authored content reached the OpenAI Responses and OpenAI-codex-responses transports verbatim and wedged the session (the poisoned item was re-sent every turn). Both transports now neutralize reserved control tokens across the entire outgoing `input` array at the request boundary via an idempotent zero-width-space insertion that keeps the text human-readable.
+
+- Closed the remaining `Request blocked (code=invalid_prompt)` wedge on gpt-5.6 caused by header-form leaked Harmony markers. The reserved-control-token sanitizer only matched the simple `<|ident|>` shape, so a header-form marker carrying a recipient (e.g. `<|assistant to=functions.bash|>`) survived every sanitizer path (replay, request boundary, compaction) and kept re-poisoning history even after the earlier fixes. The pattern now also matches the scoped header grammar — a known Harmony role (`system`/`developer`/`user`/`assistant`/`tool`) plus a `to=<recipient>` assignment with unbounded recipient length — while leaving ordinary delimiter/pipe text untouched (arbitrary `<|foo bar=baz|>`, F# `value <| f |> g`, compact `sum<|a+b|>c`, and multi-line bodies never match). The simple branch remains a strict superset of the prior identifier-only pattern (#2267).
+
+## [0.10.2] - 2026-07-14
+
+### Fixed
+
+- Fixed frequent `Request blocked (code=invalid_prompt)` failures on gpt-5.6 (Sol/Terra/Luna) subagent, default-agent, and compaction turns (ref openai/codex#32028, oh-my-pi#5184). Leaked Harmony control-token markers (e.g. `<|channel|>analysis`) were only neutralized on the replayed-history payload path, so markers in assistant reasoning summaries, live-converted message/tool-output text, and user-authored content reached the OpenAI Responses and OpenAI-codex-responses transports verbatim and wedged the session (the poisoned item was re-sent every turn). Both transports now neutralize reserved control tokens across the entire outgoing `input` array at the request boundary via an idempotent zero-width-space insertion that keeps the text human-readable.
+
 ## [0.10.0] - 2026-07-12
 ### Fixed
 
@@ -417,7 +434,7 @@
 
 - Added `onAuthError` to `StreamOptions` and wired `streamSimple()` to retry once with a replacement API key when the first provider response is a 401 before any assistant events are emitted
 - Added generation-aware snapshot metadata (`generation`, `serverNowMs`, `refresher`, and `rotatesInMs`) to auth-broker snapshot responses to support client-side credential-rotation planning
-- Added `transport: "pi-native"` on `Model` and the matching `streamPiNative` client. When `model.transport === "pi-native"`, `streamSimple` short-circuits the per-provider dispatch and POSTs the canonical `Context` to the auth-gateway's `POST /v1/pi/stream` endpoint. The response is SSE-framed `AssistantMessageEvent`s parsed by `readSseJson` and pushed verbatim into the local `AssistantMessageEventStream` — no wire-format translation, no partial-stripping reconstruction. Used by containerized gjc installs (robogjc slots, swarm extension, etc.) to route every LLM call through a credential-holding sidecar; the slot itself never sees the real provider tokens. Server-controlled fields (`apiKey`, `signal`, `fetch`, lifecycle callbacks, the provider-session map) are stripped from the wire body — `apiKey` rides in the `Authorization` header as the gateway bearer.
+- Added `transport: "pi-native"` on `Model` and the matching `streamPiNative` client. When `model.transport === "pi-native"`, `streamSimple` short-circuits the per-provider dispatch and POSTs the canonical `Context` to the auth-gateway's `POST /v1/pi/stream` endpoint. The response is SSE-framed `AssistantMessageEvent`s parsed by `readSseJson` and pushed verbatim into the local `AssistantMessageEventStream` — no wire-format translation, no partial-stripping reconstruction. Used by containerized GJC deployments and swarm extensions to route every LLM call through a credential-holding sidecar; the container never sees the real provider tokens. Server-controlled fields (`apiKey`, `signal`, `fetch`, lifecycle callbacks, the provider-session map) are stripped from the wire body — `apiKey` rides in the `Authorization` header as the gateway bearer.
 - Added `POST /v1/pi/stream` to the auth-gateway. Same auth + abort + model-resolution + openai-code-compat + prefix-cache plumbing as the foreign-wire routes; only the wire-format translation is skipped. Request body is `{ modelId, context, options?, stream? }` where `context` is the canonical pi-ai `Context` and `options` is `SimpleStreamOptions` with non-serializable fields stripped. Response is SSE-framed `AssistantMessageEvent` (terminated by `data: [DONE]`) when streaming, or `{ message: AssistantMessage }` JSON when `stream: false`.
 - Added Vertex AI authentication via Google Application Default Credentials from `GOOGLE_APPLICATION_CREDENTIALS`, `~/.config/gcloud/application_default_credentials.json`, or metadata server tokens, with token caching and refresh skew control via `GOOGLE_VERTEX_REFRESH_SKEW_MS`
 - Added support for Anthropic image message parts with `type: "url"` and `type: "file"` sources
@@ -436,7 +453,7 @@
 - Added `AuthStorageOptions.refreshOAuthCredential` override so a remote-store client can route every OAuth refresh through the broker instead of the local OAuth endpoint.
 - Added `REMOTE_REFRESH_SENTINEL` (`"__remote__"`) — the wire placeholder substituted for OAuth refresh tokens in broker snapshots; clients never see the real refresh token.
 - Exposed the OAuth provider catalog (`getOAuthProviders`, `OAuthProvider`, `OAuthProviderInfo`) and `refreshOAuthToken` through the package barrel so the coding-agent CLI can target them without reaching into `utils/oauth`.
-- Added the auth-gateway subsystem (`@gajae-code/ai/auth-gateway`) — a forward-proxy that sits between unauthenticated clients (the macOS usage widget, llm-git, robogjc containers, …) and the broker. Clients send standard provider-format requests; the gateway parses them into gjc's canonical `Context`, dispatches through pi-ai's `streamSimple()`, and translates the canonical event stream back to the matching wire format. `Authorization` is injected server-side so access tokens never leave the gateway host. Wire surface:
+- Added the auth-gateway subsystem (`@gajae-code/ai/auth-gateway`) — a forward-proxy that sits between unauthenticated clients (the macOS usage widget, llm-git, containerized GJC deployments, …) and the broker. Clients send standard provider-format requests; the gateway parses them into gjc's canonical `Context`, dispatches through pi-ai's `streamSimple()`, and translates the canonical event stream back to the matching wire format. `Authorization` is injected server-side so access tokens never leave the gateway host. Wire surface:
 - `GET  /healthz` — unauth liveness.
 - `GET  /v1/usage` — aggregated provider usage; 5-min per-credential cache via `AuthStorage.fetchUsageReports`.
 - `GET  /v1/models` — model catalog (scoped to providers with credentials).

package/dist/types/auth-gateway/server.d.ts

@@ -1,3 +1,22 @@
+/**
+ * gjc auth-gateway HTTP server.
+ *
+ * Accepts any provider-format request (OpenAI chat-completions, Anthropic
+ * messages, OpenAI Responses) and dispatches through pi-ai's `streamSimple()`
+ * — which handles credential injection, anthropic-beta headers, OpenAI code backend
+ * websocket transport, and all the per-provider intricacies. The gateway is
+ * pure protocol translation: foreign wire → gjc Context → pi-ai stream() →
+ * gjc events → foreign wire.
+ *
+ * Endpoints:
+ *   GET  /healthz                          → unauth; ok + version
+ *   GET  /v1/usage                         → aggregated provider usage (5-min per-credential cache via AuthStorage)
+ *   GET  /v1/credentials/check             → per-credential auth probe (diagnose 401s in a multi-account pool)
+ *   GET  /v1/models                        → list known models from the registry
+ *   POST /v1/chat/completions              → OpenAI chat-completions in/out
+ *   POST /v1/messages                      → Anthropic messages in/out
+ *   POST /v1/responses                     → OpenAI Responses in/out
+ */
 import type { AuthStorage } from "../auth-storage";
 import type { Api, Model } from "../types";
 import type { AuthGatewayServerHandle, AuthGatewayServerOptions } from "./types";

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

@@ -510,6 +510,8 @@ export declare class AuthStorage {
         baseUrlResolver?: (provider: Provider) => string | undefined;
         /** Caller's cancel signal; only rejects this caller, never the shared upstream fetch. */
         signal?: AbortSignal;
+        /** Disable provider/account/error logging for secret-safe control surfaces. */
+        logDetails?: boolean;
     }): Promise<UsageReport[] | null>;
     /**
      * Probe each stored credential against its provider's auth-verifying usage

package/dist/types/context-cap-policy.d.ts

@@ -0,0 +1,10 @@
+import type { Api, Model } from "./types";
+export interface CodexGpt56ContextCapPolicy {
+    fallback: number;
+    ceiling: number;
+}
+export declare const CODEX_GPT_5_6_CONTEXT_CAP: CodexGpt56ContextCapPolicy;
+export declare function isCodexProductTransport(model: Pick<Model<Api>, "api" | "provider">): boolean;
+export declare function isCodexGpt56Tier(model: Pick<Model<Api>, "id">): boolean;
+export declare function resolveCodexGpt56DiscoveryContext(model: Pick<Model<Api>, "api" | "id" | "provider">, rawContextWindow: unknown, policy?: CodexGpt56ContextCapPolicy): number;
+export declare function applyFinalCodexGpt56ContextCap<TApi extends Api>(models: readonly Model<TApi>[], policy?: CodexGpt56ContextCapPolicy): Model<TApi>[];

package/dist/types/index.d.ts

@@ -4,6 +4,7 @@ export * from "./auth-broker";
 export { type AuthGatewayBootOptions, type ModelResolver, startAuthGateway } from "./auth-gateway/server";
 export * from "./auth-gateway/types";
 export * from "./auth-storage";
+export * from "./context-cap-policy";
 export * from "./model-cache";
 export * from "./model-manager";
 export * from "./model-thinking";
@@ -41,6 +42,7 @@ export * from "./usage/zai";
 export * from "./utils/anthropic-auth";
 export * from "./utils/discovery";
 export * from "./utils/event-stream";
+export * from "./utils/fallback-transport";
 export * from "./utils/h2-fetch";
 export * from "./utils/oauth";
 export type { OAuthCredentials, OAuthProvider, OAuthProviderId, OAuthProviderInfo, } from "./utils/oauth/types";

package/dist/types/providers/openai-codex/response-handler.d.ts

@@ -10,6 +10,7 @@ export type CodexRateLimits = {
 export type CodexErrorInfo = {
     message: string;
     status: number;
+    code?: string;
     friendlyMessage?: string;
     rateLimits?: CodexRateLimits;
     raw?: string;

package/dist/types/providers/pi-native-server.d.ts

@@ -4,7 +4,7 @@
  * Where the OpenAI / Anthropic / Responses route modules translate foreign
  * wire shapes through pi-ai's canonical {@link Context}, this module accepts
  * the canonical shape *directly* — for clients that already speak pi-ai
- * (containerized gjc and robogjc's sidecar auth-gateway).
+ * (containerized GJC deployments and sidecar auth gateways).
  * Skipping the wire-format → Context → wire-format round-trip cuts
  * per-request CPU but, more importantly, avoids the quantization that those
  * translations impose on first-class pi-ai fields (service tier, cache
@@ -51,8 +51,8 @@ export declare function parseRequest(body: unknown, _headers?: Headers): PiNativ
  * canonical event type IS the wire type. Including the rolling
  * `partial: AssistantMessage` on every delta is quadratic in turn length
  * on the wire, but for the loopback / sidecar topology this transport
- * targets (containerized gjc → host gateway, robogjc slot → gjc-auth-gateway
- * sidecar) the bandwidth cost is negligible compared to provider latency —
+ * targets (containerized GJC → host gateway) the bandwidth cost is negligible
+ * compared to provider latency —
  * and the client gets to feed the events straight into its existing
  * `AssistantMessageEventStream.push()` plumbing with zero translation.
  */

package/dist/types/types.d.ts

@@ -12,6 +12,7 @@ import type { OpenAICodexResponsesOptions } from "./providers/openai-codex-respo
 import type { OpenAICompletionsOptions } from "./providers/openai-completions";
 import type { OpenAIResponsesOptions } from "./providers/openai-responses";
 import type { AssistantMessageEventStream } from "./utils/event-stream";
+import type { FallbackAttemptToken, TransportFailureFacts } from "./utils/fallback-transport";
 export type { AssistantMessageEventStream } from "./utils/event-stream";
 export type KnownApi = "openai-completions" | "openai-responses" | "openai-codex-responses" | "azure-openai-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-gemini-cli" | "google-vertex" | "ollama-chat" | "cursor-agent";
 export type Api = KnownApi | (string & {});
@@ -31,6 +32,8 @@ export interface ApiOptionsMap {
 export type OptionsForApi<TApi extends Api> = StreamOptions | (TApi extends keyof ApiOptionsMap ? ApiOptionsMap[TApi] : never);
 /** Canonical thinking transport used by a model. */
 export type ThinkingControlMode = "effort" | "budget" | "google-level" | "anthropic-adaptive" | "anthropic-budget-effort";
+/** Canonical runtime vocabulary for provider thinking transports. */
+export declare const THINKING_CONTROL_MODES: readonly ["effort", "budget", "google-level", "anthropic-adaptive", "anthropic-budget-effort"];
 /** Per-model thinking capabilities used to clamp and map user-facing effort levels. */
 export interface ThinkingConfig {
     /** Least intensive supported user-facing effort level. */
@@ -163,6 +166,10 @@ export interface StreamOptions {
     maxTokens?: number;
     signal?: AbortSignal;
     apiKey?: string;
+    /** Disables all transport-level replay; the fallback controller owns retries. */
+    fallbackManaged?: boolean;
+    /** Opaque token returned by beginAttempt for a managed transport invocation. */
+    fallbackAttempt?: FallbackAttemptToken;
     /**
      * Called when a provider returns 401 before any replay-unsafe assistant
      * event has been emitted. Returning a different key retries the provider
@@ -434,6 +441,8 @@ export interface AssistantMessage {
     errorKind?: AssistantErrorKind;
     /** HTTP status surfaced by the provider when the request failed. Populated by every provider's catch block alongside `errorMessage` so consumers (auth retry, telemetry, UI) can branch without regex-scraping the message. */
     errorStatus?: number;
+    /** Typed upstream failure facts retained for retry classification without parsing errorMessage. */
+    transportFailure?: TransportFailureFacts;
     /**
      * Stable identifiers for request features the provider silently dropped
      * during this turn (e.g. `"priority"`). Set when a server-side rejection
@@ -790,10 +799,9 @@ export interface Model<TApi extends Api = any> {
      * (or compatible) host; `headers.Authorization` (or `apiKey` resolved by
      * the registry) carries the gateway bearer.
      *
-     * Used by containerized gjc installs (e.g. robogjc slots) to route every
-     * LLM call through a sidecar gateway that holds the real provider
-     * credentials. The model's other metadata (pricing, context window,
-     * thinking config, …) still resolves locally; only the streaming
+     * Used by containerized GJC installs to route every LLM call through a
+     * sidecar gateway that holds the real provider credentials. The model's other
+     * metadata (pricing, context window, thinking config, …) still resolves locally; only the streaming
      * dispatch is redirected.
      */
     transport?: "pi-native";

package/dist/types/utils/event-stream.d.ts

@@ -15,11 +15,19 @@ export declare class EventStream<T, R = T> implements AsyncIterable<T> {
     /**
      * Read-only snapshot of the not-yet-consumed events. Always a fresh copy:
      * external code can never mutate internal queue state or observe head-index
-     * tombstones, so the deque cannot desynchronize.
+     * tombstones or private consumer-drain sentinels, so the deque cannot desynchronize.
      */
     get queue(): T[];
+    /** Read-only test seam for outstanding consumer-drain waiters. */
+    get pendingConsumerDrainCountForTests(): number;
     push(event: T): void;
     deliver(event: T): void;
+    /**
+     * Resolves after every event enqueued before this call has been yielded and
+     * the consumer asks the iterator for its next node. The private sentinel is
+     * never exposed through the async iterator.
+     */
+    waitForConsumerDrain(signal: AbortSignal): Promise<void>;
     end(result?: R): void;
     endWaiting(): void;
     fail(err: unknown): void;
@@ -28,6 +36,4 @@ export declare class EventStream<T, R = T> implements AsyncIterable<T> {
 }
 export declare class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
     constructor();
-    push(event: AssistantMessageEvent): void;
-    end(result?: AssistantMessage): void;
 }

package/dist/types/utils/fallback-transport.d.ts

@@ -0,0 +1,55 @@
+export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "other";
+export interface FallbackTrigger {
+    class: FallbackTriggerClass;
+    retryAfterMs?: number;
+}
+export type TransportHeaders = Headers | Record<string, string | undefined>;
+/**
+ * Structured facts from an upstream HTTP or transport failure. Retry decisions
+ * must use these facts rather than provider- or application-owned error text.
+ */
+export interface TransportFailureFacts {
+    kind: "transport";
+    status?: number;
+    providerCode?: string;
+    headers?: TransportHeaders;
+}
+/** Opaque per-invocation marker required by managed fallback transport calls. */
+export interface FallbackAttemptToken {
+    readonly modelKey: string;
+    readonly attemptId: string | number;
+}
+/**
+ * Marks a single outer fallback invocation. Accounting belongs to the caller;
+ * this token prevents managed transport calls from silently bypassing it.
+ */
+export declare function beginAttempt(modelKey: string, attemptId: string | number): FallbackAttemptToken;
+export declare function assertManagedAttempt(options: {
+    fallbackManaged?: boolean;
+    fallbackAttempt?: FallbackAttemptToken;
+} | undefined): void;
+/**
+ * Compatibility input for callers that have not yet wrapped their HTTP facts
+ * in the discriminated form. Only its structured fields are inspected.
+ */
+export interface FallbackTriggerInput {
+    status?: number;
+    providerCode?: string;
+    code?: string;
+    headers?: TransportHeaders;
+    response?: {
+        status?: number;
+        headers?: TransportHeaders;
+    };
+    error?: {
+        code?: string;
+        type?: string;
+    };
+}
+/** Extracts only explicit HTTP/transport metadata; it never parses error text. */
+export declare function transportFailureFacts(error: unknown, capturedResponse?: {
+    status?: number;
+    headers?: TransportHeaders;
+}): TransportFailureFacts | undefined;
+/** Classifies only typed upstream transport facts without consuming response bodies. */
+export declare function classifyFallbackTrigger(errorOrFacts: TransportFailureFacts | FallbackTriggerInput | unknown): FallbackTrigger;

package/dist/types/utils/retry.d.ts

@@ -23,4 +23,5 @@ export declare function callWithCopilotModelRetry<T>(fn: () => Promise<T>, optio
     provider: string;
     signal?: AbortSignal;
     retryBaseDelayMs?: number;
+    fallbackManaged?: boolean;
 }): Promise<T>;

package/dist/types/utils.d.ts

@@ -18,6 +18,48 @@ export declare function normalizeResponsesToolCallId(id: string, itemPrefix?: Re
  */
 export declare function truncateResponseItemId(id: string, prefix: string): string;
 export declare function sanitizeOpenAIResponsesHistoryItemsForReplay(items: Array<Record<string, unknown>>): ResponseInput;
+/**
+ * Neutralize leaked OpenAI Harmony / control tokens (`<|channel|>`, `<|message|>`,
+ * `<|call|>`, `<|constrain|>`, `<|recipient|>`, `<|content|>`, ...) in replayed
+ * history text. A subagent whose tool-call channel degenerates can dump raw
+ * control-token scaffolding into its reply text; once that poisoned text lands in
+ * history the Codex / Responses endpoint rejects every subsequent request with
+ * `Request blocked (code=invalid_prompt)`, permanently wedging the session because
+ * the offending item is re-sent on each turn. Insert a zero-width space after `<`
+ * so the delimiter can no longer be tokenized as a reserved control token while the
+ * text stays human-readable.
+ *
+ * The pattern matches the two control-token shapes only, so ordinary text and pipe
+ * syntax is left untouched:
+ *   - simple form `<|ident|>` — a leading run of identifier chars then `|>`; and
+ *   - header form `<|role to=recipient|>` — a known Harmony role
+ *     (`system`/`developer`/`user`/`assistant`/`tool`) followed by a single
+ *     recipient assignment `to=<recipient>` whose value is an unbounded run of
+ *     non-delimiter, non-whitespace chars (so long MCP/custom tool recipients like
+ *     `to=functions.<long.name>` are covered).
+ * The header branch is deliberately scoped to the known role + `to=` recipient
+ * grammar rather than an arbitrary `key=value`, so request-boundary sanitization
+ * never rewrites non-control delimiter text such as `<|foo bar=baz|>`. A single-line
+ * body (no `\n`) and the required leading identifier char also leave compact
+ * pipe/operator syntax alone — e.g. F# `value <| f |> g` (space after `<|`),
+ * `sum<|a+b|>c` (punctuation body), and `<|foo bar|>` (no assignment) never match.
+ * The simple branch is a strict superset of the original identifier-only pattern:
+ * every marker the old regex caught still matches.
+ */
+export declare function neutralizeReservedControlTokens(text: string): string;
+/**
+ * Neutralize leaked reserved control tokens across every string in an outgoing
+ * Responses `input` array. This is the request-boundary complement to the
+ * replay-history sanitizer: leaked Harmony markers (`<|channel|>analysis`, ...)
+ * can enter the payload from assistant reasoning summaries, live-converted
+ * message/tool-output text, or user-authored content — not just replayed
+ * history — and every gpt-5.6 request that carries one is rejected with
+ * `Request blocked (code=invalid_prompt)`. Walking every string (rather than an
+ * item-type allowlist) guarantees no leak source is missed as item shapes
+ * evolve; the zero-width-space insertion is idempotent (`<\u200b|` no longer
+ * matches `<|`) and keeps the text human-readable.
+ */
+export declare function neutralizeResponsesInputControlTokens<T>(items: readonly T[]): T[];
 export declare function createOpenAIResponsesHistoryPayload(provider: string, items: Array<Record<string, unknown>>, incremental?: boolean): OpenAIResponsesHistoryPayload;
 export declare function getOpenAIResponsesHistoryPayload(providerPayload: ProviderPayload | undefined, currentProvider: string, fallbackProvider?: string): OpenAIResponsesHistoryPayload | undefined;
 export declare function getOpenAIResponsesHistoryItems(providerPayload: ProviderPayload | undefined, currentProvider: string, fallbackProvider?: string): Array<Record<string, unknown>> | undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/ai",
-	"version": "0.10.1",
+	"version": "0.11.0",
 	"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.10.1",
+		"@gajae-code/utils": "0.11.0",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/auth-gateway/server.ts

@@ -17,6 +17,7 @@
  *   POST /v1/messages                      → Anthropic messages in/out
  *   POST /v1/responses                     → OpenAI Responses in/out
  */
+
 import { logger } from "@gajae-code/utils";
 import type { AuthStorage } from "../auth-storage";
 import { Effort } from "../model-thinking";
@@ -26,6 +27,7 @@ import * as openaiResponses from "../providers/openai-responses-server";
 import * as piNative from "../providers/pi-native-server";
 import { streamSimple } from "../stream";
 import type { Api, AssistantMessageEventStream, Context, Model, SimpleStreamOptions } from "../types";
+import { beginAttempt, classifyFallbackTrigger } from "../utils/fallback-transport";
 import { parseBind } from "../utils/parse-bind";
 import {
 	captureRequestHeaders,
@@ -260,6 +262,90 @@ async function refreshGatewayApiKeyAfterAuthError(
 	return storage.getApiKey(provider, undefined, { modelId: model.id, signal });
 }
 
+/**
+ * Records a managed gateway failure against the credential selected for this
+ * request. This deliberately never returns a replacement key: the outer
+ * fallback controller owns the next attempt and is the only component allowed
+ * to make another upstream request.
+ */
+async function markManagedGatewayCredentialFailure(
+	storage: AuthStorage,
+	model: Model<Api>,
+	apiKey: string,
+	error: unknown,
+	signal: AbortSignal,
+	format: string,
+	peer: string,
+): Promise<void> {
+	const trigger = classifyFallbackTrigger(error);
+	try {
+		if (trigger.class === "auth") {
+			await storage.invalidateCredentialMatching(model.provider, apiKey, signal);
+		} else if (trigger.class === "quota" || trigger.class === "rate_limit") {
+			await storage.markUsageLimitReached(model.provider, undefined, {
+				retryAfterMs: trigger.retryAfterMs,
+				signal,
+			});
+		} else {
+			return;
+		}
+		logger.debug("auth-gateway recorded managed credential failure", {
+			format,
+			provider: model.provider,
+			peer,
+			trigger: trigger.class,
+		});
+	} catch (markError) {
+		// Credential bookkeeping must not replace the upstream failure returned to
+		// the fallback controller.
+		logger.warn("auth-gateway failed to record managed credential failure", {
+			format,
+			provider: model.provider,
+			peer,
+			error: markError instanceof Error ? markError.message : String(markError),
+		});
+	}
+}
+
+function observeManagedGatewayFailure(
+	events: AssistantMessageEventStream,
+	markFailure: (error: unknown) => Promise<void>,
+): AssistantMessageEventStream {
+	let marked = false;
+	const markOnce = async (error: unknown): Promise<void> => {
+		if (marked) return;
+		marked = true;
+		await markFailure(error);
+	};
+	async function* observed() {
+		try {
+			for await (const event of events) {
+				if (event.type === "error") {
+					await markOnce(event.error.transportFailure ?? { kind: "transport", status: event.error.errorStatus });
+				}
+				yield event;
+			}
+		} catch (error) {
+			await markOnce(error);
+			throw error;
+		}
+	}
+	const result = observed() as unknown as AssistantMessageEventStream;
+	result.result = async () => {
+		try {
+			const message = await events.result();
+			if (message.stopReason === "error") {
+				await markOnce(message.transportFailure ?? { kind: "transport", status: message.errorStatus });
+			}
+			return message;
+		} catch (error) {
+			await markOnce(error);
+			throw error;
+		}
+	};
+	return result;
+}
+
 function clientClosedResponse(route: { module: FormatModule }): Response {
 	return route.module.formatError(499, "request_aborted", "client closed request");
 }
@@ -361,17 +447,21 @@ async function handleFormatEndpoint(
 
 	const streamOpts = buildStreamOptions(parsed, model.api, controller.signal);
 	streamOpts.apiKey = apiKey;
-	streamOpts.onAuthError = (provider, oldKey, error) =>
-		refreshGatewayApiKeyAfterAuthError(
-			bootOpts.storage,
-			model,
-			provider,
-			oldKey,
-			error,
-			controller.signal,
-			route.label,
-			peer,
-		);
+	if (streamOpts.fallbackManaged) {
+		streamOpts.fallbackAttempt = beginAttempt(model.id, "auth-gateway");
+	} else {
+		streamOpts.onAuthError = (provider, oldKey, error) =>
+			refreshGatewayApiKeyAfterAuthError(
+				bootOpts.storage,
+				model,
+				provider,
+				oldKey,
+				error,
+				controller.signal,
+				route.label,
+				peer,
+			);
+	}
 
 	logger.info("auth-gateway request", {
 		format: route.label,
@@ -387,10 +477,34 @@ async function handleFormatEndpoint(
 		if (controller.signal.aborted) return clientClosedResponse(route);
 		events = streamSimple(model, parsed.context, streamOpts);
 	} catch (error) {
+		if (streamOpts.fallbackManaged) {
+			await markManagedGatewayCredentialFailure(
+				bootOpts.storage,
+				model,
+				apiKey,
+				error,
+				controller.signal,
+				route.label,
+				peer,
+			);
+		}
 		const classified = classifyGatewayError(error);
 		logger.warn("auth-gateway streamSimple threw", { format: route.label, error: classified.message, peer });
 		return route.module.formatError(classified.status, classified.type, classified.message);
 	}
+	if (streamOpts.fallbackManaged) {
+		events = observeManagedGatewayFailure(events, error =>
+			markManagedGatewayCredentialFailure(
+				bootOpts.storage,
+				model,
+				apiKey,
+				error,
+				controller.signal,
+				route.label,
+				peer,
+			),
+		);
+	}
 
 	if (!parsed.stream) {
 		try {
@@ -509,17 +623,21 @@ async function handlePiNative(bootOpts: AuthGatewayBootOptions, req: Request, pe
 	// only inject server-controlled fields. The OpenAI code backend temperature/topP strip
 	// matches `buildStreamOptions` — OpenAI code backend rejects them with a 400.
 	const streamOpts: SimpleStreamOptions = { ...parsed.options, apiKey, signal: controller.signal };
-	streamOpts.onAuthError = (provider, oldKey, error) =>
-		refreshGatewayApiKeyAfterAuthError(
-			bootOpts.storage,
-			model,
-			provider,
-			oldKey,
-			error,
-			controller.signal,
-			"pi-native",
-			peer,
-		);
+	if (streamOpts.fallbackManaged) {
+		streamOpts.fallbackAttempt = beginAttempt(model.id, "auth-gateway-pi-native");
+	} else {
+		streamOpts.onAuthError = (provider, oldKey, error) =>
+			refreshGatewayApiKeyAfterAuthError(
+				bootOpts.storage,
+				model,
+				provider,
+				oldKey,
+				error,
+				controller.signal,
+				"pi-native",
+				peer,
+			);
+	}
 	if (model.api === "openai-codex-responses") {
 		delete streamOpts.temperature;
 		delete streamOpts.topP;
@@ -547,10 +665,34 @@ async function handlePiNative(bootOpts: AuthGatewayBootOptions, req: Request, pe
 		if (controller.signal.aborted) return aborted();
 		events = streamSimple(model, parsed.context, streamOpts);
 	} catch (error) {
+		if (streamOpts.fallbackManaged) {
+			await markManagedGatewayCredentialFailure(
+				bootOpts.storage,
+				model,
+				apiKey,
+				error,
+				controller.signal,
+				"pi-native",
+				peer,
+			);
+		}
 		const classified = classifyGatewayError(error);
 		logger.warn("auth-gateway streamSimple threw", { format: "pi-native", error: classified.message, peer });
 		return piNative.formatError(classified.status, classified.type, classified.message);
 	}
+	if (streamOpts.fallbackManaged) {
+		events = observeManagedGatewayFailure(events, error =>
+			markManagedGatewayCredentialFailure(
+				bootOpts.storage,
+				model,
+				apiKey,
+				error,
+				controller.signal,
+				"pi-native",
+				peer,
+			),
+		);
+	}
 
 	if (!parsed.stream) {
 		try {