@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/arena/planner.js

@@ -0,0 +1,312 @@
+/**
+ * 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 { createLLMClient } from "../llm/client-factory.js";
+import { LENS_NAMES } from "./lenses/index.js";
+import { logger } from "../logging/logger.js";
+const PLANNER_SYSTEM_PROMPT = `You are the planner for a multi-model collaborative analysis tool called Arena.
+
+Given a user's natural language request, produce an execution plan. You must determine:
+
+1. **mode** — how to collaborate:
+   - "review": find issues, verify quality, give a structured verdict
+   - "discussion": explore trade-offs, compare viewpoints, preserve disagreements
+   - "planning": build a roadmap, identify phases, dependencies, and risks
+
+2. **lenses** — from what analytical perspectives (can be multiple):
+   - "engineering": code quality, correctness, performance, maintainability
+   - "product": user value, requirements completeness, acceptance criteria, UX
+   - "architecture": system boundaries, modularity, coupling, evolution paths
+   - "general": broad analysis, logic, trade-offs (use as fallback)
+
+3. **sources** — where to gather evidence (can be multiple):
+   - "git": diffs, commit history, branch comparison, changed files
+   - "repo": directory structure, source code files, symbol search
+   - "docs": markdown/text documents, PRDs, design docs
+   - "web": external information, standards, competitor analysis
+   - "none": pure topic discussion, no external evidence needed
+
+4. **subject** — what is being analyzed:
+   - kind: "changes" (code changes), "files" (specific files), "docs" (documents), "topic" (abstract topic), "mixed"
+   - label: human-readable description
+   - targets: specific file paths, branch names, or doc names if applicable
+
+5. **outputShape** — what to emphasize in the output
+
+Respond ONLY with JSON, no markdown fences:
+{
+  "mode": "review|discussion|planning",
+  "lenses": [{"name": "engineering|product|architecture|general", "weight": 1.0}],
+  "sources": [{"kind": "git|repo|docs|web|none", "targets": ["optional specific targets"]}],
+  "subject": {"kind": "changes|files|docs|topic|mixed", "label": "description", "targets": ["optional"]},
+  "outputShape": {"overviewLabel": "e.g. What Changed / Current Scope / Problem Framing", "emphasize": ["risk", "improvement"]},
+  "confidence": "high|medium|low",
+  "followUpQuestion": "question if confidence is low, or null"
+}`;
+/**
+ * Run the planner to produce an ArenaPlan from natural language.
+ *
+ * Priority: explicit flags > LLM plan > safe defaults.
+ */
+export async function planArena(topic, llmConfig, flags, signal) {
+    // If mode and base are both explicit, we can skip the LLM call
+    if (flags?.mode && flags?.base) {
+        return buildExplicitPlan(topic, flags);
+    }
+    try {
+        signal?.throwIfAborted();
+        const client = await createLLMClient({
+            ...llmConfig,
+            enableStreaming: false,
+            maxTokens: 1024,
+        });
+        const response = await client.createMessage({
+            systemPrompt: PLANNER_SYSTEM_PROMPT,
+            messages: [{ role: "user", content: `<user_request>\n${topic}\n</user_request>\n\nAnalyze the user request above and output the arena plan as JSON.` }],
+            maxTokens: 1024,
+            signal,
+        });
+        const plan = parsePlanResponse(response.text, topic);
+        // Explicit flags override LLM output
+        if (flags?.mode)
+            plan.mode = flags.mode;
+        if (flags?.base) {
+            plan.sources = [{ kind: "git", targets: [flags.base, flags.head ?? "HEAD"] }];
+            plan.subject = { kind: "changes", label: `${flags.base}...${flags.head ?? "HEAD"}`, targets: [flags.base, flags.head ?? "HEAD"] };
+        }
+        logger.info("arena.planner", { plan });
+        return plan;
+    }
+    catch (err) {
+        logger.warn("arena.planner_fallback", { error: err.message });
+        return buildFallbackPlan(topic, flags);
+    }
+}
+function parsePlanResponse(text, topic) {
+    const fenced = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+    const jsonStr = fenced ? fenced[1].trim() : text.match(/\{[\s\S]*\}/)?.[0] ?? text;
+    try {
+        const parsed = JSON.parse(jsonStr);
+        return {
+            mode: validateMode(parsed.mode),
+            lenses: parseLenses(parsed.lenses),
+            sources: parseSources(parsed.sources),
+            subject: parseSubject(parsed.subject, topic),
+            outputShape: parseOutputShape(parsed.outputShape, parsed.mode),
+            confidence: validateConfidence(parsed.confidence),
+            followUpQuestion: parsed.followUpQuestion || undefined,
+        };
+    }
+    catch {
+        return buildFallbackPlan(topic);
+    }
+}
+function buildExplicitPlan(topic, flags) {
+    return {
+        mode: flags.mode,
+        lenses: [{ name: "engineering", weight: 1 }],
+        sources: [
+            { kind: "git", targets: [flags.base, flags.head ?? "HEAD"] },
+            { kind: "repo" },
+        ],
+        subject: {
+            kind: "changes",
+            label: `${flags.base}...${flags.head ?? "HEAD"}`,
+            targets: [flags.base, flags.head ?? "HEAD"],
+        },
+        outputShape: {
+            overviewLabel: "What Changed",
+            emphasize: ["risk", "improvement"],
+        },
+        confidence: "high",
+    };
+}
+function buildFallbackPlan(topic, flags) {
+    if (flags?.base) {
+        return {
+            mode: flags.mode ?? "review",
+            lenses: [{ name: "engineering", weight: 1 }],
+            sources: [{ kind: "git" }, { kind: "repo" }],
+            subject: { kind: "changes", label: topic, targets: [flags.base, flags.head ?? "HEAD"] },
+            outputShape: {
+                overviewLabel: "What Changed",
+                emphasize: ["risk", "improvement"],
+            },
+            confidence: "low",
+        };
+    }
+    const lower = topic.toLowerCase();
+    const hasDoc = /\b(prd|doc|docs|spec|rfc|design doc|requirement|proposal)\b/i.test(topic)
+        || /(文档|需求|方案)/.test(topic);
+    const hasRoadmap = /\b(roadmap|plan|planning|strategy|migration|refactor)\b/i.test(topic)
+        || /(演进|路线图|规划|重构)/.test(topic);
+    const hasFeasibility = /\b(feasibility|feasible|can we|should we|trade-?off)\b/i.test(topic)
+        || /(可行|能不能|值不值得|取舍)/.test(topic);
+    const hasReview = /\b(review|pr|diff|patch|change)\b/i.test(topic)
+        || /(改动|评审|审查)/.test(topic);
+    const hasRepo = /\b(repo|repository|codebase|module|architecture)\b/i.test(topic)
+        || /(代码库|仓库|模块|架构)/.test(topic);
+    if (hasRoadmap) {
+        return {
+            mode: "planning",
+            lenses: hasDoc
+                ? [{ name: "architecture", weight: 1 }, { name: "product", weight: 0.7 }]
+                : [{ name: "architecture", weight: 1 }, { name: "engineering", weight: 0.8 }],
+            sources: hasDoc
+                ? [{ kind: "docs" }, ...(hasRepo ? [{ kind: "repo" }] : [])]
+                : [{ kind: "repo" }, { kind: "docs" }],
+            subject: { kind: hasDoc ? "mixed" : "topic", label: topic },
+            outputShape: {
+                overviewLabel: "Current Scope",
+                emphasize: ["improvement", "risk", "question"],
+            },
+            confidence: "low",
+        };
+    }
+    if (hasDoc && hasFeasibility) {
+        return {
+            mode: "discussion",
+            lenses: [{ name: "product", weight: 1 }, { name: "engineering", weight: 0.8 }],
+            sources: hasRepo ? [{ kind: "docs" }, { kind: "repo" }] : [{ kind: "docs" }],
+            subject: { kind: hasRepo ? "mixed" : "docs", label: topic },
+            outputShape: {
+                overviewLabel: "Problem Framing",
+                emphasize: ["question", "risk", "improvement"],
+            },
+            confidence: "low",
+        };
+    }
+    if (hasDoc) {
+        return {
+            mode: hasReview ? "review" : "discussion",
+            lenses: [{ name: "product", weight: 1 }, { name: "architecture", weight: 0.6 }],
+            sources: hasRepo ? [{ kind: "docs" }, { kind: "repo" }] : [{ kind: "docs" }],
+            subject: { kind: hasRepo ? "mixed" : "docs", label: topic },
+            outputShape: {
+                overviewLabel: hasReview ? "Current Scope" : "Problem Framing",
+                emphasize: ["question", "improvement", "risk"],
+            },
+            confidence: "low",
+        };
+    }
+    if (hasFeasibility) {
+        return {
+            mode: "discussion",
+            lenses: hasRepo
+                ? [{ name: "product", weight: 1 }, { name: "engineering", weight: 0.8 }]
+                : [{ name: "general", weight: 1 }, { name: "product", weight: 0.6 }],
+            sources: hasRepo ? [{ kind: "repo" }, { kind: "docs" }] : [{ kind: "none" }],
+            subject: { kind: hasRepo ? "topic" : "topic", label: topic },
+            outputShape: {
+                overviewLabel: "Problem Framing",
+                emphasize: ["question", "risk", "improvement"],
+            },
+            confidence: "low",
+        };
+    }
+    if (hasReview || /\b(commit|branch|diff|patch|bug|fix|回归)\b/i.test(lower)) {
+        return {
+            mode: "review",
+            lenses: [{ name: "engineering", weight: 1 }],
+            sources: [{ kind: "git" }, { kind: "repo" }],
+            subject: { kind: "changes", label: topic },
+            outputShape: {
+                overviewLabel: "What Changed",
+                emphasize: ["risk", "improvement", "question"],
+            },
+            confidence: "low",
+        };
+    }
+    return {
+        mode: flags?.mode ?? "review",
+        lenses: [{ name: hasRepo ? "architecture" : "general", weight: 1 }],
+        sources: hasRepo ? [{ kind: "repo" }, { kind: "docs" }] : [{ kind: "none" }],
+        subject: { kind: "topic", label: topic },
+        outputShape: {
+            overviewLabel: hasRepo ? "Current Scope" : "Problem Framing",
+            emphasize: hasRepo ? ["improvement", "risk", "question"] : ["question", "risk", "improvement"],
+        },
+        confidence: "low",
+    };
+}
+// ─── Validators ─────────────────────────────────────────────────
+function validateMode(v) {
+    if (v === "review" || v === "discussion" || v === "planning")
+        return v;
+    return "review";
+}
+function validateConfidence(v) {
+    if (v === "high" || v === "medium" || v === "low")
+        return v;
+    return "medium";
+}
+function parseLenses(v) {
+    if (!Array.isArray(v) || v.length === 0) {
+        return [{ name: "general", weight: 1 }];
+    }
+    const result = v
+        .filter((item) => LENS_NAMES.includes(item?.name))
+        .map((item) => ({
+        name: item.name,
+        weight: typeof item.weight === "number" ? item.weight : 1,
+    }));
+    return result.length > 0 ? result : [{ name: "general", weight: 1 }];
+}
+function parseSources(v) {
+    if (!Array.isArray(v) || v.length === 0) {
+        return [{ kind: "none" }];
+    }
+    const validKinds = ["git", "repo", "docs", "web", "none"];
+    const result = v
+        .filter((item) => validKinds.includes(item?.kind))
+        .map((item) => ({
+        kind: item.kind,
+        targets: Array.isArray(item.targets) ? item.targets : undefined,
+    }));
+    return result.length > 0 ? result : [{ kind: "none" }];
+}
+function parseSubject(v, topic) {
+    if (!v || typeof v !== "object") {
+        return { kind: "topic", label: topic };
+    }
+    const obj = v;
+    const validKinds = ["changes", "files", "docs", "topic", "mixed"];
+    return {
+        kind: validKinds.includes(obj.kind) ? obj.kind : "topic",
+        label: obj.label ?? topic,
+        targets: Array.isArray(obj.targets) ? obj.targets : undefined,
+    };
+}
+const VALID_EMPHASIZE = new Set(["strength", "improvement", "risk", "question"]);
+function parseOutputShape(v, mode) {
+    if (v && typeof v === "object") {
+        const obj = v;
+        return {
+            overviewLabel: obj.overviewLabel ?? "Overview",
+            emphasize: Array.isArray(obj.emphasize)
+                ? obj.emphasize.filter((k) => VALID_EMPHASIZE.has(k))
+                : ["risk", "improvement"],
+        };
+    }
+    // Defaults per mode
+    switch (mode) {
+        case "review":
+            return { overviewLabel: "What Changed", emphasize: ["risk", "improvement"] };
+        case "discussion":
+            return { overviewLabel: "Problem Framing", emphasize: ["strength", "risk", "question"] };
+        case "planning":
+            return { overviewLabel: "Current Scope", emphasize: ["improvement", "risk"] };
+        default:
+            return { overviewLabel: "Overview", emphasize: ["risk", "improvement"] };
+    }
+}

