@vib-rato/ai 0.16.0

package/src/providers/openai-opencodex-responses.ts

@@ -0,0 +1,174 @@
+import * as fs from "node:fs/promises";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import type { Model } from "../types";
+
+export const OPENCODEX_DEFAULT_PORT = 10100;
+export const OPENCODEX_PROBE_TIMEOUT_MS = 750;
+export const OPENCODEX_MODEL_CACHE_TTL_MS = 5 * 60 * 1000;
+
+interface RuntimePortFile {
+	hostname?: unknown;
+	host?: unknown;
+	port?: unknown;
+}
+
+interface HealthPayload {
+	ok?: unknown;
+	pid?: unknown;
+	port?: unknown;
+	version?: unknown;
+}
+
+interface CatalogRow {
+	id?: unknown;
+	model?: unknown;
+	name?: unknown;
+	displayName?: unknown;
+	contextWindow?: unknown;
+	maxTokens?: unknown;
+	reasoning?: unknown;
+	input?: unknown;
+}
+
+export interface OpenCodexEndpoint {
+	baseUrl: string;
+}
+
+function timeoutSignal(signal?: AbortSignal): AbortSignal {
+	return signal
+		? AbortSignal.any([signal, AbortSignal.timeout(OPENCODEX_PROBE_TIMEOUT_MS)])
+		: AbortSignal.timeout(OPENCODEX_PROBE_TIMEOUT_MS);
+}
+
+function normalizeEndpoint(hostname: string, port: number): string | undefined {
+	if (!Number.isInteger(port) || port < 1 || port > 65535) return undefined;
+	const host = normalizeLoopbackHost(hostname);
+	if (!host) return undefined;
+	return `http://${formatEndpointHost(host)}:${port}`;
+}
+
+function normalizeLoopbackHost(hostname: string): string | undefined {
+	const host = hostname.trim().toLowerCase();
+	if (net.isIP(host) === 4 && host.startsWith("127.")) return host;
+	if (host === "::1") return host;
+	return undefined;
+}
+
+function formatEndpointHost(host: string): string {
+	return host.includes(":") ? `[${host}]` : host;
+}
+
+function healthPort(endpoint: string): number {
+	return Number(new URL(endpoint).port);
+}
+
+async function readRuntimeEndpoint(): Promise<string | undefined> {
+	const home = process.env.OPENCODEX_HOME?.trim() || path.join(os.homedir(), ".opencodex");
+	try {
+		const raw = JSON.parse(await fs.readFile(path.join(home, "runtime-port.json"), "utf8")) as RuntimePortFile;
+		const hostname =
+			typeof raw.hostname === "string" ? raw.hostname : typeof raw.host === "string" ? raw.host : "127.0.0.1";
+		const port = typeof raw.port === "number" ? raw.port : typeof raw.port === "string" ? Number(raw.port) : NaN;
+		return normalizeEndpoint(hostname, port);
+	} catch {
+		return undefined;
+	}
+}
+
+function candidateEndpoints(runtimeEndpoint: string | undefined): string[] {
+	const candidates = runtimeEndpoint ? [runtimeEndpoint] : [];
+	const fallback = normalizeEndpoint("127.0.0.1", OPENCODEX_DEFAULT_PORT);
+	if (fallback && !candidates.includes(fallback)) candidates.push(fallback);
+	return candidates;
+}
+
+async function fetchJson(url: string, signal?: AbortSignal): Promise<unknown> {
+	const response = await fetch(url, {
+		headers: { Accept: "application/json" },
+		redirect: "error",
+		signal: timeoutSignal(signal),
+	});
+	if (!response.ok) return undefined;
+	return response.json();
+}
+
+function isOpenCodexHealth(payload: unknown, expectedPort: number): boolean {
+	if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
+	const health = payload as HealthPayload;
+	return health.ok === true && health.version === "opencodex" && health.port === expectedPort;
+}
+
+export async function resolveOpenCodexEndpoint(signal?: AbortSignal): Promise<OpenCodexEndpoint | undefined> {
+	const runtimeEndpoint = await readRuntimeEndpoint();
+	for (const candidate of candidateEndpoints(runtimeEndpoint)) {
+		try {
+			const health = await fetchJson(`${candidate}/healthz`, signal);
+			if (isOpenCodexHealth(health, healthPort(candidate))) return { baseUrl: candidate };
+		} catch {
+			// An unavailable or foreign listener is a normal provider absence.
+		}
+	}
+	return undefined;
+}
+
+function asPositiveNumber(value: unknown, fallback: number): number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function normalizeCatalogPayload(payload: unknown): CatalogRow[] {
+	if (Array.isArray(payload)) return payload as CatalogRow[];
+	if (payload && typeof payload === "object" && Array.isArray((payload as { models?: unknown }).models)) {
+		return (payload as { models: CatalogRow[] }).models;
+	}
+	return [];
+}
+
+function normalizeModel(row: CatalogRow, endpoint: OpenCodexEndpoint): Model<"openai-responses"> | undefined {
+	const rawId = typeof row.id === "string" ? row.id.trim() : typeof row.model === "string" ? row.model.trim() : "";
+	if (!rawId || rawId.includes("\n")) return undefined;
+	const publicId = `opencodex/${rawId}`;
+	const input =
+		Array.isArray(row.input) && row.input.every(value => value === "text" || value === "image")
+			? row.input
+			: ["text"];
+	return {
+		id: publicId,
+		wireModelId: rawId,
+		name: typeof row.displayName === "string" ? row.displayName : typeof row.name === "string" ? row.name : rawId,
+		api: "openai-responses",
+		provider: "opencodex",
+		baseUrl: `${endpoint.baseUrl}/v1`,
+		compat: { supportsServiceTier: true },
+		reasoning: row.reasoning !== false,
+		input,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: asPositiveNumber(row.contextWindow, 128_000),
+		maxTokens: asPositiveNumber(row.maxTokens, 16_384),
+	};
+}
+
+export async function fetchOpenCodexModels(): Promise<readonly Model<"openai-responses">[] | null> {
+	const endpoint = await resolveOpenCodexEndpoint();
+	if (!endpoint) return null;
+	try {
+		const rows = normalizeCatalogPayload(await fetchJson(`${endpoint.baseUrl}/api/models`));
+		const models = rows
+			.map(row => normalizeModel(row, endpoint))
+			.filter((model): model is Model<"openai-responses"> => model !== undefined);
+		return models.length > 0 ? models : null;
+	} catch {
+		return null;
+	}
+}
+
+export async function checkOpenCodexStatus(onProgress?: (message: string) => void): Promise<void> {
+	const endpoint = await resolveOpenCodexEndpoint();
+	if (endpoint) {
+		onProgress?.(`OpenCodex is available at ${endpoint.baseUrl}`);
+		return;
+	}
+	onProgress?.("OpenCodex is unavailable; no identity-checked local proxy was found.");
+}

