@vellumai/assistant 0.11.5 → 0.11.6-staging.1

package/src/telemetry/live-voice-funnel.ts

@@ -58,18 +58,85 @@ export type LiveVoiceStepName =
 export type LiveVoiceSessionOutcome = "completed" | "failed";
 
 /**
- * The `screen` dimension for an ended session: how it closed, plus the
- * protocol error code when a failure is what closed it.
+ * How far a session that produced NO turn actually got.
  *
- * Both halves are the daemon's own vocabulary verbatim
- * (`LiveVoiceSessionCloseReason`, `LiveVoiceProtocolErrorCode`) rather than a
- * mapping, so a rename on either side surfaces here as a compile error instead
- * of a silently-empty dashboard facet. The longest pair this can produce is
- * well inside the wire field's 64-char bound.
+ * A quarter of live-voice sessions end without a single turn, at a median of a
+ * few seconds. That is the closest thing the telemetry has to a "voice didn't
+ * work for me" rate, and a bare connect/close row cannot separate a denied
+ * microphone from a muted one from someone deliberately backing out. Those have
+ * completely different fixes, so the reason is what makes the rate actionable.
+ *
+ * The four values are ordered by how far the session got, and each one narrows
+ * the cause to a different layer:
+ *
+ * - `no_ready`  never reached `active`: died in the credential preflight or
+ *               the transport, before the user could have said anything.
+ * - `no_audio`  reached `active` but not one audio chunk ever arrived, so the
+ *               microphone never opened. Permission denial looks like this.
+ * - `no_speech` audio arrived but the detector never classified any of it as
+ *               speech: a muted or dead mic, or a genuinely silent user.
+ * - `no_turn`   speech was detected but no turn was ever dispatched, so the
+ *               utterance was abandoned, aborted, or failed to arm.
+ */
+export type LiveVoiceSilenceReason =
+  | "no_ready"
+  | "no_audio"
+  | "no_speech"
+  | "no_turn";
+
+/**
+ * Classify a zero-turn session from what the session observed. Call only when
+ * the session really produced no turn: every branch here asserts silence, so a
+ * session that did dispatch a turn would be mislabelled by the last one.
+ */
+export function liveVoiceSilenceReason(signals: {
+  reachedActive: boolean;
+  receivedAudio: boolean;
+  detectedSpeech: boolean;
+}): LiveVoiceSilenceReason {
+  if (!signals.reachedActive) {
+    return "no_ready";
+  }
+  if (!signals.receivedAudio) {
+    return "no_audio";
+  }
+  if (!signals.detectedSpeech) {
+    return "no_speech";
+  }
+  return "no_turn";
+}
+
+/**
+ * The `screen` dimension for an ended session: how it closed, plus a detail
+ * half. That detail is the protocol error code when a failure closed it, or the
+ * silence classification when the session produced no turn at all.
+ *
+ * Every part is the daemon's own vocabulary verbatim
+ * (`LiveVoiceSessionCloseReason`, `LiveVoiceProtocolErrorCode`,
+ * {@link LiveVoiceSilenceReason}) rather than a mapping, so a rename on any of
+ * them surfaces here as a compile error instead of a silently-empty dashboard
+ * facet. The longest combination this can produce is well inside the wire
+ * field's 64-char bound.
+ *
+ * A failure code wins over a silence reason when both apply: a session that
+ * died on an error is explained by the error, and the silence is a consequence
+ * of it rather than a separate finding.
+ *
+ * The silence value carries a `silent_` prefix on purpose. It shares the detail
+ * slot with failure codes, and the admin dashboard currently renders that slot
+ * in a column labelled "failure code", so the value has to read correctly even
+ * where the column header is wrong, until that panel learns the difference.
  */
 export function liveVoiceEndScreen(
   reason: LiveVoiceSessionCloseReason,
   failureCode?: LiveVoiceProtocolErrorCode | null,
+  silenceReason?: LiveVoiceSilenceReason | null,
 ): string {
-  return failureCode ? `ended_${reason}:${failureCode}` : `ended_${reason}`;
+  if (failureCode) {
+    return `ended_${reason}:${failureCode}`;
+  }
+  if (silenceReason) {
+    return `ended_${reason}:silent_${silenceReason}`;
+  }
+  return `ended_${reason}`;
 }

package/src/tools/credentials/store.ts

