@holoscript/framework 6.0.3

package/src/agents/__tests__/TaskDelegationService.test.ts

@@ -0,0 +1,446 @@
+/**
+ * TaskDelegationService Tests
+ *
+ * Tests cross-agent task forwarding (local + remote delegation).
+ * Part of HoloScript v5.5 "Agents as Universal Orchestrators".
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { TaskDelegationService, type DelegationRequest } from '../TaskDelegationService';
+import { AgentRegistry, resetDefaultRegistry } from '../AgentRegistry';
+import type { AgentManifest } from '../AgentManifest';
+
+// =============================================================================
+// FIXTURES
+// =============================================================================
+
+function makeLocalAgent(overrides: Partial<AgentManifest> = {}): AgentManifest {
+  return {
+    id: 'local-agent-1',
+    name: 'Local Agent',
+    version: '1.0.0',
+    capabilities: [{ type: 'analyze', domain: 'spatial' }],
+    endpoints: [{ protocol: 'local', address: 'local://agent-1', primary: true }],
+    trustLevel: 'local',
+    status: 'online',
+    ...overrides,
+  };
+}
+
+function makeRemoteAgent(overrides: Partial<AgentManifest> = {}): AgentManifest {
+  return {
+    id: 'remote-agent-1',
+    name: 'Remote Agent',
+    version: '1.0.0',
+    capabilities: [{ type: 'transform', domain: 'spatial' }],
+    endpoints: [{ protocol: 'https', address: 'https://remote.example.com/a2a', primary: true }],
+    trustLevel: 'external',
+    status: 'online',
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// TESTS
+// =============================================================================
+
+describe('TaskDelegationService', () => {
+  let registry: AgentRegistry;
+
+  beforeEach(() => {
+    resetDefaultRegistry();
+    registry = new AgentRegistry();
+  });
+
+  afterEach(() => {
+    registry.stop();
+    registry.clear();
+  });
+
+  describe('delegateTo', () => {
+    it('delegates to a local agent using localExecutor', async () => {
+      await registry.register(makeLocalAgent());
+
+      const service = new TaskDelegationService(registry, undefined, {
+        localExecutor: async (skillId, args) => ({
+          parsed: true,
+          skillId,
+          input: args.code,
+        }),
+      });
+
+      const result = await service.delegateTo({
+        targetAgentId: 'local-agent-1',
+        skillId: 'parse_hs',
+        arguments: { code: 'object Cube {}' },
+      });
+
+      expect(result.status).toBe('completed');
+      expect(result.delegatedTo.agentId).toBe('local-agent-1');
+      expect((result.result as Record<string, unknown>).parsed).toBe(true);
+      expect(result.durationMs).toBeGreaterThanOrEqual(0);
+    });
+
+    it('returns rejected for unknown agent ID', async () => {
+      const service = new TaskDelegationService(registry);
+
+      const result = await service.delegateTo({
+        targetAgentId: 'nonexistent',
+        skillId: 'test',
+        arguments: {},
+      });
+
+      expect(result.status).toBe('rejected');
+      expect(result.error).toContain('Agent not found');
+    });
+
+    it('delegates to a remote agent via A2A JSON-RPC', async () => {
+      await registry.register(makeRemoteAgent());
+
+      const service = new TaskDelegationService(registry, undefined, {
+        fetchFn: async () =>
+          ({
+            ok: true,
+            json: async () => ({
+              jsonrpc: '2.0',
+              id: 'test',
+              result: { status: 'completed', artifacts: [{ data: 'remote-result' }] },
+            }),
+          }) as Response,
+      });
+
+      const result = await service.delegateTo({
+        targetAgentId: 'remote-agent-1',
+        skillId: 'compile_hs',
+        arguments: { code: 'test', target: 'threejs' },
+      });
+
+      expect(result.status).toBe('completed');
+      expect(result.delegatedTo.endpoint).toBe('https://remote.example.com/a2a');
+    });
+
+    it('sends idempotency key header and payload for remote delegation', async () => {
+      await registry.register(makeRemoteAgent());
+
+      let capturedInit: RequestInit | undefined;
+      const service = new TaskDelegationService(registry, undefined, {
+        idempotencyKeyFactory: () => 'idem-fixed-key',
+        fetchFn: async (_url, init) => {
+          capturedInit = init;
+          return {
+            ok: true,
+            json: async () => ({ result: { status: 'completed' } }),
+          } as Response;
+        },
+      });
+
+      const result = await service.delegateTo({
+        targetAgentId: 'remote-agent-1',
+        skillId: 'compile_hs',
+        arguments: { code: 'x' },
+      });
+
+      expect(result.status).toBe('completed');
+      const headers = (capturedInit?.headers ?? {}) as Record<string, string>;
+      expect(headers['Idempotency-Key']).toBe('idem-fixed-key');
+
+      const body = JSON.parse(String(capturedInit?.body ?? '{}')) as {
+        params?: { message?: { parts?: Array<{ data?: Record<string, unknown> }> } };
+      };
+      const data = body.params?.message?.parts?.[0]?.data;
+      expect(data?.idempotencyKey).toBe('idem-fixed-key');
+      expect(data?.schema).toBe('holoscript.task-bridge.v1');
+      expect((data?.task as Record<string, unknown> | undefined)?.skillId).toBe('compile_hs');
+      expect((data?.task as Record<string, unknown> | undefined)?.idempotency_key).toBe('idem-fixed-key');
+    });
+
+    it('uses transport adapter when configured', async () => {
+      await registry.register(makeRemoteAgent());
+
+      const send = vi.fn(async () => ({ status: 'completed', via: 'adapter' }));
+      const service = new TaskDelegationService(registry, undefined, {
+        transportAdapter: { send },
+        idempotencyKeyFactory: () => 'adapter-idem',
+      });
+
+      const result = await service.delegateTo({
+        targetAgentId: 'remote-agent-1',
+        skillId: 'compile_hs',
+        arguments: { code: 'x' },
+      });
+
+      expect(result.status).toBe('completed');
+      expect(send).toHaveBeenCalledTimes(1);
+      expect(send.mock.calls[0][0].idempotencyKey).toBe('adapter-idem');
+    });
+
+    it('handles remote agent HTTP errors', async () => {
+      await registry.register(makeRemoteAgent());
+
+      const service = new TaskDelegationService(registry, undefined, {
+        fetchFn: async () => ({ ok: false, status: 500 }) as Response,
+      });
+
+      const result = await service.delegateTo({
+        targetAgentId: 'remote-agent-1',
+        skillId: 'test',
+        arguments: {},
+      });
+
+      expect(result.status).toBe('failed');
+      expect(result.error).toContain('500');
+    });
+
+    it('handles remote agent JSON-RPC errors', async () => {
+      await registry.register(makeRemoteAgent());
+
+      const service = new TaskDelegationService(registry, undefined, {
+        fetchFn: async () =>
+          ({
+            ok: true,
+            json: async () => ({
+              jsonrpc: '2.0',
+              error: { code: -32000, message: 'Skill not found' },
+            }),
+          }) as Response,
+      });
+
+      const result = await service.delegateTo({
+        targetAgentId: 'remote-agent-1',
+        skillId: 'nonexistent',
+        arguments: {},
+      });
+
+      expect(result.status).toBe('failed');
+      expect(result.error).toContain('Skill not found');
+    });
+
+    it('times out on slow execution', async () => {
+      await registry.register(makeLocalAgent());
+
+      const service = new TaskDelegationService(registry, undefined, {
+        localExecutor: async () => {
+          await new Promise((resolve) => setTimeout(resolve, 500));
+          return { result: 'too-slow' };
+        },
+      });
+
+      const result = await service.delegateTo({
+        targetAgentId: 'local-agent-1',
+        skillId: 'slow_skill',
+        arguments: {},
+        timeout: 50,
+      });
+
+      expect(result.status).toBe('timeout');
+      expect(result.error).toContain('timed out');
+    });
+
+    it('retries on failure with exponential backoff', async () => {
+      await registry.register(makeLocalAgent());
+
+      let callCount = 0;
+      const service = new TaskDelegationService(registry, undefined, {
+        localExecutor: async () => {
+          callCount++;
+          if (callCount < 3) throw new Error('Transient error');
+          return { success: true };
+        },
+      });
+
+      const result = await service.delegateTo({
+        targetAgentId: 'local-agent-1',
+        skillId: 'flaky_skill',
+        arguments: {},
+        retries: 2,
+      });
+
+      expect(result.status).toBe('completed');
+      expect(callCount).toBe(3);
+    }, 15000);
+
+    it('fails after exhausting retries', async () => {
+      await registry.register(makeLocalAgent());
+
+      const service = new TaskDelegationService(registry, undefined, {
+        localExecutor: async () => {
+          throw new Error('Persistent error');
+        },
+      });
+
+      const result = await service.delegateTo({
+        targetAgentId: 'local-agent-1',
+        skillId: 'broken_skill',
+        arguments: {},
+        retries: 1,
+      });
+
+      expect(result.status).toBe('failed');
+      expect(result.error).toBe('Persistent error');
+    });
+  });
+
+  describe('autoDelegate', () => {
+    it('auto-selects the best agent and delegates', async () => {
+      await registry.register(makeLocalAgent());
+
+      const service = new TaskDelegationService(registry, undefined, {
+        localExecutor: async (skillId) => ({ delegated: true, skillId }),
+      });
+
+      const result = await service.autoDelegate(
+        { type: 'analyze', domain: 'spatial' },
+        'parse_hs',
+        { code: 'test' }
+      );
+
+      expect(result.status).toBe('completed');
+      expect(result.delegatedTo.agentId).toBe('local-agent-1');
+    });
+
+    it('returns rejected when no matching agent found', async () => {
+      const service = new TaskDelegationService(registry);
+
+      const result = await service.autoDelegate(
+        { type: 'render', domain: 'vision' },
+        'test_skill',
+        {}
+      );
+
+      expect(result.status).toBe('rejected');
+      expect(result.error).toContain('No agent found');
+    });
+  });
+
+  describe('history tracking', () => {
+    it('tracks delegation results', async () => {
+      await registry.register(makeLocalAgent());
+
+      const service = new TaskDelegationService(registry, undefined, {
+        localExecutor: async () => ({ ok: true }),
+      });
+
+      await service.delegateTo({
+        targetAgentId: 'local-agent-1',
+        skillId: 'test',
+        arguments: {},
+      });
+
+      const history = service.getDelegationHistory();
+      expect(history).toHaveLength(1);
+      expect(history[0].status).toBe('completed');
+    });
+
+    it('getStatus retrieves result by taskId', async () => {
+      await registry.register(makeLocalAgent());
+
+      const service = new TaskDelegationService(registry, undefined, {
+        localExecutor: async () => ({ ok: true }),
+      });
+
+      const result = await service.delegateTo({
+        targetAgentId: 'local-agent-1',
+        skillId: 'test',
+        arguments: {},
+      });
+
+      const status = service.getStatus(result.taskId);
+      expect(status).toBeDefined();
+      expect(status!.taskId).toBe(result.taskId);
+    });
+
+    it('enforces maxHistory with LRU eviction', async () => {
+      await registry.register(makeLocalAgent());
+
+      const service = new TaskDelegationService(registry, undefined, {
+        maxHistory: 2,
+        localExecutor: async () => ({ ok: true }),
+      });
+
+      await service.delegateTo({ targetAgentId: 'local-agent-1', skillId: 'a', arguments: {} });
+      await service.delegateTo({ targetAgentId: 'local-agent-1', skillId: 'b', arguments: {} });
+      await service.delegateTo({ targetAgentId: 'local-agent-1', skillId: 'c', arguments: {} });
+
+      const history = service.getDelegationHistory();
+      expect(history).toHaveLength(2);
+    });
+
+    it('getStats returns correct counts', async () => {
+      await registry.register(makeLocalAgent());
+
+      let shouldFail = false;
+      const service = new TaskDelegationService(registry, undefined, {
+        localExecutor: async () => {
+          if (shouldFail) throw new Error('fail');
+          return { ok: true };
+        },
+      });
+
+      await service.delegateTo({ targetAgentId: 'local-agent-1', skillId: 'a', arguments: {} });
+      shouldFail = true;
+      await service.delegateTo({ targetAgentId: 'local-agent-1', skillId: 'b', arguments: {} });
+      await service.delegateTo({ targetAgentId: 'nonexistent', skillId: 'c', arguments: {} });
+
+      const stats = service.getStats();
+      expect(stats.total).toBe(3);
+      expect(stats.completed).toBe(1);
+      expect(stats.failed).toBe(1);
+      expect(stats.rejected).toBe(1);
+    });
+
+    it('emits trace events via traceHook and exposes trace history', async () => {
+      await registry.register(makeLocalAgent());
+
+      const traceEvents: string[] = [];
+      const service = new TaskDelegationService(registry, undefined, {
+        localExecutor: async () => ({ ok: true }),
+        traceHook: (event) => {
+          traceEvents.push(event.phase);
+        },
+      });
+
+      const result = await service.delegateTo({
+        targetAgentId: 'local-agent-1',
+        skillId: 'traceable_skill',
+        arguments: {},
+      });
+
+      const taskTrace = service.getTraceHistory(result.taskId);
+      expect(traceEvents).toContain('start');
+      expect(traceEvents).toContain('attempt');
+      expect(traceEvents).toContain('success');
+      expect(taskTrace.length).toBeGreaterThan(0);
+      expect(taskTrace[0].taskId).toBe(result.taskId);
+    });
+
+    it('replays a delegated task from stored request history', async () => {
+      await registry.register(makeLocalAgent());
+
+      const service = new TaskDelegationService(registry, undefined, {
+        localExecutor: async () => ({ replayable: true }),
+      });
+
+      const initial = await service.delegateTo({
+        targetAgentId: 'local-agent-1',
+        skillId: 'replay_skill',
+        arguments: { pass: 1 },
+      });
+
+      const replay = await service.replay(initial.taskId, {
+        arguments: { pass: 2 },
+      });
+
+      expect(replay.status).toBe('completed');
+      expect(replay.taskId).not.toBe(initial.taskId);
+
+      const originalTrace = service.getTraceHistory(initial.taskId).map((event) => event.phase);
+      expect(originalTrace).toContain('replay_requested');
+      expect(originalTrace).toContain('replay_completed');
+    });
+
+    it('throws when replaying unknown task id', async () => {
+      const service = new TaskDelegationService(registry);
+      await expect(service.replay('missing-task-id')).rejects.toThrow('Replay unavailable');
+    });
+  });
+});

package/src/agents/index.ts

@@ -0,0 +1,107 @@
+/**
+ * @holoscript/framework - Agents Module
+ *
+ * Multi-agent orchestration and choreography system.
+ * Migrated from @holoscript/core as part of A.011.02a.
+ */
+
+// Agent Types (uAA2++ Protocol)
+export * from './AgentTypes';
+
+// Agent Manifest (Registration declarations)
+export {
+  type AgentManifest,
+  type AgentCapability,
+  type AgentEndpoint,
+  type SpatialScope,
+  type BoundingBox,
+  type Vector3,
+  type TrustLevel,
+  type VerificationStatus,
+  type ResourceCost,
+  type LatencyProfile,
+  type CapabilityType,
+  type CapabilityDomain,
+  type EndpointProtocol,
+  type ValidationResult as AgentValidationResult,
+  LATENCY_THRESHOLDS,
+  AgentManifestBuilder,
+  createManifest as createAgentManifest,
+  validateManifest,
+} from './AgentManifest';
+
+// Capability Matcher (Query & Discovery)
+export {
+  type CapabilityQuery,
+  type SpatialQuery,
+  type CapabilityMatch,
+  type AgentMatch,
+  CapabilityMatcher,
+  defaultMatcher,
+  findAgents,
+  findBestAgent,
+} from './CapabilityMatcher';
+
+// Agent Registry (Central Registration)
+export {
+  type DiscoveryMode,
+  type RegistryConfig as AgentRegistryConfig,
+  type RegistryEvents,
+  DEFAULT_REGISTRY_CONFIG,
+  AgentRegistry,
+  getDefaultRegistry,
+  resetDefaultRegistry,
+} from './AgentRegistry';
+
+// Federated Registry Adapter (v5.5 Cross-Composition Discovery)
+export {
+  FederatedRegistryAdapter,
+  type FederatedRegistryConfig,
+  type A2AAgentCard,
+  type A2ASkill,
+} from './FederatedRegistryAdapter';
+
+// Task Delegation Service (v5.5 Cross-Agent Task Forwarding)
+export {
+  TaskDelegationService,
+  type TaskDelegationConfig,
+  type A2ATransportAdapter,
+  type DelegationRequest,
+  type DelegationResult,
+  type DelegationTraceEvent,
+  type DelegationTracePhase,
+} from './TaskDelegationService';
+
+// Skill Workflow Engine (v5.5 Skill Composition/Chaining)
+export {
+  SkillWorkflowEngine,
+  type WorkflowDefinition,
+  type WorkflowStep,
+  type WorkflowInput,
+  type WorkflowValidation,
+  type WorkflowResult,
+  type WorkflowStepResult,
+  type SkillExecutor,
+  type ProgressCallback,
+} from './SkillWorkflowEngine';
+
+// Orchestrator Agent (v5.5 First Concrete BaseAgent)
+export { OrchestratorAgent, type OrchestratorConfig } from './OrchestratorAgent';
+
+// Agent Wallet Registry (Autonomous wallet management)
+export { AgentWalletRegistry, type AgentWallet } from './AgentWalletRegistry';
+
+// Authenticated CRDT (DID-signed conflict-free state sync)
+export * from './AuthenticatedCRDT';
+
+// Cross-Reality Handoff Protocol
+export * from './CrossRealityHandoff';
+
+// Cultural Memory (Dual memory architecture)
+export * from './CulturalMemory';
+
+// Norm Engine (CRSEC norm lifecycle)
+export * from './NormEngine';
+
+// Spatial Communication Stack
+export * from './spatial-comms';