@x12i/ai-gateway 10.3.1 → 10.4.0

package/README.md

@@ -13,7 +13,7 @@ Unified gateway for LLM provider routing, structured logging, optional Activix a
 | **Activix** | Optional Mongo-backed activity rows; billing written from gateway-computed slice on **`completeRecord`** (`outer.cost` + root fields). No Activix **`autoCost`** re-pricing. |
 | **Trace mode** | `diagnostics.mode === 'trace'` adds `metadata.attempts[]`, `metadata.usage`, and per-attempt **`costUsd`** / **`costStatus`**. |
 
-Pinned dependency versions are in `package.json` (currently **Activix ^9.0**, **ai-tools ^3.3**, **ai-profiles ^3.4**, **ai-providers-router ^4.9**).
+Pinned dependency versions are in `package.json` (currently **Activix ^9.0**, **ai-tools ^3.3**, **ai-profiles ^3.4**, **ai-providers-router ^4.9**, **openrouter-runtime ^1.0**).
 
 ---
 
@@ -350,6 +350,97 @@ Live tests use `LIVE_TEST_PROVIDER` / `LIVE_TEST_MODEL` (default `openrouter` +
 
 ---
 
+## OpenRouter server tools
+
+`ai-gateway` exposes OpenRouter server tools through `config.serverTools` (and `modelConfig.serverTools`). This is **additive** and only applies when the final provider is `openrouter`. Existing calls without `serverTools` behave the same.
+
+OpenRouter execution uses `@x12i/openrouter-runtime` internally (enabled by default). Control via:
+
+| Variable | Effect |
+|----------|--------|
+| `AI_GATEWAY_USE_OPENROUTER_RUNTIME=0` | Legacy router OpenRouter path |
+| `AI_GATEWAY_USE_LEGACY_OPENROUTER=1` | Same as legacy (emergency fallback) |
+
+Gateway constructor: `openrouterRuntime: { enabled, apiMode, includeRawInTrace }`, `defaultServerTools`.
+
+### Web search
+
+```typescript
+await gateway.invoke({
+  ...base,
+  config: {
+    provider: 'openrouter',
+    model: 'openai/gpt-5.2',
+    maxTokens: 1200,
+    serverTools: {
+      webSearch: {
+        mode: 'required',
+        engine: 'auto',
+        maxResults: 5,
+        maxTotalResults: 15,
+      },
+    },
+  },
+});
+```
+
+### Search + fetch
+
+```typescript
+serverTools: {
+  webSearch: { mode: 'required' },
+  webFetch: {
+    mode: 'allowed',
+    engine: 'openrouter',
+    maxContentTokens: 50000,
+  },
+}
+```
+
+### Datetime
+
+```typescript
+serverTools: {
+  datetime: {
+    mode: 'allowed',
+    timezone: 'Asia/Jerusalem',
+  },
+}
+```
+
+### Apply patch
+
+Apply patch requires OpenRouter Responses API and returns patch proposals only. The gateway **never** writes files.
+
+```typescript
+config: {
+  provider: 'openrouter',
+  model: 'openai/o4-mini',
+  maxTokens: 1200,
+  openrouter: { apiMode: 'responses' },
+  serverTools: {
+    applyPatch: {
+      mode: 'required',
+      behavior: 'return_only',
+    },
+  },
+}
+```
+
+### Metadata
+
+Tool usage and artifacts appear under:
+
+- `response.metadata.serverTools`
+- `response.metadata.citations`
+- `response.metadata.generatedImages`
+- `response.metadata.patchProposals`
+- `response.metadata.openrouterRuntime`
+
+Cost remains under `response.metadata.costUsd`, `response.metadata.costStatus`, and `response.metadata.tokens`.
+
+---
+
 ## Documentation index
 
 Full index: **[docs/README.md](./docs/README.md)**. Upstream gaps: **[docs/upstream-reports/](./docs/upstream-reports/README.md)**.

package/dist/activity-manager.js

@@ -230,6 +230,39 @@ function pickActivixCompletionRoutingMetadata(response) {
             if (m.effectiveModelConfig != null && typeof m.effectiveModelConfig === 'object') {
                 out.effectiveModelConfig = m.effectiveModelConfig;
             }
+            const citations = m.citations;
+            if (Array.isArray(citations) && citations.length) {
+                out.citations = citations
+                    .filter((c) => c != null && typeof c === 'object')
+                    .map((c) => {
+                    const row = c;
+                    return {
+                        ...(typeof row.url === 'string' ? { url: row.url } : {}),
+                        ...(typeof row.title === 'string' ? { title: row.title } : {}),
+                    };
+                });
+                out.citationCount = citations.length;
+            }
+            const serverTools = m.serverTools;
+            const generatedImages = m.generatedImages;
+            const patchProposals = m.patchProposals;
+            const openrouterRuntime = m.openrouterRuntime;
+            if (serverTools != null ||
+                openrouterRuntime != null ||
+                (Array.isArray(generatedImages) && generatedImages.length) ||
+                (Array.isArray(patchProposals) && patchProposals.length)) {
+                out.openrouterRuntime = {
+                    ...(openrouterRuntime != null && typeof openrouterRuntime === 'object'
+                        ? {
+                            apiMode: openrouterRuntime.apiMode,
+                            serverTools,
+                        }
+                        : { serverTools }),
+                    citationCount: Array.isArray(citations) ? citations.length : 0,
+                    generatedImageCount: Array.isArray(generatedImages) ? generatedImages.length : 0,
+                    patchProposalCount: Array.isArray(patchProposals) ? patchProposals.length : 0,
+                };
+            }
         }
     }
     return out;

