@plurnk/plurnk-mcp 1.6.1 → 1.7.0

package/dist/Module.js

@@ -1,55 +1,669 @@
-import ServerConnection from "./client.js";
-import { serverConfig, serverNames } from "./config.js";
+import { Problems, Validator, } from "@plurnk/plurnk-contracts";
+import { SdkError, SdkErrorCode, } from "@modelcontextprotocol/client";
+import ServerConnection, { AuthorizationRequiredError } from "./client.js";
+import { serviceDefinitions } from "./config.js";
 import McpExecutor, { runtimeDecl } from "./McpExecutor.js";
 import McpResources from "./McpResources.js";
+import { MCP_PROTOCOL_VERSION } from "./protocol.js";
+const OWNER = "@plurnk/plurnk-mcp";
+const STATE_VERSION = 1;
+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 errorTreeSome = (error, predicate, seen = new Set()) => {
+    if ((typeof error !== "object" && typeof error !== "function") || error === null) {
+        return predicate(error);
+    }
+    if (seen.has(error))
+        return false;
+    seen.add(error);
+    if (predicate(error))
+        return true;
+    if (error instanceof AggregateError) {
+        return [...error.errors].some((candidate) => errorTreeSome(candidate, predicate, seen));
+    }
+    return error instanceof Error && error.cause !== undefined
+        ? errorTreeSome(error.cause, predicate, seen)
+        : false;
+};
+const lacksRequiredProtocolRevision = (error) => errorTreeSome(error, (candidate) => SdkError.isInstance(candidate)
+    && candidate.code === SdkErrorCode.EraNegotiationFailed
+    && candidate.message.includes("the server did not offer pinned protocol version")
+    && candidate.message.includes("via server/discover"));
+const preparationError = (definition, cause, closeCause) => {
+    const completeCause = closeCause === undefined
+        ? cause
+        : new AggregateError([cause, closeCause], `MCP server '${definition.name}' preparation and cleanup failed.`);
+    if (lacksRequiredProtocolRevision(cause)) {
+        return actionError("protocol-revision-unsupported", 502, `MCP server '${definition.name}' did not offer required revision ${MCP_PROTOCOL_VERSION} through server/discover; upgrade or replace the legacy endpoint.`, {
+            server: definition.name,
+            transport: definition.transport,
+            requiredRevision: MCP_PROTOCOL_VERSION,
+            requiredMethod: "server/discover",
+            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 !== "attached" && value.kind !== "detached")) {
+            throw new Error(`MCP workspace server '${name}' has an invalid state.`);
+        }
+        if (value.kind === "detached") {
+            assertExactKeys(value, ["kind"], `MCP workspace server '${name}'`);
+            parsed[name] = { kind: "detached" };
+            continue;
+        }
+        assertExactKeys(value, ["kind", "definition"], `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: "attached", definition };
+    }
+    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 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 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();
+    #defaults;
+    #workspaces = new Map();
+    #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]));
     }
     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",
+                });
+            }),
+        });
+        const action = (name, handler) => seam.registerModuleAction({ name, scope: "workspace", handler });
+        action("workspace.mcp.list", async (_params, context) => this.#list(workspaceIdOf(context)));
+        action("workspace.mcp.attach", async (params, context) => this.#change("attach", workspaceIdOf(context), params));
+        action("workspace.mcp.replace", async (params, context) => this.#change("replace", workspaceIdOf(context), params));
+        action("workspace.mcp.detach", async (params, context) => this.#detach(workspaceIdOf(context), params));
+        action("workspace.mcp.reconnect", async (params, context) => this.#reconnect(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);
+        }
+    }
+    #effective(state) {
+        const effective = new Map([...this.#defaults].map(([name, definition]) => [
+            name,
+            { definition: structuredClone(definition), source: "service" },
+        ]));
+        for (const [name, value] of Object.entries(state.servers)) {
+            if (value.kind === "detached")
+                effective.delete(name);
+            else
+                effective.set(name, {
+                    definition: structuredClone(value.definition),
+                    source: "workspace",
+                });
+        }
+        return new Map([...effective].toSorted(([left], [right]) => left.localeCompare(right)));
+    }
+    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 ?? [] });
+        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),
+                    executor,
+                    availability,
+                    scheme: new McpResources(definition.name, candidate, executor.catalog),
+                },
+            };
+        }
+        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.#effective(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))
+                attachment.connection.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);
+                const attachment = supplied ?? await this.#prepareAttachment(workspaceId, definition);
+                next.set(name, attachment);
+                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()].map(({ connection }) => connection));
+        const obsolete = [...current?.attachments.values() ?? []]
+            .map(({ connection }) => connection)
+            .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: "reconnect",
+                    expectedDefinition: structuredClone(attachment.definition),
+                    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(name, attachment) {
+        const definition = attachment.definition;
+        const base = {
+            name,
+            source: attachment.source,
+            transport: definition.transport,
+            state: attachment.kind === "active" ? "connected" : "authorization-required",
+            enabledTools: definition.tools ?? null,
+            read: definition.read ?? [],
+        };
+        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,
+        };
+    }
+    #list(workspaceId) {
+        const snapshot = this.#snapshot(workspaceId);
+        return {
+            servers: [...snapshot.attachments]
+                .toSorted(([left], [right]) => left.localeCompare(right))
+                .map(([name, attachment]) => this.#summary(name, attachment)),
+        };
+    }
+    #definition(params) {
+        try {
+            return structuredClone(Validator.assertMcpServerDefinition(params.server));
+        }
+        catch (cause) {
+            throw actionError("definition-invalid", 400, "The MCP server definition is invalid.", { field: "server", retryable: false }, cause);
+        }
+    }
+    async #change(operation, workspaceId, params) {
+        return this.#serialize(workspaceId, async () => {
+            const definition = this.#definition(params);
+            const snapshot = this.#snapshot(workspaceId);
+            const effective = this.#effective(snapshot.state);
+            const exists = effective.has(definition.name);
+            if (operation === "attach" ? exists : !exists) {
+                throw actionError(operation === "attach" ? "server-exists" : "server-not-found", operation === "attach" ? 409 : 404, operation === "attach"
+                    ? `MCP server '${definition.name}' is already attached to this workspace.`
+                    : `MCP server '${definition.name}' is not attached to this workspace.`, { workspaceId, name: definition.name, retryable: false });
+            }
+            const state = cloneState(snapshot.state);
+            state.servers[definition.name] = {
+                kind: "attached",
+                definition,
             };
-        }));
-        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);
+            const result = await this.#applyState(workspaceId, state, {
+                force: new Set([definition.name]),
+                authorizationDisposition: "defer-mutation",
+            });
+            if (result.authorization !== undefined) {
+                await this.#setPending(workspaceId, definition.name, {
+                    operation,
+                    expectedDefinition: exists
+                        ? structuredClone(effective.get(definition.name)?.definition ?? null)
+                        : null,
+                    definition: { definition, source: "workspace" },
+                    connection: result.authorization.connection,
+                    authorizationUrl: result.authorization.authorizationUrl,
+                });
+                return {
+                    status: 202,
+                    authorization: { url: result.authorization.authorizationUrl },
+                };
+            }
+            const attached = this.#snapshot(workspaceId).attachments.get(definition.name);
+            if (attached === undefined)
+                throw new Error("Committed MCP attachment is absent.");
+            await this.#clearPending(workspaceId, definition.name, attached.connection);
+            return { status: operation === "attach" ? 201 : 200, server: this.#summary(definition.name, attached) };
+        });
+    }
+    async #detach(workspaceId, params) {
+        return this.#serialize(workspaceId, async () => {
+            const name = requiredString(params, "name");
+            const snapshot = this.#snapshot(workspaceId);
+            if (!this.#effective(snapshot.state).has(name)) {
+                throw actionError("server-not-found", 404, `MCP server '${name}' is not attached to this workspace.`, { workspaceId, name, retryable: false });
+            }
+            const state = cloneState(snapshot.state);
+            if (this.#defaults.has(name)) {
+                state.servers[name] = { kind: "detached" };
+            }
+            else {
+                delete state.servers[name];
+            }
+            await this.#applyState(workspaceId, state, {
+                force: new Set([name]),
+                authorizationDisposition: "defer-mutation",
+            });
+            await this.#clearPending(workspaceId, name);
+            return { status: 200, name, detached: true };
+        });
+    }
+    async #reconnect(workspaceId, params) {
+        return this.#serialize(workspaceId, async () => {
+            const name = requiredString(params, "name");
+            const snapshot = this.#snapshot(workspaceId);
+            const definition = this.#effective(snapshot.state).get(name);
+            if (definition === undefined) {
+                throw actionError("server-not-found", 404, `MCP server '${name}' is not attached to this workspace.`, { workspaceId, name, retryable: false });
+            }
+            const result = await this.#applyState(workspaceId, snapshot.state, {
+                force: new Set([name]),
+                authorizationDisposition: "defer-mutation",
+            });
+            if (result.authorization !== undefined) {
+                await this.#setPending(workspaceId, name, {
+                    operation: "reconnect",
+                    expectedDefinition: structuredClone(definition.definition),
+                    definition,
+                    connection: result.authorization.connection,
+                    authorizationUrl: result.authorization.authorizationUrl,
+                });
+                return {
+                    status: 202,
+                    authorization: { url: result.authorization.authorizationUrl },
+                };
+            }
+            const attached = this.#snapshot(workspaceId).attachments.get(name);
+            if (attached === undefined)
+                throw new Error("Reconnected MCP attachment is absent.");
+            await this.#clearPending(workspaceId, name, attached.connection);
+            return { status: 200, server: this.#summary(name, attached) };
+        });
+    }
+    #oauthCompletionState(workspaceId, name, pending) {
+        const snapshot = this.#snapshot(workspaceId);
+        const current = this.#effective(snapshot.state).get(name)?.definition ?? null;
+        const expected = pending.expectedDefinition;
+        if ((expected === null && current !== null)
+            || (expected !== null && (current === null || !sameDefinition(expected, current)))) {
+            throw actionError("oauth-target-conflict", 409, `MCP server '${name}' changed while its OAuth authorization was pending.`, {
+                workspaceId,
+                name,
+                recovery: "Start authorization again from the server's current definition.",
+                retryable: false,
+            });
+        }
+        const state = cloneState(snapshot.state);
+        if (pending.operation === "attach" || pending.operation === "replace") {
+            state.servers[name] = {
+                kind: "attached",
+                definition: structuredClone(pending.definition.definition),
+            };
+        }
+        return state;
+    }
+    async #completeOAuth(workspaceId, params) {
+        return this.#serialize(workspaceId, async () => {
+            const name = requiredString(params, "name");
+            const callbackUrl = requiredString(params, "callbackUrl");
+            const key = this.#pendingKey(workspaceId, name);
+            const pending = this.#pending.get(key);
+            if (pending === undefined) {
+                throw actionError("oauth-not-pending", 404, `MCP server '${name}' has no pending OAuth authorization.`, { workspaceId, name, 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 '${name}' could not be completed.`, { workspaceId, name, retryable: false }, cause);
+                }
+            }
+            const state = this.#oauthCompletionState(workspaceId, name, pending);
+            await this.#applyState(workspaceId, state, {
+                force: new Set([name]),
+                prepared: new Map([[name, pending.prepared]]),
+                authorizationDisposition: "defer-mutation",
+            });
+            this.#pending.delete(key);
+            const attached = this.#snapshot(workspaceId).attachments.get(name);
+            if (attached === undefined)
+                throw new Error("Authorized MCP attachment is absent.");
+            return { status: 200, server: this.#summary(name, attached) };
+        });
+    }
+    async #complete(workspaceId, params) {
+        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 ?? [],
+        });
+        const availability = await executor.requireAvailable();
+        const refreshed = {
+            ...attachment,
+            executor,
+            runtime: {
+                namespaceOwner: OWNER,
+                decl: runtimeDecl(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()) {
+                connections.add(attachment.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