@vellumai/assistant 0.3.5 → 0.3.7

package/src/tools/terminal/parser.ts

@@ -36,6 +36,28 @@ export interface ParsedCommand {
 }
 
 const SHELL_PROGRAMS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'fish']);
+// Script interpreters that can execute arbitrary code from stdin — piping
+// untrusted data into these is as dangerous as piping into a shell.
+const SCRIPT_INTERPRETERS = new Set([
+  'python', 'python3', 'ruby', 'perl', 'node', 'deno', 'bun',
+]);
+// Flags that make an interpreter execute code from an inline argument or stdin
+// rather than from a file (e.g. `python -c 'code'`, `node -e 'code'`).
+const STDIN_EXEC_FLAGS = new Set(['-c', '-e', '-']);
+// Per-interpreter flags that consume the next argument as a value (not a filename).
+// Mapped by interpreter name since flags differ across interpreters
+// (e.g. -I is standalone in Python but takes a value in Ruby).
+// Note: `-m` is intentionally excluded — it means "run module", so the next arg
+// is a module name and the interpreter is NOT in stdin-exec mode.
+const INTERPRETER_VALUE_FLAGS: ReadonlyMap<string, ReadonlySet<string>> = new Map([
+  ['python', new Set(['-W', '-X', '-Q'])],
+  ['python3', new Set(['-W', '-X', '-Q'])],
+  ['ruby', new Set(['-r', '--require', '-I'])],
+  ['node', new Set(['-r', '--require', '--import', '--conditions'])],
+  ['deno', new Set()],
+  ['bun', new Set()],
+  ['perl', new Set(['-I'])],
+]);
 const OPAQUE_PROGRAMS = new Set(['eval', 'source', 'alias']);
 const DANGEROUS_ENV_VARS = new Set([
   'LD_PRELOAD', 'LD_LIBRARY_PATH',
@@ -239,6 +261,28 @@ function extractSegments(node: TSNode): CommandSegment[] {
   return segments;
 }
 
+/**
+ * Returns true when the interpreter args indicate stdin-exec mode — i.e. the
+ * interpreter will read code from stdin (or from an inline -c/-e argument)
+ * rather than from a file.  Concretely:
+ *   - Any STDIN_EXEC_FLAGS present → stdin-exec
+ *   - No positional (non-flag) arguments at all → stdin-exec (bare `python`)
+ *   - Otherwise the first positional arg is a filename → NOT stdin-exec
+ */
+function isStdinExecMode(interpreter: string, args: string[]): boolean {
+  const valueFlags = INTERPRETER_VALUE_FLAGS.get(interpreter) ?? new Set<string>();
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (STDIN_EXEC_FLAGS.has(arg)) return true;
+    // First non-flag argument is a filename/module → file mode
+    if (!arg.startsWith('-')) return false;
+    // Flags like -W, -X consume the next token as their value — skip it
+    if (valueFlags.has(arg)) i++;
+  }
+  // No positional arguments at all → interpreter reads from stdin
+  return true;
+}
+
 function detectDangerousPatterns(node: TSNode, segments: CommandSegment[]): DangerousPattern[] {
   const patterns: DangerousPattern[] = [];
 
@@ -251,6 +295,12 @@ function detectDangerousPatterns(node: TSNode, segments: CommandSegment[]): Dang
           description: `Pipeline into ${prog}`,
           text: segments[i].command,
         });
+      } else if (SCRIPT_INTERPRETERS.has(prog) && isStdinExecMode(prog, segments[i].args)) {
+        patterns.push({
+          type: 'pipe_to_shell',
+          description: `Pipeline into ${prog}`,
+          text: segments[i].command,
+        });
       }
     }
   }

package/src/tools/watcher/delete.ts

@@ -1,5 +1,6 @@
 import type { ToolContext, ToolExecutionResult } from '../types.js';
 import { getWatcher, deleteWatcher } from '../../watcher/watcher-store.js';
