@cjhyy/code-shell-arena 0.8.0

package/dist/capability.js

@@ -0,0 +1,453 @@
+/**
+ * Built-in Arena tool — multi-model collaborative analysis.
+ *
+ * Launches an arena session where multiple LLM participants independently
+ * research a topic, cross-review each other's findings, and build consensus.
+ *
+ * The LLM config (baseUrl, apiKey) is injected at runtime by the Engine via
+ * setArenaLLMConfig(), following the same pattern as setAskUserFn() and
+ * setSubAgentConfig().
+ */
+import { SettingsManager, } from "@cjhyy/code-shell-core/extension";
+import { z } from "zod";
+import { Arena } from "./arena.js";
+import { MODEL_PRESETS, getMaxOutputTokens } from "./model-presets.js";
+import { createProgressRenderer } from "./render/terminal.js";
+import { formatArenaResultForSession } from "./render/session.js";
+export const arenaToolDef = {
+    name: "Arena",
+    description: "Launch a multi-model collaborative analysis session. " +
+        "Arena automatically detects the mode, analysis perspective (lens), and evidence sources from the user's natural language request. " +
+        "Supports: code review, PRD/document review, architecture planning, product discussions, open-ended debates, and more. " +
+        "Multiple LLM participants independently research the topic, cross-review findings, and produce structured consensus. " +
+        "Use model preset names (e.g. 'claude', 'gpt', 'gemini', 'deepseek') or full model paths.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            topic: {
+                type: "string",
+                description: "The topic or question to analyze in natural language. Arena auto-detects mode/lens/sources. " +
+                    "Examples: 'review my latest changes', 'review 这个 PRD 是否完整', '讨论 arena 的产品定位', " +
+                    "'规划通用化重构方案', 'discuss whether we should productize arena'",
+            },
+            mode: {
+                type: "string",
+                enum: ["review", "discussion", "planning"],
+                description: "Arena mode override. Usually auto-detected from topic. 'review' for structured review, 'discussion' for open analysis, 'planning' for roadmaps.",
+            },
+            participants: {
+                type: "array",
+                items: { type: "string" },
+                description: "Model preset names or full model paths for participants (min 2). " +
+                    "Preset names: " +
+                    Object.keys(MODEL_PRESETS).join(", ") +
+                    ". " +
+                    "Default: ['claude', 'gpt'] if omitted.",
+            },
+            concluder: {
+                type: "string",
+                description: "Which participant builds the final consensus (by name). Default: first participant.",
+            },
+        },
+        required: ["topic"],
+    },
+};
+// ─── Runtime LLM config — read from ctx, not module singletons ──
+/**
+ * Snapshot of last-known Arena config, kept for the protocol-level
+ * /arena-status query. The query is not tied to an in-flight tool
+ * invocation, so it can't read ctx; instead, ctx-bearing tool calls
+ * publish their config here for the status endpoint to read back.
+ *
+ * This is a read-only cache used purely for diagnostics — Arena's
+ * actual execution path always reads from the per-call ctx.
+ */
+let _lastSeenLLMConfig;
+let _lastSeenModelPool;
+export function getArenaStatus() {
+    const baseUrl = _lastSeenLLMConfig?.baseUrl;
+    const entries = _lastSeenModelPool?.list() ?? [];
+    const fromSettings = readSettingsParticipants();
+    // Mirror arenaTool's resolution: settings is authoritative when
+    // present; otherwise fall back to the pool-derived preview so users
+    // can still see *something* in /arena-status before they configure.
+    const defaults = fromSettings.length >= 2 ? fromSettings : resolveDefaultParticipantNames(entries);
+    const probed = defaults.map((name) => {
+        const r = probeParticipant(name, entries, _lastSeenLLMConfig);
+        return {
+            name,
+            model: r.modelPath,
+            source: r.source,
+            compatible: r.compatible,
+            ...(r.reason ? { reason: r.reason } : {}),
+        };
+    });
+    return {
+        endpoint: baseUrl,
+        defaultParticipants: probed,
+        poolSize: entries.length,
+    };
+}
+/**
+ * Resolve a preset name or model path into an ArenaParticipant,
+ * inheriting baseUrl/apiKey from the engine's LLM config.
+ */
+/**
+ * Arena uses a lower temperature than the default conversation model
+ * to produce more deterministic, evidence-grounded analysis.
+ */
+const ARENA_TEMPERATURE = 0.3;
+/**
+ * Resolution priority:
+ *   1. ModelPool key (the user's own configured models — uses each
+ *      entry's own baseUrl/apiKey, so e.g. a "claude" pool entry
+ *      pointing at OpenRouter still works while the active session
+ *      runs on DeepSeek direct).
+ *   2. MODEL_PRESETS — only if the active endpoint can accept the
+ *      preset's model namespace; otherwise we throw rather than
+ *      silently miswire credentials.
+ *   3. Raw model path against the active endpoint.
+ */
+function resolveParticipant(nameOrPath, llmConfig, pool) {
+    const fallbackBaseUrl = llmConfig.baseUrl;
+    const fallbackApiKey = llmConfig.apiKey;
+    // (1) ModelPool entry — preferred path
+    const poolEntry = pool?.get(nameOrPath);
+    if (poolEntry)
+        return participantFromPool(poolEntry, llmConfig);
+    // (2) Built-in preset
+    const preset = MODEL_PRESETS[nameOrPath];
+    if (preset) {
+        assertEndpointAcceptsModel(fallbackBaseUrl, preset.model, nameOrPath);
+        return {
+            name: nameOrPath,
+            llm: {
+                provider: preset.provider,
+                model: preset.model,
+                maxTokens: preset.maxOutputTokens,
+                baseUrl: fallbackBaseUrl,
+                apiKey: fallbackApiKey,
+            },
+            clientDefaults: { temperature: ARENA_TEMPERATURE },
+        };
+    }
+    // (3) Raw model path
+    assertEndpointAcceptsModel(fallbackBaseUrl, nameOrPath, nameOrPath);
+    return {
+        name: nameOrPath.split("/").pop() ?? nameOrPath,
+        llm: {
+            provider: "openai",
+            model: nameOrPath,
+            maxTokens: getMaxOutputTokens(nameOrPath),
+            baseUrl: fallbackBaseUrl,
+            apiKey: fallbackApiKey,
+        },
+        clientDefaults: { temperature: ARENA_TEMPERATURE },
+    };
+}
+function participantFromPool(entry, llmConfig) {
+    // Pool entries carry their own baseUrl/apiKey — never paper over
+    // them with the active session's credentials, which is exactly the
+    // bug that caused 401/400s when Arena ran on a DeepSeek-only
+    // session but the pool had OpenRouter-keyed entries.
+    return {
+        name: entry.key,
+        llm: {
+            provider: entry.provider,
+            model: entry.model,
+            maxTokens: entry.maxOutputTokens ?? getMaxOutputTokens(entry.model),
+            baseUrl: entry.baseUrl ?? llmConfig.baseUrl,
+            apiKey: entry.apiKey ?? llmConfig.apiKey,
+        },
+        clientDefaults: { temperature: ARENA_TEMPERATURE },
+    };
+}
+/**
+ * Non-throwing variant of resolveParticipant used by /arena status —
+ * we want to *display* what would happen, not bail.
+ */
+function probeParticipant(nameOrPath, poolEntries, llmConfig) {
+    const fromPool = poolEntries.find((e) => e.key === nameOrPath);
+    if (fromPool) {
+        return { modelPath: fromPool.model, source: "pool", compatible: true };
+    }
+    const preset = MODEL_PRESETS[nameOrPath];
+    const modelPath = preset?.model ?? nameOrPath;
+    const source = preset ? "preset" : "raw";
+    const baseUrl = llmConfig?.baseUrl;
+    const endpointVendor = baseUrl ? inferEndpointVendor(baseUrl) : null;
+    const modelVendor = modelPath.includes("/") ? modelPath.split("/")[0].toLowerCase() : null;
+    if (endpointVendor && modelVendor && modelVendor !== endpointVendor) {
+        return {
+            modelPath,
+            source,
+            compatible: false,
+            reason: `endpoint serves "${endpointVendor}" only`,
+        };
+    }
+    return { modelPath, source, compatible: true };
+}
+/**
+ * Quick, non-throwing predicate: would `nameOrPath` resolve to a
+ * working participant on the current endpoint? Used to decide whether
+ * the model's chosen `participants` list is honorable, or whether we
+ * should silently swap in the pool defaults (single-vendor endpoint
+ * with cross-vendor preset names is the common bad case).
+ */
+function participantWouldResolve(nameOrPath, poolEntries, baseUrl) {
+    return probeParticipant(nameOrPath, poolEntries, baseUrl ? { baseUrl } : undefined)
+        .compatible;
+}
+/**
+ * Read the user's configured arena participants from settings.json.
+ * Returns the list of string-form pool keys (the most common shape).
+ * Object-form entries (full name/model/provider tuples) are currently
+ * only honored by the CLI entry point and are skipped here.
+ *
+ * Returns an empty array if no settings file exists or the field is empty.
+ */
+function readSettingsParticipants(cwd) {
+    // A4: prefer Engine cwd when caller provides one; fall back to host
+    // process cwd for non-tool callers like getArenaStatus().
+    try {
+        const settings = new SettingsManager(cwd ?? process.cwd(), "full").get();
+        const raw = settings.capabilities?.arena?.participants ?? settings.arena?.participants ?? [];
+        const parsed = ArenaCapabilitySettingsSchema.shape.participants.safeParse(raw);
+        return parsed.success ? parsed.data : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Persist the capability-owned settings namespace; legacy `arena.*` remains read-only. */
+export function saveArenaSettingsByKeys(keys) {
+    const participants = ArenaCapabilitySettingsSchema.shape.participants.parse(keys);
+    new SettingsManager(process.cwd(), "full").saveUserSetting("capabilities.arena.participants", participants);
+}
+/** Package-owned schema for the optional capability settings namespace. */
+export const ArenaCapabilitySettingsSchema = z
+    .object({
+    participants: z.array(z.string().trim().min(1)).default([]),
+})
+    .passthrough();
+/**
+ * If the user didn't explicitly pass `participants`, default to every
+ * pool entry. With <2 entries, fall back to pre-existing behavior so
+ * we don't regress installs that haven't filled out the pool yet.
+ *
+ * NOTE: this is now only used by getArenaStatus() for the diagnostic
+ * /arena-status preview. The actual execution path in arenaTool() reads
+ * from settings (readSettingsParticipants) and refuses to silently
+ * grab the whole pool — we hit a bug where the pool included a
+ * gemini-3.1-pro entry that the active endpoint couldn't serve, and
+ * the user's curated settings.arena.participants list was bypassed.
+ */
+function resolveDefaultParticipantNames(poolEntries) {
+    if (poolEntries.length >= 2) {
+        return poolEntries.map((e) => e.key);
+    }
+    if (poolEntries.length === 1) {
+        // Single-model pool: use it twice — Arena requires ≥2. Same model
+        // running twice still gives a useful self-review pass.
+        const onlyKey = poolEntries[0].key;
+        return [onlyKey, onlyKey];
+    }
+    // Empty pool: legacy fallback. The endpoint check downstream will
+    // turn an obviously-wrong combo (e.g. claude preset on DeepSeek
+    // direct) into a fast, descriptive error.
+    return ["claude", "gpt"];
+}
+/**
+ * Arena presets use OpenRouter-style namespaced model paths
+ * (`anthropic/claude-opus-4.6`, `openai/gpt-5.4`, etc.). Those only
+ * resolve correctly on a multi-provider gateway like OpenRouter — a
+ * vendor's direct endpoint will reject any model name that isn't its
+ * own and we'd burn tens of seconds on retries before the user sees
+ * a useful error. Fail fast instead, naming the conflict.
+ */
+function assertEndpointAcceptsModel(baseUrl, modelPath, participantLabel) {
+    if (!baseUrl)
+        return;
+    const endpointVendor = inferEndpointVendor(baseUrl);
+    if (!endpointVendor)
+        return; // unknown gateway — assume permissive (e.g. OpenRouter, custom)
+    const modelVendor = modelPath.includes("/") ? modelPath.split("/")[0].toLowerCase() : null;
+    // Direct endpoint, no vendor prefix → caller must have used the
+    // exact model name the endpoint expects. Trust it.
+    if (modelVendor === null)
+        return;
+    if (modelVendor !== endpointVendor) {
+        throw new Error(`Arena participant "${participantLabel}" maps to model "${modelPath}", ` +
+            `but the active endpoint (${baseUrl}) only serves "${endpointVendor}" models. ` +
+            `Either switch to an aggregator endpoint (e.g. OpenRouter) or pick participants ` +
+            `whose models are native to this provider (e.g. "deepseek-v4-pro").`);
+    }
+}
+function inferEndpointVendor(baseUrl) {
+    const u = baseUrl.toLowerCase();
+    if (u.includes("api.deepseek.com"))
+        return "deepseek";
+    if (u.includes("api.openai.com"))
+        return "openai";
+    if (u.includes("api.anthropic.com"))
+        return "anthropic";
+    if (u.includes("generativelanguage.googleapis.com"))
+        return "google";
+    // OpenRouter, Together, custom proxies, etc. — assume multi-vendor.
+    return null;
+}
+function formatStartupBanner(participants, llmConfig, source) {
+    const endpoint = llmConfig.baseUrl ?? "(none)";
+    const lines = [];
+    lines.push(`Arena: endpoint=${endpoint}`);
+    const sourceTag = source === "explicit-coerced-to-settings"
+        ? "settings (auto-corrected from incompatible user picks)"
+        : source === "explicit"
+            ? "user-specified"
+            : "settings";
+    lines.push(`Arena: participants=${participants.join(", ")} (${sourceTag})`);
+    return lines.join("\n");
+}
+/** Strip ANSI escape codes from chalk-styled text */
+function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\x1b\[[0-9;]*m/g, "");
+}
+export async function arenaTool(args, ctx) {
+    const topic = args.topic;
+    if (!topic)
+        return "Error: topic is required";
+    const signal = args.__signal;
+    if (signal?.aborted)
+        return "Arena aborted before starting.";
+    if (!ctx?.llmConfig) {
+        return "Error: Arena LLM config not initialized. This is a bug — the engine should inject it via ToolContext.";
+    }
+    const llmConfig = ctx.llmConfig;
+    const pool = ctx.modelPool;
+    // Update the diagnostic snapshot used by /arena-status
+    _lastSeenLLMConfig = llmConfig;
+    _lastSeenModelPool = pool;
+    const explicitParticipants = args.participants;
+    const poolEntries = pool?.list() ?? [];
+    // Participant resolution order:
+    //   1. Explicit `participants` arg from the tool call — honored only
+    //      when every entry resolves on the current endpoint; otherwise
+    //      we coerce to settings (preferred) or pool defaults.
+    //   2. settings.arena.participants — the user's curated list. This
+    //      is the authoritative config; we never silently grab the whole
+    //      pool, because the pool can contain models that the active
+    //      endpoint can't serve (e.g. gemini-3.1-pro on Google direct).
+    //   3. No settings configured → return an actionable error pointing
+    //      the user at where to configure it. Previously we silently
+    //      defaulted to the entire pool, which caused 404/400 storms
+    //      when pool entries didn't match the active endpoint.
+    let participantNames;
+    let participantSource;
+    if (explicitParticipants && explicitParticipants.length > 0) {
+        const allCompatible = explicitParticipants.every((name) => participantWouldResolve(name, poolEntries, llmConfig.baseUrl));
+        if (allCompatible) {
+            participantNames = explicitParticipants;
+            participantSource = "explicit";
+        }
+        else {
+            const fromSettings = readSettingsParticipants(ctx?.cwd);
+            if (fromSettings.length >= 2) {
+                participantNames = fromSettings;
+                participantSource = "explicit-coerced-to-settings";
+            }
+            else {
+                return ("Error: Arena participants from the call are incompatible with the active endpoint, " +
+                    `and no fallback is configured. Set "capabilities.arena.participants" (≥2 model names) in ` +
+                    "~/.code-shell/settings.json, or pass a compatible `participants` array.");
+            }
+        }
+    }
+    else {
+        const fromSettings = readSettingsParticipants(ctx?.cwd);
+        if (fromSettings.length >= 2) {
+            participantNames = fromSettings;
+            participantSource = "settings";
+        }
+        else {
+            return ("Error: Arena requires at least 2 participants but none are configured. " +
+                `Add a "capabilities": { "arena": { "participants": ["model-a", "model-b", ...] } } block to ` +
+                "~/.code-shell/settings.json (each entry is a model pool key, e.g. " +
+                '"deepseek-v4-pro", "openrouter-claude-opus-4.7-fast"), or pass an explicit ' +
+                "`participants` array in the tool call.");
+        }
+    }
+    if (participantNames.length < 2) {
+        return "Error: Arena requires at least 2 participants. Provide 2 or more model names.";
+    }
+    const mode = args.mode;
+    const concluder = args.concluder;
+    // Collect progress for inclusion in the final tool result.
+    // Strip ANSI codes from progress since tool results are plain text/markdown.
+    const progressLog = [];
+    const progressRenderer = createProgressRenderer((text) => {
+        progressLog.push(stripAnsi(text));
+    });
+    // Surface the resolved configuration up front so the user can see
+    // exactly which models will be polled and against which endpoint —
+    // previously this was invisible until something blew up.
+    const configLine = formatStartupBanner(participantNames, llmConfig, participantSource);
+    progressLog.push(configLine);
+    try {
+        // resolveParticipant() may throw on endpoint/model mismatch — keep
+        // it inside the try so the error returns as a tool-result string
+        // rather than crashing the engine.
+        const participants = participantNames.map((n) => resolveParticipant(n, llmConfig, pool));
+        const arena = new Arena({
+            participants,
+            mode,
+            concluder,
+            enableContextTools: true,
+            onProgress: progressRenderer,
+            signal,
+        });
+        const result = await arena.run(topic);
+        ctx.recordBilledUsage?.(result.usage);
+        // Use session renderer (markdown, no ANSI) for tool results.
+        // Terminal renderer (chalk) is only for direct stdout printing.
+        const formattedResult = formatArenaResultForSession(result);
+        // Prepend a condensed progress summary so the LLM can see what was done
+        const progressSummary = progressLog.length > 0 ? "── Arena Progress ──\n" + progressLog.join("\n") + "\n\n" : "";
+        // Cap total output to prevent context overflow
+        const MAX_TOOL_OUTPUT = 30_000;
+        const full = progressSummary + formattedResult;
+        if (full.length > MAX_TOOL_OUTPUT) {
+            return (full.slice(0, MAX_TOOL_OUTPUT) + "\n\n... (truncated, total " + full.length + " chars)");
+        }
+        return full;
+    }
+    catch (err) {
+        if (signal?.aborted)
+            return "Arena aborted.";
+        // err may be a non-Error (string/null); `(err as Error).message` would be
+        // undefined → "Arena error: undefined", masking the real cause.
+        return `Arena error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+/** Create the explicit Arena product capability. Core does not import this package. */
+export function createArenaCapability() {
+    return {
+        id: "arena",
+        tools: [
+            {
+                definition: {
+                    ...arenaToolDef,
+                    source: "builtin",
+                    permissionDefault: "ask",
+                    isReadOnly: true,
+                    isConcurrencySafe: false,
+                    timeoutMs: 1_800_000,
+                },
+                execute: arenaTool,
+            },
+        ],
+        queries: {
+            arena_status: () => getArenaStatus(),
+        },
+    };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * 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 "@cjhyy/code-shell-core/extension";
+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;