@plurnk/plurnk-mcp 1.23.0 → 1.25.0

package/dist/Module.js

@@ -1,17 +1,16 @@
-var _a;
 // {§mcp-module} — the MCP family beneath the shared workspace Functionality
 // coordinator ({§functionality-adapter}). This module owns MCP protocol truth:
-// definitions from the POSIX cascade, inert discovery, connection preparation
-// with OAuth continuation, tool/resource publication, catalog refresh, and
-// teardown. The coordinator owns the lifecycle, durable workspace state, atomic
+// complete connection definitions, preparation with OAuth
+// continuation, tool/resource publication, catalog refresh, and teardown. The coordinator owns the lifecycle, durable workspace state, atomic
 // publication, and both the client and model projections.
 import { fileURLToPath } from "node:url";
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
-import { join } from "node:path";
-import { Problems, Validator, } from "@plurnk/plurnk-contracts";
-import ServerConnection, { AuthorizationRequiredError, isClientCredentialsRejection, } from "./client.js";
-import { expandedServerNames, overlayServerDefinitions, retryDelayMs, retryPacing, serviceDefinitions, serviceEnabledNames, summaryOverrides, } from "./config.js";
-import McpExecutor, { runtimeDecl, runtimeServerSummary, serverSummary } from "./McpExecutor.js";
+import { readDefinition } from "./definition.js";
+import { isDeepStrictEqual } from "node:util";
+import { Problems, } from "@plurnk/plurnk-contracts";
+import ServerConnection, { AuthorizationRequiredError, isClientCredentialsRejection, McpRedirectError, } from "./client.js";
+import { configuredDefinitions, connectTimeoutMs, expandedServerNames, retryDelayMs, retryPacing, registrySettings, serverSettings, } from "./config.js";
+import { RegistryError, registryEntries, searchRegistry } from "./registry.js";
+import McpExecutor, { runtimeDecl, runtimeServerSummary } from "./McpExecutor.js";
 import McpResources from "./McpResources.js";
 const OWNER = "@plurnk/plurnk-mcp";
 const FAMILY = "mcp";
@@ -39,26 +38,45 @@ const actionError = (code, status, detail, extensions = {}, cause) => new Module
     ...extensions,
 }), cause);
 const errorsOf = (error) => error instanceof AggregateError ? [...error.errors] : [error];
-const preparationError = (definition, cause, closeCause) => {
+// The first error of a type anywhere in a cause chain, aggregates included.
+const causeOf = (error, type, seen = new Set()) => {
+    if (error === null || typeof error !== "object" || seen.has(error))
+        return undefined;
+    seen.add(error);
+    if (error instanceof type)
+        return error;
+    for (const inner of error instanceof AggregateError ? error.errors : []) {
+        const found = causeOf(inner, type, seen);
+        if (found !== undefined)
+            return found;
+    }
+    return causeOf(error.cause, type, seen);
+};
+const preparationError = (definition, authorization, 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)) {
+    if (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
+            type: definition.type,
+            clientId: authorization.clientId,
+            ...(authorization.issuer === undefined
                 ? {}
-                : { issuer: definition.authorization.issuer }),
+                : { issuer: authorization.issuer }),
             retryable: false,
         }, completeCause);
     }
+    // {§mcp-redirect-refused} — the operator corrects the endpoint; retrying cannot.
+    const redirect = causeOf(cause, McpRedirectError);
+    if (redirect !== undefined) {
+        return actionError("server-redirected", 502, redirect.message, { server: definition.name, url: redirect.url, ...(redirect.location === null ? {} : { location: redirect.location }), retryable: false }, completeCause);
+    }
     return actionError("server-unavailable", 502, `Configured MCP server '${definition.name}' is unavailable.`, {
         server: definition.name,
-        transport: definition.transport,
+        type: definition.type,
         retryable: true,
     }, completeCause);
 };
@@ -92,7 +110,7 @@ const workspaceIdentityOf = (context) => {
         throw new Error("MCP actions require a workspace-scoped context.");
     return { workspaceId: context.workspaceId };
 };
