@gajae-code/ai 0.10.2 → 0.11.0

package/src/providers/openai-codex-responses.ts

@@ -48,6 +48,7 @@ import {
 	sanitizeOpenAIResponsesHistoryItemsForReplay,
 } from "../utils";
 import { AssistantMessageEventStream } from "../utils/event-stream";
+import { transportFailureFacts } from "../utils/fallback-transport";
 import { finalizeErrorMessage, type RawHttpRequestDump } from "../utils/http-inspector";
 import { getOpenAIStreamIdleTimeoutMs, iterateWithIdleTimeout } from "../utils/idle-iterator";
 import { parseStreamingJson } from "../utils/json-parse";
@@ -1373,6 +1374,7 @@ async function recoverCodexStreamError(
 	runtime: CodexStreamRuntime,
 	error: unknown,
 ): Promise<boolean> {
+	if (context.options?.fallbackManaged) return false;
 	if (await tryRetryWithoutForcedToolChoice(context, runtime, error)) {
 		return true;
 	}
@@ -1397,6 +1399,7 @@ async function tryRetryWithoutForcedToolChoice(
 	error: unknown,
 ): Promise<boolean> {
 	if (
+		context.options?.fallbackManaged ||
 		runtime.providerRetryAttempt > 0 ||
 		context.output.content.length > 0 ||
 		context.firstTokenTime !== undefined ||
@@ -1469,7 +1472,12 @@ async function tryReconnectCodexWebSocketOnConnectionLimit(
 		return false;
 	}
 	const websocketState = context.requestContext.websocketState;
-	if (!websocketState || runtime.transport !== "websocket" || context.options?.signal?.aborted) {
+	if (
+		!websocketState ||
+		runtime.transport !== "websocket" ||
+		context.options?.signal?.aborted ||
+		context.options?.fallbackManaged
+	) {
 		return false;
 	}
 
@@ -1520,6 +1528,7 @@ async function tryRecoverCodexPreviousResponseNotFound(
 	if (
 		!isCodexPreviousResponseNotFound(error) ||
 		!websocketState ||
+		context.options?.fallbackManaged ||
 		runtime.transport !== "websocket" ||
 		context.output.content.length > 0 ||
 		context.options?.signal?.aborted ||
@@ -1557,7 +1566,8 @@ async function tryReplayWebsocketFailureOverSse(
 		isCodexWebSocketRetryableStreamError(error) &&
 		runtime.canSafelyReplayWebsocketOverSse &&
 		!runtime.sawTerminalEvent &&
-		!context.options?.signal?.aborted;
+		!context.options?.signal?.aborted &&
+		!context.options?.fallbackManaged;
 	if (!canReplay) return false;
 
 	const state = websocketState;
@@ -1609,7 +1619,8 @@ async function tryRetryCodexProviderError(
 		!isRetryableCodexProviderError(error) ||
 		context.output.content.length > 0 ||
 		runtime.providerRetryAttempt >= resolveRetryBudget(context.options?.streamMaxRetries, CODEX_MAX_RETRIES) ||
-		context.options?.signal?.aborted
+		context.options?.signal?.aborted ||
+		context.options?.fallbackManaged
 	) {
 		return false;
 	}
@@ -1693,6 +1704,7 @@ async function handleCodexStreamFailure(
 	}
 	output.stopReason = context.options?.signal?.aborted ? "aborted" : "error";
 	output.errorStatus = extractHttpStatusFromError(error);
+	output.transportFailure = transportFailureFacts(error);
 	output.errorMessage = await finalizeErrorMessage(error, context.requestContext.rawRequestDump);
 	output.duration = Date.now() - context.startTime;
 	if (context.firstTokenTime) {
@@ -1720,6 +1732,7 @@ export const streamOpenAICodexResponses: StreamFunction<"openai-codex-responses"
 			try {
 				initialTransport = await openInitialCodexEventStream(model, options, requestSetup, requestContext);
 			} catch (error) {
+				if (options?.fallbackManaged) throw error;
 				initialTransport = await retryCodexInitialTransportWithoutToolChoice(
 					model,
 					options,
@@ -2409,6 +2422,7 @@ async function openCodexSseEventStream(
 		const error = new Error(info.friendlyMessage || info.message);
 		(error as { headers?: Headers; status?: number }).headers = response.headers;
 		(error as { headers?: Headers; status?: number }).status = response.status;
+		(error as { code?: string }).code = info.code;
 		throw error;
 	}
 	if (!response.body) {

package/src/providers/openai-completions.ts

@@ -38,6 +38,7 @@ import {
 import { normalizeSystemPrompts, sanitizeJsonStrings } from "../utils";
 import { createAbortSourceTracker } from "../utils/abort";
 import { AssistantMessageEventStream } from "../utils/event-stream";
+import { transportFailureFacts } from "../utils/fallback-transport";
 import { toFirepassWireModelId, toFireworksWireModelId } from "../utils/fireworks-model-id";
 import {
 	type CapturedHttpErrorResponse,
@@ -512,13 +513,18 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 				openaiStream = await callWithCopilotModelRetry(() => createCompletionsStream(), {
 					provider: model.provider,
 					signal: requestSignal,
+					fallbackManaged: options?.fallbackManaged,
 				});
 			} catch (error) {
 				const capturedErrorResponse = getCapturedErrorResponse();
 				const sentForcedToolChoice = isForcedToolChoice(
 					(rawRequestDump?.body as { tool_choice?: unknown } | undefined)?.tool_choice,
 				);
-				if (firstTokenTime === undefined && isForcedToolChoiceUnsupportedError(error, sentForcedToolChoice)) {
+				if (
+					!options?.fallbackManaged &&
+					firstTokenTime === undefined &&
+					isForcedToolChoiceUnsupportedError(error, sentForcedToolChoice)
+				) {
 					const reason = await finalizeErrorMessage(error, rawRequestDump, capturedErrorResponse);
 					markToolChoiceIncapability(model, "auto", reason);
 					const resolvedToolChoice = resolveToolChoice(model, options?.toolChoice);
@@ -534,6 +540,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 					});
 					openaiStream = await createCompletionsStream();
 				} else if (
+					!options?.fallbackManaged &&
 					isOpenRouterAnthropicModel(model) &&
 					!disableStrictTools &&
 					isCompiledGrammarTooLargeStrictError(error, capturedErrorResponse)
@@ -546,7 +553,10 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 					disableStrictTools = true;
 					openaiStream = await createCompletionsStream("none");
 				} else {
-					if (!shouldRetryWithoutStrictTools(error, capturedErrorResponse, appliedToolStrictMode, context.tools)) {
+					if (
+						options?.fallbackManaged ||
+						!shouldRetryWithoutStrictTools(error, capturedErrorResponse, appliedToolStrictMode, context.tools)
+					) {
 						throw error;
 					}
 					openaiStream = await createCompletionsStream("none");
@@ -960,6 +970,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 			const capturedErrorResponse = getCapturedErrorResponse?.();
 			output.stopReason = abortTracker.wasCallerAbort() ? "aborted" : "error";
 			output.errorStatus = extractHttpStatusFromError(error) ?? capturedErrorResponse?.status;
+			output.transportFailure = transportFailureFacts(error, capturedErrorResponse);
 			output.errorMessage =
 				firstEventTimeoutError?.message ??
 				(await finalizeErrorMessage(error, rawRequestDump, capturedErrorResponse));

package/src/providers/openai-responses.ts

@@ -40,6 +40,7 @@ import {
 } from "../utils";
 import { createAbortSourceTracker } from "../utils/abort";
 import { AssistantMessageEventStream } from "../utils/event-stream";
+import { transportFailureFacts } from "../utils/fallback-transport";
 import { finalizeErrorMessage, type RawHttpRequestDump, rewriteCopilotError } from "../utils/http-inspector";
 import {
 	createWatchdog,
@@ -299,9 +300,12 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 					await notifyProviderResponse(options, response, model, request_id);
 					return data;
 				},
-				{ provider: model.provider, signal: requestSignal },
+				{ provider: model.provider, signal: requestSignal, fallbackManaged: options?.fallbackManaged },
 			).catch(async error => {
-				if (!isForcedToolChoiceUnsupportedError(error, isForcedOpenAIResponsesToolChoice(params.tool_choice))) {
+				if (
+					options?.fallbackManaged ||
+					!isForcedToolChoiceUnsupportedError(error, isForcedOpenAIResponsesToolChoice(params.tool_choice))
+				) {
 					throw error;
 				}
 				const reason = await finalizeErrorMessage(error, rawRequestDump);
@@ -380,6 +384,7 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 			const firstEventTimeoutError = abortTracker.getLocalAbortReason();
 			output.stopReason = abortTracker.wasCallerAbort() ? "aborted" : "error";
 			output.errorStatus = extractHttpStatusFromError(error);
+			output.transportFailure = transportFailureFacts(error);
 			output.errorMessage = firstEventTimeoutError?.message ?? (await finalizeErrorMessage(error, rawRequestDump));
 			output.errorMessage = rewriteCopilotError(output.errorMessage, error, model.provider);
 			output.duration = Date.now() - startTime;

package/src/providers/pi-native-client.ts

@@ -11,8 +11,8 @@
  *
  * Activated when a {@link Model} has `transport: "pi-native"` set; the
  * dispatch hook lives in `streamSimple()` (see `../stream.ts`). Used by
- * containerized gjc deployments (e.g. robogjc slots) that route every LLM call
- * through a credential-holding sidecar so the slot itself stays credential-free.
+ * containerized GJC deployments that route every LLM call through a
+ * credential-holding sidecar so the container stays credential-free.
  */
 import { readSseJson } from "@gajae-code/utils";
 import type {
@@ -44,6 +44,7 @@ const NON_WIRE_KEYS = new Set<keyof SimpleStreamOptions>([
 	"cursorExecHandlers",
 	"cursorOnToolResult",
 	"providerSessionState",
+	"fallbackAttempt",
 ]);
 
 function buildWireOptions(options: SimpleStreamOptions | undefined): Record<string, unknown> {
@@ -70,15 +71,27 @@ async function decodeGatewayError(response: Response): Promise<Error> {
 		if (typeof err === "object" && err !== null) {
 			const message = (err as { message?: unknown }).message;
 			const type = (err as { type?: unknown }).type;
+			const code = (err as { code?: unknown }).code;
 			const out = new Error(typeof message === "string" ? message : `auth-gateway ${status}`);
-			(out as { status?: number; type?: string }).status = status;
-			if (typeof type === "string") (out as { type?: string }).type = type;
+			const transportError = out as Error & {
+				status?: number;
+				type?: string;
+				providerCode?: string;
+				headers?: Headers;
+			};
+			transportError.status = status;
+			transportError.headers = response.headers;
+			if (typeof type === "string") transportError.type = type;
+			if (typeof code === "string") transportError.providerCode = code;
+			else if (typeof type === "string") transportError.providerCode = type;
 			return out;
 		}
 	}
 	const text = typeof body === "string" ? body : JSON.stringify(body);
 	const err = new Error(`auth-gateway ${status}: ${text || response.statusText}`);
-	(err as { status?: number }).status = status;
+	const transportError = err as Error & { status?: number; headers?: Headers };
+	transportError.status = status;
+	transportError.headers = response.headers;
 	return err;
 }
 
@@ -180,19 +193,18 @@ export function streamPiNative<TApi extends Api>(
 			}
 
 			if (!sawTerminal) {
-				// SSE closed before a terminal event reached us — synthesize one
-				// so awaiters of `.result()` resolve instead of hanging forever.
-				// Matches the gateway's own defensive fallback in
-				// `pi-native-server.encodeStream`.
 				const aborted = signal?.aborted === true;
-				const partial = makeSyntheticAssistant(model as Model<Api>);
 				if (aborted) {
+					const partial = makeSyntheticAssistant(model as Model<Api>);
 					partial.stopReason = "aborted";
 					partial.errorMessage = "stream closed without terminal event";
 					stream.push({ type: "error", reason: "aborted", error: partial });
 				} else {
-					partial.stopReason = "stop";
-					stream.push({ type: "done", reason: "stop", message: partial });
+					const error = Object.assign(new Error("pi-native SSE stream closed without terminal event"), {
+						status: 502,
+						headers: response.headers,
+					});
+					stream.fail(error);
 				}
 			}
 			stream.end();

package/src/providers/pi-native-server.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
@@ -56,6 +56,7 @@ const ALLOWED_OPTION_KEYS: ReadonlySet<keyof SimpleStreamOptions> = new Set([
 	"headers",
 	"initiatorOverride",
 	"maxRetryDelayMs",
+	"fallbackManaged",
 	"metadata",
 	"sessionId",
 	"streamFirstEventTimeoutMs",
@@ -154,8 +155,8 @@ const SSE_DONE = SSE_ENCODER.encode("data: [DONE]\n\n");
  * 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/src/stream.ts

@@ -2,6 +2,18 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { $credentialEnv, $env, $pickCredentialEnv, extractHttpStatusFromError } from "@gajae-code/utils";
+import { assertManagedAttempt } from "./utils/fallback-transport";
+
+const managedAttemptValidated = Symbol("managedAttemptValidated");
+
+function hasValidatedManagedAttempt(options: object | undefined): boolean {
+	return (options as Record<symbol, unknown> | undefined)?.[managedAttemptValidated] === true;
+}
+
+function markManagedAttemptValidated<T extends object>(options: T): T {
+	return Object.assign(options, { [managedAttemptValidated]: true });
+}
+
 import { getCustomApi } from "./api-registry";
 import type { Effort } from "./model-thinking";
 import {
@@ -276,6 +288,10 @@ export function stream<TApi extends Api>(
 	context: Context,
 	options?: OptionsForApi<TApi>,
 ): AssistantMessageEventStream {
+	if (!hasValidatedManagedAttempt(options)) assertManagedAttempt(options);
+	if (options?.fallbackManaged) {
+		options = { ...options, requestMaxRetries: 0, streamMaxRetries: 0 } as OptionsForApi<TApi>;
+	}
 	// Check custom API registry first (extension-provided APIs like "vertex-Anthropic model-api")
 	const customApiProvider = getCustomApi(model.api);
 	if (customApiProvider) {
@@ -395,6 +411,16 @@ export function streamSimple<TApi extends Api>(
 	context: Context,
 	options?: SimpleStreamOptions,
 ): AssistantMessageEventStream {
+	assertManagedAttempt(options);
+	if (options?.fallbackManaged) {
+		options = {
+			...options,
+			requestMaxRetries: 0,
+			streamMaxRetries: 0,
+			onAuthError: undefined,
+		};
+		options = markManagedAttemptValidated(options);
+	}
 	const retryApiKey = options?.onAuthError ? (options.apiKey ?? getEnvApiKey(model.provider)) : undefined;
 	if (retryApiKey) {
 		const outer = new AssistantMessageEventStream();
@@ -662,12 +688,14 @@ function mapOptionsForApi<TApi extends Api>(
 		maxTokens: options?.maxTokens || Math.min(model.maxTokens, 32000),
 		signal: options?.signal,
 		apiKey: apiKey || options?.apiKey,
+		fallbackManaged: options?.fallbackManaged,
+		fallbackAttempt: options?.fallbackAttempt,
 		cacheRetention: options?.cacheRetention ?? model.cacheRetention,
 		headers: options?.headers,
 		initiatorOverride: options?.initiatorOverride,
 		maxRetryDelayMs: options?.maxRetryDelayMs,
-		requestMaxRetries: options?.requestMaxRetries,
-		streamMaxRetries: options?.streamMaxRetries,
+		requestMaxRetries: options?.fallbackManaged ? 0 : options?.requestMaxRetries,
+		streamMaxRetries: options?.fallbackManaged ? 0 : options?.streamMaxRetries,
 		metadata: options?.metadata,
 		sessionId: options?.sessionId,
 		providerSessionState: options?.providerSessionState,
@@ -675,6 +703,7 @@ function mapOptionsForApi<TApi extends Api>(
 		onResponse: options?.onResponse,
 		onSseEvent: options?.onSseEvent,
 		execHandlers: options?.execHandlers,
+		[managedAttemptValidated]: hasValidatedManagedAttempt(options),
 	};
 
 	switch (model.api) {

package/src/types.ts

@@ -28,6 +28,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";
 
@@ -77,6 +78,23 @@ export type ThinkingControlMode =
 	| "anthropic-adaptive"
 	| "anthropic-budget-effort";
 
+/** Canonical runtime vocabulary for provider thinking transports. */
+export const THINKING_CONTROL_MODES = [
+	"effort",
+	"budget",
+	"google-level",
+	"anthropic-adaptive",
+	"anthropic-budget-effort",
+] as const satisfies readonly ThinkingControlMode[];
+
+type _CheckThinkingControlModes = [
+	Exclude<ThinkingControlMode, (typeof THINKING_CONTROL_MODES)[number]>,
+	Exclude<(typeof THINKING_CONTROL_MODES)[number], ThinkingControlMode>,
+] extends [never, never]
+	? true
+	: false;
+true satisfies _CheckThinkingControlModes;
+
 /** Per-model thinking capabilities used to clamp and map user-facing effort levels. */
 export interface ThinkingConfig {
 	/** Least intensive supported user-facing effort level. */
@@ -306,6 +324,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
@@ -598,6 +620,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
@@ -939,10 +963,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/src/utils/discovery/codex.ts

@@ -1,10 +1,10 @@
 import * as z from "zod/v4";
+import { resolveCodexGpt56DiscoveryContext } from "../../context-cap-policy";
 import { CODEX_BASE_URL, OPENAI_HEADER_VALUES, OPENAI_HEADERS } from "../../providers/openai-codex/constants";
 import type { Model } from "../../types";
 import { isRecord } from "../../utils";
 
 const DEFAULT_MODEL_LIST_PATHS = ["/codex/models", "/models"] as const;
-const DEFAULT_CONTEXT_WINDOW = 272_000;
 const DEFAULT_MAX_TOKENS = 128_000;
 const DEFAULT_CODEX_CLIENT_VERSION = "0.99.0";
 const NPM_CODEX_LATEST_URL = "https://registry.npmjs.org/@openai%2Fcodex/latest";
@@ -258,7 +258,8 @@ function normalizeCodexModelEntry(entry: unknown, baseUrl: string): NormalizedCo
 	}
 
 	const name = toNonEmptyString(payload.display_name) ?? slug;
-	const contextWindow = toPositiveInt(payload.context_window) ?? DEFAULT_CONTEXT_WINDOW;
+	const modelIdentity = { id: slug, api: "openai-codex-responses", provider: "openai-codex" } as const;
+	const contextWindow = resolveCodexGpt56DiscoveryContext(modelIdentity, payload.context_window);
 	const maxTokens = Math.min(DEFAULT_MAX_TOKENS, contextWindow);
 	const reasoning = supportsReasoning(payload.default_reasoning_level, payload.supported_reasoning_levels);
 	const input = normalizeInputModalities(payload.input_modalities);
@@ -346,16 +347,6 @@ function toNonEmptyString(value: unknown): string | null {
 	return trimmed.length > 0 ? trimmed : null;
 }
 
-function toPositiveInt(value: unknown): number | null {
-	if (typeof value !== "number" || !Number.isFinite(value)) {
-		return null;
-	}
-	if (value <= 0) {
-		return null;
-	}
-	return Math.trunc(value);
-}
-
 function toFiniteNumber(value: unknown): number | null {
 	if (typeof value !== "number" || !Number.isFinite(value)) {
 		return null;