@skastr0/prism-sdk 0.3.0

package/dist/mcp/daemon-resolver.js

@@ -0,0 +1,185 @@
+/**
+ * Resolve-or-spawn: given a plugin name, produce a *live* daemon registry
+ * entry to connect to -- spawning a fresh daemon when the registry has no
+ * entry, the recorded entry is dead, or the recorded entry's bundle hash no
+ * longer matches the compiled bundle on disk (a `prism refresh` ran since
+ * that daemon started).
+ *
+ * Builds entirely on the wave-0 substrate rather than re-implementing any of
+ * it:
+ *  - `getDaemon` / the per-plugin registry file (`uds-registry.ts`).
+ *  - `udsPathFor`, the content-addressed socket path (`uds-path.ts`) --
+ *    a different bundle hash always yields a different socket path, so a
+ *    stale daemon (old hash) and a fresh one (new hash) never collide on the
+ *    same file.
+ *  - `probeSocketLiveness` (`uds-singleton.ts`).
+ *
+ * This module deliberately never binds a socket or acquires the bind lock
+ * itself. Every compiled bundle's own runtime already calls
+ * `bindUnixSocketSingleton` on startup (see `src/compile/mcp-bundle.ts`'s
+ * `MCP_SDK_HTTP_RUNTIME`), and *that* is what guarantees exactly one winner
+ * when N callers race to spawn the same plugin: this module just spawns
+ * (possibly redundantly) and waits for a live registry entry to show up.
+ * Losing spawns detect "already-served" inside their own bundle and
+ * `process.exit(0)` before ever registering.
+ */
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { udsPathFor as udsPathForDefault } from "./uds-path.js";
+import { getDaemon as getDaemonDefault } from "./uds-registry.js";
+import { probeSocketLiveness as probeSocketLivenessDefault } from "./uds-singleton.js";
+export class DaemonResolveError extends Error {
+    pluginName;
+    cause;
+    kind = "daemon-resolve-error";
+    constructor(pluginName, message, cause) {
+        super(`[${pluginName}] ${message}`);
+        this.pluginName = pluginName;
+        this.cause = cause;
+        this.name = "DaemonResolveError";
+    }
+}
+const errorMessage = (error) => (error instanceof Error ? error.message : String(error));
+const delay = (ms) => new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+export const DEFAULT_SPAWN_TIMEOUT_MS = 15_000;
+const DEFAULT_POLL_INTERVAL_MS = 50;
+/**
+ * `<prismHome>/runtime/mcp/<plugin>` -- the per-plugin runtime directory
+ * that owns this plugin's registry file, socket file(s), and compiled
+ * bundle. Derived from `udsPathFor` (any hash value yields the same parent
+ * directory) rather than re-deriving the layout independently.
+ *
+ * `prismHome` is threaded explicitly (never read from the environment
+ * here): the CLI edge resolves `PRISM_HOME` once via `resolvePrismHome()`
+ * and passes the result down. An omitted value falls back to the same
+ * `~/.prism` default `resolvePrismHome()` uses when unset -- `prism-sdk`
+ * cannot import that resolver itself (no dependency on the root `src/`
+ * tree).
+ */
+export const pluginRuntimeDir = (plugin, prismHome) => dirname(udsPathForDefault(plugin, "", prismHome));
+/**
+ * `<prismHome>/runtime/mcp/<plugin>/server.mjs` -- the canonical compiled
+ * bundle a `prism refresh` run produces. This module only ever reads it; it
+ * never writes or rebuilds it.
+ */
+export const pluginBundlePath = (plugin, prismHome) => join(pluginRuntimeDir(plugin, prismHome), "server.mjs");
+const sha256Hex = (content) => createHash("sha256").update(content).digest("hex");
+const defaultHashBundle = async (bundlePath) => sha256Hex(await readFile(bundlePath));
+/**
+ * Spawns `bun <bundle>` detached (so it outlives this process) with the UDS
+ * + registry identity env the bundle's own runtime reads at startup (see
+ * `PRISM_MCP_UDS_PATH` / `PRISM_MCP_REGISTRY_PLUGIN_NAME` /
+ * `PRISM_MCP_REGISTRY_BUNDLE_HASH` in `MCP_SDK_HTTP_RUNTIME`). Never waits
+ * on the child and never lets a spawn-level error (e.g. `bun` missing from
+ * PATH) throw unhandled -- resolution simply times out and reports a typed
+ * `DaemonResolveError` instead.
+ */
+const defaultSpawnDaemon = ({ plugin, bundlePath, udsPath, bundleHash }) => {
+    const child = spawn("bun", [bundlePath], {
+        cwd: dirname(bundlePath),
+        env: {
+            ...process.env,
+            PRISM_MCP_UDS_PATH: udsPath,
+            PRISM_MCP_REGISTRY_PLUGIN_NAME: plugin,
+            PRISM_MCP_REGISTRY_BUNDLE_HASH: bundleHash,
+        },
+        detached: true,
+        stdio: "ignore",
+    });
+    child.on("error", () => undefined);
+    child.unref();
+};
+/**
+ * Returns `true` when the bundle on disk no longer matches
+ * `registeredHash`. Locating the bundle (`bundlePathFor`, which by default
+ * derives from `udsPathFor` and so can throw `UDSPathLengthError` for a
+ * plugin/home combination that would not fit a UDS socket path either) or
+ * reading it (deleted, or -- in a hermetic test -- never written) are both
+ * treated as "unknown, not proven stale": a live daemon is strictly better
+ * than none, so failing to independently re-derive where a *hypothetical
+ * replacement* bundle would live never forces a respawn of an
+ * otherwise-healthy, already-reachable daemon.
+ */
+const isBundleStale = async (options) => {
+    try {
+        const bundlePath = options.bundlePathFor(options.plugin);
+        return (await options.hashBundle(bundlePath)) !== options.registeredHash;
+    }
+    catch {
+        return false;
+    }
+};
+const waitForLiveEntry = async (options) => {
+    const { plugin, udsPath, getDaemon, probeSocketLiveness, spawnTimeoutMs, pollIntervalMs } = options;
+    const deadline = Date.now() + spawnTimeoutMs;
+    while (true) {
+        const registered = await getDaemon(plugin);
+        if (registered.kind === "ok" && registered.value.sock === udsPath) {
+            const liveness = await probeSocketLiveness(registered.value.sock);
+            if (liveness === "live")
+                return registered.value;
+        }
+        if (Date.now() >= deadline) {
+            throw new DaemonResolveError(plugin, `spawned daemon did not become live at ${udsPath} within ${spawnTimeoutMs}ms`);
+        }
+        await delay(pollIntervalMs);
+    }
+};
+/**
+ * Resolves the live registry entry to connect to for `plugin`:
+ *
+ *   registry entry present -> liveness probe
+ *     live & bundle hash matches on-disk bundle -> use it
+ *     dead, OR bundle hash stale               -> spawn fresh
+ *   registry entry absent                       -> spawn fresh
+ *
+ * "Spawn fresh" computes the bundle's current content hash, derives its
+ * content-addressed socket path via `udsPathFor`, launches the daemon, and
+ * polls the registry + a liveness probe until a live entry at that exact
+ * socket path appears or `spawnTimeoutMs` elapses.
+ *
+ * Throws `DaemonResolveError` when the bundle cannot be read (nothing to
+ * spawn) or the spawned daemon never becomes live in time.
+ */
+export const resolveOrSpawnDaemon = async (options) => {
+    const { plugin } = options;
+    const spawnTimeoutMs = options.spawnTimeoutMs ?? DEFAULT_SPAWN_TIMEOUT_MS;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const getDaemon = options.getDaemon ?? getDaemonDefault;
+    const probeSocketLiveness = options.probeSocketLiveness ?? probeSocketLivenessDefault;
+    const bundlePathFor = options.bundlePathFor ?? ((plugin) => pluginBundlePath(plugin, options.prismHome));
+    const buildUdsPath = options.udsPathFor ?? ((plugin, bundleHash) => udsPathForDefault(plugin, bundleHash, options.prismHome));
+    const hashBundle = options.hashBundle ?? defaultHashBundle;
+    const spawnDaemon = options.spawnDaemon ?? defaultSpawnDaemon;
+    const registered = await getDaemon(plugin);
+    if (registered.kind === "ok") {
+        const liveness = await probeSocketLiveness(registered.value.sock);
+        if (liveness === "live") {
+            const stale = await isBundleStale({
+                plugin,
+                registeredHash: registered.value.bundleHash,
+                bundlePathFor,
+                hashBundle,
+            });
+            if (!stale)
+                return registered.value;
+        }
+    }
+    // Reaching here means we are actually about to spawn, so -- unlike the
+    // staleness check above -- locating and reading the bundle now has to
+    // succeed; there is nothing to fall back to.
+    let bundlePath;
+    let currentHash;
+    try {
+        bundlePath = bundlePathFor(plugin);
+        currentHash = await hashBundle(bundlePath);
+    }
+    catch (error) {
+        throw new DaemonResolveError(plugin, `cannot spawn: unable to locate/read compiled bundle: ${errorMessage(error)}`, error);
+    }
+    const udsPath = buildUdsPath(plugin, currentHash);
+    spawnDaemon({ plugin, bundlePath, udsPath, bundleHash: currentHash });
+    return waitForLiveEntry({ plugin, udsPath, getDaemon, probeSocketLiveness, spawnTimeoutMs, pollIntervalMs });
+};

