@x12i/ai-gateway 7.9.1

package/dist/gateway-config.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Gateway Configuration Module
+ * Handles configuration loading and setup
+ */
+import type { GatewayConfig } from './types.js';
+import type { Logxer } from '@x12i/logxer';
+import { LLMProviderRouter } from '@x12i/ai-providers-router';
+import { ActivityManager } from './activity-manager.js';
+import { UsageTracker } from './usage-tracker.js';
+import type { MessageBuilderConfig } from './message-builder.js';
+import type { TemplateRenderOptions } from '@x12i/rendrix';
+export interface GatewayConfigContext {
+    defaultModelConfig: Record<string, unknown>;
+    defaultInstructionsBlocks: Record<string, any>;
+    config: GatewayConfig;
+    logger: Logxer;
+    router: LLMProviderRouter;
+    activityManager: ActivityManager;
+    usageTracker: UsageTracker;
+    messageBuilderConfig: MessageBuilderConfig;
+}
+/**
+ * Loads configuration from JSON files (model config and instructionsBlocks)
+ * Note: Called before logger is initialized, so no logging here
+ */
+export declare function loadConfig(): {
+    defaultModelConfig: Record<string, unknown>;
+    defaultInstructionsBlocks: Record<string, any>;
+    defaultTemplateRendering?: TemplateRenderOptions;
+};
+/**
+ * Gets the minimum flex-md compliance level from environment variable
+ * Defaults to 'L0' if not set or invalid
+ */
+export declare function getFlexMdMinComplianceLevel(): 'L0' | 'L1' | 'L2' | 'L3';
+/**
+ * Sets up request interceptor for jobId propagation and config cleanup
+ */
+export declare function setupRequestInterceptor(router: LLMProviderRouter, logger: Logxer): void;
+/**
+ * Initializes gateway components
+ */
+export declare function initializeGatewayComponents(config: GatewayConfig, defaultModelConfig: Record<string, unknown>, defaultInstructionsBlocks: Record<string, any>, defaultTemplateRendering?: TemplateRenderOptions): {
+    logger: Logxer;
+    router: LLMProviderRouter;
+    activityManager: ActivityManager;
+    usageTracker: UsageTracker;
+    messageBuilderConfig: MessageBuilderConfig;
+};

package/dist/gateway-config.js

