@wildo-ai/saas-backend-lib 1.0.1

package/src/flows-actors/agent-catalogs.backend.ts

@@ -0,0 +1,427 @@
+/**
+ * Agent Catalogs - Reusable atomic elements for agent composition
+ * 
+ * Catalogs provide typed, reusable building blocks:
+ * - ConstraintsCatalog: Security, privacy, safety, scope, compliance constraints
+ * - InstructionsCatalog: Behavioral instruction strings
+ * - HintsCatalog: Soft guidance preferences
+ * - OutOfScopeCatalog: Explicit scope boundaries
+ * - ModelPresetsCatalog: LLM configuration presets
+ * - ToolBundlesCatalog: Tool function bundles
+ * - MCPBundlesCatalog: MCP server bundles
+ * 
+ * @see AGENT_FACETS_AND_CATALOGS.md for design documentation
+ */
+
+import { FlowsActors_Agent_ConstraintType } from '@wildo-ai/saas-models';
+
+
+//===============================================================
+// CONSTRAINTS CATALOG
+//===============================================================
+
+export const ConstraintsCatalog = {
+  //===================
+  // SECURITY
+  //===================
+  
+  NO_CREDENTIAL_EXPOSURE: {
+    id: "sec-no-creds",
+    text: "Never expose credentials, API keys, secrets, or internal system details in output",
+    type: FlowsActors_Agent_ConstraintType.SECURITY,
+    onViolation: "refuse" as const,
+  },
+  
+  NO_SECRET_LOGGING: {
+    id: "sec-no-log-secrets",
+    text: "Never log, store, or transmit sensitive credentials or tokens",
+    type: FlowsActors_Agent_ConstraintType.SECURITY,
+    onViolation: "refuse" as const,
+  },
+  
+  NO_BYPASS_SECURITY: {
+    id: "sec-no-bypass",
+    text: "Never suggest bypassing or weakening security controls",
+    type: FlowsActors_Agent_ConstraintType.SECURITY,
+    onViolation: "refuse" as const,
+  },
+  
+  ANALYSIS_ONLY: {
+    id: "sec-analysis-only",
+    text: "Only analyze code, never execute, run, or test it",
+    type: FlowsActors_Agent_ConstraintType.SECURITY,
+    onViolation: "refuse" as const,
+  },
+  
+  //===================
+  // PRIVACY
+  //===================
+  
+  NO_PII_OUTPUT: {
+    id: "priv-no-pii",
+    text: "Do not include or expose personally identifiable information (PII) in output",
+    type: FlowsActors_Agent_ConstraintType.PRIVACY,
+    onViolation: "refuse" as const,
+  },
+  
+  ANONYMIZE_EXAMPLES: {
+    id: "priv-anon-examples",
+    text: "Always anonymize any examples that could identify individuals",
+    type: FlowsActors_Agent_ConstraintType.PRIVACY,
+    onViolation: "warn" as const,
+  },
+  
+  //===================
+  // SAFETY
+  //===================
+  
+  CONFIRM_BEFORE_DESTRUCTIVE: {
+    id: "safe-confirm-destructive",
+    text: "Always require explicit confirmation before destructive or irreversible actions",
+    type: FlowsActors_Agent_ConstraintType.SAFETY,
+    onViolation: "refuse" as const,
+  },
+  
+  NO_PRODUCTION_CHANGES_UNATTENDED: {
+    id: "safe-no-prod-unattended",
+    text: "Never modify production systems without explicit user approval",
+    type: FlowsActors_Agent_ConstraintType.SAFETY,
+    onViolation: "refuse" as const,
+  },
+  
+  VERIFY_PREREQUISITES: {
+    id: "safe-verify-prereqs",
+    text: "Verify all prerequisites before proceeding with any operation",
+    type: FlowsActors_Agent_ConstraintType.SAFETY,
+    onViolation: "warn" as const,
+  },
+  
+  //===================
+  // SCOPE
+  //===================
+  
+  STAY_IN_TASK_BOUNDS: {
+    id: "scope-task-bounds",
+    text: "Only operate within the explicitly defined task boundaries",
+    type: FlowsActors_Agent_ConstraintType.SCOPE,
+    onViolation: "warn" as const,
+  },
+  
+  NO_SCOPE_CREEP: {
+    id: "scope-no-creep",
+    text: "Do not add features or functionality not explicitly requested",
+    type: FlowsActors_Agent_ConstraintType.SCOPE,
+    onViolation: "warn" as const,
+  },
+  
+  SINGLE_RESPONSIBILITY: {
+    id: "scope-single-resp",
+    text: "Focus on the specific task, do not attempt to solve adjacent problems",
+    type: FlowsActors_Agent_ConstraintType.SCOPE,
+    onViolation: "warn" as const,
+  },
+  
+  //===================
+  // COMPLIANCE
+  //===================
+  
+  DOCUMENT_ALL_ACTIONS: {
+    id: "comp-doc-actions",
+    text: "Document every action taken for audit purposes",
+    type: FlowsActors_Agent_ConstraintType.COMPLIANCE,
+    onViolation: "warn" as const,
+  },
+  
+  FOLLOW_DATA_RETENTION: {
+    id: "comp-data-retention",
+    text: "Adhere to data retention policies - do not persist data beyond required scope",
+    type: FlowsActors_Agent_ConstraintType.COMPLIANCE,
+    onViolation: "warn" as const,
+  },
+  
+} as const;
+
+export type ConstraintId = keyof typeof ConstraintsCatalog;
+
+
+//===============================================================
+// INSTRUCTIONS CATALOG
+//===============================================================
+
+export const InstructionsCatalog = {
+  //===================
+  // STRUCTURE
+  //===================
+  
+  USE_CONSISTENT_STRUCTURE: "Present output in a structured, consistent format",
+  CITE_SOURCES: "Cite specific sources or evidence for all claims",
+  SHOW_REASONING: "Explain the reasoning behind conclusions",
+  SUMMARIZE_FIRST: "Start with a brief summary before detailed analysis",
+  
+  //===================
+  // QUALITY
+  //===================
+  
+  VERIFY_BEFORE_ASSERTING: "Verify information before making assertions",
+  ACKNOWLEDGE_LIMITATIONS: "Acknowledge limitations and areas of uncertainty",
+  PREFER_SIMPLICITY: "Prefer simpler solutions over complex ones when equivalent",
+  AVOID_JARGON: "Avoid unnecessary jargon; explain technical terms when used",
+  
+  //===================
+  // SAFETY
+  //===================
+  
+  LOG_DECISION_RATIONALE: "Log the rationale for each significant decision",
+  VALIDATE_INPUTS: "Validate all inputs before processing",
+  CHECK_OUTPUTS: "Verify outputs match expected format before returning",
+  
+  //===================
+  // PRIVACY
+  //===================
+  
+  REDACT_PII_IN_OUTPUT: "Redact any PII (names, emails, phone numbers) in output",
+  USE_SYNTHETIC_DATA: "Use synthetic data for examples instead of real data",
+  
+  //===================
+  // DOMAIN: Security
+  //===================
+  
+  FOCUS_OWASP_TOP_10: "Focus on OWASP Top 10 vulnerabilities when reviewing security",
+  PROVIDE_REMEDIATION: "Provide specific remediation steps for each finding",
+  RATE_SEVERITY: "Rate each finding by severity (Critical, High, Medium, Low, Info)",
+  
+  //===================
+  // DOMAIN: Data Analysis
+  //===================
+  
+  IDENTIFY_PATTERNS: "Identify key themes and patterns in the provided content",
+  SUPPORT_WITH_EVIDENCE: "Support findings with specific evidence from the input",
+  QUANTIFY_WHEN_POSSIBLE: "Quantify findings with metrics when possible",
+  
+  //===================
+  // DOMAIN: Operations
+  //===================
+  
+  DOCUMENT_EACH_STEP: "Document each step of the operation for audit purposes",
+  VALIDATE_OUTCOMES: "Validate outcomes against expected results",
+  STATE_IMPACT_BEFORE_ACTION: "Before any action, clearly state what will happen",
+  
+} as const;
+
+export type InstructionId = keyof typeof InstructionsCatalog;
+
+
+//===============================================================
+// HINTS CATALOG
+//===============================================================
+
+export const HintsCatalog = {
+  //===================
+  // BEHAVIOR PREFERENCES
+  //===================
+  
+  PREFER_ACCURACY_OVER_SPEED: "When in doubt, prefer accuracy over speed",
+  PREFER_REVERSIBLE_ACTIONS: "Prefer reversible actions over irreversible ones",
+  FAIL_SAFE_ON_UNCERTAINTY: "When uncertain, fail safely rather than guess",
+  ASK_RATHER_THAN_ASSUME: "Ask for clarification rather than making assumptions",
+  DOCUMENT_ASSUMPTIONS: "Document any assumptions you make",
+  
+  //===================
+  // COMMUNICATION
+  //===================
+  
+  BE_DIRECT: "Be direct and get to the point quickly",
+  USE_EXAMPLES: "Use examples to clarify complex concepts",
+  MATCH_USER_TONE: "Match the formality level of the user's request",
+  ANTICIPATE_FOLLOW_UPS: "Anticipate likely follow-up questions",
+  
+  //===================
+  // QUALITY
+  //===================
+  
+  DOUBLE_CHECK_CRITICAL: "Double-check critical calculations and facts",
+  CONSIDER_EDGE_CASES: "Consider edge cases in your analysis",
+  TEST_YOUR_LOGIC: "Walk through your logic step by step",
+  
+} as const;
+
+export type HintId = keyof typeof HintsCatalog;
+
+
+//===============================================================
+// OUT OF SCOPE CATALOG
+//===============================================================
+
+export const OutOfScopeCatalog = {
+  //===================
+  // SECURITY
+  //===================
+  
+  NO_EXPLOIT_CODE: "Do not provide exploit code or proof-of-concept attacks",
+  NO_SECURITY_BYPASS_ADVICE: "Do not advise on bypassing security measures",
+  NO_EXECUTE_CODE: "Do not execute or run any code",
+  
+  //===================
+  // OPERATIONS
+  //===================
+  
+  NO_AUTO_EXECUTE: "Do not auto-execute without explicit confirmation",
+  NO_PROD_MODIFY: "Do not modify production data without explicit approval",
+  
+  //===================
+  // SCOPE
+  //===================
+  
+  NO_ADJACENT_PROBLEMS: "Do not solve problems outside the requested scope",
+  NO_FEATURE_CREEP: "Do not add features not explicitly requested",
+  
+} as const;
+
+export type OutOfScopeId = keyof typeof OutOfScopeCatalog;
+
+
+//===============================================================
+// MODEL PRESETS CATALOG
+//===============================================================
+
+export const ModelPresetsCatalog = {
+  //===================
+  // PRECISION
+  //===================
+  
+  /**
+   * Deterministic output with zero randomness
+   * Note: Use agent-level config.seed for reproducible outputs if needed
+   */
+  DETERMINISTIC: {
+    temperature: 0,
+  },
+  
+  LOW_CREATIVITY: {
+    temperature: 0.2,
+    topP: 0.9,
+  },
+  
+  //===================
+  // CREATIVE
+  //===================
+  
+  BALANCED: {
+    temperature: 0.5,
+    topP: 0.95,
+  },
+  
+  CREATIVE: {
+    temperature: 0.8,
+    topP: 1.0,
+  },
+  
+  HIGH_CREATIVITY: {
+    temperature: 1.0,
+    topP: 1.0,
+  },
+  
+  //===================
+  // SPECIALIZED
+  //===================
+  
+  THINKING_MODE: {
+    thinkingEnabled: true,
+  },
+  
+  TOOLING_ENABLED: {
+    toolingFunctionEnabled: true,
+  },
+  
+  MCP_COMPATIBLE: {
+    mcpCompatible: true,
+  },
+  
+  CODE_GENERATION: {
+    temperature: 0.2,
+    frequencyPenalty: 0.1,
+  },
+  
+} as const;
+
+export type ModelPresetId = keyof typeof ModelPresetsCatalog;
+
+
+//===============================================================
+// TOOL BUNDLES CATALOG
+//===============================================================
+
+export const ToolBundlesCatalog = {
+  //===================
+  // SECURITY
+  //===================
+  
+  SECURITY_ANALYSIS: {
+    functionRefs: ["security-scanner", "dependency-checker", "secrets-detector"],
+  },
+  
+  //===================
+  // CODE
+  //===================
+  
+  CODE_REVIEW: {
+    functionRefs: ["linter", "formatter", "complexity-analyzer"],
+  },
+  
+  CODE_GENERATION: {
+    functionRefs: ["code-generator", "test-generator", "doc-generator"],
+  },
+  
+  //===================
+  // DATA
+  //===================
+  
+  DATA_ANALYSIS: {
+    functionRefs: ["data-query", "chart-generator", "stats-calculator"],
+  },
+  
+  //===================
+  // OPERATIONS
+  //===================
+  
+  DEPLOYMENT: {
+    functionRefs: ["kubectl-runner", "health-checker", "rollback-trigger"],
+  },
+  
+} as const;
+
+export type ToolBundleId = keyof typeof ToolBundlesCatalog;
+
+
+//===============================================================
+// MCP BUNDLES CATALOG
+//===============================================================
+
+export const MCPBundlesCatalog = {
+  //===================
+  // DEVELOPMENT
+  //===================
+  
+  CODE_ASSISTANT: {
+    mcpRefs: ["filesystem-mcp", "code-editor-mcp", "git-mcp"],
+  },
+  
+  //===================
+  // BROWSER
+  //===================
+  
+  WEB_AUTOMATION: {
+    mcpRefs: ["browser-mcp", "screenshot-mcp"],
+  },
+  
+  //===================
+  // DATABASE
+  //===================
+  
+  DATABASE_ACCESS: {
+    mcpRefs: ["mongodb-mcp", "postgres-mcp"],
+  },
+  
+} as const;
+
+export type MCPBundleId = keyof typeof MCPBundlesCatalog;

