vellum 0.0.16 → 0.2.0

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

@@ -0,0 +1,368 @@
+/**
+ * Channel inbound idempotency + delivery state tracking.
+ *
+ * Ensures duplicate channel messages (e.g. Telegram webhook retries)
+ * don't produce duplicate replies. Tracks delivery acknowledgement
+ * so the runtime owns the full lifecycle instead of web Postgres.
+ *
+ * Dead-letter support: when processMessage fails, the event is marked
+ * with processing_status='failed' (retryable) or 'dead_letter' (fatal
+ * or max attempts exceeded). A periodic sweep retries failed events,
+ * and a replay endpoint allows manual recovery of dead-lettered ones.
+ */
+
+import { eq, and, lte, isNotNull } from 'drizzle-orm';
+import { v4 as uuid } from 'uuid';
+import { getDb } from './db.js';
+import { channelInboundEvents, conversations } from './schema.js';
+import { getOrCreateConversation } from './conversation-key-store.js';
+import {
+  classifyError,
+  retryDelayForAttempt,
+  RETRY_MAX_ATTEMPTS,
+} from './job-utils.js';
+
+export interface InboundResult {
+  accepted: boolean;
+  eventId: string;
+  conversationId: string;
+  duplicate: boolean;
+}
+
+export interface RecordInboundOptions {
+  sourceMessageId?: string;
+}
+
+/**
+ * Record an inbound channel event. Returns `duplicate: true` if this
+ * exact (assistant, channel, chat, message) combination was already seen.
+ */
+export function recordInbound(
+  assistantId: string,
+  sourceChannel: string,
+  externalChatId: string,
+  externalMessageId: string,
+  options?: RecordInboundOptions,
+): InboundResult {
+  const db = getDb();
+
+  const existing = db
+    .select({
+      id: channelInboundEvents.id,
+      conversationId: channelInboundEvents.conversationId,
+    })
+    .from(channelInboundEvents)
+    .where(
+      and(
+        eq(channelInboundEvents.assistantId, assistantId),
+        eq(channelInboundEvents.sourceChannel, sourceChannel),
+        eq(channelInboundEvents.externalChatId, externalChatId),
+        eq(channelInboundEvents.externalMessageId, externalMessageId),
+      ),
+    )
+    .get();
+
+  if (existing) {
+    return {
+      accepted: true,
+      eventId: existing.id,
+      conversationId: existing.conversationId,
+      duplicate: true,
+    };
+  }
+
+  const conversationKey = `${sourceChannel}:${externalChatId}`;
+  const mapping = getOrCreateConversation(assistantId, conversationKey);
+  const now = Date.now();
+  const eventId = uuid();
+
+  db.transaction((tx) => {
+    tx.update(conversations)
+      .set({ updatedAt: now })
+      .where(eq(conversations.id, mapping.conversationId))
+      .run();
+    tx.insert(channelInboundEvents)
+      .values({
+        id: eventId,
+        assistantId,
+        sourceChannel,
+        externalChatId,
+        externalMessageId,
+        sourceMessageId: options?.sourceMessageId ?? null,
+        conversationId: mapping.conversationId,
+        deliveryStatus: 'pending',
+        createdAt: now,
+        updatedAt: now,
+      })
+      .run();
+  });
+
+  return {
+    accepted: true,
+    eventId,
+    conversationId: mapping.conversationId,
+    duplicate: false,
+  };
+}
+
+/**
+ * Link an inbound event to the user message it created, so edits can
+ * later find the correct message by source_message_id → message_id.
+ */
+export function linkMessage(eventId: string, messageId: string): void {
+  const db = getDb();
+  db.update(channelInboundEvents)
+    .set({ messageId, updatedAt: Date.now() })
+    .where(eq(channelInboundEvents.id, eventId))
+    .run();
+}
+
+/**
+ * Find the message ID linked to the original inbound event for a given
+ * platform-level message identifier (e.g. Telegram message_id).
+ */
+export function findMessageBySourceId(
+  assistantId: string,
+  sourceChannel: string,
+  externalChatId: string,
+  sourceMessageId: string,
+): { messageId: string; conversationId: string } | null {
+  const db = getDb();
+  const row = db
+    .select({
+      messageId: channelInboundEvents.messageId,
+      conversationId: channelInboundEvents.conversationId,
+    })
+    .from(channelInboundEvents)
+    .where(
+      and(
+        eq(channelInboundEvents.assistantId, assistantId),
+        eq(channelInboundEvents.sourceChannel, sourceChannel),
+        eq(channelInboundEvents.externalChatId, externalChatId),
+        eq(channelInboundEvents.sourceMessageId, sourceMessageId),
+        isNotNull(channelInboundEvents.messageId),
+      ),
+    )
+    .get();
+
+  if (!row || !row.messageId) return null;
+  return { messageId: row.messageId, conversationId: row.conversationId };
+}
+
+/**
+ * Acknowledge delivery of an outbound message for a channel event.
+ */
+export function acknowledgeDelivery(
+  assistantId: string,
+  sourceChannel: string,
+  externalChatId: string,
+  externalMessageId: string,
+): boolean {
+  const db = getDb();
+  const now = Date.now();
+
+  const existing = db
+    .select({ id: channelInboundEvents.id })
+    .from(channelInboundEvents)
+    .where(
+      and(
+        eq(channelInboundEvents.assistantId, assistantId),
+        eq(channelInboundEvents.sourceChannel, sourceChannel),
+        eq(channelInboundEvents.externalChatId, externalChatId),
+        eq(channelInboundEvents.externalMessageId, externalMessageId),
+      ),
+    )
+    .get();
+
+  if (!existing) return false;
+
+  db.update(channelInboundEvents)
+    .set({
+      deliveryStatus: 'delivered',
+      updatedAt: now,
+    })
+    .where(eq(channelInboundEvents.id, existing.id))
+    .run();
+
+  return true;
+}
+
+// ── Dead-letter queue helpers ───────────────────────────────────────
+
+/**
+ * Store the raw request payload on an inbound event so it can be
+ * replayed later if processing fails.
+ */
+export function storePayload(eventId: string, payload: Record<string, unknown>): void {
+  const db = getDb();
+  db.update(channelInboundEvents)
+    .set({ rawPayload: JSON.stringify(payload), updatedAt: Date.now() })
+    .where(eq(channelInboundEvents.id, eventId))
+    .run();
+}
+
+/**
+ * Clear a previously stored payload. Used when the ingress check
+ * detects secret-bearing content — the payload must not remain on disk.
+ */
+export function clearPayload(eventId: string): void {
+  const db = getDb();
+  db.update(channelInboundEvents)
+    .set({ rawPayload: null, updatedAt: Date.now() })
+    .where(eq(channelInboundEvents.id, eventId))
+    .run();
+}
+
+/** Mark an event as successfully processed. */
+export function markProcessed(eventId: string): void {
+  const db = getDb();
+  db.update(channelInboundEvents)
+    .set({ processingStatus: 'processed', updatedAt: Date.now() })
+    .where(eq(channelInboundEvents.id, eventId))
+    .run();
+}
+
+/**
+ * Record a processing failure. Classifies the error to decide whether
+ * the event should be retried (status='failed') or dead-lettered
+ * (status='dead_letter') when the error is fatal or max attempts
+ * are exhausted.
+ */
+export function recordProcessingFailure(eventId: string, err: unknown): void {
+  const db = getDb();
+  const now = Date.now();
+
+  const row = db
+    .select({ attempts: channelInboundEvents.processingAttempts })
+    .from(channelInboundEvents)
+    .where(eq(channelInboundEvents.id, eventId))
+    .get();
+
+  const attempts = (row?.attempts ?? 0) + 1;
+  const category = classifyError(err);
+  const errorMsg = err instanceof Error ? err.message : String(err);
+
+  if (category === 'fatal' || attempts >= RETRY_MAX_ATTEMPTS) {
+    db.update(channelInboundEvents)
+      .set({
+        processingStatus: 'dead_letter',
+        processingAttempts: attempts,
+        lastProcessingError: errorMsg,
+        retryAfter: null,
+        updatedAt: now,
+      })
+      .where(eq(channelInboundEvents.id, eventId))
+      .run();
+  } else {
+    const delay = retryDelayForAttempt(attempts);
+    db.update(channelInboundEvents)
+      .set({
+        processingStatus: 'failed',
+        processingAttempts: attempts,
+        lastProcessingError: errorMsg,
+        retryAfter: now + delay,
+        updatedAt: now,
+      })
+      .where(eq(channelInboundEvents.id, eventId))
+      .run();
+  }
+}
+
+/** Fetch events eligible for automatic retry (failed + past their backoff). */
+export function getRetryableEvents(limit = 20): Array<{
+  id: string;
+  assistantId: string;
+  conversationId: string;
+  processingAttempts: number;
+  rawPayload: string | null;
+}> {
+  const db = getDb();
+  const now = Date.now();
+  return db
+    .select({
+      id: channelInboundEvents.id,
+      assistantId: channelInboundEvents.assistantId,
+      conversationId: channelInboundEvents.conversationId,
+      processingAttempts: channelInboundEvents.processingAttempts,
+      rawPayload: channelInboundEvents.rawPayload,
+    })
+    .from(channelInboundEvents)
+    .where(
+      and(
+        eq(channelInboundEvents.processingStatus, 'failed'),
+        lte(channelInboundEvents.retryAfter, now),
+      ),
+    )
+    .limit(limit)
+    .all();
+}
+
+/** Fetch dead-lettered events for an assistant. */
+export function getDeadLetterEvents(assistantId: string): Array<{
+  id: string;
+  sourceChannel: string;
+  externalChatId: string;
+  externalMessageId: string;
+  conversationId: string;
+  processingAttempts: number;
+  lastProcessingError: string | null;
+  createdAt: number;
+}> {
+  const db = getDb();
+  return db
+    .select({
+      id: channelInboundEvents.id,
+      sourceChannel: channelInboundEvents.sourceChannel,
+      externalChatId: channelInboundEvents.externalChatId,
+      externalMessageId: channelInboundEvents.externalMessageId,
+      conversationId: channelInboundEvents.conversationId,
+      processingAttempts: channelInboundEvents.processingAttempts,
+      lastProcessingError: channelInboundEvents.lastProcessingError,
+      createdAt: channelInboundEvents.createdAt,
+    })
+    .from(channelInboundEvents)
+    .where(
+      and(
+        eq(channelInboundEvents.assistantId, assistantId),
+        eq(channelInboundEvents.processingStatus, 'dead_letter'),
+      ),
+    )
+    .all();
+}
+
+/**
+ * Reset dead-lettered events back to 'failed' so the sweep can retry
+ * them. Resets attempt counter and sets an immediate retry_after.
+ */
+export function replayDeadLetters(assistantId: string, eventIds: string[]): number {
+  const db = getDb();
+  const now = Date.now();
+  let count = 0;
+  for (const id of eventIds) {
+    const existing = db
+      .select({ id: channelInboundEvents.id })
+      .from(channelInboundEvents)
+      .where(
+        and(
+          eq(channelInboundEvents.id, id),
+          eq(channelInboundEvents.assistantId, assistantId),
+          eq(channelInboundEvents.processingStatus, 'dead_letter'),
+        ),
+      )
+      .get();
+    if (!existing) continue;
+
+    db.update(channelInboundEvents)
+      .set({
+        processingStatus: 'failed',
+        processingAttempts: 0,
+        lastProcessingError: null,
+        retryAfter: now,
+        updatedAt: now,
+      })
+      .where(eq(channelInboundEvents.id, id))
+      .run();
+    count++;
+  }
+  return count;
+}

