@cjhyy/code-shell-arena 0.8.0

package/dist/phases/participant-research.js

@@ -0,0 +1,322 @@
+/**
+ * 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 { createLLMClient } from "@cjhyy/code-shell-core/extension";
+import { CONTEXT_TOOLS, MAX_TOOL_ROUNDS, executeContextTool } from "../context/context-tools.js";
+import { logger } from "@cjhyy/code-shell-core/extension";
+import { createHash } from "node:crypto";
+/**
+ * Run participant research phase in parallel.
+ * Each participant reads the shared context, optionally requests more,
+ * then produces structured findings with evidence trails.
+ */
+export async function runParticipantResearch(options) {
+    const results = await runParticipantResearchWithDossiers(options);
+    return results.map((r) => r.report);
+}
+/**
+ * Run participant research phase with full dossier output.
+ * Returns both reports (backward compat) and dossiers (evidence trail).
+ */
+export async function runParticipantResearchWithDossiers(options) {
+    const { participants, strategy, topic, baseContext, enableContextTools, contextTools, signal, onProgress, onUsage } = options;
+    const tools = enableContextTools ? (contextTools ?? CONTEXT_TOOLS) : undefined;
+    const tasks = participants.map(async (p) => {
+        onProgress?.({ type: "research_start", participant: p.name });
+        const client = await createLLMClient(p.llm, p.clientDefaults);
+        const messages = [
+            {
+                role: "user",
+                content: strategy.researchUserPrompt(topic, baseContext),
+            },
+        ];
+        let finalText = "";
+        let totalRounds = 0;
+        const toolTraces = [];
+        const evidencePackets = [];
+        // ── Tool-use loop ──────────────────────────────────────────
+        const MAX_MESSAGES = 30; // Cap messages to prevent token overflow
+        for (let round = 0; round <= MAX_TOOL_ROUNDS; round++) {
+            totalRounds = round;
+            // Safety: prevent unbounded message growth
+            if (messages.length >= MAX_MESSAGES) {
+                logger.warn("arena.research_message_limit", {
+                    participant: p.name,
+                    messageCount: messages.length,
+                    round,
+                });
+                break;
+            }
+            const response = await client.createMessage({
+                systemPrompt: strategy.researchSystemPrompt(p.name),
+                messages,
+                tools,
+                signal,
+            });
+            onUsage?.(response.usage);
+            const toolNames = (response.toolCalls ?? []).map((tc) => tc.toolName);
+            const hasTools = response.toolCalls && response.toolCalls.length > 0;
+            logger.info("arena.research_round", {
+                participant: p.name,
+                round,
+                toolCount: response.toolCalls?.length ?? 0,
+                toolNames,
+                textLen: response.text?.length ?? 0,
+                stopReason: response.stopReason ?? "unknown",
+            });
+            if (!hasTools) {
+                finalText = response.text;
+                break;
+            }
+            // Report tool usage to UI
+            onProgress?.({
+                type: "context_lookup",
+                participant: p.name,
+                tools: response.toolCalls.map((tc) => `${tc.toolName}(${JSON.stringify(tc.args)})`),
+            });
+            // Append assistant message with tool_use blocks
+            const assistantBlocks = [];
+            if (response.text) {
+                assistantBlocks.push({ type: "text", text: response.text });
+            }
+            for (const tc of response.toolCalls) {
+                assistantBlocks.push({
+                    type: "tool_use",
+                    id: tc.id,
+                    name: tc.toolName,
+                    input: tc.args,
+                });
+            }
+            messages.push({ role: "assistant", content: assistantBlocks });
+            // Execute tools, record traces, and build evidence packets
+            const resultBlocks = [];
+            for (const tc of response.toolCalls) {
+                const result = executeContextTool(tc);
+                // Record tool trace
+                const trace = {
+                    round,
+                    toolName: tc.toolName,
+                    args: tc.args,
+                    resultRef: buildResultRef(tc),
+                    keptAsEvidence: result.length > 50 && !result.startsWith("Error:") && !result.startsWith("Tool error:") && !result.startsWith("Unknown tool:"),
+                };
+                toolTraces.push(trace);
+                // Build evidence packet from successful tool results
+                if (trace.keptAsEvidence) {
+                    const packet = buildEvidencePacketFromTool(p.name, tc, result, inferSourceKind(tc.toolName));
+                    evidencePackets.push(packet);
+                }
+                resultBlocks.push({
+                    type: "tool_result",
+                    tool_use_id: tc.id,
+                    content: result,
+                });
+            }
+            // ── Anti-loop hard nudge ───────────────────────────────────
+            // Thinking-mode models (DeepSeek V4 in particular) will
+            // otherwise spend every available round on read_file with
+            // textLen=0, then need a separate force_conclude pass to emit
+            // findings. We prepend the directive to the user turn so it
+            // appears BEFORE the tool results — trailing text after
+            // tool_result blocks gets ignored by some implementations.
+            const remaining = MAX_TOOL_ROUNDS - round;
+            const isLastAllowedRound = remaining <= 0;
+            const isPenultimate = remaining === 1;
+            if (isLastAllowedRound || isPenultimate) {
+                const directive = isLastAllowedRound
+                    ? "STOP. You have used your tool budget. Your NEXT response MUST be the findings JSON. Do NOT call any more tools — any further tool_use will be discarded."
+                    : "FINAL ROUND. Use the tool results below plus any prior context to output the findings JSON in your NEXT response. Do not call more tools.";
+                resultBlocks.unshift({
+                    type: "text",
+                    text: `[arena-research:${p.name}] ${directive}`,
+                });
+            }
+            messages.push({ role: "user", content: resultBlocks });
+        }
+        // ── Force-conclude if no text yet ──────────────────────────
+        if (!finalText) {
+            logger.warn("arena.research_force_conclude", {
+                participant: p.name,
+                totalRounds,
+                messageCount: messages.length,
+            });
+            // Bail out before spending a request if the user already stopped. Without
+            // this (and the `signal` below) a Stop during the force-conclude phase
+            // left the final model request running to completion — still billed, and
+            // still holding the task alive until the provider answered on its own.
+            signal?.throwIfAborted();
+            const forceResponse = await client.createMessage({
+                systemPrompt: strategy.researchSystemPrompt(p.name),
+                messages: [
+                    ...messages,
+                    {
+                        role: "user",
+                        content: "You have gathered enough context. " +
+                            "Based on ALL the tool results above, output your findings NOW.\n\n" +
+                            "Respond ONLY with the <report> XML element specified in the system prompt — " +
+                            "output your highest-confidence findings (typically 5-15 for a substantive topic; " +
+                            "each <summary> should be 80+ words with concrete evidence). " +
+                            "Do NOT request any more tools. No prose outside the XML.",
+                    },
+                ],
+                signal,
+            });
+            onUsage?.(forceResponse.usage);
+            logger.info("arena.research_force_conclude_response", {
+                participant: p.name,
+                textLen: forceResponse.text?.length ?? 0,
+                stopReason: forceResponse.stopReason ?? "unknown",
+            });
+            finalText = forceResponse.text;
+        }
+        // ── Final output ───────────────────────────────────────────
+        logger.info("arena.research_raw_response", {
+            participant: p.name,
+            textLength: finalText.length,
+            text: finalText,
+        });
+        // If still empty after force-conclude, mark as failed
+        if (!finalText || finalText.trim().length === 0) {
+            logger.warn("arena.research_failed", {
+                participant: p.name,
+                totalRounds,
+                messageCount: messages.length,
+            });
+            const failedReport = {
+                participant: p.name,
+                contextSummary: `(research failed: model returned empty response after ${totalRounds} tool rounds)`,
+                findings: [],
+            };
+            const failedDossier = {
+                participant: p.name,
+                contextSummary: failedReport.contextSummary,
+                findings: [],
+                toolTrace: toolTraces,
+                evidencePackets,
+                findingEvidenceLinks: [],
+            };
+            onProgress?.({ type: "research_done", participant: p.name, report: failedReport });
+            return { report: failedReport, dossier: failedDossier };
+        }
+        const report = strategy.parseResearchResponse(p.name, finalText);
+        // Build finding-evidence links by matching finding evidence refs to packets
+        const findingEvidenceLinks = buildFindingEvidenceLinks(report, evidencePackets);
+        const dossier = {
+            participant: p.name,
+            contextSummary: report.contextSummary,
+            findings: report.findings,
+            toolTrace: toolTraces,
+            evidencePackets,
+            findingEvidenceLinks,
+        };
+        onProgress?.({ type: "research_done", participant: p.name, report });
+        return { report, dossier };
+    });
+    return Promise.all(tasks);
+}
+// ─── Helper functions ──────────────────────────────────────────
+/** Build a stable ref string for a tool call */
+function buildResultRef(tc) {
+    if (tc.toolName === "read_file" && tc.args.path)
+        return `file:${tc.args.path}`;
+    if (tc.toolName === "grep_code" && tc.args.pattern)
+        return `grep:${tc.args.pattern}`;
+    if (tc.toolName === "list_files" && tc.args.path)
+        return `dir:${tc.args.path}`;
+    if (tc.toolName === "git_show" && tc.args.ref)
+        return `git:${tc.args.ref}`;
+    if (tc.toolName === "git_blame" && tc.args.path)
+        return `blame:${tc.args.path}`;
+    return `${tc.toolName}:${JSON.stringify(tc.args).slice(0, 60)}`;
+}
+/** Generate a stable packet ID */
+function generatePacketId(participant, source, ref, snippet) {
+    const hash = createHash("sha256")
+        .update(`${participant}:${source}:${ref}:${snippet.slice(0, 200)}`)
+        .digest("hex")
+        .slice(0, 12);
+    return `pkt-${hash}`;
+}
+/** Infer the evidence source kind from the tool that produced it */
+function inferSourceKind(toolName) {
+    switch (toolName) {
+        case "git_show":
+        case "git_blame":
+            return "git";
+        case "read_file":
+        case "grep_code":
+        case "list_files":
+            return "repo";
+        default:
+            return "repo";
+    }
+}
+/** Build an EvidencePacket from a tool call result */
+function buildEvidencePacketFromTool(participant, tc, result, source) {
+    const ref = buildResultRef(tc);
+    const snippet = result.slice(0, 500);
+    const packetId = generatePacketId(participant, source, ref, snippet);
+    return {
+        packetId,
+        participant,
+        source,
+        title: `${tc.toolName}: ${formatToolArgs(tc.args)}`,
+        refs: [ref],
+        summary: result.slice(0, 200),
+        excerpts: [{
+                ref,
+                snippet,
+                note: `Result of ${tc.toolName} call`,
+            }],
+    };
+}
+/** Format tool args into a concise display string */
+function formatToolArgs(args) {
+    const parts = [];
+    for (const [key, value] of Object.entries(args)) {
+        if (typeof value === "string")
+            parts.push(value.slice(0, 60));
+        else
+            parts.push(`${key}=${JSON.stringify(value)}`);
+    }
+    return parts.join(", ").slice(0, 100);
+}
+/**
+ * Build links between findings and evidence packets by matching
+ * finding evidence refs against packet refs.
+ */
+function buildFindingEvidenceLinks(report, packets) {
+    const links = [];
+    for (const finding of report.findings) {
+        const matchedPacketIds = [];
+        for (const evidence of finding.evidence) {
+            const evidenceRef = `${evidence.type}:${evidence.ref}`;
+            // Find packets whose refs overlap with this evidence ref
+            for (const packet of packets) {
+                const matches = packet.refs.some((pRef) => {
+                    // Exact match
+                    if (pRef === evidenceRef)
+                        return true;
+                    // Partial match — packet ref contains the file path
+                    if (evidence.ref && pRef.includes(evidence.ref))
+                        return true;
+                    return false;
+                });
+                if (matches && !matchedPacketIds.includes(packet.packetId)) {
+                    matchedPacketIds.push(packet.packetId);
+                }
+            }
+        }
+        if (matchedPacketIds.length > 0) {
+            links.push({
+                findingId: finding.id,
+                evidencePacketIds: matchedPacketIds,
+            });
+        }
+    }
+    return links;
+}

