@vellumai/assistant 0.8.7 → 0.8.8

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

@@ -0,0 +1,267 @@
+// Single source of truth for classifying `web_search` provider/backend
+// failures and the user-facing copy we surface for them (ATL-727).
+//
+// This is a pure leaf module: it has NO imports from `daemon/`, `agent/`,
+// `apps/`, or any client/UI package. It may only import the logger and pino
+// types (for the telemetry helper). Every web_search code path — native
+// Anthropic handler, app-side providers, and the web client default — funnels
+// failures through `classifyWebSearchFailure` so the same friendly message
+// propagates to every client via `WebSearchMetadata.errorMessage`.
+
+import type { Logger } from "pino";
+
+import { isAbortReason } from "../../util/abort-reasons.js";
+import { truncateForLog } from "../../util/logger.js";
+import { isRetryableNetworkError } from "../../util/retry.js";
+
+/**
+ * Canonical user-facing copy for a recoverable web_search backend failure.
+ * This is what propagates to every client via `WebSearchMetadata.errorMessage`.
+ *
+ * It names the search tool as the thing struggling, offers retry /
+ * continue-without-search / paste-details, does not blame the user, does not
+ * imply we can fix the provider, does not claim the whole internet or all
+ * tools are down, and contains no raw provider details, JSON, stack traces,
+ * or exception names.
+ */
+export const WEB_SEARCH_BACKEND_FAILURE_MESSAGE =
+  "Search is having trouble right now. You can try again in a moment, continue without web search, or paste the relevant details here and I'll use those.";
+
+const QUERY_TOO_LONG_MESSAGE =
+  "That search query was too long. Try a shorter query.";
+
+const MAX_USES_EXCEEDED_MESSAGE =
+  "I've hit the web-search limit for this turn. I can continue without more searches, or you can paste the details and I'll use those.";
+
+const CONFIG_MESSAGE = "Web search isn't configured.";
+
+export type WebSearchFailureCategory =
+  | "backend_unavailable"
+  | "rate_limited"
+  | "query_too_long"
+  | "max_uses_exceeded"
+  | "config"
+  | "no_results"
+  | "unknown";
+
+export interface WebSearchFailureClassification {
+  category: WebSearchFailureCategory;
+  isBackendFailure: boolean;
+  userMessage: string;
+  rawDetail: string;
+}
+
+export interface WebSearchFailureInput {
+  /** Anthropic `web_search_tool_result_error` code, when present. */
+  errorCode?: string;
+  /** Thrown error or rejected value from a fetch/provider call. */
+  error?: unknown;
+  /** HTTP status code from a provider response, when present. */
+  statusCode?: number;
+  /** Whether the tool result was flagged as an error. */
+  isError?: boolean;
+  /** Whether a successful call returned any results. */
+  hasResults?: boolean;
+}
+
+/** Categories we consider a transient backend failure worth the friendly copy. */
+function isBackendFailureCategory(category: WebSearchFailureCategory): boolean {
+  return category === "backend_unavailable" || category === "rate_limited";
+}
+
+function userMessageFor(category: WebSearchFailureCategory): string {
+  switch (category) {
+    case "backend_unavailable":
+    case "rate_limited":
+      return WEB_SEARCH_BACKEND_FAILURE_MESSAGE;
+    case "query_too_long":
+      return QUERY_TOO_LONG_MESSAGE;
+    case "max_uses_exceeded":
+      return MAX_USES_EXCEEDED_MESSAGE;
+    case "config":
+      return CONFIG_MESSAGE;
+    case "no_results":
+    case "unknown":
+      // Neutral passthrough: callers keep their existing behavior.
+      return "";
+  }
+}
+
+/** Map an Anthropic `web_search_tool_result_error` code to a category. */
+function categoryFromErrorCode(
+  errorCode: string,
+): WebSearchFailureCategory | undefined {
+  switch (errorCode) {
+    case "unavailable":
+    case "internal_error":
+    case "overloaded_error":
+      return "backend_unavailable";
+    case "too_many_requests":
+      return "rate_limited";
+    case "query_too_long":
+      return "query_too_long";
+    case "max_uses_exceeded":
+      return "max_uses_exceeded";
+    case "invalid_input":
+      // Recoverable, but not a backend failure — let callers handle it.
+      return "unknown";
+    default:
+      return undefined;
+  }
+}
+
+/** Map an HTTP status code to a category. */
+function categoryFromStatusCode(
+  statusCode: number,
+): WebSearchFailureCategory | undefined {
+  if (statusCode === 429) return "rate_limited";
+  if (statusCode === 401 || statusCode === 403) return "config";
+  if (statusCode >= 500) return "backend_unavailable";
+  return undefined;
+}
+
+/**
+ * Classify a thrown error / rejected value. This module is web_search-only, so
+ * network-layer failures (fetch failed, connection reset/refused, DNS, and
+ * timeouts without an explicit user-abort reason) are treated as backend
+ * failures.
+ */
+function categoryFromError(error: unknown): WebSearchFailureCategory | undefined {
+  if (error == null) return undefined;
+
+  // A user-initiated abort (Stop/Esc, preemption, dispose) is not a failure.
+  // The tagged `AbortReason` may surface directly (`AbortSignal.throwIfAborted`
+  // throws `signal.reason` verbatim), via `error.reason`, or — when a provider
+  // wrapper erases the `AbortError` name — on `ProviderError.abortReason`. Check
+  // all three FIRST, before the transport-retryability and abort/timeout
+  // substring heuristics, so a tagged cancellation that ALSO carries a
+  // transport-shaped `cause` (e.g. ECONNRESET) short-circuits to "not a
+  // failure" instead of being mislabeled a backend outage. A bare
+  // AbortError/timeout with no tagged reason still falls through below.
+  if (
+    isAbortReason(error) ||
+    isAbortReason((error as { reason?: unknown }).reason) ||
+    isAbortReason((error as { abortReason?: unknown }).abortReason)
+  ) {
+    return undefined;
+  }
+
+  // Retryable transport failures (ECONNRESET/ECONNREFUSED/ETIMEDOUT, socket
+  // hang-ups, including one level of `cause` chain) are backend failures.
+  if (isRetryableNetworkError(error)) return "backend_unavailable";
+
+  const name = typeof (error as { name?: unknown }).name === "string"
+    ? (error as { name: string }).name
+    : "";
+  const haystack = `${name} ${(error as { message?: unknown }).message ?? ""}`
+    .toLowerCase();
+
+  // web_search-only: treat aborts/timeouts/DNS/fetch failures (the cases
+  // `isRetryableNetworkError` doesn't cover) as backend failures.
+  if (
+    name === "AbortError" ||
+    haystack.includes("abort") ||
+    haystack.includes("timeout") ||
+    haystack.includes("timed out") ||
+    haystack.includes("fetch failed") ||
+    haystack.includes("failed to fetch") ||
+    haystack.includes("enotfound")
+  ) {
+    return "backend_unavailable";
+  }
+  return undefined;
+}
+
+/** Build the internal-only raw detail string (never embedded in userMessage). */
+function buildRawDetail(input: WebSearchFailureInput): string {
+  const parts: string[] = [];
+  if (input.errorCode) parts.push(`errorCode=${input.errorCode}`);
+  if (typeof input.statusCode === "number") {
+    parts.push(`statusCode=${input.statusCode}`);
+  }
+  if (input.error != null) {
+    const err = input.error as { message?: unknown };
+    const msg =
+      typeof err.message === "string" ? err.message : String(input.error);
+    if (msg) parts.push(msg);
+  }
+  return truncateForLog(parts.join(" "), 500);
+}
+
+/**
+ * Classify a web_search failure into a stable category, a user-facing message,
+ * and an internal-only raw detail. Never treats an empty-but-successful result
+ * as a failure.
+ */
+export function classifyWebSearchFailure(
+  input: WebSearchFailureInput,
+): WebSearchFailureClassification {
+  const rawDetail = buildRawDetail(input);
+
+  // Success-passthrough: nothing went wrong, there were just no results.
+  if (!input.isError && input.error == null) {
+    return {
+      category: "no_results",
+      isBackendFailure: false,
+      userMessage: userMessageFor("no_results"),
+      rawDetail,
+    };
+  }
+
+  // Resolution order: Anthropic `errorCode` → explicit HTTP `statusCode` →
+  // error-body/network heuristics. An explicit status code is authoritative
+  // over substring-sniffing the provider's response body (which can contain
+  // misleading keywords like "timeout"/"abort"). Tagged user-aborts carry no
+  // status code, so they still flow through `categoryFromError` and
+  // short-circuit to a non-failure.
+  const category =
+    (input.errorCode != null
+      ? categoryFromErrorCode(input.errorCode)
+      : undefined) ??
+    (typeof input.statusCode === "number"
+      ? categoryFromStatusCode(input.statusCode)
+      : undefined) ??
+    categoryFromError(input.error) ??
+    "unknown";
+
+  return {
+    category,
+    isBackendFailure: isBackendFailureCategory(category),
+    userMessage: userMessageFor(category),
+    rawDetail,
+  };
+}
+
+export interface WebSearchBackendFailureMeta {
+  provider: string;
+  requestId?: string;
+  errorCategory: WebSearchFailureCategory;
+  rawDetail: string;
+  fallbackShown: boolean;
+  queryLength?: number;
+}
+
+/**
+ * Emit a structured warning for a web_search backend failure (ATL-727).
+ *
+ * Do NOT log raw query text — only `queryLength`. `rawDetail` is internal-only
+ * provider/HTTP context and must never be surfaced to users.
+ */
+export function logWebSearchBackendFailure(
+  log: Logger,
+  meta: WebSearchBackendFailureMeta,
+): void {
+  log.warn(
+    {
+      event: "web_search_backend_failure",
+      tool: "web_search",
+      provider: meta.provider,
+      requestId: meta.requestId,
+      errorCategory: meta.errorCategory,
+      rawDetail: meta.rawDetail,
+      fallbackShown: meta.fallbackShown,
+      queryLength: meta.queryLength,
+    },
+    "web_search backend failure",
+  );
+}

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

