@vib-rato/ai 0.16.0

package/src/utils/oauth/xiaomi.ts

@@ -0,0 +1,199 @@
+/**
+ * Xiaomi MiMo login flow.
+ *
+ * Xiaomi MiMo provides OpenAI-compatible models via
+ * https://api.xiaomimimo.com/v1.
+ *
+ * Standard Xiaomi login opens the pay-as-you-go API key console. Token Plan
+ * login opens plan management so users copy the regional `tp-...` key.
+ */
+
+import type { FetchImpl } from "../../types";
+import type { OAuthController } from "./types";
+
+const PROVIDER_ID = "xiaomi";
+const PROVIDER_NAME = "Xiaomi MiMo";
+const STANDARD_AUTH_URL = "https://platform.xiaomimimo.com/#/console/api-keys";
+const TOKEN_PLAN_AUTH_URL = "https://platform.xiaomimimo.com/console/plan-manage";
+const STANDARD_API_BASE_URL = "https://api.xiaomimimo.com/v1";
+const TOKEN_PLAN_KEY_PREFIX = "tp-";
+const STANDARD_VALIDATION_MODEL = "mimo-v2-flash";
+const TOKEN_PLAN_VALIDATION_MODEL = "mimo-v2.5";
+const TOKEN_PLAN_SGP_API_BASE_URL = "https://token-plan-sgp.xiaomimimo.com/v1";
+const TOKEN_PLAN_AMS_API_BASE_URL = "https://token-plan-ams.xiaomimimo.com/v1";
+const TOKEN_PLAN_CN_API_BASE_URL = "https://token-plan-cn.xiaomimimo.com/v1";
+
+/** Region codes accepted by the Xiaomi Token Plan login flow. */
+export type XiaomiTokenPlanRegion = "sgp" | "ams" | "cn";
+
+type XiaomiValidationEndpoint = {
+	baseUrl: string;
+	model: string;
+};
+
+const TOKEN_PLAN_VALIDATION_ENDPOINTS: Record<XiaomiTokenPlanRegion, XiaomiValidationEndpoint> = {
+	sgp: { baseUrl: TOKEN_PLAN_SGP_API_BASE_URL, model: TOKEN_PLAN_VALIDATION_MODEL },
+	ams: { baseUrl: TOKEN_PLAN_AMS_API_BASE_URL, model: TOKEN_PLAN_VALIDATION_MODEL },
+	cn: { baseUrl: TOKEN_PLAN_CN_API_BASE_URL, model: TOKEN_PLAN_VALIDATION_MODEL },
+};
+
+const TOKEN_PLAN_REGION_NAMES: Record<XiaomiTokenPlanRegion, string> = {
+	sgp: "Singapore",
+	ams: "Europe",
+	cn: "China",
+};
+
+function isTokenPlanKey(apiKey: string): boolean {
+	return apiKey.startsWith(TOKEN_PLAN_KEY_PREFIX);
+}
+
+const VALIDATION_TIMEOUT_MS = 15_000;
+
+async function validateXiaomiApiKey(
+	apiKey: string,
+	tokenPlanRegion: XiaomiTokenPlanRegion | undefined,
+	signal?: AbortSignal,
+	fetchOverride?: FetchImpl,
+): Promise<void> {
+	const fetchImpl = fetchOverride ?? fetch;
+	// Region-specific Token Plan logins must validate against the selected
+	// cluster. Generic Xiaomi login keeps the historical SGP → AMS → CN fallback.
+	const endpoints = tokenPlanRegion
+		? [TOKEN_PLAN_VALIDATION_ENDPOINTS[tokenPlanRegion]]
+		: isTokenPlanKey(apiKey)
+			? [
+					TOKEN_PLAN_VALIDATION_ENDPOINTS.sgp,
+					TOKEN_PLAN_VALIDATION_ENDPOINTS.ams,
+					TOKEN_PLAN_VALIDATION_ENDPOINTS.cn,
+				]
+			: [{ baseUrl: STANDARD_API_BASE_URL, model: STANDARD_VALIDATION_MODEL }];
+
+	let lastError: Error | null = null;
+
+	for (const ep of endpoints) {
+		// Fresh timeout per endpoint so SGP→AMS fallback works after a regional
+		// timeout: a shared AbortSignal.timeout would stay aborted and instantly
+		// abort the AMS fetch.
+		const timeoutSignal = AbortSignal.timeout(VALIDATION_TIMEOUT_MS);
+		const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+		try {
+			const response = await fetchImpl(`${ep.baseUrl}/chat/completions`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					Authorization: `Bearer ${apiKey}`,
+				},
+				body: JSON.stringify({
+					model: ep.model,
+					max_tokens: 1,
+					messages: [{ role: "user", content: "ping" }],
+				}),
+				signal: requestSignal,
+			});
+
+			if (response.ok) {
+				return;
+			}
+
+			// 401 means this endpoint didn't accept the key; try the next one
+			if (response.status === 401) {
+				let details = "";
+				try {
+					details = (await response.text()).trim();
+				} catch {
+					// ignore body parse errors, status is enough
+				}
+				lastError = new Error(
+					details
+						? `${PROVIDER_NAME} API key validation failed (${response.status}): ${details}`
+						: `${PROVIDER_NAME} API key validation failed (${response.status})`,
+				);
+				continue;
+			}
+
+			// Non-auth errors are real failures
+			let details = "";
+			try {
+				details = (await response.text()).trim();
+			} catch {
+				// ignore body parse errors, status is enough
+			}
+			const message = details
+				? `${PROVIDER_NAME} API key validation failed (${response.status}): ${details}`
+				: `${PROVIDER_NAME} API key validation failed (${response.status})`;
+			throw new Error(message);
+		} catch (e) {
+			// Only re-throw AbortError when the caller explicitly cancelled.
+			// Timeout aborts (from AbortSignal.timeout) should fall through to
+			// the next endpoint so SGP→AMS fallback works during regional outages.
+			if (e instanceof DOMException && e.name === "AbortError" && signal?.aborted) {
+				throw e;
+			}
+			lastError = e instanceof Error ? e : new Error(String(e));
+		}
+	}
+	throw lastError ?? new Error(`${PROVIDER_NAME} API key validation failed`);
+}
+
+/**
+ * Login to Xiaomi MiMo.
+ *
+ * Opens browser to API keys page, prompts user to paste their API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export async function loginXiaomi(options: OAuthController): Promise<string> {
+	const fetchImpl = options.fetch ?? fetch;
+	if (!options.onPrompt) {
+		throw new Error(`${PROVIDER_NAME} login requires onPrompt callback`);
+	}
+	options.onAuth?.({
+		url: STANDARD_AUTH_URL,
+		instructions: "Copy your API key from the Xiaomi MiMo console",
+	});
+	const apiKey = await options.onPrompt({
+		message: "Paste your Xiaomi API key (sk-... or token-plan tp-...)",
+		placeholder: "sk-... or tp-...",
+	});
+	if (options.signal?.aborted) {
+		throw new Error("Login cancelled");
+	}
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new Error("API key is required");
+	}
+
+	options.onProgress?.(`Validating ${PROVIDER_ID} API key...`);
+	await validateXiaomiApiKey(trimmed, undefined, options.signal, fetchImpl);
+	return trimmed;
+}
+
+/**
+ * Login to a regional Xiaomi Token Plan endpoint.
+ *
+ * Prompts for a token-plan API key and validates it against the selected region.
+ */
+export async function loginXiaomiTokenPlan(options: OAuthController, region: XiaomiTokenPlanRegion): Promise<string> {
+	const fetchImpl = options.fetch ?? fetch;
+	if (!options.onPrompt) {
+		throw new Error(`Xiaomi Token Plan (${TOKEN_PLAN_REGION_NAMES[region]}) login requires onPrompt callback`);
+	}
+	options.onAuth?.({
+		url: TOKEN_PLAN_AUTH_URL,
+		instructions: `Copy your token-plan API key for the ${TOKEN_PLAN_REGION_NAMES[region]} region`,
+	});
+	const apiKey = await options.onPrompt({
+		message: `Paste your Xiaomi Token Plan ${TOKEN_PLAN_REGION_NAMES[region]} API key (tp-...)`,
+		placeholder: "tp-...",
+	});
+	if (options.signal?.aborted) {
+		throw new Error("Login cancelled");
+	}
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new Error("API key is required");
+	}
+
+	options.onProgress?.(`Validating Xiaomi Token Plan (${TOKEN_PLAN_REGION_NAMES[region]}) API key...`);
+	await validateXiaomiApiKey(trimmed, region, options.signal, fetchImpl);
+	return trimmed;
+}

