@zackbart/connecta 0.40.0 → 0.42.0

package/dist/config.js

@@ -82,7 +82,8 @@ const calls = {
     /**
      * Deadline (ms) for `call_tool`/`call_destructive_tool` calls that pass no
      * `timeoutMs`. An explicit per-call value wins. Unset by default, when those
-     * calls fall back to `execute.hostCallTimeoutMs`.
+     * calls fall back to `execute.hostCallTimeoutMs`. `execute.watchdogMs` caps
+     * every one of them.
      *
      * Each call makes one attempt. `connecta.call` inside `execute_code` uses
      * it too, ahead of `execute.hostCallTimeoutMs`; `connecta.result`,
@@ -118,16 +119,19 @@ const execute = {
      * `connecta.read`, in milliseconds. Default 15_000. Discovery uses
      * `discovery.probeTimeoutMs`. `connecta.call` and the direct call tools use it only when
      * `calls.defaultTimeoutMs` is unset, and an explicit per-call `timeoutMs`
-     * always wins. Raise it for providers whose legitimate calls run longer,
-     * such as analytics queries.
+     * wins, up to `execute.watchdogMs`. Raise it for providers whose legitimate
+     * calls run longer, such as analytics queries.
      */
     hostCallTimeoutMs: whole({ min: 1, default: D.execute.hostCallTimeoutMs }),
     /**
-     * Hard ceiling on one execution, in milliseconds, enforced outside the
-     * sandbox. Default 120_000, above both executors' own deadlines (QuickJS
-     * 30_000, the Dynamic Worker 60_000), so it only ends a run whose executor
-     * never settled; that run fails as unresponsive and its admission slot is
-     * released. Keep it above any raised executor deadline.
+     * Ceiling on one `execute_code` or direct call response, in milliseconds,
+     * counted from the request's arrival and enforced outside the sandbox.
+     * Default 55_000: MCP clients commonly abandon a request at 60_000, and only
+     * a response sent before that reaches the agent as a typed result. It sits
+     * above both executors' own deadlines (QuickJS 30_000, the Dynamic Worker
+     * 50_000), so a run ends here only if its executor never settled, or if
+     * queueing spent its time. An explicit `timeoutMs` above it is cut to it. Raise it,
+     * and any executor deadline with it, only for clients whose own limit is raised.
      */
     watchdogMs: whole({ min: 1, default: D.execute.watchdogMs }),
     /**
@@ -143,6 +147,15 @@ const execute = {
      * model step. From 4_000 to 1_000_000.
      */
     maxResultChars: whole({ min: 4_000, max: 1_000_000, default: D.execute.maxResultChars }),
+    /**
+     * `false` stops listing `execute_read_code` on writable human endpoints. A
+     * read program runs unprompted on hosts that auto-approve reads, so a deployment
+     * that wants a person to see every program can turn it off. Default true.
+     */
+    readRoute: opaque({
+        check: assertFlag,
+        resolve: (value) => value ?? D.execute.readRoute,
+    }),
 };
 function admissionPool(defaults) {
     return {
@@ -189,7 +202,7 @@ function assertFlag(value, path) {
     if (typeof value !== "boolean")
         throw new ConfigError(`${path} must be true or false.`);
 }
-/** Longest pool `description`, in characters, after trimming. */
+/** Longest pool `description`, in UTF-16 code units, after trimming. */
 const MAX_POOL_DESCRIPTION_LENGTH = 500;
 /**
  * A pool description is one line of prose for the model. C0 and C1 controls
@@ -209,9 +222,9 @@ function assertPoolDescription(value, path) {
     const trimmed = typeof value === "string" ? value.trim() : undefined;
     if (trimmed === undefined ||
         trimmed.length === 0 ||
-        [...trimmed].length > MAX_POOL_DESCRIPTION_LENGTH ||
+        trimmed.length > MAX_POOL_DESCRIPTION_LENGTH ||
         hasLineBreakOrControlCharacter(trimmed)) {
-        throw new ConfigError(`${path} must be text of 1 to ${MAX_POOL_DESCRIPTION_LENGTH} characters after trimming, with no line breaks or control characters.`);
+        throw new ConfigError(`${path} must be text of 1 to ${MAX_POOL_DESCRIPTION_LENGTH} UTF-16 code units after trimming, with no line breaks or control characters.`);
     }
 }
 /** Shape only; each reference resolves against auth and agents in createConnecta. */
@@ -263,7 +276,7 @@ const pool = {
      * What this pool is for, in plain words for the model: appended to the MCP
      * `initialize` instructions at `/mcp/<name>` and `/agent/<name>`, so a
      * caller learns its scope ("Team tier: shared tools only."). Trimmed, 1 to
-     * 500 characters, no line breaks or control characters. It grants and hides nothing; plain
+     * 500 UTF-16 code units, no line breaks or control characters. It grants and hides nothing; plain
      * `/mcp` never shows it.
      */
     description: opaque({ check: assertPoolDescription }),
@@ -359,11 +372,14 @@ const connectaConfig = {
     /** Named tool pools, each served at `/mcp/<name>` to its members only. */
     pools: record(object(pool)),
     /** Exact connector id -> tool name -> verdict. Hidden tools cannot be discovered or called.
+     * `"read"` applies only where the source is silent, and asserts the call is safe to repeat; a
+     * source's declared write stays a write and is reported. `"read-repeatable"` also serves a
+     * declared write as a read: the deployment has checked it and accepts that hosts may repeat it.
      * Unknown static names fail construction; absent runtime names stay dormant and are reported. */
     classification: record(record(opaque({
         check: (value, path) => {
-            if (value !== "read" && value !== "write" && value !== "hidden") {
-                throw new ConfigError(`${path} must be "read", "write", or "hidden".`);
+            if (value !== "read" && value !== "read-repeatable" && value !== "write" && value !== "hidden") {
+                throw new ConfigError(`${path} must be "read", "read-repeatable", "write", or "hidden".`);
             }
         },
     }))),
@@ -396,8 +412,9 @@ const connectaConfig = {
         resolve: (value) => value ?? memoryStorage(),
     }),
     /**
-     * Public base URL. Defaults to the request origin per-request. Configuring an
-     * HTTPS URL also redirects matching inbound HTTP requests to HTTPS.
+     * Public base URL. Defaults to the request origin per-request, except that
+     * clerkAuth requires it here or as its own `publicUrl`. Configuring an HTTPS
+     * URL also redirects matching inbound HTTP requests to HTTPS.
      */
     publicUrl: opaque({ check: httpUrl }),
     /**
@@ -419,7 +436,10 @@ const connectaConfig = {
             }
         },
     }),
-    /** Replaceable owner-partitioned credential storage. Omit for config-owned secrets. */
+    /**
+     * Replaceable owner-partitioned credential storage. Omit for config-owned
+     * secrets. With any OAuth connector it must implement `seal` and `open`.
+     */
     vault: opaque({
         check: (value) => {
             if (!hasMethods(value, ["get", "getAll", "set", "setAll", "metadata", "delete"]) ||
@@ -464,6 +484,14 @@ const connectaConfig = {
      * saturation.
      */
     admission: object(admission),
+    /** Payload-free request timing logs; 0 disables tracing, 1 samples every MCP request. */
+    timingTraceSampleRate: opaque({
+        check: (value, path) => {
+            if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1)
+                throw new ConfigError(`${path} must be a finite number between 0 and 1.`);
+        },
+        resolve: (value) => value ?? 0,
+    }),
     /** Diagnostic output. Use "silent" to disable all diagnostic logging. */
     logger: opaque({
         check: (value, path) => {
@@ -528,10 +556,21 @@ function assertCoherent(config) {
         config.discovery.catalogMaxTtlSeconds > 86_400) {
         throw new ConfigError("ConnectaConfig.discovery requires catalogMinTtlSeconds <= catalogMaxTtlSeconds <= 86400.");
     }
+    const { vault } = config;
+    const oauth = config.connectors.find((connector) => connector.startAuth);
+    if (oauth && vault && (typeof vault.seal !== "function" || typeof vault.open !== "function")) {
+        throw new ConfigError(`ConnectaConfig.vault must implement both seal and open: connector "${oauth.id}" stores downstream OAuth ` +
+            "tokens, client registration and PKCE verifiers through it. Use encryptedCredentialVault(storage, key) " +
+            "from @zackbart/connecta/credentials, or add both methods.");
+    }
     if (config.agents.some((agent) => !agent.vercel) && !config.accessTokens) {
         throw new ConfigError("ConnectaConfig.agents needs accessTokens: accessTokens(storage) from @zackbart/connecta/auth/access-tokens " +
             "holds each agent's token slot.");
     }
+    if (!config.publicUrl && config.auth.some((provider) => provider.requiresPublicUrl)) {
+        throw new ConfigError("ConnectaConfig.publicUrl is required with clerkAuth, which checks tokens and sessions against it: " +
+            "set it, or clerkAuth({ publicUrl }), to this deployment's URL, http://localhost:<port> for local development.");
+    }
 }
 /**
  * Validate a configuration and apply every default. Unknown keys are refused

package/dist/connectors/remote-mcp/call.js

@@ -55,7 +55,7 @@ export function remoteMcpCall(rt) {
                     }
                     : state.toolDefinitions.get(name);
                 if (toolDefinition?.execution?.taskSupport === "required") {
-                    throw new ConnectorCallError("connector_call_failed", `Tool "${name}" requires task-based execution, which Connecta does not support.`);
+                    throw new ConnectorCallError("unsupported_capability", `Tool "${name}" requires task-based execution, which Connecta does not support.`);
                 }
                 let output;
                 const outputError = (code, message) => rt.atMcpBoundary(ctx, new ProtocolError(code, message), "tools/call", client.transport, [ctx.signal]);

package/dist/connectors/remote-mcp/catalog.js

@@ -5,7 +5,7 @@ import { SdkHttpError, specTypeSchemas, UnauthorizedError } from "@modelcontextp
 import { redactCatalog } from "../../sent-secrets.js";
 import { MAX_CATALOG_TOOLS, MAX_SERIALIZED_CATALOG_BYTES } from "../../catalog-limits.js";
 import { catalogItems, observeCompletedCatalogRefresh, observeCatalogFetch, observeCatalogExpiry, } from "../../catalog-cache.js";
-import { ConnectorCallError, msg } from "../../errors.js";
+import { ConnectorCallError, isAccessRefusal, msg } from "../../errors.js";
 import { carryFailureFacts, failureRecord, logFailure } from "../../operator-record.js";
 import { assertDownstreamOutputSafe } from "../../downstream-input-context.js";
 import { hasSdkPayload, ownAbortReason, requiresAuthorization } from "./errors.js";
@@ -78,6 +78,10 @@ export function remoteMcpCatalog(rt) {
             listingContext(options),
             authMethod(() => authFlow(function* () {
                 const before = toolPages;
+                // The one write that follows no cache read, which is what
+                // otherwise captures the fence this listing may lift.
+                if (options?.cacheMode === "refresh")
+                    (yield authInvoke(cache, "captureFence", []));
                 let result;
                 try {
                     result = (yield authCall(listTools, [params, options]));
@@ -86,6 +90,9 @@ export function remoteMcpCatalog(rt) {
                     const bounded = rt.atMcpBoundary(cache.currentContext(), error, "tools/list", client.transport, [
                         cache.currentContext().signal,
                     ]);
+                    // Fenced as this listing was bound, whatever is current by now.
+                    if (requiresAuthorization(bounded) || isAccessRefusal(bounded))
+                        (yield authInvoke(cache, "fenceListing", []));
                     const transient = (error instanceof SdkHttpError && [502, 503, 504].includes(error.status)) ||
                         (bounded instanceof ConnectorCallError && bounded.code === "unavailable");
                     const fallback = transient && toolPages === before
@@ -247,32 +254,49 @@ export function remoteMcpCatalog(rt) {
             }
         }
         state.toolDefinitions = new Map(clean.map((tool) => [tool.name, tool]));
-        return clean.map((t) => ({
-            name: t.name,
-            ...(t.title !== undefined ? { title: t.title } : {}),
-            ...(t.icons !== undefined
-                ? {
-                    icons: t.icons.filter((icon) => !/^data:/i.test(icon.src)),
-                }
-                : {}),
-            ...(t.execution !== undefined ? { execution: t.execution } : {}),
-            ...(t.description !== undefined ? { description: t.description } : {}),
-            ...(t.inputSchema !== undefined
-                ? {
-                    inputSchema: t.inputSchema,
-                }
-                : {}),
-            ...(t.outputSchema !== undefined
-                ? {
-                    outputSchema: t.outputSchema,
-                }
-                : {}),
-            ...(t.annotations !== undefined
-                ? {
-                    annotations: t.annotations,
-                }
-                : {}),
-        }));
+        return toolDefinitions(clean);
+    }));
+    // Served by discovery only, marked by the caller; the listing above stays
+    // the only source a call resolves through.
+    const peekCatalogOperation = authMethod((ctx) => authFlow(function* () {
+        if (liveListings.has(ctx))
+            return undefined;
+        const entry = (yield authCall(rt.peekCatalog, [ctx]));
+        if (!entry)
+            return undefined;
+        return {
+            tools: toolDefinitions(redactCatalog(ctx, entry.result.tools)),
+            fetchedAt: entry.fetchedAt,
+            expiresAt: entry.expiresAt,
+        };
+    }));
+    return { installCatalogIntake, listingContexts, liveListings, listToolsOperation, peekCatalogOperation };
+}
+function toolDefinitions(tools) {
+    return tools.map((t) => ({
+        name: t.name,
+        ...(t.title !== undefined ? { title: t.title } : {}),
+        ...(t.icons !== undefined
+            ? {
+                icons: t.icons.filter((icon) => !/^data:/i.test(icon.src)),
+            }
+            : {}),
+        ...(t.execution !== undefined ? { execution: t.execution } : {}),
+        ...(t.description !== undefined ? { description: t.description } : {}),
+        ...(t.inputSchema !== undefined
+            ? {
+                inputSchema: t.inputSchema,
+            }
+            : {}),
+        ...(t.outputSchema !== undefined
+            ? {
+                outputSchema: t.outputSchema,
+            }
+            : {}),
+        ...(t.annotations !== undefined
+            ? {
+                annotations: t.annotations,
+            }
+            : {}),
     }));
-    return { installCatalogIntake, listingContexts, liveListings, listToolsOperation };
 }

package/dist/connectors/remote-mcp/connection.js

@@ -3,8 +3,8 @@
 // served without connecting (INV-10).
 import { routePhrases } from "../../agent-routes.js";
 import { authView } from "../../auth/native-call.js";
-import { authFlow, authCall, authInvoke, authMethod, authStorageMany } from "../../auth/native.js";
-import { openRequest, viewServices, viewSignal, viewReads, serviceFor } from "../../runtime/call.js";
+import { authFlow, authCall, authInvoke, authMethod } from "../../auth/native.js";
+import { openRequest, viewServices, viewSignal } from "../../runtime/call.js";
 import { secretDigest } from "../../storage-digest.js";
 import { downstreamClientMetadata, downstreamRedirectUri, remoteClientAuthMethod, selfHostedClientUrl, } from "../../auth/downstream-client-metadata.js";
 import { Client, SdkErrorCode, SdkHttpError, UnauthorizedError } from "@modelcontextprotocol/client";
@@ -12,8 +12,8 @@ import { Deferred, Effect, Exit, Scope } from "effect";
 import { KvOAuthProvider, refreshCoordinatorsByPartition } from "../../auth/downstream-oauth.js";
 import { trackOAuthStartReset } from "../../auth/oauth-start-reset.js";
 import { sentSecretsFor } from "../../sent-secrets.js";
-import { catalogClientOptions, observeCatalogChange } from "../../catalog-cache.js";
-import { ConnectorCallError, resendAdvice } from "../../errors.js";
+import { catalogClientOptions, observeCatalogChange, observeCatalogExpiry, observeCatalogFetch, prefetchCatalog, retainedCatalogIdentity, } from "../../catalog-cache.js";
+import { ConnectorCallError, isAccessRefusal, resendAdvice } from "../../errors.js";
 import { carryFailureFacts, failureRecord, logFailure } from "../../operator-record.js";
 import { CONNECTA_VERSION } from "../../version.js";
 import { oauthSealerFor } from "../../oauth-sealing.js";
@@ -23,13 +23,42 @@ import { downstreamInputCapabilities } from "../../downstream-input-context.js";
 import { detach, runEdge } from "../../runtime/run.js";
 import { requestPrincipalFor } from "../../request-principal.js";
 import { callerOf } from "../../connector-caller.js";
-import { CatalogPolicy } from "../../catalog-policy.js";
-import { negotiationKeys, responseCacheKeys } from "../../storage/keys.js";
+import { negotiationKeys } from "../../storage/keys.js";
 import { forgetNegotiation, readNegotiation, storeNegotiation } from "../negotiation-cache.js";
 import { carriesIllegalHeaderChar, credentialHeaderValue } from "./config.js";
 import { AUTH_OR_THROTTLE, promised, recordWireErrors, requiresAuthorization } from "./errors.js";
 import { MAX_TOOL_PAGES } from "./catalog.js";
 import { SKILLS_EXTENSION } from "./resources.js";
+/** Retain every abandoned lease release until the final scope close joins it. */
+export function retainCleanup(state, release) {
+    const pending = detach(release);
+    state.cleanup.add(pending);
+    if (state.closing)
+        state.closing = Promise.all([state.closing, pending]).then(() => { });
+    // Register at the release itself as well: a late connect can acquire a
+    // session after the owner's first close has already settled.
+    try {
+        state.defer?.(pending);
+    }
+    catch {
+        // Runtime hooks are best-effort; the bounded cleanup is already running.
+    }
+    void pending.then(() => state.cleanup.delete(pending));
+    return pending;
+}
+/** Scope.closeUnsafe returns nothing on a second close, even during release. */
+export function closeConnectionScope(state) {
+    if (!state.closing) {
+        const release = Scope.closeUnsafe(state.scope, Exit.void);
+        if (release)
+            retainCleanup(state, release);
+        state.closing = (async () => {
+            while (state.cleanup.size)
+                await Promise.all(state.cleanup);
+        })();
+    }
+    return state.closing;
+}
 /** One connector's connection states, credential reads and connect attempts. */
 export function remoteMcpConnection(rt) {
     const { requestAuth, forwarding, id, staticClient, clientMetadataUrl, opts, oauthScope, authorizationParams, destination, isOauth, extraHeaders, credentialHeader, credentialScheme, skillsEnabled, principalPolicy, credentialAuth, } = rt;
@@ -105,6 +134,9 @@ export function remoteMcpConnection(rt) {
         if (!state) {
             state = {
                 scope: Scope.makeUnsafe(),
+                closing: null,
+                cleanup: new Set(),
+                defer: ctx.defer,
                 lease: null,
                 client: null,
                 transport: null,
@@ -120,10 +152,8 @@ export function remoteMcpConnection(rt) {
             states.set(key, state);
             const owned = state;
             owner.own(() => {
-                const closing = Scope.closeUnsafe(owned.scope, Exit.void);
+                void closeConnectionScope(owned);
                 reset(owned);
-                if (closing)
-                    detach(closing);
             });
         }
         return state;
@@ -191,7 +221,7 @@ export function remoteMcpConnection(rt) {
         reset(state);
         const release = lease && Scope.closeUnsafe(lease, Exit.void);
         if (release)
-            detach(release);
+            retainCleanup(state, release);
     };
     const waitForConnection = (attempt, signal) => runEdge(Deferred.await(attempt), signal ? { signal } : {});
     const oauthConfigFor = (ctx) => isOauth
@@ -258,7 +288,7 @@ export function remoteMcpConnection(rt) {
      * same cache through the SDK, so it skips this read. What was already read
      * is handed to that connect, so a resolver runs once per listing.
      */
-    const cachedCatalog = authMethod((ctx) => authFlow(function* () {
+    const readCatalog = authMethod((ctx, use) => authFlow(function* () {
         const principal = principalPolicy
             ? requestPrincipalFor(principalPolicy, ctx, (reason) => new rt.CredentialRequiredError(`Connector "${id}" ${reason}.`))
             : undefined;
@@ -274,6 +304,7 @@ export function remoteMcpConnection(rt) {
         try {
             let epoch = "";
             let identity;
+            let pinnedIdentity;
             if (isOauth) {
                 // Read-only grant snapshots: no in-place sealing, epoch binding or
                 // refresh. Every identity check during cache acceptance re-reads the
@@ -284,6 +315,7 @@ export function remoteMcpConnection(rt) {
                 epoch = snapshot.epoch;
                 if (provider.isOperatorDisconnectedEpoch(epoch) || !snapshot.tokens)
                     return preread;
+                pinnedIdentity = yield authCall(secretDigest, [ctx, JSON.stringify(snapshot.tokens)]);
                 const bound = epoch;
                 identity = authMethod(() => authFlow(function* () {
                     const current = (yield authInvoke(provider, "peekGrant", []));
@@ -297,16 +329,18 @@ export function remoteMcpConnection(rt) {
                 const digest = (yield authCall(negotiationKey, [ctx, credentialDigest, epoch]));
                 // Both reads only locate cached data. Acceptance and dispatch keep
                 // their fresh generation and credential checks.
-                yield viewReads(ctx).prefetch([
-                    { storage: ctx.storage, key: negotiationKeys.verdict(digest) },
-                    {
-                        storage: serviceFor(ctx, CatalogPolicy)?.storage ?? ctx.storage,
-                        key: responseCacheKeys.generation(id),
-                    },
-                ], (storage, keys) => authStorageMany(storage, keys));
+                yield authCall(prefetchCatalog, [
+                    ctx,
+                    id,
+                    (yield authCall(catalogConfigFor, [ctx])),
+                    JSON.stringify([epoch, credentialDigest]),
+                    catalogSharing,
+                    pinnedIdentity,
+                    negotiationKeys.verdict(digest),
+                ]);
                 const prior = (yield authCall(readNegotiation, [ctx, digest]));
                 preread.negotiation = { digest, prior };
-                if (prior?.kind === "modern")
+                if (prior?.kind === "modern" && use === "list")
                     return preread;
             }
             const cache = (yield authCall(catalogClientOptions, [
@@ -320,6 +354,10 @@ export function remoteMcpConnection(rt) {
                 identity,
                 true,
             ]));
+            if (use === "peek") {
+                const entry = (yield authInvoke(cache, "peekTools", [ctx]));
+                return entry ? { ...preread, peek: entry } : preread;
+            }
             const result = (yield authInvoke(cache, "cachedTools", [ctx]));
             if (result)
                 return { tools: result.tools };
@@ -331,6 +369,34 @@ export function remoteMcpConnection(rt) {
         }
         return preread;
     }));
+    // A peek is the first half of the listing that may follow it: that listing
+    // takes what the peek read, once, so a discovery that peeks first still reads
+    // its stored entry and runs a credential resolver once. Nothing is taken if
+    // the catalog was invalidated or the credential changed in between, and the
+    // whole hand-off lives and dies with the request scope.
+    const peeks = new WeakMap();
+    const peekCatalog = authMethod((ctx) => authFlow(function* () {
+        // A connector known to need authorization is never listed from a cache.
+        if (stateFor(ctx).authRequired)
+            return undefined;
+        const read = (yield authCall(readCatalog, [ctx, "peek"]));
+        peeks.set(ctx.requestScope ?? ctx, { identity: retainedCatalogIdentity(ctx), read });
+        return read.peek;
+    }));
+    const cachedCatalog = authMethod((ctx) => authFlow(function* () {
+        const scope = ctx.requestScope ?? ctx;
+        const handed = peeks.get(scope);
+        peeks.delete(scope);
+        if (!handed || handed.identity !== retainedCatalogIdentity(ctx))
+            return (yield authCall(readCatalog, [ctx, "list"]));
+        const { peek, ...preread } = handed.read;
+        if (!peek || peek.expiresAt <= Date.now())
+            return preread;
+        // The listing's own view keeps the provenance a direct read would record.
+        observeCatalogFetch(ctx, peek.fetchedAt);
+        observeCatalogExpiry(ctx, "tools/list", typeof peek.result.ttlMs === "number" ? peek.result.ttlMs : peek.expiresAt - peek.fetchedAt, peek.expiresAt);
+        return { tools: peek.result.tools };
+    }));
     const ensureConnected = authMethod((ctx, state, preread) => authFlow(function* () {
         let joined = state.connecting;
         if (joined)
@@ -520,6 +586,25 @@ export function remoteMcpConnection(rt) {
                 ])));
                 if (!owned())
                     return yield* Effect.fail(rt.scopeEndedError());
+                // The generation a refused handshake is about, as it is now. Read from
+                // this connect's memo, so a connect that is not refused costs no I/O.
+                const handshakeBinding = yield* promised(authMethod(() => authInvoke(cacheOptions, "bindListing", [ctx, { credentialIdentity: undefined }]))).pipe(Effect.catch(() => Effect.succeed(undefined)));
+                if (!owned())
+                    return yield* Effect.fail(rt.scopeEndedError());
+                // What the attempt sent, in memory: never the grant as it is by now. A
+                // provider that read no tokens in this epoch sent none and has no catalog.
+                const fenceHandshake = authMethod(() => authFlow(function* () {
+                    let credentialIdentity;
+                    if (provider) {
+                        if (!provider.observedTokens || provider.observed?.epoch !== genAtStart)
+                            return;
+                        credentialIdentity = yield authCall(secretDigest, [ctx, JSON.stringify(provider.observedTokens)]);
+                    }
+                    (yield authInvoke(cacheOptions, "fenceTools", [
+                        ctx,
+                        { ...handshakeBinding, credentialIdentity },
+                    ]));
+                }));
                 const makeClient = () => {
                     const { intake: _intake, completeCatalogRefresh: _refresh, withListing: _listing, currentContext: _context, cachedTools: _cached, ...clientOptions } = cacheOptions;
                     const client = new Client({ name: "connecta", version: CONNECTA_VERSION }, {
@@ -587,7 +672,12 @@ export function remoteMcpConnection(rt) {
                     }
                 }))).pipe(Effect.mapError((err) => rt.atMcpBoundary(ctx, 
                 // First, while the runtime's text can still be read for it.
-                rt.withoutCredential(ctx, err, credentialValue, credentialFramed), "MCP handshake", t, [ctx.signal, connectionAbort.signal, handshakeAbort.signal])));
+                rt.withoutCredential(ctx, err, credentialValue, credentialFramed), "MCP handshake", t, [ctx.signal, connectionAbort.signal, handshakeAbort.signal])), 
+                // Before the lease closes the signal this write runs under. Waiters see
+                // the failure after it, and it never replaces the refusal.
+                Effect.tapError((error) => handshakeBinding && (requiresAuthorization(error) || isAccessRefusal(error))
+                    ? promised(fenceHandshake).pipe(Effect.catch(() => Effect.void))
+                    : Effect.void));
                 held.client = c;
                 // A probe deadline can end its scope while connect is still in flight.
                 // The transport is closed immediately by closeScope; if connect wins
@@ -644,13 +734,13 @@ export function remoteMcpConnection(rt) {
                         state.authRequired = true;
                     const release = Scope.closeUnsafe(lease, Exit.void);
                     if (release)
-                        detach(release);
+                        retainCleanup(state, release);
                 }
                 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(rt.closeConnection(held.client, held.transport, ctx.logger));
+                    retainCleanup(state, rt.closeConnection(held.client, held.transport, ctx.logger));
                 }
                 if (err instanceof UnauthorizedError) {
                     return Effect.fail(carryFailureFacts(err, rt.authRequiredError(ctx)));
@@ -675,6 +765,7 @@ export function remoteMcpConnection(rt) {
         ensureConnected,
         requestOptions,
         cachedCatalog,
+        peekCatalog,
         cacheOwner,
         reset,
         states,

package/dist/connectors/remote-mcp/oauth.js

@@ -1,5 +1,6 @@
 // The downstream OAuth surface: bounded SDK flows, early renewal before a
 // call, unchallenged consent starts, and the connector's auth operations.
+import { retainCleanup } from "./connection.js";
 import { authView } from "../../auth/native-call.js";
 import { authFlow, authCall, authInvoke, authMethod } from "../../auth/native.js";
 import { viewSignal } from "../../runtime/call.js";
@@ -10,7 +11,6 @@ import { byteReadResponse } from "../../byte-read-response.js";
 import { requestSentSecrets, sentSecretsFor } from "../../sent-secrets.js";
 import { ConnectorCallError, resendAdvice, WithheldTextError } from "../../errors.js";
 import { attachFailureFacts, carryFailureFacts, OAUTH_ERROR_CODES } from "../../operator-record.js";
-import { detach } from "../../runtime/run.js";
 import { retryAfterMs } from "../../http-policy.js";
 import { sendCredentialPost } from "../../guarded-transport.js";
 import { UnboundOAuthFlowsError, downstreamCallError, errorKind, hasSdkPayload, ownAbortReason, requiresAuthorization, startMessage, withheldAs, } from "./errors.js";
@@ -376,7 +376,7 @@ export function remoteMcpOAuth(rt) {
                 ]));
             }
             finally {
-                detach(rt.closeConnection(null, t, ctx.logger));
+                retainCleanup(state, rt.closeConnection(null, t, ctx.logger));
             }
         })), true));
         connector.verifyState = authMethod((oauthState, ctx) => authFlow(function* () {

package/dist/connectors/remote-mcp/resources.js

@@ -345,8 +345,11 @@ export function remoteMcpResources(rt) {
             if (client.getProtocolEra() !== "modern" ||
                 !skillObject(capabilities?.resources) ||
                 !skillObject(extension) ||
+                // The released Beta specification defines no revision setting.
+                // Never enable a future breaking revision under the same ID.
+                extension.revision !== undefined ||
                 (extension.directoryRead !== undefined && typeof extension.directoryRead !== "boolean")) {
-                throw new ConnectorCallError("connector_call_failed", "The downstream did not declare a valid Skills extension and resources capability.");
+                throw new ConnectorCallError("unsupported_capability", "The downstream did not declare a valid Skills extension and resources capability.");
             }
             const result = (yield authCall(run, [client, state]));
             skillScopeOpen(ctx, state);
@@ -415,7 +418,7 @@ export function remoteMcpResources(rt) {
             rt.listingContexts.set(options, ctx);
             try {
                 if (!client.getServerCapabilities()?.resources)
-                    throw unadvertisedResource();
+                    throw new ConnectorCallError("unsupported_capability", "The downstream did not declare resources support.");
                 const resources = (yield authInvoke(client, "listResources", [undefined, options]));
                 const templates = (yield authInvoke(client, "listResourceTemplates", [
                     undefined,

package/dist/connectors/remote-mcp/transport.js

@@ -18,7 +18,7 @@ import { learnedUrlRefusal } from "../../url-safety.js";
 import { RequestScope } from "../../runtime/request-scope.js";
 import { Context } from "effect";
 import { downstreamWriteContinuation } from "../../downstream-input-context.js";
-import { guardedTransport, sendGuarded, sendCredentialPost } from "../../guarded-transport.js";
+import { learnedDestination, guardedTransport, sendGuarded, sendCredentialPost, } from "../../guarded-transport.js";
 import { dispatchProviderRequest, recordProviderResponse, knownProviderFailure, providerRequest, renewedAfterUnauthorized, } from "../../provider-call.js";
 import { recordRequestField } from "../../provider-call-facts.js";
 import { AUTH_OR_THROTTLE, errorBodyText, jsonRpcErrorBody, keepsModernVerdict, promised } from "./errors.js";
@@ -128,11 +128,25 @@ labelErrorClass(RemoteMcpDestinationError, "RemoteMcpDestinationError");
  */
 export function learnedUrlSafeFetch(connectorId, configured, baseFetch) {
     return authMethod((input, init) => authFlow(function* () {
-        const reason = learnedUrlRefusal(configured, new URL(input));
-        if (reason !== undefined) {
-            throw new RemoteMcpDestinationError(connectorId, reason);
+        let target = new URL(input);
+        for (let hop = 0; hop < 10; hop++) {
+            const reason = learnedUrlRefusal(configured, target);
+            if (reason !== undefined)
+                throw new RemoteMcpDestinationError(connectorId, reason);
+            const marked = { ...init, redirect: "manual", [learnedDestination]: configured };
+            const response = (yield authCall(baseFetch, [target, marked]));
+            if (!REDIRECT_STATUSES.has(response.status) ||
+                !response.headers.has("location") ||
+                (init?.method ?? "GET").toUpperCase() !== "GET")
+                return byteReadResponse(response);
+            const location = response.headers.get("location");
+            void response.body?.cancel().catch(() => { });
+            const redirected = new URL(location, target);
+            if (redirected.origin !== target.origin)
+                throw new RemoteMcpDestinationError(connectorId, "cross-origin redirect refused");
+            target = redirected;
         }
-        return byteReadResponse((yield authCall(baseFetch, [input, init])));
+        throw new RemoteMcpDestinationError(connectorId, "redirect limit exceeded");
     }));
 }
 /**
@@ -289,7 +303,11 @@ export function remoteMcpTransport(rt) {
             if (customFetch && new URL(input instanceof Request ? input.url : String(input)).origin !== destination.origin)
                 throw new ConnectorCallError("connector_call_failed", `Connector "${id}" refused a request outside its origin; nothing was sent.`, { retryable: false });
             // The deployment's fetch owns the wire: each write is handed over once.
-            const sender = flight?.write ? (customSender ?? guardedTransport(true)) : undefined;
+            const sender = flight?.write
+                ? (customSender ?? guardedTransport(true))
+                : init?.[learnedDestination]
+                    ? guardedTransport(false)
+                    : undefined;
             if (flight?.write) {
                 if (flight.sent) {
                     if (flight.request && flight.authorization)