@vellumai/assistant 0.8.7 → 0.8.8

package/src/telemetry/usage-telemetry-reporter.test.ts

@@ -94,7 +94,15 @@ mock.module("../version.js", () => ({
 let mockCollectUsageData = true;
 
 mock.module("../config/loader.js", () => ({
-  getConfig: () => ({ collectUsageData: mockCollectUsageData }),
+  getConfig: () => ({
+    ui: {},
+    model: "test",
+    provider: "test",
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0 },
+    secretDetection: { enabled: false },
+    collectUsageData: mockCollectUsageData,
+  }),
 }));
 
 const mockQueryUnreportedLifecycleEvents = mock(
@@ -130,13 +138,24 @@ mock.module("../memory/onboarding-events-store.js", () => ({
   queryUnreportedOnboardingEvents: mockQueryUnreportedOnboardingEvents,
 }));
 
+// The auth-fallback store is intentionally NOT mocked — it has its own
+// DB-backed tests, and Bun's `mock.module` is process-global, so mocking it
+// here would leak into those tests when files share an invocation. We seed the
+// real DB instead so every auth-fallback test stays order-independent.
+
 // ---------------------------------------------------------------------------
 // Production import (after mocks)
 // ---------------------------------------------------------------------------
 
+import { recordAuthFallbackCounts } from "../memory/auth-fallback-events-store.js";
+import { getDb } from "../memory/db-connection.js";
+import { initializeDb } from "../memory/db-init.js";
+import { authFallbackEvents } from "../memory/schema.js";
 import type { UsageEvent } from "../usage/types.js";
 import { UsageTelemetryReporter } from "./usage-telemetry-reporter.js";
 
+initializeDb();
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -201,6 +220,7 @@ beforeEach(() => {
   mockQueryUnreportedLifecycleEvents.mockReturnValue([]);
   mockQueryUnreportedOnboardingEvents.mockReset();
   mockQueryUnreportedOnboardingEvents.mockReturnValue([]);
+  getDb().delete(authFallbackEvents).run();
   mockPlatformClient = null;
   mockGetPlatformBaseUrl.mockReset();
   mockGetDeviceId.mockReset();
@@ -909,9 +929,9 @@ describe("UsageTelemetryReporter", () => {
     // No HTTP call should have been made
     expect(mockFetch).not.toHaveBeenCalled();
 
-    // All 4 timestamp watermarks should have been advanced (IDs left untouched
+    // All 5 timestamp watermarks should have been advanced (IDs left untouched
     // so the compound-cursor branch stays active)
-    expect(mockSetMemoryCheckpoint).toHaveBeenCalledTimes(4);
+    expect(mockSetMemoryCheckpoint).toHaveBeenCalledTimes(5);
 
     const calls = mockSetMemoryCheckpoint.mock.calls;
     const keys = calls.map((c) => c[0]);
@@ -919,6 +939,7 @@ describe("UsageTelemetryReporter", () => {
     expect(keys).toContain("telemetry:turns:last_reported_at");
     expect(keys).toContain("telemetry:lifecycle:last_reported_at");
     expect(keys).toContain("telemetry:onboarding:last_reported_at");
+    expect(keys).toContain("telemetry:auth_fallback:last_reported_at");
   });
 
   test("events sent normally after re-enabling collectUsageData", async () => {
@@ -1075,4 +1096,92 @@ describe("UsageTelemetryReporter", () => {
     // Envelope still reflects the running binary, not either event.
     expect(body.assistant_version).toBe("1.2.3-test");
   });
+
+  // -------------------------------------------------------------------------
+  // Auth-fallback events
+  // -------------------------------------------------------------------------
+
+  test("auth_fallback events are included in the events array with type discriminator", async () => {
+    mockQueryUnreportedUsageEvents.mockReturnValue([]);
+    recordAuthFallbackCounts(1700000740000, 1700000800000, [
+      {
+        guard: "edge",
+        path: "/v1/messages",
+        failureKind: "missing_authorization",
+        count: 42,
+      },
+    ]);
+    mockFetch.mockImplementation(() =>
+      Promise.resolve(new Response('{"accepted":1}', { status: 200 })),
+    );
+
+    const reporter = new UsageTelemetryReporter();
+    await reporter.flush();
+
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const body = JSON.parse(
+      (mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string,
+    );
+    expect(body.events.length).toBe(1);
+    expect(body.events[0]).toMatchObject({
+      type: "auth_fallback",
+      guard: "edge",
+      path: "/v1/messages",
+      failure_kind: "missing_authorization",
+      count: 42,
+      window_start: 1700000740000,
+      window_end: 1700000800000,
+      assistant_version: "1.2.3-test",
+    });
+    // recorded_at is the row's createdAt (stamped at record time).
+    expect(typeof body.events[0].recorded_at).toBe("number");
+    expect(typeof body.events[0].daemon_event_id).toBe("string");
+  });
+
+  test("auth_fallback watermark advances to the last reported row on success", async () => {
+    mockQueryUnreportedUsageEvents.mockReturnValue([]);
+    recordAuthFallbackCounts(1700000000000, 1700000001000, [
+      {
+        guard: "edge-scoped",
+        path: "/v1/a",
+        failureKind: "insufficient_scope",
+        count: 1,
+      },
+      {
+        guard: "edge-guardian",
+        path: "/v1/b",
+        failureKind: "guardian_mismatch",
+        count: 3,
+      },
+    ]);
+    mockFetch.mockImplementation(() =>
+      Promise.resolve(new Response('{"accepted":2}', { status: 200 })),
+    );
+
+    // The last row by the reporter's (createdAt, id) cursor order is the one
+    // whose watermark should be persisted after a successful upload.
+    const rows = getDb()
+      .select()
+      .from(authFallbackEvents)
+      .orderBy(authFallbackEvents.createdAt, authFallbackEvents.id)
+      .all();
+    const lastRow = rows[rows.length - 1];
+
+    const reporter = new UsageTelemetryReporter();
+    await reporter.flush();
+
+    const watermarkCalls = mockSetMemoryCheckpoint.mock.calls.filter(
+      (c) => c[0] === "telemetry:auth_fallback:last_reported_at",
+    );
+    expect(watermarkCalls.length).toBeGreaterThanOrEqual(1);
+    expect(watermarkCalls[watermarkCalls.length - 1][1]).toBe(
+      String(lastRow.createdAt),
+    );
+
+    const idCalls = mockSetMemoryCheckpoint.mock.calls.filter(
+      (c) => c[0] === "telemetry:auth_fallback:last_reported_id",
+    );
+    expect(idCalls.length).toBeGreaterThanOrEqual(1);
+    expect(idCalls[idCalls.length - 1][1]).toBe(lastRow.id);
+  });
 });

package/src/telemetry/usage-telemetry-reporter.ts

@@ -15,6 +15,7 @@ import {
   getPlatformUserId,
 } from "../config/env.js";
 import { getConfig } from "../config/loader.js";
+import { queryUnreportedAuthFallbackEvents } from "../memory/auth-fallback-events-store.js";
 import {
   getMemoryCheckpoint,
   setMemoryCheckpoint,
@@ -47,6 +48,10 @@ const CHECKPOINT_KEY_ONBOARDING_WATERMARK =
   "telemetry:onboarding:last_reported_at";
 const CHECKPOINT_KEY_ONBOARDING_WATERMARK_ID =
   "telemetry:onboarding:last_reported_id";
+const CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK =
+  "telemetry:auth_fallback:last_reported_at";
+const CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK_ID =
+  "telemetry:auth_fallback:last_reported_id";
 const REPORT_INTERVAL_MS = 5 * 60 * 1000;
 const INITIAL_FLUSH_DELAY_MS = 30_000; // Delay first flush to let CES handshake complete
 const BATCH_SIZE = 500;
@@ -139,6 +144,7 @@ export class UsageTelemetryReporter {
         setMemoryCheckpoint(CHECKPOINT_KEY_TURN_WATERMARK, now);
         setMemoryCheckpoint(CHECKPOINT_KEY_LIFECYCLE_WATERMARK, now);
         setMemoryCheckpoint(CHECKPOINT_KEY_ONBOARDING_WATERMARK, now);
+        setMemoryCheckpoint(CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK, now);
         return;
       }
 
@@ -171,6 +177,14 @@ export class UsageTelemetryReporter {
         getMemoryCheckpoint(CHECKPOINT_KEY_ONBOARDING_WATERMARK_ID) ??
         undefined;
 
+      // Read auth-fallback watermark (compound cursor: createdAt + id)
+      const authFallbackWatermark = Number(
+        getMemoryCheckpoint(CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK) ?? "0",
+      );
+      const authFallbackWatermarkId =
+        getMemoryCheckpoint(CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK_ID) ??
+        undefined;
+
       // Query unreported events
       const events = queryUnreportedUsageEvents(
         watermark,
@@ -192,12 +206,18 @@ export class UsageTelemetryReporter {
         onboardingWatermarkId,
         BATCH_SIZE,
       );
+      const authFallbackEvents = queryUnreportedAuthFallbackEvents(
+        authFallbackWatermark,
+        authFallbackWatermarkId,
+        BATCH_SIZE,
+      );
 
       if (
         events.length === 0 &&
         turnEvents.length === 0 &&
         lifecycleEvents.length === 0 &&
-        onboardingEvents.length === 0
+        onboardingEvents.length === 0 &&
+        authFallbackEvents.length === 0
       )
         return;
 
@@ -211,6 +231,7 @@ export class UsageTelemetryReporter {
           turnCount: turnEvents.length,
           lifecycleCount: lifecycleEvents.length,
           onboardingCount: onboardingEvents.length,
+          authFallbackCount: authFallbackEvents.length,
         },
         "Telemetry flush: resolved auth context",
       );
@@ -337,6 +358,25 @@ export class UsageTelemetryReporter {
             assistant_version: APP_VERSION,
           }),
         ),
+        ...authFallbackEvents.map(
+          (e): TelemetryEvent => ({
+            type: "auth_fallback",
+            daemon_event_id: e.id,
+            recorded_at: e.createdAt,
+            guard: e.guard,
+            path: e.path,
+            failure_kind: e.failureKind,
+            count: e.count,
+            window_start: e.windowStart,
+            window_end: e.windowEnd,
+            // Aggregated counts forwarded by the gateway carry no record-time
+            // binary version; stamp the running binary's `APP_VERSION` so the
+            // wire value is concrete rather than an explicit null that would
+            // override the envelope under the platform's per-event-wins
+            // contract.
+            assistant_version: APP_VERSION,
+          }),
+        ),
       ];
 
       const organizationId = getPlatformOrganizationId() || undefined;
@@ -422,12 +462,27 @@ export class UsageTelemetryReporter {
         );
       }
 
+      // Advance auth-fallback watermark (compound cursor)
+      if (authFallbackEvents.length > 0) {
+        const lastAuthFallback =
+          authFallbackEvents[authFallbackEvents.length - 1];
+        setMemoryCheckpoint(
+          CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK,
+          String(lastAuthFallback.createdAt),
+        );
+        setMemoryCheckpoint(
+          CHECKPOINT_KEY_AUTH_FALLBACK_WATERMARK_ID,
+          lastAuthFallback.id,
+        );
+      }
+
       // If we got a full batch of any type, there may be more — recurse
       if (
         events.length === BATCH_SIZE ||
         turnEvents.length === BATCH_SIZE ||
         lifecycleEvents.length === BATCH_SIZE ||
-        onboardingEvents.length === BATCH_SIZE
+        onboardingEvents.length === BATCH_SIZE ||
+        authFallbackEvents.length === BATCH_SIZE
       ) {
         await this._doFlush(batchCount + 1);
       }

package/src/tools/executor.ts

@@ -1,18 +1,10 @@
 import { readFileSync } from "node:fs";
 
-import { parseChannelId } from "../channels/types.js";
 import { getConfig } from "../config/loader.js";
 import { bridgeCesApproval } from "../credential-execution/approval-bridge.js";
 import { isCesShellLockdownEnabled } from "../credential-execution/feature-gates.js";
 import { PermissionPrompter } from "../permissions/prompter.js";
 import { RiskLevel } from "../permissions/types.js";
-import { runPipeline } from "../plugins/pipeline.js";
-import { getMiddlewaresFor } from "../plugins/registry.js";
-import type {
-  ToolExecuteArgs,
-  ToolExecuteResult,
-  TurnContext,
-} from "../plugins/types.js";
 import { isUntrustedTrustClass } from "../runtime/actor-trust-resolver.js";
 import { redactSensitiveFields } from "../security/redaction.js";
 import { TokenExpiredError } from "../security/token-manager.js";
@@ -52,54 +44,10 @@ export class ToolExecutor {
     name: string,
     input: Record<string, unknown>,
     context: ToolContext,
-    /**
-     * Optional per-turn context threaded in by the agent loop. Production
-     * sites propagate the orchestrator-built `TurnContext` (real
-     * `conversationId`, trust cascade, attached `contextWindowManager`) so
-     * middleware registered on the `toolExecute` pipeline sees the same
-     * context every other pipeline slot uses. When omitted (CLI/test
-     * invocations that call `ToolExecutor.execute` directly), the executor
-     * synthesizes a fallback context from the {@link ToolContext}.
-     */
-    turnContext?: TurnContext,
   ): Promise<ToolExecutionResult> {
-    // Prefer the orchestrator-supplied `turnContext` so the pipeline sees
-    // the real conversation identity, per-turn trust, and context-window
-    // manager. When absent (CLI / test invocations that bypass the agent
-    // loop), synthesize a minimal context from the `ToolContext`.
-    const turnCtx: TurnContext = turnContext ?? {
-      requestId: context.requestId ?? "",
-      conversationId: context.conversationId,
-      turnIndex: 0,
-      trust: {
-        sourceChannel: parseChannelId(context.executionChannel) ?? "vellum",
-        trustClass: context.trustClass,
-      },
-    };
-
-    const middlewares = getMiddlewaresFor("toolExecute");
     const { name: executionName, input: executionInput } =
       resolveToolInvocationAlias(name, input, context.allowedToolNames);
-    const pipelineArgs: ToolExecuteArgs = {
-      name: executionName,
-      input: executionInput,
-      context,
-    };
-
-    // No pipeline-level timeout: `executeInternal` already wraps the real
-    // tool invocation in `executeWithTimeout`, which is the sole enforcer
-    // of the per-tool budget. The pipeline itself runs untimed so that
-    // upstream phases (permission checks, approval waits, middleware) are
-    // not racing the tool budget — only the actual tool call is. Runaway
-    // middleware is a plugin-health concern handled by per-plugin timeouts,
-    // not here.
-    return runPipeline<ToolExecuteArgs, ToolExecuteResult>(
-      "toolExecute",
-      middlewares,
-      (args) => this.executeInternal(args.name, args.input, args.context),
-      pipelineArgs,
-      turnCtx,
-    );
+    return this.executeInternal(executionName, executionInput, context);
   }
 
   private async executeInternal(

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

@@ -1,5 +1,7 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
+import { WEB_SEARCH_BACKEND_FAILURE_MESSAGE } from "../web-search-error.js";
+
 // Mutable mock state - set per test
 let mockWebSearchProvider: string | undefined = "perplexity";
 let mockBraveSecureKey: string | undefined;
@@ -32,7 +34,9 @@ mock.module("../../../security/secure-keys.js", () => ({
   },
 }));
 
+const realLogger = await import("../../../util/logger.js");
 mock.module("../../../util/logger.js", () => ({
+  ...realLogger,
   getLogger: () =>
     new Proxy({} as Record<string, unknown>, {
       get: () => () => {},
@@ -169,7 +173,9 @@ describe("web_search activity metadata", () => {
     expect(meta.provider).toBe("perplexity");
     expect(meta.resultCount).toBe(0);
     expect(meta.results).toEqual([]);
-    expect(meta.errorMessage).toContain("rate limit exceeded");
+    // Post-retry rate limits now surface the centralized friendly recoverable
+    // copy (ATL-727) rather than provider-specific rate-limit wording.
+    expect(meta.errorMessage).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
   });
 
   // ---- Tavily -------------------------------------------------------------

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

@@ -1,5 +1,7 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
+import { WEB_SEARCH_BACKEND_FAILURE_MESSAGE } from "../web-search-error.js";
+
 // Mutable mock state - set per test
 let mockWebSearchProvider: string | undefined = "perplexity";
 let mockWebSearchMode: string | undefined = "your-own";
@@ -42,7 +44,9 @@ mock.module("../../../security/secure-keys.js", () => ({
   },
 }));
 
+const realLogger = await import("../../../util/logger.js");
 mock.module("../../../util/logger.js", () => ({
+  ...realLogger,
   getLogger: () =>
     new Proxy({} as Record<string, unknown>, {
       get: () => () => {},
@@ -201,7 +205,8 @@ describe("web_search tool", () => {
 
     const result = await execute({ query: "test" });
     expect(result.isError).toBe(true);
-    expect(result.content).toContain("rate limit exceeded");
+    // Post-retry rate limits surface the friendly recoverable copy (ATL-727).
+    expect(result.content).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
     // 1 initial + 3 retries = 4 calls
     expect(callCount).toBe(4);
   });
@@ -214,7 +219,9 @@ describe("web_search tool", () => {
 
     const result = await execute({ query: "test" });
     expect(result.isError).toBe(true);
-    expect(result.content).toContain("status 500");
+    // 5xx is a backend failure -> friendly recoverable copy, no raw status.
+    expect(result.content).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+    expect(result.content).not.toContain("500");
   });
 
   // ---- Brave provider -----------------------------------------------------
@@ -673,7 +680,8 @@ describe("web_search tool", () => {
 
     const result = await execute({ query: "test" });
     expect(result.isError).toBe(true);
-    expect(result.content).toContain("rate limit exceeded");
+    // Post-retry rate limits surface the friendly recoverable copy (ATL-727).
+    expect(result.content).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
     expect(callCount).toBe(4);
   });
 

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

@@ -0,0 +1,248 @@
+import { describe, expect, test } from "bun:test";
+
+import { createAbortReason } from "../../util/abort-reasons.js";
+import {
+  classifyWebSearchFailure,
+  logWebSearchBackendFailure,
+  WEB_SEARCH_BACKEND_FAILURE_MESSAGE,
+} from "./web-search-error.js";
+
+describe("classifyWebSearchFailure", () => {
+  test("Anthropic 'unavailable' code is a backend failure with friendly copy", () => {
+    const result = classifyWebSearchFailure({
+      isError: true,
+      errorCode: "unavailable",
+    });
+    expect(result.category).toBe("backend_unavailable");
+    expect(result.isBackendFailure).toBe(true);
+    expect(result.userMessage).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+    expect(result.rawDetail).toContain("unavailable");
+  });
+
+  test.each(["internal_error", "overloaded_error"])(
+    "Anthropic '%s' code is a backend failure",
+    (errorCode) => {
+      const result = classifyWebSearchFailure({ isError: true, errorCode });
+      expect(result.category).toBe("backend_unavailable");
+      expect(result.isBackendFailure).toBe(true);
+    },
+  );
+
+  test("HTTP 503 is a backend failure", () => {
+    const result = classifyWebSearchFailure({ isError: true, statusCode: 503 });
+    expect(result.category).toBe("backend_unavailable");
+    expect(result.userMessage).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+  });
+
+  test("thrown TypeError('fetch failed') is a backend failure", () => {
+    const result = classifyWebSearchFailure({
+      isError: true,
+      error: new TypeError("fetch failed"),
+    });
+    expect(result.category).toBe("backend_unavailable");
+    expect(result.isBackendFailure).toBe(true);
+  });
+
+  test("AbortError-shaped timeout is a backend failure", () => {
+    const err = new Error("The operation was aborted due to timeout");
+    err.name = "AbortError";
+    const result = classifyWebSearchFailure({ isError: true, error: err });
+    expect(result.category).toBe("backend_unavailable");
+    expect(result.isBackendFailure).toBe(true);
+  });
+
+  test("user-initiated abort is not a backend failure", () => {
+    const err = new Error("The operation was aborted");
+    err.name = "AbortError";
+    Object.assign(err, {
+      reason: createAbortReason("user_cancel", "cancelGeneration"),
+    });
+    const result = classifyWebSearchFailure({ isError: true, error: err });
+    expect(result.isBackendFailure).toBe(false);
+    expect(result.userMessage).not.toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+  });
+
+  test("wrapped ProviderError carrying abortReason is not a backend failure", () => {
+    // A provider wrapper erases the AbortError name and re-words the message,
+    // but carries the tagged reason on `abortReason` (ProviderError shape).
+    const err = Object.assign(new Error("Request was aborted"), {
+      name: "ProviderError",
+      abortReason: createAbortReason("user_cancel", "cancelGeneration"),
+    });
+    const result = classifyWebSearchFailure({ isError: true, error: err });
+    expect(result.category).not.toBe("backend_unavailable");
+    expect(result.isBackendFailure).toBe(false);
+    expect(result.userMessage).not.toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+  });
+
+  test("tagged abort with a transport-shaped cause is not a backend failure", () => {
+    // A user cancellation wrapped as a ProviderError that ALSO carries a
+    // transport-shaped `cause` (ECONNRESET). The tagged abort guard must win
+    // over transport-retryability so this is not mislabeled a backend outage.
+    const err = Object.assign(new Error("Request was aborted"), {
+      name: "ProviderError",
+      cause: { code: "ECONNRESET" },
+      abortReason: createAbortReason("user_cancel", "cancelGeneration"),
+    });
+    const result = classifyWebSearchFailure({ isError: true, error: err });
+    expect(result.category).not.toBe("backend_unavailable");
+    expect(result.isBackendFailure).toBe(false);
+    expect(result.userMessage).not.toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+  });
+
+  test("explicit statusCode wins over a misleading error-body keyword", () => {
+    // The provider response body contains "aborted" (a keyword the error-body
+    // heuristic would sniff as a non-failure), but the authoritative HTTP 503
+    // must classify this as a backend failure.
+    const result = classifyWebSearchFailure({
+      isError: true,
+      statusCode: 503,
+      error: new Error("the upstream request was aborted unexpectedly"),
+    });
+    expect(result.category).toBe("backend_unavailable");
+    expect(result.isBackendFailure).toBe(true);
+    expect(result.userMessage).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+  });
+
+  test("ECONNRESET network error is a backend failure", () => {
+    const err = Object.assign(new Error("socket hang up"), {
+      code: "ECONNRESET",
+    });
+    const result = classifyWebSearchFailure({ isError: true, error: err });
+    expect(result.category).toBe("backend_unavailable");
+  });
+
+  test("Anthropic 'too_many_requests' code is rate-limited with backend copy", () => {
+    const result = classifyWebSearchFailure({
+      isError: true,
+      errorCode: "too_many_requests",
+    });
+    expect(result.category).toBe("rate_limited");
+    expect(result.isBackendFailure).toBe(true);
+    expect(result.userMessage).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+  });
+
+  test("HTTP 429 is rate-limited with backend copy", () => {
+    const result = classifyWebSearchFailure({ isError: true, statusCode: 429 });
+    expect(result.category).toBe("rate_limited");
+    expect(result.userMessage).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+  });
+
+  test("'query_too_long' has a distinct, non-backend message", () => {
+    const result = classifyWebSearchFailure({
+      isError: true,
+      errorCode: "query_too_long",
+    });
+    expect(result.category).toBe("query_too_long");
+    expect(result.isBackendFailure).toBe(false);
+    expect(result.userMessage).not.toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+    expect(result.userMessage.length).toBeGreaterThan(0);
+  });
+
+  test("'max_uses_exceeded' has a distinct, non-backend message", () => {
+    const result = classifyWebSearchFailure({
+      isError: true,
+      errorCode: "max_uses_exceeded",
+    });
+    expect(result.category).toBe("max_uses_exceeded");
+    expect(result.isBackendFailure).toBe(false);
+    expect(result.userMessage).not.toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+    expect(result.userMessage.length).toBeGreaterThan(0);
+  });
+
+  test("'invalid_input' is unknown and not a backend failure", () => {
+    const result = classifyWebSearchFailure({
+      isError: true,
+      errorCode: "invalid_input",
+    });
+    expect(result.category).toBe("unknown");
+    expect(result.isBackendFailure).toBe(false);
+  });
+
+  test("HTTP 401 is a config failure, not the backend copy", () => {
+    const result = classifyWebSearchFailure({ isError: true, statusCode: 401 });
+    expect(result.category).toBe("config");
+    expect(result.isBackendFailure).toBe(false);
+    expect(result.userMessage).not.toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+  });
+
+  test("HTTP 403 is a config failure", () => {
+    const result = classifyWebSearchFailure({ isError: true, statusCode: 403 });
+    expect(result.category).toBe("config");
+    expect(result.isBackendFailure).toBe(false);
+  });
+
+  test("successful-but-empty result is no_results, not a failure", () => {
+    const result = classifyWebSearchFailure({
+      isError: false,
+      hasResults: false,
+    });
+    expect(result.category).toBe("no_results");
+    expect(result.isBackendFailure).toBe(false);
+    expect(result.userMessage).not.toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+  });
+
+  test("rawDetail is truncated to 500 chars", () => {
+    const result = classifyWebSearchFailure({
+      isError: true,
+      error: new Error("x".repeat(1000)),
+    });
+    expect(result.rawDetail.length).toBeLessThanOrEqual(500 + 40);
+    expect(result.rawDetail).toContain("truncated");
+  });
+});
+
+describe("WEB_SEARCH_BACKEND_FAILURE_MESSAGE copy safety", () => {
+  test("offers retry / continue-without / paste", () => {
+    expect(WEB_SEARCH_BACKEND_FAILURE_MESSAGE).toContain("try again");
+    expect(WEB_SEARCH_BACKEND_FAILURE_MESSAGE).toContain("continue without");
+    expect(WEB_SEARCH_BACKEND_FAILURE_MESSAGE).toContain("paste");
+  });
+
+  test("contains no raw provider details, JSON, or exception names", () => {
+    for (const banned of [
+      "{",
+      "error_code",
+      "Anthropic",
+      "web_search_tool_result_error",
+      "TypeError",
+      "stack",
+    ]) {
+      expect(WEB_SEARCH_BACKEND_FAILURE_MESSAGE).not.toContain(banned);
+    }
+  });
+});
+
+describe("logWebSearchBackendFailure", () => {
+  test("captures the event and rawDetail without raw query text", () => {
+    const calls: unknown[][] = [];
+    const fakeLogger = {
+      warn: (...args: unknown[]) => {
+        calls.push(args);
+      },
+    } as unknown as Parameters<typeof logWebSearchBackendFailure>[0];
+
+    const secretQuery = "super secret user query text";
+    logWebSearchBackendFailure(fakeLogger, {
+      provider: "anthropic",
+      requestId: "req-1",
+      errorCategory: "backend_unavailable",
+      rawDetail: "errorCode=unavailable",
+      fallbackShown: true,
+      queryLength: secretQuery.length,
+    });
+
+    expect(calls).toHaveLength(1);
+    const [payload, msg] = calls[0] as [Record<string, unknown>, string];
+    expect(payload.event).toBe("web_search_backend_failure");
+    expect(payload.tool).toBe("web_search");
+    expect(payload.provider).toBe("anthropic");
+    expect(payload.rawDetail).toBe("errorCode=unavailable");
+    expect(payload.queryLength).toBe(secretQuery.length);
+    expect(msg).toBe("web_search backend failure");
+
+    // The raw query text must never appear anywhere in the logged payload.
+    const serialized = JSON.stringify(calls);
+    expect(serialized).not.toContain(secretQuery);
+  });
+});