@holoscript/framework 6.0.3

package/src/__tests__/goal-synthesizer.test.ts

@@ -0,0 +1,236 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { GoalSynthesizer, GENERIC_GOALS, DOMAIN_GOALS } from '../protocol/goal-synthesizer';
+import type { GoalContext, SynthesizedGoal } from '../protocol/goal-synthesizer';
+import type { KnowledgeStore, StoredEntry } from '../knowledge/knowledge-store';
+
+// ── Helpers ──
+
+function mockKnowledgeStore(entries: Partial<StoredEntry>[] = []): KnowledgeStore {
+  return {
+    search: vi.fn().mockReturnValue(entries),
+  } as unknown as KnowledgeStore;
+}
+
+function mockLLMConfig() {
+  return {
+    provider: 'anthropic' as const,
+    model: 'claude-sonnet-4',
+    apiKey: 'test-key',
+  };
+}
+
+// ── Tests ──
+
+describe('GoalSynthesizer', () => {
+  describe('constructor', () => {
+    it('creates without options (no LLM, no knowledge)', () => {
+      const gs = new GoalSynthesizer();
+      expect(gs).toBeDefined();
+    });
+
+    it('creates with LLM and knowledge store', () => {
+      const gs = new GoalSynthesizer({
+        llm: mockLLMConfig(),
+        knowledge: mockKnowledgeStore(),
+      });
+      expect(gs).toBeDefined();
+    });
+  });
+
+  describe('synthesize (backward-compatible sync API)', () => {
+    it('returns a valid Goal with defaults', () => {
+      const gs = new GoalSynthesizer();
+      const goal = gs.synthesize();
+      expect(goal).toHaveProperty('id');
+      expect(goal).toHaveProperty('description');
+      expect(goal).toHaveProperty('category');
+      expect(goal).toHaveProperty('priority');
+      expect(goal).toHaveProperty('estimatedComplexity');
+      expect(goal).toHaveProperty('generatedAt');
+      expect(goal).toHaveProperty('source');
+      expect(goal.id).toMatch(/^GOAL-/);
+      expect(goal.source).toBe('autonomous-boredom');
+    });
+
+    it('respects custom domain', () => {
+      const gs = new GoalSynthesizer();
+      const goal = gs.synthesize('coding');
+      expect(goal.description).toBeTruthy();
+    });
+
+    it('respects custom source', () => {
+      const gs = new GoalSynthesizer();
+      const goal = gs.synthesize('general', 'system-mandate');
+      expect(goal.source).toBe('system-mandate');
+    });
+
+    it('generates goals with complexity 1-5', () => {
+      const gs = new GoalSynthesizer();
+      for (let i = 0; i < 20; i++) {
+        const goal = gs.synthesize();
+        expect(goal.estimatedComplexity).toBeGreaterThanOrEqual(1);
+        expect(goal.estimatedComplexity).toBeLessThanOrEqual(5);
+      }
+    });
+  });
+
+  describe('synthesizeMultiple (async, context-aware)', () => {
+    it('returns requested number of goals via heuristic', async () => {
+      const gs = new GoalSynthesizer();
+      const context: GoalContext = { domain: 'coding' };
+      const goals = await gs.synthesizeMultiple(context, 3);
+      expect(goals).toHaveLength(3);
+      for (const g of goals) {
+        expect(g).toHaveProperty('rationale');
+        expect(g).toHaveProperty('relevanceScore');
+        expect(g.relevanceScore).toBeGreaterThan(0);
+        expect(g.relevanceScore).toBeLessThanOrEqual(1);
+      }
+    });
+
+    it('returns domain-specific goals for coding', async () => {
+      const gs = new GoalSynthesizer();
+      const goals = await gs.synthesizeMultiple({ domain: 'coding' }, 5);
+      expect(goals.length).toBeGreaterThan(0);
+      expect(goals.length).toBeLessThanOrEqual(5);
+    });
+
+    it('returns domain-specific goals for security', async () => {
+      const gs = new GoalSynthesizer();
+      const goals = await gs.synthesizeMultiple({ domain: 'security' }, 3);
+      expect(goals).toHaveLength(3);
+    });
+
+    it('returns domain-specific goals for research', async () => {
+      const gs = new GoalSynthesizer();
+      const goals = await gs.synthesizeMultiple({ domain: 'research' }, 3);
+      expect(goals).toHaveLength(3);
+    });
+
+    it('falls back to generic goals for unknown domains', async () => {
+      const gs = new GoalSynthesizer();
+      const goals = await gs.synthesizeMultiple({ domain: 'quantum-knitting' }, 2);
+      expect(goals).toHaveLength(2);
+      // Should still produce valid goals
+      for (const g of goals) {
+        expect(g.description).toBeTruthy();
+      }
+    });
+
+    it('uses knowledge store gotchas to derive goals', async () => {
+      const store = mockKnowledgeStore([
+        {
+          id: 'G.TEST.001',
+          type: 'gotcha',
+          content: 'Memory leak in WebSocket reconnection handler',
+          domain: 'coding',
+          confidence: 0.9,
+          source: 'test',
+          queryCount: 0,
+          reuseCount: 0,
+          createdAt: new Date().toISOString(),
+          authorAgent: 'test-agent',
+        },
+      ]);
+      const gs = new GoalSynthesizer({ knowledge: store });
+      const goals = await gs.synthesizeMultiple({ domain: 'coding' }, 3);
+      expect(goals.length).toBeGreaterThan(0);
+      // Knowledge store should have been queried
+      expect(store.search).toHaveBeenCalledWith('coding', 5);
+    });
+
+    it('filters out recently completed tasks', async () => {
+      const gs = new GoalSynthesizer();
+      const completed = GENERIC_GOALS.slice(0, 4);
+      const goals = await gs.synthesizeMultiple({
+        domain: 'general',
+        recentCompletedTasks: completed,
+      }, 3);
+      // None of the returned goals should match completed tasks
+      for (const g of goals) {
+        expect(completed.map(c => c.toLowerCase())).not.toContain(g.description.toLowerCase());
+      }
+    });
+
+    it('first goal has highest relevance score', async () => {
+      const gs = new GoalSynthesizer();
+      const goals = await gs.synthesizeMultiple({ domain: 'coding' }, 3);
+      if (goals.length >= 2) {
+        expect(goals[0].relevanceScore).toBeGreaterThanOrEqual(goals[1].relevanceScore);
+      }
+    });
+
+    it('includes rationale for each goal', async () => {
+      const gs = new GoalSynthesizer();
+      const goals = await gs.synthesizeMultiple({ domain: 'coding' }, 2);
+      for (const g of goals) {
+        expect(g.rationale).toBeTruthy();
+        expect(typeof g.rationale).toBe('string');
+      }
+    });
+  });
+
+  describe('LLM-based synthesis', () => {
+    it('falls back to heuristic when LLM call fails', async () => {
+      // Mock callLLM to throw
+      vi.doMock('../llm/llm-adapter', () => ({
+        callLLM: vi.fn().mockRejectedValue(new Error('API key invalid')),
+      }));
+
+      const gs = new GoalSynthesizer({
+        llm: mockLLMConfig(),
+      });
+
+      const goals = await gs.synthesizeMultiple({ domain: 'coding' }, 2);
+      // Should still return goals via heuristic fallback
+      expect(goals.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('knowledge-derived goals', () => {
+    it('marks knowledge-derived goals with knowledge-gap category', async () => {
+      const store = mockKnowledgeStore([
+        {
+          id: 'G.SEC.001',
+          type: 'gotcha',
+          content: 'SQL injection in search endpoint',
+          domain: 'security',
+          confidence: 0.95,
+          source: 'audit',
+          queryCount: 0,
+          reuseCount: 0,
+          createdAt: new Date().toISOString(),
+          authorAgent: 'scanner',
+        },
+      ]);
+
+      const gs = new GoalSynthesizer({ knowledge: store });
+      // Request enough goals to ensure the knowledge-derived one is included
+      const goals = await gs.synthesizeMultiple({ domain: 'security' }, 15);
+
+      const knowledgeGapGoals = goals.filter(g => g.category === 'knowledge-gap');
+      // At least one goal should be derived from the gotcha
+      expect(knowledgeGapGoals.length).toBeGreaterThanOrEqual(1);
+      const derived = knowledgeGapGoals[0];
+      expect(derived.description).toContain('SQL injection');
+      expect(derived.rationale).toContain('knowledge store');
+    });
+  });
+
+  describe('exported constants', () => {
+    it('GENERIC_GOALS is a non-empty array of strings', () => {
+      expect(Array.isArray(GENERIC_GOALS)).toBe(true);
+      expect(GENERIC_GOALS.length).toBeGreaterThan(0);
+      for (const g of GENERIC_GOALS) {
+        expect(typeof g).toBe('string');
+      }
+    });
+
+    it('DOMAIN_GOALS has expected domains', () => {
+      expect(DOMAIN_GOALS).toHaveProperty('coding');
+      expect(DOMAIN_GOALS).toHaveProperty('research');
+      expect(DOMAIN_GOALS).toHaveProperty('security');
+      expect(DOMAIN_GOALS).toHaveProperty('reviewer');
+    });
+  });
+});

package/src/__tests__/presence.test.ts

@@ -0,0 +1,223 @@
+import { describe, it, expect, vi } from 'vitest';
+import { defineAgent } from '../define-agent';
+import { defineTeam } from '../define-team';
+import type { AgentConfig } from '../types';
+
+// Mock protocol-agent so runCycle doesn't hit real LLMs
+vi.mock('../protocol-agent', () => ({
+  runProtocolCycle: vi.fn().mockResolvedValue({
+    summary: 'Done',
+    insights: [],
+  }),
+}));
+
+function makeAgent(name: string, role: AgentConfig['role'] = 'coder'): AgentConfig {
+  return defineAgent({
+    name,
+    role,
+    model: { provider: 'anthropic', model: 'claude-sonnet-4' },
+    capabilities: ['code-generation'],
+    claimFilter: { roles: ['coder'], maxPriority: 10 },
+  });
+}
+
+describe('Local Presence Tracking (FW-0.3)', () => {
+  describe('localHeartbeat()', () => {
+    it('registers an agent on first heartbeat', () => {
+      const team = defineTeam({ name: 'presence-test', agents: [makeAgent('Alice')] });
+      team.localHeartbeat('Alice');
+      const agents = team.localPresence();
+      expect(agents).toHaveLength(1);
+      expect(agents[0].name).toBe('Alice');
+      expect(agents[0].status).toBe('online');
+    });
+
+    it('updates lastSeen on subsequent heartbeats', () => {
+      const team = defineTeam({ name: 'presence-test', agents: [makeAgent('Alice')] });
+      team.localHeartbeat('Alice');
+      const first = team.localPresence()[0].lastSeen;
+
+      // Advance time slightly
+      vi.useFakeTimers();
+      vi.advanceTimersByTime(100);
+      team.localHeartbeat('Alice');
+      const second = team.localPresence()[0].lastSeen;
+      expect(second).toBeGreaterThanOrEqual(first);
+      vi.useRealTimers();
+    });
+
+    it('tracks currentTask when provided', () => {
+      const team = defineTeam({ name: 'presence-test', agents: [makeAgent('Alice')] });
+      team.localHeartbeat('Alice', 'Fix auth bug');
+      const agents = team.localPresence();
+      expect(agents[0].currentTask).toBe('Fix auth bug');
+    });
+
+    it('clears currentTask when heartbeat has no task', () => {
+      const team = defineTeam({ name: 'presence-test', agents: [makeAgent('Alice')] });
+      team.localHeartbeat('Alice', 'Fix auth bug');
+      team.localHeartbeat('Alice');
+      const agents = team.localPresence();
+      expect(agents[0].currentTask).toBeUndefined();
+    });
+
+    it('tracks multiple agents independently', () => {
+      const team = defineTeam({
+        name: 'presence-test',
+        agents: [makeAgent('Alice'), makeAgent('Bob', 'reviewer')],
+      });
+      team.localHeartbeat('Alice', 'Task A');
+      team.localHeartbeat('Bob', 'Task B');
+      const agents = team.localPresence();
+      expect(agents).toHaveLength(2);
+      const names = agents.map(a => a.name).sort();
+      expect(names).toEqual(['Alice', 'Bob']);
+    });
+  });
+
+  describe('localPresence() status transitions', () => {
+    it('marks agent as idle after idleTimeout', () => {
+      vi.useFakeTimers();
+      const team = defineTeam({
+        name: 'idle-test',
+        agents: [makeAgent('Alice')],
+        presence: { idleTimeoutMs: 1000, offlineTimeoutMs: 5000 },
+      });
+
+      team.localHeartbeat('Alice');
+      expect(team.localPresence()[0].status).toBe('online');
+
+      vi.advanceTimersByTime(1500); // past idle threshold
+      expect(team.localPresence()[0].status).toBe('idle');
+
+      vi.useRealTimers();
+    });
+
+    it('marks agent as offline after offlineTimeout', () => {
+      vi.useFakeTimers();
+      const team = defineTeam({
+        name: 'offline-test',
+        agents: [makeAgent('Alice')],
+        presence: { idleTimeoutMs: 1000, offlineTimeoutMs: 5000 },
+      });
+
+      team.localHeartbeat('Alice');
+      vi.advanceTimersByTime(6000); // past offline threshold
+      expect(team.localPresence()[0].status).toBe('offline');
+
+      vi.useRealTimers();
+    });
+
+    it('returns to online after a fresh heartbeat', () => {
+      vi.useFakeTimers();
+      const team = defineTeam({
+        name: 'recover-test',
+        agents: [makeAgent('Alice')],
+        presence: { idleTimeoutMs: 1000, offlineTimeoutMs: 5000 },
+      });
+
+      team.localHeartbeat('Alice');
+      vi.advanceTimersByTime(6000);
+      expect(team.localPresence()[0].status).toBe('offline');
+
+      // Agent comes back
+      team.localHeartbeat('Alice');
+      expect(team.localPresence()[0].status).toBe('online');
+
+      vi.useRealTimers();
+    });
+
+    it('uses default timeouts (60s idle, 300s offline) when not configured', () => {
+      vi.useFakeTimers();
+      const team = defineTeam({
+        name: 'default-timeout-test',
+        agents: [makeAgent('Alice')],
+      });
+
+      team.localHeartbeat('Alice');
+      expect(team.localPresence()[0].status).toBe('online');
+
+      vi.advanceTimersByTime(61_000); // past default 60s idle
+      expect(team.localPresence()[0].status).toBe('idle');
+
+      vi.advanceTimersByTime(240_000); // total ~301s, past default 300s offline
+      expect(team.localPresence()[0].status).toBe('offline');
+
+      vi.useRealTimers();
+    });
+  });
+
+  describe('uptime tracking', () => {
+    it('computes uptime from first heartbeat', () => {
+      vi.useFakeTimers();
+      const team = defineTeam({
+        name: 'uptime-test',
+        agents: [makeAgent('Alice')],
+        presence: { idleTimeoutMs: 60_000, offlineTimeoutMs: 300_000 },
+      });
+
+      team.localHeartbeat('Alice');
+      vi.advanceTimersByTime(10_000);
+      team.localHeartbeat('Alice'); // refresh lastSeen but firstSeen stays
+
+      const agents = team.localPresence();
+      expect(agents[0].uptime).toBeGreaterThanOrEqual(10_000);
+
+      vi.useRealTimers();
+    });
+  });
+
+  describe('auto-heartbeat during runCycle', () => {
+    it('automatically heartbeats agents that claim tasks during a cycle', async () => {
+      const team = defineTeam({
+        name: 'auto-hb-test',
+        agents: [makeAgent('Alice')],
+      });
+
+      await team.addTasks([
+        { title: 'Fix bug', description: 'Important', priority: 1, role: 'coder' },
+      ]);
+
+      // Before cycle — no presence data
+      expect(team.localPresence()).toHaveLength(0);
+
+      await team.runCycle();
+
+      // After cycle — agent should have been auto-heartbeated
+      const agents = team.localPresence();
+      expect(agents).toHaveLength(1);
+      expect(agents[0].name).toBe('Alice');
+      expect(agents[0].status).toBe('online');
+      expect(agents[0].currentTask).toBe('Fix bug');
+    });
+
+    it('does not heartbeat agents that skip (no matching task)', async () => {
+      const team = defineTeam({
+        name: 'skip-hb-test',
+        agents: [makeAgent('Alice')],
+      });
+
+      // No tasks on board, but more than threshold so no synthesis
+      await team.addTasks([
+        { title: 'Task 1', description: '', priority: 1, role: 'reviewer' as const },
+        { title: 'Task 2', description: '', priority: 2, role: 'reviewer' as const },
+        { title: 'Task 3', description: '', priority: 3, role: 'reviewer' as const },
+      ]);
+
+      await team.runCycle();
+
+      // Alice is a coder, all tasks are reviewer-only — she should have skipped
+      expect(team.localPresence()).toHaveLength(0);
+    });
+  });
+
+  describe('empty presence', () => {
+    it('returns empty array when no heartbeats recorded', () => {
+      const team = defineTeam({
+        name: 'empty-test',
+        agents: [makeAgent('Alice')],
+      });
+      expect(team.localPresence()).toEqual([]);
+    });
+  });
+});