@@ -10,12 +10,13 @@
  * the plugin-facing {@link ../../plugin-api/store-credential.storeCredential}
  * both compose it.
  *
- * The transcript scrub and the connection sync are imported lazily, at the
- * point of use. Both pull heavy graphs behind them (the scrub reaches the
- * conversation database and registry; the sync reaches the OAuth store), and
- * this module sits under `@vellumai/plugin-api`, so a static edge would drag
- * that machinery into every plugin-api consumer for a write most of them never
- * perform.
+ * The transcript scrub, connection sync, and provider rotation refresh are
+ * imported lazily, at the point of use. They pull heavy graphs behind them
+ * (the scrub reaches the conversation database and registry, the sync reaches
+ * the OAuth store, and the refresh reaches the provider and conversation
+ * graphs), and this module sits under `@vellumai/plugin-api`, so static edges
+ * would drag that machinery into every plugin-api consumer for a write most of
+ * them never perform.
  *
  * Callers own their own transport-level argument validation and error mapping;
  * this module throws {@link InvalidCredentialInputError} for a value it will
@@ -164,5 +165,16 @@ export async function storeCredentialValue(
     await import("../../oauth/manual-token-connection.js");
   await syncManualTokenConnection(service);
 
+  try {
+    const { refreshProvidersForRotatedCredential } =
+      await import("../../providers/inference/credential-rotation.js");
+    await refreshProvidersForRotatedCredential(service, field);
+  } catch (err) {
+    log.warn(
+      { err, service, field },
+      "Credential stored, but provider rotation refresh failed",
+    );
+  }
+
   return { credentialId: metadata.credentialId, service, field };
 }

