@zackbart/connecta 0.28.0 → 0.29.0

package/dist/connectors/remote-mcp.js

@@ -1,15 +1,30 @@
-import { Client, ProtocolError, SdkHttpError, isInputRequiredResult, specTypeSchemas, StreamableHTTPClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
+import { assertRemoteOAuthClient, declareSelfHostedClient, downstreamClientMetadata, downstreamRedirectUri, remoteClientAuthMethod, selfHostedClientUrl, trackRemoteClientRequest, } from "../auth/downstream-client-metadata.js";
+import { AuthorizationServerMismatchError, Client, InsecureTokenEndpointError, InsufficientScopeError, IssuerMismatchError, MissingRequiredClientCapabilityError, OAuthClientFlowError, OAuthError, ProtocolError, RegistrationRejectedError, ResourceNotFoundError, SdkError, SdkErrorCode, SdkHttpError, SseError, UnsupportedProtocolVersionError, UrlElicitationRequiredError, isInputRequiredResult, fromJsonSchema, isJSONRPCErrorResponse, isJSONRPCNotification, specTypeSchemas, StreamableHTTPClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
 import { Deferred, Duration, Effect, Exit, Scope } from "effect";
-import { KvOAuthProvider, OAuthRefreshCoordinator, } from "../auth/downstream-oauth.js";
+import { assertOAuthScope, authorizingContext, KvOAuthProvider, OAuthRequestNotSentError, refreshCoordinatorsByPartition, } from "../auth/downstream-oauth.js";
 import { trackOAuthStartReset } from "../auth/oauth-start-reset.js";
-import { MAX_CATALOG_TOOLS } from "../catalog-limits.js";
+import { byteReadResponse } from "../byte-read-response.js";
+import { redactCatalog, redactSentSecrets, sentSecretsFor, shortSecretWarning, trackCredentialReads, } from "../sent-secrets.js";
+import { MAX_CATALOG_TOOLS, MAX_SERIALIZED_CATALOG_BYTES } from "../catalog-limits.js";
+import { catalogClientOptions, catalogItems, observeCompletedCatalogRefresh, closeCatalogCacheScope, observeCatalogChange, observeCatalogFetch, observeCatalogExpiry, } from "../catalog-cache.js";
+import { reviewedClassification } from "../catalog-drift.js";
 import { connectorScopeCleanupClaimed } from "../connector-scope.js";
-import { boundedEchoText, ConnectorCallError, msg, unavailableCallError, } from "../errors.js";
+import { boundedEchoText, ConnectorCallError, msg, networkErrorCode, unavailableCallError, WithheldTextError, } from "../errors.js";
+import { attachFailureFacts, carryFailureFacts, errorLabel, failureRecord, failureStatus, labelErrorClass, logFailure, OAUTH_ERROR_CODES, ownStatus, } from "../operator-record.js";
 import { CONNECTA_VERSION } from "../version.js";
 import { learnedUrlRefusal } from "../url-safety.js";
-import { inheritOAuthSealer, oauthSealerFor } from "../oauth-sealing.js";
-import { attachOAuthPartition, oauthPartitionFor, retainOAuthPartition } from "../oauth-partition.js";
+import { oauthSealerFor } from "../oauth-sealing.js";
+import { retainingOAuthPartition } from "../oauth-partition.js";
+import { registerInvocationAuth } from "../invocation-auth.js";
+import { downstreamInputCapabilities, assertDownstreamOutputSafe, downstreamWriteContinuation, } from "../downstream-input-context.js";
 import { detach, runEdge } from "../runtime/run.js";
+import { assertKnownOptions, keys, optionsOf } from "../config-schema.js";
+import { describedEndpoint, describedUrl } from "../described.js";
+import { retryAfterMs } from "./guarded-fetch.js";
+import { resourceUriMatchesTemplates } from "./resource-uri.js";
+import { callerOf } from "../connector-caller.js";
+import { readNegotiation, storeNegotiation } from "./negotiation-cache.js";
+import { CALL_ADMISSION, REMOTE_MCP_AUTH, USAGE_GUIDE } from "./option-shapes.js";
 /**
  * Apply a maintained provider's slot copy and header framing to credential
  * auth the deployment left bare.
@@ -25,11 +40,16 @@ export function withCredentialDefaults(auth, defaults) {
     return {
         ...auth,
         credential: auth.credential ?? defaults.credential,
-        ...(auth.scheme === undefined && defaults.scheme !== undefined
-            ? { scheme: defaults.scheme }
-            : {}),
+        ...(auth.scheme === undefined && defaults.scheme !== undefined ? { scheme: defaults.scheme } : {}),
     };
 }
+/** The closed options remoteMcp() accepts; see `assertKnownOptions`. */
+const REMOTE_MCP_OPTIONS = optionsOf()({
+    ...keys("url", "title", "description", "authScope", "maxResultBytes", "versionNegotiation", "redirects", "requireHttps", "logger", "_transportFactory", "classify", "skills"),
+    callAdmission: CALL_ADMISSION,
+    usageGuide: USAGE_GUIDE,
+    auth: REMOTE_MCP_AUTH,
+});
 /**
  * How long a downstream gets to answer the session-termination DELETE before
  * teardown stops waiting. This is a network round-trip budget, deliberately
@@ -47,18 +67,347 @@ const TERMINATE_SESSION_BUDGET_MS = 1_000;
  * 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.
- *
- * The walk terminates on its own well before this: a cursor handed back twice
- * is a definite loop, two consecutive pages that add no new tools are a server
- * going nowhere, and MAX_CATALOG_TOOLS caps what any of it can accumulate.
- * This exists only so the loop is finite even if a downstream somehow
- * satisfies all three forever on a path with no discovery deadline. Set high
- * enough that no honest server reaches it.
- */
+function unadvertisedResource() {
+    return new ConnectorCallError("not_found", "The resource URI is not advertised by this connector.", {
+        retryable: false,
+    });
+}
+/** SDK aggregation cap; intake also refuses loops and non-progress (INV-8). */
 const MAX_TOOL_PAGES = 10_000;
+const SKILLS_EXTENSION = "io.modelcontextprotocol/skills";
+const MAX_SKILLS = 10_000;
+const MAX_SKILL_FILES = 512;
+const MAX_SKILL_BYTES = 16 * 1024 * 1024;
+// A valid UTF-8 text file can expand sixfold when JSON escapes control bytes.
+// Leave room for the envelope while accepting every file up to the spec limit.
+const MAX_SKILL_READ_RPC_BYTES = 6 * MAX_SKILL_BYTES + 1024 * 1024;
+/** Count UTF-8 without allocating another full copy of a bounded response. */
+function skillTextBytes(value) {
+    let bytes = 0;
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code < 0x80)
+            bytes++;
+        else if (code < 0x800)
+            bytes += 2;
+        else if (code >= 0xd800 &&
+            code <= 0xdbff &&
+            i + 1 < value.length &&
+            value.charCodeAt(i + 1) >= 0xdc00 &&
+            value.charCodeAt(i + 1) <= 0xdfff) {
+            bytes += 4;
+            i++;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
+function skillObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function skillJsonBytes(value) {
+    return skillTextBytes(JSON.stringify(value));
+}
+function validSkill(value) {
+    if (!skillObject(value) ||
+        typeof value.uri !== "string" ||
+        !value.uri ||
+        !skillObject(value.frontmatter) ||
+        typeof value.frontmatter.name !== "string" ||
+        !value.frontmatter.name ||
+        typeof value.frontmatter.description !== "string" ||
+        !value.frontmatter.description)
+        return false;
+    if (value.resources === "dynamic")
+        return true;
+    if (!Array.isArray(value.resources) || !value.resources.length || value.resources.length > MAX_SKILL_FILES)
+        return false;
+    const uris = new Set();
+    let bytes = 0;
+    for (const resource of value.resources) {
+        if (!skillObject(resource) ||
+            typeof resource.uri !== "string" ||
+            !resource.uri ||
+            uris.has(resource.uri) ||
+            typeof resource.digest !== "string" ||
+            !/^sha256:[a-f0-9]{64}$/.test(resource.digest) ||
+            typeof resource.size !== "number" ||
+            !Number.isSafeInteger(resource.size) ||
+            resource.size < 0)
+            return false;
+        uris.add(resource.uri);
+        bytes += resource.size;
+        if (bytes > MAX_SKILL_BYTES)
+            return false;
+    }
+    return uris.has(value.uri);
+}
+function completeSkillResult(value) {
+    // The modern SDK codec rejects non-complete wire results and removes
+    // resultType before invoking an explicit result schema.
+    return (skillObject(value) &&
+        typeof value.ttlMs === "number" &&
+        Number.isSafeInteger(value.ttlMs) &&
+        value.ttlMs >= 0 &&
+        (value.cacheScope === "public" || value.cacheScope === "private"));
+}
+const SkillPageSchema = {
+    "~standard": {
+        version: 1,
+        vendor: "connecta",
+        validate(value) {
+            if (!completeSkillResult(value) ||
+                !Array.isArray(value.skills) ||
+                value.skills.length > MAX_SKILLS ||
+                !value.skills.every(validSkill) ||
+                (value.nextCursor !== undefined && typeof value.nextCursor !== "string")) {
+                return { issues: [{ message: "Invalid or incomplete Skills listing." }] };
+            }
+            const bytes = skillJsonBytes(value);
+            if (bytes > MAX_SERIALIZED_CATALOG_BYTES)
+                return { issues: [{ message: "Skills listing exceeds the byte limit." }] };
+            return {
+                value: {
+                    skills: value.skills,
+                    bytes,
+                    ...(typeof value.nextCursor === "string" ? { nextCursor: value.nextCursor } : {}),
+                },
+            };
+        },
+    },
+};
+function skillReadSchema(uri) {
+    return {
+        "~standard": {
+            version: 1,
+            vendor: "connecta",
+            validate(value) {
+                if (!completeSkillResult(value) ||
+                    !Array.isArray(value.contents) ||
+                    value.contents.length !== 1 ||
+                    skillJsonBytes(value) > MAX_SKILL_READ_RPC_BYTES) {
+                    return { issues: [{ message: "Invalid or incomplete skill resource response." }] };
+                }
+                const content = value.contents[0];
+                if (!skillObject(content) ||
+                    content.uri !== uri ||
+                    (content.mimeType !== undefined && typeof content.mimeType !== "string")) {
+                    return { issues: [{ message: "Unexpected skill resource contents." }] };
+                }
+                const mimeType = typeof content.mimeType === "string" ? { mimeType: content.mimeType } : {};
+                if (typeof content.text === "string" &&
+                    !("blob" in content) &&
+                    skillTextBytes(content.text) <= MAX_SKILL_BYTES) {
+                    return { value: [{ uri, ...mimeType, text: content.text }] };
+                }
+                if (typeof content.blob === "string" &&
+                    !("text" in content) &&
+                    content.blob.length % 4 === 0 &&
+                    !/[^A-Za-z0-9+/]/.test(content.blob.replace(/={1,2}$/, ""))) {
+                    const bytes = (content.blob.length / 4) * 3 - (content.blob.endsWith("==") ? 2 : content.blob.endsWith("=") ? 1 : 0);
+                    if (bytes <= MAX_SKILL_BYTES)
+                        return { value: [{ uri, ...mimeType, blob: content.blob }] };
+                }
+                return { issues: [{ message: "Invalid or oversized skill resource bytes." }] };
+            },
+        },
+    };
+}
+/** Bound the body before SDK consumption, including its detached SSE reader. */
+async function boundedSkillResponse(response, limit, rpcId, signal) {
+    const exceeded = () => new ConnectorCallError("connector_call_failed", "Downstream Skills response exceeds the RPC byte limit.");
+    const declared = response.headers.get("content-length");
+    if (declared !== null && Number(declared) > limit) {
+        await response.body?.cancel().catch(() => { });
+        throw exceeded();
+    }
+    if (!response.body)
+        return response;
+    const reader = response.body.getReader();
+    const abort = () => {
+        void reader.cancel().catch(() => { });
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+    let bytes = 0;
+    const chunks = [];
+    let buffer;
+    let buffered = 0;
+    const sse = response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() === "text/event-stream";
+    // Decode an entire SSE message once. Its byte buffer has no per-chunk or
+    // per-line objects, and preserves embedded resource BOMs on workerd too.
+    const decoder = new TextDecoder("utf-8", { ignoreBOM: true, fatal: false });
+    let data = new Uint8Array(0);
+    let dataBytes = 0;
+    let hasData = false;
+    const newline = new Uint8Array([10]);
+    const field = [100, 97, 116, 97, 58]; // data:
+    const bom = [239, 187, 191];
+    let bomOffset = 0;
+    let fieldOffset = 0;
+    // 0: field prefix, 1: optional value space, 2: data value, 3: ignored line.
+    let state = 0;
+    let lineBytes = false;
+    let skipLf = false;
+    const append = (value) => {
+        const needed = dataBytes + value.byteLength;
+        if (needed > limit)
+            throw exceeded();
+        if (needed > data.length) {
+            const next = new Uint8Array(Math.min(limit, Math.max(65_536, needed, data.length * 2)));
+            next.set(data.subarray(0, dataBytes));
+            data = next;
+        }
+        data.set(value, dataBytes);
+        dataBytes = needed;
+    };
+    const beginData = () => {
+        if (hasData)
+            append(newline);
+        hasData = true;
+    };
+    const consume = (chunk) => {
+        for (let offset = 0; offset < chunk.length;) {
+            const byte = chunk[offset];
+            if (skipLf) {
+                skipLf = false;
+                if (byte === 10) {
+                    offset++;
+                    continue;
+                }
+            }
+            // Strip exactly one initial UTF-8 BOM, even across single-byte chunks.
+            if (bomOffset >= 0) {
+                if (byte === bom[bomOffset]) {
+                    if (++bomOffset === bom.length)
+                        bomOffset = -1;
+                    offset++;
+                    continue;
+                }
+                if (bomOffset) {
+                    lineBytes = true;
+                    state = 3;
+                }
+                bomOffset = -1;
+            }
+            if (byte === 10 || byte === 13) {
+                if (lineBytes) {
+                    if (state === 0 && fieldOffset === 4)
+                        beginData();
+                }
+                else {
+                    const json = hasData && dataBytes ? decoder.decode(data.subarray(0, dataBytes)) : "";
+                    dataBytes = 0;
+                    hasData = false;
+                    if (json) {
+                        const message = JSON.parse(json);
+                        if (skillObject(message) && message.id === rpcId && ("result" in message || "error" in message)) {
+                            data = new Uint8Array(0);
+                            return json;
+                        }
+                    }
+                }
+                state = 0;
+                fieldOffset = 0;
+                lineBytes = false;
+                skipLf = byte === 13;
+                offset++;
+                continue;
+            }
+            lineBytes = true;
+            if (state === 0) {
+                if (byte === field[fieldOffset]) {
+                    if (++fieldOffset === field.length) {
+                        beginData();
+                        state = 1;
+                    }
+                }
+                else
+                    state = 3;
+                offset++;
+                continue;
+            }
+            if (state === 1) {
+                state = 2;
+                if (byte === 32) {
+                    offset++;
+                    continue;
+                }
+            }
+            let end = offset;
+            while (end < chunk.length && chunk[end] !== 13 && chunk[end] !== 10)
+                end++;
+            if (state === 2)
+                append(chunk.subarray(offset, end));
+            offset = end;
+        }
+    };
+    const terminalResponse = async (json) => {
+        // The SDK's detached SSE consumer does not settle body-read errors. Hand
+        // it the bounded terminal answer and close a server-kept-open stream.
+        await reader.cancel().catch(() => { });
+        const headers = new Headers(response.headers);
+        headers.set("content-type", "application/json");
+        headers.delete("content-length");
+        return new Response(json, { status: response.status, statusText: response.statusText, headers });
+    };
+    try {
+        while (true) {
+            if (signal?.aborted)
+                throw signal.reason;
+            const chunk = await reader.read();
+            if (signal?.aborted)
+                throw signal.reason;
+            if (chunk.done) {
+                break;
+            }
+            bytes += chunk.value.byteLength;
+            if (bytes > limit)
+                throw exceeded();
+            if (!sse) {
+                // Network chunk count and backing-buffer size are untrusted. Retain
+                // only owned fixed-size blocks, never one object per incoming byte.
+                for (let offset = 0; offset < chunk.value.byteLength;) {
+                    buffer ??= new Uint8Array(65_536);
+                    const size = Math.min(buffer.length - buffered, chunk.value.byteLength - offset);
+                    buffer.set(chunk.value.subarray(offset, offset + size), buffered);
+                    offset += size;
+                    buffered += size;
+                    if (buffered === buffer.length) {
+                        chunks.push(buffer);
+                        buffer = undefined;
+                        buffered = 0;
+                    }
+                }
+                continue;
+            }
+            const terminal = consume(chunk.value);
+            if (terminal !== undefined)
+                return await terminalResponse(terminal);
+        }
+        if (sse)
+            throw new ConnectorCallError("connector_call_failed", "Downstream Skills stream ended without a terminal RPC response.");
+        if (buffer && buffered)
+            chunks.push(buffer.subarray(0, buffered));
+        return new Response(new ReadableStream({
+            pull(controller) {
+                const chunk = chunks.shift();
+                if (chunk)
+                    controller.enqueue(chunk);
+                else
+                    controller.close();
+            },
+        }), { status: response.status, statusText: response.statusText, headers: response.headers });
+    }
+    catch (error) {
+        await reader.cancel().catch(() => { });
+        throw error;
+    }
+    finally {
+        signal?.removeEventListener("abort", abort);
+        reader.releaseLock();
+    }
+}
 /**
  * Compatibility concession for hand-rolled servers that serialize
  * end-of-pagination as `null`. Only the cursor is widened; every tool and every
@@ -69,10 +418,7 @@ const CompatibleListToolsResultSchema = {
         version: 1,
         vendor: "connecta",
         validate(value) {
-            const normalized = typeof value === "object" &&
-                value !== null &&
-                "nextCursor" in value &&
-                value.nextCursor === null
+            const normalized = typeof value === "object" && value !== null && "nextCursor" in value && value.nextCursor === null
                 ? (() => {
                     const copy = { ...value };
                     delete copy.nextCursor;
@@ -103,6 +449,16 @@ function isCursorShapeError(err) {
     // failing path in the message rather than exposing the validator's issues.
     return msg(err).startsWith("Invalid result for tools/list: nextCursor:");
 }
+/**
+ * An `authorize_connector` start message for a failure: its text, which has
+ * passed the MCP and OAuth boundaries, and the origin and errno connecta
+ * derived for it, which a message alone would drop.
+ */
+function startMessage(err) {
+    const details = err instanceof ConnectorCallError ? err.details : undefined;
+    const facts = [details?.host, details?.code].filter(Boolean).join(", ");
+    return facts ? `${msg(err)} (${facts})` : msg(err);
+}
 /**
  * End the downstream's session before the connection is torn down.
  *
@@ -127,12 +483,9 @@ function terminateSession(transport, logger, connectorId) {
     const terminate = transport.terminateSession;
     if (typeof terminate !== "function")
         return Effect.void;
-    const warn = (message, error) => Effect.sync(() => {
+    const warn = (log) => Effect.sync(() => {
         try {
-            if (error === undefined)
-                logger.warn(message);
-            else
-                logger.warn(message, error);
+            log();
         }
         catch {
             // A diagnostic sink cannot make best-effort teardown observable to the
@@ -145,13 +498,14 @@ function terminateSession(transport, logger, connectorId) {
     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 ` +
+        promised(() => Promise.resolve(terminate.call(transport))).pipe(Effect.catch((error) => 
+        // The SDK's error quotes the downstream's status text, and its `data`
+        // the body, so the record keeps only the status it answered with.
+        warn(() => logFailure(logger, "session termination refused or failed; the downstream session may remain until its provider timeout", failureRecord({ connector: connectorId }, error instanceof SdkHttpError ? attachFailureFacts(error, { httpStatus: error.status }) : error))))),
+        Effect.sleep(Duration.millis(TERMINATE_SESSION_BUDGET_MS)).pipe(Effect.andThen(warn(() => logger.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 session will remain until its provider timeout.")))),
     ]);
 }
 /**
@@ -178,14 +532,69 @@ function closeLocally(client, transport) {
 function promised(evaluate) {
     return Effect.tryPromise({ try: evaluate, catch: (error) => error });
 }
-/** Classify protocol/status facts; provider prose never decides retryability. */
-function downstreamCallError(error) {
-    if (error instanceof ProtocolError && error.code === -32602) {
-        return new ConnectorCallError("invalid_args", boundedEchoText(error.message));
+/** A retained cause chain must not smuggle an SDK payload past the boundary. */
+function hasSdkPayload(error) {
+    const seen = new Set();
+    for (let current = error; current instanceof Error && !seen.has(current); current = current.cause) {
+        if (current instanceof ProtocolError || current instanceof SdkError)
+            return true;
+        seen.add(current);
+    }
+    return false;
+}
+/** Cancellation can bypass an inner SDK catch and return the signal's reason. */
+function payloadFree(run) {
+    return async (...args) => {
+        try {
+            return await run(...args);
+        }
+        catch (error) {
+            throw hasSdkPayload(error) ? carryFailureFacts(error, downstreamCallError(error)) : error;
+        }
+    };
+}
+/** Both the SDK's auth signal and its classified form invalidate a live client. */
+function requiresAuthorization(error) {
+    return (error instanceof UnauthorizedError ||
+        (error instanceof ConnectorCallError &&
+            (error.code === "auth_required" || error.code === "downstream_oauth_required")));
+}
+/** Classify SDK/runtime facts, dropping every SDK payload and cause chain. */
+function downstreamCallError(error, httpStatus, wait, oauthStep, secrets) {
+    if (error instanceof ConnectorCallError) {
+        return hasSdkPayload(error.cause) ? carryFailureFacts(error, withheldAs(error.message, error)) : error;
+    }
+    if (error instanceof WithheldTextError || error instanceof UnauthorizedError)
+        return error;
+    const network = !(error instanceof SdkError) && !(error instanceof OAuthClientFlowError) ? networkErrorCode(error) : undefined;
+    if (network) {
+        return network === "timeout" || network === "ETIMEDOUT" || network.endsWith("_TIMEOUT")
+            ? new ConnectorCallError("timeout", "The downstream request timed out.")
+            : unavailableCallError(error);
+    }
+    const status = error instanceof SdkHttpError || error instanceof RegistrationRejectedError ? error.status : httpStatus;
+    if (error instanceof InsufficientScopeError ||
+        (status === 403 && !(error instanceof RegistrationRejectedError)) ||
+        (error instanceof OAuthError && ["insufficient_scope", "invalid_scope", "access_denied"].includes(error.code))) {
+        return new ConnectorCallError("provider_permission_denied", "The provider denied this operation. Check the account's permissions and the tool's required access with the provider or an administrator.");
     }
-    if (error instanceof SdkHttpError && error.status >= 400 && error.status < 500) {
-        let message = error.message;
-        if (typeof error.data.text === "string") {
+    // Token endpoints return typed OAuth recovery codes on HTTP 400. Other
+    // OAuth steps, especially registration, keep their HTTP status verdict.
+    if (error instanceof OAuthError &&
+        OAUTH_ERROR_CODES.has(error.code) &&
+        (status === undefined || oauthStep === "token request")) {
+        return new ConnectorCallError(["invalid_client", "invalid_grant", "invalid_token", "unauthorized_client"].includes(error.code)
+            ? "downstream_oauth_required"
+            : error.code === "too_many_requests"
+                ? "rate_limited"
+                : ["server_error", "temporarily_unavailable"].includes(error.code)
+                    ? "unavailable"
+                    : "connector_call_failed", `OAuth failed with error ${error.code}.`);
+    }
+    if (status !== undefined && status >= 400) {
+        let message = `The downstream service answered HTTP ${status}.`;
+        if (error instanceof SdkHttpError && status < 500 && typeof error.data.text === "string") {
+            message = error.message;
             try {
                 const body = JSON.parse(error.data.text);
                 const detail = body?.message ?? body?.error?.message ?? body?.error_description;
@@ -193,12 +602,28 @@ function downstreamCallError(error) {
                     message = detail;
             }
             catch {
-                // Non-JSON refusals still retain a bounded diagnostic.
+                // Non-JSON MCP refusals retain only a bounded diagnostic.
             }
         }
-        return new ConnectorCallError(error.status === 429 ? "rate_limited" : error.status === 408 ? "timeout" : "connector_call_failed", boundedEchoText(message));
+        return new ConnectorCallError(status === 401 && !(error instanceof RegistrationRejectedError)
+            ? "auth_required"
+            : status === 429
+                ? "rate_limited"
+                : status === 408 && !(error instanceof RegistrationRejectedError)
+                    ? "timeout"
+                    : "connector_call_failed", boundedEchoText(secrets?.text(message) ?? message), {
+            retryable: [429, 502, 503, 504].includes(status) || (status === 408 && !(error instanceof RegistrationRejectedError)),
+            ...(wait !== undefined ? { retryAfterMs: wait } : {}),
+        });
+    }
+    if (error instanceof SdkError && error.code === SdkErrorCode.RequestTimeout) {
+        return new ConnectorCallError("timeout", "The downstream request timed out.");
     }
-    return error;
+    // ProtocolError.data is server-chosen even when its message is allowed.
+    if (error instanceof ProtocolError) {
+        return new ConnectorCallError(error.code === -32602 ? "invalid_args" : "connector_call_failed", boundedEchoText(secrets?.text(error.message) ?? error.message));
+    }
+    return new ConnectorCallError("connector_call_failed", "The downstream operation failed.");
 }
 const encoder = new TextEncoder();
 /** Base64 of a UTF-8 string, Web-API only so the core still runs on workerd. */
@@ -231,9 +656,7 @@ async function digestOf(value) {
 function credentialHeaderValue(scheme, value) {
     if (scheme === null)
         return value;
-    return /(?:^|\s)basic$/i.test(scheme)
-        ? `${scheme} ${base64Utf8(value)}`
-        : `${scheme} ${value}`;
+    return /(?:^|\s)basic$/i.test(scheme) ? `${scheme} ${base64Utf8(value)}` : `${scheme} ${value}`;
 }
 /**
  * True when a stored credential carries a character a header cannot.
@@ -260,10 +683,7 @@ function carriesIllegalHeaderChar(value) {
 /** RFC 9110 field-name token, checked once at construction. */
 const HEADER_NAME_TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 function isLoopbackHost(hostname) {
-    return (hostname === "localhost" ||
-        hostname === "127.0.0.1" ||
-        hostname === "[::1]" ||
-        hostname === "::1");
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
 }
 export const MAX_REMOTE_REDIRECT_HOPS = 5;
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
@@ -281,6 +701,7 @@ export class RemoteMcpRedirectError extends ConnectorCallError {
         this.name = "RemoteMcpRedirectError";
     }
 }
+labelErrorClass(RemoteMcpRedirectError, "RemoteMcpRedirectError");
 function redirectedInit(init, status) {
     const method = (init.method ?? "GET").toUpperCase();
     const becomesGet = (status === 303 && method !== "GET" && method !== "HEAD") ||
@@ -319,11 +740,13 @@ export function redirectSafeFetch(connectorId, policy = "none", baseFetch = fetc
             }
             catch (cause) {
                 if (cause instanceof ConnectorCallError)
-                    throw cause;
-                throw unavailableCallError(cause, current.href);
+                    throw downstreamCallError(cause);
+                throw unavailableCallError(cause, current.href, undefined, hasSdkPayload(cause) ? undefined : (init.signal ?? undefined));
             }
+            // Every MCP and OAuth exchange reads its answer through here, and the
+            // SDK reads bodies with `.text()` and `.json()`: as bytes, never text.
             if (!REDIRECT_STATUSES.has(response.status))
-                return response;
+                return byteReadResponse(response);
             const location = response.headers.get("location");
             await response.body?.cancel().catch(() => { });
             if (!location) {
@@ -361,22 +784,55 @@ export function redirectSafeFetch(connectorId, policy = "none", baseFetch = fetc
         }
     };
 }
-class RemoteMcpDestinationError extends ConnectorCallError {
+class RemoteMcpDestinationError extends OAuthRequestNotSentError {
     constructor(connectorId, reason) {
         super("connector_call_failed", `Connector "${connectorId}" refused an OAuth URL the downstream advertised: ${reason}.`);
         this.name = "RemoteMcpDestinationError";
     }
 }
+labelErrorClass(RemoteMcpDestinationError, "RemoteMcpDestinationError");
+/** A connection whose request scope ended while it was being made. */
+class ScopeEndedError extends Error {
+    name = "ScopeEndedError";
+}
+labelErrorClass(ScopeEndedError, "ScopeEndedError");
+/** The MCP client's transport lacks the OAuth flow seams this release is pinned against. */
+class UnboundOAuthFlowsError extends Error {
+    name = "UnboundOAuthFlowsError";
+}
+labelErrorClass(UnboundOAuthFlowsError, "UnboundOAuthFlowsError");
+// The pinned SDK's exported errors, labelled by identity for records and
+// connecta's fixed text.
+for (const [ctor, label] of [
+    [SdkError, "SdkError"],
+    [SdkHttpError, "SdkHttpError"],
+    [ProtocolError, "ProtocolError"],
+    [MissingRequiredClientCapabilityError, "MissingRequiredClientCapabilityError"],
+    [ResourceNotFoundError, "ResourceNotFoundError"],
+    [UnsupportedProtocolVersionError, "UnsupportedProtocolVersionError"],
+    [UrlElicitationRequiredError, "UrlElicitationRequiredError"],
+    [SseError, "SseError"],
+    [OAuthError, "OAuthError"],
+    [UnauthorizedError, "UnauthorizedError"],
+    [OAuthClientFlowError, "OAuthClientFlowError"],
+    [AuthorizationServerMismatchError, "AuthorizationServerMismatchError"],
+    [InsecureTokenEndpointError, "InsecureTokenEndpointError"],
+    [InsufficientScopeError, "InsufficientScopeError"],
+    [IssuerMismatchError, "IssuerMismatchError"],
+    [RegistrationRejectedError, "RegistrationRejectedError"],
+]) {
+    labelErrorClass(ctor, label);
+}
 /**
  * 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.
+ * so this sits below the refresh coordinator on both send paths. Resource
+ * redirects stay same-origin; credential-bearing token requests bypass the
+ * redirect wrapper. The typed local refusal proves that this guard sent nothing;
+ * failures after an HTTP dispatch keep their permanent ambiguous verdict.
  */
 function learnedUrlSafeFetch(connectorId, configured, baseFetch) {
     return async (input, init) => {
@@ -384,9 +840,178 @@ function learnedUrlSafeFetch(connectorId, configured, baseFetch) {
         if (reason !== undefined) {
             throw new RemoteMcpDestinationError(connectorId, reason);
         }
-        return await baseFetch(input, init);
+        return byteReadResponse(await baseFetch(input, init));
     };
 }
+/** The JSON-RPC error answers each transport delivered, as `code\0message`. */
+const wireErrors = new WeakMap();
+/** Answers remembered per transport; one request scope rarely sees more. */
+const MAX_WIRE_ERRORS = 64;
+function wireErrorKey(code, message) {
+    return `${String(code)}\u0000${String(message)}`;
+}
+/**
+ * Remember every JSON-RPC error response `transport` delivers, so that a
+ * `ProtocolError` can be told apart as the downstream's own answer. The SDK
+ * builds its local refusals (an output schema it cannot compile, a result
+ * that fails it) from the same class, with its own text about what the
+ * downstream sent; only one whose code and message arrived on the wire is
+ * the answer. Installed before `Client.connect`, whose protocol calls the
+ * `onmessage` it finds there ahead of its own for every message, and whose
+ * version probe restores it when the probe is done.
+ */
+function recordWireErrors(transport, catalogChanged) {
+    const seen = new Set();
+    wireErrors.set(transport, seen);
+    transport.onmessage = (message) => {
+        // The public transport observer runs before SDK 2.3.1's delete-based
+        // eviction. Ordinary opposite-scope cleanup never rotates this fence.
+        if (isJSONRPCNotification(message) &&
+            (message.method === "notifications/tools/list_changed" ||
+                message.method === "notifications/resources/list_changed"))
+            catalogChanged();
+        if (isJSONRPCErrorResponse(message) && seen.size < MAX_WIRE_ERRORS) {
+            seen.add(wireErrorKey(message.error.code, message.error.message));
+        }
+    };
+}
+/**
+ * Whether an error leaving the SDK may keep its own text. The boundary is an
+ * allow-list: a JSON-RPC error the downstream answered with, an HTTP 4xx
+ * refusal from the MCP endpoint, and errors already in connecta's words (its
+ * own classes, an OAuth error the token responses were rebuilt into, and
+ * `UnauthorizedError`, whose class is the whole verdict and whose text is
+ * never shown). The request's own abort reason is checked by identity before
+ * this. Everything else is withheld.
+ */
+function keepsItsText(err, transport) {
+    if (err instanceof ConnectorCallError ||
+        err instanceof WithheldTextError ||
+        err instanceof UnauthorizedError ||
+        err instanceof OAuthError) {
+        return true;
+    }
+    if (err instanceof SdkHttpError)
+        return err.status >= 400 && err.status < 500;
+    if (err instanceof ProtocolError) {
+        return transport !== undefined && wireErrors.get(transport)?.has(wireErrorKey(err.code, err.message)) === true;
+    }
+    return false;
+}
+/**
+ * The SDK's own checks of a tool's output schema, recognized by how the
+ * pinned SDK (2.3.1) begins their messages, and told in connecta's words.
+ * Recognition reads the SDK's text only to choose connecta's: none of it, nor
+ * the validator's account that follows, is repeated.
+ */
+const SDK_OUTPUT_SCHEMA_CHECKS = [
+    [
+        /^Structured content does not match the tool's output schema/,
+        "the result did not match the tool's declared output schema",
+    ],
+    [
+        /^Tool .* has an output schema but did not return structured content/s,
+        "the result did not return structured content although the tool declares an output schema",
+    ],
+    [/^Tool .* has an invalid outputSchema/s, "the tool's declared output schema could not be compiled"],
+];
+function sdkCheckFailed(err) {
+    if (err instanceof SdkError && err.code === SdkErrorCode.RequestTimeout)
+        return ": the request timed out";
+    if (!(err instanceof ProtocolError))
+        return "";
+    const check = SDK_OUTPUT_SCHEMA_CHECKS.find(([pattern]) => pattern.test(err.message));
+    return check ? `: ${check[1]}` : "";
+}
+/** The first error in `err`'s cause chain already told in connecta's words. */
+function connectaErrorWithin(err) {
+    const seen = new Set();
+    for (let current = err instanceof Error ? err.cause : undefined; current instanceof Error && !seen.has(current); current = current.cause) {
+        seen.add(current);
+        if (current instanceof ConnectorCallError || current instanceof WithheldTextError)
+            return current;
+    }
+    return undefined;
+}
+/** The request's own abort reason, by identity, never by name or class. */
+function ownAbortReason(err, signals) {
+    return signals.some((signal) => signal?.aborted === true && err === signal.reason);
+}
+/**
+ * The request's own abort reason as the SDK hands it back: a request it
+ * cancels rejects with `new SdkError(RequestTimeout, String(reason))` unless
+ * the reason already is one (pinned against client 2.3.1). Its text is the
+ * caller's, so it passes as the SDK wrote it.
+ */
+function ownAbortReasonAsSdkReports(err, signals) {
+    return (err instanceof SdkError &&
+        err.code === SdkErrorCode.RequestTimeout &&
+        signals.some((signal) => signal?.aborted === true && err.message === String(signal.reason)));
+}
+/** An error's class name, when it is a plain identifier worth naming. */
+function errorKind(err) {
+    const label = errorLabel(err);
+    return label && label !== "Error" ? ` (${label})` : "";
+}
+/**
+ * Replace text while keeping a verdict already derived from structured facts.
+ * Never retain the original SDK error as a cause.
+ */
+function withheldAs(message, verdict) {
+    if (verdict instanceof ConnectorCallError) {
+        return new ConnectorCallError(verdict.code, message, {
+            retryable: verdict.retryable,
+            ...(verdict.retryAfterMs !== undefined ? { retryAfterMs: verdict.retryAfterMs } : {}),
+            ...(verdict.details ? { details: verdict.details } : {}),
+            ...(verdict.validation ? { validation: verdict.validation } : {}),
+            ...(verdict.current ? { current: verdict.current } : {}),
+        });
+    }
+    return new WithheldTextError(message, verdict);
+}
+/**
+ * Record each OAuth request on `trail` before sending it. Pinned against
+ * `@modelcontextprotocol/client` 2.3.1: every request the SDK sends anywhere
+ * but the MCP endpoint is a discovery GET, a token request (a form carrying
+ * `grant_type`), or the JSON POST of dynamic client registration.
+ */
+function tracedOAuthFetch(trail, endpoint, baseFetch) {
+    return async (input, init) => {
+        const url = new URL(input);
+        if (url.href === endpoint.href) {
+            trail.last = undefined;
+        }
+        else {
+            const body = init?.body;
+            const step = (init?.method ?? "GET").toUpperCase() === "GET"
+                ? "discovery"
+                : body instanceof URLSearchParams || (typeof body === "string" && new URLSearchParams(body).has("grant_type"))
+                    ? "token request"
+                    : "client registration";
+            trail.last = { step, host: url.origin };
+            if (step === "client registration")
+                trail.registration = url.origin;
+        }
+        const leg = trail.last;
+        const response = await baseFetch(input, init);
+        if (leg) {
+            leg.httpStatus = response.status;
+            const wait = retryAfterMs(response.headers);
+            if (wait !== undefined)
+                leg.retryAfterMs = wait;
+        }
+        return byteReadResponse(response);
+    };
+}
+function registrationErrorCode(body) {
+    try {
+        const code = JSON.parse(body)?.error;
+        return typeof code === "string" && OAUTH_ERROR_CODES.has(code) ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * 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
@@ -398,19 +1023,28 @@ function learnedUrlSafeFetch(connectorId, configured, baseFetch) {
  * server or hide other connectors).
  */
 export function remoteMcp(id, opts) {
+    opts = assertKnownOptions(opts, `remoteMcp(${JSON.stringify(id)})`, REMOTE_MCP_OPTIONS);
+    const skillsEnabled = opts.skills;
+    if (skillsEnabled !== undefined && typeof skillsEnabled !== "boolean") {
+        throw new Error(`[connecta] connector "${id}" skills must be a boolean.`);
+    }
+    const classification = opts.classify === undefined ? undefined : reviewedClassification(opts.classify, `connector "${id}"`);
     const clientMetadataUrl = opts.auth?.type === "oauth" ? opts.auth.clientMetadataUrl : undefined;
     const oauthScope = opts.auth?.type === "oauth" ? opts.auth.scope : undefined;
-    if (oauthScope !== undefined && !/^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/.test(oauthScope)) {
-        throw new Error(`[connecta] connector "${id}" OAuth scope must contain space-separated scope tokens.`);
-    }
+    assertOAuthScope(id, oauthScope);
+    const staticClient = opts.auth?.type === "oauth" && opts.auth.client ? { ...opts.auth.client } : undefined;
+    assertRemoteOAuthClient(id, staticClient);
+    if (staticClient && clientMetadataUrl !== undefined)
+        throw new Error(`[connecta] connector "${id}" OAuth client and clientMetadataUrl are mutually exclusive.`);
     if (clientMetadataUrl !== undefined) {
         let valid = false;
         try {
             const url = new URL(clientMetadataUrl);
-            valid = url.protocol === "https:" && url.pathname !== "/" &&
-                !url.username && !url.password && !url.hash;
+            valid = url.protocol === "https:" && url.pathname !== "/" && !url.username && !url.password && !url.hash;
+        }
+        catch {
+            /* Invalid configuration is rejected below without echoing its value. */
         }
-        catch { /* Invalid configuration is rejected below without echoing its value. */ }
         if (!valid)
             throw new Error(`[connecta] connector "${id}" clientMetadataUrl must be an HTTPS URL with a non-root path, without credentials or a fragment.`);
     }
@@ -425,28 +1059,69 @@ export function remoteMcp(id, opts) {
     // 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();
+    const cacheOwner = {};
+    // A cached transport may dispatch concurrent calls and listings. Register
+    // its actual sent auth with every operation using that client, including
+    // handshake/discovery requests and OAuth rotations. Remove settled users.
+    const activeContexts = new WeakMap();
+    const trackSentRequest = (ctx, input, init) => {
+        const active = activeContexts.get(entryFor(ctx));
+        const recipients = new Set([sentSecretsFor(ctx), ...[...(active ?? [])].map(sentSecretsFor)]);
+        for (const secrets of recipients) {
+            if (opts.auth?.type === "oauth")
+                trackRemoteClientRequest(secrets, input, init);
+            else
+                secrets.request(input, init);
+        }
+    };
+    const connectingWaiters = new WeakMap();
     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.
-    const refreshCoordinators = new WeakMap();
-    const refreshCoordinatorFor = (ctx) => {
-        // Production contexts carry a stable registry partition. Hand-written
-        // contexts can coordinate by their shared storage object instead.
-        const partition = oauthPartitionFor(ctx) ?? ctx.storage;
-        let coordinator = refreshCoordinators.get(partition);
-        if (!coordinator) {
-            coordinator = new OAuthRefreshCoordinator(() => retainOAuthPartition(partition));
-            refreshCoordinators.set(partition, coordinator);
-        }
-        return coordinator;
-    };
+    const refreshCoordinatorFor = refreshCoordinatorsByPartition();
     const logger = opts.logger ?? console;
+    const warnShortSecret = shortSecretWarning();
+    warnShortSecret(staticClient?.clientSecret, logger);
+    if (opts.auth?.type === "headers") {
+        for (const [name, value] of Object.entries(opts.auth.headers)) {
+            if (!/key|token|secret|password|auth|signature|session/i.test(name))
+                continue;
+            const basic = /^Basic\s+(.+)$/i.exec(value);
+            if (basic) {
+                try {
+                    const decoded = atob(basic[1]);
+                    const colon = decoded.indexOf(":");
+                    if (colon !== -1)
+                        warnShortSecret(decoded.slice(colon + 1), logger);
+                }
+                catch {
+                    /* Invalid Basic configuration is not a short password. */
+                }
+            }
+            else
+                warnShortSecret(value.replace(/^(?:Bearer|token)\s+/i, ""), logger);
+        }
+    }
     const credentialAuth = opts.auth?.type === "credential" ? opts.auth : undefined;
     if (credentialAuth?.credential?.fields?.length) {
         throw new Error(`[connecta] connector "${id}" credential auth declares named fields; ` +
             "this shape sends one secret in one header and reads the reserved " +
             "`value` field only.");
     }
+    const requestAuth = opts.auth?.type === "request" ? opts.auth : undefined;
+    if (requestAuth && (typeof requestAuth.token !== "function" || opts.authScope === "personal")) {
+        throw new Error(`remoteMcp(${JSON.stringify(id)}) requires a request token callback and shared authScope.`);
+    }
+    if (requestAuth?.headers) {
+        try {
+            if (Object.keys(requestAuth.headers).some((name) => name.toLowerCase() === "authorization"))
+                throw new Error();
+            new Headers(requestAuth.headers);
+        }
+        catch {
+            throw new Error(`remoteMcp(${JSON.stringify(id)}) requires valid request auth headers without Authorization.`);
+        }
+    }
     const credentialConfig = credentialAuth?.credential ?? {
         label: "API key",
     };
@@ -469,9 +1144,15 @@ export function remoteMcp(id, opts) {
     // endpoint sends bearer tokens / API keys in cleartext. Loopback is exempt
     // for local development.
     const destination = new URL(opts.url);
+    // Only a web URL reaches a remote MCP server. Another scheme cannot, and a
+    // wrapping one (`blob:https://…`) would also carry its inner URL, userinfo
+    // and all, into every place the endpoint is reported; the value is not echoed.
+    if (destination.protocol !== "https:" && destination.protocol !== "http:") {
+        throw new Error(`[connecta] connector "${id}" url must be an http(s) URL.`);
+    }
     const insecureDestination = destination.protocol !== "https:" && !isLoopbackHost(destination.hostname);
     if (insecureDestination) {
-        if (opts.requireHttps) {
+        if (opts.requireHttps || requestAuth) {
             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
@@ -481,11 +1162,186 @@ export function remoteMcp(id, opts) {
             logger.warn(`[connecta] connector "${id}" sends static credentials to ${opts.url} over a non-https:// connection — those tokens will be transmitted in cleartext.`);
         }
     }
-    /** Typed per-call auth signal; the SDK's UnauthorizedError stays as cause. */
-    const authRequiredError = (cause) => new ConnectorCallError("auth_required", `Connector "${id}" requires authorization — call authorize_connector({ connector: "${id}" }) and open the returned URL.`, { cause });
+    /**
+     * Typed per-call auth signal. The `UnauthorizedError` behind it is not kept
+     * as cause: the class is the whole verdict, and a logger rendering the
+     * chain would render whatever text the error carried.
+     */
+    const authRequiredError = () => new ConnectorCallError(isOauth ? "downstream_oauth_required" : "auth_required", `Connector "${id}" requires authorization — call authorize_connector({ connector: "${id}" }) and open the returned URL.`);
+    /**
+     * Tell a failure of one OAuth flow in connecta's words.
+     *
+     * The SDK builds these errors from what a downstream or its authorization
+     * server sent: a refused registration quotes the response body whole, an
+     * issuer mismatch quotes the issuers, a discovery failure the URL or the
+     * metadata it could not accept. Any of them can echo what the request
+     * carried, or text the server planted for an agent to read. What survives
+     * is the step and host of the flow's last request, the classification, and
+     * for a registration the status and a registered OAuth error code.
+     * Anything not already in connecta's words is withheld, including a store's
+     * error while the flow saves what it discovered, which can quote it.
+     */
+    const withoutAuthorizationServerText = async (ctx, err, trail, signals) => {
+        const safeOrigin = async (host) => {
+            if (!host || sentSecretsFor(ctx).contains(host, true))
+                return undefined;
+            if (host === destination.origin || (staticClient && host === new URL(staticClient.issuer).origin))
+                return host;
+            try {
+                return host === (await newProvider(ctx).validatedIssuerOrigin()) ? host : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        };
+        if (ownAbortReason(err, signals) && !hasSdkPayload(err))
+            return err;
+        if (err instanceof RegistrationRejectedError) {
+            const code = registrationErrorCode(err.body);
+            const origin = await safeOrigin(trail.registration);
+            const facts = {
+                step: "OAuth client registration",
+                ...(origin ? { origin } : {}),
+                httpStatus: err.status,
+                ...(code ? { oauthError: code } : {}),
+            };
+            return attachFailureFacts(carryFailureFacts(err, withheldAs(`Connector "${id}" could not register an OAuth client with ` +
+                `${origin ?? "its authorization server"}: the ` +
+                `registration endpoint answered HTTP ${err.status}` +
+                `${code ? ` with OAuth error ${code}` : ""}. Its response is ` +
+                "withheld because it can quote the request or anything the server " +
+                "chose to add. Check the server's client registration policy, then " +
+                "retry authorization.", downstreamCallError(err, undefined, trail.last?.retryAfterMs))), facts);
+        }
+        const leg = trail.last;
+        const origin = await safeOrigin(leg?.host);
+        const facts = leg
+            ? {
+                step: `OAuth ${leg.step}`,
+                ...(origin ? { origin } : {}),
+                ...(leg.httpStatus ? { httpStatus: leg.httpStatus } : {}),
+            }
+            : { step: "OAuth flow" };
+        if (err instanceof UnauthorizedError || err instanceof ConnectorCallError || err instanceof WithheldTextError) {
+            return attachFailureFacts(downstreamCallError(err), facts);
+        }
+        const classified = downstreamCallError(err, leg?.httpStatus, leg?.retryAfterMs, leg?.step);
+        if (err instanceof OAuthError ||
+            (classified instanceof ConnectorCallError && classified.code === "provider_permission_denied")) {
+            return attachFailureFacts(carryFailureFacts(err, classified), facts);
+        }
+        return attachFailureFacts(carryFailureFacts(err, withheldAs(`Connector "${id}" OAuth ${leg ? `${leg.step}${origin ? ` with ${origin}` : ""}` : "flow"} ` +
+            `failed${errorKind(err)}. The error is withheld because its text can ` +
+            "quote what the server sent. Check the server's OAuth metadata, then " +
+            "retry authorization.", classified)), facts);
+    };
+    const endpointOrigin = new URL(opts.url).origin;
+    /**
+     * The MCP boundary, where an error leaves the SDK at the handshake, a
+     * `tools/list` page, or a `tools/call`. The request's own abort reason
+     * passes first, by identity, then what `keepsItsText` allows. Anything else
+     * (a parser's or validator's account, a non-4xx body, a runtime's message)
+     * is told as the step, the endpoint's origin, the HTTP status if there was
+     * one, and the error's class, classified as `verdict` would have been.
+     */
+    const atMcpBoundary = (ctx, err, step, transport, signals) => {
+        // An OAuth flow already attached the step and origin it failed at. The
+        // outer MCP operation must not replace them with the endpoint's facts.
+        if (failureRecord({}, err).step?.startsWith("OAuth "))
+            return downstreamCallError(err);
+        const httpStatus = err instanceof SdkHttpError ? err.status : undefined;
+        // Skills operations retain the existing closed operator-record vocabulary.
+        const facts = {
+            ...(step === "skills/list" || step === "resources/read" ? {} : { step }),
+            origin: endpointOrigin,
+            ...(httpStatus ? { httpStatus } : {}),
+        };
+        const classified = downstreamCallError(redactSentSecrets(ctx, err), undefined, undefined, undefined, sentSecretsFor(ctx));
+        const verdict = isOauth && classified instanceof ConnectorCallError && classified.code === "auth_required"
+            ? carryFailureFacts(err, authRequiredError())
+            : classified;
+        if (ownAbortReasonAsSdkReports(err, signals)) {
+            return attachFailureFacts(carryFailureFacts(err, withheldAs(msg(err), verdict)), facts);
+        }
+        if (err instanceof InsufficientScopeError) {
+            return attachFailureFacts(carryFailureFacts(err, verdict), facts);
+        }
+        if (requestAuth && httpStatus === 401) {
+            return attachFailureFacts(new ConnectorCallError("auth_required", "The downstream rejected this request's Bearer token."), facts);
+        }
+        if (ownAbortReason(err, signals) || keepsItsText(err, transport)) {
+            return attachFailureFacts(carryFailureFacts(err, redactSentSecrets(ctx, err instanceof UnauthorizedError || (ownAbortReason(err, signals) && !hasSdkPayload(err)) ? err : verdict)), facts);
+        }
+        // The SDK wraps a failure of connecta's own fetch (a refused redirect, an
+        // unreachable host) in an error of its own, such as the version probe's;
+        // that failure's words are connecta's, and they say what happened.
+        const ours = connectaErrorWithin(err);
+        if (ours) {
+            return attachFailureFacts(carryFailureFacts(ours, withheldAs(ours.message, ours)), facts);
+        }
+        const status = httpStatus ? ` with HTTP ${httpStatus}` : "";
+        return attachFailureFacts(carryFailureFacts(err, withheldAs(`Connector "${id}" ${step} with ${endpointOrigin} failed${status}` +
+            `${errorKind(err)}${sdkCheckFailed(err)}. The error is withheld because ` +
+            "its text can quote what the server sent.", verdict)), facts);
+    };
+    /**
+     * Run every OAuth flow the SDK starts on `transport` inside a boundary of
+     * its own: a trail only that flow's requests write to, and
+     * `withoutAuthorizationServerText` on whatever the flow throws. Calls on
+     * one client can each start a flow at once, so no flow's failure is ever
+     * told by another flow's last request.
+     *
+     * Pinned against `@modelcontextprotocol/client` 2.3.1, whose transport
+     * offers no public seam for this. A flow starts in exactly two places, each
+     * handing `auth()` the fetch to use: the adapted provider's
+     * `onUnauthorized` (a 401, at connect or on a live client), given the fetch
+     * in its context, and `_stepUpAuthorize` (a 403 `insufficient_scope`),
+     * which reads `this._fetchWithInit`. The callback's code exchange runs
+     * outside both, and the callback route repeats nothing it throws. If an
+     * upgrade moves either seam, this refuses to build the transport rather
+     * than run flows unbounded.
+     */
+    const boundOAuthFlows = (ctx, transport, endpoint, 
+    /** The request's and connection's signals: only their reasons pass as written. */
+    signals) => {
+        const internals = transport;
+        const adapted = internals._authProvider;
+        const onUnauthorized = adapted?.onUnauthorized;
+        const stepUp = internals._stepUpAuthorize;
+        if (!adapted || typeof onUnauthorized !== "function" || typeof stepUp !== "function") {
+            // Its own class, so that a status record, which carries no message, says so.
+            throw new UnboundOAuthFlowsError(`[connecta] connector "${id}": the MCP client's transport no longer ` +
+                "has the OAuth flow seams this release is pinned against, so its " +
+                "flows cannot be bounded. Pin @modelcontextprotocol/client to the " +
+                "version this release ships with.");
+        }
+        const flow = async (start) => {
+            const trail = {};
+            try {
+                return await start((fetchFn) => tracedOAuthFetch(trail, endpoint, async (input, init) => {
+                    trackSentRequest(ctx, input, init);
+                    return await fetchFn(input, init);
+                }));
+            }
+            catch (err) {
+                throw await withoutAuthorizationServerText(ctx, err, trail, signals);
+            }
+        };
+        adapted.onUnauthorized = (ctx) => flow((trace) => onUnauthorized.call(adapted, { ...ctx, fetchFn: trace(ctx.fetchFn ?? fetch) }));
+        internals._stepUpAuthorize = (challenge, retries) => flow((trace) => {
+            const traced = trace(internals._fetchWithInit ?? fetch);
+            // The step-up reads its fetch from `this`; everything else it reads
+            // and writes stays the transport's own.
+            const self = new Proxy(transport, {
+                get: (target, key) => (key === "_fetchWithInit" ? traced : Reflect.get(target, key, target)),
+                set: (target, key, value) => Reflect.set(target, key, value, target),
+            });
+            return stepUp.call(self, challenge, retries);
+        });
+    };
     class OperatorDisconnectedError extends ConnectorCallError {
         constructor() {
-            super("auth_required", `Connector "${id}" was disconnected by an operator — explicitly start authorization to reconnect it.`);
+            super("downstream_oauth_required", `Connector "${id}" was disconnected by an operator — explicitly start authorization to reconnect it.`);
         }
     }
     const operatorDisconnectedError = () => new OperatorDisconnectedError();
@@ -507,6 +1363,27 @@ export function remoteMcp(id, opts) {
      * without a redeploy. The value stays in the caller's local scope.
      */
     const readCredential = async (ctx) => {
+        if (requestAuth) {
+            let value;
+            try {
+                value = await requestAuth.token(ctx);
+            }
+            catch (error) {
+                if (error instanceof ConnectorCallError)
+                    throw error;
+                throw new ConnectorCallError("auth_required", "The request token could not be resolved.");
+            }
+            ctx.signal?.throwIfAborted();
+            if (typeof value !== "string" ||
+                !value.trim() ||
+                Array.from(value).some((char) => {
+                    const code = char.charCodeAt(0);
+                    return code <= 32 || (code >= 127 && code <= 159);
+                })) {
+                throw new ConnectorCallError("auth_required", "The request token is empty or cannot be sent as a Bearer header.");
+            }
+            return value;
+        }
         if (!ctx.credential) {
             throw new CredentialRequiredError(`Connector "${id}" needs an operator-managed credential, but ` +
                 "credential storage is not configured. Configure vault in deployment code and redeploy. Call authorize_connector for recovery options.");
@@ -551,6 +1428,10 @@ export function remoteMcp(id, opts) {
         let current = err;
         while (current instanceof Error && !seen.has(current)) {
             seen.add(current);
+            // Decided already, beneath the transport, and wrapped by the SDK on
+            // the way up (the version probe's error, say).
+            if (current instanceof CredentialRequiredError)
+                return 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. Call authorize_connector for recovery options. When available, " +
@@ -561,30 +1442,146 @@ export function remoteMcp(id, opts) {
         }
         return err;
     };
-    const scopeEndedError = () => new Error(`Connector "${id}" scope ended during connection.`);
+    // Its own class, so that a status record, which carries no message, still says so.
+    const scopeEndedError = () => new ScopeEndedError(`Connector "${id}" scope ended during connection.`);
     const requestOptions = (ctx) => ctx.timeoutMs || ctx.signal
         ? {
             ...(ctx.timeoutMs ? { timeout: ctx.timeoutMs } : {}),
             ...(ctx.signal ? { signal: ctx.signal } : {}),
         }
         : undefined;
-    /**
-     * One `tools/list` request. The SDK schema is retained wholesale except for
-     * accepting `null` as the common, unambiguous end-of-chain spelling. Other
-     * cursor shapes still get a useful connector-level diagnosis.
-     */
-    const listPage = async (client, cursor, ctx) => {
-        try {
-            return await client.request({
-                method: "tools/list",
-                ...(cursor === undefined ? {} : { params: { cursor } }),
-            }, CompatibleListToolsResultSchema, requestOptions(ctx));
-        }
-        catch (err) {
-            if (!isCursorShapeError(err))
-                throw err;
-            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 });
-        }
+    /** Wrap the public request seam, before listTools aggregates or auto-caches.
+     * SDK 2.3.1 treats an identical repeated page as completion. Refuse it here:
+     * an advertised successor is never proof of a complete catalog (INV-8). */
+    const listingContexts = new WeakMap();
+    const installCatalogIntake = (client, ctx, cache) => {
+        let toolPages = 0;
+        const listingContext = (options) => {
+            const { signal: _signal, timeoutMs: _timeout, ...base } = ctx;
+            return ((options && listingContexts.get(options)) ?? {
+                ...base,
+                requestScope: ctx.requestScope ?? ctx,
+                ...(options?.signal ? { signal: options.signal } : {}),
+                ...(options?.timeout ? { timeoutMs: options.timeout } : {}),
+            });
+        };
+        const listTools = client.listTools.bind(client);
+        client.listTools = (params, options) => cache.withListing(listingContext(options), async () => {
+            const before = toolPages;
+            let result;
+            try {
+                result = await listTools(params, options);
+            }
+            catch (error) {
+                const bounded = atMcpBoundary(cache.currentContext(), error, "tools/list", client.transport, [
+                    cache.currentContext().signal,
+                ]);
+                const transient = (error instanceof SdkHttpError && [502, 503, 504].includes(error.status)) ||
+                    (bounded instanceof ConnectorCallError && bounded.code === "unavailable");
+                const fallback = transient && toolPages === before ? await cache.fallbackTools() : undefined;
+                if (!fallback)
+                    throw error;
+                return fallback;
+            }
+            if (toolPages !== before && params?.cursor === undefined) {
+                const refresh = await cache.completeCatalogRefresh(result);
+                if (refresh) {
+                    try {
+                        await observeCompletedCatalogRefresh(cache.currentContext(), refresh);
+                    }
+                    catch (error) {
+                        logFailure(cache.currentContext().logger, "catalog refresh observation failed", failureRecord({ connector: id }, error));
+                    }
+                }
+            }
+            return result;
+        });
+        const listResources = client.listResources.bind(client);
+        client.listResources = (params, options) => cache.withListing(listingContext(options), () => listResources(params, options));
+        const listResourceTemplates = client.listResourceTemplates.bind(client);
+        client.listResourceTemplates = (params, options) => cache.withListing(listingContext(options), () => listResourceTemplates(params, options));
+        const request = client.request.bind(client);
+        const walks = new WeakMap();
+        client.request = (async (...args) => {
+            const message = args[0];
+            if (message.method !== "tools/list" &&
+                message.method !== "resources/list" &&
+                message.method !== "resources/templates/list")
+                return Reflect.apply(request, client, args);
+            const method = message.method;
+            const ctx = cache.currentContext();
+            const options = (args.length === 3 ? args[2] : args[1]);
+            if (isClosed(entryFor(ctx)))
+                throw scopeEndedError();
+            if (options?.signal?.aborted)
+                throw options.signal.reason;
+            const key = options ?? message;
+            let walk = walks.get(key);
+            if (message.params?.cursor === undefined || !walk) {
+                walk = { names: new Set(), cursors: new Set(), barren: 0, bytes: 0 };
+                walks.set(key, walk);
+            }
+            let page;
+            try {
+                page = await request(message, method === "tools/list"
+                    ? CompatibleListToolsResultSchema
+                    : method === "resources/list"
+                        ? specTypeSchemas.ListResourcesResult
+                        : specTypeSchemas.ListResourceTemplatesResult, options);
+            }
+            catch (error) {
+                if (isCursorShapeError(error))
+                    throw new ConnectorCallError("connector_call_failed", "Downstream catalog nextCursor must be a string, null, or absent.", { retryable: false });
+                throw error;
+            }
+            assertDownstreamOutputSafe(ctx.requestScope ?? ctx, page);
+            const clean = cache.intake(ctx, method, page);
+            if (method === "tools/list")
+                toolPages++;
+            if (message.params?.cursor === undefined)
+                observeCatalogFetch(ctx, Date.now(), method);
+            const tools = catalogItems(method, clean).filter((item) => {
+                const name = method === "tools/list"
+                    ? item.name
+                    : method === "resources/list"
+                        ? item.uri
+                        : item.uriTemplate;
+                if (walk.names.has(name))
+                    return false;
+                walk.names.add(name);
+                return true;
+            });
+            walk.bytes += new TextEncoder().encode(JSON.stringify(tools)).byteLength;
+            if (walk.names.size > MAX_CATALOG_TOOLS || walk.bytes > MAX_SERIALIZED_CATALOG_BYTES) {
+                throw new ConnectorCallError("connector_call_failed", "Downstream catalog exceeds the complete-catalog ceiling.", { retryable: false });
+            }
+            if (clean.nextCursor !== undefined) {
+                if (walk.cursors.has(clean.nextCursor))
+                    throw new ConnectorCallError("connector_call_failed", "Downstream catalog pagination chain loops.", {
+                        retryable: false,
+                    });
+                if (tools.length === 0 && ++walk.barren > 1)
+                    throw new ConnectorCallError("connector_call_failed", "Downstream catalog pagination is not advancing.", {
+                        retryable: false,
+                    });
+                if (tools.length > 0)
+                    walk.barren = 0;
+                walk.cursors.add(clean.nextCursor);
+            }
+            const field = method === "tools/list" ? "tools" : method === "resources/list" ? "resources" : "resourceTemplates";
+            const result = { ...clean, [field]: tools };
+            if (!walk.first)
+                walk.first = result;
+            else {
+                // SDK aggregation retains page-one metadata. A later page may only
+                // narrow its reuse grant, never broaden the complete catalog's scope.
+                walk.first.ttlMs = Math.min(walk.first.ttlMs, clean.ttlMs);
+                if (clean.cacheScope !== "public")
+                    walk.first.cacheScope = "private";
+            }
+            observeCatalogExpiry(ctx, method, walk.first.ttlMs);
+            return result;
+        });
     };
     /** This request scope's entry, open or closed, created on first sight. */
     const entryFor = (ctx) => {
@@ -601,6 +1598,7 @@ export function remoteMcp(id, opts) {
                 authRequired: false,
                 provider: null,
                 connectedGeneration: null,
+                attemptProvider: null,
                 credentialDigest: null,
             };
             states.set(key, state);
@@ -614,25 +1612,29 @@ export function remoteMcp(id, opts) {
             throw scopeEndedError();
         return state;
     };
-    const newProvider = (ctx, state) => {
+    const newProvider = (ctx, state, signal = ctx.signal) => {
         if (state?.provider)
             return state.provider;
-        const provider = new KvOAuthProvider(id, ctx.storage, `${ctx.baseUrl}/oauth/callback/${id}`, refreshCoordinatorFor(ctx), ctx.allowAuthorization === true, oauthSealerFor(ctx), ctx.signal, JSON.stringify({
+        const metadataUrl = staticClient ? undefined : (clientMetadataUrl ?? selfHostedClientUrl(ctx.publicUrl, id));
+        const redirectUri = downstreamRedirectUri(ctx.baseUrl, ctx.publicUrl, id);
+        const provider = new KvOAuthProvider(id, ctx.storage, redirectUri, refreshCoordinatorFor(ctx), ctx.allowAuthorization === true, oauthSealerFor(ctx), signal, JSON.stringify({
             url: new URL(opts.url).href,
-            redirectUri: `${ctx.baseUrl}/oauth/callback/${id}`,
-            clientMetadata: {
-                redirect_uris: [`${ctx.baseUrl}/oauth/callback/${id}`],
-                client_name: "connecta",
-                grant_types: ["authorization_code", "refresh_token"],
-                response_types: ["code"],
-                token_endpoint_auth_method: "none",
-                ...(oauthScope !== undefined ? { scope: oauthScope } : {}),
-            },
+            redirectUri,
+            clientMetadata: downstreamClientMetadata(redirectUri, oauthScope, ctx.oauthClientName, staticClient ? remoteClientAuthMethod(staticClient) : "none"),
             authScope: opts.authScope ?? "shared",
             versionNegotiation: opts.versionNegotiation ?? "auto",
             redirects: opts.redirects ?? "none",
-            clientMetadataUrl,
-        }), (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset), clientMetadataUrl, oauthScope);
+            clientMetadataUrl: metadataUrl,
+            ...(staticClient
+                ? {
+                    client: {
+                        issuer: staticClient.issuer,
+                        clientId: staticClient.clientId,
+                        tokenEndpointAuthMethod: staticClient.tokenEndpointAuthMethod,
+                    },
+                }
+                : {}),
+        }), (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset), metadataUrl, oauthScope, undefined, { name: ctx.oauthClientName, client: staticClient, secrets: sentSecretsFor(ctx) });
         if (state)
             state.provider = provider;
         return provider;
@@ -643,22 +1645,71 @@ export function remoteMcp(id, opts) {
      * by the caller so the raw secret is not passed around twice. Never
      * retained past the transport it configures.
      */
-    credentialFramed = null) => {
+    credentialFramed = null, signal = ctx.signal, 
+    /** The raw value behind `credentialFramed`, under the same terms. */
+    credentialValue = null) => {
         if (opts._transportFactory)
             return opts._transportFactory(ctx);
         const url = new URL(opts.url);
-        const guardedFetch = redirectSafeFetch(id, opts.redirects);
+        const trackedFetch = async (input, init) => {
+            trackSentRequest(ctx, input, init);
+            let rpc;
+            if (typeof init?.body === "string") {
+                try {
+                    rpc = JSON.parse(init.body);
+                }
+                catch {
+                    /* OAuth exchanges can send form-encoded bodies. */
+                }
+            }
+            const writeContinuation = downstreamWriteContinuation(ctx.requestScope ?? ctx) &&
+                init?.method === "POST" &&
+                skillObject(rpc) &&
+                rpc.method === "tools/call";
+            const response = writeContinuation
+                ? await fetch(input, { ...init, redirect: "manual" })
+                : await fetch(input, init);
+            if (writeContinuation && (response.status === 401 || (response.status >= 300 && response.status < 400))) {
+                await response.body?.cancel().catch(() => { });
+                // Stop before the SDK can refresh auth or follow a redirect and resend
+                // this write. The host's one-use continuation nonce remains spent.
+                if (response.status === 401)
+                    throw authRequiredError();
+                throw new ConnectorCallError("connector_call_failed", "The downstream redirected a write continuation; it was not repeated.", { retryable: false });
+            }
+            if (skillsEnabled && skillObject(rpc) && (rpc.method === "skills/list" || rpc.method === "resources/read")) {
+                return boundedSkillResponse(response, rpc.method === "skills/list" ? MAX_SERIALIZED_CATALOG_BYTES : MAX_SKILL_READ_RPC_BYTES, rpc.id, init?.signal);
+            }
+            return response;
+        };
+        // A runtime refusing the assembled header quotes it, and the transport
+        // error below keeps none of what the runtime said. So whether the
+        // rejection quoted the credential is decided here, first, and survives
+        // as the class of the error rather than as its text.
+        const guardedFetch = redirectSafeFetch(id, opts.redirects, credentialFramed === null
+            ? trackedFetch
+            : async (input, init) => {
+                try {
+                    return await trackedFetch(input, init);
+                }
+                catch (err) {
+                    throw withoutCredential(err, credentialValue, credentialFramed);
+                }
+            });
         if (opts.auth?.type === "oauth") {
-            const oauthProvider = provider ?? newProvider(ctx);
-            return new StreamableHTTPClientTransport(url, {
+            const oauthProvider = provider ?? newProvider(ctx, undefined, signal);
+            const transport = new StreamableHTTPClientTransport(url, {
                 authProvider: oauthProvider,
-                fetch: refreshCoordinatorFor(ctx).coordinatedFetch(oauthProvider, learnedUrlSafeFetch(id, url, guardedFetch), ctx.signal),
+                onInsufficientScope: "throw",
+                fetch: refreshCoordinatorFor(ctx).coordinatedFetch(oauthProvider, learnedUrlSafeFetch(id, url, trackedFetch), signal, ctx.defer, learnedUrlSafeFetch(id, url, guardedFetch)),
             });
+            boundOAuthFlows(ctx, transport, url, [signal, ctx.signal]);
+            return transport;
         }
         const headers = opts.auth?.type === "headers"
             ? opts.auth.headers
-            : credentialAuth && credentialFramed !== null
-                ? { [credentialHeader]: credentialFramed }
+            : (credentialAuth || requestAuth) && credentialFramed !== null
+                ? { ...requestAuth?.headers, [credentialHeader]: credentialFramed }
                 : undefined;
         return new StreamableHTTPClientTransport(url, {
             ...(headers ? { requestInit: { headers } } : {}),
@@ -677,8 +1728,8 @@ export function remoteMcp(id, opts) {
         state.credentialDigest = null;
         // `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
+    // 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. Terminating and closing are
     // each bounded, so no close waits more than two seconds in all.
     const closingSessions = new WeakMap();
@@ -710,7 +1761,7 @@ export function remoteMcp(id, opts) {
         // for the one call that observed it. Do not let the still-cached client make
         // a later status or call in the same scope report healthy.
         if (state.authRequired) {
-            throw authRequiredError(new UnauthorizedError("Downstream authorization is no longer valid."));
+            throw authRequiredError();
         }
         // Read the OAuth epoch before trusting either a cached client or starting a
         // transport. A disconnected epoch is a durable operator instruction, not
@@ -719,14 +1770,14 @@ export function remoteMcp(id, opts) {
         let oauthGeneration;
         if (isOauth && (state.client || state.connecting)) {
             const provider = newProvider(ctx, state);
-            oauthGeneration = await provider.generation();
-            if (provider.isOperatorDisconnectedGeneration(oauthGeneration)) {
+            oauthGeneration = await provider.liveEpoch();
+            if (provider.isOperatorDisconnectedEpoch(oauthGeneration)) {
                 closeHalf(state);
                 throw operatorDisconnectedError();
             }
         }
-        // Cross-isolate force re-auth: another isolate bumped the KV generation and
-        // wiped credentials. This request's cached client still speaks the old
+        // Cross-isolate force re-auth: another isolate replaced the grant's epoch,
+        // and the grant with it. 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 (isClosed(state))
@@ -743,7 +1794,7 @@ export function remoteMcp(id, opts) {
         let credentialValue = null;
         let credentialFramed = null;
         let credentialDigest = null;
-        if (credentialAuth) {
+        if (credentialAuth || requestAuth) {
             credentialValue = await readCredential(ctx);
             credentialFramed = credentialHeaderValue(credentialScheme, credentialValue);
             credentialDigest = await digestOf(credentialValue);
@@ -754,8 +1805,16 @@ export function remoteMcp(id, opts) {
             if ((state.client || state.connecting) &&
                 state.credentialDigest !== null &&
                 state.credentialDigest !== credentialDigest) {
+                // A slow vault/token read or digest can resume after a newer caller
+                // connected with the replacement. Never let that stale read tear down
+                // the newer connection and install the rotated-away credential.
+                const observedConnection = state.client ?? state.connecting;
+                const currentCredential = await readCredential(ctx);
                 if (isClosed(state))
                     throw scopeEndedError();
+                if (currentCredential !== credentialValue || (state.client ?? state.connecting) !== observedConnection) {
+                    throw new ConnectorCallError("connector_call_failed", "The downstream credential changed while connecting; retry the operation.", { retryable: true });
+                }
                 closeHalf(state);
             }
         }
@@ -763,13 +1822,28 @@ export function remoteMcp(id, opts) {
             throw scopeEndedError();
         if (state.client)
             return state.client;
-        const attempt = state.connecting ??
-            startConnect(ctx, state, credentialValue, credentialFramed, credentialDigest);
+        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));
+        connectingWaiters.set(attempt, (connectingWaiters.get(attempt) ?? 0) + 1);
+        let client;
+        try {
+            client = await runEdge(Deferred.await(attempt), { signal: ctx.signal });
+        }
+        finally {
+            const remaining = (connectingWaiters.get(attempt) ?? 1) - 1;
+            if (remaining > 0)
+                connectingWaiters.set(attempt, remaining);
+            else {
+                connectingWaiters.delete(attempt);
+                // A cancelled waiter leaves its siblings' handshake alone. Once every
+                // waiter has left, abandon the attempt and its OAuth refresh too.
+                if (ctx.signal?.aborted && state.connecting === attempt)
+                    closeHalf(state);
+            }
+        }
         // 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.
@@ -806,58 +1880,150 @@ export function remoteMcp(id, opts) {
         // 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.
+            // The transport and its OAuth provider are shared by every call in this
+            // scope. A call's deadline signal is aborted even on success, so retaining
+            // the first caller's signal here would abort its siblings and later calls.
+            // Keep OAuth work cancellable by the connection's own lifetime instead;
+            // requestOptions still passes each call's signal to the SDK separately.
+            const connectionAbort = new AbortController();
+            // Own cancellation before beginFlow's storage reads.
+            // The lease first owns just the signal, then the transport it creates.
+            const lease = Scope.forkUnsafe(state.scope);
             const handshakeAbort = new AbortController();
-            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 },
-            });
-            // @modelcontextprotocol/client 2.0.0 can attempt the legacy initialized
-            // notification after we close its transport. Its rejected Promise is
-            // unhandled under workerd even though connect() has a caller. This
-            // connection is already abandoned, so skip only that final handshake
-            // notification after our abort. Remove when the SDK owns this race:
-            // https://github.com/modelcontextprotocol/typescript-sdk/issues/2864
-            const notify = c.notification.bind(c);
-            c.notification = (message, options) => {
-                if (handshakeAbort.signal.aborted && message.method === "notifications/initialized") {
-                    return Promise.resolve();
-                }
-                return notify(message, options);
+            const held = {
+                client: null,
+                transport: null,
             };
-            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.sync(() => handshakeAbort.abort()).pipe(Effect.andThen(Effect.suspend(() => closeConnection(held.client, t, ctx.logger)))));
+            yield* Scope.addFinalizer(lease, Effect.sync(() => handshakeAbort.abort()).pipe(Effect.andThen(Effect.suspend(() => {
+                if (!held.transport)
+                    connectionAbort.abort();
+                return closeConnection(held.client, held.transport, ctx.logger);
+            })), 
+            // Let session termination use the OAuth fetch wrapper before ending
+            // its lifetime. Local transport close aborts all active MCP fetches.
+            Effect.ensuring(Effect.sync(() => connectionAbort.abort()))));
             state.lease = lease;
-            state.transport = t;
             return yield* Effect.gen(function* () {
-                yield* promised(() => c.connect(t, { signal: handshakeAbort.signal }));
+                // 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, undefined, connectionAbort.signal) : null;
+                // Every OAuth run of this attempt — a 401's refresh or consent, a
+                // step-up — happens inside the SDK, bound to the epoch live now: a
+                // reset meanwhile fails the attempt rather than handing it the next
+                // epoch's grant.
+                const genAtStart = provider ? yield* promised(() => provider.beginFlow()) : "";
+                if (!owned())
+                    return yield* Effect.fail(scopeEndedError());
+                if (provider)
+                    state.attemptProvider = provider;
+                if (provider?.isOperatorDisconnectedEpoch(genAtStart)) {
+                    return yield* Effect.fail(operatorDisconnectedError());
+                }
+                // 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 oauthConfig = isOauth
+                    ? {
+                        client: staticClient,
+                        clientMetadataUrl: staticClient
+                            ? undefined
+                            : (clientMetadataUrl ?? selfHostedClientUrl(ctx.publicUrl, id)),
+                        redirectUri: downstreamRedirectUri(ctx.baseUrl, ctx.publicUrl, id),
+                        clientName: ctx.oauthClientName,
+                    }
+                    : undefined;
+                const negotiationDigest = yield* promised(() => digestOf(JSON.stringify([
+                    opts.url,
+                    opts.versionNegotiation ?? "auto",
+                    opts.auth?.type,
+                    opts.auth?.type === "headers" ? opts.auth.headers : requestAuth?.headers,
+                    credentialHeader,
+                    credentialScheme,
+                    opts.authScope ?? "shared",
+                    opts.redirects ?? "none",
+                    oauthConfig,
+                    oauthScope,
+                    state.credentialDigest,
+                    genAtStart,
+                    callerOf(ctx),
+                    skillsEnabled === true,
+                ])));
+                const prior = opts.versionNegotiation === "legacy"
+                    ? undefined
+                    : yield* promised(() => readNegotiation(ctx, negotiationDigest));
+                if (!owned())
+                    return yield* Effect.fail(scopeEndedError());
+                const cacheOptions = yield* promised(() => catalogClientOptions(ctx, id, JSON.stringify({
+                    url: new URL(opts.url).href,
+                    auth: opts.auth?.type ?? null,
+                    headers: opts.auth?.type === "headers" ? opts.auth.headers : requestAuth?.headers,
+                    credentialHeader,
+                    credentialScheme,
+                    authScope: opts.authScope ?? "shared",
+                    redirects: opts.redirects ?? "none",
+                    versionNegotiation: opts.versionNegotiation ?? "auto",
+                    oauthConfig,
+                    oauthScope,
+                }), JSON.stringify([genAtStart, state.credentialDigest]), connectionAbort.signal, cacheOwner, requestAuth || opts.authScope === "personal" ? "private" : "shared", provider ? async () => digestOf(JSON.stringify(await provider.tokens())) : undefined));
+                if (!owned())
+                    return yield* Effect.fail(scopeEndedError());
+                const makeClient = () => {
+                    const { intake: _intake, completeCatalogRefresh: _refresh, withListing: _listing, currentContext: _context, ...clientOptions } = cacheOptions;
+                    const client = new Client({ name: "connecta", version: CONNECTA_VERSION }, {
+                        ...clientOptions,
+                        listMaxPages: MAX_TOOL_PAGES,
+                        versionNegotiation: {
+                            mode: opts.versionNegotiation ?? "auto",
+                        },
+                        capabilities: {
+                            ...downstreamInputCapabilities(ctx.requestScope ?? ctx),
+                            ...(skillsEnabled ? { extensions: { [SKILLS_EXTENSION]: {} } } : {}),
+                        },
+                        // The host owns each sealed continuation; never auto-retry a write.
+                        inputRequired: { autoFulfill: false },
+                    });
+                    installCatalogIntake(client, ctx, cacheOptions);
+                    return client;
+                };
+                let c = makeClient();
+                let t = buildTransport(ctx, provider, credentialFramed, connectionAbort.signal, credentialValue);
+                if (!owned()) {
+                    held.transport = t;
+                    return yield* Effect.fail(scopeEndedError());
+                }
+                state.transport = t;
+                held.transport = t;
+                recordWireErrors(t, () => observeCatalogChange(ctx, id, connectionAbort.signal, cacheOwner));
+                yield* promised(async () => {
+                    try {
+                        await c.connect(t, { signal: handshakeAbort.signal, ...(prior ? { prior } : {}) });
+                    }
+                    catch (error) {
+                        // Some legacy servers crash on an unknown pre-initialize method.
+                        // Only an auto probe's typed HTTP 5xx permits a fresh legacy
+                        // handshake. An auth failure, timeout or initialize failure does not.
+                        if (prior ||
+                            opts.versionNegotiation === "legacy" ||
+                            !(error instanceof SdkHttpError) ||
+                            error.code !== SdkErrorCode.EraNegotiationFailed ||
+                            error.status < 500 ||
+                            error.status >= 600 ||
+                            !owned() ||
+                            handshakeAbort.signal.aborted)
+                            throw error;
+                        // The SDK closed the failed probe transport. Its replacement owns
+                        // a new connection, with the same credential and OAuth generation.
+                        c = makeClient();
+                        t = buildTransport(ctx, provider, credentialFramed, connectionAbort.signal, credentialValue);
+                        state.transport = held.transport = t;
+                        recordWireErrors(t, () => observeCatalogChange(ctx, id, connectionAbort.signal, cacheOwner));
+                        await c.connect(t, { signal: handshakeAbort.signal, prior: { kind: "legacy" } });
+                    }
+                }).pipe(Effect.mapError((err) => atMcpBoundary(ctx, 
+                // First, while the runtime's text can still be read for it.
+                withoutCredential(err, credentialValue, credentialFramed), "MCP handshake", t, [ctx.signal, connectionAbort.signal, handshakeAbort.signal])));
+                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
                 // that race anyway, close the resulting client rather than resurrecting
@@ -868,8 +2034,8 @@ export function remoteMcp(id, opts) {
                 // 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
+                    const generation = yield* promised(() => provider.liveEpoch());
+                    // closeScope can land while the epoch read is pending, after
                     // connect succeeded but before this client is cached. Discard the
                     // client on that side of the await too.
                     if (!owned())
@@ -878,21 +2044,24 @@ export function remoteMcp(id, opts) {
                         return yield* Effect.fail(new UnauthorizedError("Connector was re-authorized during connect; reconnect required."));
                     }
                 }
-                held.client = c;
                 state.client = c;
                 state.connectedGeneration = genAtStart;
                 state.authRequired = false;
+                const discover = c.getDiscoverResult();
+                if (!prior)
+                    yield* promised(() => storeNegotiation(ctx, negotiationDigest, discover ? { kind: "modern", discover } : { kind: "legacy" }));
+                if (!owned())
+                    return yield* Effect.fail(scopeEndedError());
                 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)
+                    if (requiresAuthorization(err))
                         state.authRequired = true;
                     const release = Scope.closeUnsafe(lease, Exit.void);
                     if (release)
@@ -902,10 +2071,10 @@ export function remoteMcp(id, opts) {
                     // 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));
+                    detach(closeConnection(held.client, held.transport, ctx.logger));
                 }
                 if (err instanceof UnauthorizedError) {
-                    return Effect.fail(authRequiredError(err));
+                    return Effect.fail(carryFailureFacts(err, authRequiredError()));
                 }
                 // Defense in depth for the one error class that can quote the
                 // credential: a runtime refusing the assembled header.
@@ -921,32 +2090,156 @@ export function remoteMcp(id, opts) {
         // 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 reset = provider.resetAuthorization(operatorDisconnected, preserveClient);
+        const reset = operatorDisconnected
+            ? provider.disconnectAuthorization(learnedUrlSafeFetch(id, new URL(opts.url), async (input, init) => {
+                trackSentRequest(ctx, input, init);
+                return await fetch(input, init);
+            }))
+            : provider.resetAuthorization(false, preserveClient);
         try {
             await reset;
         }
         finally {
             // Abandon any connect in flight and close whichever half of the
-            // client/transport exists. Reset is unconditional because KV may already
+            // client/transport exists. Reset is unconditional because storage may already
             // be fenced behind a newer epoch after a cleanup error.
             closeHalf(state);
         }
     };
+    // Built once from construction-time values: names, framing, and public
+    // URLs only. A static header's value and a stored credential never reach
+    // it, and a URL keeps origin and path: a CIMD document's query may carry a
+    // token even though the document itself is public.
+    const describedClientMetadataUrl = describedUrl(clientMetadataUrl);
+    const authDescription = requestAuth
+        ? {
+            mode: "request",
+            header: "Authorization",
+            scheme: "Bearer",
+            ...(requestAuth.headers ? { headerNames: Object.keys(requestAuth.headers) } : {}),
+        }
+        : opts.auth?.type === "headers"
+            ? { mode: "headers", headerNames: Object.keys(opts.auth.headers) }
+            : credentialAuth
+                ? { mode: "credential", header: credentialHeader, scheme: credentialScheme }
+                : isOauth
+                    ? {
+                        mode: "oauth",
+                        ...(oauthScope !== undefined ? { scope: oauthScope } : {}),
+                        ...(describedClientMetadataUrl !== undefined ? { clientMetadataUrl: describedClientMetadataUrl } : {}),
+                    }
+                    : { mode: "none" };
+    const endpoint = describedEndpoint(opts.url);
+    const optionSources = Object.freeze({
+        "source.kind": "default",
+        "auth.mode": opts.auth === undefined ? "default" : "config",
+        "auth.header": credentialAuth?.header === undefined ? "default" : "config",
+        "auth.scheme": credentialAuth?.scheme === undefined ? "default" : "config",
+        "credential.label": credentialAuth?.credential === undefined ? "default" : "config",
+        ...Object.fromEntries(["versionNegotiation", "redirects", "requireHttps"].map((key) => [
+            `transport.${key}`,
+            opts[key] === undefined ? "default" : "config",
+        ])),
+    });
+    const resourceTemplateRefusals = new Set();
+    const skillScopeOpen = (ctx, state) => {
+        if (isClosed(state))
+            throw scopeEndedError();
+        if (ctx.signal?.aborted)
+            throw ctx.signal.reason instanceof Error ? ctx.signal.reason : scopeEndedError();
+    };
+    const withSkillsClient = async (ctx, method, run) => {
+        const state = stateFor(ctx);
+        const client = await ensureConnected(ctx, state);
+        try {
+            skillScopeOpen(ctx, state);
+            const capabilities = client.getServerCapabilities();
+            const extension = capabilities?.extensions?.[SKILLS_EXTENSION];
+            if (client.getProtocolEra() !== "modern" ||
+                !skillObject(capabilities?.resources) ||
+                !skillObject(extension) ||
+                (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.");
+            }
+            const result = await run(client, state);
+            skillScopeOpen(ctx, state);
+            return result;
+        }
+        catch (error) {
+            if (ownAbortReason(error, [ctx.signal]) && !hasSdkPayload(error))
+                throw error;
+            const classified = atMcpBoundary(ctx, error, method, client.transport, [ctx.signal]);
+            if (requiresAuthorization(classified) && state.client === client)
+                state.authRequired = true;
+            // The SDK and downstream can quote whole manifests or bodies in errors.
+            // Keep their typed verdict and operator facts, never the quoted payload.
+            throw carryFailureFacts(classified, withheldAs(`Connector "${id}" downstream ${method} failed.`, classified));
+        }
+    };
     const connector = {
         id,
         ...(opts.title !== undefined ? { title: opts.title } : {}),
         kind: "mcp",
-        ...(opts.description !== undefined
-            ? { description: opts.description }
-            : {}),
+        describe: () => ({
+            optionSources,
+            source: { kind: "remote-mcp" },
+            ...(endpoint ? { endpoint } : {}),
+            auth: authDescription,
+            transport: {
+                versionNegotiation: opts.versionNegotiation ?? "auto",
+                redirects: opts.redirects ?? "none",
+                requireHttps: opts.requireHttps ?? false,
+            },
+        }),
+        ...(opts.description !== undefined ? { description: opts.description } : {}),
         ...(opts.authScope !== undefined ? { authScope: opts.authScope } : {}),
-        ...(opts.maxResultBytes !== undefined
-            ? { maxResultBytes: opts.maxResultBytes }
-            : {}),
-        ...(opts.callAdmission !== undefined
-            ? { callAdmission: opts.callAdmission }
-            : {}),
+        ...(opts.maxResultBytes !== undefined ? { maxResultBytes: opts.maxResultBytes } : {}),
+        ...(opts.callAdmission !== undefined ? { callAdmission: opts.callAdmission } : {}),
         ...(opts.usageGuide !== undefined ? { usageGuide: opts.usageGuide } : {}),
+        ...(skillsEnabled
+            ? {
+                downstreamSkills: {
+                    list: (ctx) => withSkillsClient(ctx, "skills/list", async (client, state) => {
+                        const listed = [];
+                        const uris = new Set();
+                        const cursors = new Set();
+                        let cursor;
+                        let bytes = 0;
+                        for (let page = 0; page < MAX_SKILLS; page++) {
+                            skillScopeOpen(ctx, state);
+                            const result = await client.request({ method: "skills/list", ...(cursor === undefined ? {} : { params: { cursor } }) }, SkillPageSchema, requestOptions(ctx));
+                            bytes += result.bytes;
+                            if (bytes > MAX_SERIALIZED_CATALOG_BYTES || listed.length + result.skills.length > MAX_SKILLS) {
+                                throw new ConnectorCallError("connector_call_failed", "Downstream Skills listing exceeds the aggregate limit.");
+                            }
+                            for (const skill of result.skills) {
+                                if (uris.has(skill.uri))
+                                    throw new ConnectorCallError("connector_call_failed", "Downstream Skills listing contains duplicate skill URIs.");
+                                uris.add(skill.uri);
+                                listed.push(skill);
+                            }
+                            if (result.nextCursor === undefined)
+                                return listed;
+                            if (!result.skills.length || cursors.has(result.nextCursor)) {
+                                throw new ConnectorCallError("connector_call_failed", "Downstream Skills pagination loops or makes no progress.");
+                            }
+                            cursors.add(result.nextCursor);
+                            cursor = result.nextCursor;
+                        }
+                        throw new ConnectorCallError("connector_call_failed", "Downstream Skills listing exceeds the page limit.");
+                    }),
+                    read: (uri, ctx) => withSkillsClient(ctx, "resources/read", async (client) => {
+                        // The registry admits only advertised manifest URIs. An explicit
+                        // request bypasses the SDK readResource response cache entirely and
+                        // validates the raw result before its resource union drops fields.
+                        return client.request({ method: "resources/read", params: { uri } }, skillReadSchema(uri), requestOptions(ctx));
+                    }),
+                },
+            }
+            : {}),
+        // Data the registry classifies every read with; listTools below returns
+        // the downstream's listing unclassified.
+        ...(classification !== undefined ? { classification } : {}),
         // Declaring the slot is what makes the rest of the operator surface work:
         // the connection's credential form renders it, the shape check compares
         // against it, and authorize_connector returns the operator handoff rather than
@@ -996,117 +2289,48 @@ export function remoteMcp(id, opts) {
                 },
             }
             : {}),
-        // `tools/list` is cursor-paginated: the server chooses the page size and
-        // signals "there is more" with a `nextCursor`, which the SDK's
-        // Client.listTools() returns without following. Collect the whole chain
-        // here, because a half-collected catalog is indistinguishable from a small
-        // one — later-page tools would simply appear not to exist, unsearchable and
-        // unaddressable, with nothing anywhere saying why.
-        //
-        // All pages ride the one request-scoped client already connected above, and
-        // the accumulator is returned rather than stored: a cursor is opaque and
-        // session-bound, so nothing here may outlive this call.
+        // The SDK walks the whole chain and writes one complete result. Intake
+        // runs on its public request seam before any page can enter that cache.
         async listTools(ctx) {
-            // 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);
-            // 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 = [];
-            const names = new Set();
-            const spent = new Set();
-            let cursor;
-            /** Consecutive pages that advertised a successor but added nothing. */
-            let barren = 0;
-            let complete = false;
+            let clean;
+            const options = requestOptions(ctx) ?? {};
+            listingContexts.set(options, ctx);
             try {
-                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 (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
-                    // in-flight SDK request, so expiry never starts one more round trip.
-                    if (ctx.signal?.aborted) {
-                        throw ctx.signal.reason instanceof Error
-                            ? ctx.signal.reason
-                            : new Error(`Connector "${id}" catalog deadline expired.`);
-                    }
-                    // Page one sends no params at all, so a non-paginated server sees
-                    // exactly the request it saw before pagination existed.
-                    const res = await listPage(client, cursor, ctx);
-                    let added = 0;
-                    for (const t of res.tools) {
-                        // First page wins. An unstable cursor can serve the same tool on
-                        // two pages — a duplicate would inflate `toolCount`, double the
-                        // `search_tools` row, and churn catalog persistence.
-                        if (names.has(t.name))
-                            continue;
-                        names.add(t.name);
-                        listed.push(t);
-                        added++;
-                    }
-                    // Pagination ends when `nextCursor` is absent or null — never merely
-                    // falsy. Empty string is present and means "keep going".
-                    const next = res.nextCursor;
-                    if (next === undefined || next === null) {
-                        complete = true;
-                        break;
-                    }
-                    // A page that adds nothing and still claims a successor made no
-                    // progress. Allow exactly one: the widespread idiom is to advertise
-                    // a cursor whenever a page came back full and then serve one empty
-                    // page to terminate. Two in a row is a downstream going nowhere.
-                    if (added === 0 && ++barren > 1) {
-                        throw new Error(`Connector "${id}" returned two consecutive tools/list pages that added no tools and still advertised another — the catalog is not advancing.`);
-                    }
-                    if (added > 0)
-                        barren = 0;
-                    // A cursor handed back a second time is a loop, not a slow server.
-                    if (spent.has(next)) {
-                        throw new Error(`Connector "${id}" handed back a tools/list cursor it had already issued — the pagination chain loops.`);
-                    }
-                    // Checked here rather than on arrival: this bounds what a *walk* may
-                    // accumulate; a one-page server was always free to send its page.
-                    if (listed.length > MAX_CATALOG_TOOLS) {
-                        throw new Error(`Connector "${id}" advertised further tools/list pages past ${listed.length} tools, over the ${MAX_CATALOG_TOOLS}-tool ceiling one catalog refresh will collect.`);
-                    }
-                    // Opaque by contract: handed straight back, never parsed, rewritten,
-                    // or persisted.
-                    spent.add(next);
-                    cursor = next;
-                }
+                const result = await client.listTools(undefined, options);
+                clean = redactCatalog(ctx, result.tools);
             }
             catch (err) {
-                // A grant can be revoked after connect and after any earlier page.
-                // Classify that exactly like connect-time and call-time authorization
-                // failures, and latch it for the rest of this request scope.
-                if (err instanceof UnauthorizedError) {
+                if (ownAbortReason(err, [ctx.signal]) && !hasSdkPayload(err))
+                    throw err;
+                const bounded = atMcpBoundary(ctx, err, "tools/list", client.transport, [ctx.signal]);
+                if (requiresAuthorization(bounded)) {
                     if (state.client === client)
                         state.authRequired = true;
-                    throw authRequiredError(err);
+                    if (bounded instanceof UnauthorizedError)
+                        throw carryFailureFacts(bounded, authRequiredError());
                 }
-                throw err;
-            }
-            // Fail the refresh outright. Returning what we have would publish a
-            // partial catalog that looks complete; throwing lets the registry keep
-            // serving the last complete one via its stale fallback.
-            if (!complete) {
-                throw new Error(`Connector "${id}" kept advertising more tools/list pages after ${MAX_TOOL_PAGES} — refusing to page further.`);
-            }
-            // Publish definitions only after the full walk succeeds. A later-page
-            // failure must not leave a partial validation/header view behind.
-            state.toolDefinitions = new Map(listed.map((tool) => [tool.name, tool]));
-            return listed.map((t) => ({
+                throw bounded;
+            }
+            finally {
+                listingContexts.delete(options);
+            }
+            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
+                    ? {
+                        // Inline images can consume the catalog ceiling and storage chunks.
+                        // The SDK needs no icons for validation or parameter mirroring.
+                        icons: t.icons.filter((icon) => !/^data:/i.test(icon.src)),
+                    }
+                    : {}),
+                ...(t.execution !== undefined ? { execution: t.execution } : {}),
+                // SEP-2243 declarations live in inputSchema. SDK validation and header
+                // mirroring need no _meta keys, so arbitrary downstream metadata stays
+                // out of the persisted catalog.
                 ...(t.description !== undefined ? { description: t.description } : {}),
                 ...(t.inputSchema !== undefined
                     ? {
@@ -1125,37 +2349,132 @@ export function remoteMcp(id, opts) {
                     : {}),
             }));
         },
-        async callTool(name, args, ctx) {
+        async callTool(name, args, ctx, options) {
+            if (classification?.unlisted === "hide" && !Object.hasOwn(classification.tools, name)) {
+                throw new ConnectorCallError("invalid_args", "This tool is not in the connector allowlist.");
+            }
             const state = stateFor(ctx);
             const client = await ensureConnected(ctx, state);
             try {
-                const toolDefinition = state.toolDefinitions.get(name);
+                const definition = options?.definition;
+                const toolDefinition = definition
+                    ? {
+                        ...definition,
+                        // Older stored catalogs and custom connectors may omit inputSchema.
+                        inputSchema: (definition.inputSchema ?? { type: "object" }),
+                    }
+                    : state.toolDefinitions.get(name);
                 if (toolDefinition?.execution?.taskSupport === "required") {
-                    throw new Error(`Tool "${name}" requires task-based execution, which Connecta does not support.`);
+                    throw new ConnectorCallError("connector_call_failed", `Tool "${name}" requires task-based execution, which Connecta does not support.`);
                 }
-                const result = await client.callTool({
+                let output;
+                const outputError = (code, message) => atMcpBoundary(ctx, new ProtocolError(code, message), "tools/call", client.transport, [ctx.signal]);
+                if (toolDefinition?.outputSchema) {
+                    try {
+                        output = fromJsonSchema(toolDefinition.outputSchema);
+                    }
+                    catch {
+                        throw outputError(-32602, `Tool '${name}' has an invalid outputSchema: schema could not be compiled`);
+                    }
+                }
+                const result = await client
+                    .callTool({
                     name,
                     arguments: (args ?? {}),
+                    ...options?.input,
                 }, {
                     ...requestOptions(ctx),
                     allowInputRequired: true,
-                    ...(toolDefinition ? { toolDefinition } : {}),
+                    // SDK 2.3.1's callTool checks outputSchema even for a suspension.
+                    // Retain its header mirroring, then validate only final results.
+                    ...(toolDefinition ? { toolDefinition: { ...toolDefinition, outputSchema: undefined } } : {}),
+                })
+                    .catch((err) => {
+                    assertDownstreamOutputSafe(ctx.requestScope ?? ctx, err);
+                    throw atMcpBoundary(ctx, err, "tools/call", client.transport, [ctx.signal]);
                 });
                 if (isInputRequiredResult(result)) {
-                    throw new ConnectorCallError("input_required_unsupported", `Connector "${id}" returned input_required for "${name}". ` +
-                        "Connecta cannot relay multi-round-trip input yet; this " +
-                        "capability is gated pending real host and downstream adoption.");
+                    return result;
+                }
+                assertDownstreamOutputSafe(ctx.requestScope ?? ctx, result);
+                if (output && !result.isError) {
+                    if (result.structuredContent === undefined)
+                        throw outputError(-32600, `Tool ${name} has an output schema but did not return structured content`);
+                    const validation = await output["~standard"].validate(result.structuredContent);
+                    if (validation.issues)
+                        throw outputError(-32602, "Structured content does not match the tool's output schema: validation failed");
                 }
                 return result;
             }
             catch (err) {
                 // A grant revoked after connect surfaces here, not in ensureConnected.
-                if (err instanceof UnauthorizedError) {
+                if (ownAbortReason(err, [ctx.signal]) && !hasSdkPayload(err))
+                    throw err;
+                if (requiresAuthorization(err)) {
+                    if (state.client === client)
+                        state.authRequired = true;
+                    if (err instanceof UnauthorizedError)
+                        throw carryFailureFacts(err, authRequiredError());
+                }
+                throw downstreamCallError(err, undefined, undefined, undefined, sentSecretsFor(ctx));
+            }
+        },
+        async readResource(uri, ctx) {
+            const state = stateFor(ctx);
+            const client = await ensureConnected(ctx, state);
+            try {
+                const options = requestOptions(ctx) ?? {};
+                listingContexts.set(options, ctx);
+                try {
+                    if (!client.getServerCapabilities()?.resources)
+                        throw unadvertisedResource();
+                    const resources = await client.listResources(undefined, options);
+                    const templates = await client.listResourceTemplates(undefined, options);
+                    const exact = resources.resources.some((resource) => resource.uri === uri);
+                    if (!exact) {
+                        const match = resourceUriMatchesTemplates(uri, templates.resourceTemplates, (code) => resourceTemplateRefusals.add(code));
+                        if (!match.matched) {
+                            if (match.refusal)
+                                throw new ConnectorCallError(match.refusal, match.refusal === "resource_template_ambiguous"
+                                    ? "The advertised resource templates have ambiguous expression boundaries."
+                                    : "Resource template matching exceeds the read work limit.", { retryable: false });
+                            throw unadvertisedResource();
+                        }
+                    }
+                }
+                catch (err) {
+                    throw atMcpBoundary(ctx, err, "resources/read", client.transport, [ctx.signal]);
+                }
+                finally {
+                    listingContexts.delete(options);
+                }
+                const result = await client
+                    .readResource({ uri }, {
+                    ...requestOptions(ctx),
+                    cacheMode: "bypass",
+                    allowInputRequired: true,
+                })
+                    .catch((err) => {
+                    if (err instanceof ResourceNotFoundError) {
+                        throw new ConnectorCallError("not_found", "The downstream resource does not exist.");
+                    }
+                    throw atMcpBoundary(ctx, err, "resources/read", client.transport, [ctx.signal]);
+                });
+                if (isInputRequiredResult(result)) {
+                    throw new ConnectorCallError("input_required_unsupported", "Resource reads inside programs cannot request mid-call input.");
+                }
+                return result;
+            }
+            catch (err) {
+                if (ownAbortReason(err, [ctx.signal]) && !hasSdkPayload(err))
+                    throw err;
+                if (requiresAuthorization(err)) {
                     if (state.client === client)
                         state.authRequired = true;
-                    throw authRequiredError(err);
+                    if (err instanceof UnauthorizedError)
+                        throw carryFailureFacts(err, authRequiredError());
                 }
-                throw downstreamCallError(err);
+                throw downstreamCallError(err, undefined, undefined, undefined, sentSecretsFor(ctx));
             }
         },
         async closeScope(ctx) {
@@ -1166,68 +2485,95 @@ export function remoteMcp(id, opts) {
             // 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);
+            const cacheClosing = closeCatalogCacheScope(ctx, id, cacheOwner);
+            // Storage cannot cancel an already-started write. Bound the join in
+            // parallel with transport cleanup so it adds no unbounded teardown tail.
+            const cacheClosed = cacheClosing &&
+                runEdge(Effect.raceAllFirst([
+                    Effect.promise(() => cacheClosing),
+                    Effect.sleep(Duration.millis(LOCAL_CLOSE_BUDGET_MS)),
+                ]));
             reset(state);
             // Runs the live connection's lease finalizer, if there is one.
             if (release)
                 await runEdge(release);
+            await cacheClosed;
         },
         async status(ctx) {
             const state = stateFor(ctx);
+            const report = async (status) => {
+                const path = isOauth ? await newProvider(ctx, state).registrationPath() : undefined;
+                return ownStatus({
+                    ...status,
+                    ...(path ? { registrationPath: path } : {}),
+                    ...(resourceTemplateRefusals.size ? { resourceTemplateRefusals: [...resourceTemplateRefusals] } : {}),
+                });
+            };
             try {
                 await ensureConnected(ctx, state);
-                return { state: "ok" };
+                return report({ state: "ok" });
             }
             catch (err) {
                 // An empty slot, or one with no vault behind it, is reported the way a
                 // missing grant is: present, unauthenticated, and repairable — never a
                 // boot failure and never a silently absent connector.
                 if (err instanceof CredentialRequiredError) {
-                    return { state: "auth_required", message: err.message };
+                    return report({ state: "auth_required", message: err.message });
+                }
+                if (err instanceof OperatorDisconnectedError) {
+                    return report({ state: "auth_required", message: err.message });
                 }
                 if (state.authRequired) {
                     // Only an OAuth connector has a pending consent URL to offer. A
                     // credential connector's downstream 401 is repaired in the operator
                     // UI connection, so do not reach into OAuth storage to look for one.
-                    return {
+                    return report({
                         state: "auth_required",
                         message: credentialAuth
                             ? "Authorization required — the downstream rejected this connector's stored credential."
                             : "Authorization required — open the URL to connect.",
-                    };
+                    });
                 }
-                if (err instanceof OperatorDisconnectedError) {
-                    return { state: "auth_required", message: err.message };
-                }
-                return { state: "error", message: msg(err) };
+                // An operator surface: the record, never the error's own text.
+                return failureStatus(id, err);
             }
         },
         async finishAuth(code, ctx, callbackParams) {
             const state = stateFor(ctx);
             const provider = newProvider(ctx, state);
-            // 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.
-            // 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));
+            // verifyState ran on this request-scoped provider first and found the
+            // consent; a programmatic exchange names it by its callback's state.
+            const consent = callbackParams?.get("state") ?? null;
+            if (!consent || !(await provider.verifyCallbackState(consent))) {
+                throw new ConnectorCallError("connector_call_failed", `Connector "${id}" authorization callback matches no pending consent; nothing was exchanged.`);
+            }
+            // The exchange reads and writes only the epoch its consent was written
+            // in; it decides nothing about the grant there.
+            provider.validateCallbackIssuer(callbackParams?.get("iss") ?? null);
+            await provider.bindFlow();
+            // Always a transport of the exchange's own, over the provider that
+            // verified the state: that provider holds the consent's claim, and the
+            // fence before the token request is its to cross. A connection this
+            // scope opened earlier speaks for its connect attempt, not this callback.
+            const t = buildTransport(ctx, provider);
+            const trail = {};
+            const internals = t;
+            const traced = tracedOAuthFetch(trail, new URL(opts.url), internals._fetchWithInit ?? fetch);
+            const exchange = new Proxy(t, {
+                get: (target, key) => (key === "_fetchWithInit" ? traced : Reflect.get(target, key, target)),
+                set: (target, key, value) => Reflect.set(target, key, value, target),
+            });
             try {
-                if (callbackParams !== undefined) {
-                    await t.finishAuth(callbackParams);
-                }
-                else {
-                    await t.finishAuth(code);
-                }
-                await provider.clearPending();
+                await exchange.finishAuth(callbackParams);
                 // Reset so the next use reconnects with the freshly stored tokens.
                 closeHalf(state);
             }
+            catch (err) {
+                throw await withoutAuthorizationServerText(ctx, err, trail, [ctx.signal]);
+            }
             finally {
                 // This exchange-only transport has no lease in the request scope.
-                // It must close even when redemption or pending-state cleanup fails.
-                if (!leased)
-                    detach(closeConnection(null, t, ctx.logger));
+                detach(closeConnection(null, t, ctx.logger));
             }
         },
     };
@@ -1236,15 +2582,18 @@ export function remoteMcp(id, opts) {
             const state = stateFor(ctx);
             return newProvider(ctx, state).verifyState(oauthState);
         };
+        connector.verifyCallbackIssuer = async (issuer, ctx) => {
+            newProvider(ctx, stateFor(ctx)).validateCallbackIssuer(issuer);
+            return true;
+        };
+        connector.consumeAuthError = async (ctx) => {
+            await newProvider(ctx, stateFor(ctx)).consumeAuthError();
+        };
         connector.disconnectAuth = async (ctx) => {
             await disconnectAuthorization(ctx, stateFor(ctx), true);
         };
         connector.startAuth = async (ctx, startOpts) => {
-            ctx = attachOAuthPartition(inheritOAuthSealer(ctx, {
-                ...ctx,
-                requestScope: ctx.requestScope ?? ctx,
-                allowAuthorization: true,
-            }), oauthPartitionFor(ctx));
+            ctx = authorizingContext(ctx);
             const state = stateFor(ctx);
             state.provider = null;
             const p = newProvider(ctx, state);
@@ -1283,36 +2632,116 @@ export function remoteMcp(id, opts) {
             }
             catch (err) {
                 if (state.authRequired) {
-                    const authorizationUrl = await p.pendingAuthorizationUrl();
+                    // The consent this start's attempt stored, while its epoch is live:
+                    // one a later reset published belongs to another flow, and this
+                    // start fails rather than hand it out.
+                    let authorizationUrl;
+                    try {
+                        authorizationUrl = await state.attemptProvider?.consentUrl();
+                    }
+                    catch (readErr) {
+                        return { state: "error", message: startMessage(readErr) };
+                    }
                     return {
                         state: "auth_required",
                         ...(authorizationUrl !== undefined ? { authorizationUrl } : {}),
                         message: "Authorization required — open the URL to connect.",
                     };
                 }
-                return { state: "error", message: msg(err) };
+                return { state: "error", message: startMessage(err) };
             }
         };
     }
+    const withActiveSecrets = async (ctx, run, redactResult = true, preserveInput = false) => {
+        trackCredentialReads(ctx);
+        const secrets = sentSecretsFor(ctx);
+        if (opts.auth?.type === "headers") {
+            for (const value of Object.values(opts.auth.headers))
+                secrets.header(value);
+        }
+        const state = entryFor(ctx);
+        let active = activeContexts.get(state);
+        if (!active) {
+            active = new Set();
+            activeContexts.set(state, active);
+        }
+        active.add(ctx);
+        try {
+            const result = await run();
+            // Opaque state must reach the sealing handler byte-exact. Invocation
+            // intercepts it before ordinary result processing or guest exposure.
+            if (!preserveInput || !isInputRequiredResult(result))
+                assertDownstreamOutputSafe(ctx.requestScope ?? ctx, result);
+            return (preserveInput && isInputRequiredResult(result)) || !redactResult
+                ? result
+                : redactSentSecrets(ctx, result);
+        }
+        catch (error) {
+            assertDownstreamOutputSafe(ctx.requestScope ?? ctx, error);
+            throw redactSentSecrets(ctx, error);
+        }
+        finally {
+            active.delete(ctx);
+        }
+    };
+    const callTool = connector.callTool;
+    connector.callTool = (name, args, ctx, options) => withActiveSecrets(ctx, () => callTool(name, args, ctx, options), true, true);
+    const listTools = connector.listTools;
+    connector.listTools = (ctx) => withActiveSecrets(ctx, () => listTools(ctx));
+    const readResource = connector.readResource;
+    connector.readResource = (uri, ctx) => withActiveSecrets(ctx, () => readResource(uri, ctx));
+    if (connector.downstreamSkills) {
+        const { list, read } = connector.downstreamSkills;
+        connector.downstreamSkills.list = (ctx) => withActiveSecrets(ctx, () => list(ctx), false);
+        connector.downstreamSkills.read = (uri, ctx) => withActiveSecrets(ctx, () => read(uri, ctx), false);
+    }
+    if (isOauth && !staticClient && clientMetadataUrl === undefined)
+        declareSelfHostedClient(connector, oauthScope);
     if (isOauth) {
+        const start = connector.startAuth;
+        connector.startAuth = async (...args) => {
+            const status = await start(...args);
+            const path = await newProvider(args[0], stateFor(args[0])).registrationPath();
+            return { ...status, ...(path ? { registrationPath: path } : {}) };
+        };
         // Pin before the first asynchronous storage/discovery read, not only once
         // a refresh flight exists. These operations do not take call admission.
-        const retain = (operation, contextIndex) => async (...args) => {
-            const release = retainOAuthPartition(oauthPartitionFor(args[contextIndex]));
-            try {
-                return await operation(...args);
-            }
-            finally {
-                release();
-            }
-        };
+        const retain = retainingOAuthPartition;
         connector.listTools = retain(connector.listTools, 0);
         connector.callTool = retain(connector.callTool, 2);
+        connector.readResource = retain(connector.readResource, 1);
+        if (connector.downstreamSkills) {
+            connector.downstreamSkills.list = retain(connector.downstreamSkills.list, 0);
+            connector.downstreamSkills.read = retain(connector.downstreamSkills.read, 1);
+        }
         connector.status = retain(connector.status, 0);
         connector.startAuth = retain(connector.startAuth, 0);
         connector.disconnectAuth = retain(connector.disconnectAuth, 0);
         connector.verifyState = retain(connector.verifyState, 1);
+        connector.verifyCallbackIssuer = retain(connector.verifyCallbackIssuer, 1);
+        connector.consumeAuthError = retain(connector.consumeAuthError, 0);
         connector.finishAuth = retain(connector.finishAuth, 1);
     }
+    connector.listTools = payloadFree(connector.listTools);
+    connector.callTool = payloadFree(connector.callTool);
+    connector.readResource = payloadFree(connector.readResource);
+    if (connector.downstreamSkills) {
+        connector.downstreamSkills.list = payloadFree(connector.downstreamSkills.list);
+        connector.downstreamSkills.read = payloadFree(connector.downstreamSkills.read);
+    }
+    if (connector.startAuth)
+        connector.startAuth = payloadFree(connector.startAuth);
+    if (connector.finishAuth)
+        connector.finishAuth = payloadFree(connector.finishAuth);
+    if (isOauth)
+        registerInvocationAuth(connector, retainingOAuthPartition(async (ctx) => {
+            // Only inspect local grant state here. Discovery, refresh, and MCP
+            // transports remain inside callTool and cannot establish retry safety.
+            const provider = newProvider(ctx, stateFor(ctx));
+            if (await provider.operatorDisconnected())
+                throw operatorDisconnectedError();
+            if (!(await provider.tokens()))
+                throw authRequiredError();
+        }, 0));
     return connector;
 }