@agent-native/core 0.121.2 → 0.122.0

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

@@ -382,6 +382,31 @@ export const recordingViews = table("recording_views", {
   viewedAt: text("viewed_at").notNull().default(now()),
 });
 
+// Agent views — one row per (clip, agent, time bucket). Deliberately separate
+// from `recording_viewers` / `recording_views` so no human-view count can ever
+// pick agents up by forgetting a filter: the human tables stay agent-free.
+export const recordingAgentViews = table(
+  "recording_agent_views",
+  {
+    id: text("id").primaryKey(),
+    recordingId: text("recording_id").notNull(),
+    // sha256 of user-agent + request IP. Never stores the raw IP.
+    agentKey: text("agent_key").notNull(),
+    agentLabel: text("agent_label"),
+    // Time bucket that collapses one agent's burst of context/transcript/frame
+    // polls into a single view.
+    viewSessionId: text("view_session_id").notNull(),
+    firstSeenAt: text("first_seen_at").notNull().default(now()),
+    lastSeenAt: text("last_seen_at").notNull().default(now()),
+    requestCount: integer("request_count").notNull().default(1),
+  },
+  (view) => ({
+    recordingAgentViewSessionUnique: uniqueIndex(
+      "recording_agent_views_session_unique_idx",
+    ).on(view.recordingId, view.agentKey, view.viewSessionId),
+  }),
+);
+
 // -----------------------------------------------------------------------------
 // Meetings (Granola-style) — recording + transcript + AI notes anchored to
 // a calendar event or an ad-hoc meeting block. Composes with the existing

package/corpus/templates/clips/server/lib/agent-views.ts