@@ -0,0 +1,292 @@
+/**
+ * Gateway Configuration Module
+ * Handles configuration loading and setup
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+/** Resolve current module directory across ESM/CJS builds. */
+function getModuleDir() {
+    if (typeof __dirname !== 'undefined') {
+        return __dirname;
+    }
+    try {
+        const getMetaUrl = new Function('return import.meta.url');
+        const metaUrl = getMetaUrl();
+        if (metaUrl && metaUrl.startsWith('file:')) {
+            return path.dirname(fileURLToPath(metaUrl));
+        }
+    }
+    catch {
+        // Fall through to cwd
+    }
+    return process.cwd();
+}
+/** Resolve directory containing defaults/ with package-local precedence. */
+function getDefaultsDir() {
+    const moduleDir = getModuleDir();
+    const cwd = process.cwd();
+    const candidates = [
+        moduleDir,
+        path.resolve(moduleDir, '..'),
+        path.resolve(moduleDir, '../dist'),
+        path.resolve(moduleDir, '../dist-cjs'),
+        path.resolve(moduleDir, '../src'),
+        path.join(cwd, 'dist'),
+        path.join(cwd, 'dist-cjs'),
+        path.join(cwd, 'src'),
+    ];
+    for (const dir of candidates) {
+        const modelConfigPath = path.join(dir, 'defaults', 'model-config.json');
+        if (fs.existsSync(modelConfigPath)) {
+            return dir;
+        }
+    }
+    // Keep existing behavior as a last fallback.
+    return path.join(cwd, 'dist');
+}
+import { LLMProviderRouter } from '@x12i/ai-providers-router';
+import { createGatewayLogger } from './logger-factory.js';
+import { ActivityManager } from './activity-manager.js';
+import { UsageTracker } from './usage-tracker.js';
+import { mergeTemplateRenderOptions } from './template-render-merge.js';
+import { GatewayRateLimiter } from './gateway-rate-limiter.js';
+import { DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS, DEFAULT_RATE_LIMIT_ENABLED } from './gateway-rate-limiter-constants.js';
+/**
+ * Loads configuration from JSON files (model config and instructionsBlocks)
+ * Note: Called before logger is initialized, so no logging here
+ */
+export function loadConfig() {
+    const defaultModelConfig = {};
+    const defaultInstructionsBlocks = {};
+    let defaultTemplateRendering;
+    try {
+        const defaultsDir = getDefaultsDir();
+        const templateRenderingPath = path.join(defaultsDir, 'defaults', 'template-rendering.json');
+        if (fs.existsSync(templateRenderingPath)) {
+            const trContent = fs.readFileSync(templateRenderingPath, 'utf-8');
+            defaultTemplateRendering = JSON.parse(trContent);
+        }
+        // Load model config (includes rate limiting and retry defaults)
+        const modelConfigPath = path.join(defaultsDir, 'defaults', 'model-config.json');
+        if (fs.existsSync(modelConfigPath)) {
+            const content = fs.readFileSync(modelConfigPath, 'utf-8');
+            const parsed = JSON.parse(content);
+            Object.assign(defaultModelConfig, parsed);
+        }
+        // Load instructionsBlocks
+        const instructionsBlocksPath = path.join(defaultsDir, 'defaults', 'instructions-blocks.json');
+        if (fs.existsSync(instructionsBlocksPath)) {
+            const content = fs.readFileSync(instructionsBlocksPath, 'utf-8');
+            const parsed = JSON.parse(content);
+            // Use Object.assign to merge, preserving nested structure
+            Object.assign(defaultInstructionsBlocks, parsed);
+            // Debug: Log what was loaded (only in development)
+            if (process.env.NODE_ENV !== 'production') {
+                console.log('Loaded instructions blocks:', {
+                    topLevelKeys: Object.keys(defaultInstructionsBlocks),
+                    hasOutput: 'output' in defaultInstructionsBlocks,
+                    outputKeys: 'output' in defaultInstructionsBlocks ? Object.keys(defaultInstructionsBlocks.output) : []
+                });
+            }
+        }
+        else {
+            // Optional file: fallback defaults below still keep the gateway functional.
+            if (process.env.NODE_ENV !== 'production') {
+                console.debug('Optional instructions blocks file not found at:', instructionsBlocksPath);
+            }
+        }
+    }
+    catch (error) {
+        // Can't log here as logger isn't initialized yet
+        // Error will be logged after logger initialization in constructor
+        console.warn('Failed to load defaults from JSON files:', error);
+    }
+    // Ensure critical blocks exist even if file loading failed
+    if (!defaultInstructionsBlocks['outputObjectPrefix']) {
+        defaultInstructionsBlocks['outputObjectPrefix'] = "Reply in Markdown. Return your entire answer inside a single ```markdown fenced block and nothing else. The content must conform to the schema provided below. If no items are found, return empty arrays (e.g., emails: []). Never ask for more input. Do not write conversational text. Do not write explanations. Do not ask questions.\n\n";
+    }
+    if (!defaultInstructionsBlocks['outputObjectTypesPrefix']) {
+        defaultInstructionsBlocks['outputObjectTypesPrefix'] = "Reply in Markdown. Return your entire answer inside a single ```markdown fenced block and nothing else. Select ONE of the following object types based on the input. The content must conform to the chosen schema. Do not write conversational text. Do not write explanations.\n\n";
+    }
+    return { defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering };
+}
+/**
+ * Gets the minimum flex-md compliance level from environment variable
+ * Defaults to 'L0' if not set or invalid
+ */
+export function getFlexMdMinComplianceLevel() {
+    const envValue = process.env.FLEX_MD_MIN_COMPLIANCE_LEVEL;
+    if (envValue === 'L0' || envValue === 'L1' || envValue === 'L2' || envValue === 'L3') {
+        return envValue;
+    }
+    return 'L0'; // Default: allow anything
+}
+/**
+ * Sets up request interceptor for jobId propagation and config cleanup
+ */
+export function setupRequestInterceptor(router, logger) {
+    logger.debug('Setting up request interceptor for jobId propagation and config cleanup');
+    router.addRequestInterceptor(async (request, provider) => {
+        // Propagate jobId to request metadata
+        if (request.jobId) {
+            logger.verbose('Propagating jobId to request metadata', {
+                jobId: request.jobId,
+                provider: provider?.getProviderName?.() || 'unknown'
+            });
+            if (!request.config) {
+                request.config = {};
+            }
+            if (!request.config.metadata) {
+                request.config.metadata = {};
+            }
+            request.config.metadata.jobId = request.jobId;
+        }
+        // Remove 'provider' from config - router uses it for routing but providers don't accept it
+        // Router reads config.provider to determine which provider to call, but then passes
+        // the entire config to the provider, which rejects 'provider' as invalid
+        if (request.config && 'provider' in request.config) {
+            logger.debug('Removing provider from config before passing to provider', {
+                provider: request.config.provider
+            });
+            const { provider: _, ...cleanConfig } = request.config;
+            request.config = cleanConfig;
+        }
+        return request;
+    });
+    logger.debug('Request interceptor configured');
+}
+/**
+ * Initializes gateway components
+ */
+export function initializeGatewayComponents(config, defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering) {
+    // Initialize logger FIRST (before other components that might need it)
+    const logger = createGatewayLogger({
+        enableLogging: config.enableLogging ?? true,
+        packageName: config.packageName,
+        customLogger: config.logger
+    });
+    // Now that logger is initialized, log the defaults loading
+    logger.verbose('Gateway initializing', {
+        defaultEngine: config.defaultEngine,
+        hasDefaultInstructionsBlocks: Object.keys(defaultInstructionsBlocks).length > 0
+    });
+    // Activity tracking is handled by Activix internally.
+    // Initialize router - this is the ONLY way to access providers
+    // RouterConfig properties are inherited from RouterConfig interface
+    const routerConfig = {};
+    const defaultTarget = config.defaultTarget;
+    if (defaultTarget) {
+        routerConfig.defaultTarget = defaultTarget;
+    }
+    else if (config.defaultProvider !== undefined) {
+        routerConfig.defaultProvider = config.defaultProvider;
+    }
+    else if (config.defaultEngine !== undefined) {
+        routerConfig.defaultProvider = config.defaultEngine;
+    }
+    const fallbackChain = config.fallbackChain;
+    if (fallbackChain) {
+        routerConfig.fallbackChain = fallbackChain;
+    }
+    else if (config.fallbackChain !== undefined) {
+        routerConfig.fallbackChain = config.fallbackChain;
+    }
+    if (config.autoDiscover !== undefined)
+        routerConfig.autoDiscover = config.autoDiscover;
+    if (config.usageTracker !== undefined)
+        routerConfig.usageTracker = config.usageTracker;
+    // OpenRouter: enable when key is set and not explicitly disabled (so consumers get a working default without registering providers).
+    // Prefer explicit config from consumer (e.g. ai-skills) to avoid env-loading timing; fall back to process.env.
+    const explicitOpenRouterKey = config.openrouter?.apiKey;
+    const isExplicitKey = typeof explicitOpenRouterKey === 'string' && !explicitOpenRouterKey.startsWith('ENV.');
+    const openRouterKey = isExplicitKey ? explicitOpenRouterKey : (process.env.OPEN_ROUTER_KEY ?? process.env.OPENROUTER_API_KEY);
+    const useOpenRouter = config.openRouter?.enabled !== undefined ? config.openRouter?.enabled : process.env.USE_OPENROUTER;
+    if (openRouterKey && useOpenRouter !== false && useOpenRouter !== 'false') {
+        routerConfig.openRouter = { enabled: true };
+        routerConfig.openrouter = { apiKey: openRouterKey };
+        routerConfig.defaultMode = 'openrouter';
+    }
+    const router = new LLMProviderRouter(routerConfig);
+    // Set up BETWEEN-CALLS rate limiting as a request interceptor (applies to all provider calls)
+    // This ensures rate limiting works even when router is used directly without gateway
+    // Hidden in the flow - automatic and transparent
+    // 
+    // NOTE: This is for BETWEEN-CALLS rate limiting (smart, tracks last call time).
+    // Retry delays are handled separately in gateway-retry.ts (simple sleep, not smart).
+    const rateLimitConfig = config.rateLimit;
+    // Get defaults from JSON config, fallback to constants
+    const jsonRateLimitConfig = defaultModelConfig.rateLimit || {};
+    const rateLimitEnabled = rateLimitConfig?.enabled ?? jsonRateLimitConfig.enabled ?? DEFAULT_RATE_LIMIT_ENABLED;
+    if (rateLimitEnabled) {
+        // Priority: explicit config > JSON defaults > constants
+        const defaultMinIntervalMs = rateLimitConfig?.defaultMinIntervalMs
+            ?? jsonRateLimitConfig.defaultMinIntervalMs
+            ?? DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS;
+        const providerIntervals = rateLimitConfig?.providerIntervals;
+        const rateLimiter = new GatewayRateLimiter(defaultMinIntervalMs, providerIntervals, logger);
+        // Add request interceptor for BETWEEN-CALLS rate limiting (hidden in the flow)
+        router.addRequestInterceptor(async (request, provider) => {
+            // Get provider name
+            const providerName = typeof provider?.getProviderName === 'function'
+                ? provider.getProviderName()
+                : 'global';
+            // Smart rate limiting: wait only if necessary based on last call time
+            // This is for BETWEEN-CALLS, not retries (retries use simple sleep in gateway-retry.ts)
+            await rateLimiter.waitIfNeeded(providerName);
+            // Return request unchanged (interceptor can modify request, but we just need to wait)
+            return request;
+        });
+        // Add response interceptor to record call completion
+        // Note: Type assertion needed due to ResponseInterceptor type definition mismatch
+        router.addResponseInterceptor((async (response, request, provider) => {
+            // Get provider name
+            const providerName = typeof provider?.getProviderName === 'function'
+                ? provider.getProviderName()
+                : 'global';
+            // Record the call time after completion (for smart between-calls rate limiting)
+            rateLimiter.recordCall(providerName);
+            // Return response unchanged
+            return response;
+        }));
+        logger.debug('Between-calls rate limiting configured as router interceptor', {
+            defaultMinIntervalMs,
+            providerIntervals: providerIntervals ? Object.keys(providerIntervals).length : 0,
+            enabled: true,
+            note: 'Smart rate limiting (between-calls only). Retry delays handled separately (simple sleep).'
+        });
+    }
+    else {
+        logger.debug('Rate limiting disabled');
+    }
+    // Initialize usage tracking
+    const usageTracker = new UsageTracker({
+        enableUsageTracking: config.enableUsageTracking ?? true,
+        usageTier: config.usageTier,
+        logger
+    });
+    // Initialize activity tracking
+    const activityManager = new ActivityManager({
+        enableActivityTracking: config.enableActivityTracking ?? true,
+        customTracker: config.activityTracker,
+        logger
+    });
+    const templateRendering = mergeTemplateRenderOptions(defaultTemplateRendering, config.templateRendering);
+    const instructionsBlockOverrides = {
+        ...(config.instructionsBlocks ?? {})
+    };
+    // Initialize message builder config - for direct message construction
+    const messageBuilderConfig = {
+        defaultInstructionsBlocks,
+        instructionsBlockOverrides,
+        logger,
+        templateRendering
+    };
+    return {
+        logger,
+        router,
+        activityManager,
+        usageTracker,
+        messageBuilderConfig
+    };
+}

