nemoris 0.1.0 → 0.1.2

package/src/tools/registry.js

@@ -1,348 +1,348 @@
-import { readFile, readdir } from "node:fs/promises";
-import { join } from "node:path";
-import { isToolResultContract, hashToolCall } from "./tool-result-contract.js";
-import { parseToml } from "../config/toml-lite.js";
-
-const BUILT_IN_MICRO_TOOLS = {
-  read_file: {
-    tier: "micro",
-    description: "Read file contents by path",
-    input: { path: { type: "string", required: true }, encoding: { type: "string", default: "utf8" } },
-    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
-  },
-  write_file: {
-    tier: "micro",
-    description: "Write content to file path",
-    input: { path: { type: "string", required: true }, content: { type: "string", required: true } },
-    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
-  },
-  list_dir: {
-    tier: "micro",
-    description: "List directory contents",
-    input: { path: { type: "string", required: true } },
-    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
-  },
-  shell_exec: {
-    tier: "micro",
-    description: "Execute shell command (sandboxed, opt-in only)",
-    input: { command: { type: "string", required: true }, timeout: { type: "number", default: 5000 } },
-    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
-  },
-  http_fetch: {
-    tier: "micro",
-    description: "HTTP GET/POST with timeout",
-    input: { url: { type: "string", required: true }, method: { type: "string", default: "GET" }, body: { type: "string" }, headers: { type: "object" } },
-    limits: { timeout_ms: 30000, max_output_bytes: 1048576 },
-  },
-  trigger_job: {
-    tier: "micro",
-    description: "Dispatch a job to another agent. Returns immediately with a job_id for tracking. When objective is provided, also creates a tracked task with deadline and escalation.",
-    input: {
-      targetAgent: { type: "string", required: true },
-      jobName: { type: "string" },
-      message: { type: "string" },
-      completionTarget: { type: "string", default: "human" },
-      objective: { type: "string", description: "Creates a tracked task contract when provided" },
-      deadlineMinutes: { type: "number", default: 30 },
-      escalationChain: { type: "array", description: "Escalation targets, e.g. ['assigned','owner','operator']" },
-    },
-    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
-  },
-  memory_search: {
-    tier: "micro",
-    description: "Search agent memory (semantic + lexical). Returns ranked results from the memory store.",
-    input: {
-      query: { type: "string", required: true },
-      agentId: { type: "string", description: "Target agent ID. Defaults to caller." },
-      limit: { type: "number", default: 5 },
-    },
-    limits: { timeout_ms: 10000, max_output_bytes: 1048576 },
-  },
-  write_memory: {
-    tier: "micro",
-    description: "Store a fact or preference in long-term memory. Use when the user explicitly asks you to remember something.",
-    input: {
-      text: { type: "string", required: true, description: "The fact to remember" },
-      category: { type: "string", default: "user_preference" },
-    },
-    limits: { timeout_ms: 10000, max_output_bytes: 1048576 },
-  },
-  web_search: {
-    tier: "micro",
-    description: "Search the web via Perplexity sonar-pro. Returns a concise answer with citations.",
-    input: {
-      query: { type: "string", required: true },
-    },
-    limits: { timeout_ms: 30000, max_output_bytes: 1048576 },
-  },
-  lcm_recall: {
-    tier: "micro",
-    description: "Search your compacted conversation history for relevant context. Use when you need to recall something from earlier in this session that may have been compacted.",
-    input: {
-      query: { type: "string", required: true },
-      limit: { type: "number", default: 5 },
-    },
-    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
-  },
-  session_search: {
-    tier: "micro",
-    description: "Search conversation history using full-text search. Use when the user asks about past discussions, decisions, or topics from earlier sessions.",
-    input: {
-      query: { type: "string", required: true, description: "Search query — natural language or keywords" },
-      limit: { type: "number", default: 5 },
-    },
-    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
-  },
-  load_skill: {
-    tier: "micro",
-    description: "Load a skill by name to get instructions for a specific task. Skills provide step-by-step guidance for tools, APIs, and workflows. Use when you need to perform a specialized task you have a skill for.",
-    input: {
-      name: { type: "string", required: true, description: "Skill name (e.g. 'git-workflow', 'github')" },
-    },
-    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
-  },
-  list_skills: {
-    tier: "micro",
-    description: "List all available skills by name. Use before load_skill if you're not sure what skills exist.",
-    input: {},
-    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
-  },
-  complete_task: {
-    tier: "micro",
-    description: "Mark a task as completed with an optional result.",
-    input: {
-      taskId: { type: "string", required: true },
-      result: { type: "string" },
-    },
-    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
-  },
-  fail_task: {
-    tier: "micro",
-    description: "Mark a task as failed with an error reason.",
-    input: {
-      taskId: { type: "string", required: true },
-      error: { type: "string" },
-    },
-    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
-  },
-  cancel_task: {
-    tier: "micro",
-    description: "Cancel a task. Only the task owner can cancel.",
-    input: {
-      taskId: { type: "string", required: true },
-    },
-    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
-  },
-};
-
-export class ToolRegistry {
-  #tools = new Map();
-  #stateStore = null;
-  #mcpConsumer = null;
-
-  constructor() {
-    for (const [id, def] of Object.entries(BUILT_IN_MICRO_TOOLS)) {
-      this.#tools.set(id, {
-        id,
-        tier: def.tier,
-        description: def.description,
-        input: def.input,
-        limits: { ...def.limits },
-        handler: null,
-        schema: { name: id, description: def.description, input_schema: buildJsonSchema(def.input) },
-      });
-    }
-  }
-
-  resolve(toolId) {
-    // MCP tool: return synthetic definition
-    if (toolId.startsWith("mcp:") && this.#mcpConsumer) {
-      const [serverPart, ...toolParts] = toolId.slice(4).split(".");
-      return {
-        id: toolId,
-        tier: "mcp",
-        description: `MCP tool: ${toolParts.join(".")} from ${serverPart}`,
-        input: {},
-        limits: { timeout_ms: 30000, max_output_bytes: 1048576 },
-        handler: null,
-        schema: { name: toolId, description: `MCP tool from ${serverPart}`, input_schema: { type: "object", properties: {} } },
-      };
-    }
-    const tool = this.#tools.get(toolId);
-    if (!tool) return null;
-    return { ...tool };
-  }
-
-  has(toolId) {
-    if (toolId.startsWith("mcp:") && this.#mcpConsumer) return true;
-    return this.#tools.has(toolId);
-  }
-
-  schemasForAgent(agentId, policy) {
-    const allowed = new Set(policy.allowed || []);
-    const schemas = [];
-    for (const [id, tool] of this.#tools) {
-      if (policy.default === "deny" && !allowed.has(id)) continue;
-      if ((policy.blocked || []).includes(id)) continue;
-      schemas.push(tool.schema);
-    }
-    // Merge cached MCP schemas (bypass policy — operator-configured)
-    if (this.#mcpConsumer) {
-      for (const mcpSchema of this.#mcpConsumer.cachedSchemas()) {
-        schemas.push({
-          name: mcpSchema.name,
-          description: mcpSchema.description,
-          input_schema: mcpSchema.inputSchema,
-        });
-      }
-    }
-    return schemas;
-  }
-
-  schemasForSkill(skillId, skillManifest) {
-    const required = new Set(skillManifest.tools?.required || []);
-    const optional = new Set(skillManifest.tools?.optional || []);
-    const schemas = [];
-    for (const [id, tool] of this.#tools) {
-      if (required.has(id) || optional.has(id)) {
-        schemas.push(tool.schema);
-      }
-    }
-    return schemas;
-  }
-
-  setStateStore(stateStore) {
-    this.#stateStore = stateStore;
-  }
-
-  setMcpConsumer(consumer) {
-    this.#mcpConsumer = consumer;
-  }
-
-  registerHandler(toolId, handler) {
-    const tool = this.#tools.get(toolId);
-    if (!tool) throw new Error(`Unknown tool: ${toolId}`);
-    tool.handler = handler;
-  }
-
-  async executeTool(toolId, input) {
-    // Route mcp: prefixed tools to McpConsumer
-    if (toolId.startsWith("mcp:") && this.#mcpConsumer) {
-      const dotIdx = toolId.indexOf(".", 4); // after "mcp:"
-      if (dotIdx === -1) return { error: `Invalid MCP tool ID: ${toolId}` };
-      const serverId = toolId.slice(4, dotIdx);
-      const toolName = toolId.slice(dotIdx + 1);
-      try {
-        const output = await this.#mcpConsumer.callTool(serverId, toolName, input);
-        return { output };
-      } catch (err) {
-        return { error: `MCP tool error: ${err.message}` };
-      }
-    }
-    const tool = this.#tools.get(toolId);
-    if (!tool) return { error: `Tool '${toolId}' is not configured.` };
-    if (!tool.handler) return { error: `Tool '${toolId}' has no handler registered.` };
-
-    // Cache check for contract-aware tools
-    if (this.#stateStore) {
-      const callHash = hashToolCall(toolId, input);
-      const cached = this.#stateStore.getCachedToolResult(callHash);
-      if (cached) return { output: cached.brief };
-    }
-
-    const timeout = tool.limits.timeout_ms;
-    const maxBytes = tool.limits.max_output_bytes;
-    try {
-      const result = await Promise.race([
-        tool.handler(input),
-        new Promise((_, reject) => setTimeout(() => reject(new Error("Tool timeout")), timeout)),
-      ]);
-
-      // Contract-aware tools return { brief, raw, index_terms }
-      if (isToolResultContract(result)) {
-        if (this.#stateStore) {
-          const callHash = hashToolCall(toolId, input);
-          const rawStr = typeof result.raw === "string" ? result.raw : JSON.stringify(result.raw);
-          this.#stateStore.cacheToolResult({
-            callHash,
-            toolId,
-            brief: result.brief,
-            raw: rawStr,
-            indexTerms: result.index_terms,
-          });
-        }
-        return { output: result.brief };
-      }
-
-      const output = String(result);
-      return { output: output.length > maxBytes ? output.slice(0, maxBytes) + "\n[truncated]" : output };
-    } catch (err) {
-      return { error: `Tool error: ${err.message}. The tool failed — adjust your approach.` };
-    }
-  }
-
-  async loadTools(configDir) {
-    try {
-      const files = await readdir(configDir);
-      for (const file of files) {
-        if (!file.endsWith(".toml")) continue;
-        const content = await readFile(join(configDir, file), "utf8");
-        const parsed = parseToml(content);
-        if (!parsed.tool?.id) continue;
-        if (this.#tools.has(parsed.tool.id)) continue;
-        this.#tools.set(parsed.tool.id, {
-          id: parsed.tool.id,
-          tier: parsed.tool.tier || "mcp",
-          description: parsed.tool.description || "",
-          input: parsed.tool.input || {},
-          limits: {
-            timeout_ms: parsed.tool.limits?.timeout_ms || 30000,
-            max_output_bytes: parsed.tool.limits?.max_output_bytes || 1048576,
-            spawn_on: parsed.tool.limits?.spawn_on || "first_use",
-            kill_after: parsed.tool.limits?.kill_after || "job_end",
-          },
-          command: parsed.tool.command,
-          args: parsed.tool.args || [],
-          env: parsed.tool.env || {},
-          handler: null,
-          schema: {
-            name: parsed.tool.id,
-            description: parsed.tool.description || "",
-            input_schema: buildJsonSchema(parsed.tool.input || {}),
-          },
-        });
-      }
-    } catch (err) {
-      if (err.code !== "ENOENT") throw err;
-    }
-  }
-
-  allToolIds() {
-    return [...this.#tools.keys()];
-  }
-
-  killAll() {
-    // Placeholder — external tool subprocess cleanup
-    // Note: MCP server cleanup is handled by McpConsumer.shutdown()
-  }
-
-  healthCheck(toolId) {
-    const tool = this.#tools.get(toolId);
-    if (!tool) return { healthy: false, reason: "not configured" };
-    if (tool.tier === "micro") return { healthy: true };
-    return { healthy: true };
-  }
-}
-
-function buildJsonSchema(input) {
-  if (!input || Object.keys(input).length === 0) return { type: "object", properties: {} };
-  const properties = {};
-  const required = [];
-  for (const [key, def] of Object.entries(input)) {
-    properties[key] = { type: def.type || "string" };
-    if (def.description) properties[key].description = def.description;
-    if (def.default !== undefined) properties[key].default = def.default;
-    if (def.required) required.push(key);
-  }
-  return { type: "object", properties, ...(required.length ? { required } : {}) };
-}
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { isToolResultContract, hashToolCall } from "./tool-result-contract.js";
+import { parseToml } from "../config/toml-lite.js";
+
+const BUILT_IN_MICRO_TOOLS = {
+  read_file: {
+    tier: "micro",
+    description: "Read file contents by path",
+    input: { path: { type: "string", required: true }, encoding: { type: "string", default: "utf8" } },
+    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
+  },
+  write_file: {
+    tier: "micro",
+    description: "Write content to file path",
+    input: { path: { type: "string", required: true }, content: { type: "string", required: true } },
+    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
+  },
+  list_dir: {
+    tier: "micro",
+    description: "List directory contents",
+    input: { path: { type: "string", required: true } },
+    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
+  },
+  shell_exec: {
+    tier: "micro",
+    description: "Execute shell command (sandboxed, opt-in only)",
+    input: { command: { type: "string", required: true }, timeout: { type: "number", default: 5000 } },
+    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
+  },
+  http_fetch: {
+    tier: "micro",
+    description: "HTTP GET/POST with timeout",
+    input: { url: { type: "string", required: true }, method: { type: "string", default: "GET" }, body: { type: "string" }, headers: { type: "object" } },
+    limits: { timeout_ms: 30000, max_output_bytes: 1048576 },
+  },
+  trigger_job: {
+    tier: "micro",
+    description: "Dispatch a job to another agent. Returns immediately with a job_id for tracking. When objective is provided, also creates a tracked task with deadline and escalation.",
+    input: {
+      targetAgent: { type: "string", required: true },
+      jobName: { type: "string" },
+      message: { type: "string" },
+      completionTarget: { type: "string", default: "human" },
+      objective: { type: "string", description: "Creates a tracked task contract when provided" },
+      deadlineMinutes: { type: "number", default: 30 },
+      escalationChain: { type: "array", description: "Escalation targets, e.g. ['assigned','owner','operator']" },
+    },
+    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
+  },
+  memory_search: {
+    tier: "micro",
+    description: "Search agent memory (semantic + lexical). Returns ranked results from the memory store.",
+    input: {
+      query: { type: "string", required: true },
+      agentId: { type: "string", description: "Target agent ID. Defaults to caller." },
+      limit: { type: "number", default: 5 },
+    },
+    limits: { timeout_ms: 10000, max_output_bytes: 1048576 },
+  },
+  write_memory: {
+    tier: "micro",
+    description: "Store a fact or preference in long-term memory. Use when the user explicitly asks you to remember something.",
+    input: {
+      text: { type: "string", required: true, description: "The fact to remember" },
+      category: { type: "string", default: "user_preference" },
+    },
+    limits: { timeout_ms: 10000, max_output_bytes: 1048576 },
+  },
+  web_search: {
+    tier: "micro",
+    description: "Search the web via Perplexity sonar-pro. Returns a concise answer with citations.",
+    input: {
+      query: { type: "string", required: true },
+    },
+    limits: { timeout_ms: 30000, max_output_bytes: 1048576 },
+  },
+  lcm_recall: {
+    tier: "micro",
+    description: "Search your compacted conversation history for relevant context. Use when you need to recall something from earlier in this session that may have been compacted.",
+    input: {
+      query: { type: "string", required: true },
+      limit: { type: "number", default: 5 },
+    },
+    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
+  },
+  session_search: {
+    tier: "micro",
+    description: "Search conversation history using full-text search. Use when the user asks about past discussions, decisions, or topics from earlier sessions.",
+    input: {
+      query: { type: "string", required: true, description: "Search query — natural language or keywords" },
+      limit: { type: "number", default: 5 },
+    },
+    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
+  },
+  load_skill: {
+    tier: "micro",
+    description: "Load a skill by name to get instructions for a specific task. Skills provide step-by-step guidance for tools, APIs, and workflows. Use when you need to perform a specialized task you have a skill for.",
+    input: {
+      name: { type: "string", required: true, description: "Skill name (e.g. 'git-workflow', 'github')" },
+    },
+    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
+  },
+  list_skills: {
+    tier: "micro",
+    description: "List all available skills by name. Use before load_skill if you're not sure what skills exist.",
+    input: {},
+    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
+  },
+  complete_task: {
+    tier: "micro",
+    description: "Mark a task as completed with an optional result.",
+    input: {
+      taskId: { type: "string", required: true },
+      result: { type: "string" },
+    },
+    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
+  },
+  fail_task: {
+    tier: "micro",
+    description: "Mark a task as failed with an error reason.",
+    input: {
+      taskId: { type: "string", required: true },
+      error: { type: "string" },
+    },
+    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
+  },
+  cancel_task: {
+    tier: "micro",
+    description: "Cancel a task. Only the task owner can cancel.",
+    input: {
+      taskId: { type: "string", required: true },
+    },
+    limits: { timeout_ms: 5000, max_output_bytes: 1048576 },
+  },
+};
+
+export class ToolRegistry {
+  #tools = new Map();
+  #stateStore = null;
+  #mcpConsumer = null;
+
+  constructor() {
+    for (const [id, def] of Object.entries(BUILT_IN_MICRO_TOOLS)) {
+      this.#tools.set(id, {
+        id,
+        tier: def.tier,
+        description: def.description,
+        input: def.input,
+        limits: { ...def.limits },
+        handler: null,
+        schema: { name: id, description: def.description, input_schema: buildJsonSchema(def.input) },
+      });
+    }
+  }
+
+  resolve(toolId) {
+    // MCP tool: return synthetic definition
+    if (toolId.startsWith("mcp:") && this.#mcpConsumer) {
+      const [serverPart, ...toolParts] = toolId.slice(4).split(".");
+      return {
+        id: toolId,
+        tier: "mcp",
+        description: `MCP tool: ${toolParts.join(".")} from ${serverPart}`,
+        input: {},
+        limits: { timeout_ms: 30000, max_output_bytes: 1048576 },
+        handler: null,
+        schema: { name: toolId, description: `MCP tool from ${serverPart}`, input_schema: { type: "object", properties: {} } },
+      };
+    }
+    const tool = this.#tools.get(toolId);
+    if (!tool) return null;
+    return { ...tool };
+  }
+
+  has(toolId) {
+    if (toolId.startsWith("mcp:") && this.#mcpConsumer) return true;
+    return this.#tools.has(toolId);
+  }
+
+  schemasForAgent(agentId, policy) {
+    const allowed = new Set(policy.allowed || []);
+    const schemas = [];
+    for (const [id, tool] of this.#tools) {
+      if (policy.default === "deny" && !allowed.has(id)) continue;
+      if ((policy.blocked || []).includes(id)) continue;
+      schemas.push(tool.schema);
+    }
+    // Merge cached MCP schemas (bypass policy — operator-configured)
+    if (this.#mcpConsumer) {
+      for (const mcpSchema of this.#mcpConsumer.cachedSchemas()) {
+        schemas.push({
+          name: mcpSchema.name,
+          description: mcpSchema.description,
+          input_schema: mcpSchema.inputSchema,
+        });
+      }
+    }
+    return schemas;
+  }
+
+  schemasForSkill(skillId, skillManifest) {
+    const required = new Set(skillManifest.tools?.required || []);
+    const optional = new Set(skillManifest.tools?.optional || []);
+    const schemas = [];
+    for (const [id, tool] of this.#tools) {
+      if (required.has(id) || optional.has(id)) {
+        schemas.push(tool.schema);
+      }
+    }
+    return schemas;
+  }
+
+  setStateStore(stateStore) {
+    this.#stateStore = stateStore;
+  }
+
+  setMcpConsumer(consumer) {
+    this.#mcpConsumer = consumer;
+  }
+
+  registerHandler(toolId, handler) {
+    const tool = this.#tools.get(toolId);
+    if (!tool) throw new Error(`Unknown tool: ${toolId}`);
+    tool.handler = handler;
+  }
+
+  async executeTool(toolId, input) {
+    // Route mcp: prefixed tools to McpConsumer
+    if (toolId.startsWith("mcp:") && this.#mcpConsumer) {
+      const dotIdx = toolId.indexOf(".", 4); // after "mcp:"
+      if (dotIdx === -1) return { error: `Invalid MCP tool ID: ${toolId}` };
+      const serverId = toolId.slice(4, dotIdx);
+      const toolName = toolId.slice(dotIdx + 1);
+      try {
+        const output = await this.#mcpConsumer.callTool(serverId, toolName, input);
+        return { output };
+      } catch (err) {
+        return { error: `MCP tool error: ${err.message}` };
+      }
+    }
+    const tool = this.#tools.get(toolId);
+    if (!tool) return { error: `Tool '${toolId}' is not configured.` };
+    if (!tool.handler) return { error: `Tool '${toolId}' has no handler registered.` };
+
+    // Cache check for contract-aware tools
+    if (this.#stateStore) {
+      const callHash = hashToolCall(toolId, input);
+      const cached = this.#stateStore.getCachedToolResult(callHash);
+      if (cached) return { output: cached.brief };
+    }
+
+    const timeout = tool.limits.timeout_ms;
+    const maxBytes = tool.limits.max_output_bytes;
+    try {
+      const result = await Promise.race([
+        tool.handler(input),
+        new Promise((_, reject) => setTimeout(() => reject(new Error("Tool timeout")), timeout)),
+      ]);
+
+      // Contract-aware tools return { brief, raw, index_terms }
+      if (isToolResultContract(result)) {
+        if (this.#stateStore) {
+          const callHash = hashToolCall(toolId, input);
+          const rawStr = typeof result.raw === "string" ? result.raw : JSON.stringify(result.raw);
+          this.#stateStore.cacheToolResult({
+            callHash,
+            toolId,
+            brief: result.brief,
+            raw: rawStr,
+            indexTerms: result.index_terms,
+          });
+        }
+        return { output: result.brief };
+      }
+
+      const output = String(result);
+      return { output: output.length > maxBytes ? output.slice(0, maxBytes) + "\n[truncated]" : output };
+    } catch (err) {
+      return { error: `Tool error: ${err.message}. The tool failed — adjust your approach.` };
+    }
+  }
+
+  async loadTools(configDir) {
+    try {
+      const files = await readdir(configDir);
+      for (const file of files) {
+        if (!file.endsWith(".toml")) continue;
+        const content = await readFile(join(configDir, file), "utf8");
+        const parsed = parseToml(content);
+        if (!parsed.tool?.id) continue;
+        if (this.#tools.has(parsed.tool.id)) continue;
+        this.#tools.set(parsed.tool.id, {
+          id: parsed.tool.id,
+          tier: parsed.tool.tier || "mcp",
+          description: parsed.tool.description || "",
+          input: parsed.tool.input || {},
+          limits: {
+            timeout_ms: parsed.tool.limits?.timeout_ms || 30000,
+            max_output_bytes: parsed.tool.limits?.max_output_bytes || 1048576,
+            spawn_on: parsed.tool.limits?.spawn_on || "first_use",
+            kill_after: parsed.tool.limits?.kill_after || "job_end",
+          },
+          command: parsed.tool.command,
+          args: parsed.tool.args || [],
+          env: parsed.tool.env || {},
+          handler: null,
+          schema: {
+            name: parsed.tool.id,
+            description: parsed.tool.description || "",
+            input_schema: buildJsonSchema(parsed.tool.input || {}),
+          },
+        });
+      }
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
+
+  allToolIds() {
+    return [...this.#tools.keys()];
+  }
+
+  killAll() {
+    // Placeholder — external tool subprocess cleanup
+    // Note: MCP server cleanup is handled by McpConsumer.shutdown()
+  }
+
+  healthCheck(toolId) {
+    const tool = this.#tools.get(toolId);
+    if (!tool) return { healthy: false, reason: "not configured" };
+    if (tool.tier === "micro") return { healthy: true };
+    return { healthy: true };
+  }
+}
+
+function buildJsonSchema(input) {
+  if (!input || Object.keys(input).length === 0) return { type: "object", properties: {} };
+  const properties = {};
+  const required = [];
+  for (const [key, def] of Object.entries(input)) {
+    properties[key] = { type: def.type || "string" };
+    if (def.description) properties[key].description = def.description;
+    if (def.default !== undefined) properties[key].default = def.default;
+    if (def.required) required.push(key);
+  }
+  return { type: "object", properties, ...(required.length ? { required } : {}) };
+}