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

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

@@ -0,0 +1,377 @@
+/**
+ * Durable client connection history.
+ *
+ * The event hub writes one row per client subscribe/dispose. Readers
+ * coalesce short reconnects into flaps so a watchdog cycle is not an
+ * outage. Writes are best-effort: a missing or unready database never
+ * throws back into the hub.
+ */
+
+import { and, asc, eq, lt, lte, type SQL } from "drizzle-orm";
+import { v4 as uuid } from "uuid";
+
+import type { InterfaceId } from "../channels/types.js";
+import { getLogger } from "../util/logger.js";
+import type { DrizzleDb } from "./db-connection.js";
+import * as dbConnection from "./db-connection.js";
+import { clientConnectionEvents } from "./schema/index.js";
+
+const log = getLogger("client-connection-events-store");
+
+/** How long a reconnect gap can be and still count as a flap, not an outage. */
+export const CLIENT_CONNECTION_FLAP_WINDOW_MS = 60_000;
+
+/** Rows older than this are deleted on each successful write. */
+export const CLIENT_CONNECTION_EVENT_RETENTION_MS = 90 * 24 * 60 * 60 * 1000;
+
+export const CLIENT_CONNECTION_EVENT_REASONS = [
+  "sse_open",
+  "sse_close",
+  "stale_replaced",
+  "shed_backpressure",
+  "force_disconnect",
+  "cap_evicted",
+] as const;
+
+export type ClientConnectionEventReason =
+  (typeof CLIENT_CONNECTION_EVENT_REASONS)[number];
+
+/** Session-only close when a later open arrives with no recorded close. */
+export type ClientConnectionSessionCloseReason =
+  | ClientConnectionEventReason
+  | "implicit_replaced";
+
+const CLOSE_REASONS = new Set<ClientConnectionEventReason>([
+  "sse_close",
+  "stale_replaced",
+  "shed_backpressure",
+  "force_disconnect",
+  "cap_evicted",
+]);
+
+export interface ClientConnectionEventInput {
+  clientId: string;
+  interfaceId: InterfaceId | string;
+  connectionId: string;
+  reason: ClientConnectionEventReason;
+  occurredAt?: number;
+  actorPrincipalId?: string;
+  clientVersion?: string;
+  sseWatchdog?: boolean;
+  machineName?: string;
+}
+
+export interface ClientConnectionEvent {
+  id: string;
+  clientId: string;
+  interfaceId: string;
+  connectionId: string;
+  reason: ClientConnectionEventReason;
+  occurredAt: number;
+  actorPrincipalId: string | null;
+  clientVersion: string | null;
+  sseWatchdog: boolean | null;
+  machineName: string | null;
+}
+
+export interface ClientConnectionSession {
+  clientId: string;
+  interfaceId: string;
+  startedAt: number;
+  endedAt: number | null;
+  durationMs: number | null;
+  flapCount: number;
+  openReason: ClientConnectionEventReason;
+  closeReason: ClientConnectionSessionCloseReason | null;
+  clientVersion: string | null;
+  sseWatchdog: boolean | null;
+  machineName: string | null;
+  connectionIds: string[];
+}
+
+export interface ListClientConnectionHistoryParams {
+  clientId?: string;
+  interfaceId?: string;
+  actorPrincipalId?: string;
+  since?: number;
+  until?: number;
+  /** Max sessions to return after coalescing. Clamped to 1-500. */
+  limit?: number;
+  now?: number;
+}
+
+export interface ClientConnectionHistory {
+  events: ClientConnectionEvent[];
+  sessions: ClientConnectionSession[];
+}
+
+const DEFAULT_SESSION_LIMIT = 50;
+const MAX_SESSION_LIMIT = 500;
+
+function resolveDb(database?: DrizzleDb): DrizzleDb | null {
+  if (database) {
+    return database;
+  }
+  // Namespace import so a test mock of db-connection that omits `isDbOpen`
+  // still loads. Incomplete mocks skip the probe and try `getDb()`.
+  if (
+    typeof dbConnection.isDbOpen === "function" &&
+    !dbConnection.isDbOpen()
+  ) {
+    return null;
+  }
+  try {
+    return dbConnection.getDb();
+  } catch (err) {
+    log.debug({ err }, "client connection history skipped: database unready");
+    return null;
+  }
+}
+
+function rowToEvent(
+  row: typeof clientConnectionEvents.$inferSelect,
+): ClientConnectionEvent {
+  return {
+    id: row.id,
+    clientId: row.clientId,
+    interfaceId: row.interfaceId,
+    connectionId: row.connectionId,
+    reason: row.reason as ClientConnectionEventReason,
+    occurredAt: row.occurredAt,
+    actorPrincipalId: row.actorPrincipalId ?? null,
+    clientVersion: row.clientVersion ?? null,
+    sseWatchdog: row.sseWatchdog ?? null,
+    machineName: row.machineName ?? null,
+  };
+}
+
+function pruneExpired(db: DrizzleDb, now: number): void {
+  const cutoff = now - CLIENT_CONNECTION_EVENT_RETENTION_MS;
+  db.delete(clientConnectionEvents)
+    .where(lt(clientConnectionEvents.occurredAt, cutoff))
+    .run();
+}
+
+/**
+ * Append one hub lifecycle event. Returns null when the main database is
+ * not open or the write fails. Never throws.
+ */
+export function recordClientConnectionEvent(
+  input: ClientConnectionEventInput,
+  database?: DrizzleDb,
+): ClientConnectionEvent | null {
+  const db = resolveDb(database);
+  if (!db) {
+    return null;
+  }
+  const now = input.occurredAt ?? Date.now();
+  const row = {
+    id: uuid(),
+    clientId: input.clientId,
+    interfaceId: input.interfaceId,
+    connectionId: input.connectionId,
+    reason: input.reason,
+    occurredAt: now,
+    actorPrincipalId: input.actorPrincipalId ?? null,
+    clientVersion: input.clientVersion ?? null,
+    sseWatchdog: input.sseWatchdog ?? null,
+    machineName: input.machineName ?? null,
+  };
+  try {
+    db.insert(clientConnectionEvents).values(row).run();
+    pruneExpired(db, now);
+    return rowToEvent(row);
+  } catch (err) {
+    log.debug({ err }, "failed to record client connection event");
+    return null;
+  }
+}
+
+function clampLimit(limit: number | undefined): number {
+  if (limit == null || !Number.isFinite(limit)) {
+    return DEFAULT_SESSION_LIMIT;
+  }
+  return Math.min(MAX_SESSION_LIMIT, Math.max(1, Math.floor(limit)));
+}
+
+function startSession(event: ClientConnectionEvent): ClientConnectionSession {
+  return {
+    clientId: event.clientId,
+    interfaceId: event.interfaceId,
+    startedAt: event.occurredAt,
+    endedAt: event.reason === "sse_open" ? null : event.occurredAt,
+    durationMs: event.reason === "sse_open" ? null : 0,
+    flapCount: 0,
+    openReason: event.reason,
+    closeReason: event.reason === "sse_open" ? null : event.reason,
+    clientVersion: event.clientVersion,
+    sseWatchdog: event.sseWatchdog,
+    machineName: event.machineName,
+    connectionIds: [event.connectionId],
+  };
+}
+
+/**
+ * Coalesce raw events into sessions. A close followed by an open within
+ * {@link CLIENT_CONNECTION_FLAP_WINDOW_MS} continues the same session and
+ * increments `flapCount`.
+ */
+export function coalesceClientConnectionSessions(
+  events: ClientConnectionEvent[],
+  now: number = Date.now(),
+): ClientConnectionSession[] {
+  const byClient = new Map<string, ClientConnectionEvent[]>();
+  for (const event of events) {
+    const list = byClient.get(event.clientId) ?? [];
+    list.push(event);
+    byClient.set(event.clientId, list);
+  }
+
+  const sessions: ClientConnectionSession[] = [];
+  for (const clientEvents of byClient.values()) {
+    clientEvents.sort((a, b) => a.occurredAt - b.occurredAt);
+    let current: ClientConnectionSession | null = null;
+
+    const finalize = () => {
+      if (!current) {
+        return;
+      }
+      if (current.endedAt == null) {
+        current.durationMs = Math.max(0, now - current.startedAt);
+      } else {
+        current.durationMs = Math.max(0, current.endedAt - current.startedAt);
+      }
+      sessions.push(current);
+      current = null;
+    };
+
+    for (const event of clientEvents) {
+      if (event.reason === "sse_open") {
+        if (
+          current &&
+          current.endedAt != null &&
+          event.occurredAt - current.endedAt < CLIENT_CONNECTION_FLAP_WINDOW_MS
+        ) {
+          current.endedAt = null;
+          current.closeReason = null;
+          current.flapCount += 1;
+          current.connectionIds.push(event.connectionId);
+          current.clientVersion = event.clientVersion ?? current.clientVersion;
+          current.sseWatchdog = event.sseWatchdog ?? current.sseWatchdog;
+          current.machineName = event.machineName ?? current.machineName;
+          continue;
+        }
+        if (current && current.endedAt == null) {
+          current.endedAt = event.occurredAt;
+          current.closeReason = "implicit_replaced";
+        }
+        finalize();
+        current = startSession(event);
+        continue;
+      }
+
+      if (!CLOSE_REASONS.has(event.reason)) {
+        continue;
+      }
+
+      if (!current) {
+        current = startSession(event);
+        continue;
+      }
+
+      current.endedAt = event.occurredAt;
+      current.closeReason = event.reason;
+      if (!current.connectionIds.includes(event.connectionId)) {
+        current.connectionIds.push(event.connectionId);
+      }
+    }
+    finalize();
+  }
+
+  sessions.sort((a, b) => b.startedAt - a.startedAt);
+  return sessions;
+}
+
+/**
+ * Read raw events and coalesced sessions. Returns empty lists when the
+ * database is not open.
+ */
+export function listClientConnectionHistory(
+  params: ListClientConnectionHistoryParams = {},
+  database?: DrizzleDb,
+): ClientConnectionHistory {
+  const db = resolveDb(database);
+  if (!db) {
+    return { events: [], sessions: [] };
+  }
+
+  const now = params.now ?? Date.now();
+  const limit = clampLimit(params.limit);
+  const filters: SQL[] = [];
+  if (params.clientId) {
+    filters.push(eq(clientConnectionEvents.clientId, params.clientId));
+  }
+  if (params.interfaceId) {
+    filters.push(eq(clientConnectionEvents.interfaceId, params.interfaceId));
+  }
+  if (params.actorPrincipalId) {
+    filters.push(
+      eq(clientConnectionEvents.actorPrincipalId, params.actorPrincipalId),
+    );
+  }
+  if (params.until != null) {
+    filters.push(lte(clientConnectionEvents.occurredAt, params.until));
+  }
+
+  try {
+    const query = db
+      .select()
+      .from(clientConnectionEvents)
+      .orderBy(asc(clientConnectionEvents.occurredAt));
+    const rows =
+      filters.length > 0 ? query.where(and(...filters)).all() : query.all();
+    const events = rows.map(rowToEvent);
+    const sessions = coalesceClientConnectionSessions(events, now)
+      .filter((session) => {
+        return sessionOverlapsWindow(session, params.since, params.until);
+      })
+      .slice(0, limit);
+    return {
+      events: events.filter((event) => {
+        return eventInWindow(event, params.since, params.until);
+      }),
+      sessions,
+    };
+  } catch (err) {
+    log.debug({ err }, "failed to list client connection history");
+    return { events: [], sessions: [] };
+  }
+}
+
+function sessionOverlapsWindow(
+  session: ClientConnectionSession,
+  since?: number,
+  until?: number,
+): boolean {
+  if (since != null && session.endedAt != null && session.endedAt < since) {
+    return false;
+  }
+  if (until != null && session.startedAt > until) {
+    return false;
+  }
+  return true;
+}
+
+function eventInWindow(
+  event: ClientConnectionEvent,
+  since?: number,
+  until?: number,
+): boolean {
+  if (since != null && event.occurredAt < since) {
+    return false;
+  }
+  if (until != null && event.occurredAt > until) {
+    return false;
+  }
+  return true;
+}

