@sayknow-cli/ai 0.2.2

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

@@ -0,0 +1,230 @@
+import { UNK_CONTEXT_WINDOW, UNK_MAX_TOKENS } from "@sayknow-cli/ai";
+import * as z from "zod/v4";
+import type { Api, FetchImpl, 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?: FetchImpl;
+	/** Optional HTTP status predicate for provider-specific hard failures. */
+	throwOnStatus?: (response: Response) => Error | undefined;
+	/**
+	 * 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) {
+		const hardFailure = options.throwOnStatus?.(response);
+		if (hardFailure) {
+			throw hardFailure;
+		}
+		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,172 @@
+import type { AssistantMessage, AssistantMessageEvent } from "../types";
+
+// Generic event stream class for async iteration
+export class EventStream<T, R = T> implements AsyncIterable<T> {
+	#queue: T[] = [];
+	#queueHead = 0;
+	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;
+	}
+
+	#enqueue(event: T): void {
+		this.#queue.push(event);
+	}
+
+	#dequeue(): T | undefined {
+		if (this.#queueHead >= this.#queue.length) return undefined;
+		const event = this.#queue[this.#queueHead]!;
+		this.#queue[this.#queueHead] = undefined as T;
+		this.#queueHead++;
+		if (this.#queueHead > 1024 && this.#queueHead * 2 >= this.#queue.length) {
+			this.#queue = this.#queue.slice(this.#queueHead);
+			this.#queueHead = 0;
+		}
+		return event;
+	}
+
+	get #queueLength(): number {
+		return this.#queue.length - this.#queueHead;
+	}
+
+	/**
+	 * Read-only snapshot of the not-yet-consumed events. Always a fresh copy:
+	 * external code can never mutate internal queue state or observe head-index
+	 * tombstones, so the deque cannot desynchronize.
+	 */
+	get queue(): T[] {
+		return this.#queue.slice(this.#queueHead);
+	}
+
+	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.#enqueue(event);
+		}
+	}
+
+	deliver(event: T): void {
+		const waiter = this.waiting.shift();
+		if (waiter) {
+			waiter.resolve({ value: event, done: false });
+		} else {
+			this.#enqueue(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.#queueLength > 0) {
+				yield this.#dequeue()!;
+			} 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 "@sayknow-cli/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("sayknow-cli.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:");
+}