+import { getWatcherProvider } from '../../watcher/provider-registry.js';
 
 export async function executeWatcherDelete(
   input: Record<string, unknown>,
@@ -20,6 +21,11 @@ export async function executeWatcherDelete(
     return { content: `Error: Failed to delete watcher: ${watcherId}`, isError: true };
   }
 
+  // Evict any in-process provider state (e.g. Linear issue-state cache) now
+  // that the watcher's DB row is gone, so its UUID doesn't leak memory.
+  const provider = getWatcherProvider(watcher.providerId);
+  provider?.cleanup?.(watcherId);
+
   return {
     content: `Watcher deleted: "${watcher.name}"`,
     isError: false,

package/src/tools/weather/service.ts

@@ -219,7 +219,7 @@ function buildWeatherPageHtml(d: WeatherPageInput): string {
     const widthPctC = Math.max(((hc - lc) / cRange) * 100, 3);
     const leftPct = isF ? leftPctF : leftPctC;
     const widthPct = isF ? widthPctF : widthPctC;
-    const precipCell = f.precip !== null && f.precip > 0
+    const precipCell = f.precip != null && f.precip > 0
       ? `<span style="font-size:12px;color:var(--v-accent);width:36px;text-align:right">${f.precip}%</span>`
       : `<span style="width:36px"></span>`;
     return `<div style="display:flex;align-items:center;gap:8px;padding:8px 0;border-bottom:1px solid var(--v-surface-border)">` +

package/src/twitter/client.ts

@@ -8,6 +8,7 @@ import {
   loadSession,
   type TwitterSession,
 } from './session.js';
+import { ProviderError } from '../util/errors.js';
 
 const CDP_BASE = 'http://localhost:9222';
 
@@ -325,17 +326,182 @@ async function graphqlGet(queryId: string, queryName: string, variables: Record<
   const url = graphqlUrl(queryId, queryName, variables);
   const json = await cdpGet(wsUrl, url) as { errors?: Array<{ message: string }> };
   if (json.errors?.length) {
-    throw new Error(`X API errors: ${json.errors.map(e => e.message).join('; ')}`);
+    throw new ProviderError(`X API errors: ${json.errors.map(e => e.message).join('; ')}`, 'x');
   }
   return json;
 }
 
-// ─── Tweet extraction helpers ────────────────────────────────────────────────
+// ─── Twitter API response types ──────────────────────────────────────────────
+
+interface TwitterUserLegacy {
+  screen_name?: string;
+  name?: string;
+}
+
+interface TwitterUserCore {
+  screen_name?: string;
+  name?: string;
+}
+
+interface TwitterUserResult {
+  rest_id?: string;
+  legacy?: TwitterUserLegacy;
+  core?: TwitterUserCore;
+}
+
+interface TwitterUserResults {
+  result?: TwitterUserResult;
+}
+
+interface TweetLegacy {
+  full_text?: string;
+  created_at?: string;
+}
+
+interface TweetResult {
+  __typename?: string;
+  rest_id?: string;
+  legacy?: TweetLegacy;
+  core?: { user_results?: TwitterUserResults };
+  tweet?: TweetResult;
+}
+
+interface TweetResults {
+  result?: TweetResult;
+}
+
+interface TimelineItemContent {
+  __typename?: string;
+  tweet_results?: TweetResults;
+  user_results?: TwitterUserResults;
+  // Notification-specific fields
+  id?: string;
+  rich_message?: { text?: string };
+  notification_text?: { text?: string };
+  timestamp_ms?: string;
+  notification_url?: { url?: string };
+}
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type AnyJson = any;
+interface TimelineModuleItem {
+  item?: { itemContent?: TimelineItemContent };
+}
+
+interface TimelineEntryContent {
+  itemContent?: TimelineItemContent;
+  items?: TimelineModuleItem[];
+}
+
+interface TimelineEntry {
+  entryId?: string;
+  content?: TimelineEntryContent;
+}
+
+interface TimelineInstruction {
+  entries?: TimelineEntry[];
+}
+
+interface TimelineContainer {
+  instructions?: TimelineInstruction[];
+}
+
+interface TimelineWrapper {
+  timeline?: TimelineContainer;
+}
+
+interface TwitterApiError {
+  message: string;
+}
+
+/** Response from CreateTweet mutation. */
+interface CreateTweetResponse {
+  errors?: TwitterApiError[];
+  data?: {
+    create_tweet?: {
+      tweet_results?: TweetResults;
+    };
+  };
+}
+
+/** Response from UserByScreenName query. */
+interface UserByScreenNameResponse {
+  data?: {
+    user?: {
+      result?: TwitterUserResult;
+    };
+  };
+}
+
+/** Response from UserTweets query. */
+interface UserTweetsResponse {
+  data?: {
+    user?: {
+      result?: {
+        timeline_v2?: TimelineWrapper;
+        timeline?: TimelineWrapper;
+      };
+    };
+  };
+}
+
+/** Response from TweetDetail query. */
+interface TweetDetailResponse {
+  data?: {
+    threaded_conversation_with_injections_v2?: TimelineContainer;
+  };
+}
+
+/** Response from SearchTimeline query. */
+interface SearchTimelineResponse {
+  data?: {
+    search_by_raw_query?: {
+      search_timeline?: TimelineWrapper;
+    };
+  };
+}
+
+/** Response from Bookmarks query. */
+interface BookmarksResponse {
+  data?: {
+    bookmark_timeline_v2?: TimelineWrapper;
+  };
+}
+
+/** Response from HomeTimeline query. */
+interface HomeTimelineResponse {
+  data?: {
+    home?: {
+      home_timeline_urt?: TimelineContainer;
+    };
+  };
+}
+
+/** Response from NotificationsTimeline query. */
+interface NotificationsTimelineResponse {
+  data?: {
+    viewer_v2?: {
+      user_results?: {
+        result?: {
+          notification_timeline?: TimelineWrapper;
+        };
+      };
+    };
+  };
+}
+
+/** Response from Likes / Following / Followers / UserMedia queries. */
+interface UserTimelineResponse {
+  data?: {
+    user?: {
+      result?: {
+        timeline?: TimelineWrapper;
+      };
+    };
+  };
+}
+
+// ─── Tweet extraction helpers ────────────────────────────────────────────────
 
-function extractScreenName(tweetResult: AnyJson): string {
+function extractScreenName(tweetResult: TweetResult): string {
   return (
     tweetResult?.core?.user_results?.result?.legacy?.screen_name ??
     tweetResult?.core?.user_results?.result?.core?.screen_name ??
@@ -344,7 +510,7 @@ function extractScreenName(tweetResult: AnyJson): string {
 }
 
 /** Extract tweets from a timeline instructions array (shared by most endpoints). */
-function extractTweetsFromInstructions(instructions: AnyJson[]): TweetEntry[] {
+function extractTweetsFromInstructions(instructions: TimelineInstruction[]): TweetEntry[] {
   const tweets: TweetEntry[] = [];
   for (const instruction of instructions) {
     // Handle both array-style entries and direct entries
@@ -386,7 +552,7 @@ function extractTweetsFromInstructions(instructions: AnyJson[]): TweetEntry[] {
 }
 
 /** Extract users from a timeline instructions array (Followers/Following). */
-function extractUsersFromInstructions(instructions: AnyJson[]): UserInfo[] {
+function extractUsersFromInstructions(instructions: TimelineInstruction[]): UserInfo[] {
   const users: UserInfo[] = [];
   for (const instruction of instructions) {
     for (const entry of instruction.entries ?? []) {
@@ -460,19 +626,19 @@ export async function postTweet(text: string, opts?: { inReplyToTweetId?: string
     queryId: QUERY_IDS.CreateTweet,
   });
 
-  const json = (await cdpFetch(wsUrl, url, body)) as AnyJson;
+  const json = (await cdpFetch(wsUrl, url, body)) as CreateTweetResponse;
 
   if (json.errors?.length) {
-    throw new Error(`X API errors: ${json.errors.map((e: AnyJson) => e.message).join('; ')}`);
+    throw new ProviderError(`X API errors: ${json.errors.map(e => e.message).join('; ')}`, 'x');
   }
 
   const tweetResults = json.data?.create_tweet?.tweet_results;
   const result = tweetResults?.result;
   if (!result?.rest_id) {
     if (tweetResults && !result) {
-      throw new Error('X rejected this post — it may be a duplicate of a recent post. Try different text.');
+      throw new ProviderError('X rejected this post — it may be a duplicate of a recent post. Try different text.', 'x');
     }
-    throw new Error(`Unexpected response from X API. Response: ${JSON.stringify(json).slice(0, 500)}`);
+    throw new ProviderError(`Unexpected response from X API. Response: ${JSON.stringify(json).slice(0, 500)}`, 'x');
   }
 
   return {
@@ -488,11 +654,11 @@ export async function getUserByScreenName(screenName: string): Promise<UserInfo>
   const json = await graphqlGet(QUERY_IDS.UserByScreenName, 'UserByScreenName', {
     screen_name: screenName,
     withGrokTranslatedBio: true,
-  }) as AnyJson;
+  }) as UserByScreenNameResponse;
 
   const user = json.data?.user?.result;
   if (!user?.rest_id) {
-    throw new Error(`User @${screenName} not found`);
+    throw new ProviderError(`User @${screenName} not found`, 'x');
   }
 
   return {
@@ -511,7 +677,7 @@ export async function getUserTweets(userId: string, count = 20): Promise<TweetEn
     includePromotedContent: true,
     withQuickPromoteEligibilityTweetFields: true,
     withVoice: true,
-  }) as AnyJson;
+  }) as UserTweetsResponse;
 
   // Response path: data.user.result.timeline_v2.timeline.instructions[]
   // Fallback to data.user.result.timeline.timeline.instructions[]
@@ -533,7 +699,7 @@ export async function getTweetDetail(tweetId: string): Promise<TweetEntry[]> {
     withQuickPromoteEligibilityTweetFields: true,
     withBirdwatchNotes: true,
     withVoice: true,
-  }) as AnyJson;
+  }) as TweetDetailResponse;
 
   // Response path: data.threaded_conversation_with_injections_v2.instructions[]
   const instructions = json.data?.threaded_conversation_with_injections_v2?.instructions ?? [];
@@ -553,7 +719,7 @@ export async function searchTweets(
   // to the search page and capture the response from network events.
   const productParam = product === 'Top' ? '' : `&f=${product.toLowerCase()}`;
   const pageUrl = `https://x.com/search?q=${encodeURIComponent(query)}&src=typed_query${productParam}`;
-  const json = await cdpNavigateAndCapture(wsUrl, pageUrl, 'SearchTimeline') as AnyJson;
+  const json = await cdpNavigateAndCapture(wsUrl, pageUrl, 'SearchTimeline') as SearchTimelineResponse;
 
   const instructions = json.data?.search_by_raw_query?.search_timeline?.timeline?.instructions ?? [];
   return extractTweetsFromInstructions(instructions);
@@ -565,7 +731,7 @@ export async function getBookmarks(count = 20): Promise<TweetEntry[]> {
   const json = await graphqlGet(QUERY_IDS.Bookmarks, 'Bookmarks', {
     count,
     includePromotedContent: true,
-  }) as AnyJson;
+  }) as BookmarksResponse;
 
   // Response path: data.bookmark_timeline_v2.timeline.instructions[]
   const instructions = json.data?.bookmark_timeline_v2?.timeline?.instructions ?? [];
@@ -580,7 +746,7 @@ export async function getHomeTimeline(count = 20): Promise<TweetEntry[]> {
     includePromotedContent: true,
     requestContext: 'launch',
     withCommunity: true,
-  }) as AnyJson;
+  }) as HomeTimelineResponse;
 
   // Response path: data.home.home_timeline_urt.instructions[]
   const instructions = json.data?.home?.home_timeline_urt?.instructions ?? [];
@@ -593,7 +759,7 @@ export async function getNotifications(count = 20): Promise<NotificationEntry[]>
   const json = await graphqlGet(QUERY_IDS.NotificationsTimeline, 'NotificationsTimeline', {
     timeline_type: 'All',
     count,
-  }) as AnyJson;
+  }) as NotificationsTimelineResponse;
 
   // Response path: data.viewer_v2.user_results.result.notification_timeline.timeline.instructions[]
   const instructions =
@@ -625,7 +791,7 @@ export async function getLikes(userId: string, count = 20): Promise<TweetEntry[]
     withClientEventToken: false,
     withBirdwatchNotes: false,
     withVoice: true,
-  }) as AnyJson;
+  }) as UserTimelineResponse;
 
   // Response path: data.user.result.timeline.timeline.instructions[]
   const instructions = json.data?.user?.result?.timeline?.timeline?.instructions ?? [];
