@x12i/ai-gateway 10.0.2 → 10.0.5

package/README.md

@@ -13,7 +13,7 @@ Unified gateway for LLM provider routing, structured logging, optional Activix a
 | **Activix** | Optional Mongo-backed activity rows (`ai-actions`, `bad-requests`, `skill-executions`) with root billing fields and `outer` I/O. |
 | **Trace mode** | `diagnostics.mode === 'trace'` adds `metadata.attempts[]`, `metadata.usage`, and per-attempt billing when priced. |
 
-Pinned dependency versions are in `package.json` (currently **Activix ^7.2**, **ai-tools ^2**).
+Pinned dependency versions are in `package.json` (currently **Activix ^8.5**, **ai-tools ^2.5**, **ai-providers-router ^4.9**).
 
 ---
 
@@ -79,7 +79,7 @@ const response = await gateway.invoke({
     agentId: 'agent-456'
   },
   workingMemory: { input: 'Hello!' },
-  config: { model: 'cheap', provider: 'openrouter' }
+  config: { model: 'openai/gpt-4o-mini', provider: 'openrouter', maxTokens: 256 }
 });
 
 console.log(response.content, response.metadata?.costUsd, response.metadata?.tokens);
@@ -87,7 +87,7 @@ console.log(response.content, response.metadata?.costUsd, response.metadata?.tok
 
 ### Providers without manual `register()`
 
-- **OpenRouter:** Set **`OPENROUTER_API_KEY`** in `.env`. The gateway always passes this key to the router when set. **By default, OpenRouter is preferred** for routing (including when you also have direct keys such as `OPENAI_API_KEY`). **`@x12i/ai-tools` ≥ 2.1** resolves model + provider agnostically (`openrouter` + `cheap` or `openai` + `gpt-4o` — same pipeline). Profile aliases (`cheap`, `balanced`, …) set `routedViaOpenRouter` from env. You do not need `USE_OPENROUTER=true` when the key is present.
+- **OpenRouter:** Set **`OPENROUTER_API_KEY`** in `.env`. The gateway always passes this key to the router when set. **By default, OpenRouter is preferred** for routing (including when you also have direct keys such as `OPENAI_API_KEY`). **`@x12i/ai-tools`** resolves concrete model ids + provider via `resolveInvokeModel()` (catalog normalization, OpenRouter vs direct transport, router proxy flags). Pass catalog model ids such as `openai/gpt-4o-mini` or `gpt-4o` — not profile shortcuts (`cheapest`, `cheap/default`) unless you set `aiTools.modelsOnly: false`.
 - **`USE_OPENROUTER=false`:** Do **not** prefer OpenRouter when a direct provider API key exists — use the direct provider instead. OpenRouter is **still** used as **fallback** when the request targets a provider without a direct key (e.g. `anthropic` without `ANTHROPIC_API_KEY`). It does not disable OpenRouter while `OPENROUTER_API_KEY` is set.
 - **Direct providers:** Set `OPENAI_API_KEY`, `GROK_API_KEY`, etc. Registered lazily on first invoke.
 
@@ -188,7 +188,7 @@ Instructions must be **complete caller text** — the gateway no longer injects
 | `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`) |
 | `LOGXER_PACKAGE_LEVELS` | Bulk stack levels, e.g. `AI_GATEWAY:info,AI_PROVIDER_ROUTER:debug` |
-| `OPENROUTER_API_KEY` | OpenRouter key; always wired when set (required for profile/OpenRouter routes) |
+| `OPENROUTER_API_KEY` | OpenRouter key; always wired when set (required for OpenRouter transport) |
 | `USE_OPENROUTER` | Optional; default **prefer** OpenRouter when key is set. `false` = use direct provider keys when present; OpenRouter still used as fallback when a provider has no key |
 | Other provider keys | `OPENAI_API_KEY`, `GROK_API_KEY`, etc. |
 
