@cjhyy/code-shell-core 0.5.0-rc.1 → 0.6.0-rc.1

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

@@ -16,7 +16,7 @@
  *
  * Everything decays naturally on any write/Bash/AskUser tool (state reset).
  */
-const READ_ONLY_TOOLS = new Set(["Read", "Grep", "Glob", "WebFetch", "WebSearch", "ToolSearch"]);
+import { READ_ONLY_TOOLS } from "./plan-mode-allowlist.js";
 const READ_BUDGET = 3;
 const SILENT_TURN_BUDGET = 3;
 const DEDUPE_OFFSET_BUCKET = 50;
@@ -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,35 +7,96 @@ 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.
+ * Read a required secret from `process.env` by NAME (Codex-style env-secret
+ * handling — the value is never persisted in MCP config). A referenced env var
+ * that is undefined OR empty string is treated as missing so the connection
+ * fails with a clear, actionable error naming the server, the config field,
+ * and the env var.
+ */
+export declare function readRequiredEnv(serverName: string, field: string, envName: string): string;
+/**
+ * Build the spawned stdio server's environment. Priority (lowest → highest):
+ * a minimal inherited allowlist < forwarded `envVars` (read from process.env by
+ * name) < explicit plaintext `config.env`. Returns `undefined` when neither
+ * `env` nor `envVars` is present, preserving the old "inherit nothing extra"
+ * behavior (transport gets `env: undefined`). Pure + exported for unit testing.
+ */
+export declare function buildStdioEnv(serverName: string, config: MCPServerConfig): Record<string, string> | undefined;
+/**
+ * Build the HTTP transport's request headers. Static `config.headers` form the
+ * base; env-sourced secrets (`bearerTokenEnvVar`, `envHeaders`) layer on top
+ * and win on conflict. Pure + exported for unit testing.
+ */
+export declare function buildHttpHeaders(serverName: string, config: MCPServerConfig, resolveCredential?: (id: string) => string | undefined): Record<string, string>;
+/**
+ * Infer the transport when the config doesn't name one: a url-only entry is
+ * HTTP, everything else stdio. This is the CC `.mcp.json` convention —
+ * plugin-bundled servers commonly write just `{ "url": "..." }`, and the old
+ * blind `?? "stdio"` default then failed them with "command is required for
+ * stdio transport" despite a perfectly good url. Pure + exported for testing.
+ */
+export declare function inferTransportType(config: MCPServerConfig): NonNullable<MCPServerConfig["transport"]>;
+/**
+ * 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.
  *
- * @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;
+    private registeredToolsByServer;
+    private desiredServerNames;
+    /**
+     * 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;
+    /** Per-owner (engine) desired server sets — see reconcile()'s shared-pool note. */
+    private desiredByOwner;
     constructor(toolRegistry: ToolRegistry);
     static getInstance(): MCPManager;
     /**
      * Connect to all configured MCP servers and register their tools.
      */
-    connectAll(servers: Record<string, MCPServerConfig>): Promise<void>;
+    connectAll(servers: Record<string, MCPServerConfig>, owner?: unknown): Promise<void>;
+    reconcile(servers: Record<string, MCPServerConfig>, owner?: unknown): Promise<void>;
+    /** Union of every registered owner's desired set; null when none registered. */
+    private unionDesired;
     /**
      * 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.
      */
@@ -44,6 +105,7 @@ export declare class MCPManager {
      * Disconnect all MCP servers.
      */
     disconnectAll(): Promise<void>;
+    disconnect(name: string): Promise<void>;
     /**
      * List connected servers.
      */
@@ -51,11 +113,11 @@ export declare class MCPManager {
     /**
      * Call a tool on a specific MCP server.
      */
-    callTool(serverName: string, toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    callTool(serverName: string, toolName: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
     /**
      * List resources from MCP servers.
      */
-    listResources(serverName?: string): Promise<Array<{
+    listResources(serverName?: string, signal?: AbortSignal): Promise<Array<{
         uri: string;
         name: string;
         description?: string;
@@ -63,5 +125,5 @@ export declare class MCPManager {
     /**
      * Read a resource from an MCP server.
      */
-    readResource(serverName: string, uri: string): Promise<string>;
+    readResource(serverName: string, uri: string, signal?: AbortSignal): Promise<string>;
 }