@@ -0,0 +1,145 @@
+/**
+ * Agent views — counting when an *outside agent* reads a clip through the
+ * public agent APIs (`/api/agent-context.json`, `/api/agent-transcript.json`,
+ * `/api/agent-frame.jpg`), as opposed to a human opening the player.
+ *
+ * Those routes are agent-only surfaces: a human watching a clip never hits
+ * them, so a request on one is the signal. Counts live in their own table so
+ * every existing human-view query stays agent-free by construction.
+ */
+
+import { createHash } from "node:crypto";
+
+import { count, desc, eq, sql } from "drizzle-orm";
+import { getRequestHeader, getRequestIP, type H3Event } from "h3";
+
+import { getDb, schema } from "../db/index.js";
+import { nanoid } from "./recordings.js";
+
+/**
+ * One agent's burst of context + transcript + frame polls is one view.
+ * Fixed windows mean a burst straddling a boundary counts twice; switch to
+ * last-seen-gap dedup if that ever shows up in the numbers.
+ */
+export const AGENT_VIEW_SESSION_MS = 30 * 60 * 1000;
+
+const AGENT_LABELS: [RegExp, string][] = [
+  [/claude|anthropic/i, "Claude"],
+  [/chatgpt|gptbot|oai-searchbot|openai/i, "ChatGPT"],
+  [/perplexity/i, "Perplexity"],
+  [/gemini|google-extended|googleother/i, "Gemini"],
+  [/copilot/i, "Copilot"],
+  [/cursor/i, "Cursor"],
+  [/bingbot|bingpreview/i, "Bing"],
+  [/applebot/i, "Apple Intelligence"],
+  [/meta-external|facebookbot/i, "Meta AI"],
+  [/bytespider|amazonbot|ccbot|diffbot|youbot/i, "Crawler"],
+];
+
+export const UNKNOWN_AGENT_LABEL = "Agent";
+
+export function agentLabelFromUserAgent(userAgent: string): string {
+  for (const [pattern, label] of AGENT_LABELS) {
+    if (pattern.test(userAgent)) return label;
+  }
+  return UNKNOWN_AGENT_LABEL;
+}
+
+export function agentViewSessionId(
+  now: number,
+  bucketMs = AGENT_VIEW_SESSION_MS,
+): string {
+  return String(Math.floor(now / bucketMs));
+}
+
+/** Hashed so an agent is distinguishable across polls without storing its IP. */
+export function agentKeyFor(userAgent: string, ip: string): string {
+  return createHash("sha256")
+    .update(`${userAgent}|${ip}`)
+    .digest("hex")
+    .slice(0, 32);
+}
+
+/**
+ * Best-effort: never let view accounting fail an agent's read of a clip.
+ */
+export async function recordAgentView(
+  event: H3Event,
+  recordingId: string,
+  nowMs: number = Date.now(),
+): Promise<void> {
+  try {
+    const userAgent = (getRequestHeader(event, "user-agent") ?? "").slice(
+      0,
+      512,
+    );
+    const ip = getRequestIP(event) || "unknown";
+    const now = new Date(nowMs).toISOString();
+
+    await getDb()
+      .insert(schema.recordingAgentViews)
+      .values({
+        id: nanoid(),
+        recordingId,
+        agentKey: agentKeyFor(userAgent, ip),
+        agentLabel: agentLabelFromUserAgent(userAgent),
+        viewSessionId: agentViewSessionId(nowMs),
+        firstSeenAt: now,
+        lastSeenAt: now,
+        requestCount: 1,
+      })
+      .onConflictDoUpdate({
+        target: [
+          schema.recordingAgentViews.recordingId,
+          schema.recordingAgentViews.agentKey,
+          schema.recordingAgentViews.viewSessionId,
+        ],
+        set: {
+          lastSeenAt: now,
+          requestCount: sql`${schema.recordingAgentViews.requestCount} + 1`,
+        },
+      });
+  } catch (err) {
+    console.warn("[agent-views] failed to record agent view:", err);
+  }
+}
+
+export async function countRecordingAgentViews(
+  recordingId: string,
+): Promise<number> {
+  const [row] = await getDb()
+    .select({ value: count() })
+    .from(schema.recordingAgentViews)
+    .where(eq(schema.recordingAgentViews.recordingId, recordingId));
+  return Number(row?.value ?? 0);
+}
+
+export interface AgentViewerSummary {
+  agentLabel: string;
+  views: number;
+  lastSeenAt: string;
+}
+
+/** Agents that read this clip, most recent first, grouped by product label. */
+export async function listRecordingAgentViewers(
+  recordingId: string,
+  limit = 8,
+): Promise<AgentViewerSummary[]> {
+  const rows = await getDb()
+    .select({
+      agentLabel: schema.recordingAgentViews.agentLabel,
+      views: count(),
+      lastSeenAt: sql<string>`MAX(${schema.recordingAgentViews.lastSeenAt})`,
+    })
+    .from(schema.recordingAgentViews)
+    .where(eq(schema.recordingAgentViews.recordingId, recordingId))
+    .groupBy(schema.recordingAgentViews.agentLabel)
+    .orderBy(desc(sql`MAX(${schema.recordingAgentViews.lastSeenAt})`))
+    .limit(limit);
+
+  return rows.map((r) => ({
+    agentLabel: r.agentLabel || UNKNOWN_AGENT_LABEL,
+    views: Number(r.views ?? 0),
+    lastSeenAt: r.lastSeenAt,
+  }));
+}

package/corpus/templates/clips/server/lib/public-agent-context.ts

@@ -31,6 +31,7 @@ import {
 } from "../../shared/transcript-segments.js";
 import { resolveTranscriptPresentation } from "../../shared/transcript-status.js";
 import { getDb, schema } from "../db/index.js";
+import { recordAgentView } from "./agent-views.js";
 import { verifySharePassword } from "./share-password.js";
 
 export type PublicAgentRecording = typeof schema.recordings._.inferSelect;
@@ -290,6 +291,12 @@ export async function loadPublicAgentAccess(
     }
   }
 
