elsabro 6.0.0 → 7.0.0

package/flow-engine/tests/party.test.js

@@ -0,0 +1,724 @@
+'use strict';
+
+const { describe, it, before, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { PartyEngine, RELEVANCE_MAP, slugify, detectAgentNames } = require('../src/party');
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function tmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'party-test-'));
+}
+
+function mockOnAgentTurn({ agent, round }) {
+  return `${agent.name} says something in round ${round}`;
+}
+
+function mockOnSynthesize({ history, topic, agents }) {
+  return {
+    consensus: ['We agree on X'],
+    debates: ['We disagree on Y'],
+    actionItems: ['Do Z'],
+    keyInsights: ['Insight A'],
+    suggestedNext: 'execute'
+  };
+}
+
+// ── Suite 1: selectAgents ────────────────────────────────────────────────────
+
+describe('selectAgents', () => {
+  const engine = new PartyEngine();
+
+  it('selects top 3 for architecture topic', () => {
+    const agents = engine.selectAgents('architecture');
+    assert.equal(agents.length, 3);
+    // planner(3) > executor(2) > debugger(1)
+    assert.equal(agents[0].id, 'planner');
+    assert.equal(agents[1].id, 'executor');
+    assert.equal(agents[2].id, 'debugger');
+  });
+
+  it('selects top 3 for testing topic', () => {
+    const agents = engine.selectAgents('testing');
+    assert.equal(agents.length, 3);
+    // qa(3) > executor(2) > verifier(1)
+    assert.equal(agents[0].id, 'qa');
+    assert.equal(agents[1].id, 'executor');
+    assert.equal(agents[2].id, 'verifier');
+  });
+
+  it('handles multi-keyword scoring', () => {
+    const agents = engine.selectAgents('design requirements');
+    // design: ux-designer(3), planner(2), analyst(1)
+    // requirements: analyst(3), planner(2), ux-designer(1)
+    // Combined: ux-designer(4), planner(4), analyst(4) — tie broken by first-match position
+    // design matches ux-designer first (position 0), requirements matches analyst first (position 1)
+    // ux-designer first-match = 0, planner first-match = 0, analyst first-match = 0
+    assert.equal(agents.length, 3);
+    // All three should be present (order may vary due to tie-breaking)
+    const ids = agents.map(a => a.id);
+    assert.ok(ids.includes('ux-designer'));
+    assert.ok(ids.includes('planner'));
+    assert.ok(ids.includes('analyst'));
+  });
+
+  it('breaks ties by first keyword appearance', () => {
+    // Both "scope" and "planning" give scrum-master points
+    // scope: analyst(3), scrum-master(2), planner(1)
+    // planning: planner(3), scrum-master(2), analyst(1)
+    // analyst: 3+1=4, scrum-master: 2+2=4, planner: 1+3=4
+    // All tied at 4 — first-match for analyst at "scope"(pos 0), scrum-master at "scope"(pos 0), planner at "scope"(pos 0)
+    const agents = engine.selectAgents('scope planning');
+    assert.equal(agents.length, 3);
+    const ids = agents.map(a => a.id);
+    assert.ok(ids.includes('analyst'));
+    assert.ok(ids.includes('scrum-master'));
+    assert.ok(ids.includes('planner'));
+  });
+
+  it('uses defaults when no keywords match', () => {
+    const agents = engine.selectAgents('something unrelated');
+    assert.equal(agents.length, 3);
+    // Default scores: analyst(2), planner(2), executor(1) — analyst/planner tied, both at 2
+    const ids = agents.map(a => a.id);
+    assert.ok(ids.includes('analyst'));
+    assert.ok(ids.includes('planner'));
+  });
+
+  it('respects manual --agents override', () => {
+    const agents = engine.selectAgents('anything', { agents: ['debugger', 'qa'] });
+    assert.equal(agents.length, 2);
+    assert.equal(agents[0].id, 'debugger');
+    assert.equal(agents[1].id, 'qa');
+  });
+
+  it('limits to maxAgents parameter', () => {
+    const agents = engine.selectAgents('architecture', { maxAgents: 2 });
+    assert.equal(agents.length, 2);
+  });
+
+  it('detects agent name in topic text', () => {
+    const agents = engine.selectAgents('ask Sherlock about the bug');
+    // Sherlock = debugger, forced first
+    assert.equal(agents[0].id, 'debugger');
+  });
+
+  it('handles empty topic', () => {
+    const agents = engine.selectAgents('');
+    assert.equal(agents.length, 3);
+    // Should get defaults
+  });
+
+  it('handles null/undefined topic gracefully', () => {
+    const agents = engine.selectAgents(null);
+    assert.equal(agents.length, 3);
+  });
+
+  it('does not duplicate for repeated keywords', () => {
+    // Repeating "testing" should not double-score agents
+    const agents1 = engine.selectAgents('testing');
+    const agents2 = engine.selectAgents('testing testing testing');
+    // Same result — dedup prevents re-scoring
+    assert.deepEqual(
+      agents1.map(a => a.id),
+      agents2.map(a => a.id)
+    );
+  });
+
+  it('all 9 agents are reachable via some keyword', () => {
+    const allAgentIds = Object.keys(engine.getCards());
+    const reachable = new Set();
+
+    // Test each keyword bucket
+    for (const keyword of Object.keys(RELEVANCE_MAP)) {
+      const agents = engine.selectAgents(keyword, { maxAgents: 9 });
+      for (const a of agents) reachable.add(a.id);
+    }
+
+    for (const id of allAgentIds) {
+      assert.ok(reachable.has(id), `Agent ${id} should be reachable via keywords`);
+    }
+  });
+
+  it('returns correct score ordering', () => {
+    // "bug" → debugger(3), qa(2), executor(1)
+    const agents = engine.selectAgents('bug');
+    assert.equal(agents[0].id, 'debugger');
+    assert.equal(agents[1].id, 'qa');
+    assert.equal(agents[2].id, 'executor');
+  });
+
+  it('instance maxAgents is respected', () => {
+    const smallEngine = new PartyEngine({ maxAgents: 2 });
+    const agents = smallEngine.selectAgents('architecture');
+    assert.equal(agents.length, 2);
+  });
+
+  it('manual override respects maxAgents limit', () => {
+    const agents = engine.selectAgents('x', {
+      agents: ['debugger', 'qa', 'planner', 'executor'],
+      maxAgents: 2
+    });
+    assert.equal(agents.length, 2);
+  });
+});
+
+// ── Suite 2: Agent Cards ─────────────────────────────────────────────────────
+
+describe('Agent Cards', () => {
+  const engine = new PartyEngine();
+
+  it('loads all 9 cards from JSON', () => {
+    const cards = engine.getCards();
+    assert.equal(Object.keys(cards).length, 9);
+  });
+
+  it('each card has required fields', () => {
+    const requiredFields = ['id', 'name', 'emoji', 'style', 'focus', 'tendency'];
+    const cards = engine.getCards();
+
+    for (const [id, card] of Object.entries(cards)) {
+      for (const field of requiredFields) {
+        assert.ok(card[field] !== undefined, `Card ${id} missing field: ${field}`);
+        assert.ok(typeof card[field] === 'string', `Card ${id}.${field} should be a string`);
+        assert.ok(card[field].length > 0, `Card ${id}.${field} should not be empty`);
+      }
+    }
+  });
+
+  it('no duplicate names or emojis', () => {
+    const cards = Object.values(engine.getCards());
+    const names = cards.map(c => c.name);
+    const emojis = cards.map(c => c.emoji);
+
+    assert.equal(new Set(names).size, names.length, 'Duplicate names found');
+    assert.equal(new Set(emojis).size, emojis.length, 'Duplicate emojis found');
+  });
+
+  it('getCard returns correct card by ID', () => {
+    const card = engine.getCard('qa');
+    assert.equal(card.name, 'Murat');
+    assert.equal(card.id, 'qa');
+  });
+
+  it('getCard returns undefined for unknown ID', () => {
+    const card = engine.getCard('unknown-agent');
+    assert.equal(card, undefined);
+  });
+});
+
+// ── Suite 3: Round Management ────────────────────────────────────────────────
+
+describe('Round Management', () => {
+  it('executes correct number of rounds', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 2, maxAgents: 2 });
+
+    const rounds = [];
+    const result = await engine.run('architecture testing', {}, {
+      onAgentTurn: (params) => {
+        rounds.push(params.round);
+        return mockOnAgentTurn(params);
+      }
+    });
+
+    // 2 rounds × 2 agents = 4 calls
+    assert.equal(rounds.length, 4);
+    assert.equal(result.rounds, 2);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('calls onAgentTurn for each agent in each round', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 2, maxAgents: 3 });
+
+    const calls = [];
+    await engine.run('testing', {}, {
+      onAgentTurn: (params) => {
+        calls.push({ agent: params.agent.id, round: params.round });
+        return 'response';
+      }
+    });
+
+    // 2 rounds × 3 agents = 6 calls
+    assert.equal(calls.length, 6);
+    // Round 1 should have 3 calls, round 2 should have 3 calls
+    assert.equal(calls.filter(c => c.round === 1).length, 3);
+    assert.equal(calls.filter(c => c.round === 2).length, 3);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('passes cumulative history', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 2, maxAgents: 2 });
+
+    const historySizes = [];
+    await engine.run('testing', {}, {
+      onAgentTurn: (params) => {
+        historySizes.push(params.history.length);
+        return 'response';
+      }
+    });
+
+    // R1A1: 0, R1A2: 1, R2A1: 2, R2A2: 3
+    assert.deepEqual(historySizes, [0, 1, 2, 3]);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('round 1 instruction is initial perspective', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 1, maxAgents: 1 });
+
+    let instruction = '';
+    await engine.run('testing', {}, {
+      onAgentTurn: (params) => {
+        instruction = params.instruction;
+        return 'response';
+      }
+    });
+
+    assert.ok(instruction.includes('initial perspective'));
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('round N>1 instruction is react', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 2, maxAgents: 1 });
+
+    let lastInstruction = '';
+    await engine.run('testing', {}, {
+      onAgentTurn: (params) => {
+        lastInstruction = params.instruction;
+        return 'response';
+      }
+    });
+
+    assert.ok(lastInstruction.includes('React'));
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('stops early on "stop" from onRoundComplete', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 3, maxAgents: 2 });
+
+    const result = await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn,
+      onRoundComplete: ({ completedRound }) => {
+        if (completedRound === 1) return 'stop';
+        return 'continue';
+      }
+    });
+
+    assert.equal(result.rounds, 1);
+    assert.equal(result.history.length, 2); // 1 round × 2 agents
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('adds round on "add_round" from onRoundComplete', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 2, maxAgents: 1 });
+
+    let addedOnce = false;
+    const result = await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn,
+      onRoundComplete: ({ completedRound }) => {
+        if (completedRound === 2 && !addedOnce) {
+          addedOnce = true;
+          return 'add_round';
+        }
+        return 'continue';
+      }
+    });
+
+    // 2 original + 1 added = 3 rounds
+    assert.equal(result.rounds, 3);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('saves checkpoint after each round', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 2, maxAgents: 1 });
+
+    const result = await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn
+    });
+
+    // Check checkpoints were created (may have been cleaned)
+    // The session ID is in the result
+    assert.ok(result.sessionId.startsWith('party-testing-'));
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('handles callback error gracefully', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 1, maxAgents: 1 });
+
+    await assert.rejects(
+      () => engine.run('testing', {}, {
+        onAgentTurn: () => { throw new Error('Agent failed'); }
+      }),
+      { message: 'Agent failed' }
+    );
+
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('respects maxRounds limit', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 1, maxAgents: 1 });
+
+    const result = await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn
+    });
+
+    assert.equal(result.rounds, 1);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('auto-continues when onRoundComplete not provided', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 2, maxAgents: 1 });
+
+    const result = await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn
+    });
+
+    // Should complete all rounds without onRoundComplete
+    assert.equal(result.rounds, 2);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('requires onAgentTurn callback', async () => {
+    const engine = new PartyEngine();
+    await assert.rejects(
+      () => engine.run('testing', {}, {}),
+      { message: /requires callbacks.onAgentTurn/ }
+    );
+  });
+});
+
+// ── Suite 4: Synthesis ───────────────────────────────────────────────────────
+
+describe('Synthesis', () => {
+  it('calls onSynthesize with full history', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 1, maxAgents: 2 });
+
+    let synthArgs = null;
+    await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn,
+      onSynthesize: (params) => {
+        synthArgs = params;
+        return mockOnSynthesize(params);
+      }
+    });
+
+    assert.ok(synthArgs);
+    assert.equal(synthArgs.history.length, 2); // 1 round × 2 agents
+    assert.equal(synthArgs.topic, 'testing');
+    assert.equal(synthArgs.agents.length, 2);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('returns structured result', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 1, maxAgents: 1 });
+
+    const result = await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn,
+      onSynthesize: mockOnSynthesize
+    });
+
+    assert.ok(result.synthesis);
+    assert.ok(Array.isArray(result.synthesis.consensus));
+    assert.ok(Array.isArray(result.synthesis.debates));
+    assert.ok(Array.isArray(result.synthesis.actionItems));
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('handles missing onSynthesize (returns empty synthesis)', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 1, maxAgents: 1 });
+
+    const result = await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn
+    });
+
+    assert.ok(result.synthesis);
+    assert.deepEqual(result.synthesis.consensus, []);
+    assert.deepEqual(result.synthesis.debates, []);
+    assert.deepEqual(result.synthesis.actionItems, []);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('validates synthesis has keyInsights and suggestedNext', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 1, maxAgents: 1 });
+
+    const result = await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn,
+      onSynthesize: mockOnSynthesize
+    });
+
+    assert.ok(Array.isArray(result.synthesis.keyInsights));
+    assert.equal(result.synthesis.suggestedNext, 'execute');
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('passes correct agents list to onSynthesize', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 1, maxAgents: 2 });
+
+    let synthAgents = [];
+    await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn,
+      onSynthesize: (params) => {
+        synthAgents = params.agents;
+        return mockOnSynthesize(params);
+      }
+    });
+
+    assert.equal(synthAgents.length, 2);
+    // For "testing": qa, executor
+    assert.ok(synthAgents.some(a => a.id === 'qa'));
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+// ── Suite 5: Persistence ─────────────────────────────────────────────────────
+
+describe('Persistence', () => {
+  it('generates correct sessionId slug', () => {
+    const slug = slugify('Architecture vs Monolith!');
+    assert.equal(slug, 'architecture-vs-monolith');
+  });
+
+  it('slugify handles special characters', () => {
+    assert.equal(slugify('hello   world'), 'hello-world');
+    assert.equal(slugify('---start---'), 'start');
+    assert.equal(slugify(''), '');
+    assert.equal(slugify('CAPS Test'), 'caps-test');
+  });
+
+  it('slugify truncates to 40 chars', () => {
+    const long = 'a'.repeat(100);
+    assert.ok(slugify(long).length <= 40);
+  });
+
+  it('checkpoint files exist during run', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 2, maxAgents: 1 });
+
+    let cpCount = 0;
+    await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn,
+      onRoundComplete: () => {
+        // Check checkpoint files during execution
+        const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+        cpCount = files.length;
+        return 'continue';
+      }
+    });
+
+    // At least 1 checkpoint should have existed during run
+    assert.ok(cpCount >= 1);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('checkpoint cleaned after completion (keepLast=2)', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 3, maxAgents: 1 });
+
+    const result = await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn
+    });
+
+    // 3 rounds = 3 checkpoints saved, then clean(keepLast=2) → 2 remain
+    const files = fs.readdirSync(dir).filter(f => f.startsWith('party-'));
+    assert.ok(files.length <= 2, `Expected <=2 checkpoints, got ${files.length}`);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('result includes valid sessionId', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 1, maxAgents: 1 });
+
+    const result = await engine.run('my topic here', {}, {
+      onAgentTurn: mockOnAgentTurn
+    });
+
+    assert.ok(result.sessionId.startsWith('party-my-topic-here-'));
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('result includes complete history entries', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 1, maxAgents: 2 });
+
+    const result = await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn
+    });
+
+    assert.equal(result.history.length, 2);
+    for (const entry of result.history) {
+      assert.ok(entry.round);
+      assert.ok(entry.agent);
+      assert.ok(entry.agent.id);
+      assert.ok(entry.agent.name);
+      assert.ok(typeof entry.response === 'string');
+      assert.ok(entry.timestamp);
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('result agents list matches selected agents', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 1, maxAgents: 2 });
+
+    const result = await engine.run('bug debug', {}, {
+      onAgentTurn: mockOnAgentTurn
+    });
+
+    assert.equal(result.agents.length, 2);
+    // "bug": debugger(3), qa(2), executor(1) — top 2
+    assert.equal(result.agents[0].id, 'debugger');
+    assert.equal(result.agents[1].id, 'qa');
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+// ── Suite 6: Integration ─────────────────────────────────────────────────────
+
+describe('Integration', () => {
+  it('full party session with mock callbacks (3 rounds, 3 agents)', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 3, maxAgents: 3 });
+
+    const result = await engine.run('architecture testing design', {}, {
+      onAgentTurn: mockOnAgentTurn,
+      onSynthesize: mockOnSynthesize
+    });
+
+    assert.equal(result.rounds, 3);
+    assert.equal(result.history.length, 9); // 3 rounds × 3 agents
+    assert.equal(result.agents.length, 3);
+    assert.ok(result.synthesis);
+    assert.ok(result.sessionId);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('party with checkpoint resume', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 3, maxAgents: 1 });
+
+    // Run and stop after round 1
+    const result1 = await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn,
+      onRoundComplete: ({ completedRound }) => completedRound === 1 ? 'stop' : 'continue'
+    });
+
+    assert.equal(result1.rounds, 1);
+
+    // Resume from checkpoint
+    const result2 = await engine.resume(result1.sessionId, {
+      onAgentTurn: mockOnAgentTurn,
+      onSynthesize: mockOnSynthesize
+    });
+
+    // Should have continued from round 2 to round 3
+    assert.equal(result2.rounds, 3);
+    // Total history: round 1 (from checkpoint) + rounds 2,3 (from resume)
+    assert.equal(result2.history.length, 3);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('party with early stop after round 1', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 5, maxAgents: 2 });
+
+    const result = await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn,
+      onSynthesize: mockOnSynthesize,
+      onRoundComplete: () => 'stop'
+    });
+
+    assert.equal(result.rounds, 1);
+    assert.equal(result.history.length, 2); // 1 round × 2 agents
+    assert.ok(result.synthesis.consensus.length > 0);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('party with add_round extends to 4', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 3, maxAgents: 1 });
+
+    let added = false;
+    const result = await engine.run('testing', {}, {
+      onAgentTurn: mockOnAgentTurn,
+      onRoundComplete: ({ completedRound }) => {
+        if (completedRound === 3 && !added) {
+          added = true;
+          return 'add_round';
+        }
+        return 'continue';
+      }
+    });
+
+    assert.equal(result.rounds, 4);
+    assert.equal(result.history.length, 4); // 4 rounds × 1 agent
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('party with manual agent override', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir, maxRounds: 1 });
+
+    const result = await engine.run('anything', { agents: ['tech-writer', 'verifier'] }, {
+      onAgentTurn: mockOnAgentTurn,
+      onSynthesize: mockOnSynthesize
+    });
+
+    assert.equal(result.agents.length, 2);
+    assert.equal(result.agents[0].id, 'tech-writer');
+    assert.equal(result.agents[1].id, 'verifier');
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('resume requires onAgentTurn callback', async () => {
+    const engine = new PartyEngine();
+    await assert.rejects(
+      () => engine.resume('some-session', {}),
+      { message: /requires callbacks.onAgentTurn/ }
+    );
+  });
+
+  it('resume throws for missing checkpoint', async () => {
+    const dir = tmpDir();
+    const engine = new PartyEngine({ checkpointDir: dir });
+
+    await assert.rejects(
+      () => engine.resume('nonexistent-session', { onAgentTurn: mockOnAgentTurn }),
+      { message: /No checkpoint found/ }
+    );
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+// ── Helper function tests ────────────────────────────────────────────────────
+
+describe('Helper functions', () => {
+  it('detectAgentNames finds names in text', () => {
+    assert.deepEqual(detectAgentNames('ask Sherlock'), ['debugger']);
+    assert.deepEqual(detectAgentNames('Murat and Sally'), ['qa', 'ux-designer']);
+    assert.deepEqual(detectAgentNames('nothing here'), []);
+  });
+
+  it('detectAgentNames is case-insensitive', () => {
+    assert.deepEqual(detectAgentNames('SHERLOCK'), ['debugger']);
+    assert.deepEqual(detectAgentNames('murat'), ['qa']);
+  });
+});