A bundle that is not JavaScript is launched and spoken to over MCP on stdio (hq ADR 0187, to-be 38 WP1b)

The runtime imported a bundle into its own process, which only JavaScript can be. Now an entrypoint
that is not a plain JavaScript file — or is one marked executable — is started as a child with the
runtime's environment and asked `tools/list` once and `tools/call` per call; what it lists is
registered exactly as an imported bundle's registrations are, a `<seat>.<verb>` name as the seat's
implementation. So a tools bundle may be in any language, and the mesh's part — the subjects, the
seats, the `tools` answer, a failed bundle named — stays in the runtime and is shared by all of
them. A child that exits mid-call tells the caller so and is started again on its next call.

Proven against a real bus beside the three bundles already there: a Python bundle with no SDK at
all answers its tool and its seat verb; a TypeScript bundle written against the protocol and marked
executable is served through the launcher, shortcut off; a bundle told to exit is relaunched.

README.md

@@ -15,6 +15,14 @@ this runtime is what loads them and puts them on the mesh. It:
    and the others serve;
 4. serves every module's tools on that module's subjects and every held seat's verbs on the seat's.
 
+A bundle that is not plain JavaScript — a Go or Rust binary, a Python script, or a JavaScript file
+marked executable — is **launched** rather than imported (novox/hq ADR 0187): the runtime starts it
+as a child with its own environment and speaks MCP over stdio to it, `tools/list` once and
+`tools/call` per call. A tool it lists as `<seat>.<verb>` is the seat's implementation. A child that
+exits is named in the log and started again on its next call. So a tools bundle may be written in
+any language; the mesh's SDK for each is the stdio loop and nothing more (`src/launch.ts` is the
+runtime's side of it).
+
 Everything hard — dispatch, collection, duplicate-name safety — is the sdk's. This is the thin
 wrapper that binds the bus and loads the modules. Keeping the bus client here, out of the sdk, is
 deliberate: a bus-client change never rebuilds a module (ADR 0039). The runtime is module-agnostic:

src/launch.ts

