@zackbart/connecta 0.38.0 → 0.40.0

package/dist/auth/native.js

@@ -40,6 +40,23 @@ export function registerAuthMethod(prototype, key, program, own) {
     entries.set(key, program);
     registerAuth(own, program);
 }
+/**
+ * Define each program once as `prototype[key]`: the native body owned
+ * programs compose by identity, and its Promise edge for SDK/custom callers,
+ * installed with a class method's name and property attributes. A class
+ * declares the edge's type with a `declare` member.
+ */
+export function authMethods(prototype, entries) {
+    for (const [key, program] of Object.entries(entries)) {
+        const edge = {
+            [key](...args) {
+                return runEdge(authOwnMethod(prototype, this, key, args));
+            },
+        }[key];
+        Object.defineProperty(prototype, key, { value: edge, writable: true, enumerable: false, configurable: true });
+        registerAuthMethod(prototype, key, program, edge);
+    }
+}
 export function authOwnMethod(prototype, receiver, key, args) {
     return Effect.suspend(() => methods.get(prototype).get(key).apply(receiver, args)).pipe(Effect.catchDefect(Effect.fail));
 }
@@ -100,6 +117,26 @@ export function authStorage(storage, key, args, beforeSubmit) {
         return Effect.flatMap(Effect.serviceOption(AuthenticationWork), (work) => work._tag === "Some" ? authDetached(submitted) : submitted);
     });
 }
