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

package/dist/tool-system/builtin/web-search.d.ts

@@ -21,5 +21,8 @@ export interface ResolvedSearchConfig {
  * the user where the value came from when debugging.
  */
 export declare function resolveSearchConfig(cwd?: string): ResolvedSearchConfig;
+export declare function isWebSearchAvailable(cwd?: string, nowMs?: number): boolean;
 export declare const webSearchToolDef: ToolDefinition;
-export declare function webSearchTool(args: Record<string, unknown>): Promise<string>;
+export declare function webSearchTool(args: Record<string, unknown>, ctx?: {
+    cwd?: string;
+}): Promise<string>;

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

@@ -18,7 +18,11 @@ export function resolveSearchConfig(cwd = process.cwd()) {
     let settingsKey;
     let settingsBaseUrl;
     try {
-        const merged = new SettingsManager(cwd).get();
+        // scope "full" so the USER-level ~/.code-shell/settings.json is read, not
+        // just ${cwd}/.code-shell — the search key is typically a personal/global
+        // credential. Default "project" scope would miss it (the "No search provider
+        // configured" bug, esp. for automation runs rooted at the app dir).
+        const merged = new SettingsManager(cwd, "full").get();
         const search = merged.search ?? {};
         const p = search.provider;
         if (p === "serper" || p === "tavily" || p === "searxng")
@@ -68,6 +72,33 @@ export function resolveSearchConfig(cwd = process.cwd()) {
         return { provider: "searxng", baseUrl: envSearxng, source: "env" };
     return { provider: "serper", source: "none" };
 }
+/**
+ * Tool-visibility guard: WebSearch is only useful when a search provider is
+ * configured. Mirrors the runtime check in the tool itself (source === "none"
+ * means no provider).
+ *
+ * Cached per-cwd with a short TTL: this runs on EVERY message's toolDefs
+ * assembly (engine.ts), and resolveSearchConfig reads + parses settings from
+ * disk each call. The 1s TTL collapses back-to-back reads while still picking
+ * up a newly-configured provider before the user's next message. The execution
+ * path (resolveSearchConfig) is intentionally NOT cached — only this boolean.
+ */
+const availCache = new Map();
+const AVAIL_TTL_MS = 1000;
+export function isWebSearchAvailable(cwd = process.cwd(), nowMs = Date.now()) {
+    const hit = availCache.get(cwd);
+    if (hit && nowMs - hit.at < AVAIL_TTL_MS)
+        return hit.value;
+    let value = false;
+    try {
+        value = resolveSearchConfig(cwd).source !== "none";
+    }
+    catch {
+        value = false; // unresolved config → treat as unavailable
+    }
+    availCache.set(cwd, { at: nowMs, value });
+    return value;
+}
 export const webSearchToolDef = {
     name: "WebSearch",
     description: "Search the web for information. Returns a list of search results with titles, URLs, and snippets. " +
@@ -84,12 +115,14 @@ export const webSearchToolDef = {
         required: ["query"],
     },
 };
-export async function webSearchTool(args) {
+export async function webSearchTool(args, ctx) {
     const query = args.query;
     if (!query)
         return "Error: query is required";
     const numResults = Math.min(args.num_results || 10, 20);
-    const config = resolveSearchConfig();
+    // Use the run's cwd (e.g. an automation job's project dir) so per-project
+    // settings resolve correctly; falls back to process.cwd() when absent.
+    const config = resolveSearchConfig(ctx?.cwd);
     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.";
     }

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

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

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

@@ -4,6 +4,7 @@
 import { writeFile, mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { fileCache } from "./file-cache.js";
+import { enforcePathPolicy } from "../path-policy.js";
 export const writeToolDef = {
     name: "Write",
     description: "Write content to a file. Creates the file if it doesn't exist, " +
@@ -17,13 +18,18 @@ export const writeToolDef = {
         required: ["file_path", "content"],
     },
 };
-export async function writeTool(args) {
+export async function writeTool(args, ctx) {
     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";
+    // Path policy gate: deny writes to sensitive paths, refuse writes outside
+    // workspace until approved. See tool-system/path-policy.ts.
+    const blocked = enforcePathPolicy(filePath, "write", ctx?.cwd);
+    if (blocked)
+        return blocked;
     try {
         await mkdir(dirname(filePath), { recursive: true });
         await writeFile(filePath, content, "utf-8");

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

@@ -65,6 +65,25 @@ export interface SubAgentSpawnRequest {
      * gets `agent_start` / `agent_end` markers via `spawner.parentStream`.
      */
     streamOverride?: StreamCallback;
+    /**
+     * Optional ModelPool key for the child Engine's LLM (e.g. "flash").
+     * Undefined → child inherits the parent's model (current behavior).
+     */
+    model?: string;
+    /**
+     * Optional tool-name allowlist for the child. When set, the child's tool
+     * pool is restricted to these names (still minus the nested-agent tools).
+     * Undefined → child inherits the parent's full tool set (current behavior).
+     */
+    toolAllowlist?: string[];
+    /**
+     * Optional per-call system prompt appended to the child Engine's prompt
+     * (the role definition's Markdown body). Undefined → child inherits only
+     * the parent's appendSystemPrompt (current behavior).
+     */
+    appendSystemPrompt?: string;
+    /** True for read-only reviewer/researcher children; tunes investigation guard reminders. */
+    readOnlySession?: boolean;
 }
 export interface SubAgentSpawner {
     /** Run a sub-agent synchronously and return its text output. */
@@ -97,6 +116,12 @@ export interface ToolContext {
     askUser?: AskUserFn;
     /** Sub-agent spawner (Agent tool). Undefined → Agent tool unavailable. */
     subAgentSpawner?: SubAgentSpawner;
+    /**
+     * Reusable sub-agent role definitions (loaded from .code-shell/agents/*.md).
+     * The Agent tool reads this to resolve `agent_type`. Undefined → only the
+     * ephemeral (inline prompt) mode is available.
+     */
+    agentDefinitions?: import("../agent/agent-definition-registry.js").AgentDefinitionRegistry;
     /**
      * True when this Engine is itself a sub-agent. Set from EngineConfig.
      * The Agent tool refuses to spawn when this is true — runtime check
@@ -150,6 +175,24 @@ export interface ToolContext {
      * Populated from `settings.disabledSkills` by Engine.run().
      */
     disabledSkills?: string[];
+    /**
+     * Plugin names the user has totally disabled. Every skill whose
+     * namespaced name starts with `${pluginName}:` is hidden from the
+     * LLM and rejected at dispatch by the skill builtin tool with a
+     * distinct "disabled plugin" message. Populated from
+     * `settings.disabledPlugins` by Engine.run().
+     */
+    disabledPlugins?: string[];
+    /**
+     * Builtin tool names the project's capabilityOverrides marked `off` for
+     * this cwd. Engine.run() already HIDES these from the LLM-visible tool
+     * list, but the model can still NAME a hidden builtin (hallucinated, or
+     * remembered from an earlier turn when it was visible). The executor reads
+     * this set and rejects such a call — turning `off` into a real execution
+     * gate, not just a prompt-visibility filter. Empty/undefined for
+     * sub-agents and no-cwd contexts (same as readBuiltinOverride).
+     */
+    disabledBuiltins?: Set<string>;
 }
 /**
  * Per-Engine container that produces a fresh ToolContext on demand.

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

@@ -40,7 +40,6 @@ export declare class ToolExecutor {
     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.
      */

package/dist/tool-system/executor.js

@@ -5,6 +5,7 @@ import { setMaxListeners } from "node:events";
 import { logger as rootLogger, getCurrentSid } from "../logging/logger.js";
 import { recordToolCall, recordToolResult } from "../logging/session-recorder.js";
 import { validateToolArgs } from "./validation.js";
+import { PLAN_MODE_ALLOWED_TOOLS } from "./plan-mode-allowlist.js";
 // A1 hardening: hooks must never promote a non-`allow` classifier
 // decision to `allow`. They may otherwise adjust the decision freely
 // (e.g. tighten `allow` to `deny`/`ask`, or relax `deny` to `ask` to
@@ -83,22 +84,41 @@ export class ToolExecutor {
         // Local `call` so we can rewrite args via pre_tool_use updatedInput
         // without mutating the caller's object.
         let call = callIn;
+        // 0. Abort fast-path: if the run signal is already aborted, return a
+        // synthetic error result WITHOUT running pre_tool_use hooks, the
+        // permission classifier, or the handler. registry.executeTool also checks
+        // abort, but only after this method has paid for all the per-tool
+        // hook/permission round-trips. For an aborted sub-agent whose turn queued
+        // a batch of tools (e.g. 10 Reads), this collapses the whole batch
+        // instantly instead of round-tripping each one — part of the sub-agent
+        // leak fix that keeps an aborted child from burning work post-abort.
+        if (this.signal?.aborted) {
+            return {
+                id: call.id,
+                toolName: call.toolName,
+                error: `Tool aborted before execution: ${call.toolName}`,
+                isError: true,
+            };
+        }
+        // 0. Capability override: a builtin the project marked `off` is HIDDEN from
+        // the model's tool list (engine.ts applyBuiltinOverrideVisibility), but the
+        // model can still NAME it (hallucination, or a remembered earlier turn). The
+        // registry still holds the tool, so without a gate here it would execute.
+        // Reject it the same way plan mode rejects a disallowed tool — return an
+        // error result, never run the handler.
+        if (this.toolCtx?.disabledBuiltins?.has(call.toolName)) {
+            return {
+                id: call.id,
+                toolName: call.toolName,
+                error: `Tool ${call.toolName} is disabled by this project's capability override and cannot be used. Do NOT retry this tool call.`,
+                isError: true,
+            };
+        }
         // 0. Plan mode: only allow read-only tools — no file writes at all
         if (this.toolCtx?.planMode) {
-            const allowedInPlan = new Set([
-                "EnterPlanMode",
-                "ExitPlanMode",
-                "Read",
-                "Glob",
-                "Grep",
-                "WebSearch",
-                "WebFetch",
-                "AskUserQuestion",
-                "Agent",
-                "ToolSearch",
-                "TodoWrite",
-            ]);
-            if (!allowedInPlan.has(call.toolName)) {
+            // Shared with engine.ts's tool-visibility filter so the set the model
+            // SEES and the set the executor RUNS can't drift (they had).
+            if (!PLAN_MODE_ALLOWED_TOOLS.has(call.toolName)) {
                 if (call.toolName === "Bash" && this.isReadOnlyBashCommand(call.args)) {
                     // Read-only bash is fine
                 }
@@ -447,32 +467,6 @@ export class ToolExecutor {
         }
         return false;
     }
-    async executeAll(calls) {
-        const results = [];
-        // Separate safe (concurrent) and unsafe (sequential) tools
-        const safe = [];
-        const unsafe = [];
-        for (const call of calls) {
-            const tool = this.registry.getTool(call.toolName);
-            if (tool?.isConcurrencySafe) {
-                safe.push(call);
-            }
-            else {
-                unsafe.push(call);
-            }
-        }
-        // Execute safe tools concurrently
-        if (safe.length > 0) {
-            const safeResults = await Promise.all(safe.map((c) => this.executeSingle(c)));
-            results.push(...safeResults);
-        }
-        // Execute unsafe tools sequentially
-        for (const call of unsafe) {
-            const result = await this.executeSingle(call);
-            results.push(result);
-        }
-        return results;
-    }
     /**
      * Convert tool results into Message entries for the transcript.
      */

package/dist/tool-system/investigation-guard.d.ts

@@ -21,6 +21,7 @@ export interface GuardDecision {
     block?: string;
     prepend?: string;
 }
+export type InvestigationGuardPolicy = "normal" | "soft" | "read-only-review";
 export declare class InvestigationGuard {
     private readHistory;
     private consecutiveReads;
@@ -35,8 +36,10 @@ export declare class InvestigationGuard {
      * be killed by the guard — it should still get the signal to change
      * strategy, but the tool call goes through.
      */
-    private softMode;
+    private policy;
+    private readOnlyReviewBudgetReminderShown;
     setSoftMode(soft: boolean): void;
+    setPolicy(policy: InvestigationGuardPolicy): void;
     preToolCheck(call: ToolCall): GuardDecision | undefined;
     noteText(text: string | undefined): void;
     noteToolResult(_call: ToolCall, _result: ToolResult): void;

package/dist/tool-system/investigation-guard.js

@@ -38,9 +38,13 @@ export class InvestigationGuard {
      * be killed by the guard — it should still get the signal to change
      * strategy, but the tool call goes through.
      */
-    softMode = false;
+    policy = "normal";
+    readOnlyReviewBudgetReminderShown = false;
     setSoftMode(soft) {
-        this.softMode = soft;
+        this.policy = soft ? "soft" : "normal";
+    }
+    setPolicy(policy) {
+        this.policy = policy;
     }
     preToolCheck(call) {
         const tool = call.toolName;
@@ -68,7 +72,7 @@ export class InvestigationGuard {
                 `Re-reading the same content will not produce new information. ` +
                 `Switch strategy: run a command with side effects (Bash, debug log, repro), make a code change, or ask the user a specific question. ` +
                 `If you genuinely need this content, summarize what you already know about it from prior reads instead of re-fetching.`;
-            if (this.softMode) {
+            if (this.policy !== "normal") {
                 // Soft mode (headless): deliver the same signal as a prepend so the
                 // model still sees it, but allow the tool call to proceed. Hard-
                 // blocking an unattended `code-shell run …` would dead-end the task
@@ -84,6 +88,14 @@ export class InvestigationGuard {
                 `Re-reading rarely yields new information. After this result, change strategy (Bash side-effect, edit, or ask user) rather than reading further.</system-reminder>`);
         }
         if (this.consecutiveReads > READ_BUDGET) {
+            if (this.policy === "read-only-review") {
+                if (!this.readOnlyReviewBudgetReminderShown) {
+                    this.readOnlyReviewBudgetReminderShown = true;
+                    prependParts.push(`<system-reminder>Investigation guard: ${this.consecutiveReads} consecutive read-only calls during an explicit read-only review. ` +
+                        `Continue only if each read is adding new evidence, and surface a concise status update when useful.</system-reminder>`);
+                }
+                return prependParts.length ? { prepend: prependParts.join("\n") } : undefined;
+            }
             prependParts.push(`<system-reminder>Investigation guard: ${this.consecutiveReads} consecutive read-only calls with no action taken. ` +
                 `Per coding.md, change strategy now — make a code change, run a command with side effects, or ask the user.</system-reminder>`);
         }
@@ -106,6 +118,10 @@ export class InvestigationGuard {
         this.turnHasSideEffect = false;
         if (wasSilent >= SILENT_TURN_BUDGET && turnNumber !== this.lastReminderSilent) {
             this.lastReminderSilent = turnNumber;
+            if (this.policy === "read-only-review") {
+                return (`<system-reminder>Investigation guard: you have taken ${wasSilent} consecutive turns of read-only investigation ` +
+                    `without any text update to the user. Surface a brief status update with what you have confirmed, ruled out, and will inspect next.</system-reminder>`);
+            }
             return (`<system-reminder>Investigation guard: you have taken ${wasSilent} consecutive turns of read-only investigation ` +
                 `without any text update to the user or side-effecting action. ` +
                 `Either surface a status update (what have you ruled out, what's your current hypothesis?), ` +

package/dist/tool-system/mcp-manager.d.ts

@@ -7,25 +7,38 @@ import type { Tool as McpTool } from "@modelcontextprotocol/sdk/types.js";
 import type { MCPServerConfig, RegisteredTool } from "../types.js";
 import { ToolRegistry } from "./registry.js";
 /**
- * Build the static metadata for a discovered MCP tool.
+ * Persist an MCP-returned image to disk and return the textual
+ * reference the LLM should see. Images larger than
+ * MAX_MCP_IMAGE_BYTES are dropped with a placeholder so a misbehaving
+ * MCP server (e.g. a screenshot agent in a loop) can't blow up disk
+ * or the context.
  *
- * Policy (Gate 2 / Standard §S3):
- *   - Default: isConcurrencySafe=false, isReadOnly=false — conservative
- *     safe-by-default for unknown servers that may hold mutable state.
- *   - Opt-in: when the MCP server explicitly declares
- *     `annotations.readOnlyHint === true` per the MCP spec, we honour
- *     that hint and set BOTH isConcurrencySafe and isReadOnly to true,
- *     enabling parallel execution for provably read-only tools.
- *   - Anything other than the boolean literal `true`
- *     (undefined, null, false, "true", missing annotations) stays false.
- *
- * @internal exported for unit testing without spinning up a real transport.
+ * Returns a one-line note like:
+ *   [mcp-image] server=playwright tool=screenshot saved=/abs/path.png (123 KB)
  */
+export declare function spillMcpImage(serverName: string, toolName: string, base64: string, mimeType: string, opts?: {
+    baseDir?: string;
+    now?: () => number;
+}): Promise<string>;
+export declare function wrapMcpOutput(serverName: string, toolName: string, body: string): string;
+export declare function stripInternalToolArgs(args: Record<string, unknown>): Record<string, unknown>;
 export declare function buildRegisteredTool(serverName: string, tool: McpTool): RegisteredTool;
 export declare class MCPManager {
     private readonly toolRegistry;
     private static instance;
     private connections;
+    /**
+     * In-flight connect()s keyed by server name. When the broadcast config
+     * reload (server.ts forEachSession → every session's refreshRuntimeConfig)
+     * calls connectAll for the SAME `added` server on this ONE shared pool, K
+     * concurrent connect(name) calls would each start a fresh handshake because
+     * `connections.has(name)` only becomes true AFTER the handshake completes —
+     * a thundering herd of duplicate connections racing to set(). Coalescing by
+     * name here collapses them to a SINGLE underlying connection; the late
+     * callers await the same promise and return. Cleared in finally so a failed
+     * connect can be retried later.
+     */
+    private connecting;
     constructor(toolRegistry: ToolRegistry);
     static getInstance(): MCPManager;
     /**
@@ -34,8 +47,19 @@ export declare class MCPManager {
     connectAll(servers: Record<string, MCPServerConfig>): Promise<void>;
     /**
      * Connect to a single MCP server.
+     *
+     * Coalesces concurrent calls for the same `name`: an already-connected server
+     * returns immediately, and a connect already in flight for this name is
+     * awaited rather than restarted (#5 — thundering-herd guard on the shared
+     * pool). The actual handshake lives in `performConnect`.
      */
     connect(name: string, config: MCPServerConfig): Promise<void>;
+    /**
+     * Perform the actual handshake + tool discovery for one server. Separated
+     * from `connect` so the coalescing/dedup logic stays in one place. Override
+     * `connect` (not this) in test doubles that want to count handshakes.
+     */
+    protected performConnect(name: string, config: MCPServerConfig): Promise<void>;
     /**
      * Discover tools from an MCP server and register them.
      */