@gajae-code/ai 0.1.1

package/src/utils/discovery/openai-compatible.ts

@@ -0,0 +1,224 @@
+import { UNK_CONTEXT_WINDOW, UNK_MAX_TOKENS } from "@gajae-code/ai";
+import * as z from "zod/v4";
+import type { Api, Model, Provider } from "../../types";
+
+const MODELS_PATH = "/models";
+
+/**
+ * Minimal OpenAI-style model entry shape consumed by discovery.
+ *
+ * Providers may return additional fields; this type only captures
+ * fields that are useful for generic normalization.
+ */
+export interface OpenAICompatibleModelRecord {
+	id?: unknown;
+	name?: unknown;
+	object?: unknown;
+	owned_by?: unknown;
+	[key: string]: unknown;
+}
+
+/**
+ * Tolerant envelope for OpenAI-compatible `/models` responses.
+ *
+ * Common providers return `{ data: [...] }`, but variants such as
+ * `{ models: [...] }`, `{ result: [...] }`, or direct arrays are also
+ * accepted during extraction.
+ */
+export interface OpenAICompatibleModelsEnvelope {
+	data?: unknown;
+	models?: unknown;
+	result?: unknown;
+	items?: unknown;
+	[key: string]: unknown;
+}
+
+const openAICompatibleModelRecordSchema = z
+	.object({
+		id: z.string().min(1),
+		name: z.string().optional().nullable(),
+		object: z.unknown().optional(),
+		owned_by: z.unknown().optional(),
+	})
+	.loose();
+
+const openAICompatibleModelsEnvelopeSchema = z
+	.object({
+		data: z.unknown().optional(),
+		models: z.unknown().optional(),
+		result: z.unknown().optional(),
+		items: z.unknown().optional(),
+	})
+	.loose();
+
+const openAICompatibleModelsPayloadSchema = z.union([z.array(z.unknown()), openAICompatibleModelsEnvelopeSchema]);
+
+type ParsedOpenAICompatibleModelRecord = z.infer<typeof openAICompatibleModelRecordSchema>;
+
+/**
+ * Context passed to custom OpenAI-compatible model mappers.
+ */
+export interface OpenAICompatibleModelMapperContext<TApi extends Api> {
+	api: TApi;
+	provider: Provider;
+	baseUrl: string;
+}
+
+/**
+ * Options for fetching and normalizing OpenAI-compatible `/models` catalogs.
+ */
+export interface FetchOpenAICompatibleModelsOptions<TApi extends Api> {
+	/** API type assigned to normalized models. */
+	api: TApi;
+	/** Provider id assigned to normalized models. */
+	provider: Provider;
+	/** Provider base URL used for both fetch and normalized model records. */
+	baseUrl: string;
+	/** Optional bearer token for Authorization header. */
+	apiKey?: string;
+	/** Additional request headers. */
+	headers?: Record<string, string>;
+	/** Optional AbortSignal for request cancellation. */
+	signal?: AbortSignal;
+	/** Optional fetch implementation override for testing/custom runtimes. */
+	fetch?: typeof globalThis.fetch;
+	/**
+	 * Optional post-normalization filter.
+	 * Return false to skip a model.
+	 */
+	filterModel?: (entry: OpenAICompatibleModelRecord, model: Model<TApi>) => boolean;
+	/**
+	 * Optional mapper override for provider-specific quirks.
+	 * Return null to skip a model.
+	 */
+	mapModel?: (
+		entry: OpenAICompatibleModelRecord,
+		defaults: Model<TApi>,
+		context: OpenAICompatibleModelMapperContext<TApi>,
+	) => Model<TApi> | null;
+}
+
+/**
+ * Fetches and normalizes an OpenAI-compatible `/models` catalog.
+ *
+ * Returns `null` on transport/protocol failures.
+ * Returns `[]` only when the endpoint responds successfully with no usable models.
+ */
+export async function fetchOpenAICompatibleModels<TApi extends Api>(
+	options: FetchOpenAICompatibleModelsOptions<TApi>,
+): Promise<Model<TApi>[] | null> {
+	const baseUrl = normalizeBaseUrl(options.baseUrl);
+	if (!baseUrl) {
+		return null;
+	}
+
+	const requestHeaders: Record<string, string> = {
+		Accept: "application/json",
+		...options.headers,
+	};
+	if (options.apiKey) {
+		requestHeaders.Authorization = `Bearer ${options.apiKey}`;
+	}
+
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+	let response: Response;
+	try {
+		response = await fetchImpl(`${baseUrl}${MODELS_PATH}`, {
+			method: "GET",
+			headers: requestHeaders,
+			signal: options.signal,
+		});
+	} catch {
+		return null;
+	}
+
+	if (!response.ok) {
+		return null;
+	}
+
+	let payload: unknown;
+	try {
+		payload = await response.json();
+	} catch {
+		return null;
+	}
+
+	const entries = extractModelEntries(payload);
+	if (entries === null) {
+		return null;
+	}
+
+	const context: OpenAICompatibleModelMapperContext<TApi> = {
+		api: options.api,
+		provider: options.provider,
+		baseUrl,
+	};
+
+	const deduped = new Map<string, Model<TApi>>();
+	for (const entry of entries) {
+		const defaults: Model<TApi> = {
+			id: entry.id,
+			name: typeof entry.name === "string" && entry.name.length > 0 ? entry.name : entry.id,
+			api: options.api,
+			provider: options.provider,
+			baseUrl,
+			reasoning: false,
+			input: ["text"],
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+			contextWindow: UNK_CONTEXT_WINDOW,
+			maxTokens: UNK_MAX_TOKENS,
+		};
+
+		const mapped = options.mapModel?.(entry, defaults, context) ?? defaults;
+		if (!mapped || typeof mapped.id !== "string" || mapped.id.length === 0) {
+			continue;
+		}
+		if (options.filterModel && !options.filterModel(entry, mapped)) {
+			continue;
+		}
+		deduped.set(mapped.id, mapped);
+	}
+
+	return Array.from(deduped.values()).sort((left, right) => left.id.localeCompare(right.id));
+}
+
+function normalizeBaseUrl(baseUrl: string): string {
+	const trimmed = baseUrl.trim();
+	if (!trimmed) {
+		return "";
+	}
+	return trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
+}
+
+function extractModelEntries(payload: unknown): ParsedOpenAICompatibleModelRecord[] | null {
+	return extractModelEntriesFromNode(payload);
+}
+
+function extractModelEntriesFromNode(node: unknown): ParsedOpenAICompatibleModelRecord[] | null {
+	const parsedPayload = openAICompatibleModelsPayloadSchema.safeParse(node);
+	if (!parsedPayload.success) {
+		return null;
+	}
+	if (Array.isArray(parsedPayload.data)) {
+		const parsedEntries = parsedPayload.data
+			.map(entry => openAICompatibleModelRecordSchema.safeParse(entry))
+			.flatMap(entry => (entry.success ? [entry.data] : []));
+		return parsedEntries;
+	}
+	for (const candidate of [
+		parsedPayload.data.data,
+		parsedPayload.data.models,
+		parsedPayload.data.result,
+		parsedPayload.data.items,
+	]) {
+		if (candidate === undefined) {
+			continue;
+		}
+		const nested = extractModelEntriesFromNode(candidate);
+		if (nested !== null) {
+			return nested;
+		}
+	}
+
+	return null;
+}