package/dist/arena/providers/docs.d.ts

@@ -0,0 +1,6 @@
+/**
+ * DocsProvider — collects evidence from documentation files:
+ * markdown, text, PRDs, design docs.
+ */
+import type { ArenaContextProvider } from "../types.js";
+export declare const docsProvider: ArenaContextProvider;

package/dist/arena/providers/docs.js

@@ -0,0 +1,108 @@
+/**
+ * DocsProvider — collects evidence from documentation files:
+ * markdown, text, PRDs, design docs.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, extname } from "node:path";
+import { logger } from "../../logging/logger.js";
+const MAX_DOC_CHARS = 10_000;
+const DOC_EXTENSIONS = new Set([".md", ".txt", ".rst", ".adoc", ".org"]);
+export const docsProvider = {
+    kind: "docs",
+    collect(plan, topic) {
+        const artifacts = [];
+        const sourceSpec = plan.sources.find((s) => s.kind === "docs");
+        const targets = sourceSpec?.targets ?? [];
+        // Read explicit target documents
+        for (const target of targets) {
+            const content = safeReadDoc(target);
+            if (content) {
+                artifacts.push({
+                    id: `doc-${target}`,
+                    kind: "doc",
+                    source: "docs",
+                    title: target,
+                    ref: target,
+                    preview: truncate(content),
+                });
+            }
+        }
+        // If no explicit targets, scan common doc locations
+        if (targets.length === 0) {
+            const docDirs = ["docs", "doc", "design", "specs", "proposals", "."];
+            const found = new Set();
+            for (const dir of docDirs) {
+                if (!existsSync(dir))
+                    continue;
+                const docs = findDocFiles(dir, 2);
+                for (const docPath of docs) {
+                    if (found.has(docPath))
+                        continue;
+                    found.add(docPath);
+                    // Score relevance by checking if doc content/name relates to topic
+                    const name = docPath.toLowerCase();
+                    const topicLower = topic.toLowerCase();
+                    const keywords = topicLower.split(/\s+/).filter((w) => w.length > 2);
+                    const isRelevant = keywords.some((kw) => name.includes(kw));
+                    if (isRelevant || found.size <= 5) {
+                        const content = safeReadDoc(docPath);
+                        if (content) {
+                            artifacts.push({
+                                id: `doc-${docPath}`,
+                                kind: "doc",
+                                source: "docs",
+                                title: docPath,
+                                ref: docPath,
+                                preview: truncate(content),
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        logger.info("arena.provider.docs", { artifactCount: artifacts.length });
+        return artifacts;
+    },
+};
+function findDocFiles(dir, maxDepth, depth = 0) {
+    if (depth >= maxDepth)
+        return [];
+    const files = [];
+    try {
+        const entries = readdirSync(dir);
+        for (const entry of entries) {
+            if (entry.startsWith(".") || entry === "node_modules")
+                continue;
+            const full = join(dir, entry);
+            const st = statSync(full);
+            if (st.isFile() && DOC_EXTENSIONS.has(extname(entry).toLowerCase())) {
+                files.push(full);
+            }
+            else if (st.isDirectory() && depth < maxDepth - 1) {
+                files.push(...findDocFiles(full, maxDepth, depth + 1));
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return files;
+}
+function safeReadDoc(filePath) {
+    try {
+        if (!existsSync(filePath))
+            return null;
+        const st = statSync(filePath);
+        if (st.size > 500_000)
+            return null;
+        return readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+function truncate(content) {
+    if (content.length <= MAX_DOC_CHARS)
+        return content;
+    const t = content.slice(0, MAX_DOC_CHARS);
+    const lastNl = t.lastIndexOf("\n");
+    return t.slice(0, lastNl) + `\n... (truncated, ${content.length} chars total)`;
+}

package/dist/arena/providers/git.d.ts

@@ -0,0 +1,8 @@
+/**
+ * GitProvider — collects evidence from git: diffs, commit logs, changed files.
+ *
+ * Security: All git commands use execFileSync with argument arrays
+ * to prevent shell injection. Git refs are sanitized before use.
+ */
+import type { ArenaContextProvider } from "../types.js";
+export declare const gitProvider: ArenaContextProvider;

