@vellumai/assistant 0.3.4 → 0.3.6

package/src/instrument.ts

@@ -1,5 +1,6 @@
 import * as Sentry from "@sentry/node";
 import { APP_VERSION } from "./version.js";
+import { getSentryDsn } from "./config/env.js";
 
 /** Patterns that match sensitive data in Sentry event values. */
 const PII_PATTERNS = [
@@ -20,7 +21,7 @@ function redactString(value: string): string {
 function redactObject(obj: unknown): unknown {
   if (typeof obj === "string") return redactString(obj);
   if (Array.isArray(obj)) return obj.map(redactObject);
-  if (obj !== null && typeof obj === "object") {
+  if (obj != null && typeof obj === "object") {
     const out: Record<string, unknown> = {};
     for (const [key, val] of Object.entries(obj)) {
       out[key] = redactObject(val);
@@ -30,10 +31,10 @@ function redactObject(obj: unknown): unknown {
   return obj;
 }
 
-/** Call after dotenv has loaded so process.env.SENTRY_DSN is available. */
+/** Call after dotenv has loaded so SENTRY_DSN is available. */
 export function initSentry(): void {
   Sentry.init({
-    dsn: process.env.SENTRY_DSN,
+    dsn: getSentryDsn(),
     release: `vellum-assistant@${APP_VERSION}`,
     environment: APP_VERSION === "0.0.0-dev" ? "development" : "production",
     sendDefaultPii: false,

package/src/logfire.ts

@@ -1,6 +1,7 @@
 import type { Provider, ProviderResponse, SendMessageOptions, Message, ToolDefinition } from './providers/types.js';
 import { APP_VERSION } from './version.js';
 import { getLogger } from './util/logger.js';
+import { getLogfireToken, isMonitoringEnabled } from './config/env.js';
 
 const log = getLogger('logfire');
 
@@ -8,8 +9,8 @@ type LogfireModule = typeof import('@pydantic/logfire-node');
 
 const LOGFIRE_ENABLED: boolean =
   APP_VERSION === '0.0.0-dev' &&
-  !!process.env.LOGFIRE_TOKEN &&
-  process.env.VELLUM_ENABLE_MONITORING === '1';
+  !!getLogfireToken() &&
+  isMonitoringEnabled();
 
 let logfireInstance: LogfireModule | null = null;
 
@@ -24,7 +25,7 @@ export async function initLogfire(): Promise<void> {
   try {
     const logfire = await import('@pydantic/logfire-node');
     logfire.configure({
-      token: process.env.LOGFIRE_TOKEN,
+      token: getLogfireToken(),
       serviceName: 'vellum-assistant',
       serviceVersion: APP_VERSION,
     });

package/src/memory/admin.ts

@@ -1,7 +1,7 @@
 import { getConfig } from '../config/loader.js';
 import { getLogger } from '../util/logger.js';
 import { getMemoryBackendStatus } from './embedding-backend.js';
-import { getDb } from './db.js';
+import { rawGet } from './db.js';
 import { enqueueBackfillJob, enqueueRebuildIndexJob } from './indexer.js';
 import {
   enqueueCleanupResolvedConflictsJob,
@@ -43,28 +43,35 @@ export interface MemoryConflictAndCleanupStats {
   cleanup: MemorySystemStatus['cleanup'];
 }
 
+interface ConflictStatsRow {
+  pending_count: number | null;
+  resolved_count: number | null;
+  oldest_pending_created_at: number | null;
+}
+
+interface CleanupStatsRow {
+  resolved_backlog: number | null;
+  superseded_backlog: number | null;
+  resolved_completed_24h: number | null;
+  superseded_completed_24h: number | null;
+}
+
 /** Lightweight query for conflict/cleanup metrics only — no table counts or job totals. */
 export function getMemoryConflictAndCleanupStats(): MemoryConflictAndCleanupStats {
-  const db = getDb();
-  const raw = (db as unknown as { $client: { query: (q: string) => { get: (...args: unknown[]) => unknown } } }).$client;
-  const conflictStats = raw.query(`
+  const conflictStats = rawGet<ConflictStatsRow>(`
     SELECT
       SUM(CASE WHEN status = 'pending_clarification' THEN 1 ELSE 0 END) AS pending_count,
       SUM(CASE WHEN status != 'pending_clarification' THEN 1 ELSE 0 END) AS resolved_count,
       MIN(CASE WHEN status = 'pending_clarification' THEN created_at END) AS oldest_pending_created_at
     FROM memory_item_conflicts
-  `).get() as {
-    pending_count: number | null;
-    resolved_count: number | null;
-    oldest_pending_created_at: number | null;
-  } | null;
+  `);
   const pending = conflictStats?.pending_count ?? 0;
   const oldestPendingCreatedAt = conflictStats?.oldest_pending_created_at ?? null;
-  const oldestPendingAgeMs = oldestPendingCreatedAt === null
+  const oldestPendingAgeMs = oldestPendingCreatedAt == null
     ? null
     : Math.max(0, Date.now() - oldestPendingCreatedAt);
   const throughputWindowStartMs = Date.now() - (24 * 60 * 60 * 1000);
-  const cleanupStats = raw.query(`
+  const cleanupStats = rawGet<CleanupStatsRow>(`
     SELECT
       SUM(CASE
         WHEN type = 'cleanup_resolved_conflicts' AND status IN ('pending', 'running')
@@ -83,12 +90,7 @@ export function getMemoryConflictAndCleanupStats(): MemoryConflictAndCleanupStat
         THEN 1 ELSE 0 END
       ) AS superseded_completed_24h
     FROM memory_jobs
-  `).get(throughputWindowStartMs, throughputWindowStartMs) as {
-    resolved_backlog: number | null;
-    superseded_backlog: number | null;
-    resolved_completed_24h: number | null;
-    superseded_completed_24h: number | null;
-  } | null;
+  `, throughputWindowStartMs, throughputWindowStartMs);
   return {
     conflicts: {
       pending,
@@ -107,32 +109,26 @@ export function getMemoryConflictAndCleanupStats(): MemoryConflictAndCleanupStat
 export function getMemorySystemStatus(): MemorySystemStatus {
   const config = getConfig();
   const backend = getMemoryBackendStatus(config);
-  const db = getDb();
-  const raw = (db as unknown as { $client: { query: (q: string) => { get: (...args: unknown[]) => unknown } } }).$client;
   const counts = {
     segments: countTable('memory_segments'),
     items: countTable('memory_items'),
     summaries: countTable('memory_summaries'),
     embeddings: countTable('memory_embeddings'),
   };
-  const conflictStats = raw.query(`
+  const conflictStats = rawGet<ConflictStatsRow>(`
     SELECT
       SUM(CASE WHEN status = 'pending_clarification' THEN 1 ELSE 0 END) AS pending_count,
       SUM(CASE WHEN status != 'pending_clarification' THEN 1 ELSE 0 END) AS resolved_count,
       MIN(CASE WHEN status = 'pending_clarification' THEN created_at END) AS oldest_pending_created_at
     FROM memory_item_conflicts
-  `).get() as {
-    pending_count: number | null;
-    resolved_count: number | null;
-    oldest_pending_created_at: number | null;
-  } | null;
+  `);
   const pending = conflictStats?.pending_count ?? 0;
   const oldestPendingCreatedAt = conflictStats?.oldest_pending_created_at ?? null;
-  const oldestPendingAgeMs = oldestPendingCreatedAt === null
+  const oldestPendingAgeMs = oldestPendingCreatedAt == null
     ? null
     : Math.max(0, Date.now() - oldestPendingCreatedAt);
   const throughputWindowStartMs = Date.now() - (24 * 60 * 60 * 1000);
-  const cleanupStats = raw.query(`
+  const cleanupStats = rawGet<CleanupStatsRow>(`
     SELECT
       SUM(CASE
         WHEN type = 'cleanup_resolved_conflicts' AND status IN ('pending', 'running')
@@ -151,12 +147,7 @@ export function getMemorySystemStatus(): MemorySystemStatus {
         THEN 1 ELSE 0 END
       ) AS superseded_completed_24h
     FROM memory_jobs
-  `).get(throughputWindowStartMs, throughputWindowStartMs) as {
-    resolved_backlog: number | null;
-    superseded_backlog: number | null;
-    resolved_completed_24h: number | null;
-    superseded_completed_24h: number | null;
-  } | null;
+  `, throughputWindowStartMs, throughputWindowStartMs);
   return {
     enabled: backend.enabled,
     degraded: backend.degraded,
@@ -179,8 +170,7 @@ export function getMemorySystemStatus(): MemorySystemStatus {
   };
 
   function countTable(table: string): number {
-    const row = raw.query(`SELECT COUNT(*) AS c FROM ${table}`).get() as { c: number } | null;
-    return row?.c ?? 0;
+    return rawGet<{ c: number }>(`SELECT COUNT(*) AS c FROM ${table}`)?.c ?? 0;
   }
 }
 

package/src/memory/attachments-store.ts

@@ -7,7 +7,7 @@
 
 import { eq } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
-import { getDb } from './db.js';
+import { getDb, rawRun } from './db.js';
 import { attachments, messageAttachments } from './schema.js';
 
 export interface StoredAttachment {
@@ -322,7 +322,7 @@ export function getAttachmentsForMessage(
 
   if (links.length === 0) return [];
 
-  const ids = links.map((l) => l.attachmentId).filter((id): id is string => id !== null);
+  const ids = links.map((l) => l.attachmentId).filter((id): id is string => id != null);
   return getAttachmentsByIds(ids);
 }
 
@@ -386,12 +386,9 @@ export function getAttachmentById(
  */
 export function deleteOrphanAttachments(candidateIds: string[]): number {
   if (candidateIds.length === 0) return 0;
-  const db = getDb();
-  const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
   const placeholders = candidateIds.map(() => '?').join(', ');
-  const stmt = raw.prepare(
+  return rawRun(
     `DELETE FROM attachments WHERE id IN (${placeholders}) AND id NOT IN (SELECT attachment_id FROM message_attachments)`,
+    ...candidateIds,
   );
-  const result = stmt.run(...candidateIds);
-  return result.changes;
 }

package/src/memory/channel-delivery-store.ts

@@ -11,7 +11,7 @@
  * and a replay endpoint allows manual recovery of dead-lettered ones.
  */
 
-import { eq, and, lte, isNotNull } from 'drizzle-orm';
+import { eq, and, desc, lte, isNotNull } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 import { getDb } from './db.js';
 import { channelInboundEvents, conversations } from './schema.js';
@@ -229,6 +229,35 @@ export function clearPayload(eventId: string): void {
     .run();
 }
 
+/**
+ * Retrieve the stored raw payload for a given conversation's most recent
+ * inbound event. Used by the escalation decide flow to recover the
+ * original message content after an approve/deny decision.
+ */
+export function getLatestStoredPayload(conversationId: string): Record<string, unknown> | null {
+  const db = getDb();
+  const row = db
+    .select({
+      rawPayload: channelInboundEvents.rawPayload,
+    })
+    .from(channelInboundEvents)
+    .where(
+      and(
+        eq(channelInboundEvents.conversationId, conversationId),
+        isNotNull(channelInboundEvents.rawPayload),
+      ),
+    )
+    .orderBy(desc(channelInboundEvents.createdAt))
+    .get();
+
+  if (!row?.rawPayload) return null;
+  try {
+    return JSON.parse(row.rawPayload) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
 /** Mark an event as successfully processed. */
 export function markProcessed(eventId: string): void {
   const db = getDb();

package/src/memory/channel-guardian-store.ts

@@ -8,7 +8,7 @@
  * requests track per-run guardian approval decisions.
  */
 
-import { and, desc, eq, gt, lte } from 'drizzle-orm';
+import { and, count, desc, eq, gt, lte } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 import { getDb } from './db.js';
 import {
@@ -142,6 +142,7 @@ export function createBinding(params: {
   guardianExternalUserId: string;
   guardianDeliveryChatId: string;
   verifiedVia?: string;
+  metadataJson?: string | null;
 }): GuardianBinding {
   const db = getDb();
   const now = Date.now();
@@ -156,7 +157,7 @@ export function createBinding(params: {
     status: 'active' as const,
     verifiedAt: now,
     verifiedVia: params.verifiedVia ?? 'challenge',
-    metadataJson: null,
+    metadataJson: params.metadataJson ?? null,
     createdAt: now,
     updatedAt: now,
   };
@@ -256,6 +257,20 @@ export function createChallenge(params: {
   return rowToChallenge(row);
 }
 
+export function revokePendingChallenges(assistantId: string, channel: string): void {
+  const db = getDb();
+  db.update(channelGuardianVerificationChallenges)
+    .set({ status: 'revoked', updatedAt: Date.now() })
+    .where(
+      and(
+        eq(channelGuardianVerificationChallenges.assistantId, assistantId),
+        eq(channelGuardianVerificationChallenges.channel, channel),
+        eq(channelGuardianVerificationChallenges.status, 'pending'),
+      ),
+    )
+    .run();
+}
+
 export function findPendingChallengeByHash(
   assistantId: string,
   channel: string,
@@ -281,6 +296,33 @@ export function findPendingChallengeByHash(
   return row ? rowToChallenge(row) : null;
 }
 
+/**
+ * Find any pending (non-expired) challenge for a given (assistantId, channel).
+ * Used by relay setup to detect whether a voice verification session is active.
+ */
+export function findPendingChallengeForChannel(
+  assistantId: string,
+  channel: string,
+): VerificationChallenge | null {
+  const db = getDb();
+  const now = Date.now();
+
+  const row = db
+    .select()
+    .from(channelGuardianVerificationChallenges)
+    .where(
+      and(
+        eq(channelGuardianVerificationChallenges.assistantId, assistantId),
+        eq(channelGuardianVerificationChallenges.channel, channel),
+        eq(channelGuardianVerificationChallenges.status, 'pending'),
+        gt(channelGuardianVerificationChallenges.expiresAt, now),
+      ),
+    )
+    .get();
+
+  return row ? rowToChallenge(row) : null;
+}
+
 export function consumeChallenge(
   id: string,
   consumedByExternalUserId: string,
@@ -538,6 +580,164 @@ export function updateApprovalDecision(
     .run();
 }
 
+// ---------------------------------------------------------------------------
+// Inbox / Escalation Query Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * List approval requests filtered by assistant, and optionally by channel,
+ * conversation, and status. Designed for the inbox UI to show a paginated
+ * list of escalations.
+ */
+export function listPendingApprovalRequests(params: {
+  assistantId?: string;
+  channel?: string;
+  conversationId?: string;
+  status?: ApprovalRequestStatus;
+  limit?: number;
+  offset?: number;
+}): GuardianApprovalRequest[] {
+  const db = getDb();
+
+  const conditions = [
+    eq(channelGuardianApprovalRequests.assistantId, params.assistantId ?? 'self'),
+  ];
+  if (params.channel) {
+    conditions.push(eq(channelGuardianApprovalRequests.channel, params.channel));
+  }
+  if (params.conversationId) {
+    conditions.push(eq(channelGuardianApprovalRequests.conversationId, params.conversationId));
+  }
+  conditions.push(
+    eq(channelGuardianApprovalRequests.status, params.status ?? 'pending'),
+  );
+
+  let query = db
+    .select()
+    .from(channelGuardianApprovalRequests)
+    .where(and(...conditions))
+    .orderBy(desc(channelGuardianApprovalRequests.createdAt));
+
+  if (params.limit !== undefined) {
+    query = query.limit(params.limit) as typeof query;
+  }
+  if (params.offset !== undefined) {
+    query = query.offset(params.offset) as typeof query;
+  }
+
+  return query.all().map(rowToApprovalRequest);
+}
+
+/**
+ * Fetch a single approval request by its primary key.
+ */
+export function getApprovalRequestById(id: string): GuardianApprovalRequest | null {
+  const db = getDb();
+
+  const row = db
+    .select()
+    .from(channelGuardianApprovalRequests)
+    .where(eq(channelGuardianApprovalRequests.id, id))
+    .get();
+
+  return row ? rowToApprovalRequest(row) : null;
+}
+
+/**
+ * Fetch a single approval request by run ID (any status).
+ * Useful for checking whether a run has an associated approval request.
+ */
+export function getApprovalRequestByRunId(runId: string): GuardianApprovalRequest | null {
+  const db = getDb();
+
+  const row = db
+    .select()
+    .from(channelGuardianApprovalRequests)
+    .where(eq(channelGuardianApprovalRequests.runId, runId))
+    .orderBy(desc(channelGuardianApprovalRequests.createdAt))
+    .get();
+
+  return row ? rowToApprovalRequest(row) : null;
+}
+
+/**
+ * Resolve a pending approval request with a decision.
+ *
+ * Idempotent: if the request is already resolved with the same decision,
+ * the existing record is returned unchanged. Returns null if the request
+ * does not exist or was resolved with a *different* decision.
+ */
+export function resolveApprovalRequest(
+  id: string,
+  decision: 'approved' | 'denied',
+  decidedByExternalUserId?: string,
+): GuardianApprovalRequest | null {
+  const db = getDb();
+
+  const existing = db
+    .select()
+    .from(channelGuardianApprovalRequests)
+    .where(eq(channelGuardianApprovalRequests.id, id))
+    .get();
+
+  if (!existing) return null;
+
+  // Idempotent: already resolved with the same decision
+  if (existing.status === decision) {
+    return rowToApprovalRequest(existing);
+  }
+
+  // Only resolve if currently pending
+  if (existing.status !== 'pending') {
+    return null;
+  }
+
+  const now = Date.now();
+
+  db.update(channelGuardianApprovalRequests)
+    .set({
+      status: decision,
+      decidedByExternalUserId: decidedByExternalUserId ?? null,
+      updatedAt: now,
+    })
+    .where(eq(channelGuardianApprovalRequests.id, id))
+    .run();
+
+  return rowToApprovalRequest({
+    ...existing,
+    status: decision,
+    decidedByExternalUserId: decidedByExternalUserId ?? null,
+    updatedAt: now,
+  });
+}
+
+/**
+ * Count pending approval requests for a given conversation.
+ * Used by thread state projection to compute `pending_escalation_count`.
+ */
+export function countPendingByConversation(
+  conversationId: string,
+  assistantId?: string,
+): number {
+  const db = getDb();
+
+  const conditions = [
+    eq(channelGuardianApprovalRequests.conversationId, conversationId),
+    eq(channelGuardianApprovalRequests.status, 'pending'),
+  ];
+  if (assistantId) {
+    conditions.push(eq(channelGuardianApprovalRequests.assistantId, assistantId));
+  }
+
+  const result = db
+    .select({ count: count() })
+    .from(channelGuardianApprovalRequests)
+    .where(and(...conditions))
+    .get();
+
+  return result?.count ?? 0;
+}
+
 // ---------------------------------------------------------------------------
 // Verification Rate Limits
 // ---------------------------------------------------------------------------

package/src/memory/clarification-resolver.ts

@@ -1,8 +1,8 @@
-import Anthropic from '@anthropic-ai/sdk';
-import { getConfig } from '../config/loader.js';
+import { getConfiguredProvider, createTimeout, extractToolUse, userMessage } from '../providers/provider-send-message.js';
+import type { ModelIntent } from '../providers/types.js';
 import { truncate } from '../util/truncate.js';
 
-const DEFAULT_RESOLVER_MODEL = 'claude-haiku-4-5-20251001';
+const DEFAULT_RESOLVER_MODEL_INTENT: ModelIntent = 'latency-optimized';
 const DEFAULT_RESOLVER_TIMEOUT_MS = 12_000;
 
 const DIRECTIONAL_EXISTING_CUES = ['existing', 'old', 'previous', 'first', 'earlier', 'original'];
@@ -38,6 +38,7 @@ export interface ClarificationResolverInput {
 export interface ClarificationResolverOptions {
   apiKey?: string;
   model?: string;
+  modelIntent?: ModelIntent;
   timeoutMs?: number;
 }
 
@@ -55,21 +56,20 @@ export async function resolveConflictClarification(
   const heuristicResult = resolveWithHeuristics(input);
   if (heuristicResult) return heuristicResult;
 
-  const config = getConfig();
-  const apiKey = options?.apiKey ?? config.apiKeys.anthropic ?? process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) {
+  const provider = getConfiguredProvider();
+  if (!provider) {
     return {
       resolution: 'still_unclear',
       strategy: 'no_llm_key',
       resolvedStatement: null,
-      explanation: 'No Anthropic API key available for clarification fallback.',
+      explanation: 'Configured provider unavailable for clarification fallback.',
     };
   }
 
   try {
     return await resolveWithLlm(input, {
-      apiKey,
-      model: options?.model ?? DEFAULT_RESOLVER_MODEL,
+      model: options?.model,
+      modelIntent: options?.modelIntent ?? DEFAULT_RESOLVER_MODEL_INTENT,
       timeoutMs: options?.timeoutMs ?? DEFAULT_RESOLVER_TIMEOUT_MS,
     });
   } catch (err) {
@@ -168,9 +168,9 @@ function resolveWithHeuristics(input: ClarificationResolverInput): Clarification
 
 async function resolveWithLlm(
   input: ClarificationResolverInput,
-  options: { apiKey: string; model: string; timeoutMs: number },
+  options: { model?: string; modelIntent: ModelIntent; timeoutMs: number },
 ): Promise<ClarificationResolverResult> {
-  const client = new Anthropic({ apiKey: options.apiKey });
+  const provider = getConfiguredProvider()!;
   const userPrompt = [
     'You are resolving a memory clarification response.',
     '',
@@ -179,22 +179,12 @@ async function resolveWithLlm(
     `User clarification: ${input.userMessage}`,
   ].join('\n');
 
-  const abortController = new AbortController();
-  const timer = setTimeout(() => abortController.abort(), options.timeoutMs);
+  const { signal, cleanup } = createTimeout(options.timeoutMs);
 
   try {
-  const response = await client.messages.create({
-      model: options.model,
-      max_tokens: 256,
-      system: [
-        'Classify the user clarification for conflicting memory statements.',
-        'Return exactly one resolution:',
-        '- keep_existing',
-        '- keep_candidate',
-        '- merge',
-        '- still_unclear',
-      ].join('\n'),
-      tools: [{
+    const response = await provider.sendMessage(
+      [userMessage(userPrompt)],
+      [{
         name: 'resolve_conflict_clarification',
         description: 'Resolve a pending memory contradiction using user clarification.',
         input_schema: {
@@ -216,13 +206,27 @@ async function resolveWithLlm(
           required: ['resolution', 'explanation'],
         },
       }],
-      tool_choice: { type: 'tool' as const, name: 'resolve_conflict_clarification' },
-      messages: [{ role: 'user' as const, content: userPrompt }],
-    }, { signal: abortController.signal });
-    clearTimeout(timer);
+      [
+        'Classify the user clarification for conflicting memory statements.',
+        'Return exactly one resolution:',
+        '- keep_existing',
+        '- keep_candidate',
+        '- merge',
+        '- still_unclear',
+      ].join('\n'),
+      {
+        config: {
+          ...(options.model ? { model: options.model } : { modelIntent: options.modelIntent }),
+          max_tokens: 256,
+          tool_choice: { type: 'tool' as const, name: 'resolve_conflict_clarification' },
+        },
+        signal,
+      },
+    );
+    cleanup();
 
-    const toolBlock = response.content.find((block) => block.type === 'tool_use');
-    if (!toolBlock || toolBlock.type !== 'tool_use') {
+    const toolBlock = extractToolUse(response);
+    if (!toolBlock) {
       throw new Error('No tool_use block in clarification resolver response.');
     }
 
@@ -247,8 +251,8 @@ async function resolveWithLlm(
       explanation: truncate(normalize(parsed.explanation ?? 'Resolved via LLM fallback.'), 500, ''),
     };
   } catch (err) {
-    clearTimeout(timer);
-    if (abortController.signal.aborted) {
+    cleanup();
+    if (signal.aborted) {
       throw new Error('clarification_resolver_timeout');
     }
     throw err;