package/dist/phases/planning-detail-expansion.d.ts

@@ -0,0 +1,39 @@
+/**
+ * PlanningDetailExpansion — expands high-level roadmap phases into
+ * repo-level implementation plans.
+ *
+ * This phase is planning-mode specific. It takes the roadmap produced
+ * by consensus and, for each phase, calls the LLM to produce concrete
+ * implementation details: target files, code changes, interfaces,
+ * migration steps, validation, effort, and blockers.
+ *
+ * Tool access is available so the LLM can verify file paths and interfaces.
+ */
+import type { ArenaParticipant, ArenaRoadmapPhase, ArenaRoadmapPhaseDetail, ArenaProgressEvent, ArenaExecutionLimits, ArenaStrategyPlanning, ArenaUsageRecorder } from "../types.js";
+import type { ToolDefinition } from "@cjhyy/code-shell-core/extension";
+import type { ArenaLedger } from "../ledger.js";
+interface DetailExpansionOptions {
+    /** The participant that performs the expansion (typically the concluder) */
+    concluder: ArenaParticipant;
+    strategy: ArenaStrategyPlanning;
+    topic: string;
+    /** Roadmap phases to expand */
+    phases: ArenaRoadmapPhase[];
+    ledger: ArenaLedger;
+    limits: ArenaExecutionLimits;
+    /** Enable read-only context tools for file path verification */
+    enableContextTools?: boolean;
+    /** Plan-selected tools override */
+    contextTools?: ToolDefinition[];
+    signal?: AbortSignal;
+    onProgress?: (event: ArenaProgressEvent) => void;
+    onUsage?: ArenaUsageRecorder;
+}
+/**
+ * Expand each roadmap phase into a repo-level implementation plan.
+ *
+ * Phases are expanded sequentially to avoid token explosion.
+ * The number of phases expanded is capped by limits.maxExpandedPhasesPerRun.
+ */
+export declare function runDetailExpansion(options: DetailExpansionOptions): Promise<ArenaRoadmapPhaseDetail[]>;
+export {};

