@agent-native/core 0.159.5 → 0.160.1

package/dist/server/agent-chat-plugin.js

@@ -814,11 +814,11 @@ export function createAgentChatPlugin(options) {
             try {
                 if (webGroupEnabled) {
                     const { createWebSearchToolEntry } = await import("../extensions/web-search-tool.js");
-                    const { getBuilderWebSearchBaseUrl, resolveBuilderCredentials, resolveSecret, } = await import("./credential-provider.js");
+                    const { getBuilderWebSearchBaseUrl, resolveBuilderGatewayCredentials, resolveSecret, } = await import("./credential-provider.js");
                     const { getBuilderGatewayRequestHeaders } = await import("../agent/engine/builder-gateway-headers.js");
                     webSearchTool = createWebSearchToolEntry({
                         resolveSecret,
-                        resolveBuilderCredentials,
+                        resolveBuilderCredentials: resolveBuilderGatewayCredentials,
                         getBuilderWebSearchBaseUrl,
                         getBuilderRequestHeaders: getBuilderGatewayRequestHeaders,
                     });
@@ -4161,6 +4161,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     const workerClaim = run.runId
                         ? await readBackgroundRunClaim(run.runId).catch(() => null)
                         : null;
+                    const { isBuilderGatewayDeployConfigured } = await import("./credential-provider.js");
                     return {
                         active: true,
                         runId: run.runId,
@@ -4177,6 +4178,12 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         // `/runs/active?threadId=...` and inspect `diagStage`.
                         dispatchMode: run.dispatchMode ?? null,
                         terminalReason: run.terminalReason ?? null,
+                        // Who is paying for AI here, which is also who is reading a
+                        // failure. `terminalReason` is a bare error CODE, and the client
+                        // owns the copy for the handoff failures that never produce an
+                        // error event — so without this it has to author credential copy
+                        // for a reader it cannot identify, and picks the owner's.
+                        deploymentPaysForAi: isBuilderGatewayDeployConfigured(),
                         diagStage: run.diagStage ?? null,
                         workerStage: workerClaim?.workerStage ?? null,
                         // Server clock so the client computes "stuck" elapsed time

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,10 +27,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
-    error?: undefined;
 }>>;
 export {};

package/dist/server/credential-provider.d.ts

@@ -83,6 +83,10 @@ export declare function readDeployCredentialEnv(key: string): string | undefined
  */
 export declare function isDeployCredentialFallbackAllowed(): boolean;
 export declare function canUseDeployCredentialFallbackForRequest(key?: string): boolean;
+/** The raw `btk-` gateway PAT a Builder-credits deploy injects. */
+export declare const BUILDER_GATEWAY_TOKEN_ENV_VAR = "BUILDER_GATEWAY_TOKEN";
+/** The space id that pairs with it, sent as `x-builder-api-key`. */
+export declare const BUILDER_GATEWAY_SPACE_ID_ENV_VAR = "BUILDER_GATEWAY_SPACE_ID";
 type BuilderCredentialSource = "user" | "org" | "workspace" | "env";
 export declare function isBuilderPrivateKey(value: string | null | undefined): boolean;
 export interface BuilderCredentialLookupIdentity {
@@ -177,6 +181,67 @@ export declare function resolveBuilderCredentials(identity?: BuilderCredentialLo
     isEnterprise: boolean | null;
     isFreeAccount: boolean | null;
 }>;
+/** `gateway-deploy` means the site pays, so owner-facing copy must not be shown. */
+export type BuilderGatewayLane = "identity" | "gateway-deploy";
+export interface BuilderGatewayCredentialsDetailed extends BuilderCredentialsDetailed {
+    lane: BuilderGatewayLane | null;
+}
+/**
+ * Both halves required: the gateway 403s a token with no space id before it
+ * consults any route policy, so half a pair is not a usable credential.
+ */
+export declare function resolveUsableBuilderGatewayDeployCredentials(): Promise<{
+    token: string;
+    spaceId: string;
+} | null>;
+/**
+ * Weaker than "usable" on purpose: a present-but-rejected token still means the
+ * reader is a visitor. Excludes the dev preview, which carries the same token but
+ * is read by the project owner.
+ */
+export declare function isBuilderGatewayDeployConfigured(): boolean;
+/** One decision for every gateway-lane consumer; a per-consumer copy drifts. */
+export declare function gatewayLaneUnavailableMessage(ownerFacing: string): string;
+/**
+ * Gateway-lane credentials. Fall-through: the request's own Builder connection,
+ * then the deployment's credits pair, then the legacy pair.
+ *
+ * Identity-bearing calls (asset upload, design systems, Admin GraphQL, browser
+ * agent) must keep using `resolveBuilderCredentials`: a `['gateway']` token 403s
+ * on all of them.
+ */
+export declare function resolveBuilderGatewayCredentialsDetailed(identity?: BuilderCredentialLookupIdentity): Promise<BuilderGatewayCredentialsDetailed>;
+/**
+ * Gateway-lane credentials in the same shape as `resolveBuilderCredentials`, so
+ * a consumer moves lane by changing which resolver it calls and nothing else.
+ */
+export declare function resolveBuilderGatewayCredentials(identity?: BuilderCredentialLookupIdentity): Promise<{
+    privateKey: string | null;
+    publicKey: string | null;
+    userId: string | null;
+    orgName: string | null;
+    orgKind: string | null;
+    subscription: string | null;
+    subscriptionLevel: string | null;
+    subscriptionName: string | null;
+    isEnterprise: boolean | null;
+    isFreeAccount: boolean | null;
+}>;
+export interface BuilderGatewayAuth {
+    /** `Bearer <token>` for the `Authorization` header. */
+    authorization: string;
+    /** Send as `x-builder-api-key`. Null only for a legacy single-key deployment. */
+    spaceId: string | null;
+    /** Send as `x-builder-user-id` when the lane carries a Builder user. */
+    userId: string | null;
+}
+/**
+ * The gate for gateway-lane features. Not `resolveHasBuilderPrivateKey`, which is
+ * identity-only and false on a credits site.
+ */
+export declare function resolveHasBuilderGatewayCredential(): Promise<boolean>;
+/** Gateway-lane `resolveBuilderAuthHeader`, same fall-through order. */
+export declare function resolveBuilderGatewayAuth(): Promise<BuilderGatewayAuth | null>;
 /**
  * Stale markers expire so a rejected model or a transient gateway failure
  * cannot pin a signed-in user to "Builder not connected" forever. Only a
@@ -235,6 +300,21 @@ export declare function clearProviderCredentialAuthFailure(opts: {
     key?: string | null;
     value?: string | null;
 }): Promise<void>;
+/**
+ * `builderCredentialFingerprint` needs both legacy keys, so on a credits site the
+ * legacy marker is a no-op and a rejected token would be resent forever. The
+ * gateway lane fingerprints its single token through the provider marker.
+ */
+export declare function recordBuilderGatewayAuthFailure(details?: {
+    status?: number;
+    code?: string;
+    message?: string;
+}): Promise<void>;
+/** Each clear is a no-op off its own lane, so callers need not know which they are on. */
+export declare function clearBuilderGatewayAuthFailure(creds: {
+    privateKey?: string | null;
+    publicKey?: string | null;
+}): Promise<void>;
 /**
  * Write Builder credentials to `app_secrets`.
  *

package/dist/server/credential-provider.js

@@ -18,7 +18,7 @@
  * (e.g. additional Builder-hosted services) without rewrites.
  */
 import { createHash } from "node:crypto";
-import { CREDENTIAL_STORE_UNAVAILABLE_ERROR_CODE } from "../agent/engine/credential-errors.js";
+import { CREDENTIAL_STORE_UNAVAILABLE_ERROR_CODE, GATEWAY_UNAVAILABLE_VISITOR_MESSAGE, } from "../agent/engine/credential-errors.js";
 import { getAppConfig } from "../app-config/index.js";
 import { getDbExec, isLocalDatabase, isTransientDatabaseError, } from "../db/client.js";
 import { getOrgSetting } from "../settings/org-settings.js";
@@ -128,6 +128,12 @@ export function readDeployCredentialEnv(key) {
 }
 const APP_PROVIDED_DEPLOY_CREDENTIAL_KEYS = new Set([
     "ANTHROPIC_API_KEY",
+    // The Builder-credits pair pays for the deployed app's own model calls and
+    // carries no end-user identity — the token is scoped to ['gateway'] and can
+    // make no identity-bearing Builder call. The legacy BUILDER_PRIVATE_KEY /
+    // BUILDER_PUBLIC_KEY pair can, so it must never be added to this set.
+    "BUILDER_GATEWAY_TOKEN",
+    "BUILDER_GATEWAY_SPACE_ID",
     "EMAIL_FROM",
     "EMAIL_INBOUND_WEBHOOK_SECRET",
     "EMAIL_AGENT_ADDRESS",
@@ -180,6 +186,10 @@ export function canUseDeployCredentialFallbackForRequest(key) {
         return true;
     return isLocalDatabase();
 }
+/** The raw `btk-` gateway PAT a Builder-credits deploy injects. */
+export const BUILDER_GATEWAY_TOKEN_ENV_VAR = "BUILDER_GATEWAY_TOKEN";
+/** The space id that pairs with it, sent as `x-builder-api-key`. */
+export const BUILDER_GATEWAY_SPACE_ID_ENV_VAR = "BUILDER_GATEWAY_SPACE_ID";
 const BUILDER_CREDENTIAL_KEYS = [
     "BUILDER_PRIVATE_KEY",
     "BUILDER_PUBLIC_KEY",
@@ -702,6 +712,132 @@ export async function resolveBuilderCredentials(identity) {
         isFreeAccount,
     };
 }
+/**
+ * Both halves required: the gateway 403s a token with no space id before it
+ * consults any route policy, so half a pair is not a usable credential.
+ */
+export async function resolveUsableBuilderGatewayDeployCredentials() {
+    const token = canUseDeployCredentialFallbackForRequest(BUILDER_GATEWAY_TOKEN_ENV_VAR)
+        ? readDeployCredentialEnv(BUILDER_GATEWAY_TOKEN_ENV_VAR)
+        : undefined;
+    const spaceId = canUseDeployCredentialFallbackForRequest(BUILDER_GATEWAY_SPACE_ID_ENV_VAR)
+        ? readDeployCredentialEnv(BUILDER_GATEWAY_SPACE_ID_ENV_VAR)
+        : undefined;
+    if (!token || !spaceId)
+        return null;
+    const failure = await getProviderCredentialAuthFailure({
+        key: BUILDER_GATEWAY_TOKEN_ENV_VAR,
+        value: token,
+    });
+    return failure ? null : { token, spaceId };
+}
+/**
+ * Weaker than "usable" on purpose: a present-but-rejected token still means the
+ * reader is a visitor. Excludes the dev preview, which carries the same token but
+ * is read by the project owner.
+ */
+export function isBuilderGatewayDeployConfigured() {
+    if (isHostedWorkspaceRuntime())
+        return false;
+    return Boolean(readDeployCredentialEnv(BUILDER_GATEWAY_TOKEN_ENV_VAR));
+}
+/** One decision for every gateway-lane consumer; a per-consumer copy drifts. */
+export function gatewayLaneUnavailableMessage(ownerFacing) {
+    return isBuilderGatewayDeployConfigured()
+        ? GATEWAY_UNAVAILABLE_VISITOR_MESSAGE
+        : ownerFacing;
+}
+/**
+ * Gateway-lane credentials. Fall-through: the request's own Builder connection,
+ * then the deployment's credits pair, then the legacy pair.
+ *
+ * Identity-bearing calls (asset upload, design systems, Admin GraphQL, browser
+ * agent) must keep using `resolveBuilderCredentials`: a `['gateway']` token 403s
+ * on all of them.
+ */
+export async function resolveBuilderGatewayCredentialsDetailed(identity) {
+    const scoped = await resolveBuilderCredentialsDetailed(identity);
+    if (scoped.source && scoped.source !== "env") {
+        return { ...scoped, lane: "identity" };
+    }
+    // A COMPLETE legacy pair in env is owner-configured, not deploy-injected, so it
+    // outranks the gateway here — `selectDetectedEngine` gives it priority for the
+    // same reason, and letting the gateway win would pick `builder` on the
+    // customer's own pair and then bill the call to the project's gateway space.
+    // An incomplete pair is not a usable credential and still falls through.
+    if (scoped.privateKey && scoped.publicKey) {
+        return { ...scoped, lane: "identity" };
+    }
+    const gateway = await resolveUsableBuilderGatewayDeployCredentials();
+    if (gateway) {
+        // Same discipline as `resolveBuilderCredential`: a deploy fallback must not
+        // turn an unreadable credential store into a clean connected result.
+        assertCredentialStoreReadable(scoped);
+        return {
+            privateKey: gateway.token,
+            publicKey: gateway.spaceId,
+            userId: null,
+            orgName: null,
+            orgKind: null,
+            subscription: null,
+            subscriptionLevel: null,
+            subscriptionName: null,
+            isEnterprise: null,
+            isFreeAccount: null,
+            source: "env",
+            lookupFailed: scoped.lookupFailed,
+            cause: scoped.cause,
+            lane: "gateway-deploy",
+        };
+    }
+    return { ...scoped, lane: scoped.source ? "identity" : null };
+}
+/**
+ * Gateway-lane credentials in the same shape as `resolveBuilderCredentials`, so
+ * a consumer moves lane by changing which resolver it calls and nothing else.
+ */
+export async function resolveBuilderGatewayCredentials(identity) {
+    const { privateKey, publicKey, userId, orgName, orgKind, subscription, subscriptionLevel, subscriptionName, isEnterprise, isFreeAccount, } = await resolveBuilderGatewayCredentialsDetailed(identity);
+    return {
+        privateKey,
+        publicKey,
+        userId,
+        orgName,
+        orgKind,
+        subscription,
+        subscriptionLevel,
+        subscriptionName,
+        isEnterprise,
+        isFreeAccount,
+    };
+}
+/**
+ * The gate for gateway-lane features. Not `resolveHasBuilderPrivateKey`, which is
+ * identity-only and false on a credits site.
+ */
+export async function resolveHasBuilderGatewayCredential() {
+    return Boolean(await resolveBuilderGatewayAuth());
+}
+/** Gateway-lane `resolveBuilderAuthHeader`, same fall-through order. */
+export async function resolveBuilderGatewayAuth() {
+    const creds = await resolveBuilderGatewayCredentialsDetailed();
+    const token = creds.privateKey?.trim();
+    const spaceId = creds.publicKey?.trim();
+    if (token && spaceId) {
+        return {
+            authorization: `Bearer ${token}`,
+            spaceId,
+            userId: creds.userId?.trim() || null,
+        };
+    }
+    // Single-key deployments predate the space id and still authenticate on a
+    // `bpk-` private key alone. A gateway token never reaches this branch — its
+    // pair is required above.
+    const legacyKey = (await resolveBuilderPrivateKey())?.trim();
+    return legacyKey
+        ? { authorization: `Bearer ${legacyKey}`, spaceId: null, userId: null }
+        : null;
+}
 const BUILDER_AUTH_FAILURE_SETTING_PREFIX = "builder-auth-failure:";
 /**
  * Stale markers expire so a rejected model or a transient gateway failure
@@ -882,6 +1018,37 @@ export async function clearProviderCredentialAuthFailure(opts) {
         // A stale failure marker should not block writing or using fresh keys.
     }
 }
+/**
+ * `builderCredentialFingerprint` needs both legacy keys, so on a credits site the
+ * legacy marker is a no-op and a rejected token would be resent forever. The
+ * gateway lane fingerprints its single token through the provider marker.
+ */
+export async function recordBuilderGatewayAuthFailure(details) {
+    try {
+        const creds = await resolveBuilderGatewayCredentialsDetailed();
+        if (creds.lane === "gateway-deploy" && creds.privateKey) {
+            await recordProviderCredentialAuthFailure({
+                key: BUILDER_GATEWAY_TOKEN_ENV_VAR,
+                value: creds.privateKey,
+                ...details,
+            });
+            return;
+        }
+    }
+    catch {
+        // Best-effort marker only; the chat error is still returned to the caller.
+        return;
+    }
+    await recordBuilderCredentialAuthFailure(details);
+}
+/** Each clear is a no-op off its own lane, so callers need not know which they are on. */
+export async function clearBuilderGatewayAuthFailure(creds) {
+    await clearBuilderCredentialAuthFailure(creds);
+    await clearProviderCredentialAuthFailure({
+        key: BUILDER_GATEWAY_TOKEN_ENV_VAR,
+        value: creds.privateKey,
+    });
+}
 /**
  * Write Builder credentials to `app_secrets`.
  *

package/dist/server/google-realtime-session.d.ts

@@ -8,6 +8,6 @@ export declare function resolveGoogleRealtimeCredentials(opts: {
     orgId?: string | null;
 }): Promise<string | null>;
 export declare function createGoogleRealtimeSessionHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<GoogleRealtimeSessionResponse | {
-    error: any;
+    error: string;
 }>>;
 export {};

package/dist/server/google-realtime-session.js

@@ -4,7 +4,7 @@ import { resolveCredential } from "../credentials/index.js";
 import { getOrgContext } from "../org/context.js";
 import { readAppSecret } from "../secrets/storage.js";
 import { getSession } from "./auth.js";
-import { resolveBuilderCredentials } from "./credential-provider.js";
+import { gatewayLaneUnavailableMessage, resolveBuilderGatewayCredentials, } from "./credential-provider.js";
 import { runWithRequestContext } from "./request-context.js";
 import { isSameOriginRequest } from "./request-origin.js";
 export async function resolveGoogleRealtimeCredentials(opts) {
@@ -85,11 +85,11 @@ export function createGoogleRealtimeSessionHandler() {
                     error: "Configure GOOGLE_APPLICATION_CREDENTIALS in Settings to use Google realtime transcription.",
                 };
             }
-            const builderCreds = await resolveBuilderCredentials();
+            const builderCreds = await resolveBuilderGatewayCredentials();
             if (!builderCreds.privateKey || !builderCreds.publicKey) {
                 setResponseStatus(event, 400);
                 return {
-                    error: "Builder must be connected to mint a managed realtime transcription session.",
+                    error: gatewayLaneUnavailableMessage("Builder must be connected to mint a managed realtime transcription session."),
                 };
             }
             const apiHost = process.env.BUILDER_API_HOST || "https://api.builder.io";
@@ -119,16 +119,16 @@ export function createGoogleRealtimeSessionHandler() {
                     .catch(() => ({ error: `HTTP ${res.status}` }));
                 setResponseStatus(event, res.status);
                 return {
-                    error: typeof errorBody?.error === "string"
+                    error: gatewayLaneUnavailableMessage(typeof errorBody?.error === "string"
                         ? errorBody.error
-                        : `Realtime session failed (${res.status})`,
+                        : `Realtime session failed (${res.status})`),
                 };
             }
             const payload = (await res.json());
             if (!payload?.websocketUrl) {
                 setResponseStatus(event, 502);
                 return {
-                    error: "Realtime transcription service did not return a websocket URL.",
+                    error: gatewayLaneUnavailableMessage("Realtime transcription service did not return a websocket URL."),
                 };
             }
             return payload;

package/dist/server/index.d.ts

@@ -70,7 +70,7 @@ export { registerFileUploadProvider, unregisterFileUploadProvider, listFileUploa
 export { createIntegrationsPlugin, defaultIntegrationsPlugin, enqueueRemoteCommand, slackAdapter, telegramAdapter, whatsappAdapter, discordAdapter, microsoftTeamsAdapter, emailAdapter, assertPlatformCapability, type PlatformAdapter, type IncomingMessage, type OutgoingMessage, type PlatformAdapterCapabilities, type ImmediateWebhookResponse, type IntegrationStatus, type IntegrationsPluginOptions, type IntegrationExecutionContext, BUILT_IN_INTEGRATION_CATALOG, INTEGRATION_CATEGORIES, getIntegrationCatalogEntry, listBuiltInChannelIntegrations, listIntegrationCatalog, type BuiltInChannelId, type ChannelCapabilities, type IntegrationAvailability, type IntegrationCatalogEntry, type IntegrationCategory, type IntegrationCredentialRequirement, type IntegrationIconKey, type IntegrationSupportMaturity, } from "../integrations/index.js";
 export { isElectron, isMobile, getOrigin, getAppBasePath, getAppUrl, resolveOAuthRedirectUri, isAllowedOAuthRedirectUri, encodeOAuthState, decodeOAuthState, resolveOAuthOwner, createOAuthSession, oauthCallbackResponse, oauthErrorPage, oauthDesktopExchangePage, type OAuthStatePayload, type OAuthOwnerResult, type OAuthSessionResult, } from "./google-oauth.js";
 export { buildWorkspaceProviderAuthorizationUrl, createWorkspaceProviderOAuthHandler, exchangeWorkspaceProviderOAuthCode, handleWorkspaceProviderOAuthCallback, handleWorkspaceProviderOAuthStart, isWorkspaceProviderOAuthFlowValid, mergeWorkspaceOAuthValues, resolveWorkspaceProviderIdentity, workspaceProviderOAuthPath, type GenericWorkspaceOAuthProvider, type WorkspaceProviderOAuthFlow, } from "./workspace-provider-oauth.js";
-export { FeatureNotConfiguredError, hasBuilderPrivateKey, isBuilderEnvManaged, getBuilderProxyOrigin, getBuilderImageGenerationBaseUrl, getBuilderWebSearchBaseUrl, getBuilderAuthHeader, resolveBuilderPrivateKey, resolveBuilderAuthHeader, resolveHasBuilderPrivateKey, resolveHasCompleteBuilderConnection, resolveBuilderCredentials, resolveBuilderCredentialsDetailed, resolveBuilderCredentialSource, resolveBuilderCredential, readDeployCredentialEnv, writeBuilderCredentials, deleteBuilderCredentials, resolveSecret, type BuilderCredentialsDetailed, } from "./credential-provider.js";
+export { FeatureNotConfiguredError, hasBuilderPrivateKey, isBuilderEnvManaged, getBuilderProxyOrigin, getBuilderImageGenerationBaseUrl, getBuilderWebSearchBaseUrl, getBuilderAuthHeader, resolveBuilderPrivateKey, resolveBuilderAuthHeader, resolveHasBuilderPrivateKey, resolveHasCompleteBuilderConnection, resolveBuilderCredentials, resolveBuilderCredentialsDetailed, resolveBuilderGatewayCredentials, resolveBuilderGatewayCredentialsDetailed, resolveBuilderCredentialSource, resolveBuilderCredential, readDeployCredentialEnv, writeBuilderCredentials, deleteBuilderCredentials, resolveSecret, type BuilderCredentialsDetailed, } from "./credential-provider.js";
 export { builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, collectBuilderDesignSystemGitHubFiles, createBuilderDesignSystemProxyFields, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, type BuildBuilderDesignSystemIndexFilesOptions, type BuilderDesignSystemCodeFileInput, type BuilderDesignSystemDecodeJobStatus, type BuilderDesignSystemDocsOptions, type BuilderDesignSystemDocument, type BuilderDesignSystemHydratedReference, type BuilderDesignSystemIndexFile, type BuilderDesignSystemIndexFromSourcesOptions, type BuilderDesignSystemIndexOptions, type BuilderDesignSystemIndexResult, type BuilderDesignSystemGitHubFile, type BuilderDesignSystemGitHubFileCollection, type BuilderDesignSystemGitHubSource, type BuilderDesignSystemUploadAttachment, type BuilderDesignSystemUploadSlot, type BuilderDesignSystemProxyFields, type BuilderDesignSystemProxyFieldsOptions, type BuilderDesignSystemProxyReference, type BuilderDesignSystemSourceKind, } from "./builder-design-systems.js";
 export { createBuilderProject, ensureBuilderProject, findBuilderProjectForRepo, getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, runBuilderAgent, type BuilderProjectResult, type RunBuilderAgentResult, } from "./builder-browser.js";
 export { ensureFusionContainer, sendFusionBranchMessage, pushFusionBranch, reserveFusionHostingSlug, deployFusionProject, getFusionDeploys, getFusionBranchEditorUrl, getFusionHostingUrl, type FusionBranchRef, type EnsureFusionContainerResult, type SendFusionMessageResult, } from "./fusion-app.js";

package/dist/server/index.js

@@ -75,7 +75,12 @@ export { registerFileUploadProvider, unregisterFileUploadProvider, listFileUploa
 export { createIntegrationsPlugin, defaultIntegrationsPlugin, enqueueRemoteCommand, slackAdapter, telegramAdapter, whatsappAdapter, discordAdapter, microsoftTeamsAdapter, emailAdapter, assertPlatformCapability, BUILT_IN_INTEGRATION_CATALOG, INTEGRATION_CATEGORIES, getIntegrationCatalogEntry, listBuiltInChannelIntegrations, listIntegrationCatalog, } from "../integrations/index.js";
 export { isElectron, isMobile, getOrigin, getAppBasePath, getAppUrl, resolveOAuthRedirectUri, isAllowedOAuthRedirectUri, encodeOAuthState, decodeOAuthState, resolveOAuthOwner, createOAuthSession, oauthCallbackResponse, oauthErrorPage, oauthDesktopExchangePage, } from "./google-oauth.js";
 export { buildWorkspaceProviderAuthorizationUrl, createWorkspaceProviderOAuthHandler, exchangeWorkspaceProviderOAuthCode, handleWorkspaceProviderOAuthCallback, handleWorkspaceProviderOAuthStart, isWorkspaceProviderOAuthFlowValid, mergeWorkspaceOAuthValues, resolveWorkspaceProviderIdentity, workspaceProviderOAuthPath, } from "./workspace-provider-oauth.js";
-export { FeatureNotConfiguredError, hasBuilderPrivateKey, isBuilderEnvManaged, getBuilderProxyOrigin, getBuilderImageGenerationBaseUrl, getBuilderWebSearchBaseUrl, getBuilderAuthHeader, resolveBuilderPrivateKey, resolveBuilderAuthHeader, resolveHasBuilderPrivateKey, resolveHasCompleteBuilderConnection, resolveBuilderCredentials, resolveBuilderCredentialsDetailed, resolveBuilderCredentialSource, resolveBuilderCredential, readDeployCredentialEnv, writeBuilderCredentials, deleteBuilderCredentials, resolveSecret, } from "./credential-provider.js";
+export { FeatureNotConfiguredError, hasBuilderPrivateKey, isBuilderEnvManaged, getBuilderProxyOrigin, getBuilderImageGenerationBaseUrl, getBuilderWebSearchBaseUrl, getBuilderAuthHeader, resolveBuilderPrivateKey, resolveBuilderAuthHeader, resolveHasBuilderPrivateKey, resolveHasCompleteBuilderConnection, resolveBuilderCredentials, resolveBuilderCredentialsDetailed, 
+// Gateway lane, for the metered surfaces a deployed site can call without an
+// identity — image and video generation, realtime transcription. Falls
+// through to the identity credential first, so a consumer moves lane by
+// swapping the resolver and changing nothing else.
+resolveBuilderGatewayCredentials, resolveBuilderGatewayCredentialsDetailed, resolveBuilderCredentialSource, resolveBuilderCredential, readDeployCredentialEnv, writeBuilderCredentials, deleteBuilderCredentials, resolveSecret, } from "./credential-provider.js";
 export { builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, collectBuilderDesignSystemGitHubFiles, createBuilderDesignSystemProxyFields, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, } from "./builder-design-systems.js";
 export { createBuilderProject, ensureBuilderProject, findBuilderProjectForRepo, getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, runBuilderAgent, } from "./builder-browser.js";
 export { ensureFusionContainer, sendFusionBranchMessage, pushFusionBranch, reserveFusionHostingSlug, deployFusionProject, getFusionDeploys, getFusionBranchEditorUrl, getFusionHostingUrl, } from "./fusion-app.js";

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
-    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
+    error?: undefined;
 }>>;

package/dist/server/realtime-voice.js

@@ -5,7 +5,7 @@ import { redactSensitiveFields, sanitizeToolErrorText, sanitizeToolErrorValue, }
 import { TOOL_SEARCH_ACTION_NAME } from "../agent/tool-search.js";
 import { parseAcceptLanguage } from "../localization/server.js";
 import { getSession } from "./auth.js";
-import { getBuilderGatewayBaseUrl, resolveBuilderCredentials, resolveSecret, } from "./credential-provider.js";
+import { gatewayLaneUnavailableMessage, getBuilderGatewayBaseUrl, resolveBuilderGatewayCredentials, resolveSecret, } from "./credential-provider.js";
 import { getH3App } from "./framework-request-handler.js";
 import { runWithRequestContext } from "./request-context.js";
 import { isSameOriginRequest } from "./request-origin.js";
@@ -379,7 +379,7 @@ function createSessionHandler(tools, options) {
                 ? { browserTabId: auth.browserTabId }
                 : undefined,
         }, async () => {
-            const builderCredentials = await resolveBuilderCredentials();
+            const builderCredentials = await resolveBuilderGatewayCredentials();
             const builderConfigured = Boolean(builderCredentials.privateKey?.trim() &&
                 builderCredentials.publicKey?.trim());
             const apiKey = builderConfigured
@@ -388,7 +388,7 @@ function createSessionHandler(tools, options) {
             if (!builderConfigured && !apiKey) {
                 setResponseStatus(event, 409);
                 return {
-                    error: "Connect Builder (free tier available) or configure an OpenAI API key to use realtime voice.",
+                    error: gatewayLaneUnavailableMessage("Connect Builder (free tier available) or configure an OpenAI API key to use realtime voice."),
                     code: "realtime_voice_setup_required",
                 };
             }
@@ -466,22 +466,28 @@ function createSessionHandler(tools, options) {
                 setResponseStatus(event, 502);
                 return {
                     error: builderConfigured
-                        ? "Could not reach the Builder realtime voice gateway"
+                        ? gatewayLaneUnavailableMessage("Could not reach the Builder realtime voice gateway")
                         : "Could not reach the OpenAI Realtime API",
                 };
             }
             if (!upstream.ok) {
                 const detail = await safeOpenAiErrorDetail(upstream, builderConfigured ? builderCredentials.privateKey : apiKey);
                 setResponseStatus(event, builderConfigured ? upstream.status : 502);
+                const rejection = `${builderConfigured ? "Builder" : "OpenAI"} rejected the realtime session (${upstream.status})${detail ? `: ${detail}` : ""}`;
                 return {
-                    error: `${builderConfigured ? "Builder" : "OpenAI"} rejected the realtime session (${upstream.status})${detail ? `: ${detail}` : ""}`,
+                    error: builderConfigured
+                        ? gatewayLaneUnavailableMessage(rejection)
+                        : rejection,
                 };
             }
             const answerSdp = await upstream.text().catch(() => "");
             if (!answerSdp.trim()) {
                 setResponseStatus(event, 502);
+                const emptyAnswer = `${builderConfigured ? "Builder" : "OpenAI"} returned an empty realtime session answer`;
                 return {
-                    error: `${builderConfigured ? "Builder" : "OpenAI"} returned an empty realtime session answer`,
+                    error: builderConfigured
+                        ? gatewayLaneUnavailableMessage(emptyAnswer)
+                        : emptyAnswer,
                 };
             }
             setResponseStatus(event, upstream.status);

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    error?: undefined;
     text: string;
+    error?: undefined;
 }>>;

package/dist/server/transcribe-voice.js

@@ -23,7 +23,7 @@ import { getOrgContext } from "../org/context.js";
 import { transcribeWithBuilder } from "../transcription/builder-transcription.js";
 import { applyVoiceContextReplacements, buildVoiceGuidanceBlock, parseVoiceContextPack, voiceContextTermsOnly, } from "../voice/index.js";
 import { getSession } from "./auth.js";
-import { resolveHasBuilderPrivateKey, resolveSecret, } from "./credential-provider.js";
+import { gatewayLaneUnavailableMessage, resolveHasBuilderGatewayCredential, resolveSecret, } from "./credential-provider.js";
 import { runWithRequestContext } from "./request-context.js";
 import { isSameOriginRequest } from "./request-origin.js";
 const WHISPER_URL = "https://api.openai.com/v1/audio/transcriptions";
@@ -149,7 +149,7 @@ export function createTranscribeVoiceHandler() {
         const withRequestContext = async (fn) => requestContext.userEmail
             ? runWithRequestContext(requestContext, fn)
             : fn();
-        const hasBuilderPrivateKey = async () => withRequestContext(() => resolveHasBuilderPrivateKey());
+        const hasBuilderCredential = async () => withRequestContext(() => resolveHasBuilderGatewayCredential());
         const transcribeWithBuilderForRequest = (opts) => withRequestContext(() => transcribeWithBuilder(opts));
         const sessionId = session?.email ?? "local";
         let providerPref;
@@ -212,7 +212,7 @@ export function createTranscribeVoiceHandler() {
                 instructions: voiceGuidance,
                 contextPack: voiceContext,
                 providerPref,
-                hasBuilderPrivateKey,
+                hasBuilderCredential,
                 withRequestContext,
                 resolveApiKey,
                 clientAbortSignal: clientAbort,
@@ -266,10 +266,10 @@ export function createTranscribeVoiceHandler() {
             const label = providerPref === "builder-gemini"
                 ? "Builder Gemini Flash-Lite"
                 : "Builder";
-            if (!(await hasBuilderPrivateKey())) {
+            if (!(await hasBuilderCredential())) {
                 setResponseStatus(event, 400);
                 return {
-                    error: `${label} is selected but Builder.io is not connected. Connect Builder.io (free tier available) in Settings, or change the provider preference.`,
+                    error: gatewayLaneUnavailableMessage(`${label} is selected but Builder.io is not connected. Connect Builder.io (free tier available) in Settings, or change the provider preference.`),
                 };
             }
             try {
@@ -288,10 +288,12 @@ export function createTranscribeVoiceHandler() {
                 const message = err?.message ?? String(err);
                 if (message.includes("credits exhausted")) {
                     setResponseStatus(event, 402);
-                    return { error: message };
+                    return { error: gatewayLaneUnavailableMessage(message) };
                 }
                 setResponseStatus(event, 502);
-                return { error: `${label} transcription failed: ${message}` };
+                return {
+                    error: gatewayLaneUnavailableMessage(`${label} transcription failed: ${message}`),
+                };
             }
         }
         if (providerPref === "groq") {
@@ -322,7 +324,7 @@ export function createTranscribeVoiceHandler() {
         // ── Builder Gemini Flash-Lite path ─────────────────────────────────
         // First-priority in auto mode when Builder is connected. This lets users
         // try Gemini 3.1 Flash-Lite without bringing their own Google key.
-        if (providerPref !== "openai" && (await hasBuilderPrivateKey())) {
+        if (providerPref !== "openai" && (await hasBuilderCredential())) {
             try {
                 const result = await transcribeWithBuilderForRequest({
                     audioBytes,
@@ -339,7 +341,7 @@ export function createTranscribeVoiceHandler() {
                 // a specific upgrade prompt.
                 if (message.includes("credits exhausted")) {
                     setResponseStatus(event, 402);
-                    return { error: message };
+                    return { error: gatewayLaneUnavailableMessage(message) };
                 }
                 builderError = message;
             }
@@ -401,9 +403,9 @@ export function createTranscribeVoiceHandler() {
         if (!provider) {
             setResponseStatus(event, builderError ? 502 : 400);
             return {
-                error: builderError
+                error: gatewayLaneUnavailableMessage(builderError
                     ? `Builder transcription failed: ${builderError}. Add GEMINI_API_KEY, GROQ_API_KEY, or OPENAI_API_KEY in Settings → API Keys to enable a fallback provider.`
-                    : "No voice transcription provider configured. Connect Builder.io (free tier available) or add GEMINI_API_KEY / GROQ_API_KEY / OPENAI_API_KEY in Settings → API Keys.",
+                    : "No voice transcription provider configured. Connect Builder.io (free tier available) or add GEMINI_API_KEY / GROQ_API_KEY / OPENAI_API_KEY in Settings → API Keys."),
             };
         }
         return await callWhisperCompat({
@@ -477,7 +479,7 @@ async function callWhisperCompat({ event, provider, audioBytes, mime, language,
         clearTimeout(timeout);
     }
 }
-async function cleanupTranscriptText({ event, text, instructions, contextPack, providerPref, hasBuilderPrivateKey, withRequestContext, resolveApiKey, clientAbortSignal, }) {
+async function cleanupTranscriptText({ event, text, instructions, contextPack, providerPref, hasBuilderCredential, withRequestContext, resolveApiKey, clientAbortSignal, }) {
     const original = text.trim();
     if (!original)
         return { text: "" };
@@ -486,10 +488,10 @@ async function cleanupTranscriptText({ event, text, instructions, contextPack, p
         return { text: finalizeText(original) };
     }
     if (providerPref === "builder" || providerPref === "builder-gemini") {
-        if (!(await hasBuilderPrivateKey())) {
+        if (!(await hasBuilderCredential())) {
             setResponseStatus(event, 400);
             return {
-                error: "Builder.io cleanup is selected but Builder.io is not connected. Connect Builder.io (free tier available) in Settings, or change the provider preference.",
+                error: gatewayLaneUnavailableMessage("Builder.io cleanup is selected but Builder.io is not connected. Connect Builder.io (free tier available) in Settings, or change the provider preference."),
             };
         }
         try {
@@ -506,7 +508,7 @@ async function cleanupTranscriptText({ event, text, instructions, contextPack, p
         catch (err) {
             setResponseStatus(event, 502);
             return {
-                error: `Builder.io cleanup failed: ${err?.message ?? String(err)}`,
+                error: gatewayLaneUnavailableMessage(`Builder.io cleanup failed: ${err?.message ?? String(err)}`),
             };
         }
     }
@@ -560,7 +562,7 @@ async function cleanupTranscriptText({ event, text, instructions, contextPack, p
             };
         }
     }
-    if (await hasBuilderPrivateKey()) {
+    if (await hasBuilderCredential()) {
         try {
             const cleaned = await withRequestContext(() => cleanupWithBuilder({ text: original, instructions, clientAbortSignal }));
             if (cleaned)