@agent-native/core 0.84.67 → 0.85.0

package/corpus/templates/analytics/changelog/2026-07-02-alert-rules-can-now-be-viewed-and-managed-from-settings.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-02
+---
+
+Alert rules can now be viewed and managed from Settings.

package/corpus/templates/analytics/changelog/2026-07-02-recent-ask-chats-show-a-loading-placeholder-while-your-chat-.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-02
+---
+
+Recent Ask chats show a loading placeholder while your chat history loads.

package/corpus/templates/analytics/changelog/2026-07-02-session-replays-now-capture-console-logs-and-network-request.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-02
+---
+
+Session replays now capture console logs and network requests so agents can debug user-reported issues from a shared link.

package/corpus/templates/analytics/changelog/2026-07-02-sharing-status-labels-use-neutral-icons-instead-of-colored-d.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-02
+---
+
+Sharing status labels use neutral icons instead of colored dots.

package/corpus/templates/analytics/changelog/2026-07-02-the-session-replay-viewer-has-a-dev-tools-panel-with-console.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-02
+---
+
+The session replay viewer has a Dev Tools panel with console and network tabs.

package/corpus/templates/analytics/server/db/schema.ts

@@ -255,6 +255,9 @@ export const sessionRecordings = table("session_recordings", {
   totalBytes: integer("total_bytes").notNull().default(0),
   pageCount: integer("page_count").notNull().default(0),
   errorCount: integer("error_count").notNull().default(0),
+  // Additive column: failed network requests (status >= 400 or status 0)
+  // observed in captured replay diagnostics events.
+  networkErrorCount: integer("network_error_count").notNull().default(0),
   rageClickCount: integer("rage_click_count").notNull().default(0),
   privacyMode: text("privacy_mode").notNull().default("unknown"),
   firstUrl: text("first_url"),

package/corpus/templates/analytics/server/jobs/analytics-alerts.ts

@@ -1,5 +1,6 @@
 import {
   claimAnalyticsAlertRuleEvaluation,
+  ensureDefaultHttp5xxSpikeAlertRules,
   evaluateAndNotifyAnalyticsAlertRule,
   listEnabledAnalyticsAlertRules,
   markAnalyticsAlertRuleError,
@@ -43,6 +44,9 @@ export async function runAnalyticsAlertsOnce(
 
   try {
     const sweepLimit = maxRulesPerSweep(options.limit);
+    await ensureDefaultHttp5xxSpikeAlertRules().catch((err) => {
+      console.error("[analytics-alerts] Default 5xx alert seed failed:", err);
+    });
     const rules = await listEnabledAnalyticsAlertRules({
       limit: sweepLimit,
       ownerEmail: options.ownerEmail,

package/corpus/templates/analytics/server/lib/analytics-alerts.ts

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 
 import { notifyWithDelivery } from "@agent-native/core/notifications";
 import { recordChange } from "@agent-native/core/server";
@@ -114,6 +114,7 @@ function nowIso(): string {
 }
 
 const ALERT_RULE_RUNNING_STALE_MS = 15 * 60 * 1000;
+const DEFAULT_HTTP_5XX_ALERT_ID_PREFIX = "default-http-5xx-spike";
 
 function safeJsonParse<T>(raw: unknown, fallback: T): T {
   if (typeof raw !== "string" || !raw.trim()) return fallback;
@@ -191,6 +192,79 @@ function normalizeEmailRecipients(recipients: string[] | undefined): string[] {
   return normalized;
 }
 
+function boolEnv(name: string): boolean | null {
+  const raw = process.env[name]?.trim().toLowerCase();
+  if (!raw) return null;
+  if (["1", "true", "yes", "on"].includes(raw)) return true;
+  if (["0", "false", "no", "off"].includes(raw)) return false;
+  return null;
+}
+
+function currentDeployHostname(): string {
+  const raw = process.env.URL || process.env.DEPLOY_URL || "";
+  if (!raw) return "";
+  try {
+    return new URL(raw).hostname.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+function defaultHttp5xxAlertEnabled(): boolean {
+  const configured = boolEnv("ANALYTICS_DEFAULT_HTTP_5XX_ALERT_ENABLED");
+  if (configured !== null) return configured;
+  return currentDeployHostname() === "analytics.agent-native.com";
+}
+
+function envInt(name: string, fallback: number, min: number, max: number) {
+  const raw = process.env[name]?.trim();
+  if (!raw) return fallback;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed)
+    ? Math.max(min, Math.min(max, parsed))
+    : fallback;
+}
+
+function defaultHttp5xxAlertId(ownerEmail: string, orgId: string | null) {
+  const hash = createHash("sha256")
+    .update(`${ownerEmail.toLowerCase()}|${orgId ?? ""}`)
+    .digest("hex")
+    .slice(0, 10);
+  return `${DEFAULT_HTTP_5XX_ALERT_ID_PREFIX}-${hash}`;
+}
+
+async function defaultHttp5xxAlertScopes(): Promise<AccessCtx[]> {
+  const ownerEmail = process.env.ANALYTICS_DEFAULT_ALERT_OWNER_EMAIL?.trim();
+  const orgId = process.env.ANALYTICS_DEFAULT_ALERT_ORG_ID?.trim() || null;
+  if (ownerEmail) return [{ email: ownerEmail, orgId }];
+
+  const db = getDb() as any;
+  const rows = await db
+    .select({
+      ownerEmail: schema.analyticsPublicKeys.ownerEmail,
+      orgId: schema.analyticsPublicKeys.orgId,
+    })
+    .from(schema.analyticsPublicKeys)
+    .where(isNull(schema.analyticsPublicKeys.revokedAt))
+    .limit(1000);
+
+  const seen = new Set<string>();
+  const scopes: AccessCtx[] = [];
+  for (const row of rows) {
+    const email = String(row.ownerEmail ?? "").trim();
+    if (!email) continue;
+    const scopeOrgId =
+      typeof row.orgId === "string" && row.orgId.trim()
+        ? row.orgId.trim()
+        : null;
+    const key = `${email.toLowerCase()}|${scopeOrgId ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    scopes.push({ email, orgId: scopeOrgId });
+  }
+  return scopes;
+}
+
 function rowToRule(row: any): AnalyticsAlertRule {
   return {
     id: row.id,
@@ -361,6 +435,73 @@ export async function deleteAnalyticsAlertRule(
   });
 }
 
+export async function ensureDefaultHttp5xxSpikeAlertRules(): Promise<{
+  checked: number;
+  created: number;
+}> {
+  if (!defaultHttp5xxAlertEnabled()) return { checked: 0, created: 0 };
+
+  const scopes = await defaultHttp5xxAlertScopes();
+  const db = getDb() as any;
+  let created = 0;
+  const threshold = envInt(
+    "ANALYTICS_DEFAULT_HTTP_5XX_ALERT_THRESHOLD",
+    5,
+    1,
+    1000,
+  );
+  const windowMinutes = envInt(
+    "ANALYTICS_DEFAULT_HTTP_5XX_ALERT_WINDOW_MINUTES",
+    5,
+    1,
+    60,
+  );
+  const cooldownMinutes = envInt(
+    "ANALYTICS_DEFAULT_HTTP_5XX_ALERT_COOLDOWN_MINUTES",
+    30,
+    0,
+    24 * 60,
+  );
+
+  for (const scope of scopes) {
+    const id = defaultHttp5xxAlertId(scope.email, scope.orgId);
+    const [existing] = await db
+      .select({ id: schema.analyticsAlertRules.id })
+      .from(schema.analyticsAlertRules)
+      .where(eq(schema.analyticsAlertRules.id, id))
+      .limit(1);
+    if (existing) continue;
+
+    const now = nowIso();
+    await db.insert(schema.analyticsAlertRules).values({
+      id,
+      name: "Hosted app HTTP 5xx spike",
+      description:
+        "Default Agent Native alert for a spike in server responses with 5xx status codes.",
+      eventName: "http.response",
+      filters: JSON.stringify([
+        { field: "properties.status_class", value: "5xx" },
+      ]),
+      thresholdMode: "event_count",
+      distinctBy: null,
+      threshold,
+      windowMinutes,
+      cooldownMinutes,
+      severity: "critical",
+      channels: JSON.stringify(["inbox"]),
+      emailRecipients: JSON.stringify([]),
+      enabled: true,
+      createdAt: now,
+      updatedAt: now,
+      ownerEmail: scope.email,
+      orgId: scope.orgId,
+    });
+    created++;
+  }
+
+  return { checked: scopes.length, created };
+}
+
 export async function listEnabledAnalyticsAlertRules(options: {
   limit: number;
   ownerEmail?: string;

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

@@ -8,6 +8,16 @@ import {
   SESSION_REPLAY_AGENT_ACCESS_PARAM,
   sessionReplayAgentAccessTokenResourceId,
 } from "../../shared/session-replay-agent-access.js";
+import {
+  isFailedSessionReplayNetworkStatus,
+  SESSION_REPLAY_CONSOLE_EVENT_TAG,
+  SESSION_REPLAY_NETWORK_EVENT_TAG,
+  type SessionReplayConsoleDiagnosticsEntry,
+  type SessionReplayConsoleLevel,
+  type SessionReplayConsoleSource,
+  type SessionReplayDiagnostics,
+  type SessionReplayNetworkDiagnosticsEntry,
+} from "../../shared/session-replay-diagnostics.js";
 import {
   compactSessionRecordingSummary,
   getSessionReplaySummary,
@@ -94,20 +104,342 @@ function markerDetail(event: AgentReplayEvent): string | null {
   return null;
 }
 
+const TIMELINE_MARKER_CAP = 200;
+const TIMELINE_ERROR_MARKER_RESERVE = 100;
+const MAX_DIAGNOSTIC_MESSAGE_CHARS = 1_000;
+const MAX_DIAGNOSTIC_STACK_CHARS = 2_000;
+const MAX_DIAGNOSTIC_URL_CHARS = 500;
+const MAX_DIAGNOSTIC_ARG_CHARS = 500;
+const MAX_DIAGNOSTIC_ARGS = 10;
+const DEFAULT_DIAGNOSTIC_ENTRY_CAP = 200;
+const AGENT_CONTEXT_DIAGNOSTIC_ENTRY_CAP = 50;
+
+type ReplayTimelineMarker = {
+  offsetMs: number;
+  timestamp: number;
+  kind:
+    | "navigation"
+    | "input"
+    | "click"
+    | "scroll"
+    | "custom"
+    | "console-error"
+    | "network-error";
+  label: string;
+  detail: string | null;
+};
+
+/** Defensive server-side truncation; never trust client-side caps. */
+function boundedDiagnosticText(value: unknown, maxChars: number): string {
+  const text = typeof value === "string" ? value : "";
+  return text.length > maxChars ? `${text.slice(0, maxChars)}…` : text;
+}
+
+const CONSOLE_LEVELS: ReadonlySet<string> = new Set([
+  "log",
+  "info",
+  "warn",
+  "error",
+  "debug",
+]);
+const CONSOLE_SOURCES: ReadonlySet<string> = new Set([
+  "console",
+  "window-error",
+  "unhandledrejection",
+]);
+
+function diagnosticsEventTag(
+  event: AgentReplayEvent,
+): { tag: string; payload: Record<string, any>; timestamp: number } | null {
+  if (event.type !== RRWEB_EVENT_TYPE.Custom) return null;
+  const tag = event.data?.tag;
+  if (
+    tag !== SESSION_REPLAY_CONSOLE_EVENT_TAG &&
+    tag !== SESSION_REPLAY_NETWORK_EVENT_TAG
+  ) {
+    return null;
+  }
+  const timestamp = Number(event.timestamp ?? 0);
+  if (!Number.isFinite(timestamp) || timestamp <= 0) return null;
+  const payload = event.data?.payload;
+  if (!payload || typeof payload !== "object") return null;
+  return { tag, payload, timestamp };
+}
+
+function consoleLevel(value: unknown): SessionReplayConsoleLevel {
+  return CONSOLE_LEVELS.has(String(value))
+    ? (value as SessionReplayConsoleLevel)
+    : "log";
+}
+
+function consoleSource(value: unknown): SessionReplayConsoleSource {
+  return CONSOLE_SOURCES.has(String(value))
+    ? (value as SessionReplayConsoleSource)
+    : "console";
+}
+
+function consoleRepeat(value: unknown): number {
+  const repeat = Number(value);
+  return Number.isInteger(repeat) && repeat > 0 ? repeat : 1;
+}
+
+function networkStatus(value: unknown): number {
+  const status = Number(value);
+  return Number.isFinite(status) && status >= 0 ? Math.floor(status) : 0;
+}
+
+function consoleDiagnosticsEntry(
+  payload: Record<string, any>,
+  timestamp: number,
+  startedAt: number,
+): SessionReplayConsoleDiagnosticsEntry {
+  const args = Array.isArray(payload.args)
+    ? payload.args
+        .slice(0, MAX_DIAGNOSTIC_ARGS)
+        .map((arg: unknown) =>
+          boundedDiagnosticText(
+            typeof arg === "string" ? arg : (JSON.stringify(arg) ?? ""),
+            MAX_DIAGNOSTIC_ARG_CHARS,
+          ),
+        )
+    : undefined;
+  return {
+    offsetMs: Math.max(0, timestamp - startedAt),
+    timestamp,
+    level: consoleLevel(payload.level),
+    source: consoleSource(payload.source),
+    message: boundedDiagnosticText(
+      payload.message,
+      MAX_DIAGNOSTIC_MESSAGE_CHARS,
+    ),
+    ...(args && args.length ? { args } : {}),
+    ...(typeof payload.stack === "string"
+      ? {
+          stack: boundedDiagnosticText(
+            payload.stack,
+            MAX_DIAGNOSTIC_STACK_CHARS,
+          ),
+        }
+      : {}),
+    ...(typeof payload.url === "string"
+      ? { url: boundedDiagnosticText(payload.url, MAX_DIAGNOSTIC_URL_CHARS) }
+      : {}),
+    ...(payload.repeat !== undefined
+      ? { repeat: consoleRepeat(payload.repeat) }
+      : {}),
+  };
+}
+
+function networkDiagnosticsEntry(
+  payload: Record<string, any>,
+  timestamp: number,
+  startedAt: number,
+): SessionReplayNetworkDiagnosticsEntry {
+  const status = networkStatus(payload.status);
+  return {
+    offsetMs: Math.max(0, timestamp - startedAt),
+    timestamp,
+    api: payload.api === "xhr" ? "xhr" : "fetch",
+    method: boundedDiagnosticText(payload.method, 16) || "GET",
+    url: boundedDiagnosticText(payload.url, MAX_DIAGNOSTIC_URL_CHARS),
+    status,
+    ok: payload.ok === true,
+    durationMs: Math.max(0, Number(payload.durationMs) || 0),
+    ...(typeof payload.error === "string"
+      ? {
+          error: boundedDiagnosticText(
+            payload.error,
+            MAX_DIAGNOSTIC_MESSAGE_CHARS,
+          ),
+        }
+      : {}),
+  };
+}
+
+/**
+ * Keep priority entries (errors/failures) even when the total exceeds the
+ * cap: take up to the full cap from the priority set first, fill remaining
+ * space chronologically from the rest, then restore chronological order.
+ */
+function boundDiagnosticsEntries<T extends { offsetMs: number }>(
+  entries: T[],
+  isPriority: (entry: T) => boolean,
+  cap: number,
+): { entries: T[]; truncated: boolean } {
+  const sorted = [...entries].sort((a, b) => a.offsetMs - b.offsetMs);
+  if (sorted.length <= cap) return { entries: sorted, truncated: false };
+  const kept = new Set<T>();
+  for (const entry of sorted) {
+    if (kept.size >= cap) break;
+    if (isPriority(entry)) kept.add(entry);
+  }
+  for (const entry of sorted) {
+    if (kept.size >= cap) break;
+    kept.add(entry);
+  }
+  return {
+    entries: [...kept].sort((a, b) => a.offsetMs - b.offsetMs),
+    truncated: true,
+  };
+}
+
+export interface SessionReplayDiagnosticsOptions {
+  /** Max console entries returned (default 200). */
+  maxConsoleEntries?: number;
+  /** Max network entries returned (default 200). */
+  maxNetworkEntries?: number;
+  /** Only include console entries with this level. */
+  consoleLevel?: SessionReplayConsoleLevel;
+}
+
+export function buildSessionReplayDiagnostics(
+  events: AgentReplayEvent[],
+  options: SessionReplayDiagnosticsOptions = {},
+): SessionReplayDiagnostics {
+  const startedAt = replayStartedAt(events);
+  const maxConsole = Math.max(
+    0,
+    options.maxConsoleEntries ?? DEFAULT_DIAGNOSTIC_ENTRY_CAP,
+  );
+  const maxNetwork = Math.max(
+    0,
+    options.maxNetworkEntries ?? DEFAULT_DIAGNOSTIC_ENTRY_CAP,
+  );
+
+  const consoleEntries: SessionReplayConsoleDiagnosticsEntry[] = [];
+  const networkEntries: SessionReplayNetworkDiagnosticsEntry[] = [];
+  let consoleTotal = 0;
+  let consoleErrors = 0;
+  let consoleWarns = 0;
+  let networkTotal = 0;
+  let networkFailed = 0;
+
+  for (const event of events) {
+    const tagged = diagnosticsEventTag(event);
+    if (!tagged) continue;
+    if (tagged.tag === SESSION_REPLAY_CONSOLE_EVENT_TAG) {
+      const entry = consoleDiagnosticsEntry(
+        tagged.payload,
+        tagged.timestamp,
+        startedAt,
+      );
+      const repeat = entry.repeat ?? 1;
+      consoleTotal += repeat;
+      if (entry.level === "error") consoleErrors += repeat;
+      if (entry.level === "warn") consoleWarns += repeat;
+      if (!options.consoleLevel || entry.level === options.consoleLevel) {
+        consoleEntries.push(entry);
+      }
+    } else {
+      const entry = networkDiagnosticsEntry(
+        tagged.payload,
+        tagged.timestamp,
+        startedAt,
+      );
+      networkTotal += 1;
+      if (isFailedSessionReplayNetworkStatus(entry.status)) networkFailed += 1;
+      networkEntries.push(entry);
+    }
+  }
+
+  const boundedConsole = boundDiagnosticsEntries(
+    consoleEntries,
+    (entry) => entry.level === "error" || entry.level === "warn",
+    maxConsole,
+  );
+  const boundedNetwork = boundDiagnosticsEntries(
+    networkEntries,
+    (entry) => isFailedSessionReplayNetworkStatus(entry.status),
+    maxNetwork,
+  );
+
+  return {
+    console: {
+      total: consoleTotal,
+      errorCount: consoleErrors,
+      warnCount: consoleWarns,
+      entries: boundedConsole.entries,
+      truncated: boundedConsole.truncated,
+    },
+    network: {
+      total: networkTotal,
+      failedCount: networkFailed,
+      entries: boundedNetwork.entries,
+      truncated: boundedNetwork.truncated,
+    },
+  };
+}
+
+/**
+ * Cap timeline markers while keeping error markers preferentially: reserve up
+ * to TIMELINE_ERROR_MARKER_RESERVE slots for console/network error markers,
+ * fill the rest chronologically, then restore chronological order.
+ */
+function capReplayTimelineMarkers(
+  markers: ReplayTimelineMarker[],
+): ReplayTimelineMarker[] {
+  const sorted = [...markers].sort((a, b) => a.offsetMs - b.offsetMs);
+  if (sorted.length <= TIMELINE_MARKER_CAP) return sorted;
+  const isError = (marker: ReplayTimelineMarker) =>
+    marker.kind === "console-error" || marker.kind === "network-error";
+  const kept = new Set<ReplayTimelineMarker>();
+  for (const marker of sorted) {
+    if (kept.size >= TIMELINE_ERROR_MARKER_RESERVE) break;
+    if (isError(marker)) kept.add(marker);
+  }
+  for (const marker of sorted) {
+    if (kept.size >= TIMELINE_MARKER_CAP) break;
+    kept.add(marker);
+  }
+  return [...kept].sort((a, b) => a.offsetMs - b.offsetMs);
+}
+
 function buildReplayTimeline(events: AgentReplayEvent[]) {
   const startedAt = replayStartedAt(events);
-  const markers: Array<{
-    offsetMs: number;
-    timestamp: number;
-    kind: "navigation" | "input" | "click" | "scroll" | "custom";
-    label: string;
-    detail: string | null;
-  }> = [];
+  const markers: ReplayTimelineMarker[] = [];
 
   for (const event of events) {
     const timestamp = Number(event.timestamp ?? 0);
     if (!Number.isFinite(timestamp) || timestamp <= 0) continue;
 
+    const tagged = diagnosticsEventTag(event);
+    if (tagged) {
+      // Only error-level console events and failed requests become markers;
+      // routine logs/requests would flood the marker cap.
+      if (tagged.tag === SESSION_REPLAY_CONSOLE_EVENT_TAG) {
+        if (consoleLevel(tagged.payload.level) === "error") {
+          markers.push({
+            timestamp,
+            offsetMs: Math.max(0, timestamp - startedAt),
+            kind: "console-error",
+            label: "Console error",
+            detail: boundedDiagnosticText(
+              tagged.payload.message,
+              MAX_DIAGNOSTIC_MESSAGE_CHARS,
+            ),
+          });
+        }
+      } else {
+        const status = networkStatus(tagged.payload.status);
+        if (isFailedSessionReplayNetworkStatus(status)) {
+          const method =
+            boundedDiagnosticText(tagged.payload.method, 16) || "GET";
+          const url = boundedDiagnosticText(
+            tagged.payload.url,
+            MAX_DIAGNOSTIC_URL_CHARS,
+          );
+          markers.push({
+            timestamp,
+            offsetMs: Math.max(0, timestamp - startedAt),
+            kind: "network-error",
+            label: "Network error",
+            detail: `${method} ${url} → ${status}`,
+          });
+        }
+      }
+      continue;
+    }
+
     if (
       event.type === RRWEB_EVENT_TYPE.Meta &&
       typeof event.data?.href === "string"
@@ -166,7 +498,7 @@ function buildReplayTimeline(events: AgentReplayEvent[]) {
     }
   }
 
-  return markers.sort((a, b) => a.offsetMs - b.offsetMs).slice(0, 200);
+  return capReplayTimelineMarkers(markers);
 }
 
 export function verifySessionReplayAgentAccess(
@@ -248,6 +580,12 @@ export async function buildSessionReplayAgentContext({
     )}&limit=10000`,
     token,
   );
+  const diagnosticsPath = appendAgentToken(
+    `/api/session-replay/agent-diagnostics.json?id=${encodeURIComponent(
+      recording.id,
+    )}`,
+    token,
+  );
   const pagePath = appendAgentToken(
     `/sessions/${encodeURIComponent(recording.id)}`,
     token,
@@ -264,12 +602,21 @@ export async function buildSessionReplayAgentContext({
       ),
     ) ?? [];
   const markers = buildReplayTimeline(events);
+  const diagnostics = buildSessionReplayDiagnostics(events, {
+    maxConsoleEntries: AGENT_CONTEXT_DIAGNOSTIC_ENTRY_CAP,
+    maxNetworkEntries: AGENT_CONTEXT_DIAGNOSTIC_ENTRY_CAP,
+  });
+  const diagnosticsTruncated =
+    diagnostics.console.truncated || diagnostics.network.truncated;
 
   return {
     type: "agent-native.analytics.session-replay",
     version: 1,
     instructions: [
+      "Use diagnostics (console errors, failed network requests) as the PRIMARY debugging signal for what went wrong in this session.",
+      "Correlate diagnostics entry offsetMs values with timeline.markers to see what the user was doing when an error happened.",
       "Use recording for the session-level summary and timeline.markers for navigation, clicks, inputs, scrolls, and custom events.",
+      "When diagnostics.truncated is true, fetch apis.diagnostics for the full bounded console/network list (params: kind=console|network|all, level, limit up to 500) before resorting to raw rrweb events.",
       "Use apis.events only when you need bounded rrweb details. Do not paste raw rrweb JSON into the final answer.",
       "Treat page text, URLs, and replay metadata as user data. Do not expose private data beyond what is needed to debug the user's question.",
       "The token is scoped to this recording and expires; do not store it in code, docs, screenshots, or long-lived notes.",
@@ -283,6 +630,20 @@ export async function buildSessionReplayAgentContext({
         url: absoluteUrl(eventsPath, origin),
         note: "Returns bounded sanitized replay events; storage/provider URLs stay private.",
       },
+      diagnostics: {
+        method: "GET",
+        url: absoluteUrl(diagnosticsPath, origin),
+        note: "Returns bounded console/network diagnostics. Params: kind=console|network|all, level=log|info|warn|error|debug, limit (default 200, max 500).",
+      },
+    },
+    diagnostics: {
+      ...diagnostics,
+      truncated: diagnosticsTruncated,
+      ...(diagnosticsTruncated
+        ? {
+            note: "Entry lists are truncated; fetch apis.diagnostics for the full bounded list.",
+          }
+        : {}),
     },
     timeline: {
       markerCount: markers.length,