@zackbart/connecta 0.26.0 → 0.26.1

package/dist/branding.d.ts

@@ -18,6 +18,11 @@ interface ResolvedBranding {
     pageTitle: string;
     /** href for the page's icon link. */
     faviconHref: string;
+    /**
+     * The configured `theme-color`, or the documented `#ffffff` default.
+     * Informational: pages emit a configured value as-is, and without one they
+     * follow the scheme (`themeColorMeta`) rather than painting this default.
+     */
     themeColor: string;
     /** Only the tokens that survived their gate; the stylesheet owns the rest. */
     theme: ResolvedTheme;
@@ -43,6 +48,88 @@ export declare function droppedThemeTokens(theme?: ConnectaTheme): string[];
  * anything that would need escaping is dropped rather than rewritten.
  */
 export declare function themeCss(theme: ResolvedTheme): string;
+/**
+ * The resolved scheme as the root element's attribute. The dark palette keys
+ * off `html[data-scheme]`, so "system" leaves it off and the media query
+ * decides.
+ */
+export declare function schemeAttribute(theme: ResolvedTheme): string;
+/** Text or attribute value, escaped for any position in an HTML document. */
+export declare function escapeHtml(value: string): string;
+export interface PageLayout {
+    /** The complete `<title>`. */
+    title: string;
+    /** Whether the operator UI is mounted, and so serves `/favicon.*` and `/`. */
+    uiMounted: boolean;
+    /**
+     * The origin that serves `/favicon.*`, for a page that may be rendered on
+     * another host: root-relative icon hrefs resolve against it. A browser 404
+     * on the artifact host passes `publicUrl`, since that host answers every
+     * non-artifact path, the favicons included, with 404. Omitted, they stay
+     * root-relative.
+     */
+    iconOrigin?: string | undefined;
+    /** Markup after the masthead: the page's `<main>`. */
+    body: string;
+    /**
+     * The page's stylesheet before the theme block. Defaults to the shared
+     * tokens and primitives; the operator shell passes its own bundle, which
+     * already imports both.
+     */
+    styles?: string;
+    /** Page-specific rules appended to `styles`, still before the theme. */
+    extraStyles?: string;
+    /** Additional head markup, emitted verbatim (the Clerk loader). */
+    head?: string;
+    /** Emitted verbatim at the masthead's end (the operator nav mount). */
+    mastheadEnd?: string;
+    /** A skip link to this element id, for pages with navigation to skip. */
+    skipTo?: {
+        id: string;
+        label: string;
+    };
+    /** Markup after the body content, emitted verbatim (the operator script). */
+    tail?: string;
+}
+/**
+ * The one page layout every server-rendered page shares: the operator shell,
+ * the OAuth callback, and browser-facing 404s. Doctype and meta, the favicon a
+ * deployment actually serves, the resolved scheme, the token stylesheet with
+ * the theme block after it, and the masthead.
+ *
+ * `/favicon.svg` and `/favicon.ico` are operator UI routes. Without the UI they
+ * are 404s, so the default links are left out rather than pointing at nothing
+ * (a browser then asks for `/favicon.ico` on its own and gets the same 404). A
+ * configured `favicon.href` is the operator's own icon and is linked either way.
+ *
+ * Every interpolated branding value is escaped here; `body`, `head`,
+ * `mastheadEnd`, and `tail` are the caller's markup and are not.
+ */
+export declare function renderPage(branding: ConnectaBranding | undefined, layout: PageLayout): string;
+/**
+ * Status marks for one-message pages. Decorative: the label and heading beside
+ * each carry the meaning, so the shape repeats it and color is never alone.
+ */
+export declare const STATUS_ICONS: {
+    readonly ok: "<svg viewBox=\"0 0 20 20\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2.2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M5 10.5l3.2 3.2L15 6.8\"/></svg>";
+    readonly problem: "<svg viewBox=\"0 0 20 20\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2.2\" stroke-linecap=\"round\"><path d=\"M10 5.5v5.5\"/><path d=\"M10 14.6v.1\"/></svg>";
+    readonly declined: "<svg viewBox=\"0 0 20 20\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2.2\" stroke-linecap=\"round\"><path d=\"M6 10h8\"/></svg>";
+    readonly missing: "<svg viewBox=\"0 0 20 20\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\"><circle cx=\"9\" cy=\"9\" r=\"4.5\"/><path d=\"M12.4 12.4L16 16\"/></svg>";
+};
+/**
+ * The 404 a browser gets for a path nothing serves, and everyone else's plain
+ * `Not Found`. The body is built from deployment configuration alone and names
+ * no path, so every unserved path — on the main host or an artifact host —
+ * answers with the same bytes for the same `Accept`: a 404 must not tell one
+ * route from another. The home link appears only when the operator UI is
+ * mounted to land on, and points at the public origin so an artifact host's
+ * 404 does not link to another 404.
+ */
+export declare function notFoundResponse(request: Request, opts: {
+    branding?: ConnectaBranding | undefined;
+    ui?: object | undefined;
+    publicUrl?: string | undefined;
+}): Response;
 /**
  * Names of the branding URLs the operator set that failed their gate and were
  * replaced by a default. Lives beside the gates so the startup warning cannot

package/dist/branding.js

@@ -1,3 +1,4 @@
+import { PAGE_CSS, TOKENS_CSS } from "./page-styles.js";
 /** Connecta's default monochrome "C" mark. */
 export const CONNECTA_FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
   <style>
@@ -37,7 +38,7 @@ export function resolveBranding(branding) {
         faviconHref: faviconHref && isSafeIconHref(faviconHref)
             ? faviconHref
             : DEFAULT_FAVICON_HREF,
-        themeColor: trimmedString(branding?.themeColor) ?? "#ffffff",
+        themeColor: configuredThemeColor(branding) ?? "#ffffff",
         theme: resolveTheme(branding?.theme),
     };
 }
