@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/arena/arena.js

@@ -1,333 +0,0 @@
-/**
- * Arena — multi-model collaborative analysis engine.
- *
- * Evidence-Driven Pipeline:
- *   0. Planner            → understand what the user wants (mode, lenses, sources)
- *   1. EvidenceProviders   → collect artifacts from selected sources
- *   2. Strategy + Lens     → compose prompts (mode flow + perspective)
- *   3. ToolSelector        → determine which tools participants can use
- *   4. ParticipantResearch  → each model investigates independently (parallel)
- *   4b. ClaimRegistry      → register findings as claims, populate ledger
- *   5. VerificationReview   → claim-aware cross-review with evidence digests
- *   7. DebateRounds         → contested claims enter structured debate
- *   8. Adjudication         → moderator rules on contested claims
- *   6. ConsensusBuilder     → claim-aware structured consensus
- */
-import { logger } from "../logging/logger.js";
-import { ARENA_MODE_DEFAULTS, DEFAULT_EXECUTION_LIMITS, isStrategyPlanning } from "./types.js";
-import { getStrategy, getStrategyForPlan } from "./strategies/index.js";
-import { planArena } from "./planner.js";
-import { collectEvidence } from "./providers/index.js";
-import { selectTools } from "./tools/selector.js";
-import { runParticipantResearchWithDossiers } from "./phases/participant-research.js";
-import { runVerificationReview } from "./phases/cross-review.js";
-import { runDebateRounds } from "./phases/debate-rounds.js";
-import { runAdjudication } from "./phases/adjudication.js";
-import { buildConsensus } from "./phases/build-consensus.js";
-import { runDetailExpansion } from "./phases/planning-detail-expansion.js";
-import { withLanguage } from "./strategies/language-wrapper.js";
-import { ArenaLedger } from "./ledger.js";
-import { registerClaims } from "./phases/claim-registry.js";
-/** Bucket claims by status. Shared by the two consensus phases. */
-function summarizeClaims(all) {
-    return {
-        verified: all.filter((c) => c.status === "verified"),
-        contested: all.filter((c) => c.status === "contested"),
-        unresolved: all.filter((c) => c.status === "unresolved"),
-        rejected: all.filter((c) => c.status === "rejected"),
-    };
-}
-export class Arena {
-    config;
-    strategy;
-    limits;
-    constructor(config) {
-        if (config.participants.length < 2) {
-            throw new Error("Arena requires at least 2 participants");
-        }
-        const mode = config.mode ?? "review";
-        const defaults = ARENA_MODE_DEFAULTS[mode];
-        this.config = {
-            mode,
-            maxDiscussionRounds: config.maxDiscussionRounds ?? defaults.maxDiscussionRounds,
-            ...config,
-        };
-        this.limits = config.executionLimits ?? DEFAULT_EXECUTION_LIMITS;
-        // Initial strategy — will be overridden in run() with lens + language wrappers
-        this.strategy = config.strategy ?? getStrategy(mode);
-    }
-    /**
-     * Run a full arena session.
-     *
-     * @param topic  - User's topic/request (natural language)
-     * @param flags  - Optional explicit overrides (mode, base, head)
-     */
-    async run(topic, flags) {
-        const participantNames = this.config.participants.map((p) => p.name);
-        const signal = this.config.signal;
-        logger.info("arena.start", { mode: this.config.mode, participants: participantNames });
-        signal?.throwIfAborted();
-        // ─── Phase 0: Plan ────────────────────────────────────────
-        const llmConfig = this.config.participants[0].llm;
-        const plan = await planArena(topic, llmConfig, flags, signal);
-        this.config.onProgress?.({ type: "plan_resolved", plan });
-        logger.info("arena.plan", {
-            mode: plan.mode,
-            lenses: plan.lenses.map((l) => l.name),
-            sources: plan.sources.map((s) => s.kind),
-            subject: plan.subject.label,
-            confidence: plan.confidence,
-        });
-        if (!flags?.mode && plan.mode !== this.config.mode) {
-            this.config.mode = plan.mode;
-        }
-        signal?.throwIfAborted();
-        // ─── Phase 1: Collect Evidence ────────────────────────────
-        // Bridge collectEvidence's lifecycle events to the public
-        // ArenaProgressEvent stream so the UI sees "collecting from
-        // repo..." instead of a silent pause.
-        const onProgress = this.config.onProgress;
-        const { artifacts, quickFacts } = await collectEvidence(plan, topic, {
-            signal,
-            onProgress: (e) => {
-                if (e.type === "evidence_started") {
-                    onProgress?.({ type: "evidence_started", source: e.source });
-                }
-                else {
-                    onProgress?.({
-                        type: "evidence_source_done",
-                        source: e.source,
-                        count: e.count ?? 0,
-                        durationMs: e.durationMs ?? 0,
-                        timedOut: e.timedOut ?? false,
-                    });
-                }
-            },
-        });
-        onProgress?.({ type: "evidence_collected", artifacts });
-        logger.info("arena.evidence", {
-            artifactCount: artifacts.length,
-            sources: plan.sources.map((s) => s.kind),
-        });
-        const baseContext = { plan, artifacts, quickFacts };
-        // ─── Phase 2: Compose Strategy ────────────────────────────
-        this.strategy = this.config.strategy ?? getStrategyForPlan(plan);
-        this.strategy = withLanguage(this.strategy, topic);
-        // ─── Phase 3: Select Tools ────────────────────────────────
-        const contextTools = this.config.enableContextTools !== false
-            ? selectTools(plan)
-            : undefined;
-        signal?.throwIfAborted();
-        // ─── Phase 4: Participant Research (parallel) ─────────────
-        logger.info("arena.research_phase", { participants: participantNames });
-        const researchResults = await runParticipantResearchWithDossiers({
-            participants: this.config.participants,
-            strategy: this.strategy,
-            topic,
-            baseContext,
-            enableContextTools: this.config.enableContextTools ?? true,
-            contextTools,
-            signal,
-            onProgress: this.config.onProgress,
-        });
-        const reports = researchResults.map((r) => r.report);
-        const dossiers = researchResults.map((r) => r.dossier);
-        signal?.throwIfAborted();
-        // ─── Phase 4b: Claim Registry ─────────────────────────────
-        const ledger = new ArenaLedger();
-        // Populate ledger with dossiers
-        for (const dossier of dossiers) {
-            ledger.appendDossier(dossier);
-        }
-        // Register findings as claims
-        const claims = registerClaims({
-            dossiers,
-            ledger,
-            onProgress: this.config.onProgress,
-        });
-        logger.info("arena.claims_registered", {
-            claimCount: claims.length,
-            byOwner: Object.fromEntries(participantNames.map((name) => [
-                name,
-                claims.filter((c) => c.owner === name).length,
-            ])),
-        });
-        signal?.throwIfAborted();
-        // ─── Phase 5: Mode Policy Router ─────────────────────────
-        //
-        // Planning mode: merge-oriented review → roadmap consensus → detail expansion
-        // Review/Discussion mode: verification review → debate → adjudication → consensus
-        const concluderName = this.config.concluder ?? participantNames[0];
-        const concluderMatch = this.config.participants.find((p) => p.name === concluderName);
-        if (!concluderMatch && this.config.concluder) {
-            logger.warn("arena.concluder_not_found", {
-                requested: this.config.concluder,
-                fallback: this.config.participants[0].name,
-            });
-        }
-        const concluder = concluderMatch ?? this.config.participants[0];
-        const enableTools = this.config.enableContextTools !== false;
-        if (this.config.mode === "planning") {
-            return this.runPlanningPath({
-                topic, participantNames, plan, baseContext, reports, dossiers, ledger,
-                concluder, contextTools, enableContextTools: enableTools, signal,
-            });
-        }
-        return this.runReviewDiscussionPath({
-            topic, participantNames, plan, baseContext, reports, dossiers, ledger, concluder, signal,
-        });
-    }
-    /**
-     * Planning path: merge-oriented review → roadmap consensus → detail expansion.
-     *
-     * Planning mode does NOT enter heavy debate/adjudication. Contested findings
-     * are converted to open questions or dependency risks in the roadmap.
-     */
-    async runPlanningPath(ctx) {
-        const { topic, participantNames, plan, baseContext, reports, dossiers, ledger, concluder, contextTools, enableContextTools, signal, } = ctx;
-        // ─── Merge-Oriented Review ───────────────────────────────
-        logger.info("arena.planning_merge_review_phase");
-        const { reviews } = await runVerificationReview({
-            participants: this.config.participants,
-            strategy: this.strategy,
-            topic,
-            reports,
-            ledger,
-            limits: this.limits,
-            mode: "planning",
-            signal,
-            onProgress: this.config.onProgress,
-        });
-        signal?.throwIfAborted();
-        // ─── Roadmap Consensus ───────────────────────────────────
-        const allClaims = ledger.getAllClaims();
-        const claimSummary = summarizeClaims(allClaims);
-        logger.info("arena.planning_consensus_phase", { concluder: concluder.name });
-        const consensus = await buildConsensus({
-            concluder,
-            strategy: this.strategy,
-            topic,
-            reports,
-            reviews,
-            claimSummary,
-            signal,
-            onProgress: this.config.onProgress,
-        });
-        signal?.throwIfAborted();
-        // ─── Detail Expansion ────────────────────────────────────
-        if (consensus.roadmap.length > 0 && isStrategyPlanning(this.strategy)) {
-            logger.info("arena.detail_expansion_phase", { phaseCount: consensus.roadmap.length });
-            try {
-                const details = await runDetailExpansion({
-                    concluder,
-                    strategy: this.strategy,
-                    topic,
-                    phases: consensus.roadmap,
-                    ledger,
-                    limits: this.limits,
-                    enableContextTools,
-                    contextTools,
-                    signal,
-                    onProgress: this.config.onProgress,
-                });
-                consensus.roadmapDetails = details;
-            }
-            catch (err) {
-                // Detail expansion is non-critical — degrade gracefully
-                logger.warn("arena.detail_expansion_failed", {
-                    error: err.message,
-                    phaseCount: consensus.roadmap.length,
-                });
-            }
-        }
-        return {
-            topic,
-            mode: this.config.mode,
-            participants: participantNames,
-            plan,
-            baseContext,
-            reports,
-            dossiers,
-            claims: allClaims,
-            reviews,
-            consensus,
-        };
-    }
-    /**
-     * Review/Discussion path: verification review → debate → adjudication → consensus.
-     *
-     * This is the heavy trust loop for claim verification.
-     */
-    async runReviewDiscussionPath(ctx) {
-        const { topic, participantNames, plan, baseContext, reports, dossiers, ledger, concluder, signal } = ctx;
-        // ─── Verification Review (parallel) ──────────────────────
-        logger.info("arena.verification_review_phase");
-        const { reviews } = await runVerificationReview({
-            participants: this.config.participants,
-            strategy: this.strategy,
-            topic,
-            reports,
-            ledger,
-            limits: this.limits,
-            signal,
-            onProgress: this.config.onProgress,
-        });
-        signal?.throwIfAborted();
-        // ─── Debate Rounds ───────────────────────────────────────
-        logger.info("arena.debate_phase");
-        const debateRounds = await runDebateRounds({
-            participants: this.config.participants,
-            strategy: this.strategy,
-            topic,
-            ledger,
-            limits: this.limits,
-            maxRounds: this.config.maxDiscussionRounds,
-            signal,
-            onProgress: this.config.onProgress,
-        });
-        signal?.throwIfAborted();
-        // ─── Adjudication ────────────────────────────────────────
-        logger.info("arena.adjudication_phase", { concluder: concluder.name });
-        const adjudications = await runAdjudication({
-            concluder,
-            strategy: this.strategy,
-            topic,
-            ledger,
-            signal,
-            onProgress: this.config.onProgress,
-        });
-        signal?.throwIfAborted();
-        // ─── Consensus (claim-aware) ─────────────────────────────
-        const allClaims = ledger.getAllClaims();
-        const claimSummary = summarizeClaims(allClaims);
-        logger.info("arena.consensus_phase", {
-            concluder: concluder.name,
-            verified: claimSummary.verified.length,
-            unresolved: claimSummary.unresolved.length,
-        });
-        const consensus = await buildConsensus({
-            concluder,
-            strategy: this.strategy,
-            topic,
-            reports,
-            reviews,
-            claimSummary,
-            signal,
-            onProgress: this.config.onProgress,
-        });
-        return {
-            topic,
-            mode: this.config.mode,
-            participants: participantNames,
-            plan,
-            baseContext,
-            reports,
-            dossiers,
-            claims: allClaims,
-            reviews,
-            debateRounds,
-            adjudications,
-            consensus,
-        };
-    }
-}

