@vib-rato/ai 0.16.0

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

@@ -0,0 +1,379 @@
+import * as net from "node:net";
+import { UNK_CONTEXT_WINDOW, UNK_MAX_TOKENS } from "@vib-rato/ai";
+import * as z from "zod/v4";
+import type { Api, FetchImpl, Model, Provider } from "../../types";
+import { toNumber } from "../../utils";
+
+const MODELS_PATH = "/models";
+const MAX_MODELS_RESPONSE_BYTES = 1_000_000;
+const MAX_CATALOG_MODEL_ID_LENGTH = 200;
+
+function parseIpv6Hextets(host: string): number[] | undefined {
+	if (net.isIP(host) !== 6) return undefined;
+	const doubleColon = host.indexOf("::");
+	if (doubleColon !== host.lastIndexOf("::")) return undefined;
+	const parseSide = (value: string): number[] | undefined => {
+		if (!value) return [];
+		const parts = value.split(":");
+		if (parts.some(part => !/^[0-9a-f]{1,4}$/i.test(part))) return undefined;
+		return parts.map(part => Number.parseInt(part, 16));
+	};
+	if (doubleColon < 0) {
+		const hextets = parseSide(host);
+		return hextets?.length === 8 ? hextets : undefined;
+	}
+	const left = parseSide(host.slice(0, doubleColon));
+	const right = parseSide(host.slice(doubleColon + 2));
+	if (!left || !right) return undefined;
+	const missing = 8 - left.length - right.length;
+	if (missing < 1) return undefined;
+	return [...left, ...new Array<number>(missing).fill(0), ...right];
+}
+
+function isLoopbackHost(hostname: string): boolean {
+	const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+	if (host === "localhost") return true;
+	if (net.isIP(host) === 4) return host.split(".", 1)[0] === "127";
+	const hextets = parseIpv6Hextets(host);
+	if (!hextets) return false;
+	const isIpv6Loopback = hextets.slice(0, 7).every(part => part === 0) && hextets[7] === 1;
+	const isIpv4MappedLoopback =
+		hextets.slice(0, 5).every(part => part === 0) && hextets[5] === 0xffff && hextets[6]! >> 8 === 0x7f;
+	return isIpv6Loopback || isIpv4MappedLoopback;
+}
+
+/** Catalog identities are rendered and used for routing; unsafe values are dropped, never rewritten. */
+export function isSafeCatalogModelId(value: unknown): value is string {
+	return (
+		typeof value === "string" &&
+		value.trim().length > 0 &&
+		value.length <= MAX_CATALOG_MODEL_ID_LENGTH &&
+		!/[\u0000-\u001f\u007f-\u009f]/u.test(value)
+	);
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Resolves an endpoint for an implicit local provider without allowing an
+ * environment override to turn its keyless discovery into a remote request.
+ */
+export function resolveLoopbackOpenAIBaseUrl(value: string | undefined, fallback: string): string {
+	const candidate = value?.trim();
+	if (!candidate) return fallback;
+	try {
+		const parsed = new URL(candidate);
+		if ((parsed.protocol === "http:" || parsed.protocol === "https:") && isLoopbackHost(parsed.hostname)) {
+			return candidate;
+		}
+	} catch {
+		// Fall back to the fixed loopback endpoint below.
+	}
+	return fallback;
+}
+
+/**
+ * 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(buildModelsUrl(baseUrl), {
+			method: "GET",
+			headers: requestHeaders,
+			signal: options.signal
+				? AbortSignal.any([options.signal, AbortSignal.timeout(5_000)])
+				: AbortSignal.timeout(5_000),
+		});
+	} catch {
+		return null;
+	}
+
+	if (!response.ok) {
+		const hardFailure = options.throwOnStatus?.(response);
+		if (hardFailure) {
+			throw hardFailure;
+		}
+		return null;
+	}
+
+	let payload: unknown;
+	try {
+		payload = JSON.parse(await readModelsResponse(response));
+	} 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) {
+		if (!isSafeCatalogModelId(entry.id)) {
+			continue;
+		}
+		const rawContextWindow = firstPositiveModelNumber(
+			UNK_CONTEXT_WINDOW,
+			entry.max_model_len,
+			entry.context_length,
+			entry.context_window,
+			entry.max_context_length,
+			entry.max_position_embeddings,
+		);
+
+		const rawMaxTokens = firstPositiveModelNumber(UNK_MAX_TOKENS, entry.max_tokens, entry.max_output_tokens);
+
+		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: rawContextWindow,
+			maxTokens: rawMaxTokens,
+		};
+
+		const mapped = options.mapModel?.(entry, defaults, context) ?? defaults;
+		if (!mapped || !isSafeCatalogModelId(mapped.id)) {
+			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));
+}
+
+async function readModelsResponse(response: Response): Promise<string> {
+	const contentLength = Number(response.headers.get("content-length"));
+	if (Number.isFinite(contentLength) && contentLength > MAX_MODELS_RESPONSE_BYTES) {
+		throw new Error("OpenAI-compatible models response exceeds the size limit");
+	}
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (!value) continue;
+			total += value.byteLength;
+			if (total > MAX_MODELS_RESPONSE_BYTES) {
+				await reader.cancel();
+				throw new Error("OpenAI-compatible models response exceeds the size limit");
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const body = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		body.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(body);
+}
+
+function normalizeBaseUrl(baseUrl: string): string {
+	const trimmed = baseUrl.trim();
+	if (!trimmed) {
+		return "";
+	}
+	try {
+		const parsed = new URL(trimmed);
+		parsed.pathname = parsed.pathname.replace(/\/+$/g, "");
+		return parsed.toString();
+	} catch {
+		return trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
+	}
+}
+
+function buildModelsUrl(baseUrl: string): string {
+	try {
+		const parsed = new URL(baseUrl);
+		parsed.pathname = `${parsed.pathname.replace(/\/+$/g, "")}${MODELS_PATH}`;
+		return parsed.toString();
+	} catch {
+		return `${baseUrl}${MODELS_PATH}`;
+	}
+}
+
+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;
+}
+
+/**
+ * First positive safe integer among candidates, else the fallback.
+ *
+ * Rejects non-numbers, non-finite values (JSON `1e400` parses to `Infinity`),
+ * fractions, values outside the safe integer range, zero, and negatives so a
+ * malformed catalog field can never poison compaction thresholds or output
+ * budgets.
+ */
+function firstPositiveModelNumber(fallback: number, ...candidates: readonly unknown[]): number {
+	for (const candidate of candidates) {
+		const value = toNumber(candidate);
+		if (value !== undefined && Number.isSafeInteger(value) && value > 0) {
+			return value;
+		}
+	}
+	return fallback;
+}

package/src/utils/event-stream.d.ts

@@ -0,0 +1,41 @@
+import type { AssistantMessage, AssistantMessageEvent } from "../types";
+export declare class EventStream<T, R = T> implements AsyncIterable<T> {
+    #private;
+    waiting: Array<{
+        resolve: (value: IteratorResult<T>) => void;
+        reject: (err: unknown) => void;
+    }>;
+    done: boolean;
+    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, onConsumerClose?: () => void);
+    /**
+     * 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 or private consumer-drain sentinels, so the deque cannot desynchronize.
+     */
+    get queue(): T[];
+    /** Read-only test seam for outstanding consumer-drain waiters. */
+    get pendingConsumerDrainCountForTests(): number;
+    /** Whether an async iterator is currently consuming this stream. */
+    get hasActiveConsumer(): boolean;
+    push(event: T): void;
+    deliver(event: T): void;
+    /**
+     * Resolves after every event enqueued before this call has been yielded and
+     * the consumer asks the iterator for its next node. The private sentinel is
+     * never exposed through the async iterator.
+     */
+    waitForConsumerDrain(signal: AbortSignal): Promise<void>;
+    end(result?: R): void;
+    endWaiting(): void;
+    fail(err: unknown): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    result(): Promise<R>;
+}
+export declare class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
+    constructor(onConsumerClose?: () => void);
+}

