@vellumai/assistant 0.3.0

package/src/util/pricing.ts

@@ -0,0 +1,150 @@
+import type { PricingResult } from '../usage/types.js';
+import type { ModelPricingOverride } from '../config/schema.js';
+
+interface ModelPricing {
+  inputPer1M: number;  // USD per 1M input tokens
+  outputPer1M: number; // USD per 1M output tokens
+}
+
+/**
+ * Multi-provider pricing catalog keyed by provider then model pattern.
+ * Model patterns are matched by exact match first, then by prefix.
+ */
+const PROVIDER_PRICING: Record<string, Record<string, ModelPricing>> = {
+  anthropic: {
+    'claude-opus-4': { inputPer1M: 15, outputPer1M: 75 },
+    'claude-opus-4-6-fast': { inputPer1M: 30, outputPer1M: 150 },
+    'claude-sonnet-4': { inputPer1M: 3, outputPer1M: 15 },
+    'claude-haiku-4': { inputPer1M: 0.80, outputPer1M: 4 },
+  },
+  openai: {
+    'gpt-4o': { inputPer1M: 2.50, outputPer1M: 10 },
+    'gpt-4o-mini': { inputPer1M: 0.15, outputPer1M: 0.60 },
+    'gpt-4.1': { inputPer1M: 2.00, outputPer1M: 8.00 },
+    'gpt-4.1-mini': { inputPer1M: 0.40, outputPer1M: 1.60 },
+    'gpt-4.1-nano': { inputPer1M: 0.10, outputPer1M: 0.40 },
+    'o3': { inputPer1M: 2.00, outputPer1M: 8.00 },
+    'o3-mini': { inputPer1M: 1.10, outputPer1M: 4.40 },
+    'o3-pro': { inputPer1M: 20, outputPer1M: 80 },
+    'o4-mini': { inputPer1M: 1.10, outputPer1M: 4.40 },
+  },
+  gemini: {
+    'gemini-2.5-pro': { inputPer1M: 1.25, outputPer1M: 10 },
+    'gemini-2.5-flash': { inputPer1M: 0.15, outputPer1M: 0.60 },
+    'gemini-2.0-flash': { inputPer1M: 0.10, outputPer1M: 0.40 },
+  },
+  fireworks: {
+    'accounts/fireworks/models/kimi-k2p5': { inputPer1M: 0.60, outputPer1M: 3.00 },
+  },
+};
+
+/**
+ * Look up pricing for a model within a provider's catalog.
+ * Tries exact match first, then longest prefix match.
+ */
+function findPricing(catalog: Record<string, ModelPricing>, model: string): ModelPricing | undefined {
+  // Exact match
+  if (catalog[model]) return catalog[model];
+
+  // Prefix match: find the longest matching prefix
+  let bestMatch: ModelPricing | undefined;
+  let bestLen = 0;
+  for (const [pattern, pricing] of Object.entries(catalog)) {
+    if (model.startsWith(pattern) && pattern.length > bestLen) {
+      bestMatch = pricing;
+      bestLen = pattern.length;
+    }
+  }
+  return bestMatch;
+}
+
+/**
+ * Calculate cost from pricing and token counts.
+ */
+function calculateCost(pricing: ModelPricing, inputTokens: number, outputTokens: number): number {
+  return (inputTokens / 1_000_000) * pricing.inputPer1M
+       + (outputTokens / 1_000_000) * pricing.outputPer1M;
+}
+
+/**
+ * Resolve pricing for a provider/model combination using the built-in catalog.
+ * Returns a PricingResult with explicit priced/unpriced status.
+ */
+export function resolvePricing(
+  provider: string,
+  model: string,
+  inputTokens: number,
+  outputTokens: number,
+): PricingResult {
+  const providerCatalog = PROVIDER_PRICING[provider];
+  if (!providerCatalog) {
+    return { estimatedCostUsd: null, pricingStatus: 'unpriced' };
+  }
+
+  const pricing = findPricing(providerCatalog, model);
+  if (!pricing) {
+    return { estimatedCostUsd: null, pricingStatus: 'unpriced' };
+  }
+
+  return {
+    estimatedCostUsd: calculateCost(pricing, inputTokens, outputTokens),
+    pricingStatus: 'priced',
+  };
+}
+
+/**
+ * Resolve pricing with optional custom model overrides checked first.
+ * Overrides are matched by provider (exact) and modelPattern (prefix match).
+ * Falls back to the built-in catalog if no override matches.
+ */
+export function resolvePricingWithOverrides(
+  provider: string,
+  model: string,
+  inputTokens: number,
+  outputTokens: number,
+  overrides?: ModelPricingOverride[],
+): PricingResult {
+  if (overrides && overrides.length > 0) {
+    // Find matching overrides for this provider, use longest modelPattern prefix match
+    let bestOverride: ModelPricingOverride | undefined;
+    let bestLen = 0;
+    for (const override of overrides) {
+      if (override.provider !== provider) continue;
+      // Exact match or prefix match on modelPattern
+      if (model === override.modelPattern || model.startsWith(override.modelPattern)) {
+        if (override.modelPattern.length > bestLen) {
+          bestOverride = override;
+          bestLen = override.modelPattern.length;
+        }
+      }
+    }
+    if (bestOverride) {
+      const cost = calculateCost(
+        { inputPer1M: bestOverride.inputPer1M, outputPer1M: bestOverride.outputPer1M },
+        inputTokens,
+        outputTokens,
+      );
+      return { estimatedCostUsd: cost, pricingStatus: 'priced' };
+    }
+  }
+
+  return resolvePricing(provider, model, inputTokens, outputTokens);
+}
+
+/**
+ * Estimate cost in USD for the given token counts, provider, and model.
+ * Returns 0 if the provider/model combination is not in the pricing table
+ * (e.g. Ollama local models).
+ */
+export function estimateCost(
+  inputTokens: number,
+  outputTokens: number,
+  model: string,
+  provider: string,
+): number {
+  const result = resolvePricing(provider, model, inputTokens, outputTokens);
+  if (result.pricingStatus === 'priced' && result.estimatedCostUsd !== null) {
+    return result.estimatedCostUsd;
+  }
+  return 0;
+}

