[Init] Initial commit - NetMesh terminal manager

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/);
+});