@vellumai/assistant 0.12.2 → 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-plugin-facade.ts

@@ -1,3 +1,4 @@
+import type { ToolDefinition } from "../providers/types.js";
 import type {
   AddMessageOptions,
   ConversationRow,
@@ -5,6 +6,7 @@ import type {
   MessageRow,
 } from "./conversation-crud.js";
 import type { ArchiveStatusFilter } from "./conversation-queries.js";
+import type { ConversationToolSurface } from "./conversation-tool-surface.js";
 import type { ConversationType } from "./conversation-types.js";
 
 /**
@@ -52,6 +54,34 @@ export async function getMessages(
   return fn(conversationId);
 }
 
+/**
+ * What the conversation's most recent live turn sent to the provider that a
+ * replaying fork reproduces verbatim (its tool definitions and the
+ * delegation-section state of its system prompt), or `null` when none has
+ * been recorded.
+ */
+export async function getRecordedConversationToolSurface(
+  conversationId: string,
+): Promise<ConversationToolSurface | null> {
+  const { getConversationToolSurface: fn } =
+    await import("./conversation-tool-surface.js");
+  return fn(conversationId);
+}
+
+/**
+ * The tool definitions the conversation's most recent live turn sent to the
+ * provider, or `null` when none has been recorded. A projection of
+ * {@link getRecordedConversationToolSurface}: a fork replaying the source's
+ * request needs the whole record, whose delegation-section state the system
+ * prompt tier of the provider cache prefix depends on.
+ */
+export async function getConversationToolSurface(
+  conversationId: string,
+): Promise<ToolDefinition[] | null> {
+  const surface = await getRecordedConversationToolSurface(conversationId);
+  return surface?.tools ?? null;
+}
+
 /** Whether the conversation currently has a turn in flight. */
 export async function isConversationProcessing(id: string): Promise<boolean> {
   const { isConversationProcessing: fn } =

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/conversation-tool-surface.ts

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+
+import { eq, sql } from "drizzle-orm";
+
+import type { ToolDefinition } from "../providers/types.js";
+import { getDb } from "./db-connection.js";
+import { conversationToolSurfaces } from "./schema/index.js";
+
+/**
+ * Per-conversation record of what the most recent live turn sent to the
+ * provider that a fork wake cannot re-derive (`conversation_tool_surfaces`).
+ *
+ * The provider prompt cache is a byte-exact prefix match over
+ * `tools -> system -> messages`, so a background wake that forks a
+ * conversation can only reuse the source's cached prefix by sending the SAME
+ * tools array under the SAME system prompt. Re-deriving either on the fork
+ * cannot guarantee that: the fork may run in another process (a different
+ * tool registry), with no connected clients (different host-tool gates),
+ * under a presence the persisted message stamps do not encode, or under a
+ * wake scope that cannot spawn subagents where the source could (the system
+ * prompt's delegation section). Recording the resolved values and replaying
+ * them verbatim can.
+ */
+
+/** What a live turn sent that a replaying fork reproduces verbatim. */
+export interface ConversationToolSurface {
+  /** The tool definitions the turn sent, exactly as resolved. */
+  tools: ToolDefinition[];
+  /**
+   * Whether the turn's system prompt rendered the parallel-delegation
+   * section (`01-parallel-tasks`), which the prompt derives from the same
+   * resolved tool surface plus the turn's channel. `null` when unknown: the
+   * turn ran on a system-prompt override, or the row predates the column.
+   */
+  delegateIndependentTasks: boolean | null;
+}
+
+/** Content hash of the serialized surface. */
+export function hashConversationToolSurface(
+  surface: ConversationToolSurface,
+): string {
+  return hashSurface(
+    JSON.stringify(surface.tools),
+    surface.delegateIndependentTasks,
+  );
+}
+
+function hashSurface(
+  toolsJson: string,
+  delegateIndependentTasks: boolean | null,
+): string {
+  const marker =
+    delegateIndependentTasks === null
+      ? ""
+      : delegateIndependentTasks
+        ? "1"
+        : "0";
+  return createHash("sha256")
+    .update(toolsJson)
+    .update("\n")
+    .update(marker)
+    .digest("hex")
+    .slice(0, 32);
+}
+
+/**
+ * Persist `surface` as the conversation's current wire surface and return
+ * its hash. `knownHash` is the hash the caller last recorded for this
+ * conversation (undefined when it has recorded nothing this process
+ * lifetime): a matching hash skips the statement outright. Otherwise the
+ * upsert only rewrites a row whose stored hash differs, so a conversation
+ * reloaded from disk never rewrites an unchanged surface either.
+ */
+export function recordConversationToolSurface(
+  conversationId: string,
+  surface: ConversationToolSurface,
+  knownHash?: string,
+): string {
+  const toolsJson = JSON.stringify(surface.tools);
+  const { delegateIndependentTasks } = surface;
+  const toolsHash = hashSurface(toolsJson, delegateIndependentTasks);
+  if (knownHash === toolsHash) {
+    return toolsHash;
+  }
+  const updatedAt = Date.now();
+  getDb()
+    .insert(conversationToolSurfaces)
+    .values({
+      conversationId,
+      toolsJson,
+      toolsHash,
+      delegateIndependentTasks,
+      updatedAt,
+    })
+    .onConflictDoUpdate({
+      target: conversationToolSurfaces.conversationId,
+      set: { toolsJson, toolsHash, delegateIndependentTasks, updatedAt },
+      setWhere: sql`${conversationToolSurfaces.toolsHash} <> excluded.tools_hash`,
+    })
+    .run();
+  return toolsHash;
+}
+
+/**
+ * The surface the conversation's most recent live turn sent, or `null` when
+ * no turn has recorded one (or the stored JSON is unreadable).
+ */
+export function getConversationToolSurface(
+  conversationId: string,
+): ConversationToolSurface | null {
+  const row = getDb()
+    .select({
+      toolsJson: conversationToolSurfaces.toolsJson,
+      delegateIndependentTasks:
+        conversationToolSurfaces.delegateIndependentTasks,
+    })
+    .from(conversationToolSurfaces)
+    .where(eq(conversationToolSurfaces.conversationId, conversationId))
+    .get();
+  if (!row) {
+    return null;
+  }
+  try {
+    const parsed: unknown = JSON.parse(row.toolsJson);
+    if (!Array.isArray(parsed)) {
+      return null;
+    }
+    return {
+      tools: parsed as ToolDefinition[],
+      delegateIndependentTasks: row.delegateIndependentTasks ?? null,
+    };
+  } catch {
+    return null;
+  }
+}