package/src/util/promise-guard.ts

@@ -0,0 +1,37 @@
+/**
+ * Guards against concurrent execution of an async factory.
+ * Multiple concurrent callers share the same in-flight promise.
+ * On failure, the guard resets so subsequent calls can retry.
+ */
+export class PromiseGuard<T> {
+  private promise: Promise<T> | null = null;
+
+  /** Whether a promise is currently in-flight. */
+  get active(): boolean {
+    return this.promise !== null;
+  }
+
+  /**
+   * Execute the factory, deduplicating concurrent calls.
+   * If a call is already in-flight, returns the same promise.
+   * On failure, clears the cached promise to allow retry.
+   *
+   * @param factory - Creates the promise on first call.
+   * @param onError - Optional callback invoked when the factory rejects (before re-throwing).
+   */
+  run(factory: () => Promise<T>, onError?: (err: unknown) => void): Promise<T> {
+    if (this.promise) return this.promise;
+
+    this.promise = factory();
+    this.promise.catch((err) => {
+      this.promise = null;
+      onError?.(err);
+    });
+    return this.promise;
+  }
+
+  /** Reset the guard, allowing the next call to create a new promise. */
+  reset(): void {
+    this.promise = null;
+  }
+}

package/src/util/retry.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared retry utilities with exponential backoff + jitter.
+ *
+ * Used by both the provider retry layer (exception-based) and the
+ * web-search tool layer (HTTP response-based).
+ */
+
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BASE_DELAY_MS = 1000;
+
+export interface RetryOptions {
+  /** Maximum number of retry attempts (default 3). */
+  maxRetries?: number;
+  /** Base delay in ms for exponential backoff (default 1000). */
+  baseDelayMs?: number;
+}
+
+/**
+ * Compute a retry delay with equal jitter: guaranteed floor of cap/2
+ * plus random in [0, cap/2]. Prevents retry storms while ensuring
+ * retries never collapse to 0ms.
+ */
+export function computeRetryDelay(attempt: number, baseDelayMs = DEFAULT_BASE_DELAY_MS): number {
+  const cap = baseDelayMs * Math.pow(2, attempt);
+  const half = cap / 2;
+  return half + Math.random() * half;
+}
+
+/**
+ * Parse a Retry-After header value into milliseconds.
+ * RFC 7231 allows either delta-seconds (e.g. "120") or an HTTP-date
+ * (e.g. "Tue, 17 Feb 2026 12:00:00 GMT"). Returns undefined if unparseable.
+ */
+export function parseRetryAfterMs(value: string): number | undefined {
+  const seconds = Number(value);
+  if (!isNaN(seconds)) {
+    return seconds * 1000;
+  }
+  // Try HTTP-date format — Date.parse handles RFC 2822 / IMF-fixdate
+  const dateMs = Date.parse(value);
+  if (!isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+  return undefined;
+}
+
+/**
+ * Determine the retry delay for an HTTP response. Uses the Retry-After
+ * header if present, otherwise falls back to exponential backoff with jitter.
+ */
+export function getHttpRetryDelay(
+  response: Response,
+  attempt: number,
+  baseDelayMs = DEFAULT_BASE_DELAY_MS,
+): number {
+  const retryAfter = response.headers.get('retry-after');
+  if (retryAfter) {
+    const parsed = parseRetryAfterMs(retryAfter);
+    if (parsed !== undefined) return parsed;
+  }
+  // Enforce a minimum floor of baseDelayMs when Retry-After is missing.
+  // computeRetryDelay uses equal jitter (cap/2 + random*cap/2) which can
+  // dip to ~500ms on attempt 0 — too aggressive for 429 rate limits.
+  return Math.max(baseDelayMs, computeRetryDelay(attempt, baseDelayMs));
+}
+
+/**
+ * Whether an HTTP status code is retryable (429 or 5xx).
+ */
+export function isRetryableStatus(status: number): boolean {
+  return status === 429 || status >= 500;
+}
+
+/**
+ * Whether an error is a retryable network error (ECONNRESET, ECONNREFUSED, etc.).
+ * Checks both the error itself and one level of `cause` chain.
+ */
+export function isRetryableNetworkError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+
+  const retryableCodes = new Set(['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EPIPE']);
+
+  const code = (error as NodeJS.ErrnoException).code;
+  if (code && retryableCodes.has(code)) return true;
+
+  if (error.cause instanceof Error) {
+    const causeCode = (error.cause as NodeJS.ErrnoException).code;
+    if (causeCode && retryableCodes.has(causeCode)) return true;
+  }
+
+  return false;
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export { DEFAULT_MAX_RETRIES, DEFAULT_BASE_DELAY_MS };

package/src/util/spinner.ts

@@ -0,0 +1,51 @@
+/**
+ * Terminal spinner with elapsed time display.
+ * Renders to stderr so it doesn't interfere with stdout content.
+ * Silently no-ops when stderr is not a TTY (e.g. redirected to file).
+ */
+
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+export class Spinner {
+  private message = '';
+  private startTime = 0;
+  private frameIndex = 0;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private active = false;
+
+  get isSpinning(): boolean {
+    return this.active;
+  }
+
+  start(message: string): void {
+    if (!process.stderr.isTTY) return;
+    this.stop();
+    this.message = message;
+    this.startTime = Date.now();
+    this.frameIndex = 0;
+    this.active = true;
+    this.render();
+    this.timer = setInterval(() => this.render(), 80);
+  }
+
+  stop(): void {
+    if (!this.active) return;
+    this.active = false;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    // Clear the spinner line
+    process.stderr.write('\r\x1b[K');
+  }
+
+  private render(): void {
+    const frame = FRAMES[this.frameIndex % FRAMES.length];
+    this.frameIndex++;
+    const elapsed = Math.floor((Date.now() - this.startTime) / 1000);
+    const timeStr = elapsed > 0 ? ` (${elapsed}s)` : '';
+    process.stderr.write(`\r\x1b[K${DIM}${frame} ${this.message}${timeStr}${RESET}`);
+  }
+}

package/src/util/time.ts

@@ -0,0 +1,16 @@
+export function timeAgo(timestamp: number): string {
+  const seconds = Math.floor((Date.now() - timestamp) / 1000);
+  if (seconds < 60) return 'just now';
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days === 1) return 'yesterday';
+  if (days < 14) return `${days}d ago`;
+  const weeks = Math.floor(days / 7);
+  if (weeks < 8) return `${weeks}w ago`;
+  const date = new Date(timestamp);
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  return `${months[date.getMonth()]} ${date.getDate()}`;
+}

