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

src/messaging/index.ts

@@ -9,8 +9,12 @@ export type { Envelope };
 
 /** A request/reply call and a publish/subscribe surface over the mesh broker. */
 export interface Broker {
-  /** Ask one question and await one answer — the shape mesh-control's command API is reached by. */
+  /** Ask one question and await one answer — the client side; the shape mesh-control's command
+   *  API is reached by. */
   request<Req, Res>(key: string, body: Req): Promise<Res>;
+  /** Answer a question — the server side of request/reply. A tool runtime serves invocations this
+   *  way. Returns an unregister. */
+  handle<Req, Res>(key: string, handler: (body: Req) => Promise<Res>): Promise<() => void>;
   /** Emit an event onto the mesh. */
   publish<T>(env: Envelope<T>): Promise<void>;
   /** React to events matching a routing-key pattern. Returns an unsubscribe. */

src/tools/index.ts

@@ -4,9 +4,16 @@
 // the API client they call, live in the module (novox/hq ADR 0044).
 
 import type { ToolDefinition } from "../contracts/index.js";
+import type { Broker } from "../messaging/index.js";
 
 export type { ToolDefinition };
 
+/** One tool invocation crossing the broker: which tool, and its arguments. */
+export interface Invocation {
+  readonly tool: string;
+  readonly args: Readonly<Record<string, unknown>>;
+}
+
 /** A module contributes its tools as a function of its resolved environment. Returning [] (e.g.
  *  when a token is absent) is normal — the module simply exposes nothing until it can. */
 export type ToolContributor = (env: NodeJS.ProcessEnv) => ToolDefinition[];
@@ -42,6 +49,39 @@ export function collectTools(env: NodeJS.ProcessEnv = process.env): { module: st
   });
 }
 
+/** List the tools every registered module exposes — for discovery, without invoking anything. */
+export function listTools(env: NodeJS.ProcessEnv = process.env): { module: string; name: string; description: string }[] {
+  return collectTools(env).flatMap(({ module, tools }) =>
+    tools.map((t) => ({ module, name: t.name, description: t.description })),
+  );
+}
+
+/**
+ * Serve the registered modules' tools over the mesh broker — the tool runtime's core. It collects
+ * every module's tools, indexes them by name, and answers `tools.invoke` requests by running the
+ * named tool and returning its result. This is the stable half of serving; a specific tool's work
+ * (and its client) lives in its module. Returns a stop function.
+ *
+ * A duplicate tool name across modules is refused loudly rather than one silently shadowing the
+ * other — two tools answering one name is a fault, not a race to resolve.
+ */
+export async function serveTools(broker: Broker, env: NodeJS.ProcessEnv = process.env): Promise<() => void> {
+  const byName = new Map<string, ToolDefinition>();
+  for (const { module, tools } of collectTools(env)) {
+    for (const t of tools) {
+      if (byName.has(t.name)) {
+        throw new Error(`tool name ${t.name} is exposed by two modules (one is ${module}) — refused`);
+      }
+      byName.set(t.name, t);
+    }
+  }
+  return broker.handle<Invocation, unknown>("tools.invoke", async (inv) => {
+    const tool = byName.get(inv.tool);
+    if (!tool) throw new Error(`no such tool: ${inv.tool}`);
+    return tool.run(inv.args ?? {});
+  });
+}
+
 /** Testing/inspection: drop all registrations. */
 export function resetTools(): void {
   registrations.length = 0;