@wildo-ai/saas-backend-lib 1.0.1

package/src/flows-actors/services/agents.backend.service.ts

@@ -0,0 +1,2730 @@
+import 'reflect-metadata';
+import { injectable, inject } from 'inversify';
+import { z } from 'zod';
+import Bottleneck from 'bottleneck';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { FlowsActorsRegistryService } from './flows-actors-registry.service';
+import { ExternalProvidersRegistryBackendService } from '~wildo-backend-lib/external-providers/services/external-providers-registry.backend.service';
+import { PromptCompilerBackendService } from './prompt-compiler.backend.service';
+import {
+  FlowsActors_Agent,
+  FlowsActors_Agent_Status,
+  FlowsActors_Agent_Invocation,
+  PromptIR_ContextItem,
+  PromptIR_TrustLevel,
+  PromptIR_ContextSourceKind,
+  ErrorType,
+  ErrorCustomMessageReference,
+} from '@wildo-ai/saas-models';
+import {
+  APPLICATION_ENVIRONMENT,
+  CLIRuntime_AuthMode,
+  CLIRuntime_Configuration,
+  CLIRuntime_ExecutionProfile,
+  CLIRuntime_ModelBindingPlaceholder,
+  CLIRuntime_OutputParserMode,
+  CLIRuntime_Profile,
+  LLMProvider_ExecutionArtifactMetadata,
+  LLMProvider_ExecutionTransportMetadata,
+  LLMProvider_ExecutionTransportKind,
+  LLMProvider_ExecutionTransportMetadataSchema,
+  LLMProvider_UsageSchema,
+  ExternalProvider_ExchangeProtocol_Kind,
+  ExternalProvider_RateLimitConfigurationSchema,
+  LLMProvider_Configuration,
+  LLMProvider_OperationKey,
+  LLMProvider_MessageRole,
+} from '@wildo-ai/external-connectors-models';
+import { openai, createOpenAI } from '@ai-sdk/openai';
+import { anthropic, createAnthropic } from '@ai-sdk/anthropic';
+import { google } from '@ai-sdk/google';
+import { mistral, createMistral } from '@ai-sdk/mistral';
+import { perplexity, createPerplexity } from '@ai-sdk/perplexity';
+import { xai, createXai } from '@ai-sdk/xai';
+import { generateText, streamText, generateObject } from 'ai';
+import { userInputToContextItem } from '~wildo-backend-lib/flows-actors/utils/prompt-ir-adapters.backend.utils';
+import {
+  CLIRuntimeCommandExecutionResult,
+  CLIRuntimeRunnerError,
+  executeCLIRuntimeCommand,
+  resolveCLIRuntimeWorkingDirectory,
+} from '~wildo-backend-lib/flows-actors/utils/cli-runtime-runner.backend.utils';
+import {
+  assessCLIRuntimeOperationSupport,
+  getCLIRuntimeOperationBinding,
+  getEffectiveCLIRuntimeOutputParserMode,
+} from '~wildo-backend-lib/flows-actors/utils/cli-runtime-operation-support.backend.utils';
+
+
+
+interface executeOperationParams {
+  providerClient: any;
+  providerRef: string;
+  config: FlowsActors_Agent['config'];
+  operationKey: LLMProvider_OperationKey;
+  systemPrompt: string;
+  instructions: string;
+  input: any;
+  llmProviderConfig?: LLMProvider_Configuration;
+}
+
+interface CompiledExecutionPrompts {
+  systemPrompt: string;
+  instructions: string;
+}
+
+interface AgentExecutionResult {
+  output: unknown;
+  usage?: unknown;
+  transport?: LLMProvider_ExecutionTransportMetadata;
+}
+
+interface ResolvedCLIRuntimeInvocation {
+  command: string;
+  args?: string[];
+  env: NodeJS.ProcessEnv;
+  stdinPayload?: string;
+  requestedModel: string;
+  resolvedModel: string;
+  effectiveOutputParserMode: CLIRuntime_OutputParserMode;
+}
+
+type ResolvedAgentExecution =
+  | {
+      transport: 'api';
+      providerRef: string;
+      operationKey: LLMProvider_OperationKey;
+      llmProviderConfig?: LLMProvider_Configuration;
+    }
+  | {
+      transport: 'cli';
+      providerRef: string;
+      operationKey: LLMProvider_OperationKey;
+      executionProfileRef: string;
+      llmProviderConfig?: LLMProvider_Configuration;
+      cliRuntimeConfig: CLIRuntime_Configuration;
+      cliRuntimeProfile: CLIRuntime_Profile;
+      cliExecutionProfile: CLIRuntime_ExecutionProfile;
+    };
+
+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',
+] as const;
+
+@injectable()
+export class AgentsBackendService {
+
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  // Bottleneck instances per provider for rate limiting LLM calls
+  private readonly bottleneckInstances: Map<string, Bottleneck> = new Map();
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.FlowsActorsRegistryService) private readonly flowsActorsRegistry: FlowsActorsRegistryService,
+    @inject(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService) private readonly externalProvidersRegistry: ExternalProvidersRegistryBackendService,
+    @inject(SAAS_SERVICE_TYPES.PromptCompilerService) private readonly promptCompiler: PromptCompilerBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('AgentsBackend');
+    this.logger.setDebugTypeLogging('AgentsBackend', false);
+
+    this.logDebug('Agents backend service created');
+  }
+
+  // ================================
+  // Structured Data Chunking Utilities
+  // ================================
+
+
+  private mergeChunkedObjects<T extends Record<string, unknown>>(chunks: T[]): T {
+    if (chunks.length === 0) {
+      return {} as T;
+    }
+    if (chunks.length === 1) {
+      return chunks[0];
+    }
+
+    // Deep merge nested objects instead of shallow merge
+    const result = { ...chunks[0] } as any;
+
+    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 as T;
+  }
+
+  /**
+   * Count leaf fields in a Zod schema recursively
+   * Leaf fields are non-object fields (strings, numbers, enums, etc.)
+   */
+  private countLeafFields(schema: z.ZodSchema<any>): number {
+    if (!schema || typeof schema !== 'object' || !('_def' in schema)) {
+      return 1; // Treat as a single leaf if not a valid schema
+    }
+
+    const def = (schema as any)._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() }]
+   */
+  private flattenZodSchema(schema: z.ZodSchema<any>, basePath: string[] = []): Array<{ path: string[]; schema: z.ZodSchema<any> }> {
+    if (!schema || typeof schema !== 'object' || !('_def' in schema)) {
+      return [{ path: basePath, schema }];
+    }
+
+    const def = (schema as any)._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: Array<{ path: string[]; schema: z.ZodSchema<any> }> = [];
+      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
+   */
+  private buildNestedSchemaFromPaths(paths: Array<{ path: string[]; schema: z.ZodSchema<any> }>): z.ZodSchema<any> {
+    const nested: Record<string, any> = {};
+
+    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: Record<string, any>): z.ZodSchema<any> => {
+      const shape: Record<string, z.ZodTypeAny> = {};
+
+      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);
+  }
+
+  private chunkZodSchema(schema: z.ZodSchema<any>, maxFields: number): z.ZodSchema<any>[] {
+    if (!schema || typeof schema !== 'object' || !('_def' in schema)) {
+      return [schema];
+    }
+
+    const def = (schema as any)._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: z.ZodSchema<any>[] = [];
+
+    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
+  // ================================
+
+
+  private getBottleneckForProvider(
+    providerRef: string,
+    protocolKind: ExternalProvider_ExchangeProtocol_Kind = ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER
+  ): Bottleneck {
+    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: Record<string, number | undefined> = {
+      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
+   */
+  private setupBottleneckEventListeners(limiter: Bottleneck, providerRef: string): void {
+    // Track when jobs are queued (delayed due to rate limiting)
+    limiter.on('queued', (info: any) => {
+      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: any) => {
+      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: any) => {
+      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: any) => {
+      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: any) => {
+      this.logger.error('Rate limiter error', {
+        providerRef,
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+    });
+  }
+
+  // ================================
+  // Agent Invocation
+  // ================================
+
+  public async invokeAgent(request: FlowsActors_Agent_Invocation<any, any, any>): Promise<FlowsActors_Agent_Invocation<any, any, any>> {
+    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.
+   */
+  private normalizeOperationOutput(operationKey: LLMProvider_OperationKey, output: unknown): unknown {
+    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;
+    }
+  }
+
+  private isRecord(value: unknown): value is Record<string, any> {
+    return typeof value === 'object' && value !== null;
+  }
+
+  /**
+   * Execute agent with LLM provider using @ai-sdk
+   */
+  private async executeAgent( agent: FlowsActors_Agent, request: FlowsActors_Agent_Invocation<any, any, any>): Promise<AgentExecutionResult> {
+    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);
+  }
+
+  private resolveAgentExecution(agent: FlowsActors_Agent): ResolvedAgentExecution {
+    const providerRef = agent.config.providerRef;
+    const operationKey = agent.config.operationKey as LLMProvider_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
+    ) as LLMProvider_Configuration | undefined;
+
+    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: Extract<ResolvedAgentExecution, { transport: 'cli' }> = {
+      transport: 'cli',
+      providerRef,
+      operationKey,
+      executionProfileRef,
+      llmProviderConfig,
+      cliRuntimeConfig,
+      cliRuntimeProfile,
+      cliExecutionProfile,
+    };
+
+    this.validateCLIRuntimeDefinitionSupport(execution, agent.config.model);
+
+    return execution;
+  }
+
+  private async buildExecutionPrompts(
+    agent: FlowsActors_Agent,
+    request: FlowsActors_Agent_Invocation<any, any, any>
+  ): Promise<CompiledExecutionPrompts> {
+    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,
+    };
+  }
+
+  private extractRawInstructions(input: unknown): string {
+    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 as any[]).filter((message: any) => message.role === 'user');
+        return userMessages
+          .map((message: any) => typeof message.content === 'string' ? message.content : JSON.stringify(message.content))
+          .join('\n');
+      }
+
+      return JSON.stringify(input);
+    }
+
+    return String(input);
+  }
+
+  private async executeAgentViaApi(
+    agent: FlowsActors_Agent,
+    request: FlowsActors_Agent_Invocation<any, any, any>,
+    execution: Extract<ResolvedAgentExecution, { transport: 'api' }>,
+    prompts: CompiledExecutionPrompts
+  ): Promise<AgentExecutionResult> {
+    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,
+      },
+    };
+  }
+
+  private async executeAgentViaCLI(
+    agent: FlowsActors_Agent,
+    request: FlowsActors_Agent_Invocation<any, any, any>,
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    prompts: CompiledExecutionPrompts
+  ): Promise<AgentExecutionResult> {
+    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),
+      };
+    });
+  }
+
+  private validateCLIOperationSupport(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>
+  ): void {
+    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',
+        }
+      });
+    }
+  }
+
+  private validateCLIModelSupport(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    requestedModel: string
+  ): void {
+    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'
+      }
+    });
+  }
+
+  private validateCLIRuntimeDefinitionSupport(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    requestedModel: string
+  ): void {
+    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
+   */
+  private getAIProvider(providerRef: string, apiKey: string): any {
+    try {
+      let providerClient: any;
+
+      switch (providerRef) {
+        case "openai":
+          providerClient = createOpenAI({ apiKey } as any);
+          break;
+        case "anthropic":
+          providerClient = createAnthropic({ apiKey } as any);
+          break;
+        case "google":
+          // Google provider might use a different pattern - try google() directly
+          providerClient = google({ apiKey } as any);
+          // 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 } as any);
+          break;
+        case "perplexity":
+          providerClient = createPerplexity({ apiKey } as any);
+          break;
+        case "grok":
+          providerClient = createXai({ apiKey } as any);
+          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;
+    }
+  }
+
+  private validateCLIRuntimePolicy(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>
+  ): void {
+    const applicationEnv = (process.env.APPLICATION_ENV || APPLICATION_ENVIRONMENT.DEVELOPMENT) as APPLICATION_ENVIRONMENT;
+    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'
+        }
+      });
+    }
+  }
+
+  private buildCLIPromptInput(prompts: CompiledExecutionPrompts): string {
+    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.
+   */
+  private buildCLIRuntimePromptInput(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    prompts: CompiledExecutionPrompts,
+    input?: unknown,
+  ): string {
+    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');
+  }
+
+  private async runCLIRuntimeCommand(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    requestedModel: string,
+    promptPayload: string,
+  ): Promise<CLIRuntimeCommandExecutionResult & {
+    workingDirectory: string;
+    requestedModel: string;
+    resolvedModel: string;
+    effectiveOutputParserMode: CLIRuntime_OutputParserMode;
+  }> {
+    const invocation = this.resolveCLIRuntimeInvocation(execution, requestedModel, promptPayload);
+    let cwd: string;
+    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;
+    }
+  }
+
+  private getCLIRuntimeRunnerErrorType(error: CLIRuntimeRunnerError): ErrorType {
+    if (error.message.startsWith('Failed to start CLI runtime command')) {
+      return ErrorType.CONFIGURATION;
+    }
+
+    return ErrorType.INTERNAL;
+  }
+
+  private buildCLITransportMetadata(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    commandResult: CLIRuntimeCommandExecutionResult & {
+      workingDirectory: string;
+      requestedModel: string;
+      resolvedModel: string;
+      effectiveOutputParserMode: CLIRuntime_OutputParserMode;
+    }
+  ): LLMProvider_ExecutionTransportMetadata {
+    const artifacts: LLMProvider_ExecutionArtifactMetadata[] = [];
+
+    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,
+    };
+  }
+
+  private resolveCLIRuntimeInvocation(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    requestedModel: string,
+    promptPayload: string,
+  ): ResolvedCLIRuntimeInvocation {
+    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.
+   */
+  private resolveCLIRuntimeModel(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    requestedModel: string
+  ): string {
+    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;
+  }
+
+  private buildCLIRuntimeCommandArgs(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    resolvedModel: string,
+  ): string[] | undefined {
+    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;
+  }
+
+  private buildCLIRuntimeEnvironment(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    resolvedModel: string,
+  ): NodeJS.ProcessEnv {
+    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;
+  }
+
+  private buildCLIRuntimeBaseEnvironment(
+    profile: Pick<CLIRuntime_ExecutionProfile, 'inheritedEnvironmentVariables'>
+  ): NodeJS.ProcessEnv {
+    const env: NodeJS.ProcessEnv = {};
+    const inheritedKeys = new Set<string>([
+      ...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;
+  }
+
+  private buildCLIRuntimeTemplateValues(resolvedModel: string): Record<string, string> {
+    return {
+      [CLIRuntime_ModelBindingPlaceholder]: resolvedModel,
+    };
+  }
+
+  private applyCLIRuntimeTemplateValues(
+    template: string,
+    values: Record<string, string>,
+  ): string {
+    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.
+   */
+  private serializeCLIRuntimeStructuredSchema(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    input?: unknown,
+  ): string {
+    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),
+        }
+      });
+    }
+  }
+
+  private parseCLIOperationOutput(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    stdout: string,
+    input?: unknown,
+  ): unknown {
+    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'
+          }
+        });
+    }
+  }
+
+  private parseCLIJsonOutput(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    stdout: string
+  ): unknown {
+    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),
+        }
+      });
+    }
+  }
+
+  private extractCLITextOutput(output: unknown): string {
+    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 ?? '');
+  }
+
+  private extractCLIStructuredOutput(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    output: unknown,
+    input?: unknown,
+  ): unknown {
+    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: unknown = 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),
+        }
+      });
+    }
+  }
+
+  private getCLIRuntimeStructuredSchema(
+    execution: Extract<ResolvedAgentExecution, { transport: 'cli' }>,
+    input?: unknown,
+  ): z.ZodTypeAny {
+    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.
+   */
+  private buildSystemPrompt(agent: FlowsActors_Agent, request: FlowsActors_Agent_Invocation<any, any, any>): string {
+    const parts: string[] = [];
+
+    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
+   */
+  private async buildCompiledPrompts(
+    agent: FlowsActors_Agent,
+    request: FlowsActors_Agent_Invocation<any, any, any>,
+    instructions: string
+  ): Promise<{ systemPrompt: string; userPrompt: string }> {
+    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: PromptIR_ContextItem[] = [];
+
+    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
+   */
+  private async executeOperation({ providerClient, providerRef, config, operationKey, systemPrompt, instructions, input, llmProviderConfig }: executeOperationParams): Promise<{ output: unknown; usage?: any }> {
+    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 as any)?.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
+   */
+  private getModelFromProvider(providerClient: any, modelName: string): any {
+    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
+   */
+  private buildBaseOptions(config: FlowsActors_Agent['config']): any {
+    const baseOptions: any = {
+      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
+   */
+  private async executeGenerateText({ model, systemPrompt, instructions, baseOptions }: {
+    model: any;
+    systemPrompt: string;
+    instructions: string;
+    baseOptions: any;
+  }): Promise<{ output: unknown; usage?: any }> {
+    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
+   */
+  private async executeChatCompletion({ model, systemPrompt, instructions, input, baseOptions }: {
+    model: any;
+    systemPrompt: string;
+    instructions: string;
+    input: any;
+    baseOptions: any;
+  }): Promise<{ output: unknown; usage?: any }> {
+    let messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string | Array<any> }> = [];
+
+    try {
+      if (input && typeof input === 'object' && 'messages' in input && Array.isArray(input.messages)) {
+        messages = input.messages;
+        if (systemPrompt && !messages.some((m: any) => 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
+   */
+  private async executeChatMultimodal({ model, systemPrompt, instructions, input, baseOptions }: {
+    model: any;
+    systemPrompt: string;
+    instructions: string;
+    input: any;
+    baseOptions: any;
+  }): Promise<{ output: unknown; usage?: any }> {
+    let messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string | Array<any> }> = [];
+
+    try {
+      if (input && typeof input === 'object' && 'messages' in input && Array.isArray(input.messages)) {
+        messages = input.messages;
+        if (systemPrompt && !messages.some((m: any) => 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
+   */
+  private async executeGenerateStructured({ model, systemPrompt, instructions, input, baseOptions, llmProviderConfig, providerRef }: {
+    model: any;
+    systemPrompt: string;
+    instructions: string;
+    input: any;
+    baseOptions: any;
+    llmProviderConfig?: LLMProvider_Configuration;
+    providerRef: string;
+  }): Promise<{ output: unknown; usage?: any }> {
+    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
+   */
+  private async executeGenerateStructuredChunked({ model, systemPrompt, instructions, schema, baseOptions, maxFields, leafFieldCount, isOpenAI }: {
+    model: any;
+    systemPrompt: string;
+    instructions: string;
+    schema: z.ZodSchema<any>;
+    baseOptions: any;
+    maxFields: number;
+    leafFieldCount: number;
+    isOpenAI: boolean;
+  }): Promise<{ output: unknown; usage?: any }> {
+    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 as Record<string, unknown>,
+            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
+   */
+  private async executeGenerateStructuredSingle({ model, systemPrompt, instructions, schema, baseOptions, isOpenAI }: {
+    model: any;
+    systemPrompt: string;
+    instructions: string;
+    schema: z.ZodSchema<any>;
+    baseOptions: any;
+    isOpenAI: boolean;
+  }): Promise<{ output: unknown; usage?: any }> {
+    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
+   */
+  private async executeStreamText({ model, systemPrompt, instructions, baseOptions }: {
+    model: any;
+    systemPrompt: string;
+    instructions: string;
+    baseOptions: any;
+  }): Promise<{ output: unknown; usage?: any }> {
+    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
+   */
+  private async executeStreamStructured({ model, systemPrompt, instructions, baseOptions }: {
+    model: any;
+    systemPrompt: string;
+    instructions: string;
+    baseOptions: any;
+  }): Promise<{ output: unknown; usage?: any }> {
+    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: unknown = 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
+   */
+  private extractUsage(usage: any): { promptTokens: number; completionTokens: number; totalTokens: number } {
+    // 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
+   */
+  private extractProviderErrorDetails(error: unknown): Record<string, unknown> {
+    const details: Record<string, unknown> = {
+      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 as any;
+
+      // 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
+  // ================================
+
+  private validateAgentStatus(agent: FlowsActors_Agent): void {
+    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' }});
+    }
+  }
+
+  public validateAgentCapabilities(agentRef: string,requiredCapabilities: string[]): boolean {
+    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
+  // ================================
+
+  public getAvailableAgents(): FlowsActors_Agent[] {
+    const registry = this.flowsActorsRegistry.getRegistry();
+    return Object.values(registry.agents).filter((agent: FlowsActors_Agent) => agent.status === FlowsActors_Agent_Status.ACTIVE);
+  }
+
+  public getAgentsBySkillType(skillType: string): FlowsActors_Agent[] {
+    return this.getAvailableAgents().filter(agent => agent.promptSpec.skillType === skillType);
+  }
+
+  public getAgent(agentRef: string): FlowsActors_Agent | undefined {
+    return this.flowsActorsRegistry.getAgent(agentRef);
+  }
+
+  public getAgentOrThrow(agentRef: string): FlowsActors_Agent {
+    return this.flowsActorsRegistry.getAgentOrThrow(agentRef);
+  }
+
+  // ================================
+  // Debug Methods
+  // ================================
+
+  public getDebugInfo(): { totalAgents: number; activeAgents: number; agentsByProvider: Record<string, number>; agentsBySkillType: Record<string, number> } {
+    const allAgents = Object.values(this.flowsActorsRegistry.getRegistry().agents) as FlowsActors_Agent[];
+
+    const activeAgents = allAgents.filter(a => a.status === FlowsActors_Agent_Status.ACTIVE);
+
+    const agentsByProvider: Record<string, number> = {};
+    const agentsBySkillType: Record<string, number> = {};
+
+    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, };
+  }
+}
+