package/src/providers/openai-request-transform.d.ts

@@ -0,0 +1,4 @@
+import type { FetchImpl, ModelRequestTransform } from "../types";
+export declare function applyOpenAIRequestTransformHeaders(headers: Record<string, string>, transform: ModelRequestTransform | undefined, profileUserAgent: string): Record<string, string>;
+export declare function applyOpenAIRequestTransformBody(params: object, transform: ModelRequestTransform | undefined): void;
+export declare function wrapFetchForOpenAIRequestTransform(baseFetch: FetchImpl, transform: ModelRequestTransform | undefined, profileUserAgent: string): FetchImpl;

package/src/providers/openai-request-transform.ts

@@ -0,0 +1,136 @@
+import type { FetchImpl, ModelRequestTransform } from "../types";
+
+const PROTECTED_EXTRA_BODY_KEYS = new Set([
+	"model",
+	"messages",
+	"input",
+	"instructions",
+	"stream",
+	"stream_options",
+	"store",
+	"max_tokens",
+	"max_completion_tokens",
+	"max_output_tokens",
+	"temperature",
+	"top_p",
+	"presence_penalty",
+	"frequency_penalty",
+	"reasoning",
+	"reasoning_effort",
+	"prompt_cache_key",
+	"prompt_cache_retention",
+	"service_tier",
+	"stop",
+	"tools",
+	"tool_choice",
+	"parallel_tool_calls",
+]);
+
+const OPENAI_PROXY_STRIP_HEADERS = [
+	"x-stainless-arch",
+	"x-stainless-async",
+	"x-stainless-lang",
+	"x-stainless-os",
+	"x-stainless-package-version",
+	"x-stainless-retry-count",
+	"x-stainless-runtime",
+	"x-stainless-runtime-version",
+	"x-stainless-timeout",
+	"x-stainless-helper-method",
+	"openai-organization",
+	"openai-project",
+	"openai-beta",
+] as const;
+
+function resolveRequestTransform(
+	transform: ModelRequestTransform | undefined,
+	profileUserAgent: string,
+): ModelRequestTransform | undefined {
+	if (!transform) return undefined;
+	const profileTransform: ModelRequestTransform =
+		transform.profile === "openai-proxy"
+			? {
+					stripHeaders: [...OPENAI_PROXY_STRIP_HEADERS],
+					setHeaders: { "User-Agent": profileUserAgent },
+				}
+			: {};
+	return {
+		...profileTransform,
+		...transform,
+		stripHeaders: transform.stripHeaders ?? profileTransform.stripHeaders,
+		setHeaders: transform.setHeaders
+			? { ...(profileTransform.setHeaders ?? {}), ...transform.setHeaders }
+			: profileTransform.setHeaders,
+		extraBody: transform.extraBody,
+	};
+}
+
+function deleteHeaders(headers: Headers, names: readonly string[] | undefined): void {
+	for (const name of names ?? []) {
+		headers.delete(name);
+	}
+}
+
+function setHeaders(headers: Headers, values: Record<string, string | null> | undefined): void {
+	for (const [name, value] of Object.entries(values ?? {})) {
+		if (value === null) {
+			headers.delete(name);
+		} else {
+			headers.set(name, value);
+		}
+	}
+}
+
+function transformHeaders(
+	headers: RequestInit["headers"] | undefined,
+	transform: ModelRequestTransform | undefined,
+): Headers {
+	const result = new Headers(headers);
+	deleteHeaders(result, transform?.stripHeaders);
+	setHeaders(result, transform?.setHeaders);
+	return result;
+}
+
+export function applyOpenAIRequestTransformHeaders(
+	headers: Record<string, string>,
+	transform: ModelRequestTransform | undefined,
+	profileUserAgent: string,
+): Record<string, string> {
+	const resolved = resolveRequestTransform(transform, profileUserAgent);
+	if (!resolved) return headers;
+	return Object.fromEntries(transformHeaders(headers, resolved).entries());
+}
+
+export function applyOpenAIRequestTransformBody(params: object, transform: ModelRequestTransform | undefined): void {
+	if (!transform?.extraBody) return;
+	const body = params as Record<string, unknown>;
+	for (const [key, value] of Object.entries(transform.extraBody)) {
+		if (!PROTECTED_EXTRA_BODY_KEYS.has(key) && !(key in body)) {
+			body[key] = value;
+		}
+	}
+}
+
+export function wrapFetchForOpenAIRequestTransform(
+	baseFetch: FetchImpl,
+	transform: ModelRequestTransform | undefined,
+	profileUserAgent: string,
+): FetchImpl {
+	const resolved = resolveRequestTransform(transform, profileUserAgent);
+	if (!resolved) return baseFetch;
+	return Object.assign(
+		async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+			if (input instanceof Request) {
+				const request = new Request(input, init);
+				deleteHeaders(request.headers, resolved.stripHeaders);
+				setHeaders(request.headers, resolved.setHeaders);
+				return baseFetch(request);
+			}
+			return baseFetch(input, {
+				...init,
+				headers: transformHeaders(init?.headers, resolved),
+			});
+		},
+		baseFetch.preconnect ? { preconnect: baseFetch.preconnect } : {},
+	);
+}

