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

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

@@ -0,0 +1,155 @@
+/**
+ * Investigation Guard — runtime enforcement of read budgets.
+ *
+ * Background: prompt rules in coding.md ("never re-read the same file",
+ * "after ~3 read-only calls, change strategy") describe a behavior the model
+ * frequently violates under context pressure. This module turns those soft
+ * rules into in-loop reminders/blocks delivered through tool results.
+ *
+ * Three independent counters share one guard instance per Engine:
+ *   A) dedupe          — same Read offset hit ≥2 times → reminder; ≥3 times → block
+ *   B) read-budget     — N consecutive read-only tools with no side-effecting
+ *                        tool in between → reminder on the next read
+ *   C) silent turns    — N consecutive turns of only read-only tools with no
+ *                        text output → injected into the *next* turn's user
+ *                        message by turn-loop (the guard just tracks state).
+ *
+ * Everything decays naturally on any write/Bash/AskUser tool (state reset).
+ */
+const READ_ONLY_TOOLS = new Set(["Read", "Grep", "Glob", "WebFetch", "WebSearch", "ToolSearch"]);
+const READ_BUDGET = 3;
+const SILENT_TURN_BUDGET = 3;
+const DEDUPE_OFFSET_BUCKET = 50;
+// Cap readHistory so a long-running session can't grow it unbounded.
+// 512 distinct read signatures is far above what any real investigation
+// touches; once exceeded, evict oldest insertion-order entries.
+const READ_HISTORY_MAX = 512;
+export class InvestigationGuard {
+    readHistory = new Map();
+    consecutiveReads = 0;
+    silentTurns = 0;
+    turnHasText = false;
+    turnHasSideEffect = false;
+    lastReminderSilent = -1;
+    /**
+     * Soft mode replaces hard blocks (3rd-read dedupe) with a stronger
+     * reminder. Used in headless runs (`code-shell run …`) where there is
+     * no human to retry the task, so an unattended automation should not
+     * be killed by the guard — it should still get the signal to change
+     * strategy, but the tool call goes through.
+     */
+    softMode = false;
+    setSoftMode(soft) {
+        this.softMode = soft;
+    }
+    preToolCheck(call) {
+        const tool = call.toolName;
+        if (!READ_ONLY_TOOLS.has(tool)) {
+            if (this.isMutatingTool(tool)) {
+                this.consecutiveReads = 0;
+                this.turnHasSideEffect = true;
+            }
+            return undefined;
+        }
+        const key = this.buildKey(call);
+        if (!key)
+            return undefined;
+        const hits = (this.readHistory.get(key.signature) ?? 0) + 1;
+        this.readHistory.set(key.signature, hits);
+        if (this.readHistory.size > READ_HISTORY_MAX) {
+            const oldest = this.readHistory.keys().next().value;
+            if (oldest !== undefined)
+                this.readHistory.delete(oldest);
+        }
+        this.consecutiveReads += 1;
+        const prependParts = [];
+        if (hits >= 3) {
+            const message = `Investigation guard: ${tool} on this exact target has been called ${hits} times in this session. ` +
+                `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) {
+                // 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
+                // with no human to retry.
+                prependParts.push(`<system-reminder>${message}</system-reminder>`);
+            }
+            else {
+                return { block: message };
+            }
+        }
+        if (hits === 2) {
+            prependParts.push(`<system-reminder>Investigation guard: you already read this target once in this session. ` +
+                `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) {
+            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>`);
+        }
+        return prependParts.length ? { prepend: prependParts.join("\n") } : undefined;
+    }
+    noteText(text) {
+        if (text && text.trim().length > 0)
+            this.turnHasText = true;
+    }
+    noteToolResult(_call, _result) { }
+    turnEnded(turnNumber) {
+        if (!this.turnHasText && !this.turnHasSideEffect) {
+            this.silentTurns += 1;
+        }
+        else {
+            this.silentTurns = 0;
+        }
+        const wasSilent = this.silentTurns;
+        this.turnHasText = false;
+        this.turnHasSideEffect = false;
+        if (wasSilent >= SILENT_TURN_BUDGET && turnNumber !== this.lastReminderSilent) {
+            this.lastReminderSilent = turnNumber;
+            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?), ` +
+                `or change tactic — verify at runtime (logs, repro, Bash) instead of reading further.</system-reminder>`);
+        }
+        return undefined;
+    }
+    isMutatingTool(name) {
+        if (name === "Bash")
+            return true;
+        if (name === "Edit" || name === "Write" || name === "NotebookEdit")
+            return true;
+        if (name === "AskUserQuestion")
+            return true;
+        if (name === "TodoWrite")
+            return false;
+        return false;
+    }
+    buildKey(call) {
+        const tool = call.toolName;
+        const args = (call.args ?? {});
+        if (tool === "Read") {
+            const fp = typeof args.file_path === "string" ? args.file_path : "";
+            if (!fp)
+                return undefined;
+            const off = typeof args.offset === "number" ? args.offset : 0;
+            const bucket = Math.floor(off / DEDUPE_OFFSET_BUCKET);
+            return { tool, signature: `Read::${fp}::${bucket}` };
+        }
+        if (tool === "Grep") {
+            const pat = typeof args.pattern === "string" ? args.pattern : "";
+            const path = typeof args.path === "string" ? args.path : "";
+            const glob = typeof args.glob === "string" ? args.glob : "";
+            if (!pat)
+                return undefined;
+            return { tool, signature: `Grep::${pat}::${path}::${glob}` };
+        }
+        if (tool === "Glob") {
+            const pat = typeof args.pattern === "string" ? args.pattern : "";
+            const path = typeof args.path === "string" ? args.path : "";
+            if (!pat)
+                return undefined;
+            return { tool, signature: `Glob::${pat}::${path}` };
+        }
+        return undefined;
+    }
+}

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

