@agent-native/core 0.84.55 → 0.84.57

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)

package/corpus/templates/analytics/server/routes/[...page].get.ts

@@ -1,5 +1,108 @@
 import { createH3SSRHandler } from "@agent-native/core/server/ssr-handler";
+import {
+  defineEventHandler,
+  getQuery,
+  getRequestURL,
+  setResponseHeader,
+} from "h3";
 
-export default createH3SSRHandler(
+import {
+  buildSessionReplayAgentContext,
+  safeJsonForHtml,
+  SESSION_REPLAY_AGENT_ACCESS_PARAM,
+} from "../lib/session-replay-agent-context.js";
+
+const ssrHandler = createH3SSRHandler(
   () => import("virtual:react-router/server-build"),
 );
+
+function configuredAppBasePath(): string {
+  const raw = process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH || "";
+  if (!raw || raw === "/") return "";
+  const normalized = raw.startsWith("/") ? raw : `/${raw}`;
+  return normalized.replace(/\/+$/, "");
+}
+
+function stripAppBasePath(pathname: string): string {
+  const basePath = configuredAppBasePath();
+  if (!basePath) return pathname;
+  if (pathname === basePath) return "/";
+  if (pathname.startsWith(`${basePath}/`)) {
+    return pathname.slice(basePath.length) || "/";
+  }
+  return pathname;
+}
+
+function sessionRecordingIdFromPath(pathname: string): string | null {
+  const match = stripAppBasePath(pathname).match(/^\/sessions\/([^/]+)\/?$/);
+  if (!match?.[1]) return null;
+  try {
+    return decodeURIComponent(match[1]);
+  } catch {
+    return match[1];
+  }
+}
+
+function queryString(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && typeof value[0] === "string") return value[0];
+  return "";
+}
+
+async function buildAgentDiscoveryScript(event: any): Promise<string | null> {
+  const requestUrl = getRequestURL(event);
+  const recordingId = sessionRecordingIdFromPath(requestUrl.pathname);
+  if (!recordingId) return null;
+
+  const query = getQuery(event);
+  const token = queryString(query[SESSION_REPLAY_AGENT_ACCESS_PARAM]);
+  if (!token) return null;
+
+  const context = await buildSessionReplayAgentContext({
+    recordingId,
+    token,
+    origin: requestUrl.origin,
+    includeTimeline: false,
+  }).catch(() => null);
+  if (!context) return null;
+
+  return `<script type="application/agent-native+json" id="analytics-session-replay-agent-context">${safeJsonForHtml(
+    context,
+  )}</script>`;
+}
+
+function injectAgentDiscovery(html: string, script: string): string {
+  if (html.includes('id="analytics-session-replay-agent-context"')) {
+    return html;
+  }
+  if (html.includes("</head>")) {
+    return html.replace("</head>", `${script}</head>`);
+  }
+  if (html.includes("</body>")) {
+    return html.replace("</body>", `${script}</body>`);
+  }
+  return `${html}${script}`;
+}
+
+export default defineEventHandler(async (event) => {
+  const response = (await ssrHandler(event)) as Response;
+  const script = await buildAgentDiscoveryScript(event);
+  if (!script) return response;
+
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("text/html")) return response;
+
+  const html = await response.text();
+  const headers = new Headers(response.headers);
+  headers.delete("content-length");
+  headers.set("Cache-Control", "private, max-age=0, no-store");
+  headers.set("Referrer-Policy", "no-referrer");
+  setResponseHeader(event, "Cache-Control", "private, max-age=0, no-store");
+  setResponseHeader(event, "Referrer-Policy", "no-referrer");
+
+  return new Response(injectAgentDiscovery(html, script), {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+});

package/corpus/templates/analytics/server/routes/api/session-replay/agent-context.json.get.ts

@@ -0,0 +1,48 @@
+import {
+  defineEventHandler,
+  getQuery,
+  getRequestURL,
+  setResponseHeader,
+  setResponseStatus,
+} from "h3";
+
+import {
+  buildSessionReplayAgentContext,
+  SESSION_REPLAY_AGENT_ACCESS_PARAM,
+} from "../../../lib/session-replay-agent-context.js";
+
+function queryString(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && typeof value[0] === "string") return value[0];
+  return "";
+}
+
+function applyAgentJsonHeaders(event: any) {
+  setResponseHeader(event, "Content-Type", "application/json; charset=utf-8");
+  setResponseHeader(event, "X-Content-Type-Options", "nosniff");
+  setResponseHeader(event, "Referrer-Policy", "no-referrer");
+  setResponseHeader(event, "Cache-Control", "private, max-age=0, no-store");
+}
+
+export default defineEventHandler(async (event) => {
+  applyAgentJsonHeaders(event);
+  const query = getQuery(event);
+  const id = queryString(query.id);
+  const token = queryString(query[SESSION_REPLAY_AGENT_ACCESS_PARAM]);
+
+  if (!id || !token) {
+    setResponseStatus(event, 400);
+    return { error: "id and agent access token are required" };
+  }
+
+  try {
+    return await buildSessionReplayAgentContext({
+      recordingId: id,
+      token,
+      origin: getRequestURL(event).origin,
+    });
+  } catch (error: any) {
+    setResponseStatus(event, error?.statusCode ?? 400);
+    return { error: error?.message || String(error) };
+  }
+});