@@ -640,7 +806,7 @@ export async function getFollowers(userId: string, screenName?: string): Promise
   if (screenName) {
     requireSession();
     const wsUrl = await findTwitterTab();
-    const json = await cdpNavigateAndCapture(wsUrl, `https://x.com/${screenName}/followers`, 'Followers') as AnyJson;
+    const json = await cdpNavigateAndCapture(wsUrl, `https://x.com/${screenName}/followers`, 'Followers') as UserTimelineResponse;
     const instructions = json.data?.user?.result?.timeline?.timeline?.instructions ?? [];
     return extractUsersFromInstructions(instructions);
   }
@@ -650,7 +816,7 @@ export async function getFollowers(userId: string, screenName?: string): Promise
     count: 20,
     includePromotedContent: false,
     withGrokTranslatedBio: false,
-  }) as AnyJson;
+  }) as UserTimelineResponse;
 
   const instructions = json.data?.user?.result?.timeline?.timeline?.instructions ?? [];
   return extractUsersFromInstructions(instructions);
@@ -664,7 +830,7 @@ export async function getFollowing(userId: string, count = 20): Promise<UserInfo
     count,
     includePromotedContent: false,
     withGrokTranslatedBio: false,
-  }) as AnyJson;
+  }) as UserTimelineResponse;
 
   // Response path: data.user.result.timeline.timeline.instructions[]
   const instructions = json.data?.user?.result?.timeline?.timeline?.instructions ?? [];
