actoviq-agent-sdk 0.4.1 → 0.4.2

package/dist/src/team/modelTeam.js

@@ -101,567 +101,125 @@ async function mapWithConcurrency(items, limit, fn) {
     return results;
 }
 // ═══════════════════════════════════════════════════════════════════
-//  Panel Mode — multi-round autonomous deliberation
+//  Reviewer Mode — single read-only ReAct reviewer the main agent invokes
 // ═══════════════════════════════════════════════════════════════════
-async function runPanelMode(prompt, definition, signal) {
-    const startedAt = Date.now();
-    const primaryApi = await createMemberApi(definition.primary);
-    const memberApis = await Promise.all(definition.members.map((m) => createMemberApi(m)));
-    let rounds = 0;
-    const allResponses = [];
-    const modelSet = new Set(definition.members.map((m) => m.model));
-    modelSet.add(definition.primary.model);
-    const perModelTokens = new Map();
-    let totalInput = 0;
-    let totalOutput = 0;
-    // Round 1: parallel panel
-    rounds++;
-    const round1Start = Date.now();
-    const pool = getGlobalAgentPool();
-    const panelResults = await mapWithConcurrency(definition.members, definition.maxParallel ?? definition.members.length, async (member, i) => {
-        let slot;
-        try {
-            slot = await pool.acquire(definition.timeoutMs);
-            const result = await singleModelCall(memberApis[i], prompt, member.systemPrompt, memberSignal(signal, definition.timeoutMs));
-            const resp = {
-                round: 1,
-                model: member.model,
-                content: result.content,
-                tokens: { input: result.inputTokens, output: result.outputTokens },
-                durationMs: result.durationMs,
-            };
-            // Track tokens
-            const existing = perModelTokens.get(member.model) ?? { input: 0, output: 0 };
-            existing.input += result.inputTokens;
-            existing.output += result.outputTokens;
-            perModelTokens.set(member.model, existing);
-            totalInput += result.inputTokens;
-            totalOutput += result.outputTokens;
-            return resp;
-        }
-        catch {
-            // Graceful degradation: return error marker
-            return {
-                round: 1,
-                model: member.model,
-                content: `[ERROR: ${member.model} failed to respond]`,
-                tokens: { input: 0, output: 0 },
-                durationMs: Date.now() - round1Start,
-            };
-        }
-        finally {
-            slot?.release();
-        }
-    });
-    allResponses.push(...panelResults);
-    // Primary model analyzes and decides
-    const panelSummary = allResponses
-        .map((r) => `### ${r.model}\n${r.content}`)
-        .join('\n\n---\n\n');
-    const analysisPrompt = [
-        'You are the primary decision-maker in a multi-model panel.',
-        'Below are responses from multiple models to the same question.',
-        '',
-        'Your task:',
-        '1. Analyze the responses — note agreements, contradictions, unique insights',
-        '2. Decide whether the answer is complete or needs another round',
-        '3. If complete, synthesize a comprehensive final answer',
-        '4. If not complete, specify what needs further exploration',
-        '',
-        'Original question:',
-        prompt,
-        '',
-        'Panel responses:',
-        panelSummary,
-        '',
-        'Respond in one of these formats:',
-        '',
-        'To FINALIZE (answer is complete):',
-        'FINALIZE',
-        '<your comprehensive synthesized answer>',
-        '',
-        'To CONTINUE (need another round):',
-        'CONTINUE',
-        '<refined question for the next round>',
-        '<specific aspects to explore>',
-    ].join('\n');
-    const primaryResult = await singleModelCall(primaryApi, analysisPrompt, definition.primary?.systemPrompt, memberSignal(signal, definition.timeoutMs));
-    totalInput += primaryResult.inputTokens;
-    totalOutput += primaryResult.outputTokens;
-    const primaryModel = definition.primary.model;
-    const existing = perModelTokens.get(primaryModel) ?? { input: 0, output: 0 };
-    existing.input += primaryResult.inputTokens;
-    existing.output += primaryResult.outputTokens;
-    perModelTokens.set(primaryModel, existing);
-    // Parse primary decision
-    const isContinue = primaryResult.content.trim().startsWith('CONTINUE');
-    let finalAnswer;
-    if (isContinue) {
-        // Additional rounds — primary model continues to deliberate
-        const refinedQuestion = primaryResult.content.replace(/^CONTINUE\s*/i, '').trim();
-        let currentQuestion = refinedQuestion || prompt;
-        let converged = false;
-        // Carry the most recent round's responses forward for panel members.
-        let previousContext = panelSummary;
-        // Full deliberation history visible to the primary every round: all prior
-        // panel responses AND the primary's own prior analyses (plan: the primary
-        // accumulates full context across rounds to deliberate, not just round 1).
-        const deliberationLog = [
-            `## Round 1 — Panel responses\n${panelSummary}`,
-            `## Round 1 — Primary analysis\n${primaryResult.content}`,
-        ];
-        const maxRounds = definition.maxRounds ?? 100;
-        while (!converged && rounds < maxRounds) { // Safety cap, but primary decides convergence
-            rounds++;
-            const roundStart = Date.now();
-            const roundResults = await mapWithConcurrency(definition.members, definition.maxParallel ?? definition.members.length, async (member, i) => {
-                let slot;
-                try {
-                    slot = await pool.acquire(definition.timeoutMs);
-                    const result = await singleModelCall(memberApis[i], `[Round ${rounds}] ${currentQuestion}\n\nPrevious round context:\n${previousContext}`, member.systemPrompt, memberSignal(signal, definition.timeoutMs));
-                    const resp = {
-                        round: rounds,
-                        model: member.model,
-                        content: result.content,
-                        tokens: { input: result.inputTokens, output: result.outputTokens },
-                        durationMs: Date.now() - roundStart,
-                    };
-                    const ex = perModelTokens.get(member.model) ?? { input: 0, output: 0 };
-                    ex.input += result.inputTokens;
-                    ex.output += result.outputTokens;
-                    perModelTokens.set(member.model, ex);
-                    totalInput += result.inputTokens;
-                    totalOutput += result.outputTokens;
-                    return resp;
-                }
-                catch {
-                    return {
-                        round: rounds,
-                        model: member.model,
-                        content: `[ERROR: ${member.model} failed]`,
-                        tokens: { input: 0, output: 0 },
-                        durationMs: Date.now() - roundStart,
-                    };
-                }
-                finally {
-                    slot?.release();
-                }
-            });
-            allResponses.push(...roundResults);
-            const roundSummary = roundResults
-                .map((r) => `### ${r.model}\n${r.content}`)
-                .join('\n\n---\n\n');
-            previousContext = roundSummary;
-            const followUpPrompt = [
-                'You are the primary decision-maker in a multi-model panel.',
-                `This is round ${rounds}. Use the full deliberation history below (all prior rounds' panel responses and your own prior analyses), then weigh this round's new responses.`,
-                '',
-                'Original question:',
-                prompt,
-                '',
-                'Full deliberation history:',
-                deliberationLog.join('\n\n---\n\n'),
-                '',
-                `Round ${rounds} new panel responses to "${currentQuestion}":`,
-                roundSummary,
-                '',
-                'Decide: FINALIZE (then give the comprehensive synthesized answer) or CONTINUE (then give a refined question and the specific aspects to explore).',
-            ].join('\n');
-            const followUpResult = await singleModelCall(primaryApi, followUpPrompt, definition.primary?.systemPrompt, memberSignal(signal, definition.timeoutMs));
-            totalInput += followUpResult.inputTokens;
-            totalOutput += followUpResult.outputTokens;
-            const pex = perModelTokens.get(primaryModel) ?? { input: 0, output: 0 };
-            pex.input += followUpResult.inputTokens;
-            pex.output += followUpResult.outputTokens;
-            perModelTokens.set(primaryModel, pex);
-            if (followUpResult.content.trim().startsWith('FINALIZE')) {
-                finalAnswer = followUpResult.content.replace(/^FINALIZE\s*/i, '').trim();
-                converged = true;
-            }
-            else {
-                currentQuestion = followUpResult.content.replace(/^CONTINUE\s*/i, '').trim() || currentQuestion;
-            }
-            deliberationLog.push(`## Round ${rounds} — Panel responses\n${roundSummary}`);
-            deliberationLog.push(`## Round ${rounds} — Primary decision\n${followUpResult.content}`);
-        }
-        if (!converged) {
-            finalAnswer = primaryResult.content;
-        }
-    }
-    else {
-        finalAnswer = primaryResult.content.replace(/^FINALIZE\s*/i, '').trim();
-    }
-    const cost = computeCost([...modelSet], totalInput, totalOutput, perModelTokens);
-    return {
-        answer: finalAnswer,
-        mode: 'panel',
-        rounds,
-        panelResponses: allResponses,
-        cost,
-        durationMs: Date.now() - startedAt,
-    };
+/** Read-only tool set for expert/reviewer agents (no write/edit/bash/delegation). */
+async function buildReadOnlyExpertTools(cwd) {
+    const { createActoviqFileTools } = await import('../tools/actoviqFileTools.js');
+    const { createActoviqWebTools } = await import('../tools/actoviqWebTools.js');
+    const { createTavilySearchTool } = await import('../tools/tavilySearch.js');
+    const READ_ONLY_FILE_TOOLS = new Set(['Read', 'Glob', 'Grep']);
+    return [
+        ...createActoviqFileTools({ cwd }).filter((t) => READ_ONLY_FILE_TOOLS.has(t.name)),
+        ...createActoviqWebTools().filter((t) => t.name === 'WebFetch'),
+        createTavilySearchTool(),
+    ];
 }
-// ═══════════════════════════════════════════════════════════════════
-//  Router Mode — user-configured dispatch
-// ═══════════════════════════════════════════════════════════════════
-async function runRouterMode(prompt, definition, signal) {
+/**
+ * A single read-only ReAct agent (Read/Glob/Grep + TavilySearch/WebFetch) that
+ * inspects the project and returns confirmed issues. The main agent (the
+ * "executor") invokes it as a tool, decides what `context` to inject — what it
+ * did and the results it obtained, placed in the reviewer's system prompt — and
+ * keeps final authority over the findings. The reviewer is told to scrutinize
+ * hard but confirm ONLY issues it can actually verify: no speculation, no
+ * fabricated or padded findings.
+ */
+async function runReviewerMode(task, definition, signal, context, workDir) {
     const startedAt = Date.now();
-    const routerApi = await createMemberApi(definition.router);
-    const specialistApis = new Map();
-    for (const [key, spec] of Object.entries(definition.specialists ?? {})) {
-        specialistApis.set(key, await createMemberApi(spec));
-    }
-    const fallbackApi = definition.fallback ? await createMemberApi(definition.fallback) : null;
-    // Build classification prompt
-    const specialistDescriptions = Object.entries(definition.specialists ?? {})
-        .map(([key, spec]) => `- ${key}: ${spec.description ?? 'General tasks'}`)
-        .join('\n');
-    const classificationPrompt = definition.classificationPrompt ?? [
-        'You are a task classifier. Based on the user\'s request, determine which specialist should handle it.',
-        '',
-        'Available specialists:',
-        specialistDescriptions,
-        definition.fallback ? `- fallback: ${definition.fallback.description ?? 'General assistance'}` : null,
-        '',
-        'User request:',
-        prompt,
-        '',
-        'Return ONLY the specialist name (one word, lowercase).',
+    const reviewer = definition.reviewer;
+    // Lazy import avoids a circular dependency (agentClient imports modelTeam).
+    const { createAgentSdk } = await import('../runtime/agentClient.js');
+    const cwd = workDir ?? process.cwd();
+    const reviewerFraming = [
+        'You are a meticulous reviewer on a multi-model team.',
+        'Inspect the project using ONLY your read-only tools (Read/Glob/Grep) and the web',
+        '(TavilySearch/WebFetch). You cannot modify files, write code, or run commands.',
+        'Scrutinize as thoroughly as you can and surface every genuine problem — bugs, broken',
+        'logic, security holes, missed edge cases, violated requirements — each with concrete',
+        'file:line evidence. Critically: confirm ONLY issues you can actually verify from the',
+        'code or files. Do not speculate, invent, or pad the list; if something is uncertain,',
+        'say so explicitly instead of asserting it. If you find no real issues, say so plainly.',
+    ].join(' ');
+    const systemPrompt = [
+        reviewerFraming,
+        context ? `\n## Context from the requesting agent (what it did and obtained)\n${context}` : '',
+        reviewer.systemPrompt ? `\n${reviewer.systemPrompt}` : '',
     ].filter(Boolean).join('\n');
-    const classifyResult = await singleModelCall(routerApi, classificationPrompt, definition.router?.systemPrompt, memberSignal(signal, definition.timeoutMs));
-    const specialistKey = classifyResult.content.trim().toLowerCase();
-    const validKeys = Object.keys(definition.specialists ?? {});
-    let chosenApi;
-    let chosenKey;
-    let chosenMember;
-    if (validKeys.includes(specialistKey)) {
-        chosenApi = specialistApis.get(specialistKey);
-        chosenKey = specialistKey;
-        chosenMember = definition.specialists[specialistKey];
-    }
-    else if (fallbackApi) {
-        chosenApi = fallbackApi;
-        chosenKey = 'fallback';
-        chosenMember = definition.fallback;
-    }
-    else {
-        // No fallback, pick first specialist
-        chosenKey = validKeys[0] ?? 'default';
-        chosenApi = specialistApis.get(chosenKey);
-        chosenMember = definition.specialists[chosenKey];
-    }
-    const result = await singleModelCall(chosenApi, prompt, chosenMember.systemPrompt, memberSignal(signal, definition.timeoutMs));
-    const modelSet = new Set();
-    modelSet.add(definition.router.model);
-    modelSet.add(chosenMember.model);
-    const perModelTokens = new Map();
-    perModelTokens.set(definition.router.model, { input: classifyResult.inputTokens, output: classifyResult.outputTokens });
-    perModelTokens.set(chosenMember.model, { input: result.inputTokens, output: result.outputTokens });
-    const cost = computeCost([...modelSet], classifyResult.inputTokens + result.inputTokens, classifyResult.outputTokens + result.outputTokens, perModelTokens);
-    return {
-        answer: result.content,
-        mode: 'router',
-        specialist: chosenKey,
-        classification: classifyResult.content,
-        cost,
-        durationMs: Date.now() - startedAt,
-    };
-}
-// ═══════════════════════════════════════════════════════════════════
-//  Discussion Mode — roundtable for hard problems
-// ═══════════════════════════════════════════════════════════════════
-async function runDiscussionMode(prompt, definition, signal) {
-    const startedAt = Date.now();
-    const primaryApi = await createMemberApi(definition.primary);
-    const memberApis = await Promise.all(definition.members.map((m) => createMemberApi(m)));
-    const facilitatorApi = definition.facilitator
-        ? await createMemberApi(definition.facilitator)
-        : primaryApi; // fallback: primary acts as facilitator
-    let rounds = 0;
-    let converged = false;
-    let finalAnswer = '';
-    const facilitatorVerdicts = [];
-    const modelSet = new Set();
-    definition.members.forEach((m) => modelSet.add(m.model));
-    modelSet.add(definition.primary.model);
-    if (definition.facilitator)
-        modelSet.add(definition.facilitator.model);
     const perModelTokens = new Map();
     let totalInput = 0;
     let totalOutput = 0;
-    let discussionTranscript = `# Discussion Topic\n${prompt}\n\n`;
-    const maxRounds = definition.maxRounds ?? 100;
-    while (!converged && rounds < maxRounds) {
-        rounds++;
-        // Sequential speaking: each member sees prior speakers
-        for (let i = 0; i < definition.members.length; i++) {
-            const member = definition.members[i];
-            const speakPrompt = [
-                `## Discussion Round ${rounds}`,
-                '',
-                `Topic: ${prompt}`,
-                '',
-                'Previous discussion:',
-                discussionTranscript,
-                '',
-                `You are ${member.model}. Please contribute your perspective. ` +
-                    'Consider what previous speakers have said. Build on agreements, address disagreements.',
-            ].join('\n');
-            const result = await singleModelCall(memberApis[i], speakPrompt, member.systemPrompt, memberSignal(signal, definition.timeoutMs));
-            discussionTranscript += `\n### ${member.model} (Round ${rounds})\n${result.content}\n`;
-            const ex = perModelTokens.get(member.model) ?? { input: 0, output: 0 };
-            ex.input += result.inputTokens;
-            ex.output += result.outputTokens;
-            perModelTokens.set(member.model, ex);
-            totalInput += result.inputTokens;
-            totalOutput += result.outputTokens;
-        }
-        // Facilitator subagent rules after the round
-        const facilitatorPrompt = [
-            'You are a discussion facilitator. Review the roundtable transcript and provide:',
-            '',
-            '1. **Summary**: Key points raised, areas of agreement and disagreement',
-            '2. **Progress Assessment**: Is the discussion converging? Are there blockers?',
-            '3. **Verdict**: Should discussion CONTINUE or FINALIZE?',
-            '',
-            'Respond in this format:',
-            '',
-            'SUMMARY:',
-            '<summary>',
-            '',
-            'VERDICT: CONTINUE|FINALIZE',
-            '',
-            'If CONTINUE, add:',
-            'NEXT_TOPIC: <what the next round should focus on>',
-            '',
-            'Discussion transcript:',
-            discussionTranscript,
-        ].join('\n');
-        const facilitatorResult = await singleModelCall(facilitatorApi, facilitatorPrompt, definition.facilitator?.systemPrompt, memberSignal(signal, definition.timeoutMs));
-        if (definition.facilitator) {
-            const fex = perModelTokens.get(definition.facilitator.model) ?? { input: 0, output: 0 };
-            fex.input += facilitatorResult.inputTokens;
-            fex.output += facilitatorResult.outputTokens;
-            perModelTokens.set(definition.facilitator.model, fex);
-        }
-        totalInput += facilitatorResult.inputTokens;
-        totalOutput += facilitatorResult.outputTokens;
-        const summaryMatch = facilitatorResult.content.match(/SUMMARY:\s*\n([\s\S]*?)(?=\nVERDICT:|$)/i);
-        const verdictMatch = facilitatorResult.content.match(/VERDICT:\s*(CONTINUE|FINALIZE)/i);
-        const nextTopicMatch = facilitatorResult.content.match(/NEXT_TOPIC:\s*(.+)/i);
-        const verdict = verdictMatch?.[1]?.toUpperCase() === 'FINALIZE' ? 'finalize' : 'continue';
-        facilitatorVerdicts.push({
-            round: rounds,
-            summary: summaryMatch?.[1]?.trim() ?? facilitatorResult.content,
-            verdict,
+    let report;
+    let toolCalls = 0;
+    const pool = getGlobalAgentPool();
+    let slot;
+    let sdk;
+    try {
+        slot = await pool.acquire(definition.timeoutMs);
+        sdk = await createAgentSdk({
+            model: reviewer.model,
+            provider: reviewer.provider,
+            baseURL: reviewer.baseURL,
+            authToken: resolveApiKey(reviewer.apiKey),
+            maxTokens: reviewer.maxTokens ?? 32000,
+            workDir: cwd,
+            tools: await buildReadOnlyExpertTools(cwd),
+            permissionMode: 'bypassPermissions',
+            maxToolIterations: definition.maxIterations ?? 16,
+            systemPrompt,
         });
-        // Primary model makes final decision
-        const primaryDecisionPrompt = [
-            'As the primary decision-maker, review the facilitator\'s report and the full discussion.',
-            '',
-            'Facilitator recommendation:',
-            facilitatorResult.content,
-            '',
-            'Full discussion transcript:',
-            discussionTranscript,
-            '',
-            'You may override the facilitator\'s recommendation. Decide:',
-            '- FINALIZE: synthesize the solution and deliver it',
-            '- CONTINUE: specify what the next round should address',
-            '',
-            'Respond with FINALIZE or CONTINUE followed by your reasoning/output.',
-        ].join('\n');
-        const primaryResult = await singleModelCall(primaryApi, primaryDecisionPrompt, definition.primary?.systemPrompt, memberSignal(signal, definition.timeoutMs));
-        const pex = perModelTokens.get(definition.primary.model) ?? { input: 0, output: 0 };
-        pex.input += primaryResult.inputTokens;
-        pex.output += primaryResult.outputTokens;
-        perModelTokens.set(definition.primary.model, pex);
-        totalInput += primaryResult.inputTokens;
-        totalOutput += primaryResult.outputTokens;
-        if (primaryResult.content.trim().startsWith('FINALIZE')) {
-            finalAnswer = primaryResult.content.replace(/^FINALIZE\s*/i, '').trim();
-            converged = true;
-        }
-        else {
-            const nextTopic = nextTopicMatch?.[1] ?? primaryResult.content.replace(/^CONTINUE\s*/i, '').trim();
-            discussionTranscript += `\n### Facilitator (Round ${rounds})\nVerdict: CONTINUE\nNext topic: ${nextTopic}\n`;
-        }
+        const result = await sdk.run(task, { signal: memberSignal(signal, definition.timeoutMs) });
+        report = result.text;
+        toolCalls = result.toolCalls.length;
+        const input = result.requests.reduce((s, r) => s + (r.usage?.input_tokens ?? 0), 0);
+        const output = result.requests.reduce((s, r) => s + (r.usage?.output_tokens ?? 0), 0);
+        perModelTokens.set(reviewer.model, { input, output });
+        totalInput = input;
+        totalOutput = output;
     }
-    if (!converged) {
-        finalAnswer = discussionTranscript;
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        report = `[ERROR: reviewer ${reviewer.model} failed — ${message}]`;
     }
-    const cost = computeCost([...modelSet], totalInput, totalOutput, perModelTokens);
-    return {
-        answer: finalAnswer,
-        mode: 'discussion',
-        rounds,
-        facilitatorVerdicts,
-        cost,
-        durationMs: Date.now() - startedAt,
-    };
-}
-// ═══════════════════════════════════════════════════════════════════
-//  Executor-Reviewer Mode — advisory critique loop
-// ═══════════════════════════════════════════════════════════════════
-async function runExecutorReviewerMode(prompt, definition, signal) {
-    const startedAt = Date.now();
-    const executorApi = await createMemberApi(definition.executor);
-    const reviewerApi = await createMemberApi(definition.reviewer);
-    const decisions = [];
-    const reviews = [];
-    const modelSet = new Set([definition.executor.model, definition.reviewer.model]);
-    const perModelTokens = new Map();
-    let totalInput = 0;
-    let totalOutput = 0;
-    let iterations = 0;
-    let converged = false;
-    let finalAnswer = '';
-    let currentOutput = '';
-    const maxIterations = definition.maxIterations ?? 100;
-    // Full history visible to both roles each iteration (plan: prevents the
-    // reviewer from repeating already-addressed or rejected suggestions).
-    const transcript = [];
-    // Iteration 1: Executor produces initial output
-    iterations++;
-    const execResult = await singleModelCall(executorApi, prompt, definition.executor?.systemPrompt, memberSignal(signal, definition.timeoutMs));
-    currentOutput = execResult.content;
-    transcript.push(`## Iteration 1 — Executor output\n${currentOutput}`);
-    perModelTokens.set(definition.executor.model, { input: execResult.inputTokens, output: execResult.outputTokens });
-    totalInput += execResult.inputTokens;
-    totalOutput += execResult.outputTokens;
-    while (!converged && iterations < maxIterations) {
-        // Reviewer critiques
-        const reviewPrompt = [
-            'You are an experienced reviewer providing constructive feedback.',
-            'The history below shows prior outputs, your earlier reviews, and the executor\'s decisions (including which suggestions were rejected and why). Do NOT repeat suggestions already addressed or explicitly rejected — focus on new, unaddressed improvements.',
-            '',
-            'Original request:',
-            prompt,
-            '',
-            'History so far:',
-            transcript.join('\n\n---\n\n'),
-            '',
-            'Latest output to review:',
-            currentOutput,
-            '',
-            'Provide specific, actionable feedback. You are an advisor — the executor makes final decisions.',
-        ].join('\n');
-        const reviewResult = await singleModelCall(reviewerApi, reviewPrompt, definition.reviewer?.systemPrompt, memberSignal(signal, definition.timeoutMs));
-        reviews.push({ iteration: iterations, feedback: reviewResult.content });
-        transcript.push(`## Iteration ${iterations} — Reviewer feedback\n${reviewResult.content}`);
-        const rex = perModelTokens.get(definition.reviewer.model) ?? { input: 0, output: 0 };
-        rex.input += reviewResult.inputTokens;
-        rex.output += reviewResult.outputTokens;
-        perModelTokens.set(definition.reviewer.model, rex);
-        totalInput += reviewResult.inputTokens;
-        totalOutput += reviewResult.outputTokens;
-        // Executor decides: accept/reject/partial/finalize
-        const decisionPrompt = [
-            'You are the executor with final authority. Review the feedback and decide.',
-            '',
-            'Original request:',
-            prompt,
-            '',
-            'History so far (prior outputs, reviews, and your past decisions):',
-            transcript.join('\n\n---\n\n'),
-            '',
-            'Your current output:',
-            currentOutput,
-            '',
-            'Latest reviewer feedback:',
-            reviewResult.content,
-            '',
-            'Decide (respond with exactly one action keyword followed by explanation/output):',
-            '- ACCEPT: incorporate the feedback and provide revised output',
-            '- REJECT: explain why the suggestion is not accepted',
-            '- PARTIAL: accept some suggestions, reject others, provide revised output',
-            '- FINALIZE: the work is done, deliver final output',
-            '',
-            'Format: ACTION_KEYWORD',
-            '<explanation or revised output>',
-        ].join('\n');
-        const decisionResult = await singleModelCall(executorApi, decisionPrompt, definition.executor?.systemPrompt, memberSignal(signal, definition.timeoutMs));
-        const dex = perModelTokens.get(definition.executor.model) ?? { input: 0, output: 0 };
-        dex.input += decisionResult.inputTokens;
-        dex.output += decisionResult.outputTokens;
-        perModelTokens.set(definition.executor.model, dex);
-        totalInput += decisionResult.inputTokens;
-        totalOutput += decisionResult.outputTokens;
-        // Parse decision
-        const lines = decisionResult.content.trim().split('\n');
-        const actionLine = lines[0]?.trim().toUpperCase() ?? '';
-        const explanation = lines.slice(1).join('\n').trim();
-        let action;
-        if (actionLine.startsWith('FINALIZE')) {
-            action = 'finalize';
-            finalAnswer = explanation || currentOutput;
-            converged = true;
-        }
-        else if (actionLine.startsWith('ACCEPT')) {
-            action = 'accept';
-            currentOutput = explanation || decisionResult.content;
-        }
-        else if (actionLine.startsWith('REJECT')) {
-            action = 'reject';
-            // Keep current output, note rejection
-        }
-        else if (actionLine.startsWith('PARTIAL')) {
-            action = 'partial';
-            currentOutput = explanation || decisionResult.content;
-        }
-        else {
-            // Default: treat as finalize
-            action = 'finalize';
-            finalAnswer = decisionResult.content;
-            converged = true;
-        }
-        decisions.push({
-            iteration: iterations,
-            action,
-            explanation: explanation || decisionResult.content,
-        });
-        transcript.push(`## Iteration ${iterations} — Executor decision (${action})\n${explanation || decisionResult.content}`);
-        iterations++;
-    }
-    if (!converged) {
-        finalAnswer = currentOutput;
+    finally {
+        if (sdk)
+            await sdk.close();
+        slot?.release();
     }
-    const cost = computeCost([...modelSet], totalInput, totalOutput, perModelTokens);
+    const cost = computeCost([...perModelTokens.keys()], totalInput, totalOutput, perModelTokens);
     return {
-        answer: finalAnswer,
-        mode: 'executor-reviewer',
-        iterations,
-        decisions,
-        reviews,
+        answer: report,
+        mode: 'reviewer',
+        report,
+        toolCalls,
         cost,
         durationMs: Date.now() - startedAt,
     };
 }
 // ═══════════════════════════════════════════════════════════════════
-//  Analysis Mode — read-only ReAct expert panel (advisory)
+//  Panel-Analysis Mode — read-only ReAct expert panel + optional convergence
 // ═══════════════════════════════════════════════════════════════════
 /**
- * Each member is an independent, read-only ReAct agent (Read/Glob/Grep +
- * TavilySearch/WebFetch — no write/edit/bash/delegation) that investigates the
- * task and the project in parallel and returns a findings report. No synthesis,
- * no convergence: the caller (the main agent) decides what to do with the
- * reports. This is the autonomous "expert panel" the main model invokes as a
- * tool to assist analysis on large/complex tasks; it only analyzes and reports.
+ * Unified expert panel. Each member is an independent, read-only ReAct agent
+ * (Read/Glob/Grep + TavilySearch/WebFetch — no write/edit/bash/delegation) that
+ * investigates the task in parallel and returns a findings report.
+ *
+ * - No `primary` → single-pass advisory: the caller (the main agent) decides
+ *   what to do with the concatenated reports (the original `analysis` behavior).
+ * - With a `primary` → multi-round convergence: after each round the primary
+ *   synthesizes the findings and decides FINALIZE or CONTINUE; on CONTINUE the
+ *   panel re-investigates a refined question with prior findings as context.
+ *   Harness principle preserved: the primary decides convergence; `maxRounds`
+ *   (default 100) is only a safety cap.
+ *
+ * `analysis` and `panel-analysis` both route here; the result `mode` echoes the
+ * requested alias.
  */
-async function runAnalysisMode(prompt, definition, signal) {
+async function runPanelAnalysisMode(prompt, definition, signal, workDir) {
     const startedAt = Date.now();
     // Lazy imports avoid a circular dependency (agentClient imports modelTeam).
     const { createAgentSdk } = await import('../runtime/agentClient.js');
-    const { createActoviqFileTools } = await import('../tools/actoviqFileTools.js');
-    const { createActoviqWebTools } = await import('../tools/actoviqWebTools.js');
-    const { createTavilySearchTool } = await import('../tools/tavilySearch.js');
-    const cwd = process.cwd();
-    const READ_ONLY_FILE_TOOLS = new Set(['Read', 'Glob', 'Grep']);
-    const buildReadOnlyTools = () => [
-        ...createActoviqFileTools({ cwd }).filter((t) => READ_ONLY_FILE_TOOLS.has(t.name)),
-        ...createActoviqWebTools().filter((t) => t.name === 'WebFetch'),
-        createTavilySearchTool(),
-    ];
+    const cwd = workDir ?? process.cwd();
+    const readOnlyTools = await buildReadOnlyExpertTools(cwd);
     // Bounded ReAct depth per member so a panel can't run away (configurable).
     const memberMaxIterations = definition.maxIterations ?? 16;
     const pool = getGlobalAgentPool();
@@ -676,69 +234,167 @@ async function runAnalysisMode(prompt, definition, signal) {
         'sources), risks, blind spots, concrete recommendations, and anything the main agent should',
         'verify. Be specific and decision-useful.',
     ].join(' ');
-    const reports = await mapWithConcurrency(definition.members, definition.maxParallel ?? definition.members.length, async (member) => {
-        const start = Date.now();
-        let slot;
-        let sdk;
-        try {
-            slot = await pool.acquire();
-            sdk = await createAgentSdk({
-                model: member.model,
-                provider: member.provider,
-                baseURL: member.baseURL,
-                authToken: resolveApiKey(member.apiKey),
-                maxTokens: member.maxTokens ?? 32000,
-                workDir: cwd,
-                tools: buildReadOnlyTools(),
-                permissionMode: 'bypassPermissions',
-                maxToolIterations: memberMaxIterations,
-                systemPrompt: member.systemPrompt
-                    ? `${analysisFraming}\n\n${member.systemPrompt}`
-                    : analysisFraming,
-            });
-            const result = await sdk.run(prompt, {
-                signal: memberSignal(signal, definition.timeoutMs),
-            });
-            const input = result.requests.reduce((s, r) => s + (r.usage?.input_tokens ?? 0), 0);
-            const output = result.requests.reduce((s, r) => s + (r.usage?.output_tokens ?? 0), 0);
-            const ex = perModelTokens.get(member.model) ?? { input: 0, output: 0 };
-            ex.input += input;
-            ex.output += output;
-            perModelTokens.set(member.model, ex);
-            totalInput += input;
-            totalOutput += output;
-            return {
-                model: member.model,
-                report: result.text,
-                toolCalls: result.toolCalls.length,
-                durationMs: Date.now() - start,
-            };
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return {
-                model: member.model,
-                report: `[ERROR: ${member.model} analysis failed — ${message}]`,
-                toolCalls: 0,
-                durationMs: Date.now() - start,
-            };
-        }
-        finally {
-            if (sdk)
-                await sdk.close();
-            slot?.release();
-        }
+    // One investigation round: every member investigates `question` in parallel as
+    // a read-only ReAct agent. `priorContext` (earlier rounds' findings) lets
+    // members build on the deliberation instead of starting cold.
+    const investigate = async (round, question, priorContext) => {
+        const memberPrompt = priorContext
+            ? `${question}\n\n## Prior panel findings (build on these; don't repeat established points)\n${priorContext}`
+            : question;
+        return mapWithConcurrency(definition.members, definition.maxParallel ?? definition.members.length, async (member) => {
+            const start = Date.now();
+            let slot;
+            let sdk;
+            try {
+                slot = await pool.acquire();
+                sdk = await createAgentSdk({
+                    model: member.model,
+                    provider: member.provider,
+                    baseURL: member.baseURL,
+                    authToken: resolveApiKey(member.apiKey),
+                    maxTokens: member.maxTokens ?? 32000,
+                    workDir: cwd,
+                    tools: readOnlyTools,
+                    permissionMode: 'bypassPermissions',
+                    maxToolIterations: memberMaxIterations,
+                    systemPrompt: member.systemPrompt
+                        ? `${analysisFraming}\n\n${member.systemPrompt}`
+                        : analysisFraming,
+                });
+                const result = await sdk.run(memberPrompt, {
+                    signal: memberSignal(signal, definition.timeoutMs),
+                });
+                const input = result.requests.reduce((s, r) => s + (r.usage?.input_tokens ?? 0), 0);
+                const output = result.requests.reduce((s, r) => s + (r.usage?.output_tokens ?? 0), 0);
+                const ex = perModelTokens.get(member.model) ?? { input: 0, output: 0 };
+                ex.input += input;
+                ex.output += output;
+                perModelTokens.set(member.model, ex);
+                totalInput += input;
+                totalOutput += output;
+                return {
+                    model: member.model,
+                    report: result.text,
+                    toolCalls: result.toolCalls.length,
+                    durationMs: Date.now() - start,
+                    round,
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    model: member.model,
+                    report: `[ERROR: ${member.model} analysis failed — ${message}]`,
+                    toolCalls: 0,
+                    durationMs: Date.now() - start,
+                    round,
+                };
+            }
+            finally {
+                if (sdk)
+                    await sdk.close();
+                slot?.release();
+            }
+        });
+    };
+    const resultMode = definition.mode === 'analysis' ? 'analysis' : 'panel-analysis';
+    // With a primary, build the decision callback that synthesizes findings and
+    // votes FINALIZE/CONTINUE each round; without one, the panel is single-pass.
+    let decide;
+    if (definition.primary) {
+        const primaryApi = await createMemberApi(definition.primary);
+        const primaryModel = definition.primary.model;
+        const primarySystem = definition.primary.systemPrompt;
+        decide = async (deliberationLog) => {
+            const decisionPrompt = [
+                'You are the primary synthesizer over a panel of expert analysts; each investigated the task with read-only tools and reported findings.',
+                'Review the full panel findings, then decide whether they are sufficient to answer the task.',
+                '',
+                'Original task:',
+                prompt,
+                '',
+                'Full panel findings so far:',
+                deliberationLog,
+                '',
+                'Respond in one of these formats:',
+                '',
+                'To FINALIZE (findings are sufficient):',
+                'FINALIZE',
+                '<your comprehensive synthesized answer, grounded in the findings>',
+                '',
+                'To CONTINUE (deeper investigation needed):',
+                'CONTINUE',
+                '<a refined question and the specific aspects the panel should investigate next>',
+            ].join('\n');
+            const decision = await singleModelCall(primaryApi, decisionPrompt, primarySystem, memberSignal(signal, definition.timeoutMs));
+            totalInput += decision.inputTokens;
+            totalOutput += decision.outputTokens;
+            const pex = perModelTokens.get(primaryModel) ?? { input: 0, output: 0 };
+            pex.input += decision.inputTokens;
+            pex.output += decision.outputTokens;
+            perModelTokens.set(primaryModel, pex);
+            return decision.content;
+        };
+    }
+    const { answer, rounds, reports } = await orchestratePanel({
+        prompt,
+        maxRounds: definition.maxRounds ?? 100,
+        investigate,
+        decide,
     });
-    const answer = reports.map((r) => `### ${r.model}\n${r.report}`).join('\n\n---\n\n');
     const cost = computeCost([...perModelTokens.keys()], totalInput, totalOutput, perModelTokens);
     return {
         answer,
-        mode: 'analysis',
+        mode: resultMode,
         reports,
+        rounds,
         cost,
         durationMs: Date.now() - startedAt,
     };
 }
+/**
+ * Orchestrate the panel over an injectable `investigate` (one round of member
+ * reports) and optional `decide` (the primary's synthesize-or-continue call).
+ *
+ * - No `decide` → single-pass advisory: round 1 only; answer = labeled reports.
+ * - With `decide` → multi-round convergence: after each round the primary votes
+ *   FINALIZE (synthesize) or CONTINUE (refined question); loops until FINALIZE
+ *   or `maxRounds` (safety cap). The keyword match is case-insensitive, and any
+ *   decision that is not a leading CONTINUE finalizes (graceful default).
+ *
+ * Exported so the convergence logic is unit-testable without real model calls.
+ */
+export async function orchestratePanel(opts) {
+    const label = (rs) => rs.map((r) => `### ${r.model}\n${r.report}`).join('\n\n---\n\n');
+    const allReports = [];
+    let rounds = 1;
+    let currentReports = await opts.investigate(1, opts.prompt);
+    allReports.push(...currentReports);
+    // No primary → single-pass advisory (original `analysis` behavior).
+    if (!opts.decide) {
+        return { answer: label(currentReports), rounds, reports: allReports };
+    }
+    const deliberationLog = [`## Round 1 — Panel findings\n${label(currentReports)}`];
+    while (true) {
+        const content = await opts.decide(deliberationLog.join('\n\n---\n\n'), rounds);
+        const wantsContinue = content.trim().toUpperCase().startsWith('CONTINUE');
+        if (wantsContinue && rounds < opts.maxRounds) {
+            const refined = content.replace(/^CONTINUE\s*/i, '').trim() || opts.prompt;
+            deliberationLog.push(`## Round ${rounds} — Primary decision\nCONTINUE: ${refined}`);
+            rounds++;
+            currentReports = await opts.investigate(rounds, refined, label(currentReports));
+            allReports.push(...currentReports);
+            deliberationLog.push(`## Round ${rounds} — Panel findings\n${label(currentReports)}`);
+        }
+        else {
+            // FINALIZE, or the safety cap was reached mid-deliberation.
+            const answer = wantsContinue
+                ? label(currentReports) // cap hit: hand back the findings unsynthesized
+                : content.replace(/^FINALIZE\s*/i, '').trim() || label(currentReports);
+            return { answer, rounds, reports: allReports };
+        }
+    }
+}
 // ═══════════════════════════════════════════════════════════════════
 //  ModelTeam class
 // ═══════════════════════════════════════════════════════════════════
@@ -750,23 +406,19 @@ export class ModelTeam {
         this.definition = definition;
     }
     /**
-     * Ask the team a question. Returns the synthesized answer.
-     * Panel/Discussion: primary model decides when to converge.
-     * Router: classifies and dispatches.
-     * Executor-Reviewer: executor decides when done.
+     * Ask the team. `opts.context` is injected into the reviewer's system prompt
+     * (reviewer mode only — what the main agent did and obtained). Returns the
+     * mode-specific result.
      */
-    async ask(prompt, signal) {
+    async ask(prompt, signal, opts) {
         switch (this.definition.mode) {
-            case 'panel':
-                return runPanelMode(prompt, this.definition, signal);
-            case 'router':
-                return runRouterMode(prompt, this.definition, signal);
-            case 'discussion':
-                return runDiscussionMode(prompt, this.definition, signal);
-            case 'executor-reviewer':
-                return runExecutorReviewerMode(prompt, this.definition, signal);
+            case 'reviewer':
+            case 'executor-reviewer': // alias: the retired executor loop now runs the single reviewer
+                return runReviewerMode(prompt, this.definition, signal, opts?.context, opts?.workDir);
+            case 'panel': // alias: retired pure-text panel now runs the unified engine
             case 'analysis':
-                return runAnalysisMode(prompt, this.definition, signal);
+            case 'panel-analysis':
+                return runPanelAnalysisMode(prompt, this.definition, signal, opts?.workDir);
             default:
                 throw new Error(`Unknown team mode: ${this.definition.mode}`);
         }
@@ -786,35 +438,18 @@ function validateTeamDefinition(def) {
     if (!def.mode)
         throw new Error('Team definition must specify a mode.');
     switch (def.mode) {
-        case 'panel':
-            if (!def.primary)
-                throw new Error('Panel mode requires a primary member.');
-            if (!def.members || def.members.length === 0)
-                throw new Error('Panel mode requires at least one panel member.');
-            if (def.members.length > 8)
-                throw new Error('Panel mode supports at most 8 members.');
-            break;
-        case 'router':
-            if (!def.router)
-                throw new Error('Router mode requires a router member.');
-            if (!def.specialists || Object.keys(def.specialists).length === 0)
-                throw new Error('Router mode requires at least one specialist.');
-            break;
-        case 'discussion':
-            if (!def.primary)
-                throw new Error('Discussion mode requires a primary member.');
-            if (!def.members || def.members.length < 2)
-                throw new Error('Discussion mode requires at least 2 members.');
-            break;
-        case 'executor-reviewer':
-            if (!def.executor)
-                throw new Error('Executor-Reviewer mode requires an executor.');
+        case 'reviewer':
+        case 'executor-reviewer': // retired alias: needs only a reviewer now
             if (!def.reviewer)
-                throw new Error('Executor-Reviewer mode requires a reviewer.');
+                throw new Error('Reviewer mode requires a reviewer member.');
             break;
+        case 'panel': // retired alias of panel-analysis (primary now optional)
         case 'analysis':
+        case 'panel-analysis':
             if (!def.members || def.members.length === 0)
-                throw new Error('Analysis mode requires at least one panel member.');
+                throw new Error('Panel-analysis mode requires at least one panel member.');
+            if (def.members.length > 8)
+                throw new Error('Panel-analysis mode supports at most 8 members.');
             break;
     }
 }
@@ -824,31 +459,55 @@ function validateTeamDefinition(def) {
  */
 export function createTeamTool(definition) {
     const team = createModelTeam(definition);
+    const isReviewer = definition.mode === 'reviewer' || definition.mode === 'executor-reviewer';
+    const isPanel = definition.mode === 'analysis' || definition.mode === 'panel-analysis';
     return {
         kind: 'local',
         name: definition.name,
         description: definition.description ??
-            (definition.mode === 'analysis'
-                ? 'Expert panel: independent read-only multi-model analysis (advisory). You decide what to do with the findings.'
-                : `Multi-model team (${definition.mode} mode)`),
+            (isReviewer
+                ? 'Reviewer: a single read-only agent inspects the project and reports only genuine, verifiable issues. Pass { task } (what to check) and optional { context } (what you did + the results). It advises; you decide.'
+                : isPanel
+                    ? 'Expert panel: independent read-only multi-model analysis (advisory; optional primary-driven convergence). You decide what to do with the findings.'
+                    : `Multi-model team (${definition.mode} mode)`),
         inputSchema: {
             parse: (input) => input,
             _type: undefined,
         },
-        inputJsonSchema: {
-            type: 'object',
-            properties: {
-                prompt: { type: 'string', description: 'The question or task for the team' },
+        inputJsonSchema: isReviewer
+            ? {
+                type: 'object',
+                properties: {
+                    task: { type: 'string', description: 'What the reviewer should scrutinize' },
+                    context: { type: 'string', description: 'What you did and the results you obtained (injected into the reviewer system prompt)' },
+                },
+                required: ['task'],
+                additionalProperties: true,
+            }
+            : {
+                type: 'object',
+                properties: {
+                    prompt: { type: 'string', description: 'The question or task for the team' },
+                },
+                required: ['prompt'],
+                // Tolerate extra fields the model may add — a strict schema here caused
+                // intermittent "schema error" rejections that silently skipped the panel.
+                additionalProperties: true,
             },
-            required: ['prompt'],
-            // Tolerate extra fields the model may add — a strict schema here caused
-            // intermittent "schema error" rejections that silently skipped the panel.
-            additionalProperties: true,
-        },
         async execute(input) {
-            // Accept the prompt however the model phrases the call (bare string or any
-            // of a few common keys) so a formatting quirk never drops the panel.
+            // Accept the call however the model phrases it (bare string or any of a few
+            // common keys) so a formatting quirk never drops the invocation.
             const obj = (input ?? {});
+            if (isReviewer) {
+                const taskCandidate = typeof input === 'string' ? input : obj.task ?? obj.prompt ?? obj.question ?? obj.input;
+                const task = typeof taskCandidate === 'string' ? taskCandidate.trim() : '';
+                if (!task) {
+                    throw new Error(`Reviewer "${definition.name}" requires a non-empty "task" string.`);
+                }
+                const context = typeof obj.context === 'string' ? obj.context : undefined;
+                const result = await team.ask(task, undefined, { context });
+                return JSON.stringify({ answer: result.answer, mode: result.mode, cost: result.cost });
+            }
             const candidate = typeof input === 'string'
                 ? input
                 : obj.prompt ?? obj.query ?? obj.question ?? obj.task ?? obj.input;
@@ -869,10 +528,14 @@ export function createTeamTool(definition) {
             `## ${definition.name} (Model Team: ${definition.mode})`,
             definition.description ?? '',
             '',
-            definition.mode === 'analysis'
-                ? 'Call this tool with a { prompt } to have an expert panel of independent read-only agents investigate (read local code + search the web) and each return a findings report. They only analyze and advise — you keep full control and decide what to do with their input. Use it to assist analysis on large or complex tasks.'
-                : 'Call this tool with a { prompt } to get a multi-model synthesized answer.',
-            `Members: ${definition.members?.map((m) => m.model).join(', ') ?? 'configured via definition'}`,
+            isReviewer
+                ? 'Call this tool with { task } (what to scrutinize) and optional { context } (what you did and the results you got). A single read-only agent inspects the code/web and reports only issues it can verify — no speculation. You keep final authority; re-invoke after changes to re-check.'
+                : isPanel
+                    ? 'Call this tool with a { prompt } to have an expert panel of independent read-only agents investigate (read local code + search the web) and each return a findings report. They only analyze and advise — you keep full control and decide what to do with their input. With a configured primary the panel also converges over multiple rounds into a synthesized answer. Use it to assist analysis on large or complex tasks.'
+                    : 'Call this tool with a { prompt } to get a multi-model synthesized answer.',
+            isReviewer
+                ? `Reviewer: ${definition.reviewer?.model ?? 'configured via definition'}`
+                : `Members: ${definition.members?.map((m) => m.model).join(', ') ?? 'configured via definition'}`,
         ].join('\n'),
     };
 }