package/dist/arena/context/context-tools.d.ts

@@ -1,16 +0,0 @@
-/**
- * Context tools — read-only tools that arena participants can use
- * to fetch additional source context during research.
- *
- * Security: All shell commands use execFileSync with argument arrays
- * to prevent command injection. File paths are validated against the
- * repository boundary to prevent path traversal.
- */
-import type { ToolDefinition, ToolCall } from "../../types.js";
-export declare const MAX_TOOL_RESULT = 15000;
-export declare const MAX_TOOL_ROUNDS = 3;
-export declare const CONTEXT_TOOLS: ToolDefinition[];
-/**
- * Execute a context tool call and return the result string.
- */
-export declare function executeContextTool(tc: ToolCall): string;

package/dist/arena/context/context-tools.js

@@ -1,272 +0,0 @@
-/**
- * Context tools — read-only tools that arena participants can use
- * to fetch additional source context during research.
- *
- * Security: All shell commands use execFileSync with argument arrays
- * to prevent command injection. File paths are validated against the
- * repository boundary to prevent path traversal.
- */
-import { readFileSync, existsSync, readdirSync, statSync, realpathSync } from "node:fs";
-import { execFileSync } from "node:child_process";
-import { resolve, join, dirname, basename } from "node:path";
-import { isWithinRoot } from "./within-root.js";
-export const MAX_TOOL_RESULT = 15_000; // chars per tool call
-// 5 was too generous for thinking-mode models — they'd spend the
-// entire budget on read_file with textLen=0, then need an
-// expensive force_conclude round to actually emit findings (logs
-// consistently showed 5/5 rounds + 70-150s force_conclude). Capping
-// at 3 makes the participant commit to a conclusion much sooner.
-export const MAX_TOOL_ROUNDS = 3;
-/** Repository root boundary — all file access is restricted to this directory */
-const REPO_ROOT = resolve(".");
-export const CONTEXT_TOOLS = [
-    {
-        name: "read_file",
-        description: "Read a file from the repository. Use this when you need to see the full source of a file " +
-            "referenced in the context, or to check surrounding code (callers, type definitions, etc.).",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "Relative file path from repo root" },
-                offset: { type: "number", description: "Start line (1-based, optional)" },
-                limit: { type: "number", description: "Max lines to read (optional, default 200)" },
-            },
-            required: ["path"],
-        },
-    },
-    {
-        name: "grep_code",
-        description: "Search for a pattern across the codebase. Use this to find callers, references, " +
-            "type definitions, or usages of symbols.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                pattern: { type: "string", description: "Regex pattern to search for" },
-                glob: { type: "string", description: "File glob filter, e.g. '*.ts' (optional)" },
-            },
-            required: ["pattern"],
-        },
-    },
-    {
-        name: "list_files",
-        description: "List files in a directory. Use this to understand project structure around relevant files.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "Directory path relative to repo root (default: '.')" },
-            },
-            required: [],
-        },
-    },
-    {
-        name: "git_show",
-        description: "Show a git object (commit, file at a ref, etc.). Use for inspecting specific commits " +
-            "or viewing a file at a different branch/commit.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                ref: { type: "string", description: "Git ref, e.g. 'HEAD~3', 'main:src/foo.ts', commit hash" },
-            },
-            required: ["ref"],
-        },
-    },
-    {
-        name: "git_blame",
-        description: "Show git blame for a file. Use to understand who changed what and when.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "File path" },
-                lines: { type: "string", description: "Line range, e.g. '10,20' (optional)" },
-            },
-            required: ["path"],
-        },
-    },
-];
-/**
- * Execute a context tool call and return the result string.
- */
-export function executeContextTool(tc) {
-    try {
-        switch (tc.toolName) {
-            case "read_file":
-                return executeReadFile(tc.args);
-            case "grep_code":
-                return executeGrepCode(tc.args);
-            case "list_files":
-                return executeListFiles(tc.args);
-            case "git_show":
-                return executeGitShow(tc.args);
-            case "git_blame":
-                return executeGitBlame(tc.args);
-            default:
-                return `Unknown tool: ${tc.toolName}`;
-        }
-    }
-    catch (err) {
-        return `Tool error: ${err.message}`;
-    }
-}
-/**
- * Validate that a file path resolves within the repository root.
- * Returns the resolved absolute path, or null if outside the boundary.
- */
-function validatePath(filePath) {
-    const resolved = resolve(filePath);
-    // Realpath both sides so a symlink planted inside the repo that points OUTSIDE
-    // can't pass a lexical containment check (isWithinRoot assumes resolved input
-    // and won't catch a link escape on its own). Matches fs-service's discipline.
-    // Reads are read-only, but a contained-looking symlink would still leak an
-    // out-of-repo file into arena context. Fall back to the lexical check when the
-    // target doesn't exist yet (a read of a missing file fails downstream anyway).
-    let realRoot;
-    try {
-        realRoot = realpathSync(REPO_ROOT);
-    }
-    catch {
-        realRoot = REPO_ROOT;
-    }
-    let realTarget;
-    try {
-        realTarget = realpathSync(resolved);
-    }
-    catch {
-        // Target doesn't exist yet. Compare REAL-vs-REAL by resolving the existing
-        // parent dir's realpath and rejoining the missing leaf — comparing realRoot
-        // (a real path) against a lexical `resolved` would false-reject valid files
-        // whenever REPO_ROOT (or any ancestor) is reached through a symlink.
-        let realParent;
-        try {
-            realParent = realpathSync(dirname(resolved));
-        }
-        catch {
-            // Parent missing too — no realpath available; fall back to lexical-vs-lexical
-            // so both operands share the same (unresolved) mode.
-            return isWithinRoot(resolve(REPO_ROOT), resolved) ? resolved : null;
-        }
-        const candidate = join(realParent, basename(resolved));
-        return isWithinRoot(realRoot, candidate) ? candidate : null;
-    }
-    return isWithinRoot(realRoot, realTarget) ? realTarget : null;
-}
-function executeReadFile(args) {
-    const filePath = args.path;
-    if (!validatePath(filePath))
-        return `Error: path outside repository: ${filePath}`;
-    if (!existsSync(filePath))
-        return `Error: file not found: ${filePath}`;
-    const raw = readFileSync(filePath, "utf-8");
-    const lines = raw.split("\n");
-    const offset = Math.max(0, (args.offset ?? 1) - 1);
-    // Guard `limit` before slicing: a negative limit makes lines.slice count
-    // "from the end" and silently drop the file's tail (reader thinks the file is
-    // shorter). A missing/NaN limit falls back to the default; a non-positive
-    // limit reads nothing.
-    const rawLimit = args.limit;
-    const limit = rawLimit === undefined || !Number.isFinite(rawLimit)
-        ? 200
-        : rawLimit > 0
-            ? Math.floor(rawLimit)
-            : 0;
-    const slice = lines.slice(offset, offset + limit);
-    const numbered = slice.map((l, i) => `${offset + i + 1}\t${l}`).join("\n");
-    return truncateResult(numbered);
-}
-function executeGrepCode(args) {
-    const pattern = args.pattern;
-    const glob = args.glob;
-    const grepArgs = ["-rn", "-E", "--"];
-    if (glob) {
-        grepArgs.splice(1, 0, `--include=${glob}`);
-    }
-    grepArgs.push(pattern, ".");
-    const result = execFileSafe("grep", grepArgs, 80);
-    return result || "No matches found.";
-}
-function executeListFiles(args) {
-    const dir = args.path || ".";
-    if (!validatePath(dir))
-        return `Error: path outside repository: ${dir}`;
-    try {
-        const entries = readdirSync(dir);
-        const lines = [];
-        for (const entry of entries.slice(0, 50)) {
-            const fullPath = join(dir, entry);
-            try {
-                const st = statSync(fullPath);
-                const type = st.isDirectory() ? "d" : "-";
-                const size = st.isDirectory() ? "" : ` ${st.size}`;
-                lines.push(`${type} ${entry}${size}`);
-            }
-            catch {
-                lines.push(`? ${entry}`);
-            }
-        }
-        return lines.join("\n") || `Empty directory: ${dir}`;
-    }
-    catch {
-        return `Directory not found: ${dir}`;
-    }
-}
-function executeGitShow(args) {
-    const ref = sanitizeGitRef(args.ref);
-    if (!ref)
-        return "Error: invalid git ref";
-    const result = execFileSafe("git", ["show", "--", ref], 200);
-    return truncateResult(result || `Could not resolve: ${ref}`);
-}
-function executeGitBlame(args) {
-    const filePath = args.path;
-    if (!validatePath(filePath))
-        return `Error: path outside repository: ${filePath}`;
-    const lines = args.lines;
-    const gitArgs = ["blame"];
-    if (lines && /^\d+,\d+$/.test(lines)) {
-        gitArgs.push(`-L`, lines);
-    }
-    gitArgs.push("--", filePath);
-    const result = execFileSafe("git", gitArgs, 50);
-    return result || `Could not blame: ${filePath}`;
-}
-/**
- * Sanitize a git ref string from LLM output.
- * Only allows safe git ref characters.
- */
-function sanitizeGitRef(ref) {
-    if (!ref || ref.length > 200)
-        return null;
-    // Only allow alphanumeric, /, -, _, ~, ^, ., :
-    const cleaned = ref.replace(/[^a-zA-Z0-9/_\-~^.:]/g, "");
-    // Block shell metacharacters and path traversal attempts
-    if (/\.\.\/|;\s|&&|\|\||`|\$\(/.test(cleaned))
-        return null;
-    return cleaned || null;
-}
-/**
- * Execute a command safely using execFileSync (no shell interpretation).
- * Optionally limits output to maxLines.
- */
-function execFileSafe(cmd, args, maxLines) {
-    try {
-        const raw = execFileSync(cmd, args, {
-            encoding: "utf-8",
-            maxBuffer: 512 * 1024,
-            timeout: 10_000,
-        }).trim();
-        if (maxLines) {
-            const lines = raw.split("\n");
-            if (lines.length > maxLines) {
-                return lines.slice(0, maxLines).join("\n") + `\n... (${lines.length - maxLines} more lines)`;
-            }
-        }
-        return raw;
-    }
-    catch {
-        return "";
-    }
-}
-function truncateResult(text) {
-    if (text.length <= MAX_TOOL_RESULT)
-        return text;
-    return text.slice(0, MAX_TOOL_RESULT) + "\n... (truncated)";
-}

package/dist/arena/context/within-root.d.ts

@@ -1,7 +0,0 @@
-/**
- * True when `target` is the root itself or a descendant of it. Uses the
- * platform separator (the old check hardcoded "/", which broke on Windows)
- * and avoids the sibling-prefix trap (/repo vs /repo-evil). Both inputs are
- * assumed already resolved to absolute paths.
- */
-export declare function isWithinRoot(root: string, target: string): boolean;

package/dist/arena/context/within-root.js

@@ -1,15 +0,0 @@
-import * as path from "node:path";
-/**
- * True when `target` is the root itself or a descendant of it. Uses the
- * platform separator (the old check hardcoded "/", which broke on Windows)
- * and avoids the sibling-prefix trap (/repo vs /repo-evil). Both inputs are
- * assumed already resolved to absolute paths.
- */
-export function isWithinRoot(root, target) {
-    if (target === root)
-        return true;
-    const rel = path.relative(root, target);
-    // Outside the root iff the relative path climbs out ("..") or is absolute
-    // (different drive on Windows).
-    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
-}

package/dist/arena/detect-mode.d.ts

@@ -1,20 +0,0 @@
-/**
- * Arena mode auto-detection — infer review/discussion/planning from topic text.
- *
- * Heuristic-based: uses keyword matching with weighted scoring.
- * Falls back to "review" (safest default) when confidence is low.
- */
-import type { ArenaMode } from "./types.js";
-/** Result of heuristic mode detection */
-export interface ArenaModeDetection {
-    mode: ArenaMode;
-    confidence: "high" | "low";
-    reason: string;
-}
-/**
- * Auto-detect arena mode from the topic string.
- *
- * Returns the detected mode, confidence level, and a human-readable reason.
- * When confidence is low, falls back to "review" (the safest default).
- */
-export declare function detectArenaMode(topic: string): ArenaModeDetection;