@vellumai/assistant 0.3.3 → 0.3.5

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

@@ -10,9 +10,9 @@ import { getLogger } from '../../util/logger.js';
 const log = getLogger('auto-navigate');
 
 const CDP_BASE = 'http://localhost:9222';
-const MAX_PAGES = 15;
-const PAGE_WAIT_MS = 3500;
-const SCROLL_WAIT_MS = 2000;
+const MAX_PAGES = 10;
+const PAGE_WAIT_MS = 2500;
+const SCROLL_WAIT_MS = 1000;
 
 /** Minimal CDP client — connects to one page tab. */
 class MiniCDP {
@@ -57,15 +57,28 @@ class MiniCDP {
   close() { this.ws?.close(); }
 }
 
+export interface AutoNavProgress {
+  type: 'visiting' | 'discovered' | 'done';
+  url?: string;
+  pageNumber?: number;
+  totalDiscovered?: number;
+  visitedCount?: number;
+}
+
 /**
  * Navigate Chrome through a domain's pages to trigger API calls.
  * Discovers internal links from the DOM and visits up to ~15 unique paths.
  *
  * @param domain The domain to crawl (e.g. "example.com").
  * @param abortSignal Optional signal to stop navigation early.
+ * @param onProgress Optional callback for live progress updates.
  * @returns List of visited page URLs.
  */
-export async function autoNavigate(domain: string, abortSignal?: { aborted: boolean }): Promise<string[]> {
+export async function autoNavigate(
+  domain: string,
+  abortSignal?: { aborted: boolean },
+  onProgress?: (p: AutoNavProgress) => void,
+): Promise<string[]> {
   let wsUrl: string | null = null;
   try {
     const res = await fetch(`${CDP_BASE}/json/list`);
@@ -108,6 +121,7 @@ export async function autoNavigate(domain: string, abortSignal?: { aborted: bool
 
   // Navigate to the domain root first
   try {
+    onProgress?.({ type: 'visiting', url: rootUrl, pageNumber: 1 });
     await cdp.send('Page.navigate', { url: rootUrl });
     await sleep(PAGE_WAIT_MS);
     visited.add('/');
@@ -125,12 +139,11 @@ export async function autoNavigate(domain: string, abortSignal?: { aborted: bool
   await scrollPage(cdp);
   await sleep(SCROLL_WAIT_MS);
 
-  // Click common interactive elements on the root page
-  await clickInteractiveElements(cdp);
-  await sleep(SCROLL_WAIT_MS);
-
   // Discover internal links from the current page
-  const discoveredLinks = await discoverInternalLinks(cdp, domain);
+  let discoveredLinks = await discoverInternalLinks(cdp, domain);
+  // Sort links: deeper paths first (more likely to be content pages), skip shallow nav links
+  discoveredLinks = rankLinks(discoveredLinks);
+  onProgress?.({ type: 'discovered', totalDiscovered: discoveredLinks.length });
   log.info({ count: discoveredLinks.length }, 'Discovered internal links from root');
 
   // Visit discovered pages
@@ -140,6 +153,7 @@ export async function autoNavigate(domain: string, abortSignal?: { aborted: bool
     if (visited.has(link.key)) continue;
 
     const url = link.url;
+    onProgress?.({ type: 'visiting', url, pageNumber: visited.size + 1, totalDiscovered: discoveredLinks.length });
     log.info({ url }, 'Auto-navigate visiting page');
 
     try {
@@ -152,9 +166,9 @@ export async function autoNavigate(domain: string, abortSignal?: { aborted: bool
       await scrollPage(cdp);
       await sleep(SCROLL_WAIT_MS);
 
-      // Click interactive elements to trigger more API calls
-      await clickInteractiveElements(cdp);
-      await sleep(1500);
+      // Click tabs/buttons within the page (NOT nav links — those navigate away)
+      await clickPageTabs(cdp);
+      await sleep(800);
 
       // Discover more links from this page
       const newLinks = await discoverInternalLinks(cdp, domain);
@@ -171,6 +185,7 @@ export async function autoNavigate(domain: string, abortSignal?: { aborted: bool
   }
 
   cdp.close();
+  onProgress?.({ type: 'done', visitedCount: visitedUrls.length, totalDiscovered: discoveredLinks.length });
   log.info({ visited: visitedUrls.length, total: discoveredLinks.length + 1 }, 'Auto-navigation finished');
   return visitedUrls;
 }
@@ -180,6 +195,56 @@ interface DiscoveredLink {
   url: string;
   /** Deduplication key: origin + pathname. */
   key: string;
+  /** Path depth (number of segments). */
+  depth: number;
+}
+
+/** Paths that are typically navigation chrome, not content pages. */
+const SKIP_PATHS = [
+  '/home', '/login', '/signup', '/register', '/sign-up', '/sign-in',
+  '/help', '/support', '/contact', '/about', '/terms', '/privacy',
+  '/careers', '/press', '/blog', '/faq', '/sitemap',
+];
+
+/** Path patterns that indicate high-value purchase/content flows. */
+const HIGH_VALUE_PATTERNS = [
+  /\/orders/i, /\/cart/i, /\/checkout/i, /\/account/i, /\/settings/i,
+  /\/store\//i, /\/restaurant\//i, /\/menu/i, /\/payment/i,
+  /\/profile/i, /\/history/i, /\/favorites/i, /\/saved/i,
+  /\/search/i, /\/category/i, /\/collection/i,
+];
+
+/** Sort links to prioritize purchase/content flows, deduplicate by pattern. */
+function rankLinks(links: DiscoveredLink[]): DiscoveredLink[] {
+  const filtered = links.filter(l => {
+    const path = new URL(l.url).pathname.toLowerCase();
+    if (SKIP_PATHS.some(skip => path === skip || path === skip + '/')) return false;
+    return true;
+  });
+
+  // Deduplicate by host+path pattern — keep only one of /store/123, /store/456
+  // but preserve different subdomains (shop.example.com vs admin.example.com)
+  const byPattern = new Map<string, DiscoveredLink>();
+  for (const link of filtered) {
+    const parsed = new URL(link.url);
+    // Collapse numeric/hash segments to find the pattern
+    const pathPattern = parsed.pathname.replace(/\/\d+/g, '/{id}').replace(/\/[a-f0-9]{8,}/gi, '/{id}');
+    const pattern = parsed.hostname + pathPattern;
+    if (!byPattern.has(pattern)) {
+      byPattern.set(pattern, link);
+    }
+  }
+
+  return [...byPattern.values()].sort((a, b) => {
+    const aPath = new URL(a.url).pathname.toLowerCase();
+    const bPath = new URL(b.url).pathname.toLowerCase();
+    // High-value paths first
+    const aHighValue = HIGH_VALUE_PATTERNS.some(p => p.test(aPath)) ? 1 : 0;
+    const bHighValue = HIGH_VALUE_PATTERNS.some(p => p.test(bPath)) ? 1 : 0;
+    if (aHighValue !== bHighValue) return bHighValue - aHighValue;
+    // Then by depth (deeper = more specific)
+    return Math.min(b.depth, 4) - Math.min(a.depth, 4);
+  });
 }
 
 /** Extract internal links from the current page DOM, preserving subdomains. */
@@ -204,7 +269,11 @@ async function discoverInternalLinks(cdp: MiniCDP, domain: string): Promise<Disc
               const key = url.origin + url.pathname;
               if (!seen.has(key)) {
                 seen.add(key);
-                links.push({ url: url.origin + url.pathname, key });
+                links.push({
+                  url: url.origin + url.pathname,
+                  key,
+                  depth: path.split('/').filter(Boolean).length,
+                });
               }
             } catch { /* skip malformed URLs */ }
           }
@@ -222,25 +291,64 @@ async function discoverInternalLinks(cdp: MiniCDP, domain: string): Promise<Disc
 
 /** Scroll the page to trigger lazy-loaded content. */
 async function scrollPage(cdp: MiniCDP): Promise<void> {
-  await cdp.send('Runtime.evaluate', {
-    expression: 'window.scrollBy(0, 800)',
-    awaitPromise: false,
-  }).catch(() => {});
+  // Scroll in increments to trigger multiple lazy-load thresholds
+  for (let i = 0; i < 3; i++) {
+    await cdp.send('Runtime.evaluate', {
+      expression: 'window.scrollBy(0, 600)',
+      awaitPromise: false,
+    }).catch(() => {});
+    await sleep(500);
+  }
 }
 
-/** Click common interactive elements (tabs, nav buttons) to trigger API calls. */
-async function clickInteractiveElements(cdp: MiniCDP): Promise<void> {
+/**
+ * Click tabs, buttons, and flow-relevant elements within the current page.
+ * Avoids clicking navigation links (which would navigate away).
+ */
+async function clickPageTabs(cdp: MiniCDP): Promise<void> {
   const selectors = [
-    'nav a:not([href="/"])',
-    '[role="tab"]',
-    '[role="tablist"] button',
+    '[role="tab"]:not(:first-child)',
+    '[role="tablist"] button:not(:first-child)',
     'button[data-tab]',
-    '.tab, .nav-tab, .nav-link',
+    '[data-testid*="tab"]',
+    'button[aria-expanded="false"]',
   ];
 
   for (const selector of selectors) {
     await clickInPage(cdp, selector);
-    await sleep(800);
+    await sleep(600);
+  }
+
+  // Also try clicking purchase-flow buttons to trigger API calls
+  // (Add to Cart, etc. — these fire API requests even if we don't complete the flow)
+  await clickByText(cdp, 'Add to Cart');
+  await clickByText(cdp, 'Add to Order');
+  await clickByText(cdp, 'Add Item');
+}
+
+/** Click a button by its visible text content. */
+async function clickByText(cdp: MiniCDP, text: string): Promise<boolean> {
+  try {
+    const result = await cdp.send('Runtime.evaluate', {
+      expression: `
+        (function() {
+          const buttons = document.querySelectorAll('button, [role="button"]');
+          for (const btn of buttons) {
+            if (btn.textContent && btn.textContent.trim().toLowerCase().includes(${JSON.stringify(text.toLowerCase())})) {
+              btn.scrollIntoView({ block: 'center' });
+              btn.click();
+              return true;
+            }
+          }
+          return false;
+        })()
+      `,
+      awaitPromise: false,
+      returnByValue: true,
+    }) as { result?: { value?: boolean } };
+    return result?.result?.value === true;
+  } catch {
+    return false;
   }
 }
 

package/src/tools/browser/browser-manager.ts

@@ -191,74 +191,80 @@ class BrowserManager {
     if (this.contextCreating) return this.contextCreating;
 
     this.contextCreating = (async () => {
-      // Try to detect or negotiate CDP before falling back to headless.
-      // This auto-detects an existing Chrome with --remote-debugging-port,
-      // or asks the client to restart Chrome with CDP enabled.
-      let useCdp = this._browserMode === 'cdp';
-      const sender = invokingSessionId ? this.sessionSenders.get(invokingSessionId) : undefined;
-      if (!useCdp) {
-        const cdpAvailable = await this.detectCDP();
-        if (cdpAvailable) {
-          useCdp = true;
-        } else if (invokingSessionId && sender) {
-          log.info({ sessionId: invokingSessionId }, 'Requesting CDP from client');
-          const accepted = await this.requestCDPFromClient(invokingSessionId, sender);
-          if (accepted) {
-            const nowAvailable = await this.detectCDP();
-            if (nowAvailable) {
-              useCdp = true;
+      // Deterministic test mode: when launch is injected via setLaunchFn,
+      // bypass ambient CDP probing/negotiation and use the injected launcher.
+      const hasInjectedLaunchFn = launchPersistentContext !== null;
+
+      if (!hasInjectedLaunchFn) {
+        // Try to detect or negotiate CDP before falling back to headless.
+        // This auto-detects an existing Chrome with --remote-debugging-port,
+        // or asks the client to restart Chrome with CDP enabled.
+        let useCdp = this._browserMode === 'cdp';
+        const sender = invokingSessionId ? this.sessionSenders.get(invokingSessionId) : undefined;
+        if (!useCdp) {
+          const cdpAvailable = await this.detectCDP();
+          if (cdpAvailable) {
+            useCdp = true;
+          } else if (invokingSessionId && sender) {
+            log.info({ sessionId: invokingSessionId }, 'Requesting CDP from client');
+            const accepted = await this.requestCDPFromClient(invokingSessionId, sender);
+            if (accepted) {
+              const nowAvailable = await this.detectCDP();
+              if (nowAvailable) {
+                useCdp = true;
+              } else {
+                log.warn('Client accepted CDP request but CDP not detected');
+              }
             } else {
-              log.warn('Client accepted CDP request but CDP not detected');
+              log.info('Client declined CDP request');
             }
-          } else {
-            log.info('Client declined CDP request');
           }
         }
-      }
 
-      if (useCdp) {
-        try {
-          const pw = await import('playwright');
-          const browser = await pw.chromium.connectOverCDP(this.cdpUrl, { timeout: 10_000 });
-          this.cdpBrowser = browser;
-          this._browserLaunched = false;
-          const contexts = browser.contexts();
-          const ctx = contexts[0] || await browser.newContext();
-          this.setBrowserMode('cdp');
-          await this.initBrowserCdpSession();
-          log.info({ cdpUrl: this.cdpUrl }, 'Connected to Chrome via CDP');
-          return ctx as unknown as BrowserContext;
-        } catch (err) {
-          log.warn({ err }, 'CDP connectOverCDP failed');
-          this._browserMode = 'headless';
+        if (useCdp) {
+          try {
+            const pw = await import('playwright');
+            const browser = await pw.chromium.connectOverCDP(this.cdpUrl, { timeout: 10_000 });
+            this.cdpBrowser = browser;
+            this._browserLaunched = false;
+            const contexts = browser.contexts();
+            const ctx = contexts[0] || await browser.newContext();
+            this.setBrowserMode('cdp');
+            await this.initBrowserCdpSession();
+            log.info({ cdpUrl: this.cdpUrl }, 'Connected to Chrome via CDP');
+            return ctx as unknown as BrowserContext;
+          } catch (err) {
+            log.warn({ err }, 'CDP connectOverCDP failed');
+            this._browserMode = 'headless';
+          }
         }
-      }
 
-      // If a client is connected, launch headed Chromium (minimized) so the user
-      // can interact directly when handoff triggers (e.g. CAPTCHAs).
-      // The window stays offscreen until bringToFront() is called during handoff.
-      const hasSender = !!(invokingSessionId && this.sessionSenders.get(invokingSessionId));
-      if (hasSender && this._browserMode === 'headless') {
-        try {
-          const pw2 = await import('playwright');
-          const headedBrowser = await pw2.chromium.launch({
-            channel: 'chrome',
-            headless: false,
-            args: [
-              '--window-position=-32000,-32000',
-              '--window-size=1,1',
-              '--disable-blink-features=AutomationControlled',
-            ],
-          });
-          const ctx = headedBrowser.contexts()[0] || await headedBrowser.newContext();
-          this.cdpBrowser = headedBrowser as unknown as typeof this.cdpBrowser;
-          this._browserLaunched = true;
-          this.setBrowserMode('cdp');
-          await this.initBrowserCdpSession();
-          log.info('Launched headed Chromium (minimized) for interactive handoff support');
-          return ctx as unknown as BrowserContext;
-        } catch (err2) {
-          log.warn({ err: err2 }, 'Headed Chromium launch failed, falling back to headless');
+        // If a client is connected, launch headed Chromium (minimized) so the user
+        // can interact directly when handoff triggers (e.g. CAPTCHAs).
+        // The window stays offscreen until bringToFront() is called during handoff.
+        const hasSender = !!(invokingSessionId && this.sessionSenders.get(invokingSessionId));
+        if (hasSender && this._browserMode === 'headless') {
+          try {
+            const pw2 = await import('playwright');
+            const headedBrowser = await pw2.chromium.launch({
+              channel: 'chrome',
+              headless: false,
+              args: [
+                '--window-position=-32000,-32000',
+                '--window-size=1,1',
+                '--disable-blink-features=AutomationControlled',
+              ],
+            });
+            const ctx = headedBrowser.contexts()[0] || await headedBrowser.newContext();
+            this.cdpBrowser = headedBrowser as unknown as typeof this.cdpBrowser;
+            this._browserLaunched = true;
+            this.setBrowserMode('cdp');
+            await this.initBrowserCdpSession();
+            log.info('Launched headed Chromium (minimized) for interactive handoff support');
+            return ctx as unknown as BrowserContext;
+          } catch (err2) {
+            log.warn({ err: err2 }, 'Headed Chromium launch failed, falling back to headless');
+          }
         }
       }
 

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

@@ -54,6 +54,7 @@ class CallStartTool implements Tool {
       task: input.task as string,
       context: input.context as string | undefined,
       conversationId: context.conversationId,
+      assistantId: context.assistantId,
       callerIdentityMode: input.caller_identity_mode as 'assistant_number' | 'user_number' | undefined,
     });
 

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

@@ -6,6 +6,7 @@ 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';
+import { getCCCommand, loadCCCommandTemplate } from '../../commands/cc-command-registry.js';
 
 const log = getLogger('claude-code-tool');
 
@@ -62,7 +63,15 @@ export const claudeCodeTool: Tool = {
         properties: {
           prompt: {
             type: 'string',
-            description: 'The coding task or question for Claude Code to work on',
+            description: 'The coding task or question for Claude Code to work on. Use this for free-form tasks. Mutually exclusive with command.',
+          },
+          command: {
+            type: 'string',
+            description: 'Name of a .claude/commands/*.md command template to execute. The template will be loaded and $ARGUMENTS substituted before execution. Use this instead of prompt when invoking a named CC command.',
+          },
+          arguments: {
+            type: 'string',
+            description: 'Arguments to substitute into the command template ($ARGUMENTS placeholder). Only used with the command input.',
           },
           working_dir: {
             type: 'string',
@@ -82,7 +91,6 @@ export const claudeCodeTool: Tool = {
             description: 'Worker profile that scopes tool access. Defaults to general (backward compatible).',
           },
         },
-        required: ['prompt'],
       },
     };
   },
@@ -92,8 +100,52 @@ export const claudeCodeTool: Tool = {
       return { content: 'Cancelled', isError: true };
     }
 
-    const prompt = input.prompt as string;
     const workingDir = (input.working_dir as string) || context.workingDir;
+
+    // Resolve prompt: either from direct prompt input or by loading a CC command template
+    let prompt: string;
+    if (input.command != null && typeof input.command !== 'string') {
+      return {
+        content: `Error: "command" must be a string, got ${typeof input.command}`,
+        isError: true,
+      };
+    }
+    const commandName = input.command as string | undefined;
+    if (commandName) {
+      // Command-template execution path: load .claude/commands/<command>.md,
+      // apply $ARGUMENTS substitution, and use the result as the prompt.
+      const entry = getCCCommand(workingDir, commandName);
+      if (!entry) {
+        return {
+          content: `Error: CC command "${commandName}" not found. Looked for .claude/commands/${commandName}.md in ${workingDir} and parent directories.`,
+          isError: true,
+        };
+      }
+
+      let template: string;
+      try {
+        template = loadCCCommandTemplate(entry);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: `Error: Failed to load CC command template "${commandName}": ${message}`,
+          isError: true,
+        };
+      }
+
+      // Substitute $ARGUMENTS placeholder with the provided arguments
+      const args = (input.arguments as string) ?? '';
+      prompt = template.replace(/\$ARGUMENTS/g, args);
+
+      log.info({ command: commandName, templatePath: entry.filePath, hasArgs: !!args }, 'Loaded CC command template');
+    } else if (typeof input.prompt === 'string') {
+      prompt = input.prompt;
+    } else {
+      return {
+        content: 'Error: Either "prompt" or "command" must be provided.',
+        isError: true,
+      };
+    }
     const resumeSessionId = input.resume as string | undefined;
     const model = (input.model as string) || 'claude-sonnet-4-6';
     const profileName = (input.profile as WorkerProfile | undefined) ?? 'general';

package/src/tools/credentials/vault.ts

@@ -630,7 +630,7 @@ class CredentialStoreTool implements Tool {
                 const dmChannel = await conversationsOpen(botToken, installingUserId);
                 const welcomeMsg =
                   `You have installed ${identity.user}, an AI Assistant, on ${identity.team}. ` +
-                  `Manage the assistant experience for this workspace in the workspace settings page.`;
+                  `You can manage the assistant experience for this workspace by chatting with the assistant or from the Settings page.`;
                 await postMessage(botToken, dmChannel.channel.id, welcomeMsg);
               }
             } catch (err) {

package/src/tools/execution-target.ts

@@ -1,7 +1,12 @@
 import type { ExecutionTarget } from './types.js';
 import { getTool } from './registry.js';
 
-export function resolveExecutionTarget(toolName: string): ExecutionTarget {
+export interface ManifestOverride {
+  risk: 'low' | 'medium' | 'high';
+  execution_target: 'host' | 'sandbox';
+}
+
+export function resolveExecutionTarget(toolName: string, manifestOverride?: ManifestOverride): ExecutionTarget {
   const tool = getTool(toolName);
   // Manifest-declared execution target is authoritative — check it first so
   // skill tools with host_/computer_use_ prefixes aren't mis-classified.
@@ -13,6 +18,11 @@ export function resolveExecutionTarget(toolName: string): ExecutionTarget {
   if (tool?.executionMode === 'proxy') {
     return 'host';
   }
+  // Use manifest metadata for unregistered skill tools so the Permission
+  // Simulator shows accurate execution targets instead of defaulting to sandbox.
+  if (!tool && manifestOverride) {
+    return manifestOverride.execution_target;
+  }
   // Prefix heuristics for core tools that don't declare an explicit target.
   if (toolName.startsWith('host_') || toolName.startsWith('computer_use_')) {
     return 'host';

package/src/tools/executor.ts

@@ -268,7 +268,15 @@ export class ToolExecutor {
         });
 
         if (response.decision === 'deny') {
-          const denialMessage = `Permission denied by user. The user chose not to allow the "${name}" tool. Do NOT retry this tool call immediately. Instead, tell the user that the action was not performed because they denied permission, and ask if they would like you to try again or take a different approach. Wait for the user to explicitly respond before retrying.`;
+          const contextualDenial = typeof response.decisionContext === 'string'
+            ? response.decisionContext.trim()
+            : '';
+          const denialMessage = contextualDenial.length > 0
+            ? contextualDenial
+            : `Permission denied by user. The user chose not to allow the "${name}" tool. Do NOT retry this tool call immediately. Instead, tell the user that the action was not performed because they denied permission, and ask if they would like you to try again or take a different approach. Wait for the user to explicitly respond before retrying.`;
+          const denialReason = contextualDenial.length > 0
+            ? `Permission denied (${name}): contextual policy`
+            : 'Permission denied by user';
           const durationMs = Date.now() - startTime;
           emitLifecycleEvent(context, {
             type: 'permission_denied',
@@ -281,7 +289,7 @@ export class ToolExecutor {
             requestId: context.requestId,
             riskLevel,
             decision: 'deny',
-            reason: 'Permission denied by user',
+            reason: denialReason,
             durationMs,
           });
           return { content: denialMessage, isError: true };

package/src/tools/network/web-search.ts

@@ -268,7 +268,7 @@ class WebSearchTool implements Tool {
         apiKey = fallbackKey;
       } else {
         return {
-          content: 'Error: No web search API key configured. Set PERPLEXITY_API_KEY or BRAVE_API_KEY environment variable, or configure a key in settings.',
+          content: 'Error: No web search API key configured. Set a PERPLEXITY_API_KEY or BRAVE_API_KEY environment variable, or configure it from the Settings page under API Keys.',
           isError: true,
         };
       }