@@ -0,0 +1,169 @@
+// A tools bundle as a process the runtime launches (novox/hq ADR 0187).
+//
+// The runtime does not run a tool's code itself when the bundle is not JavaScript: it starts the
+// bundle's executable as a child with the runtime's environment and speaks MCP over stdio to it —
+// `initialize`, `tools/list` once, `tools/call` per call. A Rust binary, a Go binary, a Python
+// script and a Node script are the same thing from here: a process that answers those. Everything
+// the mesh adds — the subjects from the membership, the held seats, the `tools` answer, a bundle
+// that failed named and the others serving — is the runtime's, outside this file.
+//
+// A tool the child lists as `<seat>.<verb>` is the module's implementation of that seat's verb;
+// any other name is the module's own tool. The same rule the in-process registration follows.
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import type { ToolDefinition } from "@novox/mesh-sdk/tools";
+
+/** The protocol version this speaks; a bundle says the same. */
+export const PROTOCOL = "2025-03-26";
+
+/** How long a child has to answer `initialize` and `tools/list` before it is a failed bundle, and
+ *  how long a call may take before the caller is told the tool is slow rather than absent. */
+const HANDSHAKE_MS = 10_000;
+const CALL_MS = 30_000;
+
+/** Whether an entrypoint is launched as a process rather than imported: anything that is not a
+ *  plain JavaScript file, and a JavaScript file marked executable — a bundle written against the
+ *  protocol in TypeScript, served the same way as any other language. */
+export function launches(entry: string): boolean {
+  const javascript = /\.(m|c)?js$/.test(entry);
+  let executable = false;
+  try {
+    accessSync(entry, constants.X_OK);
+    executable = true;
+  } catch {
+    // not executable, or not there — importing will say which
+  }
+  return !javascript || executable;
+}
+
+/** What a launched bundle registers: the groups the in-process path would have, by name. */
+export interface Launched {
+  registrations: { module: string; tools: ToolDefinition[] }[];
+  stop(): void;
+}
+
+interface Pending {
+  resolve(v: any): void;
+  reject(e: Error): void;
+  timer: NodeJS.Timeout;
+}
+
+/**
+ * Launch a bundle and learn its tools. Rejects when the child cannot be started or does not complete
+ * the handshake, which the runtime records as the bundle having failed. A child that exits later is
+ * started again on the next call, once; a call in flight when it died is told so.
+ */
+export async function launch(module: string, entry: string, env: NodeJS.ProcessEnv = process.env): Promise<Launched> {
+  let child: ChildProcess | undefined;
+  let nextId = 1;
+  const pending = new Map<number, Pending>();
+  let stopped = false;
+
+  const start = async (): Promise<void> => {
+    const proc = spawn(entry, [], { stdio: ["pipe", "pipe", "pipe"], env });
+    child = proc;
+    let buffered = "";
+    proc.stdout!.on("data", (chunk: Buffer) => {
+      buffered += chunk.toString("utf8");
+      let at: number;
+      while ((at = buffered.indexOf("\n")) >= 0) {
+        const line = buffered.slice(0, at).trim();
+        buffered = buffered.slice(at + 1);
+        if (!line) continue;
+        let reply: { id?: number; result?: unknown; error?: { message?: string } };
+        try {
+          reply = JSON.parse(line);
+        } catch {
+          console.log(`[mesh-tools] ${module}'s bundle said something that is not a reply: ${line.slice(0, 120)}`);
+          continue;
+        }
+        const waiting = typeof reply.id === "number" ? pending.get(reply.id) : undefined;
+        if (!waiting) continue;
+        pending.delete(reply.id!);
+        clearTimeout(waiting.timer);
+        if (reply.error) waiting.reject(new Error(reply.error.message ?? "the bundle refused the request"));
+        else waiting.resolve(reply.result);
+      }
+    });
+    // stderr is the bundle's log; kept under the module's name so a fault reads where it belongs.
+    proc.stderr!.on("data", (chunk: Buffer) => {
+      for (const line of chunk.toString("utf8").split("\n")) if (line.trim()) console.log(`[${module}] ${line}`);
+    });
+    const exited = new Promise<never>((_, reject) => {
+      proc.once("error", (err) => reject(err));
+      proc.once("exit", (code, signal) => {
+        const why = `${module}'s bundle exited (${signal ?? code})`;
+        for (const [id, p] of pending) {
+          pending.delete(id);
+          clearTimeout(p.timer);
+          p.reject(new Error(why));
+        }
+        if (child === proc) child = undefined;
+        if (!stopped) console.log(`[mesh-tools] ${why}; started again on its next call`);
+        reject(new Error(why));
+      });
+    });
+    const ask = (method: string, params: unknown, ms: number): Promise<any> =>
+      Promise.race([
+        new Promise<any>((resolve, reject) => {
+          const id = nextId++;
+          const timer = setTimeout(() => {
+            pending.delete(id);
+            reject(new Error(`${module}'s bundle did not answer ${method} in ${ms / 1000}s`));
+          }, ms);
+          pending.set(id, { resolve, reject, timer });
+          proc.stdin!.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+        }),
+        exited,
+      ]);
+    exited.catch(() => {}); // observed through the race; never unhandled
+    (proc as ChildProcess & { ask?: typeof ask }).ask = ask;
+    await ask("initialize", { protocolVersion: PROTOCOL, capabilities: {}, clientInfo: { name: "node-tools", version: "1" } }, HANDSHAKE_MS);
+    proc.stdin!.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) + "\n");
+  };
+
+  const asking = async (method: string, params: unknown, ms: number): Promise<any> => {
+    if (!child) await start();
+    return (child as ChildProcess & { ask: (m: string, p: unknown, ms: number) => Promise<any> }).ask(method, params, ms);
+  };
+
+  await start();
+  const listed = (await asking("tools/list", {}, HANDSHAKE_MS)) as { tools?: { name: string; description?: string; inputSchema?: unknown }[] };
+  const groups = new Map<string, ToolDefinition[]>();
+  for (const t of listed.tools ?? []) {
+    const dot = t.name.indexOf(".");
+    const under = dot < 0 ? module : t.name.slice(0, dot);
+    const name = dot < 0 ? t.name : t.name.slice(dot + 1);
+    const tools = groups.get(under) ?? [];
+    tools.push({
+      name,
+      description: t.description ?? "",
+      input: (t.inputSchema as Record<string, unknown> | undefined) ?? {},
+      run: async (args) => {
+        const result = (await asking("tools/call", { name: t.name, arguments: args ?? {} }, CALL_MS)) as {
+          content?: { type: string; text?: string }[];
+          isError?: boolean;
+        };
+        const text = result?.content?.find((c) => c.type === "text")?.text ?? "";
+        if (result?.isError) throw new Error(text || `${module}.${t.name} failed`);
+        // The bundle's answer is JSON as text (that is what every MCP host renders); handed back as
+        // the value it encodes so a caller on the bus sees what an in-process tool would return.
+        try {
+          return JSON.parse(text);
+        } catch {
+          return text;
+        }
+      },
+    });
+    groups.set(under, tools);
+  }
+  return {
+    registrations: [...groups].map(([under, tools]) => ({ module: under, tools })),
+    stop: () => {
+      stopped = true;
+      child?.kill("SIGTERM");
+      child = undefined;
+    },
+  };
+}

