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

package/dist/tool-system/builtin/arena.js

@@ -0,0 +1,416 @@
+/**
+ * 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 { Arena, MODEL_PRESETS, getMaxOutputTokens } from "../../arena/index.js";
+import { createProgressRenderer } from "../../arena/render/terminal.js";
+import { formatArenaResultForSession } from "../../arena/render/session.js";
+import { SettingsManager } from "../../settings/manager.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,
+                temperature: ARENA_TEMPERATURE,
+                enableStreaming: false,
+            },
+        };
+    }
+    // (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,
+            temperature: ARENA_TEMPERATURE,
+            enableStreaming: false,
+        },
+    };
+}
+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,
+            temperature: ARENA_TEMPERATURE,
+            enableStreaming: false,
+        },
+    };
+}
+/**
+ * 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()).get();
+        const raw = settings.arena?.participants ?? [];
+        return raw.filter((p) => typeof p === "string");
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 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 "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 an "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);
+        // 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.";
+        return `Arena error: ${err.message}`;
+    }
+}

package/dist/tool-system/builtin/ask-user.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Built-in AskUserQuestion tool — ask the user a question during execution.
+ *
+ * Two modes:
+ *   - Plain text (no `options`): user types a free-text answer.
+ *   - Multiple choice (`options` provided): user picks from a list. An
+ *     implicit "Other..." entry is appended by the UI for free text.
+ *
+ * The actual prompt-the-user implementation is provided per-Engine via
+ * ToolContext.askUser. Headless mode (no UI wired up) leaves askUser
+ * undefined and the tool reports back asking the LLM to assume.
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export type { AskUserFn, AskUserOptions, AskUserChoice } from "../context.js";
+export declare const askUserToolDef: ToolDefinition;
+/**
+ * Tool execution. Forwards to ToolContext.askUser.
+ */
+export declare function askUserTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tool-system/builtin/ask-user.js

@@ -0,0 +1,99 @@
+/**
+ * Built-in AskUserQuestion tool — ask the user a question during execution.
+ *
+ * Two modes:
+ *   - Plain text (no `options`): user types a free-text answer.
+ *   - Multiple choice (`options` provided): user picks from a list. An
+ *     implicit "Other..." entry is appended by the UI for free text.
+ *
+ * The actual prompt-the-user implementation is provided per-Engine via
+ * ToolContext.askUser. Headless mode (no UI wired up) leaves askUser
+ * undefined and the tool reports back asking the LLM to assume.
+ */
+export const askUserToolDef = {
+    name: "AskUserQuestion",
+    description: "Ask the user a question and wait for their response. " +
+        "Use this when you need clarification, confirmation, or additional input from the user. " +
+        "Pass `options` to present a multiple-choice list (recommended when the answer is one of a small known set — much better UX than free text). " +
+        "Each option needs a short `label` (the choice the user sees) and a `description` (what it means). " +
+        "Lead with the recommended option and append a recommendation marker to its label in the same language as the question (e.g. '(Recommended)' for an English question, '(推荐)' for a Chinese question). " +
+        "Set `multiSelect: true` when more than one choice can apply. " +
+        "ALWAYS write the `question`, every option `label`, every option `description`, and the `header` in the SAME LANGUAGE the user has been writing in. If the user wrote to you in Chinese, write all of these fields in Chinese; if Japanese, in Japanese; etc. The framework's UI chrome (separator hints, the implicit 'Other...' entry) is fixed — only your fields need to match the user's language. " +
+        "In headless mode this tool will return an error.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            question: {
+                type: "string",
+                description: "The question to ask the user — in the user's language",
+            },
+            header: {
+                type: "string",
+                description: "Optional short label (≤12 chars) shown as a chip above the question (e.g. 'Language', 'Approach', '语言', '方案'). Use the user's language.",
+            },
+            options: {
+                type: "array",
+                description: "Optional 2-4 multiple-choice options. Omit for free-text input. An implicit 'Other...' entry is appended automatically by the framework.",
+                items: {
+                    type: "object",
+                    properties: {
+                        label: {
+                            type: "string",
+                            description: "Short display text (1-5 words) — in the user's language",
+                        },
+                        description: {
+                            type: "string",
+                            description: "What this option means or implies — shown next to the label, in the user's language",
+                        },
+                    },
+                    required: ["label", "description"],
+                },
+            },
+            multiSelect: {
+                type: "boolean",
+                description: "If true, the user can select multiple options. Defaults to false (single choice).",
+            },
+        },
+        required: ["question"],
+    },
+};
+/**
+ * Tool execution. Forwards to ToolContext.askUser.
+ */
+export async function askUserTool(args, ctx) {
+    const question = args.question;
+    if (!question)
+        return "Error: question is required";
+    if (!ctx?.askUser) {
+        return "Error: AskUserQuestion is not available in headless mode. Make a reasonable assumption and proceed.";
+    }
+    const opts = parseOptions(args);
+    try {
+        const answer = await ctx.askUser(question, opts);
+        return answer || "(user provided empty response)";
+    }
+    catch (err) {
+        return `Error asking user: ${err.message}`;
+    }
+}
+function parseOptions(args) {
+    const rawOptions = args.options;
+    const header = typeof args.header === "string" ? args.header : undefined;
+    const multiSelect = args.multiSelect === true;
+    if (!Array.isArray(rawOptions) || rawOptions.length === 0) {
+        if (header === undefined && !multiSelect)
+            return undefined;
+        return { header, multiSelect, options: undefined };
+    }
+    const options = rawOptions
+        .filter((o) => {
+        return (typeof o === "object" &&
+            o !== null &&
+            typeof o.label === "string" &&
+            typeof o.description === "string");
+    })
+        .map((o) => ({ label: o.label, description: o.description }));
+    if (options.length === 0)
+        return { header, multiSelect, options: undefined };
+    return { header, multiSelect, options };
+}

package/dist/tool-system/builtin/bash.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Built-in Bash shell command execution tool.
+ *
+ * Spawns commands under an optional OS-level sandbox (Seatbelt on macOS,
+ * bubblewrap on Linux). The sandbox is selected by the Engine and handed
+ * down via ToolContext.sandbox. Without a sandbox we fall back to the
+ * historical behavior — plain shell spawn in the user's environment.
+ *
+ * The actual lifecycle (spawn, IO drain, byte cap, abort cascade, timeout
+ * cascade, listener cleanup) lives in {@link safeSpawnShell}. This file
+ * keeps only Bash-specific concerns:
+ *
+ *   - The env allowlist + deny regex (a Bash threat-model thing — REPL /
+ *     PowerShell don't have free-form shell injection from the LLM).
+ *   - The final user-facing output formatting (STDERR: prefix, Exit code,
+ *     Killed by signal, the truncation message, sandbox denial hints).
+ */
+import type { ToolContext } from "../context.js";
+import type { ToolDefinition } from "../../types.js";
+export declare const bashToolDef: ToolDefinition;
+export declare function bashTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;