@vellumai/assistant 0.12.3-staging.1 → 0.12.3-staging.2

package/src/oauth/seed-providers.ts

@@ -1,3 +1,5 @@
+import type { IntegrationCategory } from "@vellumai/service-contracts/integration-categories";
+
 import type { AvailableScopes } from "./connect-types.js";
 import { migrateProviderBaseUrl, seedProviders } from "./oauth-store.js";
 
@@ -78,6 +80,8 @@ export const PROVIDER_SEED_DATA: Record<
     managedServiceIsPaid?: boolean;
     displayLabel: string;
     description: string;
+    /** Where the integrations catalog files this provider. */
+    category: IntegrationCategory;
     dashboardUrl: string | null;
     clientIdPlaceholder: string | null;
     requiresClientSecret?: boolean;
@@ -132,6 +136,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://www.googleapis.com",
     displayLabel: "Google",
     description: "Gmail, Calendar, Drive, Docs, Sheets, Slides, and Contacts",
+    category: "productivity",
     dashboardUrl: "https://console.cloud.google.com/apis/credentials",
     clientIdPlaceholder: "123456789.apps.googleusercontent.com",
     logoUrl: "https://cdn.simpleicons.org/google",
@@ -218,6 +223,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://slack.com/api",
     displayLabel: "Slack",
     description: "Workspace messaging",
+    category: "communication",
     dashboardUrl: "https://api.slack.com/apps",
     clientIdPlaceholder: null,
     logoUrl:
@@ -278,6 +284,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.notion.com",
     displayLabel: "Notion",
     description: "Pages and databases",
+    category: "productivity",
     dashboardUrl: "https://www.notion.so/my-integrations",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/notion",
@@ -312,6 +319,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.x.com",
     displayLabel: "Twitter",
     description: "Posts and direct messages",
+    category: "communication",
     dashboardUrl: "https://developer.twitter.com/en/portal/dashboard",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/x",
@@ -357,6 +365,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.github.com",
     displayLabel: "GitHub",
     description: "Repositories and issues",
+    category: "engineering",
     dashboardUrl: "https://github.com/settings/developers",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/github",
@@ -390,6 +399,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.linear.app",
     displayLabel: "Linear",
     description: "Issues and projects",
+    category: "engineering",
     dashboardUrl: "https://linear.app/settings/api",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/linear",
@@ -438,6 +448,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.spotify.com/v1",
     displayLabel: "Spotify",
     description: "Music and playlists",
+    category: "productivity",
     dashboardUrl: "https://developer.spotify.com/dashboard",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/spotify",
@@ -477,6 +488,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.todoist.com/rest/v2",
     displayLabel: "Todoist",
     description: "Tasks and projects",
+    category: "productivity",
     dashboardUrl: "https://developer.todoist.com/appconsole.html",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/todoist",
@@ -523,6 +535,7 @@ export const PROVIDER_SEED_DATA: Record<
     // documents `messages.read` as local RPC only, so requesting it would put
     // a permission on the consent screen that grants nothing here.
     description: "Your servers and profile",
+    category: "communication",
     dashboardUrl: "https://discord.com/developers/applications",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/discord",
@@ -553,6 +566,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.dropboxapi.com/2",
     displayLabel: "Dropbox",
     description: "Files and folders",
+    category: "productivity",
     dashboardUrl: "https://www.dropbox.com/developers/apps",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/dropbox",
@@ -593,6 +607,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://app.asana.com/api/1.0",
     displayLabel: "Asana",
     description: "Tasks and projects",
+    category: "productivity",
     dashboardUrl: "https://app.asana.com/0/my-apps",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/asana",
@@ -621,6 +636,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.airtable.com/v0",
     displayLabel: "Airtable",
     description: "Bases and records",
+    category: "productivity",
     dashboardUrl: "https://airtable.com/create/tokens",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/airtable",
@@ -653,6 +669,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.hubapi.com",
     displayLabel: "HubSpot",
     description: "CRM contacts and deals",
+    category: "sales",
     dashboardUrl: "https://developers.hubspot.com/",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/hubspot",
@@ -696,6 +713,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://login.salesforce.com",
     displayLabel: "Salesforce",
     description: "CRM contacts, leads, and opportunities",
