@holoscript/framework 6.0.3 → 6.0.4

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

@@ -0,0 +1,390 @@
+/**
+ * DelegationTraceHooks Tests
+ *
+ * Tests agent-to-agent delegation tracing, chain walking, and replay.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  DelegationTraceStore,
+  traceDelegation,
+  replayDelegation,
+  getDelegationChain,
+  resetDefaultTraceStore,
+  getDefaultTraceStore,
+  type DelegationEvent,
+  type DelegationTrace,
+  type DelegationExecutor,
+} from '../DelegationTraceHooks';
+
+// =============================================================================
+// TESTS
+// =============================================================================
+
+describe('DelegationTraceHooks', () => {
+  let store: DelegationTraceStore;
+
+  beforeEach(() => {
+    store = new DelegationTraceStore();
+    resetDefaultTraceStore();
+  });
+
+  // ===========================================================================
+  // traceDelegation
+  // ===========================================================================
+
+  describe('traceDelegation', () => {
+    it('creates a root delegation event with no parent', () => {
+      const event = store.traceDelegation('agent-a', 'agent-b', 'task-1', { skill: 'parse' });
+
+      expect(event.fromAgent).toBe('agent-a');
+      expect(event.toAgent).toBe('agent-b');
+      expect(event.taskId).toBe('task-1');
+      expect(event.payload).toEqual({ skill: 'parse' });
+      expect(event.parentDelegation).toBeNull();
+      expect(event.status).toBe('pending');
+      expect(event.id).toBeTruthy();
+      expect(event.timestamp).toBeTruthy();
+    });
+
+    it('creates a child delegation linked to parent', () => {
+      const root = store.traceDelegation('agent-a', 'agent-b', 'task-1');
+      const child = store.traceDelegation('agent-b', 'agent-c', 'task-2', {}, root.id);
+
+      expect(child.parentDelegation).toBe(root.id);
+
+      // Both should be in the same trace
+      const trace = store.getTrace(root.id);
+      expect(trace).toBeDefined();
+      expect(trace!.events.size).toBe(2);
+      expect(trace!.events.has(root.id)).toBe(true);
+      expect(trace!.events.has(child.id)).toBe(true);
+    });
+
+    it('creates a new trace when parent is not found', () => {
+      const orphan = store.traceDelegation('agent-x', 'agent-y', 'task-99', {}, 'nonexistent');
+
+      expect(orphan.parentDelegation).toBe('nonexistent');
+      expect(store.size).toBe(1);
+    });
+
+    it('handles empty payload', () => {
+      const event = store.traceDelegation('a', 'b', 't');
+      expect(event.payload).toEqual({});
+    });
+  });
+
+  // ===========================================================================
+  // updateStatus
+  // ===========================================================================
+
+  describe('updateStatus', () => {
+    it('updates event status', () => {
+      const event = store.traceDelegation('a', 'b', 't');
+      const updated = store.updateStatus(event.id, 'completed', { durationMs: 150 });
+
+      expect(updated).toBe(true);
+      const retrieved = store.getEvent(event.id);
+      expect(retrieved!.status).toBe('completed');
+      expect(retrieved!.durationMs).toBe(150);
+    });
+
+    it('records error on failure', () => {
+      const event = store.traceDelegation('a', 'b', 't');
+      store.updateStatus(event.id, 'failed', { error: 'Connection refused' });
+
+      const retrieved = store.getEvent(event.id);
+      expect(retrieved!.status).toBe('failed');
+      expect(retrieved!.error).toBe('Connection refused');
+    });
+
+    it('returns false for unknown event', () => {
+      expect(store.updateStatus('nonexistent', 'completed')).toBe(false);
+    });
+  });
+
+  // ===========================================================================
+  // getDelegationChain
+  // ===========================================================================
+
+  describe('getDelegationChain', () => {
+    it('returns the full chain from root to leaf', () => {
+      const root = store.traceDelegation('orchestrator', 'agent-a', 'task-1');
+      const mid = store.traceDelegation('agent-a', 'agent-b', 'task-2', {}, root.id);
+      const leaf = store.traceDelegation('agent-b', 'agent-c', 'task-3', {}, mid.id);
+
+      const chain = store.getDelegationChain(leaf.id);
+
+      expect(chain).toHaveLength(3);
+      expect(chain[0].event.id).toBe(root.id);
+      expect(chain[0].depth).toBe(0);
+      expect(chain[1].event.id).toBe(mid.id);
+      expect(chain[1].depth).toBe(1);
+      expect(chain[2].event.id).toBe(leaf.id);
+      expect(chain[2].depth).toBe(2);
+    });
+
+    it('returns single entry for root event', () => {
+      const root = store.traceDelegation('a', 'b', 't');
+      const chain = store.getDelegationChain(root.id);
+
+      expect(chain).toHaveLength(1);
+      expect(chain[0].depth).toBe(0);
+    });
+
+    it('returns empty for unknown event', () => {
+      expect(store.getDelegationChain('nonexistent')).toEqual([]);
+    });
+  });
+
+  // ===========================================================================
+  // getChildren
+  // ===========================================================================
+
+  describe('getChildren', () => {
+    it('returns direct children of an event', () => {
+      const root = store.traceDelegation('a', 'b', 't1');
+      store.traceDelegation('b', 'c', 't2', {}, root.id);
+      store.traceDelegation('b', 'd', 't3', {}, root.id);
+
+      const children = store.getChildren(root.id);
+      expect(children).toHaveLength(2);
+    });
+
+    it('returns empty for leaf events', () => {
+      const root = store.traceDelegation('a', 'b', 't');
+      expect(store.getChildren(root.id)).toHaveLength(0);
+    });
+  });
+
+  // ===========================================================================
+  // replayDelegation
+  // ===========================================================================
+
+  describe('replayDelegation', () => {
+    it('performs a dry-run replay of a trace', async () => {
+      const root = store.traceDelegation('a', 'b', 't1', { skill: 'parse' });
+      store.traceDelegation('b', 'c', 't2', { skill: 'compile' }, root.id);
+
+      const result = await store.replayDelegation(root.id);
+
+      expect(result.status).toBe('completed');
+      expect(result.steps).toHaveLength(2);
+      expect(result.steps[0].status).toBe('dry_run');
+      expect(result.steps[1].status).toBe('dry_run');
+    });
+
+    it('executes replay with an executor', async () => {
+      const root = store.traceDelegation('a', 'b', 't1', { skill: 'parse' });
+      store.traceDelegation('b', 'c', 't2', { skill: 'compile' }, root.id);
+
+      const executor: DelegationExecutor = vi.fn(async (_from, _to, _task, payload) => ({
+        executed: payload.skill,
+      }));
+
+      const result = await store.replayDelegation(root.id, executor, { execute: true });
+
+      expect(result.status).toBe('completed');
+      expect(result.steps).toHaveLength(2);
+      expect(result.steps[0].status).toBe('executed');
+      expect(result.steps[1].status).toBe('executed');
+      expect(executor).toHaveBeenCalledTimes(2);
+    });
+
+    it('reports failure when executor throws', async () => {
+      const root = store.traceDelegation('a', 'b', 't1');
+
+      const executor: DelegationExecutor = async () => {
+        throw new Error('Replay error');
+      };
+
+      const result = await store.replayDelegation(root.id, executor, { execute: true });
+
+      expect(result.steps[0].status).toBe('failed');
+      expect(result.steps[0].error).toBe('Replay error');
+    });
+
+    it('supports beforeStep to skip events', async () => {
+      const root = store.traceDelegation('a', 'b', 't1');
+      store.traceDelegation('b', 'c', 't2', {}, root.id);
+
+      const executor: DelegationExecutor = vi.fn(async () => 'ok');
+
+      const result = await store.replayDelegation(root.id, executor, {
+        execute: true,
+        beforeStep: (event) => event.fromAgent !== 'b', // skip agent-b delegations
+      });
+
+      expect(result.steps).toHaveLength(2);
+      expect(result.steps[0].status).toBe('executed'); // root a->b
+      expect(result.steps[1].status).toBe('skipped'); // child b->c
+    });
+
+    it('supports afterStep callback', async () => {
+      const root = store.traceDelegation('a', 'b', 't1');
+
+      const afterEvents: string[] = [];
+      await store.replayDelegation(root.id, undefined, {
+        afterStep: (event) => {
+          afterEvents.push(event.id);
+        },
+      });
+
+      expect(afterEvents).toHaveLength(1);
+      expect(afterEvents[0]).toBe(root.id);
+    });
+
+    it('supports payload overrides during replay', async () => {
+      const root = store.traceDelegation('a', 'b', 't1', { original: true });
+
+      const capturedPayloads: Record<string, unknown>[] = [];
+      const executor: DelegationExecutor = async (_from, _to, _task, payload) => {
+        capturedPayloads.push(payload);
+        return 'ok';
+      };
+
+      const overrides = new Map([[root.id, { overridden: true }]]);
+
+      await store.replayDelegation(root.id, executor, {
+        execute: true,
+        payloadOverrides: overrides,
+      });
+
+      expect(capturedPayloads[0]).toEqual({ overridden: true });
+    });
+
+    it('returns failed for unknown trace', async () => {
+      const result = await store.replayDelegation('nonexistent');
+      expect(result.status).toBe('failed');
+      expect(result.steps).toHaveLength(0);
+    });
+  });
+
+  // ===========================================================================
+  // Hooks (onDelegation)
+  // ===========================================================================
+
+  describe('onDelegation hooks', () => {
+    it('notifies subscribers on new delegation', () => {
+      const events: DelegationEvent[] = [];
+      store.onDelegation((event) => events.push(event));
+
+      store.traceDelegation('a', 'b', 't1');
+      store.traceDelegation('b', 'c', 't2');
+
+      expect(events).toHaveLength(2);
+    });
+
+    it('notifies on status updates', () => {
+      const events: DelegationEvent[] = [];
+      store.onDelegation((event) => events.push(event));
+
+      const e = store.traceDelegation('a', 'b', 't1');
+      store.updateStatus(e.id, 'completed');
+
+      expect(events).toHaveLength(2); // creation + update
+      expect(events[1].status).toBe('completed');
+    });
+
+    it('unsubscribe stops notifications', () => {
+      const events: DelegationEvent[] = [];
+      const unsub = store.onDelegation((event) => events.push(event));
+
+      store.traceDelegation('a', 'b', 't1');
+      unsub();
+      store.traceDelegation('c', 'd', 't2');
+
+      expect(events).toHaveLength(1);
+    });
+
+    it('hook errors do not break delegation flow', () => {
+      store.onDelegation(() => {
+        throw new Error('Hook exploded');
+      });
+
+      // Should not throw
+      const event = store.traceDelegation('a', 'b', 't1');
+      expect(event.id).toBeTruthy();
+    });
+  });
+
+  // ===========================================================================
+  // Query methods
+  // ===========================================================================
+
+  describe('query', () => {
+    it('getTracesForAgent finds all traces involving an agent', () => {
+      store.traceDelegation('agent-a', 'agent-b', 't1');
+      store.traceDelegation('agent-c', 'agent-d', 't2');
+      store.traceDelegation('agent-b', 'agent-e', 't3');
+
+      const traces = store.getTracesForAgent('agent-b');
+      expect(traces).toHaveLength(2); // t1 (as target) and t3 (as source, separate trace)
+    });
+
+    it('getAllTraces returns all traces sorted by recency', () => {
+      store.traceDelegation('a', 'b', 't1');
+      store.traceDelegation('c', 'd', 't2');
+
+      const all = store.getAllTraces();
+      expect(all).toHaveLength(2);
+    });
+
+    it('getEvent returns undefined for unknown', () => {
+      expect(store.getEvent('nonexistent')).toBeUndefined();
+    });
+  });
+
+  // ===========================================================================
+  // Eviction
+  // ===========================================================================
+
+  describe('eviction', () => {
+    it('evicts oldest traces when maxTraces is exceeded', () => {
+      const small = new DelegationTraceStore({ maxTraces: 2 });
+
+      small.traceDelegation('a', 'b', 't1');
+      small.traceDelegation('c', 'd', 't2');
+      small.traceDelegation('e', 'f', 't3');
+
+      expect(small.size).toBe(2);
+    });
+  });
+
+  // ===========================================================================
+  // Module-level convenience functions
+  // ===========================================================================
+
+  describe('module-level functions', () => {
+    it('traceDelegation uses default store', () => {
+      const event = traceDelegation('a', 'b', 't1', { key: 'val' });
+      expect(event.fromAgent).toBe('a');
+      expect(getDefaultTraceStore().size).toBe(1);
+    });
+
+    it('getDelegationChain uses default store', () => {
+      const root = traceDelegation('a', 'b', 't1');
+      const child = traceDelegation('b', 'c', 't2', {}, root.id);
+
+      const chain = getDelegationChain(child.id);
+      expect(chain).toHaveLength(2);
+      expect(chain[0].event.fromAgent).toBe('a');
+      expect(chain[1].event.fromAgent).toBe('b');
+    });
+
+    it('replayDelegation uses default store', async () => {
+      const root = traceDelegation('a', 'b', 't1');
+      const result = await replayDelegation(root.id);
+      expect(result.status).toBe('completed');
+      expect(result.steps).toHaveLength(1);
+    });
+
+    it('resetDefaultTraceStore clears state', () => {
+      traceDelegation('a', 'b', 't1');
+      expect(getDefaultTraceStore().size).toBe(1);
+
+      resetDefaultTraceStore();
+      expect(getDefaultTraceStore().size).toBe(0);
+    });
+  });
+});

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

@@ -151,13 +151,15 @@ describe('TaskDelegationService', () => {
       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');
+      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 send = vi.fn(async (_req: any) => ({ status: 'completed', via: 'adapter' }));
       const service = new TaskDelegationService(registry, undefined, {
         transportAdapter: { send },
         idempotencyKeyFactory: () => 'adapter-idem',

package/src/agents/spatial-comms/Layer1RealTime.ts

@@ -69,7 +69,9 @@ export function encodeRealTimeMessage(message: RealTimeMessage): Buffer {
       typeCode = MessageTypeCode.PERFORMANCE_METRIC;
       break;
     default:
-      throw new Error(`Unknown message type: ${(message as unknown as Record<string, unknown>).type}`);
+      throw new Error(
+        `Unknown message type: ${(message as unknown as Record<string, unknown>).type}`
+      );
   }
 
   // Encode based on type
@@ -218,27 +220,40 @@ export function decodeRealTimeMessage(buffer: Buffer): RealTimeMessage {
 
   // Decode based on type
   if (typeCode === MessageTypeCode.POSITION_SYNC) {
-    const px = buffer.readFloatBE(offset); offset += 4;
-    const py = buffer.readFloatBE(offset); offset += 4;
-    const pz = buffer.readFloatBE(offset); offset += 4;
+    const px = buffer.readFloatBE(offset);
+    offset += 4;
+    const py = buffer.readFloatBE(offset);
+    offset += 4;
+    const pz = buffer.readFloatBE(offset);
+    offset += 4;
     const position: [number, number, number] = [px, py, pz];
 
-    const rx = buffer.readFloatBE(offset); offset += 4;
-    const ry = buffer.readFloatBE(offset); offset += 4;
-    const rz = buffer.readFloatBE(offset); offset += 4;
-    const rw = buffer.readFloatBE(offset); offset += 4;
+    const rx = buffer.readFloatBE(offset);
+    offset += 4;
+    const ry = buffer.readFloatBE(offset);
+    offset += 4;
+    const rz = buffer.readFloatBE(offset);
+    offset += 4;
+    const rw = buffer.readFloatBE(offset);
+    offset += 4;
     const rotation: [number, number, number, number] = [rx, ry, rz, rw];
 
-    const sx = buffer.readFloatBE(offset); offset += 4;
-    const sy = buffer.readFloatBE(offset); offset += 4;
-    const sz = buffer.readFloatBE(offset); offset += 4;
+    const sx = buffer.readFloatBE(offset);
+    offset += 4;
+    const sy = buffer.readFloatBE(offset);
+    offset += 4;
+    const sz = buffer.readFloatBE(offset);
+    offset += 4;
     const scale: [number, number, number] = [sx, sy, sz];
 
     let velocity: [number, number, number] | undefined;
     if (offset < buffer.length) {
-      const vx = buffer.readFloatBE(offset); offset += 4;
-      const vy = buffer.readFloatBE(offset); offset += 4;
-      const vz = buffer.readFloatBE(offset); offset += 4;
+      const vx = buffer.readFloatBE(offset);
+      offset += 4;
+      const vy = buffer.readFloatBE(offset);
+      offset += 4;
+      const vz = buffer.readFloatBE(offset);
+      offset += 4;
       velocity = [vx, vy, vz];
     }
 
@@ -262,7 +277,12 @@ export function decodeRealTimeMessage(buffer: Buffer): RealTimeMessage {
     offset += 4;
     const qualityCode = buffer.readUInt8(offset);
     offset += 1;
-    const qualityLevels: Array<FrameBudgetMessage['quality_level']> = ['high', 'medium', 'low', 'minimal'];
+    const qualityLevels: Array<FrameBudgetMessage['quality_level']> = [
+      'high',
+      'medium',
+      'low',
+      'minimal',
+    ];
     const quality_level = qualityLevels[qualityCode] ?? 'medium';
 
     return {
@@ -488,10 +508,7 @@ export class Layer1RealTimeClient extends EventEmitter {
   /**
    * Send real-time message
    */