@@ -0,0 +1,67 @@
+/**
+ * MCP Server Manager — connects to external MCP servers and registers their tools.
+ *
+ * Supports stdio and streamable-http transports.
+ */
+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.
+ *
+ * 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.
+ */
+export declare function buildRegisteredTool(serverName: string, tool: McpTool): RegisteredTool;
+export declare class MCPManager {
+    private readonly toolRegistry;
+    private static instance;
+    private connections;
+    constructor(toolRegistry: ToolRegistry);
+    static getInstance(): MCPManager;
+    /**
+     * Connect to all configured MCP servers and register their tools.
+     */
+    connectAll(servers: Record<string, MCPServerConfig>): Promise<void>;
+    /**
+     * Connect to a single MCP server.
+     */
+    connect(name: string, config: MCPServerConfig): Promise<void>;
+    /**
+     * Discover tools from an MCP server and register them.
+     */
+    private discoverTools;
+    /**
+     * Disconnect all MCP servers.
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * List connected servers.
+     */
+    listServers(): string[];
+    /**
+     * Call a tool on a specific MCP server.
+     */
+    callTool(serverName: string, toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * List resources from MCP servers.
+     */
+    listResources(serverName?: string): Promise<Array<{
+        uri: string;
+        name: string;
+        description?: string;
+    }>>;
+    /**
+     * Read a resource from an MCP server.
+     */
+    readResource(serverName: string, uri: string): Promise<string>;
+}

package/dist/tool-system/mcp-manager.js

@@ -0,0 +1,249 @@
+/**
+ * MCP Server Manager — connects to external MCP servers and registers their tools.
+ *
+ * Supports stdio and streamable-http transports.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { logger } from "../logging/logger.js";
+/**
+ * Build the static metadata for a discovered MCP tool.
+ *
+ * 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.
+ */
+export function buildRegisteredTool(serverName, tool) {
+    const readOnly = tool.annotations?.readOnlyHint === true;
+    return {
+        name: `mcp_${serverName}_${tool.name}`,
+        description: `[${serverName}] ${tool.description ?? tool.name}`,
+        inputSchema: tool.inputSchema ?? { type: "object", properties: {} },
+        source: "mcp",
+        serverName,
+        permissionDefault: "ask",
+        isConcurrencySafe: readOnly,
+        isReadOnly: readOnly,
+    };
+}
+export class MCPManager {
+    toolRegistry;
+    static instance = null;
+    connections = new Map();
+    constructor(toolRegistry) {
+        this.toolRegistry = toolRegistry;
+        MCPManager.instance = this;
+    }
+    static getInstance() {
+        if (!MCPManager.instance) {
+            throw new Error("MCPManager not initialized. Connect to servers first.");
+        }
+        return MCPManager.instance;
+    }
+    /**
+     * Connect to all configured MCP servers and register their tools.
+     */
+    async connectAll(servers) {
+        const entries = Object.entries(servers);
+        if (entries.length === 0)
+            return;
+        const results = await Promise.allSettled(entries.map(([name, config]) => this.connect(name, config)));
+        for (let i = 0; i < results.length; i++) {
+            const result = results[i];
+            if (result.status === "rejected") {
+                logger.warn("mcp.connect_failed", {
+                    server: entries[i][0],
+                    error: result.reason.message,
+                });
+            }
+        }
+    }
+    /**
+     * Connect to a single MCP server.
+     */
+    async connect(name, config) {
+        if (this.connections.has(name)) {
+            logger.info("mcp.already_connected", { server: name });
+            return;
+        }
+        logger.info("mcp.connecting", { server: name, transport: config.transport ?? "stdio" });
+        const client = new Client({ name: "code-shell", version: "0.1.0" }, { capabilities: {} });
+        let transport;
+        const transportType = config.transport ?? "stdio";
+        if (transportType === "stdio") {
+            if (!config.command) {
+                throw new Error(`MCP server "${name}": command is required for stdio transport`);
+            }
+            transport = new StdioClientTransport({
+                command: config.command,
+                args: config.args,
+                env: config.env ? { ...process.env, ...config.env } : undefined,
+            });
+        }
+        else if (transportType === "streamable-http" || transportType === "sse") {
+            if (!config.url) {
+                throw new Error(`MCP server "${name}": url is required for ${transportType} transport`);
+            }
+            transport = new StreamableHTTPClientTransport(new URL(config.url), {
+                requestInit: config.headers ? { headers: config.headers } : undefined,
+            });
+        }
+        else {
+            throw new Error(`MCP server "${name}": unsupported transport "${transportType}"`);
+        }
+        // Prevent a misbehaving MCP server from hanging `connectAll()` forever.
+        // On timeout, best-effort close the transport so we don't leak the stdio
+        // child / socket when connect() is still pending in the background.
+        const CONNECT_TIMEOUT_MS = 15_000;
+        let timeoutHandle;
+        try {
+            await new Promise((resolve, reject) => {
+                timeoutHandle = setTimeout(() => {
+                    reject(new Error(`MCP server "${name}" connect timed out after ${CONNECT_TIMEOUT_MS}ms`));
+                }, CONNECT_TIMEOUT_MS);
+                client.connect(transport).then(() => resolve(), (err) => reject(err));
+            });
+        }
+        catch (err) {
+            try {
+                await transport.close?.();
+            }
+            catch {
+                // ignore cleanup errors
+            }
+            throw err;
+        }
+        finally {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+        }
+        this.connections.set(name, { client, serverName: name, transport });
+        // Discover and register tools
+        await this.discoverTools(name, client);
+        logger.info("mcp.connected", { server: name });
+    }
+    /**
+     * Discover tools from an MCP server and register them.
+     */
+    async discoverTools(serverName, client) {
+        const result = await client.listTools();
+        for (const tool of result.tools) {
+            const registered = buildRegisteredTool(serverName, tool);
+            // Register with an executor that calls the MCP server
+            this.toolRegistry.registerTool(registered, async (args) => {
+                const callResult = await client.callTool({ name: tool.name, arguments: args });
+                // Extract text from content array
+                const parts = [];
+                if (Array.isArray(callResult.content)) {
+                    for (const item of callResult.content) {
+                        if (typeof item === "object" && item !== null && "text" in item) {
+                            parts.push(String(item.text));
+                        }
+                        else if (typeof item === "string") {
+                            parts.push(item);
+                        }
+                    }
+                }
+                return parts.join("\n") || "(no output)";
+            });
+            logger.info("mcp.tool_registered", { server: serverName, tool: registered.name });
+        }
+    }
+    /**
+     * Disconnect all MCP servers.
+     */
+    async disconnectAll() {
+        for (const [name, conn] of this.connections) {
+            try {
+                await conn.client.close();
+                logger.info("mcp.disconnected", { server: name });
+            }
+            catch (err) {
+                logger.warn("mcp.disconnect_error", { server: name, error: err.message });
+            }
+        }
+        this.connections.clear();
+    }
+    /**
+     * List connected servers.
+     */
+    listServers() {
+        return [...this.connections.keys()];
+    }
+    /**
+     * Call a tool on a specific MCP server.
+     */
+    async callTool(serverName, toolName, args) {
+        const conn = this.connections.get(serverName);
+        if (!conn) {
+            throw new Error(`MCP server "${serverName}" is not connected.`);
+        }
+        const result = await conn.client.callTool({ name: toolName, arguments: args });
+        const parts = [];
+        if (Array.isArray(result.content)) {
+            for (const item of result.content) {
+                if (typeof item === "object" && item !== null && "text" in item) {
+                    parts.push(String(item.text));
+                }
+                else if (typeof item === "string") {
+                    parts.push(item);
+                }
+            }
+        }
+        return parts.join("\n") || "(no output)";
+    }
+    /**
+     * List resources from MCP servers.
+     */
+    async listResources(serverName) {
+        const results = [];
+        const servers = serverName ? [serverName] : [...this.connections.keys()];
+        for (const name of servers) {
+            const conn = this.connections.get(name);
+            if (!conn)
+                continue;
+            try {
+                const res = await conn.client.listResources();
+                for (const r of res.resources) {
+                    results.push({
+                        uri: r.uri,
+                        name: r.name ?? r.uri,
+                        description: r.description,
+                    });
+                }
+            }
+            catch {
+                // Server may not support resources
+            }
+        }
+        return results;
+    }
+    /**
+     * Read a resource from an MCP server.
+     */
+    async readResource(serverName, uri) {
+        const conn = this.connections.get(serverName);
+        if (!conn) {
+            throw new Error(`MCP server "${serverName}" is not connected.`);
+        }
+        const result = await conn.client.readResource({ uri });
+        const parts = [];
+        if (Array.isArray(result.contents)) {
+            for (const item of result.contents) {
+                if (typeof item === "object" && item !== null && "text" in item) {
+                    parts.push(String(item.text));
+                }
+            }
+        }
+        return parts.join("\n") || "(no content)";
+    }
+}

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

@@ -0,0 +1,111 @@
+/**
+ * Permission system — classifier + approval backend.
+ */
+import type { PermissionDecision, PermissionMode, PermissionRule, ApprovalRequest, ApprovalResult } from "../types.js";
+import { logger as rootPermLogger } from "../logging/logger.js";
+export interface ApprovalBackend {
+    requestApproval(request: ApprovalRequest): Promise<ApprovalResult>;
+}
+export declare class HeadlessApprovalBackend implements ApprovalBackend {
+    private readonly mode;
+    constructor(mode: "approve-all" | "deny-all" | "approve-read-only");
+    requestApproval(req: ApprovalRequest): Promise<ApprovalResult>;
+}
+/**
+ * Auto approval backend — uses fast-path heuristics to auto-approve safe operations.
+ * Falls back to a delegate backend for uncertain cases.
+ */
+export declare class AutoApprovalBackend implements ApprovalBackend {
+    private readonly delegate?;
+    constructor(delegate?: ApprovalBackend | undefined);
+    requestApproval(req: ApprovalRequest): Promise<ApprovalResult>;
+    private isSafeOperation;
+}
+/**
+ * Interactive approval backend — prompts the user via a callback.
+ *
+ * Stores "always allow" decisions at two scopes:
+ *   - session: in-memory map, lost when the process exits
+ *   - project: persisted to <cwd>/.code-shell/settings.local.json so the
+ *              same project remembers the rule across REPL restarts
+ *
+ * The classifier reads project rules from settings on session start (see
+ * Engine.buildPermissionConfig), so persisted rules become "auto-allow"
+ * the next time the user opens the project.
+ */
+export declare class InteractiveApprovalBackend implements ApprovalBackend {
+    private sessionRules;
+    private promptFn;
+    private cwd;
+    private savedProjectRules;
+    private onProjectRules;
+    setPromptFn(fn: (request: ApprovalRequest) => Promise<ApprovalResult>): void;
+    /**
+     * Has someone installed a real prompt callback? Engine consults this
+     * to decide whether to use the interactive backend (= talk to a UI)
+     * or fall back to HeadlessApprovalBackend (= deny-all). Without it,
+     * the agent-server-stdio entry — which wires setInteractiveApprovalFn
+     * during server boot — would still fall through to deny-all because
+     * the engine couldn't tell the difference. */
+    hasPromptFn(): boolean;
+    /** Inject the project root so persistence writes to the right settings file. */
+    setCwd(cwd: string): void;
+    /**
+     * Inject a callback fired when the user approves "for this project". The
+     * callback receives the *full* accumulated list of project rules saved in
+     * this session, so the classifier can be reconfigured without losing
+     * earlier approvals.
+     */
+    setOnProjectRules(fn: (rules: PermissionRule[]) => void): void;
+    requestApproval(req: ApprovalRequest): Promise<ApprovalResult>;
+}
+export declare function getInteractiveApprovalBackend(): InteractiveApprovalBackend;
+export declare function setInteractiveApprovalFn(fn: (request: ApprovalRequest) => Promise<ApprovalResult>): void;
+type BashSafetyLevel = "safe-read" | "safe-write" | "unsafe" | "dangerous";
+export declare function classifyBashCommand(command: string): BashSafetyLevel;
+export declare class DenialTracker {
+    private denials;
+    private readonly periodMs;
+    private readonly maxDenials;
+    constructor(opts?: {
+        periodMs?: number;
+        maxDenials?: number;
+    });
+    record(toolName: string): void;
+    recordSuccess(toolName: string): void;
+    shouldWarn(toolName: string): boolean;
+    getWarningMessage(toolName: string): string;
+    clear(): void;
+}
+export declare const ACCEPT_EDITS_ALLOWLIST: ReadonlySet<string>;
+export declare class PermissionClassifier {
+    private rules;
+    private defaultMode;
+    private approvalBackend;
+    private denialTracker;
+    /**
+     * Turn-scoped logger so permission events (ask/decision/auto-deny) are
+     * tagged with the current turn/turnId. Falls back to the root logger so
+     * tests and ad-hoc usages still write log lines.
+     */
+    private log;
+    constructor(rules: PermissionRule[], defaultMode?: PermissionMode, approvalBackend?: ApprovalBackend);
+    setLogger(log: typeof rootPermLogger): void;
+    /** Replace mode + backend in place so live tool execution sees the change. */
+    reconfigure(mode: PermissionMode, approvalBackend: ApprovalBackend, rules?: PermissionRule[]): void;
+    getMode(): PermissionMode;
+    classify(toolName: string, args: Record<string, unknown>): PermissionDecision;
+    handleAsk(toolName: string, args: Record<string, unknown>, reason?: string): Promise<boolean>;
+    /** Get denial warning message if the model keeps getting denied. */
+    getDenialWarning(toolName: string): string | undefined;
+    private matchesRule;
+    private isDangerousCommand;
+    private assessRisk;
+    /**
+     * Short, human-friendly subtitle. The UI shows this under the tool title;
+     * full args (command bodies, diffs, etc.) come from the args field, so this
+     * stays compact — no truncation here, just a label.
+     */
+    private describeToolCall;
+}
+export {};