package/src/util/truncate.ts

@@ -0,0 +1,6 @@
+/** Truncate a string to `maxLen` characters, appending `suffix` if truncated. */
+export function truncate(str: string, maxLen: number, suffix = '...'): string {
+  if (str.length <= maxLen) return str;
+  if (maxLen < suffix.length) return str.slice(0, maxLen);
+  return str.slice(0, maxLen - suffix.length) + suffix;
+}

package/src/util/xml.ts

@@ -0,0 +1,4 @@
+/** Escape a string for safe inclusion in an XML/HTML attribute (double-quoted). */
+export function escapeXmlAttr(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}

package/src/version.ts

@@ -0,0 +1,3 @@
+// Version is embedded at compile time via --define in CI.
+// Falls back to "0.0.0-dev" for local development.
+export const APP_VERSION: string = process.env.APP_VERSION ?? "0.0.0-dev";

package/src/watcher/constants.ts

@@ -0,0 +1,11 @@
+/** Default poll interval for watchers (60 seconds). */
+export const DEFAULT_POLL_INTERVAL_MS = 60_000;
+
+/** Base delay for exponential backoff on consecutive errors. */
+export const BACKOFF_BASE_MS = 30_000;
+
+/** Maximum backoff delay (1 hour). */
+export const MAX_BACKOFF_MS = 60 * 60 * 1000;
+
+/** Disable watcher after this many consecutive errors. */
+export const MAX_CONSECUTIVE_ERRORS = 5;

