@agent-native/core-corpus 0.214.0 → 0.217.0

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

@@ -0,0 +1,33 @@
+/** The origin of a URL, or null when it has none. */
+export function normalizeReplayOrigin(
+  value: string | null | undefined,
+): string | null {
+  if (!value) return null;
+  try {
+    return new URL(value).origin;
+    // coercion-ok: a value that is not a URL names no origin, and callers treat null as "no origin".
+  } catch {
+    return null;
+  }
+}
+
+/** A replay key's allowed origins, stored as a JSON array or as comma- or newline-separated text. */
+export function parseAllowedReplayOrigins(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value
+      .map((item) =>
+        normalizeReplayOrigin(typeof item === "string" ? item.trim() : null),
+      )
+      .filter((item): item is string => Boolean(item));
+  }
+  if (typeof value !== "string" || !value.trim()) return [];
+  try {
+    return parseAllowedReplayOrigins(JSON.parse(value));
+    // coercion-ok: text that is not JSON is the comma- or newline-separated form.
+  } catch {
+    return value
+      .split(/[\n,]/)
+      .map((item) => normalizeReplayOrigin(item.trim()))
+      .filter((item): item is string => Boolean(item));
+  }
+}

package/corpus/templates/analytics/server/lib/session-event-index.ts

@@ -14,6 +14,7 @@ import {
 } from "drizzle-orm";
 import { alias } from "drizzle-orm/pg-core";
 
+import { OUTPUT_MADE_EVENT, outputUseRule } from "../../shared/output-use.js";
 import {
   AUTOMATIC_ANALYTICS_EVENT_NAMES,
   type EventCatalogApp,
@@ -686,6 +687,18 @@ export async function listSessionEventNames(
   };
 }
 
+function outputEventRole(
+  app: string | null,
+  eventName: string,
+): EventCatalogEntry["outputRole"] {
+  const rule = outputUseRule(app);
+  if (!rule) return null;
+  if (rule.madeEvents.includes(eventName)) return "made";
+  return rule.usedEvents.some((event) => event.eventName === eventName)
+    ? "used"
+    : null;
+}
+
 export function isAutomaticAnalyticsEvent(eventName: string): boolean {
   return AUTOMATIC_ANALYTICS_EVENT_NAMES.has(eventName);
 }
@@ -798,6 +811,7 @@ export async function listEventCatalog(
         app: c.app,
         eventCount: sql<number>`count(distinct ${c.eventName})`,
         customEventCount: sql<number>`count(distinct ${c.eventName}) filter (where ${notInArray(c.eventName, [...AUTOMATIC_ANALYTICS_EVENT_NAMES])})`,
+        madeEventCount: sql<number>`count(*) filter (where ${eq(c.eventName, OUTPUT_MADE_EVENT)})`,
         volume: sql<number>`sum(${c.eventCount})`,
       })
       .from(c)
@@ -837,6 +851,7 @@ export async function listEventCatalog(
         description: null,
         automatic: isAutomaticAnalyticsEvent(row.eventName),
         stoppedFiring: false,
+        outputRole: outputEventRole(row.app, row.eventName),
       };
     },
   );
@@ -861,12 +876,17 @@ export async function listEventCatalog(
       app: string;
       eventCount: unknown;
       customEventCount: unknown;
+      madeEventCount: unknown;
       volume: unknown;
     }) => ({
       app: row.app || null,
       eventCount: Number(row.eventCount),
       volume: Number(row.volume),
       onlyAutomaticEvents: Number(row.customEventCount) === 0,
+      makesOutputs: Number(row.madeEventCount) > 0,
+      usedItEvents:
+        outputUseRule(row.app)?.usedEvents.map((event) => event.eventName) ??
+        [],
     }),
   );
 

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

@@ -1,17 +1,5 @@
 import { fail } from "@agent-native/core/action";
