tools serve: the dispatch harness, proven end to end

Add serveTools(broker) — the tool runtime's core: collect every module's
registered tools, index by name (refusing a duplicate name across two
modules rather than silently shadowing), and answer 'tools.invoke'
requests by running the named tool and returning its result. Plus
listTools() for discovery and Broker.handle() (the server side of
request/reply).

Proven by test: a real async, network-calling tool is registered (as a
module does), served over an in-memory broker, and invoked by name — it
reaches its upstream and returns the computed result. So a module's tools
genuinely serve: register -> collect -> serve -> invoke -> real work ->
result. The per-node runtime process that binds the mesh's real broker
and imports the assigned modules is the thin wrapper over this.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

test/sdk.test.ts

@@ -5,7 +5,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { seal, unseal, compareVersions } from "../dist/primitives/index.js";
-import { registerModuleTools, collectTools, resetTools } from "../dist/tools/index.js";
+import { registerModuleTools, collectTools, resetTools, serveTools, listTools } from "../dist/tools/index.js";
 import { runProvisioner, type Grant } from "../dist/provisioner/index.js";
 
 test("seal round-trips and rejects the wrong key", () => {
@@ -72,6 +72,82 @@ test("provisioner creates a sealed credential for a grant, then removes on withd
   stop();
 });
 
+test("modules can SERVE: a real async tool, loaded and invoked over the broker", async () => {
+  resetTools();
+
+  // Stand up a fake upstream the tool actually calls over the network — proving a tool that does
+  // real work (not a pure function) serves end to end.
+  const { createServer } = await import("node:http");
+  const server = createServer((_req, res) => {
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify({ id: "site-123" }));
+  });
+  await new Promise<void>((r) => server.listen(0, r));
+  const addr = server.address() as { port: number };
+  const base = `http://127.0.0.1:${addr.port}`;
+
+  // A module registers its tool exactly as umami does — the tool calls the upstream and returns a
+  // result computed from it.
+  registerModuleTools("demo", () => [
+    {
+      name: "create_site",
+      description: "register a site and return its snippet",
+      input: { domain: { type: "string" } },
+      run: async (args) => {
+        const res = await fetch(`${base}/api/websites`, { method: "POST" });
+        const { id } = (await res.json()) as { id: string };
+        return { domain: String(args.domain), snippet: `<script data-website-id="${id}"></script>` };
+      },
+    },
+  ]);
+
+  const broker = memBroker();
+  const stop = await serveTools(broker, {});
+
+  // Invoke it the way a caller (mesh-control's command API) would — over the broker, by name.
+  const result = await broker.request<{ tool: string; args: Record<string, unknown> }, { snippet: string }>(
+    "tools.invoke",
+    { tool: "create_site", args: { domain: "my-app" } },
+  );
+  assert.match(result.snippet, /data-website-id="site-123"/);
+
+  // Discovery works, and an unknown tool is refused rather than silently dropped.
+  assert.deepEqual(listTools({}).map((t) => t.name), ["create_site"]);
+  await assert.rejects(broker.request("tools.invoke", { tool: "nope", args: {} }));
+
+  stop();
+  server.close();
+});
+
+test("serving refuses two modules exposing one tool name", async () => {
+  resetTools();
+  registerModuleTools("a", () => [{ name: "dup", description: "", input: {}, run: async () => 1 }]);
+  registerModuleTools("b", () => [{ name: "dup", description: "", input: {}, run: async () => 2 }]);
+  await assert.rejects(serveTools(memBroker(), {}), /exposed by two modules/);
+});
+
+// A minimal in-memory broker: request routes to a registered handle. Enough to serve tools; the
+// real broker binding is the mesh's, provided by the hosting runtime.
+function memBroker() {
+  const handlers = new Map<string, (b: unknown) => Promise<unknown>>();
+  return {
+    async request<Req, Res>(key: string, body: Req): Promise<Res> {
+      const h = handlers.get(key);
+      if (!h) throw new Error(`no handler for ${key}`);
+      return (await h(body)) as Res;
+    },
+    async handle<Req, Res>(key: string, handler: (b: Req) => Promise<Res>): Promise<() => void> {
+      handlers.set(key, handler as (b: unknown) => Promise<unknown>);
+      return () => handlers.delete(key);
+    },
+    async publish(): Promise<void> {},
+    async subscribe(): Promise<() => void> {
+      return () => {};
+    },
+    async close(): Promise<void> {},
+  };
+}
+
 async function waitFor(cond: () => boolean, ms: number): Promise<void> {
   const start = Date.now();
   while (!cond()) {