@vib-rato/ai 0.16.0

package/src/utils/fallback-transport.d.ts

@@ -0,0 +1,110 @@
+export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "unknown" | "other";
+/**
+ * Refinement of an `auth` trigger.
+ *
+ * The transport deliberately collapses HTTP 401 and 403 into a single `auth`
+ * class, but the two demand opposite handling: a credential problem may be
+ * recoverable by trying a different stored credential, whereas a plain
+ * `forbidden` is an authorization or configuration defect that rotation would
+ * only hide — it would cycle and block every otherwise-healthy credential.
+ *
+ * This is a refinement rather than a new {@link FallbackTriggerClass} member so
+ * every existing `trigger.class === "auth"` consumer keeps compiling and keeps
+ * its current behavior until it explicitly opts into the distinction.
+ */
+export type AuthDisposition = "credential" | "forbidden";
+export interface FallbackTrigger {
+    class: FallbackTriggerClass;
+    retryAfterMs?: number;
+    /** Present only when `class === "auth"`. */
+    authDisposition?: AuthDisposition;
+}
+/** Stable code for streams that time out before producing semantic progress. */
+export declare const STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE = "stream_first_event_timeout";
+/** Stable code for a nominally successful response with no content or token usage. */
+export declare const EMPTY_RESPONSE_PROVIDER_CODE = "empty_response";
+/**
+ * OpenAI's typed capacity-overload code. It arrives without an HTTP status —
+ * inside an HTTP 200 terminal Responses envelope or a Codex error event — so the
+ * code itself is the only structured evidence of the failure and must survive
+ * the existence gate below. It is always compared case-sensitively.
+ */
+export declare const SERVER_OVERLOADED_PROVIDER_CODE = "server_is_overloaded";
+export type TransportHeaders = Headers | Record<string, string | undefined>;
+/**
+ * Structured facts from an upstream HTTP or transport failure. Retry decisions
+ * must use these facts rather than provider- or application-owned error text.
+ *
+ * `headers` is always a plain record limited to the retained retry-signal
+ * entries: facts travel on persisted `AssistantMessage`s and through
+ * `structuredClone` snapshots (managed fallback attempt staging), so they must
+ * never carry a live `Headers` instance — cloning one throws `DataCloneError`
+ * ("The object can not be cloned.") and masks the real provider failure.
+ */
+export interface TransportFailureFacts {
+    kind: "transport";
+    status?: number;
+    /** Canonical provider error code used for fallback classification. */
+    providerCode?: string;
+    /** Anthropic's typed `error.type`, preserved separately at the transport boundary. */
+    anthropicErrorType?: string;
+    /** OpenAI's typed `error.code`, preserved separately at the transport boundary. */
+    openaiErrorCode?: string;
+    headers?: Record<string, string>;
+    /** Safe request-size observation for retry amplification policy. Never contains body content. */
+    requestBytes?: number;
+    /** Time spent waiting for the first semantic stream event on the failed request. */
+    firstEventElapsedMs?: number;
+    /** Configured first-event window before any bounded endpoint grace. */
+    firstEventTimeoutMs?: number;
+    /** Coarse endpoint class; deliberately excludes host, path, credentials, and query parameters. */
+    endpointClass?: "canonical" | "custom";
+    /** Provider-supplied ceiling for total attempts, including the initial request. */
+    retryMaxAttempts?: number;
+}
+/** Opaque per-invocation marker required by managed fallback transport calls. */
+export interface FallbackAttemptToken {
+    readonly modelKey: string;
+    readonly attemptId: string | number;
+}
+/**
+ * Marks a single outer fallback invocation. Accounting belongs to the caller;
+ * this token prevents managed transport calls from silently bypassing it.
+ */
+export declare function beginAttempt(modelKey: string, attemptId: string | number): FallbackAttemptToken;
+export declare function assertManagedAttempt(options: {
+    fallbackManaged?: boolean;
+    fallbackAttempt?: FallbackAttemptToken;
+} | undefined): void;
+/**
+ * Compatibility input for callers that have not yet wrapped their HTTP facts
+ * in the discriminated form. Only its structured fields are inspected.
+ */
+export interface FallbackTriggerInput {
+    status?: number;
+    providerCode?: string;
+    code?: string;
+    headers?: TransportHeaders;
+    response?: {
+        status?: number;
+        headers?: TransportHeaders;
+    };
+    error?: {
+        code?: string;
+        type?: string;
+    };
+}
+/** Extracts only explicit HTTP/transport metadata; it never parses error text. */
+export declare function transportFailureFacts(error: unknown, capturedResponse?: {
+    status?: number;
+    headers?: TransportHeaders;
+}): TransportFailureFacts | undefined;
+/** Classifies only typed upstream transport facts without consuming response bodies. */
+export declare function classifyFallbackTrigger(errorOrFacts: TransportFailureFacts | FallbackTriggerInput | unknown): FallbackTrigger;
+/**
+ * True when a failure is an `auth` failure that must NOT rotate credentials.
+ *
+ * Callers that mutate credential state on auth failures should consult this
+ * first so a plain `forbidden` cannot block otherwise-healthy credentials.
+ */
+export declare function isForbiddenAuthFailure(errorOrFacts: TransportFailureFacts | FallbackTriggerInput | unknown): boolean;