@@ -148,6 +149,174 @@ export function themeCss(theme) {
     ].filter(Boolean);
     return declarations.length ? `:root{${declarations.join(";")}}` : "";
 }
+/**
+ * The resolved scheme as the root element's attribute. The dark palette keys
+ * off `html[data-scheme]`, so "system" leaves it off and the media query
+ * decides.
+ */
+export function schemeAttribute(theme) {
+    return theme.colorScheme === "system"
+        ? ""
+        : ` data-scheme="${theme.colorScheme}"`;
+}
+/** Text or attribute value, escaped for any position in an HTML document. */
+export function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+/**
+ * The masthead's `--surface` in each palette, for the browser chrome a
+ * `theme-color` paints. A configured `themeColor` wins; without one a dark
+ * page should not sit under a white status bar.
+ */
+const SURFACE = { light: "#ffffff", dark: "#151a21" };
+/** The operator's own `themeColor`, read the one way both callers read it. */
+function configuredThemeColor(branding) {
+    return trimmedString(branding?.themeColor);
+}
+function themeColorMeta(branding, theme) {
+    const configured = configuredThemeColor(branding);
+    if (configured)
+        return `<meta name="theme-color" content="${escapeHtml(configured)}">`;
+    if (theme.colorScheme !== "system") {
+        return `<meta name="theme-color" content="${SURFACE[theme.colorScheme]}">`;
+    }
+    return `<meta name="theme-color" content="${SURFACE.light}" media="(prefers-color-scheme: light)">\n` +
+        `<meta name="theme-color" content="${SURFACE.dark}" media="(prefers-color-scheme: dark)">`;
+}
+/**
+ * The one page layout every server-rendered page shares: the operator shell,
+ * the OAuth callback, and browser-facing 404s. Doctype and meta, the favicon a
+ * deployment actually serves, the resolved scheme, the token stylesheet with
+ * the theme block after it, and the masthead.
+ *
+ * `/favicon.svg` and `/favicon.ico` are operator UI routes. Without the UI they
+ * are 404s, so the default links are left out rather than pointing at nothing
+ * (a browser then asks for `/favicon.ico` on its own and gets the same 404). A
+ * configured `favicon.href` is the operator's own icon and is linked either way.
+ *
+ * Every interpolated branding value is escaped here; `body`, `head`,
+ * `mastheadEnd`, and `tail` are the caller's markup and are not.
+ */
+export function renderPage(branding, layout) {
+    const brand = resolveBranding(branding);
+    // Top-left corner. With an owner set it reads "<owner> <product>"; without
+    // one the product label stands alone. Either half links out when the
+    // matching URL is configured.
+    const label = (className, text, href) => href
+        ? `<a class="${className} navlink" href="${escapeHtml(href)}">${escapeHtml(text)}</a>`
+        : `<span class="${className}">${escapeHtml(text)}</span>`;
+    const owner = brand.ownerName
+        ? label("brand", brand.ownerName, brand.ownerUrl)
+        : label("brand", brand.productName, brand.productUrl);
+    const product = brand.ownerName
+        ? label("product", brand.productName, brand.productUrl)
+        : "";
+    const customIcon = brand.faviconHref !== DEFAULT_FAVICON_HREF;
+    // `isSafeIconHref` already limited a relative href to one leading slash, so
+    // resolving it can only land on `iconOrigin` itself.
+    const iconHref = (href) => layout.iconOrigin && href.startsWith("/")
+        ? new URL(href, layout.iconOrigin).toString()
+        : href;
+    const icons = [
+        ...(customIcon || layout.uiMounted
+            ? [`<link rel="icon" href="${escapeHtml(iconHref(brand.faviconHref))}" type="image/svg+xml">`]
+            : []),
+        ...(layout.uiMounted
+            ? [`<link rel="shortcut icon" href="${escapeHtml(iconHref("/favicon.ico"))}">`]
+            : []),
+    ];
+    const skip = layout.skipTo
+        ? `<a class="skip-link" href="#${escapeHtml(layout.skipTo.id)}">${escapeHtml(layout.skipTo.label)}</a>\n`
+        : "";
+    const styles = (layout.styles ?? TOKENS_CSS + PAGE_CSS) + (layout.extraStyles ?? "");
+    return `<!doctype html>
+<html lang="en"${schemeAttribute(brand.theme)}>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+${themeColorMeta(branding, brand.theme)}
+<meta name="description" content="${escapeHtml(brand.description)}">
+${icons.join("\n")}
+<title>${escapeHtml(layout.title)}</title>
+${layout.head ?? ""}
+<style>${styles}${themeCss(brand.theme)}</style>
+</head>
+<body>
+${skip}<header class="masthead shell">
+  <div class="masthead-inner">
+    <div class="mast-nav">
+      ${owner}${product ? `\n      ${product}` : ""}
+    </div>${layout.mastheadEnd ? `\n    ${layout.mastheadEnd}` : ""}
+  </div>
+</header>
+${layout.body}${layout.tail ? `\n${layout.tail}` : ""}
+</body>
+</html>`;
+}
+/**
+ * Status marks for one-message pages. Decorative: the label and heading beside
+ * each carry the meaning, so the shape repeats it and color is never alone.
+ */
+export const STATUS_ICONS = {
+    ok: '<svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 10.5l3.2 3.2L15 6.8"/></svg>',
+    problem: '<svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"><path d="M10 5.5v5.5"/><path d="M10 14.6v.1"/></svg>',
+    declined: '<svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"><path d="M6 10h8"/></svg>',
+    missing: '<svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="9" cy="9" r="4.5"/><path d="M12.4 12.4L16 16"/></svg>',
+};
+/**
+ * A request a person's browser made for a page, as opposed to a client asking
+ * for data: navigations send `text/html` in `Accept`, `fetch()` and MCP
+ * clients do not.
+ */
+function wantsHtml(request) {
+    return /\btext\/html\b/i.test(request.headers.get("Accept") ?? "");
+}
+/**
+ * The 404 a browser gets for a path nothing serves, and everyone else's plain
+ * `Not Found`. The body is built from deployment configuration alone and names
+ * no path, so every unserved path — on the main host or an artifact host —
+ * answers with the same bytes for the same `Accept`: a 404 must not tell one
+ * route from another. The home link appears only when the operator UI is
+ * mounted to land on, and points at the public origin so an artifact host's
+ * 404 does not link to another 404.
+ */
+export function notFoundResponse(request, opts) {
+    if (!wantsHtml(request)) {
+        return new Response("Not Found", { status: 404, headers: { Vary: "Accept" } });
+    }
+    const brand = resolveBranding(opts.branding);
+    const uiMounted = Boolean(opts.ui);
+    const homeHref = opts.publicUrl ? new URL("/", opts.publicUrl).toString() : "/";
+    const home = uiMounted
+        ? `<div class="status-actions"><a class="btn" href="${escapeHtml(homeHref)}">Go to ${escapeHtml(brand.productName)}</a></div>`
+        : "";
+    const body = `<main class="page shell">
+  <section class="status-page" data-not-found>
+    <div class="status-head">
+      <span class="status-mark" aria-hidden="true">${STATUS_ICONS.missing}</span>
+      <p class="status-label">404</p>
+    </div>
+    <h1>Page not found</h1>
+    <p class="status-copy">Nothing is served at this address. Check the link, or ask whoever runs ${escapeHtml(brand.productName)} for the right one.</p>
+    ${home}
+  </section>
+</main>`;
+    return new Response(renderPage(opts.branding, {
+        title: `Page not found — ${brand.pageTitle}`,
+        uiMounted,
+        // Same bytes on either host: the icons, like the home link, come from
+        // the public origin.
+        iconOrigin: opts.publicUrl,
+        body,
+    }), {
+        status: 404,
+        headers: { "Content-Type": "text/html; charset=utf-8", Vary: "Accept" },
+    });
+}
 /**
  * Whether the operator meant to supply a value here — the question every
  * dropped-value warning asks before naming a field, and one definition so the

package/dist/connectors/remote-mcp.js

@@ -1,6 +1,7 @@
 import { Client, ProtocolError, SdkHttpError, isInputRequiredResult, specTypeSchemas, StreamableHTTPClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
 import { Deferred, Duration, Effect, Exit, Scope } from "effect";
 import { KvOAuthProvider, OAuthRefreshCoordinator, } from "../auth/downstream-oauth.js";
+import { trackOAuthStartReset } from "../auth/oauth-start-reset.js";
 import { MAX_CATALOG_TOOLS } from "../catalog-limits.js";
 import { boundedEchoText, ConnectorCallError, msg, unavailableCallError, } from "../errors.js";
 import { CONNECTA_VERSION } from "../version.js";
@@ -587,7 +588,20 @@ export function remoteMcp(id, opts) {
     const newProvider = (ctx, state) => {
         if (state?.provider)
             return state.provider;
-        const provider = new KvOAuthProvider(id, ctx.storage, `${ctx.baseUrl}/oauth/callback/${id}`, refreshCoordinator, ctx.allowAuthorization === true, oauthSealerFor(ctx));
+        const provider = new KvOAuthProvider(id, ctx.storage, `${ctx.baseUrl}/oauth/callback/${id}`, refreshCoordinator, ctx.allowAuthorization === true, oauthSealerFor(ctx), ctx.signal, JSON.stringify({
+            url: new URL(opts.url).href,
+            redirectUri: `${ctx.baseUrl}/oauth/callback/${id}`,
+            clientMetadata: {
+                redirect_uris: [`${ctx.baseUrl}/oauth/callback/${id}`],
+                client_name: "connecta",
+                grant_types: ["authorization_code", "refresh_token"],
+                response_types: ["code"],
+                token_endpoint_auth_method: "none",
+            },
+            authScope: opts.authScope ?? "shared",
+            versionNegotiation: opts.versionNegotiation ?? "auto",
+            redirects: opts.redirects ?? "none",
+        }), (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset));
         if (state)
             state.provider = provider;
         return provider;
@@ -871,13 +885,14 @@ export function remoteMcp(id, opts) {
             }));
         });
     };
-    const disconnectAuthorization = async (ctx, state, operatorDisconnected = false) => {
+    const disconnectAuthorization = async (ctx, state, operatorDisconnected = false, preserveClient = false) => {
         const provider = newProvider(ctx, state);
         // Publish the replacement epoch before waiting on or closing any
         // request-local transport. A hung connect therefore cannot delay the
         // fence, and every late OAuth write stays in the older namespace.
+        const reset = provider.resetAuthorization(operatorDisconnected, preserveClient);
         try {
-            await provider.resetAuthorization(operatorDisconnected);
+            await reset;
         }
         finally {
             // Abandon any connect in flight and close whichever half of the
@@ -1195,22 +1210,32 @@ export function remoteMcp(id, opts) {
             const state = stateFor(ctx);
             state.provider = null;
             const p = newProvider(ctx, state);
-            if (startOpts?.force || (await p.operatorDisconnected())) {
-                await disconnectAuthorization(ctx, state);
+            if (ctx.signal?.aborted)
+                throw ctx.signal.reason;
+            const disconnected = startOpts?.force ? false : await p.operatorDisconnected();
+            if (ctx.signal?.aborted)
+                throw ctx.signal.reason;
+            if (startOpts?.force || disconnected) {
+                await disconnectAuthorization(ctx, state, false, startOpts?.force === true);
             }
             else {
                 // A consent URL already outstanding? Re-issue it rather than re-running
                 // the SDK flow, which would overwrite the PKCE verifier and invalidate
-                // the URL the operator may be mid-consent on.
-                const pending = await p.pendingAuthorizationUrl();
+                // the URL the operator may be mid-consent on. Only a recent one: an
+                // old or untimed URL falls through to a fresh flow in this same
+                // epoch, which keeps the stored client registration and discovery.
+                const pending = await p.reusablePendingAuthorizationUrl();
                 if (pending) {
                     return {
                         state: "auth_required",
                         authorizationUrl: pending,
+                        authorizationReused: true,
                         message: "Authorization required — open the URL to connect.",
                     };
                 }
             }
+            if (ctx.signal?.aborted)
+                throw ctx.signal.reason;
             try {
                 await ensureConnected(ctx, state);
                 return {

package/dist/execute.js

@@ -1118,20 +1118,19 @@ function connectorInventory(connectors) {
     return `${prefix}${shown.join(", ")}${shown.length > 0 ? "; " : ""}+${omitted} more.`;
 }
 const executeDescription = (emitBudgets, hostLimits, connectorGuides, connectors, resumable) => `Use the configured services below to answer the task. A known address uses call_tool. Unknown-address and wider ${resumable ? "work, writes included," : "read-only work"} uses one execute_code program for discovery, calls, and reduction. Do not return catalog matches alone. ${resumable
-    ? `Writes pause for resume_execution. Limits: ${hostLimits.maxHostCalls} host calls, ${resumable.maxWrites} writes`
+    ? `Writes pause for resume_execution. Keep an authorized batch in one program; approval "tool" covers later same-address calls, other approval-required writes pause separately. Limits: ${hostLimits.maxHostCalls} host calls, ${resumable.maxWrites} writes`
     : `Only readOnlyHint: true tools are available. Limits: ${hostLimits.maxHostCalls} host calls`}, ${hostLimits.hostCallTimeoutMs / 1_000}s/host call.
 
 ${connectorInventory(connectors)}
 
-Read guides with top-level skills. Write JavaScript as async () => { ... }; connecta is global, not a parameter:
-- connecta.search({ connector, query, ${resumable ? "" : 'safety: "readOnly", '}includeSchemas: "json" }) returns { tools }. Search each operation separately; choose by connectorTitle and schemas. Use schema.required and .properties to build args, never guessed fields. Compact schemas are text.
-- connecta.describe({ address }) returns { tools } for unclear schemas.
+Read guides with top-level skills. Write async () => { ... } using the global connecta:
+- connecta.search({ connector, query, ${resumable ? "" : 'safety: "readOnly", '}includeSchemas: "json" }) returns { tools }. Search operations separately; choose by connectorTitle and schema.required/.properties, never guessed fields. Compact schemas are text.
+- connecta.describe({ address }) clarifies schemas.
 - connecta.call(address, args) returns the provider value directly.
-- Use Promise.all for independent calls, or Promise.allSettled to retain failures. Check status before reading value; rejected calls and missing fields are unknown, never false or zero.
-- connecta.emit(block): { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }; success-only, ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes.
-- console.log(...) is captured. Return data for the client to render.
+- Use Promise.all for independent calls, or Promise.allSettled to retain failures. Check status; missing values are unknown, never false or zero.
+- connecta.emit(block): { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }; success-only, ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes. console.log(...) is captured.
 
-No portable ambient capabilities. Return reduced JSON. If a provider result has an unfamiliar shape, return a small sample and continue in another call; never guess fields or use the whole text as an id. Top-level skills({ name: "usage" }): repair${connectorGuides ? ", guide handling" : ""}; skills({ name: "investigate" }): task planning.`;
+No portable ambient capabilities. Return reduced JSON. Sample unfamiliar reads. Reduce a one-time write's full result here, or use a direct call and get_result paging; never repeat it to recover output. Never guess fields or use the whole text as an id. Top-level skills({ name: "usage" }): repair${connectorGuides ? ", guide handling" : ""}; skills({ name: "investigate" }): task planning.`;
 // Module scope, like the other six meta-tool inputs: its JSON Schema is
 // derived once per process. Budgets and connectors vary by deployment and
 // view, so they live in the description, never here.

package/dist/oauth-callback-outcome.js

@@ -1,9 +1,17 @@
 import { renderFixPrompt } from "./fix-prompt.js";
 const OUTCOMES = {
-    connected: { status: 200, message: "Connected. You can close this window." },
+    connected: {
+        status: 200,
+        tone: "ok",
+        heading: "{name} is connected",
+        message: "You can close this window.",
+        namesConnector: true,
+    },
     denied: {
         status: 400,
-        message: "Authorization was declined at the provider. Nothing was stored; start authorization again when you are ready.",
+        tone: "declined",
+        heading: "Authorization was declined",
+        message: "Consent was declined at the provider, so nothing was stored. Start authorization again whenever you are ready.",
         fix: {
             problem: "Consent for a downstream OAuth connector was declined at the provider, so no grant was stored.",
             steps: [
@@ -15,7 +23,9 @@ const OUTCOMES = {
     },
     provider_error: {
         status: 400,
-        message: "The provider returned an error instead of an authorization code. Nothing was stored.",
+        tone: "problem",
+        heading: "The provider returned an error",
+        message: "It sent back an error instead of an authorization code, so nothing was stored.",
         fix: {
             problem: "A provider redirected back to the OAuth callback with an OAuth error instead of an authorization code.",
             steps: [
@@ -27,7 +37,9 @@ const OUTCOMES = {
     },
     invalid_callback: {
         status: 400,
-        message: "Authorization could not be completed. The link may be expired, already used, or replaced by a newer attempt. Re-run authorization from connecta and try again.",
+        tone: "problem",
+        heading: "Authorization could not be completed",
+        message: "The link may be expired, already used, or replaced by a newer attempt. Start authorization again from {product}.",
         fix: {
             problem: "An OAuth callback arrived that the deployment could not match to an authorization flow it started: stale, already used, replaced by a newer attempt, or finished in a different session.",
             steps: [
@@ -39,7 +51,9 @@ const OUTCOMES = {
     },
     handoff_failed: {
         status: 500,
-        message: "Authorization could not be completed. Nothing was exchanged; try again shortly.",
+        tone: "problem",
+        heading: "{name} could not be connected",
+        message: "Authorization could not be completed, and nothing was exchanged. Try again shortly.",
         namesConnector: true,
         fix: {
             problem: "The deployment could not consume the stored principal handoff for a personal-auth OAuth flow, so no authorization code was exchanged.",
@@ -51,7 +65,9 @@ const OUTCOMES = {
     },
     exchange_failed: {
         status: 500,
-        message: "Authorization failed: the provider did not accept the authorization code exchange. Nothing was stored.",
+        tone: "problem",
+        heading: "{name} could not be connected",
+        message: "The provider did not accept the authorization code exchange. Nothing was stored.",
         namesConnector: true,
         fix: {
             problem: "A provider returned an authorization code, but exchanging it for tokens failed.",
@@ -63,7 +79,6 @@ const OUTCOMES = {
         },
     },
 };
-const CONNECTOR_ID_RE = /^[a-z0-9_-]+$/;
 /**
  * RFC 6749 names `access_denied` for a declined consent (section 4.1.2.1). Every other
  * value, standard or invented, is the provider refusing the request itself —
@@ -73,22 +88,32 @@ const CONNECTOR_ID_RE = /^[a-z0-9_-]+$/;
 export function providerErrorReason(error) {
     return error === "access_denied" ? "denied" : "provider_error";
 }
-/** Page copy and fix prompt for one reason. Nothing here reads the request. */
-export function oauthCallbackOutcome(reason, connectorId) {
+/**
+ * Page copy and fix prompt for one reason. Nothing here reads the request.
+ *
+ * `connector` is read only for a reason that sets `namesConnector`. The route
+ * passes one only once the state check has proved the flow, and this gate
+ * keeps a caller that passed one earlier from naming it anyway. `productName`
+ * is deployment configuration, the same for every connector, so it cannot
+ * tell one refusal from another.
+ */
+export function oauthCallbackOutcome(reason, connector, productName = "Connecta") {
     const outcome = OUTCOMES[reason];
-    // Success is reached only after the state check proved the id configured,
-    // so it is the one page that may name the connector in its copy.
-    const message = reason === "connected" && connectorId && CONNECTOR_ID_RE.test(connectorId)
-        ? `Connected "${connectorId}". You can close this window.`
-        : outcome.message;
+    const named = outcome.namesConnector ? connector : undefined;
+    const name = named ? displayName(named) : "The connection";
     return {
         reason,
         status: outcome.status,
-        message,
+        tone: outcome.tone,
+        heading: outcome.heading.replace("{name}", () => name),
+        message: outcome.message.replace("{product}", () => productName),
         ...(outcome.fix
-            ? {
-                fixPrompt: renderFixPrompt(outcome.fix, outcome.namesConnector ? connectorId : undefined),
-            }
+            ? { fixPrompt: renderFixPrompt(outcome.fix, named?.id) }
             : {}),
     };
 }
+/** A connector's title when it has a usable one, otherwise its id. */
+function displayName(connector) {
+    const title = typeof connector.title === "string" ? connector.title.trim() : "";
+    return title || connector.id;
+}