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

package/dist/tool-system/builtin/web-search.js

@@ -0,0 +1,174 @@
+/**
+ * Built-in WebSearch tool — search the web via Serper, Tavily, or SearXNG.
+ *
+ * Provider selection / credentials are read in this precedence:
+ *   1. settings.search.{provider, apiKey, baseUrl} from ~/.code-shell/settings.json
+ *      (set via the desktop "连接" UI or hand-edited)
+ *   2. env vars SERPER_API_KEY / TAVILY_API_KEY / SEARXNG_URL (legacy / CI override)
+ * Settings take precedence so the desktop UI's "保存连接" + "测试连接" is the
+ * single source of truth for end users.
+ */
+import { SettingsManager } from "../../settings/manager.js";
+/**
+ * Resolve the active search config. Returns `source` so callers can show
+ * the user where the value came from when debugging.
+ */
+export function resolveSearchConfig(cwd = process.cwd()) {
+    let settingsProvider;
+    let settingsKey;
+    let settingsBaseUrl;
+    try {
+        const merged = new SettingsManager(cwd).get();
+        const search = merged.search ?? {};
+        const p = search.provider;
+        if (p === "serper" || p === "tavily" || p === "searxng")
+            settingsProvider = p;
+        // Per-provider bag takes precedence over the legacy single-slot fields
+        // when the active provider matches the bag entry.
+        const bag = search.providers && typeof search.providers === "object"
+            ? search.providers
+            : undefined;
+        const bagEntry = settingsProvider && bag ? bag[settingsProvider] : undefined;
+        if (bagEntry && typeof bagEntry.apiKey === "string" && bagEntry.apiKey) {
+            settingsKey = bagEntry.apiKey;
+        }
+        else if (typeof search.apiKey === "string" && search.apiKey) {
+            settingsKey = search.apiKey;
+        }
+        if (bagEntry && typeof bagEntry.baseUrl === "string" && bagEntry.baseUrl) {
+            settingsBaseUrl = bagEntry.baseUrl;
+        }
+        else if (typeof search.baseUrl === "string" && search.baseUrl) {
+            settingsBaseUrl = search.baseUrl;
+        }
+    }
+    catch {
+        /* settings unreadable — fall through to env */
+    }
+    const envSerper = process.env.SERPER_API_KEY;
+    const envTavily = process.env.TAVILY_API_KEY;
+    const envSearxng = process.env.SEARXNG_URL;
+    if (settingsProvider) {
+        if (settingsProvider === "searxng") {
+            const base = settingsBaseUrl ?? envSearxng;
+            return base
+                ? { provider: "searxng", baseUrl: base, source: settingsBaseUrl ? "settings" : "env" }
+                : { provider: "searxng", source: "none" };
+        }
+        const key = settingsKey ?? (settingsProvider === "serper" ? envSerper : envTavily);
+        return key
+            ? { provider: settingsProvider, apiKey: key, source: settingsKey ? "settings" : "env" }
+            : { provider: settingsProvider, source: "none" };
+    }
+    if (envSerper)
+        return { provider: "serper", apiKey: envSerper, source: "env" };
+    if (envTavily)
+        return { provider: "tavily", apiKey: envTavily, source: "env" };
+    if (envSearxng)
+        return { provider: "searxng", baseUrl: envSearxng, source: "env" };
+    return { provider: "serper", source: "none" };
+}
+export const webSearchToolDef = {
+    name: "WebSearch",
+    description: "Search the web for information. Returns a list of search results with titles, URLs, and snippets. " +
+        "Use this when you need up-to-date information or facts not in your training data.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: { type: "string", description: "The search query" },
+            num_results: {
+                type: "number",
+                description: "Number of results to return (default: 10, max: 20)",
+            },
+        },
+        required: ["query"],
+    },
+};
+export async function webSearchTool(args) {
+    const query = args.query;
+    if (!query)
+        return "Error: query is required";
+    const numResults = Math.min(args.num_results || 10, 20);
+    const config = resolveSearchConfig();
+    if (config.source === "none") {
+        return "Error: No search provider configured. Open desktop 设置 → 连接 to add credentials, or set SERPER_API_KEY / TAVILY_API_KEY / SEARXNG_URL.";
+    }
+    try {
+        let results;
+        if (config.provider === "serper" && config.apiKey) {
+            results = await searchSerper(query, numResults, config.apiKey);
+        }
+        else if (config.provider === "tavily" && config.apiKey) {
+            results = await searchTavily(query, numResults, config.apiKey);
+        }
+        else if (config.provider === "searxng" && config.baseUrl) {
+            results = await searchSearXNG(query, numResults, config.baseUrl);
+        }
+        else {
+            return `Error: provider "${config.provider}" missing ${config.provider === "searxng" ? "base URL" : "API key"}`;
+        }
+        if (results.length === 0)
+            return "No results found.";
+        return results
+            .map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.snippet}`)
+            .join("\n\n");
+    }
+    catch (err) {
+        return `Search error: ${err.message}`;
+    }
+}
+async function searchSerper(query, num, apiKey) {
+    const res = await fetch("https://google.serper.dev/search", {
+        method: "POST",
+        headers: {
+            "X-API-KEY": apiKey,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ q: query, num }),
+    });
+    if (!res.ok)
+        throw new Error(`Serper API error: ${res.status} ${res.statusText}`);
+    const data = (await res.json());
+    return (data.organic ?? []).map((item) => ({
+        title: item.title ?? "",
+        url: item.link ?? "",
+        snippet: item.snippet ?? "",
+    }));
+}
+async function searchTavily(query, num, apiKey) {
+    const res = await fetch("https://api.tavily.com/search", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            api_key: apiKey,
+            query,
+            max_results: num,
+            include_answer: false,
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`Tavily API error: ${res.status} ${res.statusText}`);
+    const data = (await res.json());
+    return (data.results ?? []).map((item) => ({
+        title: item.title ?? "",
+        url: item.url ?? "",
+        snippet: item.content ?? "",
+    }));
+}
+async function searchSearXNG(query, num, baseUrl) {
+    const url = new URL("/search", baseUrl);
+    url.searchParams.set("q", query);
+    url.searchParams.set("format", "json");
+    url.searchParams.set("pageno", "1");
+    const res = await fetch(url.toString(), {
+        headers: { Accept: "application/json" },
+    });
+    if (!res.ok)
+        throw new Error(`SearXNG error: ${res.status} ${res.statusText}`);
+    const data = (await res.json());
+    return (data.results ?? []).slice(0, num).map((item) => ({
+        title: item.title ?? "",
+        url: item.url ?? "",
+        snippet: item.content ?? "",
+    }));
+}

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

@@ -0,0 +1,10 @@
+/**
+ * EnterWorktree / ExitWorktree tools — create and manage isolated git worktrees.
+ */
+import type { ToolDefinition } from "../../types.js";
+import { type WorktreeSession } from "../../git/worktree.js";
+export declare function getActiveWorktree(): WorktreeSession | undefined;
+export declare const enterWorktreeToolDef: ToolDefinition;
+export declare function enterWorktreeTool(args: Record<string, unknown>): Promise<string>;
+export declare const exitWorktreeToolDef: ToolDefinition;
+export declare function exitWorktreeTool(args: Record<string, unknown>): Promise<string>;

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

@@ -0,0 +1,95 @@
+/**
+ * EnterWorktree / ExitWorktree tools — create and manage isolated git worktrees.
+ */
+import { createWorktree, removeWorktree, validateWorktreeSlug, } from "../../git/worktree.js";
+// Global worktree state
+let _activeWorktree;
+export function getActiveWorktree() {
+    return _activeWorktree;
+}
+export const enterWorktreeToolDef = {
+    name: "EnterWorktree",
+    description: "Create an isolated git worktree for safe code modifications. " +
+        "The worktree is a separate copy of the repository on a new branch. " +
+        "Changes made in the worktree do not affect the main working directory. " +
+        "Use this when you need to make experimental changes or work in isolation.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            slug: {
+                type: "string",
+                description: "A short identifier for the worktree (alphanumeric, dots, dashes only, max 64 chars). " +
+                    "Example: 'fix-auth-bug', 'refactor-api'",
+            },
+        },
+        required: ["slug"],
+    },
+};
+export async function enterWorktreeTool(args) {
+    const slug = args.slug;
+    if (!slug)
+        return "Error: slug is required";
+    if (_activeWorktree) {
+        return `Error: Already in a worktree at ${_activeWorktree.worktreePath}. Exit it first with ExitWorktree.`;
+    }
+    try {
+        validateWorktreeSlug(slug);
+    }
+    catch (err) {
+        return `Error: ${err.message}`;
+    }
+    try {
+        // Use a placeholder session ID (the agent should set this properly)
+        const sessionId = args.__sessionId ?? `wt-${Date.now()}`;
+        const cwd = args.__cwd ?? process.cwd();
+        _activeWorktree = createWorktree(cwd, slug, sessionId);
+        return (`Worktree created:\n` +
+            `  Path:   ${_activeWorktree.worktreePath}\n` +
+            `  Branch: ${_activeWorktree.worktreeBranch}\n` +
+            `  From:   ${_activeWorktree.originalBranch ?? "HEAD"}\n\n` +
+            `You are now working in an isolated copy. Changes here won't affect the main repo.`);
+    }
+    catch (err) {
+        return `Error creating worktree: ${err.message}`;
+    }
+}
+export const exitWorktreeToolDef = {
+    name: "ExitWorktree",
+    description: "Exit the current worktree and return to the main working directory. " +
+        "Choose whether to keep or discard the changes made in the worktree.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: ["keep", "discard"],
+                description: "'keep' preserves the worktree branch for later merging. " +
+                    "'discard' removes the worktree and its branch entirely.",
+            },
+        },
+        required: ["action"],
+    },
+};
+export async function exitWorktreeTool(args) {
+    if (!_activeWorktree) {
+        return "Not currently in a worktree.";
+    }
+    const action = args.action;
+    const session = _activeWorktree;
+    _activeWorktree = undefined;
+    try {
+        if (action === "discard") {
+            removeWorktree(session.worktreePath, true);
+            return `Worktree removed and branch ${session.worktreeBranch} deleted. Back to ${session.originalCwd}.`;
+        }
+        else {
+            removeWorktree(session.worktreePath, false);
+            return (`Worktree removed. Branch ${session.worktreeBranch} preserved.\n` +
+                `To merge: git merge ${session.worktreeBranch}\n` +
+                `Back to ${session.originalCwd}.`);
+        }
+    }
+    catch (err) {
+        return `Error exiting worktree: ${err.message}`;
+    }
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Built-in Write file tool.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const writeToolDef: ToolDefinition;
+export declare function writeTool(args: Record<string, unknown>): Promise<string>;

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

@@ -0,0 +1,36 @@
+/**
+ * Built-in Write file tool.
+ */
+import { writeFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { fileCache } from "./file-cache.js";
+export const writeToolDef = {
+    name: "Write",
+    description: "Write content to a file. Creates the file if it doesn't exist, " +
+        "overwrites if it does. Creates parent directories as needed.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            file_path: { type: "string", description: "Absolute path to the file to write" },
+            content: { type: "string", description: "The content to write to the file" },
+        },
+        required: ["file_path", "content"],
+    },
+};
+export async function writeTool(args) {
+    const filePath = args.file_path;
+    const content = args.content;
+    if (!filePath)
+        return "Error: file_path is required";
+    if (content === undefined)
+        return "Error: content is required";
+    try {
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, content, "utf-8");
+        fileCache.invalidate(filePath);
+        return `Successfully wrote to ${filePath}`;
+    }
+    catch (err) {
+        return `Error writing file: ${err.message}`;
+    }
+}