package/src/utils/event-stream.ts

@@ -0,0 +1,142 @@
+import type { AssistantMessage, AssistantMessageEvent } from "../types";
+
+// Generic event stream class for async iteration
+export class EventStream<T, R = T> implements AsyncIterable<T> {
+	queue: T[] = [];
+	waiting: Array<{ resolve: (value: IteratorResult<T>) => void; reject: (err: unknown) => void }> = [];
+	done = false;
+	#failed = false;
+	#error: unknown = undefined;
+	finalResultPromise: Promise<R>;
+	resolveFinalResult!: (result: R) => void;
+	rejectFinalResult!: (err: unknown) => void;
+	isComplete: (event: T) => boolean;
+	extractResult: (event: T) => R;
+
+	constructor(isComplete: (event: T) => boolean, extractResult: (event: T) => R) {
+		const { promise, resolve, reject } = Promise.withResolvers<R>();
+		// Prevent an unhandled rejection when fail() is called but nobody awaits result().
+		// Callers who do await result() still receive the rejection normally.
+		promise.catch(() => {});
+		this.finalResultPromise = promise;
+		this.resolveFinalResult = resolve;
+		this.rejectFinalResult = reject;
+		this.isComplete = isComplete;
+		this.extractResult = extractResult;
+	}
+
+	push(event: T): void {
+		if (this.done) return;
+
+		if (this.isComplete(event)) {
+			this.done = true;
+			this.resolveFinalResult(this.extractResult(event));
+		}
+
+		// Deliver to waiting consumer or queue it
+		const waiter = this.waiting.shift();
+		if (waiter) {
+			waiter.resolve({ value: event, done: false });
+		} else {
+			this.queue.push(event);
+		}
+	}
+
+	deliver(event: T): void {
+		const waiter = this.waiting.shift();
+		if (waiter) {
+			waiter.resolve({ value: event, done: false });
+		} else {
+			this.queue.push(event);
+		}
+	}
+
+	end(result?: R): void {
+		this.done = true;
+		if (result !== undefined) {
+			this.resolveFinalResult(result);
+		}
+		// Notify all waiting consumers that we're done
+		while (this.waiting.length > 0) {
+			const waiter = this.waiting.shift()!;
+			waiter.resolve({ value: undefined as any, done: true });
+		}
+	}
+
+	endWaiting(): void {
+		while (this.waiting.length > 0) {
+			const waiter = this.waiting.shift()!;
+			waiter.resolve({ value: undefined as any, done: true });
+		}
+	}
+
+	fail(err: unknown): void {
+		if (this.done) return;
+		this.done = true;
+		this.#failed = true;
+		this.#error = err;
+		this.rejectFinalResult(err);
+		while (this.waiting.length > 0) {
+			const waiter = this.waiting.shift()!;
+			waiter.reject(err);
+		}
+	}
+
+	async *[Symbol.asyncIterator](): AsyncIterator<T> {
+		while (true) {
+			if (this.queue.length > 0) {
+				yield this.queue.shift()!;
+			} else if (this.#failed) {
+				throw this.#error;
+			} else if (this.done) {
+				return;
+			} else {
+				const result = await new Promise<IteratorResult<T>>((resolve, reject) =>
+					this.waiting.push({ resolve, reject }),
+				);
+				if (result.done) return;
+				yield result.value;
+			}
+		}
+	}
+
+	result(): Promise<R> {
+		return this.finalResultPromise;
+	}
+}
+
+export class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
+	constructor() {
+		super(
+			event => event.type === "done" || event.type === "error",
+			event => {
+				if (event.type === "done") {
+					return event.message;
+				} else if (event.type === "error") {
+					return event.error;
+				}
+				throw new Error("Unexpected event type for final result");
+			},
+		);
+	}
+
+	override push(event: AssistantMessageEvent): void {
+		if (this.done) return;
+
+		// Completion resolves the final result and still emits the terminal event.
+		if (this.isComplete(event)) {
+			this.done = true;
+			this.resolveFinalResult(this.extractResult(event));
+		}
+
+		this.deliver(event);
+	}
+
+	override end(result?: AssistantMessage): void {
+		this.done = true;
+		if (result !== undefined) {
+			this.resolveFinalResult(result);
+		}
+		this.endWaiting();
+	}
+}

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.ts

