@vellumai/assistant 0.3.0

package/src/contacts/contact-store.ts

@@ -0,0 +1,410 @@
+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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,28 @@
+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

@@ -0,0 +1,108 @@
+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

@@ -0,0 +1,128 @@
+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 };
+}