@agent-native/core 0.159.5 → 0.160.1

package/corpus/templates/calendar/changelog/2026-08-13-calendar-stays-pinned-to-the-saved-timezone-and-asks-before-.md

@@ -0,0 +1,6 @@
+---
+type: changed
+date: 2026-08-13
+---
+
+Calendar stays pinned to the saved timezone and asks before adopting a changed browser timezone

package/corpus/templates/calendar/changelog/2026-08-13-working-locations-can-be-added-from-calendar-days-with-a-ful.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-08-13
+---
+
+Working locations can be added from calendar days, with a full-day first entry and timed same-day additions

package/corpus/templates/calendar/changelog/2026-08-14-choosing-office-or-other-when-adding-a-working-location-creates.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-14
+---
+
+Choosing Office or Other when adding a working location creates that type, and adding one on a day that already has a location updates that day instead of extending Home.

package/corpus/templates/calendar/changelog/2026-08-14-creating-an-other-working-location-now-keeps-the-custom-name.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-14
+---
+
+Creating an Other working location now keeps the custom name instead of saving it as Working.

package/corpus/templates/calendar/changelog/2026-08-14-timed-working-locations-keep-home-office-or-custom-titles.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-14
+---
+
+Timed working locations keep a Home, Office, or custom title instead of the generated Working location label.

package/corpus/templates/calendar/changelog/2026-08-14-timed-working-locations-now-keep-a-home-office-or-custom-title.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-14
+---
+
+Timed working locations now keep a Home, Office, or custom title instead of showing as Untitled.

package/corpus/templates/calendar/changelog/2026-08-14-turning-a-midnight-ending-working-location-back-to-all-day.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-14
+---
+
+Turning a timed working location that ends at midnight back to all-day no longer adds an extra day.

package/corpus/templates/calendar/server/lib/google-calendar.ts

@@ -1209,6 +1209,21 @@ export async function getEvent(
   };
 }
 
+function timedWorkingLocationSummary(event: CalendarEvent): string | undefined {
+  if (event.eventType !== "workingLocation" || event.allDay) return undefined;
+  const properties = event.workingLocationProperties;
+  if (properties?.type === "officeLocation") {
+    return properties.officeLocation?.label || "Office";
+  }
+  if (properties?.type === "customLocation") {
+    return properties.customLocation?.label || "Working location";
+  }
+  if (properties?.type === "homeOffice") return "Home";
+  const trimmed = event.title?.trim();
+  if (trimmed && !event.titleIsGenerated) return trimmed;
+  return "Home";
+}
+
 export async function createEvent(
   event: CalendarEvent,
   opts: {
@@ -1230,9 +1245,15 @@ export async function createEvent(
     throw new Error("Out of office and focus time events must be timed.");
   }
 
+  const workingLocationSummary = timedWorkingLocationSummary(event);
   const body: any =
     event.eventType === "workingLocation"
-      ? buildDateRange(event)
+      ? {
+          ...buildDateRange(event),
+          ...(workingLocationSummary
+            ? { summary: workingLocationSummary }
+            : {}),
+        }
       : {
           summary: event.title,
           description: event.description,

package/dist/agent/engine/builder-engine.d.ts

@@ -8,14 +8,26 @@
  * concurrency) into structured stop events that carry an upgrade URL when
  * the chat UI needs to prompt the user to upgrade.
  *
- * Credentials come from BUILDER_PRIVATE_KEY + BUILDER_PUBLIC_KEY (set via the
- * Builder CLI-auth onboarding flow). Base URL is overridable via
+ * Credentials come from the gateway lane (`resolveBuilderGatewayCredentials`):
+ * the user's own Builder connection when they have one, otherwise the
+ * deployment's Builder-credits pair. Base URL is overridable via
  * BUILDER_GATEWAY_BASE_URL.
  */
+import { type BuilderGatewayLane } from "../../server/credential-provider.js";
 import type { AgentEngine, EngineCapabilities } from "./types.js";
 export declare const BUILDER_CAPABILITIES: EngineCapabilities;
 export declare const BUILDER_SUPPORTED_MODELS: readonly ["auto", string, "gpt-5-6-terra", "gpt-5-6-sol", "claude-haiku-4-5", "claude-sonnet-4-6" | "claude-sonnet-5", "claude-opus-4-8", "gemini-3-5-flash", "gemini-3-1-pro"];
 export declare const BUILDER_MODEL_UNAUTHORIZED_ERROR_CODE = "builder_model_unauthorized";
+/**
+ * A truncated stream, not a rejected request: the client continues the partial
+ * turn, so this is absent from `isRetryableError` on purpose.
+ *
+ * Every predicate that recognises `builder_gateway_network_error` must list this
+ * too, or a truncated stream silently stops recovering: `isResumableEngineError`,
+ * `isRecoverableContinuationError`, `shouldCaptureRunError`,
+ * `isInternalContinuationError` and the client's `sse-event-processor`.
+ */
+export declare const BUILDER_GATEWAY_STREAM_ENDED_ERROR_CODE = "builder_gateway_stream_ended";
 export declare const BUILDER_DEFAULT_MODEL: string;
 /**
  * Credentials captured by a durable caller that cannot rely on ambient
@@ -26,5 +38,7 @@ export interface BuilderEngineCredentials {
     publicKey: string | null;
     userId?: string | null;
     orgName?: string | null;
+    /** Which lane these came from, when the capturing caller knew. */
+    lane?: BuilderGatewayLane | null;
 }
 export declare function createBuilderEngine(config?: Record<string, unknown>): AgentEngine;

package/dist/agent/engine/builder-engine.js

@@ -8,19 +8,20 @@
  * concurrency) into structured stop events that carry an upgrade URL when
  * the chat UI needs to prompt the user to upgrade.
  *