package/dist/tool-system/context.d.ts

@@ -0,0 +1,165 @@
+/**
+ * ToolContext — runtime services injected into every tool execution.
+ *
+ * Replaces the legacy module-level singletons (`setAskUserFn`,
+ * `setArenaLLMConfig`, `setSubAgentConfig`, `setToolSearchRegistry`).
+ *
+ * Each Engine instance builds its own ToolContext when run() starts and
+ * passes it through ToolExecutor → ToolRegistry → executor function.
+ * That makes concurrent Engine instances safe: tools never see another
+ * Engine's askUser handler or LLM credentials.
+ *
+ * Tools that don't need any context (Read/Write/Bash/...) just ignore
+ * the second argument; the type is purely additive.
+ */
+import type { LLMConfig, StreamCallback } from "../types.js";
+import type { ModelPool } from "../llm/model-pool.js";
+import type { ToolRegistry } from "./registry.js";
+import type { AgentPresetName } from "../preset/index.js";
+import type { SandboxBackend } from "./sandbox/index.js";
+import type { HookRegistry } from "../hooks/registry.js";
+import type { Engine } from "../engine/engine.js";
+/** One choice in a multiple-choice AskUserQuestion. */
+export interface AskUserChoice {
+    label: string;
+    description: string;
+}
+/**
+ * Optional rendering hints / multiple-choice options carried alongside the
+ * question. Implementations may ignore unknown fields — they're additive.
+ */
+export interface AskUserOptions {
+    /** Short chip-style label (≤12 chars) shown above the question. */
+    header?: string;
+    /** Multiple-choice options. When omitted, the UI falls back to free-text. */
+    options?: AskUserChoice[];
+    /** Allow the user to pick more than one option. Defaults to false. */
+    multiSelect?: boolean;
+}
+/**
+ * Function the host UI / server uses to ask the user a question.
+ *
+ * Second argument is optional for backwards compatibility — callers that
+ * only need free text can omit it; backends that don't support options
+ * should ignore the field and prompt for free text.
+ *
+ * Return value:
+ *   - Free-text mode: the user's typed answer (or "(user declined to answer)").
+ *   - Multiple-choice mode: the selected label, or comma-separated labels for
+ *     multiSelect, or "Other: <typed>" when the user picks the implicit
+ *     Other... entry.
+ */
+export type AskUserFn = (question: string, opts?: AskUserOptions) => Promise<string>;
+/** Spawn a sub-agent. Returns the produced text or throws. */
+export interface SubAgentSpawnRequest {
+    agentId: string;
+    description: string;
+    prompt: string;
+    maxTurns: number;
+    signal: AbortSignal;
+    /**
+     * Per-call override for where the spawned child Engine's stream events go.
+     * Defaults to `spawner.parentStream` (the parent UI). Background sub-agents
+     * pass a transcriptSink here so per-event detail is captured in the agent's
+     * transcript instead of leaking into the main feed; the main feed still
+     * gets `agent_start` / `agent_end` markers via `spawner.parentStream`.
+     */
+    streamOverride?: StreamCallback;
+}
+export interface SubAgentSpawner {
+    /** Run a sub-agent synchronously and return its text output. */
+    spawn(req: SubAgentSpawnRequest): Promise<string>;
+    /** Stream callback to forward sub-agent events back to the parent UI. */
+    parentStream?: StreamCallback;
+    /** Static config used to describe what the spawned engine looks like. */
+    describe(): {
+        cwd: string;
+        preset?: AgentPresetName;
+        permissionMode: string;
+    };
+}
+/**
+ * The full context object handed to every tool invocation.
+ *
+ * Optional fields are filled in by Engine.run(); some headless paths may
+ * leave them undefined (e.g. running without UI → no askUser).
+ */
+export interface ToolContext {
+    /** Active working directory for this Engine. */
+    cwd: string;
+    /** LLM credentials/endpoint for tools that need to make their own calls. */
+    llmConfig: LLMConfig;
+    /** Active model pool (Arena reads this to pick participants). */
+    modelPool?: ModelPool;
+    /** Tool registry (ToolSearch reads this to enumerate available tools). */
+    toolRegistry: ToolRegistry;
+    /** UI-backed AskUserQuestion handler. Undefined → headless mode. */
+    askUser?: AskUserFn;
+    /** Sub-agent spawner (Agent tool). Undefined → Agent tool unavailable. */
+    subAgentSpawner?: SubAgentSpawner;
+    /**
+     * True when this Engine is itself a sub-agent. Set from EngineConfig.
+     * The Agent tool refuses to spawn when this is true — runtime check
+     * layered on top of the tool-list strip in Engine.spawn so a registry
+     * regression can't leak nested spawns.
+     */
+    isSubAgent?: boolean;
+    /**
+     * Active sandbox backend for the Bash tool. Undefined falls back to "off"
+     * (plain spawn). Headless runs default to an OS-level sandbox; the REPL
+     * defaults to off because a human is in the loop to approve commands.
+     */
+    sandbox?: SandboxBackend;
+    /** Optional cancellation signal for the whole turn. */
+    signal?: AbortSignal;
+    /**
+     * Engine-owned HookRegistry. Tools that emit lifecycle hooks
+     * (notification, file_changed for non-Write/Edit paths, custom
+     * tool-defined events) use this. Undefined for legacy callers /
+     * standalone tests; tools must tolerate absence.
+     */
+    hooks?: HookRegistry;
+    /**
+     * Per-turn stream sink (engine.run's `onStream`). Tools that need to
+     * push UI events independently of their return value use this — e.g.
+     * TodoWrite emits a `task_update` so the desktop pinned panel and
+     * tui task list refresh immediately rather than waiting for the LLM
+     * to surface the snapshot in the next turn. Undefined in
+     * headless/test mode; tools must tolerate absence.
+     */
+    streamCallback?: StreamCallback;
+    /** Whether the owning Engine is currently in plan mode. Replaces the
+     *  removed module-level `isInPlanMode()` singleton. */
+    planMode: boolean;
+    /** The Engine that built this context. Lets tools call back into the engine
+     *  (e.g. ctx.engine.setPlanMode(true/false)) without a module-level singleton. */
+    engine: Engine;
+    /**
+     * sessionId of the Engine.run() turn this context was built for. Tools
+     * that emit session-scoped side effects (today: background-agent
+     * completion notifications) attribute the event by this. Undefined for
+     * ad-hoc contexts built outside Engine.run() — e.g. memory.auto_dream's
+     * narrow context, or standalone tool tests. (B2 — Gate 1, standard §S3.)
+     */
+    sessionId?: string;
+    /**
+     * Skill names the user has hidden from the LLM (full namespaced names
+     * for plugin skills, e.g. "docs:pdf"). The skill builtin tool uses
+     * this to refuse direct invocation of a disabled skill so the UI
+     * toggle is honored at dispatch time, not just in the prompt listing.
+     * Populated from `settings.disabledSkills` by Engine.run().
+     */
+    disabledSkills?: string[];
+}
+/**
+ * Per-Engine container that produces a fresh ToolContext on demand.
+ * Engine creates one of these in run() and passes it to ToolExecutor.
+ */
+export declare class ServiceContainer {
+    private readonly base;
+    constructor(base: ToolContext);
+    /** Snapshot of the context at this moment. */
+    get(): ToolContext;
+    /** Create a derived context with overridden fields (e.g. per-call signal). */
+    withSignal(signal: AbortSignal): ToolContext;
+}