@@ -0,0 +1,8 @@
+import { $env } from "@gajae-code/utils";
+
+export function isFoundryEnabled(): boolean {
+	const value = $env.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("gajae-code.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:");
+}

package/src/utils/http-inspector.ts

@@ -0,0 +1,176 @@
+import * as path from "node:path";
+import { extractHttpStatusFromError, getLogsDir } from "@gajae-code/utils";
+import { isCopilotTransientModelError } from "./retry.js";
+import { formatErrorMessageWithRetryAfter } from "./retry-after.js";
+
+export type RawHttpRequestDump = {
+	provider: string;
+	api: string;
+	model: string;
+	method?: string;
+	url?: string;
+	headers?: Record<string, string>;
+	body?: unknown;
+};
+
+export type CapturedHttpErrorResponse = {
+	status: number;
+	headers?: Headers;
+	bodyText?: string;
+	bodyJson?: unknown;
+};
+
+type ErrorWithStatus = {
+	status?: unknown;
+};
+
+const SENSITIVE_HEADERS = ["authorization", "x-api-key", "api-key", "cookie", "set-cookie", "proxy-authorization"];
+
+export async function appendRawHttpRequestDumpFor400(
+	message: string,
+	error: unknown,
+	dump: RawHttpRequestDump | undefined,
+): Promise<string> {
+	if (!dump || extractHttpStatusFromError(error) !== 400) {
+		return message;
+	}
+
+	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);
+
+	try {
+		await Bun.write(filePath, `${JSON.stringify(sanitizedDump, null, 2)}\n`);
+		return `${message}\nraw-http-request=${filePath}`;
+	} catch (writeError) {
+		const writeMessage = writeError instanceof Error ? writeError.message : String(writeError);
+		return `${message}\nraw-http-request-save-failed=${writeMessage}`;
+	}
+}
+
+export async function finalizeErrorMessage(
+	error: unknown,
+	rawRequestDump: RawHttpRequestDump | undefined,
+	capturedErrorResponse?: CapturedHttpErrorResponse,
+): Promise<string> {
+	let message = formatErrorMessageWithRetryAfter(error, capturedErrorResponse?.headers);
+	const capturedMessage = formatCapturedHttpError(capturedErrorResponse);
+	if (capturedMessage) {
+		if (/\bstatus code\s*\(no body\)/i.test(message)) {
+			message = `${capturedErrorResponse?.status ?? "HTTP"} status code: ${capturedMessage}`;
+		} else if (!message.includes(capturedMessage)) {
+			message = `${message}\n${capturedMessage}`;
+		}
+	}
+	return appendRawHttpRequestDumpFor400(message, error, rawRequestDump);
+}
+
+export function withHttpStatus(error: unknown, status: number): Error {
+	const wrapped = error instanceof Error ? error : new Error(String(error));
+	(wrapped as ErrorWithStatus).status = status;
+	return wrapped;
+}
+
+/**
+ * Rewrite error message for GitHub Copilot request failures.
+ * Must run AFTER finalizeErrorMessage since it replaces the message entirely.
+ *
+ * 400 `model_not_supported` = Copilot routing rollout gap for our OAuth client.
+ *        A preview model (gpt-5.3-OpenAI code backend, gpt-5.4*, ...) flaps between 200 and
+ *        400 because only some of Copilot's backends have the model. After the
+ *        in-request retry exhausts, surface guidance rather than the raw error.
+ * 401 = token invalid/expired → credential removal is safe, prompt re-login.
+ * 403 = token valid but access denied (plan, model policy, org restriction) →
+ *       do NOT reuse the auth-failed string (which triggers credential removal).
+ */
+export function rewriteCopilotError(errorMessage: string, error: unknown, provider: string): string {
+	if (provider !== "github-copilot") return errorMessage;
+	const status = extractHttpStatusFromError(error);
+	if (status === 401) {
+		return `GitHub Copilot authentication failed (HTTP 401). Your token may have been revoked. Please re-login with /login github-copilot`;
+	}
+	if (status === 403) {
+		return `GitHub Copilot access denied (HTTP 403). Your account may not have access to this model or feature. Check your Copilot plan or model policy settings.`;
+	}
+	if (isCopilotTransientModelError(error)) {
+		return `GitHub Copilot rejected this model (HTTP 400 model_not_supported) after retries. This is a known intermittent rollout gap for preview models on OAuth clients other than VS Code. Try again in a few seconds, switch to a GA model (gpt-5-mini, gpt-5.2), or run this model from VS Code.`;
+	}
+	return errorMessage;
+}
+
+function sanitizeDump(dump: RawHttpRequestDump): RawHttpRequestDump {
+	return {
+		...dump,
+		headers: redactHeaders(dump.headers),
+	};
+}
+
+function redactHeaders(headers: Record<string, string> | undefined): Record<string, string> | undefined {
+	if (!headers) {
+		return undefined;
+	}
+
+	const redacted: Record<string, string> = {};
+	for (const [key, value] of Object.entries(headers)) {
+		if (SENSITIVE_HEADERS.includes(key.toLowerCase())) {
+			redacted[key] = "[redacted]";
+			continue;
+		}
+		redacted[key] = value;
+	}
+	return redacted;
+}
+
+function formatCapturedHttpError(captured: CapturedHttpErrorResponse | undefined): string | undefined {
+	if (!captured) return undefined;
+	const bodyText = captured.bodyText?.trim();
+	if (!bodyText) return undefined;
+	const payload = parseCapturedErrorPayload(captured);
+	if (!payload) return bodyText;
+
+	const errorPayload = getObjectProperty(payload, "error") ?? payload;
+	// {"error": "string"} — the error value is a plain string, not a nested object.
+	// Fall back to it when the structured fields ("message", etc.) are absent.
+	const stringError = errorPayload === payload ? getStringProperty(payload, "error") : undefined;
+	const message =
+		getStringProperty(errorPayload, "message") ?? getStringProperty(payload, "message") ?? stringError ?? bodyText;
+	const extras = [
+		getStringProperty(errorPayload, "type") ?? getStringProperty(payload, "type"),
+		getStringProperty(errorPayload, "param") ?? getStringProperty(payload, "param"),
+		getStringProperty(errorPayload, "code") ?? getStringProperty(payload, "code"),
+	]
+		.filter(Boolean)
+		.map((value, index) => {
+			if (index === 0) return `type=${value}`;
+			if (index === 1) return `param=${value}`;
+			return `code=${value}`;
+		});
+	return extras.length > 0 ? `${message} (${extras.join(" ")})` : message;
+}
+
+function parseCapturedErrorPayload(captured: CapturedHttpErrorResponse): Record<string, unknown> | undefined {
+	if (isObject(captured.bodyJson)) {
+		return captured.bodyJson;
+	}
+	if (!captured.bodyText) return undefined;
+	try {
+		const parsed = JSON.parse(captured.bodyText);
+		return isObject(parsed) ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function getObjectProperty(value: Record<string, unknown>, key: string): Record<string, unknown> | undefined {
+	const property = value[key];
+	return isObject(property) ? property : undefined;
+}
+
+function getStringProperty(value: Record<string, unknown>, key: string): string | undefined {
+	const property = value[key];
+	return typeof property === "string" && property.trim().length > 0 ? property : undefined;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}