@agent-native/core 0.176.1 → 0.176.2-nightly-20260831184159

package/dist/server/core-routes-plugin.js

@@ -43,8 +43,8 @@ import { readAnalyticsClientPlatformHeader, readBrowserSessionIdHeader, } from "
 import { getConfiguredAppBasePath, stripAppBasePath } from "./app-base-path.js";
 import { getSession } from "./auth.js";
 import { getBetterAuthInternalAdapter, getBetterAuthSync, } from "./better-auth-instance.js";
-import { BUILDER_CONNECT_PARAM, BUILDER_CONNECT_MODE_PARAM, BUILDER_AGENT_NATIVE_PROVISION_MODE, BUILDER_PROVISIONING_TOKEN_PARAM, BUILDER_CONNECT_STATE_COOKIE, BUILDER_ENV_KEYS, BUILDER_OPENER_PARAM, BUILDER_RELAY_FLOW_HEADER, BUILDER_RELAY_SIGNATURE_HEADER, BUILDER_RELAY_STATE_PARAM, BUILDER_RELAY_TIMESTAMP_HEADER, appendBuilderConnectToken, appendBuilderConnectStateCookie, builderConnectTrackingProperties, createBuilderConnectState, createBuilderBrowserCallbackErrorPage, createBuilderBrowserCallbackPage, createBuilderRelayRequest, getBuilderConnectTrackingParams, getBuilderBrowserOriginForEvent, getBuilderBrowserStatusForEvent, isBuilderAccountProvisioningEnabled, isBuilderConnectCallbackUrlAllowed, isSignedBuilderConnectState, normalizeBuilderAgentContext, provisionBuilderAccount, resolveBuilderBranchProjectId, resolveBuilderConnectCallbackUrl, resolveBuilderConnectCallbackState, resolveBuilderPreviewRelayParentOrigin, removeBuilderConnectStateCookie, runBuilderAgent, verifyBuilderRelayRequest, verifyBuilderPreviewRelayStateForCallback, verifyBuilderConnectTokenAndGetOwner, signBuilderProvisioningToken, verifyBuilderProvisioningToken, } from "./builder-browser.js";
-import { BUILDER_ASSETS_WRITE_SCOPE, BUILDER_OAUTH_SCOPE, deleteBuilderOAuthSession, exchangeBuilderOAuthAuthorization, hasBuilderOAuthSession, resolveBuilderOAuthRequestAccess, saveBuilderOAuthCredentials, startBuilderOAuthAuthorization, } from "./builder-oauth.js";
+import { BUILDER_CONNECT_PARAM, BUILDER_CONNECT_MODE_PARAM, BUILDER_AGENT_NATIVE_PROVISION_MODE, BUILDER_PROVISIONING_TOKEN_PARAM, BUILDER_CONNECT_ATTEMPT_PARAM, BUILDER_CONNECT_STATE_COOKIE, BUILDER_ENV_KEYS, BUILDER_OPENER_PARAM, BUILDER_RELAY_FLOW_HEADER, BUILDER_RELAY_SIGNATURE_HEADER, BUILDER_RELAY_STATE_PARAM, BUILDER_RELAY_TIMESTAMP_HEADER, appendBuilderConnectToken, appendBuilderConnectStateCookie, builderConnectTrackingProperties, createBuilderConnectState, createBuilderBrowserCallbackErrorPage, createBuilderBrowserCallbackPage, createBuilderRelayRequest, getBuilderConnectTrackingParams, getBuilderBrowserOriginForEvent, getBuilderBrowserStatusForEvent, isBuilderAccountAlreadyExistsError, isBuilderAccountProvisioningEnabled, isBuilderConnectCallbackUrlAllowed, isSignedBuilderConnectState, normalizeBuilderAgentContext, provisionBuilderAccount, resolveBuilderBranchProjectId, resolveBuilderConnectCallbackUrl, resolveBuilderConnectCallbackState, resolveBuilderPreviewRelayParentOrigin, removeBuilderConnectStateCookie, runBuilderAgent, verifyBuilderRelayRequest, verifyBuilderPreviewRelayStateForCallback, verifyBuilderConnectTokenAndGetOwner, signBuilderProvisioningToken, verifyBuilderProvisioningToken, } from "./builder-browser.js";
+import { BUILDER_ASSETS_WRITE_SCOPE, BUILDER_OAUTH_SCOPE, deleteBuilderOAuthSession, exchangeBuilderOAuthAuthorization, getBuilderOAuthStoredScope, hasBuilderOAuthSession, resolveBuilderOAuthRequestAccess, saveBuilderOAuthCredentials, startBuilderOAuthAuthorization, } from "./builder-oauth.js";
 import { captureError, registerErrorCaptureProvider } from "./capture-error.js";
 import { resolveCoreRoutesMcpOptions, } from "./core-routes/mcp-connect-options.js";
 import { getAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
@@ -55,7 +55,7 @@ import { createEmbedStartRouteHandler } from "./embed-route.js";
 import { shouldReportError } from "./error-noise-filter.js";
 import { FRAMEWORK_AUTH_EARLY_PATHS, getH3App, awaitBootstrap, markDefaultPluginProvided, markFrameworkRoutesReadyBeforeBootstrap, trackPluginInit, } from "./framework-request-handler.js";
 import { createGatewayAccessCheckHandler } from "./gateway-access-check.js";
-import { checkGoogleSignInCredential } from "./google-credential-check.js";
+import { checkGoogleManagedCredential, checkGoogleSignInCredential, } from "./google-credential-check.js";
 import { getAppBasePath, getOrigin } from "./google-oauth.js";
 import { createGoogleRealtimeSessionHandler } from "./google-realtime-session.js";
 import { readBody, DEFAULT_UPLOAD_MAX_FILE_BYTES, isAllowedUploadMimeType, } from "./h3-helpers.js";
@@ -111,16 +111,19 @@ export async function resolveAgentEngineStatus(deps) {
     const configuredEngine = getAppConfig().agent.engine;
     const envEntry = configuredEngine ? lookupEntry(configuredEngine) : undefined;
     if (envEntry) {
-        if (!(await deps.isStoredEngineUsable({ engine: envEntry.name }, envEntry)))
+        if (await deps.isStoredEngineUsable({ engine: envEntry.name }, envEntry)) {
+            return {
+                configured: true,
+                engine: envEntry.name,
+                model: envEntry.defaultModel ?? DEFAULT_MODEL,
+                source: "env",
+                envVar: "AGENT_ENGINE",
+                openAiBaseUrlConfigured,
+            };
+        }
+        if (getRequestContext()?.isSyntheticTraffic !== true) {
             return { configured: false, openAiBaseUrlConfigured };
-        return {
-            configured: true,
-            engine: envEntry.name,
-            model: envEntry.defaultModel ?? DEFAULT_MODEL,
-            source: "env",
-            envVar: "AGENT_ENGINE",
-            openAiBaseUrlConfigured,
-        };
+        }
     }
     // Stored provider selections win over an existing Builder connection, so
     // this is checked before the app_secrets sweep — and the sweep is skipped
@@ -164,29 +167,6 @@ export async function resolveAgentEngineStatus(deps) {
     }
     return { configured: false, openAiBaseUrlConfigured };
 }
-const _agentEngineStatusInFlight = new Map();
-/**
- * Share one in-flight status resolution between concurrent probes of the same
- * identity. Several client surfaces probe this route on mount and the client
- * retries after its own timeout; without this each probe re-ran the whole
- * credential sweep. The entry is dropped as soon as the lookup settles, so a
- * joiner never sees an answer older than one lookup — no TTL, nothing to
- * invalidate when a provider is added or removed. The key carries the identity
- * that decides the answer, so no tenant can read another's result.
- */
-export function shareAgentEngineStatusLookup(identityKey, compute) {
-    const existing = _agentEngineStatusInFlight.get(identityKey);
-    if (existing)
-        return existing;
-    const started = compute().finally(() => {
-        _agentEngineStatusInFlight.delete(identityKey);
-    });
-    _agentEngineStatusInFlight.set(identityKey, started);
-    return started;
-}
-export function agentEngineStatusIdentityKey(userEmail, orgId) {
-    return `${userEmail ?? ""}\u0000${orgId ?? ""}`;
-}
 function requestAgentEngineStatusDeps() {
     return {
         readStoredEngine: async () => (await getSetting("agent-engine")),
@@ -225,14 +205,12 @@ async function resolveAgentEngineStatusIdentity(event) {
     }
 }
 /**
- * A Builder grant is shared by everyone in the caller's org, so establishing,
- * overwriting, or revoking one requires org owner/admin authority. Returns the
- * authorized org id and a denial message (null when allowed). The org id is
- * captured at connect start so the grant is stored under the org that was
- * authorized, not one re-resolved after the OAuth round trip. Fails closed: an
- * unreadable owner/admin role is denied.
+ * Shared Builder grants stay org-scoped, but connect initiation can come from
+ * any authenticated member. Revocation still needs owner/admin authority.
+ * Capture the org id at connect start so the grant is stored under the org
+ * that was authorized, not one re-resolved after the OAuth round trip.
  */
-async function resolveBuilderOrgMutation(event) {
+export async function resolveBuilderOrgMutation(event, options = {}) {
     let orgId = null;
     let role = null;
     try {
@@ -243,13 +221,23 @@ async function resolveBuilderOrgMutation(event) {
     catch {
         // coercion-ok: org is missing, it will fail closed
     }
+    if (options.allowMemberInitiation) {
+        if (orgId)
+            return { orgId, role, deny: null };
+        return {
+            orgId,
+            role,
+            deny: "Only signed-in organization members can connect Builder.",
+        };
+    }
     if (role !== "owner" && role !== "admin") {
         return {
             orgId,
+            role,
             deny: "Only an organization owner or admin can change the shared Builder connection.",
         };
     }
-    return { orgId, deny: null };
+    return { orgId, role, deny: null };
 }
 export function getFrameworkEnvKeys() {
     return [
@@ -857,6 +845,16 @@ function redactValues(text, values) {
     }
     return out;
 }
+const DEFAULT_GOOGLE_OAUTH_CALLBACK_PATH = "/_agent-native/google/callback";
+const GOOGLE_OAUTH_CALLBACK_PATH_PATTERN = /^\/_agent-native\/[A-Za-z0-9._/-]+\/callback$/;
+function normalizeGoogleOAuthCallbackPaths(paths) {
+    const values = [...new Set(paths ?? [DEFAULT_GOOGLE_OAUTH_CALLBACK_PATH])];
+    if (values.length === 0 ||
+        values.some((value) => !GOOGLE_OAUTH_CALLBACK_PATH_PATTERN.test(value))) {
+        throw new Error("googleOAuthCallbackPaths must contain /_agent-native/*/callback paths.");
+    }
+    return values;
+}
 export async function readLegacyCoreRouteInitSettings(readSetting = getSetting) {
     const readOrNull = async (key) => {
         try {
@@ -994,6 +992,9 @@ export async function resolveOAuthCustodyBuilderKeyStatus(dependencies = {
     }
 }
 export function createCoreRoutesPlugin(options = {}) {
+    const googleOAuthCallbackPaths = normalizeGoogleOAuthCallbackPaths(options.googleOAuthCallbackPaths);
+    const googleOAuthCredentialMode = options.googleOAuthCredentialMode ?? "managed";
+    const googleOAuthManagedConnection = options.googleOAuthManagedConnection ?? "unknown";
     return async (nitroApp) => {
         markDefaultPluginProvided(nitroApp, "core-routes");
         // No-op when called from inside the bootstrap (auto-mount path).
@@ -1073,12 +1074,37 @@ export function createCoreRoutesPlugin(options = {}) {
                 // health handler would otherwise swallow this path.
                 getH3App(nitroApp).use(`${P}/health/google`, defineEventHandler(async (event) => {
                     setResponseHeader(event, "cache-control", "no-store");
-                    const result = await checkGoogleSignInCredential();
+                    const result = event.url?.searchParams.get("client") === "managed"
+                        ? googleOAuthManagedConnection === "not_applicable"
+                            ? {
+                                status: "unconfigured",
+                                clientId: null,
+                                mismatchedPairs: false,
+                                credentialSource: "none",
+                                reason: "this app does not expose deployment-level Google OAuth",
+                                checkedAt: Date.now(),
+                            }
+                            : googleOAuthCredentialMode === "user"
+                                ? {
+                                    status: "unconfigured",
+                                    clientId: null,
+                                    mismatchedPairs: false,
+                                    credentialSource: "user",
+                                    reason: "user-scoped OAuth credentials are checked after authentication",
+                                    checkedAt: Date.now(),
+                                }
+                                : await checkGoogleManagedCredential()
+                        : await checkGoogleSignInCredential();
                     // `invalid` is the fleet-wide outage shape: the deploy is up and
                     // healthy while nobody can sign in. Page on it.
                     if (result.status === "invalid")
                         setResponseStatus(event, 503);
-                    return result;
+                    return {
+                        ...result,
+                        callbackPaths: googleOAuthCallbackPaths,
+                        credentialMode: googleOAuthCredentialMode,
+                        managedConnection: googleOAuthManagedConnection,
+                    };
                 }));
                 getH3App(nitroApp).use(`${P}/health`, defineEventHandler(async (event) => {
                     setResponseHeader(event, "cache-control", "no-store");
@@ -1567,6 +1593,8 @@ export function createCoreRoutesPlugin(options = {}) {
                     }
                 }
                 return runWithRequestContext({ userEmail, orgId: orgId ?? undefined }, async () => {
+                    const requestUrl = getFrameworkRouteRequestUrl(event);
+                    const connectAttemptId = requestUrl.searchParams.get(BUILDER_CONNECT_ATTEMPT_PARAM);
                     const projectId = await resolveBuilderBranchProjectId();
                     const requestStatus = {
                         ...envStatus,
@@ -1582,8 +1610,16 @@ export function createCoreRoutesPlugin(options = {}) {
                         if (userEmail) {
                             const errKey = `builder-connect-error:${userEmail}`;
                             const errRow = await getSetting(errKey);
-                            if (errRow && typeof errRow.message === "string") {
-                                await deleteSetting(errKey).catch(() => { });
+                            const isCorrelatedProvisioningError = errRow?.code === "account_exists" &&
+                                typeof connectAttemptId === "string" &&
+                                errRow.attemptId === connectAttemptId;
+                            const isLegacyConnectError = errRow?.code !== "account_exists";
+                            if (errRow &&
+                                typeof errRow.message === "string" &&
+                                (isCorrelatedProvisioningError || isLegacyConnectError)) {
+                                if (isLegacyConnectError) {
+                                    await deleteSetting(errKey).catch(() => { });
+                                }
                                 return withConnectToken({
                                     ...requestStatus,
                                     configured: false,
@@ -1602,6 +1638,9 @@ export function createCoreRoutesPlugin(options = {}) {
                                         at: typeof errRow.at === "number"
                                             ? errRow.at
                                             : Date.now(),
+                                        ...(typeof errRow.code === "string"
+                                            ? { code: errRow.code }
+                                            : {}),
                                     },
                                 });
                             }
@@ -1614,7 +1653,7 @@ export function createCoreRoutesPlugin(options = {}) {
                         let oauthAccess = null;
                         let hasOAuthCustody = false;
                         try {
-                            hasOAuthCustody = await hasBuilderOAuthSession(userEmail);
+                            hasOAuthCustody = await hasBuilderOAuthSession(userEmail, orgId);
                         }
                         catch {
                             return withConnectToken({
@@ -1634,6 +1673,7 @@ export function createCoreRoutesPlugin(options = {}) {
                                 oauthAccess = await resolveBuilderOAuthRequestAccess({
                                     ownerEmail: userEmail,
                                     requiredScope: BUILDER_OAUTH_SCOPE,
+                                    orgId,
                                 });
                             }
                             catch {
@@ -1852,6 +1892,8 @@ export function createCoreRoutesPlugin(options = {}) {
             //      the cookie. The callback still requires the matching session,
             //      pending row, and a successful PKCE exchange before persistence.
             getH3App(nitroApp).use(`${P}/builder/connect`, defineEventHandler(async (event) => {
+                const requestUrl = getFrameworkRouteRequestUrl(event);
+                const connectAttemptId = requestUrl.searchParams.get(BUILDER_CONNECT_ATTEMPT_PARAM);
                 const ownerContext = await resolveBuilderOwnerContext(event, "connect");
                 const ownerEmail = ownerContext.email;
                 if (!ownerEmail) {
@@ -1866,9 +1908,9 @@ export function createCoreRoutesPlugin(options = {}) {
                         title: "Sign in required",
                         body: "Builder OAuth is tied to a signed-in account. Sign in, then try Connect Builder again.",
                         parentOrigin: getBuilderBrowserOriginForEvent(event),
+                        ...(connectAttemptId ? { attemptId: connectAttemptId } : {}),
                     });
                 }
-                const requestUrl = getFrameworkRouteRequestUrl(event);
                 const connectToken = requestUrl.searchParams.get(BUILDER_CONNECT_PARAM);
                 const connectTokenOwner = verifyBuilderConnectTokenAndGetOwner(connectToken);
                 const connectTracking = getBuilderConnectTrackingParams(requestUrl.searchParams);
@@ -1896,6 +1938,7 @@ export function createCoreRoutesPlugin(options = {}) {
                     await putSetting(`builder-connect-error:${ownerEmail}`, {
                         message: crossOriginMessage,
                         at: Date.now(),
+                        ...(connectAttemptId ? { attemptId: connectAttemptId } : {}),
                     }).catch(() => { });
                     console.warn("[builder-connect] rejected cross-origin connect", {
                         hasConnectToken: Boolean(connectToken),
@@ -1910,15 +1953,18 @@ export function createCoreRoutesPlugin(options = {}) {
                         body: "The connect popup did not include a valid signed link for this app.",
                         closeHint: "Close this popup, refresh the app, and try Connect account again.",
                         parentOrigin: getBuilderBrowserOriginForEvent(event),
+                        ...(connectAttemptId ? { attemptId: connectAttemptId } : {}),
                     });
                 }
                 const shouldProvisionAgentNativeAccount = requestUrl.searchParams.get(BUILDER_CONNECT_MODE_PARAM) ===
                     BUILDER_AGENT_NATIVE_PROVISION_MODE;
                 if (shouldProvisionAgentNativeAccount) {
-                    const failProvisioning = async (status, message, reason) => {
+                    const failProvisioning = async (status, message, reason, code) => {
                         await putSetting(`builder-connect-error:${ownerEmail}`, {
                             message,
                             at: Date.now(),
+                            ...(code ? { code } : {}),
+                            ...(connectAttemptId ? { attemptId: connectAttemptId } : {}),
                         }).catch(() => { });
                         await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
                             ...builderConnectTrackingProperties(connectTracking),
@@ -1929,6 +1975,8 @@ export function createCoreRoutesPlugin(options = {}) {
                         setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
                         return createBuilderBrowserCallbackErrorPage(message, {
                             parentOrigin: getBuilderBrowserOriginForEvent(event),
+                            ...(connectAttemptId ? { attemptId: connectAttemptId } : {}),
+                            ...(code ? { code } : {}),
                         });
                     };
                     if (!isBuilderAccountProvisioningEnabled()) {
@@ -1961,10 +2009,16 @@ export function createCoreRoutesPlugin(options = {}) {
                         const parentOrigin = getBuilderBrowserOriginForEvent(event);
                         setResponseHeader(event, "Cache-Control", "no-store");
                         setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                        return createBuilderBrowserCallbackPage(`${parentOrigin}${getAppBasePath() || "/"}`, { parentOrigin });
+                        return createBuilderBrowserCallbackPage(`${parentOrigin}${getAppBasePath() || "/"}`, {
+                            parentOrigin,
+                            ...(connectAttemptId ? { attemptId: connectAttemptId } : {}),
+                        });
                     }
                     catch (error) {
                         console.error("[builder] Agent-Native account provisioning failed:", error instanceof Error ? error.message : error);
+                        if (isBuilderAccountAlreadyExistsError(error)) {
+                            return failProvisioning(409, "A Builder account already exists for this email. Log in to connect it.", "account_exists", "account_exists");
+                        }
                         return failProvisioning(502, "Couldn't create your Builder account. Try again or connect an existing account.", "provision_failed");
                     }
                 }
@@ -1988,9 +2042,12 @@ export function createCoreRoutesPlugin(options = {}) {
                         title: "Builder connection is unavailable here",
                         body: "Open this app on its public HTTPS URL, then try again.",
                         parentOrigin: getBuilderBrowserOriginForEvent(event),
+                        ...(connectAttemptId ? { attemptId: connectAttemptId } : {}),
                     });
                 }
-                const { orgId: connectOrgId, deny: orgConnectDenied } = await resolveBuilderOrgMutation(event);
+                const { orgId: connectOrgId, role: connectRole, deny: orgConnectDenied, } = await resolveBuilderOrgMutation(event, {
+                    allowMemberInitiation: true,
+                });
                 if (orgConnectDenied) {
                     await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
                         ...builderConnectTrackingProperties(connectTracking),
@@ -2001,8 +2058,9 @@ export function createCoreRoutesPlugin(options = {}) {
                     setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
                     return createBuilderBrowserCallbackErrorPage(orgConnectDenied, {
                         title: "Not allowed to connect Builder for this organization",
-                        body: "Ask an organization owner or admin to connect Builder.",
+                        body: orgConnectDenied,
                         parentOrigin: getBuilderBrowserOriginForEvent(event),
+                        ...(connectAttemptId ? { attemptId: connectAttemptId } : {}),
                     });
                 }
                 // The standard OAuth client discovers Builder's protected-resource
@@ -2021,11 +2079,12 @@ export function createCoreRoutesPlugin(options = {}) {
                     await putSetting(`builder-connect-pending:${state}`, {
                         ownerEmail,
                         orgId: connectOrgId,
-                        role: null,
+                        role: connectRole,
                         encryptedOAuthFlow: encryptSecretValue(JSON.stringify(oauthFlow)),
                         redirectUri: callbackUrl,
                         expiresAt: Date.now() + BUILDER_CONNECT_PENDING_TTL_MS,
                         tracking: connectTracking,
+                        ...(connectAttemptId ? { attemptId: connectAttemptId } : {}),
                     });
                     await purgeExpiredBuilderConnectPendingStates().catch(() => 0); // coercion-ok: connect already persisted the new pending row; purge of abandoned rows must not fail OAuth start
                     setCookie(event, BUILDER_CONNECT_STATE_COOKIE, appendBuilderConnectStateCookie(getCookie(event, BUILDER_CONNECT_STATE_COOKIE), state), {
@@ -2049,11 +2108,13 @@ export function createCoreRoutesPlugin(options = {}) {
                     await putSetting(`builder-connect-error:${ownerEmail}`, {
                         message: msg,
                         at: Date.now(),
+                        ...(connectAttemptId ? { attemptId: connectAttemptId } : {}),
                     }).catch(() => { });
                     setResponseStatus(event, 503);
                     setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
                     return createBuilderBrowserCallbackErrorPage(msg, {
                         parentOrigin: getBuilderBrowserOriginForEvent(event),
+                        ...(connectAttemptId ? { attemptId: connectAttemptId } : {}),
                     });
                 }
                 await trackBuilderLifecycle(event, "builder connect started", ownerEmail, {
@@ -2248,6 +2309,7 @@ export function createCoreRoutesPlugin(options = {}) {
                 setResponseHeader(event, "Pragma", "no-cache");
                 setResponseHeader(event, "Referrer-Policy", "no-referrer");
                 const requestUrl = getFrameworkRouteRequestUrl(event);
+                const requestConnectAttemptId = requestUrl.searchParams.get(BUILDER_CONNECT_ATTEMPT_PARAM);
                 const relayStateRaw = requestUrl.searchParams.get(BUILDER_RELAY_STATE_PARAM);
                 if (relayStateRaw) {
                     let relayPayload = null;
@@ -2262,7 +2324,9 @@ export function createCoreRoutesPlugin(options = {}) {
                     if (!relayPayload) {
                         setResponseStatus(event, 403);
                         setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                        return createBuilderBrowserCallbackErrorPage("Builder preview relay state is invalid or expired.");
+                        return createBuilderBrowserCallbackErrorPage("Builder preview relay state is invalid or expired.", requestConnectAttemptId
+                            ? { attemptId: requestConnectAttemptId }
+                            : undefined);
                     }
                     const relayOpenerOrigin = requestUrl.searchParams.get(BUILDER_OPENER_PARAM);
                     const relayParentOrigin = resolveBuilderPreviewRelayParentOrigin({
@@ -2274,7 +2338,12 @@ export function createCoreRoutesPlugin(options = {}) {
                     if (!privateKey || !publicKey) {
                         setResponseStatus(event, 400);
                         setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                        return createBuilderBrowserCallbackErrorPage("Builder didn't return credentials. Restart the connect flow from settings.", { parentOrigin: relayParentOrigin });
+                        return createBuilderBrowserCallbackErrorPage("Builder didn't return credentials. Restart the connect flow from settings.", {
+                            parentOrigin: relayParentOrigin,
+                            ...(requestConnectAttemptId
+                                ? { attemptId: requestConnectAttemptId }
+                                : {}),
+                        });
                     }
                     const credentials = {
                         privateKey,
@@ -2309,10 +2378,18 @@ export function createCoreRoutesPlugin(options = {}) {
                         setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
                         return createBuilderBrowserCallbackErrorPage(message, {
                             parentOrigin: relayParentOrigin,
+                            ...(requestConnectAttemptId
+                                ? { attemptId: requestConnectAttemptId }
+                                : {}),
                         });
                     }
                     setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                    return createBuilderBrowserCallbackPage(`${relayParentOrigin}${relayPayload.basePath || "/"}`, { parentOrigin: relayParentOrigin });
+                    return createBuilderBrowserCallbackPage(`${relayParentOrigin}${relayPayload.basePath || "/"}`, {
+                        parentOrigin: relayParentOrigin,
+                        ...(requestConnectAttemptId
+                            ? { attemptId: requestConnectAttemptId }
+                            : {}),
+                    });
                 }
                 // Builder sometimes drops the top-level OAuth state. Recover it
                 // from the host-only cookie set by /builder/connect; the pending row
@@ -2320,11 +2397,13 @@ export function createCoreRoutesPlugin(options = {}) {
                 const queryState = requestUrl.searchParams.get("state");
                 const state = resolveBuilderConnectCallbackState(queryState, getCookie(event, BUILDER_CONNECT_STATE_COOKIE));
                 const parentOrigin = getBuilderBrowserOriginForEvent(event);
+                let callbackAttemptId = requestConnectAttemptId;
                 const fail = async (status, message, ownerEmail, reason, tracking = {}) => {
                     if (ownerEmail) {
                         await putSetting(`builder-connect-error:${ownerEmail}`, {
                             message,
                             at: Date.now(),
+                            ...(callbackAttemptId ? { attemptId: callbackAttemptId } : {}),
                         }).catch(() => { });
                         await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
                             ...builderConnectTrackingProperties(tracking),
@@ -2336,6 +2415,7 @@ export function createCoreRoutesPlugin(options = {}) {
                     setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
                     return createBuilderBrowserCallbackErrorPage(message, {
                         parentOrigin,
+                        ...(callbackAttemptId ? { attemptId: callbackAttemptId } : {}),
                     });
                 };
                 if (!state || !isSignedBuilderConnectState(state)) {
@@ -2345,6 +2425,10 @@ export function createCoreRoutesPlugin(options = {}) {
                 if (!pending) {
                     return fail(403, "No active Builder connect flow found. Restart the connection from Settings.");
                 }
+                callbackAttemptId =
+                    typeof pending.attemptId === "string"
+                        ? pending.attemptId
+                        : callbackAttemptId;
                 const ownerEmail = typeof pending.ownerEmail === "string" ? pending.ownerEmail : null;
                 const tracking = pending.tracking && typeof pending.tracking === "object"
                     ? pending.tracking
@@ -2395,10 +2479,24 @@ export function createCoreRoutesPlugin(options = {}) {
                 // PKCE proves the callback belongs to this flow before its pending
                 // row is consumed. Persist first so a transient credential-store
                 // failure does not strand an otherwise valid pending flow.
+                let callbackRole = null;
+                if (pending.role === "owner" || pending.role === "admin") {
+                    // Re-check authority after the external OAuth round trip. A role
+                    // captured at connect start must not authorize a later org write.
+                    const currentOrg = await resolveBuilderOrgMutation(event, {
+                        allowMemberInitiation: true,
+                    });
+                    if (currentOrg.orgId === pending.orgId &&
+                        (currentOrg.role === "owner" || currentOrg.role === "admin")) {
+                        callbackRole = currentOrg.role;
+                    }
+                }
+                let credentialScope = "user";
                 try {
-                    await saveBuilderOAuthCredentials({
+                    credentialScope = await saveBuilderOAuthCredentials({
                         ownerEmail,
                         orgId: typeof pending.orgId === "string" ? pending.orgId : undefined,
+                        role: callbackRole,
                         credentials,
                     });
                 }
@@ -2434,10 +2532,13 @@ export function createCoreRoutesPlugin(options = {}) {
                 await trackBuilderLifecycle(event, "builder connect succeeded", ownerEmail, {
                     ...builderConnectTrackingProperties(tracking),
                     stage: "callback",
-                    credential_scope: "user",
+                    credential_scope: credentialScope,
                 });
                 setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                return createBuilderBrowserCallbackPage(`${parentOrigin}${getAppBasePath() || "/"}`, { parentOrigin });
+                return createBuilderBrowserCallbackPage(`${parentOrigin}${getAppBasePath() || "/"}`, {
+                    parentOrigin,
+                    ...(callbackAttemptId ? { attemptId: callbackAttemptId } : {}),
+                });
             }));
             // POST /_agent-native/builder/disconnect — remove this user's OAuth
             // custody. Legacy BUILDER_* secrets are cleared at user scope when OAuth
@@ -2454,19 +2555,6 @@ export function createCoreRoutesPlugin(options = {}) {
                     return { error: "unauthorized" };
                 }
                 try {
-                    const hadOAuth = await hasBuilderOAuthSession(session.email);
-                    // Revoking an org-scoped grant takes the connection offline for
-                    // every member, so require org owner/admin before doing so.
-                    if (hadOAuth) {
-                        const { deny } = await resolveBuilderOrgMutation(event);
-                        if (deny) {
-                            setResponseStatus(event, 403);
-                            return { error: deny };
-                        }
-                    }
-                    const oauthResult = hadOAuth
-                        ? await deleteBuilderOAuthSession(session.email)
-                        : { localDeleted: false, remoteRevoked: false };
                     const { deleteBuilderCredentials } = await import("./credential-provider.js");
                     let orgId = null;
                     let role = null;
@@ -2479,7 +2567,21 @@ export function createCoreRoutesPlugin(options = {}) {
                     catch {
                         // coercion-ok: org module is optional; disconnect still clears user-scoped custody.
                     }
-                    await deleteBuilderCredentials(session.email, hadOAuth ? undefined : { orgId, role });
+                    const oauthScope = await getBuilderOAuthStoredScope(session.email, orgId);
+                    const hadOAuth = oauthScope !== null;
+                    // Revoking an org-scoped grant takes the connection offline for
+                    // every member, so require org owner/admin before doing so.
+                    if (oauthScope === "org") {
+                        const { deny } = await resolveBuilderOrgMutation(event);
+                        if (deny) {
+                            setResponseStatus(event, 403);
+                            return { error: deny };
+                        }
+                    }
+                    const oauthResult = oauthScope
+                        ? await deleteBuilderOAuthSession(session.email, oauthScope, orgId)
+                        : { localDeleted: false, remoteRevoked: false };
+                    await deleteBuilderCredentials(session.email, oauthScope ? undefined : { orgId, role });
                     await trackBuilderLifecycle(event, "builder disconnect succeeded", session.email, {
                         oauth_present: hadOAuth,
                         remote_revoked: hadOAuth
@@ -2636,7 +2738,7 @@ export function createCoreRoutesPlugin(options = {}) {
             getH3App(nitroApp).use(`${P}/agent-engine/status`, defineEventHandler(async (event) => {
                 try {
                     const { userEmail, orgId } = await resolveAgentEngineStatusIdentity(event);
-                    return await shareAgentEngineStatusLookup(agentEngineStatusIdentityKey(userEmail, orgId), () => Promise.resolve(runWithRequestContext({ userEmail, orgId }, () => resolveAgentEngineStatus(requestAgentEngineStatusDeps()))));
+                    return await runWithRequestContext({ userEmail, orgId }, () => resolveAgentEngineStatus(requestAgentEngineStatusDeps()));
                 }
                 catch (err) {
                     // NOT `{ configured: false }`. A 200 saying "not configured" is an
@@ -3376,4 +3478,6 @@ export function createCoreRoutesPlugin(options = {}) {
  * export { defaultCoreRoutesPlugin as default } from "@agent-native/core/server";
  * ```
  */
-export const defaultCoreRoutesPlugin = createCoreRoutesPlugin();
+export const defaultCoreRoutesPlugin = createCoreRoutesPlugin({
+    googleOAuthManagedConnection: "not_applicable",
+});

package/dist/server/credential-provider.js

@@ -23,7 +23,7 @@ import { getAppConfig } from "../app-config/index.js";
 import { getDbExec, isLocalDatabase, isTransientDatabaseError, } from "../db/client.js";
 import { getOrgSetting } from "../settings/org-settings.js";
 import { isTruthyRuntimeValue } from "../shared/runtime-config.js";
-import { getRequestUserEmail, getRequestOrgId } from "./request-context.js";
+import { getRequestContext, getRequestUserEmail, getRequestOrgId, } from "./request-context.js";
 const DISPATCH_VAULT_ACCESS_SETTINGS_KEY = "dispatch-vault-access-settings";
 /**
  * The designated vault fallback is an all-apps compatibility path. Manual
@@ -179,6 +179,11 @@ export function isDeployCredentialFallbackAllowed() {
     return isLocalDatabase();
 }
 export function canUseDeployCredentialFallbackForRequest(key) {
+    // Synthetic checks must never fall through to a deploy-wide provider key.
+    // If the dedicated test credential is rejected, using the site's shared key
+    // would make a green retry both misleading and billable to real traffic.
+    if (getRequestContext()?.isSyntheticTraffic === true)
+        return false;
     const email = getRequestUserEmail();
     if (!email)
         return true;
@@ -1245,17 +1250,17 @@ export async function prefetchSecrets(keys) {
     if (!email || keys.length === 0)
         return;
     const { readAppSecrets } = await import("../secrets/storage.js");
-    const orgId = getRequestOrgId() || (await resolveOrgIdForRequestEmail(email)).orgId;
-    const scopes = [
-        { scope: "user", scopeId: email },
-        ...(orgId
-            ? [
-                { scope: "org", scopeId: orgId },
-                { scope: "workspace", scopeId: orgId },
-            ]
-            : []),
-        { scope: "workspace", scopeId: `solo:${email}` },
-    ];
+    const syntheticTraffic = getRequestContext()?.isSyntheticTraffic === true;
+    const orgId = syntheticTraffic
+        ? undefined
+        : getRequestOrgId() || (await resolveOrgIdForRequestEmail(email)).orgId;
+    const scopes = [{ scope: "user", scopeId: email }];
+    if (orgId && !syntheticTraffic) {
+        scopes.push({ scope: "org", scopeId: orgId }, { scope: "workspace", scopeId: orgId });
+    }
+    if (!syntheticTraffic) {
+        scopes.push({ scope: "workspace", scopeId: `solo:${email}` });
+    }
     await Promise.all(scopes.map((s) => readAppSecrets({ keys, ...s }).catch(() => undefined)));
 }
 /**
@@ -1411,6 +1416,7 @@ export async function resolveSecretPair(keys, options) {
 export async function resolveSecretDetailed(key) {
     const traceLookup = shouldTraceCredentialResolve();
     const email = getRequestUserEmail();
+    const syntheticTraffic = getRequestContext()?.isSyntheticTraffic === true;
     let lookupFailed = false;
     let cause;
     if (email) {
@@ -1428,6 +1434,10 @@ export async function resolveSecretDetailed(key) {
                 }
                 return { value: userSecret.value, lookupFailed: false };
             }
+            // The beta suite writes one user-scoped credential and must never turn a
+            // rejected or missing test key into a charge against a shared scope.
+            if (syntheticTraffic)
+                return NOT_FOUND;
             // Mirrors resolveScopedBuilderCredential: a transient org_members read
             // failure makes getOrgContext report no org, which would otherwise hide
             // an org-scoped vault row behind an intermittent "not configured" error.

package/dist/server/email.d.ts

@@ -32,6 +32,10 @@ export interface SendEmailArgs {
     subject: string;
     html: string;
     text?: string;
+    /** Keep security-sensitive links out of provider click-tracking redirects. */
+    disableClickTracking?: boolean;
+    /** Use deployment credentials for process-owned sends, not request-scoped overrides. */
+    useDeploymentCredentials?: boolean;
     from?: string;
     /**
      * Display-name-only override. Keeps the configured (domain-verified) sending