package/src/persistence/conversation-crud.ts

@@ -1,5 +1,6 @@
 import { mkdirSync, rmSync } from "node:fs";
 
+import { TrustClassSchema } from "@vellumai/gateway-client";
 import {
   and,
   asc,
@@ -26,6 +27,7 @@ import {
   forgetActivationConversation,
   forgetAllActivationConversations,
 } from "../activation/progress-store.js";
+import { TolerantModeSessionSchema } from "../api/mode-session.js";
 import type { ChannelId, InterfaceId } from "../channels/types.js";
 import { parseChannelId, parseInterfaceId } from "../channels/types.js";
 import { CHANNEL_IDS, isChannelId } from "../channels/types.js";
@@ -47,7 +49,6 @@ import { runHook } from "../plugins/pipeline.js";
 import type { ContentBlock } from "../providers/types.js";
 import { getCurrentSeq } from "../runtime/assistant-stream-state.js";
 import { publishSyncInvalidation } from "../runtime/sync/sync-publisher.js";
-import { trustClassSchema } from "../runtime/trust-class.js";
 import { UserError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 import { getLogsDbPath } from "../util/logs-db-path.js";
@@ -91,6 +92,7 @@ import {
   REFERENTIAL_FORK_STRATEGY,
   resolveConversationLineage,
 } from "./conversation-lineage.js";
+import { repairConversationModeSessionBoundaries } from "./conversation-mode-sessions.js";
 import { deleteConversationRowsInBatches } from "./conversation-row-batch-delete.js";
 import {
   BACKGROUND_CONVERSATION_TYPES,
@@ -333,6 +335,8 @@ const backgroundToolCompletionMetadataSchema = z.object({
 
 export const messageMetadataSchema = z
   .object({
+    /** Immutable ownership of this transcript row by a recorded mode session. */
+    modeSession: TolerantModeSessionSchema,
     /**
      * Epoch ms the content actually happened, when that differs from when
      * the row was written. Set wherever persistence lags the event: a queued
@@ -383,7 +387,7 @@ export const messageMetadataSchema = z
      * trust status changes later. Used by the memory write gate (indexer)
      * and read gate (conversation history loading) to enforce trust-aware access.
      */
-    provenanceTrustClass: trustClassSchema.optional(),
+    provenanceTrustClass: TrustClassSchema.optional(),
     /**
      * Model that actually served this assistant row, carried on the agent
      * loop's `message_complete` event (the provider's `response.model`, the
@@ -398,6 +402,22 @@ export const messageMetadataSchema = z
     provenanceSourceChannel: channelIdSchema.optional(),
     provenanceGuardianExternalUserId: z.string().optional(),
     provenanceRequesterIdentifier: z.string().optional(),
+    /**
+     * Contact id of the person who wrote this row, from the gateway trust
+     * verdict at persist time. Stamped only on a person's own message or
+     * reaction (`actorAuthorProvenance`), never on rows the assistant writes
+     * during their turn: the other `provenance*` fields describe the turn,
+     * this one the author. Absent when the author resolved to no contact.
+     */
+    provenanceContactId: z.string().optional(),
+    /**
+     * Set on a backfilled row whose sender was looked up but no usable gateway
+     * verdict came back, so its trust class is the guardian-address fallback
+     * and it names no author. Distinguishes that row from a sender the gateway
+     * resolved as a stranger, so the lookup can be re-run later. Live ingress
+     * never persists such a row: it denies a turn whose verdict failed.
+     */
+    provenanceLookupFailed: z.boolean().optional(),
     automated: z.boolean().optional(),
     /**
      * Transcript-suppression flag: the row is a machine signal (e.g. the
@@ -469,10 +489,10 @@ export const messageMetadataSchema = z
      */
     attachmentStoredPaths: z.record(z.string(), z.string()).optional(),
     /**
-     * Marks a role-`"user"` row whose arrival interrupted a turn that had made
-     * no tool call yet. `loadFromDb` rebuilds the LLM-facing
-     * `<interrupted_turn>` note from it; the row's own content is exactly what
-     * the user sent, so clients render nothing extra.
+     * Marks a role-`"user"` row whose arrival interrupted a running turn.
+     * `loadFromDb` rebuilds the LLM-facing `<interrupted_turn>` note from it;
+     * the row's own content is exactly what the user sent, so clients render
+     * nothing extra.
      */
     interruptedPriorTurn: z.boolean().optional(),
     memoryInjectedBlock: z.string().optional(),
@@ -577,6 +597,12 @@ export function isProviderErrorMetadata(
  * assistant rows, and turn grouping closes on them, so display merging and
  * the turn resolver agree on boundaries. Takes the raw persisted `metadata`
  * JSON string; malformed JSON and non-assistant roles are never standalone.
+ *
+ * The web folds adjacent assistant rows again after pagination and reads the
+ * same rule off the wire projection in its own `isStandaloneAssistantMessage`
+ * (clients/web/src/domains/chat/utils/is-standalone-assistant-message.ts). A
+ * kind added here without a matching flag and check there merges on the
+ * client anyway.
  */
 export function isStandaloneAssistantMessage(
   role: string,
@@ -4337,6 +4363,24 @@ export function purgeConversationSegments(
   return segmentIds;
 }
 
+/** Repair derived mode-session boundaries without changing delete success. */
+function repairModeSessionBoundariesAfterDelete(conversationId: string): void {
+  const maxAttempts = 2;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      repairConversationModeSessionBoundaries(conversationId);
+      return;
+    } catch (err) {
+      if (attempt === maxAttempts) {
+        log.warn(
+          { err, conversationId, attempts: maxAttempts },
+          "Failed to repair mode session boundaries after message deletion; continuing",
+        );
+      }
+    }
+  }
+}
+
 export function deleteLastExchange(conversationId: string): number {
   const db = getDb();
 
@@ -4441,6 +4485,10 @@ export function deleteLastExchange(conversationId: string): number {
     } satisfies MessageDeletedInputContext);
   }
 
+  if (deleted > 0) {
+    repairModeSessionBoundariesAfterDelete(conversationId);
+  }
+
   return deleted;
 }
 
@@ -4751,6 +4799,7 @@ export function deleteMessageById(
       messageId,
       createdAt: msgRow.createdAt,
     } satisfies MessageDeletedInputContext);
+    repairModeSessionBoundariesAfterDelete(msgRow.conversationId);
   }
 
   return result;