vellum 0.2.14 → 0.3.2

package/src/util/pricing.ts

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

@@ -1,37 +0,0 @@
-/**
- * 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

@@ -1,98 +0,0 @@
-/**
- * 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

@@ -1,51 +0,0 @@
-/**
- * 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

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

@@ -1,6 +0,0 @@
-/** 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

@@ -1,4 +0,0 @@
-/** 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

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

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

@@ -1,199 +0,0 @@
-/**
- * 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

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

@@ -1,48 +0,0 @@
-/** 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>;
-}