package/dist/gateway-conversion.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Gateway Conversion Module
+ * Handles structured text conversion and two-step conversion
+ *
+ * Text mode now uses flex-md format exclusively.
+ * Two-step conversion parses flex-md directly to JSON without additional LLM call.
+ */
+import type { AIRequest, EnhancedLLMResponse, GatewayConfig } from './types.js';
+import type { Logxer } from '@x12i/logxer';
+import type { AIGateway } from './gateway.js';
+/**
+ * Invoke structured text mode (first step of two-step conversion)
+ */
+export declare function invokeStructuredText(request: AIRequest, gateway: AIGateway): Promise<EnhancedLLMResponse<string>>;
+/**
+ * Get default conversion instructions for two-step mode
+ *
+ * NOTE: This function is no longer used in two-step conversion.
+ * Two-step mode now parses flex-md directly using the flex-md package.
+ * This function is kept for backward compatibility only.
+ */
+export declare function getDefaultConversionInstructions(): string;
+/**
+ * Convert flex-md structured text to JSON (second step of two-step conversion)
+ *
+ * This function now parses flex-md directly using the flex-md package,
+ * eliminating the need for an additional LLM call.
+ */
+export declare function convertStructuredToJson(structuredText: string, originalRequest: AIRequest, config: GatewayConfig, gateway: AIGateway, logger: Logxer): Promise<EnhancedLLMResponse>;

