vellum 0.2.0 → 0.2.2

package/src/tools/browser/x-auto-navigate.ts

@@ -0,0 +1,207 @@
+/**
+ * CDP-based auto-navigation for X.com.
+ *
+ * Drives Chrome through key X.com pages to trigger GraphQL API calls,
+ * so the NetworkRecorder captures the full API surface without manual browsing.
+ */
+
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('x-auto-navigate');
+
+const CDP_BASE = 'http://localhost:9222';
+
+interface NavStep {
+  label: string;
+  url?: string;
+  clickSelector?: string;
+}
+
+/** Minimal CDP client — connects to one page tab. */
+class MiniCDP {
+  private ws: WebSocket | null = null;
+  private nextId = 1;
+  private callbacks = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+
+  async connect(wsUrl: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(wsUrl);
+      ws.onopen = () => { this.ws = ws; resolve(); };
+      ws.onerror = (e) => reject(new Error(`CDP error: ${e}`));
+      ws.onclose = () => { this.ws = null; };
+      ws.onmessage = (event) => {
+        const msg = JSON.parse(String(event.data));
+        if (msg.id != null) {
+          const cb = this.callbacks.get(msg.id);
+          if (cb) {
+            this.callbacks.delete(msg.id);
+            msg.error ? cb.reject(new Error(msg.error.message)) : cb.resolve(msg.result);
+          }
+        }
+      };
+    });
+  }
+
+  async send(method: string, params?: Record<string, unknown>): Promise<unknown> {
+    if (!this.ws) throw new Error('Not connected');
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      this.callbacks.set(id, { resolve, reject });
+      this.ws!.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  close() { this.ws?.close(); }
+}
+
+/**
+ * Navigate Chrome through X.com pages to trigger GraphQL calls.
+ * The NetworkRecorder should already be attached and capturing.
+ *
+ * @param abortSignal Optional signal to stop navigation early.
+ * @returns List of step labels that completed successfully.
+ */
+export async function navigateXPages(abortSignal?: { aborted: boolean }): Promise<string[]> {
+  let wsUrl: string | null = null;
+  try {
+    const res = await fetch(`${CDP_BASE}/json/list`);
+    if (!res.ok) {
+      log.warn('CDP not available for auto-navigation');
+      return [];
+    }
+    const targets = (await res.json()) as Array<{ type: string; url: string; webSocketDebuggerUrl: string }>;
+    const xTab = targets.find(
+      t => t.type === 'page' && (t.url.includes('x.com') || t.url.includes('twitter.com')),
+    );
+    wsUrl = xTab?.webSocketDebuggerUrl ?? targets.find(t => t.type === 'page')?.webSocketDebuggerUrl ?? null;
+  } catch (err) {
+    log.warn({ err }, 'Failed to discover Chrome tabs');
+    return [];
+  }
+
+  if (!wsUrl) {
+    log.warn('No Chrome tab found for auto-navigation');
+    return [];
+  }
+
+  const cdp = new MiniCDP();
+  try {
+    await cdp.connect(wsUrl);
+  } catch (err) {
+    log.warn({ err }, 'Failed to connect CDP for auto-navigation');
+    return [];
+  }
+
+  await cdp.send('Page.enable').catch(() => {});
+  const completed: string[] = [];
+
+  // Navigate to home first to discover the screen name
+  try {
+    await cdp.send('Page.navigate', { url: 'https://x.com/home' });
+    await sleep(3000);
+  } catch (err) {
+    log.warn({ err }, 'Failed to navigate to home');
+    cdp.close();
+    return [];
+  }
+
+  // Resolve screen name for profile-based URLs
+  let screenName: string | null = null;
+  try {
+    const result = await cdp.send('Runtime.evaluate', {
+      expression: `
+        (function() {
+          const link = document.querySelector('a[data-testid="AppTabBar_Profile_Link"]');
+          if (link) return link.getAttribute('href')?.replace('/', '') ?? null;
+          return null;
+        })()
+      `,
+      awaitPromise: false,
+      returnByValue: true,
+    }) as { result?: { value?: string | null } };
+    screenName = result?.result?.value ?? null;
+  } catch { /* ignore */ }
+
+  log.info({ screenName }, 'Detected screen name');
+
+  // Build steps with resolved URLs
+  const steps: NavStep[] = [
+    { label: 'Home timeline', url: 'https://x.com/home' },
+    { label: 'Profile', clickSelector: 'a[data-testid="AppTabBar_Profile_Link"]' },
+    { label: 'Tweet detail', clickSelector: 'article[data-testid="tweet"] a[href*="/status/"]' },
+    { label: 'Search', url: 'https://x.com/search?q=hello&src=typed_query' },
+    { label: 'Bookmarks', url: 'https://x.com/i/bookmarks' },
+    { label: 'Notifications', url: 'https://x.com/notifications' },
+  ];
+
+  // Add profile-based URLs if we have the screen name
+  if (screenName) {
+    steps.push(
+      { label: 'Likes', url: `https://x.com/${screenName}/likes` },
+      { label: 'Followers', url: `https://x.com/${screenName}/followers` },
+      { label: 'Following', url: `https://x.com/${screenName}/following` },
+      { label: 'Media', url: `https://x.com/${screenName}/media` },
+    );
+  }
+
+  for (const step of steps) {
+    if (abortSignal?.aborted) break;
+
+    log.info({ step: step.label }, 'Auto-navigate step starting');
+
+    try {
+      if (step.url) {
+        await cdp.send('Page.navigate', { url: step.url });
+        await sleep(3000);
+      }
+
+      if (step.clickSelector) {
+        await sleep(1500);
+        await clickInPage(cdp, step.clickSelector);
+        await sleep(2000);
+      }
+
+      // Scroll to trigger lazy-loaded content
+      await cdp.send('Runtime.evaluate', {
+        expression: 'window.scrollBy(0, 800)',
+        awaitPromise: false,
+      }).catch(() => {});
+
+      await sleep(2000);
+
+      completed.push(step.label);
+      log.info({ step: step.label }, 'Auto-navigate step completed');
+    } catch (err) {
+      log.warn({ err, step: step.label }, 'Auto-navigate step failed');
+    }
+  }
+
+  cdp.close();
+  log.info({ completed: completed.length, total: steps.length }, 'Auto-navigation finished');
+  return completed;
+}
+
+async function clickInPage(cdp: MiniCDP, selector: string): Promise<boolean> {
+  try {
+    const result = await cdp.send('Runtime.evaluate', {
+      expression: `
+        (function() {
+          const el = document.querySelector(${JSON.stringify(selector)});
+          if (!el) return false;
+          el.scrollIntoView({ block: 'center' });
+          el.click();
+          return true;
+        })()
+      `,
+      awaitPromise: false,
+      returnByValue: true,
+    }) as { result?: { value?: boolean } };
+    return result?.result?.value === true;
+  } catch {
+    return false;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(r => setTimeout(r, ms));
+}

package/src/tools/calls/call-end.ts

@@ -0,0 +1,67 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { registerTool } from '../registry.js';
+import { cancelCall } from '../../calls/call-domain.js';
+
+const definition: ToolDefinition = {
+  name: 'call_end',
+  description: 'End an active phone call',
+  input_schema: {
+    type: 'object',
+    properties: {
+      call_session_id: {
+        type: 'string',
+        description: 'The call session ID to end',
+      },
+      reason: {
+        type: 'string',
+        description: 'Reason for ending the call',
+      },
+    },
+    required: ['call_session_id'],
+  },
+};
+
+class CallEndTool implements Tool {
+  name = 'call_end';
+  description = definition.description;
+  category = 'communication';
+  defaultRiskLevel = RiskLevel.Medium;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const callSessionId = input.call_session_id as string | undefined;
+    if (!callSessionId || typeof callSessionId !== 'string') {
+      return { content: 'Error: call_session_id is required and must be a string', isError: true };
+    }
+
+    const reason = input.reason as string | undefined;
+
+    const result = await cancelCall({ callSessionId, reason });
+
+    if (!result.ok) {
+      // If the call already ended, report it as a non-error for the tool
+      if (result.status === 409) {
+        return { content: result.error, isError: false };
+      }
+      return { content: `Error: ${result.error}`, isError: true };
+    }
+
+    const lines = [
+      'Call ended successfully.',
+      `  Call Session ID: ${callSessionId}`,
+      `  Status: cancelled`,
+    ];
+    if (reason) {
+      lines.push(`  Reason: ${reason}`);
+    }
+
+    return { content: lines.join('\n'), isError: false };
+  }
+}
+
+registerTool(new CallEndTool());