package/src/flows-actors/controllers/flows-actors.controller.ts

@@ -0,0 +1,91 @@
+import 'reflect-metadata';
+import { injectable, inject } from 'inversify';
+import { Request, Response, NextFunction } from 'express';
+import { AbstractControllerBackendService } from '~wildo-backend-lib/base-classes/services/controllers/abstract-controller.backend.service';
+import { FlowsActorsRegistryService } from '~wildo-backend-lib/flows-actors/services/flows-actors-registry.service';
+import { extractAllFrontendVisibleSystemsInfo } from '~wildo-backend-lib/flows-actors/utils/flows-actors-frontend-extractor.utils';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { ErrorHandlerService } from '~wildo-backend-lib/errors/services/error-handler.backend.service';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { FlowsActors_FrontendInfoResponse, FlowActorSystem_Kind } from '@wildo-ai/saas-models';
+
+/**
+ * FlowsActors Controller Backend Service
+ *
+ * Provides HTTP endpoints for the FlowsActors system frontend integration.
+ *
+ * Endpoints:
+ * - GET /frontend-info - Returns frontend-visible FlowActorSystems with extracted config
+ */
+
+@injectable()
+export class FlowsActorsControllerBackendService extends AbstractControllerBackendService {
+
+  private readonly flowsActorsRegistry: FlowsActorsRegistryService;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.ErrorHandlerService) errorHandler: ErrorHandlerService,
+    @inject(SAAS_SERVICE_TYPES.FlowsActorsRegistryService) flowsActorsRegistry: FlowsActorsRegistryService
+  ) {
+    super(logger, errorBuilder, errorHandler, 'FlowsActorsController');
+    this.flowsActorsRegistry = flowsActorsRegistry;
+  }
+
+  /**
+   * Custom mount path for this controller
+   * Overrides default /api/custom/<controller-name> pattern
+   */
+  public getCustomMountBasePath(): string {
+    return '/api/flows-actors';
+  }
+
+  /**
+   * Setup routes for flows-actors endpoints
+   */
+  protected setupRoutes(): void {
+    // GET /frontend-info - Get frontend-visible flow actor systems
+    this.router.get('/frontend-info', this.asyncHandler(this.getFrontendInfo.bind(this)));
+
+    this.logRouteRegistration('GET', '/frontend-info', 'Get frontend-visible FlowActorSystems with extracted configuration');
+  }
+
+  /**
+   * Get frontend-visible FlowActorSystems
+   * Returns systems with visibility=FRONTEND and their extracted frontend-relevant config
+   */
+  private async getFrontendInfo(req: Request, res: Response, next: NextFunction): Promise<void> {
+    try {
+      this.logDebug('Getting frontend-visible flow actor systems');
+
+      // Get all systems (flows and actors)
+      const allFlows = this.flowsActorsRegistry.getFlows();
+      const allActors = this.flowsActorsRegistry.getActors();
+      const allSystems = [...allFlows, ...allActors];
+
+      // Extract frontend info for visible systems only
+      const frontendSystems = extractAllFrontendVisibleSystemsInfo(allSystems);
+
+      const response: FlowsActors_FrontendInfoResponse = {
+        systems: frontendSystems,
+      };
+
+      this.logDebug('Frontend info extracted', {
+        totalSystems: allSystems.length,
+        frontendVisibleCount: frontendSystems.length,
+        flowsCount: frontendSystems.filter(s => s.kind === FlowActorSystem_Kind.FLOW).length,
+        actorsCount: frontendSystems.filter(s => s.kind === FlowActorSystem_Kind.ACTOR).length,
+      });
+
+      this.jsonSuccess(res, response);
+
+    } catch (error) {
+      this.logDebug('Failed to get frontend info', {
+        error: error instanceof Error ? error.message : 'Unknown error'
+      });
+      throw error;
+    }
+  }
+}