agent-nuvira 3.4.0 → 3.5.0

package/dist/mcp/prereqs.d.ts

@@ -0,0 +1,145 @@
+/**
+ * MCP prerequisite probe — "what must exist before this server can run".
+ *
+ * WHY THIS EXISTS. The shipped catalog pinned npm specs that do not resolve
+ * (`docs/mcp-assessment.md` §2: 4 of 6 entries E404'd), and the install path
+ * could not tell a user why a server would never start: it wrote a config and
+ * reported success. A capability slot now offers several WAYS to run the same
+ * server (hosted remote, `npx`, a local binary, `uvx`, docker), and each way
+ * declares what it needs. This module answers — locally, without spawning
+ * anything — "on THIS machine, which of those ways can actually run, and what
+ * is missing from the others".
+ *
+ * Two rules keep it honest:
+ *   1. A probe never claims more than it checked. `command`/`env`/`file` are
+ *      verified here. A version requirement satisfied by an alternate runtime
+ *      binary is reported as PRESENT-BUT-UNVERIFIED (the version is established
+ *      by the MCP handshake at connect time, not by guessing at install).
+ *   2. Absence is never fatal by itself. The caller decides: the catalog shows
+ *      the gap, `install` refuses only when NO variant can run.
+ *
+ * THE DOCKER CASE — why `service` exists. A CLI binary on PATH is not the same
+ * as a working service. `docker` 29.7 was installed at /opt/homebrew/bin/docker
+ * on the dev machine while its daemon socket did not exist, so "docker is
+ * installed" was true and `docker run` still failed. A `command` prereq cannot
+ * express that, and a wrong "not installed" message sends the user to install
+ * something they already have. A `service` prereq names the binary AND the
+ * probe that must succeed (`docker info`), so the report can say exactly which
+ * half is missing. Running that probe EXECUTES a process, so it is opt-in
+ * (`deep`): the CLI asks for it at install time, unit tests never do.
+ *
+ * Hermetic by construction: PATH lookup + `process.env` reads only. No spawn,
+ * no network, no config write. Tests can inject `env`/`nodeVersion`.
+ */
+/** What a variant can require of the machine. */
+export type MCPPrereqKind = 
+/** A Node.js version floor, e.g. `>=20.18.1` — checked against `nodeVersion`. */
+'node'
+/** An executable that must be resolvable on PATH (npx, uvx, docker, a binary). */
+ | 'command'
+/**
+ * A background SERVICE behind a CLI: the binary must exist AND `check` must
+ * succeed (e.g. `docker info` — the daemon is reachable). Checked only in
+ * `deep` mode; a shallow probe reports it as present-but-unverified.
+ */
+ | 'service'
+/** An environment variable that must be set (a credential, an endpoint). */
+ | 'env'
+/** A file/directory that must exist (a local server entry point, a mount). */
+ | 'file';
+export interface MCPPrereq {
+    kind: MCPPrereqKind;
+    /**
+     * `command`/`env`/`file`: the name/path to look for.
+     * `node`: the literal `node` (the version lives in `minVersion`).
+     */
+    name: string;
+    /** `node` only — the minimum version, e.g. `20.18.1`. */
+    minVersion?: string;
+    /** `service` only — the command that must EXIT 0 for the service to count as up. */
+    check?: {
+        args: string[];
+        timeoutMs?: number;
+    };
+    /** What to install / set, in the user's words, shown BEFORE anything is enabled. */
+    hint: string;
+}
+/** A prerequisite whose binary exists but whose check failed (service down). */
+export interface MCPBlockedPrereq {
+    prereq: MCPPrereq;
+    /** What was observed, e.g. "daemon not reachable (Cannot connect to the Docker daemon)". */
+    reason: string;
+}
+/** The outcome of probing a variant's prerequisites. */
+export interface MCPPrereqStatus {
+    /** True when every prerequisite is satisfied — the variant can be started. */
+    ok: boolean;
+    /** The prerequisites that are not satisfied, in declaration order. */
+    missing: MCPPrereq[];
+    /**
+     * Requirements satisfied WITHOUT verification, with the reason. Today this is
+     * one case: a `node` floor met by an alternate runtime binary — the binary is
+     * present, its version is established by the handshake at connect time.
+     */
+    unverified: string[];
+    /**
+     * Requirements whose binary IS present but which still cannot work (a service
+     * that is down). Separate from `missing` because the fix is different: the user
+     * must START something, not install it.
+     */
+    blocked: MCPBlockedPrereq[];
+}
+export interface MCPProbeOptions {
+    /**
+     * Run the `service` checks (executes `check.args` against the named binary,
+     * bounded by `timeoutMs`). OFF by default so a unit test never spawns
+     * anything; the CLI turns it on for `catalog` / `install`.
+     */
+    deep?: boolean;
+    /** Environment to read (`process.env` by default; tests inject one). */
+    env?: NodeJS.ProcessEnv;
+    /** Node version to check against a `node` floor (defaults to this process). */
+    nodeVersion?: string;
+    /**
+     * An alternate runtime command declared by the variant (`runtime.command`).
+     * When set, a `node` floor is satisfied by the runtime's PRESENCE and the
+     * version check is reported as unverified rather than passed silently.
+     */
+    runtimeCommand?: string;
+}
+/**
+ * Compare two dotted versions. Returns <0 when `a` is older, 0 when equal,
+ * >0 when `a` is newer. Missing components count as 0, so `18` < `18.18`.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Is `command` runnable? An absolute or relative path is checked directly; a
+ * bare name is looked up on PATH (honouring PATHEXT on Windows). Executability
+ * is verified where the platform exposes it, so a non-executable file on PATH
+ * is reported as missing rather than assumed usable.
+ */
+export declare function commandExists(command: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Where an executable actually is — the first candidate that exists and is
+ * executable, or null. Reporting the PATH is what turns "not installed" into a
+ * check the user can falsify in one command (`ls -l /opt/homebrew/bin/docker`).
+ */
+export declare function resolveCommandPath(command: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Probe one variant's prerequisites. Pure with respect to the filesystem
+ * (reads only) and to the network (never touches it).
+ */
+export declare function probePrereqs(prereqs: MCPPrereq[], options?: MCPProbeOptions): MCPPrereqStatus;
+/**
+ * One human line per missing prerequisite: what is absent, and what to do about
+ * it. Used by `nuvira mcp catalog` / `install` so a dependency is named BEFORE
+ * the user enables anything rather than surfacing as a dead server later.
+ */
+export declare function describeMissingPrereqs(missing: MCPPrereq[]): string[];
+/**
+ * Every reason a variant cannot run, in the words the user needs: something
+ * ABSENT (install it) or something PRESENT BUT DOWN (start it). One function, so
+ * the CLI, the dashboard and the installer cannot phrase it differently.
+ */
+export declare function describePrereqProblems(status: MCPPrereqStatus): string[];
+//# sourceMappingURL=prereqs.d.ts.map

package/dist/mcp/prereqs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prereqs.d.ts","sourceRoot":"","sources":["../../src/mcp/prereqs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAMH,iDAAiD;AACjD,MAAM,MAAM,aAAa;AACvB,iFAAiF;AAC/E,MAAM;AACR,kFAAkF;GAChF,SAAS;AACX;;;;GAIG;GACD,SAAS;AACX,4EAA4E;GAC1E,KAAK;AACP,8EAA8E;GAC5E,MAAM,CAAC;AAEX,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,SAAS,CAAC;IAClB,4FAA4F;IAC5F,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,EAAE,EAAE,OAAO,CAAC;IACZ,sEAAsE;IACtE,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB;;;;OAIG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;;;;OAIG;IACH,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAeD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAS5D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE5F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,IAAI,CA8BvG;AAkCD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,OAAO,GAAE,eAAoB,GAAG,eAAe,CAkEjG;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,CAiBrE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,EAAE,CAMxE"}

package/dist/mcp/prereqs.js

@@ -0,0 +1,245 @@
+/**
+ * MCP prerequisite probe — "what must exist before this server can run".
+ *
+ * WHY THIS EXISTS. The shipped catalog pinned npm specs that do not resolve
+ * (`docs/mcp-assessment.md` §2: 4 of 6 entries E404'd), and the install path
+ * could not tell a user why a server would never start: it wrote a config and
+ * reported success. A capability slot now offers several WAYS to run the same
+ * server (hosted remote, `npx`, a local binary, `uvx`, docker), and each way
+ * declares what it needs. This module answers — locally, without spawning
+ * anything — "on THIS machine, which of those ways can actually run, and what
+ * is missing from the others".
+ *
+ * Two rules keep it honest:
+ *   1. A probe never claims more than it checked. `command`/`env`/`file` are
+ *      verified here. A version requirement satisfied by an alternate runtime
+ *      binary is reported as PRESENT-BUT-UNVERIFIED (the version is established
+ *      by the MCP handshake at connect time, not by guessing at install).
+ *   2. Absence is never fatal by itself. The caller decides: the catalog shows
+ *      the gap, `install` refuses only when NO variant can run.
+ *
+ * THE DOCKER CASE — why `service` exists. A CLI binary on PATH is not the same
+ * as a working service. `docker` 29.7 was installed at /opt/homebrew/bin/docker
+ * on the dev machine while its daemon socket did not exist, so "docker is
+ * installed" was true and `docker run` still failed. A `command` prereq cannot
+ * express that, and a wrong "not installed" message sends the user to install
+ * something they already have. A `service` prereq names the binary AND the
+ * probe that must succeed (`docker info`), so the report can say exactly which
+ * half is missing. Running that probe EXECUTES a process, so it is opt-in
+ * (`deep`): the CLI asks for it at install time, unit tests never do.
+ *
+ * Hermetic by construction: PATH lookup + `process.env` reads only. No spawn,
+ * no network, no config write. Tests can inject `env`/`nodeVersion`.
+ */
+import { accessSync, constants, existsSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { delimiter, isAbsolute, join } from 'node:path';
+/** Strip a leading `v` and any pre-release suffix: `v20.18.1-rc.1` → `20.18.1`. */
+function normalizeVersion(version) {
+    return String(version ?? '')
+        .trim()
+        .replace(/^v/i, '')
+        .split('-')[0]
+        .split('.')
+        .map((part) => {
+        const n = Number.parseInt(part, 10);
+        return Number.isFinite(n) ? n : 0;
+    });
+}
+/**
+ * Compare two dotted versions. Returns <0 when `a` is older, 0 when equal,
+ * >0 when `a` is newer. Missing components count as 0, so `18` < `18.18`.
+ */
+export function compareVersions(a, b) {
+    const left = normalizeVersion(a);
+    const right = normalizeVersion(b);
+    const len = Math.max(left.length, right.length);
+    for (let i = 0; i < len; i++) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * Is `command` runnable? An absolute or relative path is checked directly; a
+ * bare name is looked up on PATH (honouring PATHEXT on Windows). Executability
+ * is verified where the platform exposes it, so a non-executable file on PATH
+ * is reported as missing rather than assumed usable.
+ */
+export function commandExists(command, env = process.env) {
+    return resolveCommandPath(command, env) !== null;
+}
+/**
+ * Where an executable actually is — the first candidate that exists and is
+ * executable, or null. Reporting the PATH is what turns "not installed" into a
+ * check the user can falsify in one command (`ls -l /opt/homebrew/bin/docker`).
+ */
+export function resolveCommandPath(command, env = process.env) {
+    const name = String(command ?? '').trim();
+    if (!name)
+        return null;
+    const candidates = [];
+    if (isAbsolute(name) || name.includes('/') || name.includes('\\')) {
+        candidates.push(name);
+    }
+    else {
+        const extensions = process.platform === 'win32'
+            ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+            : [''];
+        const dirs = (env.PATH ?? '').split(delimiter).filter(Boolean);
+        for (const dir of dirs) {
+            for (const ext of extensions) {
+                candidates.push(join(dir, `${name}${ext}`));
+            }
+        }
+    }
+    for (const candidate of candidates) {
+        try {
+            if (!statSync(candidate).isFile())
+                continue;
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Not there, or not executable — try the next candidate.
+        }
+    }
+    return null;
+}
+/** Default budget for one deep service check. */
+const SERVICE_CHECK_TIMEOUT_MS = 2500;
+/**
+ * Run a service check (`<binary> <args…>`) and require exit 0. Returns the
+ * observed failure reason on non-zero/missing/timeout, so the caller can show it
+ * verbatim instead of guessing.
+ */
+function runServiceCheck(binary, check, env) {
+    try {
+        const result = spawnSync(binary, check.args, {
+            timeout: check.timeoutMs ?? SERVICE_CHECK_TIMEOUT_MS,
+            encoding: 'utf-8',
+            env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (result.error)
+            return { ok: false, reason: result.error.message };
+        if (result.status === 0)
+            return { ok: true };
+        const stderr = String(result.stderr ?? '').trim().split('\n').filter(Boolean).pop();
+        const stdout = String(result.stdout ?? '').trim().split('\n').filter(Boolean).pop();
+        const raw = stderr || stdout || `exited with status ${result.status}`;
+        // Tools like docker print a paragraph; keep the report one readable line.
+        return { ok: false, reason: raw.length > 160 ? `${raw.slice(0, 157)}…` : raw };
+    }
+    catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Probe one variant's prerequisites. Pure with respect to the filesystem
+ * (reads only) and to the network (never touches it).
+ */
+export function probePrereqs(prereqs, options = {}) {
+    const env = options.env ?? process.env;
+    const nodeVersion = options.nodeVersion ?? process.versions.node;
+    const missing = [];
+    const unverified = [];
+    const blocked = [];
+    for (const prereq of prereqs) {
+        switch (prereq.kind) {
+            case 'command': {
+                if (!commandExists(prereq.name, env))
+                    missing.push(prereq);
+                break;
+            }
+            case 'service': {
+                const binary = resolveCommandPath(prereq.name, env);
+                if (!binary) {
+                    // The BINARY is missing — the actionable fix is to install it.
+                    missing.push(prereq);
+                    break;
+                }
+                if (!options.deep || !prereq.check) {
+                    // Present, daemon state not established: say so rather than assume.
+                    unverified.push(`'${prereq.name}' found at ${binary} — its service was not checked`);
+                    break;
+                }
+                const result = runServiceCheck(binary, prereq.check, env);
+                if (!result.ok) {
+                    blocked.push({
+                        prereq,
+                        reason: `'${prereq.name}' is installed (${binary}) but not running: ${result.reason}`,
+                    });
+                }
+                break;
+            }
+            case 'env': {
+                const value = env[prereq.name];
+                if (!value || !String(value).trim())
+                    missing.push(prereq);
+                break;
+            }
+            case 'file': {
+                if (!existsSync(prereq.name))
+                    missing.push(prereq);
+                break;
+            }
+            case 'node': {
+                if (options.runtimeCommand) {
+                    // The floor is met by running the server under a different runtime.
+                    // Verify the runtime is present; its VERSION is established by the
+                    // handshake at connect time — say so instead of claiming a pass.
+                    if (!commandExists(options.runtimeCommand, env)) {
+                        missing.push(prereq);
+                    }
+                    else if (prereq.minVersion && compareVersions(nodeVersion, prereq.minVersion) < 0) {
+                        unverified.push(`${prereq.name} ≥ ${prereq.minVersion} via '${options.runtimeCommand}' — version checked at connect`);
+                    }
+                    break;
+                }
+                if (prereq.minVersion && compareVersions(nodeVersion, prereq.minVersion) < 0) {
+                    missing.push(prereq);
+                }
+                break;
+            }
+        }
+    }
+    return { ok: missing.length === 0 && blocked.length === 0, missing, unverified, blocked };
+}
+/**
+ * One human line per missing prerequisite: what is absent, and what to do about
+ * it. Used by `nuvira mcp catalog` / `install` so a dependency is named BEFORE
+ * the user enables anything rather than surfacing as a dead server later.
+ */
+export function describeMissingPrereqs(missing) {
+    return missing.map((prereq) => {
+        switch (prereq.kind) {
+            case 'node':
+                return `Node.js ${prereq.minVersion ?? ''}+ (this process runs ${process.versions.node}) — ${prereq.hint}`.trim();
+            case 'command':
+                return `'${prereq.name}' not found on PATH — ${prereq.hint}`;
+            case 'service':
+                return `'${prereq.name}' not found on PATH — ${prereq.hint}`;
+            case 'env':
+                return `$${prereq.name} is not set — ${prereq.hint}`;
+            case 'file':
+                return `${prereq.name} does not exist — ${prereq.hint}`;
+            default:
+                return `${prereq.name} — ${prereq.hint}`;
+        }
+    });
+}
+/**
+ * Every reason a variant cannot run, in the words the user needs: something
+ * ABSENT (install it) or something PRESENT BUT DOWN (start it). One function, so
+ * the CLI, the dashboard and the installer cannot phrase it differently.
+ */
+export function describePrereqProblems(status) {
+    const lines = describeMissingPrereqs(status.missing);
+    for (const { reason, prereq } of status.blocked) {
+        lines.push(`${reason} — ${prereq.hint}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=prereqs.js.map

package/dist/mcp/prereqs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prereqs.js","sourceRoot":"","sources":["../../src/mcp/prereqs.ts"],"names":[],"mappings":"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"}

package/dist/mcp/runtime.d.ts

@@ -0,0 +1,59 @@
+/**
+ * MCP runtime override — start a stdio server under its OWN interpreter.
+ *
+ * THE PROBLEM THIS SOLVES. `@upstash/context7-mcp@4.3.0` declares
+ * `engines.node: ">=20.18.1"`. Nuvira ships `engines.node: ">=18.18.0"` and is
+ * widely installed on Node 18 and 20. Raising the global floor would drop
+ * supported machines; leaving the pin at the broken 1.5.2 would keep a
+ * capability advertised that cannot start. A per-server runtime override keeps
+ * both honest: the product's floor does not move, and the outlier server runs
+ * under the interpreter it requires.
+ *
+ * THE CONTRACT. A config may carry
+ *
+ *   "runtime": { "command": "/opt/node20/bin/node", "args": ["/usr/local/bin/npx"] }
+ *
+ * and the child process becomes
+ *
+ *   /opt/node20/bin/node /usr/local/bin/npx <the variant's command>…
+ *
+ * i.e. `runtime.command` + `runtime.args` + the server's own `command` and
+ * `args`. For an `npx`-based server that is exactly "run npx with a newer Node"
+ * — `npx` is a JS entry point, so the interpreter that starts it is what decides
+ * the Node version. For a native binary the prefix is simply omitted.
+ *
+ * VERIFICATION IS HONEST. The prerequisite probe checks only that
+ * `runtime.command` EXISTS; its version is established by the MCP handshake when
+ * the server connects (`initialize` carries the protocol version, and a wrong
+ * interpreter fails there loudly) — never claimed as verified before that.
+ */
+import type { MCPServerConfig } from './types.js';
+/** The command + args actually spawned for a stdio server, runtime prefix applied. */
+export interface ResolvedStdioCommand {
+    command: string;
+    args: string[];
+    /** True when a runtime override was applied (for reporting/tests). */
+    runtimeApplied: boolean;
+}
+/**
+ * Resolve the stdio command and args to spawn, applying `config.runtime` when
+ * present. Pure — no spawn, no filesystem — so it is trivially testable and
+ * usable by a dry-run reporter.
+ */
+export declare function resolveStdioCommand(config: Pick<MCPServerConfig, 'command' | 'args' | 'runtime'>): ResolvedStdioCommand;
+/**
+ * Parse a runtime spec from a command line (`--runtime "/opt/node20/bin/node
+ * /usr/local/bin/npx"` or the dashboard's single text field) into a runtime
+ * override. The first token is the command, the rest are its args. Returns null
+ * for an empty spec.
+ *
+ * Lives here, not in the CLI, because the dashboard's MCP page accepts the same
+ * string — one parser means `--runtime` and the UI field cannot disagree.
+ */
+export declare function parseRuntimeSpec(spec: string | undefined): {
+    command: string;
+    args?: string[];
+} | null;
+/** A one-line description of what will be spawned (used by CLI listings). */
+export declare function describeStdioCommand(config: Pick<MCPServerConfig, 'command' | 'args' | 'runtime'>): string;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/mcp/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/mcp/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,sFAAsF;AACtF,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,sEAAsE;IACtE,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,oBAAoB,CAevH;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAItG;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,CAQ1G"}

package/dist/mcp/runtime.js

@@ -0,0 +1,77 @@
+/**
+ * MCP runtime override — start a stdio server under its OWN interpreter.
+ *
+ * THE PROBLEM THIS SOLVES. `@upstash/context7-mcp@4.3.0` declares
+ * `engines.node: ">=20.18.1"`. Nuvira ships `engines.node: ">=18.18.0"` and is
+ * widely installed on Node 18 and 20. Raising the global floor would drop
+ * supported machines; leaving the pin at the broken 1.5.2 would keep a
+ * capability advertised that cannot start. A per-server runtime override keeps
+ * both honest: the product's floor does not move, and the outlier server runs
+ * under the interpreter it requires.
+ *
+ * THE CONTRACT. A config may carry
+ *
+ *   "runtime": { "command": "/opt/node20/bin/node", "args": ["/usr/local/bin/npx"] }
+ *
+ * and the child process becomes
+ *
+ *   /opt/node20/bin/node /usr/local/bin/npx <the variant's command>…
+ *
+ * i.e. `runtime.command` + `runtime.args` + the server's own `command` and
+ * `args`. For an `npx`-based server that is exactly "run npx with a newer Node"
+ * — `npx` is a JS entry point, so the interpreter that starts it is what decides
+ * the Node version. For a native binary the prefix is simply omitted.
+ *
+ * VERIFICATION IS HONEST. The prerequisite probe checks only that
+ * `runtime.command` EXISTS; its version is established by the MCP handshake when
+ * the server connects (`initialize` carries the protocol version, and a wrong
+ * interpreter fails there loudly) — never claimed as verified before that.
+ */
+/**
+ * Resolve the stdio command and args to spawn, applying `config.runtime` when
+ * present. Pure — no spawn, no filesystem — so it is trivially testable and
+ * usable by a dry-run reporter.
+ */
+export function resolveStdioCommand(config) {
+    const command = String(config.command ?? '').trim();
+    if (!command) {
+        throw new Error('No stdio command to run');
+    }
+    const serverArgs = config.args ?? [];
+    const runtime = config.runtime;
+    if (!runtime || !runtime.command || !String(runtime.command).trim()) {
+        return { command, args: [...serverArgs], runtimeApplied: false };
+    }
+    return {
+        command: String(runtime.command).trim(),
+        args: [...(runtime.args ?? []), command, ...serverArgs],
+        runtimeApplied: true,
+    };
+}
+/**
+ * Parse a runtime spec from a command line (`--runtime "/opt/node20/bin/node
+ * /usr/local/bin/npx"` or the dashboard's single text field) into a runtime
+ * override. The first token is the command, the rest are its args. Returns null
+ * for an empty spec.
+ *
+ * Lives here, not in the CLI, because the dashboard's MCP page accepts the same
+ * string — one parser means `--runtime` and the UI field cannot disagree.
+ */
+export function parseRuntimeSpec(spec) {
+    const parts = String(spec ?? '').trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0)
+        return null;
+    return parts.length === 1 ? { command: parts[0] } : { command: parts[0], args: parts.slice(1) };
+}
+/** A one-line description of what will be spawned (used by CLI listings). */
+export function describeStdioCommand(config) {
+    try {
+        const resolved = resolveStdioCommand(config);
+        const line = [resolved.command, ...resolved.args].join(' ');
+        return resolved.runtimeApplied ? `${line}   (runtime override)` : line;
+    }
+    catch {
+        return '(no command)';
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/mcp/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/mcp/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAYH;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA6D;IAC/F,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACpE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,UAAU,CAAC,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;IACnE,CAAC;IACD,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE;QACvC,IAAI,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC;QACvD,cAAc,EAAE,IAAI;KACrB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAwB;IACvD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACrE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAClG,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,oBAAoB,CAAC,MAA6D;IAChG,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC7C,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5D,OAAO,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,uBAAuB,CAAC,CAAC,CAAC,IAAI,CAAC;IACzE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,cAAc,CAAC;IACxB,CAAC;AACH,CAAC"}

package/dist/mcp/server.d.ts

@@ -37,6 +37,22 @@ export declare const AGENT_MCP_SERVER_INFO: {
  * registry tool NEVER silently exposes it over MCP.
  */
 export declare const AGENT_MCP_TOOL_NAMES: readonly ["build", "resume", "repair", "document", "website", "analyze", "test", "code_search", "web_search", "read_page"];
+/**
+ * The agent's MEMORY surface, opt-in via `nuvira mcp serve --memory`.
+ *
+ * WHY A SEPARATE ALLOWLIST. Memory is private by default: it holds what the user
+ * told the agent, facts learned from their sessions, and their profile. Serving
+ * it is therefore a deliberate choice a user makes for a trusted client, not
+ * something the default public surface should leak by adding a name to a list.
+ * It is also the half that makes agent-nuvira usable AS a memory server: a client
+ * (Claude Code, Cursor, an IDE) gets semantic recall over the same store the
+ * agent writes to, instead of spawning a fourth, disconnected memory.
+ *
+ * Writes are included because the registry's own effect classes govern them
+ * (`add_memory`/`replace_memory`/`delete_memory` are non-read), and the MCP host
+ * is where the user sees and approves the call.
+ */
+export declare const MEMORY_MCP_TOOL_NAMES: readonly ["search_memory", "add_memory", "replace_memory", "delete_memory", "list_memories", "memory_stats", "memory"];
 /** Options for createAgentMcpServer. */
 export interface AgentMcpServerOptions {
     /** Working directory for tool runs (defaults to process.cwd()). */
@@ -48,6 +64,11 @@ export interface AgentMcpServerOptions {
      * default — explicit opt-in for irreversible/loop-dependent tools.
      */
     extraTools?: string[];
+    /**
+     * Also expose the MEMORY surface ({@link MEMORY_MCP_TOOL_NAMES}). Off by
+     * default: memory is private, so serving it is an explicit opt-in.
+     */
+    includeMemory?: boolean;
 }
 /**
  * Build the MCP server with every safe H1 tool registered. Returns the SDK

package/dist/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AASrD,iDAAiD;AACjD,eAAO,MAAM,qBAAqB;;;CAAiD,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,4HAWvB,CAAC;AAEX,wCAAwC;AACxC,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,SAAS,CAAC,CAiBpB;AAoDD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAGnE;AAED,iEAAiE;AACjE,wBAAsB,UAAU,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,SAAS,CAAC,CAIrF"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AASrD,iDAAiD;AACjD,eAAO,MAAM,qBAAqB;;;CAAiD,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,4HAWvB,CAAC;AAEX;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,wHAQxB,CAAC;AAEX,wCAAwC;AACxC,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,SAAS,CAAC,CAqBpB;AAoDD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAGnE;AAED,iEAAiE;AACjE,wBAAsB,UAAU,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,SAAS,CAAC,CAIrF"}

package/dist/mcp/server.js

@@ -51,6 +51,30 @@ export const AGENT_MCP_TOOL_NAMES = [
     'web_search',
     'read_page',
 ];
+/**
+ * The agent's MEMORY surface, opt-in via `nuvira mcp serve --memory`.
+ *
+ * WHY A SEPARATE ALLOWLIST. Memory is private by default: it holds what the user
+ * told the agent, facts learned from their sessions, and their profile. Serving
+ * it is therefore a deliberate choice a user makes for a trusted client, not
+ * something the default public surface should leak by adding a name to a list.
+ * It is also the half that makes agent-nuvira usable AS a memory server: a client
+ * (Claude Code, Cursor, an IDE) gets semantic recall over the same store the
+ * agent writes to, instead of spawning a fourth, disconnected memory.
+ *
+ * Writes are included because the registry's own effect classes govern them
+ * (`add_memory`/`replace_memory`/`delete_memory` are non-read), and the MCP host
+ * is where the user sees and approves the call.
+ */
+export const MEMORY_MCP_TOOL_NAMES = [
+    'search_memory',
+    'add_memory',
+    'replace_memory',
+    'delete_memory',
+    'list_memories',
+    'memory_stats',
+    'memory',
+];
 /**
  * Build the MCP server with every safe H1 tool registered. Returns the SDK
  * McpServer (NOT yet connected — call `connectStdio()` or attach a transport).
@@ -63,7 +87,11 @@ export async function createAgentMcpServer(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const configManager = opts.configManager ?? new ConfigManager();
     const configManagerCtx = configManager;
-    const toolNames = new Set([...AGENT_MCP_TOOL_NAMES, ...(opts.extraTools ?? [])]);
+    const toolNames = new Set([
+        ...AGENT_MCP_TOOL_NAMES,
+        ...(opts.includeMemory ? MEMORY_MCP_TOOL_NAMES : []),
+        ...(opts.extraTools ?? []),
+    ]);
     for (const tool of listTools()) {
         if (!toolNames.has(tool.name))
             continue;