@x12i/ai-gateway 9.1.6 → 9.3.0

package/dist/gateway-utils.js

@@ -3,8 +3,11 @@
  * Handles utility functions
  */
 import * as crypto from 'crypto';
+import { ModelResolutionError } from '@x12i/ai-tools';
 import { getPreParsedInstructions } from './gateway-instructions.js';
 import { getModelMaxTokensFromFlexMd } from './flex-md-loader.js';
+import { applyModelResolution } from './ai-tools-client.js';
+import { getGatewayOperationalMode, isProdGatewayMode, resolveGatewayDefaultModel, warnDefaultModelSubstitution } from './gateway-mode.js';
 /**
  * Generates MD5 hash of a string
  */
@@ -29,11 +32,34 @@ export async function ensureTaskTypeId(request, logger) {
     });
     return taskTypeId;
 }
+function applyGatewayDefaultToMerged(merged, defaults, config) {
+    merged.model = defaults.model;
+    if (defaults.provider) {
+        merged.provider = defaults.provider;
+    }
+    else if (!merged.provider) {
+        merged.provider = config.defaultEngine;
+    }
+}
+async function substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, reason, original) {
+    const operationalMode = getGatewayOperationalMode(config);
+    const defaults = resolveGatewayDefaultModel(mergeOptions?.defaultModelConfig, config.defaultEngine);
+    warnDefaultModelSubstitution(logger, request.identity, {
+        reason,
+        mode: operationalMode,
+        defaultSource: defaults.source,
+        defaultProvider: defaults.provider ?? merged.provider,
+        defaultModel: defaults.model,
+        originalProvider: original?.provider ?? merged.provider,
+        originalModel: original?.model
+    });
+    applyGatewayDefaultToMerged(merged, defaults, config);
+}
 /**
  * Merges config with defaults
  * Supports using internal system action defaults (internalSkill or skillAudit) when useInternalDefaults is set
  */