package/dist/gateway-config.js

@@ -11,6 +11,7 @@ import { createGatewayLogger } from './logger-factory.js';
 import { ActivityManager } from './activity-manager.js';
 import { UsageTracker } from './usage-tracker.js';
 import { mergeTemplateRenderOptions } from './template-render-merge.js';
+import { registerOpenRouterRuntime, shouldUseOpenRouterRuntime, } from './openrouter-runtime-adapter/index.js';
 /** Resolve current module directory across ESM/CJS builds. */
 function getModuleDir() {
     if (typeof __dirname !== 'undefined') {
@@ -167,6 +168,20 @@ export function initializeGatewayComponents(config) {
     }
     const router = new LLMProviderRouter(routerConfig);
     setupRequestInterceptor(router, logger);
+    if (openRouterKey && shouldUseOpenRouterRuntime(config)) {
+        registerOpenRouterRuntime(router, {
+            apiKey: openRouterKey,
+            logger,
+            runtimeConfig: config.openrouterRuntime,
+        });
+    }
+    else if (openRouterKey) {
+        logger.debug('OpenRouter legacy provider path enabled (runtime disabled)', {
+            AI_GATEWAY_USE_OPENROUTER_RUNTIME: process.env.AI_GATEWAY_USE_OPENROUTER_RUNTIME,
+            AI_GATEWAY_USE_LEGACY_OPENROUTER: process.env.AI_GATEWAY_USE_LEGACY_OPENROUTER,
+            openrouterRuntimeEnabled: config.openrouterRuntime?.enabled,
+        });
+    }
     const usageTracker = new UsageTracker({
         enableUsageTracking: config.enableUsageTracking ?? true,
         usageTier: config.usageTier,

package/dist/gateway-utils.d.ts

@@ -5,6 +5,7 @@
 import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayFallbackAttempt, GatewayInvokeRejectionMetadata, GatewayTraceAttempt, GatewayTraceMergedConfig, GatewayTraceRequestIds, GatewayTraceUsageSummary, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 import { type AiCostResult, type AiModelsCatalogClient, type CostCalculator, type OpenRouterRoutingConfig } from '@x12i/ai-tools';
+import { pickOpenRouterRuntimeMetadataSlice, enrichTraceOpenRouterRuntimeMetadata } from './openrouter-runtime-adapter/index.js';
 /**
  * Generates MD5 hash of a string
  */
@@ -132,7 +133,13 @@ export declare function buildTraceUsageSummary(tokens: {
     prompt: number;
     completion: number;
     total: number;
-}, billing: ResolvedActivityCost, maxTokensRequested?: number): GatewayTraceUsageSummary | undefined;
+}, billing: ResolvedActivityCost, maxTokensRequested?: number, openrouterExtras?: Pick<GatewayTraceUsageSummary, 'serverTools' | 'citations'>): GatewayTraceUsageSummary | undefined;
+/**
+ * Additive OpenRouter runtime metadata for gateway responses.
+ */
+export declare function pickEnhancedOpenRouterMetadata(routerResponse: unknown, traceEnabled?: boolean): ReturnType<typeof pickOpenRouterRuntimeMetadataSlice> & {
+    openrouterRuntime?: ReturnType<typeof enrichTraceOpenRouterRuntimeMetadata>;
+};
 /**
  * Apply resolved billing to trace attempts: final successful attempt gets aggregate billing;
  * other successful attempts without router cost get per-attempt catalog pricing when enabled.

package/dist/gateway-utils.js

@@ -9,6 +9,7 @@ import { extractHttpStatusCode } from './gateway-retry.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 import { MaxTokensRequiredError, ModelRequiredError, } from './instruction-errors.js';
 import { normalizeInvokeModelAtIngress } from './invoke-model-ingress.js';
+import { applyOnlineVariantMigration, applyPostRoutingServerToolsPolicy, mergeOpenRouterConfig, mergeServerToolsConfig, normalizeApplyPatchDefaults, resolveOpenRouterRuntimeDefaults, pickOpenRouterRuntimeMetadataSlice, enrichTraceOpenRouterRuntimeMetadata, } from './openrouter-runtime-adapter/index.js';
 import { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P } from './gateway-defaults.js';
 function getPreParsedInstructions(instructions) {
     return instructions ?? '';
@@ -115,6 +116,31 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
     merged.model = ingress.model;
     originalProvider = merged.provider;
     originalModel = merged.model;
+    const runtimeDefaults = resolveOpenRouterRuntimeDefaults(config);
+    let mergedServerTools = normalizeApplyPatchDefaults(mergeServerToolsConfig(config.defaultServerTools, request.config?.serverTools, request.modelConfig?.serverTools));
+    const mergedOpenRouter = mergeOpenRouterConfig({ apiMode: runtimeDefaults.apiMode, includeRawInTrace: runtimeDefaults.includeRawInTrace }, request.config?.openrouter, request.modelConfig?.openrouter);
+    const onlineMigration = applyOnlineVariantMigration(merged.model, mergedServerTools);
+    if (onlineMigration.model !== merged.model) {
+        merged.model = onlineMigration.model;
+        originalModel = merged.model;
+        mergedServerTools = onlineMigration.serverTools;
+        logger.warn('OpenRouter :online model variant migrated', {
+            jobId: request.identity.jobId,
+            code: onlineMigration.warning?.code,
+            message: onlineMigration.warning?.message,
+        });
+        const warnings = request._openrouterWarnings;
+        if (onlineMigration.warning) {
+            request._openrouterWarnings = [
+                ...(warnings ?? []),
+                onlineMigration.warning,
+            ];
+        }
+    }
+    if (mergedServerTools)
+        merged.serverTools = mergedServerTools;
+    if (mergedOpenRouter)
+        merged.openrouter = mergedOpenRouter;
     if (resolveModels && mergeOptions?.catalog) {
         try {
             const resolved = await resolveInvokeModel({ provider: merged.provider, model: merged.model }, {
@@ -175,6 +201,34 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
             merged.providerProxy = resolved.router.providerProxy;
         }
     }
+    const serverToolsPolicy = applyPostRoutingServerToolsPolicy({
+        provider: merged.provider,
+        serverTools: merged.serverTools,
+        openrouter: merged.openrouter,
+        openRouterApiKey: mergeOptions?.openRouterApiKey,
+    });
+    if (serverToolsPolicy.forceOpenRouter) {
+        merged.provider = 'openrouter';
+        logger.verbose('Required OpenRouter server tool forced provider=openrouter', {
+            jobId: request.identity.jobId,
+        });
+    }
+    if (serverToolsPolicy.serverTools) {
+        merged.serverTools = serverToolsPolicy.serverTools;
+    }
+    else {
+        delete merged.serverTools;
+    }
+    if (serverToolsPolicy.warnings.length) {
+        const existing = request._openrouterWarnings;
+        request._openrouterWarnings = [
+            ...(existing ?? []),
+            ...serverToolsPolicy.warnings,
+        ];
+        for (const w of serverToolsPolicy.warnings) {
+            logger.warn(w.message, { jobId: request.identity.jobId, code: w.code });
+        }
+    }
     if (!merged.model) {
         throw new ModelRequiredError();
     }
@@ -571,7 +625,7 @@ function buildTraceAttemptPricingRecord(attempt, mergedConfig) {
 /**
  * Trace-mode summary: final token usage + resolved billing (after catalog pricing when applicable).
  */
-export function buildTraceUsageSummary(tokens, billing, maxTokensRequested) {
+export function buildTraceUsageSummary(tokens, billing, maxTokensRequested, openrouterExtras) {
     if (!hasNonZeroTokenUsage(tokens) && !billing.costStatus) {
         return undefined;
     }
@@ -589,8 +643,26 @@ export function buildTraceUsageSummary(tokens, billing, maxTokensRequested) {
     if (billing.costBreakdown) {
         summary.costBreakdown = billing.costBreakdown;
     }
+    if (openrouterExtras?.serverTools)
+        summary.serverTools = openrouterExtras.serverTools;
+    if (openrouterExtras?.citations?.length)
+        summary.citations = openrouterExtras.citations;
     return summary;
 }
+/**
+ * Additive OpenRouter runtime metadata for gateway responses.
+ */
+export function pickEnhancedOpenRouterMetadata(routerResponse, traceEnabled = false) {
+    const slice = pickOpenRouterRuntimeMetadataSlice(routerResponse);
+    if (!slice.openrouterRuntime && !slice.serverTools && !slice.citations?.length) {
+        return slice;
+    }
+    const openrouterRuntime = enrichTraceOpenRouterRuntimeMetadata(slice.openrouterRuntime, slice, traceEnabled);
+    return {
+        ...slice,
+        ...(openrouterRuntime ? { openrouterRuntime } : {}),
+    };
+}
 /**
  * Apply resolved billing to trace attempts: final successful attempt gets aggregate billing;
  * other successful attempts without router cost get per-attempt catalog pricing when enabled.

package/dist/gateway.js

@@ -11,7 +11,8 @@ import { resolveRetryConfig } from './gateway-defaults.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd } from './flex-md-loader.js';
 import { enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
-import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
+import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, pickEnhancedOpenRouterMetadata, resolveCostCompletionWithAiTools, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
+import { buildTraceAttemptOpenRouterRuntimeSlice } from './openrouter-runtime-adapter/index.js';
 import { getAiToolsClient } from './ai-tools-client.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
@@ -140,9 +141,12 @@ export class AIGateway {
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
+                const routingMetadataSliceChat = pickInvokeRoutingMetadataSlice(response, mergedConfig);
+                const effectiveModelConfigChat = pickEffectiveModelConfigForMetadata(mergedConfig);
+                const openrouterMetadataChat = pickEnhancedOpenRouterMetadata(response, false);
                 // Create enhanced response
                 const enhancedResponse = {
-                    content: response.content || '',
+                    content: response.content || response.outputText || '',
                     metadata: {
                         aiRequestId: request.aiRequestId,
                         identity: request.identity,
@@ -150,6 +154,9 @@ export class AIGateway {
                         tokens: tokensChat,
                         taskTypeId,
                         agentType: 'chat',
+                        ...routingMetadataSliceChat,
+                        ...(effectiveModelConfigChat !== undefined ? { effectiveModelConfig: effectiveModelConfigChat } : {}),
+                        ...openrouterMetadataChat,
                         ...(costCompletionChat.costStatus === 'priced'
                             ? {
                                 costUsd: costCompletionChat.cost,
@@ -466,6 +473,9 @@ export class AIGateway {
                                             const rawStr = typeof raw === 'string' ? raw : safeJsonStringify(raw);
                                             a.rawProviderPayload = capString(rawStr, 4000);
                                         }
+                                        const runtimeSlice = buildTraceAttemptOpenRouterRuntimeSlice(pickEnhancedOpenRouterMetadata(respAny, true));
+                                        if (runtimeSlice)
+                                            a.openrouterRuntime = runtimeSlice;
                                     }
                                     else if (tryErr) {
                                         a.error = { name: tryErr.name || 'Error', message: capErrorMessage(tryErr.message || String(tryErr)) };
@@ -617,6 +627,7 @@ export class AIGateway {
                 const routerMetaForCost = routerResponse?.metadata || {};
                 const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
                 const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);
+                const openrouterMetadata = pickEnhancedOpenRouterMetadata(routerResponse, traceEnabled);
                 const traceMergedRouterSnapshot = traceEnabled ? pickTraceMergedRouterConfig(mergedConfig) : undefined;
                 if (traceEnabled && traceAttempts) {
                     await enrichTraceAttemptsWithBilling(traceAttempts, costCompletion, {
@@ -626,7 +637,10 @@ export class AIGateway {
                     });
                 }
                 const traceUsageSummary = traceEnabled
-                    ? buildTraceUsageSummary(tokens, costCompletion, routingMetadataSlice.maxTokensRequested)
+                    ? buildTraceUsageSummary(tokens, costCompletion, routingMetadataSlice.maxTokensRequested, {
+                        serverTools: openrouterMetadata.serverTools,
+                        citations: openrouterMetadata.citations,
+                    })
                     : undefined;
                 const enhancedResponse = {
                     content: content,
@@ -642,6 +656,7 @@ export class AIGateway {
                         parsingMethod,
                         ...routingMetadataSlice,
                         ...(effectiveModelConfig !== undefined ? { effectiveModelConfig } : {}),
+                        ...openrouterMetadata,
                         ...(costCompletion.costStatus === 'priced'
                             ? {
                                 costUsd: costCompletion.cost,

package/dist/index.d.ts

@@ -14,11 +14,12 @@ export type { RequestInterceptor, ResponseInterceptor } from '@x12i/ai-providers
 export type { UsageTracker } from '@x12i/ai-providers-router';
 export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
-export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError, GatewayAliasModelRejectedError, } from './instruction-errors.js';
+export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError, GatewayAliasModelRejectedError, GatewayValidationError, ProviderConfigError, ProviderInvokeError, GatewayPolicyViolationError, } from './instruction-errors.js';
 export { normalizeInvokeModelAtIngress } from './invoke-model-ingress.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayFallbackAttempt, GatewayTraceRequestIds, GatewayTraceAttempt, GatewayTraceUsageSummary, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
+export { registerOpenRouterRuntime, shouldUseOpenRouterRuntime, mapGatewayServerTools, } from './openrouter-runtime-adapter/index.js';
+export type { GatewayConfig, ProviderModelRef, ModelConfig, GatewayModelConfig, GatewayServerToolsConfig, GatewayOpenRouterConfig, GatewayOpenRouterRuntimeConfig, GatewayServerToolUsageMap, GatewayCitation, GatewayGeneratedImage, GatewayPatchProposal, GatewayOpenRouterRuntimeMetadata, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayFallbackAttempt, GatewayTraceRequestIds, GatewayTraceAttempt, GatewayTraceUsageSummary, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, pickEnhancedOpenRouterMetadata, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, parseModelProviderSpec } from './gateway-mode.js';
 export type { GatewayOperationalMode } from './gateway-mode.js';
 export { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_RETRY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P, resolveRetryConfig } from './gateway-defaults.js';

package/dist/index.js

@@ -15,10 +15,11 @@ export { ProviderNotFoundError, FallbackExhaustedError } from '@x12i/ai-provider
 export * from '@x12i/ai-providers-router';
 // Export enhanced gateway
 export { AIGateway } from './gateway.js';
-export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError, GatewayAliasModelRejectedError, } from './instruction-errors.js';
+export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError, GatewayAliasModelRejectedError, GatewayValidationError, ProviderConfigError, ProviderInvokeError, GatewayPolicyViolationError, } from './instruction-errors.js';
 export { normalizeInvokeModelAtIngress } from './invoke-model-ingress.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
+export { registerOpenRouterRuntime, shouldUseOpenRouterRuntime, mapGatewayServerTools, } from './openrouter-runtime-adapter/index.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, pickEnhancedOpenRouterMetadata, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, parseModelProviderSpec } from './gateway-mode.js';
 export { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_RETRY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P, resolveRetryConfig } from './gateway-defaults.js';
 export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';

package/dist/instruction-errors.d.ts

@@ -14,6 +14,27 @@ export declare class GatewayAliasModelRejectedError extends Error {
     readonly code = "GATEWAY_ALIAS_MODEL_REJECTED";
     constructor(aliasModel: string, message?: string);
 }
+export declare class GatewayValidationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class ProviderConfigError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class ProviderInvokeError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly retryable?: boolean;
+    constructor(code: string, message: string, options?: {
+        status?: number;
+        retryable?: boolean;
+    });
+}
+export declare class GatewayPolicyViolationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
 export declare class InstructionNotFoundError extends Error {
     key: string;
     backend: string;

package/dist/instruction-errors.js

@@ -25,6 +25,42 @@ export class GatewayAliasModelRejectedError extends Error {
         this.name = 'GatewayAliasModelRejectedError';
     }
 }
+export class GatewayValidationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'GatewayValidationError';
+        this.code = code;
+    }
+}
+export class ProviderConfigError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ProviderConfigError';
+        this.code = code;
+    }
+}
+export class ProviderInvokeError extends Error {
+    code;
+    status;
+    retryable;
+    constructor(code, message, options) {
+        super(message);
+        this.name = 'ProviderInvokeError';
+        this.code = code;
+        this.status = options?.status;
+        this.retryable = options?.retryable;
+    }
+}
+export class GatewayPolicyViolationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'GatewayPolicyViolationError';
+        this.code = code;
+    }
+}
 export class InstructionNotFoundError extends Error {
     key;
     backend;

package/dist/openrouter-runtime-adapter/create-openrouter-runtime-adapter.d.ts

@@ -0,0 +1,23 @@
+import type { ProviderSDKCallSpec } from '@x12i/ai-provider-interface';
+import type { AIResponse } from '@x12i/ai-providers-router';
+export declare function createOpenRouterRuntimeAdapter(): {
+    provider: string;
+    buildCallSpec(input: {
+        requestId: string;
+        mode: "sync" | "stream";
+        request: Record<string, unknown>;
+        exec?: {
+            timeoutMs?: number;
+            retries?: number;
+            idempotencyKey?: string;
+            signal?: AbortSignal;
+        };
+    }): ProviderSDKCallSpec;
+    parseResponse(input: {
+        requestId: string;
+        request: unknown;
+        execResult: {
+            rawResponse: unknown;
+        };
+    }): AIResponse;
+};

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

@@ -0,0 +1,31 @@
+import { mapGatewayRequestToRuntimeRequestFromRouter, OPENROUTER_RUNTIME_OPERATION, } from './map-gateway-request.js';
+import { parseRuntimeResponseToAIResponse } from './map-runtime-response.js';
+export function createOpenRouterRuntimeAdapter() {
+    return {
+        provider: 'openrouter',
+        buildCallSpec(input) {
+            const runtimeRequest = mapGatewayRequestToRuntimeRequestFromRouter({
+                request: input.request,
+                exec: input.exec,
+            });
+            return {
+                requestId: input.requestId,
+                provider: 'openrouter',
+                mode: input.mode === 'stream' ? 'sync' : input.mode,
+                operation: OPENROUTER_RUNTIME_OPERATION,
+                args: runtimeRequest,
+                exec: input.exec
+                    ? {
+                        timeoutMs: input.exec.timeoutMs,
+                        retries: input.exec.retries,
+                        idempotencyKey: input.exec.idempotencyKey,
+                        signal: input.exec.signal,
+                    }
+                    : undefined,
+            };
+        },
+        parseResponse(input) {
+            return parseRuntimeResponseToAIResponse(input);
+        },
+    };
+}

package/dist/openrouter-runtime-adapter/create-openrouter-runtime-provider.d.ts

@@ -0,0 +1,9 @@
+import { type OpenRouterRuntime } from '@x12i/openrouter-runtime';
+import type { ProviderModule } from '@x12i/ai-provider-interface';
+import type { Logxer } from '@x12i/logxer';
+export type OpenRouterRuntimeProviderOptions = {
+    apiKey: string;
+    logger?: Logxer;
+    runtime?: OpenRouterRuntime;
+};
+export declare function createOpenRouterRuntimeProvider(options: OpenRouterRuntimeProviderOptions): ProviderModule;

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

@@ -0,0 +1,41 @@
+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';
+export function createOpenRouterRuntimeProvider(options) {
+    const runtime = options.runtime ??
+        createOpenRouterRuntime({
+            apiKey: options.apiKey,
+            defaults: {
+                retry: { enabled: false },
+                onPolicyViolation: 'return_error',
+            },
+        });
+    return {
+        name: 'openrouter',
+        capabilities: {
+            modes: { sync: true, stream: false, batch: false },
+            operations: [OPENROUTER_RUNTIME_OPERATION],
+            maxConcurrency: 10,
+        },
+        async execute(spec) {
+            if (spec.operation !== OPENROUTER_RUNTIME_OPERATION) {
+                throw new Error(`Unsupported OpenRouter runtime operation: ${spec.operation}`);
+            }
+            const runtimeRequest = spec.args;
+            try {
+                const response = await runtime.run(runtimeRequest);
+                if (response.status !== 'completed') {
+                    throwMappedRuntimeResponseErrors(response);
+                }
+                return { rawResponse: response };
+            }
+            catch (err) {
+                if (err instanceof RuntimeConfigError)
+                    throwMappedRuntimeConfigError(err);
+                if (err instanceof OpenRouterHttpError)
+                    throwMappedOpenRouterHttpError(err);
+                throw err;
+            }
+        },
+    };
+}

package/dist/openrouter-runtime-adapter/index.d.ts

@@ -0,0 +1,8 @@
+export { registerOpenRouterRuntime, shouldUseOpenRouterRuntime, resolveOpenRouterRuntimeDefaults, } from './register-openrouter-runtime.js';
+export { createOpenRouterRuntimeProvider } from './create-openrouter-runtime-provider.js';
+export { createOpenRouterRuntimeAdapter } from './create-openrouter-runtime-adapter.js';
+export { mapGatewayServerTools } from './map-server-tools.js';
+export { mapGatewayRequestToRuntimeRequest } from './map-gateway-request.js';
+export { pickOpenRouterRuntimeMetadataSlice, extractOpenRouterRuntimeRouterMetadata, parseRuntimeResponseToAIResponse, } from './map-runtime-response.js';
+export { applyOnlineVariantMigration, applyPostRoutingServerToolsPolicy, mergeOpenRouterConfig, mergeServerToolsConfig, normalizeApplyPatchDefaults, validateApplyPatchConfig, hasAnyActiveServerTool, hasRequiredServerTool, } from './validate-server-tools.js';
+export { buildTraceAttemptOpenRouterRuntimeSlice, enrichTraceOpenRouterRuntimeMetadata, redactRawOpenRouterPayload, } from './map-trace.js';

package/dist/openrouter-runtime-adapter/index.js

@@ -0,0 +1,8 @@
+export { registerOpenRouterRuntime, shouldUseOpenRouterRuntime, resolveOpenRouterRuntimeDefaults, } from './register-openrouter-runtime.js';
+export { createOpenRouterRuntimeProvider } from './create-openrouter-runtime-provider.js';
+export { createOpenRouterRuntimeAdapter } from './create-openrouter-runtime-adapter.js';
+export { mapGatewayServerTools } from './map-server-tools.js';
+export { mapGatewayRequestToRuntimeRequest } from './map-gateway-request.js';
+export { pickOpenRouterRuntimeMetadataSlice, extractOpenRouterRuntimeRouterMetadata, parseRuntimeResponseToAIResponse, } from './map-runtime-response.js';
+export { applyOnlineVariantMigration, applyPostRoutingServerToolsPolicy, mergeOpenRouterConfig, mergeServerToolsConfig, normalizeApplyPatchDefaults, validateApplyPatchConfig, hasAnyActiveServerTool, hasRequiredServerTool, } from './validate-server-tools.js';
+export { buildTraceAttemptOpenRouterRuntimeSlice, enrichTraceOpenRouterRuntimeMetadata, redactRawOpenRouterPayload, } from './map-trace.js';

package/dist/openrouter-runtime-adapter/map-gateway-request.d.ts

@@ -0,0 +1,26 @@
+import type { RuntimeRequest } from '@x12i/openrouter-runtime';
+export declare const OPENROUTER_RUNTIME_OPERATION = "openrouter-runtime.run";
+export type GatewayRouterInvokeRequest = {
+    messages?: Array<{
+        role: string;
+        content: string | unknown[];
+        name?: string;
+        toolCallId?: string;
+    }>;
+    config?: Record<string, unknown>;
+    identity?: Record<string, unknown>;
+    aiRequestId?: string;
+    agentId?: string;
+    actionType?: string;
+    actionRef?: string;
+};
+export declare function mapGatewayRequestToRuntimeRequest(request: GatewayRouterInvokeRequest, exec?: {
+    timeoutMs?: number;
+}): RuntimeRequest;
+export declare function mapGatewayRequestToRuntimeRequestFromRouter(input: {
+    request: GatewayRouterInvokeRequest;
+    exec?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    };
+}): RuntimeRequest;