@x12i/ai-gateway 10.3.0 → 10.4.0

package/dist-cjs/types.d.ts

@@ -51,6 +51,202 @@ export type GatewayTraceRequestIds = {
     /** Allow additional stable ids without breaking contract. */
     [key: string]: string | undefined;
 };
+export type GatewayServerToolMode = 'disabled' | 'allowed' | 'required';
+export type GatewayNestedServerTool = {
+    type: 'openrouter:web_search';
+    parameters?: Record<string, unknown>;
+} | {
+    type: 'openrouter:web_fetch';
+    parameters?: Record<string, unknown>;
+} | {
+    type: 'openrouter:datetime';
+    parameters?: Record<string, unknown>;
+} | {
+    type: 'openrouter:image_generation';
+    parameters?: Record<string, unknown>;
+};
+export interface GatewayWebSearchToolConfig {
+    mode: GatewayServerToolMode;
+    engine?: 'auto' | 'native' | 'exa' | 'firecrawl' | 'parallel' | 'perplexity';
+    maxResults?: number;
+    maxTotalResults?: number;
+    searchContextSize?: 'low' | 'medium' | 'high';
+    maxCharacters?: number;
+    allowedDomains?: string[];
+    excludedDomains?: string[];
+    userLocation?: {
+        type: 'approximate';
+        city?: string;
+        region?: string;
+        country?: string;
+        timezone?: string;
+    };
+    requireCitations?: boolean;
+    onFailure?: 'fail' | 'warn' | 'continue';
+}
+export interface GatewayWebFetchToolConfig {
+    mode: GatewayServerToolMode;
+    engine?: 'auto' | 'native' | 'exa' | 'openrouter' | 'firecrawl' | 'parallel';
+    maxUses?: number;
+    maxContentTokens?: number;
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+    onFailure?: 'fail' | 'warn' | 'continue';
+}
+export interface GatewayDatetimeToolConfig {
+    mode: GatewayServerToolMode;
+    timezone?: string;
+}
+export interface GatewayImageGenerationToolConfig {
+    mode: GatewayServerToolMode;
+    model?: string;
+    quality?: 'low' | 'medium' | 'high' | string;
+    size?: string;
+    aspectRatio?: string;
+    background?: string;
+    outputFormat?: 'png' | 'jpeg' | 'webp' | string;
+    outputCompression?: number;
+    moderation?: string;
+}
+export interface GatewayApplyPatchToolConfig {
+    mode: GatewayServerToolMode;
+    behavior?: 'return_only' | 'apply_with_callback';
+    allowCreate?: boolean;
+    allowUpdate?: boolean;
+    allowDelete?: boolean;
+    workspaceRoot?: string;
+}
+export interface GatewayFusionToolConfig {
+    mode: GatewayServerToolMode;
+    analysisModels?: string[];
+    judgeModel?: string;
+    maxToolCalls?: number;
+    maxCompletionTokens?: number;
+    temperature?: number;
+    reasoning?: {
+        effort?: 'low' | 'medium' | 'high';
+        maxTokens?: number;
+    };
+}
+export interface GatewayAdvisorToolConfig {
+    mode: GatewayServerToolMode;
+    name?: string;
+    model?: string;
+    instructions?: string;
+    tools?: GatewayNestedServerTool[];
+    forwardTranscript?: boolean;
+    stream?: boolean;
+    maxToolCalls?: number;
+    maxCompletionTokens?: number;
+    temperature?: number;
+    reasoning?: {
+        effort?: 'low' | 'medium' | 'high';
+        maxTokens?: number;
+    };
+}
+export interface GatewaySubagentToolConfig {
+    mode: GatewayServerToolMode;
+    model?: string;
+    instructions?: string;
+    tools?: GatewayNestedServerTool[];
+    maxToolCalls?: number;
+    maxCompletionTokens?: number;
+    temperature?: number;
+    reasoning?: {
+        effort?: 'low' | 'medium' | 'high';
+        maxTokens?: number;
+    };
+}
+export interface GatewayServerToolsConfig {
+    webSearch?: GatewayWebSearchToolConfig;
+    webFetch?: GatewayWebFetchToolConfig;
+    datetime?: GatewayDatetimeToolConfig;
+    imageGeneration?: GatewayImageGenerationToolConfig;
+    applyPatch?: GatewayApplyPatchToolConfig;
+    fusion?: GatewayFusionToolConfig;
+    advisor?: GatewayAdvisorToolConfig | GatewayAdvisorToolConfig[];
+    subagent?: GatewaySubagentToolConfig;
+}
+export interface GatewayOpenRouterConfig {
+    apiMode?: 'chat' | 'responses' | 'auto';
+    rawOverrides?: Record<string, unknown>;
+    includeRawInTrace?: boolean;
+}
+export interface GatewayOpenRouterRuntimeConfig {
+    enabled?: boolean;
+    apiMode?: 'chat' | 'responses' | 'auto';
+    includeRawInTrace?: boolean;
+}
+export interface GatewayServerToolUsage {
+    requested: boolean;
+    required: boolean;
+    used: boolean;
+    callCount?: number;
+    policyViolation?: string;
+}
+export interface GatewayServerToolUsageMap {
+    webSearch?: GatewayServerToolUsage;
+    webFetch?: GatewayServerToolUsage;
+    datetime?: GatewayServerToolUsage;
+    imageGeneration?: GatewayServerToolUsage;
+    applyPatch?: GatewayServerToolUsage;
+    fusion?: GatewayServerToolUsage;
+    advisor?: GatewayServerToolUsage;
+    subagent?: GatewayServerToolUsage;
+}
+export interface GatewayCitation {
+    type: 'url';
+    url: string;
+    title?: string;
+    excerpt?: string;
+    startIndex?: number;
+    endIndex?: number;
+    sourceProvider: 'openrouter';
+}
+export interface GatewayGeneratedImage {
+    imageUrl: string;
+    status: 'ok' | 'error';
+    error?: string;
+    raw?: unknown;
+}
+export interface GatewayPatchProposal {
+    callId: string;
+    status: 'completed' | 'failed';
+    operation: {
+        type: 'create_file';
+        path: string;
+        diff: string;
+    } | {
+        type: 'update_file';
+        path: string;
+        diff: string;
+    } | {
+        type: 'delete_file';
+        path: string;
+    };
+    raw?: unknown;
+}
+export interface GatewayWarning {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export interface GatewayPolicyViolation {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export interface GatewayOpenRouterRuntimeMetadata {
+    apiMode: 'chat' | 'responses';
+    warnings: GatewayWarning[];
+    policyViolations: GatewayPolicyViolation[];
+    requestIds?: string[];
+    serverToolsRequested?: GatewayServerToolUsageMap;
+    serverToolsUsed?: GatewayServerToolUsageMap;
+    citations?: GatewayCitation[];
+    generatedImages?: GatewayGeneratedImage[];
+    patchProposals?: GatewayPatchProposal[];
+}
 export type GatewayTraceAttempt = {
     timing: {
         startedAt: number;
@@ -95,6 +291,13 @@ export type GatewayTraceAttempt = {
      * The exact shape is intentionally loose to avoid locking downstream to provider schemas.
      */
     rawProviderPayload?: unknown;
+    openrouterRuntime?: {
+        apiMode?: 'chat' | 'responses';
+        serverTools?: GatewayServerToolUsageMap;
+        citationCount?: number;
+        generatedImageCount?: number;
+        patchProposalCount?: number;
+    };
 };
 /**
  * Allowlisted merged router/generation config returned in {@link EnhancedLLMResponse.metadata}
@@ -115,6 +318,8 @@ export type GatewayTraceUsageSummary = {
     cost?: number;
     costStatus?: 'priced' | 'unpriced';
     costBreakdown?: GatewayTraceAttempt['costBreakdown'];
+    serverTools?: GatewayServerToolUsageMap;
+    citations?: GatewayCitation[];
 };
 export type GatewayTraceMergedConfig = Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP' | 'frequencyPenalty' | 'presencePenalty' | 'stop'>>;
 /**
@@ -316,11 +521,21 @@ export interface ModelConfig {
      * Generation stops when any stop sequence is encountered
      */
     stop?: string[];
+    /**
+     * OpenRouter-only server tools. Ignored unless final provider is openrouter.
+     */
+    serverTools?: GatewayServerToolsConfig;
+    /**
+     * OpenRouter-specific execution controls.
+     */
+    openrouter?: GatewayOpenRouterConfig;
     /**
      * Additional provider-specific parameters
      */
     [key: string]: any;
 }
+/** Alias for {@link ModelConfig} in gateway documentation. */
+export type GatewayModelConfig = ModelConfig;
 export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'logger'> {
     /**
      * Default target (engine + model) for routing
@@ -397,6 +612,15 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
     openRouter?: {
         prefer?: boolean;
     };
+    /**
+     * Default OpenRouter server tool policy merged into every invoke (lowest priority).
+     */
+    defaultServerTools?: GatewayServerToolsConfig;
+    /**
+     * OpenRouter runtime integration defaults.
+     * @default `{ enabled: true, apiMode: 'auto', includeRawInTrace: false }`
+     */
+    openrouterRuntime?: GatewayOpenRouterRuntimeConfig;
     /**
      * Operational mode override (`process.env.mode` / `MODE` when omitted; default `debug`).
      * Downstream hosts (ai-skills, ai-tasks, graph-engine) should expose this to their clients.
@@ -1035,6 +1259,16 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          * Reflects gateway merge order: modelConfig / request.config / defaults.
          */
         effectiveModelConfig?: Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP'>>;
+        /** OpenRouter server tool usage summary (additive). */
+        serverTools?: GatewayServerToolUsageMap;
+        /** Citations extracted by OpenRouter runtime (additive). */
+        citations?: GatewayCitation[];
+        /** Generated image metadata from OpenRouter runtime (additive). */
+        generatedImages?: GatewayGeneratedImage[];
+        /** Patch proposals from OpenRouter runtime — never applied by the gateway (additive). */
+        patchProposals?: GatewayPatchProposal[];
+        /** OpenRouter runtime execution metadata (additive). */
+        openrouterRuntime?: GatewayOpenRouterRuntimeMetadata;
         /**
          * Stable request/correlation identifiers across gateway/router/provider layers.
          * Only populated when diagnostics trace mode is enabled.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "10.3.0",
+  "version": "10.4.0",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -28,6 +28,7 @@
     "test:flex-md-parsing": "tsx .tests/flex-md-parsing-scenarios.test.ts",
     "test:flex-md-esm-regression": "npm run build:esm && node .tests/flex-md-esm-regression.test.mjs",
     "test:live": "npm run test:ai-tools:live",
+    "test:openrouter-live": "tsx .tests/openrouter-runtime-live.test.ts",
     "test:prepublish": "npm run build && npm test",
     "deps:latest": "npx npm-check-updates -u && npm install"
   },
@@ -41,12 +42,13 @@
   "author": "x12i",
   "license": "mit",
   "dependencies": {
-    "@x12i/activix": "^9.0.0",
-    "@x12i/ai-profiles": "^3.4.0",
+    "@x12i/activix": "^9.0.2",
+    "@x12i/ai-profiles": "^3.4.1",
     "@x12i/ai-providers-router": "^4.9.2",
-    "@x12i/ai-tools": "^3.3.3",
+    "@x12i/ai-tools": "^3.3.5",
     "@x12i/flex-md": "^4.8.0",
-    "@x12i/logxer": "^4.6.0",
+    "@x12i/logxer": "^5.1.0",
+    "@x12i/openrouter-runtime": "^1.0.2",
     "@x12i/rendrix": "^4.3.0"
   },
   "devDependencies": {