@gajae-code/ai 0.11.11 → 0.12.1

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,
@@ -44,7 +37,6 @@ import { AssistantMessageEventStream } from "../utils/event-stream";
 import { transportFailureFacts } from "../utils/fallback-transport";
 import { finalizeErrorMessage, type RawHttpRequestDump, rewriteCopilotError } from "../utils/http-inspector";
 import {
-	createWatchdog,
 	getOpenAIStreamIdleTimeoutMs,
 	getStreamFirstEventTimeoutMs,
 	iterateWithIdleTimeout,
@@ -159,7 +151,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 +162,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",
@@ -261,7 +264,6 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 		);
 		let rawRequestDump: RawHttpRequestDump | undefined;
 		const abortTracker = createAbortSourceTracker(options?.signal);
-		const firstEventTimeoutAbortError = new Error(OPENAI_RESPONSES_FIRST_EVENT_TIMEOUT_MESSAGE);
 		const { requestAbortController, requestSignal } = abortTracker;
 
 		try {
@@ -333,10 +335,8 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 			});
 			const firstEventFallbackMs =
 				model.provider === "alibaba-token-plan" ? ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MS : undefined;
-			const firstEventWatchdog = createWatchdog(
-				options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs, firstEventFallbackMs),
-				() => abortTracker.abortLocally(firstEventTimeoutAbortError),
-			);
+			const firstEventTimeoutMs =
+				options?.streamFirstEventTimeoutMs ?? getStreamFirstEventTimeoutMs(idleTimeoutMs, firstEventFallbackMs);
 			if (premiumRequestsTotal !== undefined) output.usage.premiumRequests = premiumRequestsTotal;
 			stream.push({ type: "start", partial: output });
 
