@x12i/ai-gateway 10.4.1 → 10.4.4

package/dist-cjs/index.d.ts

@@ -9,7 +9,7 @@ export { LLMProviderRouter } from '@x12i/ai-providers-router';
 export type { RouterConfig, HealthCheckResult } from '@x12i/ai-providers-router';
 export { createRouter, createRouterFromConfig } from '@x12i/ai-providers-router';
 export type { CreateRouterConfig } from '@x12i/ai-providers-router';
-export { ProviderNotFoundError, FallbackExhaustedError } from '@x12i/ai-providers-router';
+export { ProviderNotFoundError, FallbackExhaustedError, OpenRouterApiKeyMissingError, } from '@x12i/ai-providers-router';
 export type { RequestInterceptor, ResponseInterceptor } from '@x12i/ai-providers-router';
 export type { UsageTracker } from '@x12i/ai-providers-router';
 export * from '@x12i/ai-providers-router';
@@ -18,8 +18,8 @@ export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError,
 export { normalizeInvokeModelAtIngress } from './invoke-model-ingress.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.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 type { GatewayConfig, ProviderModelRef, ModelConfig, GatewayModelConfig, GatewayServerToolsConfig, GatewayServerToolMode, GatewayServerToolUsage, GatewayNestedServerTool, GatewayWebSearchToolConfig, GatewayWebFetchToolConfig, GatewayDatetimeToolConfig, GatewayImageGenerationToolConfig, GatewayApplyPatchToolConfig, GatewayFusionToolConfig, GatewayAdvisorToolConfig, GatewaySubagentToolConfig, GatewayOpenRouterErrorMetadata, 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, tryExtractOpenRouterMetadataFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, pickEnhancedOpenRouterMetadata, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, enrichGatewayFallbackExhaustedError, 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-cjs/instruction-errors.cjs

