@zackbart/connecta 0.29.0 → 0.31.0

package/dist/argument-redaction.js

@@ -0,0 +1,230 @@
+const PUBLIC = {};
+const OMIT = { omit: true };
+const OMITTED = Symbol("omitted argument");
+const MAX_DEPTH = 32;
+const MAX_SCHEMAS = 2048;
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function sensitive(plan) {
+    return Object.keys(plan).length > 0;
+}
+function equal(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function item(plan, index) {
+    return plan.prefix?.[index] ?? plan.items ?? PUBLIC;
+}
+/** Combine restrictions from references, siblings, and allOf without losing array indices. */
+function merge(left, right) {
+    if (left.omit || right.omit)
+        return OMIT;
+    const names = new Set([...Object.keys(left.properties ?? {}), ...Object.keys(right.properties ?? {})]);
+    const properties = Object.fromEntries([...names]
+        .sort()
+        .map((name) => [
+        name,
+        merge(Object.hasOwn(left.properties ?? {}, name) ? left.properties[name] : PUBLIC, Object.hasOwn(right.properties ?? {}, name) ? right.properties[name] : PUBLIC),
+    ]));
+    const items = mergeItems(left.items ?? PUBLIC, right.items ?? PUBLIC);
+    const prefix = Array.from({ length: Math.max(left.prefix?.length ?? 0, right.prefix?.length ?? 0) }, (_, index) => mergeItems(item(left, index), item(right, index)));
+    // Equivalent plans compare equally even when one schema spells out public prefixes.
+    while (prefix.length && equal(prefix.at(-1), items))
+        prefix.pop();
+    return {
+        ...(names.size ? { properties } : {}),
+        ...(prefix.length ? { prefix } : {}),
+        ...(sensitive(items) ? { items } : {}),
+    };
+}
+function mergeItems(left, right) {
+    if (!sensitive(left))
+        return right;
+    if (!sensitive(right))
+        return left;
+    return merge(left, right);
+}
+/** Compile a bounded plan. Unknown sensitivity refuses the entire echo, never just a branch. */
+function compile(root, unionAlternatives = false) {
+    let visited = 0;
+    const active = new Set();
+    const unresolved = () => {
+        throw new Error("Unresolved argument sensitivity");
+    };
+    function reference(ref) {
+        if (typeof ref !== "string" || !ref.startsWith("#"))
+            return unresolved();
+        const pointer = decodeURIComponent(ref.slice(1));
+        if (pointer === "")
+            return root;
+        if (!pointer.startsWith("/"))
+            return unresolved();
+        let target = root;
+        for (const encoded of pointer.slice(1).split("/")) {
+            if (/~[^01]|~$/.test(encoded))
+                return unresolved();
+            const key = encoded.replace(/~1/g, "/").replace(/~0/g, "~");
+            if (target === null || typeof target !== "object" || !Object.hasOwn(target, key))
+                return unresolved();
+            target = target[key];
+        }
+        return target;
+    }
+    function walk(schema, depth) {
+        if (++visited > MAX_SCHEMAS || depth > MAX_DEPTH)
+            return unresolved();
+        if (typeof schema === "boolean")
+            return PUBLIC;
+        if (!object(schema) || active.has(schema))
+            return unresolved();
+        if (schema["writeOnly"] !== undefined && typeof schema["writeOnly"] !== "boolean")
+            return unresolved();
+        if (schema["writeOnly"] === true)
+            return OMIT;
+        if ((schema !== root && schema["$id"] !== undefined) ||
+            schema["$dynamicRef"] !== undefined ||
+            schema["$recursiveRef"] !== undefined)
+            return unresolved();
+        active.add(schema);
+        try {
+            let plan = PUBLIC;
+            const child = (value) => walk(value, depth + 1);
+            if (schema["$ref"] !== undefined)
+                plan = merge(plan, child(reference(schema["$ref"])));
+            if (schema["properties"] !== undefined) {
+                if (!object(schema["properties"]))
+                    return unresolved();
+                const properties = Object.entries(schema["properties"])
+                    .map(([name, value]) => [name, child(value)])
+                    .filter(([, value]) => sensitive(value))
+                    .sort(([a], [b]) => a.localeCompare(b));
+                plan = merge(plan, properties.length ? { properties: Object.fromEntries(properties) } : PUBLIC);
+            }
+            const prefixes = schema["prefixItems"] ?? (Array.isArray(schema["items"]) ? schema["items"] : undefined);
+            if (prefixes !== undefined && !Array.isArray(prefixes))
+                return unresolved();
+            if (schema["prefixItems"] !== undefined && Array.isArray(schema["items"]))
+                return unresolved();
+            const tail = Array.isArray(schema["items"]) ? schema["additionalItems"] : schema["items"];
+            const arrayPlan = {
+                ...(prefixes ? { prefix: prefixes.map(child) } : {}),
+                ...(tail !== undefined ? { items: child(tail) } : {}),
+            };
+            plan = merge(plan, arrayPlan);
+            for (const keyword of ["allOf", "oneOf", "anyOf"]) {
+                const branches = schema[keyword];
+                if (branches === undefined)
+                    continue;
+                if (!Array.isArray(branches) || !branches.length)
+                    return unresolved();
+                const plans = branches.map(child);
+                if (keyword === "allOf" || unionAlternatives)
+                    for (const branch of plans)
+                        plan = merge(plan, branch);
+                else {
+                    if (plans.some((branch) => !equal(branch, plans[0])))
+                        return unresolved();
+                    plan = merge(plan, plans[0]);
+                }
+            }
+            // These applicators need matching/evaluation rules we do not implement.
+            // Public-only schemas are harmless; sensitivity or an unresolved reference fails closed.
+            for (const keyword of [
+                "additionalProperties",
+                "unevaluatedProperties",
+                "unevaluatedItems",
+                "contains",
+                "not",
+                "if",
+                "then",
+                "else",
+            ])
+                if (schema[keyword] !== undefined && sensitive(child(schema[keyword])))
+                    return unresolved();
+            for (const keyword of ["patternProperties", "dependentSchemas", "dependencies"]) {
+                if (schema[keyword] === undefined)
+                    continue;
+                if (!object(schema[keyword]))
+                    return unresolved();
+                for (const value of Object.values(schema[keyword])) {
+                    if (keyword === "dependencies" && Array.isArray(value))
+                        continue;
+                    if (sensitive(child(value)))
+                        return unresolved();
+                }
+            }
+            return plan;
+        }
+        finally {
+            active.delete(schema);
+        }
+    }
+    return walk(root, 0);
+}
+/** Omit whole array values when private elements cannot be removed without shifting indices. */
+function apply(value, plan, mark, depth = 0) {
+    if (!sensitive(plan))
+        return value;
+    if (depth > MAX_DEPTH)
+        throw new Error("Argument redaction depth exceeded");
+    if (plan.omit) {
+        mark(value);
+        return OMITTED;
+    }
+    if (Array.isArray(value)) {
+        const values = value.map((entry, index) => apply(entry, item(plan, index), mark, depth + 1));
+        return values.includes(OMITTED) ? OMITTED : values;
+    }
+    if (!object(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).flatMap(([name, entry]) => {
+        const field = Object.hasOwn(plan.properties ?? {}, name) ? plan.properties[name] : PUBLIC;
+        const filtered = apply(entry, field, mark, depth + 1);
+        return filtered === OMITTED ? [] : [[name, filtered]];
+    }));
+}
+/** Output redaction protects the union of private fields across alternatives.
+ * Other sensitivity rules and unresolved-schema handling follow echo redaction. */
+export function visitPrivateCallArguments(args, schema, visit) {
+    // Public-only schemas need no sensitivity compilation, regardless of size.
+    // Iterative traversal visits each object once, including definitions and cycles.
+    const pending = [schema];
+    const seen = new Set();
+    let privateSchema = false;
+    while (pending.length) {
+        const value = pending.pop();
+        if (value === null || typeof value !== "object" || seen.has(value))
+            continue;
+        seen.add(value);
+        if (Object.hasOwn(value, "writeOnly") && value["writeOnly"] === true) {
+            privateSchema = true;
+            break;
+        }
+        for (const entry of Object.values(value))
+            pending.push(entry);
+    }
+    if (!privateSchema)
+        return;
+    try {
+        apply(args, compile(schema, true), visit);
+    }
+    catch {
+        // When a private annotation exists but its location cannot be resolved,
+        // treat every submitted value as private, just as the echo is withheld.
+        visit(args);
+    }
+}
+/** Internal schema filter; the single echo helper owns snapshotting and byte budgeting. */
+export function redactCallArguments(args, schema) {
+    try {
+        const plan = compile(schema);
+        let redacted = false;
+        const value = apply(args, plan, () => {
+            redacted = true;
+        });
+        return { ...(value !== OMITTED ? { value } : {}), redacted };
+    }
+    catch {
+        return { redacted: true };
+    }
+}

package/dist/auth-elicitation.js

@@ -1,3 +1,4 @@
+import { enableAuthorizationHandoffs } from "./authorization-handoff.js";
 import { createRequestStateCodec, inputRequired, ProtocolError, INVALID_PARAMS, PROTOCOL_VERSION_META_KEY, CLIENT_CAPABILITIES_META_KEY, } from "@modelcontextprotocol/server";
 import { Effect } from "effect";
 import { runEdge, withDeadlineEffect } from "./runtime/run.js";
@@ -183,6 +184,14 @@ export class AuthElicitation {
                 return { structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };
             }
         }