package/src/providers/openai-responses-server-schema.ts

@@ -0,0 +1,290 @@
+/**
+ * Zod schemas for the OpenAI Responses API request shape we accept on the
+ * gateway. Mirrors https://platform.openai.com/docs/api-reference/responses.
+ *
+ * Unsupported / opaque controls (background/include/metadata/prompt/…) are
+ * accepted as `z.unknown().optional()` so we silently ignore rather than 400.
+ * Real clients (OpenAI code backend, openai-python, llm-git) routinely send these and a 400
+ * is a worse outcome than dropping them on the floor.
+ */
+import type {
+	EasyInputMessage,
+	ResponseCreateParams,
+	ResponseFunctionToolCall,
+	ResponseInputContent,
+	ResponseInputItem,
+	ResponseOutputMessage,
+	ResponseReasoningItem,
+	Tool as ResponsesTool,
+} from "openai/resources/responses/responses";
+import * as z from "zod/v4";
+
+// ─── Input content blocks ───────────────────────────────────────────────────
+
+const inputTextSchema = z.object({
+	type: z.literal("input_text"),
+	text: z.string(),
+});
+
+const plainTextSchema = z.object({
+	type: z.literal("text"),
+	text: z.string(),
+});
+
+const inputImageBlockSchema = z
+	.object({
+		type: z.literal("input_image"),
+		detail: z.enum(["auto", "low", "high"]).optional(),
+		image_url: z.string().optional(),
+		file_id: z.string().optional(),
+	})
+	.refine(v => typeof v.image_url === "string" || typeof v.file_id === "string", {
+		message: "input_image requires at least one of `image_url` or `file_id`",
+	});
+
+const inputFileBlockSchema = z.object({
+	type: z.literal("input_file"),
+	file_id: z.string().optional(),
+	filename: z.string().optional(),
+	file_data: z.string().optional(),
+});
+
+const outputTextSchema = z.object({
+	type: z.literal("output_text"),
+	text: z.string(),
+});
+
+const outputRefusalSchema = z.object({
+	type: z.literal("refusal"),
+	refusal: z.string(),
+});
+
+const summaryTextSchema = z.object({
+	type: z.literal("summary_text"),
+	text: z.string(),
+});
+
+const reasoningTextSchema = z.object({
+	type: z.literal("reasoning_text"),
+	text: z.string(),
+});
+
+const inputContentBlockSchema = z.union([
+	inputTextSchema,
+	plainTextSchema,
+	inputImageBlockSchema,
+	inputFileBlockSchema,
+]);
+const outputContentBlockSchema = z.union([outputTextSchema, plainTextSchema, outputRefusalSchema]);
+
+// ─── Input items ────────────────────────────────────────────────────────────
+
+const userMessageItemSchema = z.object({
+	type: z.literal("message").optional(),
+	role: z.union([z.literal("user"), z.literal("developer")]),
+	content: z.union([z.string(), z.array(inputContentBlockSchema)]).optional(),
+});
+
+const systemMessageItemSchema = z.object({
+	type: z.literal("message").optional(),
+	role: z.literal("system"),
+	content: z.union([z.string(), z.array(inputContentBlockSchema)]).optional(),
+});
+
+const assistantMessageItemSchema = z.object({
+	type: z.literal("message").optional(),
+	role: z.literal("assistant"),
+	content: z.union([z.string(), z.array(outputContentBlockSchema)]).optional(),
+});
+
+const reasoningItemSchema = z.object({
+	type: z.literal("reasoning"),
+	id: z.string().optional(),
+	summary: z.array(summaryTextSchema).optional(),
+	content: z.array(reasoningTextSchema).optional(),
+});
+
+const functionCallItemSchema = z.object({
+	type: z.literal("function_call"),
+	id: z.string().optional(),
+	call_id: z.string().min(1),
+	name: z.string().min(1),
+	arguments: z.string().optional(),
+});
+
+const functionCallOutputItemSchema = z.object({
+	type: z.literal("function_call_output"),
+	call_id: z.string().min(1),
+	// OpenAI code backend CLI replays multimodal tool results in array form (text + refusal).
+	output: z.union([z.string(), z.array(outputContentBlockSchema)]).optional(),
+});
+
+const customToolCallItemSchema = z.object({
+	type: z.literal("custom_tool_call"),
+	id: z.string().optional(),
+	call_id: z.string().min(1),
+	name: z.string().min(1),
+	// Raw input string — NOT JSON.stringified. apply_patch flow streams a
+	// freeform body and reading it as JSON would corrupt it.
+	input: z.string(),
+});
+
+const customToolCallOutputItemSchema = z.object({
+	type: z.literal("custom_tool_call_output"),
+	call_id: z.string().min(1),
+	output: z.string(),
+});
+
+/**
+ * An input item is one of the union members below. The convenience shape
+ * `{role, content}` (no `type`) is mapped to "message" before validation in
+ * the walker — schemas here only handle the canonical {type, ...} forms.
+ */
+export const inputItemSchema = z.union([
+	userMessageItemSchema,
+	systemMessageItemSchema,
+	assistantMessageItemSchema,
+	reasoningItemSchema,
+	functionCallItemSchema,
+	functionCallOutputItemSchema,
+	customToolCallItemSchema,
+	customToolCallOutputItemSchema,
+	// Tolerated but not bridged (file_search_call, web_search_call, …).
+	z.object({ type: z.string() }).loose(),
+]);
+
+// Variant types alias the canonical SDK union members so the walker can
+// narrow them cleanly. The convenience "message" shape (no `type` field) maps
+// to EasyInputMessage; the explicit form maps to ResponseInputItem.Message.
+export type OpenAIResponsesUserItem = EasyInputMessage | ResponseInputItem.Message;
+export type OpenAIResponsesSystemItem = EasyInputMessage | ResponseInputItem.Message;
+export type OpenAIResponsesAssistantItem = EasyInputMessage | ResponseOutputMessage;
+export type OpenAIResponsesReasoningItem = ResponseReasoningItem;
+export type OpenAIResponsesFunctionCallItem = ResponseFunctionToolCall;
+export type OpenAIResponsesFunctionCallOutputItem = ResponseInputItem.FunctionCallOutput;
+
+/** Inferred shape of the custom tool call input item (no canonical SDK alias). */
+export type OpenAIResponsesCustomToolCallItem = z.infer<typeof customToolCallItemSchema>;
+export type OpenAIResponsesCustomToolCallOutputItem = z.infer<typeof customToolCallOutputItemSchema>;
+export type OpenAIResponsesInputImageBlock = z.infer<typeof inputImageBlockSchema>;
+export type OpenAIResponsesInputFileBlock = z.infer<typeof inputFileBlockSchema>;
+export type OpenAIResponsesOutputRefusalBlock = z.infer<typeof outputRefusalSchema>;
+
+// ─── Tools ──────────────────────────────────────────────────────────────────
+
+export const toolSchema = z.object({
+	type: z.literal("function"),
+	name: z.string().min(1),
+	description: z.string().optional(),
+	parameters: z.record(z.string(), z.unknown()).optional(),
+	strict: z.boolean().optional(),
+});
+
+// Built-in / hosted tool entries (web_search_preview, file_search, …) — accepted
+// but skipped by the walker.
+const builtinToolSchema = z
+	.object({
+		type: z.string(),
+	})
+	.loose();
+
+// ─── Tool choice ────────────────────────────────────────────────────────────
+
+const hostedToolType = z.enum([
+	"web_search_preview",
+	"file_search",
+	"computer_use_preview",
+	"code_interpreter",
+	"image_generation",
+	"mcp",
+]);
+
+const allowedToolEntrySchema = z.object({
+	type: z.string(),
+	name: z.string().optional(),
+});
+
+export const toolChoiceSchema = z.union([
+	z.literal("auto"),
+	z.literal("none"),
+	z.literal("required"),
+	z.object({
+		type: z.literal("function"),
+		name: z.string().min(1),
+	}),
+	// OpenAI code backend apply_patch flow.
+	z.object({
+		type: z.literal("custom"),
+		name: z.string().min(1),
+	}),
+	// Hosted-tool selection (no extra fields).
+	z.object({
+		type: hostedToolType,
+	}),
+	// `allowed_tools` — walker treats as auto.
+	z.object({
+		type: z.literal("allowed_tools"),
+		mode: z.enum(["auto", "required"]),
+		tools: z.array(allowedToolEntrySchema),
+	}),
+]);
+
+// ─── Reasoning config ───────────────────────────────────────────────────────
+
+export const reasoningConfigSchema = z.object({
+	effort: z.string().optional(),
+	// `none` maps to hideThinkingSummary; auto/concise/detailed mean "show
+	// summary". pi-ai has no per-level plumbing for the latter — walker logs
+	// once and treats them as default.
+	summary: z.enum(["auto", "concise", "detailed", "none"]).optional(),
+});
+
+// ─── Stop ───────────────────────────────────────────────────────────────────
+
+export const stopSchema = z.union([z.string(), z.array(z.string()), z.null()]);
+
+// ─── Top-level request ──────────────────────────────────────────────────────
+
+export const openaiResponsesRequestSchema = z.object({
+	model: z.string().min(1),
+	input: z.union([z.string(), z.array(inputItemSchema)]).optional(),
+	instructions: z.union([z.string(), z.null()]).optional(),
+	tools: z.array(z.union([toolSchema, builtinToolSchema])).optional(),
+	tool_choice: toolChoiceSchema.optional(),
+	max_output_tokens: z.number().optional(),
+	temperature: z.number().optional(),
+	top_p: z.number().optional(),
+	stop: stopSchema.optional(),
+	stream: z.boolean().optional(),
+	reasoning: reasoningConfigSchema.optional(),
+	store: z.boolean().optional(),
+	previous_response_id: z.string().optional(),
+	parallel_tool_calls: z.boolean().optional(),
+	prompt_cache_key: z.string().optional(),
+	metadata: z.unknown().optional(),
+	user: z.string().optional(),
+	service_tier: z.string().optional(),
+	presence_penalty: z.number().optional(),
+	frequency_penalty: z.number().optional(),
+	// Accepted-but-ignored: include `reasoning.encrypted_content` is the canonical
+	// way to request reasoning replay — silently accept and drop.
+	background: z.unknown().optional(),
+	include: z.unknown().optional(),
+	prompt: z.unknown().optional(),
+	safety_identifier: z.unknown().optional(),
+	text: z.unknown().optional(),
+	top_logprobs: z.unknown().optional(),
+	truncation: z.unknown().optional(),
+});
+
+/**
+ * Public types are sourced from the OpenAI SDK so the gateway stays in
+ * lock-step with the canonical API surface; the schemas above are runtime
+ * validators for the subset we actually accept.
+ */
+export type OpenAIResponsesRequest = ResponseCreateParams;
+export type OpenAIResponsesInputItem = ResponseInputItem;
+export type OpenAIResponsesTool = ResponsesTool;
+export type OpenAIResponsesToolChoice = NonNullable<ResponseCreateParams["tool_choice"]>;
+export type OpenAIResponsesInputContent = ResponseInputContent;
+export type OpenAIResponsesOutputContent = ResponseOutputMessage["content"][number];