@@ -35,10 +35,13 @@ export class GatewayValidationError extends Error {
 }
 export class ProviderConfigError extends Error {
     code;
-    constructor(code, message) {
+    /** Stable alternate codes documented for upstream consumers (e.g. CR-GW-ST-001). */
+    codeAliases;
+    constructor(code, message, options) {
         super(message);
         this.name = 'ProviderConfigError';
         this.code = code;
+        this.codeAliases = options?.codeAliases;
     }
 }
 export class ProviderInvokeError extends Error {
@@ -55,10 +58,13 @@ export class ProviderInvokeError extends Error {
 }
 export class GatewayPolicyViolationError extends Error {
     code;
-    constructor(code, message) {
+    /** Partial OpenRouter tool metadata preserved when policy fails after a runtime response. */
+    routerMetadata;
+    constructor(code, message, options) {
         super(message);
         this.name = 'GatewayPolicyViolationError';
         this.code = code;
+        this.routerMetadata = options?.routerMetadata;
     }
 }
 export class InstructionNotFoundError extends Error {

package/dist-cjs/instruction-errors.d.ts

@@ -1,6 +1,7 @@
 /**
  * Errors for instruction / prompt template resolution.
  */
+import type { GatewayOpenRouterErrorMetadata } from './types.js';
 export declare class ModelRequiredError extends Error {
     readonly code = "MODEL_REQUIRED";
     constructor(message?: string);
@@ -20,7 +21,11 @@ export declare class GatewayValidationError extends Error {
 }
 export declare class ProviderConfigError extends Error {
     readonly code: string;
-    constructor(code: string, message: string);
+    /** Stable alternate codes documented for upstream consumers (e.g. CR-GW-ST-001). */
+    readonly codeAliases?: readonly string[];
+    constructor(code: string, message: string, options?: {
+        codeAliases?: readonly string[];
+    });
 }
 export declare class ProviderInvokeError extends Error {
     readonly code: string;
@@ -33,7 +38,11 @@ export declare class ProviderInvokeError extends Error {
 }
 export declare class GatewayPolicyViolationError extends Error {
     readonly code: string;
-    constructor(code: string, message: string);
+    /** Partial OpenRouter tool metadata preserved when policy fails after a runtime response. */
+    routerMetadata?: GatewayOpenRouterErrorMetadata;
+    constructor(code: string, message: string, options?: {
+        routerMetadata?: GatewayOpenRouterErrorMetadata;
+    });
 }
 export declare class InstructionNotFoundError extends Error {
     key: string;

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

@@ -7,7 +7,7 @@ export function createOpenRouterRuntimeProvider(options) {
             apiKey: options.apiKey,
             defaults: {
                 retry: { enabled: false },
-                onPolicyViolation: 'return_error',
+                onPolicyViolation: 'throw',
             },
         });
     return {

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

@@ -3,6 +3,6 @@ export { createOpenRouterRuntimeProvider } from './create-openrouter-runtime-pro
 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 { buildPartialMetadataFromRuntimeResponse, buildRouterLikeEnvelopeFromRuntimeResponse, 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-cjs/openrouter-runtime-adapter/index.d.ts

@@ -3,6 +3,6 @@ export { createOpenRouterRuntimeProvider } from './create-openrouter-runtime-pro
 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 { buildPartialMetadataFromRuntimeResponse, buildRouterLikeEnvelopeFromRuntimeResponse, 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-cjs/openrouter-runtime-adapter/map-runtime-errors.cjs

@@ -1,5 +1,10 @@
 import { OpenRouterHttpError, RuntimeConfigError, } from '@x12i/openrouter-runtime';
 import { GatewayPolicyViolationError, GatewayValidationError, ProviderConfigError, ProviderInvokeError, } from '../instruction-errors.js';
+import { buildPartialMetadataFromRuntimeResponse, buildRouterLikeEnvelopeFromRuntimeResponse, } from './map-runtime-response.js';
+function attachRouterEnvelopeToError(err, response) {
+    const envelope = buildRouterLikeEnvelopeFromRuntimeResponse(response);
+    err.response = envelope;
+}
 export function throwMappedRuntimeConfigError(err) {
     const code = err.code;
     if (code === 'OPENROUTER_API_KEY_MISSING') {
@@ -25,17 +30,26 @@ export function throwMappedOpenRouterHttpError(err) {
 export function throwMappedRuntimeResponseErrors(response) {
     if (response.status === 'completed')
         return;
+    const routerMetadata = buildPartialMetadataFromRuntimeResponse(response);
     const primary = response.errors[0];
     if (!primary) {
-        throw new ProviderInvokeError('OPENROUTER_REQUEST_FAILED', 'OpenRouter runtime request failed');
+        const err = new ProviderInvokeError('OPENROUTER_REQUEST_FAILED', 'OpenRouter runtime request failed');
+        attachRouterEnvelopeToError(err, response);
+        throw err;
     }
     if (primary.source === 'policy' || response.status === 'policy_violation') {
-        throw new GatewayPolicyViolationError(primary.code, primary.message);
+        const err = new GatewayPolicyViolationError(primary.code, primary.message, { routerMetadata });
+        attachRouterEnvelopeToError(err, response);
+        throw err;
     }
     if (primary.retryable) {
-        throw new ProviderInvokeError(primary.code, primary.message, { retryable: true });
+        const err = new ProviderInvokeError(primary.code, primary.message, { retryable: true });
+        attachRouterEnvelopeToError(err, response);
+        throw err;
     }
-    throw new ProviderInvokeError(primary.code, primary.message);
+    const err = new ProviderInvokeError(primary.code, primary.message);
+    attachRouterEnvelopeToError(err, response);
+    throw err;
 }
 export function mapRuntimeErrorToGatewayError(err) {
     if (err instanceof RuntimeConfigError) {

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

@@ -64,6 +64,39 @@ export function buildOpenRouterRuntimeMetadata(response) {
         requestIds: response.id ? [response.id] : undefined,
     };
 }
+export function buildPartialMetadataFromRuntimeResponse(response) {
+    return {
+        serverTools: mapRuntimeToolUsage(response.toolUsage),
+        citations: mapRuntimeCitations(response.citations),
+        generatedImages: mapRuntimeImages(response.images),
+        patchProposals: mapRuntimePatches(response.patches),
+        openrouterRuntime: buildOpenRouterRuntimeMetadata(response),
+    };
+}
+/** Router-shaped envelope for error-chain metadata extraction. */
+export function buildRouterLikeEnvelopeFromRuntimeResponse(response) {
+    const partial = buildPartialMetadataFromRuntimeResponse(response);
+    const usage = response.usage;
+    const promptTokens = usage?.inputTokens ?? 0;
+    const completionTokens = usage?.outputTokens ?? 0;
+    return {
+        requestId: response.id,
+        metadata: {
+            provider: 'openrouter',
+            modelUsed: response.model,
+            serverTools: partial.serverTools,
+            citations: partial.citations,
+            generatedImages: partial.generatedImages,
+            patchProposals: partial.patchProposals,
+            openrouterRuntime: partial.openrouterRuntime,
+        },
+        usage: {
+            promptTokens,
+            completionTokens,
+            totalTokens: usage?.totalTokens ?? promptTokens + completionTokens,
+        },
+    };
+}
 export function extractOpenRouterRuntimeRouterMetadata(routerResponse) {
     if (routerResponse == null || typeof routerResponse !== 'object')
         return {};

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

@@ -15,6 +15,9 @@ export type OpenRouterRuntimeRouterMetadata = {
     costUsd?: number;
     costStatus?: 'priced' | 'unpriced';
 };
+export declare function buildPartialMetadataFromRuntimeResponse(response: RuntimeResponse): OpenRouterRuntimeRouterMetadata;
+/** Router-shaped envelope for error-chain metadata extraction. */
+export declare function buildRouterLikeEnvelopeFromRuntimeResponse(response: RuntimeResponse): Record<string, unknown>;
 export declare function extractOpenRouterRuntimeRouterMetadata(routerResponse: unknown): OpenRouterRuntimeRouterMetadata;
 export declare function parseRuntimeResponseToAIResponse(input: {
     requestId: string;

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

@@ -1,5 +1,7 @@
 export function buildTraceAttemptOpenRouterRuntimeSlice(metadata) {
-    if (!metadata.openrouterRuntime && !metadata.serverTools)
+    const hasPolicy = (metadata.openrouterRuntime?.policyViolations?.length ?? 0) > 0 ||
+        (metadata.openrouterRuntime?.warnings?.length ?? 0) > 0;
+    if (!metadata.openrouterRuntime && !metadata.serverTools && !hasPolicy)
         return undefined;
     return {
         apiMode: metadata.openrouterRuntime?.apiMode,
@@ -7,6 +9,8 @@ export function buildTraceAttemptOpenRouterRuntimeSlice(metadata) {
         citationCount: metadata.citations?.length ?? 0,
         generatedImageCount: metadata.generatedImages?.length ?? 0,
         patchProposalCount: metadata.patchProposals?.length ?? 0,
+        warnings: metadata.openrouterRuntime?.warnings ?? [],
+        policyViolations: metadata.openrouterRuntime?.policyViolations ?? [],
     };
 }
 export function enrichTraceOpenRouterRuntimeMetadata(base, metadata, traceEnabled) {

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

@@ -75,7 +75,7 @@ export function applyPostRoutingServerToolsPolicy(input) {
     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');
+            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';

package/dist-cjs/types.d.ts

@@ -297,8 +297,18 @@ export type GatewayTraceAttempt = {
         citationCount?: number;
         generatedImageCount?: number;
         patchProposalCount?: number;
+        warnings?: GatewayWarning[];
+        policyViolations?: GatewayPolicyViolation[];
     };
 };
+/** OpenRouter tool metadata attached to policy/invoke errors and rejection payloads. */
+export type GatewayOpenRouterErrorMetadata = {
+    serverTools?: GatewayServerToolUsageMap;
+    citations?: GatewayCitation[];
+    generatedImages?: GatewayGeneratedImage[];
+    patchProposals?: GatewayPatchProposal[];
+    openrouterRuntime?: GatewayOpenRouterRuntimeMetadata;
+};
 /**
  * Allowlisted merged router/generation config returned in {@link EnhancedLLMResponse.metadata}
  * when `diagnostics.mode === 'trace'`. Omits arbitrary extras and secrets.
@@ -349,11 +359,33 @@ export type GatewayInvokeRejectionMetadata = {
      * Sourced from {@link FallbackExhaustedError.attempts} on the router error chain.
      */
     fallbackAttempts?: GatewayFallbackAttempt[];
+    /**
+     * Structured per-attempt diagnostics (`@x12i/ai-providers-router` ≥ 4.10).
+     * Same attempts as {@link fallbackAttempts} when enriched; prefer this for UIs.
+     */
+    providerAttempts?: Array<{
+        provider: string;
+        modelId?: string;
+        httpStatus?: number;
+        message: string;
+        code?: string;
+    }>;
+    /** Dominant stable failure sub-code when fallback chain exhausts (router ≥ 4.10). */
+    providerSubCode?: string;
+    /** Short remediation hint from router enrichment (router ≥ 4.10). */
+    operatorHint?: string;
     /**
      * True when {@link mergeConfig} did not run (e.g. message-building threw first).
      * Routing facts may only reflect request.config / modelConfig, not flex-md defaults.
      */
     mergeConfigUnavailable?: true;
+    /** OpenRouter server-tool usage map when available on partial router response or policy error. */
+    serverTools?: GatewayServerToolUsageMap;
+    citations?: GatewayCitation[];
+    generatedImages?: GatewayGeneratedImage[];
+    patchProposals?: GatewayPatchProposal[];
+    openrouterRuntime?: GatewayOpenRouterRuntimeMetadata;
+    policyViolations?: GatewayPolicyViolation[];
 };
 /** Serializable slice of a router fallback attempt for rejection metadata. */
 export type GatewayFallbackAttempt = {
@@ -361,6 +393,8 @@ export type GatewayFallbackAttempt = {
     model?: string;
     httpStatus?: number;
     error: string;
+    /** Stable sub-code from `@x12i/ai-providers-router` ≥ 4.10 (`PROVIDER_AUTH_FAILED`, …). */
+    code?: string;
     responsePreview?: string;
 };
 /**
@@ -523,10 +557,12 @@ export interface ModelConfig {
     stop?: string[];
     /**
      * OpenRouter-only server tools. Ignored unless final provider is openrouter.
+     * Merge precedence at invoke: `modelConfig.serverTools` > `config.serverTools` > `GatewayConfig.defaultServerTools`.
      */
     serverTools?: GatewayServerToolsConfig;
     /**
      * OpenRouter-specific execution controls.
+     * Merge precedence at invoke: `modelConfig.openrouter` > `config.openrouter` > `GatewayConfig.openrouterRuntime` defaults.
      */
     openrouter?: GatewayOpenRouterConfig;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "10.4.1",
+  "version": "10.4.4",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -44,11 +44,11 @@
   "dependencies": {
     "@x12i/activix": "^9.0.2",
     "@x12i/ai-profiles": "^3.4.1",
-    "@x12i/ai-providers-router": "^4.9.2",
+    "@x12i/ai-providers-router": "^4.10.0",
     "@x12i/ai-tools": "^3.3.5",
     "@x12i/flex-md": "^4.8.0",
     "@x12i/logxer": "^5.1.0",
-    "@x12i/openrouter-runtime": "^1.0.2",
+    "@x12i/openrouter-runtime": "^1.0.4",
     "@x12i/rendrix": "^4.3.0"
   },
   "devDependencies": {