package/corpus/templates/analytics/server/routes/api/session-replay/agent-events.json.get.ts

@@ -0,0 +1,63 @@
+import {
+  defineEventHandler,
+  getQuery,
+  setResponseHeader,
+  setResponseStatus,
+} from "h3";
+
+import {
+  SESSION_REPLAY_AGENT_ACCESS_PARAM,
+  verifySessionReplayAgentAccess,
+} from "../../../lib/session-replay-agent-context.js";
+import {
+  getSessionReplayTokenizedEvents,
+  type SessionReplayEventReadOptions,
+} from "../../../lib/session-replay.js";
+
+function queryString(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && typeof value[0] === "string") return value[0];
+  return "";
+}
+
+function queryInt(value: unknown): number | undefined {
+  const raw = queryString(value);
+  if (!raw || !/^\d+$/.test(raw)) return undefined;
+  return Number(raw);
+}
+
+function applyAgentJsonHeaders(event: any) {
+  setResponseHeader(event, "Content-Type", "application/json; charset=utf-8");
+  setResponseHeader(event, "X-Content-Type-Options", "nosniff");
+  setResponseHeader(event, "Referrer-Policy", "no-referrer");
+  setResponseHeader(event, "Cache-Control", "private, max-age=0, no-store");
+}
+
+export default defineEventHandler(async (event) => {
+  applyAgentJsonHeaders(event);
+  const query = getQuery(event);
+  const id = queryString(query.id);
+  const token = queryString(query[SESSION_REPLAY_AGENT_ACCESS_PARAM]);
+
+  if (!id || !token) {
+    setResponseStatus(event, 400);
+    return { error: "id and agent access token are required" };
+  }
+  if (!verifySessionReplayAgentAccess(id, token)) {
+    setResponseStatus(event, 401);
+    return { error: "Invalid or expired agent access" };
+  }
+
+  const options: SessionReplayEventReadOptions = {
+    startSeq: queryInt(query.startSeq),
+    endSeq: queryInt(query.endSeq),
+    limit: queryInt(query.limit),
+  };
+
+  try {
+    return await getSessionReplayTokenizedEvents(id, options);
+  } catch (error: any) {
+    setResponseStatus(event, error?.statusCode ?? 400);
+    return { error: error?.message || String(error) };
+  }
+});

package/corpus/templates/analytics/shared/session-replay-agent-access.ts

@@ -0,0 +1,10 @@
+export const SESSION_REPLAY_AGENT_ACCESS_PARAM = "agent_access";
+
+const SESSION_REPLAY_AGENT_ACCESS_TOKEN_PREFIX =
+  "analytics-session-replay-agent-context";
+
+export function sessionReplayAgentAccessTokenResourceId(
+  recordingId: string,
+): string {
+  return `${SESSION_REPLAY_AGENT_ACCESS_TOKEN_PREFIX}:${recordingId}`;
+}

package/corpus/templates/clips/.agents/skills/video-sharing/SKILL.md