@@ -681,7 +847,7 @@ export async function getUserMedia(userId: string, count = 20): Promise<TweetEnt
     withClientEventToken: false,
     withBirdwatchNotes: false,
     withVoice: true,
-  }) as AnyJson;
+  }) as UserTimelineResponse;
 
   // Response path: data.user.result.timeline.timeline.instructions[]
   // (same as Likes — contains tweets that have media)

package/src/twitter/session.ts

@@ -6,6 +6,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { getDataDir } from '../util/platform.js';
+import { ConfigError } from '../util/errors.js';
 import type { SessionRecording, ExtractedCredential } from '../tools/browser/network-recording-types.js';
 
 export interface TwitterSession {
@@ -50,17 +51,17 @@ export function clearSession(): void {
  */
 export function importFromRecording(recordingPath: string): TwitterSession {
   if (!existsSync(recordingPath)) {
-    throw new Error(`Recording not found: ${recordingPath}`);
+    throw new ConfigError(`Recording not found: ${recordingPath}`);
   }
   const recording = JSON.parse(readFileSync(recordingPath, 'utf-8')) as SessionRecording;
   if (!recording.cookies?.length) {
-    throw new Error('Recording contains no cookies');
+    throw new ConfigError('Recording contains no cookies');
   }
   // Require the two cookies that prove a logged-in Twitter session:
   // the auth session cookie and the ct0 CSRF cookie.
   const cookieNames = new Set(recording.cookies.map(c => c.name));
   if (!cookieNames.has('ct0') || !cookieNames.has(`auth_${'token'}`)) {
-    throw new Error(
+    throw new ConfigError(
       'Recording is missing required Twitter session cookies. ' +
       'Make sure you are logged in to x.com before recording.',
     );

package/src/util/clipboard.ts

@@ -25,7 +25,7 @@ export function extractLastCodeBlock(text: string): string | null {
   const re = /```[^\n]*\n((?:[\s\S]*?\n)?)```/g;
   let last: RegExpExecArray | null = null;
   let m: RegExpExecArray | null;
-  while ((m = re.exec(text)) !== null) {
+  while ((m = re.exec(text)) != null) {
     last = m;
   }
   if (!last) return null;

package/src/util/errors.ts

@@ -33,7 +33,71 @@ export enum ErrorCode {
   INTERNAL_ERROR = 'INTERNAL_ERROR',
 }
 
-export class AssistantError extends Error {
+// ── Root ──────────────────────────────────────────────────────────────────────
+
+/** Root base class for all named Vellum errors. */
+export class VellumError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'VellumError';
+  }
+}
+
+// ── Backend errors ────────────────────────────────────────────────────────────
+
+/**
+ * Errors originating from infrastructure or external service calls.
+ * Catch this when you want to handle any backend failure uniformly.
+ */
+export class BackendError extends VellumError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'BackendError';
+  }
+}
+
+/**
+ * The embedding or vector-search backend is not configured or not reachable.
+ * Thrown before attempting an embedding operation so callers can skip or defer.
+ */
+export class BackendUnavailableError extends BackendError {
+  constructor(reason: string) {
+    super(reason);
+    this.name = 'BackendUnavailableError';
+  }
+}
+
+/**
+ * A request or token-budget quota was exceeded.
+ * Thrown by the provider rate-limiter and by domain-specific clients (e.g. DoorDash).
+ */
+export class RateLimitError extends BackendError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RateLimitError';
+  }
+}
+
+// ── User errors ───────────────────────────────────────────────────────────────
+
+/**
+ * Errors caused by user input, policy violations, or user-facing constraints.
+ * Catch this when you want to present an actionable message to the user.
+ */
+export class UserError extends VellumError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'UserError';
+  }
+}
+
+// ── AssistantError subtree ────────────────────────────────────────────────────
+
+/**
+ * Base class for errors originating from assistant logic (providers, tools,
+ * permissions, config). Extends VellumError and carries a structured ErrorCode.
+ */
+export class AssistantError extends VellumError {
   constructor(
     message: string,
     public readonly code: ErrorCode,
@@ -111,13 +175,6 @@ export class IntegrityError extends AssistantError {
   }
 }
 
-export class RateLimitError extends AssistantError {
-  constructor(message: string) {
-    super(message, ErrorCode.RATE_LIMIT_ERROR);
-    this.name = 'RateLimitError';
-  }
-}
-
 export class IngressBlockedError extends AssistantError {
   constructor(
     message: string,

package/src/util/fs.ts

@@ -0,0 +1,40 @@
+/**
+ * Centralized filesystem helpers — single source of truth for common
+ * existence-check and stat patterns scattered across the codebase.
+ *
+ * Modules should import from here instead of using raw existsSync/statSync
+ * from 'node:fs' for these patterns.
+ */
+
+import { existsSync, mkdirSync, readFileSync, statSync, type Stats } from 'node:fs';
+
+/** Check whether a path (file or directory) exists on disk. */
+export function pathExists(path: string): boolean {
+  return existsSync(path);
+}
+
+/** Create a directory (and parents) if it doesn't already exist. */
+export function ensureDir(dir: string): void {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/** Read a UTF-8 text file, returning null if it doesn't exist or is unreadable. */
+export function readTextFileSync(path: string): string | null {
+  try {
+    if (!existsSync(path)) return null;
+    return readFileSync(path, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/** Get file stats, returning null if the path doesn't exist or is inaccessible. */
+export function safeStatSync(path: string): Stats | null {
+  try {
+    return statSync(path);
+  } catch {
+    return null;
+  }
+}

package/src/util/json.ts

@@ -0,0 +1,10 @@
+/**
+ * Parse JSON without throwing — returns null on failure.
+ */
+export function parseJsonSafe<T = unknown>(text: string): T | null {
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    return null;
+  }
+}