@x12i/ai-gateway 9.1.5 → 9.2.0

package/dist/activity-manager.d.ts

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

package/dist/activity-manager.js

@@ -155,6 +155,12 @@ function pickActivixCompletionRoutingMetadata(response) {
     if (m.effectiveModelConfig != null && typeof m.effectiveModelConfig === 'object') {
         out.effectiveModelConfig = m.effectiveModelConfig;
     }
+    if (typeof m.cost === 'number' && Number.isFinite(m.cost))
+        out.cost = m.cost;
+    if (typeof m.costUsd === 'number' && Number.isFinite(m.costUsd))
+        out.costUsd = m.costUsd;
+    if (m.costStatus === 'priced' || m.costStatus === 'unpriced')
+        out.costStatus = m.costStatus;
     return out;
 }
 function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
@@ -844,6 +850,7 @@ export class ActivityManager {
             }
             await this.activix.completeRecord(activity.activityId, {
                 cost: details.cost,
+                ...(details.costStatus ? { costStatus: details.costStatus } : {}),
                 response: details.response,
                 outer: {
                     output: details.response,

package/dist/flex-md-loader.d.ts

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

package/dist/flex-md-loader.js

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

package/dist/gateway-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/gateway-utils.js

@@ -315,6 +315,50 @@ 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);
+}
 /**
  * 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.js

@@ -8,7 +8,8 @@ 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, resolveCostCompletionForActivity, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
@@ -108,8 +109,9 @@ export class AIGateway {
                 },
                 mode: 'sync'
             });
-            const costUsdChat = extractCostUsdFromRouterResponse(response);
             const metaChat = response?.metadata || {};
+            const tokensChat = extractTokenUsageFromRouterResponse(response);
+            const costCompletionChat = resolveCostCompletionForActivity(response, tokensChat);
             // Create enhanced response
             const enhancedResponse = {
                 content: response.content || '',
@@ -117,22 +119,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
@@ -523,6 +528,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 +539,7 @@ export class AIGateway {
                         tokens = second;
                 }
             }
-            const resolvedCostUsd = extractCostUsdFromRouterResponse(routerResponse);
+            const costCompletion = resolveCostCompletionForActivity(routerResponse, tokens);
             const routerMetaForCost = routerResponse?.metadata || {};
             const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
             const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);
@@ -551,14 +558,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 +605,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

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

@@ -17,8 +17,10 @@ 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, hasNonZeroTokenUsage } from './gateway-utils.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
 // (x-models was previously used for RPM/TPM tracking but is no longer integrated)
 // Re-export activity tracking primitives (Activix)

package/dist/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[];

package/dist/memory-path-resolution.js

@@ -0,0 +1,172 @@
+/**
+ * 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 const 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`).
+ */
+export 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`. */
+export 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). */
+export 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
+ */
+export 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).
+ */
+export 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.
+ */
+export 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.*`. */
+export 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/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;
+}