package/dist/mcp/shim.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Aggregating MCP shim.
+ *
+ * A single stdio MCP server, spawned once by the harness, that fronts N
+ * Prism-generated plugin daemons over Unix domain sockets. It replaces the
+ * "one spawned process per plugin" shape with "one spawned process,
+ * multiplexed over UDS to N already-running daemons":
+ *
+ *   harness <--stdio(JSON-RPC)--> shim <--HTTP-over-UDS--> daemon[plugin A]
+ *                                      \-HTTP-over-UDS--> daemon[plugin B]
+ *
+ * Harness side (this module's `runShim`/`createShimServer`): a bare
+ * JSON-RPC MCP server over stdin/stdout using the SDK's low-level `Server`
+ * + `StdioServerTransport`. Stdio is a single duplex pipe with exactly one
+ * peer, so there is no SSE and no HTTP session concept to manage here —
+ * that machinery only exists on the daemon side.
+ *
+ * Daemon side (`DaemonConnection`): a minimal hand-rolled HTTP-over-UDS
+ * JSON-RPC client, deliberately not the SDK's `Client` +
+ * `StreamableHTTPClientTransport`. The SDK client runs every response
+ * through `safeParse(resultSchema, ...)`, which is a plain (non-passthrough)
+ * Zod object and silently drops any field the schema does not declare. This
+ * shim's job is to forward a daemon's tool-call result value-preserving —
+ * stripping no field (name mapping aside) — so the daemon's raw JSON-RPC
+ * `result`/`error` is read and handed back untouched instead of being
+ * round-tripped through schema validation on the way in.
+ *
+ * A plugin absent from the UDS registry, whose recorded daemon is dead, or
+ * whose recorded bundle hash no longer matches the compiled bundle on disk,
+ * is resolved via `daemon-resolver.ts`'s `resolveOrSpawnDaemon`: it spawns a
+ * fresh daemon and waits (bounded by a spawn timeout) for it to register
+ * and answer live. If that also fails, or a live daemon is unreachable
+ * within `daemonTimeoutMs`, the failure is never fatal to the shim: the
+ * plugin's tools are omitted from the merged `tools/list`, and a
+ * `tools/call` naming it returns a typed `McpError` (SDK
+ * `ErrorCode.ConnectionClosed`). Every other configured plugin keeps
+ * serving normally — each plugin's request runs against its own timeout and
+ * failure is caught per-plugin.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type Tool } from "@modelcontextprotocol/sdk/types.js";
+import { type RegistryResult, type RegistryEntry } from "./uds-registry.js";
+/** `p_<hash8>` — see `stableHash8` above for why this exact shape. */
+export declare const pluginWireNamespace: (pluginName: string) => string;
+/** Harness-visible tool name: `<pluginWireNamespace>__<originalToolName>`. */
+export declare const namespacedToolName: (pluginName: string, toolName: string) => string;
+/**
+ * Inverse of `namespacedToolName`. The namespace segment has a fixed
+ * width, so this splits on position rather than searching for the `__`
+ * separator — a tool name is free-form and may itself legally contain
+ * `__`, but the namespace segment never does.
+ */
+export declare const splitNamespacedToolName: (fqName: string) => {
+    readonly namespace: string;
+    readonly toolName: string;
+} | undefined;
+export declare class ShimDaemonError extends Error {
+    readonly pluginName: string;
+    readonly cause?: unknown | undefined;
+    readonly kind: "shim-daemon-error";
+    constructor(pluginName: string, message: string, cause?: unknown | undefined);
+}
+export type GetDaemonFn = (plugin: string) => Promise<RegistryResult<RegistryEntry>>;
+export type ResolveOrSpawnFn = (plugin: string) => Promise<RegistryEntry>;
+export interface ShimAggregatorOptions {
+    readonly plugins: ReadonlyArray<string>;
+    /**
+     * Prism home directory, threaded from the process entrypoint (see
+     * `src/mcp/shim-main.ts`, which resolves `PRISM_HOME` once via
+     * `resolvePrismHome()`). Forwarded to the default `resolveOrSpawn` so a
+     * `PRISM_HOME` override locates the same bundle/socket path `prism
+     * refresh` wrote, instead of always falling back to `~/.prism`. Ignored
+     * when `resolveOrSpawn` is supplied directly.
+     */
+    readonly prismHome?: string;
+    readonly daemonTimeoutMs?: number;
+    readonly spawnTimeoutMs?: number;
+    readonly getDaemon?: GetDaemonFn;
+    /**
+     * Full override of daemon resolution, bypassing `getDaemon` entirely.
+     * Tests that only want to exercise merge/dispatch/isolation (not
+     * resolve-or-spawn itself) inject a stub here instead of standing up a
+     * real compiled bundle on disk.
+     */
+    readonly resolveOrSpawn?: ResolveOrSpawnFn;
+    /** Optional set of tool names to enable; if present, only these tools are exposed. */
+    readonly enabledTools?: ReadonlySet<string>;
+    /** Optional exposure profile to pass to daemon as X-Prism-Mcp-Exposure header. */
+    readonly exposureProfile?: string;
+}
+export declare const DEFAULT_SHIM_DAEMON_TIMEOUT_MS = 30000;
+export declare class ShimAggregator {
+    private readonly plugins;
+    private readonly daemonTimeoutMs;
+    private readonly getDaemon;
+    private readonly spawnTimeoutMs;
+    private readonly resolveOrSpawn;
+    private readonly enabledTools;
+    private readonly exposureProfile;
+    private readonly connections;
+    constructor(options: ShimAggregatorOptions);
+    /**
+     * Resolves (or reuses) the connection for `plugin`: registry record
+     * present and live and fresh -> reuse; absent, dead, or stale (bundle
+     * hash no longer matches the on-disk bundle) -> `resolveOrSpawn` spawns a
+     * fresh daemon and waits for it to come up (see `daemon-resolver.ts`).
+     *
+     * Returns `undefined` if resolution ultimately fails (no bundle to spawn,
+     * or the daemon never became live within the timeout) — that is
+     * "unavailable", not fatal: the caller omits its tools / reports a typed
+     * error, but the aggregator itself never throws for one bad plugin.
+     */
+    private resolveConnection;
+    /**
+     * Merged, namespaced `tools/list` across every configured plugin.
+     * Per-plugin fetches run in parallel (one slow/dead plugin never blocks
+     * another), but results are reassembled in the fixed configured-plugin
+     * order afterward, so the merged list is deterministic regardless of
+     * which daemon happened to answer first.
+     *
+     * Tools are filtered by `enabledTools` if set: only tools in that set are
+     * returned. This is the shim-side filtering applied before any daemon
+     * response is merged.
+     */
+    listTools(): Promise<ReadonlyArray<Tool>>;
+    /**
+     * Dispatches a namespaced tool name to its owning plugin's daemon and
+     * returns the daemon's raw `CallToolResult` untouched. Throws
+     * `ShimDaemonError` (typed) when the name cannot be resolved to a
+     * configured plugin, when that plugin's daemon is absent/unreachable
+     * within the timeout, or when the tool is not in the enabled set —
+     * either way, this never crashes the shim and never touches any other
+     * plugin's connection.
+     */
+    callTool(fqName: string, args: Record<string, unknown>): Promise<unknown>;
+}
+export declare const createShimServer: (aggregator: ShimAggregator) => Server;
+export interface RunShimOptions {
+    readonly plugins: ReadonlyArray<string>;
+    /** Prism home directory, threaded from the process entrypoint. See `ShimAggregatorOptions.prismHome`. */
+    readonly prismHome?: string;
+    readonly daemonTimeoutMs?: number;
+    readonly spawnTimeoutMs?: number;
+    readonly getDaemon?: GetDaemonFn;
+    /** Optional set of tool names to enable; if present, only these tools are exposed. */
+    readonly enabledTools?: ReadonlySet<string>;
+    /** Optional exposure profile to pass to daemon as X-Prism-Mcp-Exposure header. */
+    readonly exposureProfile?: string;
+}
+/**
+ * Wires the aggregator to a stdio transport and runs until stdin closes or
+ * the process receives SIGINT/SIGTERM. Never throws for daemon-level
+ * failures — those surface per-request as typed MCP errors instead.
+ */
+export declare const runShim: (options: RunShimOptions) => Promise<void>;