@x12i/ai-gateway 9.1.6 → 9.3.0

package/dist-cjs/output-contract-normalizer.cjs

@@ -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-cjs/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-cjs/request-report-generator.cjs

@@ -1,11 +1,8 @@
-"use strict";
 /**
  * Request Report Generator
  *
  * Generates comprehensive request reports with validation, examples, and structured text information
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateRequestReport = generateRequestReport;
 /**
  * Extract validation rules from markdown
  */
@@ -148,7 +145,7 @@ function schemasMatch(schema1, schema2) {
 /**
  * Generate comprehensive request report
  */
-async function generateRequestReport(request, library, // ObjectTypesLibrary removed
+export async function generateRequestReport(request, library, // ObjectTypesLibrary removed
 logger) {
     const report = {
         requestId: request.identity.jobId || request.aiRequestId,

package/dist-cjs/response-analyzer/format-type-detector.cjs

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Format Type Detector
  *
@@ -10,12 +9,10 @@
  * - Word/character count
  * - Structure patterns
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.FormatTypeDetector = void 0;
 /**
  * Detects format type of text content
  */
-class FormatTypeDetector {
+export class FormatTypeDetector {
     /**
      * Detects format type from text
      *
@@ -116,4 +113,3 @@ class FormatTypeDetector {
         };
     }
 }
-exports.FormatTypeDetector = FormatTypeDetector;

package/dist-cjs/response-analyzer/index.cjs

@@ -1,14 +1,8 @@
-"use strict";
 /**
  * Response Analyzer Module
  *
  * Exports all public APIs for response analysis
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.FormatTypeDetector = exports.ObjectTypeDetector = exports.ResponseAnalyzer = void 0;
-var response_analyzer_js_1 = require("./response-analyzer.cjs");
-Object.defineProperty(exports, "ResponseAnalyzer", { enumerable: true, get: function () { return response_analyzer_js_1.ResponseAnalyzer; } });
-var object_type_detector_js_1 = require("./object-type-detector.cjs");
-Object.defineProperty(exports, "ObjectTypeDetector", { enumerable: true, get: function () { return object_type_detector_js_1.ObjectTypeDetector; } });
-var format_type_detector_js_1 = require("./format-type-detector.cjs");
-Object.defineProperty(exports, "FormatTypeDetector", { enumerable: true, get: function () { return format_type_detector_js_1.FormatTypeDetector; } });
+export { ResponseAnalyzer } from './response-analyzer.js';
+export { ObjectTypeDetector } from './object-type-detector.js';
+export { FormatTypeDetector } from './format-type-detector.js';

package/dist-cjs/response-analyzer/object-type-detector.cjs

@@ -1,16 +1,13 @@
-"use strict";
 /**
  * Object Type Detector
  *
  * Matches objects against predefined type definitions based on properties.
  * Uses a scoring algorithm to determine the best match.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ObjectTypeDetector = void 0;
 /**
  * Detects object types by matching against definitions
  */
-class ObjectTypeDetector {
+export class ObjectTypeDetector {
     definitions;
     minThreshold;
     constructor(config) {
@@ -96,4 +93,3 @@ class ObjectTypeDetector {
         return confidence;
     }
 }
-exports.ObjectTypeDetector = ObjectTypeDetector;

package/dist-cjs/response-analyzer/response-analyzer.cjs

@@ -1,18 +1,15 @@
-"use strict";
 /**
  * Response Analyzer
  *
  * Main class that orchestrates object type and format type detection.
  * Analyzes normalized responses and provides enhanced metadata.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ResponseAnalyzer = void 0;
-const object_type_detector_js_1 = require("./object-type-detector.cjs");
-const format_type_detector_js_1 = require("./format-type-detector.cjs");
+import { ObjectTypeDetector } from './object-type-detector.js';
+import { FormatTypeDetector } from './format-type-detector.js';
 /**
  * Analyzes AI responses to detect object types and format types
  */
-class ResponseAnalyzer {
+export class ResponseAnalyzer {
     objectDetector;
     formatDetector;
     enableFormatDetection;
@@ -20,13 +17,13 @@ class ResponseAnalyzer {
         this.enableFormatDetection = config.enableFormatDetection !== false;
         // Initialize object type detector if definitions provided
         if (config.objectTypeDefinitions && config.objectTypeDefinitions.length > 0) {
-            this.objectDetector = new object_type_detector_js_1.ObjectTypeDetector({
+            this.objectDetector = new ObjectTypeDetector({
                 objectTypeDefinitions: config.objectTypeDefinitions,
                 minConfidenceThreshold: config.minConfidenceThreshold || 0.5
             });
         }
         // Initialize format type detector
-        this.formatDetector = new format_type_detector_js_1.FormatTypeDetector();
+        this.formatDetector = new FormatTypeDetector();
     }
     /**
      * Analyzes a response and returns enhanced metadata
@@ -88,7 +85,7 @@ class ResponseAnalyzer {
      */
     updateObjectTypeDefinitions(definitions) {
         if (definitions.length > 0) {
-            this.objectDetector = new object_type_detector_js_1.ObjectTypeDetector({
+            this.objectDetector = new ObjectTypeDetector({
                 objectTypeDefinitions: definitions,
                 minConfidenceThreshold: 0.5
             });
@@ -98,4 +95,3 @@ class ResponseAnalyzer {
         }
     }
 }
-exports.ResponseAnalyzer = ResponseAnalyzer;

package/dist-cjs/response-analyzer/types.cjs

@@ -1,5 +1,4 @@
-"use strict";
 /**
  * Type definitions for Response Analyzer
  */
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist-cjs/response-fallback-fixer.cjs

@@ -1,6 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.tryFixGatewayResponseToJsonText = tryFixGatewayResponseToJsonText;
 function tryParseJson(text) {
     try {
         return JSON.parse(text);
@@ -79,7 +76,7 @@ function stripToFirstJsonLike(text) {
     const stripped = s.slice(start).trim();
     return stripped.length > 0 ? stripped : undefined;
 }
-function tryFixGatewayResponseToJsonText(raw) {
+export function tryFixGatewayResponseToJsonText(raw) {
     const warnings = [];
     const input = raw ?? '';
     if (!input || !input.trim()) {

package/dist-cjs/runtime-objects.cjs

@@ -1,17 +1,11 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.runtimeObjects = void 0;
-exports.setGatewayLastJobId = setGatewayLastJobId;
-exports.setGatewayRuntimeClients = setGatewayRuntimeClients;
-exports.getRuntimeObservabilityMode = getRuntimeObservabilityMode;
-exports.runtimeObjects = createRuntimeObjectsForMode();
-function setGatewayLastJobId(jobId) {
+export let runtimeObjects = createRuntimeObjectsForMode();
+export function setGatewayLastJobId(jobId) {
     const objects = ensureRuntimeObjectsForCurrentMode();
     if (!objects)
         return;
     objects.lastJobId = jobId;
 }
-function setGatewayRuntimeClients(input) {
+export function setGatewayRuntimeClients(input) {
     const objects = ensureRuntimeObjectsForCurrentMode();
     if (!objects)
         return;
@@ -19,17 +13,17 @@ function setGatewayRuntimeClients(input) {
     objects.logxerClient = input.logger ? asLogxerQueryableClient(input.logger) : undefined;
     objects.packagesRuntimeObjects = [];
 }
-function getRuntimeObservabilityMode() {
+export function getRuntimeObservabilityMode() {
     const rawMode = process.env.mode ?? process.env.MODE;
     return rawMode === 'prod' ? 'prod' : 'debug';
 }
 function ensureRuntimeObjectsForCurrentMode() {
     if (getRuntimeObservabilityMode() === 'prod') {
-        exports.runtimeObjects = undefined;
+        runtimeObjects = undefined;
         return undefined;
     }
-    exports.runtimeObjects ??= createRuntimeObjects();
-    return exports.runtimeObjects;
+    runtimeObjects ??= createRuntimeObjects();
+    return runtimeObjects;
 }
 function createRuntimeObjectsForMode() {
     return getRuntimeObservabilityMode() === 'debug' ? createRuntimeObjects() : undefined;

package/dist-cjs/template-parser.cjs

@@ -1,47 +1,10 @@
-"use strict";
 /**
  * Template Parser
  *
  * Uses @x12i/rendrix (v4+) to parse templates with workingMemory.
  * TemplateResolutionError from the parser is rethrown; other errors fall back to the raw template.
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseTemplate = parseTemplate;
-exports.isParserAvailable = isParserAvailable;
-const memory_path_resolution_js_1 = require("./memory-path-resolution.cjs");
+import { prepareWorkingMemoryForTemplateRender } from './memory-path-resolution.js';
 let rendrixModule = null;
 let parserLoadPromise = null;
 async function loadRendrix() {
@@ -52,7 +15,7 @@ async function loadRendrix() {
     }
     parserLoadPromise = (async () => {
         try {
-            rendrixModule = await Promise.resolve().then(() => __importStar(require('@x12i/rendrix')));
+            rendrixModule = await import('@x12i/rendrix');
         }
         catch {
             rendrixModule = null;
@@ -77,7 +40,7 @@ async function loadRendrix() {
  * @returns Parsed template string
  * @throws {Error} When the parser throws TemplateResolutionError (v4 MUST path missing after merge)
  */
-async function parseTemplate(template, workingMemory, taskConfig, shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions, logger) {
+export async function parseTemplate(template, workingMemory, taskConfig, shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions, logger) {
     // If no template or empty, return as-is
     if (!template || typeof template !== 'string') {
         return template || '';
@@ -86,7 +49,7 @@ async function parseTemplate(template, workingMemory, taskConfig, shortTermMemor
     if (!workingMemory) {
         return template;
     }
-    const wmForRender = (0, memory_path_resolution_js_1.prepareWorkingMemoryForTemplateRender)(workingMemory);
+    const wmForRender = prepareWorkingMemoryForTemplateRender(workingMemory);
     await loadRendrix();
     if (!rendrixModule) {
         return template;
@@ -134,6 +97,6 @@ async function parseTemplate(template, workingMemory, taskConfig, shortTermMemor
 /**
  * Checks if Rendrix (@x12i/rendrix) is available
  */
-function isParserAvailable() {
+export function isParserAvailable() {
     return rendrixModule !== null;
 }

package/dist-cjs/template-render-merge.cjs

@@ -1,10 +1,6 @@
-"use strict";
 /**
  * Merge @x12i/rendrix TemplateRenderOptions from gateway defaults and per-request overrides.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.mergeTemplateRenderOptions = mergeTemplateRenderOptions;
-exports.mergeGatewayAndRequestTemplateRenderOptions = mergeGatewayAndRequestTemplateRenderOptions;
 function hasMeaningfulOptions(o) {
     if (o.templateId !== undefined)
         return true;
@@ -25,7 +21,7 @@ function hasMeaningfulOptions(o) {
  * Deep-merge template render options. Request/gateway overrides win per field.
  * For `subPathSearch`, `roots` on the override replace the base list when present.
  */
-function mergeTemplateRenderOptions(base, override) {
+export function mergeTemplateRenderOptions(base, override) {
     if (!base && !override)
         return undefined;
     if (!base) {
@@ -50,7 +46,7 @@ function mergeTemplateRenderOptions(base, override) {
  * Gateway default `templateRendering` + optional request shorthand (`smartInput`, `smartInputRenderOptions`) + `templateRenderOptions`.
  * Same merge order as {@link buildMessages}.
  */
-function mergeGatewayAndRequestTemplateRenderOptions(gatewayTemplateRendering, request) {
+export function mergeGatewayAndRequestTemplateRenderOptions(gatewayTemplateRendering, request) {
     const requestSmartTemplateOpts = request.smartInput !== undefined || request.smartInputRenderOptions !== undefined
         ? {
             ...(request.smartInput !== undefined ? { smartInput: request.smartInput } : {}),

package/dist-cjs/troubleshooting-helper.cjs

@@ -1,24 +1,9 @@
-"use strict";
 /**
  * Troubleshooting Helper Toolbox
  *
  * Utility functions to diagnose and test AI Gateway issues
  * Based on TROUBLESHOOTING.md guide
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.convertSchemaToSimpleFormat = convertSchemaToSimpleFormat;
-exports.validateAIRequest = validateAIRequest;
-exports.validateJSON = validateJSON;
-exports.extractJSON = extractJSON;
-exports.validateResponse = validateResponse;
-exports.diagnoseRequest = diagnoseRequest;
-exports.diagnoseResponse = diagnoseResponse;
-exports.supportsJSONMode = supportsJSONMode;
-exports.createTestAIRequest = createTestAIRequest;
-exports.createValidationTestCases = createValidationTestCases;
-exports.runValidationTests = runValidationTests;
-exports.formatDiagnostic = formatDiagnostic;
-exports.assertValidAIRequest = assertValidAIRequest;
 /**
  * Converts JSON Schema to simple, human-readable format for LLM instructions
  *
@@ -45,7 +30,7 @@ exports.assertValidAIRequest = assertValidAIRequest;
  * @param schema - Schema object (JSON Schema or simple format)
  * @returns Schema in simple format
  */
-function convertSchemaToSimpleFormat(schema) {
+export function convertSchemaToSimpleFormat(schema) {
     if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
         return {};
     }
@@ -188,7 +173,7 @@ function validateSingleObjectType(objType, context, index) {
  * Validates AIRequest structure
  */
 const GATEWAY_ACTION_TYPES_DIAG = ['skill', 'preSkill', 'postSkill'];
-function validateAIRequest(request) {
+export function validateAIRequest(request) {
     const errors = [];
     const warnings = [];
     const identityJobId = request.identity && typeof request.identity === 'object' ? request.identity.jobId : undefined;
@@ -230,7 +215,7 @@ function validateAIRequest(request) {
 /**
  * Validates JSON string
  */
-function validateJSON(jsonString) {
+export function validateJSON(jsonString) {
     const errors = [];
     const warnings = [];
     if (!jsonString || typeof jsonString !== 'string') {
@@ -265,7 +250,7 @@ function validateJSON(jsonString) {
 /**
  * Extracts JSON from text (handles markdown code blocks, etc.)
  */
-function extractJSON(text) {
+export function extractJSON(text) {
     if (!text || typeof text !== 'string') {
         return { json: null, method: 'none' };
     }
@@ -306,7 +291,7 @@ function extractJSON(text) {
 /**
  * Validates response structure
  */
-function validateResponse(response) {
+export function validateResponse(response) {
     const errors = [];
     const warnings = [];
     if (!response.content) {
@@ -350,7 +335,7 @@ function validateResponse(response) {
 /**
  * Collects comprehensive diagnostic information
  */
-function diagnoseRequest(request) {
+export function diagnoseRequest(request) {
     // AIRequest is distinguished by having primaryObjectType, objectTypes, or other AIRequest-specific fields
     const isAIRequest = 'primaryObjectType' in request ||
         ('objectTypes' in request && Array.isArray(request.objectTypes)) ||
@@ -374,7 +359,7 @@ function diagnoseRequest(request) {
 /**
  * Diagnoses response issues
  */
-function diagnoseResponse(response) {
+export function diagnoseResponse(response) {
     if (!response) {
         return {
             hasContent: false,
@@ -409,7 +394,7 @@ function diagnoseResponse(response) {
 /**
  * Tests if a provider/model combination supports JSON mode
  */
-function supportsJSONMode(provider, model) {
+export function supportsJSONMode(provider, model) {
     if (!provider || !model) {
         return { supported: false, notes: 'Provider and model must be specified' };
     }
@@ -457,7 +442,7 @@ function supportsJSONMode(provider, model) {
 /**
  * Creates a test AIRequest with minimal valid structure
  */
-function createTestAIRequest(overrides) {
+export function createTestAIRequest(overrides) {
     const aiRequestId = 'test-ai-req-' + Date.now();
     const base = {
         aiRequestId,
@@ -496,7 +481,7 @@ function createTestAIRequest(overrides) {
 /**
  * Creates test cases for validation
  */
-function createValidationTestCases() {
+export function createValidationTestCases() {
     const sampleIdentity = (jobId, agentId) => ({
         sessionId: `session-${jobId}`,
         instance: { instanceId: agentId, type: 'test' },
@@ -631,7 +616,7 @@ function createValidationTestCases() {
 /**
  * Runs all validation tests and returns results
  */
-function runValidationTests() {
+export function runValidationTests() {
     const testCases = createValidationTestCases();
     const results = testCases.map(testCase => {
         const validation = validateAIRequest(testCase.request);
@@ -650,7 +635,7 @@ function runValidationTests() {
 /**
  * Formats diagnostic information for display
  */
-function formatDiagnostic(diagnostic) {
+export function formatDiagnostic(diagnostic) {
     const lines = [];
     lines.push('=== Request Diagnostics ===');
     lines.push(`Job ID: ${diagnostic.request.hasJobId ? '✓' : '✗'}`);
@@ -679,7 +664,7 @@ function formatDiagnostic(diagnostic) {
 /**
  * Quick validation helper - throws if invalid
  */
-function assertValidAIRequest(request, logger) {
+export function assertValidAIRequest(request, logger) {
     const validation = validateAIRequest(request);
     if (!validation.valid) {
         throw new Error(`AIRequest validation failed:\n${validation.errors.join('\n')}`);

package/dist-cjs/types.cjs

@@ -1,7 +1,6 @@
-"use strict";
 /**
  * Type definitions for AI Gateway
  *
  * Extends router types with gateway-specific enhancements
  */
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist-cjs/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.