@skastr0/prism-sdk 0.3.0

package/dist/mcp/shim.js

@@ -0,0 +1,434 @@
+/**
+ * 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 { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, LATEST_PROTOCOL_VERSION, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { getDaemon as getDaemonDefault } from "./uds-registry.js";
+import { resolveOrSpawnDaemon, DaemonResolveError, DEFAULT_SPAWN_TIMEOUT_MS } from "./daemon-resolver.js";
+// ---------------------------------------------------------------------------
+// Naming: the per-plugin namespace segment used to flatten N plugins' tools
+// into the one flat name-space a single MCP `tools/list` response can hold.
+// ---------------------------------------------------------------------------
+/**
+ * FNV-1a, 8 hex chars. Deliberately bit-for-bit identical to
+ * `stableHash8` in the root package's `src/compile/stable-hash.ts`, which
+ * backs `generatedMcpWireServerName` (`p_<hash8>`) — the segment every
+ * harness lowerer (Claude Code, Codex CLI, Antigravity, Factory Droid,
+ * Kimi Code, Cursor, Grok) already bakes into compiled permission strings
+ * and tool FQNs (e.g. Claude Code's `mcp__p_<hash8>__<tool>`).
+ *
+ * `packages/prism-sdk` cannot import that root-package module (its
+ * `tsconfig.json` `rootDir` is `./src`; a real `import` of anything under
+ * the workspace root `src/` fails to compile), so the tiny pure function is
+ * duplicated here rather than re-derived with a different algorithm. Using
+ * the *same* namespace segment the harness side already computes means a
+ * later wave that points a harness's MCP config at this shim only has to
+ * add an outer wrapper layer around `p_<hash8>__<tool>` (the shim's own
+ * server key in that harness's config), not rename every already-compiled
+ * permission string from scratch.
+ */
+const stableHash8 = (input) => {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index++) {
+        hash ^= input.codePointAt(index);
+        hash = Math.trunc(Math.imul(hash, 0x01000193));
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+};
+/** `p_<hash8>` — see `stableHash8` above for why this exact shape. */
+export const pluginWireNamespace = (pluginName) => `p_${stableHash8(pluginName)}`;
+const NAMESPACE_SEPARATOR = "__";
+/** Fixed width of `p_<hash8>`: literal `p_` (2) + 8 hex chars. */
+const NAMESPACE_LENGTH = 2 + 8;
+/** Harness-visible tool name: `<pluginWireNamespace>__<originalToolName>`. */
+export const namespacedToolName = (pluginName, toolName) => `${pluginWireNamespace(pluginName)}${NAMESPACE_SEPARATOR}${toolName}`;
+/**
+ * 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 const splitNamespacedToolName = (fqName) => {
+    if (fqName.length <= NAMESPACE_LENGTH + NAMESPACE_SEPARATOR.length)
+        return undefined;
+    const namespace = fqName.slice(0, NAMESPACE_LENGTH);
+    const separator = fqName.slice(NAMESPACE_LENGTH, NAMESPACE_LENGTH + NAMESPACE_SEPARATOR.length);
+    if (separator !== NAMESPACE_SEPARATOR)
+        return undefined;
+    const toolName = fqName.slice(NAMESPACE_LENGTH + NAMESPACE_SEPARATOR.length);
+    if (toolName.length === 0)
+        return undefined;
+    return { namespace, toolName };
+};
+// ---------------------------------------------------------------------------
+// Daemon-facing HTTP-over-UDS client
+// ---------------------------------------------------------------------------
+export class ShimDaemonError extends Error {
+    pluginName;
+    cause;
+    kind = "shim-daemon-error";
+    constructor(pluginName, message, cause) {
+        super(`[${pluginName}] ${message}`);
+        this.pluginName = pluginName;
+        this.cause = cause;
+        this.name = "ShimDaemonError";
+    }
+}
+/**
+ * One JSON-RPC-over-UDS connection to a single plugin daemon, matching the
+ * contract `src/compile/mcp-bundle.ts`'s `MCP_SDK_HTTP_RUNTIME` template
+ * implements: POST to `/mcp` with `mcp-protocol-version`, `initialize`
+ * first to obtain `mcp-session-id`, then that header on every subsequent
+ * call. Initializes once and reuses the session; a failed request drops
+ * the cached session so the next call starts a fresh handshake (the
+ * daemon may have restarted).
+ */
+class DaemonConnection {
+    pluginName;
+    socketPath;
+    timeoutMs;
+    exposureProfile;
+    sessionId;
+    requestId = 0;
+    /**
+     * In-flight handshake, memoized so concurrent first-callers share one
+     * `initialize` round-trip instead of each racing their own. Cleared
+     * (success or failure) once the handshake settles, so a later call that
+     * finds `sessionId` unset — because the handshake failed, or because a
+     * broken response later dropped the session — starts a fresh one rather
+     * than piling onto a promise that has already resolved or rejected.
+     */
+    initializing;
+    constructor(pluginName, socketPath, timeoutMs, exposureProfile) {
+        this.pluginName = pluginName;
+        this.socketPath = socketPath;
+        this.timeoutMs = timeoutMs;
+        this.exposureProfile = exposureProfile;
+    }
+    async listTools() {
+        await this.ensureInitialized();
+        const envelope = await this.rpc("tools/list");
+        if (envelope.error) {
+            throw new ShimDaemonError(this.pluginName, `daemon tools/list failed: ${envelope.error.message}`);
+        }
+        const tools = envelope.result?.tools;
+        return tools ?? [];
+    }
+    /** Returns the daemon's raw JSON-RPC `result` for `tools/call`, untouched. */
+    async callTool(toolName, args) {
+        await this.ensureInitialized();
+        const envelope = await this.rpc("tools/call", { name: toolName, arguments: args });
+        if (envelope.error) {
+            throw new ShimDaemonError(this.pluginName, `daemon tools/call '${toolName}' failed: ${envelope.error.message}`);
+        }
+        return envelope.result;
+    }
+    /**
+     * Single-flight: if a handshake is already in progress, every concurrent
+     * caller awaits that same promise instead of firing its own `initialize`
+     * request against the daemon.
+     */
+    async ensureInitialized() {
+        if (this.sessionId)
+            return;
+        if (!this.initializing) {
+            this.initializing = this.handshake().finally(() => {
+                this.initializing = undefined;
+            });
+        }
+        return this.initializing;
+    }
+    async handshake() {
+        const response = await this.request("initialize", {
+            protocolVersion: LATEST_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: "prism-mcp-shim", version: "0.1.0" },
+        });
+        const sessionId = response.headers.get("mcp-session-id");
+        if (!sessionId) {
+            throw new ShimDaemonError(this.pluginName, "daemon initialize did not return mcp-session-id");
+        }
+        const body = await this.parseBody(response);
+        if (body.error) {
+            throw new ShimDaemonError(this.pluginName, `daemon initialize failed: ${body.error.message}`);
+        }
+        this.sessionId = sessionId;
+    }
+    async rpc(method, params) {
+        const response = await this.request(method, params);
+        return this.parseBody(response);
+    }
+    /**
+     * Parses a daemon response body as the JSON-RPC envelope. A daemon that
+     * answers HTTP 200 with a truncated or otherwise non-JSON body is just as
+     * wedged as one that never answered: the malformed body is wrapped as a
+     * `ShimDaemonError` (never a raw `SyntaxError` escaping uncaught and
+     * mis-classified as `InternalError` by the caller) and the cached session
+     * is dropped, so the next call re-handshakes instead of replaying against
+     * a connection the daemon has already shown is broken.
+     */
+    async parseBody(response) {
+        const text = await response.text();
+        if (text.length === 0)
+            return {};
+        try {
+            return JSON.parse(text);
+        }
+        catch (error) {
+            this.sessionId = undefined;
+            throw new ShimDaemonError(this.pluginName, `daemon returned a malformed response body: ${errorMessage(error)}`, error);
+        }
+    }
+    /**
+     * Fires one JSON-RPC request at the daemon's UDS socket. Any failure —
+     * connection refused, socket file gone, timeout, malformed response — is
+     * wrapped as `ShimDaemonError` and drops the cached session, so a dead
+     * daemon never leaves this connection wedged on a session id that will
+     * never work again.
+     */
+    async request(method, params) {
+        const id = (this.requestId += 1);
+        const headers = {
+            accept: "application/json, text/event-stream",
+            "content-type": "application/json",
+            "mcp-protocol-version": LATEST_PROTOCOL_VERSION,
+        };
+        if (this.sessionId)
+            headers["mcp-session-id"] = this.sessionId;
+        if (this.exposureProfile)
+            headers["x-prism-mcp-exposure"] = this.exposureProfile;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const init = {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ jsonrpc: "2.0", id, method, params }),
+                signal: controller.signal,
+                unix: this.socketPath,
+            };
+            const response = await fetch("http://localhost/mcp", init);
+            if (!response.ok) {
+                this.sessionId = undefined;
+                throw new ShimDaemonError(this.pluginName, `daemon '${method}' returned HTTP ${response.status}`);
+            }
+            return response;
+        }
+        catch (error) {
+            this.sessionId = undefined;
+            if (error instanceof ShimDaemonError)
+                throw error;
+            throw new ShimDaemonError(this.pluginName, `daemon '${method}' unreachable: ${errorMessage(error)}`, error);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+const errorMessage = (error) => (error instanceof Error ? error.message : String(error));
+export const DEFAULT_SHIM_DAEMON_TIMEOUT_MS = 30_000;
+export class ShimAggregator {
+    plugins;
+    daemonTimeoutMs;
+    getDaemon;
+    spawnTimeoutMs;
+    resolveOrSpawn;
+    enabledTools;
+    exposureProfile;
+    connections = new Map();
+    constructor(options) {
+        this.plugins = options.plugins;
+        this.daemonTimeoutMs = options.daemonTimeoutMs ?? DEFAULT_SHIM_DAEMON_TIMEOUT_MS;
+        this.getDaemon = options.getDaemon ?? getDaemonDefault;
+        this.spawnTimeoutMs = options.spawnTimeoutMs ?? DEFAULT_SPAWN_TIMEOUT_MS;
+        this.enabledTools = options.enabledTools;
+        this.exposureProfile = options.exposureProfile;
+        this.resolveOrSpawn =
+            options.resolveOrSpawn ??
+                ((plugin) => resolveOrSpawnDaemon({
+                    plugin,
+                    prismHome: options.prismHome,
+                    getDaemon: this.getDaemon,
+                    spawnTimeoutMs: this.spawnTimeoutMs,
+                }));
+    }
+    /**
+     * 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.
+     */
+    async resolveConnection(plugin) {
+        let entry;
+        try {
+            entry = await this.resolveOrSpawn(plugin);
+        }
+        catch (error) {
+            this.connections.delete(plugin);
+            const detail = error instanceof DaemonResolveError || error instanceof Error ? error.message : String(error);
+            console.error(`[prism-mcp-shim] ${plugin}: ${detail}`);
+            return undefined;
+        }
+        const cached = this.connections.get(plugin);
+        if (cached && cached.sock === entry.sock) {
+            return cached.connection;
+        }
+        const connection = new DaemonConnection(plugin, entry.sock, this.daemonTimeoutMs, this.exposureProfile);
+        this.connections.set(plugin, { sock: entry.sock, connection });
+        return connection;
+    }
+    /**
+     * 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.
+     */
+    async listTools() {
+        const perPlugin = await Promise.all(this.plugins.map(async (plugin) => {
+            try {
+                const connection = await this.resolveConnection(plugin);
+                if (!connection)
+                    return [];
+                const tools = await connection.listTools();
+                return tools.map((tool) => ({ plugin, tool }));
+            }
+            catch {
+                // Unavailable for this pass; omitted, never fatal to the merge.
+                return [];
+            }
+        }));
+        const merged = [];
+        for (const named of perPlugin) {
+            for (const { plugin, tool } of named) {
+                const fqName = namespacedToolName(plugin, tool.name);
+                // Filter by enabledTools if set
+                if (this.enabledTools !== undefined && !this.enabledTools.has(fqName)) {
+                    continue;
+                }
+                merged.push({ ...tool, name: fqName });
+            }
+        }
+        return merged;
+    }
+    /**
+     * 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.
+     */
+    async callTool(fqName, args) {
+        // Filter by enabledTools if set
+        if (this.enabledTools !== undefined && !this.enabledTools.has(fqName)) {
+            throw new ShimDaemonError("shim", `tool name '${fqName}' is not enabled`);
+        }
+        const split = splitNamespacedToolName(fqName);
+        if (!split) {
+            throw new ShimDaemonError("shim", `tool name '${fqName}' is not a namespaced shim tool`);
+        }
+        const plugin = this.plugins.find((candidate) => pluginWireNamespace(candidate) === split.namespace);
+        if (!plugin) {
+            throw new ShimDaemonError("shim", `tool name '${fqName}' does not match any configured plugin`);
+        }
+        const connection = await this.resolveConnection(plugin);
+        if (!connection) {
+            throw new ShimDaemonError(plugin, `plugin has no live daemon registered`);
+        }
+        return connection.callTool(split.toolName, args);
+    }
+}
+// ---------------------------------------------------------------------------
+// Harness-facing stdio MCP server
+// ---------------------------------------------------------------------------
+const SERVER_NAME = "prism-mcp-shim";
+const SERVER_VERSION = "0.1.0";
+export const createShimServer = (aggregator) => {
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: await aggregator.listTools(),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            const result = await aggregator.callTool(name, args ?? {});
+            return result;
+        }
+        catch (error) {
+            if (error instanceof ShimDaemonError) {
+                throw new McpError(ErrorCode.ConnectionClosed, error.message);
+            }
+            throw new McpError(ErrorCode.InternalError, errorMessage(error));
+        }
+    });
+    return server;
+};
+/**
+ * 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 const runShim = async (options) => {
+    const aggregator = new ShimAggregator(options);
+    const server = createShimServer(aggregator);
+    const transport = new StdioServerTransport();
+    const shutdown = async () => {
+        try {
+            await server.close();
+        }
+        finally {
+            process.exit(0);
+        }
+    };
+    process.on("SIGINT", () => void shutdown());
+    process.on("SIGTERM", () => void shutdown());
+    await server.connect(transport);
+};

package/dist/mcp/uds-path.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Error type for UDS path violations.
+ * Typed to distinguish from other path errors.
+ */
+export declare class UDSPathLengthError extends Error {
+    readonly attemptedPath: string;
+    readonly kind: "uds-path-length-error";
+    constructor(message: string, attemptedPath: string);
+}
+/**
+ * Construct a content-addressed UDS socket path.
+ *
+ * Returns: `<prismHome>/runtime/mcp/<plugin>/<truncated-hash>.sock`
+ *
+ * @param plugin - Plugin identifier (must match /^[a-zA-Z0-9_-]+$/)
+ * @param bundleHash - Full content hash; will be truncated to first 16 hex
+ * @param prismHome - Prism home directory. Threaded explicitly by the
+ *   caller (the CLI edge resolves `PRISM_HOME` once via `resolvePrismHome()`
+ *   and passes the result down); this package cannot import that resolver
+ *   itself (`packages/prism-sdk` has no dependency on the root `src/`
+ *   tree), so an omitted value falls back to the same default
+ *   (`~/.prism`) `resolvePrismHome()` uses when unset.
+ * @returns Absolute path to the socket file
+ * @throws UDSPathLengthError if resulting path exceeds 100 bytes
+ */
+export declare function udsPathFor(plugin: string, bundleHash: string, prismHome?: string): string;

