@holoscript/framework 6.0.3

package/src/__tests__/protocol-agent.test.ts

@@ -0,0 +1,254 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ProtocolAgent, runProtocolCycle } from '../protocol-agent';
+import { ProtocolPhase } from '../protocol/implementations';
+import type { AgentConfig } from '../types';
+
+// ── Mock fetch globally ──
+
+const mockFetchResponse = (content: string) => ({
+  ok: true,
+  json: async () => ({
+    content: [{ text: content }],
+    usage: { output_tokens: 10 },
+  }),
+});
+
+const mockOpenAIResponse = (content: string) => ({
+  ok: true,
+  json: async () => ({
+    choices: [{ message: { content } }],
+    usage: { completion_tokens: 10 },
+  }),
+});
+
+const testAgent: AgentConfig = {
+  name: 'TestAgent',
+  role: 'coder',
+  model: { provider: 'anthropic', model: 'claude-sonnet-4', apiKey: 'test-key' },
+  capabilities: ['code-generation', 'testing'],
+  claimFilter: { roles: ['coder'], maxPriority: 10 },
+  knowledgeDomains: ['typescript'],
+};
+
+describe('ProtocolAgent', () => {
+  let fetchSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    fetchSpy = vi.fn();
+    vi.stubGlobal('fetch', fetchSpy);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('has correct identity from agent config', () => {
+    const agent = new ProtocolAgent(testAgent);
+    expect(agent.identity.name).toBe('TestAgent');
+    expect(agent.identity.domain).toBe('typescript');
+    expect(agent.identity.capabilities).toEqual(['code-generation', 'testing']);
+  });
+
+  it('intake phase gathers context without LLM call', async () => {
+    const agent = new ProtocolAgent(testAgent, 'some knowledge');
+    const result = await agent.intake({ task: 'Fix the bug' });
+
+    expect(result.phase).toBe(ProtocolPhase.INTAKE);
+    expect(result.status).toBe('success');
+    expect(fetchSpy).not.toHaveBeenCalled(); // no LLM call for intake
+
+    const data = result.data as Record<string, unknown>;
+    expect(data.task).toBe('Fix the bug');
+    expect(data.agent).toBe('TestAgent');
+    expect(data.knowledge).toBe('some knowledge');
+  });
+
+  it('reflect phase calls LLM with light model', async () => {
+    fetchSpy.mockResolvedValue(mockFetchResponse('Use TDD approach for this bug fix'));
+
+    const agent = new ProtocolAgent(testAgent);
+    const context = { task: 'Fix auth bug', role: 'coder', capabilities: ['code-generation'] };
+    const result = await agent.reflect(context);
+
+    expect(result.phase).toBe(ProtocolPhase.REFLECT);
+    expect(result.status).toBe('success');
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+
+    // Verify it used the light model (haiku)
+    const callBody = JSON.parse(fetchSpy.mock.calls[0][1].body);
+    expect(callBody.model).toBe('claude-haiku-4');
+  });
+
+  it('execute phase calls LLM with full model', async () => {
+    fetchSpy.mockResolvedValue(mockFetchResponse('Fixed the authentication bug by updating JWT validation'));
+
+    const agent = new ProtocolAgent(testAgent);
+    const plan = { plan: 'Use TDD', context: { task: 'Fix auth bug' } };
+    const result = await agent.execute(plan);
+
+    expect(result.phase).toBe(ProtocolPhase.EXECUTE);
+    expect(result.status).toBe('success');
+
+    // Verify it used the full model (sonnet)
+    const callBody = JSON.parse(fetchSpy.mock.calls[0][1].body);
+    expect(callBody.model).toBe('claude-sonnet-4');
+
+    const data = result.data as { output: string };
+    expect(data.output).toContain('authentication');
+  });
+
+  it('compress phase extracts knowledge items', async () => {
+    fetchSpy.mockResolvedValue(
+      mockFetchResponse(
+        '[wisdom] JWT tokens should be validated on every request\n' +
+        '[pattern] Use middleware for auth validation\n' +
+        '[gotcha] Never store refresh tokens in localStorage'
+      )
+    );
+
+    const agent = new ProtocolAgent(testAgent);
+    const result = await agent.compress({ output: 'Fixed JWT validation', task: 'Fix auth' });
+
+    expect(result.phase).toBe(ProtocolPhase.COMPRESS);
+    expect(result.status).toBe('success');
+
+    const data = result.data as { insights: Array<{ type: string; content: string }> };
+    expect(data.insights).toHaveLength(3);
+    expect(data.insights[0].type).toBe('wisdom');
+    expect(data.insights[1].type).toBe('pattern');
+    expect(data.insights[2].type).toBe('gotcha');
+  });
+
+  it('reintake phase skips LLM when no insights', async () => {
+    const agent = new ProtocolAgent(testAgent);
+    const result = await agent.reintake({ insights: [], rawOutput: 'some output' });
+
+    expect(result.phase).toBe(ProtocolPhase.REINTAKE);
+    expect(result.status).toBe('success');
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it('grow phase skips LLM when no validated insights', async () => {
+    const agent = new ProtocolAgent(testAgent);
+    const result = await agent.grow({ validated: [], rawOutput: 'some output' });
+
+    expect(result.phase).toBe(ProtocolPhase.GROW);
+    expect(result.status).toBe('success');
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it('evolve phase skips LLM when no validated insights', async () => {
+    const agent = new ProtocolAgent(testAgent);
+    const result = await agent.evolve({ patterns: '', validated: [] });
+
+    expect(result.phase).toBe(ProtocolPhase.EVOLVE);
+    expect(result.status).toBe('success');
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe('runProtocolCycle', () => {
+  let fetchSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    fetchSpy = vi.fn();
+    vi.stubGlobal('fetch', fetchSpy);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('executes all 7 phases and returns structured result', async () => {
+    let callCount = 0;
+    fetchSpy.mockImplementation(async () => {
+      callCount++;
+      // Phase 1 (reflect): light model
+      if (callCount === 1) return mockFetchResponse('Approach: fix validation logic');
+      // Phase 2 (execute): full model
+      if (callCount === 2) return mockFetchResponse('SUMMARY: Fixed JWT validation\nDone.');
+      // Phase 3 (compress): extract knowledge
+      if (callCount === 3) return mockFetchResponse('[wisdom] Always validate token expiry\n[pattern] Use middleware for auth');
+      // Phase 4 (reintake): validate
+      if (callCount === 4) return mockFetchResponse('[wisdom] Always validate token expiry');
+      // Phase 5 (grow): patterns
+      if (callCount === 5) return mockFetchResponse('Auth validation is a cross-cutting concern');
+      // Phase 6 (evolve): suggestions
+      if (callCount === 6) return mockFetchResponse('Add auth middleware to all routes');
+      return mockFetchResponse('ok');
+    });
+
+    const result = await runProtocolCycle(
+      testAgent,
+      { title: 'Fix JWT auth', description: 'JWT tokens not validated properly' },
+      '[pattern] Use middleware'
+    );
+
+    expect(result.summary).toContain('Fixed JWT validation');
+    expect(result.insights.length).toBeGreaterThan(0);
+    expect(result.insights[0].type).toBe('wisdom');
+    expect(result.phaseResults).toHaveLength(7);
+    expect(result.totalDurationMs).toBeGreaterThanOrEqual(0);
+
+    // 6 LLM calls: reflect + execute + compress + reintake + grow + evolve
+    // (intake is local, no LLM)
+    expect(fetchSpy).toHaveBeenCalledTimes(6);
+  });
+
+  it('returns summary from execute phase even when compress finds nothing', async () => {
+    fetchSpy.mockImplementation(async () =>
+      mockFetchResponse('Completed the task successfully')
+    );
+
+    const result = await runProtocolCycle(
+      testAgent,
+      { title: 'Simple task', description: 'Do something' },
+      ''
+    );
+
+    expect(result.summary).toContain('Completed the task');
+    // Empty insights are fine
+    expect(result.insights).toBeDefined();
+    expect(result.phaseResults).toHaveLength(7);
+  });
+
+  it('works with OpenAI provider', async () => {
+    const openaiAgent: AgentConfig = {
+      ...testAgent,
+      model: { provider: 'openai', model: 'gpt-4o', apiKey: 'test-key' },
+    };
+
+    fetchSpy.mockImplementation(async () =>
+      mockOpenAIResponse('Task done')
+    );
+
+    const result = await runProtocolCycle(
+      openaiAgent,
+      { title: 'Test task', description: 'Test' },
+      ''
+    );
+
+    expect(result.phaseResults).toHaveLength(7);
+    expect(result.summary).toContain('Task done');
+
+    // Verify light model used for reflect (first call)
+    const firstCallBody = JSON.parse(fetchSpy.mock.calls[0][1].body);
+    expect(firstCallBody.model).toBe('gpt-4o-mini');
+  });
+
+  it('handles LLM errors gracefully via BaseAgent.runCycle', async () => {
+    fetchSpy.mockRejectedValue(new Error('API rate limit'));
+
+    const result = await runProtocolCycle(
+      testAgent,
+      { title: 'Failing task', description: 'Will fail' },
+      ''
+    );
+
+    // Should still return a result (BaseAgent catches phase errors)
+    expect(result.phaseResults.length).toBeGreaterThan(0);
+    // The reflect phase should fail, which cascades
+    const reflectPhase = result.phaseResults.find(p => p.phase === ProtocolPhase.REFLECT);
+    expect(reflectPhase?.status).toBe('failure');
+  });
+});

package/src/__tests__/revenue-splitter.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from 'vitest';
+import { RevenueSplitter } from '../economy/RevenueSplitter';
+
+describe('RevenueSplitter', () => {
+  it('splits 50/50 correctly', () => {
+    const splitter = new RevenueSplitter([
+      { id: 'creator', basisPoints: 5000 },
+      { id: 'platform', basisPoints: 5000 },
+    ]);
+    const result = splitter.split(1_000_000n);
+    expect(result.shares.get('creator')).toBe(500_000n);
+    expect(result.shares.get('platform')).toBe(500_000n);
+    expect(RevenueSplitter.validate(result)).toBe(true);
+  });
+
+  it('splits with dust allocation to first recipient', () => {
+    const splitter = new RevenueSplitter([
+      { id: 'creator', basisPoints: 3333 },
+      { id: 'platform', basisPoints: 3334 },
+      { id: 'referrer', basisPoints: 3333 },
+    ]);
+    const result = splitter.split(100n);
+    // Sum must equal 100
+    let sum = 0n;
+    for (const v of result.shares.values()) sum += v;
+    expect(sum).toBe(100n);
+    expect(RevenueSplitter.validate(result)).toBe(true);
+  });
+
+  it('handles zero amount', () => {
+    const splitter = new RevenueSplitter([
+      { id: 'a', basisPoints: 7000 },
+      { id: 'b', basisPoints: 3000 },
+    ]);
+    const result = splitter.split(0n);
+    expect(result.shares.get('a')).toBe(0n);
+    expect(result.shares.get('b')).toBe(0n);
+    expect(RevenueSplitter.validate(result)).toBe(true);
+  });
+
+  it('throws on basis points not summing to 10000', () => {
+    expect(() => new RevenueSplitter([
+      { id: 'a', basisPoints: 5000 },
+      { id: 'b', basisPoints: 4000 },
+    ])).toThrow('sum to 10000');
+  });
+
+  it('throws on empty recipients', () => {
+    expect(() => new RevenueSplitter([])).toThrow('At least one');
+  });
+
+  it('throws on negative basis points', () => {
+    expect(() => new RevenueSplitter([
+      { id: 'a', basisPoints: -1000 },
+      { id: 'b', basisPoints: 11000 },
+    ])).toThrow('Negative');
+  });
+
+  it('throws on duplicate IDs', () => {
+    expect(() => new RevenueSplitter([
+      { id: 'a', basisPoints: 5000 },
+      { id: 'a', basisPoints: 5000 },
+    ])).toThrow('Duplicate');
+  });
+
+  it('throws on negative amount', () => {
+    const splitter = new RevenueSplitter([
+      { id: 'a', basisPoints: 10000 },
+    ]);
+    expect(() => splitter.split(-1n)).toThrow('negative');
+  });
+
+  it('splitNumeric works as convenience wrapper', () => {
+    const splitter = new RevenueSplitter([
+      { id: 'creator', basisPoints: 8000 },
+      { id: 'platform', basisPoints: 2000 },
+    ]);
+    const result = splitter.splitNumeric(1_000_000);
+    expect(result.shares.get('creator')).toBe(800_000n);
+    expect(result.shares.get('platform')).toBe(200_000n);
+  });
+
+  it('provides breakdown with percentages', () => {
+    const splitter = new RevenueSplitter([
+      { id: 'creator', basisPoints: 7000 },
+      { id: 'platform', basisPoints: 3000 },
+    ]);
+    const result = splitter.split(1_000_000n);
+    expect(result.breakdown).toHaveLength(2);
+    expect(result.breakdown[0].percentage).toBe('70.00%');
+    expect(result.breakdown[1].percentage).toBe('30.00%');
+  });
+
+  it('getRecipients returns configured recipients', () => {
+    const splitter = new RevenueSplitter([
+      { id: 'a', basisPoints: 6000 },
+      { id: 'b', basisPoints: 4000 },
+    ]);
+    const recipients = splitter.getRecipients();
+    expect(recipients).toHaveLength(2);
+    expect(recipients[0].id).toBe('a');
+  });
+
+  it('maintains sum invariant for large amounts', () => {
+    const splitter = new RevenueSplitter([
+      { id: 'creator', basisPoints: 3333 },
+      { id: 'platform', basisPoints: 1667 },
+      { id: 'referrer', basisPoints: 2500 },
+      { id: 'treasury', basisPoints: 2500 },
+    ]);
+    const result = splitter.split(999_999_999_999n);
+    expect(RevenueSplitter.validate(result)).toBe(true);
+  });
+});

package/src/__tests__/scenario-driven-todo.test.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect, vi } from 'vitest';
+import { GoalSynthesizer, DOMAIN_GOALS, GENERIC_GOALS } from '../protocol/goal-synthesizer';
+import type { KnowledgeStore, StoredEntry } from '../knowledge/knowledge-store';
+
+// Mock KnowledgeStore
+function mockKnowledgeStore(entries: Partial<StoredEntry>[] = []): KnowledgeStore {
+  return {
+    search: vi.fn().mockReturnValue(entries),
+  } as unknown as KnowledgeStore;
+}
+
+describe('Scenario-Driven Todo Generation', () => {
+  
+  it('Scenario 1: High Network Latency/Timeout generates DevOps/Performance todos', async () => {
+    // Injecting a gotcha about network lag into the knowledge store
+    const store = mockKnowledgeStore([
+      {
+        id: 'G.NET.088',
+        type: 'gotcha',
+        content: 'Mesh gossip sync consistently dropping packets under node count > 50',
+        domain: 'performance',
+        confidence: 0.95,
+        source: 'telemetry',
+        queryCount: 1,
+        reuseCount: 0,
+        createdAt: new Date().toISOString(),
+        authorAgent: 'monitor-agent',
+      },
+      {
+        id: 'G.NET.089',
+        type: 'gotcha',
+        content: 'Unbounded memory growth observed in PR #202 telemetry reporting',
+        domain: 'devops',
+        confidence: 0.85,
+        source: 'telemetry',
+        queryCount: 0,
+        reuseCount: 0,
+        createdAt: new Date().toISOString(),
+        authorAgent: 'monitor-agent',
+      }
+    ]);
+    
+    const synthesizer = new GoalSynthesizer({ knowledge: store });
+    
+    const performanceTodos = await synthesizer.synthesizeMultiple({ domain: 'performance' }, 50);
+    const devopsTodos = await synthesizer.synthesizeMultiple({ domain: 'devops' }, 50);
+    
+    // Performance agent should prioritize the dropping packets bug
+    expect(performanceTodos.some(t => t.category === 'knowledge-gap')).toBe(true);
+    expect(performanceTodos.some(t => t.description.includes('gossip sync consistently dropping'))).toBe(true);
+
+    // DevOps agent should look at telemetry reporting issues
+    expect(devopsTodos.some(t => t.category === 'knowledge-gap')).toBe(true);
+    expect(devopsTodos.some(t => t.description.includes('Unbounded memory growth'))).toBe(true);
+  });
+
+  it('Scenario 2: Team switches to "Testing" mode after major logic refactoring', async () => {
+    const synthesizer = new GoalSynthesizer();
+    // In "testing" mode with no specific recent knowledge, should yield pure heuristic testing goals
+    const testingTodos = await synthesizer.synthesizeMultiple({ domain: 'testing' }, 4);
+    
+    expect(testingTodos.length).toBe(4);
+    const allowed = new Set([...DOMAIN_GOALS['testing'], ...DOMAIN_GOALS['performance'], ...DOMAIN_GOALS['devops'],
+      'Analyze accumulated wisdom for contradictions',
+      'Refactor internal pattern database for efficiency',
+      'Explore adjacent domain knowledge',
+      'Review recent failures and simulate alternative outcomes',
+      'Update self-documentation and capability manifest',
+      'Ping other agents for potential collaboration',
+      'Optimize internal decision weights',
+      'Study historical logs for anomaly detection',
+    ]);
+    expect(testingTodos.every(t => allowed.has(t.description) || t.description.startsWith('Investigate and resolve:'))).toBe(true);
+  });
+
+  it('Scenario 3: Architecture re-evaluates service bounds based off system-mandated source', async () => {
+    const synthesizer = new GoalSynthesizer();
+    
+    // Simulate legacy synchronous call
+    const architectGoal = synthesizer.synthesize('architecture', 'system-mandate');
+    
+    expect(architectGoal).toBeDefined();
+    expect(architectGoal.source).toBe('system-mandate');
+    expect(['knowledge-gap', 'self-improvement']).toContain(architectGoal.category);
+    
+    // The description should match an architecture domain or generic fallback
+    const archDomains = DOMAIN_GOALS['architecture'];
+    expect(archDomains.includes(architectGoal.description) || GENERIC_GOALS.includes(architectGoal.description)).toBeTruthy();
+  });
+
+  it('Scenario 4: Security agent triages code injection vulnerability knowledge', async () => {
+    const store = mockKnowledgeStore([
+      {
+        id: 'G.SEC.999',
+        type: 'gotcha',
+        content: 'CRDT delta payloads bypassing type serialization checks causing prompt injection',
+        domain: 'security',
+        confidence: 0.99,
+        source: 'audit',
+        queryCount: 4,
+        reuseCount: 0,
+        createdAt: new Date().toISOString(),
+        authorAgent: 'security-scanner',
+      }
+    ]);
+    
+    const synthesizer = new GoalSynthesizer({ knowledge: store });
+    const secTodos = await synthesizer.synthesizeMultiple({ domain: 'security' }, 50);
+
+    expect(secTodos.some(t => t.description.includes('CRDT delta payloads bypassing type serialization'))).toBe(true);
+    // Security agent should rank the injection gotcha with high priority
+    const injectionTodo = secTodos.find(t => t.description.includes('CRDT delta'));
+    expect(injectionTodo?.category).toBe('knowledge-gap');
+  });
+
+  it('Scenario 5: Goal Synthesizer todos are successfully converted and pushed to the Team board', async () => {
+    // We can isolate the goal-to-task pipeline
+    const synthesizer = new GoalSynthesizer();
+    
+    // Synthesize some tasks for testing
+    const newGoals = await synthesizer.synthesizeMultiple({ domain: 'performance' }, 3);
+    
+    // Convert to board tasks structure
+    const tasksToSubmit = newGoals.map(goal => ({
+      title: goal.description,
+      description: `[Auto-Synthesized] Rationale: ${goal.rationale}\nRelevance: ${goal.relevanceScore}`,
+      priority: goal.priority === 'high' ? 1 : goal.priority === 'medium' ? 2 : 3,
+      source: `synthesizer:${goal.id}`
+    }));
+    
+    // Verify valid schema
+    expect(tasksToSubmit.length).toBe(3);
+    expect(tasksToSubmit[0].title).toBeDefined();
+    expect(tasksToSubmit[0].description).toContain('[Auto-Synthesized]');
+    expect(tasksToSubmit[0].priority).toBeGreaterThanOrEqual(1);
+    expect(tasksToSubmit[0].priority).toBeLessThanOrEqual(3);
+  });
+  it('Scenario 6: Research agent identifies knowledge gaps and proposes surveying', async () => {
+    const store = mockKnowledgeStore([
+      {
+        id: 'G.RES.101',
+        type: 'gotcha',
+        content: 'Neural Streaming data formats changing rapidly without backward compatibility',
+        domain: 'research',
+        confidence: 0.90,
+        source: 'external',
+        queryCount: 0,
+        reuseCount: 0,
+        createdAt: new Date().toISOString(),
+        authorAgent: 'researcher-agent',
+      }
+    ]);
+    
+    const synthesizer = new GoalSynthesizer({ knowledge: store });
+    const researchTodos = await synthesizer.synthesizeMultiple({ domain: 'research' }, 50);
+
+    expect(researchTodos.some(t => t.description.includes('Neural Streaming'))).toBe(true);
+    // At least one task should fall back to general heuristic if we asked for higher count
+    const hasHeuristic = researchTodos.some(t => DOMAIN_GOALS['research'].includes(t.description));
+    expect(hasHeuristic).toBe(true);
+  });
+
+  it('Scenario 7: Coding agent reacts to legacy deprecation gotchas with targeted refactoring tasks', async () => {
+    const store = mockKnowledgeStore([
+      {
+        id: 'G.CODE.404',
+        type: 'gotcha',
+        content: 'V1 Mesh APIs are throwing silent UnhandledPromiseRejection errors under load',
+        domain: 'coding',
+        confidence: 0.98,
+        source: 'bug-tracker',
+        queryCount: 3,
+        reuseCount: 1,
+        createdAt: new Date().toISOString(),
+        authorAgent: 'dev-agent',
+      }
+    ]);
+    
+    const synthesizer = new GoalSynthesizer({ knowledge: store });
+    const codingTodos = await synthesizer.synthesizeMultiple({ domain: 'coding' }, 50);
+
+    // Should prioritize the urgent deprecation / silent failure bug
+    expect(codingTodos.some(t => t.description.includes('UnhandledPromiseRejection')) || codingTodos.some(t => t.description.includes('V1 Mesh APIs'))).toBe(true);
+  });
+
+  it('Scenario 8: Reviewer agent generates task based on heuristic fallback', async () => {
+    const synthesizer = new GoalSynthesizer();
+    const reviewerTodos = await synthesizer.synthesizeMultiple({ domain: 'reviewer' }, 4);
+    
+    expect(reviewerTodos.length).toBe(4);
+    const allExpectedDomains = DOMAIN_GOALS['reviewer'];
+    const hasReviewerHeuristic = reviewerTodos.some(t => 
+      allExpectedDomains.includes(t.description)
+    );
+    expect(hasReviewerHeuristic).toBe(true);
+  });
+});