@x12i/ai-gateway 10.3.1 → 10.4.0

package/dist-cjs/openrouter-runtime-adapter/map-server-tools.cjs

@@ -0,0 +1,143 @@
+function mapWebSearch(src) {
+    if (!src)
+        return undefined;
+    return {
+        mode: src.mode,
+        engine: src.engine,
+        maxResults: src.maxResults,
+        maxTotalResults: src.maxTotalResults,
+        searchContextSize: src.searchContextSize,
+        allowedDomains: src.allowedDomains,
+        excludedDomains: src.excludedDomains,
+        userLocation: src.userLocation,
+        requireCitations: src.requireCitations,
+        onFailure: src.onFailure,
+    };
+}
+function mapWebFetch(src) {
+    if (!src)
+        return undefined;
+    return {
+        mode: src.mode,
+        engine: src.engine,
+        maxUses: src.maxUses,
+        maxContentTokens: src.maxContentTokens,
+        allowedDomains: src.allowedDomains,
+        blockedDomains: src.blockedDomains,
+        onFailure: src.onFailure,
+    };
+}
+function mapDatetime(src) {
+    if (!src)
+        return undefined;
+    return { mode: src.mode, timezone: src.timezone };
+}
+function mapImageGeneration(src) {
+    if (!src)
+        return undefined;
+    return {
+        mode: src.mode,
+        model: src.model,
+        quality: src.quality,
+        size: src.size,
+        aspectRatio: src.aspectRatio,
+        background: src.background,
+        outputFormat: src.outputFormat,
+        outputCompression: src.outputCompression,
+        moderation: src.moderation,
+    };
+}
+function mapApplyPatch(src) {
+    if (!src)
+        return undefined;
+    return {
+        mode: src.mode,
+        behavior: src.behavior ?? 'return_only',
+        workspaceRoot: src.workspaceRoot,
+        allowDelete: src.allowDelete,
+        allowCreate: src.allowCreate,
+        allowUpdate: src.allowUpdate,
+    };
+}
+function mapFusion(src) {
+    if (!src)
+        return undefined;
+    return {
+        mode: src.mode,
+        analysisModels: src.analysisModels,
+        judgeModel: src.judgeModel,
+        maxToolCalls: src.maxToolCalls,
+        maxCompletionTokens: src.maxCompletionTokens,
+        reasoning: src.reasoning,
+        temperature: src.temperature,
+    };
+}
+function mapNestedTools(tools) {
+    if (!tools?.length)
+        return undefined;
+    return tools.map((t) => ({ type: t.type, parameters: t.parameters }));
+}
+function mapAdvisor(src) {
+    if (!src)
+        return undefined;
+    const mapOne = (a) => ({
+        mode: a.mode,
+        name: a.name,
+        model: a.model,
+        instructions: a.instructions,
+        tools: mapNestedTools(a.tools),
+        forwardTranscript: a.forwardTranscript,
+        stream: a.stream,
+        maxToolCalls: a.maxToolCalls,
+        maxCompletionTokens: a.maxCompletionTokens,
+        reasoning: a.reasoning,
+        temperature: a.temperature,
+    });
+    if (Array.isArray(src))
+        return src.map(mapOne);
+    return mapOne(src);
+}
+function mapSubagent(src) {
+    if (!src)
+        return undefined;
+    return {
+        mode: src.mode,
+        model: src.model,
+        instructions: src.instructions,
+        tools: mapNestedTools(src.tools),
+        maxToolCalls: src.maxToolCalls,
+        maxCompletionTokens: src.maxCompletionTokens,
+        reasoning: src.reasoning,
+        temperature: src.temperature,
+    };
+}
+export function mapGatewayServerTools(config) {
+    if (!config)
+        return undefined;
+    const out = {};
+    const webSearch = mapWebSearch(config.webSearch);
+    const webFetch = mapWebFetch(config.webFetch);
+    const datetime = mapDatetime(config.datetime);
+    const imageGeneration = mapImageGeneration(config.imageGeneration);
+    const applyPatch = mapApplyPatch(config.applyPatch);
+    const fusion = mapFusion(config.fusion);
+    const advisor = mapAdvisor(config.advisor);
+    const subagent = mapSubagent(config.subagent);
+    if (webSearch)
+        out.webSearch = webSearch;
+    if (webFetch)
+        out.webFetch = webFetch;
+    if (datetime)
+        out.datetime = datetime;
+    if (imageGeneration)
+        out.imageGeneration = imageGeneration;
+    if (applyPatch)
+        out.applyPatch = applyPatch;
+    if (fusion)
+        out.fusion = fusion;
+    if (advisor)
+        out.advisor = advisor;
+    if (subagent)
+        out.subagent = subagent;
+    return Object.keys(out).length ? out : undefined;
+}