@@ -344,9 +344,11 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 			await processResponsesStream(
 				iterateWithIdleTimeout(openaiStream, {
 					idleTimeoutMs,
-					watchdog: firstEventWatchdog,
+					firstItemTimeoutMs: firstEventTimeoutMs,
+					firstItemErrorMessage: OPENAI_RESPONSES_FIRST_EVENT_TIMEOUT_MESSAGE,
 					errorMessage: "OpenAI responses stream stalled while waiting for the next event",
 					onIdle: () => requestAbortController.abort(),
+					onFirstItemTimeout: () => requestAbortController.abort(),
 					abortSignal: options?.signal,
 					isProgressItem: isOpenAIResponsesProgressEvent,
 				}),
@@ -385,11 +387,11 @@ export const streamOpenAIResponses: StreamFunction<"openai-responses"> = (
 			stream.end();
 		} catch (error) {
 			for (const block of output.content) delete (block as { index?: number }).index;
-			const firstEventTimeoutError = abortTracker.getLocalAbortReason();
+			const localAbortReason = 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.errorStatus = extractHttpStatusFromError(localAbortReason ?? error);
+			output.transportFailure = transportFailureFacts(localAbortReason ?? error);
+			output.errorMessage = localAbortReason?.message ?? (await finalizeErrorMessage(error, rawRequestDump));
 			output.errorMessage = rewriteCopilotError(output.errorMessage, error, model.provider);
 			// Explicitly mark the poisoned-history rejection so the shared
 			// `invalid_prompt` contract is present even when the SDK error surfaces

package/src/providers/register-builtins.ts

@@ -10,6 +10,7 @@
  * lazy wrappers below), so this file IS the main streaming path's provider
  * loader: heavy SDKs stay out of the CLI startup parse graph.
  */
+
 import type {
 	Api,
 	AssistantMessage,
@@ -21,7 +22,13 @@ import type {
 } from "../types";
 import { type AbortSourceTracker, createAbortSourceTracker } from "../utils/abort";
 import { AssistantMessageEventStream as EventStreamImpl } from "../utils/event-stream";
-import { getStreamFirstEventTimeoutMs, getStreamIdleTimeoutMs, iterateWithIdleTimeout } from "../utils/idle-iterator";
+import { transportFailureFacts } from "../utils/fallback-transport";
+import {
+	FirstEventTimeoutError,
+	getStreamFirstEventTimeoutMs,
+	getStreamIdleTimeoutMs,
+	iterateWithIdleTimeout,
+} from "../utils/idle-iterator";
 import type { BedrockOptions } from "./amazon-bedrock";
 import type { AnthropicOptions } from "./anthropic";
 import type { AzureOpenAIResponsesOptions } from "./azure-openai-responses";
@@ -229,7 +236,8 @@ function forwardStream<TApi extends Api>(
 				errorMessage: LAZY_STREAM_IDLE_TIMEOUT_ERROR,
 				firstItemErrorMessage: LAZY_STREAM_FIRST_EVENT_TIMEOUT_ERROR,
 				onIdle: () => abortTracker.abortLocally(new Error(LAZY_STREAM_IDLE_TIMEOUT_ERROR)),
-				onFirstItemTimeout: () => abortTracker.abortLocally(new Error(LAZY_STREAM_FIRST_EVENT_TIMEOUT_ERROR)),
+				onFirstItemTimeout: () =>
+					abortTracker.abortLocally(new FirstEventTimeoutError(LAZY_STREAM_FIRST_EVENT_TIMEOUT_ERROR)),
 				abortSignal: options.signal,
 				// The synthetic `start` event is yielded immediately by every provider before
 				// the upstream model has emitted any tokens. Treating it as the first "real"
@@ -261,6 +269,7 @@ function createLazyLoadErrorMessage<TApi extends Api>(
 	error: unknown,
 	stopReason: Extract<AssistantMessage["stopReason"], "aborted" | "error"> = "error",
 ): AssistantMessage {
+	const transportFailure = transportFailureFacts(error);
 	return {
 		role: "assistant",
 		content: [],
@@ -278,6 +287,7 @@ function createLazyLoadErrorMessage<TApi extends Api>(
 		stopReason,
 		errorMessage:
 			stopReason === "aborted" ? "Request was aborted" : error instanceof Error ? error.message : String(error),
+		...(transportFailure ? { transportFailure } : {}),
 		timestamp: Date.now(),
 	};
 }

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,
@@ -31,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;
 

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/fallback-transport.ts

@@ -5,6 +5,9 @@ export interface FallbackTrigger {
 	retryAfterMs?: number;
 }
 
+/** Stable code for streams that time out before producing semantic progress. */
+export const STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE = "stream_first_event_timeout";
+
 export type TransportHeaders = Headers | Record<string, string | undefined>;
 
 /**
@@ -185,7 +188,8 @@ export function transportFailureFacts(
 		!isQuotaCode(normalizedCode) &&
 		!isAuthCode(normalizedCode) &&
 		!isRateLimitCode(normalizedCode) &&
-		!isContextOverflowCode(normalizedCode)
+		!isContextOverflowCode(normalizedCode) &&
+		normalizedCode !== STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE
 	) {
 		return undefined;
 	}
@@ -256,14 +260,17 @@ export function classifyFallbackTrigger(
 		parseRetryAfterMilliseconds(headers?.get("retry-after-ms") ?? null) ??
 		parseRetryAfterSeconds(headers?.get("retry-after") ?? null);
 	const code = (facts.openaiErrorCode ?? facts.anthropicErrorType ?? facts.providerCode)?.toLowerCase();
-	const triggerClass: FallbackTriggerClass = isQuotaCode(code)
-		? "quota"
-		: facts.status === 401 || facts.status === 403 || isAuthCode(code)
-			? "auth"
-			: facts.status === 429 || isRateLimitCode(code)
-				? "rate_limit"
-				: facts.status !== undefined && facts.status >= 500 && facts.status <= 599
-					? "server"
-					: "other";
+	const triggerClass: FallbackTriggerClass =
+		code === STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE
+			? "server"
+			: isQuotaCode(code)
+				? "quota"
+				: facts.status === 401 || facts.status === 403 || isAuthCode(code)
+					? "auth"
+					: facts.status === 429 || isRateLimitCode(code)
+						? "rate_limit"
+						: facts.status !== undefined && facts.status >= 500 && facts.status <= 599
+							? "server"
+							: "other";
 	return retryAfterMs === undefined ? { class: triggerClass } : { class: triggerClass, retryAfterMs };
 }

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

@@ -1,3 +1,4 @@
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { APP_NAME, extractHttpStatusFromError, getLogsDir } from "@gajae-code/utils";
 import { isCopilotTransientModelError } from "./retry.js";
@@ -26,6 +27,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
@@ -66,6 +95,49 @@ export function formatModelUnavailableGuidance(dump: RawHttpRequestDump | undefi
 	].join("\n");
 }
 
+/**
+ * Cap on retained HTTP 400 request dumps.
+ *
+ * Each dump carries the full sanitized request body, so they are large: a
+ * developer machine accumulated 27,249 files totalling 7.0 GB, averaging 264 KB
+ * each, because nothing ever removed them. The rotating application log already
+ * bounds itself (`maxSize: 10m`, `maxFiles: 5`); these diagnostics get the same
+ * treatment so the newest failures stay available without unbounded growth.
+ */
+const MAX_RETAINED_DUMPS = 50;
+
+/** Directory holding the retained HTTP 400 dumps. */
+export function httpRequestDumpDir(): string {
+	return path.join(getLogsDir(), "http-400-requests");
+}
+
+/**
+ * Drop the oldest dumps beyond the cap. Best-effort: diagnostics must never turn
+ * a request failure into a second failure, so every step swallows its error.
+ *
+ * File names are `${Date.now()}-${hash}.json`, so a lexical sort is chronological
+ * for the millisecond timestamps this writer produces.
+ */
+export async function pruneHttpRequestDumps(dir: string = httpRequestDumpDir()): Promise<number> {
+	const entries = await fs.readdir(dir).catch(() => undefined);
+	if (!entries) return 0;
+
+	const dumps = entries.filter(name => name.endsWith(".json")).sort();
+	if (dumps.length <= MAX_RETAINED_DUMPS) return 0;
+
+	let removed = 0;
+	for (const name of dumps.slice(0, dumps.length - MAX_RETAINED_DUMPS)) {
+		if (
+			await fs.rm(path.join(dir, name), { force: true }).then(
+				() => true,
+				() => false,
+			)
+		)
+			removed++;
+	}
+	return removed;
+}
+
 export async function appendRawHttpRequestDumpFor400(
 	message: string,
 	error: unknown,
@@ -77,10 +149,12 @@ export async function appendRawHttpRequestDumpFor400(
 
 	const sanitizedDump = sanitizeDump(dump);
 	const fileName = `${Date.now()}-${Bun.hash(JSON.stringify(sanitizedDump)).toString(36)}.json`;
-	const filePath = path.join(getLogsDir(), "http-400-requests", fileName);
+	const dumpDir = httpRequestDumpDir();
+	const filePath = path.join(dumpDir, fileName);
 
 	try {
 		await Bun.write(filePath, `${JSON.stringify(sanitizedDump, null, 2)}\n`);
+		await pruneHttpRequestDumps(dumpDir);
 		return `${message}\nraw-http-request=${filePath}\n${RAW_HTTP_REQUEST_PRIVACY_NOTE}`;
 	} catch (writeError) {
 		const writeMessage = writeError instanceof Error ? writeError.message : String(writeError);
@@ -88,6 +162,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 +227,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

@@ -1,4 +1,5 @@
 import { $env } from "@gajae-code/utils";
+import { STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE } from "./fallback-transport";
 
 const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 120_000;
 const DEFAULT_STREAM_FIRST_EVENT_TIMEOUT_MS = 100_000;
@@ -66,6 +67,14 @@ export function getStreamFirstEventTimeoutMs(
 }
 
 export type Watchdog = NodeJS.Timeout | undefined;
+export class FirstEventTimeoutError extends Error {
+	readonly providerCode = STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE;
+
+	constructor(message: string) {
+		super(message);
+		this.name = "FirstEventTimeoutError";
+	}
+}
 
 const dummyWatchdog = setTimeout(() => {}, 1);
 clearTimeout(dummyWatchdog);
@@ -228,9 +237,9 @@ export async function* iterateWithIdleTimeout<T>(
 					options.onFirstItemTimeout?.();
 				}
 				closeIterator();
-				throw new Error(
-					!awaitingFirstItem ? options.errorMessage : (options.firstItemErrorMessage ?? options.errorMessage),
-				);
+				throw awaitingFirstItem
+					? new FirstEventTimeoutError(options.firstItemErrorMessage ?? options.errorMessage)
+					: new Error(options.errorMessage);
 			}
 			if (outcome.kind === "error") {
 				throw outcome.error;

package/src/utils/oauth/bizrouter.ts

@@ -0,0 +1,15 @@
+/** BizRouter login flow (API key paste, validated via /v1/models). */
+import { createApiKeyLogin } from "./api-key-login";
+
+export const loginBizRouter = createApiKeyLogin({
+	providerLabel: "BizRouter",
+	authUrl: "https://bizrouter.ai/settings/keys",
+	instructions: "Create or copy your BizRouter API key",
+	promptMessage: "Paste your BizRouter API key",
+	placeholder: "sk-br-v1-...",
+	validation: {
+		kind: "models-endpoint",
+		provider: "BizRouter",
+		modelsUrl: "https://api.bizrouter.ai/v1/models",
+	},
+});

package/src/utils/oauth/index.ts

@@ -240,6 +240,11 @@ const builtInOAuthProviders: OAuthProviderInfo[] = [
 		name: "ZenMux",
 		available: true,
 	},
+	{
+		id: "bizrouter",
+		name: "BizRouter",
+		available: true,
+	},
 	{
 		id: "opengateway",
 		name: "OpenGateway by Sionic AI",
@@ -391,6 +396,7 @@ export async function refreshOAuthToken(
 		case "vercel-ai-gateway":
 		case "qwen-portal":
 		case "zenmux":
+		case "bizrouter":
 		case "opengateway":
 		case "vllm":
 			// API keys / static bearer tokens don't expire, return as-is

package/src/utils/oauth/kimi.ts

@@ -7,7 +7,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { scheduler } from "node:timers/promises";
-import { $env, getAgentDir, isEnoent } from "@gajae-code/utils";
+import { $pickCredentialEnv, getAgentDir, isEnoent } from "@gajae-code/utils";
 import packageJson from "../../../package.json" with { type: "json" };
 import type { OAuthController, OAuthCredentials } from "./types";
 
@@ -38,8 +38,23 @@ interface TokenResponse {
 	interval?: number;
 }
 
+/**
+ * OAuth host for the device flow, from trusted environment sources only.
+ *
+ * This host receives the device-authorization request, the authorization-code
+ * exchange, and the refresh call that carries the existing refresh token, so
+ * whatever can set it can collect the user's Kimi credentials. `$env` merges the
+ * caller's `cwd/.env`, so reading it there would let repository content redirect
+ * the login flow. Resolve it the same way the credentials themselves are:
+ * launching shell plus GJC/user-owned `.env` files, never the project `.env`.
+ */
 function resolveOAuthHost(): string {
-	return $env.KIMI_CODE_OAUTH_HOST || $env.KIMI_OAUTH_HOST || DEFAULT_OAUTH_HOST;
+	return $pickCredentialEnv("KIMI_CODE_OAUTH_HOST", "KIMI_OAUTH_HOST") || DEFAULT_OAUTH_HOST;
+}
+
+/** Test seam: the OAuth host as resolved from trusted env. */
+export function resolveKimiOAuthHostForTest(): string {
+	return resolveOAuthHost();
 }
 
 function formatDeviceModel(system: string, release: string, arch: string): string {

package/src/utils/oauth/perplexity.ts

@@ -186,13 +186,32 @@ async function httpEmailLogin(ctrl: OAuthController): Promise<OAuthCredentials>
  *
  * No browser/manual token paste fallback is used.
  */
+/**
+ * Whether the operator disabled borrowing a token from the native macOS app.
+ *
+ * `GJC_AUTH_NO_BORROW` is the documented name; `PI_AUTH_NO_BORROW` is the legacy
+ * one that was the only name actually read.
+ */
+function authBorrowDisabled(): boolean {
+	return Boolean($env.GJC_AUTH_NO_BORROW || $env.PI_AUTH_NO_BORROW);
+}
+
+/** Test seam: the resolved native-app borrowing opt-out. */
+export function authBorrowDisabledForTest(): boolean {
+	return authBorrowDisabled();
+}
+
 export async function loginPerplexity(ctrl: OAuthController): Promise<OAuthCredentials> {
 	if (!ctrl.onPrompt) {
 		throw new Error("Perplexity login requires onPrompt callback");
 	}
 
-	// Path 1: Native macOS app JWT (skip if PI_AUTH_NO_BORROW=1)
-	if (!$env.PI_AUTH_NO_BORROW) {
+	// Path 1: Native macOS app JWT, skipped when the operator opts out.
+	//
+	// Presence-based on purpose: this is a privacy opt-out, so any set value must
+	// disable borrowing. A boolean contract would let `GJC_AUTH_NO_BORROW=0`
+	// silently re-enable reading a token out of another application.
+	if (!authBorrowDisabled()) {
 		ctrl.onProgress?.("Checking for Perplexity desktop app...");
 		const nativeJwt = await extractFromNativeApp();
 		if (nativeJwt) {

package/src/utils/oauth/types.ts

@@ -11,6 +11,7 @@ export type OAuthCredentials = {
 export type OAuthProvider =
 	| "alibaba-token-plan"
 	| "anthropic"
+	| "bizrouter"
 	| "cerebras"
 	| "cloudflare-ai-gateway"
 	| "cursor"