@agent-native/core 0.159.3 → 0.160.0

package/dist/mcp/screen-memory-stdio.d.ts

@@ -137,13 +137,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
+            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -159,6 +159,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
+            count?: undefined;
             query: {
                 type: string;
                 description: string;
@@ -174,7 +175,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -190,6 +190,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
+            count?: undefined;
             minutes: {
                 type: string;
                 description: string;
@@ -199,7 +200,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -216,6 +216,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
+            count?: undefined;
             query: {
                 type: string;
                 description: string;
@@ -234,7 +235,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             };
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -250,6 +250,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
+            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
@@ -263,7 +264,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
                 description: string;
             };
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             includeMicrophone?: undefined;
@@ -314,13 +314,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
+            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt: {
                 type: string;
                 description: string;
@@ -349,13 +349,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
+            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
-            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;

package/dist/notifications/routes.d.ts

@@ -16,18 +16,18 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error?: undefined;
     ok?: undefined;
 } | {
+    count?: undefined;
     updated: number;
     error?: undefined;
     ok?: undefined;
-    count?: undefined;
 } | {
+    count?: undefined;
     updated?: undefined;
     error: string;
     ok?: undefined;
-    count?: undefined;
 } | {
+    count?: undefined;
     updated?: undefined;
     error?: undefined;
     ok: boolean;
-    count?: undefined;
 }>>;

package/dist/observability/routes.d.ts

@@ -41,14 +41,14 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
 } | {
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -75,8 +75,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         user: "user";
     }>>;
 }, z.core.$strip>>, {
-    message?: undefined;
     id?: undefined;
+    message?: undefined;
     deleted?: undefined;
     providers: {
         id: string;
@@ -93,9 +93,9 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     registered?: undefined;
     label?: undefined;
 } | {
+    id?: undefined;
     message?: undefined;
     count?: undefined;
-    id?: undefined;
     deleted?: undefined;
     providers?: undefined;
     found: boolean;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/secrets/register-framework-secrets.js

@@ -107,6 +107,31 @@ export function registerFrameworkSecrets() {
             });
         }
     }
+    if (!getRequiredSecret("ANTHROPIC_API_KEY")) {
+        registerRequiredSecret({
+            key: "ANTHROPIC_API_KEY",
+            label: "Anthropic API key",
+            description: "Bring your own Claude key instead of routing model calls through Builder.io.",
+            docsUrl: "https://console.anthropic.com/settings/keys",
+            scope: "user",
+            kind: "api-key",
+            required: false,
+            validator: async (value) => {
+                const response = await fetch("https://api.anthropic.com/v1/models", {
+                    headers: {
+                        "x-api-key": value,
+                        "anthropic-version": "2023-06-01",
+                    },
+                });
+                return response.ok
+                    ? { ok: true }
+                    : {
+                        ok: false,
+                        error: `Anthropic rejected the key (HTTP ${response.status}).`,
+                    };
+            },
+        });
+    }
     if (!getRequiredSecret("OPENAI_API_KEY")) {
         registerRequiredSecret({
             key: "OPENAI_API_KEY",

package/dist/secrets/routes.d.ts

@@ -37,17 +37,17 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
     ok?: undefined;
     status?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     status: string;
-    error?: undefined;
 } | {
     ok?: undefined;
     error: string;
     removed?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
@@ -58,13 +58,13 @@ export declare function createTestSecretHandler(): import("h3").EventHandlerWith
     error: string;
     note?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note?: undefined;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     note: string;
-    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
-    error?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     removed: boolean;
-    error?: undefined;
 }>>;

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/auth.js

@@ -1981,6 +1981,16 @@ function createAuthGuardFn(app) {
             p === `${MCP_PUBLIC_ROUTE_PREFIX}/oauth/register`) {
             return;
         }
+        // Remote hosts authenticate these relay calls with their device token,
+        // not a browser session. Keep this list exact: sibling remote routes such
+        // as register, enqueue, and computer controls are session-authenticated.
+        if (p === "/_agent-native/integrations/remote/unregister" ||
+            p === "/_agent-native/integrations/remote/heartbeat" ||
+            p === "/_agent-native/integrations/remote/poll" ||
+            p === "/_agent-native/integrations/remote/result" ||
+            p === "/_agent-native/integrations/remote/run-events") {
+            return;
+        }
         // Cross-app SSO ("Sign in with Agent-Native") — CLIENT side. Both the
         // `/login` entry point and the `/callback` (hit by a user who is, by
         // definition, NOT yet signed in to THIS app) must bypass the blanket

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 {};