claude-flow 3.10.3 → 3.10.5

package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-convergence.js

@@ -0,0 +1,260 @@
+/**
+ * GAIA Convergence Layer — deterministic finalization for saturated agent loops.
+ *
+ * Detects three failure modes that cause empty FINAL_ANSWER extraction:
+ *   1. max_turns hit without a final_answer call
+ *   2. Loop detected (same tool + same args called 3× in a 5-turn window)
+ *   3. Token budget exceeded (>120k tokens of conversation context)
+ *
+ * On detection, runs a FORCED COMMIT phase:
+ *   - Injects a stripped-down summary prompt: "Based on all observations, answer with
+ *     FINAL_ANSWER: X. Do NOT explore further."
+ *   - Makes 1 final API call with strict instruction and no tools.
+ *   - If still no FINAL_ANSWER in the response, runs the Stage 1 extraction cascade
+ *     against ALL prior assistant messages (last to first), returns first non-empty hit.
+ *   - If still empty: returns null but logs the failure mode.
+ *
+ * This is NOT a new cognition layer — it is a convergence controller.
+ * It STRIPS information rather than adding it: one final chance to commit,
+ * no tools available, prior context summarized rather than appended.
+ *
+ * Architecture principle (iter 60 post-mortem):
+ *   "More information can reduce agent reliability. Past a certain point —
+ *    retrieval depth, context size, browsing breadth, tool diversity — information
+ *    increases trajectory entropy. The system becomes less likely to finalize coherently."
+ *   This layer is the entropy-reducer.
+ *
+ * Refs: #2156, iter 60 (19/25 empty FINAL_ANSWER failures), iter 62
+ */
+import * as crypto from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Token threshold (sum of input tokens across all turns) that triggers overflow detection. */
+export const TOKEN_OVERFLOW_THRESHOLD = 120_000;
+/** Number of repeated identical tool+args calls in a window that signals a loop. */
+export const LOOP_REPEAT_THRESHOLD = 3;
+/** Sliding window size (turns) for loop detection. */
+export const LOOP_WINDOW_SIZE = 5;
+/** Pattern Claude must output to signal it has a final answer. */
+const FINAL_ANSWER_RE = /FINAL_ANSWER:\s*(.+)/i;
+// ---------------------------------------------------------------------------
+// argsHash — deterministic fingerprint of a tool call
+// ---------------------------------------------------------------------------
+/**
+ * Produce a stable hash of a tool call's name + args for loop detection.
+ *
+ * Uses SHA-256 truncated to 16 hex chars — collision probability is
+ * negligible for the small call volumes in a single agent run.
+ *
+ * The hash is deterministic: same toolName + same args always → same hash.
+ * Different args always → different hash (within SHA-256 collision bounds).
+ */
+export function argsHash(toolName, args) {
+    const payload = toolName + '::' + JSON.stringify(args);
+    return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+// ---------------------------------------------------------------------------
+// checkConvergenceTriggers
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate the current ConvergenceState and return the first failure mode
+ * detected, or null if no trigger has fired.
+ *
+ * Evaluation order:
+ *   1. max_turns — turnCount >= maxTurns
+ *   2. token_overflow — totalTokens >= TOKEN_OVERFLOW_THRESHOLD
+ *   3. loop — same tool+argsHash appears >= LOOP_REPEAT_THRESHOLD times
+ *              in the last LOOP_WINDOW_SIZE entries of toolCalls
+ *
+ * Only the FIRST matching trigger is returned (stops at first detection).
+ * The caller is responsible for setting state.detectedFailureMode.
+ */
+export function checkConvergenceTriggers(state, maxTurns) {
+    // 1. max_turns
+    if (state.turnCount >= maxTurns) {
+        return 'max_turns';
+    }
+    // 2. token_overflow
+    if (state.totalTokens >= TOKEN_OVERFLOW_THRESHOLD) {
+        return 'token_overflow';
+    }
+    // 3. loop — check the sliding window
+    const window = state.toolCalls.slice(-LOOP_WINDOW_SIZE);
+    if (window.length >= LOOP_REPEAT_THRESHOLD) {
+        const callKey = (c) => c.name + '::' + c.argsHash;
+        const counts = new Map();
+        for (const call of window) {
+            const key = callKey(call);
+            const count = (counts.get(key) ?? 0) + 1;
+            counts.set(key, count);
+            if (count >= LOOP_REPEAT_THRESHOLD) {
+                return 'loop';
+            }
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// buildForcedCommitPrompt
+// ---------------------------------------------------------------------------
+/**
+ * Build the stripped-down "commit now" prompt injected as a final user turn.
+ *
+ * Deliberately short and directive — this is an entropy-reducer, not a
+ * context-enricher. Adding more information at this point would worsen the
+ * problem we are solving.
+ */
+function buildForcedCommitPrompt(triggerMode) {
+    return (`[CONVERGENCE: ${triggerMode.toUpperCase()}]\n` +
+        `You must commit to a final answer NOW. Do NOT call any more tools.\n` +
+        `Based only on the information you have already gathered:\n` +
+        `- Summarize your best answer in one line.\n` +
+        `- Output it in EXACTLY this format: FINAL_ANSWER: <your answer>\n` +
+        `- If you are uncertain, give your best estimate — do not say "I don't know".\n` +
+        `You have ONE response. No further tool calls are permitted.`);
+}
+// ---------------------------------------------------------------------------
+// extractFinalAnswerFromText — Stage 1 extraction against raw text
+// ---------------------------------------------------------------------------
+/**
+ * Run Stage 1 extraction (FINAL_ANSWER: pattern) against a raw text string.
+ * Returns the matched answer or null.
+ */
+export function extractFinalAnswerFromText(text) {
+    const match = FINAL_ANSWER_RE.exec(text);
+    if (match && match[1] && match[1].trim()) {
+        return match[1].trim();
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// extractFromPriorMessages — fallback scan of message history
+// ---------------------------------------------------------------------------
+/**
+ * Scan prior assistant messages from last to first, looking for FINAL_ANSWER.
+ *
+ * This is the fallback path when the forced-commit API call still does not
+ * produce a FINAL_ANSWER. We search backwards because the most recent
+ * assistant message is most likely to contain the best answer.
+ */
+export function extractFromPriorMessages(messages) {
+    // Iterate in reverse, assistant messages only
+    const assistantMessages = messages
+        .filter((m) => m.role === 'assistant')
+        .reverse();
+    for (const msg of assistantMessages) {
+        const text = typeof msg.content === 'string'
+            ? msg.content
+            : extractTextFromContent(msg.content);
+        if (!text)
+            continue;
+        const answer = extractFinalAnswerFromText(text);
+        if (answer)
+            return answer;
+    }
+    return null;
+}
+/**
+ * Extract plain text from a content block array (Anthropic API format).
+ * Returns concatenated text from all text-type blocks, or empty string.
+ */
+function extractTextFromContent(content) {
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const block of content) {
+        if (block && typeof block === 'object' && block.type === 'text') {
+            const text = block.text;
+            if (text)
+                parts.push(text);
+        }
+    }
+    return parts.join('\n');
+}
+// ---------------------------------------------------------------------------
+// forceCommit
+// ---------------------------------------------------------------------------
+/**
+ * Run the forced-commit phase for a saturated agent loop.
+ *
+ * Steps:
+ *   1. Append a stripped directive prompt to the message history.
+ *   2. Call the model once with NO tools — forces text-only response.
+ *   3. If FINAL_ANSWER found in the response → return it.
+ *   4. If not → scan prior assistant messages last-to-first for FINAL_ANSWER.
+ *   5. If still empty → return { answer: null, usedFallback: false }.
+ *
+ * The callModel callback must return the raw text response (assistant turn
+ * text blocks concatenated). It should be called WITHOUT tool definitions
+ * so the model cannot call tools in this turn.
+ *
+ * @param messages  Current conversation history (mutated: 1 user turn appended)
+ * @param callModel Callback that makes a single API call and returns the response text
+ * @param triggerMode  The failure mode that triggered this forced commit
+ */
+export async function forceCommit(messages, callModel, triggerMode = 'max_turns') {
+    const trigger = triggerMode ?? 'max_turns';
+    // Step 1: append the forced-commit directive
+    const commitMessages = [
+        ...messages,
+        { role: 'user', content: buildForcedCommitPrompt(trigger) },
+    ];
+    // Step 2: call the model once, no tools
+    let responseText = '';
+    try {
+        responseText = await callModel(commitMessages);
+    }
+    catch {
+        // If the API call itself fails, fall through to fallback scan
+        responseText = '';
+    }
+    // Step 3: try to extract from the forced-commit response
+    if (responseText) {
+        const answer = extractFinalAnswerFromText(responseText);
+        if (answer) {
+            return { answer, usedFallback: false, triggerMode: triggerMode };
+        }
+    }
+    // Step 4: scan prior messages last-to-first
+    const fallbackAnswer = extractFromPriorMessages(messages);
+    if (fallbackAnswer) {
+        return { answer: fallbackAnswer, usedFallback: true, triggerMode: triggerMode };
+    }
+    // Step 5: graceful failure
+    return { answer: null, usedFallback: false, triggerMode: triggerMode };
+}
+// ---------------------------------------------------------------------------
+// createConvergenceState — factory for a fresh state object
+// ---------------------------------------------------------------------------
+/** Create a new ConvergenceState with zero counters. */
+export function createConvergenceState() {
+    return {
+        turnCount: 0,
+        totalTokens: 0,
+        toolCalls: [],
+        detectedFailureMode: null,
+    };
+}
+// ---------------------------------------------------------------------------
+// recordTurn — update state after a completed turn
+// ---------------------------------------------------------------------------
+/**
+ * Update ConvergenceState after each agent turn completes.
+ *
+ * @param state       Mutable state object (modified in place)
+ * @param inputTokens Tokens consumed in this turn
+ * @param toolCallsThisTurn  Tool calls made in this turn (name + args)
+ */
+export function recordTurn(state, inputTokens, toolCallsThisTurn) {
+    state.turnCount += 1;
+    state.totalTokens += inputTokens;
+    for (const tc of toolCallsThisTurn) {
+        state.toolCalls.push({
+            name: tc.name,
+            argsHash: argsHash(tc.name, tc.args),
+            turn: state.turnCount,
+        });
+    }
+}
+//# sourceMappingURL=gaia-convergence.js.map

package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-convergence.smoke.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Smoke tests for the GAIA convergence layer (gaia-convergence.ts).
+ *
+ * 10 assertions covering:
+ *   T1:  max_turns hit → checkConvergenceTriggers returns 'max_turns'
+ *   T2:  same tool+args 3× in window → returns 'loop'
+ *   T3:  120k tokens → returns 'token_overflow'
+ *   T4:  forceCommit with prose-embedded answer in history → extraction succeeds
+ *   T5:  forceCommit with explicit FINAL_ANSWER: X in response → returns X
+ *   T6:  forceCommit on truly empty/looping conversation → returns null (graceful)
+ *   T7:  argsHash deterministic — same args → same hash
+ *   T8:  argsHash distinguishes — different args → different hash
+ *   T9:  ConvergenceState records turn counts correctly via recordTurn
+ *   T10: Anti-loop window correctly slides — only last 5 turns matter
+ *
+ * Refs: #2156, iter 62
+ */
+export {};
+//# sourceMappingURL=gaia-convergence.smoke.d.ts.map

package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-convergence.smoke.js

@@ -0,0 +1,246 @@
+/**
+ * Smoke tests for the GAIA convergence layer (gaia-convergence.ts).
+ *
+ * 10 assertions covering:
+ *   T1:  max_turns hit → checkConvergenceTriggers returns 'max_turns'
+ *   T2:  same tool+args 3× in window → returns 'loop'
+ *   T3:  120k tokens → returns 'token_overflow'
+ *   T4:  forceCommit with prose-embedded answer in history → extraction succeeds
+ *   T5:  forceCommit with explicit FINAL_ANSWER: X in response → returns X
+ *   T6:  forceCommit on truly empty/looping conversation → returns null (graceful)
+ *   T7:  argsHash deterministic — same args → same hash
+ *   T8:  argsHash distinguishes — different args → different hash
+ *   T9:  ConvergenceState records turn counts correctly via recordTurn
+ *   T10: Anti-loop window correctly slides — only last 5 turns matter
+ *
+ * Refs: #2156, iter 62
+ */
+import assert from 'node:assert';
+import { checkConvergenceTriggers, forceCommit, argsHash, createConvergenceState, recordTurn, extractFinalAnswerFromText, extractFromPriorMessages, TOKEN_OVERFLOW_THRESHOLD, LOOP_WINDOW_SIZE, } from './gaia-convergence.js';
+// ---------------------------------------------------------------------------
+// Test harness
+// ---------------------------------------------------------------------------
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+    const result = fn();
+    if (result && typeof result.then === 'function') {
+        result
+            .then(() => {
+            console.log(`  PASS  ${name}`);
+            passed++;
+        })
+            .catch((err) => {
+            console.error(`  FAIL  ${name}: ${err.message ?? err}`);
+            failed++;
+        });
+    }
+    else {
+        try {
+            console.log(`  PASS  ${name}`);
+            passed++;
+        }
+        catch (err) {
+            console.error(`  FAIL  ${name}: ${err.message ?? err}`);
+            failed++;
+        }
+    }
+}
+async function testAsync(name, fn) {
+    try {
+        await fn();
+        console.log(`  PASS  ${name}`);
+        passed++;
+    }
+    catch (err) {
+        console.error(`  FAIL  ${name}: ${err.message ?? err}`);
+        failed++;
+    }
+}
+// ---------------------------------------------------------------------------
+// T1: max_turns hit → returns 'max_turns'
+// ---------------------------------------------------------------------------
+test('T1: max_turns hit returns max_turns', () => {
+    const state = {
+        turnCount: 12,
+        totalTokens: 1000,
+        toolCalls: [],
+        detectedFailureMode: null,
+    };
+    const result = checkConvergenceTriggers(state, 12);
+    assert.strictEqual(result, 'max_turns', `Expected 'max_turns', got ${result}`);
+});
+// ---------------------------------------------------------------------------
+// T2: same tool+args 3× in last 5 turns → returns 'loop'
+// ---------------------------------------------------------------------------
+test('T2: loop detection — same tool+args 3x in window', () => {
+    const hash = argsHash('web_search', { query: 'test' });
+    const state = {
+        turnCount: 5,
+        totalTokens: 5000,
+        toolCalls: [
+            { name: 'web_search', argsHash: hash, turn: 1 },
+            { name: 'web_search', argsHash: hash, turn: 2 },
+            { name: 'web_search', argsHash: hash, turn: 3 },
+        ],
+        detectedFailureMode: null,
+    };
+    const result = checkConvergenceTriggers(state, 15);
+    assert.strictEqual(result, 'loop', `Expected 'loop', got ${result}`);
+});
+// ---------------------------------------------------------------------------
+// T3: 120k tokens → returns 'token_overflow'
+// ---------------------------------------------------------------------------
+test('T3: token_overflow at threshold', () => {
+    const state = {
+        turnCount: 5,
+        totalTokens: TOKEN_OVERFLOW_THRESHOLD,
+        toolCalls: [],
+        detectedFailureMode: null,
+    };
+    const result = checkConvergenceTriggers(state, 20);
+    assert.strictEqual(result, 'token_overflow', `Expected 'token_overflow', got ${result}`);
+});
+// ---------------------------------------------------------------------------
+// T4: forceCommit with prose-embedded answer in prior history → extraction succeeds
+// ---------------------------------------------------------------------------
+await testAsync('T4: forceCommit — prose-embedded FINAL_ANSWER in prior history', async () => {
+    const messages = [
+        { role: 'user', content: 'What is 2+2?' },
+        {
+            role: 'assistant',
+            content: 'Let me think about this. The answer is definitely 4. FINAL_ANSWER: 4',
+        },
+        { role: 'user', content: 'tool results...' },
+        { role: 'assistant', content: 'I got confused. Let me recalculate.' },
+    ];
+    // callModel returns an empty response (simulating no new FINAL_ANSWER)
+    const callModel = async () => 'I need to think more about this.';
+    const result = await forceCommit(messages, callModel, 'max_turns');
+    assert.strictEqual(result.answer, '4', `Expected '4', got ${result.answer}`);
+    assert.strictEqual(result.usedFallback, true, 'Expected usedFallback=true for history scan');
+});
+// ---------------------------------------------------------------------------
+// T5: forceCommit with explicit FINAL_ANSWER: X in forced response → returns X
+// ---------------------------------------------------------------------------
+await testAsync('T5: forceCommit — explicit FINAL_ANSWER in forced-commit response', async () => {
+    const messages = [
+        { role: 'user', content: 'What is the capital of France?' },
+        { role: 'assistant', content: 'I need to search for this.' },
+    ];
+    // callModel returns a response WITH FINAL_ANSWER
+    const callModel = async () => 'Based on my knowledge, the capital is Paris. FINAL_ANSWER: Paris';
+    const result = await forceCommit(messages, callModel, 'max_turns');
+    assert.strictEqual(result.answer, 'Paris', `Expected 'Paris', got ${result.answer}`);
+    assert.strictEqual(result.usedFallback, false, 'Expected usedFallback=false when direct extraction');
+    assert.strictEqual(result.triggerMode, 'max_turns');
+});
+// ---------------------------------------------------------------------------
+// T6: forceCommit on truly empty conversation → returns null (graceful)
+// ---------------------------------------------------------------------------
+await testAsync('T6: forceCommit — graceful null on empty conversation', async () => {
+    const messages = [
+        { role: 'user', content: 'What is something unknowable?' },
+        { role: 'assistant', content: 'I have been calling tools repeatedly with no progress.' },
+    ];
+    // callModel returns nothing useful
+    const callModel = async () => 'I cannot determine the answer to this question.';
+    const result = await forceCommit(messages, callModel, 'loop');
+    assert.strictEqual(result.answer, null, `Expected null, got ${result.answer}`);
+    assert.strictEqual(result.triggerMode, 'loop');
+});
+// ---------------------------------------------------------------------------
+// T7: argsHash deterministic — same args → same hash
+// ---------------------------------------------------------------------------
+test('T7: argsHash is deterministic', () => {
+    const h1 = argsHash('web_search', { query: 'hello world', limit: 5 });
+    const h2 = argsHash('web_search', { query: 'hello world', limit: 5 });
+    assert.strictEqual(h1, h2, 'Same inputs must produce identical hash');
+    assert.ok(h1.length === 16, `Hash should be 16 hex chars, got ${h1.length}`);
+});
+// ---------------------------------------------------------------------------
+// T8: argsHash distinguishes — different args → different hash
+// ---------------------------------------------------------------------------
+test('T8: argsHash distinguishes different args', () => {
+    const h1 = argsHash('web_search', { query: 'hello' });
+    const h2 = argsHash('web_search', { query: 'world' });
+    assert.notStrictEqual(h1, h2, 'Different args must produce different hash');
+    const h3 = argsHash('calculator', { query: 'hello' });
+    assert.notStrictEqual(h1, h3, 'Different tool names must produce different hash');
+});
+// ---------------------------------------------------------------------------
+// T9: ConvergenceState records turn counts correctly via recordTurn
+// ---------------------------------------------------------------------------
+test('T9: recordTurn increments turnCount and totalTokens', () => {
+    const state = createConvergenceState();
+    assert.strictEqual(state.turnCount, 0);
+    assert.strictEqual(state.totalTokens, 0);
+    assert.strictEqual(state.toolCalls.length, 0);
+    recordTurn(state, 1500, [
+        { name: 'web_search', args: { query: 'test' } },
+        { name: 'calculator', args: { expr: '2+2' } },
+    ]);
+    assert.strictEqual(state.turnCount, 1, `Expected turnCount=1, got ${state.turnCount}`);
+    assert.strictEqual(state.totalTokens, 1500, `Expected totalTokens=1500, got ${state.totalTokens}`);
+    assert.strictEqual(state.toolCalls.length, 2, `Expected 2 tool calls recorded, got ${state.toolCalls.length}`);
+    assert.strictEqual(state.toolCalls[0].name, 'web_search');
+    assert.strictEqual(state.toolCalls[0].turn, 1);
+    recordTurn(state, 2000, []);
+    assert.strictEqual(state.turnCount, 2);
+    assert.strictEqual(state.totalTokens, 3500);
+});
+// ---------------------------------------------------------------------------
+// T10: Anti-loop window correctly slides — only last LOOP_WINDOW_SIZE turns matter
+// ---------------------------------------------------------------------------
+test('T10: loop window slides — old calls outside window do not trigger', () => {
+    const hash = argsHash('web_search', { query: 'test' });
+    // 4 repeated calls followed by 5 different calls — window is last 5 only
+    const oldCalls = Array.from({ length: 4 }, (_, i) => ({
+        name: 'web_search', argsHash: hash, turn: i + 1,
+    }));
+    const recentCalls = Array.from({ length: LOOP_WINDOW_SIZE }, (_, i) => ({
+        name: `tool_${i}`, argsHash: argsHash(`tool_${i}`, {}), turn: i + 5,
+    }));
+    const state = {
+        turnCount: 9,
+        totalTokens: 9000,
+        toolCalls: [...oldCalls, ...recentCalls],
+        detectedFailureMode: null,
+    };
+    const result = checkConvergenceTriggers(state, 20);
+    assert.strictEqual(result, null, `Expected null (old calls outside window), got ${result}`);
+});
+// ---------------------------------------------------------------------------
+// Bonus: extractFinalAnswerFromText edge cases
+// ---------------------------------------------------------------------------
+test('T11 (bonus): extractFinalAnswerFromText handles multiline and trailing content', () => {
+    const text = 'After much deliberation:\nFINAL_ANSWER: 42\nSome extra text';
+    const result = extractFinalAnswerFromText(text);
+    assert.strictEqual(result, '42', `Expected '42', got ${result}`);
+});
+test('T12 (bonus): extractFromPriorMessages scans in reverse order', () => {
+    const messages = [
+        { role: 'user', content: 'Question' },
+        { role: 'assistant', content: 'First answer FINAL_ANSWER: wrong' },
+        { role: 'user', content: 'tool results' },
+        { role: 'assistant', content: 'After more research FINAL_ANSWER: correct' },
+    ];
+    // Should return 'correct' (last assistant message first in reverse scan)
+    const result = extractFromPriorMessages(messages);
+    assert.strictEqual(result, 'correct', `Expected 'correct' (most recent), got ${result}`);
+});
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+// Wait for all async tests to settle, then print summary
+setTimeout(() => {
+    const total = passed + failed;
+    console.log('');
+    console.log('=== GAIA Convergence Layer Smoke Test ===');
+    console.log(`Pass rate:  ${passed}/${total}`);
+    console.log(`Status:     ${failed === 0 ? 'ALL PASSED' : `${failed} FAILED`}`);
+    if (failed > 0) {
+        process.exit(1);
+    }
+}, 200);
+//# sourceMappingURL=gaia-convergence.smoke.js.map

package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-critic.d.ts

@@ -0,0 +1,123 @@
+/**
+ * GAIA Adversarial Critic — ADR-135 Track D
+ *
+ * After the main agent produces a candidate answer, a Sonnet pass reviews it.
+ * If the critic verdict is "fail", the orchestrator re-runs the agent with the
+ * critique injected as additional context.
+ *
+ * Motivation (iter 29 finding): tool quality is the bottleneck on L1 (~20.8%).
+ * The critic catches wrong-because-of-bad-tool-result answers BEFORE submission,
+ * without requiring better search backends.  Expected L1 lift: +3-5pp.
+ *
+ * Design:
+ *  - NEW file only; NOT wired into gaia-bench.ts yet to avoid merge conflicts
+ *    with in-flight iter 29/31/34 branches.  Wiring is a small follow-up PR.
+ *  - `criticReview()` — single Sonnet call, returns structured verdict.
+ *  - `runGaiaAgentWithCritic()` — orchestration wrapper: runs agent, calls
+ *    critic, retries once on "fail".  "uncertain" is treated as "pass" (don't
+ *    burn retries on borderline cases).
+ *  - API errors and malformed JSON from the critic are caught; original
+ *    candidate is returned with an error-flagged verdict.
+ *  - Default opt-in: enableCritic=false.  Set true via RunWithCriticOptions.
+ *
+ * Cost discipline:
+ *  - Critic uses claude-sonnet-4-6 (separate from the agent's default Haiku).
+ *  - One critic call + one optional retry = max 2 extra Sonnet calls per Q.
+ *  - Approximate extra cost per question: ~$0.003-0.005 (well within budget).
+ *
+ * Plugin sync TODO (follow-up PR after gaia-bench wiring):
+ *  - Update plugins/ruflo-workflows/commands/gaia-run.md with --enable-critic flag.
+ *  - Update plugins/ruflo-workflows/skills/gaia-debugging/SKILL.md: add critic
+ *    as a recommended diagnostic step for wrong-answer analysis.
+ *
+ * Refs: ADR-135, ADR-133, iter 29 finding, #2156
+ */
+import { GaiaQuestion } from './gaia-loader.js';
+import { GaiaAgentResult, GaiaAgentOptions } from './gaia-agent.js';
+/**
+ * Structured verdict returned by the adversarial critic.
+ *
+ * - "pass"      → critic agrees with the candidate; no retry needed.
+ * - "fail"      → critic found a flaw; suggestedRevision provided if possible.
+ * - "uncertain" → critic is unsure; treated as "pass" to avoid burning retries.
+ */
+export type CriticVerdictType = 'pass' | 'fail' | 'uncertain';
+export interface CriticVerdict {
+    /** Critic's assessment of the candidate answer. */
+    verdict: CriticVerdictType;
+    /** Short explanation of the reasoning (1-3 sentences). */
+    reasoning: string;
+    /** Suggested correction when verdict is "fail"; may be empty string. */
+    suggestedRevision?: string;
+    /** Estimated USD cost of this critic call. */
+    costUsd: number;
+    /** True when the critic call itself failed (API error, malformed JSON). */
+    error?: boolean;
+    /** Original raw response text when parse failed. */
+    rawResponse?: string;
+}
+export interface CriticOptions {
+    /**
+     * Model to use for the critic pass.
+     * Defaults to 'claude-sonnet-4-6' (intentionally separate from agent model).
+     */
+    model?: string;
+    /**
+     * Maximum number of agent retries on "fail" verdict.
+     * Default: 1 (one retry).  Set to 0 to disable retries (observe-only mode).
+     */
+    maxRetries?: number;
+    /** Anthropic API key (resolved via env/gcloud if omitted). */
+    apiKey?: string;
+}
+export interface GaiaAgentResultWithCritic extends GaiaAgentResult {
+    /** All critic verdicts collected (one per agent attempt). */
+    criticVerdicts: CriticVerdict[];
+    /** How many retries were actually attempted (0 if critic passed first time). */
+    retriesAttempted: number;
+}
+/** Options for runGaiaAgentWithCritic, extending core agent options. */
+export interface RunWithCriticOptions extends GaiaAgentOptions {
+    /**
+     * Enable the adversarial critic pass.  Default: false.
+     * When false, runGaiaAgentWithCritic behaves identically to runGaiaAgent.
+     */
+    enableCritic?: boolean;
+    /** Critic-specific configuration. */
+    criticOptions?: CriticOptions;
+}
+/**
+ * Run the adversarial critic against a candidate answer.
+ *
+ * @param question     - The GAIA question being evaluated.
+ * @param candidateAnswer - The agent's proposed final answer.
+ * @param trajectory   - Lightweight trajectory summary from the agent run.
+ * @param options      - Critic configuration (model, apiKey).
+ * @returns            CriticVerdict with verdict, reasoning, cost.
+ */
+export declare function criticReview(question: GaiaQuestion, candidateAnswer: string, trajectory: {
+    steps: Array<{
+        tool?: string;
+        result?: string;
+        reasoning?: string;
+    }>;
+    turns: number;
+}, options?: CriticOptions): Promise<CriticVerdict>;
+/**
+ * Run the GAIA agent with an optional adversarial critic pass.
+ *
+ * When enableCritic=false (default), this is a thin pass-through to
+ * runGaiaAgent with an empty criticVerdicts array.
+ *
+ * When enableCritic=true:
+ *  1. Run runGaiaAgent normally.
+ *  2. If the agent produced a finalAnswer, call criticReview.
+ *  3. If verdict is "fail" and retriesAttempted < maxRetries:
+ *     a. Re-run the agent with the critique injected as additional context.
+ *     b. Call criticReview again on the new answer.
+ *  4. Return the final result with all critic verdicts attached.
+ *
+ * Note on "uncertain": treated as "pass" (no retry triggered).
+ */
+export declare function runGaiaAgentWithCritic(question: GaiaQuestion, options?: RunWithCriticOptions): Promise<GaiaAgentResultWithCritic>;
+//# sourceMappingURL=gaia-critic.d.ts.map