@oscharko-dev/keiko 0.1.0-beta.0

package/dist/gateway/config.js

@@ -0,0 +1,154 @@
+// Gateway config loading, hand-rolled validation, and redaction-aware serialisation.
+// No schema library: validation is explicit if/throw with actionable messages.
+// API keys are sourced only from environment or the config file, never CLI flags,
+// and are excluded from every serialisation path.
+import { readFileSync } from "node:fs";
+import { findCapability } from "./capabilities.js";
+import { ConfigInvalidError } from "./errors.js";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_RETRY_BASE_DELAY_MS = 500;
+const DEFAULT_FAILURE_THRESHOLD = 5;
+const DEFAULT_COOLDOWN_MS = 30_000;
+const DEFAULT_HALF_OPEN_PROBES = 2;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requirePositiveInt(value, path) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new ConfigInvalidError(`${path} must be a positive integer`);
+    }
+    return value;
+}
+function requireNonEmptyString(value, path) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new ConfigInvalidError(`${path} must be a non-empty string`);
+    }
+    return value;
+}
+// Model id → KEIKO_MODEL_<UPPER>_ form: non-alphanumerics become "_", uppercased.
+function envModelToken(modelId) {
+    return modelId.replace(/[^A-Za-z0-9]/g, "_").toUpperCase();
+}
+function resolveSecret(modelId, fileValue, env, suffix) {
+    const perModel = env[`KEIKO_MODEL_${envModelToken(modelId)}_${suffix}`];
+    if (perModel !== undefined && perModel.length > 0) {
+        return perModel;
+    }
+    if (fileValue.length > 0) {
+        return fileValue;
+    }
+    const fallback = env[`KEIKO_DEFAULT_${suffix}`];
+    return fallback ?? "";
+}
+// Validates a resolved baseUrl for scheme and credential hygiene. Host/IP is
+// intentionally NOT restricted: Keiko addresses customer-internally-hosted endpoints
+// (private IPs are a valid, first-class target); this guard is scheme/credential
+// hygiene + defence-in-depth, not host filtering.
+function isLoopbackHost(hostname) {
+    return (hostname === "localhost" ||
+        hostname === "::1" ||
+        hostname === "[::1]" ||
+        hostname.startsWith("127."));
+}
+function validateBaseUrl(baseUrl, path) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        throw new ConfigInvalidError(`${path}.baseUrl must be a valid absolute URL`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new ConfigInvalidError(`${path}.baseUrl must use the http or https scheme`);
+    }
+    if (url.protocol === "http:" && !isLoopbackHost(url.hostname)) {
+        throw new ConfigInvalidError(`${path}.baseUrl must use https unless it targets localhost or loopback`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new ConfigInvalidError(`${path}.baseUrl must not embed credentials in the URL; provide the key via apiKey`);
+    }
+}
+function parseProvider(raw, index, env) {
+    const path = `providers[${String(index)}]`;
+    if (!isRecord(raw)) {
+        throw new ConfigInvalidError(`${path} must be an object`);
+    }
+    const modelId = requireNonEmptyString(raw.modelId, `${path}.modelId`);
+    if (findCapability(modelId) === undefined) {
+        throw new ConfigInvalidError(`${path}.modelId must be registered in the capability registry`);
+    }
+    const fileBaseUrl = typeof raw.baseUrl === "string" ? raw.baseUrl : "";
+    const fileApiKey = typeof raw.apiKey === "string" ? raw.apiKey : "";
+    const baseUrl = resolveSecret(modelId, fileBaseUrl, env, "BASE_URL");
+    const apiKey = resolveSecret(modelId, fileApiKey, env, "API_KEY");
+    if (baseUrl.length === 0) {
+        throw new ConfigInvalidError(`${path}.baseUrl must be set via config or environment`);
+    }
+    if (apiKey.length === 0) {
+        throw new ConfigInvalidError(`${path}.apiKey must be set via config or environment`);
+    }
+    validateBaseUrl(baseUrl, path);
+    return {
+        modelId,
+        baseUrl,
+        apiKey,
+        timeoutMs: requirePositiveInt(raw.timeoutMs ?? DEFAULT_TIMEOUT_MS, `${path}.timeoutMs`),
+        maxRetries: requireNonNegativeInt(raw.maxRetries ?? DEFAULT_MAX_RETRIES, `${path}.maxRetries`),
+        retryBaseDelayMs: requirePositiveInt(raw.retryBaseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS, `${path}.retryBaseDelayMs`),
+    };
+}
+function requireNonNegativeInt(value, path) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new ConfigInvalidError(`${path} must be a non-negative integer`);
+    }
+    return value;
+}
+function parseCircuitBreaker(raw) {
+    const source = isRecord(raw) ? raw : {};
+    return {
+        failureThreshold: requirePositiveInt(source.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD, "circuitBreaker.failureThreshold"),
+        cooldownMs: requirePositiveInt(source.cooldownMs ?? DEFAULT_COOLDOWN_MS, "circuitBreaker.cooldownMs"),
+        halfOpenProbes: requirePositiveInt(source.halfOpenProbes ?? DEFAULT_HALF_OPEN_PROBES, "circuitBreaker.halfOpenProbes"),
+    };
+}
+export function parseGatewayConfig(raw, env = {}) {
+    if (!isRecord(raw)) {
+        throw new ConfigInvalidError("config root must be a JSON object");
+    }
+    const providersRaw = raw.providers;
+    if (!Array.isArray(providersRaw) || providersRaw.length === 0) {
+        throw new ConfigInvalidError("providers must be a non-empty array");
+    }
+    const providers = providersRaw.map((item, index) => parseProvider(item, index, env));
+    return { providers, circuitBreaker: parseCircuitBreaker(raw.circuitBreaker) };
+}
+export function loadConfigFromFile(path, env = {}) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        throw new ConfigInvalidError(`config file could not be read: ${path}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new ConfigInvalidError(`config file is not valid JSON: ${path}`);
+    }
+    return parseGatewayConfig(parsed, env);
+}
+// Credential- and endpoint-free projection for logging, CLI output, and serialisation.
+export function toSafeObject(config) {
+    return {
+        providers: config.providers.map((provider) => ({
+            modelId: provider.modelId,
+            timeoutMs: provider.timeoutMs,
+            maxRetries: provider.maxRetries,
+            retryBaseDelayMs: provider.retryBaseDelayMs,
+        })),
+        circuitBreaker: config.circuitBreaker,
+    };
+}

package/dist/gateway/errors.d.ts

@@ -0,0 +1,72 @@
+export declare const ERROR_CODES: {
+    readonly AUTHENTICATION: "GATEWAY_AUTHENTICATION";
+    readonly TRANSPORT: "GATEWAY_TRANSPORT";
+    readonly MODEL_REFUSAL: "GATEWAY_MODEL_REFUSAL";
+    readonly MALFORMED_TOOL_CALL: "GATEWAY_MALFORMED_TOOL_CALL";
+    readonly CONTEXT_OVERFLOW: "GATEWAY_CONTEXT_OVERFLOW";
+    readonly RATE_LIMIT: "GATEWAY_RATE_LIMIT";
+    readonly TIMEOUT: "GATEWAY_TIMEOUT";
+    readonly CANCELLED: "GATEWAY_CANCELLED";
+    readonly CIRCUIT_OPEN: "GATEWAY_CIRCUIT_OPEN";
+    readonly PROVIDER_ERROR: "GATEWAY_PROVIDER_ERROR";
+    readonly CONFIG_INVALID: "GATEWAY_CONFIG_INVALID";
+    readonly UNKNOWN_MODEL: "GATEWAY_UNKNOWN_MODEL";
+};
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+export declare abstract class GatewayError extends Error {
+    abstract readonly code: ErrorCode;
+    abstract readonly retryable: boolean;
+    constructor(message: string, secrets?: readonly string[]);
+}
+export declare class AuthenticationError extends GatewayError {
+    readonly code: "GATEWAY_AUTHENTICATION";
+    readonly retryable = false;
+}
+export declare class TransportError extends GatewayError {
+    readonly code: "GATEWAY_TRANSPORT";
+    readonly retryable = true;
+}
+export declare class ModelRefusalError extends GatewayError {
+    readonly code: "GATEWAY_MODEL_REFUSAL";
+    readonly retryable = false;
+}
+export declare class MalformedToolCallError extends GatewayError {
+    readonly code: "GATEWAY_MALFORMED_TOOL_CALL";
+    readonly retryable = false;
+}
+export declare class ContextOverflowError extends GatewayError {
+    readonly code: "GATEWAY_CONTEXT_OVERFLOW";
+    readonly retryable = false;
+}
+export declare class RateLimitError extends GatewayError {
+    readonly code: "GATEWAY_RATE_LIMIT";
+    readonly retryable = true;
+    readonly retryAfterMs: number | null;
+    constructor(message: string, retryAfterMs?: number | null, secrets?: readonly string[]);
+}
+export declare class TimeoutError extends GatewayError {
+    readonly code: "GATEWAY_TIMEOUT";
+    readonly retryable = true;
+}
+export declare class CancelledError extends GatewayError {
+    readonly code: "GATEWAY_CANCELLED";
+    readonly retryable = false;
+}
+export declare class CircuitOpenError extends GatewayError {
+    readonly code: "GATEWAY_CIRCUIT_OPEN";
+    readonly retryable = false;
+}
+export declare class ProviderError extends GatewayError {
+    readonly code: "GATEWAY_PROVIDER_ERROR";
+    readonly retryable = false;
+    readonly httpStatus: number;
+    constructor(message: string, httpStatus: number, secrets?: readonly string[]);
+}
+export declare class ConfigInvalidError extends GatewayError {
+    readonly code: "GATEWAY_CONFIG_INVALID";
+    readonly retryable = false;
+}
+export declare class UnknownModelError extends GatewayError {
+    readonly code: "GATEWAY_UNKNOWN_MODEL";
+    readonly retryable = false;
+}

package/dist/gateway/errors.js

@@ -0,0 +1,82 @@
+// Typed error taxonomy with stable string `code` discriminants. Callers switch on
+// `error.code`; they never parse `error.message`. Every message is redacted at
+// construction so errors are always safe to log.
+import { redact } from "./redaction.js";
+export const ERROR_CODES = {
+    AUTHENTICATION: "GATEWAY_AUTHENTICATION",
+    TRANSPORT: "GATEWAY_TRANSPORT",
+    MODEL_REFUSAL: "GATEWAY_MODEL_REFUSAL",
+    MALFORMED_TOOL_CALL: "GATEWAY_MALFORMED_TOOL_CALL",
+    CONTEXT_OVERFLOW: "GATEWAY_CONTEXT_OVERFLOW",
+    RATE_LIMIT: "GATEWAY_RATE_LIMIT",
+    TIMEOUT: "GATEWAY_TIMEOUT",
+    CANCELLED: "GATEWAY_CANCELLED",
+    CIRCUIT_OPEN: "GATEWAY_CIRCUIT_OPEN",
+    PROVIDER_ERROR: "GATEWAY_PROVIDER_ERROR",
+    CONFIG_INVALID: "GATEWAY_CONFIG_INVALID",
+    UNKNOWN_MODEL: "GATEWAY_UNKNOWN_MODEL",
+};
+export class GatewayError extends Error {
+    constructor(message, secrets = []) {
+        super(redact(message, secrets));
+        this.name = new.target.name;
+    }
+}
+export class AuthenticationError extends GatewayError {
+    code = ERROR_CODES.AUTHENTICATION;
+    retryable = false;
+}
+export class TransportError extends GatewayError {
+    code = ERROR_CODES.TRANSPORT;
+    retryable = true;
+}
+export class ModelRefusalError extends GatewayError {
+    code = ERROR_CODES.MODEL_REFUSAL;
+    retryable = false;
+}
+export class MalformedToolCallError extends GatewayError {
+    code = ERROR_CODES.MALFORMED_TOOL_CALL;
+    retryable = false;
+}
+export class ContextOverflowError extends GatewayError {
+    code = ERROR_CODES.CONTEXT_OVERFLOW;
+    retryable = false;
+}
+export class RateLimitError extends GatewayError {
+    code = ERROR_CODES.RATE_LIMIT;
+    retryable = true;
+    retryAfterMs;
+    constructor(message, retryAfterMs = null, secrets = []) {
+        super(message, secrets);
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+export class TimeoutError extends GatewayError {
+    code = ERROR_CODES.TIMEOUT;
+    retryable = true;
+}
+export class CancelledError extends GatewayError {
+    code = ERROR_CODES.CANCELLED;
+    retryable = false;
+}
+export class CircuitOpenError extends GatewayError {
+    code = ERROR_CODES.CIRCUIT_OPEN;
+    retryable = false;
+}
+export class ProviderError extends GatewayError {
+    code = ERROR_CODES.PROVIDER_ERROR;
+    retryable = false;
+    httpStatus;
+    constructor(message, httpStatus, secrets = []) {
+        super(message, secrets);
+        this.httpStatus = httpStatus;
+    }
+}
+export class ConfigInvalidError extends GatewayError {
+    code = ERROR_CODES.CONFIG_INVALID;
+    retryable = false;
+}
+export class UnknownModelError extends GatewayError {
+    code = ERROR_CODES.UNKNOWN_MODEL;
+    retryable = false;
+}

package/dist/gateway/gateway.d.ts

@@ -0,0 +1,19 @@
+import type { Clock, CircuitBreakerStatus, GatewayConfig, GatewayRequest, NormalizedResponse, ProviderAdapter } from "./types.js";
+export interface GatewayDeps {
+    readonly adapter?: ProviderAdapter | undefined;
+    readonly clock?: Clock | undefined;
+}
+export declare class Gateway {
+    private readonly config;
+    private readonly clock;
+    private readonly adapter;
+    private readonly providers;
+    private readonly breakers;
+    constructor(config: GatewayConfig, deps?: GatewayDeps);
+    chat(request: GatewayRequest): Promise<NormalizedResponse>;
+    circuitStatus(modelId: string): CircuitBreakerStatus;
+    private invoke;
+    private route;
+    private breakerFor;
+    private adapterFor;
+}

package/dist/gateway/gateway.js

@@ -0,0 +1,94 @@
+// Orchestrator: routes a request through the capability registry, then through the
+// circuit breaker, bounded retry, and the provider adapter. Usage metadata
+// (request id, latency, cost class) is owned by the gateway, not the provider, so
+// the audit ledger (issue #10) has a reliable typed target on every response.
+import { randomUUID } from "node:crypto";
+import { findCapability } from "./capabilities.js";
+import { UnknownModelError } from "./errors.js";
+import { OpenAiAdapter } from "./openai-adapter.js";
+import { CircuitBreaker, executeWithRetry, systemClock } from "./resilience.js";
+export class Gateway {
+    config;
+    clock;
+    adapter;
+    providers;
+    breakers = new Map();
+    constructor(config, deps = {}) {
+        this.config = config;
+        this.clock = deps.clock ?? systemClock;
+        this.adapter = deps.adapter;
+        this.providers = new Map(config.providers.map((p) => [p.modelId, p]));
+    }
+    async chat(request) {
+        const route = this.route(request.modelId);
+        const breaker = this.breakerFor(route.provider);
+        const requestId = randomUUID();
+        const start = this.clock.now();
+        const adapter = this.adapterFor(requestId, route.capability);
+        const result = await executeWithRetry((attemptTimeoutMs) => this.invoke(breaker, adapter, request, {
+            ...route.provider,
+            ...(attemptTimeoutMs === undefined ? {} : { timeoutMs: attemptTimeoutMs }),
+        }), route.provider, this.clock, request.cancellationSignal);
+        return {
+            ...result,
+            usage: {
+                ...result.usage,
+                requestId,
+                latencyMs: Math.max(1, this.clock.now() - start),
+                costClass: route.capability.costClass,
+            },
+        };
+    }
+    circuitStatus(modelId) {
+        const breaker = this.breakers.get(modelId);
+        return (breaker?.status(modelId) ?? {
+            modelId,
+            state: "closed",
+            consecutiveFailures: 0,
+            openedAt: null,
+        });
+    }
+    async invoke(breaker, adapter, request, provider) {
+        breaker.assertAllowed();
+        try {
+            const response = await adapter.call(request, provider);
+            breaker.recordSuccess();
+            return response;
+        }
+        catch (error) {
+            breaker.recordFailure();
+            throw error;
+        }
+    }
+    route(modelId) {
+        const provider = this.providers.get(modelId);
+        if (provider === undefined) {
+            throw new UnknownModelError(`no provider configured for model '${modelId}'`);
+        }
+        const capability = findCapability(modelId);
+        if (capability === undefined) {
+            throw new UnknownModelError(`model '${modelId}' is not in the capability registry`);
+        }
+        if (capability.kind !== "chat") {
+            throw new UnknownModelError(`model '${modelId}' has kind '${capability.kind}'; the chat path requires a chat model`);
+        }
+        return { provider, capability };
+    }
+    breakerFor(provider) {
+        const existing = this.breakers.get(provider.modelId);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const breaker = new CircuitBreaker(provider.modelId, this.config.circuitBreaker, this.clock);
+        this.breakers.set(provider.modelId, breaker);
+        return breaker;
+    }
+    adapterFor(requestId, capability) {
+        return (this.adapter ??
+            new OpenAiAdapter({
+                requestId,
+                costClass: capability.costClass,
+                now: this.clock.now,
+            }));
+    }
+}

package/dist/gateway/index.d.ts

@@ -0,0 +1,10 @@
+export type { CircuitBreakerConfig, CircuitBreakerStatus, CircuitState, ChatMessage, Clock, CostClass, FinishReason, GatewayConfig, GatewayRequest, LatencyClass, ModelCapability, ModelKind, ModelProviderConfig, NormalizedResponse, NormalizedToolCall, ProviderAdapter, ResponseFormat, StreamDelta, StreamEvent, ToolDefinition, UsageMetadata, } from "./types.js";
+export { CAPABILITY_REGISTRY, findCapability, listCapabilities, selectCheapest, type CapabilityQuery, } from "./capabilities.js";
+export { loadConfigFromFile, parseGatewayConfig, toSafeObject, type EnvSource, type SafeGatewayConfig, type SafeProviderConfig, } from "./config.js";
+export { Gateway, type GatewayDeps } from "./gateway.js";
+export { OpenAiAdapter, type AdapterDeps } from "./openai-adapter.js";
+export { assertConfiguredModel, selectConfiguredModel, type ModelSelectionQuery, } from "./model-selection.js";
+export { CircuitBreaker, executeWithRetry, systemClock, type RetryConfig } from "./resilience.js";
+export { normalizeChatResponse, type UsageSeed } from "./normalize.js";
+export { redact } from "./redaction.js";
+export { AuthenticationError, CancelledError, CircuitOpenError, ConfigInvalidError, ContextOverflowError, ERROR_CODES, GatewayError, MalformedToolCallError, ModelRefusalError, ProviderError, RateLimitError, TimeoutError, TransportError, UnknownModelError, type ErrorCode, } from "./errors.js";

package/dist/gateway/index.js

@@ -0,0 +1,11 @@
+// Public barrel for the model gateway: all types, the Gateway orchestrator, the
+// capability registry helpers, config loaders, and the typed error taxonomy.
+export { CAPABILITY_REGISTRY, findCapability, listCapabilities, selectCheapest, } from "./capabilities.js";
+export { loadConfigFromFile, parseGatewayConfig, toSafeObject, } from "./config.js";
+export { Gateway } from "./gateway.js";
+export { OpenAiAdapter } from "./openai-adapter.js";
+export { assertConfiguredModel, selectConfiguredModel, } from "./model-selection.js";
+export { CircuitBreaker, executeWithRetry, systemClock } from "./resilience.js";
+export { normalizeChatResponse } from "./normalize.js";
+export { redact } from "./redaction.js";
+export { AuthenticationError, CancelledError, CircuitOpenError, ConfigInvalidError, ContextOverflowError, ERROR_CODES, GatewayError, MalformedToolCallError, ModelRefusalError, ProviderError, RateLimitError, TimeoutError, TransportError, UnknownModelError, } from "./errors.js";

package/dist/gateway/model-selection.d.ts

@@ -0,0 +1,9 @@
+import type { GatewayConfig, ModelKind } from "./types.js";
+export interface ModelSelectionQuery {
+    readonly kind: ModelKind;
+    readonly toolCalling?: boolean | undefined;
+    readonly structuredOutput?: boolean | undefined;
+    readonly minContextWindow?: number | undefined;
+}
+export declare function assertConfiguredModel(config: GatewayConfig, modelId: string): void;
+export declare function selectConfiguredModel(config: GatewayConfig, query: ModelSelectionQuery): string | undefined;

package/dist/gateway/model-selection.js

@@ -0,0 +1,36 @@
+import { listCapabilities } from "./capabilities.js";
+import { ConfigInvalidError } from "./errors.js";
+const COST_RANK = { low: 0, medium: 1, high: 2 };
+function matches(capability, query) {
+    if (capability.kind !== query.kind) {
+        return false;
+    }
+    if (query.toolCalling === true && !capability.toolCalling) {
+        return false;
+    }
+    if (query.structuredOutput === true && !capability.structuredOutput) {
+        return false;
+    }
+    if (query.minContextWindow !== undefined && capability.contextWindow < query.minContextWindow) {
+        return false;
+    }
+    return true;
+}
+export function assertConfiguredModel(config, modelId) {
+    if (!config.providers.some((provider) => provider.modelId === modelId)) {
+        throw new ConfigInvalidError(`model '${modelId}' is not configured as a provider`);
+    }
+}
+export function selectConfiguredModel(config, query) {
+    const configured = new Set(config.providers.map((provider) => provider.modelId));
+    let best;
+    for (const capability of listCapabilities()) {
+        if (!configured.has(capability.id) || !matches(capability, query)) {
+            continue;
+        }
+        if (best === undefined || COST_RANK[capability.costClass] < COST_RANK[best.costClass]) {
+            best = capability;
+        }
+    }
+    return best?.id;
+}

package/dist/gateway/normalize.d.ts

@@ -0,0 +1,7 @@
+import type { CostClass, NormalizedResponse } from "./types.js";
+export interface UsageSeed {
+    readonly requestId: string;
+    readonly latencyMs: number;
+    readonly costClass: CostClass;
+}
+export declare function normalizeChatResponse(rawPayload: unknown, modelId: string, seed: UsageSeed, expectStructured?: boolean): NormalizedResponse;

package/dist/gateway/normalize.js

@@ -0,0 +1,93 @@
+// Provider payload → NormalizedResponse. The internal contract is strict and small
+// so workflows fail closed when a provider response is unsafe or malformed.
+import { MalformedToolCallError, ModelRefusalError } from "./errors.js";
+const FINISH_REASONS = new Set([
+    "stop",
+    "tool_calls",
+    "length",
+    "content_filter",
+    "error",
+    "cancelled",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asCount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+function mapFinishReason(value) {
+    return typeof value === "string" && FINISH_REASONS.has(value)
+        ? value
+        : "stop";
+}
+function buildUsage(payload, seed) {
+    const usage = isRecord(payload.usage) ? payload.usage : {};
+    return {
+        requestId: seed.requestId,
+        promptTokens: asCount(usage.prompt_tokens),
+        completionTokens: asCount(usage.completion_tokens),
+        latencyMs: seed.latencyMs,
+        costClass: seed.costClass,
+    };
+}
+function parseToolCall(raw) {
+    if (!isRecord(raw) || !isRecord(raw.function)) {
+        throw new MalformedToolCallError("tool call is missing a function descriptor");
+    }
+    const fn = raw.function;
+    const name = typeof fn.name === "string" ? fn.name : "";
+    const id = typeof raw.id === "string" ? raw.id : "";
+    const argsText = typeof fn.arguments === "string" ? fn.arguments : "{}";
+    let parsed;
+    try {
+        parsed = JSON.parse(argsText);
+    }
+    catch {
+        throw new MalformedToolCallError(`tool call '${name}' has non-JSON arguments`);
+    }
+    if (!isRecord(parsed)) {
+        throw new MalformedToolCallError(`tool call '${name}' arguments are not an object`);
+    }
+    return { id, name, arguments: parsed };
+}
+function parseToolCalls(message) {
+    const raw = message.tool_calls;
+    return Array.isArray(raw) ? raw.map(parseToolCall) : [];
+}
+function parseStructuredOutput(content) {
+    try {
+        const parsed = JSON.parse(content);
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function assertNotRefusal(message, finishReason) {
+    if (finishReason === "content_filter") {
+        throw new ModelRefusalError("provider filtered the model response");
+    }
+    const refusal = message.refusal;
+    if (typeof refusal === "string" && refusal.length > 0) {
+        throw new ModelRefusalError("provider refused the model request");
+    }
+}
+function firstChoice(payload) {
+    const choices = payload.choices;
+    if (!Array.isArray(choices) || choices.length === 0) {
+        return undefined;
+    }
+    return isRecord(choices[0]) ? choices[0] : undefined;
+}
+export function normalizeChatResponse(rawPayload, modelId, seed, expectStructured = false) {
+    const payload = isRecord(rawPayload) ? rawPayload : {};
+    const usage = buildUsage(payload, seed);
+    const choice = firstChoice(payload);
+    const message = choice !== undefined && isRecord(choice.message) ? choice.message : {};
+    const finishReason = mapFinishReason(choice?.finish_reason);
+    assertNotRefusal(message, finishReason);
+    const toolCalls = parseToolCalls(message);
+    const content = typeof message.content === "string" ? message.content : "";
+    const structuredOutput = expectStructured && content.length > 0 ? parseStructuredOutput(content) : null;
+    return { modelId, content, finishReason, toolCalls, structuredOutput, usage };
+}

package/dist/gateway/openai-adapter.d.ts

@@ -0,0 +1,20 @@
+import type { CostClass, GatewayRequest, ModelProviderConfig, NormalizedResponse, ProviderAdapter } from "./types.js";
+export interface AdapterDeps {
+    readonly fetchImpl?: typeof fetch | undefined;
+    readonly requestId: string;
+    readonly costClass: CostClass;
+    readonly now?: (() => number) | undefined;
+}
+export declare class OpenAiAdapter implements ProviderAdapter {
+    private readonly deps;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly useBundledCaFallback;
+    constructor(deps: AdapterDeps);
+    call: (request: GatewayRequest, config: ModelProviderConfig) => Promise<NormalizedResponse>;
+    private dispatch;
+    private dispatchWithBundledCa;
+    private mapDispatchError;
+    private readBody;
+    private readErrorBody;
+}