package/dist/gateway-conversion.js

@@ -0,0 +1,174 @@
+/**
+ * Gateway Conversion Module
+ * Handles structured text conversion and two-step conversion
+ *
+ * Text mode now uses flex-md format exclusively.
+ * Two-step conversion parses flex-md directly to JSON without additional LLM call.
+ */
+import { extractJsonFromFlexMd } from './flex-md-loader.js';
+/**
+ * Get the current directory - works in both ESM and CJS
+ * In CJS: uses __dirname
+ * In ESM: uses import.meta.url (accessed via eval to avoid TS errors in CJS build)
+ */
+async function getCurrentDir() {
+    if (typeof __dirname !== 'undefined') {
+        return __dirname;
+    }
+    // ESM: use import.meta.url
+    // Use Function constructor to access import.meta without TypeScript errors
+    try {
+        const getMetaUrl = new Function('return import.meta.url');
+        const metaUrl = getMetaUrl();
+        if (metaUrl) {
+            const url = await import('url');
+            const path = await import('path');
+            return path.dirname(url.fileURLToPath(metaUrl));
+        }
+    }
+    catch {
+        // Fall through to process.cwd()
+    }
+    // Fallback
+    return process.cwd();
+}
+/**
+ * Invoke structured text mode (first step of two-step conversion)
+ */
+export async function invokeStructuredText(request, gateway) {
+    // Create a new request with structured-text mode
+    const structuredRequest = {
+        ...request,
+        jobId: `${request.jobId}-step1`
+    };
+    // Make the call (this will recursively call invoke, but with structured-text mode)
+    return await gateway.invoke(structuredRequest);
+}
+/**
+ * Get default conversion instructions for two-step mode
+ *
+ * NOTE: This function is no longer used in two-step conversion.
+ * Two-step mode now parses flex-md directly using the flex-md package.
+ * This function is kept for backward compatibility only.
+ */
+export function getDefaultConversionInstructions() {
+    return `You are a data converter. Your task is to convert structured text into valid JSON.
+
+You will receive structured text output from an AI assistant. Convert it into a valid JSON object that captures all the information from the structured text.
+
+Your response must be ONLY a valid JSON object with no other text. The JSON should preserve all information from the structured text in a structured format.
+
+CRITICAL RULES:
+- Your ENTIRE response must be parseable JSON
+- Do NOT write conversational text outside the JSON
+- Response must START with { and END with }
+- Preserve all information from the structured text
+- Use appropriate JSON data types (strings, numbers, arrays, objects)
+- If the structured text contains a story or narrative, structure it appropriately in JSON
+- Extract key elements and organize them logically`;
+}
+/**
+ * Convert flex-md structured text to JSON (second step of two-step conversion)
+ *
+ * This function now parses flex-md directly using the flex-md package,
+ * eliminating the need for an additional LLM call.
+ */
+export async function convertStructuredToJson(structuredText, originalRequest, config, gateway, logger) {
+    logger.debug('Two-step conversion: Parsing flex-md text directly using flex-md SDK 3.0.0', {
+        aiRequestId: originalRequest.aiRequestId,
+        structuredTextLength: structuredText.length,
+        usingFlexMd: true
+    });
+    try {
+        // Use flex-md 3.0.0 to extract and parse JSON
+        const flexMdResult = await extractJsonFromFlexMd(structuredText);
+        if (!flexMdResult || !flexMdResult.json) {
+            throw new Error('flex-md SDK could not extract JSON from structured text');
+        }
+        const parsedJson = flexMdResult.json;
+        // Create response structure matching EnhancedLLMResponse
+        const conversionResponse = {
+            content: structuredText, // Keep original flex-md text
+            rawText: structuredText,
+            parsedContent: parsedJson, // Parsed JSON from flex-md
+            requestId: originalRequest.aiRequestId,
+            provider: 'conversion',
+            rawResponse: structuredText,
+            metadata: {
+                aiRequestId: originalRequest.aiRequestId,
+                agentId: originalRequest.agentId,
+                latencyMs: 0, // No LLM call, so no latency
+                tokens: {
+                    prompt: 0,
+                    completion: 0,
+                    total: 0
+                },
+                model: 'flex-md-parser', // Indicate we used flex-md parser
+                provider: 'flex-md',
+                isTwoStepConversion: true,
+                structuredTextStep: 'second',
+                contentType: 'object', // Parsed JSON is an object
+                conversionMethod: 'flex-md-direct-parse'
+            }
+        };
+        logger.info('Two-step conversion completed using flex-md parser', {
+            aiRequestId: originalRequest.aiRequestId,
+            parsedContentType: typeof parsedJson,
+            isObject: typeof parsedJson === 'object' && parsedJson !== null
+        });
+        return conversionResponse;
+    }
+    catch (parseError) {
+        const error = parseError instanceof Error ? parseError : new Error(String(parseError));
+        logger.error('Two-step conversion failed: flex-md parse error', {
+            jobId: originalRequest.jobId,
+            error: error.message,
+            errorName: error.name,
+            structuredTextPreview: structuredText.substring(0, 200)
+        });
+        // Create error report for flex-md parsing issue
+        let flexMdVersion = 'unknown';
+        try {
+            // Use type assertion to allow dynamic import of package.json
+            const flexMdPkg = await import('flex-md/package.json');
+            flexMdVersion = flexMdPkg?.version || flexMdPkg?.default?.version || 'unknown';
+        }
+        catch {
+            // Package.json not accessible
+        }
+        const report = {
+            package: 'flex-md',
+            version: flexMdVersion,
+            issue: 'parse function threw error',
+            error: error.message,
+            errorName: error.name,
+            stack: error.stack,
+            timestamp: new Date().toISOString(),
+            request: {
+                jobId: originalRequest.jobId,
+                agentId: originalRequest.agentId
+            },
+            inputPreview: structuredText.substring(0, 500),
+            inputLength: structuredText.length,
+            environment: {
+                nodeVersion: process.version,
+                platform: process.platform
+            }
+        };
+        // Write report to docs directory
+        try {
+            const fs = await import('fs');
+            const path = await import('path');
+            const currentDir = await getCurrentDir();
+            const reportPath = path.join(currentDir, '../../docs/FLEX_MD_PACKAGE_ISSUE_REPORT.json');
+            fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+            logger.error('flex-md parsing error report written', { reportPath });
+        }
+        catch (writeError) {
+            logger.error('Failed to write flex-md parsing error report', {
+                error: writeError instanceof Error ? writeError.message : String(writeError)
+            });
+        }
+        throw new Error(`flex-md parsing failed: ${error.message}`);
+    }
+}

