@vellumai/assistant 0.7.3 → 0.8.1

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";
@@ -32,6 +36,11 @@ export type PermissionDecision =
         riskLevel: string;
         riskReason: string;
         riskScopeOptions: Array<{ pattern: string; label: string }>;
+        riskAllowlistOptions?: Array<{
+          label: string;
+          description: string;
+          pattern: string;
+        }>;
         riskDirectoryScopeOptions?: Array<{ scope: string; label: string }>;
         isContainerized?: boolean;
       };
@@ -51,6 +60,11 @@ export type PermissionDecision =
         riskLevel: string;
         riskReason: string;
         riskScopeOptions: Array<{ pattern: string; label: string }>;
+        riskAllowlistOptions?: Array<{
+          label: string;
+          description: string;
+          pattern: string;
+        }>;
         riskDirectoryScopeOptions?: Array<{ scope: string; label: string }>;
         isContainerized?: boolean;
       };
@@ -111,7 +125,12 @@ export class PermissionChecker {
       ? {
           riskLevel: cachedAssessment.riskLevel,
           riskReason: cachedAssessment.reason,
+          // Display ladder (regex patterns — internal only, not for save).
           riskScopeOptions: cachedAssessment.scopeOptions,
+          // Save ladder (Minimatch globs — what the gateway matches against).
+          // Populated for classifiers that produce allowlist options
+          // (bash, file, skill); undefined otherwise.
+          riskAllowlistOptions: cachedAssessment.allowlistOptions,
           riskDirectoryScopeOptions: cachedAssessment.directoryScopeOptions,
           isContainerized: getIsContainerized(),
         }
@@ -145,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" &&
@@ -185,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",

package/src/tools/skills/load.ts

@@ -19,7 +19,7 @@ import {
 import {
   collectAllMissing,
   indexCatalogById,
-  validateIncludes,
+  validateIncludeCycles,
 } from "../../skills/include-graph.js";
 import { renderInlineCommands } from "../../skills/inline-command-render.js";
 import { parseToolManifestFile } from "../../skills/tool-manifest.js";
@@ -204,6 +204,7 @@ export class SkillLoadTool implements Tool {
 
     // Load catalog for include validation and child metadata output
     let catalogIndex: Map<string, SkillSummary> | undefined;
+    let missingIncludedSkillIds: string[] = [];
     if (skill.includes && skill.includes.length > 0) {
       let catalog = loadSkillCatalog();
       catalogIndex = indexCatalogById(catalog);
@@ -260,19 +261,13 @@ export class SkillLoadTool implements Tool {
         catalogIndex = indexCatalogById(catalog);
       }
 
-      // Validate (fail-closed - catches genuinely missing deps + cycles)
-      const validation = validateIncludes(skill.id, catalogIndex);
+      missingIncludedSkillIds = [...collectAllMissing(skill.id, catalogIndex)];
+
+      // Validate cycles fail closed. Missing includes are advisory: the parent
+      // skill should still load so the assistant can decide whether to search
+      // for and install the suggested dependency.
+      const validation = validateIncludeCycles(skill.id, catalogIndex);
       if (!validation.ok) {
-        if (validation.error === "missing") {
-          return {
-            content: `Error: skill "${skill.id}" includes "${
-              validation.missingChildId
-            }" which was not found (referenced by "${
-              validation.parentId
-            }" via path: ${validation.path.join(" → ")})`,
-            isError: true,
-          };
-        }
         if (validation.error === "cycle") {
           return {
             content: `Error: skill "${
@@ -283,10 +278,6 @@ export class SkillLoadTool implements Tool {
             isError: true,
           };
         }
-        return {
-          content: `Error: skill "${skill.id}" has an invalid include graph`,
-          isError: true,
-        };
       }
     }
 
@@ -444,13 +435,25 @@ export class SkillLoadTool implements Tool {
           }
         }
       }
-      immediateChildrenSection = `Included Skills (immediate):\n${childLines.join(
-        "\n",
-      )}`;
+      immediateChildrenSection =
+        childLines.length > 0
+          ? `Included Skills (immediate):\n${childLines.join("\n")}`
+          : "Included Skills (immediate): none";
     } else {
       immediateChildrenSection = "Included Skills (immediate): none";
     }
 
+    const missingIncludesSection =
+      missingIncludedSkillIds.length > 0
+        ? [
+            "Suggested Included Skills (not loaded):",
+            ...missingIncludedSkillIds.map(
+              (id) =>
+                `  - ${id}: not installed or unavailable. If this task needs it, search for and install this skill, then load it.`,
+            ),
+          ].join("\n")
+        : undefined;
+
     let versionHash: string | undefined;
     try {
       versionHash = computeSkillVersionHash(skill.directoryPath);
@@ -512,6 +515,7 @@ export class SkillLoadTool implements Tool {
           : []),
         ...includedBodies.flatMap((b) => [b, ""]),
         immediateChildrenSection,
+        ...(missingIncludesSection ? [missingIncludesSection] : []),
         "",
         `<loaded_skill id="${skill.id}"${versionAttr} />`,
         ...includeMarkers,

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/terminal/shell.ts

@@ -17,7 +17,9 @@ import {
   registerBackgroundTool,
   removeBackgroundTool,
 } from "../background-tool-registry.js";
+import { getCredentialMetadataById } from "../credentials/metadata-store.js";
 import { resolveCredentialRef } from "../credentials/resolve.js";
+import { isToolAllowed } from "../credentials/tool-policy.js";
 import {
   getOrStartSession,
   getSessionEnv,
@@ -214,6 +216,48 @@ class ShellTool implements Tool {
         },
         "Credential refs resolved",
       );
+
+      // -------------------------------------------------------------------
+      // Tool policy enforcement — deny any credential that does not
+      // explicitly allow "bash" in its allowedTools metadata. This check
+      // runs after resolution/dedup and before proxy session creation so
+      // that a denied credential never reaches getOrStartSession.
+      // -------------------------------------------------------------------
+      const deniedCredentials: { credentialId: string; reason: string }[] = [];
+      for (const credId of credentialIds) {
+        const meta = getCredentialMetadataById(credId);
+        if (!meta) {
+          // Should not happen — we just resolved these IDs — but fail-closed.
+          deniedCredentials.push({
+            credentialId: credId,
+            reason: "metadata not found",
+          });
+          continue;
+        }
+        if (!isToolAllowed("bash", meta.allowedTools)) {
+          const tools = meta.allowedTools ?? [];
+          deniedCredentials.push({
+            credentialId: credId,
+            reason:
+              tools.length === 0
+                ? `credential ${meta.service}/${meta.field} has no allowed tools`
+                : `credential ${meta.service}/${meta.field} allows [${tools.join(", ")}] but not bash`,
+          });
+        }
+      }
+      if (deniedCredentials.length > 0) {
+        log.warn(
+          { denied: deniedCredentials },
+          "Credential tool policy denied for proxied bash",
+        );
+        const reasons = deniedCredentials
+          .map((d) => `${d.credentialId}: ${d.reason}`)
+          .join("; ");
+        return {
+          content: `Error: credential tool policy denied — ${reasons}. Each credential must include "bash" in its allowed tools to be used in a proxied shell session.`,
+          isError: true,
+        };
+      }
     } else {
       credentialIds.push(...rawCredentialRefs);
     }

package/src/tools/tool-name-aliases.ts

@@ -0,0 +1,19 @@
+const TOOL_NAME_ALIASES = new Map<string, string>([
+  ["create_app", "app_create"],
+]);
+
+/**
+ * Resolve high-confidence compatibility aliases before active-tool gating.
+ * Keep this list narrow: aliases should only cover observed model drift where
+ * the canonical target is active for the turn.
+ */
+export function resolveToolNameAlias(
+  name: string,
+  allowedToolNames?: ReadonlySet<string>,
+): string {
+  if (allowedToolNames?.has(name)) return name;
+  const canonical = TOOL_NAME_ALIASES.get(name);
+  if (!canonical) return name;
+  if (allowedToolNames && !allowedToolNames.has(canonical)) return name;
+  return canonical;
+}

package/src/tools/types.ts

@@ -115,8 +115,26 @@ export interface ToolExecutionResult {
   riskThreshold?: string;
   /** Whether the daemon is running in a containerized (Docker) environment. */
   isContainerized?: boolean;
-  /** Scope options ladder for the rule editor (narrowest to broadest). */
+  /**
+   * Display-only ladder of scope option labels for the rule editor
+   * (narrowest to broadest). The `pattern` field here is a regex-style
+   * descriptor used internally by the daemon and is NOT a valid trust
+   * rule pattern. Use `riskAllowlistOptions` for the pattern that gets
+   * saved as a trust rule.
+   */
   riskScopeOptions?: Array<{ pattern: string; label: string }>;
+  /**
+   * Allowlist options for the rule editor save path (narrowest to
+   * broadest). Each `pattern` is a Minimatch-glob compatible string
+   * (e.g. raw command for exact match, `action:<program>` for command
+   * wildcards) — what the gateway actually matches against. Mirrors
+   * the `allowlistOptions` field on `ConfirmationRequest` SSE events.
+   */
+  riskAllowlistOptions?: Array<{
+    label: string;
+    description: string;
+    pattern: string;
+  }>;
   /** Directory scope ladder for the rule editor (narrowest to broadest). */
   riskDirectoryScopeOptions?: Array<{ scope: string; label: string }>;
   /**