@x12i/ai-gateway 9.1.6 → 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,7 +17,10 @@ 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';

package/dist/index.js

@@ -17,7 +17,8 @@ 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

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

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

package/dist/output-contract-normalizer.js

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

package/dist/types.d.ts

@@ -701,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
@@ -932,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,8 +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.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.resolveGatewayMemoryPathValue = exports.prepareWorkingMemoryForTemplateRender = exports.parseLooseJsonObject = exports.mapSmartInputPathsInputsToInput = exports.extractCallerInputsBag = exports.coalesceMergedInputBucket = exports.buildMemoryResolutionRootFromWorkingMemory = exports.GATEWAY_DUAL_MEMORY_ROOTS = 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.resetObjectTypesLibrary = exports.getObjectTypesLibrary = exports.initializeObjectTypesLibrary = 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; } });
@@ -49,6 +49,13 @@ 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; } });

package/dist-cjs/index.d.ts

@@ -17,7 +17,10 @@ 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';

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

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contractSpecToFieldKeys = contractSpecToFieldKeys;
+exports.resolveOutputContractFieldKeys = resolveOutputContractFieldKeys;
+exports.enrichParsedContentForOutputContract = enrichParsedContentForOutputContract;
+const flex_md_loader_js_1 = require("./flex-md-loader.cjs");
+const memory_path_resolution_js_1 = require("./memory-path-resolution.cjs");
+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.
+ */
+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 = (0, memory_path_resolution_js_1.extractCallerInputsBag)(workingMemory);
+    if (inputs?.outputContract !== undefined)
+        return inputs.outputContract;
+    const input = (0, memory_path_resolution_js_1.coalesceMergedInputBucket)(workingMemory);
+    if (isPlainObject(input) && input.outputContract !== undefined) {
+        return input.outputContract;
+    }
+    const loose = (0, memory_path_resolution_js_1.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.
+ */
+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.
+ */
+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 = (0, flex_md_loader_js_1.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/types.d.ts

@@ -701,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
@@ -932,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "9.1.6",
+  "version": "9.2.0",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -60,7 +60,7 @@
   "author": "x12i",
   "license": "mit",
   "dependencies": {
-    "@x12i/ai-providers-router": "^4.7.7",
+    "@x12i/ai-providers-router": "^4.8.0",
     "@x12i/rendrix": "^4.3.0",
     "@aws-sdk/s3-request-presigner": "^3.953.0",
     "@x12i/env": "^4.0.1",