vellum 0.2.13 → 0.3.2

package/src/contacts/contact-store.ts

@@ -1,410 +0,0 @@
-import { and, eq, like, desc, asc } from 'drizzle-orm';
-import { v4 as uuid } from 'uuid';
-import { getDb } from '../memory/db.js';
-import { contacts, contactChannels } from '../memory/schema.js';
-import type { Contact, ContactChannel, ContactWithChannels } from './types.js';
-
-// ── Helpers ──────────────────────────────────────────────────────────
-
-/** Strip LIKE metacharacters so user input is matched literally.
- * SQLite has no default escape character for LIKE, so we strip rather than escape. */
-function escapeLike(value: string): string {
-  return value.replace(/%/g, '').replace(/_/g, '');
-}
-
-function parseContact(row: typeof contacts.$inferSelect): Contact {
-  return {
-    id: row.id,
-    displayName: row.displayName,
-    relationship: row.relationship,
-    importance: row.importance,
-    responseExpectation: row.responseExpectation,
-    preferredTone: row.preferredTone,
-    lastInteraction: row.lastInteraction,
-    interactionCount: row.interactionCount,
-    createdAt: row.createdAt,
-    updatedAt: row.updatedAt,
-  };
-}
-
-function parseChannel(row: typeof contactChannels.$inferSelect): ContactChannel {
-  return {
-    id: row.id,
-    contactId: row.contactId,
-    type: row.type,
-    address: row.address,
-    isPrimary: row.isPrimary,
-    createdAt: row.createdAt,
-  };
-}
-
-function getChannelsForContact(contactId: string): ContactChannel[] {
-  const db = getDb();
-  const rows = db
-    .select()
-    .from(contactChannels)
-    .where(eq(contactChannels.contactId, contactId))
-    .orderBy(desc(contactChannels.isPrimary), asc(contactChannels.createdAt))
-    .all();
-  return rows.map(parseChannel);
-}
-
-function withChannels(contact: Contact): ContactWithChannels {
-  return { ...contact, channels: getChannelsForContact(contact.id) };
-}
-
-// ── CRUD ─────────────────────────────────────────────────────────────
-
-export function getContact(id: string): ContactWithChannels | null {
-  const db = getDb();
-  const row = db.select().from(contacts).where(eq(contacts.id, id)).get();
-  if (!row) return null;
-  return withChannels(parseContact(row));
-}
-
-export function upsertContact(params: {
-  id?: string;
-  displayName: string;
-  relationship?: string | null;
-  importance?: number;
-  responseExpectation?: string | null;
-  preferredTone?: string | null;
-  channels?: Array<{ type: string; address: string; isPrimary?: boolean }>;
-}): ContactWithChannels & { created: boolean } {
-  const db = getDb();
-  const now = Date.now();
-
-  let contactId = params.id;
-
-  // If an ID is provided, check if the contact exists for update
-  if (contactId) {
-    const existing = db.select().from(contacts).where(eq(contacts.id, contactId)).get();
-    if (existing) {
-      db.update(contacts)
-        .set({
-          displayName: params.displayName,
-          relationship: params.relationship !== undefined ? params.relationship : existing.relationship,
-          importance: params.importance !== undefined ? params.importance : existing.importance,
-          responseExpectation: params.responseExpectation !== undefined ? params.responseExpectation : existing.responseExpectation,
-          preferredTone: params.preferredTone !== undefined ? params.preferredTone : existing.preferredTone,
-          updatedAt: now,
-        })
-        .where(eq(contacts.id, contactId))
-        .run();
-
-      if (params.channels) {
-        syncChannels(contactId, params.channels, now);
-      }
-
-      return { ...getContact(contactId)!, created: false };
-    }
-  }
-
-  // Try to find by channel address to avoid duplicates
-  if (!contactId && params.channels && params.channels.length > 0) {
-    for (const ch of params.channels) {
-      const existingChannel = db
-        .select()
-        .from(contactChannels)
-        .where(and(eq(contactChannels.type, ch.type), eq(contactChannels.address, ch.address.toLowerCase())))
-        .get();
-      if (existingChannel) {
-        contactId = existingChannel.contactId;
-        // Update existing contact
-        db.update(contacts)
-          .set({
-            displayName: params.displayName,
-            relationship: params.relationship !== undefined ? params.relationship : undefined,
-            importance: params.importance !== undefined ? params.importance : undefined,
-            responseExpectation: params.responseExpectation !== undefined ? params.responseExpectation : undefined,
-            preferredTone: params.preferredTone !== undefined ? params.preferredTone : undefined,
-            updatedAt: now,
-          })
-          .where(eq(contacts.id, contactId))
-          .run();
-
-        syncChannels(contactId, params.channels, now);
-        return { ...getContact(contactId)!, created: false };
-      }
-    }
-  }
-
-  // Create new contact
-  contactId = contactId ?? uuid();
-  db.insert(contacts).values({
-    id: contactId,
-    displayName: params.displayName,
-    relationship: params.relationship ?? null,
-    importance: params.importance ?? 0.5,
-    responseExpectation: params.responseExpectation ?? null,
-    preferredTone: params.preferredTone ?? null,
-    lastInteraction: null,
-    interactionCount: 0,
-    createdAt: now,
-    updatedAt: now,
-  }).run();
-
-  if (params.channels) {
-    syncChannels(contactId, params.channels, now);
-  }
-
-  return { ...getContact(contactId)!, created: true };
-}
-
-/**
- * Add new channels to a contact without removing existing ones.
- * Skips channels that already exist (same type+address).
- */
-function syncChannels(
-  contactId: string,
-  channels: Array<{ type: string; address: string; isPrimary?: boolean }>,
-  now: number,
-): void {
-  const db = getDb();
-
-  for (const ch of channels) {
-    const normalizedAddress = ch.address.toLowerCase();
-
-    // Check if this channel already exists for this contact
-    const existing = db
-      .select()
-      .from(contactChannels)
-      .where(
-        and(
-          eq(contactChannels.contactId, contactId),
-          eq(contactChannels.type, ch.type),
-          eq(contactChannels.address, normalizedAddress),
-        ),
-      )
-      .get();
-
-    if (existing) {
-      // Update primary flag if specified
-      if (ch.isPrimary !== undefined) {
-        db.update(contactChannels)
-          .set({ isPrimary: ch.isPrimary })
-          .where(eq(contactChannels.id, existing.id))
-          .run();
-      }
-      continue;
-    }
-
-    // Check if this channel exists for a different contact (unique constraint)
-    const conflicting = db
-      .select()
-      .from(contactChannels)
-      .where(
-        and(
-          eq(contactChannels.type, ch.type),
-          eq(contactChannels.address, normalizedAddress),
-        ),
-      )
-      .get();
-
-    if (conflicting) {
-      // Channel belongs to another contact -- skip to avoid unique constraint violation.
-      // The caller should use contact_merge to combine the two contacts.
-      continue;
-    }
-
-    db.insert(contactChannels).values({
-      id: uuid(),
-      contactId,
-      type: ch.type,
-      address: normalizedAddress,
-      isPrimary: ch.isPrimary ?? false,
-      createdAt: now,
-    }).run();
-  }
-}
-
-export function searchContacts(params: {
-  query?: string;
-  channelAddress?: string;
-  channelType?: string;
-  relationship?: string;
-  limit?: number;
-}): ContactWithChannels[] {
-  const db = getDb();
-  const limit = Math.max(1, Math.min(params.limit ?? 20, 100));
-
-  // Search by channel address first (exact or partial match)
-  if (params.channelAddress) {
-    const normalizedAddress = escapeLike(params.channelAddress.toLowerCase());
-    if (!normalizedAddress) return [];
-    const channelRows = db
-      .select()
-      .from(contactChannels)
-      .where(
-        params.channelType
-          ? and(
-              eq(contactChannels.type, params.channelType),
-              like(contactChannels.address, `%${normalizedAddress}%`),
-            )
-          : like(contactChannels.address, `%${normalizedAddress}%`),
-      )
-      .all();
-
-    const contactIds = [...new Set(channelRows.map((r) => r.contactId))];
-    if (contactIds.length === 0) return [];
-
-    const results: ContactWithChannels[] = [];
-    for (const id of contactIds.slice(0, limit)) {
-      const contact = getContact(id);
-      if (contact) results.push(contact);
-    }
-    return results;
-  }
-
-  // Search by display name and/or relationship
-  const conditions = [];
-  if (params.query) {
-    const sanitized = escapeLike(params.query);
-    if (!sanitized && !params.relationship) return [];
-    if (sanitized) {
-      conditions.push(like(contacts.displayName, `%${sanitized}%`));
-    }
-  }
-  if (params.relationship) {
-    conditions.push(eq(contacts.relationship, params.relationship));
-  }
-
-  const whereClause = conditions.length > 0
-    ? conditions.length === 1
-      ? conditions[0]
-      : and(...conditions)
-    : undefined;
-
-  const rows = db
-    .select()
-    .from(contacts)
-    .where(whereClause)
-    .orderBy(desc(contacts.importance), desc(contacts.lastInteraction))
-    .limit(limit)
-    .all();
-
-  return rows.map((r) => withChannels(parseContact(r)));
-}
-
-export function listContacts(limit = 50): ContactWithChannels[] {
-  const db = getDb();
-  const rows = db
-    .select()
-    .from(contacts)
-    .orderBy(desc(contacts.importance), desc(contacts.lastInteraction))
-    .limit(Math.min(limit, 200))
-    .all();
-  return rows.map((r) => withChannels(parseContact(r)));
-}
-
-/**
- * Merge two contacts into one. The surviving contact keeps the higher importance,
- * more recent interaction timestamp, and all channels from both contacts.
- * The donor contact is deleted after merging.
- */
-export function mergeContacts(keepId: string, mergeId: string): ContactWithChannels {
-  const db = getDb();
-
-  if (keepId === mergeId) throw new Error('Cannot merge a contact with itself');
-
-  db.transaction((tx) => {
-    const now = Date.now();
-
-    const keep = tx.select().from(contacts).where(eq(contacts.id, keepId)).get();
-    if (!keep) throw new Error(`Contact "${keepId}" not found`);
-
-    const merge = tx.select().from(contacts).where(eq(contacts.id, mergeId)).get();
-    if (!merge) throw new Error(`Contact "${mergeId}" not found`);
-
-    // Resolve merged field values — pick the better/more recent value
-    const mergedImportance = Math.max(keep.importance, merge.importance);
-    const mergedInteractionCount = keep.interactionCount + merge.interactionCount;
-    const mergedLastInteraction = Math.max(keep.lastInteraction ?? 0, merge.lastInteraction ?? 0) || null;
-
-    tx.update(contacts)
-      .set({
-        importance: mergedImportance,
-        interactionCount: mergedInteractionCount,
-        lastInteraction: mergedLastInteraction,
-        // Prefer keep's values, fall back to merge's
-        relationship: keep.relationship ?? merge.relationship,
-        responseExpectation: keep.responseExpectation ?? merge.responseExpectation,
-        preferredTone: keep.preferredTone ?? merge.preferredTone,
-        updatedAt: now,
-      })
-      .where(eq(contacts.id, keepId))
-      .run();
-
-    // Move channels from donor to survivor, skipping duplicates
-    const donorChannels = tx
-      .select()
-      .from(contactChannels)
-      .where(eq(contactChannels.contactId, mergeId))
-      .all();
-
-    for (const ch of donorChannels) {
-      const exists = tx
-        .select()
-        .from(contactChannels)
-        .where(
-          and(
-            eq(contactChannels.contactId, keepId),
-            eq(contactChannels.type, ch.type),
-            eq(contactChannels.address, ch.address),
-          ),
-        )
-        .get();
-
-      if (!exists) {
-        tx.update(contactChannels)
-          .set({ contactId: keepId })
-          .where(eq(contactChannels.id, ch.id))
-          .run();
-      }
-    }
-
-    // Delete the donor contact (cascading deletes remaining channels)
-    tx.delete(contacts).where(eq(contacts.id, mergeId)).run();
-  });
-
-  return getContact(keepId)!;
-}
-
-/**
- * Record an interaction with a contact — bumps count and updates timestamp.
- */
-export function recordInteraction(contactId: string): void {
-  const db = getDb();
-  const now = Date.now();
-  const existing = db.select().from(contacts).where(eq(contacts.id, contactId)).get();
-  if (!existing) return;
-
-  db.update(contacts)
-    .set({
-      lastInteraction: now,
-      interactionCount: existing.interactionCount + 1,
-      updatedAt: now,
-    })
-    .where(eq(contacts.id, contactId))
-    .run();
-}
-
-/**
- * Find a contact by a specific channel address. Returns null if not found.
- */
-export function findContactByAddress(type: string, address: string): ContactWithChannels | null {
-  const db = getDb();
-  const channel = db
-    .select()
-    .from(contactChannels)
-    .where(
-      and(
-        eq(contactChannels.type, type),
-        eq(contactChannels.address, address.toLowerCase()),
-      ),
-    )
-    .get();
-
-  if (!channel) return null;
-  return getContact(channel.contactId);
-}