- * Credentials come from BUILDER_PRIVATE_KEY + BUILDER_PUBLIC_KEY (set via the
- * Builder CLI-auth onboarding flow). Base URL is overridable via
+ * Credentials come from the gateway lane (`resolveBuilderGatewayCredentials`):
+ * the user's own Builder connection when they have one, otherwise the
+ * deployment's Builder-credits pair. Base URL is overridable via
  * BUILDER_GATEWAY_BASE_URL.
  */
 import { captureError } from "../../server/capture-error.js";
-import { clearBuilderCredentialAuthFailure, resolveBuilderCredentials, getBuilderGatewayBaseUrl, recordBuilderCredentialAuthFailure, } from "../../server/credential-provider.js";
+import { clearBuilderGatewayAuthFailure, isBuilderGatewayDeployConfigured, resolveBuilderGatewayCredentialsDetailed, getBuilderGatewayBaseUrl, recordBuilderGatewayAuthFailure, } from "../../server/credential-provider.js";
 import { applyBuilderUtmTrackingParams } from "../../shared/builder-link-tracking.js";
 import { isGPTReasoningModel, normalizeReasoningEffortForModel, } from "../../shared/reasoning-effort.js";
 import { isInBackgroundFunctionRuntime } from "../durable-background.js";
 import { BUILDER_MODEL_CONFIG } from "../model-config.js";
 import { getBuilderGatewayRequestHeaders } from "./builder-gateway-headers.js";
-import { LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, } from "./credential-errors.js";
-import { describeErrorWithCauses, isProviderConnectionErrorMessage, } from "./error-detail.js";
+import { gatewayVisitorFacingError, LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, } from "./credential-errors.js";
+import { classifyTerminalErrorCode, describeErrorWithCauses, isContextOverflowCode, isContextOverflowMessage, isProviderConnectionErrorMessage, } from "./error-detail.js";
 import { FIRST_STREAM_EVENT_TIMEOUT_MS } from "./first-event-timeout.js";
 import { resolveMaxOutputTokensForEngine } from "./output-tokens.js";
 import { splitSystemPromptForCache, stablePrefixCacheControl, } from "./prompt-cache.js";