-  async send(
-    message: RealTimeMessageBody,
-    targetAgent?: string
-  ): Promise<void> {
+  async send(message: RealTimeMessageBody, targetAgent?: string): Promise<void> {
     if (!this.transport) throw new Error('Transport not initialized');
 
     // Add agent ID and timestamp

package/src/agents/spatial-comms/Layer2A2A.ts

@@ -263,9 +263,7 @@ export class Layer2A2AClient extends EventEmitter {
   /**
    * Send A2A message with retry
    */
-  async send(
-    message: A2AMessageBody
-  ): Promise<A2AResponse> {
+  async send(message: A2AMessageBody): Promise<A2AResponse> {
     // Generate message ID and add metadata
     const fullMessage: A2AMessage = {
       ...message,

package/src/agents/spatial-comms/Layer3MCP.ts

@@ -253,7 +253,16 @@ export class Layer3MCPClient extends EventEmitter {
       throw new Error(response.error || 'Failed to get agent registry');
     }
 
-    return response.data as { agents: Array<{ agent_id: string; role: string; status: 'online' | 'offline' | 'degraded'; world_id?: string; capabilities: string[] }>; total: number };
+    return response.data as {
+      agents: Array<{
+        agent_id: string;
+        role: string;
+        status: 'online' | 'offline' | 'degraded';
+        world_id?: string;
+        capabilities: string[];
+      }>;
+      total: number;
+    };
   }
 
   /**
@@ -510,7 +519,7 @@ export class Layer3MCPServer extends EventEmitter {
     });
 
     // Get world status handler
-    this.registerHandler('get_world_status', async (params, context) => {
+    this.registerHandler('get_world_status', async (params, _context) => {
       const worldId = params.world_id as string;
       const status = this.worlds.get(worldId);
 
@@ -541,7 +550,7 @@ export class Layer3MCPServer extends EventEmitter {
     });
 
     // Get agent registry handler
-    this.registerHandler('get_agent_registry', async (params, context) => {
+    this.registerHandler('get_agent_registry', async (params, _context) => {
       const filter = params.filter as Record<string, unknown> | undefined;
 
       // Get all agents from worlds
@@ -570,7 +579,7 @@ export class Layer3MCPServer extends EventEmitter {
     });
 
     // Get performance metrics handler
-    this.registerHandler('get_performance_metrics', async (params, context) => {
+    this.registerHandler('get_performance_metrics', async (params, _context) => {
       const worldId = params.world_id as string | undefined;
       const agentId = params.agent_id as string | undefined;
 

package/src/agents/spatial-comms/ProtocolTypes.ts

@@ -304,7 +304,10 @@ type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : n
  * A2A message body type for the `send()` method.
  * Strips auto-generated fields so callers only provide the domain payload.
  */
-export type A2AMessageBody = DistributiveOmit<A2AMessage, 'message_id' | 'from_agent' | 'timestamp'>;
+export type A2AMessageBody = DistributiveOmit<
+  A2AMessage,
+  'message_id' | 'from_agent' | 'timestamp'
+>;
 
 /**
  * A2A protocol configuration
@@ -492,7 +495,7 @@ export interface MCPProtocolConfig {
  */
 export const DEFAULT_MCP_CONFIG: MCPProtocolConfig = {
   endpoint: 'http://localhost:5567',
-  apiKey: process.env.MCP_API_KEY || '',
+  apiKey: process.env.HOLOSCRIPT_API_KEY || '',
   timeout: 30000, // 30 seconds
 };
 

package/src/agents/spatial-comms/examples/multi-agent-world-creation.ts

@@ -102,7 +102,7 @@ class TerrainAgent {
     console.log(`[TerrainAgent] Task ${task.task_id} completed in ${duration}ms`);
   }
 
-  private async generateTerrainChunk(index: number): Promise<void> {
+  private async generateTerrainChunk(_index: number): Promise<void> {
     // Simulate work (adjust based on quality level)
     const stats = this.client.getFrameBudgetStats();
     const workAmount = {
@@ -171,7 +171,7 @@ class AssetAgent {
     console.log(`[AssetAgent] Task ${task.task_id} completed`);
   }
 
-  private async placeAsset(index: number): Promise<void> {
+  private async placeAsset(_index: number): Promise<void> {
     const stats = this.client.getFrameBudgetStats();
     const workAmount = {
       high: 8,

package/src/ai/HoloScriptGenerator.ts

@@ -12,8 +12,8 @@
 
 import type { AIAdapter } from './AIAdapter';
 class HoloScriptPlusParser {
-  constructor(opts?: { strict?: boolean }) {}
-  parse(code: string): any {
+  constructor(_opts?: { strict?: boolean }) {}
+  parse(_code: string): any {
     return { success: true, errors: [], ast: {} };
   }
 }

package/src/ai/__tests__/PerceptionSystem.prod.test.ts

@@ -84,7 +84,7 @@ describe('PerceptionSystem — Production', () => {
       id: 'self',
       type: 'sight',
       sourceId: 'guard',
-      position: { x: 0, y: 0, z: 0 },
+      position: [0, 0, 0],
       intensity: 1,
       timestamp: 0,
     };