package/src/contacts/index.ts

@@ -1,11 +0,0 @@
-export type { Contact, ContactChannel, ContactWithChannels, ChannelType } from './types.js';
-export { CHANNEL_TYPES } from './types.js';
-export {
-  getContact,
-  upsertContact,
-  searchContacts,
-  listContacts,
-  mergeContacts,
-  recordInteraction,
-  findContactByAddress,
-} from './contact-store.js';

package/src/contacts/types.ts

@@ -1,28 +0,0 @@
-export interface Contact {
-  id: string;
-  displayName: string;
-  relationship: string | null;
-  importance: number;
-  responseExpectation: string | null;
-  preferredTone: string | null;
-  lastInteraction: number | null;
-  interactionCount: number;
-  createdAt: number;
-  updatedAt: number;
-}
-
-export interface ContactChannel {
-  id: string;
-  contactId: string;
-  type: string;       // 'email' | 'slack' | 'whatsapp' | 'phone' | etc.
-  address: string;
-  isPrimary: boolean;
-  createdAt: number;
-}
-
-export interface ContactWithChannels extends Contact {
-  channels: ContactChannel[];
-}
-
-export const CHANNEL_TYPES = ['email', 'slack', 'whatsapp', 'phone', 'telegram', 'discord', 'other'] as const;
-export type ChannelType = (typeof CHANNEL_TYPES)[number];