@@ -156,9 +156,10 @@ Required Slack app setup:
 - Deploy secrets: `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, and
   `SLACK_SIGNING_SECRET`
 
-## Agent-readable public clips
+## Agent-readable clips
 
-Public recordings also expose URLs meant for external agents:
+Recordings can expose URLs meant for external agents without handing over raw
+video bytes:
 
 | Endpoint | Meaning |
 | -------- | ------- |
@@ -166,9 +167,14 @@ Public recordings also expose URLs meant for external agents:
 | `/api/agent-transcript.json?id=<recordingId>` | Timestamped transcript segments with `startMs`, `endMs`, `timestamp`, `range`, `text`, and optional `source` |
 | `/api/agent-frame.jpg?id=<recordingId>&atMs=<ms>` | JPEG frame extracted from the video at the requested original-video timestamp |
 
-These endpoints follow the same access model as `/api/public-recording`:
+These endpoints follow the same access model as `/api/public-recording`, plus a
+temporary agent-link path:
 
 - Non-public clips return not found to anonymous callers.
+- `create-recording-agent-link` resolves normal recording access, rejects
+  archived or trashed recordings, then mints a two-hour `agent_access` URL for
+  `/share/:recordingId`. The share page SSR advertises the agent context URL,
+  and the JSON endpoints accept the same scoped token.
 - Expired clips return expired.
 - Password-protected clips require `password=<pw>` once; successful JSON
   responses include short-lived tokenized links so the plaintext password is not
@@ -183,11 +189,11 @@ These endpoints follow the same access model as `/api/public-recording`:
 - Frame extraction must use the checked recording media path and must not expose
   raw provider URLs.
 
-The share popover's "Share with agents" field should copy the agent context URL,
-not raw transcript text. Its "Copy agent prompt" field may wrap that URL with
-instructions to fetch transcripts, frames, and browser diagnostics, but it should
-still point agents at the context response so they can fetch only the visual
-context they need.
+The share popover's "Share with agents" field should copy an agent context URL
+or tokenized share page URL, not raw transcript text. Its "Copy agent prompt"
+field may wrap that URL with instructions to fetch transcripts, frames, and
+browser diagnostics, but it should still point agents at the context response so
+they can fetch only the visual context they need.
 
 ## View counting
 

package/corpus/templates/clips/AGENTS.md

@@ -132,8 +132,9 @@ Detailed media, meeting, dictation, editing, and sharing rules live in
 - `navigate` moves the UI to recording/library/meeting/share surfaces.
 - Use data actions for full transcripts and media metadata.
 - For the in-app Clips agent, prefer `get-recording-player-data` for full
-  private/authenticated recording context. Use the public agent-context URLs
-  when preparing a link for another agent outside Clips.
+  private/authenticated recording context. When preparing a link for another
+  agent outside Clips, use `create-recording-agent-link`; it mints a two-hour
+  `agent_access` share URL without changing recording visibility.
 
 ## Skills
 

package/corpus/templates/clips/actions/create-recording-agent-link.ts

@@ -0,0 +1,90 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestContext,
+  getRequestUserEmail,
+  signShortLivedToken,
+} from "@agent-native/core/server";
+import { ForbiddenError, resolveAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import {
+  CLIPS_AGENT_ACCESS_PARAM,
+  CLIPS_AGENT_ACCESS_TTL_SECONDS,
+  getServerAppBasePath,
+} from "../server/lib/public-agent-context.js";
+import {
+  agentAccessTokenResourceId,
+  buildAgentApiUrls,
+} from "../shared/agent-context.js";
+
+function appOrigin(): string {
+  const origin =
+    getRequestContext()?.requestOrigin ||
+    process.env.APP_URL ||
+    process.env.BETTER_AUTH_URL ||
+    "http://localhost:3000";
+  try {
+    return new URL(origin).origin;
+  } catch {
+    return "http://localhost:3000";
+  }
+}
+
+function appendAgentAccess(url: string, token: string): string {
+  const sep = url.includes("?") ? "&" : "?";
+  return `${url}${sep}${CLIPS_AGENT_ACCESS_PARAM}=${encodeURIComponent(token)}`;
+}
+
+export default defineAction({
+  description:
+    "Create a temporary private agent-readable link for one Clips recording. The URL is scoped to that recording and expires after two hours.",
+  schema: z.object({
+    recordingId: z.string().describe("Recording ID"),
+  }),
+  readOnly: true,
+  run: async (args) => {
+    const access = await resolveAccess("recording", args.recordingId);
+    if (!access) {
+      throw new ForbiddenError(`No access to recording ${args.recordingId}`);
+    }
+
+    const recording = access.resource as {
+      id: string;
+      archivedAt?: string | null;
+      trashedAt?: string | null;
+    };
+    if (recording.archivedAt || recording.trashedAt) {
+      throw new ForbiddenError(
+        `Recording ${args.recordingId} is not shareable`,
+      );
+    }
+
+    const token = signShortLivedToken({
+      resourceId: agentAccessTokenResourceId(recording.id),
+      viewerEmail: getRequestUserEmail() || undefined,
+      ttlSeconds: CLIPS_AGENT_ACCESS_TTL_SECONDS,
+    });
+    const origin = appOrigin();
+    const basePath = getServerAppBasePath();
+    const expiresAt = new Date(
+      Date.now() + CLIPS_AGENT_ACCESS_TTL_SECONDS * 1000,
+    ).toISOString();
+    const pageUrl = appendAgentAccess(
+      `${origin}${basePath}/share/${encodeURIComponent(recording.id)}`,
+      token,
+    );
+    const api = buildAgentApiUrls(recording.id, {
+      origin,
+      basePath,
+      token,
+    });
+
+    return {
+      recordingId: recording.id,
+      url: pageUrl,
+      contextUrl: api.contextUrl,
+      expiresAt,
+      ttlSeconds: CLIPS_AGENT_ACCESS_TTL_SECONDS,
+    };
+  },
+});