@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/flows-actors/services/agents.backend.service.js

@@ -0,0 +1,2095 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import 'reflect-metadata';
+import { injectable, inject } from 'inversify';
+import { z } from 'zod';
+import Bottleneck from 'bottleneck';
+import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
+import { LoggerService } from '../../monitoring/logger/services/logger.service.js';
+import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service.js';
+import { FlowsActorsRegistryService } from './flows-actors-registry.service.js';
+import { ExternalProvidersRegistryBackendService } from '../../external-providers/services/external-providers-registry.backend.service.js';
+import { PromptCompilerBackendService } from './prompt-compiler.backend.service.js';
+import { FlowsActors_Agent_Status, PromptIR_TrustLevel, PromptIR_ContextSourceKind, ErrorType, ErrorCustomMessageReference, } from '@wildo-ai/saas-models';
+import { APPLICATION_ENVIRONMENT, CLIRuntime_AuthMode, CLIRuntime_ModelBindingPlaceholder, CLIRuntime_OutputParserMode, LLMProvider_ExecutionTransportKind, LLMProvider_ExecutionTransportMetadataSchema, LLMProvider_UsageSchema, ExternalProvider_ExchangeProtocol_Kind, ExternalProvider_RateLimitConfigurationSchema, LLMProvider_OperationKey, LLMProvider_MessageRole, } from '@wildo-ai/external-connectors-models';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { google } from '@ai-sdk/google';
+import { createMistral } from '@ai-sdk/mistral';
+import { createPerplexity } from '@ai-sdk/perplexity';
+import { createXai } from '@ai-sdk/xai';
+import { generateText, streamText, generateObject } from 'ai';
+import { CLIRuntimeRunnerError, executeCLIRuntimeCommand, resolveCLIRuntimeWorkingDirectory, } from '../../flows-actors/utils/cli-runtime-runner.backend.utils.js';
+import { assessCLIRuntimeOperationSupport, getCLIRuntimeOperationBinding, getEffectiveCLIRuntimeOutputParserMode, } from '../../flows-actors/utils/cli-runtime-operation-support.backend.utils.js';
+const DEFAULT_MAX_STRUCTURED_DATA_FIELD_ALLOWED = 99;
+const CLIRUNTIME_BASE_INHERITED_ENV_KEYS = [
+    'PATH',
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'SHELL',
+    'TMPDIR',
+    'TMP',
+    'TEMP',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+    'TERM',
+    'COLORTERM',
+    'NO_COLOR',
+    'FORCE_COLOR',
+    'CI',
+    'XDG_CONFIG_HOME',
+    'XDG_CACHE_HOME',
+    'XDG_STATE_HOME',
+    'XDG_RUNTIME_DIR',
+    'SSL_CERT_FILE',
+    'SSL_CERT_DIR',
+    'HTTP_PROXY',
+    'HTTPS_PROXY',
+    'NO_PROXY',
+];
+let AgentsBackendService = class AgentsBackendService {
+    logger;
+    errorBuilder;
+    flowsActorsRegistry;
+    externalProvidersRegistry;
+    promptCompiler;
+    logDebug;
+    // Bottleneck instances per provider for rate limiting LLM calls
+    bottleneckInstances = new Map();
+    constructor(logger, errorBuilder, flowsActorsRegistry, externalProvidersRegistry, promptCompiler) {
+        this.logger = logger;
+        this.errorBuilder = errorBuilder;
+        this.flowsActorsRegistry = flowsActorsRegistry;
+        this.externalProvidersRegistry = externalProvidersRegistry;
+        this.promptCompiler = promptCompiler;
+        this.logDebug = this.logger.debugByType('AgentsBackend');
+        this.logger.setDebugTypeLogging('AgentsBackend', false);
+        this.logDebug('Agents backend service created');
+    }
+    // ================================
+    // Structured Data Chunking Utilities
+    // ================================
+    mergeChunkedObjects(chunks) {
+        if (chunks.length === 0) {
+            return {};
+        }
+        if (chunks.length === 1) {
+            return chunks[0];
+        }
+        // Deep merge nested objects instead of shallow merge
+        const result = { ...chunks[0] };
+        for (let i = 1; i < chunks.length; i++) {
+            const chunk = chunks[i];
+            for (const key in chunk) {
+                if (chunk.hasOwnProperty(key)) {
+                    const chunkValue = chunk[key];
+                    const resultValue = result[key];
+                    // If both values are plain objects, deep merge them
+                    if (chunkValue !== null &&
+                        typeof chunkValue === 'object' &&
+                        !Array.isArray(chunkValue) &&
+                        resultValue !== null &&
+                        typeof resultValue === 'object' &&
+                        !Array.isArray(resultValue) &&
+                        resultValue.constructor === Object &&
+                        chunkValue.constructor === Object) {
+                        result[key] = this.mergeChunkedObjects([resultValue, chunkValue]);
+                    }
+                    else {
+                        // Otherwise, use the chunk value (last one wins for conflicts)
+                        result[key] = chunkValue;
+                    }
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Count leaf fields in a Zod schema recursively
+     * Leaf fields are non-object fields (strings, numbers, enums, etc.)
+     */
+    countLeafFields(schema) {
+        if (!schema || typeof schema !== 'object' || !('_def' in schema)) {
+            return 1; // Treat as a single leaf if not a valid schema
+        }
+        const def = schema._def;
+        const typeName = def.typeName || def.type;
+        // Handle wrappers - unwrap and count inner type
+        if (typeName === 'ZodOptional' || typeName === 'optional' ||
+            typeName === 'ZodNullable' || typeName === 'nullable' ||
+            typeName === 'ZodDefault' || typeName === 'default') {
+            return this.countLeafFields(def.innerType || def.wrapped);
+        }
+        if (typeName === 'ZodEffects' || typeName === 'effects' || typeName === 'transform' || typeName === 'refine') {
+            return this.countLeafFields(def.schema || def.innerType);
+        }
+        // Handle objects - count all nested leaf fields
+        if (typeName === 'ZodObject' || typeName === 'object') {
+            const shape = typeof def.shape === 'function' ? def.shape() : def.shape;
+            if (!shape)
+                return 1;
+            let count = 0;
+            for (const key of Object.keys(shape)) {
+                count += this.countLeafFields(shape[key]);
+            }
+            return count;
+        }
+        // Handle arrays - count element type
+        if (typeName === 'ZodArray' || typeName === 'array') {
+            return this.countLeafFields(def.element || def.type);
+        }
+        // Handle unions - count max of options
+        if (typeName === 'ZodUnion' || typeName === 'union' ||
+            typeName === 'ZodDiscriminatedUnion' || typeName === 'discriminatedUnion') {
+            const options = def.options || [];
+            let maxCount = 0;
+            for (const opt of options) {
+                maxCount = Math.max(maxCount, this.countLeafFields(opt));
+            }
+            return maxCount;
+        }
+        // All other types are leaf fields
+        return 1;
+    }
+    /**
+     * Flatten a nested Zod object schema to dot-notation paths with their leaf schemas
+     * e.g., { a: { b: z.string() } } -> [{ path: ['a', 'b'], schema: z.string() }]
+     */
+    flattenZodSchema(schema, basePath = []) {
+        if (!schema || typeof schema !== 'object' || !('_def' in schema)) {
+            return [{ path: basePath, schema }];
+        }
+        const def = schema._def;
+        const typeName = def.typeName || def.type;
+        // Handle wrappers - preserve wrapper but flatten inner
+        if (typeName === 'ZodOptional' || typeName === 'optional' ||
+            typeName === 'ZodNullable' || typeName === 'nullable' ||
+            typeName === 'ZodDefault' || typeName === 'default' ||
+            typeName === 'ZodEffects' || typeName === 'effects' || typeName === 'transform' || typeName === 'refine') {
+            // For wrappers, we keep the whole schema as a leaf
+            return [{ path: basePath, schema }];
+        }
+        // Handle objects - flatten recursively
+        if (typeName === 'ZodObject' || typeName === 'object') {
+            const shape = typeof def.shape === 'function' ? def.shape() : def.shape;
+            if (!shape)
+                return [{ path: basePath, schema }];
+            const result = [];
+            for (const key of Object.keys(shape)) {
+                const childFlattened = this.flattenZodSchema(shape[key], [...basePath, key]);
+                result.push(...childFlattened);
+            }
+            return result;
+        }
+        // All other types are leaf fields
+        return [{ path: basePath, schema }];
+    }
+    /**
+     * Build a nested Zod schema from flattened paths
+     */
+    buildNestedSchemaFromPaths(paths) {
+        const nested = {};
+        for (const { path, schema } of paths) {
+            let current = nested;
+            for (let i = 0; i < path.length - 1; i++) {
+                const part = path[i];
+                if (!current[part]) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+            const finalPart = path[path.length - 1];
+            current[finalPart] = schema;
+        }
+        // Recursively convert nested objects to Zod objects
+        const convertToZod = (obj) => {
+            const shape = {};
+            for (const [key, value] of Object.entries(obj)) {
+                if (value && typeof value === 'object' && '_def' in value) {
+                    // It's a Zod schema
+                    shape[key] = value;
+                }
+                else if (typeof value === 'object' && value !== null) {
+                    // It's a nested object, convert recursively
+                    shape[key] = convertToZod(value);
+                }
+            }
+            return z.object(shape);
+        };
+        return convertToZod(nested);
+    }
+    chunkZodSchema(schema, maxFields) {
+        if (!schema || typeof schema !== 'object' || !('_def' in schema)) {
+            return [schema];
+        }
+        const def = schema._def;
+        const typeName = def.typeName || def.type;
+        // Only chunk ZodObject schemas
+        if (typeName !== 'ZodObject' && typeName !== 'object') {
+            return [schema];
+        }
+        if (!def.shape) {
+            return [schema];
+        }
+        // Count total leaf fields
+        const totalLeafFields = this.countLeafFields(schema);
+        this.logDebug('Checking if schema needs chunking', {
+            totalLeafFields,
+            maxFields,
+            needsChunking: totalLeafFields > maxFields,
+        });
+        if (totalLeafFields <= maxFields) {
+            return [schema];
+        }
+        // Flatten the schema to get all leaf paths
+        const flattenedPaths = this.flattenZodSchema(schema);
+        this.logDebug('Chunking nested schema by leaf fields', {
+            totalLeafFields,
+            maxFields,
+            flattenedPathCount: flattenedPaths.length,
+        });
+        // Use 95% of maxFields to leave buffer
+        const chunkSize = Math.floor(maxFields * 0.95);
+        const schemaChunks = [];
+        for (let i = 0; i < flattenedPaths.length; i += chunkSize) {
+            const chunkPaths = flattenedPaths.slice(i, i + chunkSize);
+            const chunkSchema = this.buildNestedSchemaFromPaths(chunkPaths);
+            schemaChunks.push(chunkSchema);
+        }
+        this.logDebug('Schema chunked', {
+            totalChunks: schemaChunks.length,
+            pathsPerChunk: chunkSize,
+        });
+        return schemaChunks;
+    }
+    // ================================
+    // Bottleneck Rate Limiting
+    // ================================
+    getBottleneckForProvider(providerRef, protocolKind = ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER) {
+        const limiterKey = `${providerRef}:${protocolKind}`;
+        if (this.bottleneckInstances.has(limiterKey)) {
+            const existingLimiter = this.bottleneckInstances.get(limiterKey);
+            this.logDebug('Returning existing bottleneck instance for provider', { providerRef, protocolKind });
+            return existingLimiter;
+        }
+        this.logDebug('Creating new bottleneck instance for provider', { providerRef, protocolKind });
+        const config = this.externalProvidersRegistry.getProviderConfiguration(providerRef, protocolKind);
+        const rateLimitConfig = config && 'rateLimitConfig' in config && config.rateLimitConfig
+            ? ExternalProvider_RateLimitConfigurationSchema.parse(config.rateLimitConfig)
+            : ExternalProvider_RateLimitConfigurationSchema.parse({});
+        // Create bottleneck options
+        const bottleneckOptions = {
+            maxConcurrent: rateLimitConfig.maxConcurrent ?? 10,
+            minTime: rateLimitConfig.minTime,
+            reservoir: rateLimitConfig.reservoir,
+            reservoirRefreshInterval: rateLimitConfig.reservoirRefreshInterval,
+            reservoirRefreshAmount: rateLimitConfig.reservoirRefreshAmount,
+        };
+        // Remove undefined values
+        Object.keys(bottleneckOptions).forEach(key => {
+            if (bottleneckOptions[key] === undefined) {
+                delete bottleneckOptions[key];
+            }
+        });
+        // Create and store bottleneck instance
+        const limiter = new Bottleneck(bottleneckOptions);
+        // Add event listeners for rate limiting visibility
+        this.setupBottleneckEventListeners(limiter, limiterKey);
+        this.bottleneckInstances.set(limiterKey, limiter);
+        this.logDebug('Bottleneck instance created for provider', {
+            providerRef,
+            protocolKind,
+            maxConcurrent: bottleneckOptions.maxConcurrent,
+            minTime: bottleneckOptions.minTime,
+            reservoir: bottleneckOptions.reservoir
+        });
+        return limiter;
+    }
+    /**
+     * Setup event listeners on bottleneck instance to track rate limiting behavior
+     */
+    setupBottleneckEventListeners(limiter, providerRef) {
+        // Track when jobs are queued (delayed due to rate limiting)
+        limiter.on('queued', (info) => {
+            const jobId = info?.options?.id || 'unknown';
+            this.logDebug('API call queued (rate limited - will be delayed)', {
+                providerRef,
+                jobId,
+                queued: limiter.queued(),
+                running: limiter.running(),
+                done: limiter.done(),
+            });
+        });
+        // Track when jobs start running (immediate or after queuing)
+        limiter.on('executing', (info) => {
+            const jobId = info?.options?.id || 'unknown';
+            this.logDebug('API call executing (running now)', {
+                providerRef,
+                jobId,
+                queued: limiter.queued(),
+                running: limiter.running(),
+                done: limiter.done(),
+            });
+        });
+        // Track when jobs complete
+        limiter.on('done', (info) => {
+            const jobId = info?.options?.id || 'unknown';
+            this.logDebug('API call completed through rate limiter', {
+                providerRef,
+                jobId,
+                queued: limiter.queued(),
+                running: limiter.running(),
+                done: limiter.done(),
+            });
+        });
+        // Track when jobs are dropped (queue full or other reasons)
+        limiter.on('dropped', (info) => {
+            const jobId = info?.options?.id || 'unknown';
+            this.logger.warn('API call dropped by rate limiter (queue full or limit exceeded)', {
+                providerRef,
+                jobId,
+                queued: limiter.queued(),
+                running: limiter.running(),
+            });
+        });
+        // Track when reservoir is depleted
+        limiter.on('depleted', () => {
+            this.logDebug('Rate limiter reservoir depleted (waiting for refresh)', {
+                providerRef,
+                queued: limiter.queued(),
+                running: limiter.running(),
+            });
+        });
+        // Track errors in the limiter
+        limiter.on('error', (error) => {
+            this.logger.error('Rate limiter error', {
+                providerRef,
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined,
+            });
+        });
+    }
+    // ================================
+    // Agent Invocation
+    // ================================
+    async invokeAgent(request) {
+        const startTime = Date.now();
+        this.logDebug('Invoking agent', { agentRef: request.agentRef, hasInput: !!request.input, hasExecutionContext: !!request.executionContext });
+        const agent = this.flowsActorsRegistry.getAgentOrThrow(request.agentRef);
+        this.validateAgentStatus(agent);
+        const result = await this.executeAgent(agent, request);
+        const executionTime = Date.now() - startTime;
+        const finishedAt = new Date().toISOString();
+        const executionContext = {
+            ...request.executionContext,
+            callDuration: executionTime,
+            executionTime,
+            finishedAt,
+            ...(result.usage ? { usage: LLMProvider_UsageSchema.parse(result.usage) } : {}),
+            ...(result.transport ? { transport: LLMProvider_ExecutionTransportMetadataSchema.parse(result.transport) } : {}),
+        };
+        this.logDebug('Agent invocation completed', { agentRef: request.agentRef, executionTime, hasOutput: !!result.output });
+        return {
+            ...request,
+            output: this.normalizeOperationOutput(agent.config.operationKey, result.output),
+            executionContext,
+        };
+    }
+    /**
+     * Normalize executor outputs to the shared transport-neutral LLM contract.
+     *
+     * The current execution helpers naturally produce provider/raw payloads such as
+     * plain strings or plain objects. Downstream consumers, however, already rely on
+     * the wrapped shared schemas (`{ text }`, `{ object }`, `{ message }`, etc.).
+     * Centralizing the normalization here fixes the runtime boundary once instead of
+     * forcing every caller to guess the provider-shaped payload.
+     */
+    normalizeOperationOutput(operationKey, output) {
+        switch (operationKey) {
+            case LLMProvider_OperationKey.GENERATE_TEXT:
+            case LLMProvider_OperationKey.GENERATE_TEXT_THINKING:
+                if (this.isRecord(output) && typeof output.text === 'string') {
+                    return output;
+                }
+                return { text: typeof output === 'string' ? output : JSON.stringify(output ?? '') };
+            case LLMProvider_OperationKey.CHAT_COMPLETION:
+            case LLMProvider_OperationKey.CHAT_COMPLETION_THINKING:
+            case LLMProvider_OperationKey.CHAT_MULTIMODAL:
+            case LLMProvider_OperationKey.CHAT_MULTIMODAL_THINKING:
+                if (this.isRecord(output) && this.isRecord(output.message)) {
+                    return output;
+                }
+                return {
+                    message: {
+                        role: LLMProvider_MessageRole.ASSISTANT,
+                        content: typeof output === 'string' ? output : JSON.stringify(output ?? ''),
+                    },
+                };
+            case LLMProvider_OperationKey.GENERATE_STRUCTURED:
+            case LLMProvider_OperationKey.GENERATE_STRUCTURED_THINKING:
+                if (this.isRecord(output) && 'object' in output) {
+                    return output;
+                }
+                return { object: output };
+            case LLMProvider_OperationKey.STREAM_TEXT:
+            case LLMProvider_OperationKey.STREAM_TEXT_THINKING:
+                if (this.isRecord(output) && typeof output.textDelta === 'string') {
+                    return output;
+                }
+                return { textDelta: typeof output === 'string' ? output : JSON.stringify(output ?? '') };
+            case LLMProvider_OperationKey.STREAM_STRUCTURED:
+            case LLMProvider_OperationKey.STREAM_STRUCTURED_THINKING:
+                if (this.isRecord(output) && ('object' in output || 'partialObject' in output)) {
+                    return output;
+                }
+                return { object: output };
+            default:
+                return output;
+        }
+    }
+    isRecord(value) {
+        return typeof value === 'object' && value !== null;
+    }
+    /**
+     * Execute agent with LLM provider using @ai-sdk
+     */
+    async executeAgent(agent, request) {
+        this.logDebug('Executing agent', {
+            agentRef: agent.ref,
+            operationKey: agent.config.operationKey,
+            providerRef: agent.config.providerRef,
+            model: agent.config.model,
+            executionProfileRef: agent.config.executionProfileRef,
+        });
+        const execution = this.resolveAgentExecution(agent);
+        const prompts = await this.buildExecutionPrompts(agent, request);
+        if (execution.transport === 'cli') {
+            return this.executeAgentViaCLI(agent, request, execution, prompts);
+        }
+        return this.executeAgentViaApi(agent, request, execution, prompts);
+    }
+    resolveAgentExecution(agent) {
+        const providerRef = agent.config.providerRef;
+        const operationKey = agent.config.operationKey;
+        const semanticProtocolKind = ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER;
+        if (!this.externalProvidersRegistry.isProviderEnabled(providerRef, semanticProtocolKind)) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: {
+                    providerRef,
+                    protocolKind: semanticProtocolKind,
+                    message: 'Provider/protocol is not enabled in application configuration'
+                }
+            });
+        }
+        const llmProtocol = this.externalProvidersRegistry.getCachedProtocol(providerRef, semanticProtocolKind);
+        if (!llmProtocol) {
+            throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+                customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+                context: {
+                    providerRef,
+                    message: 'Provider not found or LLM protocol not loaded'
+                }
+            });
+        }
+        if (!('operations' in llmProtocol)) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: {
+                    providerRef,
+                    message: 'Provider does not support LLM protocol operations'
+                }
+            });
+        }
+        if (!llmProtocol.operations[operationKey]) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: {
+                    providerRef,
+                    operationKey,
+                    message: 'Operation not supported by provider'
+                }
+            });
+        }
+        const llmProviderConfig = this.externalProvidersRegistry.getProviderConfiguration(providerRef, semanticProtocolKind);
+        const executionProfileRef = agent.config.executionProfileRef;
+        if (!executionProfileRef) {
+            return {
+                transport: 'api',
+                providerRef,
+                operationKey,
+                llmProviderConfig,
+            };
+        }
+        const executionProtocolKind = ExternalProvider_ExchangeProtocol_Kind.CLI_RUNTIME;
+        if (!this.externalProvidersRegistry.isProviderEnabled(providerRef, executionProtocolKind)) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    providerRef,
+                    protocolKind: executionProtocolKind,
+                    executionProfileRef,
+                    message: 'CLI runtime protocol is not enabled for the selected provider'
+                }
+            });
+        }
+        const cliRuntimeConfig = this.externalProvidersRegistry.getCLIRuntimeConfiguration(providerRef);
+        const cliRuntimeProfile = this.externalProvidersRegistry.getCachedCLIRuntimeProfile(providerRef);
+        const cliExecutionProfile = this.externalProvidersRegistry.getCLIRuntimeExecutionProfile(providerRef, executionProfileRef);
+        if (!cliRuntimeConfig || !cliRuntimeProfile || !cliExecutionProfile) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    providerRef,
+                    executionProfileRef,
+                    message: 'CLI runtime protocol metadata or execution profile not found in provider configuration'
+                }
+            });
+        }
+        const execution = {
+            transport: 'cli',
+            providerRef,
+            operationKey,
+            executionProfileRef,
+            llmProviderConfig,
+            cliRuntimeConfig,
+            cliRuntimeProfile,
+            cliExecutionProfile,
+        };
+        this.validateCLIRuntimeDefinitionSupport(execution, agent.config.model);
+        return execution;
+    }
+    async buildExecutionPrompts(agent, request) {
+        const rawInstructions = this.extractRawInstructions(request.input);
+        if (agent.promptSpec) {
+            const compiled = await this.buildCompiledPrompts(agent, request, rawInstructions);
+            return {
+                systemPrompt: compiled.systemPrompt,
+                instructions: compiled.userPrompt,
+            };
+        }
+        return {
+            systemPrompt: this.buildSystemPrompt(agent, request),
+            instructions: rawInstructions,
+        };
+    }
+    extractRawInstructions(input) {
+        if (typeof input === 'object' && input !== null) {
+            if ('prompt' in input && typeof input.prompt === 'string') {
+                return input.prompt;
+            }
+            if ('messages' in input && Array.isArray(input.messages)) {
+                const userMessages = input.messages.filter((message) => message.role === 'user');
+                return userMessages
+                    .map((message) => typeof message.content === 'string' ? message.content : JSON.stringify(message.content))
+                    .join('\n');
+            }
+            return JSON.stringify(input);
+        }
+        return String(input);
+    }
+    async executeAgentViaApi(agent, request, execution, prompts) {
+        const apiKey = this.externalProvidersRegistry.getProviderApiKey(execution.providerRef, ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER);
+        if (!apiKey) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    providerRef: execution.providerRef,
+                    protocolKind: ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER,
+                    message: 'API key not found for provider. Please configure the provider secrets in application configuration.'
+                }
+            });
+        }
+        const aiProvider = this.getAIProvider(execution.providerRef, apiKey);
+        if (!aiProvider) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: {
+                    providerRef: execution.providerRef,
+                    message: 'AI SDK provider not available'
+                }
+            });
+        }
+        const limiter = this.getBottleneckForProvider(execution.providerRef, ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER);
+        const jobId = `${agent.ref}-api-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+        this.logDebug('Scheduling API call through rate limiter', {
+            agentRef: agent.ref,
+            providerRef: execution.providerRef,
+            operationKey: execution.operationKey,
+            model: agent.config.model,
+            jobId,
+            currentQueueSize: limiter.queued(),
+            currentRunning: limiter.running(),
+            usesPromptCompiler: !!agent.promptSpec,
+        });
+        const result = await limiter.schedule({ id: jobId }, () => this.executeOperation({
+            providerClient: aiProvider,
+            providerRef: execution.providerRef,
+            config: agent.config,
+            operationKey: execution.operationKey,
+            systemPrompt: prompts.systemPrompt,
+            instructions: prompts.instructions,
+            input: request.input,
+            llmProviderConfig: execution.llmProviderConfig,
+        }));
+        return {
+            ...result,
+            transport: {
+                kind: LLMProvider_ExecutionTransportKind.API,
+                protocolKind: ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER,
+                providerRef: execution.providerRef,
+                model: agent.config.model,
+            },
+        };
+    }
+    async executeAgentViaCLI(agent, request, execution, prompts) {
+        const limiter = this.getBottleneckForProvider(execution.providerRef, ExternalProvider_ExchangeProtocol_Kind.CLI_RUNTIME);
+        const jobId = `${agent.ref}-cli-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+        this.logDebug('Scheduling CLI execution through rate limiter', {
+            agentRef: agent.ref,
+            providerRef: execution.providerRef,
+            operationKey: execution.operationKey,
+            executionProfileRef: execution.executionProfileRef,
+            jobId,
+            currentQueueSize: limiter.queued(),
+            currentRunning: limiter.running(),
+        });
+        return limiter.schedule({ id: jobId }, async () => {
+            this.validateCLIRuntimeDefinitionSupport(execution, agent.config.model);
+            this.validateCLIRuntimePolicy(execution);
+            const cliCommandResult = await this.runCLIRuntimeCommand(execution, agent.config.model, this.buildCLIRuntimePromptInput(execution, prompts, request.input));
+            return {
+                output: this.parseCLIOperationOutput(execution, cliCommandResult.stdout, request.input),
+                transport: this.buildCLITransportMetadata(execution, cliCommandResult),
+            };
+        });
+    }
+    validateCLIOperationSupport(execution) {
+        const support = assessCLIRuntimeOperationSupport(execution.cliRuntimeProfile, execution.cliExecutionProfile, execution.operationKey);
+        if (!support.supported) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    providerRef: execution.providerRef,
+                    executionProfileRef: execution.executionProfileRef,
+                    operationKey: execution.operationKey,
+                    supportedOperationKeys: execution.cliRuntimeProfile.supportedOperationKeys,
+                    message: support.message ?? 'CLI runtime profile does not declare support for the selected semantic LLM operation',
+                }
+            });
+        }
+    }
+    validateCLIModelSupport(execution, requestedModel) {
+        if (execution.cliRuntimeProfile.supportedModels.includes(requestedModel)) {
+            return;
+        }
+        throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+            customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+            context: {
+                providerRef: execution.providerRef,
+                executionProfileRef: execution.executionProfileRef,
+                model: requestedModel,
+                supportedModels: execution.cliRuntimeProfile.supportedModels,
+                message: 'CLI runtime profile does not declare support for the selected semantic model'
+            }
+        });
+    }
+    validateCLIRuntimeDefinitionSupport(execution, requestedModel) {
+        this.validateCLIOperationSupport(execution);
+        this.validateCLIModelSupport(execution, requestedModel);
+    }
+    /**
+     * Get AI SDK provider client configured with API key
+     * Returns a provider client that has a .languageModel() method
+     */
+    getAIProvider(providerRef, apiKey) {
+        try {
+            let providerClient;
+            switch (providerRef) {
+                case "openai":
+                    providerClient = createOpenAI({ apiKey });
+                    break;
+                case "anthropic":
+                    providerClient = createAnthropic({ apiKey });
+                    break;
+                case "google":
+                    // Google provider might use a different pattern - try google() directly
+                    providerClient = google({ apiKey });
+                    // If google() returns a model directly, wrap it
+                    if (providerClient && !providerClient.languageModel && typeof providerClient !== 'function') {
+                        // google() might return a model directly, so we need to handle it differently
+                        // For now, try to use it as-is and handle in executeOperation
+                        this.logDebug('Google provider returned model directly', {
+                            hasLanguageModel: typeof providerClient?.languageModel === 'function',
+                            keys: Object.keys(providerClient).slice(0, 10)
+                        });
+                    }
+                    break;
+                case "mistral":
+                    providerClient = createMistral({ apiKey });
+                    break;
+                case "perplexity":
+                    providerClient = createPerplexity({ apiKey });
+                    break;
+                case "grok":
+                    providerClient = createXai({ apiKey });
+                    break;
+                default:
+                    return null;
+            }
+            return providerClient;
+        }
+        catch (error) {
+            this.logger.error('Failed to initialize AI provider', { providerRef, error: error instanceof Error ? error.message : String(error) });
+            throw error;
+        }
+    }
+    validateCLIRuntimePolicy(execution) {
+        const applicationEnv = (process.env.APPLICATION_ENV || APPLICATION_ENVIRONMENT.DEVELOPMENT);
+        const platformEnvironmentId = process.env.PLATFORM_ENVIRONMENT_ID;
+        const { cliExecutionProfile } = execution;
+        if (!cliExecutionProfile.allowedApplicationEnvironments.includes(applicationEnv)) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    providerRef: execution.providerRef,
+                    executionProfileRef: execution.executionProfileRef,
+                    applicationEnv,
+                    allowedApplicationEnvironments: cliExecutionProfile.allowedApplicationEnvironments,
+                    message: 'CLI runtime execution profile is not allowed in the current application environment'
+                }
+            });
+        }
+        if (cliExecutionProfile.allowedPlatformEnvironmentIds?.length
+            && (!platformEnvironmentId || !cliExecutionProfile.allowedPlatformEnvironmentIds.includes(platformEnvironmentId))) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    providerRef: execution.providerRef,
+                    executionProfileRef: execution.executionProfileRef,
+                    platformEnvironmentId,
+                    allowedPlatformEnvironmentIds: cliExecutionProfile.allowedPlatformEnvironmentIds,
+                    message: 'CLI runtime execution profile is not allowed in the current platform environment'
+                }
+            });
+        }
+    }
+    buildCLIPromptInput(prompts) {
+        if (!prompts.systemPrompt.trim()) {
+            return prompts.instructions;
+        }
+        return [
+            '[SYSTEM]',
+            prompts.systemPrompt,
+            '',
+            '[USER]',
+            prompts.instructions,
+        ].join('\n');
+    }
+    /**
+     * CLI runtimes get one synthesized task payload. Structured generation appends
+     * explicit JSON-shape instructions here instead of leaking schemas through
+     * argv, then validates the returned object against the requested Zod schema
+     * after parsing.
+     */
+    buildCLIRuntimePromptInput(execution, prompts, input) {
+        const basePrompt = this.buildCLIPromptInput(prompts);
+        if (execution.operationKey !== LLMProvider_OperationKey.GENERATE_STRUCTURED) {
+            return basePrompt;
+        }
+        const jsonSchema = this.serializeCLIRuntimeStructuredSchema(execution, input);
+        return [
+            basePrompt,
+            '',
+            '[STRUCTURED_OUTPUT_REQUIREMENTS]',
+            'Return only a valid JSON object.',
+            'Do not wrap the JSON in markdown fences or commentary.',
+            'The JSON object must conform to this JSON Schema:',
+            jsonSchema,
+        ].join('\n');
+    }
+    async runCLIRuntimeCommand(execution, requestedModel, promptPayload) {
+        const invocation = this.resolveCLIRuntimeInvocation(execution, requestedModel, promptPayload);
+        let cwd;
+        try {
+            cwd = resolveCLIRuntimeWorkingDirectory(execution.cliExecutionProfile);
+        }
+        catch (error) {
+            if (error instanceof CLIRuntimeRunnerError) {
+                throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                    context: {
+                        providerRef: execution.providerRef,
+                        executionProfileRef: execution.executionProfileRef,
+                        ...error.details,
+                        message: error.message,
+                    }
+                });
+            }
+            throw error;
+        }
+        const timeoutMs = execution.cliExecutionProfile.timeoutMs ?? 120_000;
+        try {
+            const result = await executeCLIRuntimeCommand({
+                command: invocation.command,
+                args: invocation.args,
+                cwd,
+                env: invocation.env,
+                stdinPayload: invocation.stdinPayload,
+                timeoutMs,
+            });
+            return {
+                ...result,
+                requestedModel: invocation.requestedModel,
+                resolvedModel: invocation.resolvedModel,
+                effectiveOutputParserMode: invocation.effectiveOutputParserMode,
+                workingDirectory: cwd,
+            };
+        }
+        catch (error) {
+            if (error instanceof CLIRuntimeRunnerError) {
+                const errorType = this.getCLIRuntimeRunnerErrorType(error);
+                throw this.errorBuilder.buildError(errorType, undefined, {
+                    customMessageReference: errorType === ErrorType.CONFIGURATION
+                        ? ErrorCustomMessageReference.CONFIGURATION
+                        : ErrorCustomMessageReference.INTERNAL,
+                    context: {
+                        providerRef: execution.providerRef,
+                        executionProfileRef: execution.executionProfileRef,
+                        ...error.details,
+                        message: error.message,
+                    }
+                });
+            }
+            throw error;
+        }
+    }
+    getCLIRuntimeRunnerErrorType(error) {
+        if (error.message.startsWith('Failed to start CLI runtime command')) {
+            return ErrorType.CONFIGURATION;
+        }
+        return ErrorType.INTERNAL;
+    }
+    buildCLITransportMetadata(execution, commandResult) {
+        const artifacts = [];
+        if (commandResult.stdout.length > 0) {
+            artifacts.push({
+                kind: 'stdout',
+                byteLength: Buffer.byteLength(commandResult.stdout),
+            });
+        }
+        if (commandResult.stderr.length > 0) {
+            artifacts.push({
+                kind: 'stderr',
+                byteLength: Buffer.byteLength(commandResult.stderr),
+            });
+        }
+        return {
+            kind: LLMProvider_ExecutionTransportKind.CLI,
+            protocolKind: ExternalProvider_ExchangeProtocol_Kind.CLI_RUNTIME,
+            providerRef: execution.providerRef,
+            model: commandResult.requestedModel,
+            resolvedModel: commandResult.resolvedModel,
+            executionProfileRef: execution.executionProfileRef,
+            runnerHost: execution.cliExecutionProfile.runnerHost,
+            outputParserMode: commandResult.effectiveOutputParserMode,
+            command: execution.cliExecutionProfile.command,
+            workingDirectory: commandResult.workingDirectory,
+            exitCode: commandResult.exitCode,
+            signal: commandResult.signal,
+            artifacts: artifacts.length > 0 ? artifacts : undefined,
+        };
+    }
+    resolveCLIRuntimeInvocation(execution, requestedModel, promptPayload) {
+        const resolvedModel = this.resolveCLIRuntimeModel(execution, requestedModel);
+        const effectiveOutputParserMode = getEffectiveCLIRuntimeOutputParserMode(execution.cliRuntimeProfile, execution.cliExecutionProfile, execution.operationKey);
+        return {
+            command: execution.cliExecutionProfile.command,
+            args: this.buildCLIRuntimeCommandArgs(execution, resolvedModel),
+            env: this.buildCLIRuntimeEnvironment(execution, resolvedModel),
+            stdinPayload: promptPayload,
+            requestedModel,
+            resolvedModel,
+            effectiveOutputParserMode,
+        };
+    }
+    /**
+     * CLI-backed agents still select their semantic model on `agent.config.model`.
+     * The provider-owned CLI runtime profile defines how that semantic model is
+     * translated into CLI arguments and/or environment variables.
+     */
+    resolveCLIRuntimeModel(execution, requestedModel) {
+        const modelBinding = execution.cliRuntimeProfile.modelBinding;
+        if (!modelBinding) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    providerRef: execution.providerRef,
+                    executionProfileRef: execution.executionProfileRef,
+                    requestedModel,
+                    message: 'CLI runtime profile is missing modelBinding, so semantic model selection cannot be preserved'
+                }
+            });
+        }
+        return modelBinding.modelValueOverrides?.[requestedModel] ?? requestedModel;
+    }
+    buildCLIRuntimeCommandArgs(execution, resolvedModel) {
+        const baseArgs = execution.cliExecutionProfile.args ? [...execution.cliExecutionProfile.args] : [];
+        const argumentTemplate = execution.cliRuntimeProfile.modelBinding?.argumentTemplate;
+        const operationArgumentTemplate = getCLIRuntimeOperationBinding(execution.cliRuntimeProfile, execution.operationKey)?.argumentTemplate;
+        const templateValues = this.buildCLIRuntimeTemplateValues(resolvedModel);
+        if (argumentTemplate?.length) {
+            baseArgs.push(...argumentTemplate.map((part) => this.applyCLIRuntimeTemplateValues(part, templateValues)));
+        }
+        if (operationArgumentTemplate?.length) {
+            baseArgs.push(...operationArgumentTemplate.map((part) => this.applyCLIRuntimeTemplateValues(part, templateValues)));
+        }
+        return baseArgs.length > 0 ? baseArgs : undefined;
+    }
+    buildCLIRuntimeEnvironment(execution, resolvedModel) {
+        const env = this.buildCLIRuntimeBaseEnvironment(execution.cliExecutionProfile);
+        const { cliExecutionProfile } = execution;
+        const templateValues = this.buildCLIRuntimeTemplateValues(resolvedModel);
+        if (cliExecutionProfile.authMode === CLIRuntime_AuthMode.SECRET_REF_ENV_INJECTION) {
+            if (!cliExecutionProfile.secretEnvVarName) {
+                throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                    context: {
+                        providerRef: execution.providerRef,
+                        executionProfileRef: execution.executionProfileRef,
+                        message: 'CLI runtime execution profile is missing secretEnvVarName'
+                    }
+                });
+            }
+            const secret = this.externalProvidersRegistry.getCLIRuntimeExecutionProfileSecret(execution.providerRef, execution.executionProfileRef);
+            if (!secret) {
+                throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                    context: {
+                        providerRef: execution.providerRef,
+                        executionProfileRef: execution.executionProfileRef,
+                        message: 'CLI runtime execution profile secret could not be resolved'
+                    }
+                });
+            }
+            env[cliExecutionProfile.secretEnvVarName] = secret;
+        }
+        for (const [envKey, envValueTemplate] of Object.entries(execution.cliRuntimeProfile.modelBinding?.environmentVariables ?? {})) {
+            env[envKey] = this.applyCLIRuntimeTemplateValues(envValueTemplate, templateValues);
+        }
+        for (const [envKey, envValueTemplate] of Object.entries(getCLIRuntimeOperationBinding(execution.cliRuntimeProfile, execution.operationKey)?.environmentVariables ?? {})) {
+            env[envKey] = this.applyCLIRuntimeTemplateValues(envValueTemplate, templateValues);
+        }
+        return env;
+    }
+    buildCLIRuntimeBaseEnvironment(profile) {
+        const env = {};
+        const inheritedKeys = new Set([
+            ...CLIRUNTIME_BASE_INHERITED_ENV_KEYS,
+            ...(profile.inheritedEnvironmentVariables ?? []),
+        ]);
+        for (const envKey of inheritedKeys) {
+            const envValue = process.env[envKey];
+            if (envValue !== undefined) {
+                env[envKey] = envValue;
+            }
+        }
+        return env;
+    }
+    buildCLIRuntimeTemplateValues(resolvedModel) {
+        return {
+            [CLIRuntime_ModelBindingPlaceholder]: resolvedModel,
+        };
+    }
+    applyCLIRuntimeTemplateValues(template, values) {
+        let resolved = template;
+        for (const [placeholder, value] of Object.entries(values)) {
+            resolved = resolved.replaceAll(placeholder, value);
+        }
+        return resolved;
+    }
+    /**
+     * Structured CLI execution still needs a real JSON Schema boundary even though
+     * the CLI prompt travels over stdin. We serialize the requested Zod schema
+     * once so the synthesized stdin payload can describe the contract precisely
+     * and the parsed response can be validated against the same shape.
+     */
+    serializeCLIRuntimeStructuredSchema(execution, input) {
+        try {
+            return JSON.stringify(z.toJSONSchema(this.getCLIRuntimeStructuredSchema(execution, input)));
+        }
+        catch (error) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: {
+                    providerRef: execution.providerRef,
+                    executionProfileRef: execution.executionProfileRef,
+                    operationKey: execution.operationKey,
+                    message: 'Failed to serialize the structured output schema for CLI execution',
+                    originalError: error instanceof Error ? error.message : String(error),
+                }
+            });
+        }
+    }
+    parseCLIOperationOutput(execution, stdout, input) {
+        const outputParserMode = getEffectiveCLIRuntimeOutputParserMode(execution.cliRuntimeProfile, execution.cliExecutionProfile, execution.operationKey);
+        const parsedOutput = outputParserMode === CLIRuntime_OutputParserMode.JSON
+            ? this.parseCLIJsonOutput(execution, stdout)
+            : stdout.trim();
+        switch (execution.operationKey) {
+            case LLMProvider_OperationKey.GENERATE_TEXT:
+                return {
+                    text: this.extractCLITextOutput(parsedOutput),
+                };
+            case LLMProvider_OperationKey.GENERATE_STRUCTURED:
+                return {
+                    object: this.extractCLIStructuredOutput(execution, parsedOutput, input),
+                };
+            default:
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: {
+                        providerRef: execution.providerRef,
+                        executionProfileRef: execution.executionProfileRef,
+                        operationKey: execution.operationKey,
+                        message: 'CLI runtime executor does not implement truthful output normalization for this operation yet'
+                    }
+                });
+        }
+    }
+    parseCLIJsonOutput(execution, stdout) {
+        try {
+            return JSON.parse(stdout);
+        }
+        catch (error) {
+            const outputParserMode = getEffectiveCLIRuntimeOutputParserMode(execution.cliRuntimeProfile, execution.cliExecutionProfile, execution.operationKey);
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: {
+                    providerRef: execution.providerRef,
+                    executionProfileRef: execution.executionProfileRef,
+                    outputParserMode,
+                    message: 'CLI runtime command did not return valid JSON output',
+                    originalError: error instanceof Error ? error.message : String(error),
+                }
+            });
+        }
+    }
+    extractCLITextOutput(output) {
+        if (typeof output === 'string') {
+            return output;
+        }
+        if (this.isRecord(output)) {
+            if (typeof output.result === 'string') {
+                return output.result;
+            }
+            if (typeof output.text === 'string') {
+                return output.text;
+            }
+            if (typeof output.output === 'string') {
+                return output.output;
+            }
+            if (typeof output.content === 'string') {
+                return output.content;
+            }
+        }
+        return JSON.stringify(output ?? '');
+    }
+    extractCLIStructuredOutput(execution, output, input) {
+        const binding = getCLIRuntimeOperationBinding(execution.cliRuntimeProfile, execution.operationKey);
+        const path = binding?.jsonOutputPath;
+        if (!path?.length) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    providerRef: execution.providerRef,
+                    executionProfileRef: execution.executionProfileRef,
+                    operationKey: execution.operationKey,
+                    message: 'CLI runtime structured output is missing a configured JSON output path',
+                }
+            });
+        }
+        let current = output;
+        for (const segment of path) {
+            if (!this.isRecord(current) || !(segment in current)) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: {
+                        providerRef: execution.providerRef,
+                        executionProfileRef: execution.executionProfileRef,
+                        operationKey: execution.operationKey,
+                        jsonOutputPath: path,
+                        missingSegment: segment,
+                        message: 'CLI runtime structured output did not contain the configured JSON payload path',
+                    }
+                });
+            }
+            current = current[segment];
+        }
+        let structuredOutput = current;
+        if (typeof structuredOutput === 'string') {
+            try {
+                structuredOutput = JSON.parse(structuredOutput);
+            }
+            catch (error) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: {
+                        providerRef: execution.providerRef,
+                        executionProfileRef: execution.executionProfileRef,
+                        operationKey: execution.operationKey,
+                        jsonOutputPath: path,
+                        message: 'CLI runtime structured output payload was not valid JSON',
+                        originalError: error instanceof Error ? error.message : String(error),
+                    }
+                });
+            }
+        }
+        const structuredSchema = this.getCLIRuntimeStructuredSchema(execution, input);
+        try {
+            return structuredSchema.parse(structuredOutput);
+        }
+        catch (error) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: {
+                    providerRef: execution.providerRef,
+                    executionProfileRef: execution.executionProfileRef,
+                    operationKey: execution.operationKey,
+                    jsonOutputPath: path,
+                    message: 'CLI runtime structured output did not satisfy the requested schema',
+                    originalError: error instanceof Error ? error.message : String(error),
+                }
+            });
+        }
+    }
+    getCLIRuntimeStructuredSchema(execution, input) {
+        if (execution.operationKey !== LLMProvider_OperationKey.GENERATE_STRUCTURED
+            || !input
+            || typeof input !== 'object'
+            || !('schema' in input)
+            || !(input.schema instanceof z.ZodType)) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: {
+                    providerRef: execution.providerRef,
+                    executionProfileRef: execution.executionProfileRef,
+                    operationKey: execution.operationKey,
+                    message: 'CLI runtime structured execution requires a Zod schema on the invocation input',
+                }
+            });
+        }
+        return input.schema;
+    }
+    /**
+     * Build system prompt from agent configuration
+     *
+     * If agent has promptSpec, uses the PromptCompiler for structured prompt building.
+     * Otherwise, falls back to legacy skill-based prompt building.
+     */
+    buildSystemPrompt(agent, request) {
+        const parts = [];
+        if (agent.promptSpec.role) {
+            parts.push(`Role: ${agent.promptSpec.role}`);
+        }
+        if (agent.promptSpec.persona) {
+            parts.push(`Persona: ${agent.promptSpec.persona}`);
+        }
+        if (request.executionContext) {
+            parts.push(`Context: ${JSON.stringify(request.executionContext)}`);
+        }
+        return parts.join('\n\n');
+    }
+    /**
+     * Build prompts using the PromptCompiler when agent has promptSpec
+     * Returns compiled system and user prompts
+     */
+    async buildCompiledPrompts(agent, request, instructions) {
+        if (!agent.promptSpec) {
+            // Fall back to legacy mode
+            return {
+                systemPrompt: this.buildSystemPrompt(agent, request),
+                userPrompt: instructions,
+            };
+        }
+        this.logDebug('Building compiled prompts using PromptCompiler', {
+            agentRef: agent.ref,
+            hasInstructions: agent.promptSpec.instructions.length > 0,
+            hasHints: !!agent.promptSpec.hints?.length,
+            hasCuration: !!agent.promptSpec.curation,
+        });
+        // Build context items from execution context
+        // Note: User input is NOT added here - it goes in the user prompt section, not context
+        const contextItems = [];
+        if (request.executionContext) {
+            contextItems.push({
+                id: 'exec_context',
+                content: JSON.stringify(request.executionContext, null, 2),
+                trust: PromptIR_TrustLevel.HIGH,
+                sourceKind: PromptIR_ContextSourceKind.RELATIONSHIP,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        // Compile using the prompt compiler - works directly with agent + invocation
+        const compiled = await this.promptCompiler.compile(agent, request, contextItems, instructions);
+        this.logDebug('Prompts compiled', {
+            agentRef: agent.ref,
+            format: compiled.format,
+            systemPromptLength: compiled.systemPrompt.length,
+            userPromptLength: compiled.userPrompt.length,
+            tokenEstimates: compiled.tokenEstimates,
+        });
+        return {
+            systemPrompt: compiled.systemPrompt,
+            userPrompt: compiled.userPrompt,
+        };
+    }
+    /**
+     * Execute operation based on operation key
+     * Dispatches to specific operation handlers
+     */
+    async executeOperation({ providerClient, providerRef, config, operationKey, systemPrompt, instructions, input, llmProviderConfig }) {
+        const model = this.getModelFromProvider(providerClient, config.model);
+        const baseOptions = this.buildBaseOptions(config);
+        try {
+            switch (operationKey) {
+                case LLMProvider_OperationKey.GENERATE_TEXT:
+                case LLMProvider_OperationKey.GENERATE_TEXT_THINKING:
+                    return await this.executeGenerateText({ model, systemPrompt, instructions, baseOptions });
+                case LLMProvider_OperationKey.CHAT_COMPLETION:
+                case LLMProvider_OperationKey.CHAT_COMPLETION_THINKING:
+                    return await this.executeChatCompletion({ model, systemPrompt, instructions, input, baseOptions });
+                case LLMProvider_OperationKey.CHAT_MULTIMODAL:
+                case LLMProvider_OperationKey.CHAT_MULTIMODAL_THINKING:
+                    return await this.executeChatMultimodal({ model, systemPrompt, instructions, input, baseOptions });
+                case LLMProvider_OperationKey.GENERATE_STRUCTURED:
+                case LLMProvider_OperationKey.GENERATE_STRUCTURED_THINKING:
+                    return await this.executeGenerateStructured({ model, systemPrompt, instructions, input, baseOptions, llmProviderConfig, providerRef });
+                case LLMProvider_OperationKey.STREAM_TEXT:
+                case LLMProvider_OperationKey.STREAM_TEXT_THINKING:
+                    return await this.executeStreamText({ model, systemPrompt, instructions, baseOptions });
+                case LLMProvider_OperationKey.STREAM_STRUCTURED:
+                case LLMProvider_OperationKey.STREAM_STRUCTURED_THINKING:
+                    return await this.executeStreamStructured({ model, systemPrompt, instructions, baseOptions });
+                default:
+                    throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                        customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                        context: {
+                            operationKey,
+                            message: `Unsupported operation key: ${operationKey}`,
+                            supportedOperations: Object.values(LLMProvider_OperationKey),
+                        },
+                    });
+            }
+        }
+        catch (error) {
+            // Re-throw if it's already a built error
+            if (error && typeof error === 'object' && 'errorType' in error) {
+                throw error;
+            }
+            // Extract detailed provider error information
+            const errorDetails = this.extractProviderErrorDetails(error);
+            // Log detailed error information
+            this.logger.error('Operation execution failed - provider error details', {
+                operationKey,
+                model: config.model,
+                providerRef: providerClient?.providerRef || 'unknown',
+                ...errorDetails,
+            });
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.INTERNAL,
+                context: {
+                    operationKey,
+                    model: config.model,
+                    message: `Failed to execute operation ${operationKey}: ${errorDetails.errorMessage}`,
+                    ...errorDetails,
+                },
+            });
+        }
+    }
+    /**
+     * Get model instance from provider client
+     */
+    getModelFromProvider(providerClient, modelName) {
+        if (providerClient && typeof providerClient.languageModel === 'function') {
+            try {
+                return providerClient.languageModel(modelName);
+            }
+            catch (error) {
+                this.logger.error('Failed to get model via languageModel()', {
+                    modelName,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: {
+                        modelName,
+                        message: `Failed to initialize model ${modelName} via languageModel() method`,
+                        originalError: error instanceof Error ? error.message : String(error),
+                        stack: error instanceof Error ? error.stack : undefined,
+                    },
+                });
+            }
+        }
+        if (typeof providerClient === 'function') {
+            try {
+                return providerClient(modelName);
+            }
+            catch (error) {
+                this.logger.error('Failed to get model via function call', {
+                    modelName,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: {
+                        modelName,
+                        message: `Failed to initialize model ${modelName} via provider function`,
+                        originalError: error instanceof Error ? error.message : String(error),
+                        stack: error instanceof Error ? error.stack : undefined,
+                    },
+                });
+            }
+        }
+        if (providerClient && typeof providerClient.model === 'function') {
+            try {
+                return providerClient.model(modelName);
+            }
+            catch (error) {
+                this.logger.error('Failed to get model via model()', {
+                    modelName,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: {
+                        modelName,
+                        message: `Failed to initialize model ${modelName} via model() method`,
+                        originalError: error instanceof Error ? error.message : String(error),
+                        stack: error instanceof Error ? error.stack : undefined,
+                    },
+                });
+            }
+        }
+        this.logger.error('Failed to get model from provider client', {
+            providerType: typeof providerClient,
+            providerKeys: providerClient ? Object.keys(providerClient).slice(0, 10) : [],
+            hasLanguageModel: typeof providerClient?.languageModel === 'function',
+            hasModel: typeof providerClient?.model === 'function',
+            isFunction: typeof providerClient === 'function',
+        });
+        throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+            customMessageReference: ErrorCustomMessageReference.VALIDATION,
+            context: {
+                modelName,
+                message: 'AI provider client does not support any known model initialization pattern',
+                providerType: typeof providerClient,
+                hasLanguageModel: typeof providerClient?.languageModel === 'function',
+                hasModel: typeof providerClient?.model === 'function',
+                isFunction: typeof providerClient === 'function',
+            },
+        });
+    }
+    /**
+     * Build base options for LLM operations
+     */
+    buildBaseOptions(config) {
+        const baseOptions = {
+            temperature: config.temperature,
+            topP: config.topP,
+        };
+        // Only set maxOutputTokens if explicitly configured
+        if (config.maxTokens !== undefined) {
+            baseOptions.maxOutputTokens = config.maxTokens;
+        }
+        if (config.seed !== undefined) {
+            baseOptions.seed = config.seed;
+        }
+        return baseOptions;
+    }
+    /**
+     * Execute GENERATE_TEXT operation
+     */
+    async executeGenerateText({ model, systemPrompt, instructions, baseOptions }) {
+        try {
+            const result = await generateText({
+                model,
+                prompt: instructions,
+                system: systemPrompt,
+                ...baseOptions,
+            });
+            return {
+                output: {
+                    text: result.text,
+                },
+                usage: this.extractUsage(result.usage),
+            };
+        }
+        catch (error) {
+            // Re-throw if it's already a built error
+            if (error && typeof error === 'object' && 'errorType' in error) {
+                throw error;
+            }
+            const errorDetails = this.extractProviderErrorDetails(error);
+            this.logger.error('Generate text operation failed - provider response', {
+                operation: 'GENERATE_TEXT',
+                hasSystemPrompt: !!systemPrompt,
+                instructionsLength: instructions.length,
+                ...errorDetails,
+            });
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.INTERNAL,
+                context: {
+                    operation: 'GENERATE_TEXT',
+                    message: `Failed to generate text: ${errorDetails.errorMessage}`,
+                    ...errorDetails,
+                },
+            });
+        }
+    }
+    /**
+     * Execute CHAT_COMPLETION operation
+     */
+    async executeChatCompletion({ model, systemPrompt, instructions, input, baseOptions }) {
+        let messages = [];
+        try {
+            if (input && typeof input === 'object' && 'messages' in input && Array.isArray(input.messages)) {
+                messages = input.messages;
+                if (systemPrompt && !messages.some((m) => m.role === 'system')) {
+                    messages.unshift({ role: 'system', content: systemPrompt });
+                }
+            }
+            else {
+                if (systemPrompt) {
+                    messages.push({ role: 'system', content: systemPrompt });
+                }
+                messages.push({ role: 'user', content: instructions });
+            }
+            if (messages.length === 0) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: {
+                        operation: 'CHAT_COMPLETION',
+                        message: 'No messages provided for chat completion',
+                    },
+                });
+            }
+            const result = await generateText({
+                model,
+                messages,
+                ...baseOptions,
+            });
+            return {
+                output: {
+                    message: {
+                        role: LLMProvider_MessageRole.ASSISTANT,
+                        content: result.text,
+                    },
+                },
+                usage: this.extractUsage(result.usage),
+            };
+        }
+        catch (error) {
+            // Re-throw if it's already a built error
+            if (error && typeof error === 'object' && 'errorType' in error) {
+                throw error;
+            }
+            const errorDetails = this.extractProviderErrorDetails(error);
+            this.logger.error('Chat completion operation failed - provider response', {
+                operation: 'CHAT_COMPLETION',
+                hasSystemPrompt: !!systemPrompt,
+                hasInputMessages: input && typeof input === 'object' && 'messages' in input,
+                messagesCount: messages.length,
+                ...errorDetails,
+            });
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.INTERNAL,
+                context: {
+                    operation: 'CHAT_COMPLETION',
+                    message: `Failed to complete chat: ${errorDetails.errorMessage}`,
+                    ...errorDetails,
+                },
+            });
+        }
+    }
+    /**
+     * Execute CHAT_MULTIMODAL operation
+     */
+    async executeChatMultimodal({ model, systemPrompt, instructions, input, baseOptions }) {
+        let messages = [];
+        try {
+            if (input && typeof input === 'object' && 'messages' in input && Array.isArray(input.messages)) {
+                messages = input.messages;
+                if (systemPrompt && !messages.some((m) => m.role === 'system')) {
+                    messages.unshift({ role: 'system', content: systemPrompt });
+                }
+            }
+            else {
+                if (systemPrompt) {
+                    messages.push({ role: 'system', content: systemPrompt });
+                }
+                messages.push({ role: 'user', content: instructions });
+            }
+            if (messages.length === 0) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: {
+                        operation: 'CHAT_MULTIMODAL',
+                        message: 'No messages provided for multimodal chat completion',
+                    },
+                });
+            }
+            const result = await generateText({
+                model,
+                messages,
+                ...baseOptions,
+            });
+            return {
+                output: {
+                    message: {
+                        role: LLMProvider_MessageRole.ASSISTANT,
+                        content: result.text,
+                    },
+                },
+                usage: this.extractUsage(result.usage),
+            };
+        }
+        catch (error) {
+            // Re-throw if it's already a built error
+            if (error && typeof error === 'object' && 'errorType' in error) {
+                throw error;
+            }
+            const errorDetails = this.extractProviderErrorDetails(error);
+            this.logger.error('Chat multimodal operation failed - provider response', {
+                operation: 'CHAT_MULTIMODAL',
+                hasSystemPrompt: !!systemPrompt,
+                hasInputMessages: input && typeof input === 'object' && 'messages' in input,
+                messagesCount: messages.length,
+                ...errorDetails,
+            });
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.INTERNAL,
+                context: {
+                    operation: 'CHAT_MULTIMODAL',
+                    message: `Failed to complete multimodal chat: ${errorDetails.errorMessage}`,
+                    ...errorDetails,
+                },
+            });
+        }
+    }
+    /**
+     * Execute GENERATE_STRUCTURED operation
+     */
+    async executeGenerateStructured({ model, systemPrompt, instructions, input, baseOptions, llmProviderConfig, providerRef }) {
+        try {
+            if (!input || typeof input !== 'object' || !('schema' in input) || !input.schema) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: {
+                        operation: 'GENERATE_STRUCTURED',
+                        message: 'schema is required for GENERATE_STRUCTURED operation',
+                        hasInput: !!input,
+                        inputType: typeof input,
+                        hasSchema: input && typeof input === 'object' && 'schema' in input,
+                    },
+                });
+            }
+            const schema = input.schema;
+            const maxFields = llmProviderConfig?.maxStructuredDataFieldAllowed ?? DEFAULT_MAX_STRUCTURED_DATA_FIELD_ALLOWED;
+            const isOpenAI = providerRef === "openai";
+            // Count leaf fields (not just top-level properties) to properly handle nested schemas
+            const leafFieldCount = this.countLeafFields(schema);
+            this.logDebug('Checking if schema needs chunking', {
+                leafFieldCount,
+                maxFields,
+                needsChunking: leafFieldCount > maxFields,
+                isOpenAI,
+            });
+            if (leafFieldCount > maxFields) {
+                return await this.executeGenerateStructuredChunked({
+                    model,
+                    systemPrompt,
+                    instructions,
+                    schema,
+                    baseOptions,
+                    maxFields,
+                    leafFieldCount,
+                    isOpenAI,
+                });
+            }
+            else {
+                return await this.executeGenerateStructuredSingle({
+                    model,
+                    systemPrompt,
+                    instructions,
+                    schema,
+                    baseOptions,
+                    isOpenAI,
+                });
+            }
+        }
+        catch (error) {
+            // Re-throw if it's already a built error
+            if (error && typeof error === 'object' && 'errorType' in error) {
+                throw error;
+            }
+            const errorDetails = this.extractProviderErrorDetails(error);
+            this.logger.error('Generate structured operation failed - provider response', {
+                operation: 'GENERATE_STRUCTURED',
+                hasSchema: input && typeof input === 'object' && 'schema' in input,
+                ...errorDetails,
+            });
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.INTERNAL,
+                context: {
+                    operation: 'GENERATE_STRUCTURED',
+                    message: `Failed to generate structured data: ${errorDetails.errorMessage}`,
+                    ...errorDetails,
+                },
+            });
+        }
+    }
+    /**
+     * Execute structured generation with chunking - runs chunks in parallel
+     */
+    async executeGenerateStructuredChunked({ model, systemPrompt, instructions, schema, baseOptions, maxFields, leafFieldCount, isOpenAI }) {
+        try {
+            const schemaChunks = this.chunkZodSchema(schema, maxFields);
+            this.logDebug('Chunking structured generation - parallel execution', {
+                totalLeafFields: leafFieldCount,
+                maxFields,
+                chunks: schemaChunks.length,
+                isOpenAI,
+            });
+            // Execute all chunks in parallel using Promise.all
+            const chunkPromises = schemaChunks.map(async (chunkSchema, index) => {
+                try {
+                    this.logDebug(`Starting structured chunk ${index + 1}/${schemaChunks.length}`);
+                    const chunkResult = await generateObject({
+                        model,
+                        mode: "json",
+                        prompt: instructions,
+                        system: systemPrompt,
+                        schema: chunkSchema,
+                        ...baseOptions,
+                        // Only add strictJsonSchema for OpenAI provider
+                        ...(isOpenAI ? {
+                            providerOptions: {
+                                openai: {
+                                    strictJsonSchema: true,
+                                },
+                            },
+                        } : {}),
+                    });
+                    this.logDebug(`Completed structured chunk ${index + 1}/${schemaChunks.length}`);
+                    return {
+                        index,
+                        object: chunkResult.object,
+                        usage: this.extractUsage(chunkResult.usage),
+                    };
+                }
+                catch (error) {
+                    const errorDetails = this.extractProviderErrorDetails(error);
+                    this.logger.error(`Failed to generate structured chunk ${index + 1}/${schemaChunks.length} - provider response`, {
+                        operation: 'GENERATE_STRUCTURED',
+                        chunkIndex: index,
+                        totalChunks: schemaChunks.length,
+                        ...errorDetails,
+                    });
+                    throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                        customMessageReference: ErrorCustomMessageReference.INTERNAL,
+                        context: {
+                            operation: 'GENERATE_STRUCTURED',
+                            message: `Failed to generate structured chunk ${index + 1}/${schemaChunks.length}: ${errorDetails.errorMessage}`,
+                            chunkIndex: index,
+                            totalChunks: schemaChunks.length,
+                            ...errorDetails,
+                        },
+                    });
+                }
+            });
+            // Wait for all chunks to complete in parallel
+            const chunkResultsWithMeta = await Promise.all(chunkPromises);
+            // Sort by index to ensure consistent merge order, then extract objects
+            const chunkResults = chunkResultsWithMeta
+                .sort((a, b) => a.index - b.index)
+                .map(r => r.object);
+            // Aggregate usage from all chunks
+            const totalUsage = chunkResultsWithMeta.reduce((acc, r) => ({
+                promptTokens: acc.promptTokens + r.usage.promptTokens,
+                completionTokens: acc.completionTokens + r.usage.completionTokens,
+                totalTokens: acc.totalTokens + r.usage.totalTokens,
+            }), { promptTokens: 0, completionTokens: 0, totalTokens: 0 });
+            const mergedResult = this.mergeChunkedObjects(chunkResults);
+            this.logDebug('All structured chunks completed and merged', {
+                chunks: schemaChunks.length,
+                totalUsage,
+            });
+            return {
+                output: {
+                    object: mergedResult,
+                },
+                usage: totalUsage,
+            };
+        }
+        catch (error) {
+            // Re-throw if it's already a built error
+            if (error && typeof error === 'object' && 'errorType' in error) {
+                throw error;
+            }
+            const errorDetails = this.extractProviderErrorDetails(error);
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.INTERNAL,
+                context: {
+                    operation: 'GENERATE_STRUCTURED',
+                    message: `Failed to generate structured data with chunking: ${errorDetails.errorMessage}`,
+                    ...errorDetails,
+                },
+            });
+        }
+    }
+    /**
+     * Execute structured generation without chunking
+     */
+    async executeGenerateStructuredSingle({ model, systemPrompt, instructions, schema, baseOptions, isOpenAI }) {
+        try {
+            this.logDebug('Generating structured normally', {
+                hasSchema: !!schema,
+                instructionsLength: instructions.length,
+                hasSystemPrompt: !!systemPrompt,
+                isOpenAI,
+            });
+            const result = await generateObject({
+                model,
+                mode: "json",
+                prompt: instructions,
+                system: systemPrompt,
+                schema,
+                ...baseOptions,
+                // Only add strictJsonSchema for OpenAI provider
+                ...(isOpenAI ? {
+                    providerOptions: {
+                        openai: {
+                            strictJsonSchema: true,
+                        },
+                    },
+                } : {}),
+            });
+            return {
+                output: {
+                    object: result.object,
+                },
+                usage: this.extractUsage(result.usage),
+            };
+        }
+        catch (error) {
+            const errorDetails = this.extractProviderErrorDetails(error);
+            this.logger.error('Failed to generate structured data - provider response', {
+                operation: 'GENERATE_STRUCTURED',
+                hasSchema: !!schema,
+                ...errorDetails,
+            });
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.INTERNAL,
+                context: {
+                    operation: 'GENERATE_STRUCTURED',
+                    message: `Failed to generate structured data: ${errorDetails.errorMessage}`,
+                    ...errorDetails,
+                },
+            });
+        }
+    }
+    /**
+     * Execute STREAM_TEXT operation
+     */
+    async executeStreamText({ model, systemPrompt, instructions, baseOptions }) {
+        try {
+            const result = await streamText({
+                model,
+                prompt: instructions,
+                system: systemPrompt,
+                ...baseOptions,
+            });
+            let fullText = '';
+            try {
+                for await (const chunk of result.textStream) {
+                    fullText += chunk;
+                }
+            }
+            catch (streamError) {
+                this.logger.error('Failed to read text stream', {
+                    error: streamError instanceof Error ? streamError.message : String(streamError),
+                    textLength: fullText.length,
+                });
+                throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.INTERNAL,
+                    context: {
+                        operation: 'STREAM_TEXT',
+                        message: `Failed to read text stream: ${streamError instanceof Error ? streamError.message : String(streamError)}`,
+                        originalError: streamError instanceof Error ? streamError.message : String(streamError),
+                        stack: streamError instanceof Error ? streamError.stack : undefined,
+                    },
+                });
+            }
+            const usage = await result.usage;
+            return {
+                output: {
+                    textDelta: fullText,
+                },
+                usage: this.extractUsage(usage),
+            };
+        }
+        catch (error) {
+            // Re-throw if it's already a built error
+            if (error && typeof error === 'object' && 'errorType' in error) {
+                throw error;
+            }
+            const errorDetails = this.extractProviderErrorDetails(error);
+            this.logger.error('Stream text operation failed - provider response', {
+                operation: 'STREAM_TEXT',
+                hasSystemPrompt: !!systemPrompt,
+                instructionsLength: instructions.length,
+                ...errorDetails,
+            });
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.INTERNAL,
+                context: {
+                    operation: 'STREAM_TEXT',
+                    message: `Failed to stream text: ${errorDetails.errorMessage}`,
+                    ...errorDetails,
+                },
+            });
+        }
+    }
+    /**
+     * Execute STREAM_STRUCTURED operation
+     */
+    async executeStreamStructured({ model, systemPrompt, instructions, baseOptions }) {
+        try {
+            const result = await streamText({
+                model,
+                prompt: instructions,
+                system: systemPrompt,
+                ...baseOptions,
+            });
+            let fullText = '';
+            try {
+                for await (const chunk of result.textStream) {
+                    fullText += chunk;
+                }
+            }
+            catch (streamError) {
+                const errorDetails = this.extractProviderErrorDetails(streamError);
+                this.logger.error('Failed to read structured stream - provider response', {
+                    operation: 'STREAM_STRUCTURED',
+                    textLength: fullText.length,
+                    ...errorDetails,
+                });
+                throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.INTERNAL,
+                    context: {
+                        operation: 'STREAM_STRUCTURED',
+                        message: `Failed to read structured stream: ${errorDetails.errorMessage}`,
+                        ...errorDetails,
+                    },
+                });
+            }
+            const usage = await result.usage;
+            let parsedOutput = fullText;
+            try {
+                parsedOutput = JSON.parse(fullText);
+            }
+            catch (parseError) {
+                this.logDebug('Failed to parse structured stream as JSON, returning as text', {
+                    error: parseError instanceof Error ? parseError.message : String(parseError),
+                    textLength: fullText.length,
+                });
+            }
+            return {
+                output: {
+                    object: parsedOutput,
+                },
+                usage: this.extractUsage(usage),
+            };
+        }
+        catch (error) {
+            // Re-throw if it's already a built error
+            if (error && typeof error === 'object' && 'errorType' in error) {
+                throw error;
+            }
+            const errorDetails = this.extractProviderErrorDetails(error);
+            this.logger.error('Stream structured operation failed - provider response', {
+                operation: 'STREAM_STRUCTURED',
+                hasSystemPrompt: !!systemPrompt,
+                instructionsLength: instructions.length,
+                ...errorDetails,
+            });
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.INTERNAL,
+                context: {
+                    operation: 'STREAM_STRUCTURED',
+                    message: `Failed to stream structured data: ${errorDetails.errorMessage}`,
+                    ...errorDetails,
+                },
+            });
+        }
+    }
+    /**
+     * Extract usage information from AI SDK usage object
+     * Handles different usage object structures across providers
+     */
+    extractUsage(usage) {
+        // AI SDK usage object structure varies by provider
+        // Common properties: promptTokens, completionTokens, totalTokens
+        const promptTokens = usage?.promptTokens ?? usage?.inputTokens ?? 0;
+        const completionTokens = usage?.completionTokens ?? usage?.outputTokens ?? 0;
+        const totalTokens = usage?.totalTokens ?? (promptTokens + completionTokens);
+        return { promptTokens, completionTokens, totalTokens };
+    }
+    /**
+     * Extract detailed error information from AI SDK errors
+     * Captures provider response details, status codes, and error bodies
+     */
+    extractProviderErrorDetails(error) {
+        const details = {
+            errorMessage: error instanceof Error ? error.message : String(error),
+            errorName: error instanceof Error ? error.name : typeof error,
+            stack: error instanceof Error ? error.stack : undefined,
+        };
+        // AI SDK errors often have response details
+        if (error && typeof error === 'object') {
+            const err = error;
+            // Extract HTTP response details if available
+            if (err.response) {
+                details.response = {
+                    status: err.response.status,
+                    statusText: err.response.statusText,
+                    headers: err.response.headers,
+                    data: err.response.data,
+                    body: err.response.body,
+                };
+            }
+            // Extract status code directly
+            if (err.statusCode || err.status) {
+                details.statusCode = err.statusCode || err.status;
+            }
+            // Extract error code
+            if (err.code) {
+                details.errorCode = err.code;
+            }
+            // Extract error type
+            if (err.type) {
+                details.errorType = err.type;
+            }
+            // Extract cause if available
+            if (err.cause) {
+                details.cause = this.extractProviderErrorDetails(err.cause);
+            }
+            // Extract any additional error properties
+            if (err.data) {
+                details.data = err.data;
+            }
+            if (err.body) {
+                details.body = err.body;
+            }
+            // Extract provider-specific error details
+            if (err.error) {
+                details.providerError = err.error;
+            }
+            // Extract request details if available
+            if (err.request) {
+                details.request = {
+                    method: err.request.method,
+                    url: err.request.url,
+                    headers: err.request.headers,
+                };
+            }
+            // Try to extract readable error message from various formats
+            if (err.message) {
+                details.message = err.message;
+            }
+            if (err.error?.message) {
+                details.providerErrorMessage = err.error.message;
+            }
+            if (err.data?.error?.message) {
+                details.dataErrorMessage = err.data.error.message;
+            }
+        }
+        return details;
+    }
+    // ================================
+    // Agent Validation
+    // ================================
+    validateAgentStatus(agent) {
+        if (agent.status !== FlowsActors_Agent_Status.ACTIVE) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, { customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: { agentRef: agent.ref, status: agent.status, message: 'Agent is not active' } });
+        }
+    }
+    validateAgentCapabilities(agentRef, requiredCapabilities) {
+        const agent = this.flowsActorsRegistry.getAgentOrThrow(agentRef);
+        // TODO: Implement capability validation based on agent.capabilities
+        // For now, return true
+        this.logDebug('Agent capabilities validated', { agentRef, requiredCapabilities, hasCapabilities: true });
+        return true;
+    }
+    // ================================
+    // Agent Discovery
+    // ================================
+    getAvailableAgents() {
+        const registry = this.flowsActorsRegistry.getRegistry();
+        return Object.values(registry.agents).filter((agent) => agent.status === FlowsActors_Agent_Status.ACTIVE);
+    }
+    getAgentsBySkillType(skillType) {
+        return this.getAvailableAgents().filter(agent => agent.promptSpec.skillType === skillType);
+    }
+    getAgent(agentRef) {
+        return this.flowsActorsRegistry.getAgent(agentRef);
+    }
+    getAgentOrThrow(agentRef) {
+        return this.flowsActorsRegistry.getAgentOrThrow(agentRef);
+    }
+    // ================================
+    // Debug Methods
+    // ================================
+    getDebugInfo() {
+        const allAgents = Object.values(this.flowsActorsRegistry.getRegistry().agents);
+        const activeAgents = allAgents.filter(a => a.status === FlowsActors_Agent_Status.ACTIVE);
+        const agentsByProvider = {};
+        const agentsBySkillType = {};
+        allAgents.forEach(agent => {
+            const provider = agent.config.providerRef;
+            agentsByProvider[provider] = (agentsByProvider[provider] || 0) + 1;
+            const skillType = agent.promptSpec.skillType;
+            agentsBySkillType[skillType] = (agentsBySkillType[skillType] || 0) + 1;
+        });
+        return { totalAgents: allAgents.length, activeAgents: activeAgents.length, agentsByProvider, agentsBySkillType, };
+    }
+};
+AgentsBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.FlowsActorsRegistryService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.PromptCompilerService)),
+    __metadata("design:paramtypes", [LoggerService,
+        ErrorBuilderBackendService,
+        FlowsActorsRegistryService,
+        ExternalProvidersRegistryBackendService,
+        PromptCompilerBackendService])
+], AgentsBackendService);
+export { AgentsBackendService };
+//# sourceMappingURL=agents.backend.service.js.map