@x12i/ai-gateway 9.1.5 → 9.2.0

package/dist/template-parser.js

@@ -4,6 +4,7 @@
  * Uses @x12i/rendrix (v4+) to parse templates with workingMemory.
  * TemplateResolutionError from the parser is rethrown; other errors fall back to the raw template.
  */
+import { prepareWorkingMemoryForTemplateRender } from './memory-path-resolution.js';
 let rendrixModule = null;
 let parserLoadPromise = null;
 async function loadRendrix() {
@@ -48,6 +49,7 @@ export async function parseTemplate(template, workingMemory, taskConfig, shortTe
     if (!workingMemory) {
         return template;
     }
+    const wmForRender = prepareWorkingMemoryForTemplateRender(workingMemory);
     await loadRendrix();
     if (!rendrixModule) {
         return template;
@@ -57,18 +59,18 @@ export async function parseTemplate(template, workingMemory, taskConfig, shortTe
             ? rendrixModule
             : rendrixModule.default || rendrixModule;
         if (typeof api.render === 'function') {
-            return await api.render(template, workingMemory, shortTermMemory, experienceMemory, knowledgeMemory, undefined, // functionsMap
+            return await api.render(template, wmForRender, shortTermMemory, experienceMemory, knowledgeMemory, undefined, // functionsMap
             undefined, // choiceOptions
             undefined, // filesContent
             templateRenderOptions);
         }
         if (typeof api.parse === 'function') {
-            return await api.parse(template, workingMemory);
+            return await api.parse(template, wmForRender);
         }
         else if (typeof api === 'function') {
             const parser = new api();
             if (typeof parser.parse === 'function') {
-                return await parser.parse(template, workingMemory);
+                return await parser.parse(template, wmForRender);
             }
         }
         return template;

package/dist/types.d.ts

@@ -626,6 +626,10 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
      * Working memory (optional) - Affects all template parsing
      * Passed to Rendrix (v4+) for template variable substitution.
      * Plain {{path}} tokens are MUST paths: undefined after merge throws TemplateResolutionError (rethrown by the gateway).
+     *
+     * Dual roots (graph-engine / ai-tasks contract): `inputs` is the caller / graph-entry bag;
+     * `input` is the merged MAIN payload (object or JSON string). Smart-input and `input.*` / `inputs.*`
+     * paths resolve with cross-root fallback before render (see `resolveGatewayMemoryPathValue`).
      */
     workingMemory?: unknown;
     /**
@@ -697,6 +701,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
@@ -928,6 +940,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.

package/dist-cjs/activity-manager.cjs

@@ -159,6 +159,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) {
@@ -848,6 +854,7 @@ 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-cjs/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-cjs/flex-md-loader.cjs

@@ -50,6 +50,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadFlexMd = loadFlexMd;
 exports.extractJsonFromFlexMd = extractJsonFromFlexMd;
+exports.parseMarkdownSectionsFromContent = parseMarkdownSectionsFromContent;
 exports.isFlexMdAvailable = isFlexMdAvailable;
 exports.getModelMaxTokensFromFlexMd = getModelMaxTokensFromFlexMd;
 exports.getFlexMdModule = getFlexMdModule;
@@ -549,6 +550,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`.
+ */
+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-cjs/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-cjs/gateway-utils.cjs

@@ -44,6 +44,9 @@ exports.mergeConfig = mergeConfig;
 exports.normalizeRouterUsageTokens = normalizeRouterUsageTokens;
 exports.extractTokenUsageFromRouterResponse = extractTokenUsageFromRouterResponse;
 exports.extractCostUsdFromRouterResponse = extractCostUsdFromRouterResponse;
+exports.hasNonZeroTokenUsage = hasNonZeroTokenUsage;
+exports.resolveActivityCostCompletion = resolveActivityCostCompletion;
+exports.resolveCostCompletionForActivity = resolveCostCompletionForActivity;
 exports.pickInvokeRoutingMetadataSlice = pickInvokeRoutingMetadataSlice;
 exports.pickEffectiveModelConfigForMetadata = pickEffectiveModelConfigForMetadata;
 exports.pickTraceMergedRouterConfig = pickTraceMergedRouterConfig;
@@ -366,6 +369,50 @@ function extractCostUsdFromRouterResponse(routerResponse) {
     }
     return undefined;
 }
+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.
+ */
+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`).
+ */
+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);
+}
 /**
  * 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-cjs/gateway-utils.d.ts

@@ -43,6 +43,35 @@ 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;
+};
+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;
 /**
  * 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-cjs/gateway.cjs

@@ -11,6 +11,7 @@ const activity_manager_js_1 = require("./activity-manager.cjs");
 const gateway_config_js_1 = require("./gateway-config.cjs");
 const message_builder_js_1 = require("./message-builder.cjs");
 const flex_md_loader_js_1 = require("./flex-md-loader.cjs");
+const output_contract_normalizer_js_1 = require("./output-contract-normalizer.cjs");
 const gateway_utils_js_1 = require("./gateway-utils.cjs");
 const gateway_provider_auto_register_js_1 = require("./gateway-provider-auto-register.cjs");
 const runtime_objects_js_1 = require("./runtime-objects.cjs");
@@ -111,8 +112,9 @@ class AIGateway {
                 },
                 mode: 'sync'
             });
-            const costUsdChat = (0, gateway_utils_js_1.extractCostUsdFromRouterResponse)(response);
             const metaChat = response?.metadata || {};
+            const tokensChat = (0, gateway_utils_js_1.extractTokenUsageFromRouterResponse)(response);
+            const costCompletionChat = (0, gateway_utils_js_1.resolveCostCompletionForActivity)(response, tokensChat);
             // Create enhanced response
             const enhancedResponse = {
                 content: response.content || '',
@@ -120,22 +122,25 @@ class AIGateway {
                     aiRequestId: request.aiRequestId,
                     identity: request.identity,
                     latencyMs: Date.now() - startTime,
-                    tokens: (0, gateway_utils_js_1.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
@@ -526,6 +531,8 @@ class AIGateway {
             }
             contentType = 'structured';
             parsingMethod = 'flex-md';
+            const outputContractKeys = (0, output_contract_normalizer_js_1.resolveOutputContractFieldKeys)(request);
+            parsedContent = await (0, output_contract_normalizer_js_1.enrichParsedContentForOutputContract)(parsedContent, content, outputContractKeys, this.logger);
             let tokens = (0, gateway_utils_js_1.extractTokenUsageFromRouterResponse)(routerResponse);
             if (!(tokens.prompt || tokens.completion || tokens.total)) {
                 const alt = routerResponse?.rawResponse ?? routerResponse?.raw;
@@ -535,7 +542,7 @@ class AIGateway {
                         tokens = second;
                 }
             }
-            const resolvedCostUsd = (0, gateway_utils_js_1.extractCostUsdFromRouterResponse)(routerResponse);
+            const costCompletion = (0, gateway_utils_js_1.resolveCostCompletionForActivity)(routerResponse, tokens);
             const routerMetaForCost = routerResponse?.metadata || {};
             const routingMetadataSlice = (0, gateway_utils_js_1.pickInvokeRoutingMetadataSlice)(routerResponse, mergedConfig);
             const effectiveModelConfig = (0, gateway_utils_js_1.pickEffectiveModelConfigForMetadata)(mergedConfig);
@@ -554,14 +561,15 @@ 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,
@@ -600,7 +608,7 @@ class AIGateway {
                         usage: tokens
                     };
                     await this.activityManager.logSuccess(activity, {
-                        ...(typeof resolvedCostUsd === 'number' ? { cost: resolvedCostUsd } : {}),
+                        ...costCompletion,
                         response: activityResponse,
                         endTime: Date.now(),
                         duration: Date.now() - startTime

package/dist-cjs/index.cjs

@@ -21,7 +21,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetObjectTypesLibrary = exports.getObjectTypesLibrary = exports.initializeObjectTypesLibrary = exports.getObjectTypesForAgent = exports.getObjectType = exports.OBJECT_TYPES_LIBRARY = exports.assertValidAIRequest = exports.formatDiagnostic = exports.runValidationTests = exports.createValidationTestCases = exports.createTestAIRequest = exports.supportsJSONMode = exports.diagnoseResponse = exports.diagnoseRequest = exports.validateResponse = exports.extractJSON = exports.validateJSON = exports.validateAIRequest = exports.DEFAULT_RATE_LIMIT_ENABLED = exports.DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS = exports.GatewayRateLimiter = exports.runtimeObjects = exports.DebugLogAbstract = exports.createLogxer = exports.gatewayLogDebug = exports.withActivityIdentity = exports.activityIdentityToLogMeta = exports.ensureGatewayRequestIdentity = exports.ActivityManager = exports.Activix = exports.mergeTemplateRenderOptions = exports.mergeGatewayAndRequestTemplateRenderOptions = exports.pickRequestIdsFromRouterLike = exports.tryExtractRouterLikePayloadFromErrorChain = exports.buildInvokeRejectionMetadata = exports.attachGatewayInvokeRejectionMetadata = exports.autoRegisterProviders = exports.InstructionBackendError = exports.InstructionNotFoundError = exports.AIGateway = exports.FallbackExhaustedError = exports.ProviderNotFoundError = exports.createRouterFromConfig = exports.createRouter = exports.LLMProviderRouter = void 0;
+exports.createValidationTestCases = exports.createTestAIRequest = exports.supportsJSONMode = exports.diagnoseResponse = exports.diagnoseRequest = exports.validateResponse = exports.extractJSON = exports.validateJSON = exports.validateAIRequest = exports.DEFAULT_RATE_LIMIT_ENABLED = exports.DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS = exports.GatewayRateLimiter = exports.runtimeObjects = exports.DebugLogAbstract = exports.createLogxer = exports.gatewayLogDebug = exports.withActivityIdentity = exports.activityIdentityToLogMeta = exports.ensureGatewayRequestIdentity = exports.ActivityManager = exports.Activix = exports.resolveGatewayMemoryPathValue = exports.prepareWorkingMemoryForTemplateRender = exports.parseLooseJsonObject = exports.mapSmartInputPathsInputsToInput = exports.extractCallerInputsBag = exports.coalesceMergedInputBucket = exports.buildMemoryResolutionRootFromWorkingMemory = exports.GATEWAY_DUAL_MEMORY_ROOTS = exports.mergeTemplateRenderOptions = exports.mergeGatewayAndRequestTemplateRenderOptions = exports.resolveOutputContractFieldKeys = exports.enrichParsedContentForOutputContract = exports.contractSpecToFieldKeys = exports.hasNonZeroTokenUsage = exports.resolveCostCompletionForActivity = exports.resolveActivityCostCompletion = exports.pickRequestIdsFromRouterLike = exports.tryExtractRouterLikePayloadFromErrorChain = exports.buildInvokeRejectionMetadata = exports.attachGatewayInvokeRejectionMetadata = exports.autoRegisterProviders = exports.InstructionBackendError = exports.InstructionNotFoundError = exports.AIGateway = exports.FallbackExhaustedError = exports.ProviderNotFoundError = exports.createRouterFromConfig = exports.createRouter = exports.LLMProviderRouter = void 0;
+exports.resetObjectTypesLibrary = exports.getObjectTypesLibrary = exports.initializeObjectTypesLibrary = exports.getObjectTypesForAgent = exports.getObjectType = exports.OBJECT_TYPES_LIBRARY = exports.assertValidAIRequest = exports.formatDiagnostic = exports.runValidationTests = void 0;
 // Re-export router class and types (base functionality)
 var ai_providers_router_1 = require("@x12i/ai-providers-router");
 Object.defineProperty(exports, "LLMProviderRouter", { enumerable: true, get: function () { return ai_providers_router_1.LLMProviderRouter; } });
@@ -48,9 +49,25 @@ Object.defineProperty(exports, "attachGatewayInvokeRejectionMetadata", { enumera
 Object.defineProperty(exports, "buildInvokeRejectionMetadata", { enumerable: true, get: function () { return gateway_utils_js_1.buildInvokeRejectionMetadata; } });
 Object.defineProperty(exports, "tryExtractRouterLikePayloadFromErrorChain", { enumerable: true, get: function () { return gateway_utils_js_1.tryExtractRouterLikePayloadFromErrorChain; } });
 Object.defineProperty(exports, "pickRequestIdsFromRouterLike", { enumerable: true, get: function () { return gateway_utils_js_1.pickRequestIdsFromRouterLike; } });
+Object.defineProperty(exports, "resolveActivityCostCompletion", { enumerable: true, get: function () { return gateway_utils_js_1.resolveActivityCostCompletion; } });
+Object.defineProperty(exports, "resolveCostCompletionForActivity", { enumerable: true, get: function () { return gateway_utils_js_1.resolveCostCompletionForActivity; } });
+Object.defineProperty(exports, "hasNonZeroTokenUsage", { enumerable: true, get: function () { return gateway_utils_js_1.hasNonZeroTokenUsage; } });
+var output_contract_normalizer_js_1 = require("./output-contract-normalizer.cjs");
+Object.defineProperty(exports, "contractSpecToFieldKeys", { enumerable: true, get: function () { return output_contract_normalizer_js_1.contractSpecToFieldKeys; } });
+Object.defineProperty(exports, "enrichParsedContentForOutputContract", { enumerable: true, get: function () { return output_contract_normalizer_js_1.enrichParsedContentForOutputContract; } });
+Object.defineProperty(exports, "resolveOutputContractFieldKeys", { enumerable: true, get: function () { return output_contract_normalizer_js_1.resolveOutputContractFieldKeys; } });
 var template_render_merge_js_1 = require("./template-render-merge.cjs");
 Object.defineProperty(exports, "mergeGatewayAndRequestTemplateRenderOptions", { enumerable: true, get: function () { return template_render_merge_js_1.mergeGatewayAndRequestTemplateRenderOptions; } });
 Object.defineProperty(exports, "mergeTemplateRenderOptions", { enumerable: true, get: function () { return template_render_merge_js_1.mergeTemplateRenderOptions; } });
+var memory_path_resolution_js_1 = require("./memory-path-resolution.cjs");
+Object.defineProperty(exports, "GATEWAY_DUAL_MEMORY_ROOTS", { enumerable: true, get: function () { return memory_path_resolution_js_1.GATEWAY_DUAL_MEMORY_ROOTS; } });
+Object.defineProperty(exports, "buildMemoryResolutionRootFromWorkingMemory", { enumerable: true, get: function () { return memory_path_resolution_js_1.buildMemoryResolutionRootFromWorkingMemory; } });
+Object.defineProperty(exports, "coalesceMergedInputBucket", { enumerable: true, get: function () { return memory_path_resolution_js_1.coalesceMergedInputBucket; } });
+Object.defineProperty(exports, "extractCallerInputsBag", { enumerable: true, get: function () { return memory_path_resolution_js_1.extractCallerInputsBag; } });
+Object.defineProperty(exports, "mapSmartInputPathsInputsToInput", { enumerable: true, get: function () { return memory_path_resolution_js_1.mapSmartInputPathsInputsToInput; } });
+Object.defineProperty(exports, "parseLooseJsonObject", { enumerable: true, get: function () { return memory_path_resolution_js_1.parseLooseJsonObject; } });
+Object.defineProperty(exports, "prepareWorkingMemoryForTemplateRender", { enumerable: true, get: function () { return memory_path_resolution_js_1.prepareWorkingMemoryForTemplateRender; } });
+Object.defineProperty(exports, "resolveGatewayMemoryPathValue", { enumerable: true, get: function () { return memory_path_resolution_js_1.resolveGatewayMemoryPathValue; } });
 // Usage tracking: UsageTracker class methods are available but consumption calculation is disabled
 // (x-models was previously used for RPM/TPM tracking but is no longer integrated)
 // Re-export activity tracking primitives (Activix)

package/dist-cjs/index.d.ts

@@ -17,9 +17,14 @@ 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, hasNonZeroTokenUsage } from './gateway-utils.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';
+export type { GatewayDualMemoryRoot } from './memory-path-resolution.js';
 export type { UsageTier } from './types.js';
 export { Activix } from '@x12i/activix';
 export type { ActivixRunContext, FindByRunContextCriteria, GetJobActivitiesInput, GetJobActivitiesResult } from '@x12i/activix';

package/dist-cjs/memory-path-resolution.cjs

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * Dual memory roots `input` (merged MAIN payload) and `inputs` (caller / graph-entry bag).
+ * Aligned with @exellix/graph-engine ≥ 5.5.0 resolution rules for template / smart-input paths.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GATEWAY_DUAL_MEMORY_ROOTS = void 0;
+exports.parseLooseJsonObject = parseLooseJsonObject;
+exports.extractCallerInputsBag = extractCallerInputsBag;
+exports.coalesceMergedInputBucket = coalesceMergedInputBucket;
+exports.resolveGatewayMemoryPathValue = resolveGatewayMemoryPathValue;
+exports.buildMemoryResolutionRootFromWorkingMemory = buildMemoryResolutionRootFromWorkingMemory;
+exports.prepareWorkingMemoryForTemplateRender = prepareWorkingMemoryForTemplateRender;
+exports.mapSmartInputPathsInputsToInput = mapSmartInputPathsInputsToInput;
+exports.GATEWAY_DUAL_MEMORY_ROOTS = ['input', 'inputs'];
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Parse JSON object shapes from strings (matches graph-engine `parseLooseJsonObject`).
+ */
+function parseLooseJsonObject(value) {
+    if (isPlainObject(value))
+        return value;
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('{'))
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return isPlainObject(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Caller / graph-entry bag from `workingMemory.inputs`. */
+function extractCallerInputsBag(workingMemory) {
+    if (!isPlainObject(workingMemory))
+        return undefined;
+    const inputs = workingMemory.inputs;
+    return isPlainObject(inputs) ? inputs : undefined;
+}
+/** Merged MAIN bucket from `workingMemory.input` (object or parsed JSON string). */
+function coalesceMergedInputBucket(workingMemory) {
+    if (!isPlainObject(workingMemory))
+        return undefined;
+    const raw = workingMemory.input;
+    if (raw === undefined || raw === null)
+        return undefined;
+    const parsed = parseLooseJsonObject(raw);
+    return parsed !== undefined ? parsed : raw;
+}
+function getValueAtPath(obj, path) {
+    if (obj == null)
+        return undefined;
+    if (path === '' || path === 'this' || path === '.')
+        return obj;
+    const parts = path.split('.');
+    let cur = obj;
+    for (const part of parts) {
+        if (cur == null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+function asObjectBucket(value) {
+    const parsed = parseLooseJsonObject(value);
+    if (parsed)
+        return parsed;
+    return isPlainObject(value) ? value : undefined;
+}
+/**
+ * Shallow-deep merge for template lookup: primary wins per key; nested plain objects merge recursively.
+ */
+function mergeBucketViews(primary, fallback) {
+    const pObj = asObjectBucket(primary);
+    const fObj = asObjectBucket(fallback);
+    if (!pObj && !fObj) {
+        if (primary !== undefined && primary !== null)
+            return primary;
+        return fallback;
+    }
+    if (!pObj)
+        return { ...fObj };
+    if (!fObj)
+        return { ...pObj };
+    const keys = new Set([...Object.keys(pObj), ...Object.keys(fObj)]);
+    const view = {};
+    for (const key of keys) {
+        const pv = pObj[key];
+        const fv = fObj[key];
+        if (isPlainObject(pv) && isPlainObject(fv)) {
+            view[key] = mergeBucketViews(pv, fv);
+        }
+        else {
+            view[key] = pv !== undefined ? pv : fv;
+        }
+    }
+    return view;
+}
+/**
+ * Resolve a dotted path against working memory with dual-root rules:
+ * - `inputs` / `inputs.*` → caller bag first, then merged `input`
+ * - `input` / `input.*` → merged `input` first, then caller `inputs`
+ * - other paths → direct lookup on working memory
+ */
+function resolveGatewayMemoryPathValue(workingMemory, path) {
+    const trimmed = path.trim();
+    if (!trimmed)
+        return undefined;
+    const dot = trimmed.indexOf('.');
+    const root = dot >= 0 ? trimmed.slice(0, dot) : trimmed;
+    const tail = dot >= 0 ? trimmed.slice(dot + 1) : '';
+    if (root === 'inputs') {
+        const primary = extractCallerInputsBag(workingMemory);
+        const fallback = coalesceMergedInputBucket(workingMemory);
+        if (!tail) {
+            if (primary && Object.keys(primary).length > 0)
+                return primary;
+            return fallback;
+        }
+        const fromPrimary = primary ? getValueAtPath(primary, tail) : undefined;
+        if (fromPrimary !== undefined)
+            return fromPrimary;
+        return fallback !== undefined ? getValueAtPath(fallback, tail) : undefined;
+    }
+    if (root === 'input') {
+        const primary = coalesceMergedInputBucket(workingMemory);
+        const fallback = extractCallerInputsBag(workingMemory);
+        if (!tail) {
+            if (primary !== undefined && primary !== null)
+                return primary;
+            return fallback;
+        }
+        const fromPrimary = primary !== undefined ? getValueAtPath(primary, tail) : undefined;
+        if (fromPrimary !== undefined)
+            return fromPrimary;
+        return fallback ? getValueAtPath(fallback, tail) : undefined;
+    }
+    return getValueAtPath(workingMemory, trimmed);
+}
+/**
+ * Working-memory view for Rendrix / smart-input: preserves all keys but overlays
+ * `input` and `inputs` with dual-root merge views (does not rewrite authored paths).
+ */
+function buildMemoryResolutionRootFromWorkingMemory(workingMemory) {
+    if (!isPlainObject(workingMemory))
+        return {};
+    const inputsBag = extractCallerInputsBag(workingMemory);
+    const mergedInput = coalesceMergedInputBucket(workingMemory);
+    return {
+        ...workingMemory,
+        input: mergeBucketViews(mergedInput, inputsBag),
+        inputs: mergeBucketViews(inputsBag, mergedInput)
+    };
+}
+/**
+ * When WM carries `input` and/or `inputs`, return a resolution root for template rendering.
+ * Otherwise returns the original reference unchanged.
+ */
+function prepareWorkingMemoryForTemplateRender(workingMemory) {
+    if (!isPlainObject(workingMemory))
+        return workingMemory;
+    if (workingMemory.input === undefined && workingMemory.inputs === undefined) {
+        return workingMemory;
+    }
+    return buildMemoryResolutionRootFromWorkingMemory(workingMemory);
+}
+/** Optional migration: rewrite `inputs.*` smart-input / memory paths to `input.*`. */
+function mapSmartInputPathsInputsToInput(paths) {
+    return paths.map((p) => {
+        const t = p.trim();
+        if (t === 'inputs')
+            return 'input';
+        if (t.startsWith('inputs.'))
+            return `input.${t.slice('inputs.'.length)}`;
+        return p;
+    });
+}

package/dist-cjs/memory-path-resolution.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Dual memory roots `input` (merged MAIN payload) and `inputs` (caller / graph-entry bag).
+ * Aligned with @exellix/graph-engine ≥ 5.5.0 resolution rules for template / smart-input paths.
+ */
+export declare const GATEWAY_DUAL_MEMORY_ROOTS: readonly ["input", "inputs"];
+export type GatewayDualMemoryRoot = (typeof GATEWAY_DUAL_MEMORY_ROOTS)[number];
+/**
+ * Parse JSON object shapes from strings (matches graph-engine `parseLooseJsonObject`).
+ */
+export declare function parseLooseJsonObject(value: unknown): Record<string, unknown> | undefined;
+/** Caller / graph-entry bag from `workingMemory.inputs`. */
+export declare function extractCallerInputsBag(workingMemory: unknown): Record<string, unknown> | undefined;
+/** Merged MAIN bucket from `workingMemory.input` (object or parsed JSON string). */
+export declare function coalesceMergedInputBucket(workingMemory: unknown): unknown;
+/**
+ * Resolve a dotted path against working memory with dual-root rules:
+ * - `inputs` / `inputs.*` → caller bag first, then merged `input`
+ * - `input` / `input.*` → merged `input` first, then caller `inputs`
+ * - other paths → direct lookup on working memory
+ */
+export declare function resolveGatewayMemoryPathValue(workingMemory: unknown, path: string): unknown;
+/**
+ * Working-memory view for Rendrix / smart-input: preserves all keys but overlays
+ * `input` and `inputs` with dual-root merge views (does not rewrite authored paths).
+ */
+export declare function buildMemoryResolutionRootFromWorkingMemory(workingMemory: unknown): Record<string, unknown>;
+/**
+ * When WM carries `input` and/or `inputs`, return a resolution root for template rendering.
+ * Otherwise returns the original reference unchanged.
+ */
+export declare function prepareWorkingMemoryForTemplateRender(workingMemory: unknown): unknown;
+/** Optional migration: rewrite `inputs.*` smart-input / memory paths to `input.*`. */
+export declare function mapSmartInputPathsInputsToInput(paths: string[]): string[];