@vellumai/assistant 0.7.0 → 0.7.1

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

@@ -14,6 +14,12 @@ import {
   bucketEventsByHour,
   type UsageEventBucketRow,
 } from "./usage-buckets.js";
+import {
+  bucketGroupedUsageEvents,
+  displayUsageGroup,
+  type UsageGroupedBucketRow,
+  type UsageGroupedSeriesBucket,
+} from "./usage-grouped-buckets.js";
 
 // ---------------------------------------------------------------------------
 // Write
@@ -28,6 +34,9 @@ export function recordUsageEvent(
     id: uuid(),
     createdAt: Date.now(),
     ...input,
+    callSite: input.callSite ?? null,
+    inferenceProfile: input.inferenceProfile ?? null,
+    inferenceProfileSource: input.inferenceProfileSource ?? null,
     estimatedCostUsd: pricing.estimatedCostUsd,
     pricingStatus: pricing.pricingStatus,
   };
@@ -39,6 +48,9 @@ export function recordUsageEvent(
       runId: event.runId,
       requestId: event.requestId,
       actor: event.actor,
+      callSite: event.callSite,
+      inferenceProfile: event.inferenceProfile,
+      inferenceProfileSource: event.inferenceProfileSource,
       provider: event.provider,
       model: event.model,
       inputTokens: event.inputTokens,
@@ -66,6 +78,9 @@ function rowToUsageEvent(row: {
   runId: string | null;
   requestId: string | null;
   actor: string;
+  callSite: string | null;
+  inferenceProfile: string | null;
+  inferenceProfileSource: string | null;
   provider: string;
   model: string;
   inputTokens: number;
@@ -82,6 +97,10 @@ function rowToUsageEvent(row: {
     runId: row.runId,
     requestId: row.requestId,
     actor: row.actor as UsageEvent["actor"],
+    callSite: row.callSite as UsageEvent["callSite"],
+    inferenceProfile: row.inferenceProfile,
+    inferenceProfileSource:
+      row.inferenceProfileSource as UsageEvent["inferenceProfileSource"],
     provider: row.provider,
     model: row.model,
     inputTokens: row.inputTokens,
@@ -183,17 +202,23 @@ export interface UsageDayBucket {
   eventCount: number;
 }
 
-/** A grouped breakdown row (by actor, provider, or model). */
+/** A grouped breakdown row. */
 export interface UsageGroupBreakdown {
+  /** Display label for the group. */
   group: string;
   /**
    * Stable identifier for the group. Populated with the conversation id when
    * `groupBy === "conversation"` (and `null` for that mode's "Other" bucket,
    * which aggregates events with no conversation id). For all other group-bys
-   * (`actor`, `provider`, `model`) this is always `null` — the raw grouping
-   * column is already exposed via `group`.
+   * this is always `null`.
    */
   groupId: string | null;
+  /**
+   * Raw stored grouping value for dimensions whose display label may differ
+   * from storage (`call_site`, `inference_profile`). Omitted for legacy
+   * dimensions where `group` is already the raw value.
+   */
+  groupKey?: string | null;
   /** Direct input tokens only; cache traffic is reported separately below. */
   totalInputTokens: number;
   totalOutputTokens: number;
@@ -216,9 +241,8 @@ interface TotalsRow {
   unpriced_event_count: number;
 }
 
-
 interface GroupRow {
-  group_key: string;
+  group_key: string | null;
   group_id: string | null;
   total_input_tokens: number;
   total_output_tokens: number;
@@ -274,6 +298,7 @@ function fetchRawBucketRows(range: UsageTimeRange): UsageEventBucketRow[] {
       llm_call_count
     FROM llm_usage_events
     WHERE created_at >= ?1 AND created_at <= ?2
+    ORDER BY created_at ASC
     `,
     range.from,
     range.to,
@@ -326,7 +351,64 @@ export function getUsageHourBuckets(
   return bucketEventsByHour(rows, range, tz, options);
 }
 
-type GroupByDimension = "actor" | "provider" | "model" | "conversation";
+export const USAGE_GROUP_BY_DIMENSIONS = [
+  "actor",
+  "provider",
+  "model",
+  "conversation",
+  "call_site",
+  "inference_profile",
+] as const;
+
+export type GroupByDimension = (typeof USAGE_GROUP_BY_DIMENSIONS)[number];
+
+export const USAGE_SERIES_GROUP_BY_DIMENSIONS = [
+  "actor",
+  "provider",
+  "model",
+  "call_site",
+  "inference_profile",
+] as const satisfies readonly GroupByDimension[];
+
+const GROUP_BY_COLUMNS: Record<
+  Exclude<GroupByDimension, "conversation">,
+  string
+> = {
+  actor: "actor",
+  provider: "provider",
+  model: "model",
+  call_site: "call_site",
+  inference_profile: "inference_profile",
+};
+
+const ALLOWED_DIMENSIONS = new Set<string>(USAGE_GROUP_BY_DIMENSIONS);
+
+function assertGroupByDimension(
+  groupBy: string,
+): asserts groupBy is GroupByDimension {
+  if (!ALLOWED_DIMENSIONS.has(groupBy)) {
+    throw new Error(`Invalid groupBy dimension: ${groupBy}`);
+  }
+}
+
+function mapGroupRow(
+  row: GroupRow,
+  groupBy: GroupByDimension,
+): UsageGroupBreakdown {
+  const includeGroupKey =
+    groupBy === "call_site" || groupBy === "inference_profile";
+  return {
+    group: displayUsageGroup(groupBy, row.group_key),
+    groupId: row.group_id,
+    ...(includeGroupKey ? { groupKey: row.group_key } : {}),
+    totalInputTokens: row.total_input_tokens,
+    totalOutputTokens: row.total_output_tokens,
+    totalCacheCreationTokens: row.total_cache_creation_tokens,
+    totalCacheReadTokens: row.total_cache_read_tokens,
+    totalEstimatedCostUsd: row.total_estimated_cost_usd ?? 0,
+    eventCount: row.event_count,
+  };
+}
 
 /**
  * Return grouped breakdowns across the given time range, ordered by total
@@ -337,15 +419,7 @@ export function getUsageGroupBreakdown(
   groupBy: GroupByDimension,
 ): UsageGroupBreakdown[] {
   // Runtime allowlist — defense-in-depth against SQL injection via type assertions.
-  const ALLOWED_DIMENSIONS = new Set<string>([
-    "actor",
-    "provider",
-    "model",
-    "conversation",
-  ]);
-  if (!ALLOWED_DIMENSIONS.has(groupBy)) {
-    throw new Error(`Invalid groupBy dimension: ${groupBy}`);
-  }
+  assertGroupByDimension(groupBy);
 
   // Conversation grouping requires a JOIN with conversations to resolve titles.
   if (groupBy === "conversation") {
@@ -372,22 +446,10 @@ export function getUsageGroupBreakdown(
       range.from,
       range.to,
     );
-    return rows.map((r) => ({
-      group: r.group_key,
-      // `GROUP BY e.conversation_id` makes `e.conversation_id` unambiguous
-      // inside each group — it is the seeded conversation id for real rows
-      // and `null` for the "Other" bucket (events with no conversation).
-      groupId: r.group_id,
-      totalInputTokens: r.total_input_tokens,
-      totalOutputTokens: r.total_output_tokens,
-      totalCacheCreationTokens: r.total_cache_creation_tokens,
-      totalCacheReadTokens: r.total_cache_read_tokens,
-      totalEstimatedCostUsd: r.total_estimated_cost_usd ?? 0,
-      eventCount: r.event_count,
-    }));
+    return rows.map((row) => mapGroupRow(row, groupBy));
   }
 
-  const column = groupBy;
+  const column = GROUP_BY_COLUMNS[groupBy];
   const rows = rawAll<GroupRow>(
     /*sql*/ `
     SELECT
@@ -407,18 +469,42 @@ export function getUsageGroupBreakdown(
     range.from,
     range.to,
   );
-  return rows.map((r) => ({
-    group: r.group_key,
-    // Non-conversation group-bys (actor/provider/model) don't have a
-    // separate stable id — the grouping column itself is the identifier
-    // and is already exposed via `group`. The SELECT projects
-    // `NULL AS group_id` so the runtime shape matches `GroupRow`.
-    groupId: r.group_id,
-    totalInputTokens: r.total_input_tokens,
-    totalOutputTokens: r.total_output_tokens,
-    totalCacheCreationTokens: r.total_cache_creation_tokens,
-    totalCacheReadTokens: r.total_cache_read_tokens,
-    totalEstimatedCostUsd: r.total_estimated_cost_usd ?? 0,
-    eventCount: r.event_count,
-  }));
+  return rows.map((row) => mapGroupRow(row, groupBy));
+}
+
+export function getUsageGroupedSeries(
+  range: UsageTimeRange,
+  groupBy: GroupByDimension,
+  granularity: UsageGranularity,
+  tz: string = "UTC",
+  options: UsageBucketOptions = {},
+): UsageGroupedSeriesBucket[] {
+  assertGroupByDimension(groupBy);
+  if (groupBy === "conversation") {
+    throw new Error("Grouped usage series does not support conversation");
+  }
+
+  const column = GROUP_BY_COLUMNS[groupBy];
+  const rows = rawAll<UsageGroupedBucketRow>(
+    /*sql*/ `
+    SELECT
+      created_at,
+      input_tokens,
+      output_tokens,
+      estimated_cost_usd,
+      llm_call_count,
+      ${column} AS group_key
+    FROM llm_usage_events
+    WHERE created_at >= ?1 AND created_at <= ?2
+    ORDER BY created_at ASC
+    `,
+    range.from,
+    range.to,
+  );
+
+  return bucketGroupedUsageEvents(rows, range, tz, {
+    ...options,
+    granularity,
+    groupBy,
+  });
 }

package/src/memory/memory-v2-activation-log-store.ts

@@ -0,0 +1,115 @@
+import { and, desc, eq, inArray, isNull } from "drizzle-orm";
+import { v4 as uuid } from "uuid";
+
+import { getDb } from "./db-connection.js";
+import { memoryV2ActivationLogs } from "./schema.js";
+
+export interface MemoryV2ConceptRowRecord {
+  slug: string;
+  finalActivation: number;
+  ownActivation: number;
+  priorActivation: number;
+  simUser: number;
+  simAssistant: number;
+  simNow: number;
+  spreadContribution: number;
+  source: "prior_state" | "ann_top50" | "both";
+  status: "in_context" | "injected" | "not_injected";
+}
+
+export interface MemoryV2SkillRowRecord {
+  id: string;
+  activation: number;
+  simUser: number;
+  simAssistant: number;
+  simNow: number;
+  status: "injected" | "not_injected";
+}
+
+export interface MemoryV2ConfigSnapshot {
+  d: number;
+  c_user: number;
+  c_assistant: number;
+  c_now: number;
+  k: number;
+  hops: number;
+  top_k: number;
+  top_k_skills: number;
+  epsilon: number;
+}
+
+export interface RecordMemoryV2ActivationLogParams {
+  conversationId: string;
+  turn: number;
+  mode: "context-load" | "per-turn";
+  concepts: MemoryV2ConceptRowRecord[];
+  skills: MemoryV2SkillRowRecord[];
+  config: MemoryV2ConfigSnapshot;
+}
+
+export function recordMemoryV2ActivationLog(
+  params: RecordMemoryV2ActivationLogParams,
+): void {
+  const db = getDb();
+  db.insert(memoryV2ActivationLogs)
+    .values({
+      id: uuid(),
+      conversationId: params.conversationId,
+      messageId: null,
+      turn: params.turn,
+      mode: params.mode,
+      conceptsJson: JSON.stringify(params.concepts),
+      skillsJson: JSON.stringify(params.skills),
+      configJson: JSON.stringify(params.config),
+      createdAt: Date.now(),
+    })
+    .run();
+}
+
+export function backfillMemoryV2ActivationMessageId(
+  conversationId: string,
+  messageId: string,
+): void {
+  const db = getDb();
+  db.update(memoryV2ActivationLogs)
+    .set({ messageId })
+    .where(
+      and(
+        eq(memoryV2ActivationLogs.conversationId, conversationId),
+        isNull(memoryV2ActivationLogs.messageId),
+      ),
+    )
+    .run();
+}
+
+export interface MemoryV2ActivationLog {
+  conversationId: string;
+  turn: number;
+  mode: "context-load" | "per-turn";
+  concepts: MemoryV2ConceptRowRecord[];
+  skills: MemoryV2SkillRowRecord[];
+  config: MemoryV2ConfigSnapshot;
+}
+
+export function getMemoryV2ActivationLogByMessageIds(
+  messageIds: string[],
+): MemoryV2ActivationLog | null {
+  if (messageIds.length === 0) return null;
+  const db = getDb();
+  const rows = db
+    .select()
+    .from(memoryV2ActivationLogs)
+    .where(inArray(memoryV2ActivationLogs.messageId, messageIds))
+    .orderBy(desc(memoryV2ActivationLogs.createdAt))
+    .all();
+  if (rows.length === 0) return null;
+  const row = rows[0]!;
+  return {
+    conversationId: row.conversationId,
+    turn: row.turn,
+    mode: row.mode as "context-load" | "per-turn",
+    concepts: JSON.parse(row.conceptsJson) as MemoryV2ConceptRowRecord[],
+    skills: JSON.parse(row.skillsJson) as MemoryV2SkillRowRecord[],
+    config: JSON.parse(row.configJson) as MemoryV2ConfigSnapshot,
+  };
+}

package/src/memory/migrations/233-document-conversations.ts

@@ -0,0 +1,54 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+const CHECKPOINT_KEY = "migration_document_conversations_v1";
+
+/**
+ * Create the document_conversations junction table.
+ *
+ * Tracks which conversations each document is associated with. A document may
+ * appear in multiple conversations (e.g. opened from search, linked by the
+ * assistant, etc.), so the relationship is many-to-many.
+ *
+ * The FK on surface_id cascades deletes from documents — when a document is
+ * removed, all its conversation associations are cleaned up automatically.
+ *
+ * There is intentionally NO FK to the conversations table. Conversation IDs may
+ * be synthetic or pre-resolved UUIDs that don't yet exist in the conversations
+ * table at insertion time. This means orphaned rows can accumulate when
+ * conversations are deleted. This is acceptable — the rows are tiny (two strings
+ * + timestamp) and the composite PK prevents unbounded growth per document. If
+ * cleanup becomes a concern, add a periodic sweep or hook into the conversation
+ * deletion path in memory/job-handlers/cleanup.ts.
+ *
+ * The migration also backfills from the existing documents.conversation_id column
+ * so that pre-existing document–conversation relationships are preserved.
+ */
+export function migrateCreateDocumentConversations(database: DrizzleDb): void {
+  withCrashRecovery(database, CHECKPOINT_KEY, () => {
+    const raw = getSqliteFrom(database);
+
+    raw.exec(/*sql*/ `
+      CREATE TABLE IF NOT EXISTS document_conversations (
+        surface_id TEXT NOT NULL,
+        conversation_id TEXT NOT NULL,
+        created_at INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000),
+        PRIMARY KEY (surface_id, conversation_id),
+        FOREIGN KEY (surface_id) REFERENCES documents(surface_id) ON DELETE CASCADE
+      )
+    `);
+
+    raw.exec(/*sql*/ `
+      CREATE INDEX IF NOT EXISTS idx_doc_conv_conversation_id
+      ON document_conversations(conversation_id)
+    `);
+
+    // Backfill: seed junction table from existing documents.conversation_id
+    raw.exec(/*sql*/ `
+      INSERT OR IGNORE INTO document_conversations (surface_id, conversation_id, created_at)
+      SELECT surface_id, conversation_id, created_at
+      FROM documents
+    `);
+  });
+}

package/src/memory/migrations/234-memory-v2-activation-logs.ts

@@ -0,0 +1,55 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+const CHECKPOINT_KEY = "migration_memory_v2_activation_logs_v1";
+
+/**
+ * Create the memory_v2_activation_logs table for per-turn v2 activation
+ * telemetry.
+ *
+ * Each row captures one activation pass keyed by (conversation, turn, mode):
+ * - mode is "context-load" (initial conversation hydration) or "per-turn"
+ *   (each subsequent agent turn).
+ * - concepts_json / skills_json hold the structured activation outputs.
+ * - config_json captures the resolved config snapshot used for the pass so
+ *   the inspector can reproduce activation conditions.
+ *
+ * Indexes mirror the access patterns used by the inspector tab: lookup by
+ * message_id, by conversation_id, and ordering by created_at.
+ */
+export function migrateMemoryV2ActivationLogs(database: DrizzleDb): void {
+  withCrashRecovery(database, CHECKPOINT_KEY, () => {
+    const raw = getSqliteFrom(database);
+    raw.exec(/*sql*/ `
+      CREATE TABLE IF NOT EXISTS memory_v2_activation_logs (
+        id TEXT PRIMARY KEY,
+        conversation_id TEXT NOT NULL,
+        message_id TEXT,
+        turn INTEGER NOT NULL,
+        mode TEXT NOT NULL,
+        concepts_json TEXT NOT NULL,
+        skills_json TEXT NOT NULL,
+        config_json TEXT NOT NULL,
+        created_at INTEGER NOT NULL
+      )
+    `);
+    raw.exec(/*sql*/ `
+      CREATE INDEX IF NOT EXISTS idx_memory_v2_activation_logs_message_id
+        ON memory_v2_activation_logs (message_id)
+    `);
+    raw.exec(/*sql*/ `
+      CREATE INDEX IF NOT EXISTS idx_memory_v2_activation_logs_conversation_id
+        ON memory_v2_activation_logs (conversation_id)
+    `);
+    raw.exec(/*sql*/ `
+      CREATE INDEX IF NOT EXISTS idx_memory_v2_activation_logs_created_at
+        ON memory_v2_activation_logs (created_at)
+    `);
+  });
+}
+
+export function downMemoryV2ActivationLogs(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+  raw.exec(/*sql*/ `DROP TABLE IF EXISTS memory_v2_activation_logs`);
+}

package/src/memory/migrations/235-llm-usage-attribution.ts

@@ -0,0 +1,31 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
+
+/**
+ * Add stable attribution identifiers to the local LLM usage ledger.
+ *
+ * Existing rows remain valid with NULL attribution. Provider/model continue to
+ * represent the resolved provider/model used for the request.
+ */
+export function migrateLlmUsageAttribution(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+
+  if (!tableHasColumn(database, "llm_usage_events", "call_site")) {
+    raw.exec(/*sql*/ `ALTER TABLE llm_usage_events ADD COLUMN call_site TEXT`);
+  }
+
+  if (!tableHasColumn(database, "llm_usage_events", "inference_profile")) {
+    raw.exec(
+      /*sql*/ `ALTER TABLE llm_usage_events ADD COLUMN inference_profile TEXT`,
+    );
+  }
+
+  if (
+    !tableHasColumn(database, "llm_usage_events", "inference_profile_source")
+  ) {
+    raw.exec(
+      /*sql*/ `ALTER TABLE llm_usage_events ADD COLUMN inference_profile_source TEXT`,
+    );
+  }
+}

package/src/memory/migrations/235-slack-compaction-watermark.ts

@@ -0,0 +1,44 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+const CHECKPOINT_KEY = "migration_slack_compaction_watermark_v1";
+
+const COLUMNS = [
+  {
+    name: "slack_context_compaction_watermark_ts",
+    definition: "slack_context_compaction_watermark_ts TEXT",
+  },
+  {
+    name: "slack_context_compaction_watermark_at",
+    definition: "slack_context_compaction_watermark_at INTEGER",
+  },
+] as const;
+
+/**
+ * Add Slack-specific compaction state to conversations.
+ *
+ * The existing context_compacted_message_count remains the generic DB-row
+ * compaction boundary. Slack threads need a source timestamp watermark because
+ * late thread mentions can arrive with historical Slack ts values independent
+ * of local insertion order.
+ */
+export function migrateSlackCompactionWatermark(database: DrizzleDb): void {
+  withCrashRecovery(database, CHECKPOINT_KEY, () => {
+    for (const column of COLUMNS) {
+      if (tableHasColumn(database, "conversations", column.name)) {
+        continue;
+      }
+      database.run(`ALTER TABLE conversations ADD COLUMN ${column.definition}`);
+    }
+  });
+}
+
+export function downSlackCompactionWatermark(database: DrizzleDb): void {
+  for (const column of COLUMNS) {
+    if (!tableHasColumn(database, "conversations", column.name)) {
+      continue;
+    }
+    database.run(`ALTER TABLE conversations DROP COLUMN ${column.name}`);
+  }
+}

package/src/memory/migrations/236-tool-invocations-matched-rule-id.ts

@@ -0,0 +1,26 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+const CHECKPOINT_KEY = "migration_tool_invocations_matched_trust_rule_id_v1";
+
+/**
+ * Add matched_trust_rule_id column to tool_invocations for audit and rule editor UI.
+ */
+export function migrateToolInvocationsMatchedRuleId(database: DrizzleDb): void {
+  withCrashRecovery(database, CHECKPOINT_KEY, () => {
+    if (tableHasColumn(database, "tool_invocations", "matched_trust_rule_id")) {
+      return;
+    }
+    database.run(
+      `ALTER TABLE tool_invocations ADD COLUMN matched_trust_rule_id TEXT`,
+    );
+  });
+}
+
+export function downToolInvocationsMatchedRuleId(database: DrizzleDb): void {
+  if (!tableHasColumn(database, "tool_invocations", "matched_trust_rule_id")) {
+    return;
+  }
+  database.run(`ALTER TABLE tool_invocations DROP COLUMN matched_trust_rule_id`);
+}