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

package/src/persistence/conversation-mode-sessions.ts

@@ -0,0 +1,460 @@
+import { and, asc, eq, inArray, sql } from "drizzle-orm";
+
+import {
+  type ModeSessionMode,
+  modeSessionRowStartsDisplay,
+  type ModeSessionStatus,
+  type ModeSessionSummary,
+  ModeSessionSummarySchema,
+} from "../api/mode-session.js";
+import { type DrizzleDb, getDb } from "./db-connection.js";
+import {
+  readMessageSentAt,
+  readModeSessionMetadata,
+} from "./message-metadata.js";
+import { conversationModeSessions, messages } from "./schema/index.js";
+
+export type ModeSessionWriteFailureReason =
+  | "already_exists"
+  | "not_found"
+  | "stale_revision"
+  | "terminal";
+
+export type ModeSessionWriteResult =
+  | { ok: true; session: ModeSessionSummary }
+  | {
+      ok: false;
+      reason: ModeSessionWriteFailureReason;
+      session?: ModeSessionSummary;
+    };
+
+export interface ModeSessionStoreOptions {
+  db?: DrizzleDb;
+}
+
+type ModeSessionReader = Pick<DrizzleDb, "select">;
+
+interface ModeSessionMutationOptions extends ModeSessionStoreOptions {
+  acceptTerminal?: (
+    current: typeof conversationModeSessions.$inferSelect,
+  ) => boolean;
+}
+
+export interface BeginModeSessionInput {
+  id: string;
+  conversationId: string;
+  mode: ModeSessionMode;
+  sourceStartedAt: number;
+}
+
+export interface RevisionedModeSessionInput {
+  id: string;
+  conversationId: string;
+  expectedRevision: number;
+}
+
+export interface UpdateModeSessionActivityInput extends RevisionedModeSessionInput {
+  lastActivityAt: number;
+  lastOwnedMessageId?: string | null;
+}
+
+export interface UpdateModeSessionBoundariesInput extends RevisionedModeSessionInput {
+  firstIncluded: { at: number; messageId: string } | null;
+  lastActivityAt: number;
+  lastOwnedMessageId: string | null;
+}
+
+interface FinalizeModeSessionInputBase extends RevisionedModeSessionInput {
+  endReason: string;
+  lastActivityAt?: number;
+  lastOwnedMessageId?: string | null;
+}
+
+export type FinalizeModeSessionInput = FinalizeModeSessionInputBase &
+  (
+    | { status: Extract<ModeSessionStatus, "completed">; endedAt: number }
+    | {
+        status: Extract<ModeSessionStatus, "interrupted">;
+        endedAt: number | null;
+      }
+  );
+
+function toSummary(
+  row: typeof conversationModeSessions.$inferSelect,
+): ModeSessionSummary {
+  return ModeSessionSummarySchema.parse(row);
+}
+
+function getSession(
+  database: ModeSessionReader,
+  conversationId: string,
+  id: string,
+): typeof conversationModeSessions.$inferSelect | undefined {
+  return database
+    .select()
+    .from(conversationModeSessions)
+    .where(
+      and(
+        eq(conversationModeSessions.conversationId, conversationId),
+        eq(conversationModeSessions.id, id),
+      ),
+    )
+    .get();
+}
+
+function classifyRejectedWrite(
+  current: typeof conversationModeSessions.$inferSelect | undefined,
+  expectedRevision: number,
+): ModeSessionWriteResult {
+  if (!current) {
+    return { ok: false, reason: "not_found" };
+  }
+  const session = toSummary(current);
+  if (current.status !== "active") {
+    return { ok: false, reason: "terminal", session };
+  }
+  if (current.revision !== expectedRevision) {
+    return { ok: false, reason: "stale_revision", session };
+  }
+  throw new Error("Mode session write was rejected without a state conflict");
+}
+
+function mutateActiveSession(
+  input: RevisionedModeSessionInput,
+  buildValues: (
+    current: typeof conversationModeSessions.$inferSelect,
+  ) => Partial<typeof conversationModeSessions.$inferInsert>,
+  options?: ModeSessionMutationOptions,
+): ModeSessionWriteResult {
+  const database = options?.db ?? getDb();
+  return database.transaction(
+    (tx) => {
+      const current = getSession(tx, input.conversationId, input.id);
+      if (
+        !current ||
+        current.status !== "active" ||
+        current.revision !== input.expectedRevision
+      ) {
+        if (
+          current &&
+          current.status !== "active" &&
+          options?.acceptTerminal?.(current)
+        ) {
+          return { ok: true, session: toSummary(current) };
+        }
+        return classifyRejectedWrite(current, input.expectedRevision);
+      }
+
+      tx.update(conversationModeSessions)
+        .set({
+          ...buildValues(current),
+          revision: sql`${conversationModeSessions.revision} + 1`,
+        })
+        .where(
+          and(
+            eq(conversationModeSessions.conversationId, input.conversationId),
+            eq(conversationModeSessions.id, input.id),
+            eq(conversationModeSessions.status, "active"),
+            eq(conversationModeSessions.revision, input.expectedRevision),
+          ),
+        )
+        .run();
+
+      const updated = getSession(tx, input.conversationId, input.id);
+      if (!updated || updated.revision !== input.expectedRevision + 1) {
+        return classifyRejectedWrite(updated, input.expectedRevision);
+      }
+      return { ok: true, session: toSummary(updated) };
+    },
+    { behavior: "immediate" },
+  );
+}
+
+export function beginConversationModeSession(
+  input: BeginModeSessionInput,
+  options?: ModeSessionStoreOptions,
+): ModeSessionWriteResult {
+  const database = options?.db ?? getDb();
+  return database.transaction(
+    (tx) => {
+      const existing = tx
+        .select()
+        .from(conversationModeSessions)
+        .where(eq(conversationModeSessions.id, input.id))
+        .get();
+      if (existing) {
+        return {
+          ok: false,
+          reason: "already_exists",
+          ...(existing.conversationId === input.conversationId
+            ? { session: toSummary(existing) }
+            : {}),
+        };
+      }
+
+      tx.insert(conversationModeSessions)
+        .values({
+          ...input,
+          status: "active",
+          firstIncludedAt: null,
+          firstIncludedMessageId: null,
+          lastActivityAt: input.sourceStartedAt,
+          lastOwnedMessageId: null,
+          endedAt: null,
+          endReason: null,
+          revision: 1,
+        })
+        .run();
+      const created = getSession(tx, input.conversationId, input.id);
+      if (!created) {
+        throw new Error("Mode session insert did not create a readable row");
+      }
+      return { ok: true, session: toSummary(created) };
+    },
+    { behavior: "immediate" },
+  );
+}
+
+export function updateConversationModeSessionActivity(
+  input: UpdateModeSessionActivityInput,
+  options?: ModeSessionStoreOptions,
+): ModeSessionWriteResult {
+  return mutateActiveSession(
+    input,
+    (current) => ({
+      lastActivityAt: Math.max(current.lastActivityAt, input.lastActivityAt),
+      ...(input.lastOwnedMessageId !== undefined
+        ? { lastOwnedMessageId: input.lastOwnedMessageId }
+        : {}),
+    }),
+    options,
+  );
+}
+
+export function updateConversationModeSessionBoundaries(
+  input: UpdateModeSessionBoundariesInput,
+  options?: ModeSessionStoreOptions,
+): ModeSessionWriteResult {
+  return mutateActiveSession(
+    input,
+    (current) => ({
+      firstIncludedAt: input.firstIncluded?.at ?? null,
+      firstIncludedMessageId: input.firstIncluded?.messageId ?? null,
+      lastActivityAt: Math.max(current.lastActivityAt, input.lastActivityAt),
+      lastOwnedMessageId: input.lastOwnedMessageId,
+    }),
+    options,
+  );
+}
+
+export function advanceConversationModeSessionRevision(
+  input: RevisionedModeSessionInput,
+  options?: ModeSessionStoreOptions,
+): ModeSessionWriteResult {
+  return mutateActiveSession(input, () => ({}), options);
+}
+
+export function finalizeConversationModeSession(
+  input: FinalizeModeSessionInput,
+  options?: ModeSessionStoreOptions,
+): ModeSessionWriteResult {
+  return mutateActiveSession(
+    input,
+    (current) => {
+      const lastActivityAt = Math.max(
+        current.lastActivityAt,
+        input.lastActivityAt ?? current.lastActivityAt,
+      );
+      if (input.endedAt !== null && input.endedAt < lastActivityAt) {
+        throw new Error("Mode session end cannot precede its last activity");
+      }
+      return {
+        status: input.status,
+        endedAt: input.endedAt,
+        endReason: input.endReason,
+        lastActivityAt,
+        ...(input.lastOwnedMessageId !== undefined
+          ? { lastOwnedMessageId: input.lastOwnedMessageId }
+          : {}),
+      };
+    },
+    {
+      ...options,
+      acceptTerminal: (current) =>
+        current.status === input.status &&
+        current.endedAt === input.endedAt &&
+        current.endReason === input.endReason &&
+        (input.lastActivityAt === undefined ||
+          input.lastActivityAt <= current.lastActivityAt) &&
+        (input.lastOwnedMessageId === undefined ||
+          input.lastOwnedMessageId === current.lastOwnedMessageId),
+    },
+  );
+}
+
+export function getConversationModeSession(
+  conversationId: string,
+  id: string,
+  options?: ModeSessionStoreOptions,
+): ModeSessionSummary | null {
+  const row = getSession(options?.db ?? getDb(), conversationId, id);
+  return row ? toSummary(row) : null;
+}
+
+export function listConversationModeSessionsByIds(
+  conversationId: string,
+  ids: readonly string[],
+  options?: ModeSessionStoreOptions,
+): ModeSessionSummary[] {
+  if (ids.length === 0) {
+    return [];
+  }
+  const rows = (options?.db ?? getDb())
+    .select()
+    .from(conversationModeSessions)
+    .where(
+      and(
+        eq(conversationModeSessions.conversationId, conversationId),
+        inArray(conversationModeSessions.id, [...new Set(ids)]),
+      ),
+    )
+    .all();
+  return rows.map(toSummary);
+}
+
+export function recoverActiveConversationModeSessions(
+  options?: ModeSessionStoreOptions,
+): number {
+  const result = (options?.db ?? getDb())
+    .update(conversationModeSessions)
+    .set({
+      status: "interrupted",
+      endedAt: null,
+      endReason: "assistant_restarted",
+      revision: sql`${conversationModeSessions.revision} + 1`,
+    })
+    .where(eq(conversationModeSessions.status, "active"))
+    .run() as unknown as { changes: number };
+  return result.changes;
+}
+
+/** Recompute replaceable row boundaries after destructive transcript edits. */
+export function repairConversationModeSessionBoundaries(
+  conversationId: string,
+  options?: ModeSessionStoreOptions,
+): number {
+  const database = options?.db ?? getDb();
+  return database.transaction(
+    (tx) => {
+      const sessions = tx
+        .select()
+        .from(conversationModeSessions)
+        .where(eq(conversationModeSessions.conversationId, conversationId))
+        .all();
+      if (sessions.length === 0) {
+        return 0;
+      }
+      const sessionsById = new Map(
+        sessions.map((session) => [session.id, session]),
+      );
+      const boundaries = new Map<
+        string,
+        {
+          firstAt: number | null;
+          firstMessageId: string | null;
+          lastAt: number;
+          lastMessageId: string;
+        }
+      >();
+      for (const message of tx
+        .select({
+          id: messages.id,
+          role: messages.role,
+          createdAt: messages.createdAt,
+          metadata: messages.metadata,
+        })
+        .from(messages)
+        .where(eq(messages.conversationId, conversationId))
+        .orderBy(asc(messages.createdAt), asc(messages.id))
+        .all()) {
+        const owner = readModeSessionMetadata(message.metadata);
+        if (!owner) {
+          continue;
+        }
+        const session = sessionsById.get(owner.id);
+        if (!session || session.mode !== owner.mode) {
+          continue;
+        }
+        const at = readMessageSentAt(message.metadata) ?? message.createdAt;
+        const startsDisplayBoundary = modeSessionRowStartsDisplay(
+          session.mode,
+          message.role === "assistant",
+        );
+        const current = boundaries.get(owner.id);
+        if (!current) {
+          boundaries.set(owner.id, {
+            firstAt: startsDisplayBoundary ? at : null,
+            firstMessageId: startsDisplayBoundary ? message.id : null,
+            lastAt: at,
+            lastMessageId: message.id,
+          });
+        } else {
+          if (
+            startsDisplayBoundary &&
+            (current.firstAt === null || at < current.firstAt)
+          ) {
+            current.firstAt = at;
+            current.firstMessageId = message.id;
+          }
+          current.lastAt = Math.max(current.lastAt, at);
+          current.lastMessageId = message.id;
+        }
+      }
+
+      let repaired = 0;
+      for (const session of sessions) {
+        const boundary = boundaries.get(session.id);
+        const firstIncludedAt = boundary?.firstAt ?? null;
+        const firstIncludedMessageId = boundary?.firstMessageId ?? null;
+        const lastOwnedMessageId = boundary?.lastMessageId ?? null;
+        const observedLastActivityAt =
+          boundary?.lastAt ?? session.lastActivityAt;
+        const lastActivityAt =
+          session.endedAt === null
+            ? Math.max(session.lastActivityAt, observedLastActivityAt)
+            : Math.min(
+                session.endedAt,
+                Math.max(session.lastActivityAt, observedLastActivityAt),
+              );
+        if (
+          session.firstIncludedAt === firstIncludedAt &&
+          session.firstIncludedMessageId === firstIncludedMessageId &&
+          session.lastOwnedMessageId === lastOwnedMessageId &&
+          session.lastActivityAt === lastActivityAt
+        ) {
+          continue;
+        }
+        const result = tx
+          .update(conversationModeSessions)
+          .set({
+            firstIncludedAt,
+            firstIncludedMessageId,
+            lastOwnedMessageId,
+            lastActivityAt,
+            revision: sql`${conversationModeSessions.revision} + 1`,
+          })
+          .where(
+            and(
+              eq(conversationModeSessions.conversationId, conversationId),
+              eq(conversationModeSessions.id, session.id),
+              eq(conversationModeSessions.revision, session.revision),
+            ),
+          )
+          .run() as unknown as { changes: number };
+        repaired += result.changes;
+      }
+      return repaired;
+    },
+    { behavior: "immediate" },
+  );
+}

