@nexusbloom/mcp-server 2.0.2 → 2.1.0

package/src/history.js

@@ -0,0 +1,285 @@
+/**
+ * Run history — a bounded, in-process record of what this server ran.
+ *
+ * Two things it exists for:
+ *
+ * 1. **`diff`.** Comparing what a tool produced before and after a change is the
+ *    fastest way to see whether an edit actually changed behaviour, and it is
+ *    impossible without both sides captured.
+ * 2. **Self-correction.** An agent that has just seen three failed calls in a row
+ *    is guessing; being able to read the last few runs, with their inputs, turns
+ *    a guess into a comparison.
+ *
+ * Three constraints are deliberate:
+ *
+ * - **In memory, never on disk.** Run payloads are user data and frequently
+ *   secrets. Persisting them would create an unencrypted store nobody asked for;
+ *   losing history on restart costs nothing that the tool call itself did not.
+ * - **Bounded.** A ring buffer, so a long-lived server in a chat window cannot
+ *   grow without limit.
+ * - **Redacted inputs.** Anything whose key looks like a credential is masked
+ *   before it is stored, because history is readable by anything that can read
+ *   the conversation that produced it.
+ */
+
+import { NexusBloomError, ErrorCode } from "./errors.js";
+
+/** How many runs to keep. Oldest are dropped first. */
+export const MAX_HISTORY = 50;
+
+/**
+ * How much of a result to keep, in characters.
+ *
+ * Generous for the JSON a tool returns, small enough that fifty of them cannot
+ * exhaust a host's memory. Truncation is recorded rather than silent: a diff over
+ * a truncated payload says so, instead of reporting "no differences" because the
+ * tail is missing.
+ */
+export const MAX_PAYLOAD_CHARS = 8_000;
+
+/** Keys whose values are masked in stored inputs. */
+const SECRET_KEY = /(key|secret|token|password|passwd|passphrase|credential|auth|cookie|session)/i;
+
+/** Deepest level the differ walks. Beyond this, values compare as opaque. */
+const MAX_DIFF_DEPTH = 6;
+
+/** Maximum number of differences reported, so a whole-object change is not a wall. */
+const MAX_DIFF_ENTRIES = 200;
+
+/**
+ * A bounded run log.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.limit]      How many runs to keep.
+ * @param {number} [opts.maxPayload] Character cap per stored payload.
+ * @param {() => number} [opts.now]  Clock, injected so tests are deterministic.
+ */
+export class RunHistory {
+  constructor({ limit = MAX_HISTORY, maxPayload = MAX_PAYLOAD_CHARS, now = () => Date.now() } = {}) {
+    this.limit = limit;
+    this.maxPayload = maxPayload;
+    this.now = now;
+    this.runs = [];
+    this._nextId = 1;
+  }
+
+  /**
+   * Append one run and return its record.
+   *
+   * The id is per-process and monotonic rather than a timestamp, because ids
+   * have to be short, ordered and unguessable-by-accident when they are quoted
+   * back in a `diff`.
+   */
+  record({ tool, params, data, ok, durationMs, error, code, retryable, batch }) {
+    const payload = this._cap(data);
+    const entry = {
+      id: `r${this._nextId++}`,
+      tool,
+      ok: Boolean(ok),
+      at: new Date(this.now()).toISOString(),
+      durationMs: typeof durationMs === "number" ? durationMs : null,
+      batch: Boolean(batch),
+      params: redactParams(params),
+      result: payload.value,
+      truncated: payload.truncated,
+      ...(ok ? {} : { error: error || "Unknown error.", code: code || null, retryable: Boolean(retryable) }),
+    };
+
+    this.runs.push(entry);
+    if (this.runs.length > this.limit) this.runs.splice(0, this.runs.length - this.limit);
+    return entry;
+  }
+
+  /** Every record, oldest first. */
+  list() {
+    return this.runs.slice();
+  }
+
+  /** The most recent record, or null. */
+  latest() {
+    return this.runs.at(-1) || null;
+  }
+
+  /**
+   * Find a record by id, or by a fractional reference.
+   *
+   * "the last one" is a thing people and models both say, so `-1` means the most
+   * recent and `-2` the one before it. Without that, every diff of consecutive
+   * runs needs a lookup first, which is a turn wasted on arithmetic.
+   */
+  find(reference) {
+    if (reference === undefined || reference === null || reference === "") return null;
+    const ref = String(reference).trim();
+
+    const byId = this.runs.find((r) => r.id === ref);
+    if (byId) return byId;
+
+    if (/^-?\d+$/.test(ref)) {
+      const n = Number(ref);
+      if (n < 0) return this.runs.at(n) || null;
+      // A positive integer is also accepted as an id, since ids are numeric: only
+      // fall through to ordinal lookup when nothing matched as an id.
+      return null;
+    }
+    return null;
+  }
+
+  /** Most recent records, newest first — the order a reader wants them in. */
+  recent(n = 10) {
+    return this.runs.slice(-n).reverse();
+  }
+
+  /**
+   * Compare two stored runs.
+   *
+   * Compares the *results*, because that is what a change is supposed to alter.
+   * Inputs are reported alongside when they differ, since a result that changed
+   * because its input changed is not a regression at all — and conflating the two
+   * is how a diff gets dismissed as noise.
+   */
+  diff(fromRef, toRef) {
+    const from = this.find(fromRef);
+    const to = this.find(toRef);
+    const missing = [];
+    if (!from) missing.push(fromRef ?? "(none)");
+    if (!to) missing.push(toRef ?? "(none)");
+
+    if (missing.length) {
+      throw new NexusBloomError(
+        `No run recorded for ${missing.map((m) => `"${m}"`).join(" or ")}. ` +
+          `Known run ids: ${this.runs.map((r) => r.id).join(", ") || "(none yet)"}. ` +
+          `Pass an id like "${this.runs.at(-1)?.id ?? "r1"}", or -1 for the most recent.`,
+        ErrorCode.NOT_FOUND,
+      );
+    }
+
+    const changes = diffValues(from.result, to.result, "", 0);
+    return {
+      from: summariseRun(from),
+      to: summariseRun(to),
+      identical: changes.length === 0 && from.ok === to.ok,
+      inputsChanged: JSON.stringify(from.params) !== JSON.stringify(to.params),
+      changes,
+      ...(from.truncated || to.truncated ? { truncated: true } : {}),
+    };
+  }
+
+  /** Drop everything; used by tests and by a `history clear` command. */
+  clear() {
+    this.runs = [];
+  }
+
+  _cap(value) {
+    if (value === undefined) return { value: null, truncated: false };
+    let text;
+    try {
+      text = JSON.stringify(value) ?? "null";
+    } catch {
+      text = String(value);
+    }
+    if (text.length <= this.maxPayload) return { value, truncated: false };
+
+    // Truncate the serialised form rather than the object: a half-object would
+    // break the differ, and a marked string is honest about what is missing.
+    return { value: `${text.slice(0, this.maxPayload)}…[truncated]`, truncated: true };
+  }
+}
+
+/** Mask credential-shaped values, at any depth. */
+export function redactParams(params, depth = 0) {
+  if (depth > MAX_DIFF_DEPTH) return "[deep]";
+  if (Array.isArray(params)) return params.map((p) => redactParams(p, depth + 1));
+  if (params && typeof params === "object") {
+    const out = {};
+    for (const [key, value] of Object.entries(params)) {
+      out[key] = SECRET_KEY.test(key) && typeof value === "string" ? maskValue(value) : redactParams(value, depth + 1);
+    }
+    return out;
+  }
+  return params;
+}
+
+/**
+ * Mask a secret without leaking its length.
+ *
+ * Keeping the length would let someone confirm a guessed password, so a
+ * non-empty value collapses to a fixed marker.
+ */
+function maskValue(value) {
+  return value ? "[redacted]" : "";
+}
+
+/**
+ * Structural diff of two JSON-ish values.
+ *
+ * Reports a flat list of `{path, type, from, to}` rather than a nested tree: an
+ * agent reads a flat list correctly, and a tree invites it to summarise a
+ * subtree it never looked at.
+ */
+export function diffValues(a, b, path = "", depth = 0, out = []) {
+  if (out.length >= MAX_DIFF_ENTRIES) return out;
+  if (depth > MAX_DIFF_DEPTH) {
+    if (!Object.is(a, b)) out.push({ path: path || "(root)", type: "changed", from: a, to: b });
+    return out;
+  }
+
+  if (Object.is(a, b)) return out;
+
+  const bothObjects = isPlainObject(a) && isPlainObject(b);
+  const bothArrays = Array.isArray(a) && Array.isArray(b);
+
+  if (bothObjects) {
+    const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+    for (const key of keys) {
+      const childPath = path ? `${path}.${key}` : key;
+      const inA = key in a;
+      const inB = key in b;
+      if (inA && !inB) out.push({ path: childPath, type: "removed", from: a[key] });
+      else if (!inA && inB) out.push({ path: childPath, type: "added", to: b[key] });
+      else diffValues(a[key], b[key], childPath, depth + 1, out);
+      if (out.length >= MAX_DIFF_ENTRIES) return out;
+    }
+    return out;
+  }
+
+  if (bothArrays) {
+    const length = Math.max(a.length, b.length);
+    for (let i = 0; i < length; i++) {
+      const childPath = `${path}[${i}]`;
+      if (i >= a.length) out.push({ path: childPath, type: "added", to: b[i] });
+      else if (i >= b.length) out.push({ path: childPath, type: "removed", from: a[i] });
+      else diffValues(a[i], b[i], childPath, depth + 1, out);
+      if (out.length >= MAX_DIFF_ENTRIES) return out;
+    }
+    return out;
+  }
+
+  if (a === undefined) return out.push({ path: path || "(root)", type: "added", to: b });
+  if (b === undefined) return out.push({ path: path || "(root)", type: "removed", from: a });
+
+  // Different types is a replacement, not a field-level change: reporting it as
+  // one change per field would imply a shape the data never had.
+  if (typeof a !== typeof b || (Array.isArray(a) !== Array.isArray(b))) {
+    out.push({ path: path || "(root)", type: "changed", from: a, to: b });
+    return out;
+  }
+
+  out.push({ path: path || "(root)", type: "changed", from: a, to: b });
+  return out;
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/** The one-line description of a run, used in diffs and listings. */
+export function summariseRun(run) {
+  return {
+    id: run.id,
+    tool: run.tool,
+    ok: run.ok,
+    at: run.at,
+    durationMs: run.durationMs,
+    ...(run.ok ? {} : { error: run.error, code: run.code }),
+  };
+}

package/src/local.js

@@ -0,0 +1,164 @@
+/**
+ * Local execution — run a tool's published source instead of calling the API.
+ *
+ * **The threat model, stated plainly.** Executing a tool locally means executing
+ * code that arrived over the network. `@nexusbloom/core`'s sandbox is *isolation*,
+ * not a security sandbox: it gives the tool its own process, a hard kill on
+ * timeout, a heap cap, and no access to this process's stdout. It does **not**
+ * stop that code reading files, opening sockets, or spawning processes as the
+ * user running the host.
+ *
+ * So local execution is **off by default** and requires an explicit opt-in. That
+ * is not timidity: an MCP server is driven by whatever the model decides to ask
+ * for, so the default posture has to be the one where a surprising tool call
+ * cannot become arbitrary code execution on a developer's machine. An operator who
+ * turns it on is choosing that trade deliberately — typically for a self-hosted
+ * deployment publishing only their own tools, or to keep working while the API is
+ * unreachable.
+ *
+ * Three modes:
+ *   - `remote` (default) — always call the API. Nothing local is fetched.
+ *   - `local`  — always execute locally; a tool with no published source is an error.
+ *   - `auto`   — run locally when source is available, otherwise fall back to the API.
+ *
+ * `auto` is the useful middle: it degrades to remote for the handful of tools
+ * whose source is not published, instead of failing a call the API could serve.
+ */
+
+import { execInSandbox } from "@nexusbloom/core";
+
+import { NexusBloomError, ErrorCode } from "./errors.js";
+
+/**
+ * Largest source the server will hand to the sandbox.
+ *
+ * 2 MB is far above any real tool and well below anything that would stall the
+ * compiler. A cap is the cheapest defence against a hostile manifest trying to
+ * exhaust memory before execution even starts.
+ */
+export const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
+
+/** Heap ceiling for the tool process. Mirrors the CLI's default. */
+export const DEFAULT_MEMORY_MB = 256;
+
+/**
+ * Local-execution modes, as resolved from configuration.
+ *
+ * An unrecognised value falls back to `remote` rather than being honoured:
+ * a typo in a config variable should not silently switch on code execution.
+ */
+export function resolveExecutionMode(input) {
+  const value = (input || "").trim().toLowerCase();
+  return ["local", "auto", "remote"].includes(value) ? value : "remote";
+}
+
+/**
+ * Fetch a tool's runnable source.
+ *
+ * The API exposes it as `GET /run/<slug>?source=true`. Returns null when the tool
+ * has no published source, which is a normal state — not an error to report as
+ * one, because `auto` and `local` handle it differently.
+ */
+export async function fetchSource(client, slug) {
+  let body;
+  try {
+    body = await client.request(`/run/${encodeURIComponent(slug)}?source=true`);
+  } catch (err) {
+    // A failed source fetch is not a failed tool call: `auto` must still be able
+    // to fall back to the API rather than surfacing a transport error.
+    return null;
+  }
+
+  const source =
+    body?.data?.v2_source ??
+    body?.v2_source ??
+    body?.data?.source ??
+    body?.source ??
+    null;
+
+  if (typeof source !== "string" || !source.trim()) return null;
+  if (source.length > MAX_SOURCE_BYTES) return null;
+  return source;
+}
+
+/**
+ * Execute a tool locally and return the same shape `execute()` expects.
+ *
+ * @param {object} opts
+ * @param {import("./client.js").ApiClient} opts.client
+ * @param {string} opts.slug
+ * @param {object} opts.params
+ * @param {string} opts.mode       One of local | auto | remote.
+ * @param {object} opts.config
+ * @param {object} [opts.deps]     Injected for tests: { execInSandbox }.
+ * @returns {Promise<{executed: boolean, data?: any, error?: NexusBloomError, source?: string}>}
+ */
+export async function runLocal({ client, slug, params, mode = "remote", config, deps = {} }) {
+  if (mode === "remote") return { executed: false };
+
+  const exec = deps.execInSandbox ?? execInSandbox;
+  const source = await fetchSource(client, slug);
+
+  if (!source) {
+    if (mode === "local") {
+      throw new NexusBloomError(
+        `No runnable source is published for "${slug}", so it cannot run locally. ` +
+          `Set NEXUSBLOOM_MCP_EXECUTION=auto to fall back to the API for tools like this, ` +
+          `or remote to always call the API.`,
+        ErrorCode.NOT_FOUND,
+      );
+    }
+    return { executed: false };
+  }
+
+  // The tool's own timeout is the ceiling when it declares one: a tool that says
+  // it needs 30s should not be killed at the API's default, and a tool that says
+  // nothing gets the configured budget.
+  //
+  // `> 0` is load-bearing. config.js accepts 0 as "use the default", so a
+  // configured 0 can reach here; without this guard `Number.isFinite(0)` passes,
+  // the sandbox gets a zero-millisecond budget, and every local run is SIGKILLed
+  // before it produces a result — reported to the agent as a tool timeout rather
+  // than the misconfiguration it is.
+  const timeoutMs =
+    Number.isFinite(config?.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : 15_000;
+
+  const result = await exec({
+    source,
+    input: params ?? {},
+    timeoutMs,
+    memoryMb: deps.memoryMb ?? DEFAULT_MEMORY_MB,
+  });
+
+  if (!result?.ok) {
+    throw new NexusBloomError(
+      result?.timedOut
+        ? `Local execution of "${slug}" timed out after ${timeoutMs}ms and was killed.`
+        : result?.error || `Local execution of "${slug}" failed.`,
+      // A timeout is worth retrying; a tool error is the tool's own answer and is
+      // not — retrying it unchanged is exactly what the error guidance says not to do.
+      result?.timedOut ? ErrorCode.TIMEOUT : ErrorCode.API_ERROR,
+      { retryable: Boolean(result?.timedOut) },
+    );
+  }
+
+  return { executed: true, data: result.result, source };
+}
+
+/**
+ * The startup warning, written to stderr when local execution is enabled.
+ *
+ * Printed once at startup rather than per call: an operator who has opted in does
+ * not need the warning on every run, but the person debugging a host that hangs
+ * later absolutely needs to know it was on.
+ */
+export function localExecutionNotice(mode) {
+  if (mode === "remote") return "";
+  return (
+    `\nNexusBloom MCP: local execution is ENABLED (NEXUSBLOOM_MCP_EXECUTION=${mode}).\n` +
+    `Tool source is downloaded and executed on this machine in a child process. That isolates\n` +
+    `crashes, hangs and memory, but it does NOT sandbox the code: it runs with your user\n` +
+    `permissions and can read files and open network connections. Use remote execution for\n` +
+    `tools you do not trust.\n`
+  );
+}

package/src/progress.js

@@ -0,0 +1,88 @@
+/**
+ * Progress notifications.
+ *
+ * A batch of five tools can take fifteen seconds, and a host that shows nothing
+ * for fifteen seconds is a host the user interrupts. The protocol already has a
+ * channel for this — `notifications/progress`, keyed by the `progressToken` the
+ * client sent in `_meta` — but it is opt-in on both sides, so every detail here
+ * is about degrading quietly when it is absent.
+ *
+ * The rules that matter:
+ *
+ * - **No token, no notifications.** A client that does not send one has not asked
+ *   for progress, and unsolicited notifications are noise at best and a protocol
+ *   violation at worst.
+ * - **Progress is monotonic.** The spec requires it to increase; a host that
+ *   renders a percentage bar will go backwards if a report repeats a value.
+ * - **A failed notification never fails the call.** The report is diagnostics
+ *   about work already done. Losing one must not lose the result.
+ *
+ * No SDK import: the notification is a plain object, and the suite validates it
+ * against the SDK's own schema in test/progress.test.js rather than coupling
+ * this file to a transport.
+ */
+
+/**
+ * Build a progress reporter bound to one in-flight request.
+ *
+ * @param {object} deps
+ * @param {object} [deps.extra]        The SDK's per-request extra, which carries
+ *   `sendNotification` already associated with the originating request.
+ * @param {string|number} [deps.progressToken]  From `params._meta.progressToken`.
+ * @returns {{enabled: boolean, report: (progress: number, message?: string, total?: number) => Promise<void>}}
+ */
+export function createProgressReporter({ extra, progressToken } = {}) {
+  const token = progressToken ?? extra?._meta?.progressToken;
+  const send = typeof extra?.sendNotification === "function" ? extra.sendNotification.bind(extra) : null;
+
+  if (token === undefined || token === null || !send) {
+    return { enabled: false, report: async () => {} };
+  }
+
+  let last = -1;
+
+  return {
+    enabled: true,
+
+    /**
+     * Report progress. Never rejects.
+     *
+     * `progress` counts units done. When the total is unknown the spec allows a
+     * bare increasing number, which is why `total` is optional everywhere.
+     */
+    async report(progress, message, total) {
+      const value = Number.isFinite(progress) ? progress : 0;
+      // The spec requires progress to increase on every notification. Skipping a
+      // repeat keeps a host's percentage bar monotonic without adding work.
+      if (value <= last) return;
+      last = value;
+
+      try {
+        await send({
+          method: "notifications/progress",
+          params: {
+            progressToken: token,
+            progress: value,
+            ...(Number.isFinite(total) ? { total } : {}),
+            ...(message ? { message } : {}),
+          },
+        });
+      } catch {
+        // A dropped notification is not worth losing a completed run over.
+      }
+    },
+  };
+}
+
+/**
+ * Adapt a progress reporter to the callback shape the handlers take.
+ *
+ * Handlers stay transport-free by receiving a plain `onProgress({progress,
+ * message, total})` function; this is the only place that knows about the
+ * protocol, so a handler test can pass a plain function and assert the sequence.
+ */
+export function handlerProgress(reporter) {
+  if (!reporter?.enabled) return undefined;
+  return ({ progress, message, total } = {}) =>
+    reporter.report(progress ?? 0, message, total);
+}