@zackbart/connecta 0.40.0 → 0.42.0

package/dist/auth/downstream-oauth.js

@@ -6,7 +6,7 @@ import { SentSecrets } from "../sent-secrets.js";
 import { authenticateRemoteClient, downstreamClientMetadata, remoteClientAuthMethod, } from "./downstream-client-metadata.js";
 import { authMethods } from "./native.js";
 import { OAUTH_REFRESH_SKEW_MS } from "./oauth-grant.js";
-import { consentMethods } from "./downstream-oauth/consent.js";
+import { consentMethods, withoutUrlSecrets } from "./downstream-oauth/consent.js";
 import { ACTIVE_EPOCH_PREFIX, GRANT, grantStoreMethods, isDisconnectedEpoch, } from "./downstream-oauth/grant-store.js";
 import { aborted, tokenResponse, } from "./downstream-oauth/refresh-coordinator.js";
 import { refreshRecordMethods } from "./downstream-oauth/refresh-records.js";
@@ -32,8 +32,7 @@ export function authorizingContext(ctx) {
     return deriveContext(ctx, { allowAuthorization: true });
 }
 /** A local destination guard proved that no OAuth HTTP request left. */
-export class OAuthRequestNotSentError extends ConnectorCallError {
-}
+export { OAuthRequestNotSentError } from "./oauth-request-not-sent.js";
 /**
  * OAuthClientProvider over one owner's grant record and its consents' flow
  * records, in one connector's namespace.
@@ -106,6 +105,8 @@ export class KvOAuthProvider {
      * only: no credential beyond the access token it already handed out.
      */
     observed;