-import {
-  and,
-  asc,
-  desc,
-  eq,
-  gte,
-  inArray,
-  lt,
-  lte,
-  ne,
-  or,
-  sql,
-} from "drizzle-orm";
+import { and, desc, eq, gte, inArray, lt, lte, ne, or, sql } from "drizzle-orm";
 import { alias } from "drizzle-orm/pg-core";
 
 import {
@@ -50,7 +38,10 @@ import {
   viewerTenantKeys,
   warnIndexFailure,
 } from "./session-event-index.js";
-import { sessionRecordingAssociationsReady } from "./session-recording-associations.js";
+import {
+  listRecordingSessionAssociations,
+  sessionRecordingAssociationsReady,
+} from "./session-recording-associations.js";
 
 /**
  * Performance aggregates.
@@ -69,7 +60,6 @@ const MAX_ROUTE_LENGTH = 200;
 const MAX_APP_LENGTH = 100;
 const MAX_SAMPLE_WEIGHT = 10_000;
 const SESSION_PERFORMANCE_RETENTION_BUFFER_DAYS = 2;
-const ASSOCIATION_READ_PAGE_SIZE = 500;
 // Leave room for tenant and other filters under PostgreSQL's bind limit.
 const SESSION_PERFORMANCE_SESSION_BATCH_SIZE = 25_000;
 export const ROUTE_PERFORMANCE_RETENTION_DAYS = 180;
@@ -700,30 +690,6 @@ export async function getPerformanceCoverageStart(
   return starts.at(-1) ?? null;
 }
 
-async function recordingSessionAssociations(
-  db: any,
-  recordingIds: readonly string[],
-): Promise<Array<{ recordingId: string; sessionId: string }>> {
-  const association = schema.sessionRecordingSessionAssociations;
-  const result: Array<{ recordingId: string; sessionId: string }> = [];
-  let offset = 0;
-  while (true) {
-    const page = await db
-      .select({
-        recordingId: association.recordingId,
-        sessionId: association.sessionId,
-      })
-      .from(association)
-      .where(inArray(association.recordingId, [...recordingIds]))
-      .orderBy(asc(association.recordingId), asc(association.sessionId))
-      .limit(ASSOCIATION_READ_PAGE_SIZE)
-      .offset(offset);
-    result.push(...page);
-    if (page.length < ASSOCIATION_READ_PAGE_SIZE) return result;
-    offset += page.length;
-  }
-}
-
 function mergePerformanceSummaries(
   first: SessionPerformanceSummary,
   second: SessionPerformanceSummary,
@@ -775,7 +741,7 @@ export async function getSessionPerformanceSummaries(
   const db = getDb() as any;
   if (!(await performanceTablesExist(db))) return summaries;
   const associationRows = (await sessionRecordingAssociationsReady(db))
-    ? await recordingSessionAssociations(
+    ? await listRecordingSessionAssociations(
         db,
         recordings.map((recording) => recording.id),
       )

package/corpus/templates/analytics/server/lib/session-recording-associations.ts

@@ -1,4 +1,8 @@
-import { sql } from "drizzle-orm";
+import { asc, inArray, sql } from "drizzle-orm";
+
+import { schema } from "../db/index.js";
+
+const ASSOCIATION_READ_PAGE_SIZE = 500;
 
 const readyDatabases = new WeakSet<object>();
 
@@ -26,3 +30,28 @@ export async function sessionRecordingAssociationsReady(
   }
   throw new Error("Postgres table existence check returned an invalid value");
 }
+
+/** Every session each recording observed, read in pages. */
+export async function listRecordingSessionAssociations(
+  db: any,
+  recordingIds: readonly string[],
+): Promise<Array<{ recordingId: string; sessionId: string }>> {
+  const association = schema.sessionRecordingSessionAssociations;
+  const result: Array<{ recordingId: string; sessionId: string }> = [];
+  let offset = 0;
+  while (true) {
+    const page = await db
+      .select({
+        recordingId: association.recordingId,
+        sessionId: association.sessionId,
+      })
+      .from(association)
+      .where(inArray(association.recordingId, [...recordingIds]))
+      .orderBy(asc(association.recordingId), asc(association.sessionId))
+      .limit(ASSOCIATION_READ_PAGE_SIZE)
+      .offset(offset);
+    result.push(...page);
+    if (page.length < ASSOCIATION_READ_PAGE_SIZE) return result;
+    offset += page.length;
+  }
+}

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

@@ -0,0 +1,99 @@
+import { getSessionRecordingOutputs } from "./output-outcomes.js";
+import { listRecordingFriction } from "./session-friction.js";
+import {
+  getSessionRecordingPerformance,
+  type SessionRecordingSummary,
+  type SessionReplayScope,
+} from "./session-replay.js";
+import {
+  isSessionsTriageLabEnabled,
+  sessionsTriageReadFailure,
+} from "./sessions-triage-lab.js";
+
+/**
+ * One replay's summary plus what the Sessions triage Lab adds to its page:
+ * friction, speed, and outputs, each replaced by its error when the read
+ * fails. The summary action and `view-screen` both return this, so the agent
+ * reads what the replay page shows.
+ */
+export async function withSessionsTriage(
+  summary: SessionRecordingSummary,
+  scope: SessionReplayScope,
+  logPrefix: string,
+) {
+  let labEnabled: boolean;
+  try {
+    labEnabled = await isSessionsTriageLabEnabled(
+      scope.userEmail,
+      scope.orgId ?? null,
+    );
+  } catch (error) {
+    return {
+      ...summary,
+      labStateError: sessionsTriageReadFailure("labState", logPrefix, error),
+    };
+  }
+  if (!labEnabled) return summary;
+  const [friction, speed, outputs] = await Promise.allSettled([
+    listRecordingFriction(scope, [summary.id]),
+    getSessionRecordingPerformance(scope, [summary.id]),
+    getSessionRecordingOutputs(scope, [summary.id]),
+  ]);
+  const recordingFriction =
+    friction.status === "fulfilled" ? friction.value[summary.id] : undefined;
+  const recordingSpeed =
+    speed.status === "fulfilled"
+      ? speed.value.performance[summary.id]
+      : undefined;
+  const recordingOutputs =
+    outputs.status === "fulfilled"
+      ? outputs.value.outputs[summary.id]
+      : undefined;
+  const omittedOutputs =
+    outputs.status === "fulfilled"
+      ? outputs.value.omittedOutputs[summary.id]
+      : undefined;
+  return {
+    ...summary,
+    ...(friction.status === "rejected"
+      ? {
+          frictionError: sessionsTriageReadFailure(
+            "friction",
+            logPrefix,
+            friction.reason,
+          ),
+        }
+      : recordingFriction
+        ? { friction: recordingFriction }
+        : { frictionError: "Friction read skipped this recording" }),
+    ...(speed.status === "rejected"
+      ? {
+          performanceError: sessionsTriageReadFailure(
+            "speed",
+            logPrefix,
+            speed.reason,
+          ),
+        }
+      : recordingSpeed !== undefined
+        ? {
+            performance: recordingSpeed,
+            performanceCoverageStartedAt: speed.value.coverageStartedAt,
+          }
+        : { performanceError: "Speed read skipped this recording" }),
+    ...(outputs.status === "rejected"
+      ? {
+          outputsError: sessionsTriageReadFailure(
+            "outputs",
+            logPrefix,
+            outputs.reason,
+          ),
+        }
+      : recordingOutputs !== undefined
+        ? {
+            outputs: recordingOutputs,
+            ...(omittedOutputs ? { omittedOutputs } : {}),
+            outputCoverageStartedAt: outputs.value.coverageStartedAt,
+          }
+        : { outputsError: "Outputs read skipped this recording" }),
+  };
+}

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

@@ -42,6 +42,10 @@ import {
   type AnyColumn,
 } from "drizzle-orm";
 
+import type {
+  OutputUseApp,
+  SessionRecordingOutputs,
+} from "../../shared/output-use.js";
 import { isScreenshotSize } from "../../shared/png.js";
 import {
   isSessionFrictionSort,
@@ -66,7 +70,16 @@ import {
 } from "./first-party-analytics.js";
 import { MAX_SESSION_ID_LENGTH } from "./indexed-text.js";
 import type { JourneyRecording, RecordingViewport } from "./journey-tree.js";
+import {
+  getSessionRecordingOutputs,
+  pruneOutputOutcomes,
+  unusedOutputConditions,
+} from "./output-outcomes.js";
 import { canonicalReplayLinkTimestamp } from "./replay-link-timestamp.js";
+import {
+  normalizeReplayOrigin,
+  parseAllowedReplayOrigins,
+} from "./replay-origins.js";
 import { parseIngestBody } from "./request-errors.js";
 import {
   pruneSessionEventIndex,
@@ -161,6 +174,8 @@ export interface SessionReplayListFilters {
   includePerformance?: boolean;
   /** Measured sessions that showed every one of these friction signals. */
   frictionSignals?: SessionFrictionSignal[];
+  /** Sessions that made an output of this app and never used it in time. */
+  unused?: OutputUseApp;
 }
 
 export interface SessionReplayEventReadOptions {
@@ -407,34 +422,6 @@ function replayInteger(value: unknown): number | null {
   return null;
 }
 
-function normalizeReplayOrigin(
-  value: string | null | undefined,
-): string | null {
-  if (!value) return null;
-  try {
-    return new URL(value).origin;
-  } catch {
-    return null;
-  }
-}
-
-function parseAllowedReplayOrigins(value: unknown): string[] {
-  if (Array.isArray(value)) {
-    return value
-      .map((item) => normalizeReplayOrigin(replayString(item)))
-      .filter((item): item is string => Boolean(item));
-  }
-  if (typeof value !== "string" || !value.trim()) return [];
-  try {
-    return parseAllowedReplayOrigins(JSON.parse(value));
-  } catch {
-    return value
-      .split(/[\n,]/)
-      .map((item) => normalizeReplayOrigin(item.trim()))
-      .filter((item): item is string => Boolean(item));
-  }
-}
-
 function positiveReplayLimit(value: unknown, fallback: number): number {
   const parsed = replayInteger(value);
   return parsed && parsed > 0 ? parsed : fallback;
@@ -728,8 +715,15 @@ async function storeReplayChunkBlob(
     ownerEmail: string;
     orgId: string | null;
   },
-): Promise<NormalizedSessionReplayChunk> {
-  if (chunk.storageKind === "blob" || !chunk.inlineData) return chunk;
+): Promise<{
+  chunk: NormalizedSessionReplayChunk;
+  storedBytes: number | null;
+}> {
+  // A blob the client stored itself declares its own size, which the server
+  // never measures, so it reports no stored size.
+  if (chunk.storageKind === "blob" || !chunk.inlineData) {
+    return { chunk, storedBytes: null };
+  }
 
   const gzipBytes = gzipSync(Buffer.from(chunk.inlineData, "utf8"));
   const handle = await putPrivateBlob({
@@ -759,14 +753,17 @@ async function storeReplayChunkBlob(
       );
     }
     warnInlineReplayFallback();
-    return chunk;
+    return { chunk, storedBytes: chunk.byteLength };
   }
 
   return {
-    ...chunk,
-    storageKind: "blob",
-    storageRef: encodeReplayBlobRef(handle),
-    inlineData: null,
+    chunk: {
+      ...chunk,
+      storageKind: "blob",
+      storageRef: encodeReplayBlobRef(handle),
+      inlineData: null,
+    },
+    storedBytes: gzipBytes.byteLength,
   };
 }
 
@@ -1828,12 +1825,21 @@ export async function recordSessionReplayChunks(
       });
     }
   };
+  // The usage row reserves the request's size while chunks upload, so
+  // concurrent ingests see it, then settles at the gzipped bytes actually
+  // stored. Cross-origin uploads arrive uncompressed and would otherwise count
+  // several times what they cost to keep. A gzipped request can settle a
+  // little above its wire size, since each chunk is gzipped on its own. A
+  // request carrying client-stored blobs keeps its reservation, since their
+  // sizes are only what it declares.
+  const reservedBytes = replayIngestByteLength(clampedInput, context);
+  let storedBytes: number | null = 0;
   try {
     await db.insert(schema.sessionReplayIngests).values({
       id: ingestId,
       publicKeyId: key.id,
       recordingId: recording.id,
-      byteLength: replayIngestByteLength(clampedInput, context),
+      byteLength: reservedBytes,
       createdAt: ingestedAt,
       ownerEmail: key.ownerEmail,
       orgId: key.orgId,
@@ -1860,7 +1866,7 @@ export async function recordSessionReplayChunks(
           413,
         );
       }
-      const chunk = await runWithRequestContext(
+      const stored = await runWithRequestContext(
         { userEmail: key.ownerEmail, orgId: key.orgId ?? undefined },
         () =>
           storeReplayChunkBlob(rawChunk, {
@@ -1870,6 +1876,11 @@ export async function recordSessionReplayChunks(
             orgId: key.orgId,
           }),
       );
+      const chunk = stored.chunk;
+      storedBytes =
+        storedBytes === null || stored.storedBytes === null
+          ? null
+          : storedBytes + stored.storedBytes;
       if (rawChunk.storageKind !== "blob" && chunk.storageKind === "blob") {
         const ref = decodeReplayBlobRef(chunk.storageRef);
         if (ref) uploadedBlobHandles.push(ref.handle);
@@ -2060,6 +2071,13 @@ export async function recordSessionReplayChunks(
       }
       errorCount = persistedErrorCount;
       rageClickCount = persistedRageClickCount;
+      const settledBytes = storedBytes ?? reservedBytes;
+      if (settledBytes !== reservedBytes) {
+        await tx
+          .update(schema.sessionReplayIngests)
+          .set({ byteLength: settledBytes })
+          .where(eq(schema.sessionReplayIngests.id, ingestId));
+      }
     });
     uploadedBlobHandles.length = 0;
   } catch (error) {
@@ -2457,6 +2475,13 @@ export interface SessionRecordingPage {
    * performance aggregates began, or null when they have not.
    */
   performanceCoverageStartedAt?: string | null;
+  /**
+   * With an unused-output filter: each row's outputs by recording id, and
+   * when the viewer's output tracking began, or null before it has.
+   */
+  outputs?: SessionRecordingOutputs["outputs"];
+  omittedOutputs?: SessionRecordingOutputs["omittedOutputs"];
+  outputCoverageStartedAt?: string | null;
 }
 
 const personalEmailDomains = [...FREE_EMAIL_PROVIDER_DOMAINS];
@@ -2669,6 +2694,7 @@ export async function listSessionRecordingsPage(
       didNotEvents: filters.didNotEvents,
     })),
     ...(await slowSessionConditions(scope, filters.slow)),
+    ...(await unusedOutputConditions(scope, filters.unused)),
     ...(await sessionFrictionFilterConditions(scope, filters.frictionSignals)),
   );
   const appConditions = [...conditions];
@@ -2747,18 +2773,32 @@ export async function listSessionRecordingsPage(
   const recordings: SessionRecordingSummary[] = rows.map((row: any) =>
     rowToSessionRecordingSummary(row),
   );
-  const performance =
+  const [performance, outputs] = await Promise.all([
     filters.slow || filters.includePerformance
-      ? await sessionRecordingPerformance(scope, recordings, {
+      ? sessionRecordingPerformance(scope, recordings, {
           summaries: filters.includePerformance === true,
         })
-      : null;
+      : null,
+    filters.unused
+      ? getSessionRecordingOutputs(
+          scope,
+          recordings.map((recording) => recording.id),
+        )
+      : null,
+  ]);
   return {
     recordings,
     total,
     ...(performance
       ? { performanceCoverageStartedAt: performance.coverageStartedAt }
       : {}),
+    ...(outputs
+      ? {
+          outputs: outputs.outputs,
+          omittedOutputs: outputs.omittedOutputs,
+          outputCoverageStartedAt: outputs.coverageStartedAt,
+        }
+      : {}),
     appCounts: appRows
       .filter((row: { app: string | null }) => row.app)
       .map((row: { app: string; count: number }) => ({
@@ -3624,6 +3664,11 @@ export async function runSessionReplayRetentionSweep(
   } catch (err) {
     console.warn("[session-replay] Performance aggregate pruning failed:", err);
   }
+  try {
+    await pruneOutputOutcomes(replayRetentionDays(), now);
+  } catch (err) {
+    console.warn("[session-replay] Output outcome pruning failed:", err);
+  }
   return {
     finalized: finalized.finalized,
     expired: expired.expired,

package/corpus/templates/analytics/server/lib/sessions-triage-lab.ts

@@ -17,6 +17,7 @@ const READ_FAILURES = {
   labState: "Couldn't read the Sessions triage Lab state.",
   friction: "Couldn't read session friction.",
   speed: "Couldn't read session speed data.",
+  outputs: "Couldn't read session outputs.",
 } as const;
 
 /**
@@ -33,7 +34,11 @@ export function sessionsTriageReadFailure(
 }
 
 /** What a request asked the Lab for, named in its 403. */
-export type SessionsTriageLabFeature = "events" | "friction" | "speed";
+export type SessionsTriageLabFeature =
+  | "events"
+  | "friction"
+  | "speed"
+  | "outputs";
 
 function labFeatureSubject(
   features: readonly SessionsTriageLabFeature[],
@@ -43,7 +48,8 @@ function labFeatureSubject(
     nouns.length < 3
       ? nouns.join(" and ")
       : `${nouns.slice(0, -1).join(", ")}, and ${nouns[nouns.length - 1]}`;
-  const plural = nouns.length > 1 || nouns[0] === "events";
+  const plural =
+    nouns.length > 1 || nouns[0] === "events" || nouns[0] === "outputs";
   return `Session ${list} ${plural ? "are" : "is"}`;
 }
 

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

@@ -1847,6 +1847,52 @@ CREATE UNIQUE INDEX IF NOT EXISTS dashboard_views_default_per_dashboard_idx
       name: "analytics-content-coverage-config",
       sql: CONTENT_COVERAGE_CONFIG_MIGRATION_SQL,
     },
+    {
+      version: 182,
+      name: "analytics-output-outcomes",
+      sql: {
+        // The coverage table comes last: its existence is how ingest and
+        // reads know the other two exist.
+        postgres: `CREATE TABLE IF NOT EXISTS analytics_output_outcomes (
+      id TEXT PRIMARY KEY,
+      tenant_key TEXT NOT NULL,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      app TEXT NOT NULL,
+      output_type TEXT NOT NULL,
+      output_id TEXT NOT NULL,
+      made_at TEXT,
+      use_by TEXT,
+      made_session_id TEXT,
+      first_used_at TEXT,
+      used_event TEXT,
+      last_seen_at TEXT NOT NULL
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS analytics_output_outcomes_key_idx
+      ON analytics_output_outcomes (tenant_key, app, output_id);
+    CREATE INDEX IF NOT EXISTS analytics_output_outcomes_made_session_idx
+      ON analytics_output_outcomes (tenant_key, made_session_id);
+    CREATE INDEX IF NOT EXISTS analytics_output_outcomes_last_seen_idx
+      ON analytics_output_outcomes (last_seen_at);
+    CREATE TABLE IF NOT EXISTS analytics_output_outcome_gaps (
+      id TEXT PRIMARY KEY,
+      tenant_key TEXT NOT NULL,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      first_at TEXT NOT NULL,
+      last_at TEXT NOT NULL,
+      recorded_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS analytics_output_outcome_gaps_tenant_idx
+      ON analytics_output_outcome_gaps (tenant_key, last_at);
+    CREATE TABLE IF NOT EXISTS analytics_output_outcome_coverage (
+      tenant_key TEXT PRIMARY KEY,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      started_at TEXT NOT NULL
+    )`,
+      },
+    },
   ],
   { table: "analytics_migrations" },
 );