package/dist-cjs/openrouter-runtime-adapter/map-server-tools.d.ts

@@ -0,0 +1,3 @@
+import type { GatewayServerToolsConfig } from '../types.js';
+import type { RuntimeServerToolsPolicy } from '@x12i/openrouter-runtime';
+export declare function mapGatewayServerTools(config?: GatewayServerToolsConfig): RuntimeServerToolsPolicy | undefined;

package/dist-cjs/openrouter-runtime-adapter/map-trace.cjs

@@ -0,0 +1,45 @@
+export function buildTraceAttemptOpenRouterRuntimeSlice(metadata) {
+    if (!metadata.openrouterRuntime && !metadata.serverTools)
+        return undefined;
+    return {
+        apiMode: metadata.openrouterRuntime?.apiMode,
+        serverTools: metadata.serverTools,
+        citationCount: metadata.citations?.length ?? 0,
+        generatedImageCount: metadata.generatedImages?.length ?? 0,
+        patchProposalCount: metadata.patchProposals?.length ?? 0,
+    };
+}
+export function enrichTraceOpenRouterRuntimeMetadata(base, metadata, traceEnabled) {
+    if (!traceEnabled && !base)
+        return base;
+    const merged = {
+        apiMode: base?.apiMode ?? metadata.openrouterRuntime?.apiMode ?? 'chat',
+        warnings: base?.warnings ?? metadata.openrouterRuntime?.warnings ?? [],
+        policyViolations: base?.policyViolations ?? metadata.openrouterRuntime?.policyViolations ?? [],
+        requestIds: base?.requestIds ?? metadata.openrouterRuntime?.requestIds,
+    };
+    if (traceEnabled) {
+        merged.serverToolsRequested = metadata.serverTools;
+        merged.serverToolsUsed = metadata.serverTools;
+        merged.citations = metadata.citations;
+        merged.generatedImages = metadata.generatedImages;
+        merged.patchProposals = metadata.patchProposals;
+    }
+    return merged;
+}
+export function redactRawOpenRouterPayload(raw, maxChars = 32_000) {
+    if (raw == null)
+        return raw;
+    try {
+        const text = JSON.stringify(raw);
+        const redacted = text
+            .replace(/"(Authorization|authorization|api[_-]?key)"\s*:\s*"[^"]*"/gi, '"$1":"[REDACTED]"')
+            .replace(/Bearer\s+[A-Za-z0-9._-]+/g, 'Bearer [REDACTED]');
+        if (redacted.length <= maxChars)
+            return JSON.parse(redacted);
+        return { truncated: true, preview: redacted.slice(0, maxChars) };
+    }
+    catch {
+        return { truncated: true };
+    }
+}

package/dist-cjs/openrouter-runtime-adapter/map-trace.d.ts

@@ -0,0 +1,5 @@
+import type { GatewayTraceAttempt, GatewayOpenRouterRuntimeMetadata } from '../types.js';
+import type { OpenRouterRuntimeRouterMetadata } from './map-runtime-response.js';
+export declare function buildTraceAttemptOpenRouterRuntimeSlice(metadata: OpenRouterRuntimeRouterMetadata): GatewayTraceAttempt['openrouterRuntime'];
+export declare function enrichTraceOpenRouterRuntimeMetadata(base: GatewayOpenRouterRuntimeMetadata | undefined, metadata: OpenRouterRuntimeRouterMetadata, traceEnabled: boolean): GatewayOpenRouterRuntimeMetadata | undefined;
+export declare function redactRawOpenRouterPayload(raw: unknown, maxChars?: number): unknown;

