@vellumai/assistant 0.8.7 → 0.8.8

package/src/__tests__/memory-retrieval-hook.test.ts

@@ -0,0 +1,297 @@
+/**
+ * Tests for the default `user-prompt-submit-temp` hook (memory retrieval).
+ *
+ * Covers the retrieval behavior, the side effects the hook owns (injected-block
+ * metadata, recall log, `memory_recalled` event), trust gating, error
+ * propagation, and abort-signal forwarding. Uses `mock.module` to stub the
+ * persistence helpers so the test doesn't touch the developer's real
+ * `~/.vellum` or database. The memory graph handle is a hand-rolled fake
+ * passed on the hook context — the hook only needs `prepareMemory`.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Stub the persistence helpers BEFORE importing the module under test so the
+// bindings resolve through the mocks.
+const updateMessageMetadataMock = mock((_id: string, _updates: unknown) => {});
+mock.module("../memory/conversation-crud.js", () => ({
+  updateMessageMetadata: updateMessageMetadataMock,
+}));
+
+const recordMemoryRecallLogMock = mock((_entry: unknown) => {});
+mock.module("../memory/memory-recall-log-store.js", () => ({
+  recordMemoryRecallLog: recordMemoryRecallLogMock,
+}));
+
+import type { AssistantConfig } from "../config/schema.js";
+import type { ServerMessage } from "../daemon/message-protocol.js";
+import type { ConversationGraphMemory } from "../memory/graph/conversation-graph-memory.js";
+import type { QdrantSparseVector } from "../memory/qdrant-client.js";
+import userPromptSubmitMemoryRetrieval, {
+  type MemoryRetrievalHookContext,
+} from "../plugins/defaults/memory-retrieval/hooks/user-prompt-submit-temp.js";
+import type { Message } from "../providers/types.js";
+
+/** Canonical metrics payload the graph retriever attaches to a real hit. */
+function makeMetrics() {
+  return {
+    embeddingProvider: "openai",
+    embeddingModel: "text-embedding-3-small",
+    semanticHits: 2,
+    mergedCount: 3,
+    selectedCount: 1,
+    tier1Count: 1,
+    tier2Count: 0,
+    hybridSearchLatencyMs: 5,
+    sparseVectorUsed: true,
+    topCandidates: [
+      {
+        nodeId: "node-1",
+        type: "fact",
+        score: 0.9,
+        semanticSimilarity: 0.8,
+        recencyBoost: 0.1,
+      },
+    ],
+    queryContext: "query-context",
+  };
+}
+
+/**
+ * Fake graph-memory whose `prepareMemory` returns a canonical result. The hook
+ * unpacks this return value onto `ctx.latestMessages` and records the selected
+ * PKB query pair back onto the handle via `recordPkbQueryVectors`, so tests
+ * can assert those outputs by comparing object identity.
+ */
+function makeFakeGraphMemory(overrides?: {
+  messages?: Message[];
+  injectedTokens?: number;
+  injectedBlockText?: string | null;
+  metrics?: ReturnType<typeof makeMetrics> | null;
+  queryVector?: number[];
+  sparseVector?: QdrantSparseVector;
+  userQueryVector?: number[];
+  userQuerySparseVector?: QdrantSparseVector;
+}): {
+  memory: ConversationGraphMemory;
+  prepareMemoryMock: ReturnType<typeof mock>;
+  recordPkbQueryVectorsMock: ReturnType<typeof mock>;
+} {
+  const returnValue = {
+    runMessages: overrides?.messages ?? [],
+    injectedTokens: overrides?.injectedTokens ?? 0,
+    latencyMs: 0,
+    mode: "none" as const,
+    injectedBlockText:
+      overrides?.injectedBlockText === undefined
+        ? null
+        : overrides.injectedBlockText,
+    metrics: overrides?.metrics ?? null,
+    queryVector: overrides?.queryVector,
+    sparseVector: overrides?.sparseVector,
+    userQueryVector: overrides?.userQueryVector,
+    userQuerySparseVector: overrides?.userQuerySparseVector,
+  };
+  const prepareMemoryMock = mock(async () => returnValue);
+  const recordPkbQueryVectorsMock = mock(() => {});
+  const memory = {
+    prepareMemory: prepareMemoryMock,
+    recordPkbQueryVectors: recordPkbQueryVectorsMock,
+  } as unknown as ConversationGraphMemory;
+  return { memory, prepareMemoryMock, recordPkbQueryVectorsMock };
+}
+
+function makeHookCtx(
+  overrides: Partial<MemoryRetrievalHookContext> = {},
+): MemoryRetrievalHookContext {
+  const { memory } = makeFakeGraphMemory();
+  return {
+    graphMemory: memory,
+    config: {} as AssistantConfig,
+    onEvent: () => {},
+    isTrustedActor: true,
+    conversationId: "conv-test",
+    userMessageId: "msg-test",
+    logger: {
+      warn: () => {},
+    } as unknown as MemoryRetrievalHookContext["logger"],
+    signal: new AbortController().signal,
+    latestMessages: [],
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  updateMessageMetadataMock.mockReset();
+  recordMemoryRecallLogMock.mockReset();
+});
+
+describe("user-prompt-submit-temp hook (memory retrieval)", () => {
+  test("adopts the injected run messages when the actor is trusted", async () => {
+    const injected: Message[] = [
+      { role: "user", content: [{ type: "text", text: "injected" }] },
+    ];
+    const { memory, prepareMemoryMock } = makeFakeGraphMemory({
+      messages: injected,
+    });
+    const ctx = makeHookCtx({ graphMemory: memory, isTrustedActor: true });
+
+    await userPromptSubmitMemoryRetrieval(ctx);
+
+    expect(prepareMemoryMock).toHaveBeenCalledTimes(1);
+    // The hook adopts the retriever's injected message array verbatim —
+    // consumers in the agent loop rely on that identity.
+    expect(ctx.latestMessages).toBe(injected);
+  });
+
+  test("selects the user-query dense/sparse pair when present, else the summary pair", async () => {
+    const userDense = [1, 1, 1];
+    const userSparse: QdrantSparseVector = { indices: [0], values: [1] };
+    const summaryDense = [2, 2, 2];
+    const summarySparse: QdrantSparseVector = { indices: [1], values: [2] };
+
+    const withUserQuery = makeFakeGraphMemory({
+      queryVector: summaryDense,
+      sparseVector: summarySparse,
+      userQueryVector: userDense,
+      userQuerySparseVector: userSparse,
+    });
+    const userCtx = makeHookCtx({ graphMemory: withUserQuery.memory });
+    await userPromptSubmitMemoryRetrieval(userCtx);
+    // User-query pair wins — never crossed with the summary signal — and is
+    // recorded back onto the graph handle for the PKB-reminder injector.
+    expect(withUserQuery.recordPkbQueryVectorsMock).toHaveBeenCalledWith(
+      userDense,
+      userSparse,
+    );
+
+    const summaryOnly = makeFakeGraphMemory({
+      queryVector: summaryDense,
+      sparseVector: summarySparse,
+    });
+    const summaryCtx = makeHookCtx({ graphMemory: summaryOnly.memory });
+    await userPromptSubmitMemoryRetrieval(summaryCtx);
+    expect(summaryOnly.recordPkbQueryVectorsMock).toHaveBeenCalledWith(
+      summaryDense,
+      summarySparse,
+    );
+  });
+
+  test("skips graph retrieval and side effects for untrusted actors", async () => {
+    const { memory, prepareMemoryMock, recordPkbQueryVectorsMock } =
+      makeFakeGraphMemory();
+    const seeded: Message[] = [
+      { role: "user", content: [{ type: "text", text: "seeded" }] },
+    ];
+    const ctx = makeHookCtx({
+      graphMemory: memory,
+      isTrustedActor: false,
+      latestMessages: seeded,
+    });
+
+    await userPromptSubmitMemoryRetrieval(ctx);
+
+    expect(prepareMemoryMock).not.toHaveBeenCalled();
+    // No graph retrieval ran: the working array stays the seeded input and no
+    // PKB query pair is recorded onto the graph handle.
+    expect(ctx.latestMessages).toBe(seeded);
+    expect(recordPkbQueryVectorsMock).not.toHaveBeenCalled();
+    expect(recordMemoryRecallLogMock).not.toHaveBeenCalled();
+    expect(updateMessageMetadataMock).not.toHaveBeenCalled();
+  });
+
+  test("persists injected block, recall log, and emits memory_recalled", async () => {
+    const received: ServerMessage[] = [];
+    const { memory } = makeFakeGraphMemory({
+      injectedBlockText: "injected-block",
+      metrics: makeMetrics(),
+    });
+    const ctx = makeHookCtx({
+      graphMemory: memory,
+      onEvent: (msg) => received.push(msg),
+      userMessageId: "msg-42",
+      conversationId: "conv-42",
+    });
+
+    await userPromptSubmitMemoryRetrieval(ctx);
+
+    expect(updateMessageMetadataMock).toHaveBeenCalledWith("msg-42", {
+      memoryInjectedBlock: "injected-block",
+    });
+    expect(recordMemoryRecallLogMock).toHaveBeenCalledTimes(1);
+    const logEntry = recordMemoryRecallLogMock.mock.calls[0]?.[0] as {
+      conversationId: string;
+      reason: string;
+    };
+    expect(logEntry.conversationId).toBe("conv-42");
+    expect(logEntry.reason).toBe("graph:none");
+    expect(received).toHaveLength(1);
+    expect(received[0]?.type).toBe("memory_recalled");
+  });
+
+  test("skips metadata persist when no block text is injected", async () => {
+    const { memory } = makeFakeGraphMemory({ injectedBlockText: null });
+    const ctx = makeHookCtx({ graphMemory: memory });
+
+    await userPromptSubmitMemoryRetrieval(ctx);
+
+    expect(updateMessageMetadataMock).not.toHaveBeenCalled();
+    // The recall log is still written even without an injected block.
+    expect(recordMemoryRecallLogMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("propagates errors from prepareMemory rather than swallowing them", async () => {
+    // Memory is critical — failures must surface to the caller (the agent
+    // loop) rather than silently degrading to an empty graph result.
+    const failingPrepare = mock(
+      (
+        _msgs: Message[],
+        _cfg: AssistantConfig,
+        _signal: AbortSignal,
+        _onEvent: (msg: ServerMessage) => void,
+      ) => Promise.reject(new Error("retrieval failed")),
+    );
+    const graphMemory = {
+      prepareMemory: failingPrepare,
+    } as unknown as ConversationGraphMemory;
+    const ctx = makeHookCtx({ graphMemory, isTrustedActor: true });
+
+    await expect(userPromptSubmitMemoryRetrieval(ctx)).rejects.toThrow(
+      "retrieval failed",
+    );
+  });
+
+  test("forwards the context abort signal into prepareMemory", async () => {
+    // The hook hands its `ctx.signal` straight to `prepareMemory` so an
+    // external cancel aborts the underlying retrieval.
+    let capturedSignal: AbortSignal | undefined;
+    const prepareMemoryMock = mock(
+      async (
+        _msgs: Message[],
+        _cfg: AssistantConfig,
+        signal: AbortSignal,
+        _onEvent: (msg: ServerMessage) => void,
+      ) => {
+        capturedSignal = signal;
+        return {
+          runMessages: [],
+          injectedTokens: 0,
+          latencyMs: 0,
+          mode: "none" as const,
+          injectedBlockText: null,
+          metrics: null,
+        };
+      },
+    );
+    const graphMemory = {
+      prepareMemory: prepareMemoryMock,
+      recordPkbQueryVectors: mock(() => {}),
+    } as unknown as ConversationGraphMemory;
+    const controller = new AbortController();
+    const ctx = makeHookCtx({ graphMemory, signal: controller.signal });
+
+    await userPromptSubmitMemoryRetrieval(ctx);
+
+    expect(capturedSignal).toBe(controller.signal);
+  });
+});

package/src/__tests__/memory-v2-static-injector.test.ts

@@ -2,26 +2,46 @@
  * Tests for the `memory-v2-static` runtime injector.
  *
  * Covers:
- *   - Returns null when `memoryV2Static` is missing/empty.
+ *   - Returns null when the v2 static memory files are absent/empty.
  *   - Returns null when `mode === "minimal"`.
  *   - Wraps content in `<info>...</info>` and uses
  *     `after-memory-prefix` placement.
  *   - Escapes any `</info>` substring inside the authored content so the
  *     wrapper cannot be broken out of.
+ *   - Skips (re)injection when the `<info>` block is already present in the
+ *     turn's working messages (presence detection — the block persists in
+ *     history between compactions).
  *
- * Hermetic: drives the injector's `produce()` directly with a synthesized
- * `TurnContext` — no daemon, no filesystem.
+ * The injector sources its content itself via `readMemoryV2StaticContent()`
+ * behind the personal-memory trust gate, so each test seeds the workspace
+ * memory files rather than passing the content in as an option. Mocks
+ * `config/loader` so the v2 gates are on without standing up a full config.
  */
 
-import { describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
-import { defaultInjectorsPlugin } from "../plugins/defaults/injectors/register.js";
+const realLoader = await import("../config/loader.js");
+
+mock.module("../config/loader.js", () => ({
+  ...realLoader,
+  loadConfig: () => ({
+    memory: { enabled: true, v2: { enabled: true } },
+  }),
+  getConfig: () => ({
+    memory: { enabled: true, v2: { enabled: true } },
+  }),
+}));
+
+const { defaultInjectors } =
+  await import("../plugins/defaults/injectors/register.js");
 import type { Injector, TurnContext } from "../plugins/types.js";
+import type { Message } from "../providers/types.js";
+import { getWorkspacePromptPath } from "../util/platform.js";
 
 function findInjector(name: string): Injector {
-  const injector = defaultInjectorsPlugin.injectors?.find(
-    (i) => i.name === name,
-  );
+  const injector = defaultInjectors.find((i) => i.name === name);
   if (!injector) {
     throw new Error(`injector '${name}' not registered`);
   }
@@ -34,57 +54,69 @@ function makeContext(overrides: Partial<TurnContext> = {}): TurnContext {
     conversationId: "conv-test",
     turnIndex: 0,
     trust: { sourceChannel: "vellum", trustClass: "guardian" },
+    injectionInputs: {},
     ...overrides,
   };
 }
 
+/** Seed a single v2 static memory section under `## Essentials`. */
+function seedEssentials(body: string): void {
+  const path = getWorkspacePromptPath("memory/essentials.md");
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, body, "utf-8");
+}
+
+function seedThreads(body: string): void {
+  const path = getWorkspacePromptPath("memory/threads.md");
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, body, "utf-8");
+}
+
+function clearV2StaticFiles(): void {
+  for (const file of [
+    "memory/essentials.md",
+    "memory/threads.md",
+    "memory/recent.md",
+    "memory/buffer.md",
+  ]) {
+    rmSync(getWorkspacePromptPath(file), { force: true });
+  }
+}
+
 const memoryV2StaticInjector = findInjector("memory-v2-static");
 
 describe("memory-v2-static injector", () => {
-  test("returns null when memoryV2Static is undefined", async () => {
-    const ctx = makeContext({ injectionInputs: {} });
-    expect(await memoryV2StaticInjector.produce(ctx)).toBeNull();
-  });
+  beforeEach(() => clearV2StaticFiles());
+  afterEach(() => clearV2StaticFiles());
 
-  test("returns null when memoryV2Static is null", async () => {
-    const ctx = makeContext({ injectionInputs: { memoryV2Static: null } });
-    expect(await memoryV2StaticInjector.produce(ctx)).toBeNull();
-  });
-
-  test("returns null when memoryV2Static is an empty string", async () => {
-    const ctx = makeContext({ injectionInputs: { memoryV2Static: "" } });
+  test("returns null when the v2 static memory files are absent", async () => {
+    const ctx = makeContext();
     expect(await memoryV2StaticInjector.produce(ctx)).toBeNull();
   });
 
   test("returns null in minimal mode even with content", async () => {
-    const ctx = makeContext({
-      injectionInputs: {
-        mode: "minimal",
-        memoryV2Static: "## Essentials\n\nAlice prefers VS Code.",
-      },
-    });
+    seedEssentials("Alice prefers VS Code.");
+    const ctx = makeContext({ injectionInputs: { mode: "minimal" } });
     expect(await memoryV2StaticInjector.produce(ctx)).toBeNull();
   });
 
   test("wraps content in <info>...</info> with after-memory-prefix placement", async () => {
-    const content =
-      "## Essentials\n\nAlice prefers VS Code.\n\n## Threads\n\nOpen: ship PR.";
-    const ctx = makeContext({
-      injectionInputs: { memoryV2Static: content },
-    });
+    seedEssentials("Alice prefers VS Code.");
+    seedThreads("Open: ship PR.");
+    const ctx = makeContext();
 
     const block = await memoryV2StaticInjector.produce(ctx);
     expect(block).not.toBeNull();
     expect(block!.id).toBe("memory-v2-static");
     expect(block!.placement).toBe("after-memory-prefix");
-    expect(block!.text).toBe(`<info>\n${content}\n</info>`);
+    expect(block!.text).toBe(
+      "<info>\n## Essentials\n\nAlice prefers VS Code.\n\n## Threads\n\nOpen: ship PR.\n</info>",
+    );
   });
 
   test("escapes inner </info> closing tags so the wrapper cannot be broken out of", async () => {
-    const content = "## Essentials\n\nText with </info> embedded.";
-    const ctx = makeContext({
-      injectionInputs: { memoryV2Static: content },
-    });
+    seedEssentials("Text with </info> embedded.");
+    const ctx = makeContext();
 
     const block = await memoryV2StaticInjector.produce(ctx);
     expect(block).not.toBeNull();
@@ -92,4 +124,40 @@ describe("memory-v2-static injector", () => {
       "<info>\n## Essentials\n\nText with &lt;/info&gt; embedded.\n</info>",
     );
   });
+
+  test("skips (re)injection when the <info> block is already present", async () => {
+    seedEssentials("Alice prefers VS Code.");
+    const ctx = makeContext();
+    const runMessages: Message[] = [
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "<info>\nstale memory\n</info>" },
+          { type: "text", text: "What next?" },
+        ],
+      },
+    ];
+    expect(await memoryV2StaticInjector.produce(ctx, runMessages)).toBeNull();
+  });
+
+  test("skips (re)injection when a legacy <memory>-wrapped static block is present", async () => {
+    // Rows persisted before the `<info>` switch rehydrate the static block as
+    // `<memory>…</memory>`. Re-injecting a fresh `<info>` copy alongside it
+    // would duplicate the content until the next compaction.
+    seedEssentials("Alice prefers VS Code.");
+    const ctx = makeContext();
+    const runMessages: Message[] = [
+      {
+        role: "user",
+        content: [
+          {
+            type: "text",
+            text: "<memory>\n## Essentials\n\nAlice prefers VS Code.\n</memory>",
+          },
+          { type: "text", text: "What next?" },
+        ],
+      },
+    ];
+    expect(await memoryV2StaticInjector.produce(ctx, runMessages)).toBeNull();
+  });
 });

package/src/__tests__/native-web-search.test.ts

@@ -71,9 +71,56 @@ mock.module("@anthropic-ai/sdk", () => ({
   },
 }));
 
