diff --git a/package.json b/package.json index 7c04aa6..6e420bb 100644 --- a/package.json +++ b/package.json @@ -4,11 +4,13 @@ "description": "The Novox Mesh tool runtime \u2014 binds the mesh broker and serves the assigned modules' tools.", "type": "module", "bin": { - "mesh-tools": "./dist/main.js" + "mesh-tools": "./dist/main.js", + "mesh": "./dist/mesh.js" }, "scripts": { "build": "tsc", - "test": "node --test --experimental-strip-types 'test/*.test.ts'" + "pretest": "tsc", + "test": "node --test --test-concurrency=1 --experimental-strip-types 'test/*.test.ts'" }, "dependencies": { "@novox/mesh-sdk": "^0.1.0", diff --git a/src/client.ts b/src/client.ts new file mode 100644 index 0000000..cbbdf43 --- /dev/null +++ b/src/client.ts @@ -0,0 +1,125 @@ +/** + * A person's client: the mesh's tools from a workstation (novox/hq design 25 §7). + * + * Two surfaces over one thing. A command line, for somebody at a terminal; an MCP server, for an + * agent. Both are adapters over the same three calls — what tools are there, what does this one take, + * call it — because a second way of reaching a tool is a second thing to keep correct. + * + * **It uses the same client a module's runtime uses.** Not a second protocol and not a bridge: a + * person connects as their own bus user, publishes on the tool subjects their account permits, and the + * server refuses anything else. So "what may this person do" is answered by the same permission list + * that answers it for a module, and there is nothing here for an audit to read separately. + * + * What a person may NOT do is the more interesting half, and none of it is enforced here — it is the + * account (design 25 §4): they cannot publish an event, so they cannot claim a module said something; + * they have no consumer, so there is no delivery to acknowledge; and they cannot answer a request, so + * they cannot impersonate a module on a bus where anyone may serve a tool. + */ +import { readFile } from "node:fs/promises"; + +import type { Broker } from "@novox/mesh-sdk/messaging"; + +import { connectNats, type Credential } from "./broker-nats.js"; + +/** Where the catalogue answers what tools the mesh has. */ +const CATALOGUE_TOOLS = "mesh-catalog.catalog_tools"; + +/** A tool as the catalogue describes one. */ +export interface Tool { + module: string; + name: string; + description?: string; + /** The JSON schema of what it takes, as the module declared it. */ + input?: unknown; +} + +/** + * A person's credential, as `operator issue` prints it. + * + * The same shape a module is handed, minus the parts a module needs and a person does not: no node, + * because a person is not on a machine, and no module, because they are not one. + */ +export interface PersonCredential extends Credential { + person?: string; + invokes?: string[]; +} + +/** Read the credential from the file `operator issue` produced. */ +export async function credentialFrom(path: string): Promise { + const raw = await readFile(path, "utf8"); + let held: PersonCredential; + try { + held = JSON.parse(raw) as PersonCredential; + } catch (e) { + throw new Error( + `${path} is not a credential this mesh issued: ${(e as Error).message}. ` + + "It is the JSON `operator issue` printed, saved verbatim.", + ); + } + if (!held.url || !held.user || !held.password) { + throw new Error( + `${path} names no bus, user or password. It is the JSON \`operator issue\` printed, saved ` + + "verbatim — not an edited copy of it.", + ); + } + return held; +} + +/** Connect as this person. The module name the runtime wants is their own user, because every subject + * it derives is for a tool somebody else serves. */ +export async function connectAs(held: PersonCredential): Promise { + return connectNats({ ...held, module: held.user }); +} + +/** + * What tools the mesh has, asked of the catalogue. + * + * **Asked, not configured.** The catalogue is the only thing that knows what is installed, and a + * client carrying its own list would be a list that goes stale the first time a module is assigned — + * silently, because a tool that is not offered looks exactly like a tool that does not exist. + */ +export async function toolsOn(bus: Broker): Promise { + const answered = await bus.request, { tools?: Tool[] } | Tool[]>( + CATALOGUE_TOOLS, + {}, + ); + const tools = Array.isArray(answered) ? answered : (answered.tools ?? []); + return tools + .slice() + .sort((a: Tool, b: Tool) => `${a.module}.${a.name}`.localeCompare(`${b.module}.${b.name}`)); +} + +/** Call one tool. The key is `.`, which is what a person types and what their account + * permits — one vocabulary, so a refusal names the thing they asked for. */ +export async function callTool(bus: Broker, key: string, args: unknown): Promise { + if (!key.includes(".")) { + throw new Error( + `"${key}" does not name a tool: write ., as \`mesh tools\` lists them`, + ); + } + return bus.request(key, args ?? {}); +} + +/** + * Why a call failed, said so that the remedy is in the words. + * + * Three answers a person actually gets, and they need different things done: nobody serves that tool, + * the mesh refused this person, or the tool itself failed. Without this they are one timeout and a + * stack trace. + */ +export function whyItFailed(key: string, err: unknown): string { + const message = err instanceof Error ? err.message : String(err); + if (/no responders|503/i.test(message)) { + return `nothing serves ${key}. The module may not be assigned to any machine, or it is down — ` + + "`mesh tools` lists what the catalogue says is there."; + } + if (/permissions violation|authorization/i.test(message)) { + return `this credential may not call ${key}. What it may call was fixed when it was issued; ` + + "`operator issue` again with the tool named, or ask somebody who can."; + } + if (/timeout/i.test(message)) { + return `${key} did not answer in time. Something is serving it, so this is the tool being slow ` + + "rather than absent."; + } + return `${key} failed: ${message}`; +} diff --git a/src/mcp.ts b/src/mcp.ts new file mode 100644 index 0000000..f512753 --- /dev/null +++ b/src/mcp.ts @@ -0,0 +1,139 @@ +/** + * The mesh's tools as an MCP server, over stdio (novox/hq design 25 §7). + * + * **A thin adapter and nothing more.** Every tool an agent sees is one the catalogue listed and one + * this credential may call; the schema is the module's own; the answer is the module's own. Nothing + * here decides anything, which is why it is short — an MCP surface that reshaped arguments or + * summarised answers would be a second definition of what a tool is, and the module's manifest is the + * first. + * + * Implemented against the protocol directly rather than through a library: the surface is three + * methods and one framing, and a dependency here would be a dependency on every workstation. + */ +import type { Broker } from "@novox/mesh-sdk/messaging"; + +import { callTool, toolsOn, whyItFailed, type Tool } from "./client.js"; + +/** The protocol version this speaks. Stated, because a host that wants another should be told so + * rather than discovering it through a shape it did not expect. */ +const PROTOCOL = "2024-11-05"; + +interface Request { + jsonrpc: string; + id?: number | string | null; + method: string; + params?: Record; +} + +/** + * Serve until stdin closes, which is how a host ends a session. + * + * The tool list is fetched once, on the first `tools/list`, and kept. An agent asks for it repeatedly + * and the catalogue's answer does not change mid-session; refetching would make every turn cost a + * round trip to a module for something nobody changed. + */ +export async function serveMcp(bus: Broker, who: string): Promise { + let known: Tool[] | undefined; + + const say = (message: unknown) => { + process.stdout.write(`${JSON.stringify(message)}\n`); + }; + const answer = (id: Request["id"], result: unknown) => say({ jsonrpc: "2.0", id, result }); + const refuse = (id: Request["id"], code: number, message: string) => + say({ jsonrpc: "2.0", id, error: { code, message } }); + + for await (const line of lines()) { + let request: Request; + try { + request = JSON.parse(line) as Request; + } catch { + // Unparseable, and with no id there is nobody to tell. Skipped rather than answered, because a + // reply to a request that was never framed is noise on the same channel. + continue; + } + // A notification has no id and expects no answer; `initialized` is the one every host sends. + const notification = request.id === undefined || request.id === null; + + switch (request.method) { + case "initialize": + answer(request.id, { + protocolVersion: PROTOCOL, + capabilities: { tools: {} }, + serverInfo: { name: "mesh", version: "1" }, + // Said in the handshake, because an agent that knows whose authority it is acting under can + // say so when a call is refused — and a refusal is the one thing here that is not the + // mesh's fault or the tool's. + instructions: + `These are the tools of a Novox mesh, reached as ${who}. Every call goes to the module ` + + `that serves it; what may be called was fixed when this credential was issued, so a ` + + `refusal means the credential, not the tool.`, + }); + break; + + case "notifications/initialized": + break; + + case "tools/list": { + try { + known ??= await toolsOn(bus); + } catch (e) { + refuse(request.id, -32603, whyItFailed("mesh-catalog.catalog_tools", e)); + break; + } + answer(request.id, { + tools: known.map((t) => ({ + name: `${t.module}.${t.name}`, + description: t.description ?? `${t.name}, served by ${t.module}`, + // The module's own schema, passed through. An empty object is a tool that takes nothing, + // which is a real answer and not a missing one. + inputSchema: t.input ?? { type: "object", properties: {} }, + })), + }); + break; + } + + case "tools/call": { + const name = String(request.params?.name ?? ""); + const args = request.params?.arguments ?? {}; + try { + const result = await callTool(bus, name, args); + // Text, because that is what every host renders. The content is the module's answer as + // JSON, unshaped: an adapter that flattened it would be deciding what matters in somebody + // else's answer. + answer(request.id, { + content: [{ type: "text", text: JSON.stringify(result, null, 2) }], + }); + } catch (e) { + // **An error the agent can act on, not a stack.** isError rather than a protocol failure, + // because the call was well-formed and the mesh answered it — with a refusal, an absence or + // a fault, and the words say which. + answer(request.id, { + content: [{ type: "text", text: whyItFailed(name, e) }], + isError: true, + }); + } + break; + } + + default: + if (!notification) { + refuse(request.id, -32601, `mesh's MCP surface has no ${request.method}`); + } + } + } +} + +/** stdin as newline-framed messages, which is what MCP over stdio is. */ +async function* lines(): AsyncGenerator { + let buffered = ""; + for await (const chunk of process.stdin) { + buffered += (chunk as Buffer).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 !== "") yield line; + } + } + if (buffered.trim() !== "") yield buffered.trim(); +} diff --git a/src/mesh.ts b/src/mesh.ts new file mode 100644 index 0000000..013df0b --- /dev/null +++ b/src/mesh.ts @@ -0,0 +1,145 @@ +#!/usr/bin/env node +/** + * `mesh` — the mesh's tools from a workstation, for a person (novox/hq design 25 §7). + * + * Three verbs and nothing else. What tools are there, call one, and serve the same two to an agent + * over MCP. Deliberately thin: everything that could be a decision is one the mesh already made, and a + * client that grew opinions would be a second place the mesh's behaviour is defined. + * + * mesh tools what this credential may call + * mesh call . [json] call one, arguments as JSON on the command line or on stdin + * mesh mcp the same, as an MCP server over stdio + * + * The credential comes from MESH_CREDENTIAL, or --credential. It is the JSON `operator issue` printed. + */ +import { readFile } from "node:fs/promises"; + +import { callTool, connectAs, credentialFrom, toolsOn, whyItFailed, type Tool } from "./client.js"; +import { serveMcp } from "./mcp.js"; + +const usage = `mesh tools +mesh call . [json] +mesh mcp + + --credential the JSON \`operator issue\` printed; default $MESH_CREDENTIAL`; + +async function main(argv: string[]): Promise { + const args = [...argv]; + let credentialPath = process.env.MESH_CREDENTIAL ?? ""; + for (let i = 0; i < args.length; i++) { + if (args[i] === "--credential") { + credentialPath = args[i + 1] ?? ""; + args.splice(i, 2); + i--; + } + } + const verb = args.shift(); + if (!verb || verb === "help" || verb === "--help") { + console.log(usage); + return verb ? 0 : 1; + } + if (!credentialPath) { + console.error( + "no credential: set MESH_CREDENTIAL or pass --credential . It is the JSON " + + "`operator issue` printed, saved verbatim.", + ); + return 1; + } + + const held = await credentialFrom(credentialPath); + const bus = await connectAs(held); + try { + switch (verb) { + case "tools": + return await listing(bus, held.person); + case "call": + return await calling(bus, args); + case "mcp": + // Serves until stdin closes, which is how an MCP host ends a session. + await serveMcp(bus, held.person ?? held.user ?? "somebody"); + return 0; + default: + console.error(`mesh has no "${verb}".\n\n${usage}`); + return 1; + } + } finally { + await bus.close(); + } +} + +async function listing(bus: Awaited>, who?: string): Promise { + let tools: Tool[]; + try { + tools = await toolsOn(bus); + } catch (e) { + console.error(whyItFailed("mesh-catalog.catalog_tools", e)); + return 1; + } + if (tools.length === 0) { + console.log("the catalogue lists no tools; nothing on this mesh serves any"); + return 0; + } + // **What the catalogue has, not what this credential may call.** The two differ and the difference + // is the point: a person seeing only their own tools cannot tell "not installed" from "not yours", + // and those need different people to fix them. + for (const t of tools) { + const name = `${t.module}.${t.name}`; + console.log(t.description ? `${name.padEnd(36)} ${t.description}` : name); + } + if (who) { + console.log(`\nthis is what the mesh has. What ${who} may call was fixed when the credential was issued.`); + } + return 0; +} + +async function calling( + bus: Awaited>, + args: string[], +): Promise { + const key = args.shift(); + if (!key) { + console.error("mesh call . [json]"); + return 1; + } + const raw = args.length > 0 ? args.join(" ") : await maybeStdin(); + let parsed: unknown = {}; + if (raw.trim() !== "") { + try { + parsed = JSON.parse(raw); + } catch (e) { + console.error(`the arguments are not JSON: ${(e as Error).message}`); + return 1; + } + } + try { + const answer = await callTool(bus, key, parsed); + console.log(JSON.stringify(answer, null, 2)); + return 0; + } catch (e) { + console.error(whyItFailed(key, e)); + return 1; + } +} + +/** Arguments on stdin, for a call whose JSON is too long or too quoted to type. Empty when stdin is a + * terminal, so `mesh call x.y` with no arguments does not hang waiting for something nobody is + * typing. */ +async function maybeStdin(): Promise { + if (process.stdin.isTTY) return ""; + const chunks: Buffer[] = []; + for await (const chunk of process.stdin) chunks.push(chunk as Buffer); + return Buffer.concat(chunks).toString("utf8"); +} + +// Only when run, so a test can import the pieces. +if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) { + main(process.argv.slice(2)) + .then((code) => process.exit(code)) + .catch((e) => { + console.error(e instanceof Error ? e.message : String(e)); + process.exit(1); + }); +} + +export { main, usage }; +export const _readFile = readFile; diff --git a/test/client.test.ts b/test/client.test.ts new file mode 100644 index 0000000..ca2e4aa --- /dev/null +++ b/test/client.test.ts @@ -0,0 +1,105 @@ +/** + * A person's client, against a real bus. + * + * What is worth checking is not that a request/reply works — the runtime's own tests cover that — but + * that the two surfaces are the same thing. An agent and a person must see the same tools and get the + * same answers, or the MCP surface becomes a second definition of what a tool is. + * + * docker run -d --rm --name t -p 14232:4222 nats:2.10-alpine -js + * MESH_TEST_NATS=nats://127.0.0.1:14232 node --test --experimental-strip-types test/client.test.ts + */ +import assert from "node:assert/strict"; +import { test } from "node:test"; + +// The built output, not the source: the client imports its siblings as `.js`, which is what ships and +// what every other file here does, and cannot be loaded as TypeScript directly. `pretest` builds. +import { connectNats } from "../dist/broker-nats.js"; +import { callTool, toolsOn, whyItFailed } from "../dist/client.js"; + +const url = process.env.MESH_TEST_NATS; + +/** A module serving the catalogue's tool list and one tool of its own, so the client has a mesh to + * talk to. Two connections, because a person and a module are different users even in a test. */ +async function aMeshWithTools() { + const catalogue = await connectNats({ url: url!, module: "mesh-catalog" }); + const shop = await connectNats({ url: url!, module: "shop" }); + await catalogue.handle("catalog_tools", async () => ({ + tools: [ + { module: "shop", name: "price", description: "what something costs", input: { type: "object" } }, + { module: "mesh-catalog", name: "catalog_tools", description: "what tools the mesh has" }, + ], + })); + await shop.handle("price", async (body: { of?: string }) => ({ of: body.of ?? "nothing", cost: 12 })); + return { + async close() { + await catalogue.close(); + await shop.close(); + }, + }; +} + +test("a person sees what the catalogue says the mesh has, sorted", async (t) => { + if (!url) return t.skip("MESH_TEST_NATS unset"); + const mesh = await aMeshWithTools(); + const person = await connectNats({ url, module: "person.ada" }); + try { + const tools = await toolsOn(person); + assert.deepEqual( + tools.map((x) => `${x.module}.${x.name}`), + ["mesh-catalog.catalog_tools", "shop.price"], + "the list is what the catalogue answered, in a stable order", + ); + } finally { + await person.close(); + await mesh.close(); + } +}); + +test("a person calls a tool and gets the module's own answer, unshaped", async (t) => { + if (!url) return t.skip("MESH_TEST_NATS unset"); + const mesh = await aMeshWithTools(); + const person = await connectNats({ url, module: "person.ada" }); + try { + const answer = await callTool(person, "shop.price", { of: "a hat" }); + assert.deepEqual(answer, { of: "a hat", cost: 12 }); + } finally { + await person.close(); + await mesh.close(); + } +}); + +test("a tool nobody serves says so at once, and says what to do about it", async (t) => { + if (!url) return t.skip("MESH_TEST_NATS unset"); + const person = await connectNats({ url: url!, module: "person.ada" }); + try { + const began = Date.now(); + await assert.rejects(() => callTool(person, "ghost.missing", {})); + // At once, not after the whole wait: "that module is down" and "that tool is slow" need + // different things done, and a timeout cannot tell them apart. + assert.ok(Date.now() - began < 5_000, "a tool nobody serves waited out the timeout"); + } finally { + await person.close(); + } +}); + +test("a name that is not . is refused before anything is sent", async (t) => { + if (!url) return t.skip("MESH_TEST_NATS unset"); + const person = await connectNats({ url: url!, module: "person.ada" }); + try { + await assert.rejects(() => callTool(person, "price", {}), /does not name a tool/); + } finally { + await person.close(); + } +}); + +test("each way a call fails says what to do about it", () => { + // The three answers a person actually gets. Without this they are one timeout and a stack trace, + // and the remedies are in three different places. + assert.match(whyItFailed("shop.price", new Error("no responders")), /nothing serves shop\.price/); + assert.match( + whyItFailed("shop.price", new Error("Permissions Violation for Publish")), + /may not call shop\.price/, + ); + assert.match(whyItFailed("shop.price", new Error("timeout")), /did not answer in time/); + assert.match(whyItFailed("shop.price", new Error("something else")), /something else/); +}); diff --git a/test/mcp.test.ts b/test/mcp.test.ts new file mode 100644 index 0000000..fca4b51 --- /dev/null +++ b/test/mcp.test.ts @@ -0,0 +1,124 @@ +/** + * The MCP surface, driven the way a host drives it. + * + * **The claim worth checking is that it is the same thing the command line is.** An agent and a + * person must see the same tools and get the same answers, or this becomes a second definition of what + * a tool is — which is exactly what a thin adapter is supposed to avoid. + * + * docker run -d --rm --name t -p 14232:4222 nats:2.10-alpine -js + * MESH_TEST_NATS=nats://127.0.0.1:14232 node --test --experimental-strip-types test/mcp.test.ts + */ +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { spawn } from "node:child_process"; + +import { connectNats } from "../dist/broker-nats.js"; + +const url = process.env.MESH_TEST_NATS; + +/** A module answering the catalogue's list and one tool, plus a credential file the client reads. */ +async function aMeshAndACredential(t: { after: (fn: () => Promise | void) => void }) { + const catalogue = await connectNats({ url: url!, module: "mesh-catalog" }); + const shop = await connectNats({ url: url!, module: "shop" }); + await catalogue.handle("catalog_tools", async () => ({ + tools: [{ module: "shop", name: "price", description: "what something costs" }], + })); + await shop.handle("price", async (body: { of?: string }) => ({ of: body.of ?? "nothing", cost: 12 })); + t.after(async () => { + await catalogue.close(); + await shop.close(); + }); + + const { mkdtemp, writeFile } = await import("node:fs/promises"); + const { join } = await import("node:path"); + const dir = await mkdtemp("/tmp/mesh-client-"); + const path = join(dir, "credential.json"); + await writeFile( + path, + JSON.stringify({ url, user: "person.ada", password: "x", person: "ada", invokes: ["shop.price"] }), + ); + return path; +} + +/** Drive `mesh mcp` over stdio and collect the replies, as a host would. */ +function driving(credential: string, requests: unknown[]): Promise[]> { + return new Promise((resolve, reject) => { + const child = spawn(process.execPath, ["dist/mesh.js", "mcp", "--credential", credential], { + stdio: ["pipe", "pipe", "pipe"], + }); + let out = ""; + let err = ""; + child.stdout.on("data", (d) => (out += d.toString())); + child.stderr.on("data", (d) => (err += d.toString())); + child.on("error", reject); + child.on("close", () => { + const replies = out + .split("\n") + .filter((l) => l.trim() !== "") + .map((l) => JSON.parse(l) as Record); + if (replies.length === 0 && err !== "") reject(new Error(err)); + else resolve(replies); + }); + for (const r of requests) child.stdin.write(`${JSON.stringify(r)}\n`); + child.stdin.end(); + }); +} + +test("a host initialises, lists the mesh's tools and calls one", async (t) => { + if (!url) return t.skip("MESH_TEST_NATS unset"); + const credential = await aMeshAndACredential(t); + + const replies = await driving(credential, [ + { jsonrpc: "2.0", id: 1, method: "initialize", params: {} }, + { jsonrpc: "2.0", method: "notifications/initialized" }, + { jsonrpc: "2.0", id: 2, method: "tools/list" }, + { jsonrpc: "2.0", id: 3, method: "tools/call", params: { name: "shop.price", arguments: { of: "a hat" } } }, + ]); + + const byId = new Map(replies.map((r) => [r.id, r])); + // A notification is answered with nothing, or a host waiting on ids sees a reply it cannot match. + assert.equal(replies.length, 3, `expected three replies, got ${JSON.stringify(replies)}`); + + const hello = byId.get(1)!.result; + assert.equal(hello.protocolVersion, "2024-11-05"); + assert.ok(hello.capabilities.tools, "a server offering no tools is not this one"); + assert.match(hello.instructions, /ada/, "the handshake says whose authority a call is made under"); + + const listed = byId.get(2)!.result.tools; + assert.equal(listed.length, 1); + assert.equal(listed[0].name, "shop.price", "a tool is named the way a person names it"); + assert.ok(listed[0].inputSchema, "a tool with no schema is one an agent cannot call"); + + const called = byId.get(3)!.result; + assert.ok(!called.isError, `the call failed: ${JSON.stringify(called)}`); + // The module's own answer, unshaped. An adapter that summarised it would be deciding what matters + // in somebody else's answer. + assert.deepEqual(JSON.parse(called.content[0].text), { of: "a hat", cost: 12 }); +}); + +test("a tool nobody serves comes back as an error the agent can act on", async (t) => { + if (!url) return t.skip("MESH_TEST_NATS unset"); + const credential = await aMeshAndACredential(t); + + const replies = await driving(credential, [ + { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "ghost.missing", arguments: {} } }, + ]); + const result = replies[0].result; + // isError, not a protocol failure: the call was well-formed and the mesh answered it — with an + // absence. A JSON-RPC error would tell the agent its request was malformed, which it was not. + assert.ok(result?.isError, `expected a tool error, got ${JSON.stringify(replies[0])}`); + assert.match(result.content[0].text, /nothing serves ghost\.missing/); +}); + +test("a method this surface does not have is refused, and a notification is not", async (t) => { + if (!url) return t.skip("MESH_TEST_NATS unset"); + const credential = await aMeshAndACredential(t); + + const replies = await driving(credential, [ + { jsonrpc: "2.0", id: 1, method: "resources/list" }, + { jsonrpc: "2.0", method: "notifications/cancelled" }, + ]); + assert.equal(replies.length, 1, "a notification was answered"); + assert.equal(replies[0].error.code, -32601); + assert.match(replies[0].error.message, /resources\/list/); +});