@plurnk/plurnk-mcp 1.6.1 → 1.8.0

package/dist/Module.js

@@ -1,55 +1,876 @@
-import ServerConnection from "./client.js";
-import { serverConfig, serverNames } from "./config.js";
-import McpExecutor, { runtimeDecl } from "./McpExecutor.js";
+import { Problems, Validator, } from "@plurnk/plurnk-contracts";
+import ServerConnection, { AuthorizationRequiredError, isClientCredentialsRejection, } from "./client.js";
+import { expandedServerNames, overlayServerDefinitions, serviceDefinitions, serviceEnabledNames, summaryOverrides, } from "./config.js";
+import McpExecutor, { runtimeDecl, serverSummary } from "./McpExecutor.js";
 import McpResources from "./McpResources.js";
+const OWNER = "@plurnk/plurnk-mcp";
+const STATE_VERSION = 1;
+const attachmentConnection = (attachment) => attachment.kind === "unavailable" ? undefined : attachment.connection;
+class ModuleActionError extends Error {
+    problem;
+    constructor(problem, cause) {
+        super(problem.detail, { cause });
+        this.name = "ModuleActionError";
+        this.problem = problem;
+    }
+}
+const actionError = (code, status, detail, extensions = {}, cause) => new ModuleActionError(Problems.create("mcp:management", code, status, detail, {
+    stage: "mcp-management",
+    retryable: status === 409 || status >= 500,
+    ...extensions,
+}), cause);
+const errorsOf = (error) => error instanceof AggregateError ? [...error.errors] : [error];
+const preparationError = (definition, cause, closeCause) => {
+    const completeCause = closeCause === undefined
+        ? cause
+        : new AggregateError([cause, closeCause], `MCP server '${definition.name}' preparation and cleanup failed.`);
+    // {§oauth-client-credentials} — a rejected grant is an authorization fact,
+    // never a generic unavailability.
+    if (definition.authorization?.type === "client-credentials" && isClientCredentialsRejection(cause)) {
+        return actionError("oauth-client-credentials-failed", 502, `MCP server '${definition.name}' rejected the client-credentials grant; check the configured client credentials and issuer.`, {
+            server: definition.name,
+            transport: definition.transport,
+            clientId: definition.authorization.clientId,
+            ...(definition.authorization.issuer === undefined
+                ? {}
+                : { issuer: definition.authorization.issuer }),
+            retryable: false,
+        }, completeCause);
+    }
+    return actionError("server-unavailable", 502, `Configured MCP server '${definition.name}' is unavailable.`, {
+        server: definition.name,
+        transport: definition.transport,
+        retryable: true,
+    }, completeCause);
+};
+export const closeConnections = async (connections) => {
+    const results = await Promise.allSettled([...new Set(connections)].map((connection) => connection.close()));
+    const errors = results
+        .filter((result) => result.status === "rejected")
+        .flatMap((result) => errorsOf(result.reason));
+    if (errors.length > 0) {
+        throw new AggregateError(errors, "MCP connection shutdown failed");
+    }
+};
+const objectOf = (value) => typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value
+    : null;
+const assertExactKeys = (value, allowed, owner) => {
+    const extras = Object.keys(value).filter((key) => !allowed.includes(key));
+    if (extras.length > 0)
+        throw new Error(`${owner} contains unsupported field(s): ${extras.join(", ")}.`);
+};
+const emptyState = () => ({ version: STATE_VERSION, servers: {} });
+const parseState = (source) => {
+    if (source === null)
+        return emptyState();
+    const state = objectOf(source);
+    if (state === null)
+        throw new Error("MCP workspace state must be an object.");
+    assertExactKeys(state, ["version", "servers"], "MCP workspace state");
+    if (state.version !== STATE_VERSION) {
+        throw new Error(`MCP workspace state version must be ${STATE_VERSION}.`);
+    }
+    const servers = objectOf(state.servers);
+    if (servers === null)
+        throw new Error("MCP workspace state servers must be an object.");
+    const parsed = {};
+    for (const [name, raw] of Object.entries(servers).toSorted(([left], [right]) => left.localeCompare(right))) {
+        const value = objectOf(raw);
+        if (value === null || (value.kind !== "service" && value.kind !== "workspace")) {
+            throw new Error(`MCP workspace server '${name}' has an invalid state.`);
+        }
+        if (typeof value.enabled !== "boolean") {
+            throw new Error(`MCP workspace server '${name}' must declare boolean enabledness.`);
+        }
+        if (value.kind === "service") {
+            assertExactKeys(value, ["kind", "enabled"], `MCP workspace server '${name}'`);
+            parsed[name] = { kind: "service", enabled: value.enabled };
+            continue;
+        }
+        assertExactKeys(value, ["kind", "definition", "enabled"], `MCP workspace server '${name}'`);
+        const definition = structuredClone(Validator.assertMcpServerDefinition(value.definition));
+        if (definition.name !== name) {
+            throw new Error(`MCP workspace server key '${name}' does not match definition '${definition.name}'.`);
+        }
+        parsed[name] = { kind: "workspace", definition, enabled: value.enabled };
+    }
+    return { version: STATE_VERSION, servers: parsed };
+};
+const persistedState = (state) => Object.keys(state.servers).length === 0 ? null : state;
+const cloneState = (state) => parseState(structuredClone(state));
+const sameDefinition = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const sameServerState = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const requiredString = (params, field) => {
+    const value = params[field];
+    if (typeof value !== "string" || value.length === 0) {
+        throw actionError("parameter-required", 400, `MCP action requires a non-empty '${field}' string.`, { field, retryable: false });
+    }
+    return value;
+};
+const assertActionKeys = (params, allowed) => {
+    const extras = Object.keys(params).filter((key) => !allowed.includes(key));
+    if (extras.length === 0)
+        return;
+    throw actionError("parameters-invalid", 400, `MCP action contains unsupported parameter(s): ${extras.join(", ")}.`, { fields: extras, retryable: false });
+};
+const workspaceIdOf = (context) => {
+    if (context.scope !== "workspace") {
+        throw actionError("workspace-context-required", 500, "MCP action received no workspace context.");
+    }
+    return context.workspaceId;
+};
+const statusOf = (error) => {
+    const candidate = objectOf(error);
+    const direct = objectOf(candidate?.problem);
+    if (typeof direct?.status === "number")
+        return direct.status;
+    const result = objectOf(candidate?.result);
+    const problem = objectOf(result?.problem);
+    return typeof problem?.status === "number" ? problem.status : null;
+};
 export default class Module {
     #env;
-    #connections = new Map();
+    #summaries;
+    #expanded;
+    #defaults;
+    #defaultEnabled;
+    #workspaces = new Map();
+    // {§oauth-lifetime} — pending candidates are process-memory per
+    // (workspace, alias); a restart loses them by design.
+    #pending = new Map();
+    #locks = new Map();
+    #refreshTimers = new Map();
+    #seam;
+    #closed = false;
     static init(options = {}) {
         return new Module(options.env ?? process.env);
     }
     constructor(environ) {
         this.#env = environ;
+        this.#defaults = new Map(serviceDefinitions(environ).map((definition) => [definition.name, definition]));
+        this.#defaultEnabled = new Set(serviceEnabledNames(environ));
+        this.#summaries = summaryOverrides(environ);
+        this.#expanded = new Set(expandedServerNames(environ));
     }
     async setup(seam) {
-        const results = await Promise.allSettled(serverNames(this.#env).map(async (name) => {
-            const config = serverConfig(name, this.#env);
-            if (config === null)
-                throw new Error(`MCP server '${name}' disappeared during configuration.`);
-            const connection = new ServerConnection(config, this.#env);
-            this.#connections.set(name, connection);
-            const decl = runtimeDecl(name);
-            const executor = new McpExecutor({
-                runtime: name,
-                glyph: decl.glyph ?? "",
-            }, connection);
+        this.#seam = seam;
+        seam.registerWorkspaceCapabilityProvider(OWNER, {
+            hydrate: async (workspaceId) => this.#serialize(workspaceId, async () => {
+                const state = parseState(await seam.readWorkspaceModuleState(workspaceId, OWNER));
+                await this.#applyState(workspaceId, state, {
+                    authorizationDisposition: "publish-required",
+                    preparationFailureDisposition: "publish-unavailable",
+                });
+            }),
+        });
+        const action = (name, handler) => seam.registerModuleAction({ name, scope: "workspace", handler });
+        action("workspace.mcp.list", async (params, context) => {
+            assertActionKeys(params, ["overlay"]);
+            return this.#list(workspaceIdOf(context), params.overlay);
+        });
+        action("workspace.mcp.add", async (params, context) => this.#add(workspaceIdOf(context), params));
+        action("workspace.mcp.enable", async (params, context) => this.#setEnabled(workspaceIdOf(context), params, true));
+        action("workspace.mcp.disable", async (params, context) => this.#setEnabled(workspaceIdOf(context), params, false));
+        action("workspace.mcp.remove", async (params, context) => this.#remove(workspaceIdOf(context), params));
+        action("workspace.mcp.oauth.complete", async (params, context) => this.#completeOAuth(workspaceIdOf(context), params));
+        action("workspace.mcp.complete", async (params, context) => this.#complete(workspaceIdOf(context), params));
+    }
+    #pendingKey(workspaceId, name) {
+        return `${workspaceId}:${name}`;
+    }
+    async #serialize(workspaceId, run) {
+        const prior = this.#locks.get(workspaceId) ?? Promise.resolve();
+        let release = () => undefined;
+        const barrier = new Promise((resolve) => { release = resolve; });
+        const queued = prior.then(() => barrier, () => barrier);
+        this.#locks.set(workspaceId, queued);
+        await prior.catch(() => undefined);
+        try {
+            return await run();
+        }
+        finally {
+            release();
+            if (this.#locks.get(workspaceId) === queued)
+                this.#locks.delete(workspaceId);
+        }
+    }
+    #available(state) {
+        const available = new Map([...this.#defaults].map(([name, definition]) => [
+            name,
+            {
+                definition: structuredClone(definition),
+                source: "service",
+                enabled: this.#defaultEnabled.has(name),
+            },
+        ]));
+        for (const [name, value] of Object.entries(state.servers)) {
+            if (value.kind === "service") {
+                const configured = available.get(name);
+                if (configured !== undefined)
+                    available.set(name, { ...configured, enabled: value.enabled });
+                continue;
+            }
+            available.set(name, {
+                definition: structuredClone(value.definition),
+                source: "workspace",
+                enabled: value.enabled,
+            });
+        }
+        return new Map([...available].toSorted(([left], [right]) => left.localeCompare(right)));
+    }
+    #enabled(state) {
+        return new Map([...this.#available(state)]
+            .filter(([, value]) => value.enabled)
+            .map(([name, { definition, source }]) => [name, { definition, source }]));
+    }
+    async #prepareAttachment(workspaceId, effective, connection) {
+        const definition = effective.definition;
+        const candidate = connection ?? new ServerConnection(definition, this.#env, {
+            onCatalogChanged: (error) => {
+                if (error !== null) {
+                    console.error(`MCP server '${definition.name}' catalog refresh failed:`, error);
+                    return;
+                }
+                this.#scheduleCatalogRefresh(workspaceId, definition.name);
+            },
+            onInfrastructureError: (error) => {
+                console.error(`MCP server '${definition.name}' infrastructure failure:`, error);
+            },
+        });
+        const executor = new McpExecutor({ runtime: definition.name, glyph: "🔌" }, candidate, { tools: definition.tools ?? null, read: definition.read ?? [] }, this.#summaries.tools);
+        try {
+            const availability = await executor.requireAvailable();
             return {
-                namespaceOwner: "@plurnk/plurnk-mcp",
-                decl,
+                kind: "active",
+                ...effective,
+                connection: candidate,
                 executor,
-                availability: await executor.probe(),
-                scheme: new McpResources(name, connection),
+                runtime: {
+                    namespaceOwner: OWNER,
+                    decl: runtimeDecl(definition.name, serverSummary(definition.name, executor.catalog, this.#summaries.servers.get(definition.name)), this.#expanded.has(definition.name)),
+                    executor,
+                    availability,
+                    scheme: new McpResources(definition.name, candidate, executor.catalog),
+                },
             };
-        }));
-        const errors = results
-            .filter((result) => result.status === "rejected")
-            .map((result) => result.reason);
-        if (errors.length > 0)
-            throw new AggregateError(errors, "MCP module setup failed");
-        const registrations = results.flatMap((result) => result.status === "fulfilled" ? [result.value] : []);
-        for (const registration of registrations) {
-            await seam.registerRuntime(registration);
+        }
+        catch (cause) {
+            if (cause instanceof AuthorizationRequiredError) {
+                return {
+                    kind: "authorization-required",
+                    ...effective,
+                    connection: candidate,
+                    authorizationUrl: cause.authorizationUrl,
+                };
+            }
+            let closeCause;
+            try {
+                await candidate.close();
+            }
+            catch (error) {
+                closeCause = error;
+            }
+            throw preparationError(definition, cause, closeCause);
         }
     }
+    async #applyState(workspaceId, state, options) {
+        const seam = this.#seam;
+        if (seam === undefined)
+            throw new Error("MCP module is not set up.");
+        const current = this.#workspaces.get(workspaceId);
+        const effective = this.#enabled(state);
+        const force = options.force ?? new Set();
+        for (const [name, attachment] of current?.attachments ?? []) {
+            const next = effective.get(name);
+            if (next === undefined
+                || force.has(name)
+                || !sameDefinition(attachment.definition, next.definition))
+                attachmentConnection(attachment)?.assertReplaceable();
+        }
+        const next = new Map();
+        const fresh = [];
+        try {
+            for (const [name, definition] of effective) {
+                const existing = current?.attachments.get(name);
+                if (existing !== undefined
+                    && !force.has(name)
+                    && sameDefinition(existing.definition, definition.definition)) {
+                    next.set(name, existing);
+                    continue;
+                }
+                const supplied = options.prepared?.get(name);
+                let attachment;
+                try {
+                    attachment = supplied ?? await this.#prepareAttachment(workspaceId, definition);
+                }
+                catch (cause) {
+                    if (options.preparationFailureDisposition === "reject")
+                        throw cause;
+                    const failure = cause instanceof ModuleActionError
+                        ? cause
+                        : preparationError(definition.definition, cause);
+                    attachment = {
+                        kind: "unavailable",
+                        ...definition,
+                        problem: structuredClone(failure.problem),
+                    };
+                    console.error(`MCP server '${name}' unavailable during workspace hydration: ${failure.problem.detail}`, failure.cause ?? failure);
+                }
+                next.set(name, attachment);
+                if (attachment.kind !== "unavailable")
+                    fresh.push(attachment);
+            }
+        }
+        catch (cause) {
+            const cleanup = await Promise.allSettled(fresh.map(({ connection }) => connection.close()));
+            const failures = cleanup.flatMap((result) => result.status === "rejected" ? errorsOf(result.reason) : []);
+            if (failures.length > 0) {
+                throw new AggregateError([cause, ...failures], "MCP workspace preparation and cleanup failed.");
+            }
+            throw cause;
+        }
+        const authorization = [...fresh].find((attachment) => attachment.kind === "authorization-required");
+        if (authorization !== undefined && options.authorizationDisposition === "defer-mutation") {
+            const discard = fresh.filter((attachment) => attachment !== authorization);
+            await closeConnections(discard.map(({ connection }) => connection));
+            return { authorization };
+        }
+        const runtimes = [...next.values()].flatMap((attachment) => attachment.kind === "active" ? [attachment.runtime] : []);
+        try {
+            await seam.replaceWorkspaceCapabilities({
+                workspaceId,
+                namespaceOwner: OWNER,
+                state: persistedState(state),
+                runtimes,
+            });
+        }
+        catch (cause) {
+            const cleanup = await Promise.allSettled(fresh.map(({ connection }) => connection.close()));
+            const failures = cleanup.flatMap((result) => result.status === "rejected" ? errorsOf(result.reason) : []);
+            if (failures.length > 0) {
+                throw new AggregateError([cause, ...failures], "MCP workspace commit and cleanup failed.");
+            }
+            throw cause;
+        }
+        this.#workspaces.set(workspaceId, { state: cloneState(state), attachments: next });
+        const retained = new Set([...next.values()].flatMap((attachment) => attachmentConnection(attachment) ?? []));
+        const obsolete = [...current?.attachments.values() ?? []]
+            .flatMap((attachment) => attachmentConnection(attachment) ?? [])
+            .filter((connection) => !retained.has(connection));
+        if (obsolete.length > 0) {
+            try {
+                await closeConnections(obsolete);
+            }
+            catch (cause) {
+                throw actionError("obsolete-connection-close-failed", 500, "The MCP capability change committed, but an obsolete connection did not close cleanly.", { workspaceId, committed: true }, cause);
+            }
+        }
+        if (options.authorizationDisposition === "publish-required") {
+            for (const [name, attachment] of next) {
+                if (attachment.kind !== "authorization-required")
+                    continue;
+                await this.#setPending(workspaceId, name, {
+                    operation: "enable",
+                    expectedState: structuredClone(state.servers[name] ?? null),
+                    expectedDefinition: structuredClone(attachment.definition),
+                    expectedEnabled: true,
+                    definition: {
+                        definition: structuredClone(attachment.definition),
+                        source: attachment.source,
+                    },
+                    connection: attachment.connection,
+                    authorizationUrl: attachment.authorizationUrl,
+                }, false);
+            }
+        }
+        return authorization === undefined ? {} : { authorization };
+    }
+    async #setPending(workspaceId, name, pending, closeExisting = true) {
+        const key = this.#pendingKey(workspaceId, name);
+        const existing = this.#pending.get(key);
+        this.#pending.set(key, pending);
+        if (closeExisting && existing !== undefined && existing.connection !== pending.connection) {
+            await existing.connection.close();
+        }
+    }
+    async #clearPending(workspaceId, name, retained) {
+        const key = this.#pendingKey(workspaceId, name);
+        const pending = this.#pending.get(key);
+        this.#pending.delete(key);
+        if (pending === undefined || pending.connection === retained)
+            return;
+        try {
+            await pending.connection.close();
+        }
+        catch (cause) {
+            throw actionError("pending-authorization-close-failed", 500, "The MCP capability change committed, but its superseded authorization request did not close cleanly.", { workspaceId, name, committed: true }, cause);
+        }
+    }
+    #snapshot(workspaceId) {
+        const snapshot = this.#workspaces.get(workspaceId);
+        if (snapshot === undefined) {
+            throw actionError("workspace-not-hydrated", 409, "MCP capabilities have not been hydrated for this workspace.", { workspaceId, recovery: "Retry after workspace initialization completes." });
+        }
+        return snapshot;
+    }
+    #summary(alias, available, attachment) {
+        const definition = available.definition;
+        const base = {
+            alias,
+            source: available.source,
+            transport: definition.transport,
+            target: definition.transport === "http" ? definition.url : definition.command,
+            enabled: available.enabled,
+            state: available.enabled
+                ? attachment?.kind === "active"
+                    ? "connected"
+                    : attachment?.kind === "authorization-required"
+                        ? "authorization-required"
+                        : "unavailable"
+                : "disabled",
+            enabledTools: definition.tools ?? null,
+            read: definition.read ?? [],
+        };
+        if (attachment?.kind === "authorization-required") {
+            return { ...base, authorization: { url: attachment.authorizationUrl } };
+        }
+        if (attachment?.kind === "unavailable") {
+            return { ...base, problem: structuredClone(attachment.problem) };
+        }
+        if (attachment?.kind !== "active")
+            return base;
+        const catalog = attachment.executor.catalog;
+        return {
+            ...base,
+            protocolVersion: catalog.protocolVersion,
+            server: catalog.server ?? null,
+            capabilities: catalog.capabilities,
+            tools: catalog.tools.map(({ name: toolName }) => toolName).toSorted(),
+            resources: catalog.resources.length,
+            resourceTemplates: catalog.resourceTemplates.length,
+            prompts: catalog.prompts.length,
+        };
+    }
+    #overlayDefinitions(state, value) {
+        if (value === undefined)
+            return new Map();
+        try {
+            const bases = new Map([...this.#available(state)]
+                .map(([alias, { definition }]) => [alias, definition]));
+            return overlayServerDefinitions(structuredClone(value), bases);
+        }
+        catch (cause) {
+            throw actionError("configuration-invalid", 400, "Client MCP configuration is invalid.", { retryable: false }, cause);
+        }
+    }
+    #list(workspaceId, overlay) {
+        const snapshot = this.#snapshot(workspaceId);
+        const available = this.#available(snapshot.state);
+        const configured = this.#overlayDefinitions(snapshot.state, overlay);
+        const summaries = new Map([...available].map(([alias, definition]) => [
+            alias,
+            this.#summary(alias, definition, snapshot.attachments.get(alias)),
+        ]));
+        for (const [alias, definition] of configured) {
+            if (available.has(alias))
+                continue;
+            summaries.set(alias, this.#summary(alias, {
+                definition,
+                source: "client",
+                enabled: false,
+            }));
+        }
+        return {
+            servers: [...summaries]
+                .toSorted(([left], [right]) => left.localeCompare(right))
+                .map(([, summary]) => summary),
+        };
+    }
+    #definition(params) {
+        assertActionKeys(params, ["alias", "target", "options"]);
+        const alias = requiredString(params, "alias");
+        const target = requiredString(params, "target");
+        try {
+            const options = structuredClone(Validator.assertMcpServerOptions((params.options ?? {})));
+            const definition = /^https?:\/\//u.test(target)
+                ? { name: alias, transport: "http", url: target, ...options }
+                : {
+                    name: alias,
+                    transport: "stdio",
+                    command: target,
+                    ...options,
+                    args: options.args ?? [],
+                };
+            return structuredClone(Validator.assertMcpServerDefinition(definition));
+        }
+        catch (cause) {
+            throw actionError("definition-invalid", 400, `MCP server '${alias}' has an invalid target or options.`, { alias, retryable: false }, cause);
+        }
+    }
+    async #add(workspaceId, params) {
+        return this.#serialize(workspaceId, async () => {
+            const definition = this.#definition(params);
+            const alias = definition.name;
+            const snapshot = this.#snapshot(workspaceId);
+            if (this.#available(snapshot.state).has(alias)) {
+                throw actionError("server-exists", 409, `MCP server alias '${alias}' is already available in this workspace.`, { workspaceId, alias, retryable: false });
+            }
+            const state = cloneState(snapshot.state);
+            state.servers[alias] = {
+                kind: "workspace",
+                definition,
+                enabled: true,
+            };
+            const result = await this.#applyState(workspaceId, state, {
+                authorizationDisposition: "defer-mutation",
+                preparationFailureDisposition: "reject",
+            });
+            if (result.authorization !== undefined) {
+                await this.#setPending(workspaceId, alias, {
+                    operation: "add",
+                    expectedState: structuredClone(snapshot.state.servers[alias] ?? null),
+                    expectedDefinition: null,
+                    expectedEnabled: false,
+                    definition: { definition, source: "workspace" },
+                    connection: result.authorization.connection,
+                    authorizationUrl: result.authorization.authorizationUrl,
+                });
+                return {
+                    status: 202,
+                    authorization: { url: result.authorization.authorizationUrl },
+                };
+            }
+            const committed = this.#snapshot(workspaceId);
+            const attached = committed.attachments.get(alias);
+            if (attached === undefined || attached.kind === "unavailable") {
+                throw new Error("Committed MCP attachment is absent.");
+            }
+            await this.#clearPending(workspaceId, alias, attached.connection);
+            const available = this.#available(committed.state).get(alias);
+            if (available === undefined)
+                throw new Error("Committed MCP definition is absent.");
+            return { status: 201, server: this.#summary(alias, available, attached) };
+        });
+    }
+    #stateWithEnabled(state, alias, available, enabled) {
+        const next = cloneState(state);
+        if (available.source === "service") {
+            next.servers[alias] = { kind: "service", enabled };
+            return next;
+        }
+        const current = next.servers[alias];
+        if (current?.kind !== "workspace") {
+            throw new Error(`Workspace MCP server '${alias}' has no owned definition.`);
+        }
+        next.servers[alias] = { ...current, enabled };
+        return next;
+    }
+    #stateWithDefinition(state, alias, definition, enabled) {
+        const next = cloneState(state);
+        next.servers[alias] = this.#definitionSource(alias, definition) === "service"
+            ? { kind: "service", enabled }
+            : {
+                kind: "workspace",
+                definition: structuredClone(definition),
+                enabled,
+            };
+        return next;
+    }
+    #definitionSource(alias, definition) {
+        const service = this.#defaults.get(alias);
+        return service !== undefined && sameDefinition(service, definition)
+            ? "service"
+            : "workspace";
+    }
+    #definitionWithOptions(definition, value) {
+        if (value === undefined)
+            return structuredClone(definition);
+        try {
+            const options = structuredClone(Validator.assertMcpServerOptions(value));
+            return structuredClone(Validator.assertMcpServerDefinition({
+                ...definition,
+                ...options,
+            }));
+        }
+        catch (cause) {
+            throw actionError("definition-invalid", 400, `MCP server '${definition.name}' has invalid enable options.`, { alias: definition.name, retryable: false }, cause);
+        }
+    }
+    async #setEnabled(workspaceId, params, enabled) {
+        return this.#serialize(workspaceId, async () => {
+            assertActionKeys(params, enabled ? ["alias", "overlay", "options"] : ["alias"]);
+            const alias = requiredString(params, "alias");
+            const snapshot = this.#snapshot(workspaceId);
+            const current = this.#available(snapshot.state).get(alias);
+            const configured = enabled
+                ? this.#overlayDefinitions(snapshot.state, params.overlay).get(alias)
+                : undefined;
+            if (current === undefined && configured === undefined) {
+                throw actionError("server-not-found", 404, `MCP server alias '${alias}' is not available in this workspace.`, { workspaceId, alias, retryable: false });
+            }
+            if (current === undefined && !enabled)
+                throw new Error("Disabled MCP target is absent.");
+            const candidate = configured ?? current?.definition;
+            if (candidate === undefined)
+                throw new Error("Enabled MCP target is absent.");
+            const definition = enabled
+                ? this.#definitionWithOptions(candidate, params.options)
+                : structuredClone(candidate);
+            const attachment = snapshot.attachments.get(alias);
+            const retryUnavailable = enabled
+                && current?.enabled === true
+                && sameDefinition(current.definition, definition)
+                && attachment?.kind === "unavailable";
+            const definitionChanged = current === undefined
+                || !sameDefinition(current.definition, definition);
+            if (current?.enabled === enabled && !definitionChanged && !retryUnavailable) {
+                if (attachment?.kind === "authorization-required") {
+                    return {
+                        status: 202,
+                        authorization: { url: attachment.authorizationUrl },
+                    };
+                }
+                return { status: 200, server: this.#summary(alias, current, attachment) };
+            }
+            const state = retryUnavailable
+                ? cloneState(snapshot.state)
+                : enabled
+                    ? this.#stateWithDefinition(snapshot.state, alias, definition, true)
+                    : this.#stateWithEnabled(snapshot.state, alias, current, false);
+            const result = await this.#applyState(workspaceId, state, {
+                ...(retryUnavailable ? { force: new Set([alias]) } : {}),
+                authorizationDisposition: "defer-mutation",
+                preparationFailureDisposition: "reject",
+            });
+            if (result.authorization !== undefined) {
+                await this.#setPending(workspaceId, alias, {
+                    operation: "enable",
+                    expectedState: structuredClone(snapshot.state.servers[alias] ?? null),
+                    expectedDefinition: structuredClone(current?.definition ?? null),
+                    expectedEnabled: current?.enabled ?? false,
+                    definition: {
+                        definition: structuredClone(definition),
+                        source: this.#definitionSource(alias, definition),
+                    },
+                    connection: result.authorization.connection,
+                    authorizationUrl: result.authorization.authorizationUrl,
+                });
+                return {
+                    status: 202,
+                    authorization: { url: result.authorization.authorizationUrl },
+                };
+            }
+            await this.#clearPending(workspaceId, alias);
+            const committed = this.#snapshot(workspaceId);
+            const committedDefinition = this.#available(committed.state).get(alias);
+            if (committedDefinition === undefined)
+                throw new Error("Committed MCP definition is absent.");
+            return {
+                status: 200,
+                server: this.#summary(alias, committedDefinition, committed.attachments.get(alias)),
+            };
+        });
+    }
+    async #remove(workspaceId, params) {
+        return this.#serialize(workspaceId, async () => {
+            assertActionKeys(params, ["alias"]);
+            const alias = requiredString(params, "alias");
+            const snapshot = this.#snapshot(workspaceId);
+            const available = this.#available(snapshot.state).get(alias);
+            if (available === undefined) {
+                throw actionError("server-not-found", 404, `MCP server alias '${alias}' is not available in this workspace.`, { workspaceId, alias, retryable: false });
+            }
+            if (available.source === "service") {
+                throw actionError("server-service-owned", 409, `MCP server alias '${alias}' is service-owned and can be disabled, not removed.`, { workspaceId, alias, recovery: `Use workspace.mcp.disable for '${alias}'.`, retryable: false });
+            }
+            const state = cloneState(snapshot.state);
+            const service = this.#defaults.get(alias);
+            if (service === undefined) {
+                delete state.servers[alias];
+            }
+            else {
+                state.servers[alias] = {
+                    kind: "service",
+                    enabled: false,
+                };
+            }
+            await this.#applyState(workspaceId, state, {
+                authorizationDisposition: "defer-mutation",
+                preparationFailureDisposition: "reject",
+            });
+            await this.#clearPending(workspaceId, alias);
+            return { status: 200, alias, removed: true };
+        });
+    }
+    #oauthCompletionState(workspaceId, alias, pending) {
+        const snapshot = this.#snapshot(workspaceId);
+        const available = this.#available(snapshot.state).get(alias);
+        const current = available?.definition ?? null;
+        const expected = pending.expectedDefinition;
+        if (!sameServerState(snapshot.state.servers[alias] ?? null, pending.expectedState)
+            || (expected === null && current !== null)
+            || (expected !== null && (current === null || !sameDefinition(expected, current)))
+            || (available?.enabled ?? false) !== pending.expectedEnabled) {
+            throw actionError("oauth-target-conflict", 409, `MCP server '${alias}' changed while its OAuth authorization was pending.`, {
+                workspaceId,
+                alias,
+                recovery: "Start authorization again from the server's current definition.",
+                retryable: false,
+            });
+        }
+        if (pending.operation === "add") {
+            const state = cloneState(snapshot.state);
+            state.servers[alias] = {
+                kind: "workspace",
+                definition: structuredClone(pending.definition.definition),
+                enabled: true,
+            };
+            return state;
+        }
+        return this.#stateWithDefinition(snapshot.state, alias, pending.definition.definition, true);
+    }
+    async #completeOAuth(workspaceId, params) {
+        return this.#serialize(workspaceId, async () => {
+            assertActionKeys(params, ["alias", "callbackUrl"]);
+            const alias = requiredString(params, "alias");
+            const callbackUrl = requiredString(params, "callbackUrl");
+            const key = this.#pendingKey(workspaceId, alias);
+            const pending = this.#pending.get(key);
+            if (pending === undefined) {
+                // {§oauth-lifetime} — restart during pending authorization
+                // surfaces as a factual not-pending state, never a secret replay.
+                throw actionError("oauth-not-pending", 404, `MCP server '${alias}' has no pending OAuth authorization.`, { workspaceId, alias, retryable: false });
+            }
+            if (pending.prepared === undefined) {
+                try {
+                    await pending.connection.finishAuthorization(callbackUrl);
+                    const prepared = await this.#prepareAttachment(workspaceId, pending.definition, pending.connection);
+                    if (prepared.kind !== "active") {
+                        throw new Error("OAuth completion returned another authorization challenge.");
+                    }
+                    pending.prepared = prepared;
+                }
+                catch (cause) {
+                    throw actionError("oauth-callback-invalid", 400, `OAuth authorization for MCP server '${alias}' could not be completed.`, { workspaceId, alias, retryable: false }, cause);
+                }
+            }
+            const state = this.#oauthCompletionState(workspaceId, alias, pending);
+            await this.#applyState(workspaceId, state, {
+                force: new Set([alias]),
+                prepared: new Map([[alias, pending.prepared]]),
+                authorizationDisposition: "defer-mutation",
+                preparationFailureDisposition: "reject",
+            });
+            this.#pending.delete(key);
+            const committed = this.#snapshot(workspaceId);
+            const attached = committed.attachments.get(alias);
+            if (attached === undefined || attached.kind !== "active") {
+                throw new Error("Authorized MCP attachment is absent.");
+            }
+            const available = this.#available(committed.state).get(alias);
+            if (available === undefined)
+                throw new Error("Authorized MCP definition is absent.");
+            return { status: 200, server: this.#summary(alias, available, attached) };
+        });
+    }
+    async #complete(workspaceId, params) {
+        assertActionKeys(params, ["server", "ref", "argument", "context"]);
+        const server = requiredString(params, "server");
+        const attachment = this.#snapshot(workspaceId).attachments.get(server);
+        if (attachment === undefined || attachment.kind !== "active") {
+            throw actionError("server-not-connected", 409, `MCP server '${server}' is not connected in this workspace.`, { workspaceId, name: server, retryable: false });
+        }
+        const ref = objectOf(params.ref);
+        const argument = objectOf(params.argument);
+        if (ref === null || argument === null) {
+            throw actionError("completion-parameters-invalid", 400, "MCP completion requires 'ref' and 'argument' objects.", { retryable: false });
+        }
+        return attachment.connection.complete({
+            ref: ref,
+            argument: argument,
+            ...(objectOf(params.context) === null ? {} : { context: params.context }),
+        });
+    }
+    async #refreshCatalog(workspaceId, name) {
+        const seam = this.#seam;
+        if (seam === undefined)
+            throw new Error("MCP module is not set up.");
+        const snapshot = this.#workspaces.get(workspaceId);
+        const attachment = snapshot?.attachments.get(name);
+        if (snapshot === undefined || attachment === undefined || attachment.kind !== "active")
+            return;
+        const executor = new McpExecutor({ runtime: name, glyph: "🔌" }, attachment.connection, {
+            tools: attachment.definition.tools ?? null,
+            read: attachment.definition.read ?? [],
+        }, this.#summaries.tools);
+        const availability = await executor.requireAvailable();
+        const refreshed = {
+            ...attachment,
+            executor,
+            runtime: {
+                namespaceOwner: OWNER,
+                decl: runtimeDecl(name, serverSummary(name, executor.catalog, this.#summaries.servers.get(name)), this.#expanded.has(name)),
+                executor,
+                availability,
+                scheme: new McpResources(name, attachment.connection, executor.catalog),
+            },
+        };
+        const attachments = new Map(snapshot.attachments);
+        attachments.set(name, refreshed);
+        await seam.replaceWorkspaceCapabilities({
+            workspaceId,
+            namespaceOwner: OWNER,
+            state: persistedState(snapshot.state),
+            runtimes: [...attachments.values()].flatMap((candidate) => candidate.kind === "active" ? [candidate.runtime] : []),
+        });
+        this.#workspaces.set(workspaceId, {
+            state: cloneState(snapshot.state),
+            attachments,
+        });
+    }
+    #scheduleCatalogRefresh(workspaceId, name, attempt = 0) {
+        if (this.#closed)
+            return;
+        const key = this.#pendingKey(workspaceId, name);
+        if (this.#refreshTimers.has(key))
+            return;
+        const delay = Math.min(250 * (2 ** attempt), 5000);
+        const timer = setTimeout(() => {
+            this.#refreshTimers.delete(key);
+            void this.#serialize(workspaceId, async () => {
+                await this.#refreshCatalog(workspaceId, name);
+            }).catch((error) => {
+                if (statusOf(error) === 409) {
+                    this.#scheduleCatalogRefresh(workspaceId, name, attempt + 1);
+                    return;
+                }
+                console.error(`MCP server '${name}' capability refresh failed:`, error);
+            });
+        }, delay);
+        timer.unref();
+        this.#refreshTimers.set(key, timer);
+    }
     async close() {
-        const connections = [...this.#connections.values()];
-        this.#connections.clear();
-        const results = await Promise.allSettled(connections.map((connection) => connection.close()));
-        const errors = results
-            .filter((result) => result.status === "rejected")
-            .map((result) => result.reason);
-        if (errors.length > 0)
-            throw new AggregateError(errors, "MCP connection shutdown failed");
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const timer of this.#refreshTimers.values())
+            clearTimeout(timer);
+        this.#refreshTimers.clear();
+        const connections = new Set();
+        for (const snapshot of this.#workspaces.values()) {
+            for (const attachment of snapshot.attachments.values()) {
+                const connection = attachmentConnection(attachment);
+                if (connection !== undefined)
+                    connections.add(connection);
+            }
+        }
+        for (const pending of this.#pending.values())
+            connections.add(pending.connection);
+        this.#workspaces.clear();
+        this.#pending.clear();
+        await closeConnections([...connections]);
     }
 }
 //# sourceMappingURL=Module.js.map