@wildo-ai/saas-backend-lib 1.0.1

package/src/flows-actors/services/__tests__/agents.backend.service.cli-runtime.test.ts

@@ -0,0 +1,234 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+
+import { ErrorType } from '@wildo-ai/saas-models';
+import {
+  CLIRuntime_AuthMode,
+  CLIRuntime_OutputParserMode,
+  CLIRuntime_RunnerHost,
+  LLMProvider_OperationKey,
+  LLM_Model,
+} from '@wildo-ai/external-connectors-models';
+import { AgentsBackendService } from '../agents.backend.service';
+import { CLIRuntimeRunnerError } from '../../utils/cli-runtime-runner.backend.utils';
+
+function createService(): AgentsBackendService {
+  return new AgentsBackendService(
+    {
+      debugByType: () => () => undefined,
+      setDebugTypeLogging: () => undefined,
+      error: () => undefined,
+    } as any,
+    {
+      buildError: (_type: unknown, _details: unknown, config?: { context?: { message?: string } }) =>
+        new Error(config?.context?.message ?? 'error'),
+    } as any,
+    {} as any,
+    {} as any,
+    {} as any,
+  );
+}
+
+describe('AgentsBackendService CLI runtime helpers', () => {
+  it('delivers Anthropic text prompts through stdin while keeping CLI args generic', () => {
+    const service = createService();
+    const execution = {
+      transport: 'cli',
+      providerRef: 'anthropic',
+      operationKey: LLMProvider_OperationKey.GENERATE_TEXT,
+      executionProfileRef: 'claude_cli_smoke',
+      llmProviderConfig: undefined,
+      cliRuntimeConfig: {} as any,
+      cliRuntimeProfile: {
+        supportedOperationKeys: [LLMProvider_OperationKey.GENERATE_TEXT],
+        supportedModels: [LLM_Model.CLAUDE_SONNET_4_5],
+        modelBinding: {
+          argumentTemplate: ['--model', '{model}'],
+        },
+        operationBindings: {
+          [LLMProvider_OperationKey.GENERATE_TEXT]: {
+            argumentTemplate: ['--bare', '-p', 'Read the complete task from stdin and return only the final answer.'],
+          },
+        },
+      },
+      cliExecutionProfile: {
+        runnerHost: CLIRuntime_RunnerHost.BACKEND_SUBPROCESS,
+        command: 'claude',
+        authMode: CLIRuntime_AuthMode.HOST_MANAGED,
+        allowedApplicationEnvironments: ['production'],
+        workspaceRootPath: '/app',
+        outputParserMode: CLIRuntime_OutputParserMode.TEXT,
+      },
+    } as const;
+
+    const invocation = (service as any).resolveCLIRuntimeInvocation(
+      execution,
+      LLM_Model.CLAUDE_SONNET_4_5,
+      'Summarize this project',
+      { prompt: 'Summarize this project' },
+    );
+
+    expect(invocation.args).toEqual([
+      '--model',
+      LLM_Model.CLAUDE_SONNET_4_5,
+      '--bare',
+      '-p',
+      'Read the complete task from stdin and return only the final answer.',
+    ]);
+    expect(invocation.stdinPayload).toBe('Summarize this project');
+  });
+
+  it('builds structured Anthropic CLI invocations without leaking schema through args and validates the returned object', () => {
+    const service = createService();
+    const execution = {
+      transport: 'cli',
+      providerRef: 'anthropic',
+      operationKey: LLMProvider_OperationKey.GENERATE_STRUCTURED,
+      executionProfileRef: 'claude_cli_smoke',
+      llmProviderConfig: undefined,
+      cliRuntimeConfig: {} as any,
+      cliRuntimeProfile: {
+        supportedOperationKeys: [LLMProvider_OperationKey.GENERATE_STRUCTURED],
+        supportedModels: [LLM_Model.CLAUDE_SONNET_4_5],
+        modelBinding: {
+          argumentTemplate: ['--model', '{model}'],
+        },
+        operationBindings: {
+          [LLMProvider_OperationKey.GENERATE_STRUCTURED]: {
+            argumentTemplate: ['--bare', '-p', 'Read the complete task from stdin and return only the requested JSON object.', '--output-format', 'json'],
+            outputParserMode: CLIRuntime_OutputParserMode.JSON,
+            jsonOutputPath: ['result'],
+          },
+        },
+      },
+      cliExecutionProfile: {
+        runnerHost: CLIRuntime_RunnerHost.BACKEND_SUBPROCESS,
+        command: 'claude',
+        authMode: CLIRuntime_AuthMode.HOST_MANAGED,
+        allowedApplicationEnvironments: ['production'],
+        workspaceRootPath: '/app',
+        outputParserMode: CLIRuntime_OutputParserMode.TEXT,
+      },
+    } as const;
+
+    const input = {
+      prompt: 'Return title and count',
+      schema: z.object({
+        title: z.string(),
+        count: z.number(),
+      }),
+    };
+
+    const promptPayload = (service as any).buildCLIRuntimePromptInput(
+      execution,
+      {
+        systemPrompt: '',
+        instructions: 'Return title and count',
+      },
+      input,
+    );
+    const invocation = (service as any).resolveCLIRuntimeInvocation(
+      execution,
+      LLM_Model.CLAUDE_SONNET_4_5,
+      promptPayload,
+      input,
+    );
+
+    expect(invocation.args).toEqual([
+      '--model',
+      LLM_Model.CLAUDE_SONNET_4_5,
+      '--bare',
+      '-p',
+      'Read the complete task from stdin and return only the requested JSON object.',
+      '--output-format',
+      'json',
+    ]);
+    expect(invocation.stdinPayload).toContain('[STRUCTURED_OUTPUT_REQUIREMENTS]');
+    expect(invocation.stdinPayload).toContain('"title"');
+    expect(invocation.effectiveOutputParserMode).toBe(CLIRuntime_OutputParserMode.JSON);
+
+    expect(
+      (service as any).parseCLIOperationOutput(
+        execution,
+        JSON.stringify({
+          result: '{"title":"Summary","count":2}',
+        }),
+        input,
+      ),
+    ).toEqual({
+      object: {
+        title: 'Summary',
+        count: 2,
+      },
+    });
+  });
+
+  it('passes only the allowed inherited environment variables to CLI subprocesses', () => {
+    const service = createService();
+    const originalPath = process.env.PATH;
+    const originalHome = process.env.HOME;
+    const originalAnthropicKey = process.env.ANTHROPIC_API_KEY;
+    const originalDbUrl = process.env.DATABASE_URL;
+
+    process.env.PATH = '/usr/bin';
+    process.env.HOME = '/Users/tester';
+    process.env.ANTHROPIC_API_KEY = 'anthropic-key';
+    process.env.DATABASE_URL = 'postgres://secret';
+
+    try {
+      const env = (service as any).buildCLIRuntimeBaseEnvironment({
+        inheritedEnvironmentVariables: ['ANTHROPIC_API_KEY'],
+      });
+
+      expect(env.PATH).toBe('/usr/bin');
+      expect(env.HOME).toBe('/Users/tester');
+      expect(env.ANTHROPIC_API_KEY).toBe('anthropic-key');
+      expect(env.DATABASE_URL).toBeUndefined();
+    } finally {
+      process.env.PATH = originalPath;
+      process.env.HOME = originalHome;
+      process.env.ANTHROPIC_API_KEY = originalAnthropicKey;
+      process.env.DATABASE_URL = originalDbUrl;
+    }
+  });
+
+  it('classifies CLI runner start failures as configuration errors', () => {
+    const service = createService();
+
+    expect(
+      (service as any).getCLIRuntimeRunnerErrorType(
+        new CLIRuntimeRunnerError('Failed to start CLI runtime command: spawn claude ENOENT', {
+          originalError: 'spawn claude ENOENT',
+        }),
+      ),
+    ).toBe(ErrorType.CONFIGURATION);
+  });
+
+  it('does not persist raw CLI argv in transport metadata', () => {
+    const service = createService();
+
+    expect(
+      (service as any).buildCLITransportMetadata(
+        {
+          transport: 'cli',
+          providerRef: 'anthropic',
+          executionProfileRef: 'claude_cli_smoke',
+          cliExecutionProfile: {
+            runnerHost: CLIRuntime_RunnerHost.BACKEND_SUBPROCESS,
+            command: 'claude',
+          },
+        },
+        {
+          stdout: 'ok',
+          stderr: '',
+          exitCode: 0,
+          signal: null,
+          workingDirectory: '/app',
+          requestedModel: LLM_Model.CLAUDE_SONNET_4_5,
+          resolvedModel: LLM_Model.CLAUDE_SONNET_4_5,
+          effectiveOutputParserMode: CLIRuntime_OutputParserMode.TEXT,
+        },
+      ),
+    ).not.toHaveProperty('args');
+  });
+});

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