package/dist/tool-system/context.js

@@ -0,0 +1,18 @@
+/**
+ * Per-Engine container that produces a fresh ToolContext on demand.
+ * Engine creates one of these in run() and passes it to ToolExecutor.
+ */
+export class ServiceContainer {
+    base;
+    constructor(base) {
+        this.base = base;
+    }
+    /** Snapshot of the context at this moment. */
+    get() {
+        return this.base;
+    }
+    /** Create a derived context with overridden fields (e.g. per-call signal). */
+    withSignal(signal) {
+        return { ...this.base, signal };
+    }
+}

package/dist/tool-system/executor.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tool executor — orchestrates permission checks, hooks, and execution.
+ */
+import type { ToolCall, ToolResult, Message } from "../types.js";
+import type { HookRegistry } from "../hooks/registry.js";
+import { ToolRegistry } from "./registry.js";
+import { PermissionClassifier } from "./permission.js";
+import { logger as rootLogger } from "../logging/logger.js";
+import type { ToolContext } from "./context.js";
+import type { InvestigationGuard } from "./investigation-guard.js";
+import type { TaskGuard } from "./task-guard.js";
+type Logger = typeof rootLogger;
+export declare class ToolExecutor {
+    private readonly registry;
+    private readonly permission;
+    private readonly hooks;
+    private signal?;
+    /** Per-Engine ToolContext injected for every tool call. */
+    private toolCtx?;
+    /**
+     * Turn-scoped logger set by TurnLoop at the top of each iteration.
+     * Falls back to the root logger so executor calls outside the turn loop
+     * (tests, ad-hoc tool runs) still write log lines, just without turn tags.
+     */
+    private log;
+    private guard?;
+    private taskGuard?;
+    constructor(registry: ToolRegistry, permission: PermissionClassifier, hooks: HookRegistry);
+    setInvestigationGuard(guard: InvestigationGuard | undefined): void;
+    getInvestigationGuard(): InvestigationGuard | undefined;
+    setTaskGuard(guard: TaskGuard | undefined): void;
+    getTaskGuard(): TaskGuard | undefined;
+    /** Set the abort signal for cascading cancellation. */
+    setSignal(signal?: AbortSignal): void;
+    /** Set the per-Engine ToolContext (askUser, llmConfig, modelPool, etc.). */
+    setContext(ctx: ToolContext | undefined): void;
+    /** Inject a turn-scoped logger so tool-execution lines carry turn/turnId. */
+    setLogger(log: Logger): void;
+    /** Check if a tool is safe for concurrent execution (read-only). */
+    isConcurrencySafe(toolName: string): boolean;
+    executeSingle(callIn: ToolCall): Promise<ToolResult>;
+    private isReadOnlyBashCommand;
+    executeAll(calls: ToolCall[]): Promise<ToolResult[]>;
+    /**
+     * Convert tool results into Message entries for the transcript.
+     */
+    resultsToMessages(toolCalls: ToolCall[], results: ToolResult[]): Message[];
+}
+export {};