package/src/context/token-estimator.ts

@@ -1,108 +0,0 @@
-import type { ContentBlock, Message } from '../providers/types.js';
-
-const CHARS_PER_TOKEN = 4;
-const MESSAGE_OVERHEAD_TOKENS = 4;
-const TEXT_BLOCK_OVERHEAD_TOKENS = 2;
-const TOOL_BLOCK_OVERHEAD_TOKENS = 16;
-const IMAGE_BLOCK_TOKENS = 1024;
-const IMAGE_BLOCK_OVERHEAD_TOKENS = 16;
-const FILE_BLOCK_OVERHEAD_TOKENS = 48;
-const OTHER_BLOCK_TOKENS = 16;
-const SYSTEM_PROMPT_OVERHEAD_TOKENS = 8;
-const GEMINI_INLINE_FILE_MIME_TYPES = new Set(['application/pdf']);
-
-export interface TokenEstimatorOptions {
-  providerName?: string;
-}
-
-export function estimateTextTokens(text: string): number {
-  if (text.length === 0) return 0;
-  return Math.ceil(text.length / CHARS_PER_TOKEN);
-}
-
-function shouldCountFileSourceData(block: Extract<ContentBlock, { type: 'file' }>, options?: TokenEstimatorOptions): boolean {
-  if (options?.providerName !== 'gemini') {
-    return false;
-  }
-  return GEMINI_INLINE_FILE_MIME_TYPES.has(block.source.media_type);
-}
-
-function estimateImageSourceDataTokens(
-  block: Extract<ContentBlock, { type: 'image' }>,
-): number {
-  // Image payloads are carried inline as base64 for all currently supported
-  // providers, so estimator must scale with payload size (not fixed per image).
-  return estimateTextTokens(block.source.data);
-}
-
-export function estimateContentBlockTokens(block: ContentBlock, options?: TokenEstimatorOptions): number {
-  switch (block.type) {
-    case 'text':
-      return TEXT_BLOCK_OVERHEAD_TOKENS + estimateTextTokens(block.text);
-    case 'tool_use':
-      return TOOL_BLOCK_OVERHEAD_TOKENS
-        + estimateTextTokens(block.name)
-        + estimateTextTokens(stableJson(block.input));
-    case 'tool_result': {
-      let tokens = TOOL_BLOCK_OVERHEAD_TOKENS
-        + estimateTextTokens(block.tool_use_id)
-        + estimateTextTokens(block.content);
-      if (block.contentBlocks) {
-        for (const cb of block.contentBlocks) {
-          tokens += estimateContentBlockTokens(cb, options);
-        }
-      }
-      return tokens;
-    }
-    case 'image':
-      return Math.max(
-        IMAGE_BLOCK_TOKENS,
-        IMAGE_BLOCK_OVERHEAD_TOKENS
-          + estimateTextTokens(block.source.media_type)
-          + estimateImageSourceDataTokens(block),
-      );
-    case 'file':
-      return FILE_BLOCK_OVERHEAD_TOKENS
-        + estimateTextTokens(block.source.filename)
-        + estimateTextTokens(block.source.media_type)
-        + (shouldCountFileSourceData(block, options) ? estimateTextTokens(block.source.data) : 0)
-        + estimateTextTokens(block.extracted_text ?? '');
-    case 'thinking':
-      return TEXT_BLOCK_OVERHEAD_TOKENS + estimateTextTokens(block.thinking);
-    case 'redacted_thinking':
-      return TEXT_BLOCK_OVERHEAD_TOKENS + estimateTextTokens(block.data);
-    default:
-      return OTHER_BLOCK_TOKENS;
-  }
-}
-
-export function estimateMessageTokens(message: Message, options?: TokenEstimatorOptions): number {
-  let total = MESSAGE_OVERHEAD_TOKENS;
-  for (const block of message.content) {
-    total += estimateContentBlockTokens(block, options);
-  }
-  return total;
-}
-
-export function estimateMessagesTokens(messages: Message[], options?: TokenEstimatorOptions): number {
-  let total = 0;
-  for (const message of messages) {
-    total += estimateMessageTokens(message, options);
-  }
-  return total;
-}
-
-export function estimatePromptTokens(messages: Message[], systemPrompt?: string, options?: TokenEstimatorOptions): number {
-  const systemTokens = systemPrompt
-    ? SYSTEM_PROMPT_OVERHEAD_TOKENS + estimateTextTokens(systemPrompt)
-    : 0;
-  return systemTokens + estimateMessagesTokens(messages, options);
-}
-
-function stableJson(value: unknown): string {
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return '<unserializable />';
-  }
-}