+        const envelope = context.mcpReq.envelope;
+        const capabilities = envelope?.[CLIENT_CAPABILITIES_META_KEY];
+        const elicitation = object(capabilities) ? capabilities.elicitation : undefined;
+        const capable = envelope?.[PROTOCOL_VERSION_META_KEY] === "2026-07-28" &&
+            object(elicitation) &&
+            Object.hasOwn(elicitation, "url") &&
+            object(elicitation.url);
+        enableAuthorizationHandoffs(this.options.requestScope, !capable);
         let result = await operation();
         const relayed = await this.downstream.finish(tool, args, context, result, previous);
         if (relayed !== result)
@@ -221,21 +230,17 @@ export class AuthElicitation {
             unavailable ||
             !canManage(id))
             return result;
-        const envelope = context.mcpReq.envelope;
-        const capabilities = envelope?.[CLIENT_CAPABILITIES_META_KEY];
-        const elicitation = object(capabilities) ? capabilities.elicitation : undefined;
-        const capable = envelope?.[PROTOCOL_VERSION_META_KEY] === "2026-07-28" &&
-            object(elicitation) &&
-            Object.hasOwn(elicitation, "url") &&
-            object(elicitation.url);
-        if (blocked || !capable || !vault?.requestStateKey || !vault.seal || !vault.open) {
+        // Incapable hosts already received the shared explicit-authorization handoff.
+        if (!capable)
+            return result;
+        if (blocked || !vault?.requestStateKey || !vault.seal || !vault.open) {
             if (!authFailure)
                 return result;
             const structuredContent = {
                 ...result.structuredContent,
                 error: {
                     ...result.structuredContent?.error,
-                    authorizationUrl: (await this.options.connectLink(id)).url,
+                    authorizationUrl: error.authorizationUrl ?? (await this.options.connectLink(id)).url,
                 },
             };
             return { ...result, structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };

package/dist/authorization-handoff.js

@@ -0,0 +1,111 @@
+import { boundedEchoText } from "./errors.js";
+function oauthFollowUp(connectorId) {
+    return `Then retry the original call; connecta.search({ connector: ${JSON.stringify(connectorId)} }) inside execute_code confirms the catalog now loads.`;
+}
+/** Shared with explicit authorization; errors never request a forced restart. */
+export async function authorizationHandoff(registry, baseUrl, requestScope, opts, args) {
+    const connector = registry.getConnector(args.connector);
+    if (!connector) {
+        throw new Error(`Unknown connector "${boundedEchoText(args.connector)}"`);
+    }
+    if (!connector.startAuth) {
+        if (!connector.credential) {
+            return {
+                connector: connector.id,
+                recovery: "unavailable",
+                message: `Connector "${connector.id}" declares neither downstream OAuth ` +
+                    "nor an operator-managed credential slot. Update the connector " +
+                    "or deployment configuration before retrying.",
+            };
+        }
+        const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
+        if (!ctx.credential || !opts.credentialHandoffUrl) {
+            return {
+                connector: connector.id,
+                recovery: "unavailable",
+                message: "Credential recovery needs both a vault and the optional UI. Configure " +
+                    "vault and ui in deployment code, then call " +
+                    "authorize_connector again.",
+            };
+        }
+        const fields = connector.credential.fields?.map((field) => ({
+            name: field.name,
+            guidance: field.description ?? field.label,
+        })) ?? [
+            {
+                name: "value",
+                guidance: connector.credential.description ?? connector.credential.label,
+            },
+        ];
+        return {
+            connector: connector.id,
+            recovery: "operator_config",
+            credential: {
+                label: connector.credential.label,
+                fields,
+            },
+            operatorUrl: opts.credentialHandoffUrl,
+            instructions: "Have the operator open operatorUrl, set and test the credential, " +
+                "then retry the original call. No redeploy is needed. " +
+                (connector.authScope === "personal"
+                    ? "Credential mutation requires the signed-in principal who owns this connection."
+                    : "Shared credential mutation requires a signed-in human with access to this connector."),
+        };
+    }
+    if (opts.oauthConnectUnavailable || !opts.oauthConnectUrl)
+        return {
+            connector: connector.id,
+            recovery: "unavailable",
+            message: opts.oauthConnectUnavailable ??
+                "OAuth connection requires an interactive provider and a credential vault with a handoff signing key.",
+        };
+    if (!opts.canManageAuth?.(connector.id))
+        return {
+            connector: connector.id,
+            recovery: "unavailable",
+            message: "Your identity is not permitted to manage authentication for this connection.",
+        };
+    return {
+        connector: connector.id,
+        recovery: "oauth",
+        status: "auth_required",
+        authorizationUrl: await opts.oauthConnectUrl(connector.id, args.force),
+        instructions: "Copy authorizationUrl exactly as returned; do not decode or re-encode it. Open it in a browser and sign in as the user who requested this connection. Connecta verifies your identity and permission before starting consent. " +
+            oauthFollowUp(connector.id),
+    };
+}
+const requests = new WeakMap();
+/** Retain the admitted route's factory when program utilities share its scope. */
+export function bindAuthorizationHandoffs(scope, create) {
+    if (!requests.has(scope))
+        requests.set(scope, { create, enabled: true, handoffs: new Map() });
+}
+export function enableAuthorizationHandoffs(scope, enabled) {
+    const request = requests.get(scope);
+    if (request)
+        request.enabled = enabled;
+}
+/** One promise per connector also bounds concurrent errors in a program. */
+export async function withAuthorizationHandoff(scope, error) {
+    const request = requests.get(scope);
+    if (!request?.enabled ||
+        !error.nextAction ||
+        !("tool" in error.nextAction) ||
+        error.nextAction.tool !== "authorize_connector")
+        return error;
+    const connector = error.nextAction.arguments.connector;
+    let handoff = request.handoffs.get(connector);
+    if (!handoff) {
+        handoff = request.create(connector);
+        request.handoffs.set(connector, handoff);
+    }
+    try {
+        const value = await handoff;
+        return { ...error, ...value, message: error.message, ...(value.message ? { instructions: value.message } : {}) };
+    }
+    catch {
+        // A signing/configuration failure cannot replace the original call failure
+        // or leak an arbitrary vault exception into the recovery envelope.
+        return error;
+    }
+}

package/dist/call-recovery.js

@@ -0,0 +1,25 @@
+const MAX_FACTS = 4;
+const MAX_TEXT = 128;
+const NAME = /^[A-Za-z][A-Za-z0-9]*$/;
+const facts = new WeakMap();
+/**
+ * Record facts that let the caller reconcile or safely retry this call's
+ * write. Bounded: at most four string facts with short camelCase names; a fact
+ * outside the bound is dropped rather than truncated.
+ */
+export function recordRecovery(ctx, recovery) {
+    const kept = { ...facts.get(ctx) };
+    for (const [name, value] of Object.entries(recovery)) {
+        if (Object.keys(kept).length >= MAX_FACTS && !Object.hasOwn(kept, name))
+            break;
+        if (!NAME.test(name) || name.length > 32 || typeof value !== "string" || value.length > MAX_TEXT)
+            continue;
+        kept[name] = value;
+    }
+    facts.set(ctx, Object.freeze(kept));
+}
+/** The facts a connector recorded on this call's context, if any. */
+export function recoveryFor(ctx) {
+    const recorded = ctx ? facts.get(ctx) : undefined;
+    return recorded && Object.keys(recorded).length > 0 ? recorded : undefined;
+}

package/dist/catalog-cache.js

@@ -203,7 +203,7 @@ export function catalogIntake(ctx, result) {
     }));
     if (tools.length > MAX_CATALOG_TOOLS)
         throw catalogCeiling();
