@cjhyy/code-shell-arena 0.8.0

package/dist/phases/cross-review.js

@@ -0,0 +1,224 @@
+/**
+ * CrossReview / VerificationReview — participants review each other's findings.
+ *
+ * V1 (CrossReview): Each participant sees the other participants' structured findings
+ * and provides per-finding verdicts: agree, refine, disagree, needs_evidence.
+ *
+ * V2 (VerificationReview): Reviewers get claim + evidence packet + digest data,
+ * and produce ClaimChallenge records that feed into the claim state machine.
+ */
+import { createLLMClient } from "@cjhyy/code-shell-core/extension";
+import { isStrategyV2, isStrategyPlanning } from "../types.js";
+import { selectClaimsForReview } from "./claim-registry.js";
+import { buildDigest } from "../digest-builder.js";
+import { markUnderReview, applyReviewResult } from "../transitions.js";
+import { logger } from "@cjhyy/code-shell-core/extension";
+/**
+ * Run cross-review phase (V1). Each participant reviews the others' findings.
+ */
+export async function runCrossReview(options) {
+    const { participants, strategy, topic, reports, signal, onProgress, onUsage } = options;
+    onProgress?.({ type: "cross_review_start", round: 1 });
+    const allReviews = [];
+    const tasks = participants.map(async (p) => {
+        const myReport = reports.find((r) => r.participant === p.name);
+        const otherReports = reports.filter((r) => r.participant !== p.name);
+        // Skip if no other reports to review
+        if (otherReports.length === 0)
+            return [];
+        if (!myReport)
+            return [];
+        const client = await createLLMClient(p.llm, p.clientDefaults);
+        const systemPrompt = strategy.crossReviewSystemPrompt(p.name);
+        const userContent = strategy.crossReviewUserPrompt(topic, myReport, otherReports);
+        let response = await client.createMessage({
+            systemPrompt,
+            messages: [{ role: "user", content: userContent }],
+            signal,
+        });
+        onUsage?.(response.usage);
+        logger.info("arena.cross_review_raw_response", {
+            participant: p.name,
+            text: response.text,
+            stopReason: response.stopReason,
+        });
+        // Retry if truncated
+        if (response.stopReason === "length") {
+            logger.warn("arena.cross_review_truncated", { participant: p.name });
+            const retryResponse = await client.createMessage({
+                systemPrompt,
+                messages: [
+                    { role: "user", content: userContent },
+                    { role: "assistant", content: response.text },
+                    {
+                        role: "user",
+                        content: "Your previous response was truncated. Please output the COMPLETE review JSON, using shorter comments. Respond ONLY with JSON.",
+                    },
+                ],
+                signal,
+            });
+            onUsage?.(retryResponse.usage);
+            logger.info("arena.cross_review_retry", {
+                participant: p.name,
+                stopReason: retryResponse.stopReason,
+            });
+            response = retryResponse;
+        }
+        return strategy.parseCrossReviewResponse(p.name, response.text);
+    });
+    const results = await Promise.all(tasks);
+    for (const reviews of results) {
+        allReviews.push(...reviews);
+    }
+    onProgress?.({ type: "cross_review_done", reviews: allReviews });
+    return allReviews;
+}
+/**
+ * Run verification-review phase. Reviewers get claim + evidence + digest data.
+ * Falls back to V1 cross-review if strategy doesn't implement V2.
+ */
+export async function runVerificationReview(options) {
+    const { participants, strategy, topic, reports, ledger, limits, mode, signal, onProgress, onUsage } = options;
+    // Select claims to review, prioritized by severity + confidence
+    const allClaims = ledger.getAllClaims();
+    const claimsToReview = selectClaimsForReview(allClaims, limits.maxClaimsForReview);
+    // Transition selected claims to under_review
+    for (const claim of claimsToReview) {
+        markUnderReview(claim);
+    }
+    // Build digest for reviewer context
+    const relevantClaimIds = claimsToReview.map((c) => c.claimId);
+    const digest = buildDigest(ledger, { round: 1, relevantClaimIds });
+    const isPlanningMerge = mode === "planning" && isStrategyPlanning(strategy);
+    if (isPlanningMerge) {
+        onProgress?.({ type: "planning_merge_review_start" });
+    }
+    else {
+        onProgress?.({ type: "verification_start" });
+    }
+    const v2 = isStrategyV2(strategy);
+    const allReviews = [];
+    const allChallenges = [];
+    // Assign claims to reviewers: each claim reviewed by non-owners, capped
+    const tasks = participants.map(async (p) => {
+        const myReport = reports.find((r) => r.participant === p.name);
+        const otherReports = reports.filter((r) => r.participant !== p.name);
+        if (!myReport || otherReports.length === 0)
+            return;
+        // Claims this participant should review (not their own)
+        const myClaims = claimsToReview.filter((c) => c.owner !== p.name);
+        if (myClaims.length === 0)
+            return;
+        const client = await createLLMClient(p.llm, p.clientDefaults);
+        const systemPrompt = strategy.crossReviewSystemPrompt(p.name);
+        if (v2) {
+            // V2 path: claim-aware verification review (or merge review for planning)
+            const userContent = isPlanningMerge
+                ? strategy.mergeReviewUserPrompt(topic, myReport, myClaims, digest)
+                : strategy
+                    .verificationReviewUserPrompt(topic, myReport, myClaims, digest);
+            let response = await client.createMessage({
+                systemPrompt,
+                messages: [{ role: "user", content: userContent }],
+                signal,
+            });
+            onUsage?.(response.usage);
+            logger.info("arena.verification_review_raw", {
+                participant: p.name,
+                stopReason: response.stopReason,
+            });
+            if (response.stopReason === "length") {
+                const retryResponse = await client.createMessage({
+                    systemPrompt,
+                    messages: [
+                        { role: "user", content: userContent },
+                        { role: "assistant", content: response.text },
+                        { role: "user", content: "Truncated. Output the COMPLETE JSON array, shorter comments. JSON only." },
+                    ],
+                    signal,
+                });
+                onUsage?.(retryResponse.usage);
+                response = retryResponse;
+            }
+            const challenges = isPlanningMerge
+                ? strategy.parseMergeReviewResponse(p.name, response.text)
+                : strategy
+                    .parseVerificationReviewResponse(p.name, response.text);
+            for (const challenge of challenges) {
+                allChallenges.push(challenge);
+                ledger.appendChallenge(challenge);
+            }
+            // Also produce FindingReview for backward compat
+            for (const ch of challenges) {
+                allReviews.push({
+                    reviewer: ch.reviewer,
+                    findingId: ch.claimId,
+                    verdict: ch.verdict,
+                    reason: ch.reason,
+                    extraEvidence: ch.supportingEvidenceRefs,
+                });
+            }
+        }
+        else {
+            // V1 fallback: standard cross-review, then map to challenges
+            const userContent = strategy.crossReviewUserPrompt(topic, myReport, otherReports);
+            let response = await client.createMessage({
+                systemPrompt,
+                messages: [{ role: "user", content: userContent }],
+                signal,
+            });
+            onUsage?.(response.usage);
+            if (response.stopReason === "length") {
+                const retryResponse = await client.createMessage({
+                    systemPrompt,
+                    messages: [
+                        { role: "user", content: userContent },
+                        { role: "assistant", content: response.text },
+                        { role: "user", content: "Truncated. Output COMPLETE review JSON. Shorter comments. JSON only." },
+                    ],
+                    signal,
+                });
+                onUsage?.(retryResponse.usage);
+                response = retryResponse;
+            }
+            const reviews = strategy.parseCrossReviewResponse(p.name, response.text);
+            allReviews.push(...reviews);
+            // Map FindingReview → ClaimChallenge for claim state updates
+            for (const review of reviews) {
+                // Find the claim that matches this finding
+                const claim = claimsToReview.find((c) => c.finding.id === review.findingId || c.claimId === review.findingId);
+                if (claim) {
+                    const challenge = {
+                        reviewer: review.reviewer,
+                        claimId: claim.claimId,
+                        verdict: review.verdict,
+                        reason: review.reason,
+                        supportingEvidenceRefs: review.extraEvidence,
+                    };
+                    allChallenges.push(challenge);
+                    ledger.appendChallenge(challenge);
+                }
+            }
+        }
+    });
+    await Promise.all(tasks);
+    // Apply review results to claim status transitions
+    for (const claim of claimsToReview) {
+        const claimChallenges = ledger.getChallengesForClaim(claim.claimId);
+        const hasPendingChecks = ledger.getPendingChecksForClaim(claim.claimId).length > 0;
+        applyReviewResult(claim, claimChallenges, hasPendingChecks);
+    }
+    logger.info("arena.verification_done", {
+        reviewCount: allReviews.length,
+        challengeCount: allChallenges.length,
+        claimStatuses: Object.fromEntries(claimsToReview.map((c) => [c.claimId, c.status])),
+    });
+    if (isPlanningMerge) {
+        onProgress?.({ type: "planning_merge_review_done", mergeCount: allChallenges.length });
+    }
+    else {
+        onProgress?.({ type: "verification_done", challengeCount: allChallenges.length });
+    }
+    onProgress?.({ type: "cross_review_done", reviews: allReviews });
+    return { reviews: allReviews, challenges: allChallenges };
+}