package/src/persistence/conversation-queries.ts

@@ -955,19 +955,6 @@ function likeContainsPattern(query: string): string {
     .replace(/_/g, "\\_")}%`;
 }
 
-/**
- * Whether the sparse Qdrant `messages_lexical` index — the only source of
- * message-content matches — is a safe read source. Content matching is
- * unavailable (title matches only) until the one-time upgrade backfill has
- * fully drained: a partially populated collection would silently miss older
- * content (an empty result — not a throw). Indexing itself is unconditional
- * host infrastructure, so completion is the only gate; the recall read site
- * applies the same one via the shared {@link isLexicalBackfillComplete}.
- */
-function isMessageContentSearchAvailable(): boolean {
-  return isLexicalBackfillComplete();
-}
-
 /**
  * Full-text search across message content.
  *
@@ -976,9 +963,9 @@ function isMessageContentSearchAvailable(): boolean {
  * merged with a `LIKE` match on conversation titles; matching conversations
  * return with their relevant messages, ordered by most recently updated.
  *
- * Content matching is index-only — there is no `messages.content` scan
+ * Content matching is index-only: there is no `messages.content` scan
  * fallback and no other content source. Only the title arm can match while
- * the index is not a safe read source ({@link isMessageContentSearchAvailable}),
+ * the index is not a safe read source ({@link isLexicalBackfillComplete}),
  * for a query that tokenizes to nothing under the shared tokenizer (non-ASCII
  * or single-char input like "你", "é", "C++"), or when the Qdrant lexical
  * lookup fails (logged). An unindexed or unreachable index yields fewer
@@ -1017,7 +1004,7 @@ export async function searchConversations(
   const maxMsgsPerConv = opts?.maxMessagesPerConversation ?? 3;
 
   const hasTokens = hasLexicalTokens(trimmed);
-  const contentSearchAvailable = isMessageContentSearchAvailable();
+  const contentSearchAvailable = isLexicalBackfillComplete();
 
   // LIKE pattern for title matching (message-content indexes don't cover titles).
   const titlePattern = likeContainsPattern(query);
@@ -1453,9 +1440,9 @@ function buildExcerptFromText(
     text.length,
     match.index + match.length + EXCERPT_WINDOW,
   );
-  const excerpt =
+  return (
     (start > 0 ? "\u2026" : "") +
     text.slice(start, end).replace(/\s+/g, " ").trim() +
-    (end < text.length ? "\u2026" : "");
-  return excerpt;
+    (end < text.length ? "\u2026" : "")
+  );
 }

package/src/persistence/llm-usage-store.ts

@@ -515,19 +515,13 @@ interface GroupRow {
 
 type UsageQueryParam = ScheduleAttributionSqlParam;
 
-function normalizeUsageAggregationFilter(
-  filter?: UsageAggregationFilter,
-): UsageAggregationFilter {
-  return normalizeScheduleAttributionFilter(filter);
-}
-
 function buildUsageAggregationWhere(
   range: UsageTimeRange,
   filter?: UsageAggregationFilter,
   eventAlias?: string,
   now: number = Date.now(),
 ): { sql: string; params: UsageQueryParam[] } {
-  const normalized = normalizeUsageAggregationFilter(filter);
+  const normalized = normalizeScheduleAttributionFilter(filter);
   const eventTable = eventAlias ?? "llm_usage_events";
   const createdAt = `${eventTable}.created_at`;
   const clauses = [`${createdAt} >= ? AND ${createdAt} <= ?`];
@@ -852,7 +846,7 @@ export function getUsageGroupBreakdown(
   // Runtime allowlist — defense-in-depth against SQL injection via type assertions.
   assertGroupByDimension(groupBy);
 
-  const normalizedFilter = normalizeUsageAggregationFilter(filter);
+  const normalizedFilter = normalizeScheduleAttributionFilter(filter);
 
   // Conversation grouping requires a JOIN with conversations to resolve titles.
   if (groupBy === "conversation") {
@@ -984,7 +978,7 @@ export function getUsageGroupedSeries(
     throw new Error("Grouped usage series does not support conversation");
   }
 
-  const normalizedFilter = normalizeUsageAggregationFilter(filter);
+  const normalizedFilter = normalizeScheduleAttributionFilter(filter);
   let rows: UsageGroupedBucketRow[];
 
   if (groupBy === "schedule") {

package/src/persistence/message-metadata.ts

@@ -1,3 +1,4 @@
+import { type ModeSession, parseModeSession } from "../api/mode-session.js";
 import { safeParseRecord } from "../util/json.js";
 
 /**
@@ -18,3 +19,27 @@ export function mergeMessageMetadata(
     ...updates,
   });
 }
+
+export function readModeSessionMetadata(
+  metadata: string | null | undefined,
+): ModeSession | undefined {
+  if (!metadata) {
+    return undefined;
+  }
+  return parseModeSession(safeParseRecord(metadata).modeSession);
+}
+
+export function readMessageSentAt(
+  metadata: string | null | undefined,
+): number | undefined {
+  if (!metadata) {
+    return undefined;
+  }
+  const sentAt = safeParseRecord(metadata).sentAt;
+  return typeof sentAt === "number" &&
+    Number.isInteger(sentAt) &&
+    sentAt >= 0 &&
+    Number.isFinite(new Date(sentAt).getTime())
+    ? sentAt
+    : undefined;
+}

package/src/persistence/migrations/381-create-conversation-mode-sessions.ts

@@ -0,0 +1,41 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+const TABLE = "conversation_mode_sessions";
+
+export function migrateCreateConversationModeSessions(
+  database: DrizzleDb,
+): void {
+  const sqlite = getSqliteFrom(database);
+  sqlite.exec(/* sql */ `
+    CREATE TABLE IF NOT EXISTS ${TABLE} (
+      id TEXT PRIMARY KEY,
+      conversation_id TEXT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+      mode TEXT NOT NULL CHECK (mode IN ('computer_use', 'browser', 'live_vision', 'ambient')),
+      status TEXT NOT NULL CHECK (status IN ('active', 'completed', 'interrupted')),
+      source_started_at INTEGER NOT NULL,
+      first_included_at INTEGER,
+      first_included_message_id TEXT,
+      last_activity_at INTEGER NOT NULL,
+      last_owned_message_id TEXT,
+      ended_at INTEGER,
+      end_reason TEXT,
+      revision INTEGER NOT NULL DEFAULT 1 CHECK (revision > 0),
+      CHECK ((first_included_at IS NULL) = (first_included_message_id IS NULL)),
+      CHECK (
+        (status = 'active' AND ended_at IS NULL AND end_reason IS NULL)
+        OR (status = 'completed' AND ended_at IS NOT NULL AND end_reason IS NOT NULL AND length(end_reason) > 0)
+        OR (status = 'interrupted' AND end_reason IS NOT NULL AND length(end_reason) > 0)
+      ),
+      CHECK (ended_at IS NULL OR ended_at >= last_activity_at),
+      CHECK (last_activity_at >= source_started_at),
+      CHECK (first_included_at IS NULL OR first_included_at <= last_activity_at)
+    );
+    CREATE INDEX IF NOT EXISTS idx_conversation_mode_sessions_conversation_status
+      ON ${TABLE} (conversation_id, status);
+  `);
+}
+
+export function downCreateConversationModeSessions(database: DrizzleDb): void {
+  getSqliteFrom(database).exec(`DROP TABLE IF EXISTS ${TABLE}`);
+}

package/src/persistence/migrations/382-create-client-connection-events.ts

@@ -0,0 +1,40 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+const TABLE = "client_connection_events";
+
+/**
+ * Create `client_connection_events`: the durable hub subscribe/dispose
+ * ledger used by `assistant clients history`.
+ *
+ * One row per client-subscriber lifecycle event. Reconnects shorter than
+ * the flap window are coalesced at read time, not at write time, so the
+ * raw event stream stays a complete audit.
+ *
+ * Idempotent via IF NOT EXISTS.
+ */
+export function migrateCreateClientConnectionEvents(database: DrizzleDb): void {
+  const sqlite = getSqliteFrom(database);
+  sqlite.exec(
+    `CREATE TABLE IF NOT EXISTS ${TABLE} (
+       id TEXT PRIMARY KEY,
+       client_id TEXT NOT NULL,
+       interface_id TEXT NOT NULL,
+       connection_id TEXT NOT NULL,
+       reason TEXT NOT NULL,
+       occurred_at INTEGER NOT NULL,
+       actor_principal_id TEXT,
+       client_version TEXT,
+       sse_watchdog INTEGER,
+       machine_name TEXT
+     )`,
+  );
+  sqlite.exec(
+    `CREATE INDEX IF NOT EXISTS idx_client_connection_events_client_occurred
+       ON ${TABLE} (client_id, occurred_at)`,
+  );
+  sqlite.exec(
+    `CREATE INDEX IF NOT EXISTS idx_client_connection_events_occurred
+       ON ${TABLE} (occurred_at)`,
+  );
+}