@x12i/ai-gateway 11.0.0 → 11.0.1

package/README.md

@@ -463,14 +463,14 @@ At invoke, gateway merges server-tool intent in this order (later wins):
 2. `request.config.serverTools` / `request.config.openrouter`
 3. `request.modelConfig.serverTools` / `request.modelConfig.openrouter`
 
-Gateway then applies **post-routing policy** internally (`applyPostRoutingServerToolsPolicy`): required tools force `provider=openrouter`; `allowed` tools on non-OpenRouter providers are stripped with a warning. **Do not duplicate post-routing policy in consumers** — merge pre-invoke intent only.
+Gateway then applies **post-routing policy** internally (`applyPostRoutingServerToolsPolicy`): any active server tool (`allowed` or `required`) forces `provider=openrouter` so tools are sent in the OpenRouter request. **Do not duplicate post-routing policy in consumers** — merge pre-invoke intent only.
 
 ### Stable error codes
 
 | Code | When |
 |------|------|
-| `SERVER_TOOL_REQUIRES_OPENROUTER_PROVIDER` | Not thrown — gateway **forces** `provider=openrouter` when required tools are configured and a key is present |
-| `OPENROUTER_SERVER_TOOL_REQUIRES_KEY` | Required tools but no OpenRouter key (`codeAliases` includes `OPENROUTER_SERVER_TOOL_REQUIRES_OPENROUTER_KEY`) |
+| `SERVER_TOOL_REQUIRES_OPENROUTER_PROVIDER` | Not thrown — gateway **forces** `provider=openrouter` when active server tools are configured and a key is present |
+| `OPENROUTER_SERVER_TOOL_REQUIRES_KEY` | Active server tools but no OpenRouter key (`codeAliases` includes `OPENROUTER_SERVER_TOOL_REQUIRES_OPENROUTER_KEY`) |
 | `WEB_SEARCH_REQUIRED_BUT_NOT_USED`, etc. | From `@x12i/openrouter-runtime` policy → `GatewayPolicyViolationError.code` and `error.metadata.openrouterRuntime.policyViolations` |
 | `CITATIONS_REQUIRED_BUT_MISSING` | `@x12i/openrouter-runtime` ≥ **1.0.3** policy when `webSearch.requireCitations: true` (or global default) and search used with no citations |
 | `APPLY_PATCH_REQUIRES_RESPONSES_API` | `applyPatch` with `openrouter.apiMode: 'chat'` |

package/dist/gateway-utils.js