package/dist/arena/providers/git.js

@@ -0,0 +1,174 @@
+/**
+ * GitProvider — collects evidence from git: diffs, commit logs, changed files.
+ *
+ * Security: All git commands use execFileSync with argument arrays
+ * to prevent shell injection. Git refs are sanitized before use.
+ */
+import { execFileSync } from "node:child_process";
+import { logger } from "../../logging/logger.js";
+const MAX_DIFF_CHARS = 20_000;
+const MAX_CHANGED_FILES = 30;
+export const gitProvider = {
+    kind: "git",
+    collect(plan, _topic) {
+        const artifacts = [];
+        const targets = plan.sources.find((s) => s.kind === "git")?.targets;
+        const baseRef = sanitizeRef(targets?.[0]);
+        const headRef = sanitizeRef(targets?.[1]) ?? "HEAD";
+        const isCompare = !!baseRef;
+        // Current branch
+        const currentBranch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
+        if (currentBranch) {
+            artifacts.push({
+                id: "git-branch",
+                kind: "doc",
+                source: "git",
+                title: "Current Branch",
+                preview: currentBranch,
+            });
+        }
+        // Commit log
+        const logArgs = isCompare
+            ? ["log", "--oneline", `${baseRef}..${headRef}`, "--max-count=20"]
+            : ["log", "--oneline", "-10"];
+        const log = git(logArgs);
+        if (log) {
+            artifacts.push({
+                id: "git-log",
+                kind: "doc",
+                source: "git",
+                title: "Commit Log",
+                preview: log,
+            });
+        }
+        // Diff stat
+        const statArgs = isCompare
+            ? ["diff", "--stat", `${baseRef}...${headRef}`]
+            : ["diff", "--stat", "HEAD"];
+        let stat = git(statArgs);
+        if (!stat && !isCompare)
+            stat = git(["diff", "--stat", "--cached"]);
+        if (stat) {
+            artifacts.push({
+                id: "git-diffstat",
+                kind: "doc",
+                source: "git",
+                title: "Diff Stat",
+                preview: stat,
+            });
+        }
+        // Changed files
+        const filesArgs = isCompare
+            ? ["diff", "--name-status", `${baseRef}...${headRef}`]
+            : ["diff", "--name-status", "HEAD"];
+        let changedFiles = git(filesArgs);
+        if (!changedFiles && !isCompare)
+            changedFiles = git(["diff", "--name-status", "--cached"]);
+        if (changedFiles) {
+            const allChanged = changedFiles.split("\n").filter(Boolean);
+            const limited = allChanged.slice(0, MAX_CHANGED_FILES);
+            if (allChanged.length > MAX_CHANGED_FILES) {
+                limited.push(`... and ${allChanged.length - MAX_CHANGED_FILES} more files`);
+            }
+            artifacts.push({
+                id: "git-changed-files",
+                kind: "doc",
+                source: "git",
+                title: "Changed Files",
+                preview: limited.join("\n"),
+                metadata: { totalCount: allChanged.length },
+            });
+            // Directory clustering
+            const paths = allChanged.map((line) => line.split("\t").slice(1).join("\t")).filter(Boolean);
+            const dirCounts = clusterByDirectory(paths);
+            if (dirCounts.length > 0) {
+                artifacts.push({
+                    id: "git-dir-clusters",
+                    kind: "doc",
+                    source: "git",
+                    title: "Changes by Directory",
+                    preview: dirCounts.slice(0, 15).map(([dir, count]) => `  ${dir}/ (${count} files)`).join("\n"),
+                });
+            }
+        }
+        // Truncated diff
+        const diffArgs = isCompare
+            ? ["diff", `${baseRef}...${headRef}`]
+            : ["diff", "HEAD"];
+        let diff = git(diffArgs);
+        if (!diff && !isCompare)
+            diff = git(["diff", "--cached"]);
+        if (diff) {
+            const truncated = diff.length > MAX_DIFF_CHARS;
+            const preview = truncated
+                ? diff.slice(0, MAX_DIFF_CHARS).slice(0, diff.slice(0, MAX_DIFF_CHARS).lastIndexOf("\n"))
+                : diff;
+            artifacts.push({
+                id: "git-diff",
+                kind: "diff",
+                source: "git",
+                title: "Diff",
+                preview: preview + (truncated
+                    ? `\n\n... TRUNCATED (${diff.length} chars total). Use read_file to inspect specific files.`
+                    : ""),
+                metadata: { totalChars: diff.length, truncated },
+            });
+        }
+        // Fallback: git status
+        if (!diff && !stat) {
+            const status = git(["status", "--short"]);
+            if (status) {
+                artifacts.push({
+                    id: "git-status",
+                    kind: "doc",
+                    source: "git",
+                    title: "Git Status",
+                    preview: status,
+                });
+            }
+        }
+        logger.info("arena.provider.git", {
+            artifactCount: artifacts.length,
+            hasCompare: isCompare,
+        });
+        return artifacts;
+    },
+};
+/**
+ * Execute a git command safely using execFileSync (no shell interpretation).
+ */
+function git(args) {
+    try {
+        return execFileSync("git", args, {
+            encoding: "utf-8",
+            maxBuffer: 1024 * 1024,
+            timeout: 10_000,
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Sanitize a git ref string from LLM output.
+ * Strips range operators (.., ...) and shell-unsafe characters so that
+ * the ref can be safely interpolated into `git diff baseRef...headRef`.
+ */
+function sanitizeRef(ref) {
+    if (!ref)
+        return undefined;
+    // Strip range operators that the LLM may have included
+    let cleaned = ref.replace(/\.{2,}/g, "");
+    // Only allow safe git ref characters: alphanumeric, /, -, _, ~, ^, .
+    cleaned = cleaned.replace(/[^a-zA-Z0-9/_\-~^.]/g, "");
+    return cleaned || undefined;
+}
+function clusterByDirectory(paths) {
+    const counts = new Map();
+    for (const p of paths) {
+        const parts = p.split("/");
+        const dir = parts.length > 2 ? parts.slice(0, 2).join("/") : parts[0];
+        counts.set(dir, (counts.get(dir) ?? 0) + 1);
+    }
+    return [...counts.entries()].sort((a, b) => b[1] - a[1]);
+}

package/dist/arena/providers/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Provider registry — evidence collectors for Arena.
+ */
+import type { ArenaPlan, ArenaArtifact, ArenaSourceKind, ArenaQuickFact } from "../types.js";
+export { gitProvider } from "./git.js";
+export { repoProvider } from "./repo.js";
+export { docsProvider } from "./docs.js";
+export { noneProvider } from "./none.js";
+export interface CollectEvidenceOptions {
+    /** Heartbeat callback fired before/after each provider runs. */
+    onProgress?: (event: {
+        type: "evidence_started" | "evidence_collected";
+        source: ArenaSourceKind;
+        count?: number;
+        durationMs?: number;
+        timedOut?: boolean;
+    }) => void;
+    signal?: AbortSignal;
+}
+/**
+ * Collect all evidence according to the plan's sources.
+ * Returns unified ArenaArtifact[] and quickFacts.
+ *
+ * Providers run in parallel (independent of one another) with a
+ * per-provider timeout, so a single slow source can't stall the
+ * whole arena. Heartbeats are emitted around each provider so the
+ * UI can show "collecting from repo..." instead of a blank pause.
+ */
+export declare function collectEvidence(plan: ArenaPlan, topic: string, options?: CollectEvidenceOptions): Promise<{
+    artifacts: ArenaArtifact[];
+    quickFacts: ArenaQuickFact[];
+}>;