Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(web-search): ride out a Vertex blip on a remembered answer, without ever replaying one over a safety block

nirholas2b73f2e8f006
diff --git a/api/_lib/web-search.js b/api/_lib/web-search.js
index d4f0c484c..dcb230517 100644
--- a/api/_lib/web-search.js
+++ b/api/_lib/web-search.js
@@ -25,6 +25,7 @@
// VERTEX_GEMINI_MODEL : model id (default: google/gemini-2.5-flash)
import { getGcpAccessToken } from './gcp-auth.js';
+import { isRetryableError } from './resilience.js';
import { vertexGeminiAvailable, vertexGeminiModel, vertexGeminiThinkingBudget } from './vertex-gemini.js';
const FETCH_TIMEOUT_MS = 20_000;
@@ -78,6 +79,54 @@ export async function groundedSearch(query, { maxSources = 8, signal } = {}) {
const q = String(query || '').trim();
if (!q) throw new Error('web search: empty query');
+ // Grounded search has one provider and no second opinion worth the name: a
+ // different engine would answer a different question with different
+ // citations. What it can have is a memory. The same query asked twice inside
+ // a few minutes deserves the same answer, so a remembered result rides out a
+ // Vertex blip instead of turning a search box into a 502.
+ //
+ // The memory covers AVAILABILITY failures only. A safety block, an empty
+ // answer or a 4xx is the model's verdict on this request, and replaying an
+ // older answer over it would quietly overturn a decision that was made on
+ // purpose. Those still reject, exactly as before.
+ const key = `${q.toLowerCase()}::${maxSources}`;
+ try {
+ const value = await groundedSearchLive(q, { maxSources, signal });
+ _searchMemory.set(key, { value, at: Date.now() });
+ if (_searchMemory.size > SEARCH_MEMORY_MAX) {
+ _searchMemory.delete(_searchMemory.keys().next().value);
+ }
+ return value;
+ } catch (err) {
+ if (!isAvailabilityFailure(err)) throw err;
+ const hit = _searchMemory.get(key);
+ if (!hit || Date.now() - hit.at > SEARCH_MEMORY_MAX_AGE_MS) throw err;
+ console.warn(`[web-search] upstream unavailable (${err?.message || err}); serving a remembered answer`);
+ return { ...hit.value, stale: true, as_of: new Date(hit.at).toISOString() };
+ }
+}
+
+const SEARCH_MEMORY_MAX = 500;
+const SEARCH_MEMORY_MAX_AGE_MS = 10 * 60_000;
+const _searchMemory = new Map();
+
+/**
+ * Whether an error means "the provider could not answer right now" as opposed
+ * to "the provider answered, and this is the answer". Only the first kind may
+ * be papered over with a remembered result.
+ */
+function isAvailabilityFailure(err) {
+ if (isRetryableError(err)) return true;
+ const msg = String(err?.message || err);
+ return /fetch failed|network|socket hang up|ECONNRESET|ETIMEDOUT|EAI_AGAIN|timed? ?out/i.test(msg);
+}
+
+/** Test seam: forget every remembered answer. */
+export function _resetWebSearchMemory() {
+ _searchMemory.clear();
+}
+
+async function groundedSearchLive(q, { maxSources, signal }) {
const token = await getGcpAccessToken();
const think = vertexGeminiThinkingBudget();
const res = await fetch(groundedUrl(), {
@@ -104,7 +153,7 @@ export async function groundedSearch(query, { maxSources = 8, signal } = {}) {
});
if (!res.ok) {
const detail = (await res.text().catch(() => '')).slice(0, 300);
- throw new Error(`web search upstream ${res.status}: ${detail}`);
+ throw Object.assign(new Error(`web search upstream ${res.status}: ${detail}`), { status: res.status });
}
const body = await res.json();
diff --git a/tests/api/web-search-grounded.test.js b/tests/api/web-search-grounded.test.js
index 9b9c56ba2..f1dba0c6f 100644
--- a/tests/api/web-search-grounded.test.js
+++ b/tests/api/web-search-grounded.test.js
@@ -21,7 +21,7 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
// request body and the failure reporting, so stub the token out.
vi.mock('../../api/_lib/gcp-auth.js', () => ({ getGcpAccessToken: async () => 'test-token' }));
-const { groundedSearch, webSearchAvailable } = await import('../../api/_lib/web-search.js');
+const { groundedSearch, webSearchAvailable, _resetWebSearchMemory } = await import('../../api/_lib/web-search.js');
const OLD_ENV = { ...process.env };
@@ -124,3 +124,51 @@ describe('groundedSearch failure reporting', () => {
expect(fetchSpy).not.toHaveBeenCalled();
});
});
+
+// A single-provider surface cannot fail over, but it can remember. The line
+// that matters is WHICH failures a memory is allowed to cover: an unreachable
+// provider, yes; a safety block or an empty answer, never, because replaying an
+// older answer over one of those quietly overturns a decision made on purpose.
+describe('groundedSearch availability memory', () => {
+ const answered = (text) =>
+ jsonResponse({ candidates: [{ content: { parts: [{ text }] } }] });
+
+ beforeEach(() => {
+ _resetWebSearchMemory();
+ });
+
+ it('serves a remembered answer when the provider is unreachable', async () => {
+ vi.stubGlobal('fetch', async () => answered('cached answer'));
+ const live = await groundedSearch('memory-q');
+ expect(live.answer).toBe('cached answer');
+ expect(live.stale).toBeUndefined();
+
+ vi.stubGlobal('fetch', async () => {
+ throw new TypeError('fetch failed');
+ });
+ const stale = await groundedSearch('memory-q');
+ expect(stale.answer).toBe('cached answer');
+ expect(stale.stale).toBe(true);
+ expect(stale.as_of).toBeTruthy();
+ });
+
+ it('serves a remembered answer through a 503, but never through a safety block', async () => {
+ vi.stubGlobal('fetch', async () => answered('cached answer'));
+ await groundedSearch('memory-q2');
+
+ vi.stubGlobal('fetch', async () => jsonResponse({ error: 'busy' }, false, 503));
+ expect((await groundedSearch('memory-q2')).stale).toBe(true);
+
+ vi.stubGlobal('fetch', async () =>
+ jsonResponse({ candidates: [], promptFeedback: { blockReason: 'SAFETY' } }),
+ );
+ await expect(groundedSearch('memory-q2')).rejects.toThrow(/promptBlockReason=SAFETY/);
+ });
+
+ it('rethrows when the provider is unreachable and nothing was ever remembered', async () => {
+ vi.stubGlobal('fetch', async () => {
+ throw new TypeError('fetch failed');
+ });
+ await expect(groundedSearch('never-seen')).rejects.toThrow(/fetch failed/);
+ });
+});