+// Mock daemon collaborators the handler module imports at load time so the
+// handler-level tests below can drive `server_tool_complete` in isolation.
+mock.module("../config/loader.js", () => ({
+  getConfig: () => ({
+    skills: {
+      entries: {},
+      load: { extraDirs: [], watch: false, watchDebounceMs: 0 },
+      install: { nodeManager: "npm" },
+      allowBundled: null,
+      remoteProviders: {
+        skillssh: { enabled: true },
+        clawhub: { enabled: true },
+      },
+      remotePolicy: {
+        blockSuspicious: true,
+        blockMalware: true,
+        maxSkillsShRisk: "medium",
+      },
+    },
+  }),
+  loadConfig: () => ({}),
+}));
+
+mock.module("../memory/conversation-crud.js", () => ({
+  addMessage: () => ({ id: "mock-msg-id" }),
+  getMessageById: () => null,
+  updateMessageContent: () => {},
+  provenanceFromTrustContext: () => ({}),
+  reserveMessage: mock(async () => ({ id: "msg-reserve" })),
+}));
+
+mock.module("../memory/llm-request-log-store.js", () => ({
+  recordRequestLog: () => {},
+  backfillMessageIdOnLogs: () => {},
+}));
+
 // Import after mocking
+import {
+  createEventHandlerState,
+  type EventHandlerState,
+} from "../daemon/conversation-agent-loop-handlers.js";
 import { AnthropicProvider } from "../providers/anthropic/client.js";
 import { isNativeWebSearchCapableProvider } from "../providers/registry.js";