package/src/utils/oauth/zai.ts

@@ -0,0 +1,60 @@
+/**
+ * Z.AI login flow.
+ *
+ * Z.AI is a platform that provides access to GLM models through an OpenAI-compatible API.
+ * API docs: https://docs.z.ai/guides/overview/quick-start
+ *
+ * This is not OAuth - it's a simple API key flow:
+ * 1. User gets their API key from https://z.ai/settings/api-keys
+ * 2. User pastes the API key into the CLI
+ */
+
+import { validateOpenAICompatibleApiKey } from "./api-key-validation";
+import type { OAuthController } from "./types";
+
+const AUTH_URL = "https://z.ai/manage-apikey/apikey-list";
+const API_BASE_URL = "https://api.z.ai/api/coding/paas/v4";
+const VALIDATION_MODEL = "glm-4.7";
+
+/**
+ * Login to Z.AI.
+ *
+ * Opens browser to API keys page, prompts user to paste their API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export async function loginZai(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new Error("Z.AI login requires onPrompt callback");
+	}
+
+	// Open browser to API keys page
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: "Copy your API key from the dashboard",
+	});
+
+	// Prompt user to paste their API key
+	const apiKey = await options.onPrompt({
+		message: "Paste your Z.AI API key",
+		placeholder: "sk-...",
+	});
+
+	if (options.signal?.aborted) {
+		throw new Error("Login cancelled");
+	}
+
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new Error("API key is required");
+	}
+
+	options.onProgress?.("Validating API key...");
+	await validateOpenAICompatibleApiKey({
+		provider: "Z.AI",
+		apiKey: trimmed,
+		baseUrl: API_BASE_URL,
+		model: VALIDATION_MODEL,
+		signal: options.signal,
+	});
+	return trimmed;
+}

package/src/utils/oauth/zenmux.ts

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

package/src/utils/overflow.ts

@@ -0,0 +1,275 @@
+import type { AssistantMessage } from "../types";
+import type { TransportFailureFacts } from "./fallback-transport";
+
+/**
+ * Regex patterns to detect context overflow errors from different providers.
+ *
+ * These patterns match error messages returned when the input exceeds
+ * the model's context window.
+ *
+ * Provider-specific patterns (with example error messages):
+ *
+ * - Anthropic: "prompt is too long: 213462 tokens > 200000 maximum"
+ * - OpenAI: "Your input exceeds the context window of this model"
+ * - Google: "The input token count (1196265) exceeds the maximum number of tokens allowed (1048575)"
+ * - xAI: "This model's maximum prompt length is 131072 but the request contains 537812 tokens"
+ * - Groq: "Please reduce the length of the messages or completion"
+ * - OpenRouter: "This endpoint's maximum context length is X tokens. However, you requested about Y tokens"
+ * - llama.cpp: "the request exceeds the available context size, try increasing it"
+ * - LM Studio: "tokens to keep from the initial prompt is greater than the context length"
+ * - GitHub Copilot: "prompt token count of X exceeds the limit of Y"
+ * - MiniMax: "invalid params, context window exceeds limit"
+ * - Kimi For Coding: "Your request exceeded model token limit: X (requested: Y)"
+ * - Anthropic 413: "request_too_large" / "Request exceeds the maximum size" (payload too large)
+ * - HTTP 413 variants: "Payload Too Large" / "Request Entity Too Large"
+ * - z.ai / GLM: Returns finish_reason: "model_context_window_exceeded" mapped to error message
+ * - z.ai: Does NOT error, accepts overflow silently - handled via usage.input > contextWindow
+ * - Ollama: Silently truncates input - not detectable via error message
+ */
+const OVERFLOW_PATTERNS = [
+	/prompt is too long/i, // Anthropic
+	/input is too long for requested model/i, // Amazon Bedrock
+	/exceeds the context window/i, // OpenAI (Completions & Responses API)
+	/input token count.*exceeds the maximum/i, // Google (Gemini)
+	/maximum prompt length is \d+/i, // xAI (Grok)
+	/reduce the length of the messages/i, // Groq
+	/maximum context length is \d+ tokens/i, // OpenRouter (all backends)
+	/exceeds the limit of \d+/i, // GitHub Copilot
+	/exceeds the available context size/i, // llama.cpp server
+	/requested tokens?.*exceed.*context (window|length|size)/i, // llama.cpp / OpenAI-compatible local servers
+	/context (window|length|size).*(exceeded|overflow|too small)/i, // Generic local server variants
+	/(prompt|input).*(too long|too large).*(context|n_ctx)/i, // llama.cpp phrasing variants
+	/requested tokens?.*(exceeds?|greater than).*(n_ctx|context)/i, // llama.cpp n_ctx variants
+	/greater than the context length/i, // LM Studio
+	/context window exceeds limit/i, // MiniMax
+	/exceeded model token limit/i, // Kimi For Coding
+	/context[_ ]length[_ ]exceeded/i, // Generic fallback
+	/too many tokens/i, // Generic fallback
+	/token limit exceeded/i, // Generic fallback
+	/request_too_large/i, // Anthropic 413 (request body too large)
+	/request exceeds the maximum size/i, // Anthropic 413 variant
+	/payload too large/i, // Generic HTTP 413 variant
+	/entity too large/i, // Generic HTTP 413 variant
+	/\b413\b.*\b(request|payload|entity)\b.*\btoo large\b/i, // "413 Request Entity Too Large" variants
+	/model_context_window_exceeded/i, // z.ai non-standard finish_reason surfaced as error text
+];
+/**
+ * Threshold below which a "successful" (stopReason "stop") response with empty
+ * content is considered anomalous. Some proxies (notably LiteLLM) return an
+ * empty `choices[0].message.content` with a near-zero `usage` (e.g. input: 1,
+ * output: 1) when the upstream model context window is exceeded, instead of
+ * surfacing a proper error. The total token count for such a response is well
+ * below any realistic turn, so we treat it as a proxy-level overflow signal.
+ */
+const EMPTY_RESPONSE_USAGE_THRESHOLD = 5;
+/**
+ * Check if an assistant message represents a context overflow error.
+ *
+ * This handles three cases:
+ * 1. Error-based overflow: Most providers return stopReason "error" with a
+ *    specific error message pattern.
+ * 2. Silent overflow: Some providers accept overflow requests and return
+ *    successfully. For these, we check if usage.input exceeds the context window.
+ * 3. Proxy-level overflow: Some proxies (e.g. LiteLLM) return a "successful"
+ *    response with empty content and a fabricated near-zero usage when the
+ *    upstream model's context window is exceeded.
+ *
+ * ## Reliability by Provider
+ *
+ * **Reliable detection (returns error with detectable message):**
+ * - Anthropic: "prompt is too long: X tokens > Y maximum"
+ * - OpenAI (Completions & Responses): "exceeds the context window"
+ * - Google Gemini: "input token count exceeds the maximum"
+ * - xAI (Grok): "maximum prompt length is X but request contains Y"
+ * - Groq: "reduce the length of the messages"
+ * - Cerebras: 400/413 status code (no body)
+ * - Mistral: 400/413 status code (no body)
+ * - HTTP 413 payload/entity-too-large variants
+ * - OpenRouter (all backends): "maximum context length is X tokens"
+ * - llama.cpp: "exceeds the available context size"
+ * - LM Studio: "greater than the context length"
+ * - Kimi For Coding: "exceeded model token limit: X (requested: Y)"
+ * - Anthropic 413: "request_too_large" (request body exceeds size limit)
+ * - HTTP 413: "Payload Too Large" / "Request Entity Too Large"
+ *
+ * **Unreliable detection:**
+ * - z.ai: Sometimes accepts overflow silently (detectable via usage.input > contextWindow),
+ *   sometimes returns rate limit errors. Pass contextWindow param to detect silent overflow.
+ * - Ollama: Silently truncates input without error. Cannot be detected via this function.
+ * - LiteLLM proxy: Returns a "successful" response with empty content and a
+ *   fabricated near-zero usage (e.g. input: 1, output: 1) when the upstream
+ *   model's context window is exceeded. Detected via Case 3 (empty content +
+ *   anomalously low usage). Note: the LiteLLM proxy's context limit may differ
+ *   from the underlying model's advertised contextWindow (e.g. configured via
+ *   `model_info.max_tokens` in LiteLLM's config.yaml), so Case 2 (which compares
+ *   usage.input against contextWindow) may not catch it.
+ *   The response will have usage.input < expected, but we don't know the expected value.
+ *
+ * ## Custom Providers
+ *
+ * If you've added custom models via settings.json, this function may not detect
+ * overflow errors from those providers. To add support:
+ *
+ * 1. Send a request that exceeds the model's context window
+ * 2. Check the errorMessage in the response
+ * 3. Create a regex pattern that matches the error
+ * 4. The pattern should be added to OVERFLOW_PATTERNS in this file, or
+ *    check the errorMessage yourself before calling this function
+ *
+ * @param message - The assistant message to check
+ * @param contextWindow - Optional context window size for detecting silent overflow (z.ai)
+ * @returns true if the message indicates a context overflow
+ */
+/**
+ * Authoritatively classify a context overflow from the assistant result and
+ * normalized transport facts. Typed facts take precedence over provider prose:
+ * an explicit non-overflow transport failure cannot be upgraded by hostile or
+ * misleading error text.
+ */
+const OVERFLOW_PROVIDER_CODES = new Set(["context_length_exceeded", "request_too_large"]);
+/**
+ * Codes that name a specific non-overflow *cause*. These are authoritative and
+ * can never be upgraded by error prose. Generic HTTP envelope types belong in
+ * {@link GENERIC_ENVELOPE_PROVIDER_CODES} instead.
+ */
+const NON_OVERFLOW_PROVIDER_CODES = new Set([
+	"authentication_error",
+	"invalid_api_key",
+	"invalid_token",
+	"token_expired",
+	"unauthorized",
+	"forbidden",
+	"insufficient_quota",
+	"quota_exceeded",
+	"quota_exhausted",
+	"usage_limit_reached",
+	"usage_not_included",
+	"out_of_credits",
+	"rate_limit",
+	"rate_limit_error",
+	"rate_limit_exceeded",
+	"too_many_requests",
+	"empty_response",
+]);
+
+function transportCodes(transportFailure: TransportFailureFacts | undefined): string[] {
+	return [transportFailure?.openaiErrorCode, transportFailure?.anthropicErrorType, transportFailure?.providerCode]
+		.filter((code): code is string => typeof code === "string")
+		.map(code => code.toLowerCase());
+}
+
+function hasTypedNonOverflowCode(transportFailure: TransportFailureFacts | undefined): boolean {
+	return transportCodes(transportFailure).some(code => NON_OVERFLOW_PROVIDER_CODES.has(code));
+}
+
+/**
+ * Generic envelope codes that name the HTTP error *category*, not its cause.
+ *
+ * Anthropic reports context overflow through this envelope:
+ *
+ *   {"type":"error","error":{"type":"invalid_request_error",
+ *    "message":"prompt is too long: 1158066 tokens > 1000000 maximum"}}
+ *
+ * Treating the envelope as an authoritative non-overflow cause vetoed the
+ * overflow classification, so auto-compaction never ran and the session died on
+ * the very overflow it was supposed to absorb.
+ *
+ * Unlike {@link NON_OVERFLOW_PROVIDER_CODES} (auth, quota, rate limit), this
+ * envelope names no cause, so it must not veto an overflow the provider stated
+ * quantitatively. It still vetoes free-form prose: only the self-verifying
+ * measured form below can override it.
+ */
+const GENERIC_ENVELOPE_PROVIDER_CODES = new Set(["invalid_request_error"]);
+
+/**
+ * Anthropic's measured overflow report: `<used> tokens > <limit> maximum`.
+ *
+ * Deliberately far narrower than {@link OVERFLOW_PATTERNS}. Those patterns
+ * include loose prose (`too many tokens`, `token limit exceeded`) that a tool
+ * result or a model-authored string can trivially contain, so they must never
+ * be able to flip a typed transport classification. This form carries its own
+ * arithmetic proof and is verified below, so injected text cannot satisfy it
+ * without also asserting a real overage.
+ */
+const ANTHROPIC_MEASURED_OVERFLOW_PATTERN = /prompt is too long:\s*(\d+)\s*tokens?\s*>\s*(\d+)\s*maximum/i;
+
+/**
+ * True only for a provider-measured overflow that verifies against itself:
+ * the reported usage must actually exceed the reported maximum.
+ */
+function hasSelfVerifyingOverflowMeasurement(message: AssistantMessage): boolean {
+	if (message.stopReason !== "error") return false;
+	const errorMessage = message.errorMessage;
+	if (!errorMessage) return false;
+	const match = ANTHROPIC_MEASURED_OVERFLOW_PATTERN.exec(errorMessage);
+	if (!match) return false;
+	const used = Number(match[1]);
+	const maximum = Number(match[2]);
+	if (!Number.isFinite(used) || !Number.isFinite(maximum) || maximum <= 0) return false;
+	return used > maximum;
+}
+
+function isTypedNoBodyOverflow(
+	message: AssistantMessage,
+	transportFailure: TransportFailureFacts | undefined,
+): boolean {
+	if (transportFailure?.status !== 400 && transportFailure?.status !== 413) return false;
+	return !message.errorMessage || /\b4(00|13)\s*(status code)?\s*\(no body\)/i.test(message.errorMessage);
+}
+
+export function classifyContextOverflow(
+	message: AssistantMessage,
+	transportFailure?: TransportFailureFacts,
+	contextWindow?: number,
+): boolean {
+	if (transportFailure?.status === 429) return false;
+	const typedCodes = transportCodes(transportFailure);
+	if (typedCodes.some(code => OVERFLOW_PROVIDER_CODES.has(code))) return true;
+	// A specific non-overflow cause (auth, quota, rate limit) is authoritative
+	// and can never be upgraded by error prose.
+	if (hasTypedNonOverflowCode(transportFailure)) return false;
+	// A generic envelope (`invalid_request_error`) names no cause. It still
+	// vetoes free-form overflow prose, but must not veto a provider-measured,
+	// self-verifying overflow report — that is how Anthropic reports overflow.
+	if (
+		typedCodes.some(code => GENERIC_ENVELOPE_PROVIDER_CODES.has(code)) &&
+		!hasSelfVerifyingOverflowMeasurement(message)
+	) {
+		return false;
+	}
+	if (isTypedNoBodyOverflow(message, transportFailure)) return true;
+
+	const errorMessage = message.errorMessage;
+	if (message.stopReason === "error" && errorMessage) {
+		if (OVERFLOW_PATTERNS.some(pattern => pattern.test(errorMessage))) return true;
+		if (/\b4(00|13)\s*(status code)?\s*\(no body\)/i.test(errorMessage)) return true;
+	}
+
+	if (contextWindow) {
+		const inputTokens = message.usage.input + message.usage.cacheRead + message.usage.cacheWrite;
+		if (inputTokens > contextWindow) return true;
+	}
+
+	return (
+		message.stopReason === "stop" &&
+		message.content.length === 0 &&
+		message.usage.input + message.usage.output <= EMPTY_RESPONSE_USAGE_THRESHOLD
+	);
+}
+
+/**
+ * Check if an assistant message represents a context overflow error.
+ *
+ * Callers with normalized transport facts should use {@link classifyContextOverflow}
+ * so typed provider codes take precedence over error prose.
+ */
+export function isContextOverflow(message: AssistantMessage, contextWindow?: number): boolean {
+	return classifyContextOverflow(message, undefined, contextWindow);
+}
+
+/**
+ * Get the overflow patterns for testing purposes.
+ */
+export function getOverflowPatterns(): RegExp[] {
+	return [...OVERFLOW_PATTERNS];
+}

