@vellumai/assistant 0.9.0 → 0.10.0-staging.2

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

@@ -35,8 +35,9 @@ const BRAVE_SEARCH_PATH = "/res/v1/web/search";
 const BRAVE_API_URL = `https://api.search.brave.com${BRAVE_SEARCH_PATH}`;
 const PERPLEXITY_API_URL = "https://api.perplexity.ai/chat/completions";
 const TAVILY_API_URL = "https://api.tavily.com/search";
+const FIRECRAWL_API_URL = "https://api.firecrawl.dev/v2/search";
 
-type WebSearchProvider = "perplexity" | "brave" | "tavily";
+type WebSearchProvider = "perplexity" | "brave" | "tavily" | "firecrawl";
 type WebSearchMode = "managed" | "your-own";
 
 /**
@@ -108,6 +109,28 @@ interface TavilySearchResponse {
   results?: TavilySearchResult[];
 }
 
+interface FirecrawlSearchResult {
+  title?: string;
+  description?: string;
+  url?: string;
+  category?: string;
+}
+
+/**
+ * Firecrawl `/v2/search` returns one array per requested source under `data`
+ * (defaults to `web`). We request only `web`, so that is the array we read;
+ * `news`/`images` are typed loosely since we never request them here.
+ */
+interface FirecrawlSearchResponse {
+  success?: boolean;
+  data?: {
+    web?: FirecrawlSearchResult[];
+    news?: FirecrawlSearchResult[];
+    images?: unknown[];
+  };
+  warning?: string | null;
+}
+
 function getWebSearchProvider(): WebSearchProvider {
   const config = getConfig();
   const configured = config.services["web-search"].provider ?? "perplexity";
@@ -229,6 +252,34 @@ function formatTavilyResults(
   return lines.join("\n");
 }
 
+function formatFirecrawlResults(
+  data: FirecrawlSearchResponse,
+  query: string,
+): string {
+  const results = data.data?.web ?? [];
+
+  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.description) {
+      lines.push(`   ${r.description}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
 function buildBraveMetadata(
   results: BraveSearchResult[],
   query: string,
@@ -365,6 +416,55 @@ function tavilyTimeRangeForFreshness(
   }
 }
 
+function buildFirecrawlMetadata(
+  data: FirecrawlSearchResponse,
+  query: string,
+  durationMs: number,
+): WebSearchMetadata {
+  const results = data.data?.web ?? [];
+  const items: WebSearchResultItem[] = results.map((r, i) => {
+    const url = r.url ?? "";
+    const domain = extractDomain(url);
+    return {
+      rank: i + 1,
+      title: r.title?.trim() || url.trim() || "Untitled result",
+      url,
+      domain,
+      faviconUrl: faviconUrlForDomain(domain),
+      snippet: r.description,
+    };
+  });
+  return {
+    query,
+    provider: "firecrawl",
+    resultCount: items.length,
+    durationMs,
+    results: items,
+  };
+}
+
+/**
+ * Map the tool's `freshness` window onto Firecrawl's `tbs` time filter
+ * (`qdr:d` / `qdr:w` / `qdr:m` / `qdr:y`). Returns `undefined` for an
+ * unrecognized value so the request omits `tbs` entirely.
+ */
+function firecrawlTbsForFreshness(
+  freshness: string | undefined,
+): "qdr:d" | "qdr:w" | "qdr:m" | "qdr:y" | undefined {
+  switch (freshness) {
+    case "pd":
+      return "qdr:d";
+    case "pw":
+      return "qdr:w";
+    case "pm":
+      return "qdr:m";
+    case "py":
+      return "qdr:y";
+    default:
+      return undefined;
+  }
+}
+
 function errorResult(
   query: string,
   provider: WebSearchProvider,
@@ -396,8 +496,7 @@ function errorResult(
  */
 function rawBodyDetail(body: unknown): { message: string } | undefined {
   if (body == null) return undefined;
-  const text =
-    typeof body === "string" ? body : safeStringifyBody(body);
+  const text = typeof body === "string" ? body : safeStringifyBody(body);
   const trimmed = text.trim();
   return trimmed ? { message: trimmed } : undefined;
 }
@@ -602,10 +701,7 @@ async function executeManagedBraveSearch(
   if (!proxyResult.ok) {
     // Keep billing/auth/unavailable mapping as specific copy; route genuine
     // platform 5xx (transport-level failures) to the friendly backend helper.
-    if (
-      proxyResult.kind === "platform-error" &&
-      proxyResult.status >= 500
-    ) {
+    if (proxyResult.kind === "platform-error" && proxyResult.status >= 500) {
       return backendFailureResult(
         query,
         "brave",
@@ -868,6 +964,104 @@ async function executeTavilySearch(
   );
 }
 
+async function executeFirecrawlSearch(
+  query: string,
+  count: number,
+  freshness: string | undefined,
+  apiKey: string,
+  signal?: AbortSignal,
+): Promise<ToolExecutionResult> {
+  const tbs = firecrawlTbsForFreshness(freshness);
+  const body: Record<string, unknown> = {
+    query,
+    limit: count,
+    sources: ["web"],
+  };
+  if (tbs) {
+    body.tbs = tbs;
+  }
+
+  const startedAt = Date.now();
+
+  for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
+    let response: Response;
+    try {
+      response = await fetch(FIRECRAWL_API_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+          "X-Client-Source": "vellum-assistant",
+        },
+        body: JSON.stringify(body),
+        signal,
+      });
+    } catch (err) {
+      return networkFailureResult(query, "firecrawl", startedAt, err, signal);
+    }
+
+    if (response.ok) {
+      const data = (await response.json()) as FirecrawlSearchResponse;
+      const durationMs = Date.now() - startedAt;
+      return {
+        content:
+          wrapUntrustedContent(formatFirecrawlResults(data, query), {
+            source: "search",
+            sourceDetail: "firecrawl",
+          }) + CITATION_INSTRUCTION,
+        isError: false,
+        activityMetadata: {
+          webSearch: buildFirecrawlMetadata(data, query, durationMs),
+        },
+      };
+    }
+
+    const bodyText = await response.text();
+
+    if (response.status === 401 || response.status === 403) {
+      return errorResult(
+        query,
+        "firecrawl",
+        startedAt,
+        "Invalid or expired Firecrawl API key",
+      );
+    }
+
+    if (response.status === 429 && attempt < DEFAULT_MAX_RETRIES) {
+      const delayMs = getHttpRetryDelay(
+        response,
+        attempt,
+        DEFAULT_BASE_DELAY_MS,
+      );
+      log.warn(
+        { attempt: attempt + 1, delayMs },
+        "Firecrawl Search rate limited, retrying",
+      );
+      await sleep(delayMs);
+      continue;
+    }
+
+    log.warn({ status: response.status }, "Firecrawl Search API error");
+    return backendFailureResult(
+      query,
+      "firecrawl",
+      startedAt,
+      { statusCode: response.status, error: rawBodyDetail(bodyText) },
+      response.status === 429
+        ? "Firecrawl Search rate limit exceeded after retries. Try again shortly."
+        : `Firecrawl Search API returned status ${response.status}`,
+    );
+  }
+
+  return backendFailureResult(
+    query,
+    "firecrawl",
+    startedAt,
+    { statusCode: 429 },
+    "Firecrawl Search rate limit exceeded after retries. Try again shortly.",
+  );
+}
+
 // ----------------------------------------------------------------------------
 // Adapter registry
 //
@@ -909,6 +1103,14 @@ const tavilySearchAdapter: WebSearchAdapter = {
     executeTavilySearch(query, count, freshness, apiKey, signal),
 };
 
+const firecrawlSearchAdapter: WebSearchAdapter = {
+  id: "firecrawl",
+  providerKeyName: "firecrawl",
+  fallbackOrder: 4,
+  execute: ({ query, count, freshness, apiKey, signal }) =>
+    executeFirecrawlSearch(query, count, freshness, apiKey, signal),
+};
+
 /**
  * All built-in web-search adapters keyed by provider id. The
  * `Record<WebSearchProvider, ...>` shape forces TypeScript to flag any
@@ -918,6 +1120,7 @@ const WEB_SEARCH_ADAPTERS: Record<WebSearchProvider, WebSearchAdapter> = {
   perplexity: perplexitySearchAdapter,
   brave: braveSearchAdapter,
   tavily: tavilySearchAdapter,
+  firecrawl: firecrawlSearchAdapter,
 };
 
 /**
@@ -949,7 +1152,7 @@ export const webSearchTool = {
       count: {
         type: "number",
         description:
-          "Number of results to return (1-20, default 10). Used with Brave and Tavily providers.",
+          "Number of results to return (1-20, default 10). Used with Brave, Tavily, and Firecrawl providers.",
       },
       offset: {
         type: "number",
@@ -959,7 +1162,7 @@ export const webSearchTool = {
       freshness: {
         type: "string",
         description:
-          'Filter by recency: "pd" (past day), "pw" (past week), "pm" (past month), "py" (past year). Used with Brave and Tavily providers.',
+          'Filter by recency: "pd" (past day), "pw" (past week), "pm" (past month), "py" (past year). Used with Brave, Tavily, and Firecrawl providers.',
       },
     },
     required: ["query"],
@@ -1039,7 +1242,7 @@ export const webSearchTool = {
           query,
           provider,
           startedAt,
-          "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.",
+          "No web search API key configured. Set it via `keys set perplexity <key>`, `keys set brave <key>`, `keys set tavily <key>`, or `keys set firecrawl <key>`, or configure it from the Settings page under API Keys.",
         );
       }
     }

package/src/tools/permission-checker.ts

@@ -16,6 +16,7 @@ import type {
   RiskThreshold,
 } from "../permissions/types.js";
 import { RiskLevel } from "../permissions/types.js";
+import { resolveCapabilities } from "../runtime/capabilities.js";
 import { getLogger } from "../util/logger.js";
 import { buildPolicyContext } from "./policy-context.js";
 import { isSideEffectTool } from "./side-effects.js";
@@ -173,7 +174,7 @@ export class PermissionChecker {
       if (
         context.forcePromptSideEffects &&
         result.decision === "allow" &&
-        isSideEffectTool(name, input)
+        isSideEffectTool(name)
       ) {
         result.decision = "prompt";
         result.reason = "Side-effect tool requires explicit approval";
@@ -238,7 +239,7 @@ export class PermissionChecker {
         result.decision === "prompt" &&
         context.isPlatformHosted &&
         name === "bash" &&
-        context.trustClass === "guardian" &&
+        resolveCapabilities(context.trustClass).canSelfApproveTools &&
         !context.requireFreshApproval
       ) {
         log.info(
@@ -274,7 +275,7 @@ export class PermissionChecker {
           true;
         if (
           context.isInteractive === false &&
-          context.trustClass === "guardian" &&
+          resolveCapabilities(context.trustClass).canSelfApproveTools &&
           !context.requireFreshApproval &&
           !isDynamicSkillLoad
         ) {

package/src/tools/registry.ts

@@ -548,6 +548,26 @@ export function getMcpToolDefinitions(): Tool[] {
   );
 }
 
+/**
+ * Return MCP tools grouped by their owning server ID. Each entry contains
+ * the server ID and the tool definitions registered by that server.
+ */
+export function getMcpToolsByServer(): Map<string, Tool[]> {
+  const byServer = new Map<string, Tool[]>();
+  for (const [name, owner] of ownersByName) {
+    if (owner.kind !== "mcp") continue;
+    const tool = tools.get(name);
+    if (!tool) continue;
+    let list = byServer.get(owner.id);
+    if (!list) {
+      list = [];
+      byServer.set(owner.id, list);
+    }
+    list.push(tool);
+  }
+  return byServer;
+}
+
 /**
  * Return the names of all currently registered skill-origin tools.
  */

package/src/tools/schedule/create.ts

@@ -1,5 +1,4 @@
-import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
-import { getConfig } from "../../config/loader.js";
+import { resolveCapabilities } from "../../runtime/capabilities.js";
 import { validateScheduleInferenceProfile } from "../../schedule/inference-profile.js";
 import { formatIntegrationSummary } from "../../schedule/integration-status.js";
 import { validateRruleSetLines } from "../../schedule/recurrence-engine.js";
@@ -17,7 +16,7 @@ import {
 } from "../../schedule/schedule-store.js";
 import {
   CapabilityManifestSchema,
-  resolveCapabilities,
+  resolveCapabilities as resolveWorkflowCapabilities,
 } from "../../workflows/capabilities.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -32,7 +31,7 @@ export async function executeScheduleCreate(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  if (context.trustClass !== "guardian") {
+  if (!resolveCapabilities(context.trustClass).canManageSchedules) {
     return {
       content:
         "Error: schedule_create is restricted to guardian actors because schedules execute with elevated privileges.",
@@ -121,13 +120,9 @@ export async function executeScheduleCreate(
       };
     }
   } else if (mode === "workflow") {
-    // Workflow mode is gated by the `workflows` flag (a scheduled run would
-    // otherwise hard-fail at trigger time) and requires a saved workflow name —
-    // mirrors the HTTP route's create-side validation so the assistant-facing
-    // path and the settings route enforce the same shape.
-    if (!isAssistantFeatureFlagEnabled("workflows", getConfig())) {
-      return { content: "Error: workflows are not enabled.", isError: true };
-    }
+    // Workflow mode requires a saved workflow name — mirrors the HTTP route's
+    // create-side validation so the assistant-facing path and the settings route
+    // enforce the same shape.
     if (!workflowName) {
       return {
         content:
@@ -144,7 +139,7 @@ export async function executeScheduleCreate(
     if (input.capabilities !== undefined) {
       try {
         const manifest = CapabilityManifestSchema.parse(input.capabilities);
-        resolveCapabilities(manifest);
+        resolveWorkflowCapabilities(manifest);
         capabilities = manifest;
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

package/src/tools/schedule/update.ts

@@ -1,5 +1,4 @@
-import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
-import { getConfig } from "../../config/loader.js";
+import { resolveCapabilities } from "../../runtime/capabilities.js";
 import { validateScheduleInferenceProfile } from "../../schedule/inference-profile.js";
 import { validateRruleSetLines } from "../../schedule/recurrence-engine.js";
 import {
@@ -31,7 +30,7 @@ export async function executeScheduleUpdate(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  if (context.trustClass !== "guardian") {
+  if (!resolveCapabilities(context.trustClass).canManageSchedules) {
     return {
       content:
         "Error: schedule_update is restricted to guardian actors because schedules execute with elevated privileges.",
@@ -205,8 +204,8 @@ export async function executeScheduleUpdate(
     };
   }
 
-  // Mirror the HTTP route: a schedule whose RESULTING mode is `workflow` must be
-  // flag-enabled and carry a non-empty workflowName. Compute the post-update
+  // Mirror the HTTP route: a schedule whose RESULTING mode is `workflow` must
+  // carry a non-empty workflowName. Compute the post-update
   // state (the update's value if present, else the persisted one) so both
   // "switch to workflow without a name" and "clear the name on a workflow
   // schedule" are rejected — otherwise the scheduler hits the `!job.workflowName`
@@ -217,12 +216,6 @@ export async function executeScheduleUpdate(
       const resultingMode =
         updates.mode !== undefined ? (updates.mode as string) : existing.mode;
       if (resultingMode === "workflow") {
-        if (!isAssistantFeatureFlagEnabled("workflows", getConfig())) {
-          return {
-            content: "Error: workflows are not enabled.",
-            isError: true,
-          };
-        }
         const resultingWorkflowName =
           updates.workflowName !== undefined
             ? ((updates.workflowName as string | null) ?? "")

package/src/tools/shared/filesystem/path-policy.ts

@@ -31,6 +31,40 @@ export type PathResult =
 const CONTAINER_WORKSPACE_PREFIX = "/workspace/";
 const CONTAINER_WORKSPACE_EXACT = "/workspace";
 
+// ---------------------------------------------------------------------------
+// Symlink resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve symlinks in an absolute path.
+ *
+ * For an existing path, returns its `realpathSync`. For a path that does not
+ * exist yet (e.g. a `file_write` target), walks up to the nearest existing
+ * ancestor, resolves that ancestor via `realpathSync`, then re-appends the
+ * trailing (non-existent) components — so a symlink anywhere in the existing
+ * prefix is still followed. Falls back to the lexical input when nothing on
+ * the path resolves (e.g. the path lives on a filesystem this process cannot
+ * see, as with host_file paths proxied to a remote client).
+ *
+ * Used both for sandbox-boundary enforcement and to canonicalize paths before
+ * security risk classification, so a symlink cannot mask the true target of a
+ * file operation.
+ */
+export function resolveRealPath(absolutePath: string): string {
+  let current = absolutePath;
+  const trailing: string[] = [];
+  while (current !== dirname(current)) {
+    try {
+      const real = realpathSync(current);
+      return trailing.length > 0 ? join(real, ...trailing) : real;
+    } catch {
+      trailing.unshift(basename(current));
+      current = dirname(current);
+    }
+  }
+  return absolutePath;
+}
+
 // ---------------------------------------------------------------------------
 // Sandbox policy
 // ---------------------------------------------------------------------------
@@ -82,18 +116,7 @@ export function sandboxPolicy(
       realResolved = resolved;
     }
   } else {
-    let current = resolved;
-    const trailing: string[] = [];
-    while (current !== dirname(current)) {
-      try {
-        const real = realpathSync(current);
-        realResolved = trailing.length > 0 ? join(real, ...trailing) : real;
-        break;
-      } catch {
-        trailing.unshift(basename(current));
-        current = dirname(current);
-      }
-    }
+    realResolved = resolveRealPath(resolved);
   }
 
   // Resolve the boundary directory's real path too (in case it's a symlink)
@@ -115,7 +138,10 @@ export function sandboxPolicy(
 
   // Check both the logical path and the symlink-resolved path so a symlink
   // with a non-denied name pointing at a denied file is still caught.
-  if (DENIED_BASENAMES.has(basename(resolved)) || DENIED_BASENAMES.has(basename(realResolved))) {
+  if (
+    DENIED_BASENAMES.has(basename(resolved)) ||
+    DENIED_BASENAMES.has(basename(realResolved))
+  ) {
     return {
       ok: false,
       reason: "denied",

package/src/tools/side-effects.ts

@@ -25,22 +25,7 @@ const SIDE_EFFECT_TOOLS: ReadonlySet<string> = new Set([
  * Returns `true` if the given tool name is classified as having side effects
  * (i.e. it can modify the filesystem, execute arbitrary commands, or trigger
  * external actions). Read-only and informational tools return `false`.
- *
- * For mixed-action tools (e.g. credential_store), the optional
- * `input` parameter is inspected to distinguish mutating actions (create,
- * update, cancel) from read-only ones (list, get).
  */
-export function isSideEffectTool(
-  toolName: string,
-  input?: Record<string, unknown>,
-): boolean {
-  if (SIDE_EFFECT_TOOLS.has(toolName)) return true;
-
-  // Action-aware checks for mixed-action tools
-  if (toolName === "credential_store") {
-    const action = input?.action;
-    return action === "store" || action === "delete" || action === "prompt";
-  }
-
-  return false;
+export function isSideEffectTool(toolName: string): boolean {
+  return SIDE_EFFECT_TOOLS.has(toolName);
 }

package/src/tools/skills/execute.ts

@@ -62,6 +62,39 @@ export function resolveSkillExecuteInput(
   return {};
 }
 
+/**
+ * Augment an inner-tool error with `skill_execute` envelope guidance when the
+ * call carried no inner parameters.
+ *
+ * {@link resolveSkillExecuteInput} rescues *misplaced* parameters (siblings, a
+ * JSON-encoded string). It cannot rescue a genuinely empty call — there is
+ * nothing to relocate — so the inner tool runs with `{}` and rejects it with a
+ * field-level message ("<field> is required") that says nothing about the
+ * envelope. Weak models then retry the identical empty shape, oscillating over
+ * whether parameters belong under `input`, as siblings, or as a JSON string.
+ *
+ * Appending the canonical envelope shape gives the next attempt a concrete
+ * template. Fires only when the resolved inner input was empty AND the tool
+ * errored, so well-formed calls and tools that legitimately accept no
+ * parameters are untouched.
+ */
+export function augmentSkillExecuteError(
+  toolName: string,
+  resolvedInput: Record<string, unknown>,
+  result: ToolExecutionResult,
+): ToolExecutionResult {
+  if (!result.isError || Object.keys(resolvedInput).length > 0) return result;
+
+  const guidance =
+    `\n\nThis skill_execute call carried no parameters for "${toolName}". ` +
+    `Put the tool's parameters inside \`input\`. For example: ` +
+    `{"tool": "${toolName}", "input": { /* the tool's parameters */ }, ` +
+    `"activity": "..."}. The skill's instructions (from skill_load) list ` +
+    `"${toolName}"'s required fields.`;
+
+  return { ...result, content: result.content + guidance };
+}
+
 export const skillExecuteTool = {
   name: "skill_execute",
   description: