@agent-native/core 0.80.0 → 0.80.1

package/corpus/templates/analytics/server/lib/real-data-actions.ts

@@ -69,9 +69,33 @@ const MCP_DATA_SOURCE_TOKENS = [
   "stripe",
 ];
 
+function normalizeActionToolName(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-")
+    .replace(/-+/g, "-");
+}
+
+function isToolName(name: string, expected: string): boolean {
+  return normalizeActionToolName(name) === expected;
+}
+
+function isDataQueryActionName(name: string): boolean {
+  return DATA_QUERY_ACTIONS.has(normalizeActionToolName(name));
+}
+
+function isCorpusSourceActionName(name: string): boolean {
+  return CORPUS_SOURCE_ACTIONS.has(normalizeActionToolName(name));
+}
+
+function isCorpusReductionActionName(name: string): boolean {
+  return CORPUS_REDUCTION_ACTIONS.has(normalizeActionToolName(name));
+}
+
 function isMcpDataSourceTool(name: string): boolean {
-  if (!name.startsWith("mcp__")) return false;
   const normalized = name.toLowerCase();
+  if (!normalized.startsWith("mcp__")) return false;
   return MCP_DATA_SOURCE_TOKENS.some((token) => normalized.includes(token));
 }
 
@@ -94,13 +118,13 @@ function getRunCodeBridgeToolNames(content: string | undefined): string[] {
 
 function hasRunCodeDataQueryAttempt(content: string | undefined): boolean {
   return getRunCodeBridgeToolNames(content).some(
-    (name) => DATA_QUERY_ACTIONS.has(name) || isMcpDataSourceTool(name),
+    (name) => isDataQueryActionName(name) || isMcpDataSourceTool(name),
   );
 }
 
 function hasRunCodeCorpusWorkflowAttempt(content: string | undefined): boolean {
   return getRunCodeBridgeToolNames(content).some(
-    (name) => CORPUS_SOURCE_ACTIONS.has(name) || isCorpusCapableMcpTool(name),
+    (name) => isCorpusSourceActionName(name) || isCorpusCapableMcpTool(name),
   );
 }
 
@@ -208,7 +232,7 @@ const UNSUPPORTED_RESULT_CLAIM =
   /(?:\b\d[\d,.]*(?:\.\d+)?\s*(?:%|percent|users?|customers?|accounts?|sessions?|events?|deals?|tickets?|issues?|calls?|messages?|signups?|pageviews?)\b|\$\s*\d|\b(?:data|query|results?)\s+(?:shows?|showed|indicates?|returned|found)\b|\b(?:i found|the top|the bottom|highest|lowest|increased|decreased|grew|declined|converted|churned|retained|averaged|total(?:ed)?|count(?:ed)?)\b)/i;
 
 const SAFE_NO_DATA_RESPONSE =
-  /\b(?:i can't|i cannot|can't retrieve|cannot retrieve|couldn't retrieve|unable to retrieve|don't have access|do not have access|not configured|missing credentials?|need (?:a|the)? ?data source|need to know which source|which source|which data source|clarify|can you|once (?:that'?s|it is) (?:connected|configured|available)|no data source|without a successful|before (?:i|we) can (?:calculate|report|answer|analyze)|i need to query)\b/i;
+  /\b(?:i can't|i cannot|can't retrieve|cannot retrieve|couldn't retrieve|unable to retrieve|don't have access|do not have access|not configured|missing credentials?|need (?:a|the)? ?data source|need to know which source|which source|which data source|clarify|can you|once (?:that'?s|it is) (?:connected|configured|available)|no data source|without a successful|query failed|source query failed|sql failed|error running|before (?:i|we) can (?:calculate|report|answer|analyze)|i need to query)\b/i;
 
 export function isSafeNoDataAnalyticsResponse(text: string): boolean {
   const trimmed = text.trim();
@@ -358,10 +382,10 @@ export function hasIncompleteDataEvidence(
     const name = String(result.name ?? "");
     if (
       name &&
-      !DATA_QUERY_ACTIONS.has(name) &&
+      !isDataQueryActionName(name) &&
       !isMcpDataSourceTool(name) &&
-      name !== "run-code" &&
-      name !== "provider-api-request"
+      !isToolName(name, "run-code") &&
+      !isToolName(name, "provider-api-request")
     ) {
       return false;
     }
@@ -419,11 +443,50 @@ export function hasDataQueryAttempt(
     if (result.isError) return false;
     if (isProviderErrorOnlyContent(result.content)) return false;
     const name = String(result.name ?? "");
-    if (name === "run-code") return hasRunCodeDataQueryAttempt(result.content);
-    return DATA_QUERY_ACTIONS.has(name) || isMcpDataSourceTool(name);
+    if (isToolName(name, "run-code")) {
+      return hasRunCodeDataQueryAttempt(result.content);
+    }
+    return isDataQueryActionName(name) || isMcpDataSourceTool(name);
   });
 }
 
+function isFailedDataQueryAttempt(result: {
+  name?: string;
+  isError?: boolean;
+  content?: string;
+}): boolean {
+  const name = String(result.name ?? "");
+  const isDataQuery =
+    isDataQueryActionName(name) ||
+    isMcpDataSourceTool(name) ||
+    (isToolName(name, "run-code") &&
+      hasRunCodeDataQueryAttempt(result.content));
+  if (!isDataQuery) return false;
+  return result.isError === true || isProviderErrorOnlyContent(result.content);
+}
+
+function compactToolFailure(content: string | undefined): string {
+  const trimmed = String(content ?? "").trim();
+  if (!trimmed) return "the tool returned an error result without details";
+  const max = 900;
+  return trimmed.length > max ? `${trimmed.slice(0, max)}...` : trimmed;
+}
+
+export function failedDataQueryAttemptMessage(
+  toolResults:
+    | Array<{ name?: string; isError?: boolean; content?: string }>
+    | undefined,
+): string | null {
+  const failed = (toolResults ?? []).find(isFailedDataQueryAttempt);
+  if (!failed) return null;
+  const name = String(failed.name ?? "data-source query");
+  return (
+    `I did try \`${name}\`, but it did not return a successful data result: ` +
+    compactToolFailure(failed.content) +
+    "\n\nI need to fix and rerun that query, or report that exact source error instead of giving numbers."
+  );
+}
+
 export function hasCorpusWorkflowAttempt(
   toolResults:
     | Array<{ name?: string; isError?: boolean; content?: string }>
@@ -433,8 +496,8 @@ export function hasCorpusWorkflowAttempt(
     if (result.isError) return false;
     if (isProviderErrorOnlyContent(result.content)) return false;
     const name = String(result.name ?? "");
-    if (CORPUS_SOURCE_ACTIONS.has(name)) return true;
-    if (name === "run-code") {
+    if (isCorpusSourceActionName(name)) return true;
+    if (isToolName(name, "run-code")) {
       return hasRunCodeCorpusWorkflowAttempt(result.content);
     }
 
@@ -453,10 +516,7 @@ export function hasFailedCorpusWorkflowEvidence(
 ): boolean {
   return (toolResults ?? []).some((result) => {
     const name = String(result.name ?? "");
-    if (
-      !CORPUS_SOURCE_ACTIONS.has(name) &&
-      !CORPUS_REDUCTION_ACTIONS.has(name)
-    ) {
+    if (!isCorpusSourceActionName(name) && !isCorpusReductionActionName(name)) {
       return false;
     }
     if (result.isError) return true;
@@ -576,19 +636,20 @@ function actionEvidenceTextForSourceRecords(result: {
   content?: string;
 }): string {
   const name = String(result.name ?? "");
+  const normalizedName = normalizeActionToolName(name);
   const content = String(result.content ?? "");
   const parsed = tryParseJsonContent(content);
 
-  if (name === "provider-corpus-job") {
+  if (normalizedName === "provider-corpus-job") {
     return corpusJobSourceEvidenceText(parsed);
   }
-  if (name === "provider-api-request") {
+  if (normalizedName === "provider-api-request") {
     return providerRequestEvidenceText(parsed);
   }
-  if (name === "query-staged-dataset") {
+  if (normalizedName === "query-staged-dataset") {
     return queryStagedDatasetEvidenceText(parsed);
   }
-  if (name === "gong-calls") {
+  if (normalizedName === "gong-calls") {
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return "";
     }
@@ -600,7 +661,7 @@ function actionEvidenceTextForSourceRecords(result: {
       transcripts: record.transcripts,
     });
   }
-  if (name === "run-code") {
+  if (normalizedName === "run-code") {
     return content;
   }
   if (isCorpusCapableMcpTool(name)) {

package/corpus/templates/analytics/server/lib/replay-storage.ts

@@ -0,0 +1,79 @@
+import { listFileUploadProviders } from "@agent-native/core/file-upload";
+import {
+  resolveHasBuilderPrivateKey,
+  runWithRequestContext,
+} from "@agent-native/core/server";
+
+/**
+ * Session replay chunk bytes are stored through the framework file-upload /
+ * private-blob path (Builder.io CDN by default, or an S3-compatible bucket).
+ * In production we require a configured provider — storing replay chunks inline
+ * in SQL is a local/dev-only fallback. This mirrors the Clips video-storage
+ * contract so replay capture fails loudly (and the UI can prompt setup) instead
+ * of silently recording empty, unplayable sessions.
+ */
+export const REPLAY_STORAGE_SETUP_REQUIRED_REASON =
+  "Session replay storage is not connected yet. Connect Builder.io or configure S3-compatible storage to record replays.";
+
+function appDatabaseUrl(): string {
+  const appName = process.env.APP_NAME?.toUpperCase().replace(/-/g, "_");
+  if (appName) {
+    const appUrl = process.env[`${appName}_DATABASE_URL`];
+    if (appUrl) return appUrl;
+  }
+  return process.env.DATABASE_URL || process.env.NETLIFY_DATABASE_URL || "";
+}
+
+function isLikelyLocalDatabase(): boolean {
+  const url = appDatabaseUrl();
+  return url === "" || url.startsWith("file:") || !url.includes("://");
+}
+
+export function requiresConfiguredReplayStorage(): boolean {
+  return process.env.NODE_ENV === "production" || !isLikelyLocalDatabase();
+}
+
+export interface ReplayStorageResolveContext {
+  userEmail?: string;
+  orgId?: string | null;
+}
+
+/**
+ * Whether a durable upload provider (non-inline) is configured for the given
+ * owner/org scope. Iterates registered providers (e.g. S3) first, then falls
+ * back to a resolvable Builder.io private key. When a scope is supplied the
+ * check runs inside that user/org request context so org-scoped `app_secrets`
+ * credentials resolve — exactly the scope the anonymous replay-ingest path
+ * lacks on its own.
+ */
+export async function hasRequestReplayStorage(
+  context?: ReplayStorageResolveContext,
+): Promise<boolean> {
+  const resolve = async () => {
+    for (const provider of listFileUploadProviders()) {
+      if (provider.id === "builder") continue;
+      if (provider.isConfigured()) return true;
+      if (provider.isConfiguredForRequest) {
+        try {
+          if (await provider.isConfiguredForRequest()) return true;
+        } catch {
+          // Treat a failed scoped lookup as not configured.
+        }
+      }
+    }
+
+    try {
+      return await resolveHasBuilderPrivateKey();
+    } catch {
+      return false;
+    }
+  };
+
+  if (context?.userEmail) {
+    return runWithRequestContext(
+      { userEmail: context.userEmail, orgId: context.orgId ?? undefined },
+      resolve,
+    );
+  }
+  return resolve();
+}

package/corpus/templates/analytics/server/lib/s3-upload-provider.ts

@@ -0,0 +1,255 @@
+/**
+ * S3-compatible file upload provider.
+ *
+ * Works with AWS S3, Cloudflare R2, DigitalOcean Spaces, MinIO, Backblaze B2,
+ * and any other S3-compatible object storage. Uses SigV4 signing via Web Crypto
+ * — no SDK dependency.
+ *
+ * Env vars (S3_* or R2_* prefix, first found wins):
+ *   S3_BUCKET | R2_BUCKET                — required
+ *   S3_ACCESS_KEY_ID | R2_ACCESS_KEY_ID  — required
+ *   S3_SECRET_ACCESS_KEY | R2_SECRET_ACCESS_KEY — required
+ *   S3_ENDPOINT | R2_ENDPOINT            — required (e.g. https://s3.us-east-1.amazonaws.com
+ *                                           or https://<acct>.r2.cloudflarestorage.com)
+ *   S3_REGION | R2_REGION                — optional, default "auto"
+ *   S3_PUBLIC_BASE_URL | R2_PUBLIC_BASE_URL — optional (for public read URLs)
+ */
+
+import type { FileUploadProvider } from "@agent-native/core/file-upload";
+import { resolveSecret } from "@agent-native/core/server";
+
+interface S3Config {
+  region: string;
+  bucket: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  endpoint: string;
+  publicBaseUrl: string | null;
+}
+
+function cleanValue(value: string | null | undefined): string | undefined {
+  const cleaned = value?.trim();
+  return cleaned ? cleaned : undefined;
+}
+
+function buildS3Config(values: {
+  bucket?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  endpoint?: string;
+  region?: string;
+  publicBaseUrl?: string;
+}): S3Config | null {
+  const bucket = cleanValue(values.bucket);
+  const accessKeyId = cleanValue(values.accessKeyId);
+  const secretAccessKey = cleanValue(values.secretAccessKey);
+  const endpoint = cleanValue(values.endpoint);
+  if (!bucket || !accessKeyId || !secretAccessKey || !endpoint) return null;
+  return {
+    region: cleanValue(values.region) ?? "auto",
+    bucket,
+    accessKeyId,
+    secretAccessKey,
+    endpoint: endpoint.replace(/\/+$/, ""),
+    publicBaseUrl:
+      cleanValue(values.publicBaseUrl)?.replace(/\/+$/, "") ?? null,
+  };
+}
+
+function readS3EnvConfig(): S3Config | null {
+  const env = process.env;
+  return buildS3Config({
+    bucket: env.S3_BUCKET || env.R2_BUCKET,
+    accessKeyId: env.S3_ACCESS_KEY_ID || env.R2_ACCESS_KEY_ID,
+    secretAccessKey: env.S3_SECRET_ACCESS_KEY || env.R2_SECRET_ACCESS_KEY,
+    endpoint: env.S3_ENDPOINT || env.R2_ENDPOINT,
+    region: env.S3_REGION || env.R2_REGION,
+    publicBaseUrl: env.S3_PUBLIC_BASE_URL || env.R2_PUBLIC_BASE_URL,
+  });
+}
+
+async function resolveS3Secret(primary: string, fallback: string) {
+  return (
+    cleanValue(await resolveSecret(primary).catch(() => null)) ??
+    cleanValue(await resolveSecret(fallback).catch(() => null))
+  );
+}
+
+async function readS3Config(): Promise<S3Config | null> {
+  return buildS3Config({
+    bucket: await resolveS3Secret("S3_BUCKET", "R2_BUCKET"),
+    accessKeyId: await resolveS3Secret("S3_ACCESS_KEY_ID", "R2_ACCESS_KEY_ID"),
+    secretAccessKey: await resolveS3Secret(
+      "S3_SECRET_ACCESS_KEY",
+      "R2_SECRET_ACCESS_KEY",
+    ),
+    endpoint: await resolveS3Secret("S3_ENDPOINT", "R2_ENDPOINT"),
+    region: await resolveS3Secret("S3_REGION", "R2_REGION"),
+    publicBaseUrl: await resolveS3Secret(
+      "S3_PUBLIC_BASE_URL",
+      "R2_PUBLIC_BASE_URL",
+    ),
+  });
+}
+
+// ── SigV4 helpers (Web Crypto, no SDK) ────────────────────────────────
+
+async function hmac(key: ArrayBuffer, msg: string): Promise<ArrayBuffer> {
+  const k = await crypto.subtle.importKey(
+    "raw",
+    key,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  return crypto.subtle.sign("HMAC", k, new TextEncoder().encode(msg));
+}
+
+async function sha256(data: Uint8Array): Promise<string> {
+  const ab = new ArrayBuffer(data.byteLength);
+  new Uint8Array(ab).set(data);
+  const buf = await crypto.subtle.digest("SHA-256", ab);
+  return toHex(buf);
+}
+
+function toHex(buf: ArrayBuffer): string {
+  const bytes = new Uint8Array(buf);
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+
+async function deriveSigningKey(
+  secret: string,
+  dateStamp: string,
+  region: string,
+): Promise<ArrayBuffer> {
+  const kSecret = new TextEncoder().encode(`AWS4${secret}`);
+  const kDate = await hmac(kSecret.buffer as ArrayBuffer, dateStamp);
+  const kRegion = await hmac(kDate, region);
+  const kService = await hmac(kRegion, "s3");
+  return hmac(kService, "aws4_request");
+}
+
+function rfc3986(str: string): string {
+  return encodeURIComponent(str).replace(
+    /[!'()*]/g,
+    (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase(),
+  );
+}
+
+async function putObject(
+  cfg: S3Config,
+  key: string,
+  body: Uint8Array,
+  contentType: string,
+): Promise<string> {
+  const now = new Date();
+  const amzDate =
+    now
+      .toISOString()
+      .replace(/[:-]|\.\d{3}/g, "")
+      .slice(0, 15) + "Z";
+  const dateStamp = amzDate.slice(0, 8);
+  const credentialScope = `${dateStamp}/${cfg.region}/s3/aws4_request`;
+
+  const hostUrl = new URL(cfg.endpoint);
+  const host = hostUrl.host;
+  const canonicalUri = `/${cfg.bucket}/${key.split("/").map(rfc3986).join("/")}`;
+
+  const payloadHash = await sha256(body);
+
+  const headers: Record<string, string> = {
+    host,
+    "content-type": contentType,
+    "x-amz-content-sha256": payloadHash,
+    "x-amz-date": amzDate,
+  };
+
+  const signedHeaderKeys = Object.keys(headers).sort();
+  const signedHeaders = signedHeaderKeys.join(";");
+  const canonicalHeaders =
+    signedHeaderKeys.map((k) => `${k}:${headers[k]}`).join("\n") + "\n";
+
+  const canonicalRequest = [
+    "PUT",
+    canonicalUri,
+    "", // no query string
+    canonicalHeaders,
+    signedHeaders,
+    payloadHash,
+  ].join("\n");
+
+  const crHash = await sha256(new TextEncoder().encode(canonicalRequest));
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    amzDate,
+    credentialScope,
+    crHash,
+  ].join("\n");
+
+  const signingKey = await deriveSigningKey(
+    cfg.secretAccessKey,
+    dateStamp,
+    cfg.region,
+  );
+  const signature = toHex(await hmac(signingKey, stringToSign));
+
+  const authorization =
+    `AWS4-HMAC-SHA256 Credential=${cfg.accessKeyId}/${credentialScope}, ` +
+    `SignedHeaders=${signedHeaders}, Signature=${signature}`;
+
+  const url = `${cfg.endpoint}${canonicalUri}`;
+  const res = await fetch(url, {
+    method: "PUT",
+    headers: {
+      ...headers,
+      Authorization: authorization,
+      "Content-Length": String(body.byteLength),
+    },
+    body: body.buffer.slice(
+      body.byteOffset,
+      body.byteOffset + body.byteLength,
+    ) as BodyInit,
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(
+      `S3 PutObject failed (${res.status}): ${text || res.statusText}`,
+    );
+  }
+
+  return cfg.publicBaseUrl
+    ? `${cfg.publicBaseUrl}/${key}`
+    : `${cfg.endpoint}/${cfg.bucket}/${key}`;
+}
+
+// ── Provider ──────────────────────────────────────────────────────────
+
+export const s3FileUploadProvider: FileUploadProvider = {
+  id: "s3",
+  name: "S3-compatible storage",
+  isConfigured: () => readS3EnvConfig() !== null,
+  isConfiguredForRequest: async () => (await readS3Config()) !== null,
+  upload: async ({ data, filename, mimeType }) => {
+    const cfg = await readS3Config();
+    if (!cfg) throw new Error("S3 credentials are not configured");
+
+    const ext = filename?.split(".").pop() ?? "bin";
+    const stamp = Date.now();
+    const rand = Math.random().toString(36).slice(2, 10);
+    const objectKey = `replays/${stamp}-${rand}.${ext}`;
+    const contentType = mimeType || "application/octet-stream";
+
+    const bytes =
+      data instanceof Uint8Array
+        ? data
+        : new Uint8Array(data as unknown as ArrayBuffer);
+
+    const publicUrl = await putObject(cfg, objectKey, bytes, contentType);
+    return { url: publicUrl, provider: "s3" };
+  },
+};

package/corpus/templates/analytics/server/lib/session-replay.ts

@@ -8,7 +8,7 @@ import {
   readPrivateBlob,
   type PrivateBlobHandle,
 } from "@agent-native/core/private-blob";
-import { recordChange } from "@agent-native/core/server";
+import { recordChange, runWithRequestContext } from "@agent-native/core/server";
 import {
   accessFilter,
   resolveAccess,
@@ -988,6 +988,9 @@ function rowToSessionRecordingSummary(
 }
 
 function hasVisibleSessionRecordingIdentity(row: any): boolean {
+  // /sessions intentionally lists signed-in, email-backed recordings only (see
+  // analytics CLAUDE.md + the "rejects anonymous recordings" spec). Keep this in
+  // sync with replayVisibleIdentityCondition().
   return Boolean(replayEmail(row.userId) || replayEmail(row.userKey));
 }
 
@@ -1050,6 +1053,8 @@ function replayTextContains(column: unknown, query: string) {
 }
 
 function replayVisibleIdentityCondition() {
+  // Email-backed identity only — /sessions lists signed-in recordings (see
+  // analytics CLAUDE.md). Mirror of hasVisibleSessionRecordingIdentity().
   return or(
     replayTextContains(schema.sessionRecordings.userId, "@"),
     replayTextContains(schema.sessionRecordings.userKey, "@"),
@@ -1140,7 +1145,12 @@ export async function recordSessionReplayChunks(
         lastIngestedAt: ingestedAt,
         ownerEmail: key.ownerEmail,
         orgId: key.orgId,
-        visibility: "private",
+        // Session replay is an org-analytics surface: a recording captured under
+        // an org-scoped analytics key must be visible to everyone in that org
+        // (via accessFilter's "org" branch), not only the key owner. Without an
+        // org we fall back to owner-private. This is what makes /sessions show
+        // recordings to teammates instead of only the single key owner.
+        visibility: key.orgId ? "org" : "private",
       })
       .onConflictDoNothing();
 
@@ -1204,12 +1214,23 @@ export async function recordSessionReplayChunks(
           413,
         );
       }
-      const chunk = await storeReplayChunkBlob(rawChunk, {
-        publicKeyId: key.id,
-        recordingId: recording.id,
-        ownerEmail: key.ownerEmail,
-        orgId: key.orgId,
-      });
+      // Replay ingest is anonymous + cross-origin (no session), so blob storage
+      // would otherwise have no request context and `resolveBuilderPrivateKey()`
+      // (and any S3 provider's scoped-secret lookup) would resolve nothing —
+      // every chunk upload then 503s and recordings persist as empty shells.
+      // Run the upload in the public key owner's user/org scope so the org's
+      // connected Builder (or S3) credential in `app_secrets` resolves. Mirrors
+      // the resources upload precedent (core resources/handlers.ts).
+      const chunk = await runWithRequestContext(
+        { userEmail: key.ownerEmail, orgId: key.orgId ?? undefined },
+        () =>
+          storeReplayChunkBlob(rawChunk, {
+            publicKeyId: key.id,
+            recordingId: recording.id,
+            ownerEmail: key.ownerEmail,
+            orgId: key.orgId,
+          }),
+      );
       if (rawChunk.storageKind !== "blob" && chunk.storageKind === "blob") {
         const ref = decodeReplayBlobRef(chunk.storageRef);
         if (ref) uploadedBlobHandles.push(ref.handle);

package/corpus/templates/analytics/server/plugins/agent-chat.ts

@@ -9,6 +9,7 @@ import {
 import actionsRegistry from "../../.generated/actions-registry.js";
 import { renderDataDictionary } from "../lib/data-dictionary-context";
 import {
+  failedDataQueryAttemptMessage,
   hasExplicitPartialDisclosure,
   hasFailedCorpusWorkflowEvidence,
   hasDataQueryAttempt,
@@ -39,6 +40,7 @@ const INITIAL_TOOL_NAMES = [
   "get-sql-dashboard",
   "mutate-dashboard",
   "generate-chart",
+  "query-agent-native-analytics",
   "bigquery",
   "search-bigquery-schema",
   "bigquery-table-info",
@@ -139,6 +141,13 @@ function realDataFinalGuard(context: AgentLoopFinalResponseGuardContext) {
   }
   if (hasDataQueryAttempt(context.toolResults)) return null;
   if (isSafeNoDataAnalyticsResponse(context.text)) return null;
+  const failedQueryMessage = failedDataQueryAttemptMessage(context.toolResults);
+  if (failedQueryMessage) {
+    return {
+      retryMessage: failedQueryMessage,
+      fallbackMessage: failedQueryMessage,
+    };
+  }
 
   return {
     retryMessage:
@@ -175,8 +184,8 @@ export default createAgentChatPlugin({
       "SURFACE DIFFERENTIATION — You are the analytics assistant for definitions, deep-dive analysis, and action. For questions about what a metric, model, or table means, use the Data Dictionary and configured schema tools first. For trends, comparisons, anomalies, current data, or anything that requires querying live data, answer directly in chat with the relevant provider query, dashboard analysis, and inline charts when useful. " +
       "DASHBOARD CREATION RULE — You may create dashboards, analyses, SQL panels, or other resources only when the user explicitly asks you to (e.g. 'build me a dashboard for...', 'create a new analysis', 'add a chart for...'). Never create any resource proactively during research, trend analysis, or answering questions. If you think a dashboard would be useful, suggest it and wait for explicit confirmation before creating anything. Never add new items to the sidebar or modify existing dashboards without an explicit user directive. " +
       "DASHBOARD MUTATION RULE — For dashboard edits, default to `mutate-dashboard` with the typed `dashboard.*` script API so the main payload is a string and avoids native-array serialization traps. It can move panels by id, edit titles/SQL/config, insert, duplicate, remove, and patch dashboard fields in one atomic save. The script API is constrained: no variables/imports/loops/functions, only JSON-compatible arguments on documented dashboard methods. Do not count shifting `/panels/<index>` positions for ordinary dashboard edits unless the user specifically asks for low-level JSON-pointer operations. " +
-      "DASHBOARD READ RULE — `get-sql-dashboard` is compact by default: use its `panels` summaries plus `layout.panelOrder` and `layout.firstPanelIds` for orientation and verification. Pass `includeConfig: true` only when you truly need full panel SQL/config. " +
-      'DASHBOARD REORDER RULE — For simple chart/section moves, use `mutate-dashboard` code such as `dashboard.panels(["panel-a","panel-b"]).moveToTop();`. Never count shifting `/panels/<index>` positions for ordinary \'move this chart\' requests. Use `get-sql-dashboard.layout.firstPanelIds` or `mutate-dashboard.panelOrder` as proof of placement. ' +
+      "DASHBOARD READ RULE — `get-sql-dashboard` is compact by default: use its `panels` summaries plus `layout.panelOrder`, `layout.firstPanelIds`, and `layout.groups[].rows[].rowNumber/panelIds` for orientation and verification. Pass `includeConfig: true` only when you truly need full panel SQL/config. " +
+      'DASHBOARD REORDER RULE — For simple chart/section moves, use `mutate-dashboard` code such as `dashboard.panels(["panel-a","panel-b"]).moveToTop();`. For visible placement requests like "second row" or "next to return rates", use row-aware placement such as `dashboard.insertPanel({...}).nextTo("retention-over-time")`, `.atRow(2)`, or `dashboard.panel("panel-a").moveNextTo("panel-b")`; these keep panels in the intended rendered row and expand/rebalance that row when needed. Never count shifting `/panels/<index>` positions for ordinary \'move this chart\' requests. Use `get-sql-dashboard.layout.groups[].rows` as proof of visible row placement, not only flat `panelOrder`. ' +
       "Use configured data sources and actions only. Call `data-source-status` when you need to know which providers are connected, and treat provider actions as unavailable for analysis if they return missing credentials, permission, syntax, quota, or network errors. " +
       "The built-in `demo` dashboard source is a demo-environment Prometheus source reserved for the Node Exporter demo. It must never satisfy REAL_DATA_REQUIRED or be cited as user analytics evidence unless the user explicitly asks to inspect the demo dashboard. " +
       "When the user names a provider or tool such as Jira, Pylon, HubSpot, Gong, Slack, Sentry, GA4, or BigQuery, that named source is authoritative for the turn: use that provider's real tool/API surface, not a warehouse or different-provider substitute, unless the user explicitly asks for the copy/fallback. For bounded lookups where a first-class action fully models the requested source, object, filter, and pagination need, that shortcut is fine. For broad provider searches, cross-source joins, corpus-wide counts, exact cohort coverage, or any answer where absence matters, do not start and stop with shortcuts; use the broad provider API/MCP and corpus/code workflow as the primary path. " +