package/src/memory/checkpoints.ts

@@ -0,0 +1,52 @@
+import { eq } from 'drizzle-orm';
+import { getDb } from './db.js';
+import { memoryCheckpoints } from './schema.js';
+
+export interface MessageCursorCheckpoint {
+  createdAt: number;
+  messageId: string;
+}
+
+export function getMemoryCheckpoint(key: string): string | null {
+  const db = getDb();
+  const row = db
+    .select({ value: memoryCheckpoints.value })
+    .from(memoryCheckpoints)
+    .where(eq(memoryCheckpoints.key, key))
+    .get();
+  return row?.value ?? null;
+}
+
+export function setMemoryCheckpoint(key: string, value: string): void {
+  const db = getDb();
+  const now = Date.now();
+  db.insert(memoryCheckpoints)
+    .values({ key, value, updatedAt: now })
+    .onConflictDoUpdate({
+      target: memoryCheckpoints.key,
+      set: { value, updatedAt: now },
+    })
+    .run();
+}
+
+export function readMessageCursorCheckpoint(
+  createdAtKey: string,
+  messageIdKey: string,
+): MessageCursorCheckpoint {
+  const createdAt = Number.parseInt(getMemoryCheckpoint(createdAtKey) ?? '0', 10) || 0;
+  const messageId = getMemoryCheckpoint(messageIdKey) ?? '';
+  return { createdAt, messageId };
+}
+
+export function writeMessageCursorCheckpoint(
+  createdAtKey: string,
+  messageIdKey: string,
+  checkpoint: MessageCursorCheckpoint,
+): void {
+  setMemoryCheckpoint(createdAtKey, String(checkpoint.createdAt));
+  setMemoryCheckpoint(messageIdKey, checkpoint.messageId);
+}
+
+export function resetMessageCursorCheckpoint(createdAtKey: string, messageIdKey: string): void {
+  writeMessageCursorCheckpoint(createdAtKey, messageIdKey, { createdAt: 0, messageId: '' });
+}