package/src/tools/network/__tests__/firecrawl-compat.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  extractFirecrawlCompatSearchResults,
+  resolveProviderApiUrl,
+  searchResultSnippet,
+} from "../firecrawl-compat.js";
+
+describe("resolveProviderApiUrl", () => {
+  test("uses the default base when apiBase is empty", () => {
+    expect(
+      resolveProviderApiUrl("", "/v1/search", "https://api.fastcrw.com"),
+    ).toBe("https://api.fastcrw.com/v1/search");
+    expect(
+      resolveProviderApiUrl(undefined, "/v1/scrape", "https://api.fastcrw.com"),
+    ).toBe("https://api.fastcrw.com/v1/scrape");
+  });
+
+  test("strips trailing slashes from a custom base", () => {
+    expect(
+      resolveProviderApiUrl(
+        "http://localhost:3000///",
+        "/v1/search",
+        "https://api.fastcrw.com",
+      ),
+    ).toBe("http://localhost:3000/v1/search");
+  });
+});
+
+describe("extractFirecrawlCompatSearchResults", () => {
+  test("reads grouped data.web", () => {
+    expect(
+      extractFirecrawlCompatSearchResults({
+        data: { web: [{ title: "A", url: "https://a.test" }] },
+      }),
+    ).toEqual([{ title: "A", url: "https://a.test" }]);
+  });
+
+  test("reads data.results as a flat array", () => {
+    expect(
+      extractFirecrawlCompatSearchResults({
+        data: { results: [{ title: "B", url: "https://b.test" }] },
+      }),
+    ).toEqual([{ title: "B", url: "https://b.test" }]);
+  });
+
+  test("reads self-hosted data.results.web when sources group by type", () => {
+    expect(
+      extractFirecrawlCompatSearchResults({
+        data: {
+          results: {
+            web: [{ title: "Self-host", url: "https://local.test" }],
+            news: [{ title: "News", url: "https://news.test" }],
+          },
+        },
+      }),
+    ).toEqual([{ title: "Self-host", url: "https://local.test" }]);
+  });
+
+  test("reads a flat data array", () => {
+    expect(
+      extractFirecrawlCompatSearchResults({
+        data: [{ title: "C", url: "https://c.test" }],
+      }),
+    ).toEqual([{ title: "C", url: "https://c.test" }]);
+  });
+});
+
+describe("searchResultSnippet", () => {
+  test("prefers description then snippet", () => {
+    expect(
+      searchResultSnippet({ description: "desc", snippet: "snip" }),
+    ).toBe("desc");
+    expect(searchResultSnippet({ snippet: "snip" })).toBe("snip");
+    expect(searchResultSnippet({})).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,169 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { setConfig } from "../../../__tests__/helpers/set-config.js";
+
+let mockFastcrwSecureKey: string | undefined;
+
+function seedWebFetch(provider: string, apiBase?: string): void {
+  const entry: Record<string, string> = { provider };
+  if (apiBase !== undefined) {
+    entry.apiBase = apiBase;
+  }
+  setConfig("services", { "web-fetch": entry });
+}
+
+mock.module("../../../security/secure-keys.js", () => ({
+  getProviderKeyAsync: async (provider: string) =>
+    provider === "fastcrw" ? mockFastcrwSecureKey : undefined,
+}));
+
+const realLogger = await import("../../../util/logger.js");
+mock.module("../../../util/logger.js", () => ({
+  ...realLogger,
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, { get: () => () => {} }),
+}));
+
+mock.module("../../../permissions/types.js", () => ({
+  RiskLevel: { Low: "low", Medium: "medium", High: "high" },
+}));
+
+let mockResolveAddresses: string[] = [];
+const realUrlSafety = await import("../url-safety.js");
+mock.module("../url-safety.js", () => ({
+  ...realUrlSafety,
+  resolveHostAddresses: async () => mockResolveAddresses,
+}));
+
+const { executeFastcrwScrape, webFetchTool } = await import("../web-fetch.js");
+
+function scrapeResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+describe("executeFastcrwScrape", () => {
+  let originalFetch: typeof globalThis.fetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    mockFastcrwSecureKey = undefined;
+    mockResolveAddresses = ["93.184.216.34"];
+  });
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test("hits the cloud default /v1/scrape endpoint", async () => {
+    let capturedUrl = "";
+    let capturedHeaders: any = null;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      capturedUrl = url;
+      capturedHeaders = new Headers(init?.headers);
+      return scrapeResponse({
+        success: true,
+        data: {
+          markdown: "# Hello\n\nFrom fastCRW.",
+          metadata: {
+            title: "Example",
+            url: "https://example.com/",
+            statusCode: 200,
+          },
+        },
+      });
+    }) as typeof fetch;
+
+    const result = await executeFastcrwScrape(
+      { url: "https://example.com" },
+      { apiKey: "crw_live_test" },
+    );
+
+    expect(result.isError).toBe(false);
+    expect(capturedUrl).toBe("https://api.fastcrw.com/v1/scrape");
+    expect(capturedHeaders?.get("authorization")).toBe("Bearer crw_live_test");
+    expect(result.activityMetadata?.webFetch?.provider).toBe("fastcrw");
+    expect(result.content).toContain("From fastCRW.");
+  });
+
+  test("uses a custom API base from config", async () => {
+    seedWebFetch("fastcrw", "http://localhost:3000/");
+    let capturedUrl = "";
+    globalThis.fetch = (async (url: string) => {
+      capturedUrl = url;
+      return scrapeResponse({
+        success: true,
+        data: { markdown: "local", metadata: { statusCode: 200 } },
+      });
+    }) as typeof fetch;
+
+    const result = await executeFastcrwScrape(
+      { url: "https://example.com" },
+      { apiKey: "" },
+    );
+
+    expect(result.isError).toBe(false);
+    expect(capturedUrl).toBe("http://localhost:3000/v1/scrape");
+  });
+});
+
+describe("webFetchTool fastCRW dispatch", () => {
+  let originalFetch: typeof globalThis.fetch;
+
+  const execute = (input: Record<string, unknown>, ctx: any = {}) =>
+    webFetchTool.execute(input, ctx);
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    mockFastcrwSecureKey = "crw_live_test";
+    mockResolveAddresses = ["93.184.216.34"];
+  });
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test("routes to fastCRW when provider=fastcrw and a key is set", async () => {
+    seedWebFetch("fastcrw");
+    let fastcrwHit = false;
+    globalThis.fetch = (async (url: string) => {
+      if (String(url).includes("api.fastcrw.com")) {
+        fastcrwHit = true;
+      }
+      return scrapeResponse({
+        success: true,
+        data: {
+          markdown: "ok",
+          metadata: { statusCode: 200, url: "https://example.com/" },
+        },
+      });
+    }) as typeof fetch;
+
+    const result = await execute({ url: "https://example.com" });
+    expect(fastcrwHit).toBe(true);
+    expect(result.activityMetadata?.webFetch?.provider).toBe("fastcrw");
+  });
+
+  test("routes to fastCRW without a key when a custom API base is set", async () => {
+    seedWebFetch("fastcrw", "http://127.0.0.1:3000");
+    mockFastcrwSecureKey = undefined;
+    let capturedUrl = "";
+    let capturedHeaders: any = null;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      capturedUrl = String(url);
+      capturedHeaders = new Headers(init?.headers);
+      return scrapeResponse({
+        success: true,
+        data: {
+          markdown: "self-host",
+          metadata: { statusCode: 200, url: "https://example.com/" },
+        },
+      });
+    }) as typeof fetch;
+
+    const result = await execute({ url: "https://example.com" });
+    expect(capturedUrl).toBe("http://127.0.0.1:3000/v1/scrape");
+    expect(capturedHeaders?.get("authorization")).toBeNull();
+    expect(result.activityMetadata?.webFetch?.provider).toBe("fastcrw");
+  });
+});

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

