@plurnk/plurnk-mcp 1.7.0 → 1.9.0

package/dist/Module.js

@@ -1,12 +1,21 @@
 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 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";
-import { MCP_PROTOCOL_VERSION } from "./protocol.js";
 const OWNER = "@plurnk/plurnk-mcp";
-const STATE_VERSION = 1;
+const FAMILY = "mcp";
+const NONEMPTY_STRING = { type: "string", minLength: 1 };
+const OPEN_OBJECT = { type: "object", additionalProperties: true };
+const MCP_DEFINITION = { $ref: "https://schemas.plurnk.xyz/v0/McpServerDefinition.json" };
+const MUTATION_RESULT = { $ref: "https://schemas.plurnk.xyz/v0/FunctionalityMutationResult.json" };
+const actionInput = (properties, required = []) => ({
+    type: "object",
+    additionalProperties: false,
+    properties,
+    ...(required.length === 0 ? {} : { required: [...required] }),
+});
+const attachmentConnection = (attachment) => attachment.kind === "unavailable" ? undefined : attachment.connection;
 class ModuleActionError extends Error {
     problem;
     constructor(problem, cause) {
@@ -21,36 +30,20 @@ const actionError = (code, status, detail, extensions = {}, cause) => new Module
     ...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.`, {
+    // {§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,
-            requiredRevision: MCP_PROTOCOL_VERSION,
-            requiredMethod: "server/discover",
+            clientId: definition.authorization.clientId,
+            ...(definition.authorization.issuer === undefined
+                ? {}
+                : { issuer: definition.authorization.issuer }),
             retryable: false,
         }, completeCause);
     }
@@ -72,78 +65,60 @@ export const closeConnections = async (connections) => {
 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 };
+const assertActionKeys = (params, allowed) => {
+    const extras = Object.keys(params).filter((key) => !allowed.includes(key));
+    if (extras.length > 0) {
+        throw actionError("parameters-invalid", 400, `Unsupported parameter(s): ${extras.join(", ")}.`, { retryable: false });
     }
-    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];
+const requiredString = (params, key) => {
+    const value = params[key];
     if (typeof value !== "string" || value.length === 0) {
-        throw actionError("parameter-required", 400, `MCP action requires a non-empty '${field}' string.`, { field, retryable: false });
+        throw actionError("parameters-invalid", 400, `'${key}' must be a non-empty string.`, { field: key, 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 workerIdentityOf = (context) => {
+    if (context.scope !== "worker")
+        throw new Error("MCP actions require a worker-scoped context.");
+    return { workspaceId: context.workspaceId, workerId: context.workerId };
 };
+const sameDefinition = (left, right) => JSON.stringify(left) === JSON.stringify(right);
 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);
+    if (typeof error !== "object" || error === null)
+        return null;
+    const problem = error.problem
+        ?? error.result?.problem;
     return typeof problem?.status === "number" ? problem.status : null;
 };
+const catalogDetail = (executor) => {
+    const catalog = executor.catalog;
+    return {
+        protocolVersion: catalog.protocolVersion,
+        server: catalog.server ?? null,
+        capabilities: catalog.capabilities,
+        tools: catalog.tools.map(({ name }) => name).toSorted(),
+        resources: catalog.resources.length,
+        resourceTemplates: catalog.resourceTemplates.length,
+        prompts: catalog.prompts.length,
+    };
+};
 export default class Module {
     #env;
+    #summaries;
+    #expanded;
     #defaults;
-    #workspaces = new Map();
+    #defaultEnabled;
+    // The committed attachments per Worker: the adapter's mirror of the snapshot
+    // the coordinator holds, for continuations and refresh.
+    #attachments = new Map();
+    #identities = new Map();
     #pending = new Map();
-    #locks = new Map();
+    #dirty = new Set();
+    #connections = new Set();
     #refreshTimers = new Map();
-    #seam;
+    #retainWorker = new Map();
+    #handle;
     #closed = false;
     static init(options = {}) {
         return new Module(options.env ?? process.env);
@@ -151,86 +126,192 @@ export default class Module {
     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) {
-        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",
-                });
-            }),
+        this.#handle = seam.registerFunctionalityAdapter({
+            family: FAMILY,
+            namespaceOwner: OWNER,
+            summary: "Manage this Worker's MCP server attachments: list, discover, add, enable, disable, remove.",
+            definitionSchema: MCP_DEFINITION,
+            available: async () => [...this.#defaults].map(([name, definition]) => ({
+                alias: name,
+                definition: structuredClone(definition),
+                enabled: this.#defaultEnabled.has(name),
+            })),
+            discover: (query) => this.#discover(query),
+            admit: async (input) => this.#admit(input),
+            prepare: (preparation) => this.#prepare(preparation),
+            teardown: (snapshot, identity) => this.#teardown(snapshot, identity),
+        });
+        // Protocol continuations beneath the common grammar.
+        seam.registerModuleAction({
+            name: "worker.mcp.oauth.complete",
+            scope: "worker",
+            inputSchema: actionInput({ alias: NONEMPTY_STRING, callbackUrl: NONEMPTY_STRING }, ["alias", "callbackUrl"]),
+            outputSchema: MUTATION_RESULT,
+            handler: (params, context) => this.#completeOAuth(workerIdentityOf(context), params),
+        });
+        seam.registerModuleAction({
+            name: "worker.mcp.complete",
+            scope: "worker",
+            inputSchema: actionInput({
+                server: NONEMPTY_STRING,
+                ref: OPEN_OBJECT,
+                argument: OPEN_OBJECT,
+                context: OPEN_OBJECT,
+            }, ["server", "ref", "argument"]),
+            outputSchema: OPEN_OBJECT,
+            handler: (params, context) => this.#complete(workerIdentityOf(context).workerId, params),
         });
-        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}`;
+    #assertOpen() {
+        if (this.#closed)
+            throw new Error("MCP module is closed.");
     }
-    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();
+    #handleOrThrow() {
+        if (this.#handle === undefined)
+            throw new Error("MCP module is not set up.");
+        return this.#handle;
+    }
+    #pendingKey(workerId, name) {
+        return `${workerId}:${name}`;
+    }
+    #retain(workerId) {
+        const retain = this.#retainWorker.get(workerId);
+        if (retain === undefined) {
+            throw new Error(`MCP worker ${workerId} has no Functionality residency context.`);
         }
-        finally {
-            release();
-            if (this.#locks.get(workspaceId) === queued)
-                this.#locks.delete(workspaceId);
+        return retain();
+    }
+    async #closeOwned(connections) {
+        const owned = [...new Set(connections)];
+        const results = await Promise.allSettled(owned.map((connection) => connection.close()));
+        const errors = [];
+        for (const [index, result] of results.entries()) {
+            if (result.status === "fulfilled") {
+                this.#connections.delete(owned[index]);
+                continue;
+            }
+            errors.push(...errorsOf(result.reason));
         }
-    }
-    #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",
+        if (errors.length > 0)
+            throw new AggregateError(errors, "MCP connection shutdown failed");
+    }
+    // {§mcp-discovery} — inert: a direct target is probed and disconnected;
+    // caller configuration is parsed into candidates; registry search waits for
+    // a configured downstream registry.
+    async #discover(query) {
+        this.#assertOpen();
+        const candidates = [];
+        if (query.configuration !== undefined) {
+            let definitions;
+            try {
+                definitions = overlayServerDefinitions(structuredClone(query.configuration), this.#defaults);
+            }
+            catch (cause) {
+                throw actionError("configuration-invalid", 400, "The supplied MCP configuration is invalid.", { retryable: false }, cause);
+            }
+            for (const [name, definition] of definitions) {
+                candidates.push({
+                    alias: name,
+                    definition,
+                    provenance: { kind: "client-configuration", source: `PLURNK_MCP_${name.toUpperCase().replaceAll("-", "_")}` },
+                    summary: `${definition.transport} ${definition.transport === "http" ? definition.url : definition.command}`,
                 });
+            }
+        }
+        if (query.source !== undefined) {
+            // A URL is a Streamable HTTP target; anything else is a command line
+            // split on whitespace (exact paths with spaces are added, not probed).
+            const source = query.source;
+            const [command = "", ...args] = source.trim().split(/\s+/u);
+            const definition = /^https?:\/\//u.test(source)
+                ? { name: "discovered", transport: "http", url: source }
+                : { name: "discovered", transport: "stdio", command, args };
+            Validator.assertMcpServerDefinition(definition);
+            const connection = new ServerConnection(definition, this.#env, {
+                onCatalogChanged: () => undefined,
+                onInfrastructureError: () => undefined,
+            });
+            this.#connections.add(connection);
+            const executor = new McpExecutor({ runtime: "discovered", glyph: "🔌" }, connection, () => () => undefined);
+            try {
+                await executor.requireAvailable();
+                const catalog = executor.catalog;
+                const name = catalog.server?.name?.toLowerCase().replaceAll(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "") || "discovered";
+                candidates.push({
+                    alias: name,
+                    definition: { ...definition, name },
+                    provenance: { kind: "direct-target", source },
+                    summary: serverSummary(name, catalog, undefined),
+                });
+            }
+            catch (cause) {
+                if (cause instanceof AuthorizationRequiredError) {
+                    candidates.push({
+                        alias: "discovered",
+                        definition,
+                        provenance: { kind: "direct-target", source },
+                        summary: "The server requires authorization before it can be inspected; add it and complete the authorization.",
+                    });
+                }
+                else {
+                    throw actionError("discover-failed", 502, `MCP target '${source}' could not be inspected.`, { source, retryable: true }, cause);
+                }
+            }
+            finally {
+                await this.#closeOwned([connection]);
+            }
+        }
+        if (query.query !== undefined && query.source === undefined && query.configuration === undefined) {
+            throw actionError("registry-not-configured", 501, "MCP registry search requires a configured downstream registry; none is configured.", { query: query.query, recovery: "Discover an explicit source (URL or command) or configure a registry.", retryable: false });
+        }
+        return candidates;
+    }
+    #admit(input) {
+        const params = objectOf(input) ?? {};
+        let definition;
+        try {
+            definition = structuredClone(Validator.assertMcpServerDefinition(structuredClone(params.definition)));
         }