package/src/utils/parse-bind.ts

@@ -0,0 +1,81 @@
+/**
+ * Shared `host:port` parser used by the auth-broker and auth-gateway boot
+ * paths. Centralized so the two servers can't drift on what they accept (the
+ * gateway used to silently allow empty hostnames; this fixes it).
+ */
+import { isIP } from "node:net";
+
+export interface ParsedBind {
+	hostname: string;
+	port: number;
+}
+
+function parsePort(raw: string, bind: string): number {
+	if (!/^\d+$/.test(raw)) {
+		throw new Error(`Invalid bind '${bind}'; port must be an integer.`);
+	}
+	const port = Number.parseInt(raw, 10);
+	if (!Number.isFinite(port) || port < 0 || port > 65535) {
+		throw new Error(`Invalid bind '${bind}'; port out of range.`);
+	}
+	return port;
+}
+
+/**
+ * Parse a `host:port` (or bare `port`, which assumes loopback) string.
+ *
+ * Accepts:
+ *   - `"4000"`            → `127.0.0.1:4000`
+ *   - `"0.0.0.0:4000"`    → as written
+ *   - `"[::1]:4000"`      → as written (brackets retained, Bun handles them)
+ *
+ * Rejects:
+ *   - empty input
+ *   - empty hostname (`":4000"`)
+ *   - non-integer / out-of-range port
+ */
+export function parseBind(raw: string): ParsedBind {
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) {
+		throw new Error("Invalid bind; expected 'host:port' or 'port'.");
+	}
+	if (/^\d+$/.test(trimmed)) {
+		return { hostname: "127.0.0.1", port: parsePort(trimmed, raw) };
+	}
+	const lastColon = trimmed.lastIndexOf(":");
+	if (lastColon < 0) {
+		throw new Error(`Invalid bind '${raw}'; expected 'host:port' or 'port'.`);
+	}
+	const hostPart = trimmed.slice(0, lastColon);
+	const portPart = trimmed.slice(lastColon + 1);
+	if (hostPart.length === 0) {
+		throw new Error(`Invalid bind '${raw}'; host must not be empty.`);
+	}
+	return { hostname: hostPart, port: parsePort(portPart, raw) };
+}
+
+/** True for loopback-only hostnames the auth servers may bind without credentials. */
+export function isLoopbackHostname(hostname: string): boolean {
+	const normalized = hostname
+		.trim()
+		.toLowerCase()
+		.replace(/^\[|\]$/g, "");
+	if (normalized === "localhost" || normalized === "::1") return true;
+	// Strict numeric IPv4 loopback literals only: a bare prefix match would
+	// accept attacker-controlled names like `127.evil.example`, and short/hex
+	// IPv4 forms (`127.1`, `0x7f.1`) are rejected by the parser anyway.
+	return isIP(normalized) === 4 && normalized.split(".")[0] === "127";
+}
+
+/**
+ * Fail closed when an unauthenticated auth server (empty bearer token set)
+ * would bind a non-loopback address: that exposes credential operations to the
+ * network with no proof of possession.
+ */
+export function assertAuthenticatedOrLoopback(bind: ParsedBind, bearerTokenCount: number, serverName: string): void {
+	if (bearerTokenCount > 0) return;
+	if (isLoopbackHostname(bind.hostname)) return;
+	throw new Error(
+		`${serverName} refuses to bind ${bind.hostname}:${bind.port} without bearer tokens; unauthenticated mode is loopback-only.`,
+	);
+}

