@agent-native/core 0.161.0 → 0.161.2

package/corpus/templates/analytics/server/lib/first-party-analytics-backend.ts

@@ -34,6 +34,23 @@ export interface FirstPartyAnalyticsScope {
   orgId: string | null;
 }
 
+/**
+ * Stored panel SQL is valid PostgreSQL but has no BigQuery equivalent. This is
+ * not a query failure: the panel cannot run for this scope until its SQL or the
+ * scope's sink changes, so retrying is pointless and callers render an
+ * explanatory state instead. `construct` names the exact syntax that has no
+ * mapping, and is the only part safe to show a user.
+ */
+export class FirstPartyAnalyticsUnsupportedSqlError extends Error {
+  readonly construct: string;
+
+  constructor(construct: string, message: string) {
+    super(message);
+    this.name = "FirstPartyAnalyticsUnsupportedSqlError";
+    this.construct = construct;
+  }
+}
+
 interface FirstPartyAnalyticsBackendSetting {
   sink?: unknown;
   table?: unknown;
@@ -572,6 +589,59 @@ function rewriteOutsideSqlLiterals(
   return result;
 }
 
+const SQL_LITERAL_PLACEHOLDER_PREFIX = "_fpa_lit_";
+
+/**
+ * Same intent as `rewriteOutsideSqlLiterals`, but `rewrite` sees one string
+ * with each literal stood in for by an identifier-shaped placeholder rather
+ * than a sequence of fragments split at every quote. A cast operand routinely
+ * sits on the far side of a literal — `'2026-08-01'::date`,
+ * `(COALESCE(properties, '{}'))::text` — and the fragment view cuts that
+ * operand in half, which is why both read as "invalid PostgreSQL cast".
+ */
+function rewriteWithMaskedSqlLiterals(
+  sql: string,
+  rewrite: (code: string) => string,
+): string {
+  if (sql.includes(SQL_LITERAL_PLACEHOLDER_PREFIX)) {
+    throw new FirstPartyAnalyticsUnsupportedSqlError(
+      `an identifier reserved for query translation (${SQL_LITERAL_PLACEHOLDER_PREFIX}*)`,
+      `First-party BigQuery query cannot use identifiers starting with ${SQL_LITERAL_PLACEHOLDER_PREFIX}`,
+    );
+  }
+  const literals: string[] = [];
+  let masked = "";
+  let cursor = 0;
+  while (cursor < sql.length) {
+    const literalStart = sql.indexOf("'", cursor);
+    if (literalStart === -1) {
+      masked += sql.slice(cursor);
+      break;
+    }
+    masked += sql.slice(cursor, literalStart);
+    let literalEnd = literalStart + 1;
+    while (literalEnd < sql.length) {
+      if (sql[literalEnd] !== "'") {
+        literalEnd++;
+        continue;
+      }
+      if (sql[literalEnd + 1] === "'") {
+        literalEnd += 2;
+        continue;
+      }
+      literalEnd++;
+      break;
+    }
+    masked += `${SQL_LITERAL_PLACEHOLDER_PREFIX}${literals.length}_`;
+    literals.push(sql.slice(literalStart, literalEnd));
+    cursor = literalEnd;
+  }
+  return rewrite(masked).replace(
+    new RegExp(`${SQL_LITERAL_PLACEHOLDER_PREFIX}(\\d+)_`, "g"),
+    (whole, index: string) => literals[Number(index)] ?? whole,
+  );
+}
+
 function findMatchingSqlParen(sql: string, openIndex: number): number {
   let depth = 0;
   let inLiteral = false;
@@ -697,6 +767,46 @@ function coerceDateComparisonOperands(sql: string): string {
   );
 }
 
+/**
+ * Extent of the operand a `::` cast at `castIndex` applies to.
+ *
+ * The function-call case is the trap: stopping at the matching `(` leaves the
+ * function name outside the rewritten CAST, so `sum(x)::numeric` became
+ * `sumCAST((x) AS NUMERIC)` and BigQuery answered `Function not found: SUMCAST`.
+ */
+function postgresCastOperandBounds(
+  code: string,
+  castIndex: number,
+): { start: number; end: number } {
+  let end = castIndex;
+  while (end > 0 && /\s/.test(code[end - 1] ?? "")) {
+    end--;
+  }
+  let start = end;
+  if (code[end - 1] === ")") {
+    let depth = 0;
+    for (let index = end - 1; index >= 0; index--) {
+      if (code[index] === ")") depth++;
+      if (code[index] !== "(") continue;
+      depth--;
+      if (depth === 0) {
+        start = index;
+        break;
+      }
+    }
+  }
+  while (start > 0 && /[A-Za-z0-9_.$]/.test(code[start - 1] ?? "")) {
+    start--;
+  }
+  if (start === end) {
+    throw new FirstPartyAnalyticsUnsupportedSqlError(
+      "a PostgreSQL cast with no readable operand",
+      "First-party BigQuery query has an invalid PostgreSQL cast",
+    );
+  }
+  return { start, end };
+}
+
 function replacePostgresCastsInCode(code: string): string {
   const castType = new RegExp(
     "::\\s*(date|timestamp|timestamptz|int|int2|int4|int8|integer|float|float4|float8|double\\s+precision|numeric|text|varchar|boolean|bool|json|jsonb)\\b",
@@ -728,40 +838,16 @@ function replacePostgresCastsInCode(code: string): string {
     };
     const targetType = mappedType[normalizedType];
     if (!targetType) {
-      throw new Error(
+      throw new FirstPartyAnalyticsUnsupportedSqlError(
+        `a PostgreSQL ${normalizedType} cast`,
         `First-party BigQuery query does not support PostgreSQL ${normalizedType} casts`,
       );
     }
 
-    let operandEnd = match.index;
-    while (operandEnd > 0 && /\s/.test(result[operandEnd - 1] ?? "")) {
-      operandEnd--;
-    }
-    let operandStart = operandEnd;
-    if (result[operandEnd - 1] === ")") {
-      let depth = 0;
-      for (let index = operandEnd - 1; index >= 0; index--) {
-        if (result[index] === ")") depth++;
-        if (result[index] !== "(") continue;
-        depth--;
-        if (depth === 0) {
-          operandStart = index;
-          break;
-        }
-      }
-    } else {
-      while (
-        operandStart > 0 &&
-        /[A-Za-z0-9_.$]/.test(result[operandStart - 1] ?? "")
-      ) {
-        operandStart--;
-      }
-    }
-    if (operandStart === operandEnd) {
-      throw new Error(
-        "First-party BigQuery query has an invalid PostgreSQL cast",
-      );
-    }
+    const { start: operandStart, end: operandEnd } = postgresCastOperandBounds(
+      result,
+      match.index,
+    );
     const operand = result.slice(operandStart, operandEnd).trim();
     const castEnd = match.index + match[0].length;
     result = `${result.slice(0, operandStart)}CAST(${operand} AS ${targetType})${result.slice(castEnd)}`;
@@ -810,12 +896,45 @@ function replaceBigQueryDateArithmetic(code: string): string {
   return translated;
 }
 
+/**
+ * PostgreSQL truncates to the start of the ISO week (Monday); BigQuery's bare
+ * `WEEK` starts on Sunday, so the week mapping must name the weekday or the
+ * same query silently buckets differently on each backend.
+ */
+const BIGQUERY_DATE_TRUNC_PARTS: Record<string, string> = {
+  day: "DAY",
+  week: "WEEK(MONDAY)",
+  month: "MONTH",
+  quarter: "QUARTER",
+  year: "YEAR",
+};
+
+/**
+ * BigQuery JSONPath field names are always quoted here rather than only when
+ * they look unusual: an unquoted `$.$ai_model` is rejected outright, and an
+ * unquoted `$.page.title` silently reads a nested field the caller never asked
+ * for.
+ */
+function bigQueryJsonPath(key: string): string {
+  return `'$."${key.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"'`;
+}
+
 function translatePostgresJsonOperators(sql: string): string {
-  return sql.replace(
-    /\b([A-Za-z_][A-Za-z0-9_.]*)\s*::\s*jsonb\s*->>\s*'([^']+)'/gi,
-    (_match, expression: string, key: string) =>
-      `JSON_VALUE(${expression}, '$.${key}')`,
-  );
+  const jsonExtract = /\s*::\s*jsonb?\s*->>\s*'([^']*)'/gi;
+  let result = sql;
+  let match = jsonExtract.exec(result);
+  while (match) {
+    const { start, end } = postgresCastOperandBounds(result, match.index);
+    const operand = result.slice(start, end).trim();
+    const replacement = `JSON_VALUE(${operand}, ${bigQueryJsonPath(match[1] ?? "")})`;
+    result =
+      result.slice(0, start) +
+      replacement +
+      result.slice(match.index + match[0].length);
+    jsonExtract.lastIndex = start + replacement.length;
+    match = jsonExtract.exec(result);
+  }
+  return result;
 }
 
 function translateFirstPartyAnalyticsBigQuerySql(sql: string): string {
@@ -837,16 +956,20 @@ function translateFirstPartyAnalyticsBigQuerySql(sql: string): string {
       `INTERVAL ${amount} ${unit.replace(/s$/i, "").toUpperCase()}`,
   );
   translated = rewriteSqlFunctionCalls(translated, "date_trunc", (args) => {
-    if (args.length !== 2 || !/^'week'$/i.test(args[0] ?? "")) {
-      throw new Error(
-        "First-party BigQuery query only supports PostgreSQL date_trunc('week', ...) expressions",
+    const unit = /^'([a-z]+)'$/i.exec(args[0] ?? "")?.[1]?.toLowerCase();
+    const datePart = unit ? BIGQUERY_DATE_TRUNC_PARTS[unit] : undefined;
+    if (args.length !== 2 || !datePart) {
+      throw new FirstPartyAnalyticsUnsupportedSqlError(
+        `date_trunc(${args[0] ?? "?"}, ...)`,
+        `First-party BigQuery query supports PostgreSQL date_trunc with ${Object.keys(BIGQUERY_DATE_TRUNC_PARTS).join(", ")}`,
       );
     }
-    return `DATE_TRUNC(CAST(${translatePostgresDateExpression(args[1] ?? "")} AS DATE), WEEK(MONDAY))`;
+    return `DATE_TRUNC(CAST(${translatePostgresDateExpression(args[1] ?? "")} AS DATE), ${datePart})`;
   });
   translated = rewriteSqlFunctionCalls(translated, "to_char", (args) => {
     if (args.length !== 2 || !/^'YYYY-MM-DD'$/i.test(args[1] ?? "")) {
-      throw new Error(
+      throw new FirstPartyAnalyticsUnsupportedSqlError(
+        `to_char(..., ${args[1] ?? "?"})`,
         "First-party BigQuery query only supports PostgreSQL to_char(..., 'YYYY-MM-DD') expressions",
       );
     }
@@ -854,7 +977,10 @@ function translateFirstPartyAnalyticsBigQuerySql(sql: string): string {
   });
   translated = rewriteSqlFunctionCalls(translated, "chr", (args) => {
     if (args.length !== 1) {
-      throw new Error("First-party BigQuery query has an invalid chr call");
+      throw new FirstPartyAnalyticsUnsupportedSqlError(
+        "a multi-argument chr(...) call",
+        "First-party BigQuery query has an invalid chr call",
+      );
     }
     return `CHR(${args[0]})`;
   });
@@ -864,14 +990,15 @@ function translateFirstPartyAnalyticsBigQuerySql(sql: string): string {
     translated = rewriteSqlFunctionCalls(translated, "split_part", (args) => {
       const index = Number(args[2]);
       if (args.length !== 3 || !Number.isInteger(index) || index < 1) {
-        throw new Error(
+        throw new FirstPartyAnalyticsUnsupportedSqlError(
+          "split_part(...) with a non-literal or non-positive index",
           "First-party BigQuery query only supports split_part with a positive integer index",
         );
       }
       return `SPLIT(${args[0]}, ${args[1]})[SAFE_OFFSET(${index - 1})]`;
     });
   }
-  translated = rewriteOutsideSqlLiterals(translated, (code) => {
+  translated = rewriteWithMaskedSqlLiterals(translated, (code) => {
     let rewritten = replacePostgresCastsInCode(code);
     rewritten = rewritten
       .replace(/\bnow\s*\(\s*\)/gi, "CURRENT_TIMESTAMP()")
@@ -893,10 +1020,16 @@ function translateFirstPartyAnalyticsBigQuerySql(sql: string): string {
     [/\bINTERVAL\s*'/i, "PostgreSQL interval literals"],
     [/\bAT\s+TIME\s+ZONE\b/i, "AT TIME ZONE"],
     [/\bFILTER\s*\(\s*WHERE\b/i, "FILTER (WHERE ...)"],
+    [/\bDISTINCT\s+ON\b/i, "SELECT DISTINCT ON"],
+    // Anything the JSON translation above could not consume. BigQuery has no
+    // such operators, so leaving it through buys a provider 400 instead of a
+    // rendered explanation.
+    [/->>|->|#>>|@>/, "PostgreSQL JSON operators"],
   ];
   const incompatible = unsupported.find(([pattern]) => pattern.test(code));
   if (incompatible) {
-    throw new Error(
+    throw new FirstPartyAnalyticsUnsupportedSqlError(
+      incompatible[1],
       `First-party analytics query uses unsupported PostgreSQL syntax (${incompatible[1]}) after BigQuery translation`,
     );
   }
@@ -977,6 +1110,16 @@ function addPartitionPrunedEventDeduplication(
   return result;
 }
 
+/**
+ * Throws `FirstPartyAnalyticsUnsupportedSqlError` when this SQL has no BigQuery
+ * translation. Save-time validation runs on the panel's own (unscoped) SQL,
+ * which is a subset of what the read path translates, so a pass here cannot
+ * pass a construct through that the read path would then reject.
+ */
+export function assertFirstPartyAnalyticsBigQuerySql(sql: string): void {
+  translateFirstPartyAnalyticsBigQuerySql(sql);
+}
+
 export function renderFirstPartyAnalyticsBigQuerySql(
   scopedSql: string,
   args: Array<string | null>,

package/corpus/templates/analytics/server/lib/first-party-analytics.ts

@@ -10,6 +10,8 @@ import {
   type DerivedExceptionFields,
 } from "./error-capture.js";
 import {
+  assertFirstPartyAnalyticsBigQuerySql,
+  type FirstPartyAnalyticsSink,
   getFirstPartyAnalyticsBackend,
   getFirstPartyAnalyticsTable,
   insertFirstPartyAnalyticsRows,
@@ -1088,6 +1090,44 @@ function inferSchema(rows: Record<string, unknown>[]): {
   }));
 }
 
+/**
+ * Which store this query actually runs against under a given sink. Save-time
+ * validation and the read path both route through here: a panel validated for
+ * one store and executed against the other is the whole bug class.
+ */
+function firstPartyAnalyticsQueryTarget(
+  sql: string,
+  sink: FirstPartyAnalyticsSink,
+): "sql-store" | "bigquery" {
+  if (sink !== "bigquery") return "sql-store";
+  const usesSessionRecordings = /\bsession_recordings\b/i.test(sql);
+  const usesEventTables =
+    /\banalytics_events\b|\banalytics_event_daily_rollups\b|\banalytics_user_days\b/i.test(
+      sql,
+    );
+  if (usesSessionRecordings && usesEventTables) {
+    throw new Error(
+      "Cross-backend joins are not supported; query first-party event tables in BigQuery and session_recordings in the Analytics SQL store separately.",
+    );
+  }
+  return usesSessionRecordings ? "sql-store" : "bigquery";
+}
+
+/**
+ * Save-time counterpart to `queryFirstPartyAnalytics`. `sink` is a mutable
+ * per-scope setting, so generic PostgreSQL validation alone accepts panels the
+ * live backend cannot execute.
+ */
+export async function validateFirstPartyAnalyticsSqlForScope(
+  sql: string,
+  scope: AnalyticsScope,
+): Promise<void> {
+  validateFirstPartyAnalyticsSql(sql);
+  const backend = await getFirstPartyAnalyticsBackend(scope);
+  if (firstPartyAnalyticsQueryTarget(sql, backend.sink) !== "bigquery") return;
+  assertFirstPartyAnalyticsBigQuerySql(sql);
+}
+
 export async function queryFirstPartyAnalytics(
   sql: string,
   scope: AnalyticsScope,
@@ -1095,22 +1135,10 @@ export async function queryFirstPartyAnalytics(
 ): Promise<AnalyticsQueryResult> {
   validateFirstPartyAnalyticsSql(sql);
   const backend = await getFirstPartyAnalyticsBackend(scope);
-  if (backend.sink === "bigquery") {
-    const usesSessionRecordings = /\bsession_recordings\b/i.test(sql);
-    const usesEventTables =
-      /\banalytics_events\b|\banalytics_event_daily_rollups\b|\banalytics_user_days\b/i.test(
-        sql,
-      );
-    if (usesSessionRecordings && usesEventTables) {
-      throw new Error(
-        "Cross-backend joins are not supported; query first-party event tables in BigQuery and session_recordings in the Analytics SQL store separately.",
-      );
-    }
-    if (!usesSessionRecordings) {
-      const table = await getFirstPartyAnalyticsTable(backend.table);
-      const scoped = scopedAnalyticsSql(sql, scope);
-      return queryFirstPartyAnalyticsInBigQuery(scoped.sql, scoped.args, table);
-    }
+  if (firstPartyAnalyticsQueryTarget(sql, backend.sink) === "bigquery") {
+    const table = await getFirstPartyAnalyticsTable(backend.table);
+    const scoped = scopedAnalyticsSql(sql, scope);
+    return queryFirstPartyAnalyticsInBigQuery(scoped.sql, scoped.args, table);
   }
   const scoped = scopedAnalyticsSql(sql, scope);
   const wrappedSql = `SELECT * FROM (${scoped.sql}) AS first_party_analytics_query LIMIT ${MAX_QUERY_ROWS}`;

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

@@ -21,7 +21,7 @@ import { isInBackgroundFunctionRuntime } from "../durable-background.js";
 import { BUILDER_MODEL_CONFIG } from "../model-config.js";
 import { getBuilderGatewayRequestHeaders } from "./builder-gateway-headers.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 { classifyTerminalErrorCode, describeErrorWithCauses, isBuilderGatewayInternalErrorMessage, 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";
@@ -340,6 +340,11 @@ function isTransientGatewayFailure(rawMessage, status) {
     if (status !== undefined && RETRYABLE_GATEWAY_STATUSES.has(status)) {
         return true;
     }
+    // The gateway's unhandled-500 envelope, which reaches the in-stream error
+    // frame with no status at all. Without this it read as terminal there while
+    // the identical body read as retryable when it arrived as an HTTP 500.
+    if (isBuilderGatewayInternalErrorMessage(rawMessage))
+        return true;
     return TRANSIENT_UPSTREAM_PATTERN.test(rawMessage);
 }
 /**
@@ -650,6 +655,7 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                         const explicitErrMsg = event.error || event.message || event.detail;
                         const errMsg = explicitErrMsg ??
                             `Gateway error (no detail; raw event: ${JSON.stringify(event)})`;
+                        const gatewayRequestId = typeof event.requestId === "string" ? event.requestId : undefined;
                         const gatewayErrCode = event.errorCode ?? event.code;
                         // The gateway already authenticated this request before streaming,
                         // so a bare "Unauthorized" here means the account cannot use this
@@ -679,7 +685,7 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                                                 // 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}`);
+                        console.error(`[builder-engine] stop reason=error model=${model} code=${errCode ?? "(none)"} requestId=${gatewayRequestId ?? "(none)"} error=${errMsg}`);
                         if (isCredentialAuthError) {
                             await recordBuilderGatewayAuthFailure({
                                 code: typeof gatewayErrCode === "string" ? gatewayErrCode : errCode,
@@ -694,9 +700,7 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                         // it's thrown, but without these tags.
                         if (!explicitErrMsg) {
                             captureBuilderGatewayNoDetailError({
-                                requestId: typeof event.requestId === "string"
-                                    ? event.requestId
-                                    : undefined,
+                                requestId: gatewayRequestId,
                                 model,
                                 gatewayUrl: captureContext.gatewayUrl,
                                 rawEvent: event,
@@ -711,6 +715,10 @@ async function* parseJsonlStream(reader, model, captureContext = {}) {
                             ...(isTransientGatewayFailure(String(errMsg))
                                 ? { providerRetryable: true }
                                 : {}),
+                            // requestId rides the stop event whether or not the gateway sent a
+                            // message: a message like "...ERROR ID: <hex>" is as opaque as no
+                            // message at all, and this is the only key that reaches upstream.
+                            ...(gatewayRequestId ? { requestId: gatewayRequestId } : {}),
                         });
                     }
                     else if (reason === "end_turn" ||

package/dist/agent/engine/error-detail.d.ts

@@ -35,6 +35,23 @@ export declare function isProviderConnectionError(err: unknown): boolean;
  * for every other engine, which still delivers its own message intact.
  */
 export declare function isContextOverflowMessage(message: string): boolean;
+/**
+ * The Builder gateway's own 500 envelope, which is the whole message: an
+ * apology sentence plus a correlation id, e.g. "Sorry, we ran into an issue
+ * processing your request. ERROR ID: 0f3c...". The apology prose varies; the
+ * correlation id does not, so that is what the predicate below anchors on.
+ */
+export declare const BUILDER_GATEWAY_INTERNAL_ERROR_CODE = "builder_gateway_internal_error";
+/**
+ * The gateway attaches that envelope to an unhandled 500, and it arrives two
+ * ways: as an HTTP body, which is already retried because 500 is in the
+ * engine's retryable status set, and as an in-stream error frame after the
+ * gateway has already answered 200, where there is no status to read and the
+ * prose carries no keyword any other predicate here matches. Naming it is what
+ * makes the second path behave like the first instead of dying uncoded on the
+ * first attempt.
+ */
+export declare function isBuilderGatewayInternalErrorMessage(message: string): boolean;
 /** The overflow codes a provider or gateway may report instead of prose. */
 export declare function isContextOverflowCode(code: string | undefined): boolean;
 /** Classification fields an AI SDK provider failure carries. */

package/dist/agent/engine/error-detail.js

@@ -83,6 +83,28 @@ export function isContextOverflowMessage(message) {
         msg.includes("input token count exceeds") ||
         msg.includes("request too large"));
 }
+/**
+ * The Builder gateway's own 500 envelope, which is the whole message: an
+ * apology sentence plus a correlation id, e.g. "Sorry, we ran into an issue
+ * processing your request. ERROR ID: 0f3c...". The apology prose varies; the
+ * correlation id does not, so that is what the predicate below anchors on.
+ */
+export const BUILDER_GATEWAY_INTERNAL_ERROR_CODE = "builder_gateway_internal_error";
+const BUILDER_GATEWAY_ERROR_ID_PATTERN = /\berror id:\s*([0-9a-f]+)\b/i;
+const BUILDER_GATEWAY_ERROR_ID_MIN_CHARS = 8;
+/**
+ * The gateway attaches that envelope to an unhandled 500, and it arrives two
+ * ways: as an HTTP body, which is already retried because 500 is in the
+ * engine's retryable status set, and as an in-stream error frame after the
+ * gateway has already answered 200, where there is no status to read and the
+ * prose carries no keyword any other predicate here matches. Naming it is what
+ * makes the second path behave like the first instead of dying uncoded on the
+ * first attempt.
+ */
+export function isBuilderGatewayInternalErrorMessage(message) {
+    const match = BUILDER_GATEWAY_ERROR_ID_PATTERN.exec(message);
+    return (match !== null && match[1].length >= BUILDER_GATEWAY_ERROR_ID_MIN_CHARS);
+}
 /** The overflow codes a provider or gateway may report instead of prose. */
 export function isContextOverflowCode(code) {
     const normalized = (code ?? "").toLowerCase();
@@ -203,5 +225,10 @@ export function classifyTerminalErrorCode(message) {
     if (/(?:err_)?ssl|tlsv?\d|tls handshake|ssl routines|econnreset|econnrefused|und_err_socket|socket hang up/i.test(message)) {
         return "provider_network_error";
     }
+    // Last, so a gateway 500 whose body happens to quote a more specific upstream
+    // failure keeps that classification instead of collapsing to this one.
+    if (isBuilderGatewayInternalErrorMessage(message)) {
+        return BUILDER_GATEWAY_INTERNAL_ERROR_CODE;
+    }
     return undefined;
 }

package/dist/agent/engine/types.d.ts

@@ -26,6 +26,8 @@ export declare class EngineError extends Error {
     readonly statusCode?: number;
     /** Whether the provider explicitly marked this error as retryable. */
     readonly providerRetryable?: boolean;
+    /** Upstream request id, when the provider/gateway supplied one. */
+    readonly requestId?: string;
     /**
      * Whether the request exceeded the model's context window. Set by engines that
      * classified the provider's own reply, because the delivered message may not
@@ -39,6 +41,7 @@ export declare class EngineError extends Error {
         upgradeUrl?: string;
         statusCode?: number;
         providerRetryable?: boolean;
+        requestId?: string;
         contextOverflow?: boolean;
     });
 }
@@ -196,6 +199,13 @@ export type EngineEvent = {
      * should retry even if status code / message patterns don't match.
      */
     providerRetryable?: boolean;
+    /**
+     * Upstream request id, when the provider/gateway supplies one. This is
+     * the only key that ties a user-facing error back to the upstream log,
+     * so it must survive to the capture even when the error also carries a
+     * message — an opaque message is not a diagnostic.
+     */
+    requestId?: string;
     /**
      * The request exceeded the model's context window. Carried structurally
      * for the same reason as `providerRetryable`: `error` is visitor copy on a

package/dist/agent/engine/types.js

@@ -25,6 +25,8 @@ export class EngineError extends Error {
     statusCode;
     /** Whether the provider explicitly marked this error as retryable. */
     providerRetryable;
+    /** Upstream request id, when the provider/gateway supplied one. */
+    requestId;
     /**
      * Whether the request exceeded the model's context window. Set by engines that
      * classified the provider's own reply, because the delivered message may not
@@ -40,6 +42,7 @@ export class EngineError extends Error {
         this.upgradeUrl = opts?.upgradeUrl;
         this.statusCode = opts?.statusCode;
         this.providerRetryable = opts?.providerRetryable;
+        this.requestId = opts?.requestId;
         this.contextOverflow = opts?.contextOverflow;
     }
 }

package/dist/agent/production-agent.js

@@ -28,7 +28,7 @@ import { AGENT_CHAT_BACKGROUND_RUN_FIELD, AGENT_CHAT_PROCESS_RUN_PATH, backgroun
 import { applyContextXrayTransformForIteration } from "./engine/context-directives-transform.js";
 import { attemptContinuationDispatch } from "./engine/continuation-dispatch-retry.js";
 import { formatLlmCredentialErrorMessage, LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, userFacingLlmCredentialError, } from "./engine/credential-errors.js";
-import { isContextOverflowCode, isContextOverflowMessage, isProviderConnectionErrorMessage, } from "./engine/error-detail.js";
+import { BUILDER_GATEWAY_INTERNAL_ERROR_CODE, isContextOverflowCode, isContextOverflowMessage, isProviderConnectionErrorMessage, } from "./engine/error-detail.js";
 import { resolveEngine, explicitEngineName, registerBuiltinEngines, getStoredModelForEngine, normalizeModelForEngine, isResolvedEngineUsableForRequest, } from "./engine/index.js";
 import { resolveEmptyResponseRetryMaxOutputTokens, resolveMainChatMaxOutputTokens, resolveMaxOutputTokensForEngine, } from "./engine/output-tokens.js";
 import { PROVIDER_TO_ENV } from "./engine/provider-env-vars.js";
@@ -880,6 +880,9 @@ export function isRetryableError(err) {
             return true;
     }
     return (code === "builder_gateway_error" ||
+        // The gateway's unhandled-500 envelope arriving in-stream, where there is no
+        // status to read. Same failure as `http_500` below, so same verdict.
+        code === BUILDER_GATEWAY_INTERNAL_ERROR_CODE ||
         code === "builder_gateway_network_error" ||
         code === "provider_network_error" ||
         code === "http_429" ||
@@ -3749,6 +3752,7 @@ export async function runAgentLoop(opts) {
                                     statusCode: event.statusCode,
                                     providerRetryable: event.providerRetryable,
                                     contextOverflow: event.contextOverflow,
+                                    requestId: event.requestId,
                                 });
                             }
                         }
@@ -5177,6 +5181,8 @@ export function isRecoverableContinuationError(event) {
         // the server read the sentence instead, which a Builder-credits deployment
         // replaces with one visitor line.
         code === "http_500" ||
+        // The same 500, delivered in-stream with no status attached.
+        code === BUILDER_GATEWAY_INTERNAL_ERROR_CODE ||
         code === "http_502" ||
         code === "http_503" ||
         code === "http_504" ||

package/dist/agent/run-manager.js

@@ -1060,6 +1060,10 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
     let pendingTerminalEvent = null;
     const captureRunError = (error, phase) => {
         const errorCode = getRunErrorCode(error);
+        // A gateway error often arrives as one opaque user-facing sentence, so the
+        // structured fields EngineError already carries are the whole diagnostic.
+        // Dropping them here left operators with an error id and nothing to join on.
+        const engineError = error instanceof EngineError ? error : null;
         captureError(error, {
             route: "/_agent-native/agent-chat",
             aiTraceId: runId,
@@ -1070,6 +1074,10 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
                 softTimedOut: softTimedOut ? "true" : "false",
                 abortReason: run.abortReason,
                 errorCode,
+                gatewayRequestId: engineError?.requestId,
+                statusCode: engineError?.statusCode != null
+                    ? String(engineError.statusCode)
+                    : undefined,
             },
             extra: {
                 runId,

package/dist/agent/thread-data-builder.js

@@ -1,5 +1,6 @@
 import { formatChatErrorText, normalizeChatError, } from "../client/error-format.js";
 import { isCredentialGapCodeAgentEvent, normalizeCodeAgentTranscript, } from "../code-agents/transcript-normalizer.js";
+import { BUILDER_GATEWAY_INTERNAL_ERROR_CODE } from "./engine/error-detail.js";
 const INTERRUPTED_TOOL_RESULT = "Interrupted before this tool returned a result.";
 export const ASSISTANT_RUN_DURATION_METADATA_KEY = "agentNativeRunDurationMs";
 const MAX_STORED_ATTACHMENT_CHARS = 60_000;
@@ -20,6 +21,10 @@ function isInternalContinuationError(event) {
         code === "http_408" ||
         code === "http_429" ||
         code === "http_500" ||
+        // The gateway's unhandled-500 envelope arriving in-stream. Without this the
+        // turn stored Builder's internal correlation id as the assistant's visible
+        // answer instead of a continuation.
+        code === BUILDER_GATEWAY_INTERNAL_ERROR_CODE ||
         code === "http_502" ||
         code === "http_503" ||
         code === "http_504" ||