A person's client: the mesh's tools from a workstation

Design 25 §7's second item. Two surfaces over one thing — a command line for somebody
at a terminal, an MCP server for an agent — and both are adapters over the same three
calls: what tools are there, what does this one take, call it. A second way of reaching
a tool would be a second thing to keep correct.

It uses the client a module's runtime uses. Not a bridge and not a second protocol: a
person connects as their own bus user and publishes on the tool subjects their account
permits, so "what may this person do" is answered by the same permission list that
answers it for a module, and an audit has nothing separate to read.

`mesh tools` lists what the *catalogue* has, not what this credential may call. The two
differ and the difference is the point: somebody seeing only their own tools cannot tell
"not installed" from "not yours", and those need different people to fix them.

A failed call says which of three things happened, because the remedies are in three
different places: nobody serves that tool, this credential may not call it, or the tool
itself was slow. Without that they are one timeout and a stack trace.

The MCP surface decides nothing. The tool names are the ones a person types, the schemas
are the modules' own, and an answer is passed through unshaped — an adapter that
summarised somebody else's answer would be deciding what matters in it. A tool that fails
comes back as a tool error rather than a protocol error, because the request was
well-formed and the mesh answered it.

Written against the protocol directly: it is three methods and one framing, and a
dependency here would be a dependency on every workstation.

Tests drive both surfaces against a real bus, including that a host's notification is
answered with nothing and an unknown method is refused. They run one file at a time,
because each stands up a module serving the same tool subjects and run together their
requests get split between them — which showed up as one test reading another's answer.

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<PersonCredential> {
+  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<Broker> {
+  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<Tool[]> {
+  const answered = await bus.request<Record<string, never>, { 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 `<module>.<tool>`, 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<unknown> {
+  if (!key.includes(".")) {
+    throw new Error(
+      `"${key}" does not name a tool: write <module>.<tool>, as \`mesh tools\` lists them`,
+    );
+  }
+  return bus.request<unknown, unknown>(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}`;
+}