src/runtime.ts

@@ -15,6 +15,7 @@ import { useBroker } from "@novox/mesh-sdk/messaging";
 import { collectTools, toolKey, type ToolDefinition } from "@novox/mesh-sdk/tools";
 import type { Broker } from "@novox/mesh-sdk/messaging";
 import { atWork, seatToolSubject, type Credential, type RuntimeBroker } from "./broker-nats.js";
+import { launch, launches } from "./launch.js";
 
 /**
  * The one verb every module's runtime answers for it (novox/hq ADR 0152, design 34 §3): the
@@ -106,20 +107,31 @@ export async function runTools(opts: RuntimeOptions): Promise<() => void> {
   // Importing the entrypoint runs its registerModuleTools(...) — that is the whole handshake — and
   // the registrations it adds are the ones that appear after it, which is how each is attributed
   // to the module whose bundle made it.
+  // A bundle that is not plain JavaScript — or is marked executable — is launched as a process
+  // and spoken to over MCP on stdio instead (ADR 0187); what it lists is registered the same way.
   const failed = new Map<string, string>();
   const owner: string[] = []; // registration index → the module whose bundle registered it
+  const launched: { module: string; owner: string; tools: ToolDefinition[] }[] = [];
+  const children: Array<() => void> = [];
   for (const [module, entrypoints] of served) {
     for (const entry of entrypoints) {
-      const before = collectTools().length;
+      const path = resolve(entry);
       try {
-        await import(pathToFileURL(resolve(entry)).href);
+        if (launches(path)) {
+          const child = await launch(module, path);
+          children.push(child.stop);
+          for (const r of child.registrations) launched.push({ ...r, owner: module });
+          continue;
+        }
+        const before = collectTools().length;
+        await import(pathToFileURL(path).href);
+        const after = collectTools().length;
+        for (let i = before; i < after; i++) owner[i] = module;
       } catch (err) {
         const why = err instanceof Error ? err.message : String(err);
         failed.set(module, why);
         console.log(`[mesh-tools] ${module}'s bundle ${entry} failed to load: ${why}; its tools are not served here`);
       }
-      const after = collectTools().length;
-      for (let i = before; i < after; i++) owner[i] = module;
     }
   }
 
@@ -131,14 +143,17 @@ export async function runTools(opts: RuntimeOptions): Promise<() => void> {
   // out rather than fatal — on 2026-10-01 the credential of a module that had just learned to
   // implement a seat did not yet name the claim, and the whole runtime restarted for it.
   const claimed = seatsClaimed(served.keys(), self, opts.credential, runtime);
-  const registrations = collectTools().map((r, i) => ({ ...r, owner: owner[i] ?? self ?? r.module }));
+  const registrations = [
+    ...collectTools().map((r, i) => ({ ...r, owner: owner[i] ?? self ?? r.module })),
+    ...launched,
+  ];
   const ownRegistrations = registrations.filter(({ module, owner: by }) => {
     if (served.has(module)) return true;
     if (claimed.has(module)) return false;
     console.log(`[mesh-tools] ${by} registers tools under "${module}", which is neither a module served here nor a seat one of them claims; not served until the mesh issues the claim`);
     return false;
   });
-  const stops: Array<() => void> = [];
+  const stops: Array<() => void> = [...children];
   const stop = (): void => stops.splice(0).forEach((s) => s());
 
   // Refused before anything is bound if a module named a tool of its own `tools`: one name

test/fixtures/many-delta.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+# A tools bundle in a second language (novox/hq ADR 0187): MCP over stdio, no SDK, no dependencies.
+# One tool of its own, one seat verb, and one that exits the process mid-call.
+import json, sys
+
+def say(m):
+    m["jsonrpc"] = "2.0"; sys.stdout.write(json.dumps(m) + "\n"); sys.stdout.flush()
+
+TOOLS = [
+    {"name": "greet", "description": "say hello", "inputSchema": {"type": "object", "properties": {"who": {"type": "string"}}}},
+    {"name": "node-lamp.on", "description": "the seat's verb", "inputSchema": {"type": "object", "properties": {}}},
+    {"name": "die", "description": "exit without answering", "inputSchema": {"type": "object", "properties": {}}},
+]
+for line in sys.stdin:
+    req = json.loads(line); rid = req.get("id"); m = req.get("method"); p = req.get("params") or {}
+    if m == "initialize":
+        say({"id": rid, "result": {"protocolVersion": "2025-03-26", "capabilities": {"tools": {}}, "serverInfo": {"name": "delta", "version": "1"}}})
+    elif m == "tools/list":
+        say({"id": rid, "result": {"tools": TOOLS}})
+    elif m == "tools/call":
+        name = p.get("name"); args = p.get("arguments") or {}
+        if name == "greet":
+            say({"id": rid, "result": {"content": [{"type": "text", "text": json.dumps({"greeting": "hello " + args.get("who", "world"), "language": "python"})}]}})
+        elif name == "node-lamp.on":
+            say({"id": rid, "result": {"content": [{"type": "text", "text": json.dumps({"on": True, "language": "python"})}]}})
+        elif name == "die":
+            print("delta: told to die", file=sys.stderr); sys.exit(3)
+        else:
+            say({"id": rid, "error": {"code": -32602, "message": "no such tool"}})

test/fixtures/many-epsilon.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// A TypeScript bundle written against the protocol and marked executable: served through the
+// launcher like any other language, with the in-process shortcut off (novox/hq ADR 0187).
+import { serveStdio } from "@novox/mesh-sdk/stdio";
+
+await serveStdio("epsilon", [
+  { name: "seven", description: "epsilon's", input: {}, run: async () => ({ epsilon: 7, via: "stdio" }) },
+]);

test/node-runtime.test.ts

@@ -91,7 +91,7 @@ test("MESH_TOOL_MODULES names modules and their entrypoints; a bare path is the
   assert.deepEqual(servedModulesFrom("", "x"), { serves: [], moduleEntrypoints: [] });
 });
 
-test("the node's runtime serves three modules' bundles on one credential, names the one that fails, and follows a re-issued membership", async (t) => {
+test("the node's runtime serves five modules' bundles on one credential — two of them launched, one broken — and follows a re-issued membership", async (t) => {
   if (!url) return t.skip("MESH_TEST_NATS unset");
   resetTools();
   const mesh = await aMesh();
@@ -100,6 +100,10 @@ test("the node's runtime serves three modules' bundles on one credential, names
   await mesh.issue(membershipOf("alpha", "anchor", { plain: true }));
   await mesh.issue(membershipOf("beta", "anchor", { seats: { "node-shelf": ["list", "clear"] } }));
   await mesh.issue(membershipOf("gamma", "anchor"));
+  // Two more, launched rather than loaded (ADR 0187): delta is Python and holds the node-lamp seat;
+  // epsilon is TypeScript written against the protocol and marked executable.
+  await mesh.issue(membershipOf("delta", "anchor", { seats: { "node-lamp": ["on"] } }));
+  await mesh.issue(membershipOf("epsilon", "anchor"));
   // The node's credential: the runtime module's name, no claims (seats come from the memberships).
   const credential = { url, node: "anchor", module: "node-tools" };
   const nodeTools = await connectNats(credential);
@@ -118,13 +122,15 @@ test("the node's runtime serves three modules' bundles on one credential, names
         { module: "alpha", entrypoints: [fixture("many-alpha.mjs")] },
         { module: "beta", entrypoints: [fixture("many-beta.mjs")] },
         { module: "gamma", entrypoints: [fixture("many-broken.mjs")] },
+        { module: "delta", entrypoints: [fixture("many-delta.py")] },
+        { module: "epsilon", entrypoints: [fixture("many-epsilon.mjs")] },
       ],
     });
     console.log = log;
-    assert.deepEqual(nodeTools.serving().sort(), ["alpha", "beta", "gamma", "node-tools"]);
+    assert.deepEqual(nodeTools.serving().sort(), ["alpha", "beta", "delta", "epsilon", "gamma", "node-tools"]);
     assert.ok(said.some((s) => /the operator's account here is somebody \(home \/home\/somebody\)/.test(s)), said.join("\n"));
     assert.ok(said.some((s) => /gamma's bundle .*many-broken\.mjs failed to load: gamma's bundle cannot find its client; its tools are not served here/.test(s)), said.join("\n"));
-    assert.ok(said.some((s) => /serving 5 tool\(s\) for 3 module\(s\): alpha\.one, alpha\.two, beta\.three, beta\.four, beta\.five; not serving gamma/.test(s)), said.join("\n"));
+    assert.ok(said.some((s) => /serving 8 tool\(s\) for 5 module\(s\): alpha\.one, alpha\.two, beta\.three, beta\.four, beta\.five, delta\.greet, delta\.die, epsilon\.seven; not serving gamma/.test(s)), said.join("\n"));
 
     // Five tools answer, each where its module's membership says: alpha anywhere and here, beta here only.
     assert.deepEqual((await callTool(asker, "alpha.one", {})).result, { alpha: 1 });
@@ -138,6 +144,15 @@ test("the node's runtime serves three modules' bundles on one credential, names
     assert.deepEqual((await callTool(asker, "seat:node-shelf.list@anchor", {})).result, { shelf: ["a", "b"] });
     assert.deepEqual((await callTool(asker, "seat:node-shelf.clear@anchor", {})).result, { cleared: true });
 
+    // A bundle in another language answers the same way, its seat verb among them; so does a
+    // TypeScript bundle served through the protocol rather than imported.
+    assert.deepEqual((await callTool(asker, "delta.greet@anchor", { who: "mesh" })).result, { greeting: "hello mesh", language: "python" });
+    assert.deepEqual((await callTool(asker, "seat:node-lamp.on@anchor", {})).result, { on: true, language: "python" });
+    assert.deepEqual((await callTool(asker, "epsilon.seven@anchor", {})).result, { epsilon: 7, via: "stdio" });
+    // A child that exits mid-call tells the caller so and is started again on the next call.
+    await assert.rejects(callTool(asker, "delta.die@anchor", {}), /delta's bundle exited \(3\)/);
+    assert.deepEqual((await callTool(asker, "delta.greet@anchor", {})).result, { greeting: "hello world", language: "python" });
+
     // A tool that emits does so as its module, not as the runtime.
     const landed = mesh.nextEvent("mesh.mod.*.event.>");
     assert.deepEqual((await callTool(asker, "alpha.two", {})).result, { alpha: 2 });
@@ -152,10 +167,10 @@ test("the node's runtime serves three modules' bundles on one credential, names
 
     // And discovery says so, with the reason, beside the modules that answered.
     const catalogue = await connectNats({ url, module: "mesh-catalog" });
-    await catalogue.handle("catalog_modules", async () => ({ modules: [{ module: "alpha" }, { module: "beta" }, { module: "gamma" }] }));
+    await catalogue.handle("catalog_modules", async () => ({ modules: [{ module: "alpha" }, { module: "beta" }, { module: "gamma" }, { module: "delta" }, { module: "epsilon" }] }));
     try {
       const have = await toolsOn(asker);
-      assert.deepEqual(have.tools.map((x) => `${x.module}.${x.name}`), ["alpha.one", "alpha.two", "beta.five", "beta.four", "beta.three"]);
+      assert.deepEqual(have.tools.map((x) => `${x.module}.${x.name}`), ["alpha.one", "alpha.two", "beta.five", "beta.four", "beta.three", "delta.die", "delta.greet", "epsilon.seven"]);
       assert.deepEqual(have.notAnswering, ["gamma (its tools bundle failed to load: gamma's bundle cannot find its client)", "mesh-controller (seat)"]);
     } finally {
       await catalogue.close();