package/src/tools/calls/call-start.ts

@@ -0,0 +1,73 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { registerTool } from '../registry.js';
+import { startCall } from '../../calls/call-domain.js';
+import { getConfig } from '../../config/loader.js';
+
+const definition: ToolDefinition = {
+  name: 'call_start',
+  description:
+    'Place an outbound phone call via AI voice. The assistant will converse with the callee on behalf of the user.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      phone_number: {
+        type: 'string',
+        description: 'E.164 formatted phone number (e.g. +14155551234)',
+      },
+      task: {
+        type: 'string',
+        description: 'What the call should accomplish',
+      },
+      context: {
+        type: 'string',
+        description: 'Additional context for the conversation',
+      },
+    },
+    required: ['phone_number', 'task'],
+  },
+};
+
+class CallStartTool implements Tool {
+  name = 'call_start';
+  description = definition.description;
+  category = 'communication';
+  defaultRiskLevel = RiskLevel.High;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    if (!getConfig().calls.enabled) {
+      return { content: 'Error: Calls feature is disabled via configuration. Set calls.enabled to true to use this feature.', isError: true };
+    }
+
+    const result = await startCall({
+      phoneNumber: input.phone_number as string,
+      task: input.task as string,
+      context: input.context as string | undefined,
+      conversationId: context.conversationId,
+    });
+
+    if (!result.ok) {
+      return { content: `Error: ${result.error}`, isError: true };
+    }
+
+    return {
+      content: [
+        'Call initiated successfully.',
+        `  Call Session ID: ${result.session.id}`,
+        `  Call SID: ${result.callSid}`,
+        `  To: ${result.session.toNumber}`,
+        `  Status: initiated`,
+        '',
+        'The AI voice assistant is now placing the call. Use call_status to check progress.',
+      ].join('\n'),
+      isError: false,
+    };
+  }
+}
+
+registerTool(new CallStartTool());