package/src/utils/fallback-transport.ts

@@ -0,0 +1,411 @@
+export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "unknown" | "other";
+
+/**
+ * Refinement of an `auth` trigger.
+ *
+ * The transport deliberately collapses HTTP 401 and 403 into a single `auth`
+ * class, but the two demand opposite handling: a credential problem may be
+ * recoverable by trying a different stored credential, whereas a plain
+ * `forbidden` is an authorization or configuration defect that rotation would
+ * only hide — it would cycle and block every otherwise-healthy credential.
+ *
+ * This is a refinement rather than a new {@link FallbackTriggerClass} member so
+ * every existing `trigger.class === "auth"` consumer keeps compiling and keeps
+ * its current behavior until it explicitly opts into the distinction.
+ */
+export type AuthDisposition = "credential" | "forbidden";
+
+export interface FallbackTrigger {
+	class: FallbackTriggerClass;
+	retryAfterMs?: number;
+	/** Present only when `class === "auth"`. */
+	authDisposition?: AuthDisposition;
+}
+
+/** Stable code for streams that time out before producing semantic progress. */
+export const STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE = "stream_first_event_timeout";
+/** Stable code for a nominally successful response with no content or token usage. */
+export const EMPTY_RESPONSE_PROVIDER_CODE = "empty_response";
+/**
+ * OpenAI's typed capacity-overload code. It arrives without an HTTP status —
+ * inside an HTTP 200 terminal Responses envelope or a Codex error event — so the
+ * code itself is the only structured evidence of the failure and must survive
+ * the existence gate below. It is always compared case-sensitively.
+ */
+export const SERVER_OVERLOADED_PROVIDER_CODE = "server_is_overloaded";
+
+export type TransportHeaders = Headers | Record<string, string | undefined>;
+
+/**
+ * Structured facts from an upstream HTTP or transport failure. Retry decisions
+ * must use these facts rather than provider- or application-owned error text.
+ *
+ * `headers` is always a plain record limited to the retained retry-signal
+ * entries: facts travel on persisted `AssistantMessage`s and through
+ * `structuredClone` snapshots (managed fallback attempt staging), so they must
+ * never carry a live `Headers` instance — cloning one throws `DataCloneError`
+ * ("The object can not be cloned.") and masks the real provider failure.
+ */
+export interface TransportFailureFacts {
+	kind: "transport";
+	status?: number;
+	/** Canonical provider error code used for fallback classification. */
+	providerCode?: string;
+	/** Anthropic's typed `error.type`, preserved separately at the transport boundary. */
+	anthropicErrorType?: string;
+	/** OpenAI's typed `error.code`, preserved separately at the transport boundary. */
+	openaiErrorCode?: string;
+	headers?: Record<string, string>;
+	/** Safe request-size observation for retry amplification policy. Never contains body content. */
+	requestBytes?: number;
+	/** Time spent waiting for the first semantic stream event on the failed request. */
+	firstEventElapsedMs?: number;
+	/** Configured first-event window before any bounded endpoint grace. */
+	firstEventTimeoutMs?: number;
+	/** Coarse endpoint class; deliberately excludes host, path, credentials, and query parameters. */
+	endpointClass?: "canonical" | "custom";
+	/** Provider-supplied ceiling for total attempts, including the initial request. */
+	retryMaxAttempts?: number;
+}
+
+/** Opaque per-invocation marker required by managed fallback transport calls. */
+export interface FallbackAttemptToken {
+	readonly modelKey: string;
+	readonly attemptId: string | number;
+}
+
+const issuedAttemptTokens = new WeakSet<object>();
+const consumedAttemptTokens = new WeakSet<object>();
+
+/**
+ * Marks a single outer fallback invocation. Accounting belongs to the caller;
+ * this token prevents managed transport calls from silently bypassing it.
+ */
+export function beginAttempt(modelKey: string, attemptId: string | number): FallbackAttemptToken {
+	const token = Object.freeze({ modelKey, attemptId });
+	issuedAttemptTokens.add(token);
+	return token;
+}
+
+export function assertManagedAttempt(
+	options: { fallbackManaged?: boolean; fallbackAttempt?: FallbackAttemptToken } | undefined,
+): void {
+	if (!options?.fallbackManaged) return;
+	const token = options.fallbackAttempt;
+	if (!token || !issuedAttemptTokens.has(token)) {
+		throw new Error("fallbackManaged transport invocation requires a token returned by beginAttempt()");
+	}
+	if (consumedAttemptTokens.has(token)) {
+		throw new Error("fallbackManaged transport invocation cannot reuse a beginAttempt() token");
+	}
+	consumedAttemptTokens.add(token);
+}
+
+/**
+ * Compatibility input for callers that have not yet wrapped their HTTP facts
+ * in the discriminated form. Only its structured fields are inspected.
+ */
+export interface FallbackTriggerInput {
+	status?: number;
+	providerCode?: string;
+	code?: string;
+	headers?: TransportHeaders;
+	response?: { status?: number; headers?: TransportHeaders };
+	error?: { code?: string; type?: string };
+}
+
+function isTransportHeaders(value: unknown): value is TransportHeaders {
+	try {
+		return value instanceof Headers || (!!value && typeof value === "object");
+	} catch {
+		return false;
+	}
+}
+
+function propertyOf(value: unknown, name: string): unknown {
+	if (!value || typeof value !== "object") return undefined;
+	try {
+		return Reflect.get(value, name);
+	} catch {
+		return undefined;
+	}
+}
+
+function finiteStatus(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function finiteNonNegativeInteger(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+
+function finitePositiveInteger(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+
+/** Retry-signal headers retained on transport facts; everything else is dropped. */
+const RETAINED_TRANSPORT_HEADERS = ["retry-after", "retry-after-ms"] as const;
+
+const RETAINED_TRANSPORT_HEADER_SET: ReadonlySet<string> = new Set(RETAINED_TRANSPORT_HEADERS);
+
+/**
+ * Reduce transport headers to the retained retry-signal entries in a plain
+ * record, so facts stay structured-cloneable and JSON-serializable and never
+ * persist arbitrary response headers into session files.
+ *
+ * Exception-safe by contract: inspection uses only `Headers.get()` results
+ * that are primitive strings or own data-descriptor record entries. Any
+ * failure omits headers instead of throwing — status/providerCode facts
+ * extracted by the caller must survive a hostile headers object.
+ */
+function retainedHeaderRecord(headers: TransportHeaders | undefined): Record<string, string> | undefined {
+	if (headers === undefined) return undefined;
+	let record: Record<string, string> | undefined;
+	try {
+		if (headers instanceof Headers) {
+			for (const name of RETAINED_TRANSPORT_HEADERS) {
+				const value = headers.get(name);
+				if (typeof value !== "string") continue;
+				record ??= {};
+				record[name] = value;
+			}
+			return record;
+		}
+		for (const key of Object.keys(headers)) {
+			const descriptor = Object.getOwnPropertyDescriptor(headers, key);
+			if (!descriptor || !("value" in descriptor) || typeof descriptor.value !== "string") continue;
+			const name = key.toLowerCase();
+			if (!RETAINED_TRANSPORT_HEADER_SET.has(name)) continue;
+			record ??= {};
+			record[name] = descriptor.value;
+		}
+		return record;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Extracts only explicit HTTP/transport metadata; it never parses error text. */
+export function transportFailureFacts(
+	error: unknown,
+	capturedResponse?: { status?: number; headers?: TransportHeaders },
+): TransportFailureFacts | undefined {
+	if (!error || typeof error !== "object") return undefined;
+	const value = error as FallbackTriggerInput & { kind?: unknown; type?: unknown };
+	const response = propertyOf(value, "response");
+	const nestedError = propertyOf(value, "error");
+	const status =
+		finiteStatus(propertyOf(value, "status")) ??
+		finiteStatus(propertyOf(response, "status")) ??
+		finiteStatus(propertyOf(capturedResponse, "status"));
+	// `anthropicErrorType` is also read from its own key so re-normalizing an
+	// already-built facts object (which consumers do deliberately) preserves it
+	// instead of silently dropping the Anthropic code on the second pass.
+	const anthropicErrorType =
+		stringValue(propertyOf(nestedError, "type")) ??
+		stringValue(propertyOf(value, "anthropicErrorType")) ??
+		stringValue(propertyOf(value, "type"));
+	const openaiErrorCode =
+		stringValue(propertyOf(value, "openaiErrorCode")) ?? stringValue(propertyOf(nestedError, "code"));
+	const providerCode =
+		stringValue(propertyOf(value, "providerCode")) ??
+		openaiErrorCode ??
+		stringValue(propertyOf(value, "code")) ??
+		anthropicErrorType;
+	const errorHeaders = propertyOf(value, "headers");
+	const responseHeaders = propertyOf(response, "headers");
+	const capturedHeaders = propertyOf(capturedResponse, "headers");
+	const rawHeaders = isTransportHeaders(errorHeaders)
+		? errorHeaders
+		: isTransportHeaders(responseHeaders)
+			? responseHeaders
+			: isTransportHeaders(capturedHeaders)
+				? capturedHeaders
+				: undefined;
+	// Normalize BEFORE the existence gate so normalization is idempotent:
+	// facts built from an error whose headers carry no retained retry signal
+	// must not exist on the first pass and then vanish when re-normalized
+	// (consumers deliberately re-run transportFailureFacts on embedded facts).
+	const headers = retainedHeaderRecord(rawHeaders);
+	const normalizedCode = providerCode?.toLowerCase();
+	const requestBytes = finiteNonNegativeInteger(propertyOf(value, "requestBytes"));
+	const firstEventElapsedMs = finiteNonNegativeInteger(propertyOf(value, "firstEventElapsedMs"));
+	const firstEventTimeoutMs = finiteNonNegativeInteger(propertyOf(value, "firstEventTimeoutMs"));
+	const retryMaxAttempts = finitePositiveInteger(propertyOf(value, "retryMaxAttempts"));
+	const endpointClassValue = propertyOf(value, "endpointClass");
+	const endpointClass =
+		endpointClassValue === "canonical" || endpointClassValue === "custom" ? endpointClassValue : undefined;
+	if (
+		status === undefined &&
+		headers === undefined &&
+		!isQuotaCode(normalizedCode) &&
+		!isAuthCode(normalizedCode) &&
+		!isRateLimitCode(normalizedCode) &&
+		!isContextOverflowCode(normalizedCode) &&
+		normalizedCode !== STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE &&
+		normalizedCode !== EMPTY_RESPONSE_PROVIDER_CODE &&
+		// Matched case-sensitively against the raw code: this is the one gate a
+		// provider-owned code can open on its own, so a cased or padded variant
+		// must not materialize facts that would disqualify an unrelated
+		// bare-default retry.
+		providerCode !== SERVER_OVERLOADED_PROVIDER_CODE &&
+		requestBytes === undefined &&
+		firstEventElapsedMs === undefined &&
+		firstEventTimeoutMs === undefined &&
+		endpointClass === undefined &&
+		retryMaxAttempts === undefined
+	) {
+		return undefined;
+	}
+	return {
+		kind: "transport",
+		status,
+		providerCode,
+		anthropicErrorType,
+		openaiErrorCode,
+		headers,
+		...(requestBytes === undefined ? {} : { requestBytes }),
+		...(firstEventElapsedMs === undefined ? {} : { firstEventElapsedMs }),
+		...(firstEventTimeoutMs === undefined ? {} : { firstEventTimeoutMs }),
+		...(endpointClass === undefined ? {} : { endpointClass }),
+		...(retryMaxAttempts === undefined ? {} : { retryMaxAttempts }),
+	};
+}
+
+function headersOf(headers: TransportHeaders | undefined): Headers | undefined {
+	if (headers instanceof Headers) return headers;
+	return headers ? new Headers(headers as Record<string, string>) : undefined;
+}
+
+function parseRetryAfterSeconds(value: string | null, now = Date.now()): number | undefined {
+	if (!value) return undefined;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1000);
+	const date = Date.parse(value);
+	return Number.isFinite(date) ? Math.max(0, date - now) : undefined;
+}
+
+function parseRetryAfterMilliseconds(value: string | null): number | undefined {
+	if (!value) return undefined;
+	const milliseconds = Number(value);
+	return Number.isFinite(milliseconds) && milliseconds >= 0 ? Math.round(milliseconds) : undefined;
+}
+
+function isContextOverflowCode(code: string | undefined): boolean {
+	return code === "context_length_exceeded";
+}
+function isQuotaCode(code: string | undefined): boolean {
+	return (
+		code === "insufficient_quota" ||
+		code === "quota_exceeded" ||
+		code === "quota_exhausted" ||
+		code === "usage_limit_reached" ||
+		code === "usage_not_included" ||
+		code === "out_of_credits"
+	);
+}
+
+const FORBIDDEN_AUTH_CODE = "forbidden";
+
+/** Auth codes that name a credential problem rather than an authorization one. */
+function isCredentialAuthCode(code: string | undefined): boolean {
+	return (
+		code === "authentication_error" ||
+		code === "invalid_api_key" ||
+		code === "invalid_token" ||
+		code === "token_expired" ||
+		code === "unauthorized"
+	);
+}
+
+function isAuthCode(code: string | undefined): boolean {
+	return isCredentialAuthCode(code) || code === FORBIDDEN_AUTH_CODE;
+}
+
+/**
+ * Resolves the {@link AuthDisposition} for an `auth` trigger.
+ *
+ * Precedence is explicit and ordered by specificity rather than by field,
+ * because transport facts can carry a first-party typed code and a
+ * `providerCode` that disagree:
+ *
+ * 1. A code naming a concrete credential fault (`invalid_api_key`,
+ *    `authentication_error`, …) wins, from whichever field it arrives in: it is
+ *    a specific diagnosis, while `forbidden` is the generic bucket this
+ *    refinement exists to distrust.
+ * 2. Otherwise a `forbidden` code in any field is terminal, so
+ *    `{status: 401, providerCode: "forbidden"}` does not mutate credentials.
+ * 3. Otherwise the HTTP status decides, and an unknown-status `auth` defaults to
+ *    `credential` because that is the classification the pre-refinement code
+ *    already produced.
+ *
+ * Trigger-class selection deliberately keeps its single-code precedence
+ * (`openaiErrorCode ?? anthropicErrorType ?? providerCode`); only this auth
+ * refinement reads every code field.
+ */
+function resolveAuthDisposition(codes: readonly (string | undefined)[], status: number | undefined): AuthDisposition {
+	if (codes.some(code => isCredentialAuthCode(code))) return "credential";
+	if (codes.some(code => code === FORBIDDEN_AUTH_CODE)) return "forbidden";
+	return status === 403 ? "forbidden" : "credential";
+}
+
+function isRateLimitCode(code: string | undefined): boolean {
+	return (
+		code === "rate_limit" ||
+		code === "rate_limit_error" ||
+		code === "rate_limit_exceeded" ||
+		code === "too_many_requests"
+	);
+}
+
+/** Classifies only typed upstream transport facts without consuming response bodies. */
+export function classifyFallbackTrigger(
+	errorOrFacts: TransportFailureFacts | FallbackTriggerInput | unknown,
+): FallbackTrigger {
+	const facts = transportFailureFacts(errorOrFacts);
+	if (!facts) return { class: "other" };
+	const headers = headersOf(facts.headers);
+	const retryAfterMs =
+		parseRetryAfterMilliseconds(headers?.get("retry-after-ms") ?? null) ??
+		parseRetryAfterSeconds(headers?.get("retry-after") ?? null);
+	const rawCodes = [facts.openaiErrorCode, facts.anthropicErrorType, facts.providerCode];
+	const codes = rawCodes.map(value => value?.toLowerCase());
+	const code = codes[0] ?? codes[1] ?? codes[2];
+	// The capacity-overload code is provider-owned and is the only code that can
+	// classify without a status, so it is matched case-sensitively — the same
+	// exactness the parser and the session admission use.
+	const rawCode = rawCodes[0] ?? rawCodes[1] ?? rawCodes[2];
+	const triggerClass: FallbackTriggerClass =
+		code === STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE ||
+		code === EMPTY_RESPONSE_PROVIDER_CODE ||
+		(facts.status === undefined && rawCode === SERVER_OVERLOADED_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";
+	const trigger: FallbackTrigger = { class: triggerClass };
+	if (retryAfterMs !== undefined) trigger.retryAfterMs = retryAfterMs;
+	if (triggerClass === "auth") trigger.authDisposition = resolveAuthDisposition(codes, facts.status);
+	return trigger;
+}
+
+/**
+ * True when a failure is an `auth` failure that must NOT rotate credentials.
+ *
+ * Callers that mutate credential state on auth failures should consult this
+ * first so a plain `forbidden` cannot block otherwise-healthy credentials.
+ */
+export function isForbiddenAuthFailure(errorOrFacts: TransportFailureFacts | FallbackTriggerInput | unknown): boolean {
+	const trigger = classifyFallbackTrigger(errorOrFacts);
+	return trigger.class === "auth" && trigger.authDisposition === "forbidden";
+}

package/src/utils/fireworks-model-id.d.ts

@@ -0,0 +1,10 @@
+export declare function toFireworksPublicModelId(modelId: string): string;
+export declare function toFireworksWireModelId(modelId: string): string;
+/**
+ * Fire Pass exposes its Kimi K2.6 Turbo subscription through a dedicated router
+ * endpoint at `accounts/fireworks/routers/<id>` rather than the `models/` namespace.
+ * We keep a friendly public id (e.g. `kimi-k2.6-turbo`) in the catalog and translate
+ * to the wire form (`accounts/fireworks/routers/kimi-k2p6-turbo`) at request time.
+ */
+export declare function toFirepassPublicModelId(modelId: string): string;
+export declare function toFirepassWireModelId(modelId: string): string;

package/src/utils/fireworks-model-id.ts

@@ -0,0 +1,30 @@
+const FIREWORKS_WIRE_PREFIX = "accounts/fireworks/models/";
+const FIREPASS_WIRE_PREFIX = "accounts/fireworks/routers/";
+const VERSION_SEPARATOR_PATTERN = /(?<=\d)p(?=\d)/g;
+const VERSION_DOT_PATTERN = /(?<=\d)\.(?=\d)/g;
+
+export function toFireworksPublicModelId(modelId: string): string {
+	const stripped = modelId.startsWith(FIREWORKS_WIRE_PREFIX) ? modelId.slice(FIREWORKS_WIRE_PREFIX.length) : modelId;
+	return stripped.replace(VERSION_SEPARATOR_PATTERN, ".");
+}
+
+export function toFireworksWireModelId(modelId: string): string {
+	const stripped = modelId.startsWith(FIREWORKS_WIRE_PREFIX) ? modelId.slice(FIREWORKS_WIRE_PREFIX.length) : modelId;
+	return `${FIREWORKS_WIRE_PREFIX}${stripped.replace(VERSION_DOT_PATTERN, "p")}`;
+}
+
+/**
+ * Fire Pass exposes its Kimi K2.6 Turbo subscription through a dedicated router
+ * endpoint at `accounts/fireworks/routers/<id>` rather than the `models/` namespace.
+ * We keep a friendly public id (e.g. `kimi-k2.6-turbo`) in the catalog and translate
+ * to the wire form (`accounts/fireworks/routers/kimi-k2p6-turbo`) at request time.
+ */
+export function toFirepassPublicModelId(modelId: string): string {
+	const stripped = modelId.startsWith(FIREPASS_WIRE_PREFIX) ? modelId.slice(FIREPASS_WIRE_PREFIX.length) : modelId;
+	return stripped.replace(VERSION_SEPARATOR_PATTERN, ".");
+}
+
+export function toFirepassWireModelId(modelId: string): string {
+	const stripped = modelId.startsWith(FIREPASS_WIRE_PREFIX) ? modelId.slice(FIREPASS_WIRE_PREFIX.length) : modelId;
+	return `${FIREPASS_WIRE_PREFIX}${stripped.replace(VERSION_DOT_PATTERN, "p")}`;
+}

package/src/utils/foundry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 Vibrato/user-owned
+ * `.env` files, never the project `.env`).
+ */
+export declare function isFoundryEnabled(): boolean;

package/src/utils/foundry.ts

@@ -0,0 +1,18 @@
+import { $credentialEnv } from "@vib-rato/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 Vibrato/user-owned
+ * `.env` files, never the project `.env`).
+ */
+export function isFoundryEnabled(): boolean {
+	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/h2-fetch.ts

@@ -0,0 +1,60 @@
+/**
+ * Patch `globalThis.fetch` to advertise HTTP/2 in TLS ALPN, with transparent
+ * HTTP/1.1 fallback when the server doesn't negotiate `h2`.
+ *
+ * Bun's HTTP/2 client is gated on `BUN_FEATURE_FLAG_EXPERIMENTAL_HTTP2_CLIENT`,
+ * read by the native runtime before any JS executes; assigning to
+ * `process.env` from inside JS is a no-op. Per-request `protocol: "http2"`
+ * activates h2 over TLS ALPN and rejects with `error.code === "HTTP2Unsupported"`
+ * if the server picks anything else, so we catch and retry without the hint.
+ *
+ * Some HTTPS endpoints (e.g. corporate API gateways behind reverse proxies)
+ * advertise h2 via ALPN but then refuse or reset the connection at the HTTP/2
+ * framing layer. Bun surfaces these as `ConnectionRefused`, `ConnectionReset`,
+ * or `ConnectionClosed` rather than `HTTP2Unsupported`, so we treat those
+ * codes as h2-fallback triggers as well.
+ *
+ * Bun negotiates h2 via ALPN over TLS only (no h2c), so plain `http://` URLs
+ * skip the attempt entirely — avoids the throw/retry round-trip for localhost.
+ *
+ * Idempotent.
+ */
+
+const installed: unique symbol = Symbol.for("vib-rato.h2fetch.installed");
+
+interface PatchedFetch {
+	[installed]?: true;
+}
+
+export function installH2Fetch(): void {
+	const original = globalThis.fetch as typeof fetch & PatchedFetch;
+	if (original[installed]) return;
+
+	/** Error codes that indicate h2 negotiation/transport failure (not an application error). */
+	const h2FallbackCodes: ReadonlySet<string> = new Set([
+		"HTTP2Unsupported", // Server selected h1 in ALPN
+		"ConnectionRefused", // Server refused the h2 connection
+		"ConnectionReset", // Server reset during h2 handshake
+		"ConnectionClosed", // Server closed before h2 response
+	]);
+	const wrapper = async function h2fetch(input: string | URL | Request, init?: RequestInit): Promise<Response> {
+		if (!isHttps(input)) return original(input, init);
+		try {
+			return await original(input, { ...init, protocol: "http2" });
+		} catch (err) {
+			if (!h2FallbackCodes.has((err as { code?: string }).code ?? "")) throw err;
+			return original(input, init);
+		}
+	} as typeof fetch & PatchedFetch;
+
+	// Preserve `fetch.preconnect` and any other statics SDK code might poke at.
+	Object.assign(wrapper, original);
+	wrapper[installed] = true;
+	globalThis.fetch = wrapper;
+}
+
+function isHttps(input: string | URL | Request): boolean {
+	if (typeof input === "string") return input.startsWith("https:");
+	if (input instanceof URL) return input.protocol === "https:";
+	return input.url.startsWith("https:");
+}