package/dist-cjs/openrouter-runtime-adapter/register-openrouter-runtime.cjs

@@ -0,0 +1,14 @@
+import { createOpenRouterRuntimeAdapter } from './create-openrouter-runtime-adapter.js';
+import { createOpenRouterRuntimeProvider } from './create-openrouter-runtime-provider.js';
+export function registerOpenRouterRuntime(router, options) {
+    const { apiKey, logger } = options;
+    const provider = createOpenRouterRuntimeProvider({ apiKey, logger });
+    router.registerProvider(provider);
+    const adapter = createOpenRouterRuntimeAdapter();
+    router.getAdapterRegistry().register(adapter);
+    logger?.info('Registered OpenRouter runtime provider and adapter', {
+        provider: 'openrouter',
+        runtimeEnabled: true,
+    });
+}
+export { shouldUseOpenRouterRuntime, resolveOpenRouterRuntimeDefaults } from './should-use-openrouter-runtime.js';

package/dist-cjs/openrouter-runtime-adapter/register-openrouter-runtime.d.ts

@@ -0,0 +1,10 @@
+import type { LLMProviderRouter } from '@x12i/ai-providers-router';
+import type { Logxer } from '@x12i/logxer';
+import type { GatewayOpenRouterRuntimeConfig } from '../types.js';
+export type RegisterOpenRouterRuntimeOptions = {
+    apiKey: string;
+    logger?: Logxer;
+    runtimeConfig?: GatewayOpenRouterRuntimeConfig;
+};
+export declare function registerOpenRouterRuntime(router: LLMProviderRouter, options: RegisterOpenRouterRuntimeOptions): void;
+export { shouldUseOpenRouterRuntime, resolveOpenRouterRuntimeDefaults } from './should-use-openrouter-runtime.js';

package/dist-cjs/openrouter-runtime-adapter/should-use-openrouter-runtime.cjs

@@ -0,0 +1,29 @@
+/**
+ * Whether the gateway should register @x12i/openrouter-runtime instead of the router's legacy OpenRouter provider.
+ *
+ * - AI_GATEWAY_USE_LEGACY_OPENROUTER=1 → legacy router OpenRouter
+ * - AI_GATEWAY_USE_OPENROUTER_RUNTIME=0 → legacy
+ * - GatewayConfig.openrouterRuntime.enabled=false → legacy
+ * - default → runtime enabled
+ */
+export function shouldUseOpenRouterRuntime(config) {
+    const legacyEnv = process.env.AI_GATEWAY_USE_LEGACY_OPENROUTER;
+    if (legacyEnv === '1' || legacyEnv === 'true') {
+        return false;
+    }
+    const runtimeEnv = process.env.AI_GATEWAY_USE_OPENROUTER_RUNTIME;
+    if (runtimeEnv === '0' || runtimeEnv === 'false') {
+        return false;
+    }
+    if (config?.openrouterRuntime?.enabled === false) {
+        return false;
+    }
+    return true;
+}
+export function resolveOpenRouterRuntimeDefaults(config) {
+    const rt = config?.openrouterRuntime;
+    return {
+        apiMode: rt?.apiMode ?? 'auto',
+        includeRawInTrace: rt?.includeRawInTrace ?? false,
+    };
+}

package/dist-cjs/openrouter-runtime-adapter/should-use-openrouter-runtime.d.ts

@@ -0,0 +1,14 @@
+import type { GatewayConfig } from '../types.js';
+/**
+ * Whether the gateway should register @x12i/openrouter-runtime instead of the router's legacy OpenRouter provider.
+ *
+ * - AI_GATEWAY_USE_LEGACY_OPENROUTER=1 → legacy router OpenRouter
+ * - AI_GATEWAY_USE_OPENROUTER_RUNTIME=0 → legacy
+ * - GatewayConfig.openrouterRuntime.enabled=false → legacy
+ * - default → runtime enabled
+ */
+export declare function shouldUseOpenRouterRuntime(config?: GatewayConfig): boolean;
+export declare function resolveOpenRouterRuntimeDefaults(config?: GatewayConfig): {
+    apiMode: 'chat' | 'responses' | 'auto';
+    includeRawInTrace: boolean;
+};