package/src/tools/calls/call-status.ts

@@ -0,0 +1,81 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { registerTool } from '../registry.js';
+import { getCallStatus } from '../../calls/call-domain.js';
+
+const definition: ToolDefinition = {
+  name: 'call_status',
+  description: 'Check the status of an active or recent phone call',
+  input_schema: {
+    type: 'object',
+    properties: {
+      call_session_id: {
+        type: 'string',
+        description: 'Specific call session ID to check. If omitted, checks for an active call in the current conversation.',
+      },
+    },
+    required: [],
+  },
+};
+
+class CallStatusTool implements Tool {
+  name = 'call_status';
+  description = definition.description;
+  category = 'communication';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return definition;
+  }
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    const callSessionId = input.call_session_id as string | undefined;
+
+    const result = getCallStatus(callSessionId, context.conversationId);
+
+    if (!result.ok) {
+      // When no active call is found and no specific ID was requested, it's not an error
+      if (!callSessionId && result.error === 'No active call found in the current conversation') {
+        return { content: result.error, isError: false };
+      }
+      return { content: `Error: ${result.error}`, isError: true };
+    }
+
+    const { session } = result;
+    const lines = [
+      `Call Session: ${session.id}`,
+      `  Status: ${session.status}`,
+      `  To: ${session.toNumber}`,
+      `  From: ${session.fromNumber}`,
+    ];
+
+    if (session.providerCallSid) {
+      lines.push(`  Call SID: ${session.providerCallSid}`);
+    }
+
+    if (session.task) {
+      lines.push(`  Task: ${session.task}`);
+    }
+
+    if (session.startedAt) {
+      const durationMs = (session.endedAt ?? Date.now()) - session.startedAt;
+      const durationSec = Math.round(durationMs / 1000);
+      lines.push(`  Duration: ${durationSec}s`);
+    }
+
+    if (session.lastError) {
+      lines.push(`  Last Error: ${session.lastError}`);
+    }
+
+    if (result.pendingQuestion) {
+      lines.push('');
+      lines.push(`  Pending Question: ${result.pendingQuestion.questionText}`);
+      lines.push(`  Question ID: ${result.pendingQuestion.id}`);
+    }
+
+    return { content: lines.join('\n'), isError: false };
+  }
+}
+
+registerTool(new CallStatusTool());

