@gajae-code/ai 0.11.10 → 0.12.0

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

@@ -1,4 +1,4 @@
-import { $env, extractHttpStatusFromError, logger } from "@gajae-code/utils";
+import { $credentialEnv, $env, extractHttpStatusFromError, logger } from "@gajae-code/utils";
 import { AzureOpenAI } from "openai";
 import type {
 	Tool as OpenAITool,
@@ -234,8 +234,13 @@ function resolveAzureConfig(
 ): { baseUrl: string; apiVersion: string } {
 	const apiVersion = options?.azureApiVersion || $env.AZURE_OPENAI_API_VERSION || DEFAULT_AZURE_API_VERSION;
 
-	const baseUrl = options?.azureBaseUrl?.trim() || $env.AZURE_OPENAI_BASE_URL?.trim() || undefined;
-	const resourceName = options?.azureResourceName || $env.AZURE_OPENAI_RESOURCE_NAME;
+	// Trusted sources only: both of these decide the request endpoint that carries
+	// the Azure credential, and `$env` merges the caller's `cwd/.env`. The resource
+	// name is the alternate constructor for the same host
+	// (`https://<resource>.openai.azure.com/openai/v1`), so it needs the same
+	// boundary as the explicit base URL.
+	const baseUrl = options?.azureBaseUrl?.trim() || $credentialEnv("AZURE_OPENAI_BASE_URL") || undefined;
+	const resourceName = options?.azureResourceName || $credentialEnv("AZURE_OPENAI_RESOURCE_NAME");
 
 	let resolvedBaseUrl = baseUrl;
 
@@ -259,6 +264,14 @@ function resolveAzureConfig(
 	};
 }
 
+/** Test seam: the Azure endpoint config as resolved from trusted env. */
+export function resolveAzureConfigForTest(
+	model: Model<"azure-openai-responses">,
+	options?: AzureOpenAIResponsesOptions,
+): { baseUrl: string; apiVersion: string } {
+	return resolveAzureConfig(model, options);
+}
+
 function createClient(model: Model<"azure-openai-responses">, apiKey: string, options?: AzureOpenAIResponsesOptions) {
 	if (!apiKey) {
 		const envKey = $env.AZURE_OPENAI_API_KEY;

package/src/providers/google-auth.ts

@@ -15,7 +15,7 @@
 import { Buffer } from "node:buffer";
 import * as os from "node:os";
 import * as path from "node:path";
-import { $envpos, isEnoent, logger } from "@gajae-code/utils";
+import { $credentialEnv, $envpos, isEnoent, logger } from "@gajae-code/utils";
 import type { FetchImpl } from "../types";
 
 const OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
@@ -70,8 +70,19 @@ async function readJsonFile<T>(filePath: string): Promise<T | undefined> {
 	}
 }
 
+/** Test seam: the ADC credentials file path as resolved from trusted env. */
+export function resolveAdcCredentialsPathForTest(): string | undefined {
+	return $credentialEnv("GOOGLE_APPLICATION_CREDENTIALS");
+}
+
 async function loadAdcCredentials(): Promise<{ source: string; creds: AdcFileCredentials } | undefined> {
-	const gacPath = Bun.env.GOOGLE_APPLICATION_CREDENTIALS;
+	// Trusted sources only: this path is read as service-account / authorized-user
+	// credentials and exchanged for a Google access token, so whatever can set it
+	// chooses the identity the agent authenticates as. `Bun.env` is `process.env`
+	// and the env module merges the caller's `cwd/.env` into it, so reading it
+	// there would let repository content point this at a key file it ships.
+	// `stream.ts` already resolves the same variable through `$credentialEnv`.
+	const gacPath = $credentialEnv("GOOGLE_APPLICATION_CREDENTIALS");
 	if (gacPath) {
 		const creds = await readJsonFile<AdcFileCredentials>(gacPath);
 		if (!creds) {

package/src/providers/google-gemini-headers.ts

@@ -5,7 +5,7 @@
  */
 export const GEMINI_CLI_VERSION_ENV = "GJC_AI_GEMINI_CLI_VERSION";
 export const LEGACY_GEMINI_CLI_VERSION_ENV = "PI_AI_GEMINI_CLI_VERSION";
-export const DEFAULT_GEMINI_CLI_VERSION = "0.50.0";
+export const DEFAULT_GEMINI_CLI_VERSION = "0.52.0";
 
 export function getGeminiCliUserAgent(modelId = "gemini-3.1-pro-preview"): string {
 	const version =

package/src/providers/google-vertex.ts

@@ -1,4 +1,4 @@
-import { $env } from "@gajae-code/utils";
+import { $credentialEnv, $env } from "@gajae-code/utils";
 import type { Context, Model, StreamFunction } from "../types";
 import type { AssistantMessageEventStream } from "../utils/event-stream";
 import { getVertexAccessToken } from "./google-auth";
@@ -58,12 +58,17 @@ export const streamGoogleVertex: StreamFunction<"google-vertex"> = (
 		},
 	});
 
+/** Test seam: the Vertex API key as resolved from options plus trusted env. */
+export function resolveVertexApiKeyForTest(options?: GoogleVertexOptions): string | undefined {
+	return resolveApiKey(options);
+}
+
 function resolveApiKey(options?: GoogleVertexOptions): string | undefined {
 	// options.apiKey may contain sentinel values like "<authenticated>" or "N/A"
 	// leaked from the agent loop — only use it if it looks like a real API key.
 	const optKey = options?.apiKey;
 	const realKey = optKey && !optKey.startsWith("<") && optKey !== "N/A" ? optKey : undefined;
-	return realKey || $env.GOOGLE_CLOUD_API_KEY;
+	return realKey || $credentialEnv("GOOGLE_CLOUD_API_KEY");
 }
 
 function resolveProject(options?: GoogleVertexOptions): string {

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

@@ -2,7 +2,7 @@ import * as os from "node:os";
 import { scheduler } from "node:timers/promises";
 import {
 	$env,
-	$flag,
+	$pickflag,
 	asRecord,
 	extractHttpStatusFromError,
 	fetchWithRetry,
@@ -98,7 +98,7 @@ export interface OpenAICodexResponsesOptions extends StreamOptions {
 	serviceTier?: ServiceTier;
 }
 
-const CODEX_DEBUG = $flag("PI_CODEX_DEBUG");
+const CODEX_DEBUG = $pickflag("GJC_OPENAI_CODE_DEBUG", "PI_CODEX_DEBUG");
 const CODEX_MAX_RETRIES = 5;
 const CODEX_RETRY_DELAY_MS = 500;
 const CODEX_WEBSOCKET_CONNECT_TIMEOUT_MS = 10000;
@@ -133,6 +133,31 @@ const CODEX_WEBSOCKET_FATAL_PATTERNS = ["websocket error:", "websocket closed be
 /** Max total time to spend retrying 429s with server-provided delays (5 minutes). */
 const CODEX_RATE_LIMIT_BUDGET_MS = 5 * 60 * 1000;
 
+/**
+ * Tool names the Codex backend reserves for its own namespaces. Sending a
+ * function tool under one of these names is rejected with
+ * `Function 'computer.computer' not allowed in namespace 'computer'`.
+ * These are renamed on the wire and mapped back on receive so the internal
+ * tool name stays canonical everywhere else in the harness.
+ */
+const CODEX_RESERVED_TOOL_WIRE_NAMES: ReadonlyMap<string, string> = new Map([
+	["browser", "browser_tool"],
+	["computer", "computer_tool"],
+]);
+const CODEX_CANONICAL_TOOL_NAMES: ReadonlyMap<string, string> = new Map(
+	Array.from(CODEX_RESERVED_TOOL_WIRE_NAMES, ([canonical, wire]) => [wire, canonical]),
+);
+
+/** Maps a canonical tool name to the name Codex accepts on the wire. */
+export function codexToolWireName(name: string): string {
+	return CODEX_RESERVED_TOOL_WIRE_NAMES.get(name) ?? name;
+}
+
+/** Maps a Codex wire tool name back to the canonical harness tool name. */
+export function codexToolCanonicalName(wireName: string): string {
+	return CODEX_CANONICAL_TOOL_NAMES.get(wireName) ?? wireName;
+}
+
 const CODEX_PROGRESS_EVENT_TYPES = new Set([
 	"response.created",
 	"response.output_item.added",
@@ -299,24 +324,34 @@ function parseCodexPositiveInteger(value: string | undefined, fallback: number):
 }
 
 function isCodexWebSocketEnvEnabled(): boolean {
-	return $flag("PI_CODEX_WEBSOCKET");
+	return $pickflag("GJC_OPENAI_CODE_WEBSOCKET", "PI_CODEX_WEBSOCKET");
 }
 
 function getCodexWebSocketRetryBudget(options?: Pick<OpenAICodexResponsesOptions, "streamMaxRetries">): number {
 	if (options?.streamMaxRetries !== undefined) {
 		return resolveRetryBudget(options.streamMaxRetries, CODEX_WEBSOCKET_RETRY_BUDGET);
 	}
-	return parseCodexNonNegativeInteger($env.PI_CODEX_WEBSOCKET_RETRY_BUDGET, CODEX_WEBSOCKET_RETRY_BUDGET);
+	return parseCodexNonNegativeInteger(
+		$env.GJC_OPENAI_CODE_WEBSOCKET_RETRY_BUDGET ?? $env.PI_CODEX_WEBSOCKET_RETRY_BUDGET,
+		CODEX_WEBSOCKET_RETRY_BUDGET,
+	);
 }
 
 function getCodexWebSocketRetryDelayMs(retry: number): number {
-	const baseDelay = parseCodexPositiveInteger($env.PI_CODEX_WEBSOCKET_RETRY_DELAY_MS, CODEX_RETRY_DELAY_MS);
+	const baseDelay = parseCodexPositiveInteger(
+		$env.GJC_OPENAI_CODE_WEBSOCKET_RETRY_DELAY_MS ?? $env.PI_CODEX_WEBSOCKET_RETRY_DELAY_MS,
+		CODEX_RETRY_DELAY_MS,
+	);
 	return baseDelay * Math.max(1, retry);
 }
 
 function getCodexWebSocketIdleTimeoutMs(overrideMs?: number): number {
 	return (
-		overrideMs ?? parseCodexPositiveInteger($env.PI_CODEX_WEBSOCKET_IDLE_TIMEOUT_MS, CODEX_WEBSOCKET_IDLE_TIMEOUT_MS)
+		overrideMs ??
+		parseCodexPositiveInteger(
+			$env.GJC_OPENAI_CODE_WEBSOCKET_IDLE_TIMEOUT_MS ?? $env.PI_CODEX_WEBSOCKET_IDLE_TIMEOUT_MS,
+			CODEX_WEBSOCKET_IDLE_TIMEOUT_MS,
+		)
 	);
 }
 
@@ -467,7 +502,7 @@ export function normalizeCodexToolChoice(
 			: undefined;
 		return customTool
 			? { type: "custom", name: customTool.customWireName ?? customTool.name }
-			: { type: "function", name };
+			: { type: "function", name: codexToolWireName(name) };
 	};
 	if (choice.type === "function") {
 		if ("function" in choice && choice.function?.name) {
@@ -1090,7 +1125,7 @@ function createOutputBlockForItem(item: CodexEventItem): CodexOutputBlock | null
 		return {
 			type: "toolCall",
 			id: encodeResponsesToolCallId(item.call_id, item.id),
-			name: item.name,
+			name: codexToolCanonicalName(item.name),
 			arguments: {},
 			partialJson: item.arguments || "",
 		};
@@ -1348,7 +1383,7 @@ function handleOutputItemDone(
 		const toolCall: ToolCall = {
 			type: "toolCall",
 			id,
-			name: item.name,
+			name: codexToolCanonicalName(item.name),
 			arguments: parseStreamingJson(item.arguments || "{}"),
 		};
 		runtime.canSafelyReplayWebsocketOverSse = false;
@@ -2690,6 +2725,13 @@ function convertMessages(model: Model<"openai-codex-responses">, context: Contex
 				true,
 				customCallIds,
 			);
+			for (const item of outputItems) {
+				// Reconstructed (non-raw) history carries canonical tool names; the
+				// wire form has to match the renamed `tools` entries.
+				if (item.type === "function_call" && typeof item.name === "string") {
+					item.name = codexToolWireName(item.name);
+				}
+			}
 			if (outputItems.length > 0) {
 				messages.push(...outputItems);
 			}
@@ -2776,7 +2818,7 @@ export function convertOpenAICodexResponsesTools(
 		const { schema: parameters, strict: effectiveStrict } = adaptSchemaForStrict(baseParameters, strict);
 		return {
 			type: "function",
-			name: tool.name,
+			name: codexToolWireName(tool.name),
 			description: tool.description || "",
 			parameters,
 			...(effectiveStrict && { strict: true }),

package/src/providers/openai-completions.ts

@@ -1,4 +1,4 @@
-import { $credentialEnv, $env, $inheritedEnv, extractHttpStatusFromError, logger } from "@gajae-code/utils";
+import { $credentialEnv, $env, extractHttpStatusFromError, logger } from "@gajae-code/utils";
 import OpenAI from "openai";
 import type {
 	ChatCompletionAssistantMessageParam,
@@ -102,7 +102,9 @@ function resolveOpenAIProviderBaseUrl(
 	authCredentialType: "api_key" | "oauth" | undefined,
 ): string {
 	if (authCredentialType === "oauth") return OPENAI_DEFAULT_BASE_URL;
-	const envBaseUrl = $inheritedEnv("OPENAI_BASE_URL") ?? $env.OPENAI_BASE_URL?.trim();
+	// Trusted sources only: this base URL becomes the request endpoint that carries
+	// the OpenAI credential, and `$env` merges the caller's `cwd/.env`.
+	const envBaseUrl = $credentialEnv("OPENAI_BASE_URL");
 	const configuredBaseUrl = baseUrl?.trim();
 	if (envBaseUrl && (!configuredBaseUrl || isDefaultOpenAIBaseUrl(configuredBaseUrl))) {
 		return envBaseUrl;
@@ -110,6 +112,14 @@ function resolveOpenAIProviderBaseUrl(
 	return configuredBaseUrl || envBaseUrl || OPENAI_DEFAULT_BASE_URL;
 }
 
+/** Test seam: the provider base URL as resolved from trusted env. */
+export function resolveOpenAICompletionsBaseUrlForTest(
+	baseUrl: string | undefined,
+	authCredentialType: "api_key" | "oauth" | undefined,
+): string {
+	return resolveOpenAIProviderBaseUrl(baseUrl, authCredentialType);
+}
+
 /**
  * Normalize tool call ID for Mistral.
  * Mistral requires tool IDs to be exactly 9 alphanumeric characters (a-z, A-Z, 0-9).

package/src/providers/openai-responses.ts

@@ -1,11 +1,4 @@
-import {
-	$credentialEnv,
-	$env,
-	$inheritedEnv,
-	extractHttpStatusFromError,
-	logger,
-	structuredCloneJSON,
-} from "@gajae-code/utils";
+import { $credentialEnv, extractHttpStatusFromError, logger, structuredCloneJSON } from "@gajae-code/utils";
 import OpenAI from "openai";
 import type {
 	Tool as OpenAITool,
@@ -159,7 +152,10 @@ function resolveOpenAIProviderBaseUrl(
 	authCredentialType: "api_key" | "oauth" | undefined,
 ): string {
 	if (authCredentialType === "oauth") return OPENAI_DEFAULT_BASE_URL;
-	const envBaseUrl = $inheritedEnv("OPENAI_BASE_URL") ?? $env.OPENAI_BASE_URL?.trim();
+	// Trusted sources only: this base URL becomes the request endpoint that carries
+	// the OpenAI credential, and `$env` merges the caller's `cwd/.env`, so reading it
+	// there would let repository content redirect authenticated traffic.
+	const envBaseUrl = $credentialEnv("OPENAI_BASE_URL");
 	const configuredBaseUrl = baseUrl?.trim();
 	if (envBaseUrl && (!configuredBaseUrl || isDefaultOpenAIBaseUrl(configuredBaseUrl))) {
 		return envBaseUrl;
@@ -167,6 +163,14 @@ function resolveOpenAIProviderBaseUrl(
 	return configuredBaseUrl || envBaseUrl || OPENAI_DEFAULT_BASE_URL;
 }
 
+/** Test seam: the provider base URL as resolved from trusted env. */
+export function resolveOpenAIProviderBaseUrlForTest(
+	baseUrl: string | undefined,
+	authCredentialType: "api_key" | "oauth" | undefined,
+): string {
+	return resolveOpenAIProviderBaseUrl(baseUrl, authCredentialType);
+}
+
 const OPENAI_RESPONSES_PROGRESS_EVENT_TYPES = new Set([
 	"response.created",
 	"response.output_item.added",

package/src/stream.ts

@@ -163,6 +163,7 @@ const serviceProviderMap: Record<string, KeyResolver> = {
 	together: "TOGETHER_API_KEY",
 	zenmux: "ZENMUX_API_KEY",
 	opengateway: "OPENGATEWAY_API_KEY",
+	bizrouter: "BIZROUTER_API_KEY",
 	venice: "VENICE_API_KEY",
 	vllm: "VLLM_API_KEY",
 	xiaomi: "XIAOMI_API_KEY",

package/src/types.ts

@@ -148,6 +148,7 @@ export type KnownProvider =
 	| "opencode-go"
 	| "opencode-zen"
 	| "opengateway"
+	| "bizrouter"
 	| "synthetic"
 	| "cloudflare-ai-gateway"
 	| "huggingface"

package/src/usage/claude.ts

@@ -1,4 +1,5 @@
 import { scheduler } from "node:timers/promises";
+import { claudeCodeVersion } from "../providers/anthropic";
 import type {
 	CredentialRankingStrategy,
 	UsageAmount,
@@ -17,6 +18,13 @@ const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
 const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
 const MAX_ATTEMPTS = 3;
 const BASE_RETRY_DELAY_MS = 500;
+/**
+ * Ceiling for a server-supplied `Retry-After`. Matches `OPENAI_RETRY_DELAY_CAP_MS`
+ * and `fetchWithRetry`'s `DEFAULT_MAX_DELAY_MS`. Without it a hostile or
+ * misconfigured endpoint stalls the usage fetch for as long as it likes
+ * (`Retry-After: 86400` previously produced a 24h sleep).
+ */
+const MAX_RETRY_DELAY_MS = 60_000;
 
 const CLAUDE_HEADERS = {
 	accept: "application/json, text/plain, */*",
@@ -24,7 +32,7 @@ const CLAUDE_HEADERS = {
 	"anthropic-beta":
 		"claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05",
 	"content-type": "application/json",
-	"user-agent": "claude-cli/2.1.63 (external, cli)",
+	"user-agent": `claude-cli/${claudeCodeVersion} (external, cli)`,
 	connection: "keep-alive",
 } as const;
 
@@ -140,13 +148,23 @@ function isAbortError(error: unknown, signal?: AbortSignal): boolean {
 	return error.name === "AbortError" || error.name === "TimeoutError";
 }
 
+/**
+ * Honour the server hint but never exceed `MAX_RETRY_DELAY_MS`, and never
+ * return a negative/non-finite delay. Keeps the sleep bounded so an abort has
+ * an upper bound to fire within.
+ */
+function clampRetryDelay(baseline: number, hintMs: number): number {
+	const hint = Number.isFinite(hintMs) ? Math.max(0, hintMs) : 0;
+	return Math.min(Math.max(baseline, hint), MAX_RETRY_DELAY_MS);
+}
+
 function retryDelayMs(attempt: number, retryAfter: string | null): number {
 	const baseline = BASE_RETRY_DELAY_MS * 2 ** attempt;
 	if (!retryAfter?.trim()) return baseline;
 	const seconds = Number.parseFloat(retryAfter);
-	if (Number.isFinite(seconds)) return Math.max(baseline, Math.max(0, seconds * 1000));
+	if (Number.isFinite(seconds)) return clampRetryDelay(baseline, seconds * 1000);
 	const dateDelay = Date.parse(retryAfter) - Date.now();
-	return Number.isFinite(dateDelay) ? Math.max(baseline, Math.max(0, dateDelay)) : baseline;
+	return Number.isFinite(dateDelay) ? clampRetryDelay(baseline, dateDelay) : baseline;
 }
 
 async function waitBeforeRetry(

package/src/usage/grok-cli.ts

@@ -1,3 +1,4 @@
+import { $credentialEnv } from "@gajae-code/utils";
 import type {
 	CredentialRankingStrategy,
 	UsageFetchContext,
@@ -64,10 +65,20 @@ function isUnsafeGrokBaseUrlOverride(baseUrl?: string): boolean {
 }
 
 function resolveAccessToken(params: UsageFetchParams): string | undefined {
-	const token = params.credential.accessToken ?? params.credential.apiKey ?? process.env.GROK_CLI_OAUTH_TOKEN;
+	// Trusted sources only for the env fallback: this token authenticates the
+	// billing/usage call, so whatever can set it decides which account is queried
+	// with it. `$env` merges the caller's `cwd/.env` into `process.env`, so
+	// reading it there would let repository content supply the credential.
+	// Stored credentials keep precedence.
+	const token = params.credential.accessToken ?? params.credential.apiKey ?? $credentialEnv("GROK_CLI_OAUTH_TOKEN");
 	return token?.trim() || undefined;
 }
 
+/** Test seam: the usage access token as resolved from a credential plus trusted env. */
+export function resolveGrokAccessTokenForTest(params: UsageFetchParams): string | undefined {
+	return resolveAccessToken(params);
+}
+
 function buildMonthlyUsageLimit(usage: BillingUsage, nowMs: number): UsageLimit {
 	const usedFraction = usage.monthlyLimit > 0 ? usage.used / usage.monthlyLimit : 0;
 	const percent = usedFraction * 100;

package/src/usage/kimi.ts

@@ -1,4 +1,4 @@
-import { $env } from "@gajae-code/utils";
+import { $credentialEnv } from "@gajae-code/utils";
 import type {
 	UsageAmount,
 	UsageFetchContext,
@@ -31,12 +31,26 @@ type KimiUsageRow = {
 	window?: UsageWindow;
 };
 
+/**
+ * Usage endpoint base, with the environment override resolved from trusted
+ * sources only.
+ *
+ * The result becomes the usage URL that the request sends
+ * `Authorization: Bearer <accessToken>` to, so whatever can set it receives the
+ * user's Kimi access token. `$env` merges the caller's `cwd/.env`, so reading it
+ * there would let repository content collect that token.
+ */
 function normalizeBaseUrl(baseUrl?: string): string {
-	const envBase = $env.KIMI_CODE_BASE_URL?.trim();
+	const envBase = $credentialEnv("KIMI_CODE_BASE_URL");
 	const candidate = baseUrl?.trim() || envBase || DEFAULT_BASE_URL;
 	return candidate.replace(/\/+$/, "");
 }
 
+/** Test seam: the usage base URL as resolved from a caller value plus trusted env. */
+export function normalizeKimiUsageBaseUrlForTest(baseUrl?: string): string {
+	return normalizeBaseUrl(baseUrl);
+}
+
 function buildUsageUrl(baseUrl: string): string {
 	const normalized = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
 	return `${normalized}${USAGE_PATH}`;

package/src/utils/anthropic-auth.ts

@@ -8,7 +8,7 @@
  * `authStorage.getApiKey("anthropic", sessionId)` first, then pass the result
  * through {@link buildAnthropicAuthConfig} for header/URL shaping.
  */
-import { $env } from "@gajae-code/utils";
+import { $credentialEnv } from "@gajae-code/utils";
 import {
 	buildAnthropicHeaders as buildProviderAnthropicHeaders,
 	normalizeAnthropicBaseUrl,
@@ -29,12 +29,20 @@ function normalizeBaseUrl(baseUrl: string | undefined): string | undefined {
 	return trimmed ? trimmed.replace(/\/+$/, "") : undefined;
 }
 
+/**
+ * Resolve the Anthropic base URL from the environment.
+ *
+ * Trusted sources only: the result becomes the request URL that carries the
+ * Anthropic API key / OAuth token, so whatever can set it can redirect
+ * authenticated traffic. `$env` merges the caller's `cwd/.env`, so reading it
+ * there would let repository content choose where credentials are sent.
+ */
 export function resolveAnthropicBaseUrlFromEnv(): string | undefined {
 	if (isFoundryEnabled()) {
-		const foundryBaseUrl = normalizeBaseUrl($env.FOUNDRY_BASE_URL);
+		const foundryBaseUrl = normalizeBaseUrl($credentialEnv("FOUNDRY_BASE_URL"));
 		if (foundryBaseUrl) return foundryBaseUrl;
 	}
-	const anthropicBaseUrl = normalizeBaseUrl($env.ANTHROPIC_BASE_URL);
+	const anthropicBaseUrl = normalizeBaseUrl($credentialEnv("ANTHROPIC_BASE_URL"));
 	return anthropicBaseUrl || undefined;
 }
 

package/src/utils/foundry.ts

@@ -1,7 +1,17 @@
-import { $env } from "@gajae-code/utils";
+import { $credentialEnv } from "@gajae-code/utils";
 
+/**
+ * Whether Anthropic requests run in Foundry gateway mode.
+ *
+ * Resolved from trusted environment sources only. Enabling Foundry switches the
+ * request base URL and injects TLS client material, so whatever can set this
+ * redirects authenticated traffic. `$env` merges the caller's `cwd/.env`, so
+ * reading it there would let repository content flip the mode; resolve it the
+ * same way the credentials themselves are (launching shell plus GJC/user-owned
+ * `.env` files, never the project `.env`).
+ */
 export function isFoundryEnabled(): boolean {
-	const value = $env.CLAUDE_CODE_USE_FOUNDRY;
+	const value = $credentialEnv("CLAUDE_CODE_USE_FOUNDRY");
 	if (!value) return false;
 	const normalized = value.trim().toLowerCase();
 	return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";

package/src/utils/http-inspector.ts

@@ -26,6 +26,34 @@ type ErrorWithStatus = {
 
 const SENSITIVE_HEADERS = ["authorization", "x-api-key", "api-key", "cookie", "set-cookie", "proxy-authorization"];
 
+/**
+ * Connection-level failure codes, meaning the request never reached the
+ * provider and no HTTP status exists. Bun reports the first group for `fetch`;
+ * the `E*`/`UND_ERR_*` group comes from Node-style DNS and socket errors.
+ *
+ * Deliberately excludes aborts and TLS/certificate codes: an abort is a
+ * user/watchdog outcome with its own display path, and its message must keep
+ * matching the abort normalizers in `modes/utils/abort-message`.
+ */
+const TRANSPORT_FAILURE_CODES: ReadonlySet<string> = new Set([
+	"ConnectionClosed",
+	"ConnectionRefused",
+	"ConnectionReset",
+	"ConnectionTimeout",
+	"FailedToOpenSocket",
+	"HTTP2Unsupported",
+	"EAI_AGAIN",
+	"ECONNREFUSED",
+	"ECONNRESET",
+	"EHOSTUNREACH",
+	"ENETUNREACH",
+	"ENOTFOUND",
+	"EPIPE",
+	"ETIMEDOUT",
+	"UND_ERR_CONNECT_TIMEOUT",
+	"UND_ERR_SOCKET",
+]);
+
 /**
  * Privacy note appended next to a saved raw HTTP request dump. The dump is
  * sanitized (secrets/thinking redacted) but can still contain prompt content
@@ -88,6 +116,54 @@ export async function appendRawHttpRequestDumpFor400(
 	}
 }
 
+/** Origin and path of `value`, dropping query, fragment, and credentials so a
+ *  key carried in the request URL (Google `?key=`, signed URLs) never lands in
+ *  a user-visible error string. */
+function redactRequestUrl(value: unknown): string | undefined {
+	if (typeof value !== "string" || value.trim().length === 0) return undefined;
+	try {
+		const url = new URL(value);
+		return `${url.origin}${url.pathname}`;
+	} catch {
+		return undefined;
+	}
+}
+
+function findTransportFailure(error: unknown, depth: number): { code: string; url?: string } | undefined {
+	if (!error || typeof error !== "object" || depth > 2) return undefined;
+	const info = error as { code?: unknown; path?: unknown; url?: unknown; cause?: unknown };
+	if (typeof info.code === "string" && TRANSPORT_FAILURE_CODES.has(info.code)) {
+		return { code: info.code, url: redactRequestUrl(info.path) ?? redactRequestUrl(info.url) };
+	}
+	return findTransportFailure(info.cause, depth + 1);
+}
+
+/**
+ * Name the failed connection when the request never produced an HTTP status.
+ *
+ * Bun raises DNS and socket failures as a bare `Error` whose message is a
+ * standalone hint ("Was there a typo in the url or port?", "Unable to connect.
+ * Is the computer able to access the url?") while the actionable facts live on
+ * `code` and `path`. Those properties are dropped when only `message` reaches
+ * the assistant message, so a provider outage, a local DNS failure, and a
+ * mistyped custom base URL all render as the same context-free sentence.
+ * Appending the code and the target URL tells the user which host failed and
+ * whether the fault is theirs.
+ */
+export function appendTransportFailureContext(
+	message: string,
+	error: unknown,
+	rawRequestDump: RawHttpRequestDump | undefined,
+): string {
+	if (extractHttpStatusFromError(error) !== undefined) return message;
+	const failure = findTransportFailure(error, 0);
+	if (!failure) return message;
+
+	const url = failure.url ?? redactRequestUrl(rawRequestDump?.url);
+	const context = url ? `transport=${failure.code} url=${url}` : `transport=${failure.code}`;
+	return message.includes(context) ? message : `${message} (${context})`;
+}
+
 export async function finalizeErrorMessage(
 	error: unknown,
 	rawRequestDump: RawHttpRequestDump | undefined,
@@ -105,6 +181,7 @@ export async function finalizeErrorMessage(
 	if (isModelUnavailableError(message, error)) {
 		message = `${message}\n\n${formatModelUnavailableGuidance(rawRequestDump)}`;
 	}
+	message = appendTransportFailureContext(message, error, rawRequestDump);
 	return appendRawHttpRequestDumpFor400(message, error, rawRequestDump);
 }
 

package/src/utils/idle-iterator.ts

@@ -19,7 +19,7 @@ function normalizeIdleTimeoutMs(value: string | undefined, fallback: number): nu
 /**
  * Returns the idle timeout used for provider streaming transports.
  *
- * `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is accepted as a backward-compatible alias.
+ * `GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS` is honored first; `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is a backward-compatible alias.
  * Set `PI_STREAM_IDLE_TIMEOUT_MS=0` to disable the watchdog.
  *
  * Providers that legitimately stream much slower than the global default can pass
@@ -27,17 +27,20 @@ function normalizeIdleTimeoutMs(value: string | undefined, fallback: number): nu
  * Caller options still take precedence; env overrides still trump the fallback.
  */
 export function getStreamIdleTimeoutMs(fallbackMs: number = DEFAULT_STREAM_IDLE_TIMEOUT_MS): number | undefined {
-	return normalizeIdleTimeoutMs($env.PI_STREAM_IDLE_TIMEOUT_MS ?? $env.PI_OPENAI_STREAM_IDLE_TIMEOUT_MS, fallbackMs);
+	return normalizeIdleTimeoutMs(
+		$env.GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS ?? $env.PI_STREAM_IDLE_TIMEOUT_MS ?? $env.PI_OPENAI_STREAM_IDLE_TIMEOUT_MS,
+		fallbackMs,
+	);
 }
 
 /**
  * Returns the idle timeout used for OpenAI-family streaming transports.
  *
- * Set `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS=0` to disable the watchdog.
+ * Honors `GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS` first (`PI_OPENAI_STREAM_IDLE_TIMEOUT_MS` is the legacy alias). Set `=0` to disable.
  */
 export function getOpenAIStreamIdleTimeoutMs(): number | undefined {
 	return normalizeIdleTimeoutMs(
-		$env.PI_OPENAI_STREAM_IDLE_TIMEOUT_MS ?? $env.PI_STREAM_IDLE_TIMEOUT_MS,
+		$env.GJC_OPENAI_STREAM_IDLE_TIMEOUT_MS ?? $env.PI_OPENAI_STREAM_IDLE_TIMEOUT_MS ?? $env.PI_STREAM_IDLE_TIMEOUT_MS,
 		DEFAULT_STREAM_IDLE_TIMEOUT_MS,
 	);
 }
@@ -173,8 +176,6 @@ export async function* iterateWithIdleTimeout<T>(
 			}
 		}
 
-		const nextResultPromise = withRacy(iterator.next());
-
 		const racers: Array<
 			Promise<
 				| { kind: "next"; result: IteratorResult<T> }
@@ -182,7 +183,7 @@ export async function* iterateWithIdleTimeout<T>(
 				| { kind: "timeout" }
 				| { kind: "abort" }
 			>
-		> = [nextResultPromise];
+		> = [];
 
 		let timer: NodeJS.Timeout | undefined;
 		let resolveTimeout: ((value: { kind: "timeout" }) => void) | undefined;
@@ -207,6 +208,13 @@ export async function* iterateWithIdleTimeout<T>(
 			racers.push(promise);
 		}
 
+		// Arm timeout/abort races before asking the source for its next item. A
+		// periodic keepalive iterator commonly registers its own timer inside
+		// `next()`; registering that first lets equal-deadline keepalives win every
+		// race and extend the idle window forever. Already-buffered items still
+		// settle as microtasks before a 0ms watchdog.
+		racers.unshift(withRacy(iterator.next()));
+
 		try {
 			const outcome = await Promise.race(racers);
 			if (outcome.kind === "abort") {