package/dist/phases/debate-rounds.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DebateRounds — contested claims enter structured debate between
+ * the claim owner and the primary challenger.
+ *
+ * Each debate round:
+ *   1. Both debaters produce a DebateTurn (stance + argument)
+ *   2. Convergence check: all stances are "support" or "narrow" → resolved
+ *   3. If max rounds exhausted → stays contested for adjudication
+ */
+import type { ArenaParticipant, ArenaStrategy, DebateRound, ArenaExecutionLimits, ArenaProgressEvent, ArenaUsageRecorder } from "../types.js";
+import type { ArenaLedger } from "../ledger.js";
+interface DebateOptions {
+    participants: ArenaParticipant[];
+    strategy: ArenaStrategy;
+    topic: string;
+    ledger: ArenaLedger;
+    limits: ArenaExecutionLimits;
+    maxRounds: number;
+    signal?: AbortSignal;
+    onProgress?: (event: ArenaProgressEvent) => void;
+    onUsage?: ArenaUsageRecorder;
+}
+/**
+ * Run debate rounds for all contested claims.
+ * Returns empty array if no contested claims exist.
+ */
+export declare function runDebateRounds(options: DebateOptions): Promise<DebateRound[]>;
+export {};

package/dist/phases/debate-rounds.js

@@ -0,0 +1,161 @@
+/**
+ * DebateRounds — contested claims enter structured debate between
+ * the claim owner and the primary challenger.
+ *
+ * Each debate round:
+ *   1. Both debaters produce a DebateTurn (stance + argument)
+ *   2. Convergence check: all stances are "support" or "narrow" → resolved
+ *   3. If max rounds exhausted → stays contested for adjudication
+ */
+import { createLLMClient } from "@cjhyy/code-shell-core/extension";
+import { isStrategyV2 } from "../types.js";
+import { buildDigest } from "../digest-builder.js";
+import { parseDebateTurn as parseDebateTurnUtil } from "../strategies/utils.js";
+import { logger } from "@cjhyy/code-shell-core/extension";
+/**
+ * Run debate rounds for all contested claims.
+ * Returns empty array if no contested claims exist.
+ */
+export async function runDebateRounds(options) {
+    const { participants, strategy, topic, ledger, limits, maxRounds, signal, onProgress, onUsage } = options;
+    // Select contested claims, capped
+    const contested = ledger.getClaimsByStatus("contested")
+        .slice(0, limits.maxContestedClaimsForDebate);
+    if (contested.length === 0) {
+        logger.info("arena.debate_skip", { reason: "no contested claims" });
+        return [];
+    }
+    logger.info("arena.debate_start", {
+        contestedCount: contested.length,
+        maxRounds,
+    });
+    const allDebateRounds = [];
+    const v2 = isStrategyV2(strategy);
+    // Debate each claim sequentially (to avoid token explosion from parallelism)
+    for (const claim of contested) {
+        signal?.throwIfAborted();
+        const claimDebateRounds = await debateClaim({
+            claim,
+            participants,
+            strategy,
+            v2,
+            topic,
+            ledger,
+            maxRounds,
+            signal,
+            onProgress,
+            onUsage,
+        });
+        allDebateRounds.push(...claimDebateRounds);
+        // Attach debate rounds to claim record
+        claim.debateRounds.push(...claimDebateRounds);
+    }
+    return allDebateRounds;
+}
+async function debateClaim(options) {
+    const { claim, participants, strategy, v2, topic, ledger, maxRounds, signal, onProgress, onUsage } = options;
+    // Identify debaters: claim owner + primary challenger
+    const owner = participants.find((p) => p.name === claim.owner);
+    const primaryChallenger = findPrimaryChallenger(claim, participants);
+    if (!owner || !primaryChallenger) {
+        logger.warn("arena.debate_skip_claim", {
+            claimId: claim.claimId,
+            reason: "cannot identify debaters",
+        });
+        return [];
+    }
+    const debaters = [owner, primaryChallenger];
+    const rounds = [];
+    const allTurns = [];
+    for (let round = 1; round <= maxRounds; round++) {
+        signal?.throwIfAborted();
+        onProgress?.({ type: "debate_round_start", round, claims: [claim.claimId] });
+        const digest = buildDigest(ledger, {
+            round,
+            relevantClaimIds: [claim.claimId],
+        });
+        // Each debater produces a turn
+        const turnPromises = debaters.map(async (p) => {
+            const client = await createLLMClient(p.llm, p.clientDefaults);
+            const systemPrompt = strategy.crossReviewSystemPrompt(p.name);
+            let userContent;
+            if (v2) {
+                userContent = strategy
+                    .debateTurnUserPrompt(topic, claim, allTurns, digest);
+            }
+            else {
+                // Fallback prompt for non-V2 strategies
+                userContent = buildFallbackDebatePrompt(topic, claim, allTurns);
+            }
+            const response = await client.createMessage({
+                systemPrompt,
+                messages: [{ role: "user", content: userContent }],
+                signal,
+            });
+            onUsage?.(response.usage);
+            logger.info("arena.debate_turn", {
+                participant: p.name,
+                claimId: claim.claimId,
+                round,
+                stopReason: response.stopReason,
+            });
+            if (v2) {
+                return strategy.parseDebateTurnResponse(p.name, response.text);
+            }
+            return parseDebateTurnUtil(p.name, response.text);
+        });
+        const turns = await Promise.all(turnPromises);
+        allTurns.push(...turns);
+        // Check convergence
+        const resolved = turns.every((t) => t.stance === "support" || t.stance === "narrow");
+        const resolutionNote = resolved
+            ? `Converged in round ${round}: ${turns.map((t) => `${t.participant}=${t.stance}`).join(", ")}`
+            : undefined;
+        const debateRound = {
+            round,
+            claimId: claim.claimId,
+            participants: turns,
+            resolved,
+            resolutionNote,
+        };
+        rounds.push(debateRound);
+        onProgress?.({ type: "debate_round_done", round, resolved: resolved ? 1 : 0 });
+        if (resolved) {
+            logger.info("arena.debate_converged", {
+                claimId: claim.claimId,
+                round,
+            });
+            break;
+        }
+    }
+    return rounds;
+}
+/**
+ * Find the primary challenger — the participant who disagreed or requested evidence.
+ */
+function findPrimaryChallenger(claim, participants) {
+    // Prefer disagree over needs_evidence
+    const disagreeChallenge = claim.challenges.find((c) => c.verdict === "disagree");
+    const needsEvidenceChallenge = claim.challenges.find((c) => c.verdict === "needs_evidence");
+    const challenge = disagreeChallenge ?? needsEvidenceChallenge ?? claim.challenges[0];
+    if (!challenge)
+        return undefined;
+    return participants.find((p) => p.name === challenge.reviewer);
+}
+/**
+ * Build a fallback debate prompt for non-V2 strategies.
+ */
+function buildFallbackDebatePrompt(topic, claim, priorTurns) {
+    const turnsText = priorTurns.length > 0
+        ? priorTurns.map((t) => `[${t.participant}] ${t.stance}: ${t.summary}`).join("\n")
+        : "No prior turns.";
+    return (`## Topic: ${topic}\n\n` +
+        `## Contested Claim\n` +
+        `[${claim.claimId}] ${claim.finding.title}\n${claim.finding.summary}\n\n` +
+        `## Prior Debate\n${turnsText}\n\n` +
+        `State your position on this claim. Build on prior turns: cite specific evidence, ` +
+        `acknowledge counter-arguments, and explain your reasoning in 150-300 words. ` +
+        `Brevity here means missed nuance — depth wins.\n` +
+        `Respond ONLY with JSON:\n` +
+        `{"stance": "support|oppose|narrow|uncertain", "summary": "your argument", "newEvidenceRefs": ["optional"]}`);
+}

