From 1436b0275579c3963e945708a3044698362c4a2c Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 2 Oct 2026 21:24:20 +0200 Subject: [PATCH] A bundle that is not JavaScript is launched and spoken to over MCP on stdio (hq ADR 0187, to-be 38 WP1b) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 `.` 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 | 8 ++ src/launch.ts | 169 +++++++++++++++++++++++++++++++++ src/runtime.ts | 27 ++++-- test/fixtures/many-delta.py | 29 ++++++ test/fixtures/many-epsilon.mjs | 8 ++ test/node-runtime.test.ts | 25 ++++- 6 files changed, 255 insertions(+), 11 deletions(-) create mode 100644 src/launch.ts create mode 100755 test/fixtures/many-delta.py create mode 100755 test/fixtures/many-epsilon.mjs diff --git a/README.md b/README.md index e471085..f82b448 100644 --- a/README.md +++ b/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 `.` 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: diff --git a/src/launch.ts b/src/launch.ts new file mode 100644 index 0000000..83180c8 --- /dev/null +++ b/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 `.` 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 { + let child: ChildProcess | undefined; + let nextId = 1; + const pending = new Map(); + let stopped = false; + + const start = async (): Promise => { + 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((_, 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 => + Promise.race([ + new Promise((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 => { + if (!child) await start(); + return (child as ChildProcess & { ask: (m: string, p: unknown, ms: number) => Promise }).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(); + 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 | 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; + }, + }; +} diff --git a/src/runtime.ts b/src/runtime.ts index bda4a9f..4f0ce91 100644 --- a/src/runtime.ts +++ b/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(); 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 diff --git a/test/fixtures/many-delta.py b/test/fixtures/many-delta.py new file mode 100755 index 0000000..4ab229a --- /dev/null +++ b/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"}}) diff --git a/test/fixtures/many-epsilon.mjs b/test/fixtures/many-epsilon.mjs new file mode 100755 index 0000000..be23f22 --- /dev/null +++ b/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" }) }, +]); diff --git a/test/node-runtime.test.ts b/test/node-runtime.test.ts index 69bbd91..b9daecc 100644 --- a/test/node-runtime.test.ts +++ b/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();