@x12i/ai-gateway 10.0.6 → 10.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @x12i/ai-gateway
 
-Unified gateway for LLM provider routing, structured logging, optional Activix activity persistence, and cost/model resolution via **@x12i/ai-tools** v2. Built on **@x12i/ai-providers-router**, **@x12i/logxer**, **@x12i/rendrix** (templates), and **@x12i/flex-md** (output-format hints and max-token lookup).
+Unified gateway for LLM provider routing, structured logging, optional Activix activity persistence, and cost/model resolution via **@x12i/ai-tools** v3. Built on **@x12i/ai-providers-router**, **@x12i/logxer**, **@x12i/rendrix** (templates), and **@x12i/flex-md** (output-format hints and max-token lookup).
 
 ## What this package does
 
@@ -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 ^8.5**, **ai-tools ^2.5**, **ai-providers-router ^4.9**).
+Pinned dependency versions are in `package.json` (currently **Activix ^8.6**, **ai-tools ^3.0**, **ai-providers-router ^4.9**).
 
 ---
 
@@ -148,7 +148,7 @@ import {
 
 **Required on every invoke:** `config.model` (or `modelConfig.model`) and `maxTokens` (`request.config`, `modelConfig`, `GatewayConfig`, or `internalSystemActions`). Missing model → `ModelRequiredError` (`code: 'MODEL_REQUIRED'`). Missing `maxTokens` → `MaxTokensRequiredError` (`code: 'MAX_TOKENS_REQUIRED'`). There is **no** packaged default model, **no** flex-md / Optimixer auto-fill, and **no** `GATEWAY_DEFAULT_MAX_TOKENS`. Use [@x12i/optimixer](https://www.npmjs.com/package/@x12i/optimixer) in the **client** that wraps this gateway if you want adaptive completion budgets.
 
-**Rate limiting:** removed from the gateway. See [AI_PROVIDER_ROUTER_RATE_LIMITING_FEATURE_REQUEST.md](./docs/AI_PROVIDER_ROUTER_RATE_LIMITING_FEATURE_REQUEST.md) — implement in `@x12i/ai-providers-router`.
+**Rate limiting:** removed from the gateway. See [upstream rate-limit spec](./docs/upstream-reports/AI_PROVIDER_ROUTER_RATE_LIMITING.md) — implement in `@x12i/ai-providers-router`.
 
 ### Template rendering (`defaults/template-rendering.json`)
 
@@ -184,7 +184,8 @@ Instructions must be **complete caller text** — the gateway no longer injects
 
 | Variable | Role |
 |----------|------|
-| `MONGO_URI`, `MONGO_LOGS_DB` / `MONGO_DB` | Activix when no custom tracker |
+| `MONGO_URI`, `MONGO_LOGS_DB` / `MONGO_DB` / `MONGO_AI_LOGS_DB` | Activix when no custom tracker |
+| `ACTIVIX_DB_NAME` | Activix database override (falls back to `MONGO_AI_LOGS_DB` → `MONGO_LOGS_DB` → `MONGO_DB`) |
 | `mode` / `MODE` | Operational mode (`dev`, `debug`, `prod`) — expose to downstream clients |
 | `AI_GATEWAY_LOGS_LEVEL` | Log threshold for gateway diagnostics (`AI_GATEWAY` prefix): `error` … `verbose` |
 | `AI_GATEWAY_VERBOSE` | Full payload lines (still requires `AI_GATEWAY_LOGS_LEVEL=verbose`) |
@@ -241,13 +242,13 @@ Implemented in **`resolveCostCompletionWithAiTools`** only ( **`CostCalculator.c
 
 - **No Catalox / Firestore** — catalogs come from ai-tools open-assets JSON (optional **`bundledOnly`**).
 
-Gateway exports the model orchestrator from `@x12i/ai-tools` ≥ **2.5.0** (`resolveInvokeModel`, …) — see [AI_TOOLS_INVOKE_MODEL_RESOLUTION_ORCHESTRATOR_SPEC.md](./docs/upstream-reports/AI_TOOLS_INVOKE_MODEL_RESOLUTION_ORCHESTRATOR_SPEC.md).
+Gateway exports the model orchestrator from `@x12i/ai-tools` ≥ **3.0.0** (`resolveInvokeModel`, `useOpenRouter`, …). v3 requires **`profile/choice`** keys (e.g. `cheap/default`) or concrete catalog ids — shortcuts like `cheapest` / bare `cheap` are rejected.
 
 Gateway billing helpers (exported for tests/integrators): `resolveCostCompletionWithAiTools`, `buildGatewayPricingRecord`, `catalogPricingSucceeded`, `buildTraceUsageSummary`, `enrichTraceAttemptsWithBilling`.
 
 ---
 
-## Activity tracking (@x12i/activix 8.x)
+## Activity tracking (@x12i/activix 8.6)
 
 When tracking is enabled and no custom tracker is supplied, the gateway constructs Activix with fixed collection names (see `src/config/activity-tracking-config.ts`):
 
@@ -261,12 +262,14 @@ When tracking is enabled and no custom tracker is supplied, the gateway construc
 
 **Successful completion** (no duplicate billing on `outer.metadata`):
 
-- Root: `cost`, `costUsd`, `costStatus`, **`metadata`** (routing + billing mirror for Activix 7.x)
+- Root: `cost`, `costUsd`, `costStatus`, **`metadata`** (routing + billing mirror; **`metadata.modelUsed`** for studio)
 - `outer.metadata`: routing only (`modelUsed`, `provider`, …)
 - `outer.cost`: Activix cost shape (`usd`, `tokens`, `provider`, `model`, `details`)
 - `response.metadata`: same billing slice as returned to callers
 
-Gateway resolves billing **before** `completeRecord` and sets **`outer.cost`** from that slice. Activix **`autoCost`** is **not** used on the default activity manager (no second pricing path).
+Activix **8.6** runs **`materializeRecordRoutingAndBilling`** on persist (root **`config`** mirror from routing metadata). Gateway resolves billing **before** `completeRecord` and sets **`outer.cost`** from that slice.
+
+**`autoCost`:** Activix 8.6 default is **`false`**. The gateway keeps **`autoCost: false`** on the default activity manager so billing is not recomputed via ai-tools at persist time (no second pricing path). Custom **`activityTracker`** instances may opt in to Activix **`autoCost`** (uses **@x12i/ai-tools** v3 **`calculateFromRecord`** when enabled).
 
 Mongo env: `MONGO_URI` + `MONGO_LOGS_DB` or `MONGO_DB`.
 
@@ -335,20 +338,17 @@ Live tests use `LIVE_TEST_PROVIDER` / `LIVE_TEST_MODEL` (default `openrouter` +
 
 ## Documentation index
 
+Full index: **[docs/README.md](./docs/README.md)**. Upstream gaps: **[docs/upstream-reports/](./docs/upstream-reports/README.md)**.
+
 | Document | Topic |
 |----------|--------|
-| [IDENTITY_OBJECT_CONTRACT.md](./docs/IDENTITY_OBJECT_CONTRACT.md) | Identity / `runContext` |
 | [AI_GATEWAY_INVOKE_EXECUTION_METADATA.md](./docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md) | Metadata, cost, trace, Activix completion |
-| [LOGGER_INITIALIZATION.md](./docs/LOGGER_INITIALIZATION.md) | Logxer setup |
-| [flex-md-compliance.md](./docs/flex-md-compliance.md) | Output format levels |
-| [PROMPT_TEMPLATE_USAGE.md](./docs/PROMPT_TEMPLATE_USAGE.md) | Rendrix templates |
-| [OPENROUTER_ENV.md](./docs/OPENROUTER_ENV.md) | `OPENROUTER_API_KEY` and `USE_OPENROUTER` semantics |
-| [UPSTREAM_PROFILE_RESOLUTION_AND_OPENROUTER_FALLBACK.md](./docs/UPSTREAM_PROFILE_RESOLUTION_AND_OPENROUTER_FALLBACK.md) | Profile routing and OpenRouter fallback checklist |
-| [upstream-reports/README.md](./docs/upstream-reports/README.md) | Upstream issues (one file per package/gap) |
-| [AI_PROVIDER_ROUTER_RATE_LIMITING_FEATURE_REQUEST.md](./docs/AI_PROVIDER_ROUTER_RATE_LIMITING_FEATURE_REQUEST.md) | Router rate-limit FR (gateway no longer sleeps between calls) |
-| [RUNTIME_OBJECTS_OBSERVABILITY.md](./docs/RUNTIME_OBJECTS_OBSERVABILITY.md) | Runtime object keys |
+| [IDENTITY_OBJECT_CONTRACT.md](./docs/IDENTITY_OBJECT_CONTRACT.md) | Identity / `runContext` |
+| [OPENROUTER_ENV.md](./docs/OPENROUTER_ENV.md) | `OPENROUTER_API_KEY` and `USE_OPENROUTER` |
+| [UPSTREAM_PROFILE_RESOLUTION_AND_OPENROUTER_FALLBACK.md](./docs/UPSTREAM_PROFILE_RESOLUTION_AND_OPENROUTER_FALLBACK.md) | Profile routing + OpenRouter fallback |
 | [UPSTREAM_TEMPLATE_RENDERING_AND_PARSER_V4.md](./docs/UPSTREAM_TEMPLATE_RENDERING_AND_PARSER_V4.md) | Parser v4 + `template-rendering.json` |
 | [GRAPH_EXECUTION_SUPPORT.md](./docs/GRAPH_EXECUTION_SUPPORT.md) | Graph / node identity |
+| [LOGGER_INITIALIZATION.md](./docs/LOGGER_INITIALIZATION.md) | Logxer setup |
 | [DUAL_PACKAGE_SETUP_GUIDE.md](./docs/DUAL_PACKAGE_SETUP_GUIDE.md) | ESM + CJS publish layout |
 
 ---

package/dist/activity-manager.d.ts

@@ -32,8 +32,8 @@ export interface ActivityManagerConfig {
     customTracker?: Activix;
     logger: Logxer;
     /**
-     * Activix 7.2+ {@link ActivixAutoCostOptions}: fill `outer.cost` via @x12i/ai-tools when the gateway
-     * did not supply a valid cost. Ignored when `customTracker` is provided.
+     * Activix 8.6+ {@link ActivixAutoCostOptions}: optional persist-time cost via @x12i/ai-tools v3.
+     * Default gateway manager leaves this off — billing is set before completeRecord.
      */
     autoCost?: boolean | ActivixAutoCostOptions;
 }

package/dist/activity-manager.js

@@ -165,7 +165,7 @@ function pickActivixUsageTokens(response) {
     };
 }
 /**
- * Activix 7.x `outer.cost` from gateway billing + routing (Run Analysis G8).
+ * Activix 8.x `outer.cost` from gateway billing + routing (Run Analysis G8).
  * Uses Activix {@link normalizeToActivixCostShape} so the shape matches package validators.
  */
 function buildActivixOuterCost(routingMeta, billing, response) {
@@ -193,7 +193,7 @@ function buildActivixOuterCost(routingMeta, billing, response) {
     };
     return normalizeToActivixCostShape(candidate, 'gateway.outer.cost') ?? undefined;
 }
-/** Run-level record metadata (Activix 7.x top-level `metadata`, sibling to `outer`). */
+/** Run-level record metadata (Activix 8.x top-level `metadata`, sibling to `outer`). */
 function buildActivixRecordMetadata(response, billing) {
     const out = {
         ...pickActivixCompletionRoutingMetadata(response)

package/dist/ai-tools-client.d.ts

@@ -6,8 +6,10 @@ import { type AiToolsInvokeClient, type ModelResolutionSuccess, type OpenRouterR
 import type { Logxer } from '@x12i/logxer';
 import type { GatewayConfig } from './types.js';
 export type AiToolsClientBundle = AiToolsInvokeClient;
-export { resolveInvokeModel, applyOpenRouterInvokePolicy, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
-export { resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv } from './openrouter-routing.js';
+export { resolveInvokeModel, applyOpenRouterInvokeRouting, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
+/** @deprecated Use `applyOpenRouterInvokeRouting` (ai-tools v3). */
+export { applyOpenRouterInvokeRouting as applyOpenRouterInvokePolicy } from '@x12i/ai-tools';
+export { resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
 export type { InvokeModelResolutionDiagnostics, InvokeModelResolutionInput, InvokeModelResolutionOptions, InvokeModelResolutionResult, InvokeRouterConfigSlice, AiToolsInvokeClient, } from '@x12i/ai-tools';
 /** @deprecated Use buildInvokeModelResolverOptions */
 export declare function buildModelResolverOptions(config: GatewayConfig, routingEnv?: OpenRouterRoutingConfig): import("@x12i/ai-tools").ModelResolverOptions;

package/dist/ai-tools-client.js

@@ -4,9 +4,11 @@
  */
 import { getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, CostCalculator, } from '@x12i/ai-tools';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
-import { resolvePreferOpenRouter } from './openrouter-routing.js';
-export { resolveInvokeModel, applyOpenRouterInvokePolicy, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
-export { resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv } from './openrouter-routing.js';
+import { resolveUseOpenRouter } from './openrouter-routing.js';
+export { resolveInvokeModel, applyOpenRouterInvokeRouting, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
+/** @deprecated Use `applyOpenRouterInvokeRouting` (ai-tools v3). */
+export { applyOpenRouterInvokeRouting as applyOpenRouterInvokePolicy } from '@x12i/ai-tools';
+export { resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
 let bootstrapFailedLogged = false;
 function invokeClientOptions(config) {
     return {
@@ -26,7 +28,8 @@ function withCatalogLaneCalculator(client, config) {
             ...(config.aiTools?.costIncludeBreakdown ? { includeBreakdown: true } : {}),
             resolverOptions: buildInvokeModelResolverOptions({
                 routingEnv: client.routingEnv,
-                catalogLane: lane
+                catalogLane: lane,
+                useOpenRouter: resolveUseOpenRouter(config),
             })
         })
     };
@@ -35,7 +38,7 @@ function withCatalogLaneCalculator(client, config) {
 export function buildModelResolverOptions(config, routingEnv) {
     return buildInvokeModelResolverOptions({
         routingEnv,
-        preferOpenRouter: resolvePreferOpenRouter(config),
+        useOpenRouter: resolveUseOpenRouter(config),
     });
 }
 /**

package/dist/gateway-config.d.ts

@@ -37,6 +37,6 @@ export declare function initializeGatewayComponents(config: GatewayConfig): {
     activityManager: ActivityManager;
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
-    preferOpenRouter: boolean;
+    useOpenRouter: boolean;
     openRouterApiKey?: string;
 };

package/dist/gateway-config.js

@@ -5,7 +5,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { resolveOpenRouterApiKey, resolvePreferOpenRouter, } from './openrouter-routing.js';
+import { resolveOpenRouterApiKey, resolveUseOpenRouter, } from './openrouter-routing.js';
 import { LLMProviderRouter } from '@x12i/ai-providers-router';
 import { createGatewayLogger } from './logger-factory.js';
 import { ActivityManager } from './activity-manager.js';
@@ -154,14 +154,14 @@ export function initializeGatewayComponents(config) {
     if (config.logging !== undefined)
         routerConfig.logging = config.logging;
     const openRouterKey = resolveOpenRouterApiKey(config);
-    const preferOpenRouter = resolvePreferOpenRouter(config);
+    const useOpenRouter = resolveUseOpenRouter(config);
     if (openRouterKey) {
         routerConfig.openrouter = { apiKey: openRouterKey };
         routerConfig.openRouter = {
             enabled: true,
-            prefer: preferOpenRouter,
+            prefer: useOpenRouter,
         };
-        if (preferOpenRouter) {
+        if (useOpenRouter) {
             routerConfig.defaultMode = 'openrouter';
         }
     }
@@ -190,7 +190,7 @@ export function initializeGatewayComponents(config) {
         activityManager,
         usageTracker,
         messageBuilderConfig,
-        preferOpenRouter,
+        useOpenRouter,
         openRouterApiKey: openRouterKey,
     };
 }

package/dist/gateway-utils.d.ts

@@ -17,7 +17,7 @@ export type MergeConfigOptions = {
     catalog?: AiModelsCatalogClient | null;
     routingEnv?: OpenRouterRoutingConfig;
     openRouterApiKey?: string;
-    preferOpenRouter?: boolean;
+    useOpenRouter?: boolean;
 };
 export { MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, } from '@x12i/ai-tools';
 /**

package/dist/gateway-utils.js

@@ -104,7 +104,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
                 catalog: mergeOptions.catalog,
                 routingEnv: mergeOptions.routingEnv,
                 openRouterApiKey: mergeOptions.openRouterApiKey,
-                preferOpenRouter: mergeOptions.preferOpenRouter,
+                useOpenRouter: mergeOptions.useOpenRouter,
                 defaultProvider: config.defaultEngine,
                 resolveModels: true,
                 modelsOnly: config.aiTools?.modelsOnly !== false,
@@ -146,7 +146,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
             resolveModels: false,
             routingEnv: mergeOptions.routingEnv,
             openRouterApiKey: mergeOptions.openRouterApiKey,
-            preferOpenRouter: mergeOptions.preferOpenRouter,
+            useOpenRouter: mergeOptions.useOpenRouter,
             defaultProvider: config.defaultEngine,
         });
         merged.provider = resolved.router.provider;
@@ -512,7 +512,14 @@ export async function resolveCostCompletionWithAiTools(routerResponse, tokens, o
         options?.calculator &&
         hasNonZeroTokenUsage(tokens)) {
         try {
-            const record = buildGatewayPricingRecord(routerResponse, tokens, options.mergedConfig);
+            const record = routerResponse != null && typeof routerResponse === 'object'
+                ? {
+                    ...routerResponse,
+                    ...(options.mergedConfig != null ? { config: options.mergedConfig } : {})
+                }
+                : options.mergedConfig != null
+                    ? { config: options.mergedConfig, metadata: { tokens } }
+                    : { metadata: { tokens } };
             const result = await options.calculator.calculateFromRecord(record);
             billing = mapAiCostResultToResolvedActivityCost(billing, result);
         }

package/dist/gateway.d.ts

@@ -18,7 +18,7 @@ export declare class AIGateway {
     private messageBuilderConfig?;
     private _autoRegisterDone;
     private _aiToolsClient;
-    private readonly preferOpenRouter;
+    private readonly useOpenRouter;
     private readonly openRouterApiKey?;
     constructor(config?: GatewayConfig, activityManager?: ActivityManager);
     /**

package/dist/gateway.js

@@ -59,7 +59,7 @@ export class AIGateway {
     messageBuilderConfig;
     _autoRegisterDone = false;
     _aiToolsClient = null;
-    preferOpenRouter;
+    useOpenRouter;
     openRouterApiKey;
     constructor(config = {}, activityManager) {
         this.config = config;
@@ -69,7 +69,7 @@ export class AIGateway {
         this.router = components.router;
         this.activityManager = components.activityManager;
         this.messageBuilderConfig = components.messageBuilderConfig;
-        this.preferOpenRouter = components.preferOpenRouter;
+        this.useOpenRouter = components.useOpenRouter;
         this.openRouterApiKey = components.openRouterApiKey;
         setGatewayRuntimeClients({
             activix: this.activityManager?.getTracker(),
@@ -100,7 +100,7 @@ export class AIGateway {
                 catalog: aiTools?.catalog ?? null,
                 routingEnv: aiTools?.routingEnv,
                 openRouterApiKey: this.openRouterApiKey,
-                preferOpenRouter: this.preferOpenRouter,
+                useOpenRouter: this.useOpenRouter,
             });
             // Activix start snapshot must match what the router receives (modelConfig-only callers omit request.config.model).
             request._mergedRouterConfig = mergedConfig;
@@ -288,7 +288,7 @@ export class AIGateway {
                 catalog: aiTools?.catalog ?? null,
                 routingEnv: aiTools?.routingEnv,
                 openRouterApiKey: this.openRouterApiKey,
-                preferOpenRouter: this.preferOpenRouter,
+                useOpenRouter: this.useOpenRouter,
             });
             request._mergedRouterConfig = mergedConfig;
             logResolvedModelRouting(this.logger, request, mergedConfig);

package/dist/index.d.ts

@@ -40,8 +40,8 @@ export type { GatewayLoggerConfig } from './logger-factory.js';
 export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
 export type { GatewayLogCode as GatewayDiagnosticCode } from './gateway-log-diagnostics.js';
-/** Re-export @x12i/ai-tools invoke orchestrator (≥ 2.5.0) for engine callers. */
-export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
+/** Re-export @x12i/ai-tools invoke orchestrator (≥ 3.0.0) for engine callers. */
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
 export type { AiToolsClientBundle, AiToolsInvokeClient, InvokeModelResolutionDiagnostics, InvokeModelResolutionInput, InvokeModelResolutionOptions, InvokeModelResolutionResult, InvokeRouterConfigSlice, } from './ai-tools-client.js';
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';
 export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';

package/dist/index.js

@@ -33,8 +33,8 @@ export { activityIdentityToLogContext, activityIdentityToLogMeta, withActivityId
 export { createGatewayLogger, resolveGatewayVerboseEnabled } from './logger-factory.js';
 export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
-/** Re-export @x12i/ai-tools invoke orchestrator (≥ 2.5.0) for engine callers. */
-export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
+/** Re-export @x12i/ai-tools invoke orchestrator (≥ 3.0.0) for engine callers. */
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
 // Re-export logging (@x12i/logxer)
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';
 export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';

package/dist/openrouter-routing.d.ts

@@ -1,8 +1,16 @@
 /**
- * Gateway-level OpenRouter key + prefer flags mapped to @x12i/ai-tools invoke helpers.
+ * Gateway-level OpenRouter key + USE_OPENROUTER flags mapped to @x12i/ai-tools v3 invoke helpers.
  */
-import { readPreferOpenRouterFromEnv } from '@x12i/ai-tools';
+import { readUseOpenRouterFromEnv } from '@x12i/ai-profiles';
 import type { GatewayConfig } from './types.js';
-export { readPreferOpenRouterFromEnv };
+export { readUseOpenRouterFromEnv };
 export declare function resolveOpenRouterApiKey(config?: GatewayConfig): string | undefined;
+/**
+ * Effective OpenRouter preference for invoke-time routing (ai-tools `useOpenRouter`).
+ * Constructor `openRouter.prefer` / `openRouter.enabled` override env `USE_OPENROUTER`.
+ */
+export declare function resolveUseOpenRouter(config?: GatewayConfig): boolean;
+/** @deprecated Use {@link resolveUseOpenRouter} (ai-tools v3 renamed prefer → useOpenRouter). */
 export declare function resolvePreferOpenRouter(config?: GatewayConfig): boolean;
+/** @deprecated Use {@link readUseOpenRouterFromEnv} from `@x12i/ai-profiles`. */
+export declare function readPreferOpenRouterFromEnv(): boolean;

package/dist/openrouter-routing.js

@@ -1,12 +1,17 @@
 /**
- * Gateway-level OpenRouter key + prefer flags mapped to @x12i/ai-tools invoke helpers.
+ * Gateway-level OpenRouter key + USE_OPENROUTER flags mapped to @x12i/ai-tools v3 invoke helpers.
  */
-import { readPreferOpenRouterFromEnv, resolveOpenRouterApiKey as resolveOpenRouterApiKeyFromTools, resolvePreferOpenRouter as resolvePreferFromTools, } from '@x12i/ai-tools';
-export { readPreferOpenRouterFromEnv };
+import { resolveOpenRouterApiKey as resolveOpenRouterApiKeyFromTools, resolveUseOpenRouterPreference, } from '@x12i/ai-tools';
+import { readUseOpenRouterFromEnv } from '@x12i/ai-profiles';
+export { readUseOpenRouterFromEnv };
 export function resolveOpenRouterApiKey(config = {}) {
     return resolveOpenRouterApiKeyFromTools(config.openrouter?.apiKey);
 }
-export function resolvePreferOpenRouter(config = {}) {
+/**
+ * Effective OpenRouter preference for invoke-time routing (ai-tools `useOpenRouter`).
+ * Constructor `openRouter.prefer` / `openRouter.enabled` override env `USE_OPENROUTER`.
+ */
+export function resolveUseOpenRouter(config = {}) {
     if (config.openRouter?.prefer === true)
         return true;
     if (config.openRouter?.prefer === false)
@@ -15,5 +20,13 @@ export function resolvePreferOpenRouter(config = {}) {
         return true;
     if (config.openRouter?.enabled === false)
         return false;
-    return resolvePreferFromTools();
+    return resolveUseOpenRouterPreference();
+}
+/** @deprecated Use {@link resolveUseOpenRouter} (ai-tools v3 renamed prefer → useOpenRouter). */
+export function resolvePreferOpenRouter(config = {}) {
+    return resolveUseOpenRouter(config);
+}
+/** @deprecated Use {@link readUseOpenRouterFromEnv} from `@x12i/ai-profiles`. */
+export function readPreferOpenRouterFromEnv() {
+    return readUseOpenRouterFromEnv() ?? true;
 }

package/dist-cjs/activity-manager.cjs

@@ -165,7 +165,7 @@ function pickActivixUsageTokens(response) {
     };
 }
 /**
- * Activix 7.x `outer.cost` from gateway billing + routing (Run Analysis G8).
+ * Activix 8.x `outer.cost` from gateway billing + routing (Run Analysis G8).
  * Uses Activix {@link normalizeToActivixCostShape} so the shape matches package validators.
  */
 function buildActivixOuterCost(routingMeta, billing, response) {
@@ -193,7 +193,7 @@ function buildActivixOuterCost(routingMeta, billing, response) {
     };
     return normalizeToActivixCostShape(candidate, 'gateway.outer.cost') ?? undefined;
 }
-/** Run-level record metadata (Activix 7.x top-level `metadata`, sibling to `outer`). */
+/** Run-level record metadata (Activix 8.x top-level `metadata`, sibling to `outer`). */
 function buildActivixRecordMetadata(response, billing) {
     const out = {
         ...pickActivixCompletionRoutingMetadata(response)

package/dist-cjs/activity-manager.d.ts

@@ -32,8 +32,8 @@ export interface ActivityManagerConfig {
     customTracker?: Activix;
     logger: Logxer;
     /**
-     * Activix 7.2+ {@link ActivixAutoCostOptions}: fill `outer.cost` via @x12i/ai-tools when the gateway
-     * did not supply a valid cost. Ignored when `customTracker` is provided.
+     * Activix 8.6+ {@link ActivixAutoCostOptions}: optional persist-time cost via @x12i/ai-tools v3.
+     * Default gateway manager leaves this off — billing is set before completeRecord.
      */
     autoCost?: boolean | ActivixAutoCostOptions;
 }

package/dist-cjs/ai-tools-client.cjs

@@ -4,9 +4,11 @@
  */
 import { getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, CostCalculator, } from '@x12i/ai-tools';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
-import { resolvePreferOpenRouter } from './openrouter-routing.js';
-export { resolveInvokeModel, applyOpenRouterInvokePolicy, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
-export { resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv } from './openrouter-routing.js';
+import { resolveUseOpenRouter } from './openrouter-routing.js';
+export { resolveInvokeModel, applyOpenRouterInvokeRouting, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
+/** @deprecated Use `applyOpenRouterInvokeRouting` (ai-tools v3). */
+export { applyOpenRouterInvokeRouting as applyOpenRouterInvokePolicy } from '@x12i/ai-tools';
+export { resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
 let bootstrapFailedLogged = false;
 function invokeClientOptions(config) {
     return {
@@ -26,7 +28,8 @@ function withCatalogLaneCalculator(client, config) {
             ...(config.aiTools?.costIncludeBreakdown ? { includeBreakdown: true } : {}),
             resolverOptions: buildInvokeModelResolverOptions({
                 routingEnv: client.routingEnv,
-                catalogLane: lane
+                catalogLane: lane,
+                useOpenRouter: resolveUseOpenRouter(config),
             })
         })
     };
@@ -35,7 +38,7 @@ function withCatalogLaneCalculator(client, config) {
 export function buildModelResolverOptions(config, routingEnv) {
     return buildInvokeModelResolverOptions({
         routingEnv,
-        preferOpenRouter: resolvePreferOpenRouter(config),
+        useOpenRouter: resolveUseOpenRouter(config),
     });
 }
 /**

package/dist-cjs/ai-tools-client.d.ts

@@ -6,8 +6,10 @@ import { type AiToolsInvokeClient, type ModelResolutionSuccess, type OpenRouterR
 import type { Logxer } from '@x12i/logxer';
 import type { GatewayConfig } from './types.js';
 export type AiToolsClientBundle = AiToolsInvokeClient;
-export { resolveInvokeModel, applyOpenRouterInvokePolicy, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
-export { resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv } from './openrouter-routing.js';
+export { resolveInvokeModel, applyOpenRouterInvokeRouting, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
+/** @deprecated Use `applyOpenRouterInvokeRouting` (ai-tools v3). */
+export { applyOpenRouterInvokeRouting as applyOpenRouterInvokePolicy } from '@x12i/ai-tools';
+export { resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
 export type { InvokeModelResolutionDiagnostics, InvokeModelResolutionInput, InvokeModelResolutionOptions, InvokeModelResolutionResult, InvokeRouterConfigSlice, AiToolsInvokeClient, } from '@x12i/ai-tools';
 /** @deprecated Use buildInvokeModelResolverOptions */
 export declare function buildModelResolverOptions(config: GatewayConfig, routingEnv?: OpenRouterRoutingConfig): import("@x12i/ai-tools").ModelResolverOptions;

package/dist-cjs/gateway-config.cjs

@@ -5,7 +5,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { resolveOpenRouterApiKey, resolvePreferOpenRouter, } from './openrouter-routing.js';
+import { resolveOpenRouterApiKey, resolveUseOpenRouter, } from './openrouter-routing.js';
 import { LLMProviderRouter } from '@x12i/ai-providers-router';
 import { createGatewayLogger } from './logger-factory.js';
 import { ActivityManager } from './activity-manager.js';
@@ -154,14 +154,14 @@ export function initializeGatewayComponents(config) {
     if (config.logging !== undefined)
         routerConfig.logging = config.logging;
     const openRouterKey = resolveOpenRouterApiKey(config);
-    const preferOpenRouter = resolvePreferOpenRouter(config);
+    const useOpenRouter = resolveUseOpenRouter(config);
     if (openRouterKey) {
         routerConfig.openrouter = { apiKey: openRouterKey };
         routerConfig.openRouter = {
             enabled: true,
-            prefer: preferOpenRouter,
+            prefer: useOpenRouter,
         };
-        if (preferOpenRouter) {
+        if (useOpenRouter) {
             routerConfig.defaultMode = 'openrouter';
         }
     }
@@ -190,7 +190,7 @@ export function initializeGatewayComponents(config) {
         activityManager,
         usageTracker,
         messageBuilderConfig,
-        preferOpenRouter,
+        useOpenRouter,
         openRouterApiKey: openRouterKey,
     };
 }

package/dist-cjs/gateway-config.d.ts

@@ -37,6 +37,6 @@ export declare function initializeGatewayComponents(config: GatewayConfig): {
     activityManager: ActivityManager;
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
-    preferOpenRouter: boolean;
+    useOpenRouter: boolean;
     openRouterApiKey?: string;
 };

package/dist-cjs/gateway-utils.cjs

@@ -104,7 +104,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
                 catalog: mergeOptions.catalog,
                 routingEnv: mergeOptions.routingEnv,
                 openRouterApiKey: mergeOptions.openRouterApiKey,
-                preferOpenRouter: mergeOptions.preferOpenRouter,
+                useOpenRouter: mergeOptions.useOpenRouter,
                 defaultProvider: config.defaultEngine,
                 resolveModels: true,
                 modelsOnly: config.aiTools?.modelsOnly !== false,
@@ -146,7 +146,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
             resolveModels: false,
             routingEnv: mergeOptions.routingEnv,
             openRouterApiKey: mergeOptions.openRouterApiKey,
-            preferOpenRouter: mergeOptions.preferOpenRouter,
+            useOpenRouter: mergeOptions.useOpenRouter,
             defaultProvider: config.defaultEngine,
         });
         merged.provider = resolved.router.provider;
@@ -512,7 +512,14 @@ export async function resolveCostCompletionWithAiTools(routerResponse, tokens, o
         options?.calculator &&
         hasNonZeroTokenUsage(tokens)) {
         try {
-            const record = buildGatewayPricingRecord(routerResponse, tokens, options.mergedConfig);
+            const record = routerResponse != null && typeof routerResponse === 'object'
+                ? {
+                    ...routerResponse,
+                    ...(options.mergedConfig != null ? { config: options.mergedConfig } : {})
+                }
+                : options.mergedConfig != null
+                    ? { config: options.mergedConfig, metadata: { tokens } }
+                    : { metadata: { tokens } };
             const result = await options.calculator.calculateFromRecord(record);
             billing = mapAiCostResultToResolvedActivityCost(billing, result);
         }

package/dist-cjs/gateway-utils.d.ts

@@ -17,7 +17,7 @@ export type MergeConfigOptions = {
     catalog?: AiModelsCatalogClient | null;
     routingEnv?: OpenRouterRoutingConfig;
     openRouterApiKey?: string;
-    preferOpenRouter?: boolean;
+    useOpenRouter?: boolean;
 };
 export { MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, } from '@x12i/ai-tools';
 /**

package/dist-cjs/gateway.cjs

@@ -59,7 +59,7 @@ export class AIGateway {
     messageBuilderConfig;
     _autoRegisterDone = false;
     _aiToolsClient = null;
-    preferOpenRouter;
+    useOpenRouter;
     openRouterApiKey;
     constructor(config = {}, activityManager) {
         this.config = config;
@@ -69,7 +69,7 @@ export class AIGateway {
         this.router = components.router;
         this.activityManager = components.activityManager;
         this.messageBuilderConfig = components.messageBuilderConfig;
-        this.preferOpenRouter = components.preferOpenRouter;
+        this.useOpenRouter = components.useOpenRouter;
         this.openRouterApiKey = components.openRouterApiKey;
         setGatewayRuntimeClients({
             activix: this.activityManager?.getTracker(),
@@ -100,7 +100,7 @@ export class AIGateway {
                 catalog: aiTools?.catalog ?? null,
                 routingEnv: aiTools?.routingEnv,
                 openRouterApiKey: this.openRouterApiKey,
-                preferOpenRouter: this.preferOpenRouter,
+                useOpenRouter: this.useOpenRouter,
             });
             // Activix start snapshot must match what the router receives (modelConfig-only callers omit request.config.model).
             request._mergedRouterConfig = mergedConfig;
@@ -288,7 +288,7 @@ export class AIGateway {
                 catalog: aiTools?.catalog ?? null,
                 routingEnv: aiTools?.routingEnv,
                 openRouterApiKey: this.openRouterApiKey,
-                preferOpenRouter: this.preferOpenRouter,
+                useOpenRouter: this.useOpenRouter,
             });
             request._mergedRouterConfig = mergedConfig;
             logResolvedModelRouting(this.logger, request, mergedConfig);

package/dist-cjs/gateway.d.ts

@@ -18,7 +18,7 @@ export declare class AIGateway {
     private messageBuilderConfig?;
     private _autoRegisterDone;
     private _aiToolsClient;
-    private readonly preferOpenRouter;
+    private readonly useOpenRouter;
     private readonly openRouterApiKey?;
     constructor(config?: GatewayConfig, activityManager?: ActivityManager);
     /**

package/dist-cjs/index.cjs

@@ -33,8 +33,8 @@ export { activityIdentityToLogContext, activityIdentityToLogMeta, withActivityId
 export { createGatewayLogger, resolveGatewayVerboseEnabled } from './logger-factory.js';
 export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
-/** Re-export @x12i/ai-tools invoke orchestrator (≥ 2.5.0) for engine callers. */
-export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
+/** Re-export @x12i/ai-tools invoke orchestrator (≥ 3.0.0) for engine callers. */
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
 // Re-export logging (@x12i/logxer)
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';
 export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';

package/dist-cjs/index.d.ts

@@ -40,8 +40,8 @@ export type { GatewayLoggerConfig } from './logger-factory.js';
 export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
 export type { GatewayLogCode as GatewayDiagnosticCode } from './gateway-log-diagnostics.js';
-/** Re-export @x12i/ai-tools invoke orchestrator (≥ 2.5.0) for engine callers. */
-export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
+/** Re-export @x12i/ai-tools invoke orchestrator (≥ 3.0.0) for engine callers. */
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
 export type { AiToolsClientBundle, AiToolsInvokeClient, InvokeModelResolutionDiagnostics, InvokeModelResolutionInput, InvokeModelResolutionOptions, InvokeModelResolutionResult, InvokeRouterConfigSlice, } from './ai-tools-client.js';
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';
 export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';

package/dist-cjs/openrouter-routing.cjs

@@ -1,12 +1,17 @@
 /**
- * Gateway-level OpenRouter key + prefer flags mapped to @x12i/ai-tools invoke helpers.
+ * Gateway-level OpenRouter key + USE_OPENROUTER flags mapped to @x12i/ai-tools v3 invoke helpers.
  */
-import { readPreferOpenRouterFromEnv, resolveOpenRouterApiKey as resolveOpenRouterApiKeyFromTools, resolvePreferOpenRouter as resolvePreferFromTools, } from '@x12i/ai-tools';
-export { readPreferOpenRouterFromEnv };
+import { resolveOpenRouterApiKey as resolveOpenRouterApiKeyFromTools, resolveUseOpenRouterPreference, } from '@x12i/ai-tools';
+import { readUseOpenRouterFromEnv } from '@x12i/ai-profiles';
+export { readUseOpenRouterFromEnv };
 export function resolveOpenRouterApiKey(config = {}) {
     return resolveOpenRouterApiKeyFromTools(config.openrouter?.apiKey);
 }
-export function resolvePreferOpenRouter(config = {}) {
+/**
+ * Effective OpenRouter preference for invoke-time routing (ai-tools `useOpenRouter`).
+ * Constructor `openRouter.prefer` / `openRouter.enabled` override env `USE_OPENROUTER`.
+ */
+export function resolveUseOpenRouter(config = {}) {
     if (config.openRouter?.prefer === true)
         return true;
     if (config.openRouter?.prefer === false)
@@ -15,5 +20,13 @@ export function resolvePreferOpenRouter(config = {}) {
         return true;
     if (config.openRouter?.enabled === false)
         return false;
-    return resolvePreferFromTools();
+    return resolveUseOpenRouterPreference();
+}
+/** @deprecated Use {@link resolveUseOpenRouter} (ai-tools v3 renamed prefer → useOpenRouter). */
+export function resolvePreferOpenRouter(config = {}) {
+    return resolveUseOpenRouter(config);
+}
+/** @deprecated Use {@link readUseOpenRouterFromEnv} from `@x12i/ai-profiles`. */
+export function readPreferOpenRouterFromEnv() {
+    return readUseOpenRouterFromEnv() ?? true;
 }

package/dist-cjs/openrouter-routing.d.ts

@@ -1,8 +1,16 @@
 /**
- * Gateway-level OpenRouter key + prefer flags mapped to @x12i/ai-tools invoke helpers.
+ * Gateway-level OpenRouter key + USE_OPENROUTER flags mapped to @x12i/ai-tools v3 invoke helpers.
  */
-import { readPreferOpenRouterFromEnv } from '@x12i/ai-tools';
+import { readUseOpenRouterFromEnv } from '@x12i/ai-profiles';
 import type { GatewayConfig } from './types.js';
-export { readPreferOpenRouterFromEnv };
+export { readUseOpenRouterFromEnv };
 export declare function resolveOpenRouterApiKey(config?: GatewayConfig): string | undefined;
+/**
+ * Effective OpenRouter preference for invoke-time routing (ai-tools `useOpenRouter`).
+ * Constructor `openRouter.prefer` / `openRouter.enabled` override env `USE_OPENROUTER`.
+ */
+export declare function resolveUseOpenRouter(config?: GatewayConfig): boolean;
+/** @deprecated Use {@link resolveUseOpenRouter} (ai-tools v3 renamed prefer → useOpenRouter). */
 export declare function resolvePreferOpenRouter(config?: GatewayConfig): boolean;
+/** @deprecated Use {@link readUseOpenRouterFromEnv} from `@x12i/ai-profiles`. */
+export declare function readPreferOpenRouterFromEnv(): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "10.0.6",
+  "version": "10.1.0",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -41,9 +41,9 @@
   "author": "x12i",
   "license": "mit",
   "dependencies": {
-    "@x12i/activix": "^8.5.0",
+    "@x12i/activix": "^8.6.0",
     "@x12i/ai-providers-router": "^4.9.2",
-    "@x12i/ai-tools": "^2.5.0",
+    "@x12i/ai-tools": "^3.0.0",
     "@x12i/flex-md": "^4.8.0",
     "@x12i/logxer": "^4.6.0",
     "@x12i/rendrix": "^4.3.0"