package/dist/gateway-instructions.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Gateway Instructions Module
+ * Handles instructions block resolution from inline config only (no content registry).
+ */
+import type { Logxer } from '@x12i/logxer';
+export interface InstructionsContext {
+    defaultInstructionsBlocks: Record<string, any>;
+    /** Flat overrides from gateway `instructionsBlocks` (merged at init). */
+    instructionsBlockOverrides: Record<string, string>;
+    /** Per-request flat overrides from `request.config.instructionsBlocks`. */
+    requestInstructionsBlocks?: Record<string, string>;
+    config: {
+        instructionsBlocks?: Record<string, any>;
+    };
+    logger: Logxer;
+}
+/**
+ * Resolves nested instructionsBlocks (e.g., "input.inputRecognitionRule")
+ * Supports dot notation for nested object access in defaultInstructionsBlocks,
+ * then flat keys in merged overrides.
+ */
+export declare function resolveNestedInstructionsBlock(blockPath: string, _agentId: string, _taskTypeId: string | undefined, context: InstructionsContext): Promise<string>;
+/**
+ * Resolves instructionsBlocks from config overrides, request overrides, nested defaults, or flat defaults.
+ */
+export declare function resolveInstructionsBlock(blockName: string, agentId: string, taskTypeId: string | undefined, context: InstructionsContext): Promise<string>;
+/**
+ * Pre-parse instructions string for stable hashing (taskTypeId). No external resolution.
+ */
+export declare function getPreParsedInstructions(instructions: string | undefined): string;