package/dist/phases/planning-detail-expansion.js

@@ -0,0 +1,120 @@
+/**
+ * PlanningDetailExpansion — expands high-level roadmap phases into
+ * repo-level implementation plans.
+ *
+ * This phase is planning-mode specific. It takes the roadmap produced
+ * by consensus and, for each phase, calls the LLM to produce concrete
+ * implementation details: target files, code changes, interfaces,
+ * migration steps, validation, effort, and blockers.
+ *
+ * Tool access is available so the LLM can verify file paths and interfaces.
+ */
+import { createLLMClient } from "@cjhyy/code-shell-core/extension";
+import { logger } from "@cjhyy/code-shell-core/extension";
+import { buildDigest } from "../digest-builder.js";
+import { CONTEXT_TOOLS, MAX_TOOL_ROUNDS, executeContextTool } from "../context/context-tools.js";
+/** Max tool rounds per phase expansion (lighter than research) */
+const MAX_EXPANSION_TOOL_ROUNDS = 3;
+/**
+ * Expand each roadmap phase into a repo-level implementation plan.
+ *
+ * Phases are expanded sequentially to avoid token explosion.
+ * The number of phases expanded is capped by limits.maxExpandedPhasesPerRun.
+ */
+export async function runDetailExpansion(options) {
+    const { concluder, strategy, topic, phases, ledger, limits, signal, onProgress, onUsage } = options;
+    const tools = options.enableContextTools !== false
+        ? (options.contextTools ?? CONTEXT_TOOLS)
+        : undefined;
+    // Cap phases to expand
+    const toExpand = phases.slice(0, limits.maxExpandedPhasesPerRun);
+    onProgress?.({ type: "roadmap_expansion_start", phaseCount: toExpand.length });
+    logger.info("arena.detail_expansion_start", { phaseCount: toExpand.length });
+    const details = [];
+    const client = await createLLMClient(concluder.llm, concluder.clientDefaults);
+    const systemPrompt = strategy.detailExpansionSystemPrompt();
+    // Expand each phase sequentially
+    for (const phase of toExpand) {
+        signal?.throwIfAborted();
+        // Build phase-specific digest using related findings
+        const relevantClaimIds = phase.relatedFindings ?? [];
+        const digest = buildDigest(ledger, { round: 1, relevantClaimIds });
+        const userContent = strategy.detailExpansionUserPrompt(topic, phase, digest);
+        const messages = [{ role: "user", content: userContent }];
+        let finalText = "";
+        // Tool-use loop: allow LLM to verify file paths and interfaces.
+        // `maxRounds` bounds the number of tool rounds; after the last one we make
+        // one final call (without tools) so the model produces text FROM the tool
+        // results rather than the empty text it emitted alongside the tool calls.
+        const maxRounds = tools ? Math.min(MAX_EXPANSION_TOOL_ROUNDS, MAX_TOOL_ROUNDS) : 0;
+        for (let round = 0; round <= maxRounds; round++) {
+            // On the final round, stop offering tools so the model must answer.
+            const offerTools = round < maxRounds ? tools : undefined;
+            const response = await client.createMessage({
+                systemPrompt,
+                messages,
+                tools: offerTools,
+                signal,
+            });
+            onUsage?.(response.usage);
+            const hasTools = response.toolCalls && response.toolCalls.length > 0;
+            logger.info("arena.detail_expansion_round", {
+                phase: phase.title,
+                round,
+                toolCount: response.toolCalls?.length ?? 0,
+                stopReason: response.stopReason,
+            });
+            if (!hasTools) {
+                finalText = response.text;
+                break;
+            }
+            // Append assistant message with tool_use blocks
+            const assistantBlocks = [];
+            if (response.text) {
+                assistantBlocks.push({ type: "text", text: response.text });
+            }
+            for (const tc of response.toolCalls) {
+                assistantBlocks.push({
+                    type: "tool_use",
+                    id: tc.id,
+                    name: tc.toolName,
+                    input: tc.args,
+                });
+            }
+            messages.push({ role: "assistant", content: assistantBlocks });
+            // Execute tools and append results
+            const toolResultBlocks = [];
+            for (const tc of response.toolCalls) {
+                const result = executeContextTool(tc);
+                toolResultBlocks.push({
+                    type: "tool_result",
+                    tool_use_id: tc.id,
+                    content: result.slice(0, 15_000),
+                });
+            }
+            messages.push({ role: "user", content: toolResultBlocks });
+        }
+        // Retry if truncated
+        if (!finalText) {
+            finalText = "";
+        }
+        logger.info("arena.detail_expansion_phase", {
+            phase: phase.title,
+            textLen: finalText.length,
+        });
+        const detail = strategy.parseDetailExpansionResponse(finalText);
+        if (!detail.phaseTitle)
+            detail.phaseTitle = phase.title;
+        // Log parse quality
+        if (detail.targetFiles.length === 0 && detail.codeChanges.length === 0) {
+            logger.warn("arena.detail_expansion_sparse", {
+                phase: phase.title,
+                objective: detail.objective.slice(0, 200),
+            });
+        }
+        details.push(detail);
+    }
+    logger.info("arena.detail_expansion_done", { detailCount: details.length });
+    onProgress?.({ type: "roadmap_expansion_done", detailCount: details.length });
+    return details;
+}

package/dist/planner.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Planner — the brain of Evidence-Driven Arena.
+ *
+ * Takes a natural language user request and produces a complete ArenaPlan:
+ * - mode (how to collaborate)
+ * - lenses (from what perspectives)
+ * - sources (where to gather evidence)
+ * - subject (what is being analyzed)
+ * - outputShape (how to structure the result)
+ *
+ * Replaces the old IntentResolver + ScopeResolver pipeline with a single
+ * LLM call that outputs a holistic execution plan.
+ */
+import type { LLMConfig } from "@cjhyy/code-shell-core/extension";
+import type { ArenaUsageRecorder } from "./types.js";
+import type { ArenaPlan, ArenaMode } from "./types.js";
+/** Explicit flags the user may pass via CLI or tool args */
+export interface PlannerFlags {
+    mode?: ArenaMode;
+    base?: string;
+    head?: string;
+}
+/**
+ * Run the planner to produce an ArenaPlan from natural language.
+ *
+ * Priority: explicit flags > LLM plan > safe defaults.
+ */
+export declare function planArena(topic: string, llmConfig: LLMConfig, flags?: PlannerFlags, signal?: AbortSignal, onUsage?: ArenaUsageRecorder): Promise<ArenaPlan>;