@agent-native/core 0.84.56 → 0.84.58

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

@@ -11,14 +11,20 @@ import {
 } from "h3";
 
 import { runApiHandlerWithContext } from "../lib/credentials";
+import {
+  SESSION_REPLAY_AGENT_ACCESS_PARAM,
+  verifySessionReplayAgentAccess,
+} from "../lib/session-replay-agent-context.js";
 import {
   getSessionReplayManifest,
   getSessionReplayEvents,
   getSessionReplaySummary,
+  getSessionReplayTokenizedManifest,
   listSessionRecordings,
   parseSessionReplayIngestPayload,
   recordSessionReplayChunks,
   readSessionReplayChunkBytes,
+  readSessionReplayTokenizedChunkBytes,
   type SessionReplayListFilters,
 } from "../lib/session-replay.js";
 
@@ -200,6 +206,32 @@ function asStatus(value: unknown): "active" | "completed" | undefined {
   return raw === "active" || raw === "completed" ? raw : undefined;
 }
 
+function appendQueryParam(path: string, name: string, value: string): string {
+  const sep = path.includes("?") ? "&" : "?";
+  return `${path}${sep}${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
+}
+
+function applyAgentReplayReadHeaders(event: any): void {
+  setResponseHeader(event, "Cache-Control", "private, max-age=0, no-store");
+  setResponseHeader(event, "Referrer-Policy", "no-referrer");
+  setResponseHeader(event, "X-Content-Type-Options", "nosniff");
+}
+
+function readAgentReplayAccessToken(event: any): string | undefined {
+  return asString(getQuery(event)[SESSION_REPLAY_AGENT_ACCESS_PARAM]);
+}
+
+function verifyAgentReplayAccessToken(
+  event: any,
+  recordingId: string,
+): string | null {
+  const token = readAgentReplayAccessToken(event);
+  if (!token) return null;
+  if (verifySessionReplayAgentAccess(recordingId, token)) return token;
+  setResponseStatus(event, 401);
+  return "";
+}
+
 function listFiltersFromQuery(
   query: Record<string, unknown>,
 ): SessionReplayListFilters {
@@ -326,6 +358,31 @@ export const handleSessionReplayManifest = defineEventHandler(async (event) => {
     return { error: "Missing recordingId" };
   }
 
+  const agentAccessToken = verifyAgentReplayAccessToken(event, recordingId);
+  if (agentAccessToken === "") {
+    return { error: "Invalid or expired agent access" };
+  }
+  if (agentAccessToken) {
+    try {
+      applyAgentReplayReadHeaders(event);
+      const manifest = await getSessionReplayTokenizedManifest(recordingId);
+      return {
+        ...manifest,
+        chunks: manifest.chunks.map((chunk) => ({
+          ...chunk,
+          bytesPath: appendQueryParam(
+            chunk.bytesPath,
+            SESSION_REPLAY_AGENT_ACCESS_PARAM,
+            agentAccessToken,
+          ),
+        })),
+      };
+    } catch (error: any) {
+      setResponseStatus(event, statusFromError(error));
+      return { error: messageFromError(error) };
+    }
+  }
+
   return runApiHandlerWithContext(event, async (ctx) => {
     try {
       return await getSessionReplayManifest(recordingId, {
@@ -349,6 +406,27 @@ export const handleSessionReplayChunkBytes = defineEventHandler(
       return { error: "Missing recordingId or seq" };
     }
 
+    const agentAccessToken = verifyAgentReplayAccessToken(event, recordingId);
+    if (agentAccessToken === "") {
+      return { error: "Invalid or expired agent access" };
+    }
+    if (agentAccessToken) {
+      try {
+        const result = await readSessionReplayTokenizedChunkBytes(
+          recordingId,
+          seq,
+        );
+        applyAgentReplayReadHeaders(event);
+        setResponseHeader(event, "Content-Type", "application/json");
+        setResponseHeader(event, "X-Session-Replay-Seq", String(result.seq));
+        setResponseHeader(event, "X-Session-Replay-Checksum", result.checksum);
+        return result.json;
+      } catch (error: any) {
+        setResponseStatus(event, statusFromError(error));
+        return { error: messageFromError(error) };
+      }
+    }
+
     return runApiHandlerWithContext(event, async (ctx) => {
       try {
         const result = await readSessionReplayChunkBytes(recordingId, seq, {

package/corpus/templates/analytics/server/lib/agent-chat-plan-mode.ts

@@ -0,0 +1,29 @@
+import type { ActionEntry } from "@agent-native/core/server";
+
+export const PLAN_MODE_ACT_ONLY_TOOLS = new Set([
+  "query-agent-native-analytics",
+  "bigquery",
+  "provider-api-request",
+  "provider-corpus-job",
+  "query-staged-dataset",
+  "account-deep-dive",
+  "hubspot-deals",
+  "hubspot-records",
+  "gong-calls",
+  "jira-search",
+  "slack-messages",
+  "sentry",
+]);
+
+export function applyAnalyticsPlanModePolicy(
+  actions: Record<string, ActionEntry>,
+): Record<string, ActionEntry> {
+  return Object.fromEntries(
+    Object.entries(actions).map(([name, entry]) => [
+      name,
+      PLAN_MODE_ACT_ONLY_TOOLS.has(name)
+        ? { ...entry, allowInPlanMode: false }
+        : entry,
+    ]),
+  );
+}

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

@@ -0,0 +1,313 @@
+import {
+  getRequestContext,
+  signShortLivedToken,
+  verifyShortLivedToken,
+} from "@agent-native/core/server";
+
+import {
+  SESSION_REPLAY_AGENT_ACCESS_PARAM,
+  sessionReplayAgentAccessTokenResourceId,
+} from "../../shared/session-replay-agent-access.js";
+import {
+  compactSessionRecordingSummary,
+  getSessionReplaySummary,
+  getSessionReplayTokenizedEvents,
+  getSessionReplayTokenizedSummary,
+  type ReplayScope,
+} from "./session-replay.js";
+
+export { SESSION_REPLAY_AGENT_ACCESS_PARAM };
+export const SESSION_REPLAY_AGENT_ACCESS_TTL_SECONDS = 2 * 60 * 60;
+
+type AgentReplayEvent = Record<string, any>;
+
+const RRWEB_EVENT_TYPE = {
+  IncrementalSnapshot: 3,
+  Meta: 4,
+  Custom: 5,
+} as const;
+
+const INCREMENTAL_SOURCE = {
+  MouseInteraction: 2,
+  Scroll: 3,
+  Input: 5,
+} as const;
+
+const MOUSE_INTERACTION = {
+  Click: 2,
+  DblClick: 4,
+  Focus: 5,
+} as const;
+
+function appBasePath(): string {
+  const raw = process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH || "";
+  const base = raw.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+  return base ? `/${base}` : "";
+}
+
+function appOrigin(explicitOrigin?: string): string {
+  const fromContext = getRequestContext()?.requestOrigin;
+  const origin =
+    explicitOrigin ||
+    fromContext ||
+    process.env.APP_URL ||
+    process.env.BETTER_AUTH_URL ||
+    "http://localhost:3000";
+  try {
+    return new URL(origin).origin;
+  } catch {
+    return "http://localhost:3000";
+  }
+}
+
+function absoluteUrl(path: string, origin?: string): string {
+  return `${appOrigin(origin)}${appBasePath()}${path}`;
+}
+
+function appendAgentToken(path: string, token: string): string {
+  const sep = path.includes("?") ? "&" : "?";
+  return `${path}${sep}${SESSION_REPLAY_AGENT_ACCESS_PARAM}=${encodeURIComponent(
+    token,
+  )}`;
+}
+
+function replayStartedAt(events: AgentReplayEvent[]): number {
+  const first = events.find((event) =>
+    Number.isFinite(Number(event.timestamp)),
+  );
+  return Number(first?.timestamp ?? 0) || 0;
+}
+
+function pathLabel(href: string): string {
+  try {
+    const parsed = new URL(href);
+    return parsed.pathname || parsed.hostname;
+  } catch {
+    return href;
+  }
+}
+
+function markerDetail(event: AgentReplayEvent): string | null {
+  const payload = event.data?.payload;
+  if (typeof payload?.message === "string") return payload.message;
+  if (typeof event.data?.href === "string") return event.data.href;
+  return null;
+}
+
+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;
+  }> = [];
+
+  for (const event of events) {
+    const timestamp = Number(event.timestamp ?? 0);
+    if (!Number.isFinite(timestamp) || timestamp <= 0) continue;
+
+    if (
+      event.type === RRWEB_EVENT_TYPE.Meta &&
+      typeof event.data?.href === "string"
+    ) {
+      markers.push({
+        timestamp,
+        offsetMs: Math.max(0, timestamp - startedAt),
+        kind: "navigation",
+        label: pathLabel(event.data.href),
+        detail: event.data.href,
+      });
+    } else if (
+      event.type === RRWEB_EVENT_TYPE.IncrementalSnapshot &&
+      event.data?.source === INCREMENTAL_SOURCE.Input
+    ) {
+      markers.push({
+        timestamp,
+        offsetMs: Math.max(0, timestamp - startedAt),
+        kind: "input",
+        label: "Input",
+        detail: null,
+      });
+    } else if (
+      event.type === RRWEB_EVENT_TYPE.IncrementalSnapshot &&
+      event.data?.source === INCREMENTAL_SOURCE.Scroll
+    ) {
+      markers.push({
+        timestamp,
+        offsetMs: Math.max(0, timestamp - startedAt),
+        kind: "scroll",
+        label: "Scroll",
+        detail: null,
+      });
+    } else if (
+      event.type === RRWEB_EVENT_TYPE.IncrementalSnapshot &&
+      event.data?.source === INCREMENTAL_SOURCE.MouseInteraction &&
+      (event.data?.type === MOUSE_INTERACTION.Click ||
+        event.data?.type === MOUSE_INTERACTION.DblClick ||
+        event.data?.type === MOUSE_INTERACTION.Focus)
+    ) {
+      markers.push({
+        timestamp,
+        offsetMs: Math.max(0, timestamp - startedAt),
+        kind: "click",
+        label: event.data.type === MOUSE_INTERACTION.Focus ? "Focus" : "Click",
+        detail: null,
+      });
+    } else if (event.type === RRWEB_EVENT_TYPE.Custom) {
+      markers.push({
+        timestamp,
+        offsetMs: Math.max(0, timestamp - startedAt),
+        kind: "custom",
+        label: String(event.data?.tag ?? "Custom event"),
+        detail: markerDetail(event),
+      });
+    }
+  }
+
+  return markers.sort((a, b) => a.offsetMs - b.offsetMs).slice(0, 200);
+}
+
+export function verifySessionReplayAgentAccess(
+  recordingId: string,
+  token: string,
+): boolean {
+  return verifyShortLivedToken(
+    token,
+    sessionReplayAgentAccessTokenResourceId(recordingId),
+  ).ok;
+}
+
+export async function createSessionReplayAgentLink({
+  recordingId,
+  scope,
+  origin,
+}: {
+  recordingId: string;
+  scope: ReplayScope;
+  origin?: string;
+}) {
+  const recording = await getSessionReplaySummary(recordingId, scope);
+  const token = signShortLivedToken({
+    resourceId: sessionReplayAgentAccessTokenResourceId(recording.id),
+    viewerEmail: scope.userEmail,
+    ttlSeconds: SESSION_REPLAY_AGENT_ACCESS_TTL_SECONDS,
+  });
+  const expiresAt = new Date(
+    Date.now() + SESSION_REPLAY_AGENT_ACCESS_TTL_SECONDS * 1000,
+  ).toISOString();
+  const sessionPath = appendAgentToken(
+    `/sessions/${encodeURIComponent(recording.id)}`,
+    token,
+  );
+  const contextPath = appendAgentToken(
+    `/api/session-replay/agent-context.json?id=${encodeURIComponent(
+      recording.id,
+    )}`,
+    token,
+  );
+
+  return {
+    recordingId: recording.id,
+    url: absoluteUrl(sessionPath, origin),
+    contextUrl: absoluteUrl(contextPath, origin),
+    expiresAt,
+    ttlSeconds: SESSION_REPLAY_AGENT_ACCESS_TTL_SECONDS,
+  };
+}
+
+export async function buildSessionReplayAgentContext({
+  recordingId,
+  token,
+  origin,
+  includeTimeline = true,
+}: {
+  recordingId: string;
+  token: string;
+  origin?: string;
+  includeTimeline?: boolean;
+}) {
+  if (!verifySessionReplayAgentAccess(recordingId, token)) {
+    const error = Object.assign(new Error("Invalid or expired agent access"), {
+      statusCode: 401,
+    });
+    throw error;
+  }
+
+  const recording = await getSessionReplayTokenizedSummary(recordingId);
+  const contextPath = appendAgentToken(
+    `/api/session-replay/agent-context.json?id=${encodeURIComponent(
+      recording.id,
+    )}`,
+    token,
+  );
+  const eventsPath = appendAgentToken(
+    `/api/session-replay/agent-events.json?id=${encodeURIComponent(
+      recording.id,
+    )}&limit=10000`,
+    token,
+  );
+  const pagePath = appendAgentToken(
+    `/sessions/${encodeURIComponent(recording.id)}`,
+    token,
+  );
+
+  const eventsResponse = includeTimeline
+    ? await getSessionReplayTokenizedEvents(recording.id, { limit: 10000 })
+    : null;
+  const events =
+    eventsResponse?.chunks.flatMap((chunk) =>
+      chunk.events.filter(
+        (event): event is AgentReplayEvent =>
+          Boolean(event) && typeof event === "object",
+      ),
+    ) ?? [];
+  const markers = buildReplayTimeline(events);
+
+  return {
+    type: "agent-native.analytics.session-replay",
+    version: 1,
+    instructions: [
+      "Use recording for the session-level summary and timeline.markers for navigation, clicks, inputs, scrolls, and custom 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.",
+    ],
+    recording: compactSessionRecordingSummary(recording),
+    apis: {
+      page: { method: "GET", url: absoluteUrl(pagePath, origin) },
+      context: { method: "GET", url: absoluteUrl(contextPath, origin) },
+      events: {
+        method: "GET",
+        url: absoluteUrl(eventsPath, origin),
+        note: "Returns bounded sanitized replay events; storage/provider URLs stay private.",
+      },
+    },
+    timeline: {
+      markerCount: markers.length,
+      markers,
+      truncated: Boolean(eventsResponse?.truncated),
+      unavailableChunks: eventsResponse?.unavailableChunks ?? 0,
+    },
+  };
+}
+
+export function safeJsonForHtml(value: unknown): string {
+  return JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (char) => {
+    switch (char) {
+      case "<":
+        return "\\u003c";
+      case ">":
+        return "\\u003e";
+      case "&":
+        return "\\u0026";
+      case "\u2028":
+        return "\\u2028";
+      case "\u2029":
+        return "\\u2029";
+      default:
+        return char;
+    }
+  });
+}

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

@@ -144,6 +144,70 @@ export interface SessionRecordingSummary {
   canManage?: boolean;
 }
 
+export interface AgentSessionRecordingSummary {
+  id: string;
+  clientRecordingId: string;
+  sessionId: string;
+  userId: string | null;
+  anonymousId: string | null;
+  userKey: string | null;
+  startedAt: string;
+  endedAt: string | null;
+  durationMs: number | null;
+  chunkCount: number;
+  eventCount: number;
+  totalBytes: number;
+  pageCount: number;
+  errorCount: number;
+  rageClickCount: number;
+  privacyMode: string;
+  firstUrl: string | null;
+  lastUrl: string | null;
+  path: string | null;
+  hostname: string | null;
+  referrer: string | null;
+  app: string | null;
+  template: string | null;
+  status: "active" | "completed";
+  createdAt: string;
+  updatedAt: string;
+  lastIngestedAt: string | null;
+}
+
+export function compactSessionRecordingSummary(
+  recording: SessionRecordingSummary,
+): AgentSessionRecordingSummary {
+  return {
+    id: recording.id,
+    clientRecordingId: recording.clientRecordingId,
+    sessionId: recording.sessionId,
+    userId: recording.userId,
+    anonymousId: recording.anonymousId,
+    userKey: recording.userKey,
+    startedAt: recording.startedAt,
+    endedAt: recording.endedAt,
+    durationMs: recording.durationMs,
+    chunkCount: recording.chunkCount,
+    eventCount: recording.eventCount,
+    totalBytes: recording.totalBytes,
+    pageCount: recording.pageCount,
+    errorCount: recording.errorCount,
+    rageClickCount: recording.rageClickCount,
+    privacyMode: recording.privacyMode,
+    firstUrl: recording.firstUrl,
+    lastUrl: recording.lastUrl,
+    path: recording.path,
+    hostname: recording.hostname,
+    referrer: recording.referrer,
+    app: recording.app,
+    template: recording.template,
+    status: recording.status,
+    createdAt: recording.createdAt,
+    updatedAt: recording.updatedAt,
+    lastIngestedAt: recording.lastIngestedAt,
+  };
+}
+
 const MAX_REPLAY_CHUNKS_PER_REQUEST = 20;
 const MAX_REPLAY_CHUNKS_PER_RECORDING = 2_000;
 const MAX_INLINE_REPLAY_CHUNK_BYTES = 256 * 1024;
@@ -1524,6 +1588,22 @@ export async function getSessionReplaySummary(
   return rowToSessionRecordingSummary(access.resource, access.role);
 }
 
+export async function getSessionReplayTokenizedSummary(
+  recordingId: string,
+): Promise<SessionRecordingSummary> {
+  const db = getDb() as any;
+  // guard:allow-unscoped -- called only after verifySessionReplayAgentAccess(recordingId, token) verifies a signed, recording-scoped agent_access token.
+  const [row] = await db
+    .select()
+    .from(schema.sessionRecordings)
+    .where(eq(schema.sessionRecordings.id, recordingId))
+    .limit(1);
+  if (!row || !isVisibleSessionRecording(row)) {
+    throw replayError("Session recording not found", 404);
+  }
+  return rowToSessionRecordingSummary(row, "viewer");
+}
+
 function parseInlineReplayEvents(inlineData: string): unknown[] {
   try {
     const parsed = JSON.parse(inlineData);
@@ -1563,8 +1643,47 @@ export async function getSessionReplayManifest(
   }>;
 }> {
   const recording = await getSessionReplaySummary(recordingId, scope);
+  return getSessionReplayManifestForRecording(recording);
+}
+
+export async function getSessionReplayTokenizedManifest(
+  recordingId: string,
+): Promise<{
+  recording: AgentSessionRecordingSummary;
+  chunks: Array<{
+    seq: number;
+    checksum: string;
+    byteLength: number;
+    eventCount: number;
+    startedAt: string | null;
+    endedAt: string | null;
+    bytesPath: string;
+  }>;
+}> {
+  const recording = await getSessionReplayTokenizedSummary(recordingId);
+  const manifest = await getSessionReplayManifestForRecording(recording);
+  return {
+    ...manifest,
+    recording: compactSessionRecordingSummary(manifest.recording),
+  };
+}
+
+async function getSessionReplayManifestForRecording(
+  recording: SessionRecordingSummary,
+): Promise<{
+  recording: SessionRecordingSummary;
+  chunks: Array<{
+    seq: number;
+    checksum: string;
+    byteLength: number;
+    eventCount: number;
+    startedAt: string | null;
+    endedAt: string | null;
+    bytesPath: string;
+  }>;
+}> {
   const db = getDb() as any;
-  // guard:allow-unscoped -- chunk rows are loaded only after resolveAccess("session-recording", recordingId) verifies viewer access; chunks are not directly shareable resources.
+  // guard:allow-unscoped -- chunk rows are loaded only after resolveAccess("session-recording", recordingId) or a scoped agent token verifies access; chunks are not directly shareable resources.
   const rows = await db
     .select()
     .from(schema.sessionReplayChunks)
@@ -1599,8 +1718,39 @@ export async function readSessionReplayChunkBytes(
   json: string;
 }> {
   const recording = await getSessionReplaySummary(recordingId, scope);
+  return readSessionReplayChunkBytesForRecording(recording, seq);
+}
+
+export async function readSessionReplayTokenizedChunkBytes(
+  recordingId: string,
+  seq: number,
+): Promise<{
+  recording: AgentSessionRecordingSummary;
+  seq: number;
+  checksum: string;
+  /** Decompressed replay-chunk JSON text (a serialized rrweb events array). */
+  json: string;
+}> {
+  const recording = await getSessionReplayTokenizedSummary(recordingId);
+  const chunk = await readSessionReplayChunkBytesForRecording(recording, seq);
+  return {
+    ...chunk,
+    recording: compactSessionRecordingSummary(chunk.recording),
+  };
+}
+
+async function readSessionReplayChunkBytesForRecording(
+  recording: SessionRecordingSummary,
+  seq: number,
+): Promise<{
+  recording: SessionRecordingSummary;
+  seq: number;
+  checksum: string;
+  /** Decompressed replay-chunk JSON text (a serialized rrweb events array). */
+  json: string;
+}> {
   const db = getDb() as any;
-  // guard:allow-unscoped -- chunk rows are loaded only after resolveAccess("session-recording", recordingId) verifies viewer access; chunks are not directly shareable resources.
+  // guard:allow-unscoped -- chunk rows are loaded only after resolveAccess("session-recording", recordingId) or a scoped agent token verifies access; chunks are not directly shareable resources.
   const [row] = await db
     .select()
     .from(schema.sessionReplayChunks)
@@ -1660,6 +1810,51 @@ export async function getSessionReplayEvents(
   unavailableChunks: number;
 }> {
   const recording = await getSessionReplaySummary(recordingId, scope);
+  return getSessionReplayEventsForRecording(recording, options);
+}
+
+export async function getSessionReplayTokenizedEvents(
+  recordingId: string,
+  options: SessionReplayEventReadOptions = {},
+): Promise<{
+  recording: AgentSessionRecordingSummary;
+  chunks: Array<{
+    seq: number;
+    checksum: string;
+    byteLength: number;
+    eventCount: number;
+    events: unknown[];
+    unavailable?: boolean;
+  }>;
+  eventCount: number;
+  truncated: boolean;
+  unavailableChunks: number;
+}> {
+  const recording = await getSessionReplayTokenizedSummary(recordingId);
+  const result = await getSessionReplayEventsForRecording(recording, options);
+  return {
+    ...result,
+    recording: compactSessionRecordingSummary(result.recording),
+  };
+}
+
+async function getSessionReplayEventsForRecording(
+  recording: SessionRecordingSummary,
+  options: SessionReplayEventReadOptions = {},
+): Promise<{
+  recording: SessionRecordingSummary;
+  chunks: Array<{
+    seq: number;
+    checksum: string;
+    byteLength: number;
+    eventCount: number;
+    events: unknown[];
+    unavailable?: boolean;
+  }>;
+  eventCount: number;
+  truncated: boolean;
+  unavailableChunks: number;
+}> {
   const maxEvents = Math.min(
     MAX_REPLAY_EVENTS_READ,
     Math.max(1, options.limit ?? MAX_REPLAY_EVENTS_READ),
@@ -1675,7 +1870,7 @@ export async function getSessionReplayEvents(
   }
 
   const db = getDb() as any;
-  // guard:allow-unscoped -- chunk rows are loaded only after resolveAccess("session-recording", recordingId) verifies viewer access; chunks are not directly shareable resources.
+  // guard:allow-unscoped -- chunk rows are loaded only after resolveAccess("session-recording", recordingId) or a scoped agent token verifies access; chunks are not directly shareable resources.
   const rows = await db
     .select()
     .from(schema.sessionReplayChunks)