-const sameDefinition = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const sameBinding = (left, right) => isDeepStrictEqual([left.definition, left.context], [right.definition, right.context]);
 const statusOf = (error) => {
     if (typeof error !== "object" || error === null)
         return null;
@@ -112,14 +130,14 @@ const catalogDetail = (executor) => {
         prompts: catalog.prompts.length,
     };
 };
-class Module {
+export default class Module {
     #env;
     #workspaceEnvironment;
-    #workspaceDirectory;
-    #summaries;
-    #expanded;
-    #defaults;
-    #defaultEnabled;
+    #plugins;
+    #configurationNotices = new Map();
+    #operatorEnvironment;
+    #stateDirectory;
+    #configurationDirectories;
     // The committed attachments per workspace: the adapter's mirror of the snapshot
     // the coordinator holds, for continuations and refresh.
     #attachments = new Map();
@@ -131,43 +149,42 @@ class Module {
     #retainWorkspace = new Map();
     #handle;
     #closed = false;
+    #stopping = null;
     static init(options = {}) {
-        return new _a(options.env ?? process.env);
+        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) {
+        this.#plugins = (workspaceId) => seam.readWorkspacePlugins(workspaceId);
         this.#workspaceEnvironment = (workspaceId) => seam.readWorkspaceEnvironment(workspaceId);
-        this.#workspaceDirectory = (workspaceId) => seam.workspaceStateDirectory(workspaceId, OWNER);
+        this.#operatorEnvironment = () => seam.operatorEnvironment();
+        this.#stateDirectory = (workspaceId, owner) => seam.workspaceStateDirectory(workspaceId, owner);
+        this.#configurationDirectories = (workspaceId) => seam.workspaceConfigurationDirectories(workspaceId);
         this.#handle = seam.registerFunctionalityAdapter({
             family: FAMILY,
             namespaceOwner: OWNER,
             summary: "Manage MCP servers",
             definitionSchema: MCP_DEFINITION,
-            example: { alias: "files", definition: { name: "files", transport: "stdio", command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "/absolute/project/path"] } },
+            example: { alias: "example-server", definition: { name: "example-server", type: "stdio", command: "npx", args: ["-y", "example-mcp-server@1.0.0"] } },
             docsDir: fileURLToPath(new URL("..", import.meta.url)),
             discovery: {
-                details: "`source` is one MCP server URL or command line; the server is inspected without being attached, and the candidate carries the exact definition to add.",
+                details: "`query` searches the MCP Registry by server name; each candidate carries the exact definition to add.",
             },
-            available: async () => [...this.#defaults].map(([name, definition]) => ({
-                alias: name,
-                definition: structuredClone(definition),
-                enabled: this.#defaultEnabled.has(name),
-            })),
-            discover: (query, identity, options) => this.#discover(query, identity, options),
-            admit: async (input, _identity, _caller, options) => this.#admit(input, options),
+            available: (identity) => this.#available(identity),
+            configurationNotices: ({ workspaceId }) => this.#configurationNotices.get(workspaceId) ?? [],
+            discover: (query) => this.#discover(query),
+            admit: (input) => this.#admit(input),
             prepare: (preparation) => this.#prepare(preparation),
             teardown: (snapshot, identity) => this.#teardown(snapshot, identity),
+            refreshIfChanged: (identity) => this.#refreshIfChanged(identity),
         });
         // Protocol continuations beneath the common grammar.
         seam.registerModuleAction({
             name: "workspace.mcp.oauth.complete",
             scope: "workspace",
+            residency: "required",
             inputSchema: actionInput({ alias: NONEMPTY_STRING, callbackUrl: NONEMPTY_STRING }, ["alias", "callbackUrl"]),
             outputSchema: MUTATION_RESULT,
             handler: (params, context) => this.#completeOAuth(workspaceIdentityOf(context), params),
@@ -175,6 +192,7 @@ class Module {
         seam.registerModuleAction({
             name: "workspace.mcp.complete",
             scope: "workspace",
+            residency: "required",
             inputSchema: actionInput({
                 server: NONEMPTY_STRING,
                 ref: OPEN_OBJECT,
@@ -185,6 +203,68 @@ class Module {
             handler: (params, context) => this.#complete(workspaceIdentityOf(context).workspaceId, params),
         });
     }
+    async #available(identity) {
+        expandedServerNames(this.#env);
+        const { workspaceId } = identity;
+        const notices = [];
+        this.#configurationNotices.set(workspaceId, notices);
+        return configuredDefinitions(await this.#configurationDirectories(workspaceId), this.#env, {
+            ...await this.#plugins(workspaceId), report: (notice) => notices.push(notice),
+        });
+    }
+    // {§functionality-hotload} — a server's definition is complete, so the coordinator's
+    // comparison of what it would prepare with what it published is the change test.
+    async #refreshIfChanged(identity) {
+        await this.#handleOrThrow().refresh(identity, { gate: "none", ifChanged: true });
+    }
+    // {§mcp-registry-discovery} Candidates are complete definitions, never installations.
+    async #discover(query) {
+        if (query.configuration !== undefined) {
+            throw actionError("configuration-unsupported", 400, "MCP discovery searches the MCP Registry by query; client configuration contributes nothing.", { retryable: false });
+        }
+        if (query.source !== undefined) {
+            throw actionError("source-unsupported", 400, "MCP discovery searches the MCP Registry by query; it does not install from a source URL.", {
+                source: query.source, retryable: false,
+            });
+        }
+        if (query.query === undefined)
+            return [];
+        const { url, limit } = registrySettings(this.#env);
+        if (url === null) {
+            throw actionError("registry-not-configured", 501, "MCP registry search is off: the operator names no registry.", { query: query.query, retryable: false });
+        }
+        let servers;
+        try {
+            servers = await searchRegistry({ url, query: query.query, limit, timeoutMs: connectTimeoutMs(this.#env) });
+        }
+        catch (cause) {
+            throw actionError("discover-failed", 502, cause instanceof RegistryError ? cause.message : `The MCP Registry search for '${query.query}' failed.`, {
+                query: query.query, retryable: true,
+            }, cause);
+        }
+        return servers.flatMap(registryEntries).map((found) => ({
+            alias: found.alias,
+            summary: found.summary,
+            definition: readDefinition({ name: found.alias, ...structuredClone(found.entry) }),
+            provenance: { kind: "registry", source: url, reference: found.reference },
+        }));
+    }
+    // {§mcp-server-definition} Live additions use the same schema as configured definitions.
+    async #admit(input) {
+        const params = objectOf(input) ?? {};
+        let definition;
+        try {
+            definition = readDefinition(params.definition);
+        }
+        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 };
+    }
     #assertOpen() {
         if (this.#closed)
             throw new Error("MCP module is closed.");
@@ -218,149 +298,56 @@ class Module {
         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, identity, options = {}) {
+    // The attachment keeps the exact symbolic definition; resolved launch values never enter state.
+    async #prepareAttachment(workspaceId, binding, connection) {
+        const { definition, context } = binding;
         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: _a.#launchOptions(definition, options),
-                    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 = _a.#launchOptions(/^https?:\/\//u.test(source)
-                ? { name: "discovered", transport: "http", url: source }
-                : { name: "discovered", transport: "stdio", command, args }, options);
-            Validator.assertMcpServerDefinition(definition);
-            const environment = await this.#workspaceEnvironment(identity.workspaceId);
-            let directory;
-            const connection = new ServerConnection(definition, environment(this.#env), {
-                environment: environment(),
-                workingDirectory: async () => directory ??= await mkdtemp(join(await this.#workspaceDirectory(identity.workspaceId), "discover-")),
-                onCatalogChanged: () => undefined,
-                onInfrastructureError: () => undefined,
-            });
-            this.#connections.add(connection);
-            const executor = new McpExecutor({ runtime: "discovered", glyph: "🔌" }, connection, () => () => undefined);
-            let failure;
-            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 {
-                    failure = actionError("discover-failed", 502, `MCP target '${source}' could not be inspected.`, { source, retryable: true }, cause);
-                }
-            }
-            try {
-                await this.#closeOwned([connection]);
-                if (directory !== undefined)
-                    await rm(directory, { recursive: true, force: true });
-            }
-            catch (cause) {
-                if (failure !== undefined)
-                    throw new AggregateError([failure, cause], "MCP discovery and cleanup failed.");
-                throw cause;
-            }
-            if (failure !== undefined)
-                throw failure;
-        }
-        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;
-    }
-    static #launchOptions(definition, options) {
-        if (options.env === undefined || Object.keys(options.env).length === 0)
-            return definition;
-        if (definition.transport !== "stdio")
-            throw actionError("env-transport", 400, "An HTTP MCP server has no local process environment.", { retryable: false });
-        return { ...definition, env: { ...definition.env, ...options.env } };
-    }
-    #admit(input, options = {}) {
-        const params = objectOf(input) ?? {};
-        let definition;
+        // {§mcp-server-settings} — the operator's settings for this alias; a bad one isolates this server.
+        let settings;
         try {
-            definition = structuredClone(Validator.assertMcpServerDefinition(structuredClone(params.definition)));
+            settings = serverSettings(definition.name, this.#env);
         }
         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 });
+            throw actionError("server-settings-invalid", 422, `MCP server '${definition.name}' has invalid operator settings: ${cause instanceof Error ? cause.message : String(cause)}`, {
+                server: definition.name, retryable: false,
+            }, cause);
         }
-        return { alias, definition: _a.#launchOptions(definition, options) };
-    }
-    async #prepareAttachment(workspaceId, definition, connection) {
-        this.#assertOpen();
-        const environment = await this.#workspaceEnvironment(workspaceId);
-        const candidate = connection ?? new ServerConnection(definition, environment(this.#env), {
-            environment: environment(),
-            workingDirectory: async () => {
-                const directory = join(await this.#workspaceDirectory(workspaceId), "servers", definition.name);
-                await mkdir(directory, { recursive: true, mode: 0o700 });
-                return directory;
-            },
-            onCatalogChanged: (error) => {
-                if (error !== null) {
-                    console.error(`MCP server '${definition.name}' catalog refresh failed:`, error);
-                    return;
-                }
-                if (this.#closed)
-                    return;
-                this.#dirty.set(this.#pendingKey(workspaceId, definition.name), Symbol());
-                this.#scheduleCatalogRefresh(workspaceId, definition.name);
-            },
-            onInfrastructureError: (error) => {
-                console.error(`MCP server '${definition.name}' infrastructure failure:`, error);
-            },
-        });
-        this.#connections.add(candidate);
-        const executor = new McpExecutor({ runtime: definition.name, glyph: "🔌" }, candidate, () => this.#retain(workspaceId), { tools: definition.tools ?? null, read: definition.read ?? [] }, this.#summaries.tools);
+        let candidate = connection;
         try {
+            const environment = await this.#workspaceEnvironment(workspaceId);
+            this.#assertOpen();
+            // {§mcp-launch-environment} — a configured server inherits the operator's environment beneath the
+            // workspace layer, as every MCP client launches one; the model's command ceiling is not its base.
+            candidate ??= new ServerConnection(definition, environment(this.#env), {
+                ...(definition.type === "stdio" && definition.cwd === undefined && context === undefined ? { cwd: await this.#stateDirectory(workspaceId, `${OWNER}/${definition.name}`) } : {}),
+                ...(context === undefined ? {} : { plugin: context }),
+                environment: environment(this.#operatorEnvironment()),
+                onCatalogChanged: (error) => {
+                    if (error !== null) {
+                        console.error(`MCP server '${definition.name}' catalog refresh failed:`, error);
+                        return;
+                    }
+                    if (this.#closed)
+                        return;
+                    this.#dirty.set(this.#pendingKey(workspaceId, definition.name), Symbol());
+                    this.#scheduleCatalogRefresh(workspaceId, definition.name);
+                },
+                onInfrastructureError: (error) => {
+                    console.error(`MCP server '${definition.name}' infrastructure failure:`, error);
+                },
+            });
+            this.#connections.add(candidate);
+            const executor = new McpExecutor({ runtime: definition.name, glyph: "🔌" }, candidate, () => this.#retain(workspaceId), { tools: settings.tools });
             const availability = await executor.requireAvailable();
             return {
+                ...(context === undefined ? {} : { context }),
                 kind: "active",
                 definition,
                 connection: candidate,
                 executor,
                 runtime: {
                     namespaceOwner: OWNER,
-                    decl: runtimeDecl(definition.name, runtimeServerSummary(definition.name, executor.catalog, this.#summaries.servers.get(definition.name)), this.#expanded.has(definition.name), executor.catalog.instructions),
+                    decl: runtimeDecl(definition.name, runtimeServerSummary(definition.name, executor.catalog), expandedServerNames(this.#env).includes(definition.name), executor.catalog.instructions),
                     executor,
                     availability,
                     scheme: new McpResources(definition.name, candidate, executor.catalog),
@@ -368,8 +355,9 @@ class Module {
             };
         }
         catch (cause) {
-            if (cause instanceof AuthorizationRequiredError) {
+            if (cause instanceof AuthorizationRequiredError && candidate !== undefined) {
                 return {
+                    ...(context === undefined ? {} : { context }),
                     kind: "authorization-required",
                     definition,
                     connection: candidate,
@@ -377,7 +365,7 @@ class Module {
                 };
             }
             let closeCause;
-            if (connection === undefined) {
+            if (connection === undefined && candidate !== undefined) {
                 try {
                     await this.#closeOwned([candidate]);
                 }
@@ -385,7 +373,7 @@ class Module {
                     closeCause = error;
                 }
             }
-            throw preparationError(definition, cause, closeCause);
+            throw preparationError(definition, definition.type === "streamable-http" ? definition.authorization : undefined, cause, closeCause);
         }
     }
     // {§functionality-adapter} two-phase preparation: reuse unchanged live
@@ -400,7 +388,7 @@ class Module {
         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)) {
+            if (nextDefinition === undefined || force === name || !sameBinding(attachment, nextDefinition)) {
                 const activeRequests = attachmentConnection(attachment)?.activeRequests ?? 0;
                 if (activeRequests > 0)
                     throw actionError("server-busy", 409, `MCP server '${name}' has ${activeRequests} active request(s).`, { server: name, activeRequests, retryable: true });
@@ -413,15 +401,17 @@ class Module {
         const refreshed = new Map();
         try {
             for (const [name, value] of enabled) {
+                preparation.progress(name);
                 const key = this.#pendingKey(workspaceId, name);
                 const invalidation = this.#dirty.get(key);
-                const definition = value;
+                const binding = value;
+                const { definition } = binding;
                 const existing = previous.get(name);
                 const pending = this.#pending.get(this.#pendingKey(workspaceId, name));
                 if (existing !== undefined
                     && force !== name
                     && !this.#dirty.has(this.#pendingKey(workspaceId, name))
-                    && sameDefinition(existing.definition, definition)
+                    && sameBinding(existing, binding)
                     && !(pending?.prepared !== undefined)) {
                     next.set(name, existing);
                     continue;
@@ -430,10 +420,10 @@ class Module {
                 const heldConnection = existing === undefined ? undefined : attachmentConnection(existing);
                 const catalogOnly = existing !== undefined
                     && force !== name
-                    && sameDefinition(existing.definition, definition)
+                    && sameBinding(existing, binding)
                     && !(pending?.prepared !== undefined)
                     && heldConnection !== undefined;
-                if (pending?.prepared !== undefined && sameDefinition(pending.definition, definition)) {
+                if (pending?.prepared !== undefined && sameBinding(pending, binding)) {
                     attachment = pending.prepared;
                     consumedPending.set(name, pending);
                 }
@@ -443,7 +433,7 @@ class Module {
                     // spawned, so neither abort nor commit has anything of this alias to close
                     // (#429).
                     try {
-                        attachment = await this.#prepareAttachment(workspaceId, definition, heldConnection);
+                        attachment = await this.#prepareAttachment(workspaceId, binding, heldConnection);
                     }
                     catch (cause) {
                         this.#assertOpen();
@@ -453,14 +443,14 @@ class Module {
                 }
                 else {
                     try {
-                        attachment = await this.#prepareAttachment(workspaceId, definition);
+                        attachment = await this.#prepareAttachment(workspaceId, binding);
                     }
                     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) };
+                        const refusal = cause instanceof ModuleActionError ? cause : preparationError(definition, undefined, cause);
+                        attachment = { ...binding, kind: "unavailable", problem: structuredClone(refusal.problem) };
                         console.error(`MCP server '${name}' unavailable: ${refusal.problem.detail}`, refusal.cause ?? refusal);
                     }
                     // Only a connection this attempt opened is the attempt's to close on abort.
@@ -473,7 +463,7 @@ class Module {
             }
         }
         catch (cause) {
-            const cleanup = await Promise.allSettled(fresh.map(({ connection }) => this.#closeOwned([connection])));
+            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 preparation and cleanup failed.");
@@ -520,6 +510,18 @@ class Module {
                     this.#pending.delete(this.#pendingKey(workspaceId, name));
                     pending.releaseWorkspace();
                 }
+                // {§oauth-lifetime} Only the same pending connection can retain its authorization flow.
+                for (const [key, pending] of this.#pending) {
+                    if (!key.startsWith(`${workspaceId}:`))
+                        continue;
+                    const current = next.get(key.slice(`${workspaceId}:`.length));
+                    if (current?.kind === "authorization-required" && current.connection === pending.connection)
+                        continue;
+                    this.#pending.delete(key);
+                    pending.releaseWorkspace();
+                    if (!retained.has(pending.connection))
+                        obsolete.push(pending.connection);
+                }
                 for (const [name, attachment] of next) {
                     if (attachment.kind !== "authorization-required")
                         continue;
@@ -529,6 +531,7 @@ class Module {
                         continue;
                     this.#pending.set(key, {
                         definition: attachment.definition,
+                        ...(attachment.context === undefined ? {} : { context: attachment.context }),
                         connection: attachment.connection,
                         authorizationUrl: attachment.authorizationUrl,
                         releaseWorkspace: this.#retain(workspaceId),
@@ -585,13 +588,13 @@ class Module {
             throw actionError("oauth-not-pending", 404, `MCP server '${alias}' has no pending OAuth authorization.`, { workspaceId: identity.workspaceId, alias, retryable: false });
         }
         const current = this.#attachments.get(identity.workspaceId)?.get(alias);
-        if (current === undefined || current.kind !== "authorization-required" || !sameDefinition(current.definition, pending.definition)) {
+        if (current === undefined || current.kind !== "authorization-required" || !sameBinding(current, pending)) {
             throw actionError("oauth-target-conflict", 409, `MCP server '${alias}' changed while its OAuth authorization was pending.`, { workspaceId: identity.workspaceId, alias, recovery: "Start authorization again from the server's current definition.", retryable: false });
         }
         if (pending.prepared === undefined) {
             try {
                 await pending.connection.finishAuthorization(callbackUrl);
-                const prepared = await this.#prepareAttachment(identity.workspaceId, pending.definition, pending.connection);
+                const prepared = await this.#prepareAttachment(identity.workspaceId, pending, pending.connection);
                 if (prepared.kind !== "active")
                     throw new Error("OAuth completion returned another authorization challenge.");
                 pending.prepared = prepared;
@@ -656,9 +659,11 @@ class Module {
         clearTimeout(this.#refreshTimers.get(key));
         this.#refreshTimers.delete(key);
     }
-    async close() {
-        if (this.#closed)
-            return;
+    stop() {
+        this.#stopping ??= this.#stop();
+        return this.#stopping;
+    }
+    async #stop() {
         this.#closed = true;
         for (const timer of this.#refreshTimers.values())
             clearTimeout(timer);
@@ -674,6 +679,4 @@ class Module {
         await closing;
     }
 }
-_a = Module;
-export default Module;
 //# sourceMappingURL=Module.js.map