package/src/utils/provider-response.d.ts

@@ -0,0 +1,6 @@
+import type { Api, AttemptScopeRef, Model, ProviderResponseMetadata, StreamOptions } from "../types";
+export declare function normalizeProviderResponse(response: Response, requestId?: string | null, metadata?: Record<string, unknown>): ProviderResponseMetadata;
+export declare function notifyProviderResponse(options: {
+    onResponse?: StreamOptions["onResponse"];
+    attemptScope?: AttemptScopeRef;
+} | undefined, response: Response, model?: Model<Api>, requestId?: string | null, metadata?: Record<string, unknown>): Promise<void>;

package/src/utils/provider-response.ts

@@ -0,0 +1,30 @@
+import type { Api, AttemptScopeRef, Model, ProviderResponseMetadata, StreamOptions } from "../types";
+
+export function normalizeProviderResponse(
+	response: Response,
+	requestId?: string | null,
+	metadata?: Record<string, unknown>,
+): ProviderResponseMetadata {
+	const headers: Record<string, string> = {};
+	response.headers.forEach((value, key) => {
+		headers[key.toLowerCase()] = value;
+	});
+	const providerResponse: ProviderResponseMetadata = {
+		status: response.status,
+		headers,
+	};
+	if (requestId !== undefined) providerResponse.requestId = requestId;
+	if (metadata !== undefined) providerResponse.metadata = metadata;
+	return providerResponse;
+}
+
+export async function notifyProviderResponse(
+	options: { onResponse?: StreamOptions["onResponse"]; attemptScope?: AttemptScopeRef } | undefined,
+	response: Response,
+	model?: Model<Api>,
+	requestId?: string | null,
+	metadata?: Record<string, unknown>,
+): Promise<void> {
+	if (!options?.onResponse) return;
+	await options.onResponse(normalizeProviderResponse(response, requestId, metadata), model, options.attemptScope);
+}

package/src/utils/provider-safety-stop.ts

@@ -0,0 +1,8 @@
+/**
+ * Public provider safety-stop surface (issue #4777 review follow-up).
+ *
+ * First-party adapters mint terminal authority through the package-private
+ * adapter-internals module. Public consumers may only verify existing
+ * authority; message fields and structured refusal text never mint authority.
+ */
+export { isProviderSafetyStopAuthenticated } from "../adapter-internals/provider-safety-stop";