package/dist/mcp/uds-path.js

@@ -0,0 +1,70 @@
+import { homedir } from "os";
+/**
+ * Error type for UDS path violations.
+ * Typed to distinguish from other path errors.
+ */
+export class UDSPathLengthError extends Error {
+    attemptedPath;
+    kind = "uds-path-length-error";
+    constructor(message, attemptedPath) {
+        super(message);
+        this.attemptedPath = attemptedPath;
+        this.name = "UDSPathLengthError";
+    }
+}
+/**
+ * macOS sun_path limit (sockaddr_un.sun_path)
+ */
+const MACOS_SUN_PATH_LIMIT = 104;
+/**
+ * Tolerance below the hard limit to account for null terminator and safety margin.
+ * Standard practice: 104 - 4 bytes = 100 bytes.
+ */
+const PATH_LENGTH_LIMIT = 100;
+/**
+ * Regex to validate plugin names: alphanumeric, dash, underscore only.
+ * Prevents path traversal and special chars that could break socket path integrity.
+ */
+const VALID_PLUGIN_NAME = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Truncate hash to first 16 hex characters for path length safety.
+ * 16 hex chars = 64 bits, sufficient for disambiguation.
+ */
+function truncateHash(bundleHash) {
+    return bundleHash.slice(0, 16);
+}
+/**
+ * Construct a content-addressed UDS socket path.
+ *
+ * Returns: `<prismHome>/runtime/mcp/<plugin>/<truncated-hash>.sock`
+ *
+ * @param plugin - Plugin identifier (must match /^[a-zA-Z0-9_-]+$/)
+ * @param bundleHash - Full content hash; will be truncated to first 16 hex
+ * @param prismHome - Prism home directory. Threaded explicitly by the
+ *   caller (the CLI edge resolves `PRISM_HOME` once via `resolvePrismHome()`
+ *   and passes the result down); this package cannot import that resolver
+ *   itself (`packages/prism-sdk` has no dependency on the root `src/`
+ *   tree), so an omitted value falls back to the same default
+ *   (`~/.prism`) `resolvePrismHome()` uses when unset.
+ * @returns Absolute path to the socket file
+ * @throws UDSPathLengthError if resulting path exceeds 100 bytes
+ */
+export function udsPathFor(plugin, bundleHash, prismHome) {
+    // Validate plugin name
+    if (!VALID_PLUGIN_NAME.test(plugin)) {
+        throw new Error(`Invalid plugin name: '${plugin}'. Must match /^[a-zA-Z0-9_-]+$/`);
+    }
+    // Truncate hash to first 16 hex characters
+    const truncated = truncateHash(bundleHash);
+    // Build the path
+    const home = prismHome ?? `${homedir()}/.prism`;
+    const relativePath = `runtime/mcp/${plugin}/${truncated}.sock`;
+    const fullPath = `${home}/${relativePath}`;
+    // Assert length constraint
+    const pathLength = Buffer.byteLength(fullPath, "utf8");
+    if (pathLength > PATH_LENGTH_LIMIT) {
+        throw new UDSPathLengthError(`UDS socket path exceeds ${PATH_LENGTH_LIMIT}-byte limit (got ${pathLength} bytes). ` +
+            `Plugin name '${plugin}' may be too long.`, fullPath);
+    }
+    return fullPath;
+}

