@zackbart/connecta 0.24.3 → 0.25.0

package/dist/connectors/remote-mcp.js

@@ -1,8 +1,12 @@
 import { Client, ProtocolError, SdkHttpError, isInputRequiredResult, specTypeSchemas, StreamableHTTPClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
+import { Deferred, Duration, Effect, Exit, Scope } from "effect";
 import { KvOAuthProvider, OAuthRefreshCoordinator, } from "../auth/downstream-oauth.js";
 import { MAX_CATALOG_TOOLS } from "../catalog-limits.js";
 import { boundedEchoText, ConnectorCallError, msg, unavailableCallError, } from "../errors.js";
 import { CONNECTA_VERSION } from "../version.js";
+import { learnedUrlRefusal } from "../url-safety.js";
+import { inheritOAuthSealer, oauthSealerFor } from "../oauth-sealing.js";
+import { detach, runEdge } from "../runtime/run.js";
 /**
  * Apply a maintained provider's slot copy and header framing to credential
  * auth the deployment left bare.
@@ -33,6 +37,13 @@ export function withCredentialDefaults(auth, defaults) {
  * response, while callers continue to wait at most 100 ms.
  */
 const TERMINATE_SESSION_BUDGET_MS = 1_000;
+/**
+ * How long the local close gets after the DELETE: the second of the two
+ * seconds the core's deferred scope-close tail allows (see
+ * `src/runtime/connector-scope.ts`). The SDK's own transports close at once;
+ * this bounds one that never does.
+ */
+const LOCAL_CLOSE_BUDGET_MS = 1_000;
 /**
  * Absolute backstop on `tools/list` pages in one refresh — a runaway guard, not
  * the primary defense.
@@ -104,58 +115,65 @@ function isCursorShapeError(err) {
  * (405 is a legal answer), errors, or never replies all fall through to the
  * close with the session left to age out as it did before.
  */
-async function terminateSession(transport, logger, connectorId) {
-    // See documentation/connectors.md#mcp-version-skew for the legacy DELETE
-    // that Client.close() does not send.
+function terminateSession(transport, logger, connectorId) {
+    // SDK v2's Client.close() does not send the legacy session DELETE on our
+    // behalf. Connecta's own endpoint creates no protocol session, but a stateful
+    // legacy downstream can still issue `Mcp-Session-Id`, and every path that
+    // abandons one — scope teardown, credential rotation, OAuth retirement, an
+    // abandoned connect — owes it this best-effort, one-second DELETE.
     const terminate = transport.terminateSession;
     if (typeof terminate !== "function")
-        return;
-    // The SDK issues no request at all when no `mcp-session-id` was captured, so
-    // a stateless downstream never sees a spurious DELETE.
-    const done = Promise.resolve().then(() => terminate.call(transport));
-    await new Promise((resolve) => {
-        let finished = false;
-        const warn = (message, error) => {
-            try {
-                if (error === undefined)
-                    logger.warn(message);
-                else
-                    logger.warn(message, error);
-            }
-            catch {
-                // A diagnostic sink cannot make best-effort teardown observable to the
-                // caller in the one way this contract forbids: by replacing its result.
-            }
-        };
-        const timer = setTimeout(() => {
-            if (finished)
-                return;
-            finished = true;
-            warn(`[connecta] connector "${connectorId}" session termination was not ` +
-                `acknowledged within ${TERMINATE_SESSION_BUDGET_MS} ms; the ` +
-                "downstream may still finish the headers-only DELETE, otherwise " +
-                "the session will remain until its provider timeout.");
-            resolve();
-        }, TERMINATE_SESSION_BUDGET_MS);
-        done.then(() => {
-            if (finished)
-                return;
-            finished = true;
-            clearTimeout(timer);
-            resolve();
-        }, (error) => {
-            // The rejection handler stays attached after the timer wins, so an
-            // abort or other late failure is consumed without a duplicate warning.
-            if (finished)
-                return;
-            finished = true;
-            clearTimeout(timer);
-            warn(`[connecta] connector "${connectorId}" session termination was ` +
-                "refused or failed; the downstream session may remain until its " +
-                "provider timeout.", error);
-            resolve();
-        });
+        return Effect.void;
+    const warn = (message, error) => Effect.sync(() => {
+        try {
+            if (error === undefined)
+                logger.warn(message);
+            else
+                logger.warn(message, error);
+        }
+        catch {
+            // A diagnostic sink cannot make best-effort teardown observable to the
+            // caller in the one way this contract forbids: by replacing its result.
+        }
     });
+    // Whichever finishes first wins and the other is interrupted: an answer
+    // clears the timer, and a failure that lands after the timeout is consumed
+    // by the interrupted wait rather than warned about a second time.
+    return Effect.raceAllFirst([
+        // The SDK issues no request at all when no `mcp-session-id` was captured,
+        // so a stateless downstream never sees a spurious DELETE.
+        promised(() => Promise.resolve(terminate.call(transport))).pipe(Effect.catch((error) => warn(`[connecta] connector "${connectorId}" session termination was ` +
+            "refused or failed; the downstream session may remain until its " +
+            "provider timeout.", error))),
+        Effect.sleep(Duration.millis(TERMINATE_SESSION_BUDGET_MS)).pipe(Effect.andThen(warn(`[connecta] connector "${connectorId}" session termination was not ` +
+            `acknowledged within ${TERMINATE_SESSION_BUDGET_MS} ms; the ` +
+            "downstream may still finish the headers-only DELETE, otherwise " +
+            "the session will remain until its provider timeout."))),
+    ]);
+}
+/**
+ * The local half of a close: the SDK client's close once a client owns the
+ * transport, the bare transport's until then. Never fails, and stops waiting
+ * after LOCAL_CLOSE_BUDGET_MS — a transport whose close never settles would
+ * otherwise hold every caller that awaits the scope close, the credential Test
+ * action among them.
+ */
+function closeLocally(client, transport) {
+    if (!client && !transport)
+        return Effect.void;
+    return Effect.raceAllFirst([
+        promised(() => Promise.resolve(client ? client.close() : transport?.close())).pipe(Effect.ignore),
+        Effect.sleep(Duration.millis(LOCAL_CLOSE_BUDGET_MS)),
+    ]);
+}
+/**
+ * One Promise step of an Effect program. It fails with exactly what the
+ * promise rejected with, never a wrapper, because callers check the SDK's and
+ * connecta's own error classes. `evaluate` takes no signal, so the step
+ * allocates no AbortController.
+ */
+function promised(evaluate) {
+    return Effect.tryPromise({ try: evaluate, catch: (error) => error });
 }
 /** Classify protocol/status facts; provider prose never decides retryability. */
 function downstreamCallError(error) {
@@ -277,7 +295,8 @@ function redirectedInit(init, status) {
  * Wrap fetch with explicit, bounded redirect handling.
  *
  * The starting URL of each fetch call is trusted by its caller (the configured
- * MCP endpoint, or an OAuth URL discovered by the pinned SDK). Only Location
+ * MCP endpoint, or an OAuth URL the pinned SDK discovered and
+ * `learnedUrlSafeFetch` already admitted). Only Location
  * values are policy-controlled here. No rejected target is ever fetched, so
  * arbitrary static header names receive the same protection as Authorization.
  */
@@ -339,6 +358,32 @@ export function redirectSafeFetch(connectorId, policy = "none", baseFetch = fetc
         }
     };
 }
+class RemoteMcpDestinationError extends ConnectorCallError {
+    constructor(connectorId, reason) {
+        super("connector_call_failed", `Connector "${connectorId}" refused an OAuth URL the downstream advertised: ${reason}.`);
+        this.name = "RemoteMcpDestinationError";
+    }
+}
+/**
+ * Refuse, before any request leaves, a URL the downstream taught the OAuth
+ * flow that points somewhere connecta must not go (see `url-safety.ts`).
+ *
+ * The SDK learns authorization-server, token, and registration URLs from the
+ * downstream's own metadata and fetches them through the transport's fetch,
+ * so this sits on that fetch: above `redirectSafeFetch`, whose same-origin
+ * rule keeps every hop on the host checked here, and below the refresh
+ * coordinator, which already treats a non-retryable `ConnectorCallError` as
+ * connecta's own refusal rather than a token-endpoint verdict.
+ */
+function learnedUrlSafeFetch(connectorId, configured, baseFetch) {
+    return async (input, init) => {
+        const reason = learnedUrlRefusal(configured, new URL(input));
+        if (reason !== undefined) {
+            throw new RemoteMcpDestinationError(connectorId, reason);
+        }
+        return await baseFetch(input, init);
+    };
+}
 /**
  * Proxy a downstream remote MCP server. SDK clients and transports are scoped
  * to one inbound request: reused by calls within a batch/execute_code run, but
@@ -356,12 +401,11 @@ export function remoteMcp(id, opts) {
             "can own a different grant.");
     }
     // Weak keys ensure a completed request does not leave its SDK client,
-    // transport, response bodies, AbortSignals, or connection promise reachable
+    // transport, response bodies, AbortSignals, or connect attempt reachable
     // from the isolate singleton. Those are request-bound in Cloudflare Workers.
+    // A closed scope keeps its (emptied) entry, so a late or future lookup finds
+    // it closed rather than recreating an ownerless connection under it.
     const states = new WeakMap();
-    // Closing is terminal even after `states.delete`: a late or future lookup
-    // must not recreate an ownerless connection under the ended scope.
-    const closedScopes = new WeakSet();
     const isOauth = opts.auth?.type === "oauth";
     // Long-lived enough for distinct request scopes in this connector runtime to
     // join one token redemption. It owns no client, transport, or request state.
@@ -401,8 +445,8 @@ export function remoteMcp(id, opts) {
             throw new Error(`[connecta] connector "${id}" url ${opts.url} is not https:// (and not loopback) — refusing to connect (requireHttps).`);
         }
         // Both static shapes send a secret on every request; that an operator
-        // typed one into /credentials rather than a deployment file changes who
-        // owns it, not whether the wire carries it in the clear.
+        // typed one into the operator UI rather than a deployment file changes
+        // who owns it, not whether the wire carries it in the clear.
         if (opts.auth?.type === "headers" || credentialAuth) {
             logger.warn(`[connecta] connector "${id}" sends static credentials to ${opts.url} over a non-https:// connection — those tokens will be transmitted in cleartext.`);
         }
@@ -420,7 +464,7 @@ export function remoteMcp(id, opts) {
      * key to read it with). Deliberately the same `auth_required` code an absent
      * OAuth grant produces: the agent's next move is `authorize_connector`
      * either way, and that tool reads `connector.credential` to hand the
-     * operator `/credentials` instead of a consent URL.
+     * operator the connection in the UI when available instead of a consent URL.
      */
     class CredentialRequiredError extends ConnectorCallError {
         constructor(message) {
@@ -435,8 +479,7 @@ export function remoteMcp(id, opts) {
     const readCredential = async (ctx) => {
         if (!ctx.credential) {
             throw new CredentialRequiredError(`Connector "${id}" needs an operator-managed credential, but ` +
-                "credential storage is not configured. Set " +
-                "credentials.encryptionKey and redeploy.");
+                "credential storage is not configured. Configure vault in deployment code and redeploy. Call authorize_connector for recovery options.");
         }
         // A stored-shape mismatch already arrives as a typed auth_required from
         // the registry's accessor; nothing to reclassify here.
@@ -453,8 +496,9 @@ export function remoteMcp(id, opts) {
         // to the agent. So the check lives here, and says only what is wrong.
         if (carriesIllegalHeaderChar(value)) {
             throw new CredentialRequiredError(`Connector "${id}"'s stored credential contains a character a header ` +
-                "cannot carry (a line break or other control character) — re-enter " +
-                "it on /credentials. The value is not shown or logged.");
+                "cannot carry (a line break or other control character). Call " +
+                "authorize_connector for recovery options. When available, re-enter " +
+                "it in this connection in the operator UI. The value is not shown or logged.");
         }
         return value;
     };
@@ -479,8 +523,9 @@ export function remoteMcp(id, opts) {
             seen.add(current);
             if (quoted.some((secret) => current instanceof Error && current.message.includes(secret))) {
                 return new CredentialRequiredError(`Connector "${id}" could not send its stored credential as a ` +
-                    "header — re-enter it on /credentials. The value is not shown or " +
-                    "logged.");
+                    "header. Call authorize_connector for recovery options. When available, " +
+                    "re-enter it in this connection in the operator UI. " +
+                    "The value is not shown or logged.");
             }
             current = current.cause;
         }
@@ -511,13 +556,14 @@ export function remoteMcp(id, opts) {
             throw new Error(`Connector "${id}" returned a tools/list page whose nextCursor is neither a string, null, nor absent — this catalog cannot be walked.`, { cause: err });
         }
     };
-    const stateFor = (ctx) => {
-        const scope = ctx.requestScope ?? ctx;
-        if (closedScopes.has(scope))
-            throw scopeEndedError();
-        let state = states.get(scope);
+    /** This request scope's entry, open or closed, created on first sight. */
+    const entryFor = (ctx) => {
+        const key = ctx.requestScope ?? ctx;
+        let state = states.get(key);
         if (!state) {
             state = {
+                scope: Scope.makeUnsafe(),
+                lease: null,
                 client: null,
                 transport: null,
                 toolDefinitions: new Map(),
@@ -526,16 +572,22 @@ export function remoteMcp(id, opts) {
                 provider: null,
                 connectedGeneration: null,
                 credentialDigest: null,
-                closed: false,
             };
-            states.set(scope, state);
+            states.set(key, state);
         }
         return state;
     };
+    const isClosed = (state) => state.scope.state._tag === "Closed";
+    const stateFor = (ctx) => {
+        const state = entryFor(ctx);
+        if (isClosed(state))
+            throw scopeEndedError();
+        return state;
+    };
     const newProvider = (ctx, state) => {
         if (state?.provider)
             return state.provider;
-        const provider = new KvOAuthProvider(id, ctx.storage, `${ctx.baseUrl}/oauth/callback/${id}`, refreshCoordinator, ctx.allowAuthorization === true);
+        const provider = new KvOAuthProvider(id, ctx.storage, `${ctx.baseUrl}/oauth/callback/${id}`, refreshCoordinator, ctx.allowAuthorization === true, oauthSealerFor(ctx));
         if (state)
             state.provider = provider;
         return provider;
@@ -555,7 +607,7 @@ export function remoteMcp(id, opts) {
             const oauthProvider = provider ?? newProvider(ctx);
             return new StreamableHTTPClientTransport(url, {
                 authProvider: oauthProvider,
-                fetch: refreshCoordinator.coordinatedFetch(oauthProvider, guardedFetch, ctx.signal),
+                fetch: refreshCoordinator.coordinatedFetch(oauthProvider, learnedUrlSafeFetch(id, url, guardedFetch), ctx.signal),
             });
         }
         const headers = opts.auth?.type === "headers"
@@ -569,6 +621,7 @@ export function remoteMcp(id, opts) {
         });
     };
     const reset = (state) => {
+        state.lease = null;
         state.client = null;
         state.transport = null;
         state.toolDefinitions.clear();
@@ -577,40 +630,35 @@ export function remoteMcp(id, opts) {
         state.provider = null;
         state.connectedGeneration = null;
         state.credentialDigest = null;
-        // `closed` is deliberately not cleared — see ConnectionState.
+        // `scope` is deliberately left as it is — see ConnectionState.
     };
     // The context has no deferred-work hook. Detached exits start this bounded
     // best-effort tail immediately; closeScope awaits its own tail so the core
-    // can pass it to the runtime's deferred channel.
+    // can pass it to the runtime's deferred channel. Terminating and closing are
+    // each bounded, so no close waits more than two seconds in all.
     const closingSessions = new WeakMap();
-    const closeConnection = (client, transport, logger) => {
+    const closeConnection = (client, transport, logger) => Effect.suspend(() => {
         const previous = transport && closingSessions.get(transport);
         if (previous)
-            return previous;
-        const closing = (async () => {
-            try {
-                if (transport)
-                    await terminateSession(transport, logger, id);
-                if (client)
-                    await client.close();
-                else
-                    await transport?.close();
-            }
-            catch {
-                // Local close cannot replace the operation's result.
-            }
-        })();
+            return Deferred.await(previous);
+        const closed = Deferred.makeUnsafe();
         // A connect can acquire a session after an early close. Deduplicate only
         // once that session exists, so its late abandonment still sends DELETE.
         if (transport?.sessionId)
-            closingSessions.set(transport, closing);
-        return closing;
-    };
-    const closeHalf = (state, ctx) => {
-        const client = state.client;
-        const transport = state.transport;
+            closingSessions.set(transport, closed);
+        return (transport ? terminateSession(transport, logger, id) : Effect.void).pipe(Effect.andThen(closeLocally(client, transport)), Effect.ensuring(Deferred.done(closed, Exit.void)));
+    });
+    /**
+     * Forget the live connection and close its lease without waiting. A connect
+     * still in flight is unpublished with it, and sees at its next check that it
+     * has been abandoned.
+     */
+    const closeHalf = (state) => {
+        const lease = state.lease;
         reset(state);
-        void closeConnection(client, transport, ctx.logger);
+        const release = lease && Scope.closeUnsafe(lease, Exit.void);
+        if (release)
+            detach(release);
     };
     const ensureConnected = async (ctx, state) => {
         // A 401 after connect is a verdict for the whole request scope, not merely
@@ -628,9 +676,7 @@ export function remoteMcp(id, opts) {
             const provider = newProvider(ctx, state);
             oauthGeneration = await provider.generation();
             if (provider.isOperatorDisconnectedGeneration(oauthGeneration)) {
-                const connecting = state.connecting;
-                void connecting?.catch(() => { });
-                closeHalf(state, ctx);
+                closeHalf(state);
                 throw operatorDisconnectedError();
             }
         }
@@ -638,16 +684,16 @@ export function remoteMcp(id, opts) {
         // wiped credentials. This request's cached client still speaks the old
         // token — drop it so the next connect runs against current state.
         if (state.client && oauthGeneration !== undefined && state.connectedGeneration !== null) {
-            if (state.closed)
+            if (isClosed(state))
                 throw scopeEndedError();
             if (oauthGeneration !== state.connectedGeneration) {
-                closeHalf(state, ctx);
+                closeHalf(state);
             }
         }
         // The static-credential counterpart of the epoch read above, and
         // deliberately beside it: the vault is read before any cached client is
-        // trusted, so an operator's rotation on /credentials takes effect on the
-        // next call rather than the next deploy. Compared by digest — the
+        // trusted, so an operator's rotation in the UI takes effect on the next
+        // call rather than the next deploy. Compared by digest — the
         // plaintext lives in this function's scope and never reaches `state`.
         let credentialValue = null;
         let credentialFramed = null;
@@ -663,134 +709,167 @@ export function remoteMcp(id, opts) {
             if ((state.client || state.connecting) &&
                 state.credentialDigest !== null &&
                 state.credentialDigest !== credentialDigest) {
-                if (state.closed)
+                if (isClosed(state))
                     throw scopeEndedError();
-                const connecting = state.connecting;
-                void connecting?.catch(() => { });
-                closeHalf(state, ctx);
+                closeHalf(state);
             }
         }
-        if (state.closed)
+        if (isClosed(state))
             throw scopeEndedError();
         if (state.client)
-            return;
-        if (!state.connecting) {
-            let attempt;
-            attempt = (async () => {
-                const ownsAttempt = () => state.connecting === attempt && !state.closed;
-                const abandon = (client, transport) => {
-                    void closeConnection(client, transport, ctx.logger);
-                    throw scopeEndedError();
-                };
-                // Let the assignment immediately below this async IIFE publish
-                // `state.connecting = attempt` before ownership is checked. OAuth's
-                // generation read naturally yields; unauthenticated transports do not.
-                await Promise.resolve();
-                // A provider belongs to exactly one connect attempt. A force reset can
-                // abandon that attempt while its transport still holds the provider;
-                // the replacement must never mutate the abandoned provider's epoch.
-                const provider = isOauth ? newProvider(ctx) : null;
-                const genAtStart = provider ? await provider.generation() : "";
-                if (!ownsAttempt())
-                    throw scopeEndedError();
-                if (provider?.isOperatorDisconnectedGeneration(genAtStart)) {
-                    throw operatorDisconnectedError();
-                }
-                provider?.captureGeneration(genAtStart);
-                // SDK v2 selects its validator by runtime export condition: AJV on
-                // Node and @cfworker/json-schema under workerd. The Workers-safe path
-                // no longer needs Connecta-specific wiring.
-                const c = new Client({ name: "connecta", version: CONNECTA_VERSION }, {
-                    versionNegotiation: {
-                        mode: opts.versionNegotiation ?? "auto",
-                    },
-                    // Connecta has no interactive relay. Surface the result manually
-                    // below as one structured, non-retryable connector failure.
-                    inputRequired: { autoFulfill: false },
-                });
-                const t = buildTransport(ctx, provider, credentialFramed);
-                if (!ownsAttempt())
-                    abandon(null, t);
-                state.transport = t;
-                try {
-                    await c.connect(t);
-                    // A probe deadline can end its scope while connect is still in flight.
-                    // The transport is closed immediately by closeScope; if connect wins
-                    // that race anyway, close the resulting client rather than
-                    // resurrecting a session in the detached state object.
-                    if (!ownsAttempt())
-                        abandon(c, t);
-                    // A force re-auth that landed WHILE we were connecting wiped the
-                    // credentials this client just bound to. Discard it rather than
-                    // cache a stale-isolate connection.
-                    if (provider) {
-                        const generation = await provider.generation();
-                        // closeScope can land while the generation read is pending, after
-                        // connect succeeded but before this client is cached. Discard the
-                        // client on that side of the await too.
-                        if (!ownsAttempt())
-                            abandon(c, t);
-                        if (generation !== genAtStart) {
-                            void closeConnection(c, t, ctx.logger);
-                            throw new UnauthorizedError("Connector was re-authorized during connect; reconnect required.");
-                        }
+            return state.client;
+        const attempt = state.connecting ??
+            startConnect(ctx, state, credentialValue, credentialFramed, credentialDigest);
+        // A Promise edge of its own, as architecture.md's "Effect inside" requires
+        // of every shared wait: whatever this caller does next with the client is
+        // its own I/O, so it resumes in its own continuation rather than inside the
+        // call that completed the attempt.
+        const client = await runEdge(Deferred.await(attempt));
+        // Teardown can land between the attempt completing and this caller
+        // resuming. The client it would hand back is being closed, and this scope
+        // is over.
+        if (isClosed(state))
+            throw scopeEndedError();
+        return client;
+    };
+    /**
+     * Start this scope's connect attempt, publishing it before any of it runs.
+     * The attempt completes its Deferred itself, and every caller — the one that
+     * started it included — waits on that; nothing awaits the run directly,
+     * which is why handing it to `detach` orphans nothing.
+     */
+    const startConnect = (ctx, state, credentialValue, credentialFramed, credentialDigest) => {
+        const attempt = Deferred.makeUnsafe();
+        state.connecting = attempt;
+        // Published with the attempt, not with its result: a rotation that lands
+        // while this connect is in flight has to be visible to the next caller,
+        // which would otherwise wait on a client bound to the older key.
+        state.credentialDigest = credentialDigest;
+        detach(connect(ctx, state, attempt, credentialValue, credentialFramed).pipe(Effect.onExit((exit) => Effect.sync(() => {
+            // Force reset may have abandoned this attempt and installed a new
+            // one in the same request scope. An old completion must not erase
+            // the new attempt and allow a third concurrent connect.
+            if (state.connecting === attempt)
+                state.connecting = null;
+            // Last: a Deferred resumes its waiters inside this call.
+            Deferred.doneUnsafe(attempt, exit);
+        }))));
+        return attempt;
+    };
+    const connect = (ctx, state, attempt, credentialValue, credentialFramed) => {
+        // Force reset, rotation, and teardown all abandon an attempt the same way:
+        // they unpublish it and close the lease it holds, if it holds one yet.
+        const owned = () => state.connecting === attempt && !isClosed(state);
+        return Effect.gen(function* () {
+            // A provider belongs to exactly one connect attempt. A force reset can
+            // abandon that attempt while its transport still holds the provider;
+            // the replacement must never mutate the abandoned provider's epoch.
+            const provider = isOauth ? newProvider(ctx) : null;
+            const genAtStart = provider ? yield* promised(() => provider.generation()) : "";
+            if (!owned())
+                return yield* Effect.fail(scopeEndedError());
+            if (provider?.isOperatorDisconnectedGeneration(genAtStart)) {
+                return yield* Effect.fail(operatorDisconnectedError());
+            }
+            provider?.captureGeneration(genAtStart);
+            // SDK v2 selects its validator by runtime export condition: AJV on
+            // Node and @cfworker/json-schema under workerd. The Workers-safe path
+            // no longer needs Connecta-specific wiring.
+            const c = new Client({ name: "connecta", version: CONNECTA_VERSION }, {
+                versionNegotiation: {
+                    mode: opts.versionNegotiation ?? "auto",
+                },
+                // Connecta has no interactive relay. Surface the result manually
+                // below as one structured, non-retryable connector failure.
+                inputRequired: { autoFulfill: false },
+            });
+            const t = buildTransport(ctx, provider, credentialFramed);
+            if (!owned()) {
+                detach(closeConnection(null, t, ctx.logger));
+                return yield* Effect.fail(scopeEndedError());
+            }
+            // From here the connection has a lease on the scope, and closing it —
+            // force reset, rotation, teardown — closes this transport: through the
+            // client once one is cached, the bare transport until then, which is
+            // what aborts a connect still in flight.
+            const lease = Scope.forkUnsafe(state.scope);
+            const held = { client: null };
+            yield* Scope.addFinalizer(lease, Effect.suspend(() => closeConnection(held.client, t, ctx.logger)));
+            state.lease = lease;
+            state.transport = t;
+            return yield* Effect.gen(function* () {
+                yield* promised(() => c.connect(t));
+                // A probe deadline can end its scope while connect is still in flight.
+                // The transport is closed immediately by closeScope; if connect wins
+                // that race anyway, close the resulting client rather than resurrecting
+                // a session in the detached state object.
+                if (!owned())
+                    return yield* Effect.fail(scopeEndedError());
+                // A force re-auth that landed WHILE we were connecting wiped the
+                // credentials this client just bound to. Discard it rather than cache
+                // a stale-isolate connection.
+                if (provider) {
+                    const generation = yield* promised(() => provider.generation());
+                    // closeScope can land while the generation read is pending, after
+                    // connect succeeded but before this client is cached. Discard the
+                    // client on that side of the await too.
+                    if (!owned())
+                        return yield* Effect.fail(scopeEndedError());
+                    if (generation !== genAtStart) {
+                        return yield* Effect.fail(new UnauthorizedError("Connector was re-authorized during connect; reconnect required."));
                     }
-                    if (!ownsAttempt())
-                        abandon(c, t);
-                    state.client = c;
-                    state.connectedGeneration = genAtStart;
-                    state.authRequired = false;
                 }
-                catch (err) {
-                    void closeConnection(c, t, ctx.logger);
-                    if (ownsAttempt())
-                        state.transport = null;
-                    // Only a real 401/UnauthorizedError means auth is the problem — a
-                    // network error on an oauth connector must surface as "error", not
-                    // "auth_required".
-                    if (err instanceof UnauthorizedError && ownsAttempt()) {
+                held.client = c;
+                state.client = c;
+                state.connectedGeneration = genAtStart;
+                state.authRequired = false;
+                return c;
+            }).pipe(Effect.catch((err) => {
+                // Close the failed connection through its client, without waiting.
+                held.client = c;
+                if (owned()) {
+                    state.lease = null;
+                    state.transport = null;
+                    // Only a real 401/UnauthorizedError means auth is the problem —
+                    // a network error on an oauth connector must surface as "error",
+                    // not "auth_required".
+                    if (err instanceof UnauthorizedError)
                         state.authRequired = true;
-                    }
-                    if (err instanceof UnauthorizedError) {
-                        throw authRequiredError(err);
-                    }
-                    // Defense in depth for the one error class that can quote the
-                    // credential: a runtime refusing the assembled header. `readCredential`
-                    // already rejects a value that cannot ride one, so reaching this is a
-                    // gap in that check rather than a routine outcome.
-                    throw withoutCredential(err, credentialValue, credentialFramed);
+                    const release = Scope.closeUnsafe(lease, Exit.void);
+                    if (release)
+                        detach(release);
                 }
-                finally {
-                    // Force reset may have abandoned this attempt and installed a new one
-                    // in the same request scope. An old completion must not erase the new
-                    // promise and allow a third concurrent connect.
-                    if (state.connecting === attempt)
-                        state.connecting = null;
+                else {
+                    // Whoever abandoned this attempt closed the lease already, while
+                    // the connect was in flight. A session it acquired after that
+                    // close still owes its DELETE.
+                    detach(closeConnection(c, t, ctx.logger));
                 }
-            })();
-            state.connecting = attempt;
-            // Published with the attempt, not with its result: a rotation that lands
-            // while this connect is in flight has to be visible to the next caller,
-            // which would otherwise wait on a client bound to the older key.
-            state.credentialDigest = credentialDigest;
-        }
-        return state.connecting;
+                if (err instanceof UnauthorizedError) {
+                    return Effect.fail(authRequiredError(err));
+                }
+                // Defense in depth for the one error class that can quote the
+                // credential: a runtime refusing the assembled header.
+                // `readCredential` already rejects a value that cannot ride one, so
+                // reaching this is a gap in that check rather than a routine
+                // outcome.
+                return Effect.fail(withoutCredential(err, credentialValue, credentialFramed));
+            }));
+        });
     };
     const disconnectAuthorization = async (ctx, state, operatorDisconnected = false) => {
         const provider = newProvider(ctx, state);
         // Publish the replacement epoch before waiting on or closing any
         // request-local transport. A hung connect therefore cannot delay the
         // fence, and every late OAuth write stays in the older namespace.
-        const connecting = state.connecting;
         try {
             await provider.resetAuthorization(operatorDisconnected);
         }
         finally {
-            // Consume the abandoned connect and close whichever half of the
+            // Abandon any connect in flight and close whichever half of the
             // client/transport exists. Reset is unconditional because KV may already
             // be fenced behind a newer epoch after a cleanup error.
-            void connecting?.catch(() => { });
-            closeHalf(state, ctx);
+            closeHalf(state);
         }
     };
     const connector = {
@@ -809,8 +888,8 @@ export function remoteMcp(id, opts) {
             : {}),
         ...(opts.usageGuide !== undefined ? { usageGuide: opts.usageGuide } : {}),
         // Declaring the slot is what makes the rest of the operator surface work:
-        // /credentials renders it, the shape check compares against it, and
-        // authorize_connector reads it to return the operator handoff rather than
+        // the connection's credential form renders it, the shape check compares
+        // against it, and authorize_connector returns the operator handoff rather than
         // an OAuth URL this connector has none of.
         ...(credentialAuth
             ? {
@@ -867,18 +946,16 @@ export function remoteMcp(id, opts) {
         // the accumulator is returned rather than stored: a cursor is opaque and
         // session-bound, so nothing here may outlive this call.
         async listTools(ctx) {
-            // The complete-catalog rule is documented at
-            // documentation/connectors.md#catalog-contract.
+            // The catalog contract: a downstream catalog is complete or it is a
+            // failure. Follow every page to the end of the cursor chain, preserve
+            // schemas and annotations, and never cache or serve a partial walk.
             const state = stateFor(ctx);
-            await ensureConnected(ctx, state);
-            // Bind the client once so the whole walk provably rides one session — a
-            // cursor is only meaningful to the connection that issued it, and a
-            // re-read could in principle pick up a different one. It is NOT guarding
-            // against closeScope nulling state.client mid-loop: closeScope sets
-            // `closed` and nulls `client` in one synchronous run, and the loop
-            // re-checks `closed` before every page, so the nulled client is
-            // unreachable from here.
-            const client = state.client;
+            // The client this call connected or joined, bound once so the whole walk
+            // provably rides one session — a cursor is only meaningful to the
+            // connection that issued it. Never re-read from `state`: a force reset
+            // or rotation can null it before this call resumes, and teardown is
+            // caught instead by the `closed` check before every page.
+            const client = await ensureConnected(ctx, state);
             // Raw SDK tools, not ToolDefs: the metadata re-prime below needs fields
             // (task support) that a ToolDef deliberately does not carry.
             const listed = [];
@@ -892,7 +969,7 @@ export function remoteMcp(id, opts) {
                 for (let page = 0; page < MAX_TOOL_PAGES; page++) {
                     // The scope can end between pages (probe timeout, teardown). Stop
                     // rather than keep paging into a transport that is being closed.
-                    if (state.closed)
+                    if (isClosed(state))
                         throw scopeEndedError();
                     // A discovery deadline uses the same signal for the whole chain.
                     // Check it before issuing each page as well as passing it to the
@@ -989,8 +1066,7 @@ export function remoteMcp(id, opts) {
         },
         async callTool(name, args, ctx) {
             const state = stateFor(ctx);
-            await ensureConnected(ctx, state);
-            const client = state.client;
+            const client = await ensureConnected(ctx, state);
             try {
                 const toolDefinition = state.toolDefinitions.get(name);
                 if (toolDefinition?.execution?.taskSupport === "required") {
@@ -1022,20 +1098,17 @@ export function remoteMcp(id, opts) {
             }
         },
         async closeScope(ctx) {
-            const scope = ctx.requestScope ?? ctx;
-            // Tombstone before any lookup or await. This also makes close-before-use
-            // terminal rather than allowing the scope to spring into existence later.
-            closedScopes.add(scope);
-            const state = states.get(scope);
-            if (!state)
-                return;
-            // Delete before awaiting: a duplicate teardown is a no-op.
-            states.delete(scope);
-            state.closed = true;
-            const client = state.client;
-            const transport = state.transport;
+            // A scope closed before its first use gets an entry too, closed at once,
+            // so it cannot spring into existence later.
+            const state = entryFor(ctx);
+            // Closed before any await, and before the finalizers run: every check
+            // from here on sees the scope ended. A duplicate teardown finds it
+            // closed and has nothing to run.
+            const release = Scope.closeUnsafe(state.scope, Exit.void);
             reset(state);
-            await closeConnection(client, transport, ctx.logger);
+            // Runs the live connection's lease finalizer, if there is one.
+            if (release)
+                await runEdge(release);
         },
         async status(ctx) {
             const state = stateFor(ctx);
@@ -1052,8 +1125,8 @@ export function remoteMcp(id, opts) {
                 }
                 if (state.authRequired) {
                     // Only an OAuth connector has a pending consent URL to offer. A
-                    // credential connector's downstream 401 is repaired on /credentials,
-                    // so do not reach into OAuth storage to look for one.
+                    // credential connector's downstream 401 is repaired in the operator
+                    // UI connection, so do not reach into OAuth storage to look for one.
                     return {
                         state: "auth_required",
                         message: credentialAuth
@@ -1073,7 +1146,10 @@ export function remoteMcp(id, opts) {
             // verifyState ran on this request-scoped provider first and captured the
             // pending flow's generation. If force reset races the exchange, any late
             // token write remains tagged with that older generation and is unreadable.
-            const t = (state.transport ??
+            // A transport an attempt built belongs to that attempt's lease; one built
+            // here for the exchange alone belongs to this call, which closes it.
+            const leased = state.transport;
+            const t = (leased ??
                 buildTransport(ctx, provider));
             if (callbackParams !== undefined) {
                 await t.finishAuth(callbackParams);
@@ -1083,9 +1159,9 @@ export function remoteMcp(id, opts) {
             }
             await provider.clearPending();
             // Reset so the next use reconnects with the freshly stored tokens.
-            if (!state.transport)
-                state.transport = t;
-            closeHalf(state, ctx);
+            closeHalf(state);
+            if (!leased)
+                detach(closeConnection(null, t, ctx.logger));
         },
     };
     if (opts.auth?.type === "oauth") {
@@ -1097,7 +1173,11 @@ export function remoteMcp(id, opts) {
             await disconnectAuthorization(ctx, stateFor(ctx), true);
         };
         connector.startAuth = async (ctx, startOpts) => {
-            ctx = { ...ctx, requestScope: ctx.requestScope ?? ctx, allowAuthorization: true };
+            ctx = inheritOAuthSealer(ctx, {
+                ...ctx,
+                requestScope: ctx.requestScope ?? ctx,
+                allowAuthorization: true,
+            });
             const state = stateFor(ctx);
             state.provider = null;
             const p = newProvider(ctx, state);