@x12i/ai-gateway 9.2.0 → 9.3.4

package/README.md

@@ -63,6 +63,7 @@ npm install @x12i/ai-gateway
 **📚 Documentation**: After installation, documentation is available in:
 - `node_modules/@x12i/ai-gateway/CONTENT_RESOLVER_UPSTREAM_GUIDE.md` - **Content resolver (nx-content)**: config, keys, local/git, upstream checklist
 - `node_modules/@x12i/ai-gateway/docs/IDENTITY_OBJECT_CONTRACT.md` - **Identity contract** for Activix (`sessionId` + `instance`)
+- `node_modules/@x12i/ai-gateway/docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md` - **Invoke metadata**, cost/billing (G8), output contract (G6), Activix completion fields
 - `node_modules/@x12i/ai-gateway/docs/LOGGER_INITIALIZATION.md` - **Required reading**: How to properly initialize logger
 - `node_modules/@x12i/ai-gateway/TROUBLESHOOTING.md` - Troubleshooting guide
 - `node_modules/@x12i/ai-gateway/TROUBLESHOOTING_TOOLBOX.md` - Diagnostic tools
@@ -309,7 +310,7 @@ The gateway reads **Mongo connection** settings from the environment, but **coll
 `ActivityManager` drives **`@x12i/activix` v7** with a **two-phase** API:
 
 1. **`startRecord`** — Inserts a new document with **`status: 'started'`**, **`startTime`**, **`runContext`** (same object as **`request.identity`**), root **`request`** / **`config`** snapshots, gateway metadata (e.g. **`activityType`**, **`aiRequestId`**), and the initial **`outer`** fragment (see below). Activix returns **`activityId`** (prefix **`act-`**, configured as the collection **`primaryKey`**); that id is used for all later updates — **not** `jobId`.
-2. **`completeRecord`** or **`failRecord`** — Patches the **same** document by **`activityId`**. Success adds **`response`**, **`endTime`**, **`duration`**, **`cost`**, refreshed **`status`**, and sets **`outer.output`** to the completion payload. Failure adds error details (and may attach **`outer.output`** for certain failure modes such as response parsing).
+2. **`completeRecord`** or **`failRecord`** — Patches the **same** document by **`activityId`**. On success, adds **`response`**, **`endTime`**, **`duration`**, root **`cost`** / **`costUsd`** / **`costStatus`**, sets **`outer.output`** to the completion payload, merges billing into **`outer.metadata`**, and when priced or unpriced with usage, sets Activix **`outer.cost`** (`usd`, `tokens`, `provider`, `model`, optional `details`). Failure adds error details (and may attach **`outer.output`** for certain failure modes such as response parsing).
 
 **How a document is shaped (reading `ai-actions` in Mongo)**
 
@@ -317,7 +318,7 @@ The gateway reads **Mongo connection** settings from the environment, but **coll
 - **Root-level copies** of common identity fields may appear beside **`runContext`** for convenient indexing; treat **`runContext`** as the full envelope when in doubt.
 - **`request`**: Structured snapshot only — **`raw`** / **`parsed`** instructions, context, prompt; **`messages`**; **`workingMemory`** (template/user payload). There is **no** separate legacy **`input`** field on this object; use **`workingMemory`**.
 - **`config`**: `model`, `provider`, `temperature`, `maxTokens`, **`rawConfig`** (exact router config).