package/src/memory/clarification-resolver.ts

@@ -0,0 +1,297 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { getConfig } from '../config/loader.js';
+
+const DEFAULT_RESOLVER_MODEL = 'claude-haiku-4-5-20251001';
+const DEFAULT_RESOLVER_TIMEOUT_MS = 12_000;
+
+const DIRECTIONAL_EXISTING_CUES = ['existing', 'old', 'previous', 'first', 'earlier', 'original'];
+const DIRECTIONAL_CANDIDATE_CUES = ['candidate', 'new', 'latest', 'second', 'updated', 'instead', 'replace'];
+const MERGE_CUES = ['both', 'merge', 'combine', 'together', 'depends', 'either', 'mix'];
+
+const STOP_WORDS = new Set([
+  'about', 'after', 'again', 'also', 'because', 'been', 'before', 'being', 'between',
+  'could', 'doing', 'from', 'have', 'into', 'just', 'more', 'most', 'only', 'over',
+  'same', 'should', 'some', 'than', 'that', 'their', 'there', 'these', 'they', 'this',
+  'those', 'were', 'what', 'when', 'where', 'which', 'while', 'with', 'would', 'your',
+]);
+
+export type ClarificationResolution =
+  | 'keep_existing'
+  | 'keep_candidate'
+  | 'merge'
+  | 'still_unclear';
+
+export type ClarificationStrategy =
+  | 'heuristic'
+  | 'llm'
+  | 'llm_timeout'
+  | 'llm_error'
+  | 'no_llm_key';
+
+export interface ClarificationResolverInput {
+  existingStatement: string;
+  candidateStatement: string;
+  userMessage: string;
+}
+
+export interface ClarificationResolverOptions {
+  apiKey?: string;
+  model?: string;
+  timeoutMs?: number;
+}
+
+export interface ClarificationResolverResult {
+  resolution: ClarificationResolution;
+  strategy: ClarificationStrategy;
+  resolvedStatement: string | null;
+  explanation: string;
+}
+
+export async function resolveConflictClarification(
+  input: ClarificationResolverInput,
+  options?: ClarificationResolverOptions,
+): Promise<ClarificationResolverResult> {
+  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) {
+    return {
+      resolution: 'still_unclear',
+      strategy: 'no_llm_key',
+      resolvedStatement: null,
+      explanation: 'No Anthropic API key available for clarification fallback.',
+    };
+  }
+
+  try {
+    return await resolveWithLlm(input, {
+      apiKey,
+      model: options?.model ?? DEFAULT_RESOLVER_MODEL,
+      timeoutMs: options?.timeoutMs ?? DEFAULT_RESOLVER_TIMEOUT_MS,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message === 'clarification_resolver_timeout') {
+      return {
+        resolution: 'still_unclear',
+        strategy: 'llm_timeout',
+        resolvedStatement: null,
+        explanation: 'Clarification resolver timed out.',
+      };
+    }
+    return {
+      resolution: 'still_unclear',
+      strategy: 'llm_error',
+      resolvedStatement: null,
+      explanation: `Clarification resolver failed: ${message.slice(0, 300)}`,
+    };
+  }
+}
+
+function resolveWithHeuristics(input: ClarificationResolverInput): ClarificationResolverResult | null {
+  const normalizedMessage = normalize(input.userMessage);
+  if (!normalizedMessage) return null;
+
+  const lowerMessage = normalizedMessage.toLowerCase();
+
+  const hasExistingCue = containsAnyCue(lowerMessage, DIRECTIONAL_EXISTING_CUES);
+  const hasCandidateCue = containsAnyCue(lowerMessage, DIRECTIONAL_CANDIDATE_CUES);
+  const hasMergeCue = containsAnyCue(lowerMessage, MERGE_CUES);
+
+  // When multiple cue categories match, delegate to LLM to avoid misclassification
+  const matchCount = [hasExistingCue, hasCandidateCue, hasMergeCue].filter(Boolean).length;
+  if (matchCount > 1) return null;
+
+  if (hasMergeCue) {
+    return {
+      resolution: 'merge',
+      strategy: 'heuristic',
+      resolvedStatement: buildMergedStatement(input),
+      explanation: 'User response includes merge cues.',
+    };
+  }
+
+  if (hasExistingCue) {
+    return {
+      resolution: 'keep_existing',
+      strategy: 'heuristic',
+      resolvedStatement: null,
+      explanation: 'User response explicitly points to existing/old statement.',
+    };
+  }
+
+  if (hasCandidateCue) {
+    return {
+      resolution: 'keep_candidate',
+      strategy: 'heuristic',
+      resolvedStatement: null,
+      explanation: 'User response explicitly points to candidate/new statement.',
+    };
+  }
+
+  const messageTokens = tokenize(normalizedMessage);
+  const existingOverlap = overlapScore(messageTokens, tokenize(input.existingStatement));
+  const candidateOverlap = overlapScore(messageTokens, tokenize(input.candidateStatement));
+
+  if (existingOverlap >= 2 && existingOverlap >= candidateOverlap + 1) {
+    return {
+      resolution: 'keep_existing',
+      strategy: 'heuristic',
+      resolvedStatement: null,
+      explanation: 'User response overlaps more with existing statement details.',
+    };
+  }
+
+  if (candidateOverlap >= 2 && candidateOverlap >= existingOverlap + 1) {
+    return {
+      resolution: 'keep_candidate',
+      strategy: 'heuristic',
+      resolvedStatement: null,
+      explanation: 'User response overlaps more with candidate statement details.',
+    };
+  }
+
+  if (existingOverlap > 0 && candidateOverlap > 0) {
+    return {
+      resolution: 'merge',
+      strategy: 'heuristic',
+      resolvedStatement: buildMergedStatement(input),
+      explanation: 'User response overlaps with both statements.',
+    };
+  }
+
+  return null;
+}
+
+async function resolveWithLlm(
+  input: ClarificationResolverInput,
+  options: { apiKey: string; model: string; timeoutMs: number },
+): Promise<ClarificationResolverResult> {
+  const client = new Anthropic({ apiKey: options.apiKey });
+  const userPrompt = [
+    'You are resolving a memory clarification response.',
+    '',
+    `Existing statement: ${input.existingStatement}`,
+    `Candidate statement: ${input.candidateStatement}`,
+    `User clarification: ${input.userMessage}`,
+  ].join('\n');
+
+  const abortController = new AbortController();
+  const timer = setTimeout(() => abortController.abort(), 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: [{
+        name: 'resolve_conflict_clarification',
+        description: 'Resolve a pending memory contradiction using user clarification.',
+        input_schema: {
+          type: 'object' as const,
+          properties: {
+            resolution: {
+              type: 'string',
+              enum: ['keep_existing', 'keep_candidate', 'merge', 'still_unclear'],
+            },
+            resolved_statement: {
+              type: 'string',
+              description: 'Required only when resolution is merge.',
+            },
+            explanation: {
+              type: 'string',
+              description: 'One short rationale for the classification.',
+            },
+          },
+          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);
+
+    const toolBlock = response.content.find((block) => block.type === 'tool_use');
+    if (!toolBlock || toolBlock.type !== 'tool_use') {
+      throw new Error('No tool_use block in clarification resolver response.');
+    }
+
+    const parsed = toolBlock.input as {
+      resolution?: string;
+      resolved_statement?: string;
+      explanation?: string;
+    };
+
+    if (!isResolution(parsed.resolution)) {
+      throw new Error(`Invalid clarification resolution: ${String(parsed.resolution)}`);
+    }
+
+    const resolvedStatement = parsed.resolution === 'merge'
+      ? normalize(parsed.resolved_statement ?? buildMergedStatement(input)) || buildMergedStatement(input)
+      : null;
+
+    return {
+      resolution: parsed.resolution,
+      strategy: 'llm',
+      resolvedStatement,
+      explanation: normalize(parsed.explanation ?? 'Resolved via LLM fallback.').slice(0, 500),
+    };
+  } catch (err) {
+    clearTimeout(timer);
+    if (abortController.signal.aborted) {
+      throw new Error('clarification_resolver_timeout');
+    }
+    throw err;
+  }
+}
+
+function isResolution(value: string | undefined): value is ClarificationResolution {
+  return value === 'keep_existing'
+    || value === 'keep_candidate'
+    || value === 'merge'
+    || value === 'still_unclear';
+}
+
+function containsAnyCue(input: string, cues: readonly string[]): boolean {
+  return cues.some((cue) => new RegExp(`\\b${cue}\\b`).test(input));
+}
+
+function overlapScore(left: Set<string>, right: Set<string>): number {
+  let score = 0;
+  for (const token of left) {
+    if (right.has(token)) score += 1;
+  }
+  return score;
+}
+
+function tokenize(input: string): Set<string> {
+  const words = input
+    .toLowerCase()
+    .split(/[^a-z0-9]+/g)
+    .map((word) => word.trim())
+    .filter((word) => word.length >= 4 && !STOP_WORDS.has(word));
+  return new Set(words);
+}
+
+function normalize(input: string): string {
+  return input.replace(/\s+/g, ' ').trim();
+}
+
+function buildMergedStatement(input: ClarificationResolverInput): string {
+  const normalizedUserMessage = normalize(input.userMessage);
+  if (normalizedUserMessage.length >= 8 && normalizedUserMessage.length <= 320) {
+    return normalizedUserMessage;
+  }
+  const existing = normalize(input.existingStatement).slice(0, 140);
+  const candidate = normalize(input.candidateStatement).slice(0, 140);
+  return `Merged clarification: ${existing}; ${candidate}`.slice(0, 320);
+}