@agent-native/core 0.161.1 → 0.161.4

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/corpus/templates/clips/actions/save-browser-transcript.ts

@@ -26,8 +26,19 @@ import { buildCaptionSegmentsFromText } from "../shared/transcript-segments.js";
 import { booleanParam } from "./lib/cli-params.js";
 import { isAutoTitleReplaceable } from "./lib/title-source.js";
 
-function nativeSegmentsJson(fullText: string): string {
-  return JSON.stringify(buildCaptionSegmentsFromText(fullText));
+// web-speech and macos-native are both mic-only engines — see
+// transcription-engine.ts's file header. When a caller sends fullText with
+// no segments (word-level timings were never captured), there's no
+// per-line source to preserve, but for these two engines there's also no
+// ambiguity: every word came from the mic. Leaving source undefined here
+// falls through to resolveSpeaker's default and renders the whole thing as
+// "Them". Whisper mixes mic + system, so it has no safe single-speaker guess.
+function nativeSegmentsJson(
+  fullText: string,
+  engineSource?: "web-speech" | "macos-native" | "whisper",
+): string {
+  const source = engineSource && engineSource !== "whisper" ? "mic" : undefined;
+  return JSON.stringify(buildCaptionSegmentsFromText(fullText, null, source));
 }
 
 // Real transcript segments supplied by a caller that already has accurate
@@ -45,6 +56,11 @@ const segmentSchema = z
     text: z.string(),
     // Stream the segment came from; the transcript UI maps mic→"Me", system→"Them".
     source: z.enum(["mic", "system"]).optional(),
+    // Diarized speaker for this segment, when the provider identifies one.
+    // Declared so zod keeps it: an undeclared key is stripped before the array
+    // is serialized, which would drop a provider's speaker labels on save and
+    // leave the transcript unable to tell its speakers apart on reload.
+    speaker: z.string().nullable().optional(),
   })
   .transform((s) => {
     if (s.endMs < s.startMs) {
@@ -74,7 +90,7 @@ export default defineAction({
       .array(segmentSchema)
       .optional()
       .describe(
-        "Real transcript segments with accurate timestamps (ms). When provided, stored verbatim instead of synthesizing timings from fullText.",
+        "Transcript segments with per-segment timings (ms) and the `mic`/`system` stream each came from. Stored verbatim when provided, instead of synthesizing timings from fullText. Timings are the engine's own where it reported them; the mic-only engines report none, so callers may send estimates to keep each segment's speaker.",
       ),
     overwriteReady: booleanParam
       .default(false)
@@ -97,7 +113,7 @@ export default defineAction({
     const segmentsJson =
       args.segments && args.segments.length > 0
         ? JSON.stringify(args.segments)
-        : nativeSegmentsJson(fullText);
+        : nativeSegmentsJson(fullText, args.source);
 
     const [current] = await db
       .select({