-export async function mergeConfig(request, config, logger) {
+export async function mergeConfig(request, config, logger, mergeOptions) {
     const useInternalDefaults = request.useInternalDefaults;
     const internalDefaults = useInternalDefaults
         ? (useInternalDefaults === 'skill'
@@ -52,8 +78,8 @@ export async function mergeConfig(request, config, logger) {
         useInternalDefaults,
         hasInternalDefaults: !!internalDefaults
     });
-    // Default model to "gpt-5-nano" if nothing is provided (most permissive - always works)
-    const defaultModel = 'gpt-5-nano';
+    const operationalMode = getGatewayOperationalMode(config);
+    const resolveModels = config.aiTools?.resolveModels !== false;
     // Priority: modelConfig > request.config > internalSystemActions[useInternalDefaults] > gateway defaults
     // First, merge modelConfig into a config-like object if present
     const modelConfigAsConfig = request.modelConfig ? {
@@ -87,18 +113,67 @@ export async function mergeConfig(request, config, logger) {
         ...request.config,
         // ModelConfig overrides (highest priority) - merge only defined values
         ...(modelConfigAsConfig ? Object.fromEntries(Object.entries(modelConfigAsConfig).filter(([_, value]) => value !== undefined)) : {}),
-        // Ensure model is set: modelConfig > request.config > internalDefaults > default
-        model: modelConfigAsConfig?.model || request.config?.model || internalDefaults?.model || defaultModel,
+        // Model resolved below (catalog, default chain, or explicit pass-through)
+        model: modelConfigAsConfig?.model || request.config?.model || internalDefaults?.model,
         // Ensure provider is set: modelConfig > request.config > internalDefaults > gateway default
-        // Provider is required for router to know which provider to use
         provider: modelConfigAsConfig?.provider || request.config?.provider || internalDefaults?.engine || config.defaultEngine
     };
-    // Log if using default model
-    if (!request.config?.model && !internalDefaults?.model) {
-        logger.info('Using default model: gpt-5-nano (no model provided in request)', {
-            jobId: request.identity.jobId,
-            note: 'Default model ensures requests always work regardless of configuration'
-        });
+    const explicitModel = merged.model;
+    const originalProvider = merged.provider;
+    const originalModel = explicitModel;
+    if (!explicitModel) {
+        await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'no_model_provided');
+    }
+    else if (resolveModels && mergeOptions?.catalog) {
+        try {
+            const resolution = await mergeOptions.catalog.resolveModel({
+                provider: merged.provider,
+                model: explicitModel
+            });
+            if (resolution.found) {
+                applyModelResolution(merged, resolution, config.defaultEngine);
+                request._modelResolution = {
+                    modelId: resolution.modelId,
+                    routedViaOpenRouter: resolution.routedViaOpenRouter,
+                    confidence: resolution.confidence,
+                    resolvedVia: resolution.resolvedVia,
+                    originalProvider,
+                    originalModel
+                };
+                logger.verbose('Catalog resolved model name', {
+                    jobId: request.identity.jobId,
+                    originalModel,
+                    resolvedModelId: resolution.modelId,
+                    provider: merged.provider,
+                    model: merged.model,
+                    confidence: resolution.confidence,
+                    resolvedVia: resolution.resolvedVia
+                });
+            }
+            else if (isProdGatewayMode(operationalMode)) {
+                await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'model_resolution_failed', { provider: originalProvider, model: originalModel });
+            }
+            else {
+                throw new ModelResolutionError({ provider: merged.provider, model: explicitModel }, resolution);
+            }
+        }
+        catch (error) {
+            if (error instanceof ModelResolutionError) {
+                throw error;
+            }
+            if (isProdGatewayMode(operationalMode)) {
+                await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'ai_tools_unavailable', { provider: originalProvider, model: originalModel });
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    else if (resolveModels && !mergeOptions?.catalog && isProdGatewayMode(operationalMode)) {
+        await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'ai_tools_unavailable', { provider: originalProvider, model: originalModel });
+    }
+    if (!merged.model) {
+        await substituteGatewayDefaultModel(merged, request, config, logger, mergeOptions, 'no_model_provided');
     }
     // Auto-get maxTokens from flex-md if not explicitly set in ANY config source
     // Check all possible sources: request.config, internalDefaults, gateway config
@@ -315,6 +390,100 @@ export function extractCostUsdFromRouterResponse(routerResponse) {
     }
     return undefined;
 }
+export function hasNonZeroTokenUsage(tokens) {
+    return !!(tokens.prompt || tokens.completion || tokens.total);
+}
+function pickRouterCostStatus(routerResponse) {
+    if (routerResponse == null || typeof routerResponse !== 'object')
+        return undefined;
+    const r = routerResponse;
+    const meta = r.metadata != null && typeof r.metadata === 'object'
+        ? r.metadata
+        : undefined;
+    const status = meta?.costStatus ?? r.costStatus;
+    return status === 'priced' || status === 'unpriced' ? status : undefined;
+}
+/**
+ * Gateway fallback when the router does not set `metadata.costStatus`.
+ * Prefer {@link resolveCostCompletionForActivity} at invoke boundaries.
+ */
+export function resolveActivityCostCompletion(tokens, costUsd) {
+    if (typeof costUsd === 'number' && Number.isFinite(costUsd)) {
+        return { cost: costUsd, costStatus: 'priced' };
+    }
+    if (hasNonZeroTokenUsage(tokens)) {
+        return { costStatus: 'unpriced' };
+    }
+    return {};
+}
+/**
+ * Activity cost slice for Activix: router `metadata.costStatus` / cost wins when present;
+ * otherwise gateway applies the G8 fallback (usage + no price → `unpriced`).
+ */
+export function resolveCostCompletionForActivity(routerResponse, tokens) {
+    const routerStatus = pickRouterCostStatus(routerResponse);
+    const costUsd = extractCostUsdFromRouterResponse(routerResponse);
+    if (routerStatus === 'priced') {
+        return {
+            ...(typeof costUsd === 'number' && Number.isFinite(costUsd) ? { cost: costUsd } : {}),
+            costStatus: 'priced'
+        };
+    }
+    if (routerStatus === 'unpriced') {
+        return { costStatus: 'unpriced' };
+    }
+    return resolveActivityCostCompletion(tokens, costUsd);
+}
+/**
+ * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
+ */
+export async function resolveCostCompletionWithAiTools(routerResponse, tokens, options) {
+    const routerStatus = pickRouterCostStatus(routerResponse);
+    const base = resolveCostCompletionForActivity(routerResponse, tokens);
+    if (base.costStatus === 'priced') {
+        return base;
+    }
+    if (routerStatus === 'unpriced') {
+        return base;
+    }
+    if (options?.calculateCost === false || !options?.calculator) {
+        return base;
+    }
+    if (!hasNonZeroTokenUsage(tokens)) {
+        return base;
+    }
+    const routing = pickInvokeRoutingMetadataSlice(routerResponse, options.mergedConfig);
+    const cfg = options.mergedConfig != null && typeof options.mergedConfig === 'object'
+        ? options.mergedConfig
+        : {};
+    const provider = routing.provider ?? cfg.provider;
+    const modelUsed = routing.modelUsed ?? cfg.model;
+    if (!provider || !modelUsed) {
+        return base;
+    }
+    try {
+        const result = await options.calculator.calculate({
+            tokens: {
+                prompt: tokens.prompt,
+                completion: tokens.completion,
+                total: tokens.total
+            },
+            provider,
+            modelUsed
+        });
+        if (typeof result.cost === 'number' && Number.isFinite(result.cost)) {
+            return {
+                cost: result.cost,
+                costStatus: 'priced',
+                ...(result.breakdown ? { costBreakdown: result.breakdown } : {})
+            };
+        }
+    }
+    catch {
+        // Keep router/gateway unpriced fallback
+    }
+    return base;
+}
 /**
  * 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.

package/dist/gateway.d.ts

@@ -16,7 +16,9 @@ export declare class AIGateway {
     private logger;
     private activityManager?;
     private messageBuilderConfig?;
+    private defaultModelConfig;
     private _autoRegisterDone;
+    private _aiToolsClient;
     constructor(config?: GatewayConfig, activityManager?: ActivityManager);
     /**
      * Invoke chat request (without structured output requirements)
@@ -36,4 +38,5 @@ export declare class AIGateway {
     getLogger(): Logxer;
     getActivityManager(): ActivityManager | undefined;
     setActivityManager(activityManager: ActivityManager): void;
+    private getAiTools;
 }

package/dist/gateway.js

@@ -8,7 +8,9 @@ import { ensureGatewayRequestIdentity } from './activity-manager.js';
 import { initializeGatewayComponents } from './gateway-config.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd } from './flex-md-loader.js';
-import { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, capActivityFullResponsePayload, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
+import { enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
+import { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, capActivityFullResponsePayload, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
+import { getAiToolsClient } from './ai-tools-client.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
@@ -44,7 +46,9 @@ export class AIGateway {
     logger;
     activityManager;
     messageBuilderConfig;
+    defaultModelConfig = {};
     _autoRegisterDone = false;
+    _aiToolsClient = null;
     constructor(config = {}, activityManager) {
         this.config = config;
         this.activityManager = activityManager;
@@ -53,6 +57,7 @@ export class AIGateway {
         this.router = components.router;
         this.activityManager = components.activityManager;
         this.messageBuilderConfig = components.messageBuilderConfig;
+        this.defaultModelConfig = components.defaultModelConfig ?? {};
         setGatewayRuntimeClients({
             activix: this.activityManager?.getTracker(),
             logger: this.logger
@@ -76,7 +81,11 @@ export class AIGateway {
         // Simple message construction
         const messages = this.buildSimpleMessages(request);
         // Merge config (modelConfig > request.config > gateway defaults)
-        const mergedConfig = await mergeConfig(request, this.config, this.logger);
+        const aiTools = await this.getAiTools();
+        const mergedConfig = await mergeConfig(request, this.config, this.logger, {
+            defaultModelConfig: this.defaultModelConfig,
+            catalog: aiTools?.catalog ?? null
+        });
         // Activix start snapshot must match what the router receives (modelConfig-only callers omit request.config.model).
         request._mergedRouterConfig = mergedConfig;
         // Lazy auto-register providers from env (OPENAI_API_KEY, etc.) so consumers don't have to call init
@@ -108,8 +117,13 @@ export class AIGateway {
                 },
                 mode: 'sync'
             });
-            const costUsdChat = extractCostUsdFromRouterResponse(response);
             const metaChat = response?.metadata || {};
+            const tokensChat = extractTokenUsageFromRouterResponse(response);
+            const costCompletionChat = await resolveCostCompletionWithAiTools(response, tokensChat, {
+                mergedConfig,
+                calculator: aiTools?.calculator ?? null,
+                calculateCost: this.config.aiTools?.calculateCost
+            });
             // Create enhanced response
             const enhancedResponse = {
                 content: response.content || '',
@@ -117,22 +131,25 @@ export class AIGateway {
                     aiRequestId: request.aiRequestId,
                     identity: request.identity,
                     latencyMs: Date.now() - startTime,
-                    tokens: extractTokenUsageFromRouterResponse(response),
+                    tokens: tokensChat,
                     taskTypeId,
                     agentType: 'chat',
-                    ...(typeof costUsdChat === 'number'
+                    ...(costCompletionChat.costStatus === 'priced'
                         ? {
-                            costUsd: costUsdChat,
-                            ...(typeof metaChat.cost === 'number' ? { cost: metaChat.cost } : { cost: costUsdChat })
+                            costUsd: costCompletionChat.cost,
+                            ...(typeof metaChat.cost === 'number'
+                                ? { cost: metaChat.cost }
+                                : { cost: costCompletionChat.cost })
                         }
-                        : {})
+                        : {}),
+                    ...(costCompletionChat.costStatus ? { costStatus: costCompletionChat.costStatus } : {})
                 }
             };
             // Track activity success if activity was started
             if (activity) {
                 try {
                     await this.activityManager.logSuccess(activity, {
-                        ...(typeof costUsdChat === 'number' ? { cost: costUsdChat } : {}),
+                        ...costCompletionChat,
                         response: enhancedResponse,
                         endTime: Date.now(),
                         duration: Date.now() - startTime
@@ -245,7 +262,11 @@ export class AIGateway {
         // Attach parsedSnapshot to request for activity tracking
         request._parsedRequest = parsedSnapshot;
         // Merge config (modelConfig > request.config > gateway defaults)
-        const mergedConfig = await mergeConfig(request, this.config, this.logger);
+        const aiTools = await this.getAiTools();
+        const mergedConfig = await mergeConfig(request, this.config, this.logger, {
+            defaultModelConfig: this.defaultModelConfig,
+            catalog: aiTools?.catalog ?? null
+        });
         request._mergedRouterConfig = mergedConfig;
         const diagnosticsMode = request.diagnostics?.mode;
         const traceEnabled = diagnosticsMode === 'trace';
@@ -523,6 +544,8 @@ export class AIGateway {
             }
             contentType = 'structured';
             parsingMethod = 'flex-md';
+            const outputContractKeys = resolveOutputContractFieldKeys(request);
+            parsedContent = await enrichParsedContentForOutputContract(parsedContent, content, outputContractKeys, this.logger);
             let tokens = extractTokenUsageFromRouterResponse(routerResponse);
             if (!(tokens.prompt || tokens.completion || tokens.total)) {
                 const alt = routerResponse?.rawResponse ?? routerResponse?.raw;
@@ -532,7 +555,11 @@ export class AIGateway {
                         tokens = second;
                 }
             }
-            const resolvedCostUsd = extractCostUsdFromRouterResponse(routerResponse);
+            const costCompletion = await resolveCostCompletionWithAiTools(routerResponse, tokens, {
+                mergedConfig,
+                calculator: aiTools?.calculator ?? null,
+                calculateCost: this.config.aiTools?.calculateCost
+            });
             const routerMetaForCost = routerResponse?.metadata || {};
             const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
             const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);
@@ -551,14 +578,15 @@ export class AIGateway {
                     parsingMethod,
                     ...routingMetadataSlice,
                     ...(effectiveModelConfig !== undefined ? { effectiveModelConfig } : {}),
-                    ...(typeof resolvedCostUsd === 'number'
+                    ...(costCompletion.costStatus === 'priced'
                         ? {
-                            costUsd: resolvedCostUsd,
+                            costUsd: costCompletion.cost,
                             ...(typeof routerMetaForCost.cost === 'number'
                                 ? { cost: routerMetaForCost.cost }
-                                : { cost: resolvedCostUsd })
+                                : { cost: costCompletion.cost })
                         }
                         : {}),
+                    ...(costCompletion.costStatus ? { costStatus: costCompletion.costStatus } : {}),
                     ...(traceEnabled
                         ? {
                             requestIds: traceRequestIds,
@@ -597,7 +625,7 @@ export class AIGateway {
                         usage: tokens
                     };
                     await this.activityManager.logSuccess(activity, {
-                        ...(typeof resolvedCostUsd === 'number' ? { cost: resolvedCostUsd } : {}),
+                        ...costCompletion,
                         response: activityResponse,
                         endTime: Date.now(),
                         duration: Date.now() - startTime
@@ -699,6 +727,10 @@ export class AIGateway {
             logger: this.logger
         });
     }
+    getAiTools() {
+        this._aiToolsClient ??= getAiToolsClient(this.config, this.logger);
+        return this._aiToolsClient;
+    }
 }
 function resolveRuntimeJobId(request) {
     return request.identity.jobId || request.identity.sessionId || request.aiRequestId;

package/dist/index.d.ts

@@ -17,7 +17,12 @@ export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
 export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayTraceRequestIds, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, hasNonZeroTokenUsage } from './gateway-utils.js';
+export { getGatewayOperationalMode, isProdGatewayMode, resolveGatewayDefaultModel, parseModelProviderSpec, CODE_DEFAULT_MODEL } from './gateway-mode.js';
+export type { GatewayOperationalMode, GatewayDefaultModelSource, DefaultModelSubstitutionReason, ResolvedGatewayDefault } from './gateway-mode.js';
+export type { ActivityCostStatus, ResolvedActivityCost } from './gateway-utils.js';
+export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
+export type { OutputContractSpec } from './output-contract-normalizer.js';
 export { mergeGatewayAndRequestTemplateRenderOptions, mergeTemplateRenderOptions } from './template-render-merge.js';
 export type { GatewayTemplateRenderRequestSlice } from './template-render-merge.js';
 export { GATEWAY_DUAL_MEMORY_ROOTS, buildMemoryResolutionRootFromWorkingMemory, coalesceMergedInputBucket, extractCallerInputsBag, mapSmartInputPathsInputsToInput, parseLooseJsonObject, prepareWorkingMemoryForTemplateRender, resolveGatewayMemoryPathValue } from './memory-path-resolution.js';

package/dist/index.js

@@ -17,7 +17,9 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, hasNonZeroTokenUsage } from './gateway-utils.js';
+export { getGatewayOperationalMode, isProdGatewayMode, resolveGatewayDefaultModel, parseModelProviderSpec, CODE_DEFAULT_MODEL } from './gateway-mode.js';
+export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
 export { mergeGatewayAndRequestTemplateRenderOptions, mergeTemplateRenderOptions } from './template-render-merge.js';
 export { GATEWAY_DUAL_MEMORY_ROOTS, buildMemoryResolutionRootFromWorkingMemory, coalesceMergedInputBucket, extractCallerInputsBag, mapSmartInputPathsInputsToInput, parseLooseJsonObject, prepareWorkingMemoryForTemplateRender, resolveGatewayMemoryPathValue } from './memory-path-resolution.js';
 // Usage tracking: UsageTracker class methods are available but consumption calculation is disabled

package/dist/output-contract-normalizer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Normalizes invoke responses into `output.parsed` when an explicit output contract is forwarded.
+ * Does not infer contracts from other request fields — that is upstream (graph-engine / ai-tasks).
+ */
+import type { Logxer } from '@x12i/logxer';
+/** Explicit contract: field names or JSON-schema-style `properties` only. */
+export type OutputContractSpec = string[] | {
+    properties: Record<string, unknown>;
+};
+/**
+ * Maps an explicit contract spec to field keys. No inference from descriptions or other request fields.
+ */
+export declare function contractSpecToFieldKeys(contract: unknown): string[];
+/**
+ * Resolves field keys only from explicit `outputContract` on the request or graph-forwarded inputs.
+ */
+export declare function resolveOutputContractFieldKeys(request: unknown): string[] | undefined;
+/**
+ * Fills missing contract keys from markdown sections after flex-md. Only runs when explicit contract keys were supplied.
+ */
+export declare function enrichParsedContentForOutputContract(parsed: unknown, rawContent: string, contractKeys: string[] | undefined, logger?: Logxer): Promise<Record<string, unknown>>;

package/dist/output-contract-normalizer.js

@@ -0,0 +1,121 @@
+/**
+ * Normalizes invoke responses into `output.parsed` when an explicit output contract is forwarded.
+ * Does not infer contracts from other request fields — that is upstream (graph-engine / ai-tasks).
+ */
+import { parseMarkdownSectionsFromContent } from './flex-md-loader.js';
+import { coalesceMergedInputBucket, extractCallerInputsBag, parseLooseJsonObject } from './memory-path-resolution.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasMeaningfulContractValue(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'string')
+        return value.trim().length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length > 0;
+    return true;
+}
+/**
+ * Maps an explicit contract spec to field keys. No inference from descriptions or other request fields.
+ */
+export function contractSpecToFieldKeys(contract) {
+    if (contract == null)
+        return [];
+    if (Array.isArray(contract)) {
+        return contract.filter((k) => typeof k === 'string' && k.trim().length > 0);
+    }
+    if (!isPlainObject(contract))
+        return [];
+    const properties = contract.properties;
+    if (isPlainObject(properties)) {
+        return Object.keys(properties);
+    }
+    return [];
+}
+/** Graph-engine path: `workingMemory.inputs.outputContract` or merged `input.outputContract`. */
+function readExplicitOutputContractFromWorkingMemory(workingMemory) {
+    if (!isPlainObject(workingMemory))
+        return undefined;
+    const inputs = extractCallerInputsBag(workingMemory);
+    if (inputs?.outputContract !== undefined)
+        return inputs.outputContract;
+    const input = coalesceMergedInputBucket(workingMemory);
+    if (isPlainObject(input) && input.outputContract !== undefined) {
+        return input.outputContract;
+    }
+    const loose = parseLooseJsonObject(workingMemory.input);
+    if (loose?.outputContract !== undefined)
+        return loose.outputContract;
+    return undefined;
+}
+/**
+ * Resolves field keys only from explicit `outputContract` on the request or graph-forwarded inputs.
+ */
+export function resolveOutputContractFieldKeys(request) {
+    if (request == null || typeof request !== 'object')
+        return undefined;
+    const r = request;
+    const candidates = [
+        r.outputContract,
+        readExplicitOutputContractFromWorkingMemory(r.workingMemory)
+    ];
+    for (const candidate of candidates) {
+        const keys = contractSpecToFieldKeys(candidate);
+        if (keys.length > 0)
+            return keys;
+    }
+    return undefined;
+}
+function asParsedRecord(parsed) {
+    if (!isPlainObject(parsed))
+        return {};
+    return { ...parsed };
+}
+function pickAliasValue(source, key) {
+    if (hasMeaningfulContractValue(source[key]))
+        return source[key];
+    const spaced = key.replace(/([A-Z])/g, ' $1').replace(/^./, (c) => c.toUpperCase());
+    const title = spaced.charAt(0).toUpperCase() + spaced.slice(1);
+    const aliases = [
+        key,
+        key.toLowerCase(),
+        title,
+        title.replace(/\s+/g, ' '),
+        key.replace(/([A-Z])/g, '_$1').toLowerCase()
+    ];
+    for (const alias of aliases) {
+        if (hasMeaningfulContractValue(source[alias]))
+            return source[alias];
+    }
+    return undefined;
+}
+/**
+ * Fills missing contract keys from markdown sections after flex-md. Only runs when explicit contract keys were supplied.
+ */
+export async function enrichParsedContentForOutputContract(parsed, rawContent, contractKeys, logger) {
+    const base = asParsedRecord(parsed);
+    if (!contractKeys?.length)
+        return base;
+    const missing = contractKeys.filter((k) => !hasMeaningfulContractValue(base[k]));
+    if (missing.length === 0)
+        return base;
+    const content = typeof rawContent === 'string' && rawContent.trim().length > 0
+        ? rawContent
+        : typeof base.rawText === 'string'
+            ? base.rawText
+            : '';
+    if (!content.trim())
+        return base;
+    const fromMarkdown = parseMarkdownSectionsFromContent(content, logger);
+    const merged = { ...base };
+    for (const key of missing) {
+        const value = pickAliasValue(fromMarkdown, key);
+        if (hasMeaningfulContractValue(value)) {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}

package/dist/types.d.ts

@@ -340,6 +340,27 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
     openRouter?: {
         enabled?: boolean;
     };
+    /**
+     * Operational mode override (`process.env.mode` / `MODE` when omitted).
+     * - `prod`: unresolved models fall back to {@link AI_GATEWAY_DEFAULT_MODEL} / packaged default (with Logxer warn).
+     * - `dev` / `debug`: unresolved models throw {@link ModelResolutionError} from `@x12i/ai-tools`.
+     */
+    mode?: 'dev' | 'debug' | 'prod';
+    /**
+     * @x12i/ai-tools integration: catalog model resolution (request) and cost calculation (response).
+     */
+    aiTools?: {
+        /** @default true */
+        enabled?: boolean;
+        /** Inject Catalox; otherwise `createCataloxFromEnv()` from `@x12i/catalox/firebase`. */
+        catalox?: import('@x12i/catalox').Catalox;
+        cacheTtlMs?: number;
+        /** @default true */
+        resolveModels?: boolean;
+        /** @default true */
+        calculateCost?: boolean;
+        costIncludeBreakdown?: boolean;
+    };
     /**
      * InstructionsBlocks overrides
      * Key: block name, Value: block content
@@ -701,6 +722,14 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
      * attach heavy diagnostic objects or raw provider payloads.
      */
     diagnostics?: DiagnosticsOptions;
+    /**
+     * Explicit output contract from graph-engine / ai-tasks: field names or `{ properties }`.
+     * Also accepted on `workingMemory.inputs.outputContract`. When absent, the gateway does not
+     * infer contract fields from other request shapes (`expectedSchema`, config, etc.).
+     */
+    outputContract?: string[] | {
+        properties: Record<string, unknown>;
+    };
 }
 /**
  * Chat request for conversational use cases
@@ -932,6 +961,12 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          * Cost in USD (if available)
          */
         cost?: number;
+        /**
+         * Billing state for Run Analysis / Activix when usage is recorded.
+         * - `priced`: {@link cost} / {@link costUsd} is a finite number from the router
+         * - `unpriced`: usage exists but no price table / adapter cost was returned
+         */
+        costStatus?: 'priced' | 'unpriced';
         /**
          * Cost in USD (preferred stable key when the router exposes it).
          * When both are present, costUsd should mirror cost.