@x12i/ai-gateway 7.9.1

package/dist/types.d.ts

@@ -0,0 +1,1173 @@
+/**
+ * Type definitions for AI Gateway
+ *
+ * Extends router types with gateway-specific enhancements
+ */
+import { AIResponse, LLMProviderRouter, type RouterConfig } from '@x12i/ai-providers-router';
+type AIProvider = string;
+type AIModel = string;
+export type UsageTier = string;
+import type { Activix } from '@x12i/activix';
+import type { TemplateRenderOptions } from '@x12i/rendrix';
+import type { Logxer } from '@x12i/logxer';
+/**
+ * Identity object used for activity linkage.
+ * On gateway requests/responses it lives on `identity`. When activity tracking persists via Activix v5+,
+ * the same envelope is written under the BSON field `runContext` (see `@x12i/activix` changelog).
+ */
+export type ActivityIdentity = {
+    /**
+     * Run/session correlation id for Activix (one logical session or job-scoped flow).
+     * Distinct from `aiRequestId` when multiple gateway invocations share one run.
+     */
+    sessionId: string;
+    /**
+     * Required runtime identity descriptor for the execution instance.
+     * `instanceId` and `type` are always set (with gateway fallbacks); additional keys are preserved for Activix.
+     */
+    instance: {
+        instanceId: string;
+        type: string;
+        [key: string]: unknown;
+    };
+    /** Gateway-level request correlation ID. */
+    aiRequestId: string;
+    /** @deprecated Use aiRequestId. Kept only for backward compatibility. */
+    jobId?: string;
+    jobTypeId?: string;
+    agentId: string;
+    taskId?: string;
+    taskTypeId?: string;
+    /** Graph/node linkage (optional, used by activity identity grouping). */
+    graphId?: string;
+    nodeId?: string;
+    /** Alternative identifiers (optional, forwarded for compatibility with upstream). */
+    coreSkillId?: string;
+    masterSkillId?: string;
+    masterSkillActivityId?: string;
+};
+/** Re-export parser template options for gateway consumers (MUST/optional protocol, subPathSearch, etc.). */
+export type { TemplateRenderOptions } from '@x12i/rendrix';
+type LLMRequest = Parameters<LLMProviderRouter['invoke']>[0];
+type LLMResponse = Awaited<ReturnType<LLMProviderRouter['invoke']>>;
+/**
+ * Gateway configuration extending router configuration
+ *
+ * RouterConfig already includes:
+ * - defaultProvider?: LLMProvider (from llm-provider-interface)
+ * - fallbackChain?: LLMProvider[]
+ * - autoDiscover?: boolean
+ * - usageTracker?: UsageTracker
+ *
+ * We don't need to redeclare these - they're inherited from RouterConfig
+ */
+/**
+ * Provider + model reference used for defaults and fallbacks
+ */
+export interface ProviderModelRef {
+    engine: AIProvider;
+    model: AIModel;
+}
+/**
+ * Retry configuration for network and server errors
+ */
+export interface RetryConfig {
+    /**
+     * Maximum number of retry attempts
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay in milliseconds before first retry
+     * @default 1000
+     */
+    initialDelay?: number;
+    /**
+     * Maximum delay cap in milliseconds
+     * @default 30000
+     */
+    maxDelay?: number;
+    /**
+     * Enable exponential backoff multiplier
+     * @default 2
+     */
+    backoffMultiplier?: number;
+    /**
+     * Enable jitter (randomization) to prevent thundering herd
+     * @default true
+     */
+    enableJitter?: boolean;
+    /**
+     * Additional delay for 429 (throttling) errors in milliseconds
+     * @default 5000
+     */
+    throttlingDelay?: number;
+}
+/**
+ * Model configuration for request execution.
+ *
+ * Controls which model is used and how it generates responses.
+ * This configuration is passed through to the gateway for model selection and parameter control.
+ *
+ * Priority: modelConfig overrides request.config, which overrides gateway defaults.
+ */
+export interface ModelConfig {
+    /**
+     * Model identifier (e.g., "gpt-4-turbo", "claude-3-opus", "gpt-3.5-turbo")
+     * If not specified, uses gateway/router default
+     */
+    model?: string;
+    /**
+     * Model ID (alternative to model name, for provider-specific model IDs)
+     * If both model and modelId are provided, model takes precedence
+     */
+    modelId?: string;
+    /**
+     * Provider name (e.g., "openai", "anthropic")
+     * If not specified, uses client default provider
+     */
+    provider?: string;
+    /**
+     * Temperature for generation (0.0 to 2.0)
+     * Controls randomness in responses
+     */
+    temperature?: number;
+    /**
+     * Maximum tokens to generate
+     */
+    maxTokens?: number;
+    /**
+     * Top-p (nucleus) sampling parameter (0.0 to 1.0)
+     */
+    topP?: number;
+    /**
+     * Frequency penalty (-2.0 to 2.0)
+     */
+    frequencyPenalty?: number;
+    /**
+     * Presence penalty (-2.0 to 2.0)
+     */
+    presencePenalty?: number;
+    /**
+     * Stop sequences (array of strings)
+     * Generation stops when any stop sequence is encountered
+     */
+    stop?: string[];
+    /**
+     * Additional provider-specific parameters
+     */
+    [key: string]: any;
+}
+export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'logger'> {
+    /**
+     * Default target (engine + model) for routing
+     */
+    defaultTarget?: ProviderModelRef;
+    /**
+     * Fallback chain for routing (engine + model pairs)
+     */
+    fallbackChain?: ProviderModelRef[];
+    /**
+     * Usage tier for rate limiting (RPM/TPM)
+     * @default 'tier-3'
+     */
+    usageTier?: UsageTier;
+    /**
+     * Enable activity tracking
+     * @default true
+     */
+    enableActivityTracking?: boolean;
+    /**
+     * Enable usage tier tracking
+     * @default true
+     */
+    enableUsageTracking?: boolean;
+    /**
+     * Enable logging
+     * @default true
+     */
+    enableLogging?: boolean;
+    /**
+     * Custom logger instance (optional)
+     */
+    logger?: Logxer;
+    /**
+     * Custom activity tracker instance (optional)
+     */
+    activityTracker?: Activix;
+    /**
+     * Package name for logging
+     * @default 'AI_GATEWAY'
+     */
+    packageName?: string;
+    /**
+     * Default engine (e.g., 'openai', 'anthropic')
+     * Used only for provider routing when request doesn't specify provider
+     */
+    defaultEngine?: string;
+    /**
+     * OpenRouter API key passed explicitly (avoids env-loading order when the gateway is created before .env is loaded).
+     * When set, the router receives this key at creation so OpenRouter can be registered even if process.env is not yet available.
+     */
+    openrouter?: {
+        apiKey: string;
+    };
+    /**
+     * Enable OpenRouter mode. When omitted, the gateway uses process.env.USE_OPENROUTER or enables when a key is set.
+     */
+    openRouter?: {
+        enabled?: boolean;
+    };
+    /**
+     * InstructionsBlocks overrides
+     * Key: block name, Value: block content
+     */
+    instructionsBlocks?: Record<string, string>;
+    /**
+     * Default temperature for LLM requests
+     */
+    temperature?: number;
+    /**
+     * Other LLM config options
+     */
+    maxTokens?: number;
+    topP?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    /**
+     * Retry configuration for network and server errors
+     */
+    retry?: RetryConfig;
+    /**
+     * Rate limiting configuration
+     * Smart rate limiting that tracks when the last API call was made
+     * and only waits if necessary to maintain minimum intervals between calls.
+     * Applied automatically to all provider calls via router interceptors.
+     */
+    rateLimit?: {
+        /**
+         * Enable rate limiting
+         * @default true
+         */
+        enabled?: boolean;
+        /**
+         * Default minimum interval in milliseconds between API calls (used if provider-specific not set)
+         * @default 500
+         */
+        defaultMinIntervalMs?: number;
+        /**
+         * Per-provider minimum intervals in milliseconds
+         * Key: provider name (e.g., 'openai', 'grok')
+         * Value: minimum milliseconds between calls for that provider
+         *
+         * @example
+         * {
+         *   openai: 500,  // 500ms between OpenAI calls
+         *   grok: 1000,   // 1 second between Grok calls
+         *   anthropic: 300  // 300ms between Anthropic calls
+         * }
+         */
+        providerIntervals?: Record<string, number>;
+    };
+    /**
+     * Default task configuration for template rendering
+     * @deprecated taskConfig is no longer used by Rendrix 3.0.0+
+     * Kept for backward compatibility only - will be ignored
+     */
+    defaultTaskConfig?: {
+        includeThoughts?: boolean;
+    };
+    /**
+     * Default options passed to @x12i/rendrix `render` (v4+).
+     * Merged with `src/defaults/template-rendering.json` (gateway `templateRendering` overrides packaged JSON defaults).
+     * Per-request `templateRenderOptions` on the request overrides this.
+     *
+     * **Sub-path search root priority:** when `subPathSearch.enabled` is true, the **`roots` array order is the priority**
+     * (first root wins; ISSUE-005). Omit `roots` to use the parser package defaults. Example:
+     * `subPathSearch: { enabled: true, roots: ['execution', 'input', 'inputs'] }`.
+     */
+    templateRendering?: TemplateRenderOptions;
+    /**
+     * Memory manager instance for unified memory management
+     * When provided, enables fetching and merging memories from persistent storage
+     * Type: @x12i/ai-memory MemoryManager (placeholder until component is ready)
+     */
+    memoryManager?: unknown;
+    /**
+     * Memory resolution configuration
+     * Controls which memory types to fetch and how to resolve them
+     */
+    memoryResolution?: {
+        /**
+         * Whether to fetch workingMemory from the component
+         * @default true
+         */
+        fetchWorkingMemory?: boolean;
+        /**
+         * Whether to fetch shortTermMemory from the component
+         * @default true
+         */
+        fetchShortTermMemory?: boolean;
+        /**
+         * Whether to fetch experienceMemory from the component
+         * @default true
+         */
+        fetchExperienceMemory?: boolean;
+        /**
+         * Whether to fetch knowledgeMemory from the component
+         * @default true
+         */
+        fetchKnowledgeMemory?: boolean;
+        /**
+         * Whether to update existing memories in storage with merged results
+         * When true, the final merged memory (from input + fetched) will be saved back to storage
+         * @default false
+         */
+        updateExistingMemories?: boolean;
+        /**
+         * Scope of memory updates - which memory types can be updated
+         * Only applies when updateExistingMemories is true
+         * @default ['shortTermMemory', 'experienceMemory', 'knowledgeMemory']
+         */
+        updateScope?: Array<'workingMemory' | 'shortTermMemory' | 'experienceMemory' | 'knowledgeMemory'>;
+        /**
+         * Enrichment configuration for experience and knowledge memories
+         * @default { experience: 'none', knowledge: 'none' }
+         */
+        enrichment?: {
+            experience?: 'none' | 'force' | 'ttl' | 'lacking';
+            knowledge?: 'none' | 'force' | 'ttl' | 'lacking';
+        };
+        /**
+         * Strategy for memory resolution
+         * @default 'fetch-on-demand'
+         */
+        resolutionStrategy?: 'cache-only' | 'fetch-on-demand' | 'enrich';
+    };
+    /**
+     * Object types library cache TTL in milliseconds
+     * @default 3600000 (1 hour)
+     */
+    objectTypesCacheTTL?: number;
+    /**
+     * Internal system actions configuration
+     * Configures models and engines for internal AI operations (two-step conversion, instruction optimization, etc.)
+     * These are separate from user requests and use dedicated models/engines
+     */
+    internalSystemActions?: {
+        /**
+         * Model and engine for two-step conversion (second step - converting structured text to JSON)
+         * @default { engine: 'openai', model: 'gpt-5-nano' }
+         */
+        twoStepConversion?: {
+            engine?: string;
+            model: string;
+            temperature?: number;
+            maxTokens?: number;
+        };
+        /**
+         * Model and engine for instruction optimization
+         * @default { engine: 'openai', model: 'gpt-5-nano' }
+         */
+        instructionOptimization?: {
+            engine?: string;
+            model: string;
+            temperature?: number;
+            maxTokens?: number;
+        };
+        /**
+         * Model and engine for instruction auditing/testing
+         * @default { engine: 'openai', model: 'gpt-5-nano' }
+         */
+        instructionAudit?: {
+            engine?: string;
+            model: string;
+            temperature?: number;
+            maxTokens?: number;
+        };
+        /**
+         * Model and engine for default skill execution
+         * @default { engine: 'openai', model: 'gpt-5-nano' }
+         */
+        internalSkill?: {
+            engine?: string;
+            model: string;
+            temperature?: number;
+            maxTokens?: number;
+        };
+        /**
+         * Model and engine for default skill audit
+         * @default { engine: 'openai', model: 'gpt-5-nano' }
+         */
+        skillAudit?: {
+            engine?: string;
+            model: string;
+            temperature?: number;
+            maxTokens?: number;
+        };
+    };
+}
+/**
+ * Internal base request type (not exported)
+ * Contains all common properties shared by ChatRequest and AIRequest
+ * Extends LLMRequest but omits 'messages' and 'input' to allow custom message handling
+ * and make input optional (router may require it, but gateway allows it to be optional)
+ */
+interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input'> {
+    /**
+     * AI request ID - Required for all invocations and activity tracking
+     */
+    aiRequestId: string;
+    /** @deprecated Use aiRequestId. Kept only for backward compatibility. */
+    jobId?: string;
+    /**
+     * Optional top-level run/session id for Activix. Prefer `identity.sessionId`; if both are set they must match.
+     * When omitted, `ActivityManager` resolves session from `identity.sessionId`, then `jobId`, then `aiRequestId`.
+     */
+    sessionId?: string;
+    /**
+     * Optional identity object used for upstream linkage (forwarded through the request).
+     * May be partial; may include product-specific keys beyond `ActivityIdentity`. When omitted,
+     * the gateway normalizes and attaches a full envelope (`ensureGatewayRequestIdentity` / activity tracking).
+     */
+    identity?: ActivityIdentity & Record<string, unknown>;
+    /**
+     * Job type ID (optional) - Short ID or hash to identify recurring job types
+     * Best practice: Use MD5 hash of the job type string for consistent job identification
+     * Example: MD5("data-processing-job") = "abc123..." for all jobs of the same type
+     * Works like taskTypeId but for job-level aggregation
+     */
+    jobTypeId?: string;
+    /**
+     * Agent ID - Required to identify the agent
+     */
+    agentId: string;
+    /**
+     * Agent type - Identifies the type of agent making the request
+     * - 'chat': Simple chat agent (uses invokeChat)
+     * - 'ai-reasoner': AI reasoning agent (uses invoke with objectTypes)
+     * - 'ai-auditor': AI auditing agent
+     * - 'ai-scoper': AI scoping agent
+     * - 'ai-discovery': AI discovery agent
+     * - 'ai-planner': AI planning agent
+     * - 'ai-executor': AI execution agent
+     * @default 'chat' for ChatRequest, 'ai-reasoner' for AIRequest
+     */
+    agentType?: 'chat' | 'ai-reasoner' | 'ai-auditor' | 'ai-scoper' | 'ai-discovery' | 'ai-planner' | 'ai-executor';
+    /**
+     * Instructions - Required template text (parsed with workingMemory / tier memories via Rendrix).
+     */
+    instructions: string;
+    /**
+     * Task ID (optional)
+     */
+    taskId?: string;
+    /**
+     * Task type ID (optional) - Short ID or hash to identify recurring tasks
+     * If not provided, will be auto-generated as MD5 hash of the pre-parsed instructions
+     * Best practice: Use MD5 hash of the question/instruction text for consistent task identification
+     * Example: MD5("What is the capital of France?") = "abc123..." for all requests with same question
+     */
+    taskTypeId?: string;
+    /**
+     * Graph ID (optional) - Identifier for graph execution context
+     * Used when executing nodes within a graph to track which graph contains the node
+     * Example: 'graph-123' or 'workflow-data-processing'
+     * When provided, enables smarter activity identity and grouping by graph
+     */
+    graphId?: string;
+    /**
+     * Node ID (optional) - Identifier for the specific node being executed
+     * Used when executing nodes within a graph to track which node is being executed
+     * Example: 'node-456' or 'extract-emails'
+     * When provided along with graphId, enables precise activity identity and tracking
+     * Mapped to identity.nodeId in activity tracking
+     */
+    nodeId?: string;
+    /**
+     * Core Skill ID (optional) - Alternative node identifier for graph execution
+     * Used when executing nodes within a graph (alternative to nodeId or skillId)
+     * Example: 'q0' or 'extract-emails-node'
+     * Mapped to identity.nodeId in activity tracking (alternative to skillId/nodeId)
+     */
+    coreSkillId?: string;
+    /**
+     * Prompt template text (optional) — parsed with workingMemory and tier memories.
+     * Use variables such as {{input}} resolved from workingMemory.input.
+     */
+    prompt?: string;
+    /**
+     * Context text (optional) - Template that can use workingMemory
+     * Added as system message between instructions and prompt
+     */
+    context?: string;
+    /**
+     * Task configuration (optional) - Control template behavior and conditional rendering
+     * @deprecated taskConfig is no longer used by Rendrix 3.0.0+
+     * Kept for backward compatibility only - will be ignored
+     */
+    taskConfig?: {
+        includeThoughts?: boolean;
+    };
+    /**
+     * Working memory (optional) - Affects all template parsing
+     * Passed to Rendrix (v4+) for template variable substitution.
+     * Plain {{path}} tokens are MUST paths: undefined after merge throws TemplateResolutionError (rethrown by the gateway).
+     */
+    workingMemory?: unknown;
+    /**
+     * Per-request overrides for Rendrix `TemplateRenderOptions` (v4+).
+     * Merged on top of gateway `templateRendering` and packaged defaults.
+     * For `subPathSearch.roots`, array order is search priority (first match wins); a request can override
+     * the full list or only set `enabled` and inherit `roots` from the gateway default merge.
+     */
+    templateRenderOptions?: TemplateRenderOptions;
+    /**
+     * Template tokens (optional) - Tier 1 (highest priority) token values
+     * These tokens are passed directly as arguments and override all other memory sources
+     * Common tokens: taskDescription, input (from workingMemory.input), role
+     * Example: { taskDescription: "Extract emails", input: "user@example.com", role: "user" }
+     * Note: The `input` field has been removed. Use workingMemory.input instead.
+     */
+    templateTokens?: {
+        [key: string]: string | number | boolean | object | object[];
+    };
+    /**
+     * Messages array - Optional, can be used instead of instructions/prompt
+     * If provided, will be appended as-is after built messages; instructions template text is still parsed for the system message when present
+     */
+    messages?: any;
+    /**
+     * Config - Can override gateway defaults
+     *
+     * For reasoning-capable models (OpenRouter unified reasoning API), can include:
+     * ```typescript
+     * reasoning?: {
+     *   effort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh';  // xhigh normalized to high
+     *   visibility?: 'none' | 'summary' | 'trace';  // What reasoning info to return
+     *   onUnsupported?: 'error' | 'downgrade' | 'ignore';  // Error handling
+     * }
+     * ```
+     */
+    config?: any;
+    /**
+     * Model configuration for this request execution.
+     *
+     * Overrides default model settings from gateway initialization.
+     * Merged with request.config (modelConfig takes precedence).
+     *
+     * Use this field for structured model configuration from upstream clients (e.g., @woroces/ai-tasks).
+     * The gateway will merge modelConfig into request.config before passing to the router.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   modelConfig: {
+     *     model: "gpt-4-turbo",
+     *     provider: "openai",
+     *     temperature: 0.7,
+     *     maxTokens: 2000
+     *   }
+     * }
+     * ```
+     */
+    modelConfig?: ModelConfig;
+    /**
+     * Inference type for outputs library parsing (optional)
+     * When provided, response will be parsed into typed inference output
+     * Can be a single type (string) or multiple types (array)
+     */
+    inferenceType?: string | string[];
+    /**
+     * Enable output schema validation (optional)
+     * When true, validates parsed output against schema from instruction metadata or outputs library
+     * @default false
+     */
+    validateOutputSchema?: boolean;
+    /**
+     * Enable strict validation mode (optional)
+     * When true, validation errors will throw exceptions instead of warnings
+     * @default false
+     */
+    strictValidation?: boolean;
+    /**
+     * Response transformation hooks (optional)
+     * Allows transforming responses at different stages of processing
+     */
+    transformations?: ResponseTransformationConfig;
+    /**
+     * Parse options for outputs library (optional)
+     * Used when inferenceType is provided for parsing inference outputs
+     */
+    parseOptions?: Record<string, unknown>;
+}
+/**
+ * Chat request for conversational use cases
+ *
+ * Mandatory:
+ * - aiRequestId: Required for activity tracking
+ * - agentId: Required to identify the agent
+ * - instructions: Required (template text)
+ *
+ * Minimum: instructions + prompt (prompt is required for user message)
+ *
+ * Note: objectTypes is NOT supported in ChatRequest.
+ * Use AIRequest with invoke() method for structured output requests.
+ */
+export interface ChatRequest extends BaseLLMRequest {
+    /**
+     * Optional expected schema for contract output validation
+     * When provided, AI response will be parsed against this schema and stored in activity records
+     */
+    expectedSchema?: StructuredTextSpec;
+}
+/**
+ * Structured text format specification
+ * Free-form description of desired output structure
+ *
+ * NOTE: Text mode now uses flex-md format exclusively.
+ * The LLM should return valid flex-md that can be parsed to JSON.
+ */
+export interface StructuredTextSpec {
+    /**
+     * Free-form description of the output structure
+     * Examples: "a story with character, setting, and conflict",
+     * "a detailed explanation with introduction, body, and conclusion"
+     *
+     * The LLM will format this as flex-md text.
+     */
+    description: string;
+    /**
+     * Optional format hints (flex-md specific hints)
+     * If not provided, LLM should use standard flex-md format
+     */
+    formatHint?: string;
+}
+/**
+ * AI request for structured output requests
+ * Used exclusively with invoke() method for requests requiring structured output
+ *
+ * Mandatory:
+ * - aiRequestId: Required for activity tracking
+ * - agentId: Required to identify the agent
+ * - instructions: Required (template text)
+ * - primaryObjectType OR flexMdFormat: Required for structured output
+ *   * primaryObjectType: Standard/custom object type (requires outputs library)
+ *   * flexMdFormat: Direct flex-md format specification (no outputs library needed)
+ */
+export interface AIRequest extends BaseLLMRequest {
+    /**
+     * Encrypted reasoning items for conversation continuity
+     * Only include reasoning.encrypted items from previous responses
+     * Must be preserved and replayed verbatim in subsequent requests
+     */
+    reasoningEncrypted?: Array<{
+        id: string;
+        type: string;
+        format?: string;
+        index?: number;
+        data?: string;
+        summary?: any[];
+    }>;
+    /**
+     * Skill execution tracking fields
+     * Used when executing skills (instruction keys starting with 'skills/')
+     */
+    /**
+     * Master skill activity ID - The parent skill activity's ID (when a skill calls another skill)
+     * When a skill executes and calls another skill, the parent skill's activityId becomes
+     * the child skill's masterSkillActivityId. This allows tracking all sub-activities of a skill execution.
+     */
+    masterSkillActivityId?: string;
+    /**
+     * Skill ID - The skill identifier (e.g., 'skills/professional-answer')
+     * Auto-detected from instruction key if not provided. Used for skill execution tracking.
+     */
+    skillId?: string;
+    /**
+     * Master skill ID - The parent skill's identifier (when a skill calls another skill)
+     * When a skill executes and calls another skill, the parent skill's skillId becomes
+     * the child skill's masterSkillId. This allows tracking skill hierarchies.
+     */
+    masterSkillId?: string;
+}
+/**
+ * Enhanced response with comprehensive metadata and generic type support
+ *
+ * @template TContent - Type of parsedContent (defaults to unknown)
+ */
+/**
+ * Failure types for activity tracking
+ *
+ * - pre-call-validation: Request validation failed before attempting LLM call (missing/invalid prefix, schema, etc.)
+ * - api-call-failure: API call failed (network error, API error, timeout) - no response from LLM
+ * - llm-response-failure: LLM responded but couldn't answer (bad input, bad instructions, bad context, missing context, missing input)
+ * - response-parsing-failure: LLM responded but response failed to parse (non-JSON, prose instead of JSON, invalid format)
+ */
+export type FailureType = 'pre-call-validation' | 'api-call-failure' | 'llm-response-failure' | 'response-parsing-failure';
+/**
+ * LLM response failure subtypes (when failureType is 'llm-response-failure')
+ */
+export type LLMResponseFailureSubtype = 'bad-input' | 'bad-instructions' | 'bad-context' | 'missing-context' | 'missing-input';
+/**
+ * Response parsing failure subtypes (when failureType is 'response-parsing-failure')
+ */
+export type ResponseParsingFailureSubtype = 'invalid-flex-md' | 'flex-md-parse-failed' | 'invalid-json-format' | 'missing-parsed-content' | 'schema-validation-failed';
+export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse, 'content' | 'metadata' | 'reasoning'> {
+    /**
+     * Normalized content string (always present)
+     * - If original was string: returns the string
+     * - If original was object/array: returns JSON.stringify()
+     * - If original was null: returns empty string
+     */
+    content: string;
+    /**
+     * Original raw text from provider (before any parsing)
+     * Available if router preserved rawText
+     */
+    rawText?: string;
+    /**
+     * Parsed content (object or array) if content was JSON
+     * Typed based on generic TContent
+     */
+    parsedContent?: TContent;
+    /**
+     * Unified reasoning response from router (OpenRouter Reasoning API)
+     * Provides normalized reasoning across all providers
+     */
+    reasoning?: {
+        requested: {
+            effort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh';
+            visibility?: 'none' | 'summary' | 'trace';
+        };
+        applied: {
+            effort?: 'none' | 'low' | 'medium' | 'high';
+            visibility?: 'none' | 'summary' | 'trace';
+        };
+        artifacts?: {
+            summary?: {
+                text: string;
+                format: string;
+            };
+            trace?: {
+                text: string;
+                format: string;
+            };
+            encrypted?: Array<{
+                id: string;
+                format: string;
+                type?: string;
+                [key: string]: any;
+            }>;
+        };
+        availability?: {
+            supportsEffort?: boolean;
+            supportsSummary?: boolean;
+            supportsTrace?: boolean;
+            supportsEncrypted?: boolean;
+        };
+        warnings?: Array<{
+            code: 'EFFORT_NORMALIZED' | 'VISIBILITY_DOWNGRADED' | 'EFFORT_IGNORED' | 'REASONING_UNSUPPORTED';
+            message: string;
+        }>;
+    };
+    /**
+     * Encrypted reasoning items for conversation continuity
+     * Must be preserved and replayed verbatim in subsequent requests
+     * @deprecated Use reasoning.artifacts.encrypted instead (unified reasoning API)
+     */
+    reasoningEncrypted?: Array<{
+        id: string;
+        type: string;
+        format?: string;
+        index?: number;
+        data?: string;
+        summary?: any[];
+    }>;
+    /**
+     * Readable reasoning summary (human-readable)
+     * Not replayed - only for display/audit purposes
+     * @deprecated Use reasoning.artifacts.summary instead (unified reasoning API)
+     */
+    reasoningSummary?: Array<{
+        id: string;
+        type: string;
+        format?: string;
+        index?: number;
+        content?: any;
+    }>;
+    /**
+     * Enhanced metadata including latency, tokens, model, and aiRequestId
+     * Merges with existing metadata from router response
+     */
+    metadata: LLMResponse['metadata'] & {
+        /**
+         * AI request ID that triggered this execution
+         */
+        aiRequestId?: string;
+        /**
+         * Execution latency in milliseconds
+         */
+        latencyMs: number;
+        /**
+         * Detailed token usage breakdown
+         */
+        tokens: {
+            prompt: number;
+            completion: number;
+            total: number;
+        };
+        /**
+         * Model ID used (e.g., 'gpt-4o', 'claude-sonnet-4')
+         */
+        model?: string;
+        /**
+         * Provider used (e.g., 'openai', 'anthropic')
+         */
+        provider?: string;
+        /**
+         * Cost in USD (if available)
+         */
+        cost?: number;
+        /**
+         * Content type classification
+         * Indicates whether content is 'string', 'object', 'array', or 'null'
+         */
+        contentType?: 'string' | 'object' | 'array' | 'null';
+        /**
+         * Gateway normalization data (optional - tracks content normalization process)
+         * Available when content normalization was performed
+         */
+        normalization?: {
+            /**
+             * Original raw text from provider (before any parsing)
+             */
+            rawText?: string;
+            /**
+             * Parsed content (object or array) if content was JSON
+             */
+            parsedContent?: any;
+            /**
+             * Content type classification from normalization
+             */
+            contentType: 'string' | 'object' | 'array' | 'null';
+            /**
+             * Normalized content string
+             */
+            normalizedContent: string;
+        };
+        /**
+         * Output format information (optional - extracted and validated from instructions)
+         * Available when output format is extracted from instruction templates
+         */
+        outputFormat?: {
+            /**
+             * The extracted/validated format specification
+             */
+            spec?: string;
+            /**
+             * Detected compliance level (L0, L1, L2, L3)
+             */
+            level?: 'L0' | 'L1' | 'L2' | 'L3';
+            /**
+             * Whether validation passed
+             */
+            validated?: boolean;
+            /**
+             * Validation errors if any
+             */
+            validationErrors?: string[];
+        };
+        /**
+         * Provider normalization metadata (optional - tracks provider-level normalization)
+         * Available when provider normalized the request (messages format, config parameters, etc.)
+         * This comes from router response metadata.normalization
+         */
+        providerNormalization?: {
+            /**
+             * Whether the request messages/format were normalized
+             * For example, converting gateway messages array to API-specific format
+             */
+            messagesNormalized?: boolean;
+            /**
+             * Whether configuration parameters were normalized
+             * This includes parameter name conversions, removals, or value adjustments
+             */
+            configNormalized?: boolean;
+            /**
+             * The normalized configuration that was actually sent to the API
+             * This allows consumers to see exactly what parameters were used
+             */
+            normalizedConfig?: Record<string, unknown>;
+            /**
+             * The normalized messages that were actually sent to the API
+             * This allows consumers to see the exact message format used
+             */
+            normalizedMessages?: any;
+            /**
+             * The normalized request that was actually sent to the API
+             * This allows consumers to see the exact request format used
+             */
+            normalizedRequest?: any;
+            /**
+             * Warnings about parameter modifications during normalization
+             * Examples:
+             * - "Omitted temperature (not supported by gpt-5-nano)"
+             * - "Converted maxTokens -> max_output_tokens"
+             */
+            warnings?: string[];
+        };
+        /**
+         * Parsed inference output (if inferenceType was provided in request)
+         * Typed based on the inference type
+         */
+        parsedOutput?: unknown;
+        /**
+         * Inference type used for parsing (if provided)
+         */
+        inferenceType?: string;
+        /**
+         * Validation errors from schema validation (if enabled)
+         */
+        outputValidationErrors?: string[];
+        /**
+         * Whether output validation passed (if validation was enabled)
+         */
+        outputValidationPassed?: boolean;
+        /**
+         * Schema used for validation (if validation was enabled)
+         */
+        outputSchema?: Record<string, unknown>;
+        /**
+         * Whether outputs library was available and used for parsing
+         */
+        outputsLibraryAvailable?: boolean;
+        /**
+         * Method used for parsing (outputs-library, json-parse, or raw)
+         */
+        parsingMethod?: 'outputs-library' | 'json-parse' | 'raw';
+        /**
+         * Whether fallback structure was used (parsing failed but structure guaranteed)
+         * When true, parsedOutput contains a fallback structure with _fallback: true flag
+         */
+        isFallback?: boolean;
+        /**
+         * Selected object type when multiple object types were provided (v2.1.2+)
+         * Indicates which object type from the objectTypes array was used in the response
+         */
+        selectedObjectType?: string;
+        /**
+         * Index of the selected object type in the objectTypes array (v2.1.2+)
+         */
+        selectedObjectTypeIndex?: number;
+        /**
+         * All available object types that were provided in the request (v2.1.2+)
+         */
+        availableObjectTypes?: string[];
+        /**
+         * Confidence score for object type selection (0-1) (v2.1.2+)
+         * Higher values indicate better match between response and selected schema
+         */
+        objectTypeConfidence?: number;
+        /**
+         * Whether instructions-error object was detected in the response (v2.1.2+)
+         */
+        hasInstructionsError?: boolean;
+        /**
+         * Whether prompt-error object was detected in the response (v2.1.2+)
+         */
+        hasPromptError?: boolean;
+        structuredTextStep?: 'first' | 'second';
+        /**
+         * Output structure audit results (v2.1.1+)
+         * Automatically generated when outputSchema is available
+         * Provides detailed analysis of the response structure against the expected schema
+         */
+        outputAudit?: {
+            /**
+             * Whether all required fields from schema are present
+             */
+            hasAllRequiredFields: boolean;
+            /**
+             * Missing required fields (if any)
+             */
+            missingRequiredFields?: string[];
+            /**
+             * Fields present in response but not in schema (extra fields)
+             */
+            extraFields?: string[];
+            /**
+             * Fields present in both response and schema
+             */
+            matchingFields?: string[];
+            /**
+             * Total number of fields in the response
+             */
+            responseFieldCount: number;
+            /**
+             * Total number of fields expected in schema
+             */
+            schemaFieldCount: number;
+            /**
+             * Whether the structure matches the schema exactly (all required fields present, no extra fields)
+             */
+            structureMatches: boolean;
+        };
+        /**
+         * Retry information (if retries occurred)
+         */
+        retries?: {
+            /**
+             * Number of retry attempts
+             */
+            count: number;
+            /**
+             * Details of each retry attempt
+             */
+            attempts: Array<{
+                /**
+                 * Attempt number (1-based)
+                 */
+                attempt: number;
+                /**
+                 * Timestamp when retry occurred
+                 */
+                timestamp: number;
+                /**
+                 * Error message that triggered the retry
+                 */
+                error: string;
+                /**
+                 * Error type classification (network, http-429, http-5xx, timeout)
+                 */
+                errorType: string;
+                /**
+                 * Delay in milliseconds before this retry
+                 */
+                delayMs: number;
+            }>;
+        };
+        /**
+         * Response repair metadata (when gateway fallback repair was applied)
+         * Indicates that the response was repaired by the gateway before parsing
+         */
+        responseWasFixed?: boolean;
+        /**
+         * Which fix strategy was applied (e.g., 'unwrap-json', 'generate-empty-response')
+         */
+        responseFixApplied?: string;
+        /**
+         * Confidence level of the fix (0-1)
+         */
+        responseFixConfidence?: number;
+        /**
+         * Warnings about the fix (if any)
+         */
+        responseFixWarnings?: string[];
+    };
+}
+/**
+ * Instruction metadata for metadata-driven inference (e.g. output schema hints).
+ */
+export interface InstructionMetadata {
+    /**
+     * Stable instruction identifier when known (e.g. skill or catalog id).
+     */
+    instructionKey: string;
+    /**
+     * Output type (inference type) for parsing responses
+     * Maps to InferenceType from @x12i/outputs-library
+     */
+    outputType?: string;
+    /**
+     * JSON schema for output validation (JSONSchema7 format)
+     */
+    outputSchema?: Record<string, unknown>;
+    /**
+     * Required template variables for this instruction
+     */
+    requiredVariables?: string[];
+    /**
+     * Optional template variables for this instruction
+     */
+    optionalVariables?: string[];
+    /**
+     * Validation rules for the instruction
+     */
+    validationRules?: ValidationRule[];
+    /**
+     * Default output field mapping
+     * Maps output fields to standardized names
+     */
+    defaultOutputMapping?: Record<string, string>;
+    /**
+     * Default parse options for outputs library
+     * Used when outputType is provided
+     */
+    parseOptions?: {
+        question?: string;
+        classes?: string[];
+        [key: string]: unknown;
+    };
+    /**
+     * Version of the instruction
+     */
+    version?: string;
+    [key: string]: unknown;
+}
+/**
+ * Validation rule for instruction metadata
+ */
+export interface ValidationRule {
+    /**
+     * Rule name/identifier
+     */
+    name: string;
+    /**
+     * Rule type (e.g., 'required', 'format', 'range')
+     */
+    type: string;
+    /**
+     * Rule configuration/parameters
+     */
+    config?: Record<string, unknown>;
+    /**
+     * Error message if validation fails
+     */
+    message?: string;
+}
+/**
+ * Response transformation hooks configuration
+ * Allows transforming responses at different stages of processing
+ */
+export interface ResponseTransformationConfig {
+    /**
+     * Transform raw text before parsing
+     * @param rawText - Raw text from LLM response
+     * @param metadata - Request metadata (jobId, agentId, etc.)
+     * @returns Transformed raw text
+     */
+    preParse?: (rawText: string, metadata: any) => string;
+    /**
+     * Transform parsed content after parsing
+     * @param parsed - Parsed content (object/array)
+     * @param metadata - Request metadata
+     * @returns Transformed parsed content
+     */
+    postParse?: (parsed: any, metadata: any) => any;
+    /**
+     * Transform parsed content before validation
+     * @param parsed - Parsed content
+     * @param schema - JSON schema (if available)
+     * @returns Transformed parsed content
+     */
+    preValidate?: (parsed: any, schema: any) => any;
+    /**
+     * Transform validated content after validation
+     * @param validated - Validated content
+     * @param metadata - Request metadata
+     * @returns Transformed validated content
+     */
+    postValidate?: (validated: any, metadata: any) => any;
+}
+export type { LLMRequest, LLMResponse };