package/src/utils/event-stream.ts

@@ -0,0 +1,269 @@
+import type { AssistantMessage, AssistantMessageEvent } from "../types";
+
+interface EventQueueNode<T> {
+	type: "event";
+	event: T;
+}
+
+type QueueNode<T> = EventQueueNode<T> | { type: "consumer-drain"; drain: ConsumerDrain };
+
+interface ConsumerDrain {
+	settled: boolean;
+	signal: AbortSignal;
+	abortListener: () => void;
+	resolve: () => void;
+	reject: (reason: unknown) => void;
+}
+
+function abortReason(signal: AbortSignal): unknown {
+	return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
+
+// Generic event stream class for async iteration
+
+export class EventStream<T, R = T> implements AsyncIterable<T> {
+	#queue: QueueNode<T>[] = [];
+	#queueHead = 0;
+	waiting: Array<{ resolve: (value: IteratorResult<T>) => void; reject: (err: unknown) => void }> = [];
+	#pendingConsumerDrains = new Set<ConsumerDrain>();
+	#activeConsumerCount = 0;
+	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;
+	#onConsumerClose?: () => void;
+
+	constructor(isComplete: (event: T) => boolean, extractResult: (event: T) => R, onConsumerClose?: () => void) {
+		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;
+		this.#onConsumerClose = onConsumerClose;
+	}
+
+	#enqueue(node: QueueNode<T>): void {
+		this.#queue.push(node);
+	}
+
+	#dequeue(): QueueNode<T> | undefined {
+		if (this.#queueHead >= this.#queue.length) return undefined;
+		const node = this.#queue[this.#queueHead]!;
+		this.#queue[this.#queueHead] = undefined as unknown as QueueNode<T>;
+		this.#queueHead++;
+		if (this.#queueHead > 1024 && this.#queueHead * 2 >= this.#queue.length) {
+			this.#queue = this.#queue.slice(this.#queueHead);
+			this.#queueHead = 0;
+		}
+		return node;
+	}
+
+	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 or private consumer-drain sentinels, so the deque cannot desynchronize.
+	 */
+	get queue(): T[] {
+		return this.#queue.slice(this.#queueHead).flatMap(node => (node.type === "event" ? [node.event] : []));
+	}
+
+	/** Read-only test seam for outstanding consumer-drain waiters. */
+	get pendingConsumerDrainCountForTests(): number {
+		return this.#pendingConsumerDrains.size;
+	}
+
+	/** Whether an async iterator is currently consuming this stream. */
+	get hasActiveConsumer(): boolean {
+		return this.#activeConsumerCount > 0;
+	}
+
+	#settleConsumerDrain(drain: ConsumerDrain, status: "resolve" | "reject", reason?: unknown): void {
+		if (drain.settled) return;
+		drain.settled = true;
+		this.#pendingConsumerDrains.delete(drain);
+		drain.signal.removeEventListener("abort", drain.abortListener);
+		if (status === "resolve") {
+			drain.resolve();
+		} else {
+			drain.reject(reason);
+		}
+	}
+
+	#settleAllConsumerDrains(status: "resolve" | "reject", reason?: unknown): void {
+		for (const drain of this.#pendingConsumerDrains) {
+			this.#settleConsumerDrain(drain, status, reason);
+		}
+	}
+
+	#drainQueuedNodesToWaitingConsumers(): void {
+		while (this.waiting.length > 0 && this.#queueLength > 0) {
+			const node = this.#dequeue()!;
+			if (node.type === "consumer-drain") {
+				this.#settleConsumerDrain(node.drain, "resolve");
+
+				continue;
+			}
+			this.waiting.shift()!.resolve({ value: node.event, done: false });
+		}
+	}
+
+	#dequeueEvent(): EventQueueNode<T> | undefined {
+		while (this.#queueLength > 0) {
+			const node = this.#dequeue()!;
+			if (node.type === "event") return node;
+			this.#settleConsumerDrain(node.drain, "resolve");
+		}
+		return undefined;
+	}
+
+	push(event: T): void {
+		if (this.done) return;
+		try {
+			if (this.isComplete(event)) {
+				const result = this.extractResult(event);
+				this.done = true;
+				this.resolveFinalResult(result);
+			}
+		} catch (error) {
+			this.fail(error);
+			return;
+		}
+		this.deliver(event);
+	}
+
+	deliver(event: T): void {
+		if (this.#queueLength === 0) {
+			const waiter = this.waiting.shift();
+			if (waiter) {
+				waiter.resolve({ value: event, done: false });
+				return;
+			}
+		}
+		this.#enqueue({ type: "event", event });
+		this.#drainQueuedNodesToWaitingConsumers();
+	}
+
+	/**
+	 * Resolves after every event enqueued before this call has been yielded and
+	 * the consumer asks the iterator for its next node. The private sentinel is
+	 * never exposed through the async iterator.
+	 */
+	waitForConsumerDrain(signal: AbortSignal): Promise<void> {
+		if (signal.aborted) return Promise.reject(abortReason(signal));
+		if (this.#failed) return Promise.reject(this.#error);
+		if (this.done && this.#activeConsumerCount === 0) {
+			if (this.#queueLength === 0) return Promise.resolve();
+			return Promise.reject(new Error("Event stream ended before queued events could be drained"));
+		}
+
+		const { promise, resolve, reject } = Promise.withResolvers<void>();
+		let drain!: ConsumerDrain;
+		const abortListener = () => this.#settleConsumerDrain(drain, "reject", abortReason(signal));
+
+		drain = { settled: false, signal, abortListener, resolve, reject };
+		this.#pendingConsumerDrains.add(drain);
+		signal.addEventListener("abort", abortListener, { once: true });
+		this.#enqueue({ type: "consumer-drain", drain });
+		this.#drainQueuedNodesToWaitingConsumers();
+		return promise;
+	}
+
+	end(result?: R): void {
+		this.done = true;
+		if (this.#activeConsumerCount === 0) {
+			this.#settleAllConsumerDrains("reject", new Error("Event stream ended before consumer drain completed"));
+		}
+
+		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 {
+		if (this.#activeConsumerCount === 0) {
+			this.#settleAllConsumerDrains("reject", new Error("Event stream ended before consumer drain completed"));
+		}
+		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.#settleAllConsumerDrains("reject", err);
+
+		this.rejectFinalResult(err);
+		while (this.waiting.length > 0) {
+			const waiter = this.waiting.shift()!;
+			waiter.reject(err);
+		}
+	}
+
+	async *[Symbol.asyncIterator](): AsyncIterator<T> {
+		this.#activeConsumerCount += 1;
+		try {
+			while (true) {
+				const node = this.#dequeueEvent();
+				if (node !== undefined) {
+					yield node.event;
+				} 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;
+				}
+			}
+		} finally {
+			this.#activeConsumerCount -= 1;
+			this.#settleAllConsumerDrains("reject", new Error("Event stream consumer stopped before drain completed"));
+			if (!this.done) this.#onConsumerClose?.();
+		}
+	}
+
+	result(): Promise<R> {
+		return this.finalResultPromise;
+	}
+}
+
+export class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
+	constructor(onConsumerClose?: () => void) {
+		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");
+			},
+			onConsumerClose,
+		);
+	}
+}