@@ -9,6 +9,7 @@ let mockPerplexitySecureKey: string | undefined;
 let mockTavilySecureKey: string | undefined;
 let mockFirecrawlSecureKey: string | undefined;
 let mockKeenableSecureKey: string | undefined;
+let mockFastcrwSecureKey: string | undefined;
 let mockManagedSearchProxyResult: any;
 let mockManagedSearchAvailable = true;
 let mockManagedSearchProxyCalls: Array<{
@@ -21,9 +22,18 @@ let mockManagedSearchProxyCalls: Array<{
  * Seed the web-search service into the workspace config. Pass `undefined`
  * for mode to write a post-migration-132 config carrying only `provider`.
  */
-function seedWebSearch(mode: string | undefined, provider: string): void {
+function seedWebSearch(
+  mode: string | undefined,
+  provider: string,
+  apiBase?: string,
+): void {
+  const entry: Record<string, string> =
+    mode === undefined ? { provider } : { mode, provider };
+  if (apiBase !== undefined) {
+    entry.apiBase = apiBase;
+  }
   setConfig("services", {
-    "web-search": mode === undefined ? { provider } : { mode, provider },
+    "web-search": entry,
   });
 }
 
@@ -44,6 +54,9 @@ mock.module("../../../security/secure-keys.js", () => ({
     if (provider === "keenable") {
       return mockKeenableSecureKey;
     }
+    if (provider === "fastcrw") {
+      return mockFastcrwSecureKey;
+    }
     return undefined;
   },
 }));
@@ -87,6 +100,7 @@ describe("web_search tool", () => {
     mockTavilySecureKey = undefined;
     mockFirecrawlSecureKey = undefined;
     mockKeenableSecureKey = undefined;
+    mockFastcrwSecureKey = undefined;
     mockManagedSearchProxyCalls = [];
     mockManagedSearchAvailable = true;
     mockManagedSearchProxyResult = {
@@ -1047,6 +1061,87 @@ describe("web_search tool", () => {
     expect(callCount).toBe(4);
   });
 
+  // ---- fastCRW provider ---------------------------------------------------
+
+  test("executes fastCRW search against the cloud default base", async () => {
+    seedWebSearch("your-own", "fastcrw");
+    mockFastcrwSecureKey = "crw_live_test";
+    let capturedUrl = "";
+    globalThis.fetch = (async (url: string) => {
+      capturedUrl = url;
+      return new Response(
+        JSON.stringify({
+          success: true,
+          data: {
+            web: [
+              {
+                title: "fastCRW Result",
+                url: "https://example.com/crw",
+                description: "From fastCRW",
+              },
+            ],
+          },
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as any;
+
+    const result = await execute({ query: "rust scraper" });
+    expect(result.isError).toBe(false);
+    expect(capturedUrl).toBe("https://api.fastcrw.com/v1/search");
+    expect(result.content).toContain("fastCRW Result");
+    expect(result.activityMetadata?.webSearch?.provider).toBe("fastcrw");
+  });
+
+  test("fastCRW uses a custom API base and accepts flat data arrays", async () => {
+    seedWebSearch("your-own", "fastcrw", "http://localhost:3000/");
+    mockFastcrwSecureKey = "crw_live_test";
+    let capturedUrl = "";
+    globalThis.fetch = (async (url: string) => {
+      capturedUrl = url;
+      return new Response(
+        JSON.stringify({
+          success: true,
+          data: [
+            {
+              title: "Flat Result",
+              url: "https://example.com/flat",
+              snippet: "Portable flat shape",
+            },
+          ],
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as any;
+
+    const result = await execute({ query: "flat" });
+    expect(result.isError).toBe(false);
+    expect(capturedUrl).toBe("http://localhost:3000/v1/search");
+    expect(result.content).toContain("Flat Result");
+    expect(result.content).toContain("Portable flat shape");
+  });
+
+  test("fastCRW self-host with custom base runs without an API key", async () => {
+    seedWebSearch("your-own", "fastcrw", "http://127.0.0.1:3000");
+    mockFastcrwSecureKey = undefined;
+    let capturedHeaders: any = null;
+    globalThis.fetch = (async (_url: string, init?: RequestInit) => {
+      capturedHeaders = new Headers(init?.headers);
+      return new Response(
+        JSON.stringify({
+          success: true,
+          data: { results: [{ title: "Local", url: "https://local.test" }] },
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as any;
+
+    const result = await execute({ query: "local" });
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("Local");
+    expect(capturedHeaders?.get("authorization")).toBeNull();
+  });
+
   // ---- Provider fallback --------------------------------------------------
 
   test("falls back from perplexity to brave when perplexity has no key", async () => {

package/src/tools/network/firecrawl-compat.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared helpers for Firecrawl-compatible scrape/search HTTP APIs
+ * (Firecrawl hosted `/v2/*` and fastCRW `/v1/*`).
+ */
+
+export const FASTCRW_DEFAULT_API_BASE = "https://api.fastcrw.com";
+
+/**
+ * Join an API origin with a path. Empty / whitespace `apiBase` uses
+ * `defaultBase`. Trailing slashes on the base are stripped.
+ */
+export function resolveProviderApiUrl(
+  apiBase: string | undefined,
+  path: string,
+  defaultBase: string,
+): string {
+  const trimmed = apiBase?.trim() ?? "";
+  const origin = (trimmed.length > 0 ? trimmed : defaultBase).replace(
+    /\/+$/,
+    "",
+  );
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${origin}${normalizedPath}`;
+}
+
+export interface FirecrawlCompatSearchResult {
+  title?: string;
+  description?: string;
+  snippet?: string;
+  url?: string;
+  category?: string;
+}
+
+/**
+ * Portable read of Firecrawl / fastCRW search payloads:
+ * - grouped: `data.web` (Firecrawl `/v2/search`, hosted CRW with sources)
+ * - self-hosted with sources: `data.results.web` (object keyed by source)
+ * - self-hosted flat: `data.results` (array)
+ * - hosted flat: `data` is the array itself
+ */
+export function extractFirecrawlCompatSearchResults(
+  data: unknown,
+): FirecrawlCompatSearchResult[] {
+  if (!data || typeof data !== "object") {
+    return [];
+  }
+  const root = data as Record<string, unknown>;
+  const payload = root.data;
+
+  if (Array.isArray(payload)) {
+    return payload as FirecrawlCompatSearchResult[];
+  }
+
+  if (payload && typeof payload === "object") {
+    const nested = payload as Record<string, unknown>;
+    if (Array.isArray(nested.web)) {
+      return nested.web as FirecrawlCompatSearchResult[];
+    }
+    // Self-hosted CRW with sources:["web"] nests rows under data.results.web
+    // (an object keyed by source), not data.results as a flat array.
+    if (
+      nested.results &&
+      typeof nested.results === "object" &&
+      !Array.isArray(nested.results)
+    ) {
+      const resultsBySource = nested.results as Record<string, unknown>;
+      if (Array.isArray(resultsBySource.web)) {
+        return resultsBySource.web as FirecrawlCompatSearchResult[];
+      }
+      const firstSourceKey = Object.keys(resultsBySource).find((key) =>
+        Array.isArray(resultsBySource[key]),
+      );
+      if (firstSourceKey) {
+        return resultsBySource[firstSourceKey] as FirecrawlCompatSearchResult[];
+      }
+    }
+    if (Array.isArray(nested.results)) {
+      return nested.results as FirecrawlCompatSearchResult[];
+    }
+  }
+
+  return [];
+}
+
+export function searchResultSnippet(
+  result: FirecrawlCompatSearchResult,
+): string | undefined {
+  const text = result.description || result.snippet;
+  return text?.trim() || undefined;
+}