+    category: "sales",
     dashboardUrl:
       "https://help.salesforce.com/s/articleView?id=sf.connected_app_create.htm&type=5",
     clientIdPlaceholder: null,
@@ -744,6 +762,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.monday.com",
     displayLabel: "monday.com",
     description: "Boards, items, docs, and updates",
+    category: "productivity",
     dashboardUrl: "https://auth.monday.com/apps",
     clientIdPlaceholder: null,
     // Simple Icons does not host a monday.com mark (both `monday` and
@@ -868,6 +887,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://www.eventbriteapi.com",
     displayLabel: "Eventbrite",
     description: "Events, attendees, and ticket orders",
+    category: "commerce",
     dashboardUrl: "https://www.eventbrite.com/platform/api-keys/",
     clientIdPlaceholder: null,
     // Simple Icons does not host an Eventbrite mark (cdn.simpleicons.org
@@ -904,6 +924,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.calendly.com",
     displayLabel: "Calendly",
     description: "Scheduling links and meetings",
+    category: "meetings",
     dashboardUrl: "https://calendly.com/integrations/api_webhooks",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/calendly",
@@ -1003,6 +1024,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.figma.com/v1",
     displayLabel: "Figma",
     description: "Design files and comments",
+    category: "engineering",
     dashboardUrl: "https://www.figma.com/developers/apps",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/figma",
@@ -1178,6 +1200,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://graph.microsoft.com",
     displayLabel: "Outlook / Microsoft",
     description: "Email and calendar",
+    category: "productivity",
     dashboardUrl:
       "https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade",
     clientIdPlaceholder: "Application (client) ID from Azure portal",
@@ -1236,6 +1259,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://slack.com/api",
     displayLabel: "Slack Channel",
     description: "Channel bot token",
+    category: "communication",
     dashboardUrl: null,
     clientIdPlaceholder: null,
     requiresClientSecret: false,
@@ -1259,6 +1283,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://discord.com/api/v10",
     displayLabel: "Discord Server",
     description: "A bot in your server",
+    category: "communication",
     dashboardUrl: "https://discord.com/developers/applications",
     clientIdPlaceholder: null,
     requiresClientSecret: false,
@@ -1281,6 +1306,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.telegram.org",
     displayLabel: "Telegram",
     description: "Bot messaging",
+    category: "communication",
     dashboardUrl: null,
     clientIdPlaceholder: null,
     requiresClientSecret: false,
@@ -1295,6 +1321,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.sanity.io",
     displayLabel: "Sanity",
     description: "Content management platform",
+    category: "marketing",
     dashboardUrl: "https://www.sanity.io/manage",
     clientIdPlaceholder: null,
     requiresClientSecret: false,
@@ -1323,6 +1350,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://api.link.com",
     displayLabel: "Link by Stripe",
     description: "Wallet payment methods for agent purchases",
+    category: "commerce",
     dashboardUrl: "https://dashboard.stripe.com",
     // Link issues OAuth clients by request rather than through a self-serve
     // dashboard, so there is no placeholder shape to suggest.
@@ -1386,6 +1414,7 @@ export const PROVIDER_SEED_DATA: Record<
     baseUrl: "https://{tenant_host}",
     displayLabel: "Shopify",
     description: "Products, orders, customers, and inventory",
+    category: "commerce",
     dashboardUrl: "https://shopify.dev/dashboard",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/shopify",
@@ -1611,6 +1640,7 @@ export const PROVIDER_SEED_DATA: Record<
     // managed sandbox connection to the production host).
     displayLabel: "QuickBooks",
     description: "Invoices, customers, vendors, and accounting data",
+    category: "finance",
     dashboardUrl: "https://developer.intuit.com/app/developer/dashboard",
     clientIdPlaceholder: null,
     logoUrl: "https://cdn.simpleicons.org/quickbooks",

package/src/onboarding/onboarding-events-store.ts

@@ -11,6 +11,12 @@ import {
   type LiveVoiceSessionOutcome,
   type LiveVoiceStepName,
 } from "../telemetry/live-voice-funnel.js";
