@vellumai/assistant 0.8.0 → 0.8.2

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

@@ -17,8 +17,42 @@ const log = getLogger("web-search");
 
 const BRAVE_API_URL = "https://api.search.brave.com/res/v1/web/search";
 const PERPLEXITY_API_URL = "https://api.perplexity.ai/chat/completions";
+const TAVILY_API_URL = "https://api.tavily.com/search";
+
+type WebSearchProvider = "perplexity" | "brave" | "tavily";
+
+/**
+ * Arguments passed to every {@link WebSearchAdapter}. The full superset is
+ * always supplied; individual adapters ignore the fields they don't use
+ * (e.g. Perplexity ignores `count`, `offset`, and `freshness`).
+ */
+interface WebSearchAdapterArgs {
+  query: string;
+  count: number;
+  offset: number;
+  freshness: string | undefined;
+  apiKey: string;
+  signal?: AbortSignal;
+}
 
-type WebSearchProvider = "perplexity" | "brave";
+/**
+ * One built-in web-search provider. Each adapter owns its HTTP shape,
+ * freshness mapping, retry behaviour, and result formatter. Registering a
+ * new provider becomes a single entry in {@link WEB_SEARCH_ADAPTERS}.
+ */
+interface WebSearchAdapter {
+  /** Stable provider identifier (matches config + secret-catalog values). */
+  readonly id: WebSearchProvider;
+  /** Secret-catalog key used to look up the API key via `getProviderKeyAsync`. */
+  readonly secretKey: string;
+  /**
+   * Position in the fallback chain (lower = earlier). Used when the
+   * configured provider has no key and we try other BYOK providers.
+   */
+  readonly fallbackOrder: number;
+  /** Execute one search against the provider's API. */
+  execute(args: WebSearchAdapterArgs): Promise<ToolExecutionResult>;
+}
 
 interface BraveSearchResult {
   title: string;
@@ -42,6 +76,20 @@ interface PerplexityResponse {
   citations?: string[];
 }
 
+interface TavilySearchResult {
+  title?: string;
+  url?: string;
+  content?: string;
+  score?: number;
+  raw_content?: string | null;
+  favicon?: string;
+}
+
+interface TavilySearchResponse {
+  query?: string;
+  results?: TavilySearchResult[];
+}
+
 function getWebSearchProvider(): WebSearchProvider {
   const config = getConfig();
   const configured = config.services["web-search"].provider ?? "perplexity";
@@ -54,12 +102,16 @@ function getWebSearchProvider(): WebSearchProvider {
 async function getApiKey(
   provider: WebSearchProvider,
 ): Promise<string | undefined> {
-  if (provider === "brave") {
-    return (await getProviderKeyAsync("brave")) ?? undefined;
-  }
+  const adapter = WEB_SEARCH_ADAPTERS[provider];
+  return (await getProviderKeyAsync(adapter.secretKey)) ?? undefined;
+}
 
-  // Perplexity
-  return (await getProviderKeyAsync("perplexity")) ?? undefined;
+function fallbackProvidersFor(
+  provider: WebSearchProvider,
+): readonly WebSearchProvider[] {
+  return WEB_SEARCH_FALLBACK_ORDER.filter(
+    (candidate) => candidate !== provider,
+  );
 }
 
 const CITATION_INSTRUCTION =
@@ -118,6 +170,54 @@ function formatPerplexityResults(
   return lines.join("\n");
 }
 
+function formatTavilyResults(
+  data: TavilySearchResponse,
+  query: string,
+): string {
+  const results = data.results ?? [];
+
+  if (results.length === 0) {
+    return `No results found for "${query}".`;
+  }
+
+  const lines: string[] = [`Web search results for "${query}":\n`];
+
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i];
+    const title = r.title?.trim() || r.url?.trim() || "Untitled result";
+    lines.push(`${i + 1}. ${title}`);
+    if (r.url) {
+      lines.push(`   URL: ${r.url}`);
+    }
+    if (r.content) {
+      lines.push(`   ${r.content}`);
+    }
+    if (typeof r.score === "number") {
+      lines.push(`   Score: ${r.score.toFixed(3)}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function tavilyTimeRangeForFreshness(
+  freshness: string | undefined,
+): "day" | "week" | "month" | "year" | undefined {
+  switch (freshness) {
+    case "pd":
+      return "day";
+    case "pw":
+      return "week";
+    case "pm":
+      return "month";
+    case "py":
+      return "year";
+    default:
+      return undefined;
+  }
+}
+
 async function executeBraveSearch(
   query: string,
   count: number,
@@ -281,6 +381,147 @@ async function executePerplexitySearch(
   };
 }
 
+async function executeTavilySearch(
+  query: string,
+  count: number,
+  freshness: string | undefined,
+  apiKey: string,
+  signal?: AbortSignal,
+): Promise<ToolExecutionResult> {
+  const timeRange = tavilyTimeRangeForFreshness(freshness);
+  const body: Record<string, unknown> = {
+    query,
+    search_depth: "advanced",
+    max_results: count,
+  };
+  if (timeRange) {
+    body.time_range = timeRange;
+  }
+
+  for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
+    const response = await fetch(TAVILY_API_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+        "X-Client-Source": "vellum-assistant",
+      },
+      body: JSON.stringify(body),
+      signal,
+    });
+
+    if (response.ok) {
+      const data = (await response.json()) as TavilySearchResponse;
+      return {
+        content:
+          wrapUntrustedContent(formatTavilyResults(data, query), {
+            source: "search",
+            sourceDetail: "tavily",
+          }) + CITATION_INSTRUCTION,
+        isError: false,
+      };
+    }
+
+    await response.text();
+
+    if (response.status === 401 || response.status === 403) {
+      return {
+        content: "Error: Invalid or expired Tavily API key",
+        isError: true,
+      };
+    }
+
+    if (response.status === 429 && attempt < DEFAULT_MAX_RETRIES) {
+      const delayMs = getHttpRetryDelay(
+        response,
+        attempt,
+        DEFAULT_BASE_DELAY_MS,
+      );
+      log.warn(
+        { attempt: attempt + 1, delayMs },
+        "Tavily Search rate limited, retrying",
+      );
+      await sleep(delayMs);
+      continue;
+    }
+
+    log.warn({ status: response.status }, "Tavily Search API error");
+    if (response.status === 429) {
+      return {
+        content:
+          "Error: Tavily Search rate limit exceeded after retries. Try again shortly.",
+        isError: true,
+      };
+    }
+    return {
+      content: `Error: Tavily Search API returned status ${response.status}`,
+      isError: true,
+    };
+  }
+
+  return {
+    content:
+      "Error: Tavily Search rate limit exceeded after retries. Try again shortly.",
+    isError: true,
+  };
+}
+
+// ----------------------------------------------------------------------------
+// Adapter registry
+//
+// Each built-in provider exposes a {@link WebSearchAdapter} wrapping its
+// existing execute function. Adding a new provider means adding one adapter
+// const and one entry to `WEB_SEARCH_ADAPTERS` — the dispatcher, fallback
+// chain, and api-key lookup all derive from this table.
+// ----------------------------------------------------------------------------
+
+const perplexitySearchAdapter: WebSearchAdapter = {
+  id: "perplexity",
+  secretKey: "perplexity",
+  fallbackOrder: 1,
+  execute: ({ query, apiKey, signal }) =>
+    executePerplexitySearch(query, apiKey, signal),
+};
+
+const braveSearchAdapter: WebSearchAdapter = {
+  id: "brave",
+  secretKey: "brave",
+  fallbackOrder: 2,
+  execute: ({ query, count, offset, freshness, apiKey, signal }) =>
+    executeBraveSearch(query, count, offset, freshness, apiKey, signal),
+};
+
+const tavilySearchAdapter: WebSearchAdapter = {
+  id: "tavily",
+  secretKey: "tavily",
+  fallbackOrder: 3,
+  execute: ({ query, count, freshness, apiKey, signal }) =>
+    executeTavilySearch(query, count, freshness, apiKey, signal),
+};
+
+/**
+ * All built-in web-search adapters keyed by provider id. The
+ * `Record<WebSearchProvider, ...>` shape forces TypeScript to flag any
+ * provider added to the union without a corresponding adapter.
+ */
+const WEB_SEARCH_ADAPTERS: Record<WebSearchProvider, WebSearchAdapter> = {
+  perplexity: perplexitySearchAdapter,
+  brave: braveSearchAdapter,
+  tavily: tavilySearchAdapter,
+};
+
+/**
+ * Fallback chain derived from {@link WEB_SEARCH_ADAPTERS}. Sorted by each
+ * adapter's `fallbackOrder` (lower first). Used when the configured provider
+ * has no API key and we try other BYOK providers before giving up.
+ */
+const WEB_SEARCH_FALLBACK_ORDER: readonly WebSearchProvider[] = Object.values(
+  WEB_SEARCH_ADAPTERS,
+)
+  .slice()
+  .sort((a, b) => a.fallbackOrder - b.fallbackOrder)
+  .map((adapter) => adapter.id);
+
 class WebSearchTool implements Tool {
   name = "web_search";
   description =
@@ -302,7 +543,7 @@ class WebSearchTool implements Tool {
           count: {
             type: "number",
             description:
-              "Number of results to return (1-20, default 10). Only used with Brave provider.",
+              "Number of results to return (1-20, default 10). Used with Brave and Tavily providers.",
           },
           offset: {
             type: "number",
@@ -312,7 +553,7 @@ class WebSearchTool implements Tool {
           freshness: {
             type: "string",
             description:
-              'Filter by recency: "pd" (past day), "pw" (past week), "pm" (past month), "py" (past year). Only used with Brave provider.',
+              'Filter by recency: "pd" (past day), "pw" (past week), "pm" (past month), "py" (past year). Used with Brave and Tavily providers.',
           },
         },
         required: ["query"],
@@ -335,22 +576,27 @@ class WebSearchTool implements Tool {
     let provider = getWebSearchProvider();
     let apiKey = await getApiKey(provider);
 
-    // Fallback: if the configured provider has no key, try the other provider
+    // Fallback: if the configured provider has no key, try other BYOK search
+    // providers in a stable order. This preserves existing installs that only
+    // configured one search-provider key while still allowing new providers to
+    // be selected explicitly.
     if (!apiKey) {
-      const fallback: WebSearchProvider =
-        provider === "perplexity" ? "brave" : "perplexity";
-      const fallbackKey = await getApiKey(fallback);
-      if (fallbackKey) {
+      for (const fallback of fallbackProvidersFor(provider)) {
+        const fallbackKey = await getApiKey(fallback);
+        if (!fallbackKey) continue;
         log.info(
           { from: provider, to: fallback },
           "Configured web search provider has no API key, falling back",
         );
         provider = fallback;
         apiKey = fallbackKey;
-      } else {
+        break;
+      }
+
+      if (!apiKey) {
         return {
           content:
-            "Error: No web search API key configured. Set it via `keys set perplexity <key>` or `keys set brave <key>`, or configure it from the Settings page under API Keys.",
+            "Error: No web search API key configured. Set it via `keys set perplexity <key>`, `keys set brave <key>`, or `keys set tavily <key>`, or configure it from the Settings page under API Keys.",
           isError: true,
         };
       }
@@ -359,28 +605,25 @@ class WebSearchTool implements Tool {
     try {
       log.debug({ query, provider }, "Executing web search");
 
-      if (provider === "brave") {
-        const count =
-          typeof input.count === "number"
-            ? Math.min(20, Math.max(1, Math.round(input.count)))
-            : 10;
-        const offset =
-          typeof input.offset === "number"
-            ? Math.min(9, Math.max(0, Math.round(input.offset)))
-            : 0;
-        const freshness =
-          typeof input.freshness === "string" ? input.freshness : undefined;
-        return await executeBraveSearch(
-          query,
-          count,
-          offset,
-          freshness,
-          apiKey,
-          context.signal,
-        );
-      }
-
-      return await executePerplexitySearch(query, apiKey, context.signal);
+      const count =
+        typeof input.count === "number"
+          ? Math.min(20, Math.max(1, Math.round(input.count)))
+          : 10;
+      const offset =
+        typeof input.offset === "number"
+          ? Math.min(9, Math.max(0, Math.round(input.offset)))
+          : 0;
+      const freshness =
+        typeof input.freshness === "string" ? input.freshness : undefined;
+
+      return await WEB_SEARCH_ADAPTERS[provider].execute({
+        query,
+        count,
+        offset,
+        freshness,
+        apiKey,
+        signal: context.signal,
+      });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       log.error({ err }, "Web search failed");

package/src/tools/permission-checker.ts

@@ -9,7 +9,11 @@ import {
 } from "../permissions/checker.js";
 import { getAutoApproveThreshold } from "../permissions/gateway-threshold-reader.js";
 import type { PermissionPrompter } from "../permissions/prompter.js";
-import type { ApprovalMode, ApprovalReason, RiskThreshold } from "../permissions/types.js";
+import type {
+  ApprovalMode,
+  ApprovalReason,
+  RiskThreshold,
+} from "../permissions/types.js";
 import { RiskLevel } from "../permissions/types.js";
 import { getLogger } from "../util/logger.js";
 import { buildPolicyContext } from "./policy-context.js";
@@ -160,9 +164,11 @@ export class PermissionChecker {
       );
       const riskThreshold = conversationThreshold as RiskThreshold;
 
-      // Some callers force prompting for side-effect tools even when a
-      // trust/allow rule would auto-allow. Deny decisions are preserved -
-      // only allow → prompt promotion happens here.
+      // Non-interactive callers (e.g. non-guardian phone voice) force
+      // prompting for side-effect tools even when a trust/allow rule would
+      // auto-allow, so their auto-deny handler always sees a
+      // confirmation_request. Deny decisions are preserved — only
+      // allow → prompt promotion happens here.
       if (
         context.forcePromptSideEffects &&
         result.decision === "allow" &&
@@ -200,7 +206,9 @@ export class PermissionChecker {
           reason: result.reason,
           durationMs,
         });
-        const provenance = mapApprovalProvenance("denied", { matchedTrustRuleId });
+        const provenance = mapApprovalProvenance("denied", {
+          matchedTrustRuleId,
+        });
         return {
           allowed: false,
           decision: "denied",
@@ -394,7 +402,7 @@ export class PermissionChecker {
           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.`;
+              : `Permission denied. The "${name}" tool was not allowed. Do NOT retry this tool call immediately. Instead, explain that the action was not performed because permission was denied, and ask whether to try again or take a different approach. Wait for an explicit response before retrying.`;
           const denialReason =
             contextualDenial.length > 0
               ? `Permission denied (${name}): contextual policy`

package/src/tools/registry.ts

@@ -10,7 +10,7 @@ import { hostFileWriteTool } from "./host-filesystem/write.js";
 import { hostShellTool } from "./host-terminal/host-shell.js";
 import { toProviderSafeToolName } from "./provider-tool-name.js";
 import { registerSystemTools } from "./system/register.js";
-import type { Tool } from "./types.js";
+import type { PluginTool, Tool } from "./types.js";
 import { allUiSurfaceTools } from "./ui-surface/definitions.js";
 import { registerUiSurfaceTools } from "./ui-surface/registry.js";
 
@@ -193,19 +193,29 @@ export function registerSkillTools(newTools: Tool[]): Tool[] {
  */
 export function registerPluginTools(
   pluginName: string,
-  newTools: Tool[],
+  newTools: PluginTool[],
 ): Tool[] {
-  const stamped: Tool[] = newTools.map((tool) =>
-    withProviderSafeToolName({
-      ...tool,
+  const stamped: Tool[] = newTools.map((pluginTool) => {
+    const { input_schema, ...rest } = pluginTool;
+    const tool: Tool = {
+      ...rest,
+      category: "plugin",
       origin: "plugin" as const,
       ownerPluginId: pluginName,
       ownerSkillId: undefined,
       ownerMcpServerId: undefined,
       ownerSkillBundled: undefined,
       ownerSkillVersionHash: undefined,
-    }),
-  );
+      getDefinition(): ToolDefinition {
+        return {
+          name: pluginTool.name,
+          description: pluginTool.description,
+          input_schema,
+        };
+      },
+    };
+    return withProviderSafeToolName(tool);
+  });
 
   const accepted: Tool[] = [];
   for (const tool of stamped) {

package/src/tools/schedule/create.ts

@@ -150,7 +150,7 @@ export async function executeScheduleCreate(
           `  Status: ${job.status}`,
           ``,
           `Integrations: ${integrations}`,
-          `\u26a0 If this schedule requires an integration that isn't connected, it will fail at runtime. Warn the user about any missing capabilities before confirming the schedule is ready.`,
+          `\u26a0 If this schedule requires an integration that isn't connected, it will fail at runtime. Warn about any missing capabilities before confirming the schedule is ready.`,
         ].join("\n"),
         isError: false,
       };
@@ -239,7 +239,7 @@ export async function executeScheduleCreate(
         `  Next run: ${nextRunDate}`,
         ``,
         `Integrations: ${integrations}`,
-        `\u26a0 If this schedule requires an integration that isn't connected, it will fail at runtime. Warn the user about any missing capabilities before confirming the schedule is ready.`,
+        `\u26a0 If this schedule requires an integration that isn't connected, it will fail at runtime. Warn about any missing capabilities before confirming the schedule is ready.`,
       ].join("\n"),
       isError: false,
     };

package/src/tools/schema-transforms.ts

@@ -23,8 +23,13 @@ export function injectActivityField(
       return def;
     }
 
-    const schema = def.input_schema as Record<string, unknown>;
-    if (schema.type !== "object" || !schema.properties) {
+    const schema = def.input_schema as Record<string, unknown> | undefined;
+    if (
+      schema == null ||
+      typeof schema !== "object" ||
+      schema.type !== "object" ||
+      !schema.properties
+    ) {
       return def;
     }
 

package/src/tools/side-effects.ts

@@ -14,6 +14,7 @@ const SIDE_EFFECT_TOOLS: ReadonlySet<string> = new Set([
   "web_fetch",
   "document_create",
   "document_update",
+  "document_delete",
   "schedule_create",
   "schedule_update",
   "schedule_delete",

package/src/tools/skills/delete-managed.ts

@@ -1,3 +1,4 @@
+import { refreshSkillCapabilityMemories } from "../../daemon/skill-memory-refresh.js";
 import { deleteManagedSkill } from "../../skills/managed-store.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -17,19 +18,18 @@ export async function executeDeleteManagedSkill(
     };
   }
 
-  const removeFromIndex = input.remove_from_index !== false;
-
-  const result = deleteManagedSkill(skillId.trim(), removeFromIndex);
+  const result = deleteManagedSkill(skillId.trim());
 
   if (!result.deleted) {
     return { content: `Error: ${result.error}`, isError: true };
   }
 
+  refreshSkillCapabilityMemories();
+
   return {
     content: JSON.stringify({
       deleted: true,
       skill_id: skillId.trim(),
-      index_updated: result.indexUpdated,
     }),
     isError: false,
   };

package/src/tools/skills/execute.ts

@@ -30,7 +30,7 @@ class SkillExecuteTool implements Tool {
           activity: {
             type: "string",
             description:
-              "Brief non-technical explanation of what you are doing and why, shown to the user as a progress update.",
+              "Brief non-technical explanation of what you are doing and why, shown as a progress update.",
           },
         },
         required: ["tool", "input", "activity"],

package/src/tools/skills/scaffold-managed.ts

@@ -1,3 +1,4 @@
+import { refreshSkillCapabilityMemories } from "../../daemon/skill-memory-refresh.js";
 import { createManagedSkill } from "../../skills/managed-store.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -93,7 +94,6 @@ export async function executeScaffoldManagedSkill(
         ? sanitizeFrontmatterValue(input.emoji)
         : undefined,
     overwrite: input.overwrite === true,
-    addToIndex: input.add_to_index !== false,
     includes,
   });
 
@@ -101,12 +101,13 @@ export async function executeScaffoldManagedSkill(
     return { content: `Error: ${result.error}`, isError: true };
   }
 
+  refreshSkillCapabilityMemories();
+
   return {
     content: JSON.stringify({
       created: true,
       skill_id: skillId.trim(),
       path: result.path,
-      index_updated: result.indexUpdated,
     }),
     isError: false,
   };

package/src/tools/subagent/notify-parent.ts

@@ -59,7 +59,7 @@ class NotifyParentTool implements Tool {
           activity: {
             type: "string",
             description:
-              "Brief non-technical explanation of what you are doing and why, shown to the user as a status update.",
+              "Brief non-technical explanation of what you are doing and why, shown as a status update.",
           },
         },
         required: ["message", "activity"],

package/src/tools/subagent/spawn.ts

@@ -71,9 +71,9 @@ export async function executeSubagentSpawn(
 
   // The subagent runs as its own background conversation, so the agent
   // loop's background-skip rule would zero out any inherited profile.
-  // Pass the parent's profile explicitly via `SubagentConfig` so the
-  // PR 6 plumbing in `SubagentManager.spawn` forwards it back into the
-  // subagent's `runAgentLoop` call as `options.overrideProfile`.
+  // Pass the parent's profile explicitly via `SubagentConfig` so
+  // `SubagentManager.spawn` forwards it back into the subagent's
+  // `runAgentLoop` call as `options.overrideProfile`.
   //
   // Prefer the per-turn `context.overrideProfile` (populated by
   // `runAgentLoopImpl` from its resolved `turnOverrideProfile`) over a

package/src/tools/system/request-permission.ts

@@ -53,7 +53,7 @@ const FRIENDLY_NAMES: Record<PermissionType, string> = {
 class RequestSystemPermissionTool implements Tool {
   name = "request_system_permission";
   description =
-    "Ask the user to grant a macOS system permission via System Settings. " +
+    "Request a macOS system permission via System Settings. " +
     "Use when a tool fails with a permission/access error (e.g. 'Operation not permitted', 'EACCES', sandbox denial). " +
     "Do not explain how to open System Settings manually - this tool handles it with a clickable button.";
   category = "system";
@@ -74,7 +74,7 @@ class RequestSystemPermissionTool implements Tool {
           activity: {
             type: "string",
             description:
-              "Short explanation of why this permission is needed (shown to the user)",
+              "Short explanation of why this permission is needed (shown in the prompt)",
           },
         },
         required: ["permission_type", "activity"],