@@ -6,6 +6,7 @@ import type {
 import { RiskLevel } from "../../permissions/types.js";
 import { getProviderKeyAsync } from "../../security/secure-keys.js";
 import { wrapUntrustedContent } from "../../security/untrusted-content.js";
+import { isAbortReason } from "../../util/abort-reasons.js";
 import { faviconUrlForDomain } from "../../util/favicon.js";
 import { getLogger } from "../../util/logger.js";
 import {
@@ -22,6 +23,11 @@ import type {
 } from "../types.js";
 import { extractDomain } from "./domain-normalize.js";
 import type { ManagedSearchProxyResult } from "./managed-search-proxy.js";
+import {
+  classifyWebSearchFailure,
+  logWebSearchBackendFailure,
+  WEB_SEARCH_BACKEND_FAILURE_MESSAGE,
+} from "./web-search-error.js";
 
 const log = getLogger("web-search");
 
@@ -381,6 +387,115 @@ function errorResult(
   };
 }
 
+/**
+ * Wrap an already-read provider response body so {@link backendFailureResult}
+ * forwards it into the classifier's internal-only `rawDetail` (telemetry). The
+ * classifier reads `error.message`; `buildRawDetail` truncates to ≤500 chars.
+ * Returns `undefined` for an empty body so we don't pad `rawDetail` with noise.
+ * The body must NEVER reach user-facing `content`/`errorMessage`.
+ */
+function rawBodyDetail(body: unknown): { message: string } | undefined {
+  if (body == null) return undefined;
+  const text =
+    typeof body === "string" ? body : safeStringifyBody(body);
+  const trimmed = text.trim();
+  return trimmed ? { message: trimmed } : undefined;
+}
+
+function safeStringifyBody(body: unknown): string {
+  try {
+    return JSON.stringify(body);
+  } catch {
+    return String(body);
+  }
+}
+
+/**
+ * Build a {@link ToolExecutionResult} for a genuine backend/transport failure
+ * (5xx, post-retry rate-limit, thrown network/timeout error). Routes the raw
+ * detail through {@link classifyWebSearchFailure}: when it is a backend failure
+ * we surface the friendly recoverable copy (the bare sentence so the model
+ * reads it as guidance — retry / continue-without-search / paste-details —
+ * rather than fabricating) in both the model-facing `content` and the client
+ * `errorMessage`, and log the raw detail via telemetry. Non-backend categories
+ * (e.g. an unexpected 4xx) fall back to {@link errorResult} with `fallback`.
+ *
+ * Raw provider JSON / status text must never reach `content` or `errorMessage`;
+ * only `rawDetail` (internal-only) captures it for the log.
+ */
+function backendFailureResult(
+  query: string,
+  provider: WebSearchProvider,
+  startedAt: number,
+  raw: { error?: unknown; statusCode?: number; errorCode?: string },
+  fallback: string,
+): ToolExecutionResult {
+  const classification = classifyWebSearchFailure({
+    isError: true,
+    error: raw.error,
+    statusCode: raw.statusCode,
+    errorCode: raw.errorCode,
+  });
+
+  if (!classification.isBackendFailure) {
+    return errorResult(query, provider, startedAt, fallback);
+  }
+
+  logWebSearchBackendFailure(log, {
+    provider,
+    errorCategory: classification.category,
+    rawDetail: classification.rawDetail,
+    fallbackShown: true,
+    queryLength: query.length,
+  });
+
+  return {
+    content: WEB_SEARCH_BACKEND_FAILURE_MESSAGE,
+    isError: true,
+    activityMetadata: {
+      webSearch: {
+        query,
+        provider,
+        resultCount: 0,
+        durationMs: Date.now() - startedAt,
+        results: [],
+        errorMessage: WEB_SEARCH_BACKEND_FAILURE_MESSAGE,
+      },
+    },
+  };
+}
+
+/**
+ * Route a thrown fetch error (network/timeout) through {@link backendFailureResult}
+ * as a `backend_unavailable` candidate, falling back to a `Web search failed: …`
+ * error for non-backend throws (e.g. a JSON parse error).
+ *
+ * If the caller aborted the request (`signal.aborted` — the user hit Stop/Esc,
+ * or an external caller cancelled), the thrown error is re-thrown so the
+ * executor's existing cancellation handling takes over. A user-cancel must NOT
+ * surface the friendly backend copy or emit `web_search_backend_failure`
+ * telemetry. Internal fetch timeouts (where the caller's signal is not aborted)
+ * still route to the friendly backend result.
+ */
+function networkFailureResult(
+  query: string,
+  provider: WebSearchProvider,
+  startedAt: number,
+  err: unknown,
+  signal?: AbortSignal,
+): ToolExecutionResult {
+  if (signal?.aborted || isAbortReason((err as { reason?: unknown })?.reason)) {
+    throw err;
+  }
+  return backendFailureResult(
+    query,
+    provider,
+    startedAt,
+    { error: err },
+    `Web search failed: ${err instanceof Error ? err.message : String(err)}`,
+  );
+}
+
 async function executeBraveSearch(
   query: string,
   count: number,
@@ -396,21 +511,26 @@ async function executeBraveSearch(
   const startedAt = Date.now();
 
   for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
-    const response = await fetch(url, {
-      headers: {
-        Accept: "application/json",
-        "Accept-Encoding": "gzip",
-        "X-Subscription-Token": apiKey,
-      },
-      signal,
-    });
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        headers: {
+          Accept: "application/json",
+          "Accept-Encoding": "gzip",
+          "X-Subscription-Token": apiKey,
+        },
+        signal,
+      });
+    } catch (err) {
+      return networkFailureResult(query, "brave", startedAt, err, signal);
+    }
 
     if (response.ok) {
       const data = (await response.json()) as BraveSearchResponse;
       return successfulBraveResult(data, query, startedAt);
     }
 