+import {
+  PHONE_CALL_FUNNEL_VERSION,
+  PHONE_CALL_STEPS,
+  type PhoneCallOutcome,
+  type PhoneCallStepName,
+} from "../telemetry/phone-call-funnel.js";
 import { recordTelemetryOutboxEvent } from "../telemetry/telemetry-events-outbox.js";
 import type { OnboardingTelemetryEvent } from "../telemetry/types.js";
 import { getLogger } from "../util/logger.js";
@@ -136,12 +142,13 @@ export function recordActivationEvent(params: {
  * database is unavailable.
  *
  * **Never throws.** These fire from `LiveVoiceSession.start()` and `.close()`,
- * which are the user's call itself: the outbox insert raises on a telemetry DB
- * that is missing, locked, or mid-migration, and an uncaught raise there would
- * fail the session rather than the measurement. A dropped row costs a gap in a
- * chart; a raised one costs the user their conversation.
+ * and from the call store's create and status writes, which are the user's
+ * call itself: the outbox insert raises on a telemetry DB that is missing,
+ * locked, or mid-migration, and an uncaught raise there would fail the session
+ * rather than the measurement. A dropped row costs a gap in a chart; a raised
+ * one costs the user their conversation.
  */
-function recordLiveVoiceEventSafely(
+function recordVoiceFunnelEventSafely(
   record: () => OnboardingEvent | null,
 ): OnboardingEvent | null {
   try {
@@ -155,28 +162,51 @@ function recordLiveVoiceEventSafely(
   }
 }
 
-export function recordLiveVoiceSessionEvent(params: {
-  stepName: LiveVoiceStepName;
+/**
+ * Build one voice funnel row. The live-voice and phone-call funnels differ
+ * only in their version stamp and step vocabulary, so they share the row
+ * shape: same substrate, same session-keyed pairing, same duration math.
+ */
+function recordVoiceFunnelEvent(params: {
+  funnelVersion: string;
+  stepName: string;
   stepIndex: number;
   sessionId: string;
-  screen?: string;
-  outcome?: LiveVoiceSessionOutcome;
+  screen: string;
+  outcome?: string;
 }): OnboardingEvent | null {
-  return recordLiveVoiceEventSafely(() =>
+  return recordVoiceFunnelEventSafely(() =>
     recordTelemetryOutboxEvent("onboarding", (id, createdAt) =>
       buildOnboardingTelemetryEvent(id, createdAt, {
-        screen: params.screen ?? params.stepName,
+        screen: params.screen,
         sessionId: params.sessionId,
         stepName: params.stepName,
         stepIndex: params.stepIndex,
         completedAt: new Date(createdAt).toISOString(),
-        funnelVersion: LIVE_VOICE_FUNNEL_VERSION,
+        funnelVersion: params.funnelVersion,
         ...(params.outcome ? { outcome: params.outcome } : {}),
       }),
     ),
   );
 }
 
+export function recordLiveVoiceSessionEvent(params: {
+  stepName: LiveVoiceStepName;
+  stepIndex: number;
+  sessionId: string;
+  screen?: string;
+  outcome?: LiveVoiceSessionOutcome;
+}): OnboardingEvent | null {
+  return recordVoiceFunnelEvent({
+    funnelVersion: LIVE_VOICE_FUNNEL_VERSION,
+    stepName: params.stepName,
+    stepIndex: params.stepIndex,
+    sessionId: params.sessionId,
+    screen: params.screen ?? params.stepName,
+    ...(params.outcome ? { outcome: params.outcome } : {}),
+  });
+}
+
 /**
  * Record the "a live-voice session was attempted" milestone, with where it
  * was attempted from.
@@ -207,3 +237,60 @@ export function recordLiveVoiceSessionEnded(params: {
     outcome: params.outcome,
   });
 }
+
+/**
+ * Record a phone-call milestone (started / ended) on the same substrate as the
+ * live-voice pair, keyed by the call session id so the two events pair up
+ * downstream. See `telemetry/phone-call-funnel.ts` for why duration and turn
+ * count are derived from that pairing rather than carried as fields.
+ *
+ * Returns null when usage data collection is disabled or the telemetry
+ * database is unavailable, and never throws: these fire from the call store's
+ * writes, on the call's own path.
+ */
+function recordPhoneCallEvent(params: {
+  stepName: PhoneCallStepName;
+  stepIndex: number;
+  callSessionId: string;
+  screen: string;
+  outcome?: PhoneCallOutcome;
+}): OnboardingEvent | null {
+  return recordVoiceFunnelEvent({
+    funnelVersion: PHONE_CALL_FUNNEL_VERSION,
+    stepName: params.stepName,
+    stepIndex: params.stepIndex,
+    sessionId: params.callSessionId,
+    screen: params.screen,
+    ...(params.outcome ? { outcome: params.outcome } : {}),
+  });
+}
+
+/**
+ * Record the "a phone call was attempted" milestone, with how it was placed.
+ */
+export function recordPhoneCallStarted(params: {
+  callSessionId: string;
+  screen: string;
+}): OnboardingEvent | null {
+  return recordPhoneCallEvent({
+    stepName: PHONE_CALL_STEPS.callStarted.stepName,
+    stepIndex: PHONE_CALL_STEPS.callStarted.stepIndex,
+    callSessionId: params.callSessionId,
+    screen: params.screen,
+  });
+}
+
+/** Record the "a phone call ended" milestone, with how it ended. */
+export function recordPhoneCallEnded(params: {
+  callSessionId: string;
+  screen: string;
+  outcome: PhoneCallOutcome;
+}): OnboardingEvent | null {
+  return recordPhoneCallEvent({
+    stepName: PHONE_CALL_STEPS.callEnded.stepName,
+    stepIndex: PHONE_CALL_STEPS.callEnded.stepIndex,
+    callSessionId: params.callSessionId,
+    screen: params.screen,
+    outcome: params.outcome,
+  });
+}

package/src/persistence/__tests__/client-connection-events-store.test.ts

@@ -0,0 +1,322 @@
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import {
+  CLIENT_CONNECTION_EVENT_RETENTION_MS,
+  CLIENT_CONNECTION_FLAP_WINDOW_MS,
+  type ClientConnectionEvent,
+  coalesceClientConnectionSessions,
+  listClientConnectionHistory,
+  recordClientConnectionEvent,
+} from "../client-connection-events-store.js";
+import { migrateCreateClientConnectionEvents } from "../migrations/382-create-client-connection-events.js";
+import * as schema from "../schema.js";
+
+function createTestDb() {
+  const sqlite = new Database(":memory:");
+  sqlite.exec("PRAGMA journal_mode=WAL");
+  const db = drizzle(sqlite, { schema });
+  migrateCreateClientConnectionEvents(db);
+  return db;
+}
+
+function event(
+  overrides: Partial<ClientConnectionEvent> &
+    Pick<ClientConnectionEvent, "reason" | "occurredAt">,
+): ClientConnectionEvent {
+  return {
+    id: overrides.id ?? `evt-${overrides.occurredAt}`,
+    clientId: overrides.clientId ?? "client-123",
+    interfaceId: overrides.interfaceId ?? "chrome-extension",
+    connectionId: overrides.connectionId ?? `conn-${overrides.occurredAt}`,
+    reason: overrides.reason,
+    occurredAt: overrides.occurredAt,
+    actorPrincipalId: overrides.actorPrincipalId ?? "user-123",
+    clientVersion: overrides.clientVersion ?? "0.12.1",
+    sseWatchdog: overrides.sseWatchdog ?? true,
+    machineName: overrides.machineName ?? null,
+  };
+}
+
+describe("coalesceClientConnectionSessions", () => {
+  test("merges a reconnect shorter than the flap window", () => {
+    const sessions = coalesceClientConnectionSessions(
+      [
+        event({
+          reason: "sse_open",
+          occurredAt: 1_000,
+          connectionId: "conn-1",
+        }),
+        event({
+          reason: "stale_replaced",
+          occurredAt: 2_000,
+          connectionId: "conn-1",
+        }),
+        event({
+          reason: "sse_open",
+          occurredAt: 2_000 + CLIENT_CONNECTION_FLAP_WINDOW_MS - 1,
+          connectionId: "conn-2",
+        }),
+      ],
+      10_000 + CLIENT_CONNECTION_FLAP_WINDOW_MS,
+    );
+
+    expect(sessions).toHaveLength(1);
+    expect(sessions[0].flapCount).toBe(1);
+    expect(sessions[0].endedAt).toBeNull();
+    expect(sessions[0].connectionIds).toHaveLength(2);
+  });
+
+  test("keeps a gap at or beyond the flap window as a separate session", () => {
+    const sessions = coalesceClientConnectionSessions([
+      event({ reason: "sse_open", occurredAt: 1_000 }),
+      event({ reason: "sse_close", occurredAt: 2_000 }),
+      event({
+        reason: "sse_open",
+        occurredAt: 2_000 + CLIENT_CONNECTION_FLAP_WINDOW_MS,
+      }),
+    ]);
+
+    expect(sessions).toHaveLength(2);
+    expect(sessions.every((session) => session.flapCount === 0)).toBe(true);
+  });
+
+  test("leaves an unmatched open as a still-connected session", () => {
+    const now = 8_000;
+    const sessions = coalesceClientConnectionSessions(
+      [event({ reason: "sse_open", occurredAt: 1_000 })],
+      now,
+    );
+
+    expect(sessions).toHaveLength(1);
+    expect(sessions[0].endedAt).toBeNull();
+    expect(sessions[0].durationMs).toBe(7_000);
+    expect(sessions[0].closeReason).toBeNull();
+  });
+
+  test("ends an orphaned open when a later open arrives with no close", () => {
+    const sessions = coalesceClientConnectionSessions(
+      [
+        event({
+          reason: "sse_open",
+          occurredAt: 1_000,
+          connectionId: "conn-1",
+        }),
+        event({
+          reason: "sse_open",
+          occurredAt: 5_000,
+          connectionId: "conn-2",
+        }),
+      ],
+      8_000,
+    );
+
+    expect(sessions).toHaveLength(2);
+    expect(sessions[1].startedAt).toBe(1_000);
+    expect(sessions[1].endedAt).toBe(5_000);
+    expect(sessions[1].closeReason).toBe("implicit_replaced");
+    expect(sessions[1].durationMs).toBe(4_000);
+    expect(sessions[0].startedAt).toBe(5_000);
+    expect(sessions[0].endedAt).toBeNull();
+    expect(sessions[0].durationMs).toBe(3_000);
+  });
+});
+
+describe("recordClientConnectionEvent / listClientConnectionHistory", () => {
+  test("writes events and returns coalesced sessions", () => {
+    const db = createTestDb();
+    const t0 = 1_700_000_000_000;
+
+    recordClientConnectionEvent(
+      {
+        clientId: "client-123",
+        interfaceId: "chrome-extension",
+        connectionId: "conn-1",
+        reason: "sse_open",
+        occurredAt: t0,
+        actorPrincipalId: "user-123",
+        clientVersion: "0.12.1",
+        sseWatchdog: true,
+      },
+      db,
+    );
+    recordClientConnectionEvent(
+      {
+        clientId: "client-123",
+        interfaceId: "chrome-extension",
+        connectionId: "conn-1",
+        reason: "stale_replaced",
+        occurredAt: t0 + 5_000,
+        actorPrincipalId: "user-123",
+      },
+      db,
+    );
+    recordClientConnectionEvent(
+      {
+        clientId: "client-123",
+        interfaceId: "chrome-extension",
+        connectionId: "conn-2",
+        reason: "sse_open",
+        occurredAt: t0 + 6_000,
+        actorPrincipalId: "user-123",
+        clientVersion: "0.12.1",
+        sseWatchdog: true,
+      },
+      db,
+    );
+
+    const history = listClientConnectionHistory(
+      { clientId: "client-123", now: t0 + 10_000 },
+      db,
+    );
+
+    expect(history.events).toHaveLength(3);
+    expect(history.sessions).toHaveLength(1);
+    expect(history.sessions[0].flapCount).toBe(1);
+    expect(history.sessions[0].endedAt).toBeNull();
+    expect(history.sessions[0].sseWatchdog).toBe(true);
+    expect(history.sessions[0].clientVersion).toBe("0.12.1");
+  });
+
+  test("prunes rows older than the retention window", () => {
+    const db = createTestDb();
+    const now = 1_700_000_000_000;
+
+    recordClientConnectionEvent(
+      {
+        clientId: "client-123",
+        interfaceId: "chrome-extension",
+        connectionId: "conn-old",
+        reason: "sse_open",
+        occurredAt: now - CLIENT_CONNECTION_EVENT_RETENTION_MS - 1,
+      },
+      db,
+    );
+    recordClientConnectionEvent(
+      {
+        clientId: "client-123",
+        interfaceId: "chrome-extension",
+        connectionId: "conn-new",
+        reason: "sse_open",
+        occurredAt: now,
+      },
+      db,
+    );
+
+    const history = listClientConnectionHistory({ now }, db);
+    expect(history.events).toHaveLength(1);
+    expect(history.events[0].connectionId).toBe("conn-new");
+  });
+
+  test("does not throw when listing without an injected database", () => {
+    const history = listClientConnectionHistory();
+    expect(Array.isArray(history.events)).toBe(true);
+    expect(Array.isArray(history.sessions)).toBe(true);
+  });
+
+  test("preserves a session that opened before the since bound", () => {
+    const db = createTestDb();
+    const t0 = 1_700_000_000_000;
+
+    recordClientConnectionEvent(
+      {
+        clientId: "client-123",
+        interfaceId: "chrome-extension",
+        connectionId: "conn-1",
+        reason: "sse_open",
+        occurredAt: t0,
+        actorPrincipalId: "user-123",
+      },
+      db,
+    );
+    recordClientConnectionEvent(
+      {
+        clientId: "client-123",
+        interfaceId: "chrome-extension",
+        connectionId: "conn-1",
+        reason: "sse_close",
+        occurredAt: t0 + 8_000,
+        actorPrincipalId: "user-123",
+      },
+      db,
+    );
+
+    const history = listClientConnectionHistory(
+      { clientId: "client-123", since: t0 + 5_000, now: t0 + 10_000 },
+      db,
+    );
+
+    expect(history.sessions).toHaveLength(1);
+    expect(history.sessions[0].startedAt).toBe(t0);
+    expect(history.sessions[0].endedAt).toBe(t0 + 8_000);
+    expect(history.sessions[0].durationMs).toBe(8_000);
+    expect(history.events).toHaveLength(1);
+    expect(history.events[0].reason).toBe("sse_close");
+  });
+
+  test("keeps a still-open session whose only event is before since", () => {
+    const db = createTestDb();
+    const t0 = 1_700_000_000_000;
+
+    recordClientConnectionEvent(
+      {
+        clientId: "client-123",
+        interfaceId: "chrome-extension",
+        connectionId: "conn-1",
+        reason: "sse_open",
+        occurredAt: t0,
+        actorPrincipalId: "user-123",
+      },
+      db,
+    );
+
+    const history = listClientConnectionHistory(
+      { clientId: "client-123", since: t0 + 5_000, now: t0 + 10_000 },
+      db,
+    );
+
+    expect(history.sessions).toHaveLength(1);
+    expect(history.sessions[0].startedAt).toBe(t0);
+    expect(history.sessions[0].endedAt).toBeNull();
+    expect(history.sessions[0].durationMs).toBe(10_000);
+    expect(history.events).toHaveLength(0);
+  });
+
+  test("omits a session that ended before the since bound", () => {
+    const db = createTestDb();
+    const t0 = 1_700_000_000_000;
+
+    recordClientConnectionEvent(
+      {
+        clientId: "client-123",
+        interfaceId: "chrome-extension",
+        connectionId: "conn-old",
+        reason: "sse_open",
+        occurredAt: t0,
+        actorPrincipalId: "user-123",
+      },
+      db,
+    );
+    recordClientConnectionEvent(
+      {
+        clientId: "client-123",
+        interfaceId: "chrome-extension",
+        connectionId: "conn-old",
+        reason: "sse_close",
+        occurredAt: t0 + 1_000,
+        actorPrincipalId: "user-123",
+      },
+      db,
+    );
+
+    const history = listClientConnectionHistory(
+      { clientId: "client-123", since: t0 + 5_000, now: t0 + 10_000 },
+      db,
+    );
+
+    expect(history.sessions).toHaveLength(0);
+    expect(history.events).toHaveLength(0);
+  });
+});