package/src/watcher/engine.ts

@@ -0,0 +1,199 @@
+/**
+ * Watcher engine — core polling loop that runs inside the scheduler tick.
+ *
+ * Claims due watchers, fetches new events from providers, stores them,
+ * and processes pending events through a background LLM conversation.
+ */
+
+import { getLogger } from '../util/logger.js';
+import { createConversation } from '../memory/conversation-store.js';
+import { getWatcherProvider } from './provider-registry.js';
+import {
+  claimDueWatchers,
+  completeWatcherPoll,
+  failWatcherPoll,
+  disableWatcher,
+  insertWatcherEvent,
+  getPendingEvents,
+  updateEventDisposition,
+  resetStuckWatchers,
+  setWatcherConversationId,
+} from './watcher-store.js';
+import { MAX_CONSECUTIVE_ERRORS } from './constants.js';
+
+const log = getLogger('watcher-engine');
+
+export type WatcherMessageProcessor = (
+  conversationId: string,
+  message: string,
+) => Promise<unknown>;
+
+export type WatcherNotifier = (notification: {
+  title: string;
+  body: string;
+}) => void;
+
+export type WatcherEscalator = (params: {
+  title: string;
+  body: string;
+}) => void;
+
+export interface WatcherEngineHandle {
+  runOnce(): Promise<number>;
+  stop(): void;
+}
+
+/**
+ * Initialize the watcher engine. Call once at daemon startup.
+ * Resets any watchers stuck in 'polling' state from a prior crash.
+ */
+export function initWatcherEngine(): void {
+  const reset = resetStuckWatchers();
+  if (reset > 0) {
+    log.info({ count: reset }, 'Reset stuck watchers to idle on startup');
+  }
+}
+
+/**
+ * Run one watcher tick: claim due watchers, fetch events, process them.
+ * Called from the scheduler's runScheduleOnce().
+ */
+export async function runWatchersOnce(
+  processMessage: WatcherMessageProcessor,
+  notify: WatcherNotifier,
+  _escalate: WatcherEscalator,
+): Promise<number> {
+  const now = Date.now();
+  let processed = 0;
+
+  // ── Phase 1: Poll providers for new events ──────────────────────
+  const claimed = claimDueWatchers(now);
+  for (const watcher of claimed) {
+    const provider = getWatcherProvider(watcher.providerId);
+    if (!provider) {
+      failWatcherPoll(watcher.id, `Unknown provider: ${watcher.providerId}`);
+      continue;
+    }
+
+    try {
+      const config = watcher.configJson ? JSON.parse(watcher.configJson) : {};
+
+      // Initialize watermark on first poll
+      let watermark = watcher.watermark;
+      if (!watermark) {
+        watermark = await provider.getInitialWatermark(watcher.credentialService);
+        log.info({ watcherId: watcher.id, watermark }, 'Initialized watermark');
+      }
+
+      const result = await provider.fetchNew(watcher.credentialService, watermark, config);
+
+      // Store new events with dedup
+      let newEvents = 0;
+      for (const item of result.items) {
+        const inserted = insertWatcherEvent({
+          watcherId: watcher.id,
+          externalId: item.externalId,
+          eventType: item.eventType,
+          summary: item.summary,
+          payloadJson: JSON.stringify(item.payload),
+        });
+        if (inserted) newEvents++;
+      }
+
+      if (newEvents > 0) {
+        log.info({ watcherId: watcher.id, name: watcher.name, newEvents }, 'Detected new events');
+      }
+
+      completeWatcherPoll(watcher.id, {
+        watermark: result.watermark,
+        conversationId: watcher.conversationId ?? undefined,
+      });
+      processed++;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.warn({ err, watcherId: watcher.id, name: watcher.name }, 'Watcher poll failed');
+      failWatcherPoll(watcher.id, message);
+
+      // Circuit breaker: disable after too many consecutive errors
+      if ((watcher.consecutiveErrors + 1) >= MAX_CONSECUTIVE_ERRORS) {
+        const reason = `Disabled after ${MAX_CONSECUTIVE_ERRORS} consecutive errors. Last: ${message}`;
+        disableWatcher(watcher.id, reason);
+        log.warn({ watcherId: watcher.id, name: watcher.name }, 'Watcher disabled by circuit breaker');
+        notify({
+          title: `Watcher disabled: ${watcher.name}`,
+          body: reason,
+        });
+      }
+    }
+  }
+
+  // ── Phase 2: Process pending events through LLM ─────────────────
+  // Process events for all watchers that have pending events,
+  // not just the ones we just polled.
+  for (const watcher of claimed) {
+    const pendingEvents = getPendingEvents(watcher.id);
+    if (pendingEvents.length === 0) continue;
+
+    try {
+      // Get or create a background conversation for this watcher
+      let conversationId = watcher.conversationId;
+      if (!conversationId) {
+        const conv = createConversation({
+          title: `Watcher: ${watcher.name}`,
+          threadType: 'background' as 'standard' | 'private',
+        });
+        conversationId = conv.id;
+        setWatcherConversationId(watcher.id, conversationId);
+      }
+
+      // Build the LLM message with action prompt + event data
+      const eventSummaries = pendingEvents.map((e, i) =>
+        `Event ${i + 1} (id: ${e.id}):\n  Type: ${e.eventType}\n  Summary: ${e.summary}\n  Data: ${e.payloadJson}`,
+      ).join('\n\n');
+
+      const message = [
+        watcher.actionPrompt,
+        '',
+        '---',
+        '',
+        `${pendingEvents.length} new event(s) detected:`,
+        '',
+        eventSummaries,
+        '',
+        '---',
+        '',
+        'For each event, decide how to handle it and include a disposition block:',
+        '<watcher-disposition>',
+        '{"event_id": "...", "disposition": "silent|notify|escalate", "action": "what you did", "title": "notification title", "body": "notification body"}',
+        '</watcher-disposition>',
+        '',
+        'You may include multiple disposition blocks, one per event.',
+      ].join('\n');
+
+      await processMessage(conversationId, message);
+
+      // Parse dispositions from the conversation
+      // For now, mark events as processed. The LLM response handler
+      // would ideally parse <watcher-disposition> blocks, but since
+      // processMessage is async and we don't get the response text back,
+      // we'll mark events as silent by default and let the LLM use
+      // tools to notify/escalate as needed.
+      for (const event of pendingEvents) {
+        // Default to silent if we can't parse the LLM response
+        updateEventDisposition(event.id, 'silent', 'Processed by LLM');
+      }
+
+      processed++;
+    } catch (err) {
+      log.warn({ err, watcherId: watcher.id }, 'Failed to process watcher events');
+      for (const event of pendingEvents) {
+        updateEventDisposition(event.id, 'error', err instanceof Error ? err.message : String(err));
+      }
+    }
+  }
+
+  if (processed > 0) {
+    log.info({ processed }, 'Watcher tick complete');
+  }
+  return processed;
+}