+  // Every agent API route funnels through here, so this is the one place that
+  // sees an outside agent read a clip. Owner requests are previews, not views.
+  if (!viewerIsOwner) {
+    await recordAgentView(event, recording.id);
+  }
+
   return {
     ok: true,
     access: {

package/corpus/templates/clips/server/lib/recording-share-grant.ts

@@ -0,0 +1,79 @@
+/**
+ * Explicit share-grant lookup for the direct `/r/:id` recording page.
+ *
+ * Lives beside `recording-page-access.ts` rather than inside it so that module
+ * stays free of database imports and their registration side effects. Every
+ * surface that decides whether a viewer may open the authenticated recording
+ * page — the player action and the public share endpoint that auto-redirects
+ * into it — must use this helper, or the share page and the page it redirects
+ * to will disagree and ping-pong.
+ */
+
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { and, eq, or, sql } from "drizzle-orm";
+
+import { getDb, schema } from "../db/index.js";
+import type { RecordingPageAccessRole } from "./recording-page-access.js";
+import type { RecordingVisibility } from "./recordings.js";
+
+export interface RecordingShareGrantInput {
+  recordingId: string;
+  role: RecordingPageAccessRole;
+  visibility: RecordingVisibility;
+  hasPassword: boolean;
+  /** Agent/MCP/A2A callers, which may open password-less public clips. */
+  isAgentCaller?: boolean;
+  /** Omit to read the ambient request context. */
+  userEmail?: string | null;
+  /** Omit to read the ambient request context. */
+  orgId?: string | null;
+}
+
+export async function hasExplicitRecordingShare(
+  input: RecordingShareGrantInput,
+): Promise<boolean> {
+  if (input.role === "owner") return true;
+  if (input.visibility !== "public") return false;
+  if (!input.hasPassword && input.isAgentCaller) return true;
+
+  const userEmail = (
+    input.userEmail === undefined ? getRequestUserEmail() : input.userEmail
+  )
+    ?.trim()
+    .toLowerCase();
+  const orgId = input.orgId === undefined ? getRequestOrgId() : input.orgId;
+
+  const principals = [];
+  if (userEmail) {
+    principals.push(
+      and(
+        eq(schema.recordingShares.principalType, "user"),
+        sql`lower(${schema.recordingShares.principalId}) = ${userEmail}`,
+      ),
+    );
+  }
+  if (orgId) {
+    principals.push(
+      and(
+        eq(schema.recordingShares.principalType, "org"),
+        eq(schema.recordingShares.principalId, orgId),
+      ),
+    );
+  }
+  if (principals.length === 0) return false;
+
+  const [share] = await getDb()
+    .select({ id: schema.recordingShares.id })
+    .from(schema.recordingShares)
+    .where(
+      and(
+        eq(schema.recordingShares.resourceId, input.recordingId),
+        or(...principals),
+      ),
+    )
+    .limit(1);
+  return Boolean(share);
+}

package/corpus/templates/clips/server/lib/recordings.ts

@@ -1,11 +1,11 @@
 import { readAppState } from "@agent-native/core/application-state";
-import { orgMembers } from "@agent-native/core/org";
+import { implicitServiceOrgRole, orgMembers } from "@agent-native/core/org";
 import { getSession } from "@agent-native/core/server";
 import {
   getRequestUserEmail,
   getRequestOrgId,
 } from "@agent-native/core/server/request-context";
-import { and, desc, eq, sql } from "drizzle-orm";
+import { and, count, desc, eq, sql } from "drizzle-orm";
 import { HTTPError, type H3Event } from "h3";
 
 import { getDb, schema } from "../db/index.js";
@@ -142,7 +142,11 @@ export async function getOrganizationRoleForEmail(
     // org_members table may not exist yet on first boot before migrations finish.
   }
 
-  return null;
+  return implicitServiceOrgRole({
+    email,
+    orgId: organizationId,
+    requestOrgId: getRequestOrgId(),
+  });
 }
 
 export async function requireOrganizationAccess(
@@ -362,3 +366,47 @@ export function shouldCountView(
 ): boolean {
   return totalWatchMs >= 5000 || completedPct >= 75 || scrubbedToEnd;
 }
+
+/**
+ * The single definition of a counted *viewer*: one `recording_viewers` row
+ * whose `countedView` flag is set. That is one row per person, so it answers
+ * "how many distinct viewers", not "how many views" — use
+ * `countRecordingViews` for the total. The in-memory twin is
+ * `isCountedViewerRow` in `shared/view-analytics.ts`.
+ */
+export function countedViewCondition() {
+  return eq(schema.recordingViewers.countedView, true);
+}
+
+/**
+ * Total views for a recording: one per counted view *session*, so a returning
+ * viewer's second visit counts again. Every surface that reports a view count
+ * (library list, insights, player, public share page) goes through this.
+ */
+export async function countRecordingViews(
+  recordingId: string,
+): Promise<number> {
+  const db = getDb();
+  const [viewerRow] = await db
+    .select({ value: count() })
+    .from(schema.recordingViewers)
+    .where(
+      and(
+        eq(schema.recordingViewers.recordingId, recordingId),
+        countedViewCondition(),
+      ),
+    );
+  const [viewLogRow] = await db
+    .select({ value: count() })
+    .from(schema.recordingViews)
+    .where(eq(schema.recordingViews.recordingId, recordingId));
+
+  // `recording_views` only exists from migration v46, so clips recorded before
+  // it have zero log rows. Floor the total at the counted-viewer count so those
+  // clips keep reporting a real number instead of dropping to 0, and so the
+  // total can never read below the unique-viewer count beside it.
+  return Math.max(
+    Number(viewLogRow?.value ?? 0),
+    Number(viewerRow?.value ?? 0),
+  );
+}

package/corpus/templates/clips/server/plugins/db.ts

@@ -850,6 +850,29 @@ const migrations = runMigrations(
         `UPDATE organization_settings SET default_visibility = 'public' WHERE default_visibility = 'private' AND updated_at = created_at`,
       ].join("; "),
     },
+    // -------------------------------------------------------------------------
+    // Agent views — external agents polling a public clip's agent context,
+    // transcript, or frame APIs. Kept in its own table so human view counts
+    // cannot accidentally include agents.
+    // -------------------------------------------------------------------------
+    {
+      version: 51,
+      name: "recording-agent-views",
+      sql: [
+        `CREATE TABLE IF NOT EXISTS recording_agent_views (
+          id TEXT PRIMARY KEY,
+          recording_id TEXT NOT NULL,
+          agent_key TEXT NOT NULL,
+          agent_label TEXT,
+          view_session_id TEXT NOT NULL,
+          first_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+          last_seen_at TEXT NOT NULL DEFAULT (datetime('now')),
+          request_count INTEGER NOT NULL DEFAULT 1
+        )`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS recording_agent_views_session_unique_idx ON recording_agent_views (recording_id, agent_key, view_session_id)`,
+        `CREATE INDEX IF NOT EXISTS recording_agent_views_recording_idx ON recording_agent_views (recording_id, last_seen_at)`,
+      ].join("; "),
+    },
   ],
   { table: "clips_migrations" },
 );

package/corpus/templates/clips/server/routes/api/public-recording.get.ts

@@ -46,8 +46,16 @@ import { isMediaVerificationPending } from "../../lib/media-verification-state.j
 import { resolvePlayerThumbnailUrl } from "../../lib/player-thumbnail-url.js";
 import { resolvePlayerVideoUrl } from "../../lib/player-video-url.js";
 import {
+  canOpenDirectRecordingPage,
+  isRecordingExpired,
+  type RecordingPageAccessRole,
+} from "../../lib/recording-page-access.js";
+import { hasExplicitRecordingShare } from "../../lib/recording-share-grant.js";
+import {
+  countRecordingViews,
   getOrganizationRoleForEmail,
   parseSpaceIds,
+  type RecordingVisibility,
 } from "../../lib/recordings.js";
 import { verifySharePassword } from "../../lib/share-password.js";
 
@@ -258,12 +266,10 @@ export default defineEventHandler(async (event) => {
   }
 
   // Expiry check
-  if (rec.expiresAt) {
-    const expires = new Date(rec.expiresAt).getTime();
-    if (isFinite(expires) && expires < Date.now()) {
-      setResponseStatus(event, 410);
-      return { error: "Recording has expired", expired: true };
-    }
+  const recordingExpired = isRecordingExpired(rec.expiresAt);
+  if (recordingExpired) {
+    setResponseStatus(event, 410);
+    return { error: "Recording has expired", expired: true };
   }
 
   // Password check
@@ -405,6 +411,32 @@ export default defineEventHandler(async (event) => {
     recordingStatus: rec.status,
   });
 
+  const viewCount = await countRecordingViews(recordingId);
+
+  const viewerRole =
+    viewerAccess?.role ?? (viewerIsOrgMember ? "viewer" : null);
+  // Mirrors the gate in `get-recording-player-data` exactly: the share page
+  // auto-redirects on this flag, so a false positive bounces the viewer
+  // between /share/:id and /r/:id forever. Only a resolved access role can
+  // open the direct page — the org-member fallback above is a display role,
+  // not access the player action would grant.
+  const canOpenDashboard =
+    Boolean(session?.email) && viewerAccess && !recordingExpired
+      ? canOpenDirectRecordingPage({
+          role: viewerAccess.role as RecordingPageAccessRole,
+          visibility: rec.visibility as RecordingVisibility,
+          hasPassword: Boolean(rec.password),
+          hasExplicitShare: await hasExplicitRecordingShare({
+            recordingId,
+            role: viewerAccess.role as RecordingPageAccessRole,
+            visibility: rec.visibility as RecordingVisibility,
+            hasPassword: Boolean(rec.password),
+            userEmail: session?.email ?? null,
+            orgId: session?.orgId ?? null,
+          }),
+        })
+      : false;
+
   return {
     recording: {
       id: rec.id,
@@ -439,6 +471,8 @@ export default defineEventHandler(async (event) => {
       updatedAt: rec.updatedAt,
     },
     agentContextUrl,
+    // Aggregate count only — never viewer identities on this public payload.
+    viewCount,
     transcript: transcript
       ? {
           status: transcriptPresentation.status,
@@ -479,17 +513,15 @@ export default defineEventHandler(async (event) => {
       placement: c.placement,
     })),
     viewer: session?.email
-      ? (() => {
-          const role =
-            viewerAccess?.role ?? (viewerIsOrgMember ? "viewer" : null);
-          const canEdit =
-            role === "owner" || role === "admin" || role === "editor";
-          return {
-            canEdit,
-            isOwner: role === "owner",
-            role: role ?? "viewer",
-          };
-        })()
+      ? {
+          canEdit:
+            viewerRole === "owner" ||
+            viewerRole === "admin" ||
+            viewerRole === "editor",
+          isOwner: viewerRole === "owner",
+          role: viewerRole ?? "viewer",
+          canOpenDashboard,
+        }
       : null,
   };
 });

package/corpus/templates/clips/shared/recording-link.ts

@@ -0,0 +1,43 @@
+/**
+ * Canonical share URL for a recording, shared by every surface that hands a
+ * user a link to paste: the web recorder, the desktop app, and the Chrome
+ * extension.
+ *
+ * `/share/<id>` is the public viewer page — SSR-rendered, password/expiry
+ * aware, and the shape Slack unfurls. `/r/<id>` is the owner dashboard: it
+ * renders client-side only and shows a sign-in prompt to a recipient. Copying
+ * `/r/<id>` produces a link that works for the author and looks broken to
+ * everyone they send it to, so share flows must build URLs from here rather
+ * than hand-rolling a path.
+ */
+import { withShareAttribution } from "./share-attribution";
+
+/** Public share path for a recording, relative to the app base path. */
+export function recordingSharePath(recordingId: string): string {
+  return `/share/${encodeURIComponent(recordingId)}`;
+}
+
+export interface RecordingShareUrlParams {
+  recordingId: string;
+  /** Absolute origin, e.g. `https://clips.example.com` or a desktop serverUrl. */
+  origin: string;
+  /** App base path when the app is mounted under a subpath. */
+  basePath?: string;
+  /** Non-PII owner id for viral attribution. Omitted when unknown. */
+  ownerId?: string | null;
+}
+
+/**
+ * Absolute, ready-to-paste share URL for a recording, carrying the same
+ * attribution params the Share dialog mints so auto-copied links measure the
+ * signup funnel identically.
+ */
+export function buildRecordingShareUrl(
+  params: RecordingShareUrlParams,
+): string {
+  const { recordingId, origin, basePath = "", ownerId } = params;
+  const trimmedOrigin = origin.trim().replace(/\/+$/, "");
+  const trimmedBase = basePath.trim().replace(/\/+$/, "");
+  const url = `${trimmedOrigin}${trimmedBase}${recordingSharePath(recordingId)}`;
+  return withShareAttribution(url, ownerId);
+}

package/corpus/templates/clips/shared/share-attribution.ts

@@ -21,6 +21,10 @@ export const CLIP_SHARE_REF = "clip_share";
 export const REF_PARAM = "ref";
 export const VIA_PARAM = "via";
 
+/** Marker used only when `/r/:id` falls back to the public share route. */
+export const DASHBOARD_REDIRECT_PARAM = "dashboard_redirect";
+export const DASHBOARD_REDIRECT_VALUE = "1";
+
 /**
  * Append `ref=clip_share` (and `via=<ownerId>` when a non-PII owner id is
  * known) to an absolute share/embed URL, preserving any existing query params.

package/corpus/templates/clips/shared/share-dashboard-redirect.ts

@@ -0,0 +1,42 @@
+import {
+  DASHBOARD_REDIRECT_PARAM,
+  DASHBOARD_REDIRECT_VALUE,
+} from "./share-attribution.js";
+
+/** Query params worth carrying from /share/:id over to /r/:id. */
+const FORWARDED_PARAMS = ["t", "panel"] as const;
+
+export interface DashboardRedirectInput {
+  recordingId: string | null | undefined;
+  /**
+   * The server's `canOpenDirectRecordingPage` verdict, not a display role.
+   * /r sends anyone it rejects back to /share, so a looser predicate here
+   * bounces the viewer between the two routes forever.
+   */
+  canOpenDashboard: boolean;
+  /** Current location search string, with or without the leading `?`. */
+  search: string;
+}
+
+/**
+ * Where a share-link visitor should be sent instead of rendering /share/:id,
+ * or null to stay put.
+ */
+export function resolveDashboardRedirect(
+  input: DashboardRedirectInput,
+): string | null {
+  if (!input.canOpenDashboard || !input.recordingId) return null;
+
+  const params = new URLSearchParams(input.search);
+  if (params.get(DASHBOARD_REDIRECT_PARAM) === DASHBOARD_REDIRECT_VALUE)
+    return null;
+
+  const forwarded = new URLSearchParams();
+  for (const key of FORWARDED_PARAMS) {
+    const value = params.get(key);
+    if (value) forwarded.set(key, value);
+  }
+
+  const query = forwarded.toString();
+  return `/r/${encodeURIComponent(input.recordingId)}${query ? `?${query}` : ""}`;
+}

package/corpus/templates/clips/shared/view-analytics.ts

@@ -2,3 +2,29 @@ export function clampCompletionPct(value: number | null | undefined): number {
   if (typeof value !== "number" || !Number.isFinite(value)) return 0;
   return Math.min(100, Math.max(0, value));
 }
+
+/**
+ * In-memory twin of `countedViewCondition` / `countRecordingViews` in
+ * `server/lib/recordings.ts`: a view is one `recording_viewers` row whose
+ * `countedView` flag is set. Use it whenever the rows are already loaded so
+ * every surface reports the same number.
+ */
+export function isCountedViewerRow(row: { countedView?: unknown }): boolean {
+  return Boolean(row.countedView);
+}
+
+export const ANONYMOUS_VIEWER_NAME_PREFIX = "anon:";
+
+/**
+ * Anonymous rows keep their `anon:<sessionId>` dedup key in `viewer_name`.
+ * That key is storage plumbing, never a display name — return null so callers
+ * render their own "Someone" placeholder instead of leaking the session key.
+ */
+export function displayViewerName(
+  viewerName: string | null | undefined,
+): string | null {
+  if (viewerName == null) return null;
+  return viewerName.startsWith(ANONYMOUS_VIEWER_NAME_PREFIX)
+    ? null
+    : viewerName;
+}

package/corpus/templates/content/.agents/skills/content/SKILL.md

@@ -237,6 +237,11 @@ File access still requires a local Content app, Agent Native Desktop, or another
 trusted bridge. Disconnecting a folder leaves the SQL pages and disk files in
 place. Concurrent edits and missing source files require explicit review.
 
+See **`references/local-file-mode.md`** for the full folder-source Pull/Check/Push
+workflow, the manifest/CLI launch commands, Builder Symbols and Builder
+source-component preservation rules, picked-folder/Desktop component
+previews, and the agent component-edit workflow.
+
 ## MDX And Components
 
 - Preserve frontmatter keys you do not understand. Preserve MDX imports,