@zackbart/connecta 0.29.0 → 0.30.0

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/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 {

package/dist/config.d.ts

@@ -252,6 +252,8 @@ declare const connectaConfig: {
      * `@zackbart/connecta/d1` on Workers, `sqliteStorage(path)` from
      * `@zackbart/connecta/sqlite` on Node. Defaults to memoryStorage(), which
      * forgets everything on restart.
+     * Custom adapters must declare `capabilities.absoluteExpiry: true` and honor
+     * `expiresAtMs` on set and compareAndSet; older adapters fail construction.
      */
     storage: import("./config-schema.js").Field<KVStorage, KVStorage, true>;
     /**

package/dist/config.js

@@ -291,6 +291,8 @@ const connectaConfig = {
      * `@zackbart/connecta/d1` on Workers, `sqliteStorage(path)` from
      * `@zackbart/connecta/sqlite` on Node. Defaults to memoryStorage(), which
      * forgets everything on restart.
+     * Custom adapters must declare `capabilities.absoluteExpiry: true` and honor
+     * `expiresAtMs` on set and compareAndSet; older adapters fail construction.
      */
     storage: opaque({
         // Every subsystem relies on the atomic claim and enumeration, so storage
@@ -299,13 +301,16 @@ const connectaConfig = {
         // adapter, which could never offer either guarantee.
         check: (value, path) => {
             const missing = STORAGE_METHODS.filter((method) => !hasMethods(value, [method]));
-            if (missing.length === 0)
-                return;
-            throw new ConfigError(`${path} must implement ${missing.join(" and ")}. ` +
-                "Use d1Storage(env.CONNECTA_DB) from @zackbart/connecta/d1 on Workers, " +
-                "sqliteStorage(path) from @zackbart/connecta/sqlite on Node, or " +
-                "memoryStorage() in tests. Workers KV is not supported: it is eventually " +
-                "consistent and cannot compare-and-set.");
+            if (missing.length > 0)
+                throw new ConfigError(`${path} must implement ${missing.join(" and ")}. ` +
+                    "Use d1Storage(env.CONNECTA_DB) from @zackbart/connecta/d1 on Workers, " +
+                    "sqliteStorage(path) from @zackbart/connecta/sqlite on Node, or " +
+                    "memoryStorage() in tests. Workers KV is not supported: it is eventually " +
+                    "consistent and cannot compare-and-set.");
+            if (!isObject(value) || !isObject(value.capabilities) || value.capabilities.absoluteExpiry !== true) {
+                throw new ConfigError(`${path} must declare capabilities.absoluteExpiry: true and honor expiresAtMs on set and compareAndSet. ` +
+                    "Upgrade the storage adapter before declaring this capability.");
+            }
         },
         resolve: (value) => value ?? memoryStorage(),
     }),

package/dist/connectors/guarded-fetch.js

@@ -70,17 +70,17 @@ function confinementBase(provider, baseUrl) {
         base = new URL(baseUrl);
     }
     catch {
-        throw new Error(`${provider} baseUrl must be an absolute URL: ${baseUrl}`);
+        throw new Error(`${provider} baseUrl must be an absolute URL.`);
     }
     const loopback = base.hostname === "localhost" || base.hostname === "127.0.0.1" || base.hostname === "[::1]";
     if (base.protocol !== "https:" && !(base.protocol === "http:" && loopback)) {
-        throw new Error(`${provider} baseUrl must be https (http is allowed only for a loopback proxy or test double): ${baseUrl}`);
+        throw new Error(`${provider} baseUrl must be https (http is allowed only for a loopback proxy or test double).`);
     }
     if (base.username || base.password) {
         throw new Error(`${provider} baseUrl must not embed URL credentials; authentication belongs in headers.`);
     }
     if (base.search || base.hash) {
-        throw new Error(`${provider} baseUrl must not carry a query or fragment: ${baseUrl}`);
+        throw new Error(`${provider} baseUrl must not carry a query or fragment.`);
     }
     return base;
 }

package/dist/connectors/negotiation-cache.js

@@ -31,7 +31,7 @@ export async function storeNegotiation(ctx, digest, prior) {
         return;
     assertDownstreamOutputSafe(ctx.requestScope ?? ctx, prior);
     // DiscoverResult instructions, metadata and capability keys can echo auth.
-    const clean = sentSecretsForRequest(ctx.requestScope ?? ctx).redact(prior);
+    const clean = sentSecretsForRequest(ctx.requestScope ?? ctx).redactCredentials(prior);
     if (clean.kind === "modern" && !isSpecType.DiscoverResult(clean.discover))
         return;
     try {

package/dist/downstream-input-context.js

@@ -18,6 +18,15 @@ export function bindDownstreamContinuation(scope, target) {
 export function clearDownstreamContinuation(scope) {
     continuations.delete(scope);
 }
+/** The invocation's schema-filtered snapshot, never raw continuation arguments. */
+export function recordDownstreamArgumentEcho(scope, echo) {
+    const continuation = continuations.get(scope);
+    if (continuation)
+        continuation.argumentEcho = echo;
+}
+export function downstreamArgumentEcho(scope) {
+    return continuations.get(scope)?.argumentEcho ?? {};
+}
 export function downstreamWriteContinuation(scope) {
     return continuations.get(scope)?.write === true;
 }

package/dist/downstream-input.js

@@ -1,9 +1,9 @@
 import { inputRequired, specTypeSchemas, ProtocolError, INVALID_PARAMS, CLIENT_CAPABILITIES_META_KEY, PROTOCOL_VERSION_META_KEY, } from "@modelcontextprotocol/server";
-import { ConnectorCallError, echoedCallArgs } from "./errors.js";
-import { redactAgentOutput, sentSecretsForRequest } from "./sent-secrets.js";
+import { ConnectorCallError } from "./errors.js";
+import { sentSecretsForRequest } from "./sent-secrets.js";
 import { inputRetryKeys } from "./storage/keys.js";
 import { REQUEST_STATE_TTL_MS, MAX_INPUT_ROUNDS, invalidRequestState, requestDigest, stateObject, } from "./request-state.js";
-import { bindDownstreamCapabilities, downstreamInputCapabilities, bindDownstreamContinuation, clearDownstreamContinuation, assertNoPrivateStateEchoes, assertDownstreamOutputSafe, } from "./downstream-input-context.js";
+import { bindDownstreamCapabilities, downstreamInputCapabilities, bindDownstreamContinuation, clearDownstreamContinuation, downstreamArgumentEcho, assertNoPrivateStateEchoes, assertDownstreamOutputSafe, } from "./downstream-input-context.js";
 const MAX_PAYLOAD_BYTES = 64 * 1024;
 export const MAX_RELAY_STATE_CHARS = 128 * 1024;
 const MAX_REQUESTS = 16;
@@ -67,7 +67,7 @@ export async function captureDownstreamInput(scope, connector, address, raw, sec
                     url.password ||
                     [...params.url].some((char) => char.charCodeAt(0) <= 0x20 || char.charCodeAt(0) === 0x7f) ||
                     secrets.containsUrl(params.url) ||
-                    redactAgentOutput(secrets, params.url) !== params.url)
+                    secrets.redact(params.url) !== params.url)
                     return invalidInput();
             }
             catch {
@@ -84,7 +84,7 @@ export async function captureDownstreamInput(scope, connector, address, raw, sec
                 return invalidInput();
             // A schema controls the accepted answer. Refuse redaction changes rather
             // than asking the host to submit different field names or enum values.
-            if (redactAgentOutput(secrets, parsed.value.requestedSchema) !== parsed.value.requestedSchema)
+            if (secrets.redact(parsed.value.requestedSchema) !== parsed.value.requestedSchema)
                 return invalidInput();
             inputRequests[namespace(connector, index)] = inputRequired.elicit({
                 message: `Downstream ${connector}: ${parsed.value.message}`,
@@ -237,7 +237,7 @@ export class DownstreamElicitation {
                 return result;
             // The nonce is spent even when the downstream failure would normally
             // allow a retry. Preserve write reconciliation and auth prerequisites.
-            const echoed = echoedCallArgs(args.args);
+            const echoed = downstreamArgumentEcho(this.options.requestScope);
             const structuredContent = {
                 ...result.structuredContent,
                 error: {
@@ -249,9 +249,11 @@ export class DownstreamElicitation {
                                 tool: state.tool,
                                 arguments: { address: state.address, ...echoed },
                                 purpose: "Re-issue the original direct call without requestState or inputResponses to start a fresh input round. Do not resend this continuation." +
-                                    (args.args !== undefined && !("args" in echoed)
-                                        ? " Use the exact arguments you sent; they exceed the echo budget."
-                                        : ""),
+                                    (echoed.argsRedacted
+                                        ? " Re-send the original arguments; sensitive fields are omitted."
+                                        : args.args !== undefined && !("args" in echoed)
+                                            ? " Use the exact arguments you sent; they could not be echoed safely."
+                                            : ""),
                             },
                         }
                         : {}),
@@ -314,8 +316,8 @@ export class DownstreamElicitation {
         if (requestState.length > MAX_RELAY_STATE_CHARS)
             return failure("input_required_limit", "The sealed downstream state exceeds 128 KiB.");
         // Opaque echoes and mutable schemas/URLs were refused during capture.
-        // Prompt messages take the same #736 agent boundary as ordinary outputs.
-        return redactAgentOutput(sentSecretsForRequest(scope), inputRequired({
+        // Downstream prompt messages are prose under the payload rules.
+        return sentSecretsForRequest(scope).redact(inputRequired({
             ...(Object.keys(pending.inputRequests).length ? { inputRequests: pending.inputRequests } : {}),
             requestState,
         }));

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
 import type { ExecutorAdmissionErrorCode } from "./executor-admission.js";
+import type { JsonSchema } from "./types.js";
 /**
  * Machine-readable classification of a failed connector tool call.
  *
@@ -77,14 +78,14 @@ export declare const MAX_ARGUMENT_VALIDATION_ISSUES = 3;
  */
 export declare function boundedEchoText(value: string, maxBytes?: number): string;
 /**
- * `{ args }` when the caller's arguments fit the shared echo budget,
- * `{}` when they do not. All or nothing: a clipped echo would be a *different*
- * call than the one that was refused, and the routes this feeds end at a human
- * approving one. Unserializable arguments are treated the same way as oversized
- * ones — there is nothing honest to put in the field.
+ * Snapshot the caller's arguments after bounded schema-aware writeOnly omission,
+ * then apply the shared byte budget without clipping. Unresolved sensitivity
+ * omits the entire echo. argsRedacted marks partial or withheld arguments as
+ * reconciliation context; any retry must use the caller's original arguments.
  */
-export declare function echoedCallArgs(args: unknown): {
+export declare function echoedCallArgs(args: unknown, schema?: JsonSchema): {
     args?: unknown;
+    argsRedacted?: true;
 };
 /** Optional transport diagnostics; never a URL path or raw runtime message. */
 interface UnavailableDetails {
@@ -182,8 +183,25 @@ export declare class ConnectorCallError extends Error {
         current?: Readonly<Record<string, number>>;
     });
 }
+/** Secret-free payload returned by authorize_connector and auth failures. */
+export interface AuthorizationHandoff {
+    connector: string;
+    recovery: AuthRecoveryMode;
+    message?: string;
+    status?: "auth_required";
+    authorizationUrl?: string;
+    operatorUrl?: string;
+    instructions?: string;
+    credential?: {
+        label: string;
+        fields: {
+            name: string;
+            guidance?: string;
+        }[];
+    };
+}
 /** The `error` object surfaced in value-mode call results and rejected promises. */
-export interface CallErrorDetails {
+export interface CallErrorDetails extends Partial<AuthorizationHandoff> {
     /** Sanitized transport diagnostics, absent when the runtime supplies none. */
     details?: UnavailableDetails;
     code: string;
@@ -224,12 +242,13 @@ export interface CallErrorDetails {
         arguments: {
             address: string;
             /**
-             * The caller's own arguments, echoed only when they fit
-             * the shared echo budget — and then whole, never clipped. Absent
-             * means "re-send exactly what you sent": a half-copied argument object
-             * routed into a human approval prompt would describe a call nobody made.
+             * A schema-filtered snapshot within the shared byte budget, never
+             * clipped. With argsRedacted, this is partial reconciliation context.
+             * If absent or redacted, retry only with the original arguments.
              */
             args?: unknown;
+            /** Sensitive fields were omitted, or sensitivity could not be resolved. */
+            argsRedacted?: true;
         };
         purpose: string;
     } | {
@@ -253,11 +272,16 @@ export interface CallErrorDetails {
     };
     /** Configured connectors in this request's registry view only. */
     configuredConnectors?: string[];
-    /** Agent-only uncertain write, never copied to an operator record. */
+    /**
+     * Agent-only uncertain write, never copied to an operator record. argsRedacted
+     * marks partial or withheld schema-filtered arguments; argsOmitted means args
+     * is absent. Reconciliation and any explicit retry require the original input.
+     */
     uncertainCall?: {
         address: string;
         args?: unknown;
         argsOmitted?: true;
+        argsRedacted?: true;
     };
     /** Explicit retry guidance; recovery never retries or mutates by itself. */
     retry?: string;