@@ -210,12 +210,39 @@ Exports: `GATEWAY_LOGXER_PACKAGE`, `GATEWAY_LOG_ENV_PREFIX`, `createGatewayLogge
 
 ## @x12i/ai-tools v2 (models + cost)
 
-- **No Catalox / Firestore** — catalogs come from ai-tools open-assets JSON (optional `bundledOnly`).
-- **`aiTools.enabled`** — bootstrap catalog client + calculator.
-- **`aiTools.resolveModels`** — `mergeConfig()` resolves model ids (strict in **`mode: 'dev'`**).
-- **`aiTools.calculateCost`** — prices usage before Activix `completeRecord` when the router did not mark the call priced.
+Engine-owned catalog bootstrap and post-call billing. Consumers read **`metadata.costUsd`** / **`costStatus`** only — no direct `@x12i/ai-tools` dependency for cost.
 
-Gateway helpers (also exported): `resolveCostCompletionWithAiTools`, `buildTraceUsageSummary`, `enrichTraceAttemptsWithBilling`.
+### Resolution order (after every successful LLM call)
+
+| Step | Condition | Result |
+|------|-----------|--------|
+| A | Router/provider returned finite **`costUsd`** (or equivalent) | **`costStatus: "priced"`**, set cost |
+| B | Tokens + catalog pricing succeeds (`isAuthoritative`, not `unknownModel`, finite cost ≥ 0) | **`priced`** (+ optional breakdown) |
+| C | Tokens but no price | **`unpriced`** |
+| D | No usage | omit **`costUsd`** and **`costStatus`** |
+
+Step A always wins; explicit router **`costStatus: "unpriced"`** is never overridden by catalog.
+
+Implemented in **`resolveCostCompletionWithAiTools`** (delegates to **`CostCalculator.calculateFromRecord`** via **`buildGatewayPricingRecord`**). Target: move orchestrator to ai-tools as **`resolveInvokeBilling`** — see [AI_TOOLS_INVOKE_BILLING_ORCHESTRATOR_SPEC.md](./docs/upstream-reports/AI_TOOLS_INVOKE_BILLING_ORCHESTRATOR_SPEC.md).
+
+### `aiTools` config (aligned with funcx / generic engine contract)
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| **`enabled`** | `true` | Bootstrap **`AiModelsCatalogClient`** + **`CostCalculator`** |
+| **`calculateCost`** | `true` | Run post-call catalog pricing when router did not price |
+| **`resolveModels`** | `true` | **`mergeConfig()`** → **`resolveInvokeModel()`** |
+| **`modelsOnly`** | `true` | Reject profile shortcuts (`cheapest`, `cheap/default`, …) |
+| **`bundledOnly`** | `false` | Offline bundled catalogs only |
+| **`costIncludeBreakdown`** | `false` | Include prompt/completion breakdown on priced results |
+| **`catalogLane`** | `"text"` (ai-tools default) | Catalog lane for resolution + cost lookup (`text`, `image`, …) |
+| **`cacheTtlMs`** | ai-tools default (24h) | In-memory catalog cache TTL |
+
+- **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 billing helpers (also exported): `resolveCostCompletionWithAiTools`, `buildGatewayPricingRecord`, `catalogPricingSucceeded`, `ensureInvokeBillingCostStatus`, `buildTraceUsageSummary`, `enrichTraceAttemptsWithBilling`.
 
 ---
 
@@ -246,9 +273,9 @@ Mongo env: `MONGO_URI` + `MONGO_LOGS_DB` or `MONGO_DB`.
 
 ## Response metadata and cost
 
-On every successful **`invoke()`**:
+On every successful **`invoke()`** and **`invokeChat()`**:
 
-- **`metadata.provider`**, **`modelUsed`**, **`maxTokensRequested`**, **`effectiveModelConfig`**
+- **`metadata.provider`**, **`modelUsed`**, **`maxTokensRequested`**, **`effectiveModelConfig`** (invoke only)
 - **`metadata.tokens`**, **`costStatus`**, **`costUsd`** when usage exists and pricing applies
 
 Full contract: [AI Gateway invoke execution metadata](./docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md).
@@ -276,7 +303,7 @@ Adds **`metadata.attempts`**, **`metadata.usage`**, **`metadata.requestIds`**, a
 
 Set via constructor `mode` or env `mode` / `MODE`. **Downstream hosts should document and expose `mode`** so graph/skill callers know resolution behavior.
 
-Every mode requires an explicit **`model`** on the request. Unresolved catalog profiles throw (e.g. `ModelProfileUnroutableError` in dev when profile has no routable target).
+Every mode requires an explicit **`model`** on the request (concrete catalog id when `aiTools.modelsOnly` is true). Unknown models throw `ModelResolutionError`. Profile keys only work when `aiTools.modelsOnly: false`.
 
 ---
 
@@ -291,7 +318,7 @@ Every mode requires an explicit **`model`** on the request. Unresolved catalog p
 | `npm run test:flex-md-esm-regression` | ESM build regression for flex-md |
 | `npm run test:prepublish` | `build` + `npm test` |
 
-Live tests use `LIVE_TEST_PROVIDER` / `LIVE_TEST_MODEL` (default `openrouter` + `cheap`, an ai-tools profile alias). Set `LIVE_SKIP_INVOKE=1` to skip the LLM call.
+Live tests use `LIVE_TEST_PROVIDER` / `LIVE_TEST_MODEL` (default `openrouter` + `openai/gpt-4o-mini`). Set `LIVE_TEST_PROFILES=1` to run legacy profile-key invokes. Set `LIVE_SKIP_INVOKE=1` to skip the LLM call.
 
 ---
 

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

@@ -1,44 +1,26 @@
 /**
- * Lazy @x12i/ai-tools catalog + cost calculator bootstrap.
+ * @x12i/ai-tools invoke client bootstrap for the gateway.
+ * Model resolution orchestration lives in ai-tools ≥ 2.5.0 (`resolveInvokeModel`).
  */
-import { AiModelsCatalogClient, CostCalculator, type ModelResolutionSuccess, type ModelResolverOptions, type OpenRouterRoutingConfig } from '@x12i/ai-tools';
+import { type AiToolsInvokeClient, type ModelResolutionSuccess, type OpenRouterRoutingConfig } from '@x12i/ai-tools';
 import type { Logxer } from '@x12i/logxer';
-import type { ChatRequest, GatewayConfig } from './types.js';
-export type AiToolsClientBundle = {
-    catalog: AiModelsCatalogClient;
-    calculator: CostCalculator;
-    routingEnv: OpenRouterRoutingConfig;
-};
+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 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;
 /**
- * Per-invoke resolver options: ai-tools decides OpenRouter vs direct from env + optional gateway prefer override.
+ * @deprecated Use mapResolutionToRouterConfig from @x12i/ai-tools
  */
-export declare function buildModelResolverOptions(config: GatewayConfig, routingEnv?: OpenRouterRoutingConfig): ModelResolverOptions;
+export declare function applyModelResolution(merged: {
+    provider?: string;
+    model?: string;
+}, resolution: ModelResolutionSuccess, gatewayDefaultEngine?: string, inputModel?: string): void;
 /**
  * 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 `{ provider, model }` (agnostic to openrouter vs vendor input).
- */
-export declare function applyModelResolution(merged: NonNullable<ChatRequest['config']>, resolution: ModelResolutionSuccess, gatewayDefaultEngine?: string, inputModel?: string): void;
-type RouterConfigSlice = {
-    provider?: string;
-    model?: string;
-    allowOpenRouterProxy?: boolean;
-    providerProxy?: string;
-};
-type ModelResolutionMeta = {
-    routedViaOpenRouter?: boolean;
-};
-/**
- * Router invoke flags after mergeConfig + ai-tools resolution (OpenRouter vs direct transport).
- */
-export declare function applyOpenRouterInvokePolicy(merged: RouterConfigSlice, options: {
-    openRouterApiKey?: string;
-    preferOpenRouter?: boolean;
-    routingEnv?: OpenRouterRoutingConfig;
-    resolution?: ModelResolutionMeta;
-}): void;
-export {};

package/dist/ai-tools-client.js

@@ -1,26 +1,51 @@
 /**
- * Lazy @x12i/ai-tools catalog + cost calculator bootstrap.
+ * @x12i/ai-tools invoke client bootstrap for the gateway.
+ * Model resolution orchestration lives in ai-tools ≥ 2.5.0 (`resolveInvokeModel`).
  */
-import { AiModelsCatalogClient, CostCalculator, isEffectiveOpenRouterTransport, loadOpenRouterRoutingEnv, resolveModelVendorFromResolution } from '@x12i/ai-tools';
+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';
-let sharedClientPromise = null;
-let sharedConfigKey;
+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';
 let bootstrapFailedLogged = false;
-function configKey(config) {
-    return `${config.aiTools?.cacheTtlMs ?? ''}:${config.aiTools?.costIncludeBreakdown ?? ''}:${config.aiTools?.bundledOnly ?? ''}`;
+function invokeClientOptions(config) {
+    return {
+        cacheTtlMs: config.aiTools?.cacheTtlMs,
+        ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {}),
+        ...(config.aiTools?.costIncludeBreakdown ? { costIncludeBreakdown: true } : {}),
+        cacheKey: `${config.aiTools?.cacheTtlMs ?? ''}:${config.aiTools?.costIncludeBreakdown ?? ''}:${config.aiTools?.bundledOnly ?? ''}:${config.aiTools?.catalogLane ?? ''}`,
+    };
 }
-/**
- * Per-invoke resolver options: ai-tools decides OpenRouter vs direct from env + optional gateway prefer override.
- */
-export function buildModelResolverOptions(config, routingEnv) {
-    const env = routingEnv ?? loadOpenRouterRoutingEnv();
-    const prefer = resolvePreferOpenRouter(config);
+function withCatalogLaneCalculator(client, config) {
+    const lane = config.aiTools?.catalogLane;
+    if (!lane)
+        return client;
     return {
-        routingEnv: env,
-        ...(prefer ? { routeViaOpenRouter: true } : {}),
+        ...client,
+        calculator: new CostCalculator(client.catalog, {
+            ...(config.aiTools?.costIncludeBreakdown ? { includeBreakdown: true } : {}),
+            resolverOptions: buildInvokeModelResolverOptions({
+                routingEnv: client.routingEnv,
+                catalogLane: lane
+            })
+        })
     };
 }
+/** @deprecated Use buildInvokeModelResolverOptions */
+export function buildModelResolverOptions(config, routingEnv) {
+    return buildInvokeModelResolverOptions({
+        routingEnv,
+        preferOpenRouter: resolvePreferOpenRouter(config),
+    });
+}
+/**
+ * @deprecated Use mapResolutionToRouterConfig from @x12i/ai-tools
+ */
+export function applyModelResolution(merged, resolution, gatewayDefaultEngine, inputModel) {
+    const mapped = mapResolutionToRouterConfig(resolution, { provider: merged.provider, model: inputModel ?? merged.model ?? '' }, gatewayDefaultEngine);
+    merged.provider = mapped.provider;
+    merged.model = mapped.model;
+}
 /**
  * Returns catalog + calculator, or null when disabled or bootstrap fails.
  */
@@ -28,102 +53,27 @@ 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 {
-        const routingEnv = loadOpenRouterRoutingEnv();
-        const catalog = new AiModelsCatalogClient({
-            cacheTtlMs: config.aiTools?.cacheTtlMs,
-            ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {}),
-            resolverOptions: { routingEnv },
-        });
-        const calculator = new CostCalculator(catalog, {
-            includeBreakdown: config.aiTools?.costIncludeBreakdown === true,
-        });
+    const client = await getAiToolsInvokeClient(invokeClientOptions(config), {
+        warn: (msg, err) => {
+            if (!bootstrapFailedLogged) {
+                bootstrapFailedLogged = true;
+                logger.warn(msg, withActivityIdentity(undefined, {
+                    error: err instanceof Error ? err.message : String(err),
+                    debugKind: gatewayLogDebug.anomaly,
+                }));
+            }
+        },
+    });
+    if (client) {
         logger.debug('ai-tools catalog client ready', {
             debugKind: gatewayLogDebug.state,
         });
-        return { catalog, calculator, routingEnv };
-    }
-    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 `{ provider, model }` (agnostic to openrouter vs vendor input).
- */
-export function applyModelResolution(merged, resolution, gatewayDefaultEngine, inputModel) {
-    const ref = resolveModelVendorFromResolution(resolution, inputModel ?? merged.model ?? '', {
-        asOpenRouter: resolution.routedViaOpenRouter,
-    });
-    if (ref) {
-        merged.provider = ref.provider;
-        merged.model = ref.model;
-        return;
-    }
-    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;
+        return withCatalogLaneCalculator(client, config);
     }
+    return client;
 }
-/**
- * Router invoke flags after mergeConfig + ai-tools resolution (OpenRouter vs direct transport).
- */
-export function applyOpenRouterInvokePolicy(merged, options) {
-    if (!options.openRouterApiKey?.trim())
-        return;
-    const routingEnv = options.routingEnv ?? loadOpenRouterRoutingEnv();
-    const viaOpenRouter = options.resolution?.routedViaOpenRouter === true ||
-        (options.resolution?.routedViaOpenRouter !== false &&
-            isEffectiveOpenRouterTransport(routingEnv, {
-                provider: merged.provider,
-                modelId: merged.model,
-                routeViaOpenRouter: options.preferOpenRouter ? true : undefined,
-            }));
-    if (viaOpenRouter) {
-        merged.allowOpenRouterProxy = true;
-        if (merged.provider && merged.provider !== 'openrouter') {
-            merged.providerProxy = 'openrouter';
-        }
-    }
-    else {
-        merged.allowOpenRouterProxy = false;
-    }
+/** Reset singleton (tests). */
+export function resetAiToolsClientForTests() {
+    resetAiToolsInvokeClientForTestsUpstream();
+    bootstrapFailedLogged = false;
 }

package/dist/gateway-utils.d.ts

@@ -16,7 +16,10 @@ export declare function ensureTaskTypeId(request: ChatRequest, logger: Logxer):
 export type MergeConfigOptions = {
     catalog?: AiModelsCatalogClient | null;
     routingEnv?: OpenRouterRoutingConfig;
+    openRouterApiKey?: string;
+    preferOpenRouter?: boolean;
 };
+export { MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, } from '@x12i/ai-tools';
 /**
  * Merges config with defaults
  * Supports using internal system action defaults (internalSkill or skillAudit) when useInternalDefaults is set
@@ -91,13 +94,38 @@ export type ResolveCostCompletionOptions = {
     calculator?: CostCalculator | null;
     calculateCost?: boolean;
 };
-/** Record shape for {@link CostCalculator.calculateFromRecord} (router + merged config + usage). */
+/** Optional cache/reasoning token fields for catalog pricing records. */
+export type InvokeUsageExtras = {
+    cached?: number;
+    cacheWrite?: number;
+    reasoning?: number;
+};
+/**
+ * Best-effort cache/reasoning token counts from router usage buckets
+ * (for {@link buildGatewayPricingRecord} / ai-tools {@link CostCalculator.calculateFromRecord}).
+ */
+export declare function extractUsageExtrasFromRouterResponse(routerResponse: unknown): InvokeUsageExtras;
+/**
+ * Whether ai-tools catalog pricing is authoritative enough for Step B (`priced`).
+ * Matches the generic engine contract: authoritative catalog hit with finite cost ≥ 0.
+ */
+export declare function catalogPricingSucceeded(result: AiCostResult): boolean;
+/** Record shape for {@link CostCalculator.calculateFromRecord} (shared engine contract). */
 export declare function buildGatewayPricingRecord(routerResponse: unknown, tokens: {
     prompt: number;
     completion: number;
     total: number;
 }, mergedConfig?: unknown): Record<string, unknown>;
 export declare function mapAiCostResultToResolvedActivityCost(base: ResolvedActivityCost, result: AiCostResult): ResolvedActivityCost;
+/**
+ * G8 safety net: token usage without a billing signal → `unpriced`.
+ * Used at invoke boundaries after {@link resolveCostCompletionWithAiTools}.
+ */
+export declare function ensureInvokeBillingCostStatus(billing: ResolvedActivityCost, tokens: {
+    prompt: number;
+    completion: number;
+    total: number;
+}): ResolvedActivityCost;
 /**
  * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
  */
@@ -149,14 +177,6 @@ export declare function pickEffectiveModelConfigFromInvokeRequest(request: Pick<
  */
 export declare function tryExtractRouterLikePayloadFromErrorChain(error: unknown, maxDepth?: number): unknown;
 export declare function pickRequestIdsFromRouterLike(gatewayAiRequestId: string | undefined, routerLike: unknown): GatewayTraceRequestIds | undefined;
-/** Error code hint when a bundled profile name cannot be routed to a catalog target. */
-export declare const MODEL_PROFILE_UNROUTABLE = "MODEL_PROFILE_UNROUTABLE";
-export declare class ModelProfileUnroutableError extends Error {
-    readonly profileAlias: string;
-    readonly provider: string | undefined;
-    readonly code = "MODEL_PROFILE_UNROUTABLE";
-    constructor(profileAlias: string, provider: string | undefined, cause?: unknown);
-}
 type ModelResolutionCandidate = {
     provider: string;
     model: string;
@@ -175,7 +195,7 @@ export declare function mapGatewayFallbackAttemptsToRouter(attempts: GatewayFall
     responsePreview?: string;
 }>;
 /**
- * Log profile alias vs OpenRouter model id actually sent to the router after catalog resolution.
+ * Log original input vs OpenRouter model id actually sent to the router after catalog resolution.
  */
 export declare function logResolvedModelRouting(logger: Logxer, request: ChatRequest, mergedConfig: ChatRequest['config']): void;
 /**