[Init] Initial commit - NetMesh terminal manager

electron/capabilities/codegen/mcpResourceContext.test.cjs

@@ -0,0 +1,79 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+function loadFreshBridge() {
+  const bridgePath = require.resolve("../../bridges/mcpServerBridge.cjs");
+  delete require.cache[bridgePath];
+  return require("../../bridges/mcpServerBridge.cjs");
+}
+
+function envPairsToObject(envPairs) {
+  const env = { ...process.env };
+  for (const pair of envPairs || []) {
+    if (!pair?.name) continue;
+    env[pair.name] = String(pair.value ?? "");
+  }
+  return env;
+}
+
+test("MCP environment resource serializes terminal tool hints from Netcatty context", async (t) => {
+  const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+  const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
+
+  const bridge = loadFreshBridge();
+  const chatSessionId = `chat-resource-${Date.now()}`;
+  let client = null;
+
+  t.after(async () => {
+    try {
+      await client?.close();
+    } catch {
+      // Ignore teardown failures after a failed connect.
+    }
+    bridge.cleanup();
+  });
+
+  bridge.init({
+    sessions: new Map(),
+    electronModule: null,
+    terminalWorkerManager: {
+      request() {
+        throw new Error("resource context should not need a worker round trip");
+      },
+    },
+  });
+  bridge.setPermissionMode("auto");
+  bridge.updateSessionMetadata([
+    {
+      sessionId: "ssh-1",
+      hostname: "host.example",
+      label: "Prod",
+      username: "root",
+      protocol: "ssh",
+      shellType: "bash",
+      connected: true,
+    },
+  ], chatSessionId);
+
+  const port = await bridge.getOrCreateHost();
+  const config = bridge.buildMcpServerConfig(port, [], chatSessionId);
+  const transport = new StdioClientTransport({
+    command: config.command,
+    args: config.args,
+    env: envPairsToObject(config.env),
+  });
+  client = new Client({ name: "netcatty-resource-test", version: "1.0.0" });
+  await client.connect(transport);
+
+  const resource = await client.readResource({ uri: "netcatty://context" });
+  const text = resource.contents?.[0]?.text || "";
+  const context = JSON.parse(text);
+
+  assert.equal(context.hostCount, 1);
+  assert.equal(context.hosts[0].sessionId, "ssh-1");
+  assert.equal(context.tools.terminal.execute, "terminal_execute");
+  assert.equal(context.tools.terminal.start, "terminal_start");
+  assert.match(context.description, /terminal_execute/);
+});

electron/capabilities/codegen/mcpToolRegistry.cjs