-        return new Map([...effective].toSorted(([left], [right]) => left.localeCompare(right)));
+        catch (cause) {
+            throw actionError("definition-invalid", 400, "The MCP server definition is invalid.", { retryable: false }, cause);
+        }
+        const alias = typeof params.alias === "string" ? params.alias : definition.name;
+        if (alias !== definition.name) {
+            throw actionError("alias-mismatch", 400, `Alias '${alias}' must equal the definition's name '${definition.name}'.`, { alias, name: definition.name, retryable: false });
+        }
+        return { alias, definition };
     }
-    async #prepareAttachment(workspaceId, effective, connection) {
-        const definition = effective.definition;
+    async #prepareAttachment(workerId, definition, connection) {
+        this.#assertOpen();
         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);
+                this.#scheduleCatalogRefresh(workerId, 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.#connections.add(candidate);
+        const executor = new McpExecutor({ runtime: definition.name, glyph: "🔌" }, candidate, () => this.#retain(workerId), { tools: definition.tools ?? null, read: definition.read ?? [] }, this.#summaries.tools);
         try {
             const availability = await executor.requireAvailable();
             return {
                 kind: "active",
-                ...effective,
+                definition,
                 connection: candidate,
                 executor,
                 runtime: {
                     namespaceOwner: OWNER,
-                    decl: runtimeDecl(definition.name),
+                    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),
@@ -241,14 +322,14 @@ export default class Module {
             if (cause instanceof AuthorizationRequiredError) {
                 return {
                     kind: "authorization-required",
-                    ...effective,
+                    definition,
                     connection: candidate,
                     authorizationUrl: cause.authorizationUrl,
                 };
             }
             let closeCause;
             try {
-                await candidate.close();
+                await this.#closeOwned([candidate]);
             }
             catch (error) {
                 closeCause = error;
@@ -256,325 +337,191 @@ export default class Module {
             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();
+    // {§functionality-adapter} two-phase preparation: reuse unchanged live
+    // attachments, prepare the rest, and hand the coordinator runtimes and
+    // outcomes; commit adopts the set and closes what it no longer uses, abort
+    // closes only what this attempt opened.
+    async #prepare(preparation) {
+        this.#assertOpen();
+        const { workspaceId, workerId, enabled, failure, force } = preparation;
+        this.#identities.set(workerId, { workspaceId, workerId });
+        this.#retainWorker.set(workerId, preparation.retain);
+        const previous = preparation.previous ?? new Map();
+        for (const [name, attachment] of previous) {
+            const nextDefinition = enabled.get(name);
+            if (nextDefinition === undefined || force === name || !sameDefinition(attachment.definition, nextDefinition)) {
+                attachmentConnection(attachment)?.assertReplaceable();
+            }
         }
         const next = new Map();
+        const outcomes = new Map();
         const fresh = [];
+        const consumedPending = new Map();
         try {
-            for (const [name, definition] of effective) {
-                const existing = current?.attachments.get(name);
+            for (const [name, value] of enabled) {
+                const definition = value;
+                const existing = previous.get(name);
+                const pending = this.#pending.get(this.#pendingKey(workerId, name));
                 if (existing !== undefined
-                    && !force.has(name)
-                    && sameDefinition(existing.definition, definition.definition)) {
+                    && force !== name
+                    && !this.#dirty.has(this.#pendingKey(workerId, name))
+                    && sameDefinition(existing.definition, definition)
+                    && !(pending?.prepared !== undefined)) {
                     next.set(name, existing);
                     continue;
                 }
-                const supplied = options.prepared?.get(name);
-                const attachment = supplied ?? await this.#prepareAttachment(workspaceId, definition);
+                let attachment;
+                if (pending?.prepared !== undefined && sameDefinition(pending.definition, definition)) {
+                    attachment = pending.prepared;
+                    consumedPending.set(name, pending);
+                }
+                else {
+                    try {
+                        attachment = await this.#prepareAttachment(workerId, definition);
+                    }
+                    catch (cause) {
+                        this.#assertOpen();
+                        if (failure === "reject")
+                            throw cause;
+                        const refusal = cause instanceof ModuleActionError ? cause : preparationError(definition, cause);
+                        attachment = { kind: "unavailable", definition, problem: structuredClone(refusal.problem) };
+                        console.error(`MCP server '${name}' unavailable: ${refusal.problem.detail}`, refusal.cause ?? refusal);
+                    }
+                    if (attachment.kind !== "unavailable")
+                        fresh.push(attachment);
+                }
                 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.");
+                this.#dirty.delete(this.#pendingKey(workerId, name));
             }
-            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 cleanup = await Promise.allSettled(fresh.map(({ connection }) => this.#closeOwned([connection])));
             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.");
-            }
+            if (failures.length > 0)
+                throw new AggregateError([cause, ...failures], "MCP worker preparation 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);
+        for (const [name, attachment] of next) {
+            switch (attachment.kind) {
+                case "active":
+                    outcomes.set(name, { state: "active", detail: catalogDetail(attachment.executor) });
+                    break;
+                case "unavailable":
+                    outcomes.set(name, { state: "unavailable", problem: attachment.problem });
+                    break;
+                case "authorization-required":
+                    outcomes.set(name, { state: "authorization-required", authorization: { url: attachment.authorizationUrl } });
+                    break;
             }
         }
-        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);
+        const runtimes = [...next.values()].flatMap((attachment) => attachment.kind === "active" ? [attachment.runtime] : []);
         return {
-            servers: [...snapshot.attachments]
-                .toSorted(([left], [right]) => left.localeCompare(right))
-                .map(([name, attachment]) => this.#summary(name, attachment)),
+            runtimes,
+            documents: [],
+            outcomes,
+            snapshot: next,
+            commit: async () => {
+                this.#attachments.set(workerId, next);
+                const retained = new Set([...next.values()].flatMap((attachment) => attachmentConnection(attachment) ?? []));
+                const pendingConnections = new Set([...this.#pending.values()].map(({ connection }) => connection));
+                const obsolete = [...previous.values()]
+                    .flatMap((attachment) => attachmentConnection(attachment) ?? [])
+                    .filter((connection) => !retained.has(connection) && !pendingConnections.has(connection));
+                for (const [name, pending] of consumedPending) {
+                    this.#pending.delete(this.#pendingKey(workerId, name));
+                    pending.releaseWorker();
+                }
+                for (const [name, attachment] of next) {
+                    if (attachment.kind !== "authorization-required")
+                        continue;
+                    const key = this.#pendingKey(workerId, name);
+                    const current = this.#pending.get(key);
+                    if (current?.connection === attachment.connection)
+                        continue;
+                    this.#pending.set(key, {
+                        definition: attachment.definition,
+                        connection: attachment.connection,
+                        authorizationUrl: attachment.authorizationUrl,
+                        releaseWorker: this.#retain(workerId),
+                    });
+                    if (current !== undefined) {
+                        current.releaseWorker();
+                        if (!retained.has(current.connection))
+                            obsolete.push(current.connection);
+                    }
+                }
+                if (obsolete.length > 0) {
+                    try {
+                        await this.#closeOwned(obsolete);
+                    }
+                    catch (cause) {
+                        throw actionError("obsolete-connection-close-failed", 500, "The MCP capability change committed, but an obsolete connection did not close cleanly.", { workerId, committed: true }, cause);
+                    }
+                }
+            },
+            abort: async () => {
+                await this.#closeOwned(fresh.map(({ connection }) => connection));
+            },
         };
     }
-    #definition(params) {
-        try {
-            return structuredClone(Validator.assertMcpServerDefinition(params.server));
+    async #teardown(snapshot, identity) {
+        const { workerId } = identity;
+        const pending = [...this.#pending.keys()].filter((key) => key.startsWith(`${workerId}:`));
+        if (pending.length > 0) {
+            throw new Error(`MCP worker ${workerId} cannot cool with pending OAuth residency.`);
         }
-        catch (cause) {
-            throw actionError("definition-invalid", 400, "The MCP server definition is invalid.", { field: "server", retryable: false }, cause);
+        for (const [key, timer] of this.#refreshTimers) {
+            if (!key.startsWith(`${workerId}:`))
+                continue;
+            clearTimeout(timer);
+            this.#refreshTimers.delete(key);
         }
-    }
-    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 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 attachments = snapshot ?? new Map();
+        const connections = [...attachments.values()].flatMap((attachment) => attachmentConnection(attachment) ?? []);
+        this.#attachments.delete(workerId);
+        this.#retainWorker.delete(workerId);
+        this.#identities.delete(workerId);
+        await this.#closeOwned(connections);
+    }
+    // {§oauth-continuation} — the callback finishes the pending connection's
+    // authorization, prepares its attachment, and re-enables the alias through
+    // the coordinator, which consumes the prepared attachment on publication.
+    async #completeOAuth(identity, params) {
+        assertActionKeys(params, ["alias", "callbackUrl"]);
+        const alias = requiredString(params, "alias");
+        const callbackUrl = requiredString(params, "callbackUrl");
+        const key = this.#pendingKey(identity.workerId, 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.`, { workerId: identity.workerId, alias, retryable: false });
         }
-        const state = cloneState(snapshot.state);
-        if (pending.operation === "attach" || pending.operation === "replace") {
-            state.servers[name] = {
-                kind: "attached",
-                definition: structuredClone(pending.definition.definition),
-            };
+        const current = this.#attachments.get(identity.workerId)?.get(alias);
+        if (current === undefined || current.kind !== "authorization-required" || !sameDefinition(current.definition, pending.definition)) {
+            throw actionError("oauth-target-conflict", 409, `MCP server '${alias}' changed while its OAuth authorization was pending.`, { workerId: identity.workerId, alias, recovery: "Start authorization again from the server's current definition.", retryable: false });
         }
-        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(identity.workerId, pending.definition, pending.connection);
+                if (prepared.kind !== "active")
+                    throw new Error("OAuth completion returned another authorization challenge.");
+                pending.prepared = prepared;
             }
-            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);
-                }
+            catch (cause) {
+                throw actionError("oauth-callback-invalid", 400, `OAuth authorization for MCP server '${alias}' could not be completed.`, { workerId: identity.workerId, alias, 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) };
-        });
+        }
+        const result = await this.#handleOrThrow().invoke("enable", { alias }, identity);
+        return result.body;
     }
-    async #complete(workspaceId, params) {
+    async #complete(workerId, params) {
+        assertActionKeys(params, ["server", "ref", "argument", "context"]);
         const server = requiredString(params, "server");
-        const attachment = this.#snapshot(workspaceId).attachments.get(server);
+        const attachment = this.#attachments.get(workerId)?.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 });
+            throw actionError("server-not-connected", 409, `MCP server '${server}' is not connected for this worker.`, { workerId, name: server, retryable: false });
         }
         const ref = objectOf(params.ref);
         const argument = objectOf(params.argument);
@@ -587,57 +534,24 @@ export default class Module {
             ...(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) {
+    // A live catalog change republishes the unchanged state; the dirty alias
+    // rebuilds its executor on the next preparation.
+    #scheduleCatalogRefresh(workerId, name, attempt = 0) {
         if (this.#closed)
             return;
-        const key = this.#pendingKey(workspaceId, name);
+        const key = this.#pendingKey(workerId, 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) => {
+            const identity = this.#identities.get(workerId);
+            if (identity === undefined || this.#closed)
+                return;
+            this.#dirty.add(key);
+            void this.#handleOrThrow().refresh(identity).catch((error) => {
                 if (statusOf(error) === 409) {
-                    this.#scheduleCatalogRefresh(workspaceId, name, attempt + 1);
+                    this.#scheduleCatalogRefresh(workerId, name, attempt + 1);
                     return;
                 }
                 console.error(`MCP server '${name}' capability refresh failed:`, error);
@@ -653,17 +567,14 @@ export default class Module {
         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);
-            }
-        }
+        const closing = this.#closeOwned([...this.#connections]);
+        this.#attachments.clear();
         for (const pending of this.#pending.values())
-            connections.add(pending.connection);
-        this.#workspaces.clear();
+            pending.releaseWorker();
         this.#pending.clear();
-        await closeConnections([...connections]);
+        this.#retainWorker.clear();
+        this.#identities.clear();
+        await closing;
     }
 }
 //# sourceMappingURL=Module.js.map