mulmoclaude 0.6.2 → 0.6.4

package/server/agent/index.ts

@@ -53,98 +53,122 @@ export async function* runAgent({
 
   // Per-invocation read so Settings UI changes apply without a server restart.
   const userMcpRaw = loadMcpConfig().mcpServers;
-  const userServers = prepareUserServers(userMcpRaw, useDocker, workspacePath);
-  const hasUserServers = Object.keys(userServers).length > 0;
-  const hasMcp = activePlugins.length > 0 || hasUserServers;
+  // `prepareUserServers` may spawn host-side stdio→HTTP gateways for
+  // opted-in servers (#1421 Phase B); `mcpShims` MUST be torn down
+  // in the finally below or host processes / ports leak.
+  const { servers: userServers, shims: mcpShims } = await prepareUserServers(userMcpRaw, useDocker, workspacePath);
 
-  // Catches the "catalog entry pinned to a non-existent npm package" failure where the MCP subprocess never starts and
-  // Claude silently falls back to WebSearch. Fire-and-forget; per-package cache amortizes the network round-trip.
-  validateStdioPackages(userServers).catch(() => {});
-
-  // macOS sandbox: refresh from Keychain so expired OAuth tokens get replaced transparently.
-  if (useDocker && process.platform === "darwin") {
-    await refreshCredentials();
-  }
-
-  // Pre-load memory once (atomic vs topic format chosen inside
-  // `loadMemorySnapshot`) so prompt assembly itself stays sync.
-  const memorySnapshot = await loadMemorySnapshot(workspacePath);
-  const fullSystemPrompt = buildSystemPrompt({
-    role,
-    workspacePath: useDocker ? CONTAINER_WORKSPACE_PATH : workspacePath,
-    useDocker,
-    userTimezone,
-    memorySnapshot,
-  });
+  // Shims are live host processes the moment `prepareUserServers`
+  // returns. Wrap *all* subsequent setup (credential refresh, memory
+  // /prompt prep, MCP config write) so a throw before `runAgent` still
+  // tears them down — otherwise host processes / ports leak for the
+  // rest of the session.
+  try {
+    const hasUserServers = Object.keys(userServers).length > 0;
+    const hasMcp = activePlugins.length > 0 || hasUserServers;
 
-  // --debug: dump the full system prompt on the first message of each session.
-  if (!claudeSessionId && process.argv.includes("--debug")) {
-    log.info("agent", `system prompt for new session:\n${fullSystemPrompt}`);
-  }
+    // Catches the "catalog entry pinned to a non-existent npm package" failure where the MCP subprocess never starts and
+    // Claude silently falls back to WebSearch. Fire-and-forget; per-package cache amortizes the network round-trip.
+    validateStdioPackages(userServers).catch(() => {});
 
-  const mcpPaths = resolveMcpConfigPaths({
-    workspacePath,
-    sessionId,
-    useDocker,
-  });
-  if (useDocker) {
-    await mkdir(dirname(mcpPaths.hostPath), { recursive: true });
-  }
+    // macOS sandbox: refresh from Keychain so expired OAuth tokens get replaced transparently.
+    if (useDocker && process.platform === "darwin") {
+      await refreshCredentials();
+    }
 
-  // Surfaced in the --debug spawn log so developers can verify Settings UI changes reach Claude Code.
-  let mcpServerNames: string[] = [];
-  if (hasMcp) {
-    const mcpConfig = buildMcpConfig({
-      chatSessionId: sessionId,
-      port,
-      activePlugins,
+    // Pre-load memory once (atomic vs topic format chosen inside
+    // `loadMemorySnapshot`) so prompt assembly itself stays sync.
+    const memorySnapshot = await loadMemorySnapshot(workspacePath);
+    const fullSystemPrompt = buildSystemPrompt({
+      role,
+      workspacePath: useDocker ? CONTAINER_WORKSPACE_PATH : workspacePath,
       useDocker,
-      userServers,
+      userTimezone,
+      memorySnapshot,
     });
-    mcpServerNames = Object.keys(mcpConfig.mcpServers).sort();
-    // Atomic so a concurrent claude spawn can't pick up a half-written file (they share the path under the session dir).
-    await writeJsonAtomic(mcpPaths.hostPath, mcpConfig);
-  }
 
-  // Per-invocation read so allowedTools / MCP-server changes apply without a server restart.
-  const settings = loadSettings();
-  const userServerAllowedTools = userServerAllowedToolNames(userServers, useDocker);
+    // --debug: dump the full system prompt on the first message of each session.
+    if (!claudeSessionId && process.argv.includes("--debug")) {
+      log.info("agent", `system prompt for new session:\n${fullSystemPrompt}`);
+    }
 
-  // Boolean presence flags only — never write raw sessionId into long-lived log sinks.
-  const backend = getActiveBackend();
-  const spawnLog: Record<string, unknown> = {
-    backend: backend.id,
-    roleId: role.id,
-    useDocker,
-    hasMcp,
-    resumed: Boolean(claudeSessionId),
-    hasSessionId: Boolean(sessionId),
-  };
-  // --debug only: kept off the default log to avoid leaking user MCP server names into long-lived sinks.
-  if (process.argv.includes("--debug") && hasMcp) {
-    spawnLog.mcpServers = mcpServerNames;
-  }
-  log.info("agent", "spawning agent", spawnLog);
-
-  try {
-    yield* backend.runAgent({
-      systemPrompt: fullSystemPrompt,
-      message,
-      role,
+    const mcpPaths = resolveMcpConfigPaths({
       workspacePath,
       sessionId,
-      port,
-      sessionToken: claudeSessionId,
-      attachments,
-      activePlugins,
-      mcpConfigPath: hasMcp ? mcpPaths.argPath : undefined,
-      extraAllowedTools: [...settings.extraAllowedTools, ...userServerAllowedTools],
-      effortLevel: settings.effortLevel,
-      abortSignal,
-      userTimezone,
       useDocker,
     });
+    if (useDocker) {
+      await mkdir(dirname(mcpPaths.hostPath), { recursive: true });
+    }
+
+    // Surfaced in the --debug spawn log so developers can verify Settings UI changes reach Claude Code.
+    let mcpServerNames: string[] = [];
+    if (hasMcp) {
+      const mcpConfig = buildMcpConfig({
+        chatSessionId: sessionId,
+        port,
+        activePlugins,
+        useDocker,
+        userServers,
+      });
+      mcpServerNames = Object.keys(mcpConfig.mcpServers).sort();
+      // Atomic so a concurrent claude spawn can't pick up a half-written file (they share the path under the session dir).
+      await writeJsonAtomic(mcpPaths.hostPath, mcpConfig);
+    }
+
+    // Per-invocation read so allowedTools / MCP-server changes apply without a server restart.
+    const settings = loadSettings();
+    const userServerAllowedTools = userServerAllowedToolNames(userServers, useDocker);
+
+    // Boolean presence flags only — never write raw sessionId into long-lived log sinks.
+    const backend = getActiveBackend();
+    const spawnLog: Record<string, unknown> = {
+      backend: backend.id,
+      roleId: role.id,
+      useDocker,
+      hasMcp,
+      resumed: Boolean(claudeSessionId),
+      hasSessionId: Boolean(sessionId),
+    };
+    // --debug only: kept off the default log to avoid leaking user MCP server names into long-lived sinks.
+    if (process.argv.includes("--debug") && hasMcp) {
+      spawnLog.mcpServers = mcpServerNames;
+    }
+    log.info("agent", "spawning agent", spawnLog);
+
+    try {
+      yield* backend.runAgent({
+        systemPrompt: fullSystemPrompt,
+        message,
+        role,
+        workspacePath,
+        sessionId,
+        port,
+        sessionToken: claudeSessionId,
+        attachments,
+        activePlugins,
+        mcpConfigPath: hasMcp ? mcpPaths.argPath : undefined,
+        extraAllowedTools: [...settings.extraAllowedTools, ...userServerAllowedTools],
+        effortLevel: settings.effortLevel,
+        abortSignal,
+        userTimezone,
+        useDocker,
+      });
+    } finally {
+      if (hasMcp) unlink(mcpPaths.hostPath).catch(() => {});
+    }
   } finally {
-    if (hasMcp) unlink(mcpPaths.hostPath).catch(() => {});
+    // Tear down any host-side stdio→HTTP shims (#1421 Phase B) —
+    // real child processes holding ports. This outer finally also
+    // covers a throw during setup (before `runAgent`), which is the
+    // main leak risk of the opt-in escape hatch.
+    for (const shim of mcpShims) {
+      try {
+        shim.close();
+      } catch {
+        // close() is best-effort + idempotent; never let a teardown
+        // failure mask the turn's real outcome.
+      }
+    }
   }
 }

package/server/agent/mcpFailureMonitor.ts

@@ -0,0 +1,167 @@
+// Runtime failure monitor for external MCP servers (#1353).
+//
+// `mcpPreflight.ts` (#1352) handles the static case: servers that
+// can't even start because of missing required config. This module
+// handles the dynamic case: servers that start OK but fail to answer
+// tool calls (API key rotated, upstream down, OAuth scope wrong …).
+//
+// Signal source is `tool_result.is_error: true` from Claude Code's
+// stream-json. `stream.ts` now forwards that flag as
+// `AgentEvent.toolCallResult.isError`; this monitor consumes those
+// events, attributes errors to the originating MCP server (parsed
+// from `mcp__<server>__<tool>` names cached at toolCall time), and
+// fires a single warn + bell notification per server once a
+// consecutive-failure threshold is crossed.
+//
+// What the monitor intentionally does NOT do:
+//   - Restart the MCP server (operator's call).
+//   - Capture MCP subprocess stderr (Claude Agent SDK holds that —
+//     out of scope for #1353).
+//   - Auto-dismiss the bell entry when calls recover. The notification
+//     engine has no dismissal API exposed yet; future work can wire
+//     it once that lands. For now: bell stays until user dismisses.
+
+import { EVENT_TYPES } from "../../src/types/events.js";
+import { NOTIFICATION_ACTION_TYPES, NOTIFICATION_PRIORITIES } from "../../src/types/notification.js";
+import { publishNotification } from "../events/notifications.js";
+import { log } from "../system/logger/index.js";
+
+export const MCP_FAILURE_THRESHOLD = 3;
+
+// Server-id contract — mirrors `isMcpServerId` in
+// `server/system/config.ts`. Single `_` is allowed; consecutive
+// `__` is forbidden because it would collide with the
+// `mcp__<server>__<tool>` delimiter and make the parser ambiguous
+// (Codex iter-2 on #1356). Both ends agreeing on this shape is
+// what lets the monitor attribute failures back to the right
+// server entry in `mcp.json`.
+const MCP_SERVER_ID_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+const MCP_PREFIX = "mcp__";
+const MCP_DELIM = "__";
+
+function isValidServerId(value: string): boolean {
+  return MCP_SERVER_ID_PATTERN.test(value) && !value.includes("__");
+}
+
+/** Minimal AgentEvent surface the monitor needs. Defined locally to
+ *  avoid a circular import; structurally matches the relevant fields
+ *  on the real `AgentEvent` union. */
+interface TrackableEvent {
+  type: string;
+  toolUseId?: string;
+  toolName?: string;
+  content?: string;
+  isError?: boolean;
+}
+
+interface ServerStats {
+  consecutiveFailures: number;
+  totalFailures: number;
+  totalCalls: number;
+}
+
+interface NotificationSink {
+  publish: typeof publishNotification;
+  warn: (event: string, message: string, data?: Record<string, unknown>) => void;
+}
+
+const defaultSink: NotificationSink = {
+  publish: publishNotification,
+  warn: (event, message, data) => log.warn(event, message, data),
+};
+
+/** Pure helper: returns the server id encoded in an MCP tool name,
+ *  or `null` for non-MCP tools.
+ *
+ *  Parses by string-split rather than a single regex so:
+ *    - server ids containing `_` (allowed by `isMcpServerId`, e.g.
+ *      `a1_b2`) attribute correctly. The first `__` after the
+ *      `mcp__` prefix is treated as the server↔tool delimiter, so
+ *      `mcp__a1_b2__do_thing` resolves to server `"a1_b2"`,
+ *      tool-part `"do_thing"`.
+ *    - no regex backtracking surface (Codex flagged ReDoS on the
+ *      previous `[^_]+(?:_[^_]+)*` form; this fix uses split + a
+ *      simple per-character validator instead). */
+export function mcpServerFromToolName(toolName: string): string | null {
+  if (!toolName.startsWith(MCP_PREFIX)) return null;
+  const rest = toolName.slice(MCP_PREFIX.length);
+  const delim = rest.indexOf(MCP_DELIM);
+  if (delim <= 0) return null;
+  const serverId = rest.slice(0, delim);
+  // The tool-part is everything after the delimiter; it can carry
+  // `__` of its own (some MCP authors use `__` in tool names) — we
+  // only care that something is there.
+  if (rest.length <= delim + MCP_DELIM.length) return null;
+  return isValidServerId(serverId) ? serverId : null;
+}
+
+/** Build a session-scoped monitor. Returns the same shape as
+ *  `createMcpTracker` so the backend wires both in the same loop.
+ *
+ *  `sink` is injectable for tests so we don't need to mock the
+ *  notification engine / logger globally. */
+export function createMcpFailureMonitor(opts: { sink?: NotificationSink; threshold?: number } = {}): {
+  track: (event: TrackableEvent) => void;
+} {
+  const sink = opts.sink ?? defaultSink;
+  const threshold = opts.threshold ?? MCP_FAILURE_THRESHOLD;
+  const toolUseIdToServer = new Map<string, string>();
+  const stats = new Map<string, ServerStats>();
+  const notified = new Set<string>();
+
+  function recordCall(toolUseId: string, toolName: string): void {
+    const server = mcpServerFromToolName(toolName);
+    if (server === null) return;
+    toolUseIdToServer.set(toolUseId, server);
+  }
+
+  function recordResult(toolUseId: string, isError: boolean): void {
+    const server = toolUseIdToServer.get(toolUseId);
+    if (server === undefined) return; // not an MCP call (or orphan result)
+    toolUseIdToServer.delete(toolUseId);
+    const entry = stats.get(server) ?? { consecutiveFailures: 0, totalFailures: 0, totalCalls: 0 };
+    entry.totalCalls += 1;
+    if (isError) {
+      entry.consecutiveFailures += 1;
+      entry.totalFailures += 1;
+      if (entry.consecutiveFailures >= threshold && !notified.has(server)) {
+        notified.add(server);
+        emitFailureNotice(server, entry, sink);
+      }
+    } else {
+      entry.consecutiveFailures = 0;
+    }
+    stats.set(server, entry);
+  }
+
+  return {
+    track(event: TrackableEvent): void {
+      if (event.type === EVENT_TYPES.toolCall && typeof event.toolUseId === "string" && typeof event.toolName === "string") {
+        recordCall(event.toolUseId, event.toolName);
+      } else if (event.type === EVENT_TYPES.toolCallResult && typeof event.toolUseId === "string") {
+        recordResult(event.toolUseId, event.isError === true);
+      }
+    },
+  };
+}
+
+function emitFailureNotice(server: string, entry: ServerStats, sink: NotificationSink): void {
+  const message = `MCP server ${server} returned errors on ${String(entry.consecutiveFailures)} consecutive tool calls; check API key, network, or upstream service health.`;
+  sink.warn("mcp", "subprocess appears broken — consecutive tool errors crossed threshold", {
+    server,
+    consecutiveFailures: entry.consecutiveFailures,
+    totalFailures: entry.totalFailures,
+    totalCalls: entry.totalCalls,
+  });
+  sink.publish({
+    // Deterministic id so the notification engine's legacyId dedup
+    // matches across restarts — bell entries from previous boots
+    // for the same broken server don't pile up.
+    id: `mcp-failure-${server}`,
+    kind: "system",
+    title: "MCP server failing",
+    body: message,
+    action: { type: NOTIFICATION_ACTION_TYPES.none },
+    priority: NOTIFICATION_PRIORITIES.high,
+  });
+}

package/server/agent/mcpPreflight.ts

@@ -0,0 +1,185 @@
+// Boot-time + per-agent-run preflight for external MCP servers
+// (#1352).
+//
+// Built-in MCP-only tools have always done this via
+// `isMcpToolEnabled` + `logMcpStatus` (server/index.ts:750) — when an
+// env var listed in `requiredEnv` is unset, the tool drops out of
+// the list and the operator sees an info log explaining why. External
+// MCP servers (the `mcp.json` ones — Notion / GitHub / Linear /…)
+// had no equivalent, so a half-configured catalog entry would still
+// spawn a subprocess and every tool call would fail silently with
+// 401. This module is the parity fix.
+//
+// The catalog (`src/config/mcpCatalog.ts`) declares which config
+// fields are `required: true`. The user's saved `mcp.json` holds
+// resolved values. Cross-referencing the two tells us which servers
+// are ready to boot and which should be excluded from the config
+// handed to Claude Code.
+
+import type { McpServerSpec } from "../system/config.js";
+import { findCatalogEntry, requiredKeysOf, type McpCatalogEntry } from "../../src/config/mcpCatalog.js";
+import { log } from "../system/logger/index.js";
+
+export interface McpPreflightResult {
+  /** Servers that passed preflight, keyed by the same id used in
+   *  the input. Safe to pass straight into `prepareUserServers` /
+   *  `buildMcpConfig`. */
+  ready: Record<string, McpServerSpec>;
+  /** Servers excluded by preflight, with the catalog field keys
+   *  whose values were unset / unresolved. */
+  skipped: { serverId: string; missing: string[] }[];
+}
+
+const PLACEHOLDER_PATTERN = /\$\{([A-Z0-9_]+)\}/g;
+const SINGLE_PLACEHOLDER = /^\$\{([A-Z0-9_]+)\}$/;
+
+/** Returns the catalog field keys whose values are unresolved in
+ *  the user's saved spec — `""`, missing, or still carrying a
+ *  `${KEY}` placeholder.
+ *
+ *  Mapping goes: catalog `configSchema[].key` → spec env key, via
+ *  the catalog template's env value. E.g. catalog template
+ *  `env: { NOTION_TOKEN: "${NOTION_API_KEY}" }` binds the field
+ *  `NOTION_API_KEY` to the env key `NOTION_TOKEN`. We then check
+ *  the user's saved spec's `env.NOTION_TOKEN`.
+ *
+ *  HTTP-type catalog entries currently have no required fields
+ *  (deepwiki is empty) — they fall through with `[]`. When a
+ *  required HTTP header lands in the catalog, extend this helper. */
+export function findMissingRequiredEnv(entry: McpCatalogEntry, spec: McpServerSpec): string[] {
+  // Transport mismatch (e.g. catalog stdio entry but user pointed
+  // the same id at an HTTP URL) means the catalog's env template
+  // doesn't apply to this user spec — see `preflightUserServers`'s
+  // header comment for the rationale. Guard here too so callers that
+  // skip the wrapper still get the correct answer.
+  if (entry.spec.type !== spec.type) return [];
+  if (entry.spec.type !== "stdio" || !entry.spec.env) return [];
+  const fieldToEnvKey = buildFieldToEnvKeyMap(entry.spec.env);
+  const userEnv = spec.type === "stdio" ? spec.env : undefined;
+  const required = requiredKeysOf(entry);
+  const missing: string[] = [];
+  for (const fieldKey of required) {
+    const envKey = fieldToEnvKey.get(fieldKey);
+    if (envKey === undefined) continue;
+    const value = userEnv?.[envKey];
+    if (!isResolved(value)) missing.push(fieldKey);
+  }
+  return missing;
+}
+
+function buildFieldToEnvKeyMap(templateEnv: Record<string, string>): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const [envKey, value] of Object.entries(templateEnv)) {
+    const match = SINGLE_PLACEHOLDER.exec(value);
+    if (match) out.set(match[1], envKey);
+  }
+  return out;
+}
+
+function isResolved(value: string | undefined): boolean {
+  if (typeof value !== "string") return false;
+  // Trim before the empty check — `"   "` (whitespace-only) is just
+  // as misconfigured as `""` and would otherwise let preflight
+  // greenlight a server that can't actually authenticate (Codex
+  // review on #1355).
+  if (value.trim().length === 0) return false;
+  PLACEHOLDER_PATTERN.lastIndex = 0;
+  return !PLACEHOLDER_PATTERN.test(value);
+}
+
+/** Filter user MCP servers by checking the catalog's required
+ *  fields. Servers without a catalog match (= user-added custom
+ *  servers) pass through — we have no metadata to validate them
+ *  against.
+ *
+ *  Two other shapes also pass through unvalidated:
+ *
+ *  - `enabled: false` entries (CodeRabbit review on #1355). They're
+ *    intentionally disabled by the user; running them through
+ *    preflight produces spurious "missing required config" warnings
+ *    AND skews the boot summary's `started` count. The downstream
+ *    `prepareUserServers` already drops disabled entries before
+ *    spawning anything, so we just forward them.
+ *
+ *  - Type-mismatched catalog hits. If the user's mcp.json has
+ *    `gmail: { type: "http", url: ... }` but the catalog's `gmail`
+ *    entry is `type: "stdio"` with env templates, the catalog's
+ *    requirement list doesn't apply to the user's spec — they've
+ *    pointed `gmail` at a different transport, effectively making it
+ *    a custom server. Treat as custom (no preflight) rather than
+ *    false-flagging missing env. */
+export function preflightUserServers(userServers: Record<string, McpServerSpec> | undefined | null): McpPreflightResult {
+  const ready: Record<string, McpServerSpec> = {};
+  const skipped: McpPreflightResult["skipped"] = [];
+  // Defensive default (Sourcery review on #1355): a malformed
+  // mcp.json — or a future refactor that nulls `mcpServers` — would
+  // otherwise throw `Object.entries(null)` at boot.
+  for (const [serverId, spec] of Object.entries(userServers ?? {})) {
+    if (spec.enabled === false) {
+      ready[serverId] = spec;
+      continue;
+    }
+    const entry = findCatalogEntry(serverId);
+    if (entry === null || entry.spec.type !== spec.type) {
+      ready[serverId] = spec;
+      continue;
+    }
+    const missing = findMissingRequiredEnv(entry, spec);
+    if (missing.length > 0) {
+      skipped.push({ serverId, missing: missing.sort() });
+      continue;
+    }
+    ready[serverId] = spec;
+  }
+  return { ready, skipped };
+}
+
+// Snapshot of the previous run's skipped set so per-agent-run logging
+// only fires on state changes. Boot-time logging always fires (clean
+// startup signal) and seeds the snapshot for subsequent runs.
+//
+// The earlier shape — a monotonic Set that only ever grew — would
+// swallow a `missing → fixed → missing again` regression: the second
+// "missing" emitted no warning because the key had already been
+// logged on the first one (Codex review on #1355). Snapshot diffing
+// fixes that without losing the dedup property: identical state
+// across turns still logs at most once.
+let lastSkippedKeys = new Set<string>();
+
+function dedupKey(entry: { serverId: string; missing: string[] }): string {
+  return `${entry.serverId}:${entry.missing.join(",")}`;
+}
+
+/** Emit structured logs for the preflight outcome.
+ *  - `source: "boot"`  — runs once at startup; always logs and
+ *    seeds the snapshot.
+ *  - `source: "agent-run"` — runs per agent invocation; logs only
+ *    entries that are new vs the previous run's snapshot. A server
+ *    that re-enters a broken state after being fixed will log again
+ *    because the key is absent from the snapshot. */
+export function logPreflightResult(result: McpPreflightResult, source: "boot" | "agent-run"): void {
+  const isBoot = source === "boot";
+  const currentKeys = new Set(result.skipped.map(dedupKey));
+  for (const entry of result.skipped) {
+    const key = dedupKey(entry);
+    if (!isBoot && lastSkippedKeys.has(key)) continue;
+    log.warn("mcp", "preflight: skipping server — missing required config", {
+      source,
+      serverId: entry.serverId,
+      missing: entry.missing,
+    });
+  }
+  lastSkippedKeys = currentKeys;
+  if (isBoot) {
+    log.info("mcp", "preflight summary", {
+      started: Object.keys(result.ready).length,
+      skipped: result.skipped.length,
+    });
+  }
+}
+
+/** Test seam — reset the snapshot between tests so each case sees a
+ *  fresh logging state. */
+export function _resetPreflightLogCache(): void {
+  lastSkippedKeys = new Set();
+}