@@ -48,6 +49,16 @@ const MAX_BACKGROUND_BUILDER_GATEWAY_TIMEOUT_MS = 14 * 60_000;
 const MAX_LOCAL_BUILDER_GATEWAY_TIMEOUT_MS = MAX_BACKGROUND_BUILDER_GATEWAY_TIMEOUT_MS;
 const BUILDER_GATEWAY_NETWORK_ERROR_CODE = "builder_gateway_network_error";
 export const BUILDER_MODEL_UNAUTHORIZED_ERROR_CODE = "builder_model_unauthorized";
+/**
+ * A truncated stream, not a rejected request: the client continues the partial
+ * turn, so this is absent from `isRetryableError` on purpose.
+ *
+ * Every predicate that recognises `builder_gateway_network_error` must list this
+ * too, or a truncated stream silently stops recovering: `isResumableEngineError`,
+ * `isRecoverableContinuationError`, `shouldCaptureRunError`,
+ * `isInternalContinuationError` and the client's `sse-event-processor`.
+ */
+export const BUILDER_GATEWAY_STREAM_ENDED_ERROR_CODE = "builder_gateway_stream_ended";
 export const BUILDER_DEFAULT_MODEL = BUILDER_MODEL_CONFIG.defaultModel;
 /**
  * Bucket an Anthropic `thinking.budgetTokens` value into the gateway's
@@ -94,6 +105,15 @@ async function buildUpgradeUrl() {
     });
     return url.toString();
 }
+/**
+ * `isBuilderGatewayDeployConfigured()` must gate both answers: it owns the
+ * dev-preview exclusion, and a captured lane cannot substitute for it.
+ */
+function isBuilderCreditsLane(creds) {
+    if (!isBuilderGatewayDeployConfigured())
+        return false;
+    return creds.lane ? creds.lane === "gateway-deploy" : true;
+}
 class BuilderEngine {
     configuredCredentials;
     name = "builder";
@@ -105,17 +125,17 @@ class BuilderEngine {
         this.configuredCredentials = configuredCredentials;
     }
     async *stream(opts) {
-        const creds = this.configuredCredentials ?? (await resolveBuilderCredentials());
+        const creds = this.configuredCredentials ??
+            (await resolveBuilderGatewayCredentialsDetailed());
+        const creditsLane = isBuilderCreditsLane(creds);
         const authHeader = creds.privateKey ? `Bearer ${creds.privateKey}` : null;
         const spaceId = creds.publicKey;
         const builderUserId = creds.userId;
         if (!authHeader || !spaceId) {
-            yield {
-                type: "stop",
-                reason: "error",
+            yield gatewayErrorStop({
                 error: LLM_MISSING_CREDENTIALS_MESSAGE,
                 errorCode: LLM_MISSING_CREDENTIALS_ERROR_CODE,
-            };
+            }, creditsLane);
             return;
         }
         const messages = engineMessagesToBuilderGatewayAnthropic(opts.messages);
@@ -245,12 +265,12 @@ class BuilderEngine {
                         elapsedMs: Date.now() - tStart,
                     });
                 }
-                yield createBuilderGatewayTimeoutStop(err, timedOut, gatewayAbort.effectiveTimeoutMs());
+                yield createBuilderGatewayTimeoutStop(err, timedOut, gatewayAbort.effectiveTimeoutMs(), creditsLane);
                 return;
             }
             console.log(`[builder-engine] ← ${response.status} ${response.statusText} in ${Date.now() - tStart}ms`);
             if (!response.ok) {
-                yield* emitHttpError(response);
+                yield* emitHttpError(response, { creditsLane });
                 return;
             }
             // A successful gateway call proves the connected credentials are valid