package/src/watcher/provider-registry.ts

@@ -0,0 +1,15 @@
+import type { WatcherProvider } from './provider-types.js';
+
+const providers = new Map<string, WatcherProvider>();
+
+export function registerWatcherProvider(provider: WatcherProvider): void {
+  providers.set(provider.id, provider);
+}
+
+export function getWatcherProvider(id: string): WatcherProvider | undefined {
+  return providers.get(id);
+}
+
+export function listWatcherProviders(): WatcherProvider[] {
+  return Array.from(providers.values());
+}

package/src/watcher/provider-types.ts

@@ -0,0 +1,48 @@
+/** A single event detected by a watcher provider. */
+export interface WatcherItem {
+  /** Provider-specific dedup key (e.g. Gmail message ID). */
+  externalId: string;
+  /** Event category (e.g. 'new_email'). */
+  eventType: string;
+  /** One-line human-readable summary. */
+  summary: string;
+  /** Full event data for LLM processing. */
+  payload: Record<string, unknown>;
+  /** When the event occurred (epoch ms). */
+  timestamp: number;
+}
+
+/** Result of a provider fetch call. */
+export interface FetchResult {
+  items: WatcherItem[];
+  /** Opaque cursor for the next fetch. */
+  watermark: string;
+}
+
+/**
+ * A watcher provider adapts an external API into the watcher system.
+ * Each provider knows how to poll for new events and track its position.
+ */
+export interface WatcherProvider {
+  /** Unique provider key (e.g. 'gmail', 'stripe'). */
+  id: string;
+  /** Human-readable name. */
+  displayName: string;
+  /** Credential service required (e.g. 'integration:gmail'). */
+  requiredCredentialService: string;
+
+  /**
+   * Fetch new events since the given watermark.
+   * Returns new items and an updated watermark.
+   */
+  fetchNew(
+    credentialService: string,
+    watermark: string | null,
+    config: Record<string, unknown>,
+  ): Promise<FetchResult>;
+
+  /**
+   * Get the initial watermark (start from "now" so we don't replay history).
+   */
+  getInitialWatermark(credentialService: string): Promise<string>;
+}