@x12i/ai-gateway 9.1.6 → 9.3.0

package/README.md

@@ -368,6 +368,51 @@ 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,
+  },
+});
+```
+
+**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

package/dist/activity-manager.d.ts

@@ -120,6 +120,7 @@ export declare class ActivityManager {
      */
     logSuccess(activity: ActivityMetadata | undefined, details: {
         cost?: number;
+        costStatus?: 'priced' | 'unpriced';
         response: any;
         endTime: number;
         duration: number;

package/dist/activity-manager.js

@@ -155,6 +155,12 @@ function pickActivixCompletionRoutingMetadata(response) {
     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;
     return out;
 }
 function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
@@ -844,6 +850,7 @@ export class ActivityManager {
             }
             await this.activix.completeRecord(activity.activityId, {
                 cost: details.cost,
+                ...(details.costStatus ? { costStatus: details.costStatus } : {}),
                 response: details.response,
                 outer: {
                     output: details.response,

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/flex-md-loader.d.ts

@@ -43,6 +43,11 @@ export declare function extractJsonFromFlexMd(content: string, logger?: Logxer):
     json: any;
     method: string;
 } | null>;
+/**
+ * Section-based markdown → camelCase field map (e.g. `### Short Answer` → `shortAnswer`).
+ * Used when output contracts need structured `parsed` fields but flex-md returned only `rawText`.
+ */
+export declare function parseMarkdownSectionsFromContent(content: string, logger?: Logxer): Record<string, unknown>;
 /**
  * Check if flex-md module is available
  */

package/dist/flex-md-loader.js

@@ -503,6 +503,22 @@ function fallbackMarkdownParser(content, logger) {
         method: 'fallback-raw-text'
     };
 }
+/**
+ * Section-based markdown → camelCase field map (e.g. `### Short Answer` → `shortAnswer`).
+ * Used when output contracts need structured `parsed` fields but flex-md returned only `rawText`.
+ */
+export function parseMarkdownSectionsFromContent(content, logger) {
+    const parsed = fallbackMarkdownParser(content, logger);
+    const json = parsed.json;
+    if (json != null && typeof json === 'object' && !Array.isArray(json)) {
+        const keys = Object.keys(json);
+        if (keys.length === 1 && keys[0] === 'rawText') {
+            return {};
+        }
+        return json;
+    }
+    return {};
+}
 /**
  * Fallback JSON extraction when flex-md is not available
  */

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
+    }));
+}

package/dist/gateway-utils.d.ts

@@ -4,6 +4,7 @@
  */
 import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayInvokeRejectionMetadata, GatewayTraceMergedConfig, GatewayTraceRequestIds, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
+import { type AiModelsCatalogClient, type CostCalculator } from '@x12i/ai-tools';
 /**
  * Generates MD5 hash of a string
  */
@@ -12,13 +13,17 @@ export declare function generateMD5Hash(text: string): string;
  * Auto-generates taskTypeId from MD5 hash of pre-parsed instructions if not provided
  */
 export declare function ensureTaskTypeId(request: ChatRequest, logger: Logxer): Promise<string>;
+export type MergeConfigOptions = {
+    defaultModelConfig?: Record<string, unknown>;
+    catalog?: AiModelsCatalogClient | null;
+};
 /**
  * Merges config with defaults
  * Supports using internal system action defaults (internalSkill or skillAudit) when useInternalDefaults is set
  */
 export declare function mergeConfig(request: ChatRequest & {
     useInternalDefaults?: 'skill' | 'audit';
-}, config: GatewayConfig, logger: Logxer): Promise<ChatRequest['config']>;
+}, config: GatewayConfig, logger: Logxer, mergeOptions?: MergeConfigOptions): Promise<ChatRequest['config']>;
 /**
  * Maps provider/router usage objects to gateway token counts (`metadata.tokens`, Activix, trace attempts).
  * Handles promptTokens/inputTokens, OpenAI-style snake_case, Responses-style input/output tokens, and missing total (sum prompt+completion).
@@ -43,6 +48,57 @@ export declare function extractTokenUsageFromRouterResponse(routerResponse: unkn
  * Does not compute cost from tokens — adapters must populate normalized fields or raw usage.cost-style keys.
  */
 export declare function extractCostUsdFromRouterResponse(routerResponse: unknown): number | undefined;
+/** Activity billing state when token usage is recorded (Run Analysis G8). */
+export type ActivityCostStatus = 'priced' | 'unpriced';
+export type ResolvedActivityCost = {
+    cost?: number;
+    costStatus?: ActivityCostStatus;
+    costBreakdown?: {
+        promptCostUsd: number;
+        completionCostUsd: number;
+        cachingCostUsd?: number;
+        reasoningCostUsd?: number;
+        audioCostUsd?: number;
+        imageCostUsd?: number;
+        requestFlatCostUsd?: number;
+    };
+};
+export declare function hasNonZeroTokenUsage(tokens: {
+    prompt: number;
+    completion: number;
+    total: number;
+}): boolean;
+/**
+ * Gateway fallback when the router does not set `metadata.costStatus`.
+ * Prefer {@link resolveCostCompletionForActivity} at invoke boundaries.
+ */
+export declare function resolveActivityCostCompletion(tokens: {
+    prompt: number;
+    completion: number;
+    total: number;
+}, costUsd: number | undefined): ResolvedActivityCost;
+/**
+ * Activity cost slice for Activix: router `metadata.costStatus` / cost wins when present;
+ * otherwise gateway applies the G8 fallback (usage + no price → `unpriced`).
+ */
+export declare function resolveCostCompletionForActivity(routerResponse: unknown, tokens: {
+    prompt: number;
+    completion: number;
+    total: number;
+}): ResolvedActivityCost;
+export type ResolveCostCompletionOptions = {
+    mergedConfig?: unknown;
+    calculator?: CostCalculator | null;
+    calculateCost?: boolean;
+};
+/**
+ * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
+ */
+export declare function resolveCostCompletionWithAiTools(routerResponse: unknown, tokens: {
+    prompt: number;
+    completion: number;
+    total: number;
+}, options?: ResolveCostCompletionOptions): Promise<ResolvedActivityCost>;
 /**
  * Stable routing facts for gateway response metadata (router metadata + merged config fallbacks).
  * Matches trace-mode resolution; intended for every successful invoke(), not only diagnostics.trace.