package/dist-cjs/openrouter-runtime-adapter/validate-server-tools.cjs

@@ -0,0 +1,151 @@
+import { GatewayValidationError, ProviderConfigError, } from '../instruction-errors.js';
+const TOOL_KEYS = [
+    'webSearch',
+    'webFetch',
+    'datetime',
+    'imageGeneration',
+    'applyPatch',
+    'fusion',
+    'advisor',
+    'subagent',
+];
+function getToolMode(serverTools, key) {
+    const tool = serverTools?.[key];
+    if (!tool)
+        return undefined;
+    if (Array.isArray(tool)) {
+        return tool.some((t) => t.mode === 'required')
+            ? 'required'
+            : tool.some((t) => t.mode === 'allowed')
+                ? 'allowed'
+                : 'disabled';
+    }
+    return tool.mode;
+}
+export function hasAnyServerToolMode(serverTools, mode) {
+    if (!serverTools)
+        return false;
+    for (const key of TOOL_KEYS) {
+        const m = getToolMode(serverTools, key);
+        if (m === mode)
+            return true;
+    }
+    return false;
+}
+export function hasAnyActiveServerTool(serverTools) {
+    if (!serverTools)
+        return false;
+    for (const key of TOOL_KEYS) {
+        const m = getToolMode(serverTools, key);
+        if (m === 'allowed' || m === 'required')
+            return true;
+    }
+    return false;
+}
+export function hasRequiredServerTool(serverTools) {
+    return hasAnyServerToolMode(serverTools, 'required');
+}
+function resolveEffectiveApiMode(openrouter, serverTools) {
+    if (openrouter?.apiMode)
+        return openrouter.apiMode;
+    const applyPatch = serverTools?.applyPatch;
+    if (applyPatch && applyPatch.mode !== 'disabled')
+        return 'auto';
+    return 'auto';
+}
+export function validateApplyPatchConfig(serverTools, openrouter) {
+    const applyPatch = serverTools?.applyPatch;
+    if (!applyPatch || applyPatch.mode === 'disabled')
+        return;
+    if (applyPatch.behavior === 'apply_with_callback') {
+        throw new GatewayValidationError('PATCH_APPLIER_REQUIRED', 'applyPatch behavior apply_with_callback is not supported by ai-gateway; use return_only');
+    }
+    const apiMode = resolveEffectiveApiMode(openrouter, serverTools);
+    if (apiMode === 'chat') {
+        throw new GatewayValidationError('APPLY_PATCH_REQUIRES_RESPONSES_API', 'applyPatch requires openrouter.apiMode = "responses" or auto mode resolving to responses');
+    }
+}
+export function applyPostRoutingServerToolsPolicy(input) {
+    const warnings = [];
+    const { serverTools, openrouter, openRouterApiKey } = input;
+    let provider = input.provider?.toLowerCase();
+    if (!hasAnyActiveServerTool(serverTools)) {
+        return { serverTools, warnings, forceOpenRouter: false };
+    }
+    validateApplyPatchConfig(serverTools, openrouter);
+    if (hasRequiredServerTool(serverTools)) {
+        if (!openRouterApiKey) {
+            throw new ProviderConfigError('OPENROUTER_SERVER_TOOL_REQUIRES_KEY', 'Required OpenRouter server tools need OPENROUTER_API_KEY or GatewayConfig.openrouter.apiKey');
+        }
+        if (provider !== 'openrouter') {
+            provider = 'openrouter';
+            return { serverTools, warnings, forceOpenRouter: true };
+        }
+        return { serverTools, warnings, forceOpenRouter: false };
+    }
+    if (provider !== 'openrouter') {
+        warnings.push({
+            code: 'SERVER_TOOLS_IGNORED_FOR_NON_OPENROUTER_PROVIDER',
+            message: 'OpenRouter server tools were requested but the final provider is not openrouter; tools were stripped',
+        });
+        return { serverTools: undefined, warnings, forceOpenRouter: false };
+    }
+    return { serverTools, warnings, forceOpenRouter: false };
+}
+export function applyOnlineVariantMigration(model, serverTools) {
+    if (!model.endsWith(':online')) {
+        return { model, serverTools };
+    }
+    const stripped = model.slice(0, -':online'.length);
+    const merged = { ...(serverTools ?? {}) };
+    if (!merged.webSearch) {
+        merged.webSearch = { mode: 'allowed' };
+    }
+    return {
+        model: stripped,
+        serverTools: merged,
+        warning: {
+            code: 'OPENROUTER_ONLINE_VARIANT_DEPRECATED',
+            message: `Model suffix :online is deprecated; stripped to "${stripped}" and enabled webSearch.mode=allowed`,
+        },
+    };
+}
+export function mergeServerToolsConfig(...layers) {
+    const out = {};
+    for (const layer of layers) {
+        if (!layer)
+            continue;
+        for (const key of TOOL_KEYS) {
+            const val = layer[key];
+            if (val !== undefined) {
+                out[key] = val;
+            }
+        }
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+export function mergeOpenRouterConfig(...layers) {
+    const out = {};
+    for (const layer of layers) {
+        if (!layer)
+            continue;
+        if (layer.apiMode !== undefined)
+            out.apiMode = layer.apiMode;
+        if (layer.includeRawInTrace !== undefined)
+            out.includeRawInTrace = layer.includeRawInTrace;
+        if (layer.rawOverrides !== undefined) {
+            out.rawOverrides = { ...(out.rawOverrides ?? {}), ...layer.rawOverrides };
+        }
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/** Default applyPatch behavior when not specified. */
+export function normalizeApplyPatchDefaults(serverTools) {
+    if (!serverTools?.applyPatch)
+        return serverTools;
+    const applyPatch = {
+        behavior: 'return_only',
+        ...serverTools.applyPatch,
+    };
+    return { ...serverTools, applyPatch };
+}

package/dist-cjs/openrouter-runtime-adapter/validate-server-tools.d.ts

@@ -0,0 +1,30 @@
+import type { GatewayOpenRouterConfig, GatewayServerToolsConfig } from '../types.js';
+export type ServerToolValidationWarning = {
+    code: string;
+    message: string;
+};
+export declare function hasAnyServerToolMode(serverTools: GatewayServerToolsConfig | undefined, mode: 'allowed' | 'required'): boolean;
+export declare function hasAnyActiveServerTool(serverTools?: GatewayServerToolsConfig): boolean;
+export declare function hasRequiredServerTool(serverTools?: GatewayServerToolsConfig): boolean;
+export declare function validateApplyPatchConfig(serverTools: GatewayServerToolsConfig | undefined, openrouter: GatewayOpenRouterConfig | undefined): void;
+export type PostRoutingServerToolsResult = {
+    serverTools?: GatewayServerToolsConfig;
+    warnings: ServerToolValidationWarning[];
+    forceOpenRouter: boolean;
+};
+export declare function applyPostRoutingServerToolsPolicy(input: {
+    provider: string | undefined;
+    serverTools?: GatewayServerToolsConfig;
+    openrouter?: GatewayOpenRouterConfig;
+    openRouterApiKey?: string;
+}): PostRoutingServerToolsResult;
+export type OnlineVariantMigrationResult = {
+    model: string;
+    serverTools?: GatewayServerToolsConfig;
+    warning?: ServerToolValidationWarning;
+};
+export declare function applyOnlineVariantMigration(model: string, serverTools?: GatewayServerToolsConfig): OnlineVariantMigrationResult;
+export declare function mergeServerToolsConfig(...layers: (GatewayServerToolsConfig | undefined)[]): GatewayServerToolsConfig | undefined;
+export declare function mergeOpenRouterConfig(...layers: (GatewayOpenRouterConfig | undefined)[]): GatewayOpenRouterConfig | undefined;
+/** Default applyPatch behavior when not specified. */
+export declare function normalizeApplyPatchDefaults(serverTools?: GatewayServerToolsConfig): GatewayServerToolsConfig | undefined;