package/src/context/tool-result-truncation.ts

@@ -1,128 +0,0 @@
-import type { ContentBlock, ToolResultContent } from "../providers/types.js";
-
-/**
- * Maximum share of the context window that a single tool result may occupy.
- */
-export const MAX_TOOL_RESULT_CONTEXT_SHARE = 0.3;
-
-/**
- * Absolute cap on tool-result characters (~100K tokens).
- */
-export const HARD_MAX_TOOL_RESULT_CHARS = 400_000;
-
-/**
- * Minimum number of characters to preserve when truncating.
- */
-export const MIN_KEEP_CHARS = 2_000;
-
-/**
- * Suffix appended to truncated tool results.
- */
-export const TRUNCATION_SUFFIX =
-  "\n\n[Content truncated — original exceeded size limit. Use offset/limit parameters or request specific sections for large content.]";
-
-/**
- * Truncate text with newline-boundary awareness.
- *
- * If `text.length <= maxChars`, the text is returned as-is.
- * Otherwise we look for the last newline that falls within 80% of the budget
- * so we get a clean cut. At least `MIN_KEEP_CHARS` characters are always
- * preserved.
- */
-export function truncateToolResultText(
-  text: string,
-  maxChars: number,
-): string {
-  if (text.length <= maxChars) {
-    return text;
-  }
-
-  const effectiveMax = Math.max(maxChars, MIN_KEEP_CHARS);
-  const cutPoint = effectiveMax - TRUNCATION_SUFFIX.length;
-
-  // Look for a newline within the last 20% of the budget for a clean break.
-  const threshold = Math.floor(cutPoint * 0.8);
-  const lastNewline = text.lastIndexOf("\n", cutPoint);
-
-  const sliceEnd =
-    lastNewline >= threshold ? lastNewline : cutPoint;
-
-  // If sliceEnd covers the full text, nothing was actually removed — return
-  // the original text without appending the suffix.
-  if (sliceEnd >= text.length) {
-    return text;
-  }
-
-  return text.slice(0, sliceEnd) + TRUNCATION_SUFFIX;
-}
-
-/**
- * Calculate the maximum allowed characters for a tool result based on the
- * context window size. Uses ~4 chars per token as a rough heuristic.
- */
-export function calculateMaxToolResultChars(
-  contextWindowTokens: number,
-): number {
-  return Math.min(
-    HARD_MAX_TOOL_RESULT_CHARS,
-    Math.floor(contextWindowTokens * MAX_TOOL_RESULT_CONTEXT_SHARE * 4),
-  );
-}
-
-/**
- * Check whether a tool-result content block exceeds the computed character
- * budget for the given context window.
- */
-export function isOversizedToolResult(
-  block: ToolResultContent,
-  contextWindowTokens: number,
-): boolean {
-  if (typeof block.content !== "string") {
-    return false;
-  }
-  const maxChars = calculateMaxToolResultChars(contextWindowTokens);
-  return block.content.length > maxChars;
-}
-
-/**
- * If the tool-result block is oversized, return a shallow copy with its
- * `.content` truncated. Otherwise return the block unchanged.
- */
-export function truncateToolResultBlock(
-  block: ToolResultContent,
-  contextWindowTokens: number,
-): ToolResultContent {
-  const maxChars = calculateMaxToolResultChars(contextWindowTokens);
-  if (block.content.length <= maxChars) {
-    return block;
-  }
-  return {
-    ...block,
-    content: truncateToolResultText(block.content, maxChars),
-  };
-}
-
-/**
- * Map over an array of content blocks, truncating any oversized tool results.
- * Returns a new array and the number of blocks that were truncated.
- */
-export function truncateOversizedToolResults(
-  blocks: ContentBlock[],
-  contextWindowTokens: number,
-): { blocks: ContentBlock[]; truncatedCount: number } {
-  let truncatedCount = 0;
-
-  const mapped = blocks.map((block) => {
-    if (block.type !== "tool_result") {
-      return block;
-    }
-    const toolBlock = block as ToolResultContent;
-    if (isOversizedToolResult(toolBlock, contextWindowTokens)) {
-      truncatedCount++;
-      return truncateToolResultBlock(toolBlock, contextWindowTokens);
-    }
-    return block;
-  });
-
-  return { blocks: mapped, truncatedCount };
-}