@sigrun/ext-mcp 0.1.0 → 0.2.1

package/dist/config.d.ts

@@ -34,14 +34,20 @@ export declare function resolveToolExposure(server: McpServerConfig, toolName: s
  * `disabled: true` both skip it (parse-time validation rejects
  * contradictions, so either false simply means off). */
 export declare function serverEnabled(server: McpServerConfig): boolean;
-/** One configured MCP server (stdio transport). */
-export interface McpServerConfig {
-    /** The executable to spawn. */
-    readonly command: string;
-    /** Arguments to the executable. */
-    readonly args: readonly string[];
-    /** Extra environment variables for the child process. */
-    readonly env?: Readonly<Record<string, string>>;
+/** Who supplies the server's authority and owns its connection lifecycle. */
+export type McpCredentials = "user" | "shared";
+/** Whether every user starts enabled or must explicitly opt in. */
+export type McpAvailability = "all" | "opt-in";
+/** Fields every server variant carries regardless of transport. */
+interface McpServerCommon {
+    /** Per-user jailed connections by default; shared authority is opt-in. */
+    readonly credentials?: McpCredentials;
+    /** Required for shared entries: why lending this authority is acceptable. */
+    readonly sharedAuthority?: string;
+    /** Optional allowlist for a shared entry; rejected for user credentials. */
+    readonly users?: readonly string[];
+    /** Absent user settings mean enabled for all, disabled for opt-in. */
+    readonly availability?: McpAvailability;
     /** Skip this server entirely (default false). */
     readonly disabled?: boolean;
     /** Skip this server entirely (default true; contradicts `disabled`). */
@@ -53,10 +59,31 @@ export interface McpServerConfig {
     readonly toolExposure?: Readonly<Record<string, McpExposure>>;
     /** Per-request wire timeout in seconds (default 60). */
     readonly timeout?: number;
+}
+/** One configured MCP server (stdio transport). */
+export interface McpStdioServerConfig extends McpServerCommon {
+    /** The executable to spawn. */
+    readonly command: string;
+    /** Arguments to the executable. */
+    readonly args: readonly string[];
+    /** Extra environment variables for the child process. */
+    readonly env?: Readonly<Record<string, string>>;
     /** OAuth (T3c): when present, `sigrun-ext-mcp oauth <name>` can mint a
      * token and spawn injects it as `MCP_ACCESS_TOKEN` (see tokens.ts). */
     readonly oauth?: McpOAuthConfig;
 }
+/** One configured MCP server (remote transport: streamable HTTP, with a
+ * legacy-SSE fallback negotiated on first contact). */
+export interface McpUrlServerConfig extends McpServerCommon {
+    /** The server endpoint (http/https). */
+    readonly url: string;
+    /** Extra request headers (auth etc.), sent on every request. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** One configured MCP server: stdio OR remote. */
+export type McpServerConfig = McpStdioServerConfig | McpUrlServerConfig;
+/** Narrow to the stdio variant (the spawn path). */
+export declare function isStdioServer(server: McpServerConfig): server is McpStdioServerConfig;
 /** OAuth block for one server: how to run the authorization-code flow. */
 export interface McpOAuthConfig {
     /** The AS's authorize endpoint (GET; the user opens this in a browser). */
@@ -70,13 +97,21 @@ export interface McpOAuthConfig {
     /** PKCE method (optional; only "S256" is implemented — and always used). */
     readonly codeChallengeMethod?: string;
 }
+export type UserServersMode = "none" | "remote" | "all";
 /** The parsed `mcp.json` body. */
 export interface McpConfig {
     readonly servers: Readonly<Record<string, McpServerConfig>>;
+    readonly userServers?: UserServersMode;
 }
 /** The env override the config store reads. */
 export declare const MCP_CONFIG_ENV = "SIGRUN_MCP_CONFIG";
-/** Resolve the config path without reading it (for diagnostics). */
+/** Resolve the config path without reading it (for diagnostics).
+ *
+ * Resolution order: the `SIGRUN_MCP_CONFIG` override → the sigrun config
+ * dir (`SIGRUN_CONFIG_DIR`, the SAME root every sigrun store resolves
+ * through — a deployment setting one sets them all) → `~/.config/sigrun`
+ * (the pre-deployment fallback, kept so a bare user install keeps
+ * working). */
 export declare function resolveMcpConfigPath(env?: NodeJS.ProcessEnv): string;
 /**
  * Parse and validate an `mcp.json` body. Throws a clear error naming the
@@ -89,3 +124,4 @@ export declare function parseMcpConfig(text: string, source: string): McpConfig;
  * nothing); an existing-but-malformed file throws.
  */
 export declare function loadMcpConfig(env?: NodeJS.ProcessEnv): McpConfig;
+export {};

package/dist/config.js

@@ -16,7 +16,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { isAbsolute, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 /** Config-level exposure words: the four real ones plus pi's `codemode-deferred`
  * alias (normalized to "codemode" at parse time — pi compat). */
 const EXPOSURE_WORDS = [
@@ -85,15 +85,29 @@ export function resolveToolExposure(server, toolName) {
 export function serverEnabled(server) {
     return server.enabled !== false && server.disabled !== true;
 }
+/** Narrow to the stdio variant (the spawn path). */
+export function isStdioServer(server) {
+    return "command" in server;
+}
 /** The env override the config store reads. */
 export const MCP_CONFIG_ENV = "SIGRUN_MCP_CONFIG";
-/** Resolve the config path without reading it (for diagnostics). */
+/** Resolve the config path without reading it (for diagnostics).
+ *
+ * Resolution order: the `SIGRUN_MCP_CONFIG` override → the sigrun config
+ * dir (`SIGRUN_CONFIG_DIR`, the SAME root every sigrun store resolves
+ * through — a deployment setting one sets them all) → `~/.config/sigrun`
+ * (the pre-deployment fallback, kept so a bare user install keeps
+ * working). */
 export function resolveMcpConfigPath(env = process.env) {
     const override = env[MCP_CONFIG_ENV];
     if (override !== undefined && override !== "") {
         // A relative override resolves against cwd, like sigrun's other paths.
         return isAbsolute(override) ? override : resolve(override);
     }
+    const configDir = env.SIGRUN_CONFIG_DIR;
+    if (configDir !== undefined && configDir !== "") {
+        return join(configDir, "mcp.json");
+    }
     return resolve(homedir(), ".config", "sigrun", "mcp.json");
 }
 function isRecord(value) {
@@ -114,16 +128,47 @@ export function parseMcpConfig(text, source) {
     if (!isRecord(parsed)) {
         throw new Error(`mcp config ${source} must be a JSON object`);
     }
+    const userServers = parsed.userServers ?? "none";
+    if (userServers !== "none" && userServers !== "remote" && userServers !== "all") {
+        throw new Error(`mcp config ${source}: userServers must be one of "none", "remote", "all"`);
+    }
     const servers = {};
     const rawServers = parsed.servers;
     if (!isRecord(rawServers)) {
         throw new Error(`mcp config ${source} must have a "servers" object mapping names to server entries`);
     }
     for (const [name, entry] of Object.entries(rawServers)) {
+        if (name === "servers") {
+            throw new Error(`mcp config ${source}: server "servers" uses the reserved user settings namespace`);
+        }
+        if (name.startsWith("u_")) {
+            throw new Error(`mcp config ${source}: server "${name}" uses the reserved "u_" prefix`);
+        }
         if (!isRecord(entry)) {
             throw new Error(`mcp config ${source}: server "${name}" must be an object`);
         }
-        if (typeof entry.command !== "string" ||
+        // Transport dispatch: a server is EITHER a stdio child or a remote
+        // endpoint. Both arms share the optional fields below; each arm then
+        // validates its own required fields.
+        const hasCommand = entry.command !== undefined || entry.args !== undefined;
+        const hasUrl = entry.url !== undefined;
+        if (hasCommand && hasUrl) {
+            throw new Error(`mcp config ${source}: server "${name}" cannot carry both "command" (stdio) and "url" (remote) — pick one transport`);
+        }
+        if (!hasCommand && !hasUrl) {
+            throw new Error(`mcp config ${source}: server "${name}" needs either "command"+"args" (stdio) or "url" (remote)`);
+        }
+        if (hasUrl) {
+            if (typeof entry.url !== "string" || !/^https?:\/\//.test(entry.url)) {
+                throw new Error(`mcp config ${source}: server "${name}" url must be an http(s) URL`);
+            }
+            if (entry.headers !== undefined &&
+                (!isRecord(entry.headers) ||
+                    Object.values(entry.headers).some((v) => typeof v !== "string"))) {
+                throw new Error(`mcp config ${source}: server "${name}" headers must map strings to strings`);
+            }
+        }
+        else if (typeof entry.command !== "string" ||
             !Array.isArray(entry.args) ||
             entry.args.some((arg) => typeof arg !== "string")) {
             throw new Error(`mcp config ${source}: server "${name}" needs a string "command" and a string[] "args"`);
@@ -133,6 +178,28 @@ export function parseMcpConfig(text, source) {
                 Object.values(entry.env).some((v) => typeof v !== "string"))) {
             throw new Error(`mcp config ${source}: server "${name}" env must map strings to strings`);
         }
+        const credentials = (entry.credentials ?? "user");
+        if (credentials !== "user" && credentials !== "shared") {
+            throw new Error(`mcp config ${source}: server "${name}" credentials must be "user" or "shared"`);
+        }
+        if (credentials === "shared" &&
+            (typeof entry.sharedAuthority !== "string" ||
+                entry.sharedAuthority.trim() === "")) {
+            throw new Error(`mcp config ${source}: server "${name}" requires a non-empty sharedAuthority when credentials are "shared"`);
+        }
+        if (entry.users !== undefined) {
+            if (credentials !== "shared") {
+                throw new Error(`mcp config ${source}: server "${name}" users is only valid with credentials "shared"`);
+            }
+            if (!Array.isArray(entry.users) ||
+                entry.users.some((user) => typeof user !== "string" || user.trim() === "")) {
+                throw new Error(`mcp config ${source}: server "${name}" users must be a string[] of non-empty users`);
+            }
+        }
+        const availability = (entry.availability ?? "all");
+        if (availability !== "all" && availability !== "opt-in") {
+            throw new Error(`mcp config ${source}: server "${name}" availability must be "all" or "opt-in"`);
+        }
         if (entry.disabled !== undefined && typeof entry.disabled !== "boolean") {
             throw new Error(`mcp config ${source}: server "${name}" disabled must be a boolean`);
         }
@@ -169,21 +236,50 @@ export function parseMcpConfig(text, source) {
         const oauth = entry.oauth === undefined
             ? undefined
             : parseOauthEntry(entry.oauth, source, name);
-        servers[name] = {
-            command: entry.command,
-            args: entry.args,
-            ...(entry.env === undefined
+        const catalog = {
+            // Preserve the pre-catalog serialized shape when both fields are
+            // absent. Consumers use nullish defaults, so omitted and explicit
+            // default values are equivalent without changing legacy fixtures.
+            ...(entry.credentials === undefined ? {} : { credentials }),
+            ...(entry.availability === undefined ? {} : { availability }),
+            ...(entry.sharedAuthority === undefined
                 ? {}
-                : { env: entry.env }),
-            ...(entry.disabled === undefined ? {} : { disabled: entry.disabled }),
-            ...(entry.enabled === undefined ? {} : { enabled: entry.enabled }),
-            ...(exposure === undefined ? {} : { exposure }),
-            ...(toolExposure === undefined ? {} : { toolExposure }),
-            ...(entry.timeout === undefined ? {} : { timeout: entry.timeout }),
-            ...(oauth === undefined ? {} : { oauth }),
+                : { sharedAuthority: entry.sharedAuthority }),
+            ...(entry.users === undefined
+                ? {}
+                : { users: entry.users }),
         };
+        // The common optionals first, then the transport arm's own fields —
+        // the union stays discriminable by "command" vs "url" presence.
+        servers[name] = hasUrl
+            ? {
+                url: entry.url,
+                ...(entry.headers === undefined
+                    ? {}
+                    : { headers: entry.headers }),
+                ...(entry.disabled === undefined ? {} : { disabled: entry.disabled }),
+                ...(entry.enabled === undefined ? {} : { enabled: entry.enabled }),
+                ...(exposure === undefined ? {} : { exposure }),
+                ...(toolExposure === undefined ? {} : { toolExposure }),
+                ...(entry.timeout === undefined ? {} : { timeout: entry.timeout }),
+                ...catalog,
+            }
+            : {
+                command: entry.command,
+                args: entry.args,
+                ...(entry.env === undefined
+                    ? {}
+                    : { env: entry.env }),
+                ...(entry.disabled === undefined ? {} : { disabled: entry.disabled }),
+                ...(entry.enabled === undefined ? {} : { enabled: entry.enabled }),
+                ...(exposure === undefined ? {} : { exposure }),
+                ...(toolExposure === undefined ? {} : { toolExposure }),
+                ...(entry.timeout === undefined ? {} : { timeout: entry.timeout }),
+                ...(oauth === undefined ? {} : { oauth }),
+                ...catalog,
+            };
     }
-    return { servers };
+    return { servers, userServers };
 }
 /** Parse one server's oauth block. Fail-loud on a wrong shape: a
  * half-configured block is a config error, not a silently-ignored field. */

package/dist/extension.d.ts

@@ -1,51 +1,32 @@
-/**
- * The MCP extension (sigrun-ext-mcp): registers every tool discovered on
- * the configured MCP servers as a pi-durable tool named
- * `<server>/<toolname>` (ruling 4).
- *
- * Contract (sigrun's src/harness/loader.ts): the package default-exports a
- * FACTORY TAKING NO ARGUMENTS, returning `{ extension }`. The loader calls
- * it synchronously at boot, before `Harness.open` reads the registry — so
- * the factory returns immediately and the async connect/discover work lands
- * through a LIVE tools array (the registry re-reads `extension.tools` on
- * every snapshot, so tools discovered after install appear in the harness
- * without a reinstall).
- *
- * Lifecycle (ruling 5): servers spawn eagerly at factory time (a server is
- * a long-lived stdio process; lazy-at-first-use buys nothing and complicates
- * discovery visibility). Each server is ISOLATED: a spawn or handshake or
- * discovery failure quarantines just that server (warned, contributing no
- * tools) and never affects the others. Children are killed on process exit
- * and on `wiring.close()`; there is no loader-side uninstall callback to
- * hook.
- *
- * Config (ruling 2): `mcp.json` resolved as `SIGRUN_MCP_CONFIG` env
- * override → `~/.config/sigrun/mcp.json`. Malformed config THROWS from the
- * factory (the loader's quarantine semantics take over); a missing config
- * is an empty registry (the extension installs with zero tools).
- */
+/** Catalog wiring: shared operator services remain system children, while
+ * per-user entries connect and publish through the structural sigrun host. */
 import { type Extension } from "@earendil-works/pi-durable";
-/** The extension's pi-durable registry name. */
+import { type CatalogSettingsSection, type OwnerEvent, type SigrunHost, type UserService } from "./user-servers.js";
 export declare const MCP_EXTENSION_NAME = "sigrun.mcp";
-/** What {@link createMcpExtension} returns (the loader contract: `.extension`). */
+export interface ExtensionRouteContribution {
+    readonly method: "POST";
+    readonly path: string;
+    readonly auth: "user";
+    handler(request: Request, ctx: {
+        readonly principal?: {
+            readonly user?: string;
+        };
+        readonly host: SigrunHost;
+    }): Promise<Response>;
+}
 export interface McpWiring {
-    /** The extension to install into the harness registry. */
     readonly extension: Extension;
-    /**
-     * Kill every connected MCP server child process (idempotent). Called on
-     * process exit automatically; hosts may call it on harness shutdown.
-     */
-    close(): void;
-    /**
-     * Resolves when every enabled server has connected (and discovered its
-     * tools) or failed (isolated). Hosts that want tools present before
-     * `Harness.open` reads the registry await this; the loader does not.
-     */
+    readonly perUserTools: boolean;
+    readonly routes: readonly ExtensionRouteContribution[];
+    readonly userServices: readonly UserService[];
+    readonly surfaces: {
+        readonly settings: readonly CatalogSettingsSection[];
+    };
+    conversationCreated(event: OwnerEvent): Promise<void>;
+    runSettled(event: OwnerEvent): Promise<void>;
+    onSettingsChanged(keys: readonly string[], user?: string): Promise<void>;
+    /** Stop system clients immediately; per-user clients drain in-flight calls. */
+    close(): Promise<void>;
     readonly ready: Promise<void>;
 }
-/**
- * The extension factory (the loader contract: no arguments; config resolves
- * from the package context — the `SIGRUN_MCP_CONFIG` override or the sigrun
- * config dir).
- */
-export declare function createMcpExtension(): McpWiring;
+export declare function createMcpExtension(host: SigrunHost): McpWiring;