-    const clean = sentSecretsForRequest(ctx.requestScope ?? ctx).redact({ ...result, tools });
+    const clean = sentSecretsForRequest(ctx.requestScope ?? ctx).redactCredentials({ ...result, tools });
     if (new TextEncoder().encode(JSON.stringify(clean)).byteLength > MAX_SERIALIZED_CATALOG_BYTES)
         throw catalogCeiling();
     for (const tool of clean.tools)
@@ -447,7 +447,7 @@ export async function catalogClientOptions(ctx, connectorId, config, authPartiti
         const items = catalogItems(method, body).map(({ _meta: _ignored, ...item }) => item);
         if (items.length > MAX_CATALOG_TOOLS)
             throw catalogCeiling();
-        const clean = sentSecretsForRequest(ctx.requestScope ?? ctx).redact({ ...body, [field]: items });
+        const clean = sentSecretsForRequest(ctx.requestScope ?? ctx).redactCredentials({ ...body, [field]: items });
         if (new TextEncoder().encode(JSON.stringify(clean)).byteLength > MAX_SERIALIZED_CATALOG_BYTES)
             throw catalogCeiling();
         return {

package/dist/catalog-service.js

@@ -1,3 +1,4 @@
+import { withAuthorizationHandoff } from "./authorization-handoff.js";
 import { carryCatalogFreshness, catalogIsFresh } from "./catalog-freshness.js";
 import { hasControlCharacters } from "./tool-name.js";
 import { Effect, Result } from "effect";
@@ -228,6 +229,45 @@ const catalogFailureProperties = {
     message: { type: "string" },
     retryable: { type: "boolean" },
     retryAfterMs: { type: "integer", minimum: 0 },
+    connector: { type: "string" },
+    recovery: { enum: ["oauth", "operator_config", "unavailable"] },
+    status: { const: "auth_required" },
+    authorizationUrl: { type: "string" },
+    operatorUrl: { type: "string" },
+    instructions: { type: "string" },
+    credential: {
+        type: "object",
+        required: ["label", "fields"],
+        additionalProperties: false,
+        properties: {
+            label: { type: "string" },
+            fields: {
+                type: "array",
+                items: {
+                    type: "object",
+                    required: ["name"],
+                    additionalProperties: false,
+                    properties: { name: { type: "string" }, guidance: { type: "string" } },
+                },
+            },
+        },
+    },
+    retry: { type: "string" },
+    nextAction: {
+        type: "object",
+        required: ["tool", "arguments", "operatorHandoff"],
+        additionalProperties: false,
+        properties: {
+            tool: { const: "authorize_connector" },
+            arguments: {
+                type: "object",
+                required: ["connector"],
+                additionalProperties: false,
+                properties: { connector: { type: "string" } },
+            },
+            operatorHandoff: { type: "string" },
+        },
+    },
 };
 /**
  * The outputSchema contract for either search adapter. Guest API registration
@@ -245,25 +285,7 @@ export const CATALOG_SEARCH_RESULT_SCHEMA = {
                 required: ["connector", "code", "message", "retryable"],
                 additionalProperties: false,
                 properties: {
-                    connector: { type: "string" },
                     ...catalogFailureProperties,
-                    recovery: { enum: ["oauth", "operator_config", "unavailable"] },
-                    retry: { type: "string" },
-                    nextAction: {
-                        type: "object",
-                        required: ["tool", "arguments", "operatorHandoff"],
-                        additionalProperties: false,
-                        properties: {
-                            tool: { const: "authorize_connector" },
-                            arguments: {
-                                type: "object",
-                                required: ["connector"],
-                                additionalProperties: false,
-                                properties: { connector: { type: "string" } },
-                            },
-                            operatorHandoff: { type: "string" },
-                        },
-                    },
                 },
             },
         },
@@ -517,6 +539,44 @@ export class CatalogService {
             });
         });
     }
+    async catalogFailure(connector, failure) {
+        const classified = classifyCallError(failure, "catalog_lookup_failed");
+        const error = {
+            connector: connector.id,
+            code: classified.code,
+            // Catalog discovery reports recovery facts, never connector-authored
+            // error text. Clipping a downstream message does not make it safe.
+            message: classified.code === "downstream_oauth_required"
+                ? `Connector "${connector.id}" requires downstream OAuth authorization. When an auth error includes a handoff, give it to the user or operator.`
+                : classified.code === "auth_required"
+                    ? `Connector "${connector.id}" requires operator-managed credentials or configuration. When an auth error includes a handoff, give it to the user or operator.`
+                    : classified.code === "provider_permission_denied"
+                        ? `Connector "${connector.id}" requires permission from the provider's resource owner or administrator. Reconnecting alone will not grant access.`
+                        : `Connector "${connector.id}" catalog lookup failed (${classified.code}).`,
+            retryable: classified.retryable,
+            ...(classified.retryAfterMs === undefined ? {} : { retryAfterMs: classified.retryAfterMs }),
+        };
+        if (error.code === "auth_required" || error.code === "downstream_oauth_required") {
+            error.recovery = connector.startAuth
+                ? "oauth"
+                : this.registry.credentialUiAvailable() &&
+                    connector.credential &&
+                    this.registry.contextFor(connector.id, this.baseUrl, this.requestScope).credential
+                    ? "operator_config"
+                    : "unavailable";
+            error.nextAction = {
+                tool: "authorize_connector",
+                arguments: { connector: connector.id },
+                operatorHandoff: "Give the URL and instructions it returns to the operator.",
+            };
+            error.retry = `Retry discovery after the operator completes recovery for "${connector.id}".`;
+        }
+        else if (error.code === "provider_permission_denied") {
+            error.retry =
+                "Ask the provider's resource owner or administrator to grant the required permission or scope, then retry. Reconnecting alone will not grant access.";
+        }
+        return withAuthorizationHandoff(this.requestScope, error);
+    }
     async search(args) {
         if (args.query !== undefined && typeof args.query !== "string") {
             throw new DiscoveryPolicyError("invalid_args", "query must be a string. Omit it or use an empty string to browse the catalog.");
@@ -737,59 +797,25 @@ export class CatalogService {
             }
         }
         const unavailableCatalogs = catalogs.filter(Result.isFailure).length;
-        const catalogErrors = catalogs.flatMap((catalog, index) => {
+        const catalogErrors = (await Promise.all(catalogs.map(async (catalog, index) => {
             if (Result.isSuccess(catalog))
                 return [];
-            const connector = connectors[index];
-            const classified = classifyCallError(catalog.failure, "catalog_lookup_failed");
-            const error = {
-                connector: connector.id,
-                code: classified.code,
-                // Catalog discovery reports recovery facts, never connector-authored
-                // error text. Clipping a downstream message does not make it safe.
-                message: classified.code === "downstream_oauth_required"
-                    ? `Connector "${connector.id}" requires downstream OAuth authorization. Call authorize_connector and give its handoff to the operator.`
-                    : classified.code === "auth_required"
-                        ? `Connector "${connector.id}" requires operator-managed credentials or configuration. Call authorize_connector and give its handoff to the operator.`
-                        : classified.code === "provider_permission_denied"
-                            ? `Connector "${connector.id}" requires permission from the provider's resource owner or administrator. Reconnecting alone will not grant access.`
-                            : `Connector "${connector.id}" catalog lookup failed (${classified.code}).`,
-                retryable: classified.retryable,
-                ...(classified.retryAfterMs === undefined ? {} : { retryAfterMs: classified.retryAfterMs }),
-            };
-            if (error.code === "auth_required" || error.code === "downstream_oauth_required") {
-                error.recovery = connector.startAuth
-                    ? "oauth"
-                    : this.registry.credentialUiAvailable() &&
-                        connector.credential &&
-                        this.registry.contextFor(connector.id, this.baseUrl, this.requestScope).credential
-                        ? "operator_config"
-                        : "unavailable";
-                error.nextAction = {
-                    tool: "authorize_connector",
-                    arguments: { connector: connector.id },
-                    operatorHandoff: "Give the URL and instructions it returns to the operator.",
-                };
-                error.retry = `Retry discovery after the operator completes recovery for "${connector.id}".`;
-            }
-            else if (error.code === "provider_permission_denied") {
-                error.retry =
-                    "Ask the provider's resource owner or administrator to grant the required permission or scope, then retry. Reconnecting alone will not grant access.";
-            }
-            return [error];
-        });
+            return [await this.catalogFailure(connectors[index], catalog.failure)];
+        }))).flat();
         const needsAuth = (error) => error.code === "auth_required" ||
             error.code === "downstream_oauth_required" ||
             error.code === "provider_permission_denied";
         catalogErrors.sort((a, b) => Number(needsAuth(b)) - Number(needsAuth(a)));
         const scopedFailure = args.connector ? catalogErrors[0] : undefined;
         const scopedCatalogError = scopedFailure
-            ? {
-                code: scopedFailure.code,
-                message: scopedFailure.message,
-                retryable: scopedFailure.retryable,
-                ...(scopedFailure.retryAfterMs === undefined ? {} : { retryAfterMs: scopedFailure.retryAfterMs }),
-            }
+            ? scopedFailure.code === "auth_required" || scopedFailure.code === "downstream_oauth_required"
+                ? scopedFailure
+                : {
+                    code: scopedFailure.code,
+                    message: scopedFailure.message,
+                    retryable: scopedFailure.retryable,
+                    ...(scopedFailure.retryAfterMs === undefined ? {} : { retryAfterMs: scopedFailure.retryAfterMs }),
+                }
             : undefined;
         const safetyLabel = safety === "readOnly" ? "read-only " : safety === "approvalRequired" ? "approval-required " : "";
         const filterRecovery = safety === "all" ? "" : " Change safety to inspect the other tools.";
@@ -940,6 +966,17 @@ export class CatalogService {
         ];
         const loaded = await runEdge(this.discoveryCatalogs(connectorIds, "connecta.describe"));
         const catalogs = new Map(connectorIds.map((id, index) => [id, loaded[index]]));
+        const authFailures = new Map(await Promise.all(connectorIds.map(async (id) => {
+            const catalog = catalogs.get(id);
+            if (!catalog || !Result.isFailure(catalog))
+                return [id, undefined];
+            const classified = classifyCallError(catalog.failure, "catalog_lookup_failed");
+            const connector = this.registry.getConnector(id);
+            const error = classified.code === "auth_required" || classified.code === "downstream_oauth_required"
+                ? await this.catalogFailure(connector, catalog.failure)
+                : undefined;
+            return [id, error];
+        })));
         return resolved.map(({ address, resolved: addressResolution }) => {
             if (!addressResolution) {
                 const message = `Unknown address "${boundedEchoText(address)}"`;
@@ -955,6 +992,9 @@ export class CatalogService {
             }
             const catalog = catalogs.get(addressResolution.connector.id);
             if (catalog && Result.isFailure(catalog)) {
+                const authFailure = authFailures.get(addressResolution.connector.id);
+                if (authFailure)
+                    return { address: boundedEchoText(address), error: authFailure.message, errorDetails: authFailure };
                 const classified = classifyCallError(catalog.failure, "catalog_lookup_failed");
                 const message = boundedEchoText(classified.message);
                 return {