-    await response.text();
+    const bodyText = await response.text();
 
     if (response.status === 401 || response.status === 403) {
       return errorResult(
@@ -436,20 +556,22 @@ async function executeBraveSearch(
     }
 
     log.warn({ status: response.status }, "Brave Search API error");
-    return errorResult(
+    return backendFailureResult(
       query,
       "brave",
       startedAt,
+      { statusCode: response.status, error: rawBodyDetail(bodyText) },
       response.status === 429
         ? "Brave Search rate limit exceeded after retries. Try again shortly."
         : `Brave Search API returned status ${response.status}`,
     );
   }
 
-  return errorResult(
+  return backendFailureResult(
     query,
     "brave",
     startedAt,
+    { statusCode: 429 },
     "Brave Search rate limit exceeded after retries. Try again shortly.",
   );
 }
@@ -478,6 +600,23 @@ 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
+    ) {
+      return backendFailureResult(
+        query,
+        "brave",
+        startedAt,
+        {
+          statusCode: proxyResult.status,
+          error: rawBodyDetail(proxyResult.body),
+        },
+        managedSearchProxyErrorMessage(proxyResult),
+      );
+    }
     return errorResult(
       query,
       "brave",
@@ -503,12 +642,18 @@ async function executeManagedBraveSearch(
     );
   }
 
-  if (proxyResult.status === 429) {
-    return errorResult(
+  if (proxyResult.status === 429 || proxyResult.status >= 500) {
+    return backendFailureResult(
       query,
       "brave",
       startedAt,
-      "Managed Brave Search rate limit exceeded. Try again shortly.",
+      {
+        statusCode: proxyResult.status,
+        error: rawBodyDetail(proxyResult.body),
+      },
+      proxyResult.status === 429
+        ? "Managed Brave Search rate limit exceeded. Try again shortly."
+        : `Managed Brave Search provider returned status ${proxyResult.status}`,
     );
   }
 
@@ -545,18 +690,23 @@ async function executePerplexitySearch(
 ): Promise<ToolExecutionResult> {
   const startedAt = Date.now();
   for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
-    const response = await fetch(PERPLEXITY_API_URL, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${apiKey}`,
-      },
-      body: JSON.stringify({
-        model: "sonar",
-        messages: [{ role: "user", content: query }],
-      }),
-      signal,
-    });
+    let response: Response;
+    try {
+      response = await fetch(PERPLEXITY_API_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          model: "sonar",
+          messages: [{ role: "user", content: query }],
+        }),
+        signal,
+      });
+    } catch (err) {
+      return networkFailureResult(query, "perplexity", startedAt, err, signal);
+    }
 
     if (response.ok) {
       const data = (await response.json()) as PerplexityResponse;
@@ -574,7 +724,7 @@ async function executePerplexitySearch(
       };
     }
 
-    await response.text();
+    const bodyText = await response.text();
 
     if (response.status === 401 || response.status === 403) {
       return errorResult(
@@ -600,20 +750,22 @@ async function executePerplexitySearch(
     }
 
     log.warn({ status: response.status }, "Perplexity API error");
-    return errorResult(
+    return backendFailureResult(
       query,
       "perplexity",
       startedAt,
+      { statusCode: response.status, error: rawBodyDetail(bodyText) },
       response.status === 429
         ? "Perplexity rate limit exceeded after retries. Try again shortly."
         : `Perplexity API returned status ${response.status}`,
     );
   }
 
-  return errorResult(
+  return backendFailureResult(
     query,
     "perplexity",
     startedAt,
+    { statusCode: 429 },
     "Perplexity rate limit exceeded after retries. Try again shortly.",
   );
 }
@@ -638,16 +790,21 @@ async function executeTavilySearch(
   const startedAt = Date.now();
 
   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,
-    });
+    let response: Response;
+    try {
+      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,
+      });
+    } catch (err) {
+      return networkFailureResult(query, "tavily", startedAt, err, signal);
+    }
 
     if (response.ok) {
       const data = (await response.json()) as TavilySearchResponse;
@@ -665,7 +822,7 @@ async function executeTavilySearch(
       };
     }
 
-    await response.text();
+    const bodyText = await response.text();
 
     if (response.status === 401 || response.status === 403) {
       return errorResult(
@@ -691,20 +848,22 @@ async function executeTavilySearch(
     }
 
     log.warn({ status: response.status }, "Tavily Search API error");
-    return errorResult(
+    return backendFailureResult(
       query,
       "tavily",
       startedAt,
+      { statusCode: response.status, error: rawBodyDetail(bodyText) },
       response.status === 429
         ? "Tavily Search rate limit exceeded after retries. Try again shortly."
         : `Tavily Search API returned status ${response.status}`,
     );
   }
 
-  return errorResult(
+  return backendFailureResult(
     query,
     "tavily",
     startedAt,
+    { statusCode: 429 },
     "Tavily Search rate limit exceeded after retries. Try again shortly.",
   );
 }
@@ -844,13 +1003,13 @@ export const webSearchTool = {
           signal: context.signal,
         });
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
         log.error({ err }, "Managed web search failed");
-        return errorResult(
+        return networkFailureResult(
           query,
           "brave",
           startedAt,
-          `Managed web search failed: ${msg}`,
+          err,
+          context.signal,
         );
       }
     }
@@ -897,13 +1056,13 @@ export const webSearchTool = {
         signal: context.signal,
       });
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
       log.error({ err }, "Web search failed");
-      return errorResult(
+      return networkFailureResult(
         query,
         provider,
         startedAt,
-        `Web search failed: ${msg}`,
+        err,
+        context.signal,
       );
     }
   },

package/src/tools/schedule/create.ts

@@ -144,6 +144,7 @@ export async function executeScheduleCreate(
         maxRetries,
         retryBackoffMs,
         timeoutMs,
+        createdFromConversationId: context.conversationId,
       });
 
       const fireDate = formatLocalDate(job.nextRunAt);
@@ -225,6 +226,7 @@ export async function executeScheduleCreate(
       maxRetries,
       retryBackoffMs,
       timeoutMs,
+      createdFromConversationId: context.conversationId,
     });
 
     const scheduleDescription =