+import { WEB_SEARCH_BACKEND_FAILURE_MESSAGE } from "../tools/network/web-search-error.js";
+import {
+  completeNativeWebSearch,
+  createHandlerDeps,
+  lastToolResult,
+  toolResults,
+} from "./helpers/native-web-search-harness.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -499,3 +546,147 @@ describe("Native Web Search — Streaming Events", () => {
     expect(toolUseEvents).toHaveLength(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Tests — Native server_tool_complete backend-failure handling (ATL-727)
+// ---------------------------------------------------------------------------
+
+describe("Native Web Search — Backend Failure Handling", () => {
+  let state: EventHandlerState;
+
+  beforeEach(() => {
+    state = createEventHandlerState();
+  });
+
+  test("backend failure surfaces friendly copy with isError true and empty results", async () => {
+    const { deps, events } = createHandlerDeps();
+    await completeNativeWebSearch(state, deps, "tu_backend", {
+      isError: true,
+      errorCode: "unavailable",
+    });
+
+    const result = lastToolResult(events);
+    expect(result?.activityMetadata?.webSearch?.errorMessage).toBe(
+      WEB_SEARCH_BACKEND_FAILURE_MESSAGE,
+    );
+    expect(result?.isError).toBe(true);
+    expect(result?.activityMetadata?.webSearch?.resultCount).toBe(0);
+    expect(result?.activityMetadata?.webSearch?.results).toEqual([]);
+  });
+
+  test("raw error_code is logged under web_search_backend_failure but absent from user copy", async () => {
+    const { deps, events, warnings } = createHandlerDeps();
+    await completeNativeWebSearch(state, deps, "tu_log", {
+      isError: true,
+      errorCode: "unavailable",
+    });
+
+    const failureLog = warnings.find(
+      (w) => w.obj.event === "web_search_backend_failure",
+    );
+    expect(failureLog).toBeDefined();
+    expect(failureLog?.obj.provider).toBe("anthropic-native");
+    expect(String(failureLog?.obj.rawDetail)).toContain("unavailable");
+    expect(failureLog?.obj.fallbackShown).toBe(true);
+
+    const errorMessage = lastToolResult(events)?.activityMetadata?.webSearch
+      ?.errorMessage;
+    expect(errorMessage).not.toContain("unavailable");
+  });
+
+  test("dedups repeat backend failures within one turn to a single friendly notice", async () => {
+    const { deps, events, warnings } = createHandlerDeps();
+
+    await completeNativeWebSearch(state, deps, "tu_dup_1", {
+      isError: true,
+      errorCode: "unavailable",
+    });
+    await completeNativeWebSearch(state, deps, "tu_dup_2", {
+      isError: true,
+      errorCode: "overloaded_error",
+    });
+
+    const results = toolResults(events);
+    expect(results).toHaveLength(2);
+    expect(results[0]?.activityMetadata?.webSearch?.errorMessage).toBe(
+      WEB_SEARCH_BACKEND_FAILURE_MESSAGE,
+    );
+    // The second backend failure in the same turn is terse, not the full notice.
+    expect(results[1]?.activityMetadata?.webSearch?.errorMessage).not.toBe(
+      WEB_SEARCH_BACKEND_FAILURE_MESSAGE,
+    );
+
+    const failureLogs = warnings.filter(
+      (w) => w.obj.event === "web_search_backend_failure",
+    );
+    // Both failures are logged, but only the first reports fallbackShown.
+    expect(failureLogs).toHaveLength(2);
+    expect(failureLogs.filter((w) => w.obj.fallbackShown === true)).toHaveLength(
+      1,
+    );
+  });
+
+  test("successful search leaves errorMessage undefined and populates results", async () => {
+    const { deps, events, warnings } = createHandlerDeps();
+    await completeNativeWebSearch(state, deps, "tu_ok", {
+      isError: false,
+      content: [
+        {
+          type: "web_search_result",
+          title: "Weather",
+          url: "https://example.com/weather",
+        },
+      ],
+    });
+
+    const meta = lastToolResult(events)?.activityMetadata?.webSearch;
+    expect(meta?.errorMessage).toBeUndefined();
+    expect(meta?.resultCount).toBe(1);
+    expect(meta?.results[0]?.title).toBe("Weather");
+    expect(lastToolResult(events)?.isError).toBe(false);
+    expect(
+      warnings.filter((w) => w.obj.event === "web_search_backend_failure"),
+    ).toHaveLength(0);
+  });
+
+  test("query_too_long yields a distinct non-backend message", async () => {
+    const { deps, events, warnings } = createHandlerDeps();
+    await completeNativeWebSearch(state, deps, "tu_long", {
+      isError: true,
+      errorCode: "query_too_long",
+    });
+
+    const errorMessage = lastToolResult(events)?.activityMetadata?.webSearch
+      ?.errorMessage;
+    expect(errorMessage).toBeDefined();
+    expect(errorMessage).not.toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+    // Recoverable non-backend errors must NOT emit backend-failure telemetry.
+    expect(
+      warnings.filter((w) => w.obj.event === "web_search_backend_failure"),
+    ).toHaveLength(0);
+  });
+
+  test("message-less native failure (no error_code) surfaces friendly copy, not the terse 'Search failed' placeholder, and emits no backend telemetry", async () => {
+    const { deps, events, warnings } = createHandlerDeps("req-unknown");
+    // `isError:true` with no error_code/message classifies as `unknown`
+    // (isBackendFailure:false, empty userMessage). It must still get the
+    // friendly copy rather than the bare "Search failed".
+    await completeNativeWebSearch(state, deps, "tu_unknown", {
+      isError: true,
+    });
+
+    const result = lastToolResult(events);
+    const meta = result?.activityMetadata?.webSearch;
+    expect(meta?.errorMessage).toBe(WEB_SEARCH_BACKEND_FAILURE_MESSAGE);
+    expect(meta?.errorMessage).not.toBe("Search failed");
+    expect(result?.isError).toBe(true);
+    expect(meta?.resultCount).toBe(0);
+    expect(meta?.results).toEqual([]);
+
+    // An unclassifiable failure borrows the friendly copy but must NOT be
+    // logged as a backend outage.
+    expect(
+      warnings.filter((w) => w.obj.event === "web_search_backend_failure"),
+    ).toHaveLength(0);
+  });
+});