+/** Optional fresh token snapshot, with the same request ownership as an auth storage read. */
+export function authAccessToken(storage, hash) {
+    return Effect.suspend(() => {
+        const read = getNativeStorage(storage)?.accessToken;
+        if (!read)
+            return Effect.succeed(undefined);
+        const operation = authValue(() => read(hash));
+        return Effect.flatMap(Effect.serviceOption(AuthenticationWork), (work) => work._tag === "Some" ? authDetached(operation) : operation);
+    });
+}
+/** Several keys in one round trip when the store can, else one `get` at a time. */
+export function authStorageMany(storage, keys) {
+    return Effect.suspend(() => {
+        const getMany = getNativeStorage(storage)?.getMany;
+        if (!getMany)
+            return Effect.forEach(keys, (key) => authStorage(storage, "get", [key]));
+        const operation = authValue(() => getMany(keys));
+        return Effect.flatMap(Effect.serviceOption(AuthenticationWork), (work) => work._tag === "Some" ? authDetached(operation) : operation);
+    });
+}
 function authSubmission(operation, beforeSubmit) {
     return Effect.flatMap(Scheduler.Scheduler, (parent) => {
         let submitting = false;

package/dist/auth/oauth-grant.js

@@ -1,3 +1,16 @@
+/** How long before `expiresAt` a call refreshes instead of sending the token. */
+export const OAUTH_REFRESH_SKEW_MS = 60_000;
+/**
+ * The expiry a token response's `expires_in` gives, counted from `issuedAt`.
+ * Zero is a token already expired, never a missing expiry: the next call
+ * refreshes before sending it.
+ */
+export function tokenExpiry(tokens, issuedAt) {
+    const lifetime = tokens.expires_in;
+    return typeof lifetime === "number" && Number.isFinite(lifetime) && lifetime >= 0
+        ? issuedAt + lifetime * 1000
+        : undefined;
+}
 function plainObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }

package/dist/auth/static-oauth.js

@@ -1,3 +1,4 @@
+import { routePhrases } from "../agent-routes.js";
 import { withStoredAuth } from "./stored-observation.js";
 import { auth, OAuthError, UnauthorizedError } from "@modelcontextprotocol/client";
 import { Effect } from "effect";
@@ -15,9 +16,9 @@ import { SharedRead } from "../runtime/shared-read.js";
 import { sentSecretsFetch, sentSecretsFor, shortSecretWarning } from "../sent-secrets.js";
 import { unsentAfterUnauthorized } from "../write-outcome.js";
 import { trackRemoteClientRequest } from "./downstream-client-metadata.js";
-import { assertOAuthScope, authorizingContext, codeExchangeResponse, KvOAuthProvider, refreshCoordinatorsByPartition, } from "./downstream-oauth.js";
+import { assertOAuthScope, authorizingContext, codeExchangeResponse, EarlyRenewals, earlyRenewalFetch, KvOAuthProvider, refreshCoordinatorsByPartition, } from "./downstream-oauth.js";
 import { authView } from "./native-call.js";
-import { authCall, authFlow, authInvoke, authMethod, authOwnMethod, authProgram, authValue, registerAuth, registerAuthMethod, } from "./native.js";
+import { authCall, authFlow, authInvoke, authMethod, authProgram, authValue, registerAuth, authMethods, } from "./native.js";
 import { trackOAuthStartReset } from "./oauth-start-reset.js";
 import { bindRenewableGrant, OAUTH_CHALLENGE_MAX_BYTES } from "./renewable-grant.js";
 /**
@@ -226,14 +227,6 @@ class StaticOAuthProvider extends KvOAuthProvider {
         undefined, (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset), undefined, settings.scope, undefined, { secrets: sentSecretsFor(ctx), authorizationParams: settings.authorizationParams });
         this.settings = settings;
     }
-    /**
-     * The pre-registered client, answered from configuration. Its secret is
-     * never written to storage, sealed or otherwise: it is deployment config,
-     * not grant state, and an operator disconnect cannot delete it.
-     */
-    clientInformation() {
-        return runEdge(authOwnMethod(StaticOAuthProvider.prototype, this, "clientInformation", []));
-    }
     configuredAuthorizationBinding() {
         return {
             issuer: this.settings.identity,
@@ -264,26 +257,6 @@ class StaticOAuthProvider extends KvOAuthProvider {
             },
         };
     }
-    saveClientInformation() {
-        return runEdge(authOwnMethod(StaticOAuthProvider.prototype, this, "saveClientInformation", []));
-    }
-    /**
-     * Discovery as a constant. Supplying both halves keeps the SDK from
-     * fetching either: no protected-resource probe of the API origin, and no
-     * metadata request to an authorization server that may not publish any.
-     * The metadata names no `issuer`, so the SDK binds grants to the configured
-     * token endpoint and does not demand an RFC 9207 `iss` it cannot know.
-     */
-    discoveryState() {
-        return runEdge(authOwnMethod(StaticOAuthProvider.prototype, this, "discoveryState", []));
-    }
-    saveDiscoveryState() {
-        return runEdge(authOwnMethod(StaticOAuthProvider.prototype, this, "saveDiscoveryState", []));
-    }
-    /** No RFC 8707 `resource` parameter: a plain REST API names no resource. */
-    validateResourceURL() {
-        return runEdge(authOwnMethod(StaticOAuthProvider.prototype, this, "validateResourceURL", []));
-    }
     /**
      * The code exchange without `code_verifier`, for a flow whose authorization
      * request carried no challenge. Undefined everywhere else, which hands the
@@ -302,53 +275,52 @@ class StaticOAuthProvider extends KvOAuthProvider {
     exchanging(code) {
         this.exchangeCode = code;
     }
-    redirectToAuthorization(authorizationUrl) {
-        return runEdge(authOwnMethod(StaticOAuthProvider.prototype, this, "redirectToAuthorization", [authorizationUrl]));
-    }
     static {
-        registerAuthMethod(StaticOAuthProvider.prototype, "clientInformation", function () {
-            return authValue(() => this.configuredClientInformation());
-        }, StaticOAuthProvider.prototype.clientInformation);
-        registerAuthMethod(StaticOAuthProvider.prototype, "saveClientInformation", function () {
-            // Nothing to save: the SDK only saves a client it registered or stamped.
-            return Effect.void;
-        }, StaticOAuthProvider.prototype.saveClientInformation);
-        registerAuthMethod(StaticOAuthProvider.prototype, "discoveryState", function () {
-            return authValue(() => {
-                const { settings } = this;
-                const metadata = {
-                    authorization_endpoint: settings.authorizationEndpoint.href,
-                    token_endpoint: settings.tokenEndpoint.href,
-                    response_types_supported: ["code"],
-                    grant_types_supported: ["authorization_code", "refresh_token"],
-                    code_challenge_methods_supported: ["S256"],
-                    token_endpoint_auth_methods_supported: [settings.clientAuthentication],
-                };
-                return {
-                    authorizationServerUrl: settings.identity,
-                    authorizationServerMetadata: metadata,
-                    resourceMetadata: { resource: settings.serverUrl.origin },
-                };
-            });
-        }, StaticOAuthProvider.prototype.discoveryState);
-        registerAuthMethod(StaticOAuthProvider.prototype, "saveDiscoveryState", function () {
-            // Configuration is the discovery; there is nothing to remember.
-            return Effect.void;
-        }, StaticOAuthProvider.prototype.saveDiscoveryState);
-        registerAuthMethod(StaticOAuthProvider.prototype, "validateResourceURL", function () {
-            return authValue(() => {
-                return undefined;
-            });
-        }, StaticOAuthProvider.prototype.validateResourceURL);
-        registerAuthMethod(StaticOAuthProvider.prototype, "redirectToAuthorization", function (authorizationUrl) {
-            return authFlow(function* () {
-                if (!this.settings.pkce) {
-                    authorizationUrl.searchParams.delete("code_challenge");
-                    authorizationUrl.searchParams.delete("code_challenge_method");
-                }
-                (yield authCall(KvOAuthProvider.prototype.redirectToAuthorization, [authorizationUrl], this));
-            }.bind(this));
-        }, StaticOAuthProvider.prototype.redirectToAuthorization);
+        authMethods(StaticOAuthProvider.prototype, {
+            clientInformation: function () {
+                return authValue(() => this.configuredClientInformation());
+            },
+            saveClientInformation: function () {
+                // Nothing to save: the SDK only saves a client it registered or stamped.
+                return Effect.void;
+            },
+            discoveryState: function () {
+                return authValue(() => {
+                    const { settings } = this;
+                    const metadata = {
+                        authorization_endpoint: settings.authorizationEndpoint.href,
+                        token_endpoint: settings.tokenEndpoint.href,
+                        response_types_supported: ["code"],
+                        grant_types_supported: ["authorization_code", "refresh_token"],
+                        code_challenge_methods_supported: ["S256"],
+                        token_endpoint_auth_methods_supported: [settings.clientAuthentication],
+                    };
+                    return {
+                        authorizationServerUrl: settings.identity,
+                        authorizationServerMetadata: metadata,
+                        resourceMetadata: { resource: settings.serverUrl.origin },
+                    };
+                });
+            },
+            saveDiscoveryState: function () {
+                // Configuration is the discovery; there is nothing to remember.
+                return Effect.void;
+            },
+            validateResourceURL: function () {
+                return authValue(() => {
+                    return undefined;
+                });
+            },
+            redirectToAuthorization: function (authorizationUrl) {
+                return authFlow(function* () {
+                    if (!this.settings.pkce) {
+                        authorizationUrl.searchParams.delete("code_challenge");
+                        authorizationUrl.searchParams.delete("code_challenge_method");
+                    }
+                    (yield authCall(KvOAuthProvider.prototype.redirectToAuthorization, [authorizationUrl], this));
+                }.bind(this));
+            },
+        });
     }
 }
 const AUTH_REQUIRED_MESSAGE = "Authorization required — open the URL to connect.";
@@ -469,62 +441,66 @@ export function staticOAuth(id, config) {
      * rotation commits, and re-consent verdicts. Credential-bearing requests
      * never follow redirects in either OAuth adapter.
      */
-    const runAuth = authMethod((provider, ctx, exchange, requestOwned = false) => {
+    const runAuth = authMethod((provider, ctx, exchange, requestOwned = false, 
+    /** The access token an early renewal replaces. */
+    early) => {
         return authFlow(function* () {
             const secrets = sentSecretsFor(ctx);
+            const coordinated = coordinatorFor(ctx).coordinatedFetch(provider, authMethod((input, init) => {
+                return authFlow(function* () {
+                    if (exchange) {
+                        // A code exchange has no submitted refresh claim transferring
+                        // ownership. Only explicit scope revocation stops a callback:
+                        // the production callback route remains uninterruptible and
+                        // does not revoke its own scope while exchanging a code.
+                        return (yield authView(ctx, authMethod((signal) => {
+                            return authFlow(function* () {
+                                assertProviderCallOpen(ctx, id, true);
+                                const response = (yield authCall(tokenEndpointFetch, [
+                                    secrets,
+                                    input,
+                                    {
+                                        ...init,
+                                        signal: init?.signal ? AbortSignal.any([init.signal, signal]) : signal,
+                                    },
+                                ]));
+                                // An override can ignore abort. Never hand its late tokens
+                                // to the SDK, which would otherwise persist both credentials.
+                                if (signal.aborted) {
+                                    void response.body?.cancel().catch(() => { });
+                                    throw signal.reason;
+                                }
+                                // The SDK clones and reads this body after fetch resolves.
+                                // Revocation must cancel that read even for a custom fetch.
+                                return codeExchangeResponse(response, signal);
+                            });
+                        }), true));
+                    }
+                    return (yield authCall(tokenEndpointFetch, [secrets, input, init]));
+                });
+            }), viewSignal(ctx, requestOwned || exchange !== undefined), ctx.defer, undefined, () => {
+                guardedTransport(true);
+            });
             return (yield authCall(auth, [
                 provider,
                 {
                     serverUrl: settings.serverUrl,
                     ...exchange,
-                    fetchFn: coordinatorFor(ctx).coordinatedFetch(provider, authMethod((input, init) => {
-                        return authFlow(function* () {
-                            if (exchange) {
-                                // A code exchange has no submitted refresh claim transferring
-                                // ownership. Only explicit scope revocation stops a callback:
-                                // the production callback route remains uninterruptible and
-                                // does not revoke its own scope while exchanging a code.
-                                return (yield authView(ctx, authMethod((signal) => {
-                                    return authFlow(function* () {
-                                        assertProviderCallOpen(ctx, id, true);
-                                        const response = (yield authCall(tokenEndpointFetch, [
-                                            secrets,
-                                            input,
-                                            {
-                                                ...init,
-                                                signal: init?.signal ? AbortSignal.any([init.signal, signal]) : signal,
-                                            },
-                                        ]));
-                                        // An override can ignore abort. Never hand its late tokens
-                                        // to the SDK, which would otherwise persist both credentials.
-                                        if (signal.aborted) {
-                                            void response.body?.cancel().catch(() => { });
-                                            throw signal.reason;
-                                        }
-                                        // The SDK clones and reads this body after fetch resolves.
-                                        // Revocation must cancel that read even for a custom fetch.
-                                        return codeExchangeResponse(response, signal);
-                                    });
-                                }), true));
-                            }
-                            return (yield authCall(tokenEndpointFetch, [secrets, input, init]));
-                        });
-                    }), viewSignal(ctx, requestOwned || exchange !== undefined), ctx.defer, undefined, () => {
-                        guardedTransport(true);
-                    }),
+                    fetchFn: early === undefined ? coordinated : earlyRenewalFetch(coordinated, early),
                 },
             ]));
         });
     });
     // No cause, as in remoteMcp(): the `UnauthorizedError` class is the whole
     // verdict, and a logger rendering the chain renders whatever it says.
-    const authRequiredError = () => new ConnectorCallError("downstream_oauth_required", `Connector "${id}" requires authorization — call authorize_connector({ connector: "${id}" }) and open the returned URL.`);
+    const authRequiredError = (ctx) => new ConnectorCallError("downstream_oauth_required", `Connector "${id}" requires authorization — ${routePhrases(ctx).authorizeAndOpen(id)}.`);
     const disconnectedMessage = `Connector "${id}" was disconnected by an operator — explicitly start authorization to reconnect it.`;
     /**
-     * The token to send after `spent` drew a 401: one another request has
-     * already rotated in, or else one coordinated refresh.
+     * The token to send after `spent` drew a 401, or instead of an `early`
+     * one about to expire: one another request has already rotated in, or else
+     * one coordinated refresh.
      */
-    const renewedToken = authMethod((provider, ctx, spent, requestOwned = false) => {
+    const renewedToken = authMethod((provider, ctx, spent, requestOwned = false, early = false) => {
         return authFlow(function* () {
             // Only renewal whose claim CAS was submitted may survive this call.
             // Race each preparation read too, and never resume SDK work or consume a
@@ -548,29 +524,42 @@ export function staticOAuth(id, config) {
                 return current.access_token;
             if ((yield authCall(live, [
                 authMethod(() => {
-                    return authCall(runAuth, [provider, ctx, undefined, requestOwned]);
+                    return authCall(runAuth, [
+                        provider,
+                        ctx,
+                        undefined,
+                        requestOwned,
+                        early ? spent : undefined,
+                    ]);
                 }),
             ])) !== "AUTHORIZED")
-                throw authRequiredError();
+                throw authRequiredError(ctx);
             const refreshed = (yield authCall(live, [
                 authMethod(() => {
                     return authInvoke(provider, "tokens", [issuerContext]);
                 }),
             ]));
             if (!refreshed)
-                throw authRequiredError();
+                throw authRequiredError(ctx);
             return refreshed.access_token;
         });
     });
-    /** One call's grant use; submitted refresh work keeps the coordinator's owner. */
-    const grantFor = (ctx, requestOwned = false) => {
+    // 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) => {
         let provider;
         const use = authMethod((work) => {
             return authView(ctx, authMethod((signal) => {
                 return authFlow(function* () {
                     assertProviderCallOpen(ctx, id, requestOwned);
                     if (rejectedScopes.has(scopeOf(ctx)))
-                        throw authRequiredError();
+                        throw authRequiredError(ctx);
                     const live = deriveContext(ctx, { signal });
                     const release = retainOAuthPartition(oauthPartitionFor(live));
                     try {
@@ -591,7 +580,7 @@ export function staticOAuth(id, config) {
                             throw signal.reason;
                         if (error instanceof UnauthorizedError) {
                             rejectedScopes.add(scopeOf(ctx));
-                            throw authRequiredError();
+                            throw authRequiredError(ctx);
                         }
                         throw error;
                     }
@@ -604,11 +593,26 @@ export function staticOAuth(id, config) {
         return {
             token: authMethod(() => {
                 return authCall(use, [
-                    authMethod((provider) => {
+                    authMethod((provider, live) => {
                         return authFlow(function* () {
                             const tokens = (yield authInvoke(provider, "tokens", [issuerContext]));
                             if (!tokens)
-                                throw authRequiredError();
+                                throw authRequiredError(ctx);
+                            // A token about to expire is renewed before anything is sent with it,
+                            // so a write never meets the 401 it could not be repeated after.
+                            const scope = scopeOf(ctx);
+                            if (provider.renewalDue() === tokens.access_token &&
+                                (renewAgain || !earlyRenewed.settled(scope, tokens.access_token))) {
+                                const fresh = (yield authCall(renewedToken, [
+                                    provider,
+                                    live,
+                                    tokens.access_token,
+                                    requestOwned,
+                                    true,
+                                ]));
+                                earlyRenewed.record(scope, tokens.access_token, fresh, provider.observedExpiry(fresh));
+                                return fresh;
+                            }
                             return tokens.access_token;
                         });
                     }),
@@ -625,7 +629,7 @@ export function staticOAuth(id, config) {
                 return authView(ctx, authMethod(() => {
                     return authValue(() => {
                         rejectedScopes.add(scopeOf(ctx));
-                        throw authRequiredError();
+                        throw authRequiredError(ctx);
                     });
                 }), requestOwned);
             }),
@@ -755,12 +759,12 @@ export function staticOAuth(id, config) {
                                 // renewed nothing.
                                 renewedAfterUnauthorized(dispatch, stale, fresh);
                                 if (fresh === stale)
-                                    renewal = authRequiredError();
+                                    renewal = authRequiredError(ctx);
                             }
                             catch (error) {
                                 if (error instanceof UnauthorizedError)
                                     rejectedScopes.add(scopeOf(ctx));
-                                renewal = error instanceof UnauthorizedError ? authRequiredError() : error;
+                                renewal = error instanceof UnauthorizedError ? authRequiredError(ctx) : error;
                             }
                             throw vendorRefusal(unsentAfterUnauthorized(`Connector "${id}"'s API`, renewal, "downstream_oauth_required"), dispatch);
                         }
@@ -783,7 +787,7 @@ export function staticOAuth(id, config) {
                             throw signal.reason;
                         if (error instanceof UnauthorizedError) {
                             rejectedScopes.add(scopeOf(ctx));
-                            throw authRequiredError();
+                            throw authRequiredError(ctx);
                         }
                         throw error;
                     }
@@ -796,7 +800,7 @@ export function staticOAuth(id, config) {
             }), auxiliary));
         });
     });
-    const status = authMethod((ctx) => {
+    const statusOf = authMethod((ctx, provider) => {
         return authFlow(function* () {
             if (rejectedScopes.has(scopeOf(ctx))) {
                 return {
@@ -808,7 +812,6 @@ export function staticOAuth(id, config) {
             // 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.
-            const provider = providerFor(ctx);
             if ((yield authInvoke(provider, "operatorDisconnected", []))) {
                 return { state: "auth_required", message: disconnectedMessage };
             }
@@ -817,6 +820,24 @@ export function staticOAuth(id, config) {
                 : { state: "auth_required", message: AUTH_REQUIRED_MESSAGE };
         });
     });
+    const status = authMethod((ctx) => {
+        return authCall(statusOf, [ctx, providerFor(ctx)]);
+    });
+    /**
+     * The invocation's check before a call enters its handler: the status read,
+     * then, when the token it read is within a minute of its stored expiry, one
+     * coordinated refresh. A failure ends the call before the handler runs, so
+     * no write can draw the 401 it could not be repeated after (INV-9).
+     */
+    const prepareCall = authMethod((ctx) => {
+        return authFlow(function* () {
+            const provider = providerFor(ctx);
+            const state = (yield authCall(statusOf, [ctx, provider]));
+            if (state.state === "ok" && provider.renewalDue() !== undefined)
+                (yield authInvoke(grantFor(ctx, false, true), "token", []));
+            return state;
+        });
+    });
     const startAuth = authMethod((original, opts) => {
         return authFlow(function* () {
             const ctx = authorizingContext(original);
@@ -949,6 +970,7 @@ export function staticOAuth(id, config) {
     });
     return withStoredAuth({
         status: retainAuthPartition(status, 0),
+        prepareCall: retainAuthPartition(prepareCall, 0),
         startAuth: retainAuthPartition(startAuth, 0),
         disconnectAuth: retainAuthPartition(disconnectAuth, 0),
         verifyState: retainAuthPartition(verifyState, 1),

package/dist/auth-elicitation.js

@@ -74,7 +74,11 @@ export class AuthElicitation {
                 self.codec ??= yield* Effect.cached(authCall(key, [], self.options.vault).pipe(Effect.map((bytes) => createRequestStateCodec({
                     key: bytes,
                     ttlSeconds: TTL_MS / 1000,
-                    bind: () => canonical({ principal: self.options.principal, endpoint: self.options.endpoint }),
+                    bind: () => canonical({
+                        principal: self.options.principal,
+                        endpoint: self.options.endpoint,
+                        pool: self.options.registry.resultIdentity().pool,
+                    }),
                 }))));
                 return yield* self.codec;
             }), this.options.requestSignal).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
@@ -258,6 +262,7 @@ export class AuthElicitation {
                     version: 1,
                     principal,
                     endpoint: self.options.endpoint,
+                    pool: self.options.registry.resultIdentity().pool,
                     connector: id,
                     tool,
                     ...(typeof args.address === "string" ? { address: args.address } : {}),
@@ -365,6 +370,7 @@ export class AuthElicitation {
                     !principal ||
                     state.principal !== principal ||
                     state.endpoint !== endpoint ||
+                    state.pool !== registry.resultIdentity().pool ||
                     typeof state.connector !== "string" ||
                     !registry.getConnector(state.connector) ||
                     !canManage(state.connector) ||

package/dist/authorization-handoff.js

@@ -1,3 +1,4 @@
+import { 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";
@@ -14,8 +15,13 @@ function outcomeAware(build) {
     afterUnknownWrite.set(handoff, build(true));
     return handoff;
 }
-function oauthFollowUp(connectorId, unknownWrite) {
-    return `Then ${unknownWrite ? RECONCILE : "retry the original call"}; connecta.search({ connector: ${JSON.stringify(connectorId)} }) inside execute_code confirms the catalog now loads.`;
+function oauthFollowUp(connectorId, unknownWrite, opts) {
+    const then = `Then ${unknownWrite ? RECONCILE : "retry the original call"}`;
+    // Without programs, no connecta.search can confirm the catalog.
+    const { program } = routePhrases(opts.routes);
+    return program
+        ? `${then}; connecta.search({ connector: ${JSON.stringify(connectorId)} }) inside ${program} confirms the catalog now loads.`
+        : `${then}. Retry the original native call after recovery.`;
 }
 /** Shared with explicit authorization; errors never request a forced restart. */
 export function authorizationHandoff(registry, baseUrl, requestScope, opts, args) {
@@ -43,8 +49,8 @@ const authorizationHandoffNative = /* @__PURE__ */ registerAuth(authorizationHan
                     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.",
+                        "vault and ui in deployment code, then " +
+                        `${routePhrases(opts.routes).authorizeAgain}.`,
                 };
             }
             const fields = connector.credential.fields?.map((field) => ({
@@ -90,7 +96,7 @@ const authorizationHandoffNative = /* @__PURE__ */ registerAuth(authorizationHan
             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. " +
-                oauthFollowUp(connector.id, unknownWrite),
+                oauthFollowUp(connector.id, unknownWrite, opts),
         }));
     });
 });