@@ -259,8 +279,9 @@ class BuilderEngine {
             // self-healing path for workspace/env-managed credentials, which never
             // flow through writeBuilderCredentials.
             try {
-                const creds = this.configuredCredentials ?? (await resolveBuilderCredentials());
-                await clearBuilderCredentialAuthFailure({
+                const creds = this.configuredCredentials ??
+                    (await resolveBuilderGatewayCredentialsDetailed());
+                await clearBuilderGatewayAuthFailure({
                     privateKey: creds.privateKey,
                     publicKey: creds.publicKey,
                 });
@@ -272,24 +293,29 @@ class BuilderEngine {
             const contentType = response.headers.get("content-type") ?? "";
             if (contentType.includes("text/html")) {
                 const rawText = await response.text().catch(() => "");
-                yield {
-                    type: "stop",
-                    reason: "error",
-                    error: normalizeGatewayErrorText(rawText, response.status || 502),
-                    errorCode: `http_${response.status || 502}`,
-                };
+                const status = response.status || 502;
+                const error = normalizeGatewayErrorText(rawText, status);
+                yield gatewayErrorStop({
+                    error,
+                    errorCode: `http_${status}`,
+                    statusCode: status,
+                    ...(isTransientGatewayFailure(error, status)
+                        ? { providerRetryable: true }
+                        : {}),
+                }, creditsLane);
                 return;
             }
             const reader = response.body?.getReader();
             if (!reader) {
-                yield {
-                    type: "stop",
-                    reason: "error",
+                yield gatewayErrorStop({
                     error: "Builder gateway response has no body",
-                };
+                    errorCode: "builder_gateway_error",
+                    statusCode: response.status,
+                }, creditsLane);
                 return;
             }
             yield* parseJsonlStream(reader, opts.model, {
+                creditsLane,
                 abortSignal: gatewayAbort.signal,
                 didGatewayTimeout: gatewayAbort.didTimeout,
                 getGatewayTimeoutMs: gatewayAbort.effectiveTimeoutMs,
@@ -303,7 +329,49 @@ class BuilderEngine {
         }
     }
 }
-async function* emitHttpError(response) {
+/**
+ * Gateway statuses another attempt can clear. 402/401/403 quota and auth
+ * rejections are absent on purpose — they are terminal until someone acts.
+ */
+const RETRYABLE_GATEWAY_STATUSES = new Set([408, 429, 500, 502, 503, 504, 529]);
+/** Read against the RAW reply: on the credits lane the message is replaced. */
+const TRANSIENT_UPSTREAM_PATTERN = /overloaded|rate_limit|rate limit reached|too many requests|\b429\b|\b529\b|\b502\b|\b503\b|\b504\b|resource_exhausted|quota exceeded|socket hang up|connection reset|temporarily unavailable|timeout/i;
+function isTransientGatewayFailure(rawMessage, status) {
+    if (status !== undefined && RETRYABLE_GATEWAY_STATUSES.has(status)) {
+        return true;
+    }
+    return TRANSIENT_UPSTREAM_PATTERN.test(rawMessage);
+}
+/**
+ * EVERY terminal `reason: "error"` this module emits must go through here,
+ * including those with no HTTP response behind them. A branch building its own
+ * stop literal ships owner copy to a visitor; `gateway-error-retryability.spec.ts`
+ * fails on a second literal in this file.
+ *
+ * On the credits lane the message collapses to one visitor line, so
+ * `statusCode` / `providerRetryable` / `contextOverflow` are the only retry
+ * signals downstream may read: keyword coupling to the message turns a retryable
+ * throttle into a dead turn on credits sites alone.
+ */
+function gatewayErrorStop(details, creditsLane) {
+    const { error, errorCode, upgradeUrl, ...retry } = details;
+    return {
+        type: "stop",
+        reason: "error",
+        ...(creditsLane
+            ? gatewayVisitorFacingError(errorCode)
+            : {
+                error,
+                ...(errorCode ? { errorCode } : {}),
+                ...(upgradeUrl ? { upgradeUrl } : {}),
+            }),
+        ...(isContextOverflowMessage(error) || isContextOverflowCode(errorCode)
+            ? { contextOverflow: true }
+            : {}),
+        ...retry,
+    };
+}
+async function* emitHttpError(response, opts) {
     const status = response.status;
     // Read the body once as text and then try to parse — calling `.json()`
     // and then `.text()` as a fallback fails because the body stream is
@@ -321,84 +389,67 @@ async function* emitHttpError(response) {
     }
     const code = errBody.code ?? `http_${status}`;
     const message = errBody.message ?? `Builder gateway returned ${status}`;
+    const stop = (details) => gatewayErrorStop(details, opts.creditsLane);
     // Belt-and-suspenders: 402 without a structured `credits-limit` code
     // (e.g. bare proxy response) still means quota → show upgrade CTA.
     if (code.startsWith("credits-limit") || status === 402) {
-        yield {
-            type: "stop",
-            reason: "error",
+        yield stop({
             error: message,
             errorCode: code,
             upgradeUrl: await buildUpgradeUrl(),
-        };
+        });
         return;
     }
     if (code === "gateway_not_enabled") {
-        yield {
-            type: "stop",
-            reason: "error",
-            error: message,
-            errorCode: code,
-        };
+        yield stop({ error: message, errorCode: code });
         return;
     }
     if (status === 401 || code === "unauthorized") {
-        await recordBuilderCredentialAuthFailure({ status, code, message });
-        yield {
-            type: "stop",
-            reason: "error",
+        await recordBuilderGatewayAuthFailure({ status, code, message });
+        yield stop({
             error: "Builder authentication failed. Reconnect Builder (free tier available) via Settings.",
             errorCode: "builder_auth_error",
-        };
+        });
         return;
     }
     if (status === 403 && isBuilderCredentialAuthError(message)) {
-        await recordBuilderCredentialAuthFailure({ status, code, message });
-        yield {
-            type: "stop",
-            reason: "error",
+        await recordBuilderGatewayAuthFailure({ status, code, message });
+        yield stop({
             error: "Builder authentication failed. Reconnect Builder (free tier available) via Settings.",
             errorCode: "builder_auth_error",
-        };
+        });
         return;
     }
     if (status === 403) {
-        yield {
-            type: "stop",
-            reason: "error",
-            error: message,
-            errorCode: code,
-        };
+        yield stop({ error: message, errorCode: code });
         return;
     }
     if (code === "rate_limit_exceeded") {
-        yield {
-            type: "stop",
-            reason: "error",
-            error: message,
-            errorCode: code,
-        };
+        // The daily cap shares 429 with the transient throttle below and must not
+        // loop, so it carries NEITHER retry field: a bare `statusCode: 429` reads as
+        // retryable on its own.
+        yield stop({ error: message, errorCode: code });
         return;
     }
     if (status === 429 || code === "too_many_concurrent_requests") {
-        // Include "too many requests" in the message so production-agent's
-        // isRetryableError picks up transient concurrency throttles and retries
-        // the turn. Daily gateway caps use `rate_limit_exceeded` above and must
-        // not loop.
-        yield {
-            type: "stop",
-            reason: "error",
-            error: `${message} (too many requests)`,
+        // Daily gateway caps use `rate_limit_exceeded` above and must not loop;
+        // this branch is the transient concurrency throttle, which does.
+        yield stop({
+            error: message,
             errorCode: code,
-        };
+            statusCode: status,
+            providerRetryable: true,
+        });
         return;
     }
-    yield {
-        type: "stop",
-        reason: "error",
+    yield stop({
         error: message,
         errorCode: code,
-    };
+        statusCode: status,
+        ...(isTransientGatewayFailure(message, status)
+            ? { providerRetryable: true }
+            : {}),
+    });
 }
 // Yields one non-empty JSONL line at a time. Flushes any trailing content
 // after the stream ends so a final event without a newline terminator
@@ -482,12 +533,12 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
             }
             catch {
                 const normalized = normalizeGatewayErrorText(line, 502);
-                yield {
-                    type: "stop",
-                    reason: "error",
+                yield gatewayErrorStop({
                     error: `Builder gateway returned invalid JSONL: ${normalized.slice(0, 240)}`,
                     errorCode: "http_502",
-                };
+                    statusCode: 502,
+                    providerRetryable: true,
+                }, captureContext.creditsLane);
                 return;
             }
             // Heartbeats are transport-level keepalives, not proof the model is
@@ -568,15 +619,13 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                     yield* recoverUndeliveredToolCalls();
                     yield { type: "assistant-content", parts };
                     const reason = event.reason ?? "end_turn";
+                    const stop = (details) => gatewayErrorStop(details, captureContext.creditsLane);
                     if (reason === "rate_limited") {
-                        // Include "rate_limit" in the message so production-agent's
-                        // isRetryableError picks it up and retries.
-                        yield {
-                            type: "stop",
-                            reason: "error",
+                        yield stop({
                             error: `rate_limit exceeded: ${event.error ?? "upstream provider rate limited"}`,
                             errorCode: "rate_limited",
-                        };
+                            providerRetryable: true,
+                        });
                     }
                     else if (reason === "invalid_request") {
                         // errorCode has no retry-trigger keywords, so isRetryableError
@@ -590,12 +639,7 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                                 ? event.code
                                 : "invalid_request";
                         console.warn(`[builder-engine] stop reason=invalid_request model=${model} code=${errCode} error=${errMsg}`);
-                        yield {
-                            type: "stop",
-                            reason: "error",
-                            error: errMsg,
-                            errorCode: errCode,
-                        };
+                        yield stop({ error: errMsg, errorCode: errCode });
                     }
                     else if (reason === "error") {
                         // Surface every diagnostic the gateway gave us so the user (and
@@ -628,10 +672,16 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                                 : isProviderConnectionError
                                     ? BUILDER_GATEWAY_NETWORK_ERROR_CODE
                                     : (gatewayErrCode ??
-                                        (!explicitErrMsg ? "builder_gateway_error" : undefined));
+                                        (!explicitErrMsg
+                                            ? "builder_gateway_error"
+                                            : // A detailed in-stream error the gateway left uncoded:
+                                                // classify the RAW sentence here, because run persistence
+                                                // would otherwise do it downstream on the visitor line and
+                                                // record `unknown` on the credits lane alone.
+                                                classifyTerminalErrorCode(String(errMsg))));
                         console.error(`[builder-engine] stop reason=error model=${model} code=${errCode ?? "(none)"} error=${errMsg}`);
                         if (isCredentialAuthError) {
-                            await recordBuilderCredentialAuthFailure({
+                            await recordBuilderGatewayAuthFailure({
                                 code: typeof gatewayErrCode === "string" ? gatewayErrCode : errCode,
                                 message: String(errMsg),
                             });
@@ -652,12 +702,16 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                                 rawEvent: event,
                             });
                         }
-                        yield {
-                            type: "stop",
-                            reason: "error",
-                            error: errMsg,
+                        yield stop({
+                            error: String(errMsg),
                             ...(errCode ? { errorCode: errCode } : {}),
-                        };
+                            // The upstream provider giving up ("Overloaded", a bare 529) is
+                            // retryable, and the raw text is the only place it says so — a
+                            // stop event carries no status.
+                            ...(isTransientGatewayFailure(String(errMsg))
+                                ? { providerRetryable: true }
+                                : {}),
+                        });
                     }
                     else if (reason === "end_turn" ||
                         reason === "tool_use" ||
@@ -666,11 +720,7 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                         yield { type: "stop", reason };
                     }
                     else {
-                        yield {
-                            type: "stop",
-                            reason: "error",
-                            error: `Unknown stop reason: ${reason}`,
-                        };
+                        yield stop({ error: `Unknown stop reason: ${reason}` });
                     }
                     return;
                 }
@@ -683,11 +733,10 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
         flushPending();
         yield* recoverUndeliveredToolCalls();
         yield { type: "assistant-content", parts };
-        yield {
-            type: "stop",
-            reason: "error",
+        yield gatewayErrorStop({
             error: "Builder gateway stream ended without a stop event",
-        };
+            errorCode: BUILDER_GATEWAY_STREAM_ENDED_ERROR_CODE,
+        }, captureContext.creditsLane);
     }
     catch (err) {
         const timedOut = captureContext.didGatewayTimeout?.() ?? false;
@@ -705,7 +754,7 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                     : undefined,
             });
         }