@@ -0,0 +1,270 @@
+import 'reflect-metadata';
+import { injectable, inject } from 'inversify';
+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 { AgentsBackendService } from './agents.backend.service';
+import {
+  FlowActorSystem,
+  FlowActorSystem_Kind,
+  FlowActorSystem_Status,
+  FlowsActors_Status
+} from '@wildo-ai/saas-models';
+import {
+  ErrorType,
+  ErrorCustomMessageReference
+} from '@wildo-ai/saas-models';
+import {
+  ActorSystem_Execution,
+  Actors_Task_Schema,
+} from '@wildo-ai/saas-models';
+
+/**
+ * Actors System Backend Service
+ *
+ * Manages actor execution and event-driven reactive behaviors.
+ * Coordinates actor lifecycle, trigger handling, and agentic execution.
+ *
+ * Features:
+ * - Actor execution management
+ * - Event trigger handling
+ * - Reactive behavior orchestration
+ * - Agentic mode execution
+ * - State management
+ * - Task planning and execution
+ */
+@injectable()
+export class ActorsSystemBackendService {
+
+  protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  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.AgentsBackendService) private readonly agentsService: AgentsBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('ActorsSystem');
+    this.logger.setDebugTypeLogging('ActorsSystem', true);
+
+    this.logDebug('Actors system backend service created');
+  }
+
+  // ================================
+  // Actor Execution
+  // ================================
+
+  /**
+   * Execute an actor
+   * Accepts ActorSystem_Execution and executes it
+   */
+  public async executeActor(execution: ActorSystem_Execution): Promise<ActorSystem_Execution> {
+    this.logDebug('Executing actor', {
+      actorRef: execution.systemRef,
+      executionId: execution._id,
+      hasInitiator: !!execution.initiator
+    });
+
+    // Get actor from registry
+    const actor = this.flowsActorsRegistry.getSystemOrThrow(execution.systemRef, FlowActorSystem_Kind.ACTOR);
+
+    // Validate it's an actor
+    this.validateIsActor(actor);
+
+    // Validate actor status
+    this.validateActorStatus(actor);
+
+    // Execute actor behavior
+    const updatedExecution = await this.executeActorBehavior(actor, execution);
+
+    this.logDebug('Actor execution completed', {
+      actorRef: execution.systemRef,
+      executionId: updatedExecution._id || 'unknown',
+      status: updatedExecution.status
+    });
+
+    return updatedExecution;
+  }
+
+  /**
+   * Execute actor behavior based on configuration
+   */
+  private async executeActorBehavior(
+    actor: FlowActorSystem,
+    execution: ActorSystem_Execution
+  ): Promise<ActorSystem_Execution> {
+    this.logDebug('Executing actor behavior', {
+      actorRef: actor.ref,
+      executionId: execution._id
+    });
+
+    // TODO: Implement actual actor behavior execution
+    // This will involve:
+    // 1. Processing trigger event (from execution context or metadata)
+    // 2. Determining actor mode (reactive, agentic)
+    // 3. Creating Actors_Task if needed
+    // 4. Executing appropriate behavior (agentic, flow execution, human interaction)
+    // 5. Managing actor state
+    // 6. Updating standaloneTasks and standaloneTaskStates
+
+    // For now, update execution status
+    return {
+      ...execution,
+      status: FlowsActors_Status.COMPLETED,
+      finishedAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      statusChanges: [
+        ...execution.statusChanges,
+        {
+          status: FlowsActors_Status.COMPLETED,
+          timestamp: new Date().toISOString(),
+        },
+      ],
+    };
+  }
+
+  // ================================
+  // Actor Validation
+  // ================================
+
+  /**
+   * Validate system is an actor
+   */
+  private validateIsActor(system: FlowActorSystem): void {
+    if (system.kind !== FlowActorSystem_Kind.ACTOR) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        undefined,
+        {
+          customMessageReference: ErrorCustomMessageReference.VALIDATION,
+          context: {
+            systemRef: system.ref,
+            kind: system.kind,
+            message: 'System is not an actor'
+          }
+        }
+      );
+    }
+  }
+
+  /**
+   * Validate actor status before execution
+   */
+  private validateActorStatus(actor: FlowActorSystem): void {
+    if (actor.status !== FlowActorSystem_Status.ACTIVE) {
+      throw this.errorBuilder.buildError(
+        ErrorType.VALIDATION,
+        undefined,
+        {
+          customMessageReference: ErrorCustomMessageReference.VALIDATION,
+          context: {
+            actorRef: actor.ref,
+            status: actor.status,
+            message: 'Actor is not active'
+          }
+        }
+      );
+    }
+  }
+
+  // ================================
+  // Execution Context Management
+  // ================================
+
+
+  // ================================
+  // Actor Discovery
+  // ================================
+
+  /**
+   * Get all available actors
+   */
+  public getAvailableActors(): FlowActorSystem[] {
+    return this.flowsActorsRegistry.getActors().filter(
+      actor => actor.status === FlowActorSystem_Status.ACTIVE
+    );
+  }
+
+  /**
+   * Get actor by reference
+   */
+  public getActor(actorRef: string): FlowActorSystem | undefined {
+    const system = this.flowsActorsRegistry.getSystem(actorRef, FlowActorSystem_Kind.ACTOR);
+    if (system && system.kind === FlowActorSystem_Kind.ACTOR) {
+      return system;
+    }
+    return undefined;
+  }
+
+  /**
+   * Get actor or throw
+   */
+  public getActorOrThrow(actorRef: string): FlowActorSystem {
+    const actor = this.getActor(actorRef);
+    if (!actor) {
+      throw this.errorBuilder.buildError(
+        ErrorType.NOT_FOUND,
+        undefined,
+        {
+          customMessageReference: ErrorCustomMessageReference.NOT_FOUND,
+          context: { actorRef }
+        }
+      );
+    }
+    return actor;
+  }
+
+  // ================================
+  // Event Trigger Management
+  // ================================
+
+  /**
+   * Register actor for event trigger
+   */
+  public registerActorTrigger(actorRef: string, triggerType: string): void {
+    const actor = this.getActorOrThrow(actorRef);
+
+    // TODO: Implement trigger registration
+    // This will involve registering the actor to listen for specific events
+
+    this.logDebug('Actor trigger registered', {
+      actorRef,
+      triggerType
+    });
+  }
+
+  /**
+   * Unregister actor from event trigger
+   */
+  public unregisterActorTrigger(actorRef: string, triggerType: string): void {
+    const actor = this.getActorOrThrow(actorRef);
+
+    // TODO: Implement trigger unregistration
+
+    this.logDebug('Actor trigger unregistered', {
+      actorRef,
+      triggerType
+    });
+  }
+
+  // ================================
+  // Debug Methods
+  // ================================
+
+  public getDebugInfo(): {
+    totalActors: number;
+    activeActors: number;
+    actorRefs: string[];
+  } {
+    const allActors = this.flowsActorsRegistry.getActors();
+    const activeActors = allActors.filter(a => a.status === FlowActorSystem_Status.ACTIVE);
+
+    return {
+      totalActors: allActors.length,
+      activeActors: activeActors.length,
+      actorRefs: allActors.map(a => a.ref),
+    };
+  }
+}
+