@@ -209,7 +209,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
     });
     if (serverToolsPolicy.forceOpenRouter) {
         merged.provider = 'openrouter';
-        logger.verbose('Required OpenRouter server tool forced provider=openrouter', {
+        logger.verbose('OpenRouter server tool forced provider=openrouter', {
             jobId: request.identity.jobId,
         });
     }

package/dist/openrouter-runtime-adapter/create-openrouter-runtime-provider.js

@@ -1,6 +1,33 @@
 import { createOpenRouterRuntime, RuntimeConfigError, OpenRouterHttpError, } from '@x12i/openrouter-runtime';
 import { OPENROUTER_RUNTIME_OPERATION } from './map-gateway-request.js';
 import { throwMappedOpenRouterHttpError, throwMappedRuntimeConfigError, throwMappedRuntimeResponseErrors, } from './map-runtime-errors.js';
+function summarizeServerTools(serverTools) {
+    if (!serverTools)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(serverTools)) {
+        if (Array.isArray(value)) {
+            out[key] = value.map((item) => item.mode).join(',');
+            continue;
+        }
+        if (value && typeof value === 'object' && 'mode' in value && typeof value.mode === 'string') {
+            out[key] = value.mode;
+        }
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+function summarizeCompiledTools(compiled) {
+    const tools = Array.isArray(compiled.body.tools) ? compiled.body.tools : [];
+    const toolTypes = tools
+        .map((tool) => (tool && typeof tool === 'object' && 'type' in tool ? String(tool.type) : undefined))
+        .filter((type) => typeof type === 'string');
+    return {
+        apiMode: compiled.apiMode,
+        toolCount: tools.length,
+        toolTypes,
+        bodyKeys: Object.keys(compiled.body),
+    };
+}
 export function createOpenRouterRuntimeProvider(options) {
     const runtime = options.runtime ??
         createOpenRouterRuntime({
@@ -9,6 +36,22 @@ export function createOpenRouterRuntimeProvider(options) {
                 retry: { enabled: false },
                 onPolicyViolation: 'throw',
             },
+            logger: options.logger
+                ? {
+                    debug: (event, data) => options.logger?.debug(event, data),
+                    info: (event, data) => options.logger?.info(event, data),
+                    warn: (event, data) => options.logger?.warn(event, data),
+                    error: (event, data) => options.logger?.error(event, data),
+                }
+                : undefined,
+            hooks: options.logger
+                ? {
+                    beforeOpenRouterRequest: (compiled) => {
+                        const summary = summarizeCompiledTools(compiled);
+                        options.logger?.debug('OpenRouter runtime compiled request tools', summary);
+                    },
+                }
+                : undefined,
         });
     return {
         name: 'openrouter',
@@ -22,6 +65,17 @@ export function createOpenRouterRuntimeProvider(options) {
                 throw new Error(`Unsupported OpenRouter runtime operation: ${spec.operation}`);
             }
             const runtimeRequest = spec.args;
+            const rawOverrideKeys = runtimeRequest.rawOpenRouterOverrides
+                ? Object.keys(runtimeRequest.rawOpenRouterOverrides)
+                : [];
+            options.logger?.debug('OpenRouter runtime request server tools', {
+                requestId: spec.requestId,
+                model: runtimeRequest.model,
+                apiMode: runtimeRequest.apiMode,
+                serverTools: summarizeServerTools(runtimeRequest.serverTools),
+                rawOverrideKeys,
+                rawOverridesToolsPresent: Object.prototype.hasOwnProperty.call(runtimeRequest.rawOpenRouterOverrides ?? {}, 'tools'),
+            });
             try {
                 const response = await runtime.run(runtimeRequest);
                 if (response.status !== 'completed') {

package/dist/openrouter-runtime-adapter/map-gateway-request.js

@@ -22,14 +22,30 @@ function buildGenerationOverrides(config) {
         overrides.stop = config.stop;
     return overrides;
 }
+function hasActiveServerTools(serverTools) {
+    if (!serverTools)
+        return false;
+    return Object.values(serverTools).some((value) => {
+        if (Array.isArray(value))
+            return value.some((item) => item.mode !== 'disabled');
+        return !!value && value.mode !== 'disabled';
+    });
+}
+function buildRawOpenRouterOverrides(generationOverrides, trustedRaw, serverTools) {
+    const raw = { ...trustedRaw };
+    if (hasActiveServerTools(serverTools)) {
+        delete raw.tools;
+    }
+    const merged = { ...generationOverrides, ...raw };
+    return Object.keys(merged).length ? merged : undefined;
+}
 export function mapGatewayRequestToRuntimeRequest(request, exec) {
     const config = request.config ?? {};
     const openrouter = config.openrouter;
     const generationOverrides = buildGenerationOverrides(config);
     const trustedRaw = openrouter?.rawOverrides ?? {};
-    const rawOpenRouterOverrides = Object.keys(generationOverrides).length || Object.keys(trustedRaw).length
-        ? { ...generationOverrides, ...trustedRaw }
-        : undefined;
+    const serverTools = mapGatewayServerTools(config.serverTools);
+    const rawOpenRouterOverrides = buildRawOpenRouterOverrides(generationOverrides, trustedRaw, serverTools);
     const aiRequestId = (typeof request.aiRequestId === 'string' && request.aiRequestId) ||
         (typeof request.identity?.aiRequestId === 'string' ? request.identity.aiRequestId : undefined);
     return {
@@ -42,7 +58,7 @@ export function mapGatewayRequestToRuntimeRequest(request, exec) {
         reasoning: config.reasoning != null && typeof config.reasoning === 'object'
             ? config.reasoning
             : undefined,
-        serverTools: mapGatewayServerTools(config.serverTools),
+        serverTools,
         execution: exec?.timeoutMs ? { timeoutMs: exec.timeoutMs } : undefined,
         rawOpenRouterOverrides,
         metadata: {

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

@@ -73,22 +73,12 @@ export function applyPostRoutingServerToolsPolicy(input) {
         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', { codeAliases: ['OPENROUTER_SERVER_TOOL_REQUIRES_OPENROUTER_KEY'] });
-        }
-        if (provider !== 'openrouter') {
-            provider = 'openrouter';
-            return { serverTools, warnings, forceOpenRouter: true };
-        }
-        return { serverTools, warnings, forceOpenRouter: false };
+    if (!openRouterApiKey) {
+        throw new ProviderConfigError('OPENROUTER_SERVER_TOOL_REQUIRES_KEY', 'OpenRouter server tools need OPENROUTER_API_KEY or GatewayConfig.openrouter.apiKey', { codeAliases: ['OPENROUTER_SERVER_TOOL_REQUIRES_OPENROUTER_KEY'] });
     }
     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 };
+        provider = 'openrouter';
+        return { serverTools, warnings, forceOpenRouter: true };
     }
     return { serverTools, warnings, forceOpenRouter: false };
 }

package/dist-cjs/gateway-utils.cjs

@@ -209,7 +209,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
     });
     if (serverToolsPolicy.forceOpenRouter) {
         merged.provider = 'openrouter';
-        logger.verbose('Required OpenRouter server tool forced provider=openrouter', {
+        logger.verbose('OpenRouter server tool forced provider=openrouter', {
             jobId: request.identity.jobId,
         });
     }

package/dist-cjs/openrouter-runtime-adapter/create-openrouter-runtime-provider.cjs

@@ -1,6 +1,33 @@
 import { createOpenRouterRuntime, RuntimeConfigError, OpenRouterHttpError, } from '@x12i/openrouter-runtime';
 import { OPENROUTER_RUNTIME_OPERATION } from './map-gateway-request.js';
 import { throwMappedOpenRouterHttpError, throwMappedRuntimeConfigError, throwMappedRuntimeResponseErrors, } from './map-runtime-errors.js';
+function summarizeServerTools(serverTools) {
+    if (!serverTools)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(serverTools)) {
+        if (Array.isArray(value)) {
+            out[key] = value.map((item) => item.mode).join(',');
+            continue;
+        }
+        if (value && typeof value === 'object' && 'mode' in value && typeof value.mode === 'string') {
+            out[key] = value.mode;
+        }
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+function summarizeCompiledTools(compiled) {
+    const tools = Array.isArray(compiled.body.tools) ? compiled.body.tools : [];
+    const toolTypes = tools
+        .map((tool) => (tool && typeof tool === 'object' && 'type' in tool ? String(tool.type) : undefined))
+        .filter((type) => typeof type === 'string');
+    return {
+        apiMode: compiled.apiMode,
+        toolCount: tools.length,
+        toolTypes,
+        bodyKeys: Object.keys(compiled.body),
+    };
+}
 export function createOpenRouterRuntimeProvider(options) {
     const runtime = options.runtime ??
         createOpenRouterRuntime({
@@ -9,6 +36,22 @@ export function createOpenRouterRuntimeProvider(options) {
                 retry: { enabled: false },
                 onPolicyViolation: 'throw',
             },
+            logger: options.logger
+                ? {
+                    debug: (event, data) => options.logger?.debug(event, data),
+                    info: (event, data) => options.logger?.info(event, data),
+                    warn: (event, data) => options.logger?.warn(event, data),
+                    error: (event, data) => options.logger?.error(event, data),
+                }
+                : undefined,
+            hooks: options.logger
+                ? {
+                    beforeOpenRouterRequest: (compiled) => {
+                        const summary = summarizeCompiledTools(compiled);
+                        options.logger?.debug('OpenRouter runtime compiled request tools', summary);
+                    },
+                }
+                : undefined,
         });
     return {
         name: 'openrouter',
@@ -22,6 +65,17 @@ export function createOpenRouterRuntimeProvider(options) {
                 throw new Error(`Unsupported OpenRouter runtime operation: ${spec.operation}`);
             }
             const runtimeRequest = spec.args;
+            const rawOverrideKeys = runtimeRequest.rawOpenRouterOverrides
+                ? Object.keys(runtimeRequest.rawOpenRouterOverrides)
+                : [];
+            options.logger?.debug('OpenRouter runtime request server tools', {
+                requestId: spec.requestId,
+                model: runtimeRequest.model,
+                apiMode: runtimeRequest.apiMode,
+                serverTools: summarizeServerTools(runtimeRequest.serverTools),
+                rawOverrideKeys,
+                rawOverridesToolsPresent: Object.prototype.hasOwnProperty.call(runtimeRequest.rawOpenRouterOverrides ?? {}, 'tools'),
+            });
             try {
                 const response = await runtime.run(runtimeRequest);
                 if (response.status !== 'completed') {

package/dist-cjs/openrouter-runtime-adapter/map-gateway-request.cjs

@@ -22,14 +22,30 @@ function buildGenerationOverrides(config) {
         overrides.stop = config.stop;
     return overrides;
 }
+function hasActiveServerTools(serverTools) {
+    if (!serverTools)
+        return false;
+    return Object.values(serverTools).some((value) => {
+        if (Array.isArray(value))
+            return value.some((item) => item.mode !== 'disabled');
+        return !!value && value.mode !== 'disabled';
+    });
+}
+function buildRawOpenRouterOverrides(generationOverrides, trustedRaw, serverTools) {
+    const raw = { ...trustedRaw };
+    if (hasActiveServerTools(serverTools)) {
+        delete raw.tools;
+    }
+    const merged = { ...generationOverrides, ...raw };
+    return Object.keys(merged).length ? merged : undefined;
+}
 export function mapGatewayRequestToRuntimeRequest(request, exec) {
     const config = request.config ?? {};
     const openrouter = config.openrouter;
     const generationOverrides = buildGenerationOverrides(config);
     const trustedRaw = openrouter?.rawOverrides ?? {};
-    const rawOpenRouterOverrides = Object.keys(generationOverrides).length || Object.keys(trustedRaw).length
-        ? { ...generationOverrides, ...trustedRaw }
-        : undefined;
+    const serverTools = mapGatewayServerTools(config.serverTools);
+    const rawOpenRouterOverrides = buildRawOpenRouterOverrides(generationOverrides, trustedRaw, serverTools);
     const aiRequestId = (typeof request.aiRequestId === 'string' && request.aiRequestId) ||
         (typeof request.identity?.aiRequestId === 'string' ? request.identity.aiRequestId : undefined);
     return {
@@ -42,7 +58,7 @@ export function mapGatewayRequestToRuntimeRequest(request, exec) {
         reasoning: config.reasoning != null && typeof config.reasoning === 'object'
             ? config.reasoning
             : undefined,
-        serverTools: mapGatewayServerTools(config.serverTools),
+        serverTools,
         execution: exec?.timeoutMs ? { timeoutMs: exec.timeoutMs } : undefined,
         rawOpenRouterOverrides,
         metadata: {

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

@@ -73,22 +73,12 @@ export function applyPostRoutingServerToolsPolicy(input) {
         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', { codeAliases: ['OPENROUTER_SERVER_TOOL_REQUIRES_OPENROUTER_KEY'] });
-        }
-        if (provider !== 'openrouter') {
-            provider = 'openrouter';
-            return { serverTools, warnings, forceOpenRouter: true };
-        }
-        return { serverTools, warnings, forceOpenRouter: false };
+    if (!openRouterApiKey) {
+        throw new ProviderConfigError('OPENROUTER_SERVER_TOOL_REQUIRES_KEY', 'OpenRouter server tools need OPENROUTER_API_KEY or GatewayConfig.openrouter.apiKey', { codeAliases: ['OPENROUTER_SERVER_TOOL_REQUIRES_OPENROUTER_KEY'] });
     }
     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 };
+        provider = 'openrouter';
+        return { serverTools, warnings, forceOpenRouter: true };
     }
     return { serverTools, warnings, forceOpenRouter: false };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "11.0.0",
+  "version": "11.0.1",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -44,7 +44,7 @@
   "dependencies": {
     "@x12i/activix": "^9.0.2",
     "@x12i/ai-profiles": "^3.4.1",
-    "@x12i/ai-providers-router": "^4.10.0",
+    "@x12i/ai-providers-router": "^4.11.0",
     "@x12i/ai-tools": "^3.3.5",
     "@x12i/flex-md": "^4.8.0",
     "@x12i/logxer": "^5.1.0",