@@ -0,0 +1,259 @@
+"use strict";
+
+const { z } = require("zod");
+const { listMcpTools } = require("./toolSurfaces.cjs");
+
+const TERMINAL_EXECUTE_TOOLS = new Set(["terminal_execute"]);
+const TERMINAL_START_TOOLS = new Set(["terminal_start"]);
+const TERMINAL_POLL_TOOLS = new Set(["terminal_poll"]);
+const TERMINAL_STOP_TOOLS = new Set(["terminal_stop"]);
+const SESSION_CLOSE_TOOLS = new Set(["session_close"]);
+const CONTEXT_TOOLS = new Set(["get_environment"]);
+const ATTACHMENT_LIST_TOOLS = new Set(["list_attachments"]);
+const ATTACHMENT_READ_TOOLS = new Set(["read_attachment"]);
+const SFTP_WRITE_TOOLS = new Set([
+  "sftp_write_file",
+  "sftp_mkdir",
+  "sftp_delete",
+  "sftp_rename",
+  "sftp_chmod",
+]);
+
+function buildZodField(field) {
+  let schema = field.type === "number" ? z.number() : z.string();
+  if (field.type === "number") {
+    schema = schema.int().min(0);
+  }
+  if (field.description) {
+    schema = schema.describe(field.description);
+  }
+  if (field.optional) {
+    schema = schema.optional();
+  }
+  return schema;
+}
+
+function buildZodShapeObject(inputShape) {
+  const shape = {};
+  for (const [key, field] of Object.entries(inputShape || {})) {
+    shape[key] = buildZodField(field);
+  }
+  return shape;
+}
+
+function buildZodSchema(inputShape) {
+  return z.object(buildZodShapeObject(inputShape));
+}
+
+function isEmptyMcpInputShape(inputShape) {
+  return Object.keys(inputShape || {}).length === 0;
+}
+
+function formatRpcError(result) {
+  if (result?.error) return `Error: ${result.error}`;
+  if (result?.code) return `Error: Operation failed (${result.code})`;
+  return "Error: Operation failed";
+}
+
+/**
+ * True when the RPC result carries command-run evidence (output and/or exit
+ * code). Non-zero exits from PTY exec set ok:false without an error string —
+ * that is still a completed command, not an operational failure.
+ */
+function hasTerminalExecuteEvidence(result) {
+  if (!result || typeof result !== "object") return false;
+  if (typeof result.stdout === "string" && result.stdout.length > 0) return true;
+  if (typeof result.stderr === "string" && result.stderr.length > 0) return true;
+  return result.exitCode != null;
+}
+
+function formatTerminalExecuteResult(result) {
+  const parts = [];
+  if (result?.stdout) parts.push(result.stdout);
+  if (result?.stderr) parts.push(`[stderr] ${result.stderr}`);
+  if (result?.exitCode != null) {
+    parts.push(`[exit code: ${result.exitCode}]`);
+  }
+  if (result?.error) parts.push(`[error] ${result.error}`);
+  return parts.join("\n");
+}
+
+// Align with Catty executor wording when a command ran but produced no text.
+const TERMINAL_EXECUTE_NO_OUTPUT_TEXT = "Command completed (no output)";
+
+/**
+ * Format terminal_execute for MCP clients.
+ * Match Catty semantics: when the command actually ran, always surface
+ * stdout/stderr/exitCode so the model can judge the failure. Only pure
+ * operational failures (session missing, blocked, etc.) become a bare
+ * "Error: …" payload. See issue #2718.
+ *
+ * Successful empty results (serial/network raw PTY often returns ok:true with
+ * empty stdout/stderr and exitCode:null) must NOT fall back to
+ * "Error: Operation failed" — Codex P2 on PR #2724.
+ */
+function formatTerminalExecuteMcpResponse(result) {
+  if (!result || typeof result !== "object") {
+    return { content: [{ type: "text", text: formatRpcError(result) }], isError: true };
+  }
+
+  // Operational failure with no command evidence (session not found, busy, blocked…).
+  if (result.ok === false && !hasTerminalExecuteEvidence(result)) {
+    return { content: [{ type: "text", text: formatRpcError(result) }], isError: true };
+  }
+
+  // Empty successful payloads (serial/raw PTY): neutral text.
+  // Never fall back to formatRpcError here — that mislabels silent successes (#2724 P2).
+  // When result.error is set, formatTerminalExecuteResult already includes `[error] …`.
+  const text = formatTerminalExecuteResult(result) || TERMINAL_EXECUTE_NO_OUTPUT_TEXT;
+  // Mark isError only for operational/runtime failures that include an error
+  // string (timeout, cancel, stream lost). Non-zero exit alone is success of
+  // the tool call with a failed command — same as Catty ok:true + exitCode.
+  if (result.ok === false && result.error) {
+    return { content: [{ type: "text", text }], isError: true };
+  }
+  return { content: [{ type: "text", text }] };
+}
+
+function createToolHandler(toolDef, deps) {
+  const {
+    rpcCall,
+    scopeParams,
+    guardWriteOperation,
+    catalogDescription,
+  } = deps;
+  const { mcpTool, rpcMethod, description, inputShape, policy } = toolDef;
+
+  return async (args) => {
+    if (TERMINAL_EXECUTE_TOOLS.has(mcpTool) || TERMINAL_START_TOOLS.has(mcpTool)) {
+      const { sessionId, command } = args;
+      const guardErr = guardWriteOperation(command, { skipBlocklist: true });
+      if (guardErr) {
+        return { content: [{ type: "text", text: `Error: ${guardErr}` }], isError: true };
+      }
+      const result = await rpcCall(rpcMethod, { ...scopeParams, sessionId, command });
+      if (TERMINAL_START_TOOLS.has(mcpTool)) {
+        if (!result?.ok) {
+          return { content: [{ type: "text", text: formatRpcError(result) }], isError: true };
+        }
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              jobId: result.jobId,
+              sessionId: result.sessionId,
+              status: result.status,
+              startedAt: result.startedAt,
+              outputMode: result.outputMode,
+              recommendedPollIntervalMs: result.recommendedPollIntervalMs,
+            }, null, 2),
+          }],
+        };
+      }
+      return formatTerminalExecuteMcpResponse(result);
+    }
+
+    if (TERMINAL_POLL_TOOLS.has(mcpTool) || TERMINAL_STOP_TOOLS.has(mcpTool)) {
+      const params = TERMINAL_POLL_TOOLS.has(mcpTool)
+        ? { ...scopeParams, jobId: args.jobId, offset: args.offset || 0 }
+        : { ...scopeParams, jobId: args.jobId };
+      const result = await rpcCall(rpcMethod, params);
+      if (!result.ok) {
+        return { content: [{ type: "text", text: formatRpcError(result) }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+
+    if (SESSION_CLOSE_TOOLS.has(mcpTool)) {
+      const result = await rpcCall(rpcMethod, { ...scopeParams, sessionId: args.sessionId });
+      if (!result.ok) {
+        return { content: [{ type: "text", text: formatRpcError(result) }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+
+    if (CONTEXT_TOOLS.has(mcpTool)) {
+      const ctx = await rpcCall(rpcMethod, scopeParams);
+      return { content: [{ type: "text", text: JSON.stringify(ctx, null, 2) }] };
+    }
+
+    if (ATTACHMENT_LIST_TOOLS.has(mcpTool)) {
+      const result = await rpcCall(rpcMethod, scopeParams);
+      if (!result.ok) {
+        return {
+          content: [{ type: "text", text: formatRpcError(result) }],
+          isError: true,
+        };
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify(result.attachments || [], null, 2) }],
+      };
+    }
+
+    if (ATTACHMENT_READ_TOOLS.has(mcpTool)) {
+      const { filePath, filename } = args;
+      const result = await rpcCall(rpcMethod, { ...scopeParams, filePath, filename });
+      if (!result.ok) {
+        return {
+          content: [{ type: "text", text: formatRpcError(result) }],
+          isError: true,
+        };
+      }
+      const payload = {
+        filename: result.filename,
+        mediaType: result.mediaType,
+        filePath: result.filePath,
+        sizeBytes: result.sizeBytes,
+        ...(result.text != null ? { text: result.text } : { base64Data: result.base64Data }),
+      };
+      return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    }
+
+    if (policy?.write) {
+      const guardErr = guardWriteOperation("", { skipBlocklist: true });
+      if (guardErr) {
+        return { content: [{ type: "text", text: `Error: ${guardErr}` }], isError: true };
+      }
+    }
+
+    const result = await rpcCall(rpcMethod, { ...scopeParams, ...args });
+    if (result && typeof result === "object" && result.ok === false) {
+      return {
+        content: [{ type: "text", text: formatRpcError(result) }],
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  };
+}
+
+function registerMcpTools(server, deps) {
+  const tools = listMcpTools();
+  for (const toolDef of tools) {
+    if (!toolDef.mcpTool || !toolDef.rpcMethod) continue;
+    const handler = createToolHandler(toolDef, deps);
+    const toolDescription = deps.catalogDescription(toolDef.mcpTool, toolDef.description);
+    // Empty Zod objects reject omitted `arguments`. MCP allows omitting them
+    // for no-arg tools; skip the schema so both omitted and {} are valid.
+    if (isEmptyMcpInputShape(toolDef.inputShape)) {
+      server.tool(toolDef.mcpTool, toolDescription, async () => handler({}));
+      continue;
+    }
+    server.tool(toolDef.mcpTool, toolDescription, buildZodShapeObject(toolDef.inputShape), handler);
+  }
+  return tools.length;
+}
+
+module.exports = {
+  buildZodSchema,
+  buildZodShapeObject,
+  isEmptyMcpInputShape,
+  formatRpcError,
+  formatTerminalExecuteResult,
+  formatTerminalExecuteMcpResponse,
+  hasTerminalExecuteEvidence,
+  registerMcpTools,
+  SFTP_WRITE_TOOLS,
+};

electron/capabilities/codegen/toolSurfaces.cjs

@@ -0,0 +1,204 @@
+"use strict";
+
+const { AGENT_KINDS, CAPABILITY_STATUS, CAPABILITY_SURFACES } = require("../constants.cjs");
+const { ALL_CAPABILITIES } = require("../catalog/index.cjs");
+const { TOOL_INPUT_FIELDS, MODEL_DESCRIPTION_HINTS } = require("../schemas/toolInputs.cjs");
+
+function buildZodShape(fields) {
+  const shape = {};
+  for (const [key, field] of Object.entries(fields || {})) {
+    shape[key] = {
+      type: field.type,
+      optional: Boolean(field.optional),
+      description: field.description || "",
+    };
+  }
+  return shape;
+}
+
+function getMcpToolName(capability) {
+  return capability.surfaces?.public?.mcpTool
+    || capability.surfaces?.builtin?.mcpTool
+    || null;
+}
+
+function getCattyToolName(capability) {
+  return capability.surfaces?.[CAPABILITY_SURFACES.CATTY]?.toolName
+    || getMcpToolName(capability)
+    || capability.id.replace(/\./g, "_");
+}
+
+function getCattyRpcMethod(capability) {
+  return capability.surfaces?.builtin?.rpcMethod
+    || capability.surfaces?.global?.rpcMethod
+    || capability.surfaces?.public?.rpcMethod
+    || null;
+}
+
+function getAgentToolName(capability, agentKind) {
+  if (agentKind === AGENT_KINDS.GLOBAL) {
+    return capability.surfaces?.[CAPABILITY_SURFACES.GLOBAL_AGENT]?.toolName
+      || getMcpToolName(capability)
+      || capability.id.replace(/\./g, "_");
+  }
+  return getCattyToolName(capability);
+}
+
+function getAgentRpcMethod(capability) {
+  return getCattyRpcMethod(capability);
+}
+
+function buildToolDescription(capability) {
+  const hint = MODEL_DESCRIPTION_HINTS[capability.id];
+  if (!hint) return capability.description;
+  return `${capability.description} ${hint}`;
+}
+
+function listToolSurfaces(options = {}) {
+  const {
+    surface = CAPABILITY_SURFACES.PUBLIC,
+    status = CAPABILITY_STATUS.IMPLEMENTED,
+    includeCatty = true,
+  } = options;
+
+  const tools = [];
+
+  for (const capability of ALL_CAPABILITIES) {
+    if (capability.status !== status) continue;
+    const binding = capability.surfaces?.[surface] || capability.surfaces?.public || capability.surfaces?.builtin;
+    if (!binding) continue;
+
+    const mcpTool = getMcpToolName(capability);
+    const cattyToolName = getCattyToolName(capability);
+    if (!includeCatty && !mcpTool) continue;
+
+    const builtinRpc = capability.surfaces?.builtin?.rpcMethod || binding.rpcMethod || null;
+
+    tools.push({
+      capabilityId: capability.id,
+      domain: capability.domain,
+      toolName: cattyToolName,
+      mcpTool,
+      rpcMethod: builtinRpc,
+      publicRpcMethod: capability.surfaces?.public?.rpcMethod || null,
+      description: buildToolDescription(capability),
+      policy: capability.policy,
+      inputShape: buildZodShape(TOOL_INPUT_FIELDS[capability.id]),
+      cattyEnabled: includeCatty && Boolean(TOOL_INPUT_FIELDS[capability.id] != null || mcpTool),
+    });
+  }
+
+  return tools;
+}
+
+function listMcpTools() {
+  return listToolSurfaces({ surface: CAPABILITY_SURFACES.PUBLIC, includeCatty: false })
+    .filter((tool) => tool.mcpTool);
+}
+
+/** Capabilities excluded from Catty even when implemented (CLI-only / meta). */
+const CATTY_CAPABILITY_DENYLIST = new Set([
+  "meta.status",
+  "session.cancel",
+  "session.resume",
+  "session.get",
+]);
+
+function isCattyOnlyCapability(capability) {
+  return isAgentLocalOnlyCapability(capability, AGENT_KINDS.SIDEBAR);
+}
+
+function isAgentLocalOnlyCapability(capability, agentKind) {
+  if (agentKind === AGENT_KINDS.GLOBAL) {
+    return Boolean(capability.surfaces?.[CAPABILITY_SURFACES.GLOBAL_AGENT]?.toolName)
+      && !getAgentRpcMethod(capability)
+      && !getMcpToolName(capability);
+  }
+  return Boolean(capability.surfaces?.[CAPABILITY_SURFACES.CATTY]?.toolName)
+    && !getAgentRpcMethod(capability)
+    && !getMcpToolName(capability);
+}
+
+/**
+ * Resolve which agents may use a capability when agentKinds is not set explicitly.
+ * - surfaces.globalAgent only → global agent
+ * - surfaces.catty only (harness) → sidebar agent
+ * - RPC/MCP-backed tools → both agents (shared infrastructure)
+ */
+function resolveAgentKinds(capability) {
+  if (Array.isArray(capability.agentKinds) && capability.agentKinds.length > 0) {
+    return capability.agentKinds;
+  }
+  if (capability.surfaces?.[CAPABILITY_SURFACES.GLOBAL_AGENT]) {
+    return [AGENT_KINDS.GLOBAL];
+  }
+  if (isAgentLocalOnlyCapability(capability, AGENT_KINDS.SIDEBAR)) {
+    return [AGENT_KINDS.SIDEBAR];
+  }
+  if (isAgentEligibleForKind(capability, AGENT_KINDS.SIDEBAR, { skipAgentKindCheck: true })) {
+    return [AGENT_KINDS.SIDEBAR, AGENT_KINDS.GLOBAL];
+  }
+  return [];
+}
+
+function isAgentEligibleForKind(capability, agentKind, options = {}) {
+  if (capability.status !== CAPABILITY_STATUS.IMPLEMENTED) return false;
+  if (CATTY_CAPABILITY_DENYLIST.has(capability.id)) return false;
+  if (!options.skipAgentKindCheck && !resolveAgentKinds(capability).includes(agentKind)) {
+    return false;
+  }
+  const hasInputFields = Object.prototype.hasOwnProperty.call(TOOL_INPUT_FIELDS, capability.id);
+  if (!hasInputFields) return false;
+  if (isAgentLocalOnlyCapability(capability, agentKind)) return true;
+  const hasBuiltinRpc = Boolean(capability.surfaces?.builtin?.rpcMethod);
+  const hasGlobalRpc = Boolean(capability.surfaces?.global?.rpcMethod);
+  return hasBuiltinRpc || hasGlobalRpc || Boolean(getMcpToolName(capability));
+}
+
+function isCattyEligible(capability) {
+  return isAgentEligibleForKind(capability, AGENT_KINDS.SIDEBAR);
+}
+
+function listAgentToolSpecs(agentKind = AGENT_KINDS.SIDEBAR) {
+  return ALL_CAPABILITIES
+    .filter((capability) => isAgentEligibleForKind(capability, agentKind))
+    .map((capability) => {
+      const spec = {
+        capabilityId: capability.id,
+        toolName: getAgentToolName(capability, agentKind),
+        rpcMethod: getAgentRpcMethod(capability),
+        localExecution: isAgentLocalOnlyCapability(capability, agentKind),
+        description: buildToolDescription(capability),
+        inputShape: buildZodShape(TOOL_INPUT_FIELDS[capability.id]),
+        policy: capability.policy,
+      };
+      if (agentKind !== AGENT_KINDS.SIDEBAR) {
+        spec.agentKind = agentKind;
+      }
+      return spec;
+    });
+}
+
+function listCattyToolSpecs() {
+  return listAgentToolSpecs(AGENT_KINDS.SIDEBAR);
+}
+
+module.exports = {
+  AGENT_KINDS,
+  buildZodShape,
+  buildToolDescription,
+  CATTY_CAPABILITY_DENYLIST,
+  getAgentRpcMethod,
+  getAgentToolName,
+  getCattyToolName,
+  getCattyRpcMethod,
+  isAgentEligibleForKind,
+  isAgentLocalOnlyCapability,
+  isCattyEligible,
+  isCattyOnlyCapability,
+  listAgentToolSpecs,
+  listToolSurfaces,
+  listMcpTools,
+  listCattyToolSpecs,
+  resolveAgentKinds,
+};

electron/capabilities/codegen/toolSurfaces.test.cjs

@@ -0,0 +1,455 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const { CAPABILITY_STATUS } = require("../constants.cjs");
+const { ALL_CAPABILITIES } = require("../catalog/index.cjs");
+const { TOOL_INPUT_FIELDS } = require("../schemas/toolInputs.cjs");
+const {
+  listMcpTools,
+  listCattyToolSpecs,
+  CATTY_CAPABILITY_DENYLIST,
+  isCattyEligible,
+} = require("./toolSurfaces.cjs");
+const { registerMcpTools, buildZodShapeObject, isEmptyMcpInputShape } = require("./mcpToolRegistry.cjs");
+
+function mcpToolHandler(schemaOrHandler, maybeHandler) {
+  return typeof schemaOrHandler === "function" ? schemaOrHandler : maybeHandler;
+}
+
+test("listCattyToolSpecs includes terminal long-running tools", () => {
+  const specs = listCattyToolSpecs();
+  const names = specs.map((spec) => spec.toolName);
+  assert.ok(names.includes("terminal_execute"));
+  assert.ok(names.includes("terminal_start"));
+  assert.ok(names.includes("terminal_poll"));
+  assert.ok(names.includes("terminal_stop"));
+});
+
+test("listCattyToolSpecs includes SFTP write tools and attachments", () => {
+  const capabilityIds = listCattyToolSpecs().map((spec) => spec.capabilityId);
+  assert.ok(capabilityIds.includes("attachment.list"));
+  assert.ok(capabilityIds.includes("attachment.read"));
+  assert.ok(capabilityIds.includes("sftp.write"));
+  assert.ok(capabilityIds.includes("sftp.mkdir"));
+  assert.ok(capabilityIds.includes("sftp.delete"));
+  assert.ok(capabilityIds.includes("sftp.rename"));
+  assert.ok(capabilityIds.includes("sftp.chmod"));
+  assert.ok(!capabilityIds.includes("meta.status"));
+  assert.ok(!capabilityIds.includes("session.cancel"));
+});
+
+test("listCattyToolSpecs includes vault host tools and SFTP transfer", () => {
+  const capabilityIds = listCattyToolSpecs().map((spec) => spec.capabilityId);
+  assert.ok(capabilityIds.includes("vault.host.get"));
+  assert.ok(capabilityIds.includes("vault.host.list"));
+  // Sidebar Catty must not open hosts; that expands scope mid-turn.
+  assert.ok(!capabilityIds.includes("vault.host.open"));
+  assert.ok(capabilityIds.includes("vault.hosts.create"));
+  assert.ok(capabilityIds.includes("vault.host.update"));
+  assert.ok(capabilityIds.includes("vault.host.delete"));
+  assert.ok(capabilityIds.includes("vault.host.import"));
+  assert.ok(capabilityIds.includes("vault.note.create"));
+  assert.ok(capabilityIds.includes("vault.note.list"));
+  assert.ok(capabilityIds.includes("sftp.download"));
+  assert.ok(capabilityIds.includes("sftp.upload"));
+});
+
+test("host_open stays on MCP and global agent, not sidebar Catty", () => {
+  const { AGENT_KINDS, listAgentToolSpecs } = require("./toolSurfaces.cjs");
+  const sidebarIds = listAgentToolSpecs(AGENT_KINDS.SIDEBAR).map((spec) => spec.capabilityId);
+  const globalIds = listAgentToolSpecs(AGENT_KINDS.GLOBAL).map((spec) => spec.capabilityId);
+  const mcpHostOpen = listMcpTools().find((tool) => tool.mcpTool === "host_open");
+
+  assert.ok(!sidebarIds.includes("vault.host.open"));
+  assert.ok(globalIds.includes("vault.host.open"));
+  assert.ok(mcpHostOpen);
+  assert.equal(mcpHostOpen.capabilityId, "vault.host.open");
+});
+
+test("listMcpTools includes vault host update and delete for external MCP clients", () => {
+  const tools = listMcpTools();
+  const create = tools.find((tool) => tool.mcpTool === "vault_hosts_create");
+  const update = tools.find((tool) => tool.mcpTool === "vault_hosts_update");
+  const remove = tools.find((tool) => tool.mcpTool === "vault_hosts_delete");
+  assert.match(create?.inputShape.hosts?.description ?? "", /passphrase/i);
+  assert.equal(update?.capabilityId, "vault.host.update");
+  assert.equal(update?.publicRpcMethod, "public/vault/hosts/update");
+  assert.ok(update?.inputShape.keyPath);
+  assert.ok(update?.inputShape.keypath);
+  assert.ok(update?.inputShape.savePassword);
+  assert.ok(update?.inputShape.passphrase);
+  assert.equal(remove?.capabilityId, "vault.host.delete");
+  assert.equal(remove?.publicRpcMethod, "public/vault/hosts/delete");
+});
+
+test("listMcpTools includes host_open for external MCP clients", () => {
+  const tools = listMcpTools();
+  const hostOpen = tools.find((tool) => tool.mcpTool === "host_open");
+  assert.ok(hostOpen);
+  assert.equal(hostOpen.capabilityId, "vault.host.open");
+  assert.equal(hostOpen.publicRpcMethod, "public/vault/hosts/open");
+});
+
+test("session_close is exposed to agents and external MCP clients", () => {
+  const mcpTool = listMcpTools().find((tool) => tool.mcpTool === "session_close");
+  assert.ok(mcpTool);
+  assert.equal(mcpTool.capabilityId, "session.close");
+  assert.equal(mcpTool.publicRpcMethod, "public/session/close");
+
+  const cattyTool = listCattyToolSpecs().find((tool) => tool.toolName === "session_close");
+  assert.ok(cattyTool);
+  assert.equal(cattyTool.rpcMethod, "session/close");
+});
+
+test("host_open tells agents to close sessions after use", () => {
+  const hostOpen = listMcpTools().find((tool) => tool.mcpTool === "host_open");
+  assert.match(hostOpen?.description || "", /session_close/i);
+});
+
+test("vault host import tool description routes unknown attached host text to host creation", () => {
+  const importSpec = listCattyToolSpecs().find((spec) => spec.capabilityId === "vault.host.import");
+  assert.ok(importSpec);
+  assert.match(importSpec.description, /known export formats/i);
+  assert.match(importSpec.description, /unknown/i);
+  assert.match(importSpec.description, /read_attachment/i);
+  assert.match(importSpec.description, /vault_hosts_create/i);
+});
+
+test("listCattyToolSpecs binds vault note tools to global RPC methods", () => {
+  const specs = listCattyToolSpecs();
+  const noteCreate = specs.find((spec) => spec.capabilityId === "vault.note.create");
+  assert.equal(noteCreate?.rpcMethod, "vault/notes/create");
+  const noteList = specs.find((spec) => spec.capabilityId === "vault.note.list");
+  assert.equal(noteList?.rpcMethod, "vault/notes/list");
+});
+
+test("listCattyToolSpecs binds vault and portforward tools to global RPC methods", () => {
+  const specs = listCattyToolSpecs();
+  const hostNotesSet = specs.find((spec) => spec.capabilityId === "vault.host.notes.set");
+  assert.equal(hostNotesSet?.rpcMethod, "vault/host/notes/set");
+  const portforwardStart = specs.find((spec) => spec.capabilityId === "portforward.start");
+  assert.equal(portforwardStart?.rpcMethod, "portforward/start");
+});
+
+test("generic snippet agent tools expose dynamic group targets", () => {
+  const { AGENT_KINDS, listAgentToolSpecs } = require("./toolSurfaces.cjs");
+  for (const kind of [AGENT_KINDS.SIDEBAR, AGENT_KINDS.GLOBAL]) {
+    const specs = listAgentToolSpecs(kind);
+    for (const capabilityId of ["vault.snippets.create", "vault.snippets.update"]) {
+      const spec = specs.find((entry) => entry.capabilityId === capabilityId);
+      assert.ok(spec, `${capabilityId} should be exposed to ${kind}`);
+      assert.match(spec.inputShape.targetGroups?.description ?? "", /group paths/i);
+    }
+  }
+});
+
+test("listAgentToolSpecs splits sidebar harness tools from shared RPC tools", () => {
+  const { AGENT_KINDS, listAgentToolSpecs } = require("./toolSurfaces.cjs");
+  const sidebarIds = listAgentToolSpecs(AGENT_KINDS.SIDEBAR).map((spec) => spec.capabilityId);
+  const globalIds = listAgentToolSpecs(AGENT_KINDS.GLOBAL).map((spec) => spec.capabilityId);
+
+  assert.ok(sidebarIds.includes("harness.workspace.get_info"));
+  assert.ok(!globalIds.includes("harness.workspace.get_info"));
+
+  assert.ok(sidebarIds.includes("terminal.execute"));
+  assert.ok(globalIds.includes("terminal.execute"));
+  assert.ok(globalIds.includes("vault.note.create"));
+
+  assert.ok(globalIds.every((id) => sidebarIds.includes(id) || id.startsWith("harness.") === false));
+});
+
+test("listCattyToolSpecs includes harness catty-only tools with local execution", () => {
+  const specs = listCattyToolSpecs();
+  assert.ok(specs.length >= 40);
+  const harness = specs.filter((spec) => spec.capabilityId.startsWith("harness."));
+  assert.equal(harness.length, 6);
+  for (const spec of harness) {
+    assert.equal(spec.localExecution, true);
+    assert.equal(spec.rpcMethod, null);
+  }
+  const harnessIds = harness.map((spec) => spec.capabilityId);
+  assert.ok(harnessIds.includes("harness.tool_output.read"));
+  assert.ok(harnessIds.includes("harness.workspace.get_info"));
+  assert.ok(harnessIds.includes("harness.terminal.read_context"));
+});
+
+test("harness capabilities are not exposed on MCP", () => {
+  const mcpCapabilityIds = listMcpTools().map((tool) => tool.capabilityId);
+  for (const capabilityId of mcpCapabilityIds) {
+    assert.ok(!capabilityId.startsWith("harness."));
+  }
+});
+
+test("listMcpTools descriptions stay aligned with catalog capability ids", () => {
+  const mcpTools = listMcpTools();
+  assert.ok(mcpTools.length >= 35);
+  for (const tool of mcpTools) {
+    assert.ok(tool.capabilityId);
+    assert.ok(tool.mcpTool);
+    assert.ok(tool.description.length > 0);
+    assert.ok(tool.rpcMethod);
+  }
+});
+
+test("catty and mcp terminal tools share capability ids", () => {
+  const catty = listCattyToolSpecs().find((spec) => spec.toolName === "terminal_execute");
+  const mcp = listMcpTools().find((tool) => tool.mcpTool === "terminal_execute");
+  assert.equal(catty?.capabilityId, "terminal.execute");
+  assert.equal(mcp?.capabilityId, "terminal.execute");
+});
+
+test("implemented catalog tools with inputs are catty-eligible unless denylisted or agentKinds-restricted", () => {
+  const implemented = ALL_CAPABILITIES.filter((cap) => cap.status === CAPABILITY_STATUS.IMPLEMENTED);
+  for (const capability of implemented) {
+    const hasInputs = Object.prototype.hasOwnProperty.call(TOOL_INPUT_FIELDS, capability.id);
+    if (!hasInputs) continue;
+    if (CATTY_CAPABILITY_DENYLIST.has(capability.id)) {
+      assert.equal(isCattyEligible(capability), false);
+      continue;
+    }
+    if (Array.isArray(capability.agentKinds) && capability.agentKinds.length > 0
+      && !capability.agentKinds.includes("sidebar")) {
+      assert.equal(isCattyEligible(capability), false);
+      continue;
+    }
+    const hasRpc = Boolean(
+      capability.surfaces?.builtin?.rpcMethod
+      || capability.surfaces?.public?.mcpTool,
+    );
+    if (hasRpc) {
+      assert.equal(isCattyEligible(capability), true);
+    }
+  }
+});
+
+test("mcp registry builds zod shapes for every MCP tool", () => {
+  for (const tool of listMcpTools()) {
+    const shape = buildZodShapeObject(tool.inputShape);
+    assert.equal(typeof shape, "object");
+  }
+});
+
+test("registerMcpTools registers one handler per catalog MCP tool", () => {
+  const registered = [];
+  const fakeServer = {
+    tool(name, _description, schemaOrHandler, maybeHandler) {
+      registered.push({ name, handler: typeof mcpToolHandler(schemaOrHandler, maybeHandler) });
+    },
+  };
+  const count = registerMcpTools(fakeServer, {
+    rpcCall: async () => ({ ok: true }),
+    scopeParams: {},
+    guardWriteOperation: () => null,
+    catalogDescription: (_name, fallback) => fallback,
+  });
+  assert.equal(count, listMcpTools().length);
+  assert.equal(registered.length, listMcpTools().length);
+});
+
+test("no-arg MCP tools register without a params schema so omitted arguments are valid (#3049)", () => {
+  const registrations = [];
+  const fakeServer = {
+    tool(name, _description, schemaOrHandler, maybeHandler) {
+      registrations.push({
+        name,
+        hasSchema: typeof schemaOrHandler !== "function",
+        handler: mcpToolHandler(schemaOrHandler, maybeHandler),
+      });
+    },
+  };
+  registerMcpTools(fakeServer, {
+    rpcCall: async () => ({ ok: true }),
+    scopeParams: {},
+    guardWriteOperation: () => null,
+    catalogDescription: (_name, fallback) => fallback,
+  });
+
+  const noArgNames = listMcpTools()
+    .filter((tool) => isEmptyMcpInputShape(tool.inputShape))
+    .map((tool) => tool.mcpTool);
+  assert.ok(noArgNames.includes("get_environment"));
+  assert.ok(noArgNames.includes("list_attachments"));
+
+  for (const name of noArgNames) {
+    const registration = registrations.find((entry) => entry.name === name);
+    assert.equal(registration?.hasSchema, false, `${name} should omit the params schema`);
+  }
+
+  const execute = registrations.find((entry) => entry.name === "terminal_execute");
+  assert.equal(execute?.hasSchema, true);
+});
+
+test("get_environment handler runs when MCP arguments are omitted (#3049)", async () => {
+  let handler = null;
+  const fakeServer = {
+    tool(name, _description, schemaOrHandler, maybeHandler) {
+      if (name === "get_environment") handler = mcpToolHandler(schemaOrHandler, maybeHandler);
+    },
+  };
+  let rpcMethod = null;
+  registerMcpTools(fakeServer, {
+    rpcCall: async (method) => {
+      rpcMethod = method;
+      return { sessions: [] };
+    },
+    scopeParams: { chatSessionId: "chat-1" },
+    guardWriteOperation: () => null,
+    catalogDescription: (_name, fallback) => fallback,
+  });
+
+  assert.ok(handler, "get_environment handler registered");
+  const result = await handler();
+  assert.equal(result.isError, undefined);
+  assert.equal(rpcMethod, "netcatty/getContext");
+  assert.match(result.content?.[0]?.text || "", /sessions/);
+});
+
+test("session_close remains available as a cleanup action in observer mode", async () => {
+  let handler = null;
+  let guardCalls = 0;
+  const fakeServer = {
+    tool(name, _description, schemaOrHandler, maybeHandler) {
+      if (name === "session_close") handler = mcpToolHandler(schemaOrHandler, maybeHandler);
+    },
+  };
+  registerMcpTools(fakeServer, {
+    rpcCall: async (_method, params) => ({ ok: true, sessionId: params.sessionId, status: "closed" }),
+    scopeParams: { chatSessionId: "chat-1" },
+    guardWriteOperation: () => {
+      guardCalls += 1;
+      return "Observer mode";
+    },
+    catalogDescription: (_name, fallback) => fallback,
+  });
+
+  const result = await handler({ sessionId: "session-1" });
+  assert.equal(result.isError, undefined);
+  assert.equal(guardCalls, 0);
+});
+
+test("terminal_execute MCP response preserves stdout/exitCode on non-zero exit (#2718)", async () => {
+  let handler = null;
+  const fakeServer = {
+    tool(name, _description, schemaOrHandler, maybeHandler) {
+      if (name === "terminal_execute") handler = mcpToolHandler(schemaOrHandler, maybeHandler);
+    },
+  };
+  registerMcpTools(fakeServer, {
+    rpcCall: async () => ({
+      ok: false,
+      stdout: "du: cannot access '/missing': No such file or directory",
+      stderr: "",
+      exitCode: 1,
+    }),
+    scopeParams: { chatSessionId: "chat-1" },
+    guardWriteOperation: () => null,
+    catalogDescription: (_name, fallback) => fallback,
+  });
+
+  assert.ok(handler, "terminal_execute handler registered");
+  const result = await handler({ sessionId: "sess-1", command: "du /missing" });
+  assert.equal(result.isError, undefined);
+  const text = result.content?.[0]?.text || "";
+  assert.match(text, /cannot access '\/missing'/);
+  assert.match(text, /\[exit code: 1\]/);
+  assert.doesNotMatch(text, /Operation failed/);
+});
+
+test("terminal_execute MCP response keeps operational failures as isError", async () => {
+  let handler = null;
+  const fakeServer = {
+    tool(name, _description, schemaOrHandler, maybeHandler) {
+      if (name === "terminal_execute") handler = mcpToolHandler(schemaOrHandler, maybeHandler);
+    },
+  };
+  registerMcpTools(fakeServer, {
+    rpcCall: async () => ({ ok: false, error: "Session not found" }),
+    scopeParams: { chatSessionId: "chat-1" },
+    guardWriteOperation: () => null,
+    catalogDescription: (_name, fallback) => fallback,
+  });
+
+  const result = await handler({ sessionId: "gone", command: "uptime" });
+  assert.equal(result.isError, true);
+  assert.equal(result.content?.[0]?.text, "Error: Session not found");
+});
+
+test("terminal_execute MCP response includes partial output on timeout", async () => {
+  let handler = null;
+  const fakeServer = {
+    tool(name, _description, schemaOrHandler, maybeHandler) {
+      if (name === "terminal_execute") handler = mcpToolHandler(schemaOrHandler, maybeHandler);
+    },
+  };
+  registerMcpTools(fakeServer, {
+    rpcCall: async () => ({
+      ok: false,
+      stdout: "partial lines",
+      stderr: "",
+      exitCode: -1,
+      error: "Command timed out (60s)",
+    }),
+    scopeParams: { chatSessionId: "chat-1" },
+    guardWriteOperation: () => null,
+    catalogDescription: (_name, fallback) => fallback,
+  });
+
+  const result = await handler({ sessionId: "sess-1", command: "sleep 999" });
+  assert.equal(result.isError, true);
+  const text = result.content?.[0]?.text || "";
+  assert.match(text, /partial lines/);
+  assert.match(text, /\[exit code: -1\]/);
+  assert.match(text, /\[error\] Command timed out \(60s\)/);
+});
+
+test("terminal_execute MCP response uses neutral text for successful empty output (#2724)", async () => {
+  let handler = null;
+  const fakeServer = {
+    tool(name, _description, schemaOrHandler, maybeHandler) {
+      if (name === "terminal_execute") handler = mcpToolHandler(schemaOrHandler, maybeHandler);
+    },
+  };
+  // Serial/network-device raw PTY success: ok true, empty streams, exitCode null.
+  registerMcpTools(fakeServer, {
+    rpcCall: async () => ({
+      ok: true,
+      stdout: "",
+      stderr: "",
+      exitCode: null,
+    }),
+    scopeParams: { chatSessionId: "chat-1" },
+    guardWriteOperation: () => null,
+    catalogDescription: (_name, fallback) => fallback,
+  });
+
+  const result = await handler({ sessionId: "sess-1", command: "configure terminal" });
+  assert.equal(result.isError, undefined);
+  assert.equal(result.content?.[0]?.text, "Command completed (no output)");
+  assert.doesNotMatch(result.content?.[0]?.text || "", /Operation failed/);
+});
+
+test("terminal_execute MCP response keeps exit-only non-zero without isError", async () => {
+  let handler = null;
+  const fakeServer = {
+    tool(name, _description, schemaOrHandler, maybeHandler) {
+      if (name === "terminal_execute") handler = mcpToolHandler(schemaOrHandler, maybeHandler);
+    },
+  };
+  registerMcpTools(fakeServer, {
+    rpcCall: async () => ({
+      ok: false,
+      stdout: "",
+      stderr: "",
+      exitCode: 1,
+    }),
+    scopeParams: { chatSessionId: "chat-1" },
+    guardWriteOperation: () => null,
+    catalogDescription: (_name, fallback) => fallback,
+  });
+
+  const result = await handler({ sessionId: "sess-1", command: "false" });
+  assert.equal(result.isError, undefined);
+  assert.equal(result.content?.[0]?.text, "[exit code: 1]");
+  assert.doesNotMatch(result.content?.[0]?.text || "", /Operation failed/);
+});