@vellumai/assistant 0.12.3 → 0.12.4-dev.202609231620.a15f321

package/src/tools/network/__tests__/web-fetch-tinyfish.test.ts

@@ -1,4 +1,12 @@
-import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
 
 import { setConfig } from "../../../__tests__/helpers/set-config.js";
 
@@ -101,6 +109,32 @@ describe("executeTinyfishFetch", () => {
     );
   });
 
+  test("an empty upstream title is no title", async () => {
+    spyOn(globalThis, "fetch").mockResolvedValue(
+      fetchResponse({
+        results: [
+          {
+            url: "https://example.com/",
+            final_url: "https://example.com/",
+            title: "  ",
+            text: "# Example",
+            format: "markdown",
+          },
+        ],
+        errors: [],
+      }),
+    );
+
+    const result = await executeTinyfishFetch(
+      { url: "https://example.com" },
+      { apiKey: "tf_test" },
+    );
+
+    expect(result.isError).toBe(false);
+    expect(result.activityMetadata?.webFetch?.title).toBeUndefined();
+    expect(result.content).not.toContain("Title:");
+  });
+
   test("uses a custom API base and applies character windows", async () => {
     seedWebFetch("tinyfish", "https://fetch.example.com/api/");
     let capturedUrl = "";

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

@@ -12,6 +12,7 @@ let mockKeenableSecureKey: string | undefined;
 let mockFastcrwSecureKey: string | undefined;
 let mockSearxngSecureKey: string | undefined;
 let mockTinyfishSecureKey: string | undefined;
+let mockExaSecureKey: string | undefined;
 let mockManagedSearchProxyResult: any;
 let mockManagedSearchAvailable = true;
 let mockManagedSearchProxyCalls: Array<{
@@ -65,6 +66,9 @@ mock.module("../../../security/secure-keys.js", () => ({
     if (provider === "tinyfish") {
       return mockTinyfishSecureKey;
     }
+    if (provider === "exa") {
+      return mockExaSecureKey;
+    }
     return undefined;
   },
 }));
@@ -111,6 +115,7 @@ describe("web_search tool", () => {
     mockFastcrwSecureKey = undefined;
     mockSearxngSecureKey = undefined;
     mockTinyfishSecureKey = undefined;
+    mockExaSecureKey = undefined;
     mockManagedSearchProxyCalls = [];
     mockManagedSearchAvailable = true;
     mockManagedSearchProxyResult = {
@@ -1345,6 +1350,97 @@ describe("web_search tool", () => {
     },
   );
 
+  // ---- Exa provider ------------------------------------------------------
+
+  test("Exa search posts the recommended request and maps freshness", async () => {
+    seedWebSearch("your-own", "exa");
+    mockExaSecureKey = "exa_test";
+    let capturedUrl = "";
+    let capturedInit: RequestInit | undefined;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      capturedUrl = url;
+      capturedInit = init;
+      return new Response(
+        JSON.stringify({
+          requestId: "r1",
+          results: [
+            {
+              title: "Exa Result",
+              url: "https://example.com/exa",
+              publishedDate: "2026-09-18T00:00:00.000Z",
+              highlights: ["Fresh from Exa"],
+            },
+          ],
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as any;
+
+    const result = await execute({
+      query: "fresh tools",
+      freshness: "pw",
+      count: 5,
+    });
+
+    expect(result.isError).toBe(false);
+    expect(capturedUrl).toBe("https://api.exa.ai/search");
+    expect(capturedInit?.method).toBe("POST");
+    const headers = new Headers(capturedInit?.headers);
+    expect(headers.get("x-api-key")).toBe("exa_test");
+    const body = JSON.parse(String(capturedInit?.body));
+    expect(body.query).toBe("fresh tools");
+    expect(body.type).toBe("auto");
+    expect(body.numResults).toBe(5);
+    expect(body.contents.highlights).toBe(true);
+    expect(typeof body.startPublishedDate).toBe("string");
+    const delta = Date.now() - Date.parse(body.startPublishedDate);
+    expect(delta).toBeGreaterThan(7 * 24 * 60 * 60 * 1000 - 60_000);
+    expect(delta).toBeLessThan(7 * 24 * 60 * 60 * 1000 + 60_000);
+    expect(result.content).toContain("Exa Result");
+    expect(result.content).toContain("Fresh from Exa");
+    expect(result.activityMetadata?.webSearch?.provider).toBe("exa");
+  });
+
+  test("Exa omits the date filter without freshness and trims to count", async () => {
+    seedWebSearch("your-own", "exa");
+    mockExaSecureKey = "exa_test";
+    let capturedInit: RequestInit | undefined;
+    globalThis.fetch = (async (_url: string, init?: RequestInit) => {
+      capturedInit = init;
+      return new Response(
+        JSON.stringify({
+          results: [
+            { title: "A", url: "https://a.example.com", highlights: ["a"] },
+            { title: "B", url: "https://b.example.com", highlights: ["b"] },
+            { title: "C", url: "https://c.example.com", highlights: ["c"] },
+          ],
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as any;
+
+    const result = await execute({ query: "test", count: 2 });
+
+    const body = JSON.parse(String(capturedInit?.body));
+    expect(body.startPublishedDate).toBeUndefined();
+    expect(result.content).toContain("A");
+    expect(result.content).toContain("B");
+    expect(result.content).not.toContain("https://c.example.com");
+    expect(result.activityMetadata?.webSearch?.resultCount).toBe(2);
+  });
+
+  test.each([401, 402, 403])("Exa handles %d access error", async (status) => {
+    seedWebSearch("your-own", "exa");
+    mockExaSecureKey = "exa_test";
+    globalThis.fetch = (async () =>
+      new Response(JSON.stringify({ error: "denied" }), { status })) as any;
+
+    const result = await execute({ query: "test" });
+
+    expect(result.isError).toBe(true);
+    expect(result.activityMetadata?.webSearch?.provider).toBe("exa");
+  });
+
   // ---- Provider fallback --------------------------------------------------
 
   test("falls back from perplexity to brave when perplexity has no key", async () => {

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

@@ -58,6 +58,15 @@ const MAX_TIMEOUT_SECONDS = 60;
 const DEFAULT_MAX_CHARS = 12_000;
 const MAX_MAX_CHARS = 40_000;
 const MAX_DOWNLOAD_BYTES = 2_000_000;
+
+/**
+ * The metadata this assistant writes. `startIndexPastEnd` is optional on the
+ * wire because older records lack it; every writer here sets it, which is how
+ * a reader tells this metadata carries every reader-facing warning.
+ */
+type WrittenWebFetchMetadata = WebFetchMetadata & {
+  startIndexPastEnd: boolean;
+};
 const MAX_REDIRECTS = 10;
 
 const TEXT_LIKE_CONTENT_TYPES = [
@@ -672,7 +681,8 @@ export async function executeWebFetch(
           redirectCount: meta.redirectCount ?? 0,
           durationMs: Date.now() - startedAt,
           errorMessage,
-        },
+          startIndexPastEnd: false,
+        } satisfies WrittenWebFetchMetadata,
       },
     };
   };
@@ -1023,7 +1033,7 @@ export async function executeWebFetch(
     const truncated = body.truncated || safeEnd < processed.length;
     const parsedTitle = html ? parseHtmlTitle(body.text) : undefined;
     const finalDomain = extractDomain(currentUrl.href);
-    const meta: WebFetchMetadata = {
+    const meta: WrittenWebFetchMetadata = {
       url: safeRequestedUrl,
       finalUrl: sanitizeUrlForOutput(currentUrl),
       provider: "default",
@@ -1038,6 +1048,9 @@ export async function executeWebFetch(
       redirectCount,
       durationMs: Date.now() - startedAt,
       mayRequireJavaScript: mayRequireJavaScript || undefined,
+      // Past the end of the page only when the whole page was downloaded: past
+      // a capped prefix, the page may still have content at that offset.
+      startIndexPastEnd: !body.truncated && startIndex > processed.length,
     };
 
     if (!response.ok) {
@@ -1223,7 +1236,8 @@ function hostedScrapeErrorResult(
         redirectCount: 0,
         durationMs: Date.now() - startedAt,
         errorMessage,
-      },
+        startIndexPastEnd: false,
+      } satisfies WrittenWebFetchMetadata,
     },
   };
 }
@@ -1394,6 +1408,8 @@ export async function executeFirecrawlCompatScrape(
         );
       }
 
+      // A provider can pass an empty upstream title through; empty is no title.
+      const title = scrapeMeta.title?.trim() || undefined;
       const content = formatWebFetchOutput({
         requestedUrl: safeRequestedUrl,
         finalUrl,
@@ -1405,7 +1421,7 @@ export async function executeFirecrawlCompatScrape(
         startIndex: safeStart,
         endIndex: safeEnd,
         content: sliced,
-        title: scrapeMeta.title,
+        title,
         description: scrapeMeta.description,
         notices,
         raw: false,
@@ -1413,7 +1429,7 @@ export async function executeFirecrawlCompatScrape(
       });
 
       const finalDomain = extractDomain(finalUrl);
-      const meta: WebFetchMetadata = {
+      const meta: WrittenWebFetchMetadata = {
         url: safeRequestedUrl,
         finalUrl,
         provider: options.provider,
@@ -1422,11 +1438,13 @@ export async function executeFirecrawlCompatScrape(
         byteCount: bytesRead,
         charCount: sliced.length,
         truncated: safeEnd < processed.length,
-        title: scrapeMeta.title,
+        title,
         domain: finalDomain,
         faviconUrl: faviconUrlForDomain(finalDomain),
         redirectCount: 0,
         durationMs: Date.now() - startedAt,
+        startIndexPastEnd: startIndex > processed.length,
+        providerWarning: warning || undefined,
       };
 
       return {
@@ -1670,6 +1688,8 @@ export async function executeTinyfishFetch(
         );
       }
 
+      // A provider can pass an empty upstream title through; empty is no title.
+      const title = page.title?.trim() || undefined;
       const content = formatWebFetchOutput({
         requestedUrl: safeRequestedUrl,
         finalUrl,
@@ -1681,14 +1701,14 @@ export async function executeTinyfishFetch(
         startIndex: safeStart,
         endIndex: safeEnd,
         content: sliced,
-        title: page.title ?? undefined,
+        title,
         description: page.description ?? undefined,
         notices,
         raw: false,
         markdown: true,
       });
       const finalDomain = extractDomain(finalUrl);
-      const metadata: WebFetchMetadata = {
+      const metadata: WrittenWebFetchMetadata = {
         url: safeRequestedUrl,
         finalUrl,
         provider: "tinyfish",
@@ -1697,11 +1717,12 @@ export async function executeTinyfishFetch(
         byteCount: bytesRead,
         charCount: sliced.length,
         truncated: safeEnd < processed.length,
-        title: page.title ?? undefined,
+        title,
         domain: finalDomain,
         faviconUrl: faviconUrlForDomain(finalDomain),
         redirectCount: finalUrl === safeRequestedUrl ? 0 : 1,
         durationMs: Date.now() - startedAt,
+        startIndexPastEnd: startIndex > processed.length,
       };
       return {
         content,

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

@@ -45,6 +45,7 @@ const TAVILY_API_URL = "https://api.tavily.com/search";
 const FIRECRAWL_API_URL = "https://api.firecrawl.dev/v2/search";
 const FASTCRW_SEARCH_PATH = "/v1/search";
 const TINYFISH_DEFAULT_SEARCH_API_BASE = "https://api.search.tinyfish.ai";
+const EXA_API_URL = "https://api.exa.ai/search";
 // Keenable is keyless by default: the public path needs no key (rate-limited);
 // a key switches to the authenticated path and lifts the cap.
 const KEENABLE_API_BASE_URL = "https://api.keenable.ai";
@@ -59,7 +60,8 @@ type WebSearchProvider =
   | "keenable"
   | "fastcrw"
   | "searxng"
-  | "tinyfish";
+  | "tinyfish"
+  | "exa";
 
 /**
  * Arguments passed to every {@link WebSearchAdapter}. The full superset is
@@ -197,6 +199,20 @@ interface TinyfishSearchResponse {
   page?: number;
 }
 
+interface ExaSearchResult {
+  id?: string;
+  title?: string | null;
+  url?: string;
+  publishedDate?: string | null;
+  author?: string | null;
+  highlights?: string[];
+}
+
+interface ExaSearchResponse {
+  requestId?: string;
+  results?: ExaSearchResult[];
+}
+
 const SEARXNG_MISSING_INSTANCE_MESSAGE =
   "SearXNG needs an instance URL. Set API Base in Settings under Web Search.";
 const SEARXNG_JSON_DISABLED_MESSAGE =
@@ -716,6 +732,84 @@ function buildTinyfishMetadata(
   };
 }
 
+function formatExaResults(data: ExaSearchResponse, 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 result = results[i];
+    const title =
+      result.title?.trim() || result.url?.trim() || "Untitled result";
+    lines.push(`${i + 1}. ${title}`);
+    if (result.url) {
+      lines.push(`   URL: ${result.url}`);
+    }
+    const snippet = result.highlights?.join(" ").trim();
+    if (snippet) {
+      lines.push(`   ${snippet}`);
+    }
+    if (result.publishedDate) {
+      lines.push(`   Published: ${result.publishedDate}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+function buildExaMetadata(
+  data: ExaSearchResponse,
+  query: string,
+  durationMs: number,
+): WebSearchMetadata {
+  const results = data.results ?? [];
+  const items: WebSearchResultItem[] = results.map((result, index) => {
+    const url = result.url ?? "";
+    const domain = extractDomain(url);
+    return {
+      rank: index + 1,
+      title: result.title?.trim() || url.trim() || "Untitled result",
+      url,
+      domain,
+      faviconUrl: faviconUrlForDomain(domain),
+      snippet: result.highlights?.join(" ").trim() || undefined,
+    };
+  });
+  return {
+    query,
+    provider: "exa",
+    resultCount: items.length,
+    durationMs,
+    results: items,
+  };
+}
+
+function exaStartPublishedDateForFreshness(
+  freshness: string | undefined,
+  now: number = Date.now(),
+): string | undefined {
+  let days: number;
+  switch (freshness) {
+    case "pd":
+      days = 1;
+      break;
+    case "pw":
+      days = 7;
+      break;
+    case "pm":
+      days = 30;
+      break;
+    case "py":
+      days = 365;
+      break;
+    default:
+      return undefined;
+  }
+  return new Date(now - days * 24 * 60 * 60 * 1000).toISOString();
+}
+
 function tinyfishRecencyMinutesForFreshness(
   freshness: string | undefined,
 ): number | undefined {
@@ -1801,6 +1895,134 @@ async function executeTinyfishSearch(
   );
 }
 
+async function executeExaSearch(
+  query: string,
+  count: number,
+  freshness: string | undefined,
+  apiKey: string,
+  signal?: AbortSignal,
+): Promise<ToolExecutionResult> {
+  const startedAt = Date.now();
+  const requestBody: Record<string, unknown> = {
+    query,
+    type: "auto",
+    numResults: count,
+    contents: { highlights: true },
+  };
+  const startPublishedDate = exaStartPublishedDateForFreshness(freshness);
+  if (startPublishedDate !== undefined) {
+    requestBody.startPublishedDate = startPublishedDate;
+  }
+
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    "x-api-key": apiKey.trim(),
+  };
+
+  for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
+    let response: Response;
+    try {
+      response = await fetch(EXA_API_URL, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(requestBody),
+        signal,
+      });
+    } catch (err) {
+      return networkFailureResult(query, "exa", startedAt, err, signal);
+    }
+
+    const bodyText = await response.text();
+    if (response.ok) {
+      let data: ExaSearchResponse;
+      try {
+        data = JSON.parse(bodyText) as ExaSearchResponse;
+      } catch {
+        return errorResult(
+          query,
+          "exa",
+          startedAt,
+          "Exa Search returned an invalid JSON payload.",
+        );
+      }
+      if (data.results && data.results.length > count) {
+        data.results = data.results.slice(0, count);
+      }
+      const durationMs = Date.now() - startedAt;
+      return {
+        content:
+          wrapUntrustedContent(formatExaResults(data, query), {
+            source: "search",
+            sourceDetail: "exa",
+          }) + CITATION_INSTRUCTION,
+        isError: false,
+        activityMetadata: {
+          webSearch: buildExaMetadata(data, query, durationMs),
+        },
+      };
+    }
+
+    if (response.status === 401) {
+      return errorResult(
+        query,
+        "exa",
+        startedAt,
+        "Invalid or expired Exa API key",
+      );
+    }
+    if (response.status === 402) {
+      return errorResult(
+        query,
+        "exa",
+        startedAt,
+        "Exa account has no remaining credits.",
+      );
+    }
+    if (response.status === 403) {
+      return errorResult(
+        query,
+        "exa",
+        startedAt,
+        "Exa Search request was forbidden by the upstream service.",
+      );
+    }
+
+    if (response.status === 429 && attempt < DEFAULT_MAX_RETRIES) {
+      const delayMs = getHttpRetryDelay(
+        response,
+        attempt,
+        DEFAULT_BASE_DELAY_MS,
+      );
+      log.warn(
+        { attempt: attempt + 1, delayMs },
+        "Exa Search rate limited, retrying",
+      );
+      await sleep(delayMs);
+      continue;
+    }
+
+    log.warn({ status: response.status }, "Exa Search API error");
+    return backendFailureResult(
+      query,
+      "exa",
+      startedAt,
+      { statusCode: response.status, error: rawBodyDetail(bodyText) },
+      response.status === 429
+        ? "Exa Search rate limit exceeded after retries. Try again shortly."
+        : `Exa Search API returned status ${response.status}`,
+    );
+  }
+
+  return backendFailureResult(
+    query,
+    "exa",
+    startedAt,
+    { statusCode: 429 },
+    "Exa Search rate limit exceeded after retries. Try again shortly.",
+  );
+}
+
 // ----------------------------------------------------------------------------
 // Adapter registry
 //
@@ -1884,6 +2106,14 @@ const tinyfishSearchAdapter: WebSearchAdapter = {
     executeTinyfishSearch(query, count, freshness, apiKey, signal),
 };
 
+const exaSearchAdapter: WebSearchAdapter = {
+  id: "exa",
+  providerKeyName: "exa",
+  fallbackOrder: 9,
+  execute: ({ query, count, freshness, apiKey, signal }) =>
+    executeExaSearch(query, count, freshness, apiKey, signal),
+};
+
 /**
  * All built-in web-search adapters keyed by provider id. The
  * `Record<WebSearchProvider, ...>` shape forces TypeScript to flag any
@@ -1898,6 +2128,7 @@ const WEB_SEARCH_ADAPTERS: Record<WebSearchProvider, WebSearchAdapter> = {
   fastcrw: fastcrwSearchAdapter,
   searxng: searxngSearchAdapter,
   tinyfish: tinyfishSearchAdapter,
+  exa: exaSearchAdapter,
 };
 
 /**
@@ -1929,7 +2160,7 @@ export const webSearchTool = {
       count: {
         type: "number",
         description:
-          "Number of results to return (1-20, default 10). Used with Brave, Tavily, Firecrawl, Keenable, fastCRW, SearXNG, and TinyFish providers.",
+          "Number of results to return (1-20, default 10). Used with Brave, Tavily, Firecrawl, Keenable, fastCRW, SearXNG, TinyFish, and Exa providers.",
       },
       offset: {
         type: "number",
@@ -1939,7 +2170,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, Tavily, Firecrawl, Keenable, fastCRW, SearXNG, and TinyFish providers. SearXNG maps day/month/year and omits week.',
+          'Filter by recency: "pd" (past day), "pw" (past week), "pm" (past month), "py" (past year). Used with Brave, Tavily, Firecrawl, Keenable, fastCRW, SearXNG, TinyFish, and Exa providers. SearXNG maps day/month/year and omits week.',
       },
     },
     required: ["query"],
@@ -2055,7 +2286,7 @@ export const webSearchTool = {
           query,
           provider,
           startedAt,
-          "No web search API key configured. Set it via `keys set perplexity <key>`, `keys set brave <key>`, `keys set tavily <key>`, `keys set firecrawl <key>`, or `keys set fastcrw <key>`, or `keys set tinyfish <key>`, or configure it from the Settings page under API Keys. Or switch the web-search provider to Keenable, which works without a key, or SearXNG with your instance URL.",
+          "No web search API key configured. Set it via `keys set perplexity <key>`, `keys set brave <key>`, `keys set tavily <key>`, `keys set firecrawl <key>`, or `keys set fastcrw <key>`, or `keys set tinyfish <key>`, or `keys set exa <key>`, or configure it from the Settings page under API Keys. Or switch the web-search provider to Keenable, which works without a key, or SearXNG with your instance URL.",
         );
       }
     }

package/src/tools/skills/execute.ts

@@ -178,7 +178,7 @@ export function augmentSkillExecuteError(
 export const skillExecuteTool = {
   name: "skill_execute",
   description:
-    "Execute a tool provided by a loaded skill. Use this instead of calling skill tools directly. The skill's instructions (from skill_load) describe available tools and their parameters. For browser automation, use the `assistant browser` CLI commands instead.",
+    "Execute a tool provided by a loaded skill. When skill_load is available, call it for the owning skill before first use, even if a capability card says it is available. Use the current instructions and input schema over remembered arguments. Use this instead of calling skill tools directly. For browser automation, use the `assistant browser` CLI commands instead.",
   category: "skills",
   executionTarget: "sandbox",
   defaultRiskLevel: RiskLevel.Low,

package/src/tools/skills/format-input-schema.ts

@@ -0,0 +1,15 @@
+import { getWorkspaceDirDisplay } from "../../util/platform.js";
+
+/** Preserve nested fields and alternatives when disclosing a skill's input. */
+export function formatSkillInputSchema(schema: object): string {
+  const workspaceDir = getWorkspaceDirDisplay();
+  const json = JSON.stringify(
+    schema,
+    (_key, value: unknown) =>
+      typeof value === "string"
+        ? value.replaceAll("{workspaceDir}", workspaceDir)
+        : value,
+    2,
+  );
+  return `Input schema for \`skill_execute.input\`:\n\`\`\`json\n${json}\n\`\`\``;
+}