-- **`outer`**: Activix v7 **validated I/O** at the document root. At **start**, **`outer.input`** contains **`activityType`** and the same **`request`** snapshot as root **`request`** when a body exists (`{ activityType, request }`). At **success**, **`outer.output`** matches the **`response`** object written on completion. Root **`request`** / **`response`** support querying and older tooling; **`outer`** satisfies Activix’s envelope — so the same logical request snapshot can appear both at **`request`** and under **`outer.input.request`** by design. Large provider blobs (**`response.content.fullResponse`**) and size limits are described in [Activities outer duplication & payload controls](./docs/ACTIVITIES_OUTER_DUPLICATION.md).
+- **`outer`**: Activix v7 **validated I/O** at the document root. At **start**, **`outer.input`** contains **`activityType`** and the same **`request`** snapshot as root **`request`** when a body exists (`{ activityType, request }`). At **success**, **`outer.output`** matches the **`response`** object written on completion; **`outer.metadata`** mirrors routing and billing from **`response.metadata`** (`modelUsed`, `provider`, `cost`, `costUsd`, `costStatus`, optional `costBreakdown`); **`outer.cost`** holds the canonical Activix cost object when usage or price is known (see [Cost reporting](#cost-reporting-invoke-response--activix-run-analysis-g8) below). Root **`request`** / **`response`** support querying and older tooling; **`outer`** satisfies Activix’s envelope — so the same logical request snapshot can appear both at **`request`** and under **`outer.input.request`** by design. Large provider blobs (**`response.content.fullResponse`**) and size limits are described in [Activities outer duplication & payload controls](./docs/ACTIVITIES_OUTER_DUPLICATION.md).
 
 **Environment variable priority (Activix / Mongo — implemented in `@x12i/activix`, not in `activity-tracking-config.ts`):**
 - **Mongo URI**: `MONGO_LOGS_URI` if set, otherwise **`MONGO_URI`**. If neither is set, Activix cannot use the database.
@@ -368,6 +369,69 @@ The gateway only exposes official queryable clients. It exposes `activixClient`
 
 See [Runtime Objects Observability Methodology](./docs/RUNTIME_OBJECTS_OBSERVABILITY.md) for the reusable package-level contract.
 
+### Model catalog resolution and defaults (`@x12i/ai-tools`)
+
+Before each invoke, the gateway can normalize caller `config.model` / `modelConfig` via the **ai-models** Catalox catalog (`@x12i/ai-tools`). After invoke, when the router leaves cost **unpriced**, the gateway may compute USD from the same catalog.
+
+**Environment variables:**
+
+| Variable | Purpose |
+|----------|---------|
+| `AI_GATEWAY_DEFAULT_MODEL` | Default model when none is provided, or when resolution fails in **`mode=prod`**. Supports `provider/model` (e.g. `openrouter/openai/gpt-5-nano`) or a bare model id. |
+| `mode` / `MODE` | `prod` — unresolved models fall back to the default chain (with **Logxer `warn`**). `dev` / `debug` / omitted — unresolved models throw **`ModelResolutionError`**. |
+
+**Default model priority** (prod fallback only): `AI_GATEWAY_DEFAULT_MODEL` → `src/defaults/model-config.json` `defaultModel` → code constant `gpt-5-nano`.
+
+**Logxer warnings** on default substitution include structured fields: `reason` (`no_model_provided`, `model_resolution_failed`, `ai_tools_unavailable`), `defaultSource` (`env`, `model-config.json`, `code`), `originalModel`, `defaultModel`, and `mode`.
+
+Catalox/Firebase credentials are required for catalog bootstrap (same as `@x12i/ai-tools` — see that package’s README). Disable with `aiTools: { enabled: false }` on `GatewayConfig`, or inject `aiTools.catalox` for tests.
+
+**GatewayConfig (optional overrides):**
+
+```typescript
+const gateway = new AIGateway({
+  mode: 'prod', // or 'dev' | 'debug' — overrides process.env.mode
+  aiTools: {
+    enabled: true,
+    resolveModels: true,
+    calculateCost: true,
+    costIncludeBreakdown: false,
+    cacheTtlMs: 60_000,
+    // catalox: injectedCataloxInstance,
+  },
+});
+```
+
+#### Cost reporting (invoke response + Activix, Run Analysis G8)
+
+Billing is resolved once per successful **`invoke()`** / **`invokeChat()`** via **`resolveCostCompletionWithAiTools`** (see [`docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md`](./docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md)):
+
+| Layer | Fields |
+|--------|--------|
+| **Router** (`@x12i/ai-providers-router`) | Preferred source: **`metadata.costStatus`** (`priced` \| `unpriced`), **`metadata.costUsd`** / **`metadata.cost`** when priced |
+| **Gateway response** | Same slice on **`response.metadata`**: **`costStatus`**, **`costUsd`**, **`cost`**, optional **`costBreakdown`** (when **`aiTools.calculateCost`** and catalog pricing apply and the router left cost unpriced) |
+| **Activix activity (on `logSuccess`)** | Root **`cost`**, **`costUsd`**, **`costStatus`**; **`outer.metadata`** mirror; **`outer.cost`** (`usd`, `tokens` with `input`/`output`/`total`, `provider`, `model`, `details.costStatus`, optional `details.costBreakdown`) |
+
+**`costStatus` semantics:**
+
+- **`priced`** — **`costUsd`** / **`cost`** is a finite USD amount for this call (from the router or from **`@x12i/ai-tools`** catalog **`CostCalculator`** when the router did not price).
+- **`unpriced`** — Token usage was recorded but no authoritative USD price was available (explicit router **`unpriced`** is never overridden by catalog).
+- Omitted — No non-zero token usage (no billing signal).
+
+Requires **`enableActivityTracking: true`** (default when Mongo/env is configured) for Activix persistence; invoke metadata is always set on the gateway response regardless.
+
+**Tests before release:**
+
+```bash
+npm run build
+npm test                    # integration (tsx)
+npm run test:ai-tools       # unit: mode, defaults, cost helper
+npm run test:live           # LIVE: catalog + invoke (needs .env + Firebase + LLM key)
+npm run test:real:comprehensive  # optional: compiled real router matrix + npm test
+```
+
+See [`.env.example`](./.env.example) for `AI_GATEWAY_DEFAULT_MODEL`, `mode`, provider keys, and Firebase/Catalox variables.
+
 **Recommended (auto-configured from environment variables):**
 
 ```typescript
@@ -427,7 +491,7 @@ When the gateway constructs Activix internally, each collection uses **`primaryK
 - **Config data**: Stored in **`config`** (model, provider, temperature, maxTokens, **`rawConfig`**)
 - **Response data**: Stored in **`response`** on completion (content, metadata, optional **`fullResponse`** per diagnostics)
 - **Activix I/O**: Root **`outer`** — **`outer.input`** at start, **`outer.output`** on success (and some failure paths)
-- **Cost**: Calculated and stored per activity on success
+- **Cost / billing**: On success, root **`cost`**, **`costUsd`**, **`costStatus`**, plus **`outer.metadata`** and **`outer.cost`** (same values as **`response.metadata`** from the invoke path — router passthrough or catalog pricing via **`@x12i/ai-tools`**)
 
 **Best Practices for Type IDs:**
 - **`jobTypeId`**: Use MD5 hash of your job type string (e.g., `MD5('data-processing-job')`) for consistent job-level aggregation
@@ -1074,7 +1138,7 @@ The gateway uses **`@x12i/activix` v7** (xronox-activitix) for full lifecycle lo
      - Sends **`runContext`**, **`request`**, **`config`**, **`startTime`**, **`status: 'started'`**, plus Activix **`outer.input`** (wraps **`activityType`** and the same **`request`** snapshot when present — see section 2).
      - Returns **`activityId`** (and record payload) for phase 2.
    - **Phase 2 (complete / fail)**: Updates the SAME document by **`activityId`**
-     - Success: **`response`**, **`cost`**, **`endTime`**, **`duration`**, **`status`**, and **`outer.output`** set to the completion **`response`** payload (request/config are **not** re-sent).
+     - Success: **`response`**, root **`cost`** / **`costUsd`** / **`costStatus`**, **`endTime`**, **`duration`**, **`status`**, **`outer.output`** (completion payload), **`outer.metadata`** (routing + billing mirror), and **`outer.cost`** when usage or price is known (see [Cost reporting](#cost-reporting-invoke-response--activix-run-analysis-g8)).
      - Failure: error payload and timing; optional **`response`** / **`outer.output`** only for specific failure kinds.
 
 4. **Structured fields vs Activix `outer` (v2.6.0+):**
@@ -1219,8 +1283,22 @@ Example shape for a completed row in **`ai-actions`** (`activityType: 'gateway-i
   // completeRecord: outer.output ← same object as root `response` on success
   outer: {
     input: { activityType: 'gateway-invocation', request: { /* same snapshot as root request */ } },
-    output: { /* success: normalized gateway response object */ },
-    metadata: { /* tier metadata / aiRequestId routing — see @x12i/activix */ }
+    output: { /* success: gateway activity response (content, parsed, metadata, usage) */ },
+    metadata: {
+      modelUsed: 'openai/gpt-5-nano-2025-08-07',
+      provider: 'openrouter',
+      cost: 0.0000348,
+      costUsd: 0.0000348,
+      costStatus: 'priced'
+    },
+    cost: {
+      usd: 0.0000348,
+      unit: 'USD',
+      tokens: { input: 16, output: 85, total: 101 },
+      provider: 'openrouter',
+      model: 'openai/gpt-5-nano-2025-08-07',
+      details: { costStatus: 'priced' /* optional costBreakdown when aiTools.costIncludeBreakdown */ }
+    }
   },
   // inner: optional step array for multi-step flows (see @x12i/activix docs)
   
@@ -1261,8 +1339,10 @@ Example shape for a completed row in **`ai-actions`** (`activityType: 'gateway-i
     metadata: {...}
   },
   
-  // Cost (from logSuccess)
-  cost: 0.002,
+  // Billing (from logSuccess — mirrors response.metadata from invoke)
+  cost: 0.0000348,
+  costUsd: 0.0000348,
+  costStatus: 'priced',
   
   // Metadata
   createdAt: Date,
@@ -1274,7 +1354,7 @@ Example shape for a completed row in **`ai-actions`** (`activityType: 'gateway-i
 - ✅ Each activity = separate Mongo document (**`_id`**) with stable **`activityId`** (`act-…`) for Activix APIs
 - ✅ **`aiRequestId`** = per-request correlation (required on invoke)
 - ✅ **`runContext.jobId`** / **`runContext.taskId`** = upstream identity (required on invoke since v9+)
-- ✅ Request/config sent at **start**; response/timing/cost at **complete**
+- ✅ Request/config sent at **start**; response/timing/billing (`cost`, `costUsd`, `costStatus`, `outer.cost`) at **complete**
 - ✅ Updates target **`activityId`** from **`startRecord`**, not **`jobId`**
 
 #### Retry Tracking (@x12i/activix v7)
@@ -1410,8 +1490,16 @@ const response = await gateway.invoke({
       cacheTotalTokens?: number
     },
     model?: string,             // Model ID used (e.g., 'gpt-4o', 'claude-sonnet-4')
+    modelUsed?: string,         // Resolved/served model id (when distinct from request model)
     provider?: string,          // Provider used (e.g., 'openai', 'anthropic')
-    cost?: number,              // Cost in USD (if available)
+    costStatus?: 'priced' | 'unpriced',  // Billing state (Run Analysis G8)
+    costUsd?: number,           // USD when costStatus === 'priced' (preferred field)
+    cost?: number,              // USD mirror of costUsd when priced
+    costBreakdown?: {           // Optional when aiTools catalog pricing runs (calculateCost + breakdown)
+      promptCostUsd?: number;
+      completionCostUsd?: number;
+      // ...other breakdown keys from @x12i/ai-tools
+    },
     
     // ============================================
     // Inference Output Parsing (if inferenceType provided)
@@ -1458,8 +1546,10 @@ const response = await gateway.invoke({
 - `metadata.jobId` - Job ID for correlation
 - `metadata.latencyMs` - Request duration in milliseconds
 - `metadata.tokens` - Token breakdown (prompt, completion, total, cache tokens)
-- `metadata.cost` - Cost in USD
-- `metadata.model` - Model ID used
+- `metadata.costStatus` - `priced` | `unpriced` (see [Cost reporting](#cost-reporting-invoke-response--activix-run-analysis-g8))
+- `metadata.costUsd` / `metadata.cost` - USD when priced
+- `metadata.costBreakdown` - Optional catalog breakdown when `aiTools.calculateCost` applies
+- `metadata.model` / `metadata.modelUsed` - Model id used
 - `metadata.provider` - Provider used
 
 #### Example: Full Response
@@ -1509,8 +1599,10 @@ const response = await gateway.invoke({
       completion: 50,
       total: 150
     },
-    model: 'gpt-5-mini',
+    modelUsed: 'gpt-5-mini',
     provider: 'openai',
+    costStatus: 'priced',
+    costUsd: 0.002,
     cost: 0.002,
     
     // Inference output (parsed)

package/dist/activity-manager.d.ts

@@ -121,6 +121,7 @@ export declare class ActivityManager {
     logSuccess(activity: ActivityMetadata | undefined, details: {
         cost?: number;
         costStatus?: 'priced' | 'unpriced';
+        costBreakdown?: Record<string, unknown>;
         response: any;
         endTime: number;
         duration: number;

package/dist/activity-manager.js

@@ -133,34 +133,120 @@ function logUpstreamIdentityWarnings(logger, incomingIdentity, merged) {
         }));
     }
 }
-/** Routing / generation facts from gateway response metadata for Activix `outer.metadata` on completion. */
-function pickActivixCompletionRoutingMetadata(response) {
+/** Token counts for Activix `outer.cost.tokens` (maps gateway prompt/completion → input/output). */
+function pickActivixUsageTokens(response) {
     if (response == null || typeof response !== 'object')
-        return {};
-    const meta = response.metadata;
-    if (meta == null || typeof meta !== 'object')
-        return {};
-    const m = meta;
+        return undefined;
+    const r = response;
+    const raw = (r.usage != null && typeof r.usage === 'object' ? r.usage : undefined) ??
+        (r.metadata != null && typeof r.metadata === 'object'
+            ? r.metadata.tokens
+            : undefined);
+    if (raw == null || typeof raw !== 'object')
+        return undefined;
+    const t = raw;
+    const input = typeof t.prompt === 'number'
+        ? t.prompt
+        : typeof t.input === 'number'
+            ? t.input
+            : undefined;
+    const output = typeof t.completion === 'number'
+        ? t.completion
+        : typeof t.output === 'number'
+            ? t.output
+            : undefined;
+    const total = typeof t.total === 'number' ? t.total : undefined;
+    if (input === undefined && output === undefined && total === undefined)
+        return undefined;
+    return {
+        ...(input !== undefined ? { input } : {}),
+        ...(output !== undefined ? { output } : {}),
+        ...(total !== undefined ? { total } : {})
+    };
+}
+/**
+ * Activix v6+ `outer.cost` from gateway billing + routing metadata (Run Analysis G8).
+ */
+function buildActivixOuterCost(routingMeta, billing, response) {
+    const usd = typeof billing.cost === 'number' && Number.isFinite(billing.cost)
+        ? billing.cost
+        : typeof routingMeta.costUsd === 'number' && Number.isFinite(routingMeta.costUsd)
+            ? routingMeta.costUsd
+            : typeof routingMeta.cost === 'number' && Number.isFinite(routingMeta.cost)
+                ? routingMeta.cost
+                : undefined;
+    const tokens = pickActivixUsageTokens(response);
+    const provider = typeof routingMeta.provider === 'string' ? routingMeta.provider : undefined;
+    const model = typeof routingMeta.modelUsed === 'string'
+        ? routingMeta.modelUsed
+        : typeof routingMeta.model === 'string'
+            ? routingMeta.model
+            : undefined;
+    const details = {};
+    if (billing.costStatus === 'priced' || billing.costStatus === 'unpriced') {
+        details.costStatus = billing.costStatus;
+    }
+    if (billing.costBreakdown != null && typeof billing.costBreakdown === 'object') {
+        details.costBreakdown = billing.costBreakdown;
+    }
+    const hasDetails = Object.keys(details).length > 0;
+    if (usd === undefined && !tokens && !provider && !model && !hasDetails) {
+        return undefined;
+    }
+    return {
+        ...(usd !== undefined ? { usd, unit: 'USD' } : {}),
+        ...(tokens ? { tokens } : {}),
+        ...(provider ? { provider } : {}),
+        ...(model ? { model } : {}),
+        ...(hasDetails ? { details } : {})
+    };
+}
+/** Routing / generation facts for Activix `outer.metadata` on completion (includes billing mirror). */
+function pickActivixCompletionRoutingMetadata(response, billing) {
     const out = {};
-    if (typeof m.modelUsed === 'string')
-        out.modelUsed = m.modelUsed;
-    if (typeof m.model === 'string')
-        out.model = m.model;
-    if (typeof m.provider === 'string')
-        out.provider = m.provider;
-    if (typeof m.maxTokensRequested === 'number')
-        out.maxTokensRequested = m.maxTokensRequested;
-    if (typeof m.region === 'string')
-        out.region = m.region;
-    if (m.effectiveModelConfig != null && typeof m.effectiveModelConfig === 'object') {
-        out.effectiveModelConfig = m.effectiveModelConfig;
+    if (response != null && typeof response === 'object') {
+        const meta = response.metadata;
+        if (meta != null && typeof meta === 'object') {
+            const m = meta;
+            if (typeof m.modelUsed === 'string')
+                out.modelUsed = m.modelUsed;
+            if (typeof m.model === 'string')
+                out.model = m.model;
+            if (typeof m.provider === 'string')
+                out.provider = m.provider;
+            if (typeof m.maxTokensRequested === 'number')
+                out.maxTokensRequested = m.maxTokensRequested;
+            if (typeof m.region === 'string')
+                out.region = m.region;
+            if (m.effectiveModelConfig != null && typeof m.effectiveModelConfig === 'object') {
+                out.effectiveModelConfig = m.effectiveModelConfig;
+            }
+            if (typeof m.cost === 'number' && Number.isFinite(m.cost))
+                out.cost = m.cost;
+            if (typeof m.costUsd === 'number' && Number.isFinite(m.costUsd))
+                out.costUsd = m.costUsd;
+            if (m.costStatus === 'priced' || m.costStatus === 'unpriced')
+                out.costStatus = m.costStatus;
+            if (m.costBreakdown != null && typeof m.costBreakdown === 'object') {
+                out.costBreakdown = m.costBreakdown;
+            }
+        }
+    }
+    if (billing) {
+        if ((out.costStatus !== 'priced' && out.costStatus !== 'unpriced') &&
+            (billing.costStatus === 'priced' || billing.costStatus === 'unpriced')) {
+            out.costStatus = billing.costStatus;
+        }
+        if (typeof billing.cost === 'number' && Number.isFinite(billing.cost)) {
+            if (out.cost === undefined)
+                out.cost = billing.cost;
+            if (out.costUsd === undefined)
+                out.costUsd = billing.cost;
+        }
+        if (out.costBreakdown === undefined && billing.costBreakdown != null) {
+            out.costBreakdown = billing.costBreakdown;
+        }
     }
-    if (typeof m.cost === 'number' && Number.isFinite(m.cost))
-        out.cost = m.cost;
-    if (typeof m.costUsd === 'number' && Number.isFinite(m.costUsd))
-        out.costUsd = m.costUsd;
-    if (m.costStatus === 'priced' || m.costStatus === 'unpriced')
-        out.costStatus = m.costStatus;
     return out;
 }
 function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
@@ -848,13 +934,24 @@ export class ActivityManager {
                 });
                 return;
             }
+            const billingSlice = {
+                cost: details.cost,
+                costStatus: details.costStatus,
+                costBreakdown: details.costBreakdown
+            };
+            const outerMetadata = pickActivixCompletionRoutingMetadata(details.response, billingSlice);
+            const outerCost = buildActivixOuterCost(outerMetadata, billingSlice, details.response);
             await this.activix.completeRecord(activity.activityId, {
                 cost: details.cost,
+                ...(typeof details.cost === 'number' && Number.isFinite(details.cost)
+                    ? { costUsd: details.cost }
+                    : {}),
                 ...(details.costStatus ? { costStatus: details.costStatus } : {}),
                 response: details.response,
                 outer: {
                     output: details.response,
-                    metadata: pickActivixCompletionRoutingMetadata(details.response)
+                    metadata: outerMetadata,
+                    ...(outerCost ? { cost: outerCost } : {})
                 },
                 endTime: details.endTime,
                 duration: details.duration

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

@@ -0,0 +1,20 @@
+/**
+ * Lazy @x12i/ai-tools catalog + cost calculator bootstrap.
+ */
+import { AiModelsCatalogClient, CostCalculator, type ModelResolutionSuccess } from '@x12i/ai-tools';
+import type { Logxer } from '@x12i/logxer';
+import type { ChatRequest, GatewayConfig } from './types.js';
+export type AiToolsClientBundle = {
+    catalog: AiModelsCatalogClient;
+    calculator: CostCalculator;
+};
+/**
+ * Returns catalog + calculator, or null when disabled or bootstrap fails.
+ */
+export declare function getAiToolsClient(config: GatewayConfig, logger: Logxer): Promise<AiToolsClientBundle | null>;
+/** Reset singleton (tests). */
+export declare function resetAiToolsClientForTests(): void;
+/**
+ * Map catalog resolution to router config provider/model fields.
+ */
+export declare function applyModelResolution(merged: NonNullable<ChatRequest['config']>, resolution: ModelResolutionSuccess, gatewayDefaultEngine?: string): void;

package/dist/ai-tools-client.js

@@ -0,0 +1,91 @@
+/**
+ * Lazy @x12i/ai-tools catalog + cost calculator bootstrap.
+ */
+import { AiModelsCatalogClient, CostCalculator, ensureAiModelsCatalog } from '@x12i/ai-tools';
+import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
+let sharedClientPromise = null;
+let sharedConfigKey;
+let bootstrapFailedLogged = false;
+function configKey(config) {
+    const injected = config.aiTools?.catalox ? 'injected' : 'env';
+    return `${injected}:${config.aiTools?.cacheTtlMs ?? ''}:${config.aiTools?.costIncludeBreakdown ?? ''}`;
+}
+/**
+ * Returns catalog + calculator, or null when disabled or bootstrap fails.
+ */
+export async function getAiToolsClient(config, logger) {
+    if (config.aiTools?.enabled === false) {
+        return null;
+    }
+    const key = configKey(config);
+    if (sharedClientPromise && sharedConfigKey !== key) {
+        sharedClientPromise = null;
+    }
+    sharedConfigKey = key;
+    if (!sharedClientPromise) {
+        sharedClientPromise = bootstrapAiTools(config, logger);
+    }
+    return sharedClientPromise;
+}
+/** Reset singleton (tests). */
+export function resetAiToolsClientForTests() {
+    sharedClientPromise = null;
+    sharedConfigKey = undefined;
+    bootstrapFailedLogged = false;
+}
+async function bootstrapAiTools(config, logger) {
+    try {
+        let catalox = config.aiTools?.catalox;
+        if (!catalox) {
+            const { createCataloxFromEnv } = await import('@x12i/catalox/firebase');
+            const bootstrapped = createCataloxFromEnv();
+            catalox = bootstrapped.catalox;
+        }
+        await ensureAiModelsCatalog(catalox);
+        const catalog = new AiModelsCatalogClient({
+            catalox,
+            cacheTtlMs: config.aiTools?.cacheTtlMs
+        });
+        const calculator = new CostCalculator(catalog, {
+            includeBreakdown: config.aiTools?.costIncludeBreakdown === true
+        });
+        logger.debug('ai-tools catalog client ready', {
+            debugKind: gatewayLogDebug.state
+        });
+        return { catalog, calculator };
+    }
+    catch (error) {
+        if (!bootstrapFailedLogged) {
+            bootstrapFailedLogged = true;
+            logger.warn('ai-tools catalog bootstrap failed; model resolution and catalog cost calculation disabled', withActivityIdentity(undefined, {
+                error: error instanceof Error ? error.message : String(error),
+                debugKind: gatewayLogDebug.anomaly
+            }));
+        }
+        return null;
+    }
+}
+/**
+ * Map catalog resolution to router config provider/model fields.
+ */
+export function applyModelResolution(merged, resolution, gatewayDefaultEngine) {
+    if (resolution.routedViaOpenRouter) {
+        merged.provider = 'openrouter';
+        merged.model = resolution.modelId;
+        return;
+    }
+    const slash = resolution.modelId.indexOf('/');
+    if (slash > 0) {
+        merged.provider = resolution.record?.providerId ?? resolution.modelId.slice(0, slash);
+        merged.model = resolution.modelId.slice(slash + 1);
+    }
+    else {
+        merged.model = resolution.modelId;
+        if (resolution.record?.providerId) {
+            merged.provider = resolution.record.providerId;
+        }
+    }
+    if (!merged.provider && gatewayDefaultEngine) {
+        merged.provider = gatewayDefaultEngine;
+    }
+}

package/dist/gateway-config.d.ts

@@ -19,6 +19,7 @@ export interface GatewayConfigContext {
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
 }
+export type InitializedGatewayComponents = ReturnType<typeof initializeGatewayComponents>;
 /**
  * Loads configuration from JSON files (model config and instructionsBlocks).
  * Pass a {@link Logxer} instance so load diagnostics go through logxer (not console).
@@ -46,4 +47,5 @@ export declare function initializeGatewayComponents(config: GatewayConfig): {
     activityManager: ActivityManager;
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
+    defaultModelConfig: Record<string, unknown>;
 };

package/dist/gateway-config.js

@@ -283,6 +283,7 @@ export function initializeGatewayComponents(config) {
         router,
         activityManager,
         usageTracker,
-        messageBuilderConfig
+        messageBuilderConfig,
+        defaultModelConfig
     };
 }

package/dist/gateway-mode.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Gateway operational mode (prod vs dev/debug) and default model resolution.
+ */
+import type { Logxer } from '@x12i/logxer';
+import type { ActivityIdentity, GatewayConfig } from './types.js';
+export type GatewayOperationalMode = 'prod' | 'debug' | 'dev';
+export type GatewayDefaultModelSource = 'env' | 'model-config.json' | 'code';
+export type DefaultModelSubstitutionReason = 'no_model_provided' | 'model_resolution_failed' | 'ai_tools_unavailable';
+export declare const CODE_DEFAULT_MODEL = "gpt-5-nano";
+export type ResolvedGatewayDefault = {
+    model: string;
+    provider?: string;
+    source: GatewayDefaultModelSource;
+};
+/**
+ * Operational mode: `GatewayConfig.mode` overrides `process.env.mode` / `MODE`.
+ * Only `prod` allows silent default-model substitution; all other values are strict.
+ */
+export declare function getGatewayOperationalMode(config?: Pick<GatewayConfig, 'mode'>): GatewayOperationalMode;
+export declare function isProdGatewayMode(mode: GatewayOperationalMode): boolean;
+/**
+ * Parse `provider/model` or bare model id (OpenRouter ids may contain multiple slashes).
+ */
+export declare function parseModelProviderSpec(spec: string): {
+    provider?: string;
+    model: string;
+};
+/**
+ * Default model priority: AI_GATEWAY_DEFAULT_MODEL → model-config.json → code constant.
+ */
+export declare function resolveGatewayDefaultModel(defaultModelConfig?: Record<string, unknown>, gatewayDefaultEngine?: string): ResolvedGatewayDefault;
+export declare function warnDefaultModelSubstitution(logger: Logxer, identity: Partial<ActivityIdentity> | undefined, details: {
+    reason: DefaultModelSubstitutionReason;
+    mode: GatewayOperationalMode;
+    defaultSource: GatewayDefaultModelSource;
+    defaultProvider?: string;
+    defaultModel: string;
+    originalProvider?: string;
+    originalModel?: string;
+}): void;

package/dist/gateway-mode.js

@@ -0,0 +1,75 @@
+/**
+ * Gateway operational mode (prod vs dev/debug) and default model resolution.
+ */
+import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
+export const CODE_DEFAULT_MODEL = 'gpt-5-nano';
+/**
+ * Operational mode: `GatewayConfig.mode` overrides `process.env.mode` / `MODE`.
+ * Only `prod` allows silent default-model substitution; all other values are strict.
+ */
+export function getGatewayOperationalMode(config) {
+    if (config?.mode) {
+        return config.mode;
+    }
+    const raw = (process.env.mode ?? process.env.MODE ?? '').toLowerCase();
+    if (raw === 'prod')
+        return 'prod';
+    if (raw === 'dev')
+        return 'dev';
+    return 'debug';
+}
+export function isProdGatewayMode(mode) {
+    return mode === 'prod';
+}
+/**
+ * Parse `provider/model` or bare model id (OpenRouter ids may contain multiple slashes).
+ */
+export function parseModelProviderSpec(spec) {
+    const trimmed = spec.trim();
+    if (!trimmed) {
+        return { model: CODE_DEFAULT_MODEL };
+    }
+    const slash = trimmed.indexOf('/');
+    if (slash === -1) {
+        return { model: trimmed };
+    }
+    const first = trimmed.slice(0, slash);
+    const rest = trimmed.slice(slash + 1);
+    if (rest.includes('/') && (first === 'openrouter' || first === 'open-router')) {
+        return { provider: 'openrouter', model: trimmed };
+    }
+    return { provider: first, model: rest };
+}
+/**
+ * Default model priority: AI_GATEWAY_DEFAULT_MODEL → model-config.json → code constant.
+ */
+export function resolveGatewayDefaultModel(defaultModelConfig, gatewayDefaultEngine) {
+    const envSpec = process.env.AI_GATEWAY_DEFAULT_MODEL?.trim();
+    if (envSpec) {
+        const parsed = parseModelProviderSpec(envSpec);
+        return { model: parsed.model, provider: parsed.provider, source: 'env' };
+    }
+    const jsonModel = typeof defaultModelConfig?.defaultModel === 'string' ? defaultModelConfig.defaultModel : undefined;
+    if (jsonModel) {
+        const parsed = parseModelProviderSpec(jsonModel);
+        const jsonEngine = typeof defaultModelConfig?.defaultEngine === 'string'
+            ? defaultModelConfig.defaultEngine
+            : gatewayDefaultEngine;
+        return {
+            model: parsed.model,
+            provider: parsed.provider ?? jsonEngine,
+            source: 'model-config.json'
+        };
+    }
+    return {
+        model: CODE_DEFAULT_MODEL,
+        provider: gatewayDefaultEngine,
+        source: 'code'
+    };
+}
+export function warnDefaultModelSubstitution(logger, identity, details) {
+    logger.warn('Gateway substituted default model for request', withActivityIdentity(identity, {
+        ...details,
+        debugKind: gatewayLogDebug.anomaly
+    }));
+}