package/dist/phases/participant-research.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ParticipantResearch — each participant independently investigates
+ * the shared base context and produces structured findings.
+ *
+ * Phase 3 upgrade: now captures ToolTrace and builds EvidencePackets,
+ * outputting a full ResearchDossier alongside the ParticipantReport.
+ */
+import type { ArenaBaseContext, ArenaParticipant, ArenaStrategy, ParticipantReport, ResearchDossier, ArenaProgressEvent, ArenaUsageRecorder } from "../types.js";
+import type { ToolDefinition } from "@cjhyy/code-shell-core/extension";
+/** Result of a single participant's research — includes both report and dossier */
+export interface ResearchResult {
+    report: ParticipantReport;
+    dossier: ResearchDossier;
+}
+interface ResearchOptions {
+    participants: ArenaParticipant[];
+    strategy: ArenaStrategy;
+    topic: string;
+    baseContext: ArenaBaseContext;
+    enableContextTools?: boolean;
+    /** Plan-selected tools override. When provided, these are used instead of all CONTEXT_TOOLS. */
+    contextTools?: ToolDefinition[];
+    /** AbortSignal — cancels in-flight LLM calls */
+    signal?: AbortSignal;
+    onProgress?: (event: ArenaProgressEvent) => void;
+    onUsage?: ArenaUsageRecorder;
+}
+/**
+ * Run participant research phase in parallel.
+ * Each participant reads the shared context, optionally requests more,
+ * then produces structured findings with evidence trails.
+ */
+export declare function runParticipantResearch(options: ResearchOptions): Promise<ParticipantReport[]>;
+/**
+ * Run participant research phase with full dossier output.
+ * Returns both reports (backward compat) and dossiers (evidence trail).
+ */
+export declare function runParticipantResearchWithDossiers(options: ResearchOptions): Promise<ResearchResult[]>;
+export {};