package/dist/gateway-instructions.js

@@ -0,0 +1,62 @@
+/**
+ * Gateway Instructions Module
+ * Handles instructions block resolution from inline config only (no content registry).
+ */
+import { InstructionNotFoundError } from './instruction-errors.js';
+function getNestedString(blocks, dotPath) {
+    const parts = dotPath.split('.');
+    let cur = blocks;
+    for (const p of parts) {
+        if (cur == null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[p];
+    }
+    return typeof cur === 'string' ? cur : undefined;
+}
+/**
+ * Resolves nested instructionsBlocks (e.g., "input.inputRecognitionRule")
+ * Supports dot notation for nested object access in defaultInstructionsBlocks,
+ * then flat keys in merged overrides.
+ */
+export async function resolveNestedInstructionsBlock(blockPath, _agentId, _taskTypeId, context) {
+    return resolveInstructionsBlock(blockPath, _agentId, _taskTypeId, context);
+}
+/**
+ * Resolves instructionsBlocks from config overrides, request overrides, nested defaults, or flat defaults.
+ */
+export async function resolveInstructionsBlock(blockName, agentId, taskTypeId, context) {
+    const { config, logger, defaultInstructionsBlocks, instructionsBlockOverrides, requestInstructionsBlocks } = context;
+    logger.verbose('Resolving instructionsBlock', {
+        blockName,
+        agentId,
+        taskTypeId,
+        hasConfigOverride: !!config.instructionsBlocks?.[blockName]
+    });
+    const configOverride = config.instructionsBlocks?.[blockName];
+    if (typeof configOverride === 'string' && configOverride.trim()) {
+        logger.debug('Using per-call config override for instructionsBlock', { blockName, agentId });
+        return configOverride;
+    }
+    const fromRequest = requestInstructionsBlocks?.[blockName];
+    if (typeof fromRequest === 'string' && fromRequest.trim()) {
+        logger.debug('Using request.config.instructionsBlocks for instructionsBlock', { blockName, agentId });
+        return fromRequest;
+    }
+    const fromGateway = instructionsBlockOverrides[blockName];
+    if (typeof fromGateway === 'string' && fromGateway.trim()) {
+        logger.debug('Using gateway instructionsBlocks override for instructionsBlock', { blockName, agentId });
+        return fromGateway;
+    }
+    const nested = getNestedString(defaultInstructionsBlocks, blockName);
+    if (nested?.trim()) {
+        logger.debug('Using nested defaultInstructionsBlocks for instructionsBlock', { blockName, agentId });
+        return nested;
+    }
+    throw new InstructionNotFoundError(blockName, 'instructions-blocks', `InstructionsBlock "${blockName}" not found. Provide it via packaged defaults, gateway instructionsBlocks, or request.config.instructionsBlocks.`, blockName);
+}
+/**
+ * Pre-parse instructions string for stable hashing (taskTypeId). No external resolution.
+ */
+export function getPreParsedInstructions(instructions) {
+    return instructions ?? '';
+}