+    /** The same grant's tokens, which a catalog's identity digests. Memory only, like the grant they came from. */
+    observedTokens;
     constructor(connectorId, storage, redirectUri, refreshCoordinator, allowAuthorization = true, 
     /** Present when the deployment's vault can seal; the grant is then ciphertext. */
     sealer, 
@@ -154,9 +155,11 @@ export class KvOAuthProvider {
     }
     observe(grant) {
         const { tokens, expiresAt } = grant.body;
+        this.observedTokens = tokens;
         this.observed = tokens
             ? {
                 epoch: grant.epoch,
+                revision: grant.tokenRevision ?? 0,
                 accessToken: tokens.access_token,
                 refreshable: typeof tokens.refresh_token === "string" && tokens.refresh_token !== "",
                 ...(expiresAt !== undefined ? { expiresAt } : {}),
@@ -195,7 +198,7 @@ export class KvOAuthProvider {
         if (!this.callback ||
             (issuer === null
                 ? this.callback.flow.binding?.issRequired === true
-                : issuer !== this.callback.flow.binding?.issuer)) {
+                : this.flowValue(issuer) !== this.flowValue(this.callback.flow.binding?.issuer))) {
             throw new ConnectorCallError("connector_call_failed", `Connector "${this.connectorId}" authorization callback issuer does not match its consent; nothing was exchanged.`);
         }
     }
@@ -203,6 +206,14 @@ export class KvOAuthProvider {
     flowLabel(key, epoch) {
         return `${key}:${epoch}`;
     }
+    /** The sealed record's own label, so a verifier's ciphertext cannot stand in for it. */
+    flowRecordLabel(key, epoch) {
+        return `${this.flowLabel(key, epoch)}:record`;
+    }
+    /** A binding value as this provider's flow records hold it, for comparison. */
+    flowValue(value) {
+        return this.sealer ? value : withoutUrlSecrets(value);
+    }
     isOperatorDisconnectedEpoch(epoch) {
         return isDisconnectedEpoch(epoch);
     }

package/dist/auth/oauth-request-not-sent.js

@@ -0,0 +1,4 @@
+import { ConnectorCallError } from "../errors.js";
+/** A local destination guard proved that no OAuth HTTP request left. */
+export class OAuthRequestNotSentError extends ConnectorCallError {
+}

package/dist/auth/static-oauth.js

@@ -397,25 +397,31 @@ export function staticOAuth(id, config) {
         return new StaticOAuthProvider(id, ctx, coordinatorFor(ctx), settings, requestOwned);
     };
     /**
-     * The owned credential transport, with the configured token-request
-     * headers laid over the SDK's own. With discovery and registration answered
-     * from configuration the token endpoint is the only URL the SDK fetches here;
-     * the check keeps the headers on it even if that ever changes.
+     * The token request as sent, with the configured token-request headers laid
+     * over the SDK's own, and every credential it carries registered. With
+     * discovery and registration answered from configuration the token endpoint is
+     * the only URL the SDK fetches here; the check keeps the headers on it even if
+     * that ever changes.
      */
+    const registeredTokenRequest = (secrets, input, init = {}) => {
+        const url = new URL(input);
+        const request = { ...init, redirect: "manual" };
+        if (settings.tokenRequestHeaders.length && `${url.origin}${url.pathname}` === settings.identity) {
+            const headers = new Headers(init.headers);
+            for (const [name, value] of settings.tokenRequestHeaders)
+                headers.set(name, value);
+            for (const [name, value] of settings.tokenRequestHeaders)
+                if (!PUBLIC_TOKEN_REQUEST_HEADERS.get(name.toLowerCase())?.has(value))
+                    secrets.header(value);
+            request.headers = headers;
+        }
+        trackRemoteClientRequest(secrets, input, request);
+        return request;
+    };
+    /** The owned credential transport. */
     const tokenEndpointFetch = authMethod((secrets, input, init = {}) => {
         return authFlow(function* () {
-            const url = new URL(input);
-            const request = { ...init, redirect: "manual" };
-            if (settings.tokenRequestHeaders.length && `${url.origin}${url.pathname}` === settings.identity) {
-                const headers = new Headers(init.headers);
-                for (const [name, value] of settings.tokenRequestHeaders)
-                    headers.set(name, value);
-                for (const [name, value] of settings.tokenRequestHeaders)
-                    if (!PUBLIC_TOKEN_REQUEST_HEADERS.get(name.toLowerCase())?.has(value))
-                        secrets.header(value);
-                request.headers = headers;
-            }
-            trackRemoteClientRequest(secrets, input, request);
+            const request = registeredTokenRequest(secrets, input, init);
             // The coordinator or code-exchange wrapper authorizes this send. Refresh
             // claim submission may outlive the caller; this transport uses no
             // request-owned capability and changes no closed resource-call ledger.
@@ -425,7 +431,6 @@ export function staticOAuth(id, config) {
                 provider: id,
                 method: request.method ?? "GET",
             };
-            secrets.request(input, request);
             const response = (yield authCall(sendCredentialPost, [
                 input,
                 request,
@@ -446,6 +451,7 @@ export function staticOAuth(id, config) {
     early) => {
         return authFlow(function* () {
             const secrets = sentSecretsFor(ctx);
+            const owner = viewSignal(ctx, requestOwned || exchange !== undefined);
             const coordinated = coordinatorFor(ctx).coordinatedFetch(provider, authMethod((input, init) => {
                 return authFlow(function* () {
                     if (exchange) {
@@ -478,8 +484,10 @@ export function staticOAuth(id, config) {
                     }
                     return (yield authCall(tokenEndpointFetch, [secrets, input, init]));
                 });
-            }), viewSignal(ctx, requestOwned || exchange !== undefined), ctx.defer, undefined, () => {
+            }), owner, ctx.defer, undefined, (input, init) => {
                 guardedTransport(true);
+                if (!owner.aborted)
+                    registeredTokenRequest(secrets, input, init);
             });
             return (yield authCall(auth, [
                 provider,
@@ -547,12 +555,14 @@ export function staticOAuth(id, config) {
     // A token that lives under a minute is due again at once: the invocation's
     // check renews it, and the handler sends it while it is unexpired.
     const earlyRenewed = new EarlyRenewals();
-    /**
-     * One call's grant use; submitted refresh work keeps the coordinator's owner.
-     * `renewAgain` is the invocation's check, which renews any due token,
-     * even one this request's earlier renewal produced.
-     */
     const grantFor = (ctx, requestOwned = false, renewAgain = false) => {
+        const observations = new Map();
+        const capture = (provider, token) => {
+            const seen = provider.observed;
+            if (seen?.accessToken === token)
+                observations.set(token, { epoch: seen.epoch, revision: seen.revision });
+            return token;
+        };
         let provider;
         const use = authMethod((work) => {
             return authView(ctx, authMethod((signal) => {
@@ -611,9 +621,9 @@ export function staticOAuth(id, config) {
                                     true,
                                 ]));
                                 earlyRenewed.record(scope, tokens.access_token, fresh, provider.observedExpiry(fresh));
-                                return fresh;
+                                return capture(provider, fresh);
                             }
-                            return tokens.access_token;
+                            return capture(provider, tokens.access_token);
                         });
                     }),
                 ]);
@@ -621,10 +631,21 @@ export function staticOAuth(id, config) {
             refresh: authMethod((stale) => {
                 return authCall(use, [
                     authMethod((provider, live) => {
-                        return authCall(renewedToken, [provider, live, stale, requestOwned]);
+                        return authFlow(function* () {
+                            const token = (yield authCall(renewedToken, [provider, live, stale, requestOwned]));
+                            return capture(provider, token);
+                        });
                     }),
                 ]);
             }),
+            observe: authMethod((token, outcome) => {
+                const snapshot = observations.get(token);
+                if (!snapshot)
+                    return Effect.void;
+                return authCall(use, [
+                    authMethod((provider) => authInvoke(provider, "recordTokenOutcome", [snapshot, outcome])),
+                ]).pipe(Effect.asVoid, Effect.catch(() => Effect.void));
+            }),
             rejected: authMethod(() => {
                 return authView(ctx, authMethod(() => {
                     return authValue(() => {
@@ -735,6 +756,10 @@ export function staticOAuth(id, config) {
                         const grant = grantFor(ctx, auxiliary);
                         const stale = (yield authInvoke(grant, "token", []));
                         const { response: first, dispatch } = (yield authCall(send, [stale]));
+                        if (first.status === 401 || (first.status >= 200 && first.status < 300))
+                            yield authInvoke(grant, "observe", [stale, first.status === 401 ? "refused" : "accepted"]);
+                        if (signal.aborted)
+                            throw signal.reason;
                         if (first.status !== 401)
                             return first;
                         try {
@@ -773,6 +798,10 @@ export function staticOAuth(id, config) {
                             throw signal.reason;
                         renewedAfterUnauthorized(dispatch, stale, accessToken);
                         const { response: second } = (yield authCall(send, [accessToken]));
+                        if (second.status === 401 || (second.status >= 200 && second.status < 300))
+                            yield authInvoke(grant, "observe", [accessToken, second.status === 401 ? "refused" : "accepted"]);
+                        if (signal.aborted)
+                            throw signal.reason;
                         if (second.status !== 401)
                             return second;
                         void second.body?.cancel().catch(() => { });
@@ -800,7 +829,7 @@ export function staticOAuth(id, config) {
             }), auxiliary));
         });
     });
-    const statusOf = authMethod((ctx, provider) => {
+    const statusOf = authMethod((ctx, provider, forCall = false) => {
         return authFlow(function* () {
             if (rejectedScopes.has(scopeOf(ctx))) {
                 return {
@@ -808,16 +837,18 @@ export function staticOAuth(id, config) {
                     message: "Authorization required \u2014 the downstream rejected this connector's OAuth grant.",
                 };
             }
-            // A status read never starts authorization: this provider cannot, and
-            // nothing here calls the SDK. A stored grant for the configured token
-            // endpoint is healthy until a call says otherwise — the downstream is
-            // asked nothing.
-            if ((yield authInvoke(provider, "operatorDisconnected", []))) {
+            // Peek opens the current grant without migration writes or authorization.
+            const grant = (yield authInvoke(provider, "peekGrant", []));
+            if (provider.isOperatorDisconnectedEpoch(grant.epoch))
                 return { state: "auth_required", message: disconnectedMessage };
-            }
-            return (yield authInvoke(provider, "tokens", [issuerContext]))
-                ? { state: "ok" }
-                : { state: "auth_required", message: AUTH_REQUIRED_MESSAGE };
+            if (!grant.tokens || grant.issuer !== settings.identity)
+                return { state: "auth_required", message: AUTH_REQUIRED_MESSAGE };
+            return !forCall && grant.observation?.outcome === "refused"
+                ? {
+                    state: "auth_required",
+                    message: "Authorization required — the downstream rejected this connector's OAuth grant.",
+                }
+                : { state: "ok" };
         });
     });
     const status = authMethod((ctx) => {
@@ -832,7 +863,9 @@ export function staticOAuth(id, config) {
     const prepareCall = authMethod((ctx) => {
         return authFlow(function* () {
             const provider = providerFor(ctx);
-            const state = (yield authCall(statusOf, [ctx, provider]));
+            // A persisted API refusal is diagnostic, not proof the next request will fail.
+            // Keep the request-local latch, but let a later invocation observe recovery.
+            const state = (yield authCall(statusOf, [ctx, provider, true]));
             if (state.state === "ok" && provider.renewalDue() !== undefined)
                 (yield authInvoke(grantFor(ctx, false, true), "token", []));
             return state;
@@ -849,8 +882,13 @@ export function staticOAuth(id, config) {
                 : (yield authInvoke(provider, "operatorDisconnected", []));
             if (ctx.signal?.aborted)
                 throw ctx.signal.reason;
-            if (opts?.force || disconnected) {
-                (yield authInvoke(provider, "resetAuthorization", []));
+            const observed = (yield authInvoke(provider, "peekGrant", []));
+            const refused = observed.observation?.outcome === "refused";
+            if (opts?.force || disconnected || refused || rejectedScopes.has(scopeOf(original))) {
+                const fence = !opts?.force && !disconnected && refused
+                    ? { epoch: observed.epoch, revision: observed.observation.revision }
+                    : undefined;
+                (yield authInvoke(provider, "resetAuthorization", [false, false, fence]));
                 rejectedScopes.delete(scopeOf(original));
             }
             else {

package/dist/auth-elicitation.js

@@ -3,7 +3,7 @@ import { RequestScope, requestOwner } from "./runtime/request-scope.js";
 import { upwardStep } from "./upward.js";
 import { authAwait, authCall, authInvoke, authFlow, authMethod, registerAuthMethod, authOwnMethod, } from "./auth/native.js";
 import { registryProgram } from "./runtime/registry.js";
-import { enableAuthorizationHandoffs } from "./authorization-handoff.js";
+import { authorizationHandoff, connectLinkFields, 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";
@@ -17,6 +17,23 @@ import { DownstreamElicitation, MAX_RELAY_STATE_CHARS, } from "./downstream-inpu
 import { canonicalState as canonical, requestDigest as digest, stateObject as object, invalidRequestState as invalidState, REQUEST_STATE_TTL_MS as TTL_MS, MAX_INPUT_ROUNDS as MAX_ROUNDS, } from "./request-state.js";
 const INPUT_KEY = "connecta_auth";
 const MESSAGE = "Connect this service in your browser, then retry the request.";
+// A client may answer without showing anything, and the response cannot prove
+// otherwise. Neither text claims a person saw the prompt, and neither names a
+// route: an agent told to call again would only reach the same refusal.
+const REFUSED = {
+    decline: {
+        code: "auth_declined",
+        message: "The client declined the connection prompt, possibly automatically, so the user may not have seen it. Nothing was retried.",
+    },
+    cancel: {
+        code: "auth_cancelled",
+        message: "The client cancelled the connection prompt, possibly automatically, so the user may not have seen it. Nothing was retried.",
+    },
+};
+// Only a repeat can recover a refusal whose link failed, and it asks for a new
+// prompt, so a person's refusal stays final. Nothing on the server limits it to one.
+const REFUSED_NO_LINK = " No connection link could be issued. If the user has not refused this connection, repeat this request once for a new link, then give it to them. Stop if that repeat also fails.";
+const refusedPurpose = (recipient) => `Give this link to the user, unchanged, ${recipient}once, then stop. Do not prompt again, retry, or reach this service another way until they confirm. If they already refused this connection in this conversation, only mention that the link is available.`;
 function failure(code, message) {
     return toolError({ code, message, retryable: false }, { ok: false });
 }
@@ -45,14 +62,26 @@ export class AuthElicitation {
             context,
         ]));
     }
-    browserProgress(state) {
-        return runEdge(authOwnMethod(AuthElicitation.prototype, this, "browserProgress", [
-            state,
-        ]));
+    browserCompleted(state) {
+        return runEdge(authOwnMethod(AuthElicitation.prototype, this, "browserCompleted", [state]));
     }
     connected(id, context) {
         return runEdge(authOwnMethod(AuthElicitation.prototype, this, "connected", [id, context]));
     }
+    refused(action, state, force) {
+        return runEdge(authOwnMethod(AuthElicitation.prototype, this, "refused", [action, state, force]));
+    }
+    /** The one gate before any recovery link: this caller may connect this connector here. */
+    mayConnect(id) {
+        const { registry, principal, publicUrl, canManage, unavailable, credentialUi } = this.options;
+        const connector = typeof id === "string" ? registry.getConnector(id) : undefined;
+        return (typeof id === "string" &&
+            /^[a-z0-9_-]+$/.test(id) &&
+            Boolean(connector?.startAuth || (connector?.credential && credentialUi)) &&
+            Boolean(principal && publicUrl) &&
+            !unavailable &&
+            canManage(id));
+    }
     bind(context) {
         this.downstream.bind(context);
     }
@@ -114,12 +143,8 @@ export class AuthElicitation {
                     !(yield* upwardStep(authInvoke(self.options, "claimRetry", [previous.connector, previous.browserNonces.at(-1)])))) {
                     return failure("invalid_request_state", "Invalid or expired requestState");
                 }
-                if (previous && object(response)) {
-                    if (response.action === "decline")
-                        return failure("auth_declined", "Connection was declined. The request was not retried.");
-                    if (response.action === "cancel")
-                        return failure("auth_cancelled", "Connection was cancelled. The request was not retried.");
-                }
+                if (previous && object(response) && (response.action === "decline" || response.action === "cancel"))
+                    return yield* upwardStep(authInvoke(self, "refused", [response.action, previous, args.force]));
                 if (previous?.reads.length) {
                     const catalog = new CatalogService(self.options.registry, self.options.publicUrl, {
                         requestScope: self.options.requestScope,
@@ -156,18 +181,12 @@ export class AuthElicitation {
                     }
                     bindReplayReads(self.options.requestScope, previous.reads);
                 }
-                const browser = previous && tool === "authorize_connector"
-                    ? yield* upwardStep(authInvoke(self, "browserProgress", [previous]))
-                    : undefined;
-                if (browser?.completed && previous) {
-                    // Retire unspent links before the status read. A browser claim racing
-                    // these CASes either wins and is observed as pending, or is refused.
-                    yield* upwardStep(authInvoke(self.options, "closeLinks", [previous.connector, previous.browserNonces]));
-                    if ((yield* upwardStep(authInvoke(self, "browserProgress", [previous]))).completed &&
-                        (yield* upwardStep(authInvoke(self, "connected", [previous.connector, context])))) {
-                        const structuredContent = { connector: previous.connector, status: "ok" };
-                        return { structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };
-                    }
+                if (previous &&
+                    tool === "authorize_connector" &&
+                    (yield* upwardStep(authInvoke(self, "browserCompleted", [previous]))) &&
+                    (yield* upwardStep(authInvoke(self, "connected", [previous.connector, context])))) {
+                    const structuredContent = { connector: previous.connector, status: "ok" };
+                    return { structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };
                 }
                 const envelope = context.mcpReq.envelope;
                 const capabilities = envelope?.[CLIENT_CAPABILITIES_META_KEY];
@@ -216,16 +235,8 @@ export class AuthElicitation {
                         content: [{ type: "text", text: JSON.stringify(structuredContent) }],
                     };
                 }
-                const { registry, vault, principal, publicUrl, canManage, unavailable } = self.options;
-                const connector = typeof id === "string" ? registry.getConnector(id) : undefined;
-                const recoverable = connector?.startAuth || (connector?.credential && self.options.credentialUi);
-                if (typeof id !== "string" ||
-                    !/^[a-z0-9_-]+$/.test(id) ||
-                    !recoverable ||
-                    !principal ||
-                    !publicUrl ||
-                    unavailable ||
-                    !canManage(id))
+                const { vault, principal } = self.options;
+                if (!self.mayConnect(id) || !principal)
                     return result;
                 // Incapable hosts already received the shared explicit-authorization handoff.
                 if (!capable)
@@ -237,9 +248,9 @@ export class AuthElicitation {
                         ...result.structuredContent,
                         error: {
                             ...result.structuredContent?.error,
-                            authorizationUrl: error.authorizationUrl ??
+                            ...connectLinkFields(error, id, error.authorizationUrl ??
                                 (yield* upwardStep(authInvoke(self.options, "connectLink", [id])))
-                                    .url,
+                                    .url),
                         },
                     };
                     return {
@@ -250,13 +261,13 @@ export class AuthElicitation {
                 }
                 if (previous && previous.round >= MAX_ROUNDS)
                     return failure("auth_round_limit", "Connection is still required after three prompts. Connect explicitly, then start a new request.");
-                // Once a verified browser has started this attempt, retries continue it.
-                // A pending consent must never be reset by another force=true prompt.
+                // Accept is consent to open the link, not proof it opened, so every round's
+                // link stays live and they share one reset (claimOAuthConnectStart).
                 const forced = explicit && args.force === true;
                 const link = yield* upwardStep(authInvoke(self.options, "connectLink", [
                     id,
-                    forced && !browser?.predecessor,
-                    forced ? browser?.predecessor : undefined,
+                    forced,
+                    forced ? previous?.browserNonces[0] : undefined,
                 ]));
                 const state = {
                     version: 1,
@@ -285,7 +296,7 @@ export class AuthElicitation {
                         ...result.structuredContent,
                         error: {
                             ...result.structuredContent?.error,
-                            authorizationUrl: link.url,
+                            ...connectLinkFields(result.structuredContent?.error, id, link.url),
                         },
                     };
                     return {
@@ -305,6 +316,59 @@ export class AuthElicitation {
                 });
             }), this.options.requestSignal).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
         }, AuthElicitation.prototype.run);
+        registerAuthMethod(AuthElicitation.prototype, "refused", function (action, state, force) {
+            const self = this;
+            return authAwait(authFlow(function* () {
+                const { code, message } = REFUSED[action];
+                const { connector: id, tool } = state;
+                if (!self.mayConnect(id))
+                    return failure(code, message);
+                const { registry, publicUrl, canManage, unavailable, credentialHandoffUrl, routes, requestScope } = self.options;
+                try {
+                    // The signed state bound these arguments, so this is the restart the
+                    // caller asked for, sharing the prompt's reset if that prompt was opened.
+                    const forced = tool === "authorize_connector" && force === true;
+                    // The ordinary handoff, except that the link is the sealed form this
+                    // client was already shown: the agent sees no principal in it.
+                    const handoff = yield* upwardStep(authCall(authorizationHandoff, [
+                        registry,
+                        publicUrl,
+                        requestScope,
+                        {
+                            canManageAuth: canManage,
+                            credentialHandoffUrl,
+                            oauthConnectUnavailable: unavailable,
+                            routes,
+                            oauthConnectUrl: authMethod(() => authInvoke(self.options, "connectLink", [
+                                id,
+                                forced,
+                                forced ? state.browserNonces[0] : undefined,
+                            ]).pipe(Effect.map((link) => link.url))),
+                        },
+                        { connector: id },
+                    ]));
+                    const url = handoff.authorizationUrl ?? handoff.operatorUrl;
+                    if (!url)
+                        return failure(code, message);
+                    if (handoff.authorizationUrl)
+                        sentSecretsForRequest(requestScope).mintedState(handoff.authorizationUrl);
+                    return toolError({
+                        ...handoff,
+                        code,
+                        message,
+                        retryable: false,
+                        nextAction: {
+                            url,
+                            purpose: refusedPurpose(handoff.authorizationUrl ? "" : "for the operator to open, "),
+                        },
+                    }, { ok: false });
+                }
+                catch {
+                    // A signing or storage failure cannot replace the refusal itself.
+                    return failure(code, message + REFUSED_NO_LINK);
+                }
+            }), this.options.requestSignal).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
+        }, AuthElicitation.prototype.refused);
         registerAuthMethod(AuthElicitation.prototype, "connected", function (id, context) {
             const self = this;
             return authAwait(authFlow(function* () {
@@ -331,29 +395,16 @@ export class AuthElicitation {
                 }
             }), this.options.requestSignal).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
         }, AuthElicitation.prototype.connected);
-        registerAuthMethod(AuthElicitation.prototype, "browserProgress", function (state) {
+        registerAuthMethod(AuthElicitation.prototype, "browserCompleted", function (state) {
             const self = this;
             return authAwait(authFlow(function* () {
-                let started;
-                let claimed;
-                let completed = false;
-                let pending = false;
-                for (const nonce of state.browserNonces) {
-                    const progress = yield* upwardStep(authInvoke(self.options, "linkProgress", [
-                        state.connector,
-                        nonce,
-                    ]));
-                    if (progress === "started")
-                        started = nonce;
-                    if (progress === "claimed")
-                        claimed = nonce;
-                    completed ||= progress === "started";
-                    pending ||= progress === "claimed";
-                }
-                const predecessor = started ?? claimed;
-                return { ...(predecessor ? { predecessor } : {}), completed: completed && !pending };
+                // A reset never leaves "started", so no reset can be running behind this link.
+                for (const nonce of state.browserNonces)
+                    if (yield* upwardStep(authInvoke(self.options, "linkStarted", [state.connector, nonce])))
+                        return true;
+                return false;
             }), this.options.requestSignal).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
-        }, AuthElicitation.prototype.browserProgress);
+        }, AuthElicitation.prototype.browserCompleted);
         registerAuthMethod(AuthElicitation.prototype, "verify", function (wire, context) {
             const self = this;
             return authAwait(authFlow(function* () {
@@ -380,7 +431,13 @@ export class AuthElicitation {
                     !Number.isInteger(state.round) ||
                     state.round < 1 ||
                     state.round > MAX_ROUNDS ||
-                    !["call_tool", "call_destructive_tool", "execute_code", "authorize_connector"].includes(String(state.tool)) ||
+                    ![
+                        "call_tool",
+                        "call_destructive_tool",
+                        "execute_code",
+                        "execute_read_code",
+                        "authorize_connector",
+                    ].includes(String(state.tool)) ||
                     typeof state.wireTool !== "string" ||
                     typeof state.digest !== "string" ||
                     !/^[a-f0-9]{64}$/.test(state.digest) ||

package/dist/authorization-handoff.js

@@ -1,4 +1,4 @@
-import { routePhrases } from "./agent-routes.js";
+import { handoffInHand, routePhrases } from "./agent-routes.js";
 import { upwardStep } from "./upward.js";
 import { authCall, authInvoke, authFlow, registerAuth } from "./auth/native.js";
 import { Context, Deferred, Effect, Scheduler } from "effect";
@@ -15,6 +15,38 @@ function outcomeAware(build) {
     afterUnknownWrite.set(handoff, build(true));
     return handoff;
 }
+/**
+ * What to do with a handoff the error already carries. Passing it on is the
+ * whole step: calling authorize_connector would only return the same thing.
+ * After a write of unknown outcome the follow-up reconciles, never retries.
+ */
+function handoffAction(handoff, unknownWrite) {
+    const then = unknownWrite
+        ? "After they confirm, re-read the write's target before any fresh call."
+        : "Retry after they confirm.";
+    const url = handoff.authorizationUrl ?? handoff.operatorUrl;
+    if (!url)
+        return {
+            action: "contact_operator",
+            purpose: `Tell the user the operator must fix this connector, then stop. ${then}`,
+        };
+    return {
+        url,
+        purpose: `Give this link to the user, unchanged, ${handoff.authorizationUrl ? "" : "for the operator to open, "}then stop. ${then}`,
+    };
+}
+const unknownWriteError = (error) => error.writeOutcome === "unknown" || error.reconciliationRequired === true;
+/**
+ * The fields for an auth error given only a connect link, where a capable host's
+ * prompt could not carry it: the same direct step as a full handoff.
+ */
+export function connectLinkFields(error, connector, authorizationUrl) {
+    return {
+        ...(typeof error.message === "string" ? { message: handoffInHand(error.message, connector) } : {}),
+        authorizationUrl,
+        nextAction: handoffAction({ connector, recovery: "oauth", authorizationUrl }, unknownWriteError(error)),
+    };
+}
 function oauthFollowUp(connectorId, unknownWrite, opts) {
     const then = `Then ${unknownWrite ? RECONCILE : "retry the original call"}`;
     // Without programs, no connecta.search can confirm the catalog.
@@ -95,7 +127,7 @@ const authorizationHandoffNative = /* @__PURE__ */ registerAuth(authorizationHan
             recovery: "oauth",
             status: "auth_required",
             authorizationUrl,
-            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. " +
+            instructions: "For the person opening this link: sign in as the user who requested this connection; Connecta verifies identity and permission before starting consent. For the agent: pass authorizationUrl on exactly as returned. " +
                 oauthFollowUp(connector.id, unknownWrite, opts),
         }));
     });
@@ -180,7 +212,8 @@ export function withAuthorizationHandoffEffect(scope, error) {
             return {
                 ...error,
                 ...value,
-                message: error.message,
+                message: handoffInHand(error.message, connector),
+                nextAction: handoffAction(value, unknownWriteError(error)),
                 ...(value.message ? { instructions: value.message } : {}),
             };
         }),