package/src/tools/claude-code/claude-code.ts

@@ -3,6 +3,7 @@ import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
 import type { ToolDefinition } from '../../providers/types.js';
 import { getConfig } from '../../config/loader.js';
 import { getLogger } from '../../util/logger.js';
+import { truncate } from '../../util/truncate.js';
 import { getProfilePolicy } from '../../swarm/worker-backend.js';
 import type { WorkerProfile } from '../../swarm/worker-backend.js';
 
@@ -22,6 +23,11 @@ const APPROVAL_REQUIRED_TOOLS = new Set([
 
 const VALID_PROFILES: readonly WorkerProfile[] = ['general', 'researcher', 'coder', 'reviewer'];
 
+// Maximum nesting depth for Claude Code subprocesses.
+// Depth 0 = top-level assistant, depth 1 = first subprocess, etc.
+const MAX_CLAUDE_CODE_DEPTH = 1;
+const DEPTH_ENV_VAR = 'VELLUM_CLAUDE_CODE_DEPTH';
+
 export const claudeCodeTool: Tool = {
   name: 'claude_code',
   description: 'Delegate a coding task to Claude Code, an AI-powered coding agent that can read, write, and edit files, run shell commands, and perform complex multi-step software engineering tasks autonomously.',
@@ -108,7 +114,10 @@ export const claudeCodeTool: Tool = {
 
     const { query } = sdkModule;
 
-    log.info({ prompt: prompt.slice(0, 100), workingDir, model, resume: !!resumeSessionId }, 'Starting Claude Code session');
+    // Collect stderr output from the Claude Code subprocess for debugging
+    const stderrLines: string[] = [];
+
+    log.info({ prompt: truncate(prompt, 100, ''), workingDir, model, resume: !!resumeSessionId }, 'Starting Claude Code session');
 
     // Build the canUseTool callback, enforcing profile-based restrictions
     const canUseTool: import('@anthropic-ai/claude-agent-sdk').CanUseTool = async (toolName, toolInput, _options) => {
@@ -151,6 +160,26 @@ export const claudeCodeTool: Tool = {
       }
     };
 
+    // Enforce nesting depth limit to prevent infinite recursion.
+    const currentDepth = parseInt(process.env[DEPTH_ENV_VAR] ?? '0', 10);
+    if (currentDepth >= MAX_CLAUDE_CODE_DEPTH) {
+      log.warn({ currentDepth, max: MAX_CLAUDE_CODE_DEPTH }, 'Claude Code nesting depth exceeded');
+      return {
+        content: `Error: Claude Code nesting depth exceeded (depth ${currentDepth}, max ${MAX_CLAUDE_CODE_DEPTH}). Cannot spawn another Claude Code subprocess.`,
+        isError: true,
+      };
+    }
+
+    // Build a clean env for the subprocess. Strip the SDK's own nesting guard
+    // (CLAUDECODE) so it can launch, but set our depth counter to enforce our limit.
+    const subprocessEnv: Record<string, string | undefined> = {
+      ...process.env,
+      ANTHROPIC_API_KEY: apiKey,
+      [DEPTH_ENV_VAR]: String(currentDepth + 1),
+    };
+    delete subprocessEnv.CLAUDECODE;
+    delete subprocessEnv.CLAUDE_CODE_ENTRYPOINT;
+
     // Build query options
     const queryOptions: import('@anthropic-ai/claude-agent-sdk').Options = {
       cwd: workingDir,
@@ -158,12 +187,16 @@ export const claudeCodeTool: Tool = {
       canUseTool,
       permissionMode: 'default',
       allowedTools: [...AUTO_APPROVE_TOOLS],
-      env: {
-        ...process.env,
-        ANTHROPIC_API_KEY: apiKey,
-      },
+      env: subprocessEnv,
       maxTurns: 50,
       persistSession: true,
+      stderr: (data: string) => {
+        const trimmed = data.trimEnd();
+        if (trimmed) {
+          stderrLines.push(trimmed);
+          log.debug({ stderr: trimmed }, 'Claude Code subprocess stderr');
+        }
+      },
     };
 
     if (resumeSessionId) {
@@ -179,6 +212,12 @@ export const claudeCodeTool: Tool = {
       for await (const message of conversation) {
         switch (message.type) {
           case 'assistant': {
+            // Check for SDK-level errors on the assistant message
+            if (message.error) {
+              log.error({ error: message.error, sessionId: message.session_id }, 'Claude Code assistant message error');
+              hasError = true;
+              resultText += `\n\n[Claude Code error: ${message.error}]`;
+            }
             // Extract text from assistant messages
             if (message.message?.content) {
               for (const block of message.message.content) {
@@ -193,22 +232,43 @@ export const claudeCodeTool: Tool = {
           }
           case 'result': {
             sessionId = message.session_id;
+            const resultMeta = {
+              subtype: message.subtype,
+              numTurns: message.num_turns,
+              durationMs: message.duration_ms,
+              costUsd: message.total_cost_usd,
+              stopReason: message.stop_reason,
+            };
+
             if (message.subtype === 'success') {
+              log.info(resultMeta, 'Claude Code session completed successfully');
               if (message.result && !resultText) {
                 resultText = message.result;
               }
             } else {
-              // Error result
+              // Error result — surface the subtype and details
               hasError = true;
               const errors = message.errors ?? [];
+              const denials = message.permission_denials ?? [];
+
+              log.error({ ...resultMeta, errors, permissionDenials: denials.length }, 'Claude Code session failed');
+
+              const parts: string[] = [];
+              parts.push(`[${message.subtype}] (${message.num_turns} turns, ${(message.duration_ms / 1000).toFixed(1)}s)`);
               if (errors.length > 0) {
-                resultText += `\n\nErrors: ${errors.join(', ')}`;
+                parts.push(`Errors: ${errors.join('; ')}`);
+              }
+              if (denials.length > 0) {
+                const denialSummary = denials.map(d => `${d.tool_name}`).join(', ');
+                parts.push(`Permission denied: ${denialSummary}`);
               }
+              resultText += `\n\n${parts.join('\n')}`;
             }
             break;
           }
           default:
-            // Ignore other message types (system, stream_event, etc.)
+            // Log unhandled message types at debug level for diagnostics
+            log.debug({ messageType: message.type }, 'Claude Code unhandled message type');
             break;
         }
       }
@@ -221,10 +281,16 @@ export const claudeCodeTool: Tool = {
         isError: hasError,
       };
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      log.error({ err }, 'Claude Code execution failed');
+      const errMessage = err instanceof Error ? err.message : String(err);
+      const recentStderr = stderrLines.slice(-20);
+      log.error({ err, stderrTail: recentStderr }, 'Claude Code execution failed');
+
+      const parts = [`Claude Code error: ${errMessage}`];
+      if (recentStderr.length > 0) {
+        parts.push(`\nSubprocess stderr (last ${recentStderr.length} lines):\n${recentStderr.join('\n')}`);
+      }
       return {
-        content: `Claude Code error: ${message}`,
+        content: parts.join(''),
         isError: true,
       };
     }