-        yield createBuilderGatewayTimeoutStop(err, timedOut, gatewayTimeoutMs);
+        yield createBuilderGatewayTimeoutStop(err, timedOut, gatewayTimeoutMs, captureContext.creditsLane);
     }
     finally {
         // Release the reader on every exit path — early returns (invalid JSONL,
@@ -914,18 +963,32 @@ function normalizeBuilderGatewayFetchError(err, timedOut, timeoutMs) {
     }
     return message;
 }
-function createBuilderGatewayTimeoutStop(err, timedOut, timeoutMs) {
-    const networkError = !timedOut && isBuilderGatewayNetworkError(err);
-    return {
-        type: "stop",
-        reason: "error",
-        error: normalizeBuilderGatewayFetchError(err, timedOut, timeoutMs),
-        ...(timedOut
-            ? { errorCode: "builder_gateway_timeout" }
-            : networkError
-                ? { errorCode: BUILDER_GATEWAY_NETWORK_ERROR_CODE }
-                : {}),
-    };
+/**
+ * Derived from the RAW error before `gatewayErrorStop` replaces the message: on
+ * the credits lane run-manager has no text left to classify at persistence time,
+ * and a run persisted as `unknown` reads as "do not attempt recovery".
+ */
+function createBuilderGatewayTimeoutStop(err, timedOut, timeoutMs, creditsLane) {
+    const error = normalizeBuilderGatewayFetchError(err, timedOut, timeoutMs);
+    if (timedOut) {
+        // Deliberately no `providerRetryable`: the timeout spent the whole request
+        // budget, so the recovery is a fresh invocation (the client's
+        // `builder_gateway_timeout` continuation), never an in-call retry.
+        return gatewayErrorStop({ error, errorCode: "builder_gateway_timeout" }, creditsLane);
+    }
+    if (isBuilderGatewayNetworkError(err)) {
+        return gatewayErrorStop({
+            error,
+            errorCode: BUILDER_GATEWAY_NETWORK_ERROR_CODE,
+            providerRetryable: true,
+        }, creditsLane);
+    }
+    const errorCode = classifyTerminalErrorCode(error);
+    return gatewayErrorStop({
+        error,
+        ...(errorCode ? { errorCode } : {}),
+        ...(isTransientGatewayFailure(error) ? { providerRetryable: true } : {}),
+    }, creditsLane);
 }
 function formatTimeoutMs(timeoutMs) {
     if (timeoutMs < 1000)

package/dist/agent/engine/builtin.js

@@ -18,10 +18,13 @@ export function registerBuiltinEngines() {
         return;
     _registered = true;
     // ── Builder.io managed gateway ─────────────────────────────────────────────
-    // Registered first so detectEngineFromEnv picks it when both Builder keys
-    // are set — Builder is the managed path we want everyone on long-term.
-    // Users who prefer BYO keys can opt out via AGENT_ENGINE_PREFER_BYO_KEY=true,
-    // which drops Builder to the fallback slot in detectEngineFromEnv.
+    // Registered first, so it wins whenever a customer configured Builder — the
+    // legacy key pair included. Two credential shapes select it: a user's own
+    // connection via that pair, or the deployment's Builder-credits token plus
+    // space id, which is the only lane an anonymous visitor on a hosted site has.
+    // Only the injected Builder-credits set is marked deployInjected, so it alone
+    // steps aside for a provider key the customer set (see selectDetectedEngine);
+    // users who prefer BYO everywhere can still set AGENT_ENGINE_PREFER_BYO_KEY.
     registerAgentEngine({
         name: "builder",
         label: "Builder.io Gateway",
@@ -30,6 +33,12 @@ export function registerBuiltinEngines() {
         defaultModel: BUILDER_DEFAULT_MODEL,
         supportedModels: BUILDER_SUPPORTED_MODELS,
         requiredEnvVars: ["BUILDER_PRIVATE_KEY", "BUILDER_PUBLIC_KEY"],
+        alternateRequiredEnvVars: [
+            {
+                envVars: ["BUILDER_GATEWAY_TOKEN", "BUILDER_GATEWAY_SPACE_ID"],
+                deployInjected: true,
+            },
+        ],
         create: (config) => createBuilderEngine(config),
     });
     // ── Anthropic ──────────────────────────────────────────────────────────────