@wildo-ai/saas-backend-lib 1.0.1

package/src/flows-actors/services/__tests__/agent-facets-catalogs.test.ts

@@ -0,0 +1,544 @@
+/**
+ * Unit Tests for Agent Facets and Catalogs
+ * 
+ * Tests the facet composition system from AGENT_FACETS_AND_CATALOGS.md:
+ * - ConstraintsCatalog, InstructionsCatalog, HintsCatalog, etc.
+ * - AgentFacet interface and FacetCategory
+ * - AgentFacetsBackendService.composeFacets() static method
+ * - AgentFacetsBackendService.validateFacetComposition() conflict detection
+ * - AgentFacetsBackendService.resolveInheritance() for facet extends facet
+ * - AgentFacetsBackendService.createAgentFromFacets() for agent creation
+ * - Core facets and presets
+ */
+
+import 'reflect-metadata';
+import { z } from 'zod';
+import { ensureZodDecoratorsLoaded } from '@wildo-ai/zod-decorators';
+
+// Catalogs
+import {
+  ConstraintsCatalog,
+  InstructionsCatalog,
+  HintsCatalog,
+  OutOfScopeCatalog,
+  ModelPresetsCatalog,
+  ToolBundlesCatalog,
+  MCPBundlesCatalog,
+} from '~wildo-backend-lib/flows-actors/models/agent-catalogs.backend.definitions';
+
+// Facets infrastructure
+import {
+  AgentFacet,
+  FacetCategory,
+  ComposedAgentConfig,
+} from '~wildo-backend-lib/flows-actors/models/agent-facets.backend.definitions';
+import { AgentFacetsBackendService } from '~wildo-backend-lib/flows-actors/services/agent-facets.backend.service';
+
+// Core facets and presets
+import {
+  SecurityFacet,
+  StrictSecurityFacet,
+  PII_ProtectionFacet,
+  AuditTrailFacet,
+  ConfirmationGateFacet,
+  HighPrecisionFacet,
+  ConservativeFacet,
+  ThinkingModeFacet,
+  VerboseFacet,
+  SuccinctFacet,
+  SecurityAnalysisFacet,
+  MCPCodeAssistantFacet,
+  DataAnalysisFacet,
+  CriticalOperationPreset,
+  SecurityReviewerPreset,
+  CodeAssistantPreset,
+  DataAnalystPreset,
+} from '~wildo-backend-lib/flows-actors/models/core-facets.backend.definitions';
+
+// Schema types
+import {
+  FlowsActors_Agent_ConstraintType,
+  FlowsActors_Agent_Skill_Type,
+  FlowsActors_Agent_UncertaintyPolicy,
+} from '@wildo-ai/saas-models';
+
+// Ensure decorators are loaded
+beforeAll(() => {
+  ensureZodDecoratorsLoaded(z);
+});
+
+// =============================================================================
+// CATALOGS TESTS
+// =============================================================================
+
+describe('Catalogs', () => {
+  describe('ConstraintsCatalog', () => {
+    it('should have security constraints', () => {
+      expect(ConstraintsCatalog.NO_CREDENTIAL_EXPOSURE).toBeDefined();
+      expect(ConstraintsCatalog.NO_CREDENTIAL_EXPOSURE.id).toBe('sec-no-creds');
+      expect(ConstraintsCatalog.NO_CREDENTIAL_EXPOSURE.type).toBe(FlowsActors_Agent_ConstraintType.SECURITY);
+      expect(ConstraintsCatalog.NO_CREDENTIAL_EXPOSURE.onViolation).toBe('refuse');
+    });
+
+    it('should have privacy constraints', () => {
+      expect(ConstraintsCatalog.NO_PII_OUTPUT).toBeDefined();
+      expect(ConstraintsCatalog.NO_PII_OUTPUT.type).toBe(FlowsActors_Agent_ConstraintType.PRIVACY);
+    });
+
+    it('should have safety constraints', () => {
+      expect(ConstraintsCatalog.CONFIRM_BEFORE_DESTRUCTIVE).toBeDefined();
+      expect(ConstraintsCatalog.CONFIRM_BEFORE_DESTRUCTIVE.type).toBe(FlowsActors_Agent_ConstraintType.SAFETY);
+    });
+
+    it('should have scope constraints', () => {
+      expect(ConstraintsCatalog.STAY_IN_TASK_BOUNDS).toBeDefined();
+      expect(ConstraintsCatalog.STAY_IN_TASK_BOUNDS.type).toBe(FlowsActors_Agent_ConstraintType.SCOPE);
+    });
+
+    it('should have compliance constraints', () => {
+      expect(ConstraintsCatalog.DOCUMENT_ALL_ACTIONS).toBeDefined();
+      expect(ConstraintsCatalog.DOCUMENT_ALL_ACTIONS.type).toBe(FlowsActors_Agent_ConstraintType.COMPLIANCE);
+    });
+  });
+
+  describe('InstructionsCatalog', () => {
+    it('should have structure instructions', () => {
+      expect(InstructionsCatalog.USE_CONSISTENT_STRUCTURE).toBeDefined();
+      expect(typeof InstructionsCatalog.USE_CONSISTENT_STRUCTURE).toBe('string');
+    });
+
+    it('should have quality instructions', () => {
+      expect(InstructionsCatalog.VERIFY_BEFORE_ASSERTING).toBeDefined();
+    });
+
+    it('should have domain-specific instructions', () => {
+      expect(InstructionsCatalog.FOCUS_OWASP_TOP_10).toBeDefined();
+      expect(InstructionsCatalog.IDENTIFY_PATTERNS).toBeDefined();
+    });
+  });
+
+  describe('HintsCatalog', () => {
+    it('should have behavior preference hints', () => {
+      expect(HintsCatalog.PREFER_ACCURACY_OVER_SPEED).toBeDefined();
+      expect(HintsCatalog.ASK_RATHER_THAN_ASSUME).toBeDefined();
+    });
+
+    it('should have communication hints', () => {
+      expect(HintsCatalog.BE_DIRECT).toBeDefined();
+      expect(HintsCatalog.USE_EXAMPLES).toBeDefined();
+    });
+  });
+
+  describe('OutOfScopeCatalog', () => {
+    it('should have security scope boundaries', () => {
+      expect(OutOfScopeCatalog.NO_EXPLOIT_CODE).toBeDefined();
+      expect(OutOfScopeCatalog.NO_EXECUTE_CODE).toBeDefined();
+    });
+
+    it('should have operations scope boundaries', () => {
+      expect(OutOfScopeCatalog.NO_AUTO_EXECUTE).toBeDefined();
+      expect(OutOfScopeCatalog.NO_PROD_MODIFY).toBeDefined();
+    });
+  });
+
+  describe('ModelPresetsCatalog', () => {
+    it('should have precision presets', () => {
+      expect(ModelPresetsCatalog.DETERMINISTIC).toBeDefined();
+      expect(ModelPresetsCatalog.DETERMINISTIC.temperature).toBe(0);
+    });
+
+    it('should have creative presets', () => {
+      expect(ModelPresetsCatalog.CREATIVE).toBeDefined();
+      expect(ModelPresetsCatalog.CREATIVE.temperature).toBe(0.8);
+    });
+
+    it('should have specialized presets', () => {
+      expect(ModelPresetsCatalog.THINKING_MODE).toBeDefined();
+      expect(ModelPresetsCatalog.THINKING_MODE.thinkingEnabled).toBe(true);
+    });
+  });
+
+  describe('ToolBundlesCatalog', () => {
+    it('should have tool bundles with functionRefs', () => {
+      expect(ToolBundlesCatalog.SECURITY_ANALYSIS).toBeDefined();
+      expect(ToolBundlesCatalog.SECURITY_ANALYSIS.functionRefs).toContain('security-scanner');
+    });
+  });
+
+  describe('MCPBundlesCatalog', () => {
+    it('should have MCP bundles with mcpRefs', () => {
+      expect(MCPBundlesCatalog.CODE_ASSISTANT).toBeDefined();
+      expect(MCPBundlesCatalog.CODE_ASSISTANT.mcpRefs).toContain('filesystem-mcp');
+    });
+  });
+});
+
+// =============================================================================
+// FACET REGISTRY TESTS
+// =============================================================================
+
+describe('Facet Registry', () => {
+  it('should register and retrieve facets', () => {
+    const testFacet: AgentFacet = {
+      id: 'test-registry-facet',
+      name: 'Test Registry Facet',
+      description: 'For testing registry',
+      category: FacetCategory.QUALITY,
+    };
+    
+    AgentFacetsBackendService.registerFacet(testFacet);
+    const retrieved = AgentFacetsBackendService.getFacet('test-registry-facet');
+    
+    expect(retrieved).toBeDefined();
+    expect(retrieved?.name).toBe('Test Registry Facet');
+  });
+
+  it('should return all registered facets', () => {
+    const allFacets = AgentFacetsBackendService.getAllFacets();
+    expect(allFacets.length).toBeGreaterThan(0);
+    
+    // Should include core facets
+    const facetIds = allFacets.map(f => f.id);
+    expect(facetIds).toContain('security-core');
+    expect(facetIds).toContain('audit-trail');
+    expect(facetIds).toContain('high-precision');
+  });
+});
+
+// =============================================================================
+// FACET VALIDATION TESTS
+// =============================================================================
+
+describe('validateFacetComposition', () => {
+  it('should pass for non-conflicting facets', () => {
+    expect(() => {
+      AgentFacetsBackendService.validateFacetComposition([SecurityFacet, AuditTrailFacet, HighPrecisionFacet]);
+    }).not.toThrow();
+  });
+
+  it('should throw for conflicting facets', () => {
+    expect(() => {
+      AgentFacetsBackendService.validateFacetComposition([VerboseFacet, SuccinctFacet]);
+    }).toThrow(/Facet conflict/);
+  });
+
+  it('should detect conflict in either direction', () => {
+    expect(() => {
+      AgentFacetsBackendService.validateFacetComposition([SuccinctFacet, VerboseFacet]);
+    }).toThrow(/Facet conflict/);
+  });
+});
+
+// =============================================================================
+// FACET INHERITANCE TESTS
+// =============================================================================
+
+describe('resolveInheritance', () => {
+  it('should return facet unchanged if no extends', () => {
+    const resolved = AgentFacetsBackendService.resolveInheritance(SecurityFacet);
+    expect(resolved.id).toBe('security-core');
+    expect(resolved.promptSpec?.constraints).toHaveLength(2);
+  });
+
+  it('should merge parent facet when extends is set', () => {
+    const resolved = AgentFacetsBackendService.resolveInheritance(StrictSecurityFacet);
+    
+    // Should have parent's constraints + own constraints
+    expect(resolved.promptSpec?.constraints).toBeDefined();
+    const constraints = resolved.promptSpec!.constraints!;
+    expect(constraints.length).toBeGreaterThanOrEqual(2); // Parent + own
+    
+    // Should have own uncertainty policy
+    expect(resolved.promptSpec?.uncertainty?.policy).toBe(FlowsActors_Agent_UncertaintyPolicy.FAIL);
+    
+    // Should have own config
+    expect(resolved.config?.temperature).toBe(0);
+  });
+
+  it('should throw for unknown parent facet', () => {
+    const orphanFacet: AgentFacet = {
+      id: 'orphan',
+      name: 'Orphan',
+      description: 'Has unknown parent',
+      category: FacetCategory.QUALITY,
+      extends: 'non-existent-parent',
+    };
+
+    expect(() => {
+      AgentFacetsBackendService.resolveInheritance(orphanFacet);
+    }).toThrow(/extends unknown facet/);
+  });
+});
+
+// =============================================================================
+// COMPOSE FACETS TESTS
+// =============================================================================
+
+describe('composeFacets', () => {
+  it('should merge promptSpec aspects from multiple facets', () => {
+    const composed = AgentFacetsBackendService.composeFacets([SecurityFacet, AuditTrailFacet]);
+
+    // Constraints should be merged
+    expect(composed.promptSpec.constraints).toBeDefined();
+    expect(composed.promptSpec.constraints!.length).toBeGreaterThan(2);
+
+    // Instructions from AuditTrailFacet
+    expect(composed.promptSpec.instructions).toContain(InstructionsCatalog.LOG_DECISION_RATIONALE);
+  });
+
+  it('should merge config aspects', () => {
+    const composed = AgentFacetsBackendService.composeFacets([HighPrecisionFacet, ThinkingModeFacet]);
+
+    // DETERMINISTIC config from HighPrecisionFacet
+    expect(composed.config.temperature).toBe(0);
+    
+    // THINKING_MODE from ThinkingModeFacet
+    expect(composed.config.thinkingEnabled).toBe(true);
+  });
+
+  it('should merge capabilities', () => {
+    const composed = AgentFacetsBackendService.composeFacets([SecurityAnalysisFacet, MCPCodeAssistantFacet]);
+
+    // Tool bundles from SecurityAnalysisFacet
+    expect(composed.capabilities.tools.functionRefs).toContain('security-scanner');
+    
+    // MCP bundles from MCPCodeAssistantFacet
+    expect(composed.capabilities.tools.mcpRefs).toContain('filesystem-mcp');
+  });
+
+  it('should apply overrides', () => {
+    const composed = AgentFacetsBackendService.composeFacets([SecurityFacet], {
+      promptSpec: {
+        hints: ['Custom hint'],
+      },
+    });
+
+    expect(composed.promptSpec.hints).toContain('Custom hint');
+  });
+
+  it('should deduplicate constraints by id', () => {
+    // Create facets with duplicate constraint
+    const facet1: AgentFacet = {
+      id: 'dedup-test-1',
+      name: 'Dedup Test 1',
+      description: 'Test',
+      category: FacetCategory.SECURITY,
+      promptSpec: {
+        constraints: [ConstraintsCatalog.NO_CREDENTIAL_EXPOSURE],
+      },
+    };
+    const facet2: AgentFacet = {
+      id: 'dedup-test-2',
+      name: 'Dedup Test 2',
+      description: 'Test',
+      category: FacetCategory.SECURITY,
+      promptSpec: {
+        constraints: [ConstraintsCatalog.NO_CREDENTIAL_EXPOSURE], // Duplicate
+      },
+    };
+
+    const composed = AgentFacetsBackendService.composeFacets([facet1, facet2]);
+    
+    // Should only have one instance
+    const constraintIds = composed.promptSpec.constraints!.map(c => c.id);
+    const uniqueIds = [...new Set(constraintIds)];
+    expect(constraintIds.length).toBe(uniqueIds.length);
+  });
+
+  it('should deduplicate instructions', () => {
+    const facet1: AgentFacet = {
+      id: 'instr-test-1',
+      name: 'Instr Test 1',
+      description: 'Test',
+      category: FacetCategory.QUALITY,
+      promptSpec: {
+        instructions: ['Do X', 'Do Y'],
+      },
+    };
+    const facet2: AgentFacet = {
+      id: 'instr-test-2',
+      name: 'Instr Test 2',
+      description: 'Test',
+      category: FacetCategory.QUALITY,
+      promptSpec: {
+        instructions: ['Do Y', 'Do Z'], // 'Do Y' is duplicate
+      },
+    };
+
+    const composed = AgentFacetsBackendService.composeFacets([facet1, facet2]);
+    expect(composed.promptSpec.instructions).toEqual(['Do X', 'Do Y', 'Do Z']);
+  });
+});
+
+// =============================================================================
+// CREATE AGENT FROM FACETS TESTS
+// =============================================================================
+
+describe('createAgentFromFacets', () => {
+  it('should create FacetBuiltAgent with required fields', () => {
+    const built = AgentFacetsBackendService.createAgentFromFacets(
+      {
+        ref: 'test-agent',
+        displayName: 'Test Agent',
+        role: 'Test role description',
+        skillType: FlowsActors_Agent_Skill_Type.ANALYSIS,
+      },
+      [SecurityFacet, HighPrecisionFacet]
+    );
+
+    expect(built.ref).toBe('test-agent');
+    expect(built.displayName).toBe('Test Agent');
+    expect(built.promptSpec.role).toBe('Test role description');
+    expect(built.promptSpec.skillType).toBe(FlowsActors_Agent_Skill_Type.ANALYSIS);
+  });
+
+  it('should include facet constraints in promptSpec', () => {
+    const built = AgentFacetsBackendService.createAgentFromFacets(
+      {
+        ref: 'secure-agent',
+        displayName: 'Secure Agent',
+        role: 'Secure operations',
+        skillType: FlowsActors_Agent_Skill_Type.DECISION,
+      },
+      [SecurityFacet]
+    );
+
+    expect(built.promptSpec.constraints).toBeDefined();
+    expect(built.promptSpec.constraints!.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('should include configOverrides from facets', () => {
+    const built = AgentFacetsBackendService.createAgentFromFacets(
+      {
+        ref: 'precise-agent',
+        displayName: 'Precise Agent',
+        role: 'Precise calculations',
+        skillType: FlowsActors_Agent_Skill_Type.TRANSFORMATION,
+      },
+      [HighPrecisionFacet]
+    );
+
+    expect(built.configOverrides.temperature).toBe(0);
+  });
+
+  it('should include capabilities from facets', () => {
+    const built = AgentFacetsBackendService.createAgentFromFacets(
+      {
+        ref: 'tooled-agent',
+        displayName: 'Tooled Agent',
+        role: 'Uses tools',
+        skillType: FlowsActors_Agent_Skill_Type.CUSTOM,
+      },
+      [SecurityAnalysisFacet]
+    );
+
+    expect(built.capabilities.tools.functionRefs).toContain('security-scanner');
+  });
+});
+
+// =============================================================================
+// CORE FACETS TESTS
+// =============================================================================
+
+describe('Core Facets', () => {
+  describe('Security Facets', () => {
+    it('SecurityFacet should have core security constraints', () => {
+      expect(SecurityFacet.category).toBe(FacetCategory.SECURITY);
+      expect(SecurityFacet.promptSpec?.constraints).toBeDefined();
+    });
+
+    it('StrictSecurityFacet should extend SecurityFacet', () => {
+      expect(StrictSecurityFacet.extends).toBe('security-core');
+    });
+
+    it('PII_ProtectionFacet should have privacy constraints', () => {
+      expect(PII_ProtectionFacet.promptSpec?.constraints).toBeDefined();
+      const hasPrivacy = PII_ProtectionFacet.promptSpec!.constraints!.some(
+        c => c.type === FlowsActors_Agent_ConstraintType.PRIVACY
+      );
+      expect(hasPrivacy).toBe(true);
+    });
+  });
+
+  describe('Compliance Facets', () => {
+    it('AuditTrailFacet should include output requirements', () => {
+      expect(AuditTrailFacet.promptSpec?.output?.includeReasoning).toBe(true);
+      expect(AuditTrailFacet.promptSpec?.output?.requiredSections).toContain('actions_taken');
+    });
+
+    it('ConfirmationGateFacet should have ASK policy', () => {
+      expect(ConfirmationGateFacet.promptSpec?.uncertainty?.policy).toBe(
+        FlowsActors_Agent_UncertaintyPolicy.ASK
+      );
+    });
+  });
+
+  describe('Quality Facets', () => {
+    it('HighPrecisionFacet should have deterministic config', () => {
+      expect(HighPrecisionFacet.config?.temperature).toBe(0);
+    });
+
+    it('ConservativeFacet should conflict with aggressive', () => {
+      expect(ConservativeFacet.conflictsWith).toContain('aggressive');
+    });
+
+    it('ThinkingModeFacet should enable thinking', () => {
+      expect(ThinkingModeFacet.config?.thinkingEnabled).toBe(true);
+    });
+  });
+
+  describe('Output Facets', () => {
+    it('VerboseFacet and SuccinctFacet should conflict', () => {
+      expect(VerboseFacet.conflictsWith).toContain('succinct');
+      expect(SuccinctFacet.conflictsWith).toContain('verbose');
+    });
+  });
+
+  describe('Domain Facets', () => {
+    it('SecurityAnalysisFacet should have tools and instructions', () => {
+      expect(SecurityAnalysisFacet.capabilities?.tools?.functionRefs).toBeDefined();
+      expect(SecurityAnalysisFacet.promptSpec?.instructions).toContain(
+        InstructionsCatalog.FOCUS_OWASP_TOP_10
+      );
+    });
+
+    it('MCPCodeAssistantFacet should have MCP refs', () => {
+      expect(MCPCodeAssistantFacet.capabilities?.tools?.mcpRefs).toBeDefined();
+      expect(MCPCodeAssistantFacet.config?.toolingFunctionEnabled).toBe(true);
+    });
+  });
+});
+
+// =============================================================================
+// PRESETS TESTS
+// =============================================================================
+
+describe('Presets', () => {
+  it('CriticalOperationPreset should combine security and precision facets', () => {
+    expect(CriticalOperationPreset).toHaveLength(4);
+    expect(CriticalOperationPreset).toContain(SecurityFacet);
+    expect(CriticalOperationPreset).toContain(HighPrecisionFacet);
+  });
+
+  it('SecurityReviewerPreset should use strict security', () => {
+    expect(SecurityReviewerPreset).toContain(StrictSecurityFacet);
+    expect(SecurityReviewerPreset).toContain(SecurityAnalysisFacet);
+  });
+
+  it('CodeAssistantPreset should include MCP tools', () => {
+    expect(CodeAssistantPreset).toContain(MCPCodeAssistantFacet);
+    expect(CodeAssistantPreset).toContain(ThinkingModeFacet);
+  });
+
+  it('DataAnalystPreset should include PII protection', () => {
+    expect(DataAnalystPreset).toContain(PII_ProtectionFacet);
+    expect(DataAnalystPreset).toContain(DataAnalysisFacet);
+  });
+
+  it('presets should compose without conflicts', () => {
+    expect(() => AgentFacetsBackendService.composeFacets(CriticalOperationPreset)).not.toThrow();
+    expect(() => AgentFacetsBackendService.composeFacets(SecurityReviewerPreset)).not.toThrow();
+    expect(() => AgentFacetsBackendService.composeFacets(CodeAssistantPreset)).not.toThrow();
+    expect(() => AgentFacetsBackendService.composeFacets(DataAnalystPreset)).not.toThrow();
+  });
+});