package/dist/mcp/uds-registry.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Error type for registry operation violations.
+ * Used to distinguish registry errors from other file system errors.
+ */
+export declare class UDSRegistryError extends Error {
+    readonly context?: unknown | undefined;
+    readonly kind: "uds-registry-error";
+    constructor(message: string, context?: unknown | undefined);
+}
+/**
+ * Per-plugin daemon instance record.
+ */
+export interface RegistryEntry {
+    readonly pid: number;
+    readonly sock: string;
+    readonly bundleHash: string;
+    readonly startedAt: number;
+    readonly lastUsed: number;
+}
+/**
+ * Registry of active daemon instances, indexed by plugin name.
+ */
+export type RegistryData = Record<string, RegistryEntry>;
+/**
+ * Result type for registry operations that may fail gracefully.
+ * Success carries the result; absent means the entry does not exist or is corrupted.
+ */
+export type RegistryResult<T> = {
+    kind: "ok";
+    value: T;
+} | {
+    kind: "absent";
+};
+/**
+ * Register a new daemon instance or update an existing one.
+ *
+ * Atomically writes the entry to this plugin's own registry file. Never
+ * reads or rewrites any other plugin's file.
+ *
+ * Throws UDSRegistryError on I/O failure (unrecoverable).
+ */
+export declare function registerDaemon(plugin: string, entry: RegistryEntry): Promise<void>;
+/**
+ * Unregister a daemon instance by plugin name.
+ *
+ * Removes this plugin's registry file. Does nothing (no error) if the
+ * entry does not exist.
+ *
+ * Throws UDSRegistryError on I/O failure (unrecoverable), file-not-found excepted.
+ */
+export declare function unregisterDaemon(plugin: string): Promise<void>;
+/**
+ * Get a single daemon entry by plugin name.
+ *
+ * Returns `{ kind: "ok", value: entry }` on success.
+ * Returns `{ kind: "absent" }` if the plugin is not registered or
+ * the registry is corrupted.
+ *
+ * Never throws.
+ */
+export declare function getDaemon(plugin: string): Promise<RegistryResult<RegistryEntry>>;
+/**
+ * Get all registered daemon entries across every plugin.
+ *
+ * Returns `{ kind: "ok", value: data }` on success (may be empty).
+ * Returns `{ kind: "absent" }` if the registry root directory does not
+ * exist yet (nothing has ever registered).
+ *
+ * Never throws; unreadable or corrupted per-plugin files are skipped
+ * individually rather than failing the whole scan.
+ */
+export declare function getAllDaemons(): Promise<RegistryResult<RegistryData>>;
+/**
+ * Update the lastUsed timestamp for a daemon entry.
+ *
+ * Returns `{ kind: "ok" }` on success.
+ * Returns `{ kind: "absent" }` if the plugin is not registered.
+ *
+ * Throws UDSRegistryError on I/O failure (unrecoverable).
+ */
+export declare function touchDaemon(plugin: string): Promise<RegistryResult<void>>;
+/**
+ * Outcome of `cleanupDaemonIfOwner`.
+ *
+ * - "cleaned": the record belonged to the given pid; it was unregistered
+ *   and the socket file (if provided) was unlinked.
+ * - "not-owner": a record exists but names a *different* pid — a successor
+ *   that has already re-registered under the same plugin key. Nothing was
+ *   touched.
+ * - "absent": no record exists for this plugin. Treated as "not ours":
+ *   nothing was touched.
+ */
+export type OwnershipCleanupResult = "cleaned" | "not-owner" | "absent";
+/**
+ * Ownership-gated teardown for a daemon's registration and socket file.
+ *
+ * Re-reads the current registry record for `plugin` and only acts — unlink
+ * `socketPath` and remove the registry entry — when that record's pid
+ * matches `pid`, i.e. when the caller is still the process the registry
+ * currently considers live for that plugin.
+ *
+ * This exists to protect a fast-respawning successor: if a predecessor is
+ * slow to drain and only calls this after a successor has already bound
+ * the same socket path and re-registered under the same plugin key, the
+ * registry record now names the successor's pid — a missing record or one
+ * naming a different pid means "not mine to clean up", so the successor's
+ * live socket file and registration are left completely untouched.
+ */
+export declare function cleanupDaemonIfOwner(plugin: string, pid: number, socketPath: string | undefined): Promise<OwnershipCleanupResult>;