Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
const mocks = vi.hoisted(() => ({
search: vi.fn(),
searchDeveloperCategory: vi.fn(),
searchGovCategory: vi.fn(),
searchGovIfRouted: vi.fn(),
checkUrlsAgainstThreatPolicy: vi.fn(),
discoverTools: vi.fn(),
discoverSkills: vi.fn(),
removeExplicitResults: vi.fn(),
inferToolIntent: vi.fn(),
verifyTools: vi.fn(),
}));
vi.mock("./tool-intent", () => ({
AUTO_TOOLS_WAIT_MS: 300,
FUSED_FIT_THRESHOLD: 0.2,
inferToolIntent: mocks.inferToolIntent,
verifyTools: mocks.verifyTools,
}));
vi.mock("./alexandria", () => ({
discoverTools: mocks.discoverTools,
usOnlyToolsWarning: (excluded: number) => `${excluded} tools hidden`,
isAlexandriaSource: (source: { type: string }) =>
source.type === "alexandria",
}));
vi.mock("./skill-cards", () => ({
discoverSkills: mocks.discoverSkills,
isSkillsSource: (source: { type: string }) => source.type === "skills",
SKILLS_DISCOVERY_TIMEOUT_MS: 3000,
}));
vi.mock("./v2", () => ({ search: mocks.search }));
vi.mock("./developer", () => ({
wantsDeveloperCategory: (categories?: Array<string | { type: string }>) =>
(categories ?? []).some(category =>
typeof category === "string"
? category === "developer"
: category.type === "developer",
),
searchDeveloperCategory: mocks.searchDeveloperCategory,
}));
vi.mock("./gov", () => ({
wantsGovCategory: (categories?: Array<string | { type: string }>) =>
(categories ?? []).some(category =>
typeof category === "string"
? category === "gov"
: category.type === "gov",
),
searchGovCategory: mocks.searchGovCategory,
searchGovIfRouted: mocks.searchGovIfRouted,
MAX_ROUTED_LIMIT: 10,
}));
vi.mock("./scrape", () => ({
getItemsToScrape: vi.fn(() => []),
scrapeSearchResults: vi.fn(),
mergeScrapedContent: vi.fn(),
calculateScrapeCredits: vi.fn(() => 0),
}));
vi.mock("./highlights", () => ({
highlightsEnvReady: () => false,
runIndexedSearchHighlights: vi.fn(),
searchHighlightsMode: vi.fn(),
}));
vi.mock("../lib/tracking", () => ({
trackSearchRequest: vi.fn(async () => {}),
trackSearchResults: vi.fn(async () => {}),
}));
vi.mock("../lib/threat-protection/request", () => ({
checkUrlsAgainstThreatPolicy: mocks.checkUrlsAgainstThreatPolicy,
}));
vi.mock("../lib/scrape-billing", () => ({
calculateThreatScanCredits: vi.fn(() => 0),
}));
vi.mock("./safe-search", () => ({
removeExplicitResults: mocks.removeExplicitResults,
}));
import { executeSearch } from "./execute";
import { searchRequestSchema } from "../controllers/v2/types";
import { logger as rootLogger } from "../lib/logger";
const impressions = vi
.spyOn(rootLogger, "info")
.mockImplementation(() => rootLogger);
const logger = {
info: vi.fn(),
warn: vi.fn(),
error: vi.fn(),
debug: vi.fn(),
} as any;
const context = {
teamId: "team-1",
origin: "api",
apiKeyId: 1,
flags: {},
requestId: "request-1",
jobId: "job-1",
apiVersion: "v2",
};
// searchDeveloperCategory returns the exact WebSearchResult shape.
const developerResult = {
url: "https://github.com/firecrawl/firecrawl/issues/1",
title: "Retry requests",
description: "Use exponential backoff.",
position: 1,
category: "developer",
};
function options(categories: Array<{ type: string }>) {
return {
query: "retries",
limit: 10,
sources: [{ type: "web" }],
categories,
timeout: 1_000,
} as any;
}
beforeEach(() => {
vi.clearAllMocks();
mocks.searchDeveloperCategory.mockResolvedValue([developerResult]);
mocks.searchGovIfRouted.mockResolvedValue(null);
mocks.discoverTools.mockResolvedValue({
status: "available",
items: [{ id: "fred/series/observations" }],
});
mocks.discoverSkills.mockResolvedValue({ skills: [], succeeded: false });
mocks.verifyTools.mockImplementation(async (_query, items) => items);
});
it("tool-only search never runs or bills SERP", async () => {
const result = await executeSearch(
{ ...options([]), sources: [{ type: "alexandria" }] },
{ ...context, flags: { exchangeRetrieve: true } },
logger,
);
expect(mocks.search).not.toHaveBeenCalled();
expect(result.searchCredits).toBe(0);
expect(result.response.tools).toEqual([{ id: "fred/series/observations" }]);
});
it("passes through unavailable tool discovery", async () => {
mocks.discoverTools.mockResolvedValue({
items: [],
warning: "Some tool discovery results are unavailable.",
unavailable: true,
});
const result = await executeSearch(
{ ...options([]), sources: [{ type: "alexandria" }] },
{ ...context, flags: { exchangeRetrieve: true } },
logger,
);
expect(result.toolsUnavailable).toBe(true);
expect(result.response.tools).toEqual([]);
});
it("mixed search bills only normal web results", async () => {
mocks.search.mockResolvedValue({ web: [developerResult] });
const result = await executeSearch(
{ ...options([]), sources: [{ type: "web" }, { type: "alexandria" }] },
{ ...context, flags: { exchangeRetrieve: true } },
logger,
);
expect(mocks.search).toHaveBeenCalledWith(
expect.objectContaining({ type: ["web"] }),
);
expect(result.searchCredits).toBe(2);
expect(result.response.tools).toHaveLength(1);
});
describe("executeSearch tool intent", () => {
const webResult = {
url: "https://example.com/",
title: "Example",
description: "An example page.",
};
it("keeps the raw query and adds verified rewrite and domain tools", async () => {
mocks.inferToolIntent.mockResolvedValue({
toolQueries: ["institutional holders of a public company"],
domains: ["sec.gov"],
needsTools: true,
});
await executeSearch(
{
...options([]),
query: "who owns apple stock",
sources: [{ type: "alexandria" }],
inferToolQuery: true,
},
context,
logger,
);
expect(mocks.discoverTools).toHaveBeenCalledWith(
expect.objectContaining({ queries: ["who owns apple stock"] }),
logger,
);
expect(mocks.discoverTools).toHaveBeenCalledWith(
expect.objectContaining({
queries: ["institutional holders of a public company"],
urls: ["https://sec.gov/"],
}),
logger,
);
expect(mocks.verifyTools).toHaveBeenCalledWith(
"who owns apple stock",
[{ id: "fred/series/observations" }],
logger,
);
});
it("adds no tool the fit check rejects", async () => {
const own = { provider: "sec-gov", capability: "filings/filings" };
const extra = { provider: "apps-apple-com", capability: "apps/app" };
mocks.discoverTools.mockImplementation(
async (input: { queries?: string[] }) => ({
items: input.queries?.[0] === "who owns apple stock" ? [own] : [extra],
}),
);
mocks.inferToolIntent.mockResolvedValue({
toolQueries: ["institutional holders of a public company"],
domains: [],
needsTools: true,
});
mocks.verifyTools.mockResolvedValue([]);
const result = await executeSearch(
{
...options([]),
query: "who owns apple stock",
sources: [{ type: "alexandria" }],
inferToolQuery: true,
},
context,
logger,
);
expect(result.response.tools).toEqual([own]);
});
it("adds tools to a default search when the query needs them", async () => {
mocks.search.mockResolvedValue({ web: [webResult] });
mocks.inferToolIntent.mockResolvedValue({
toolQueries: ["US unemployment rate statistics"],
domains: [],
needsTools: true,
});
const result = await executeSearch(
{ ...options([]), autoTools: true },
context,
logger,
);
expect(mocks.discoverTools).toHaveBeenCalledWith(
expect.objectContaining({
toolDetail: "compact",
queries: ["retries", "US unemployment rate statistics"],
urls: [],
}),
logger,
);
expect(result.toolsAuto).toBe(true);
expect(result.response.tools).toEqual([{ id: "fred/series/observations" }]);
expect(result.searchCredits).toBe(2);
});
it("warns a US-only team about tools hidden from automatic discovery", async () => {
mocks.search.mockResolvedValue({ web: [webResult] });
mocks.inferToolIntent.mockResolvedValue({
toolQueries: ["US unemployment rate statistics"],
domains: [],
needsTools: true,
});
mocks.discoverTools.mockResolvedValue({
items: [{ id: "fred/series/observations" }],
usOnlyExcluded: 2,
});
const result = await executeSearch(
{ ...options([]), autoTools: true },
{ ...context, flags: { usOnly: true } },
logger,
);
expect(mocks.search).toHaveBeenCalledWith(
expect.objectContaining({ usOnly: true }),
);
expect(mocks.discoverTools).toHaveBeenCalledWith(
expect.objectContaining({ usOnly: true }),
logger,
);
expect(result.toolsWarning).toBe("2 tools hidden");
});
it.each([
[{ scrapeZDR: "forced" }, true],
[{ forceZDR: true }, true],
[{ scrapeZDR: "allowed" }, false],
[{}, false],
])(
"asks tool and skill discovery for zero-data-retention providers by team flags (%o)",
async (flags, zeroDataRetention) => {
mocks.search.mockResolvedValue({ web: [webResult] });
mocks.discoverTools.mockResolvedValue({ items: [] });
await executeSearch(
{
...options([]),
sources: [
{ type: "web" },
{ type: "alexandria" },
{ type: "skills" },
],
},
{ ...context, flags } as any,
logger,
);
expect(mocks.discoverTools).toHaveBeenCalledWith(
expect.objectContaining({ zeroDataRetention }),
logger,
);
expect(mocks.discoverSkills).toHaveBeenCalledWith(
expect.objectContaining({ zeroDataRetention }),
logger,
);
},
);
it("leaves a default search alone when the query does not need tools", async () => {
mocks.search.mockResolvedValue({ web: [webResult] });
mocks.inferToolIntent.mockResolvedValue({
toolQueries: ["CSS layout documentation"],
domains: [],
needsTools: false,
});
const result = await executeSearch(
{ ...options([]), autoTools: true },
context,
logger,
);
expect(mocks.discoverTools).not.toHaveBeenCalled();
expect(result.toolsAuto).toBe(false);
expect(result.response.tools).toBeUndefined();
});
it("adds query tools beside domain tools when domainTools is on", async () => {
mocks.search.mockResolvedValue({ web: [webResult] });
mocks.inferToolIntent.mockResolvedValue({
toolQueries: ["website traffic statistics of a domain"],
domains: [],
needsTools: true,
});
await executeSearch(
{ ...options([]), autoTools: true, domainTools: true },
context,
logger,
);
expect(mocks.discoverTools).toHaveBeenCalledTimes(2);
const domainCall = mocks.discoverTools.mock.calls.find(
([input]) => input.urls instanceof Promise,
);
await expect(domainCall?.[0].urls).resolves.toEqual([
"https://example.com/",
]);
expect(mocks.discoverTools).toHaveBeenCalledWith(
expect.objectContaining({
queries: ["retries", "website traffic statistics of a domain"],
urls: [],
}),
logger,
);
});
it("waits at most 300ms past the web results for tools it did not ask for", async () => {
mocks.search.mockResolvedValue({ web: [webResult] });
mocks.inferToolIntent.mockResolvedValue({
toolQueries: ["US unemployment rate statistics"],
domains: [],
needsTools: true,
});
mocks.discoverTools.mockReturnValue(new Promise(() => {}));
vi.useFakeTimers();
try {
let done = false;
const pending = executeSearch(
{ ...options([]), autoTools: true },
context,
logger,
).finally(() => {
done = true;
});
await vi.advanceTimersByTimeAsync(299);
expect(done).toBe(false);
await vi.advanceTimersByTimeAsync(1);
const result = await pending;
expect(result.response.tools).toBeUndefined();
} finally {
vi.useRealTimers();
}
});
describe("with tool fusion", () => {
const tool = (provider: string) => ({ provider, capability: "data/get" });
const intent = {
toolQueries: ["institutional holders of a public company"],
domains: [],
needsTools: true,
};
const fused = (query: string) =>
executeSearch(
{
...options([]),
query,
sources: [{ type: "alexandria" }],
inferToolQuery: true,
toolFusion: true,
},
context,
logger,
);
it("ranks rewrite tools among raw-query tools by reciprocal rank", async () => {
mocks.inferToolIntent.mockResolvedValue(intent);
mocks.discoverTools.mockImplementation(
async (input: { queries?: string[] }) =>
input.queries?.[0] === "who owns apple stock"
? {
items: [tool("a"), tool("b"), tool("c"), tool("domain")],
semanticMatches: 3,
}
: {
items: [tool("x"), tool("c"), tool("y"), tool("site")],
semanticMatches: 3,
},
);
const result = await fused("who owns apple stock");
expect(result.response.tools?.map(found => found.provider)).toEqual([
"c",
"a",
"x",
"b",
"y",
"domain",
"site",
]);
expect(mocks.verifyTools).toHaveBeenCalledWith(
"who owns apple stock",
[tool("x"), tool("c"), tool("y")],
logger,
0.2,
);
expect(mocks.verifyTools).toHaveBeenCalledWith(
"who owns apple stock",
[tool("site")],
logger,
);
});
it("logs the served tools with their rank, source and fit rejections", async () => {
mocks.inferToolIntent.mockResolvedValue(intent);
mocks.discoverTools.mockImplementation(
async (input: {
queries?: string[];
exchangeRequestIds?: { prefix: string; sent: string[] };
}) => {
input.exchangeRequestIds?.sent.push(
`${input.exchangeRequestIds.prefix}:1`,
);
return input.queries?.[0] === "who owns apple stock"
? {
items: [tool("a"), tool("b"), tool("c"), tool("domain")],
semanticMatches: 3,
}
: {
items: [tool("x"), tool("c"), tool("y"), tool("site")],
semanticMatches: 3,
};
},
);
mocks.verifyTools.mockImplementation(async (_query, items) =>
items.filter(
(item: { provider: string }) =>
item.provider !== "y" && item.provider !== "site",
),
);
const result = await fused("who owns apple stock");
expect(result.toolFusion).toBe(true);
expect(mocks.discoverTools).toHaveBeenCalledWith(
expect.objectContaining({
exchangeRequestIds: expect.objectContaining({
prefix: "job-1:tools:raw",
}),
}),
logger,
);
expect(mocks.discoverTools).toHaveBeenCalledWith(
expect.objectContaining({
exchangeRequestIds: expect.objectContaining({
prefix: "job-1:tools:rewrite",
}),
}),
logger,
);
expect(impressions).toHaveBeenCalledWith("Search tool impression", {
event: "search_tool_impression",
searchId: "job-1",
teamId: "team-1",
servedAt: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/),
auto: false,
fusion: { enabled: true, ran: true },
rewrite: "arrived",
tools: [
{ id: "c/data/get", rank: 1, source: "both" },
{ id: "a/data/get", rank: 2, source: "raw" },
{ id: "x/data/get", rank: 3, source: "rewrite" },
{ id: "b/data/get", rank: 4, source: "raw" },
{ id: "domain/data/get", rank: 5, source: "raw" },
],
fitRejected: { semantic: 1, domain: 1 },
exchangeRequestIds: {
raw: ["job-1:tools:raw:1"],
rewrite: ["job-1:tools:rewrite:1"],
},
});
expect(JSON.stringify(impressions.mock.calls)).not.toContain(
"who owns apple stock",
);
expect(logger.info).not.toHaveBeenCalledWith(
"Search tool impression",
expect.anything(),
);
});
it("reports no fusion when the rewrite found no tools", async () => {
mocks.inferToolIntent.mockResolvedValue(intent);
mocks.discoverTools.mockImplementation(
async (input: { queries?: string[] }) =>
input.queries?.[0] === "who owns apple stock"
? { items: [tool("a")], semanticMatches: 1 }
: { items: [], semanticMatches: 0 },
);
const result = await fused("who owns apple stock");
expect(result.toolFusion).toBe(false);
expect(impressions).toHaveBeenCalledWith(
"Search tool impression",
expect.objectContaining({
fusion: { enabled: true, ran: false },
rewrite: "empty",
}),
);
});
it("drops rewrite-only tools the fit check rejects", async () => {
mocks.inferToolIntent.mockResolvedValue(intent);
mocks.discoverTools.mockImplementation(
async (input: { queries?: string[] }) =>
input.queries?.[0] === "who owns apple stock"
? { items: [tool("a"), tool("b")], semanticMatches: 2 }
: { items: [tool("x"), tool("b")], semanticMatches: 2 },
);
mocks.verifyTools.mockResolvedValue([]);
const result = await fused("who owns apple stock");
expect(result.response.tools?.map(found => found.provider)).toEqual([
"b",
"a",
]);
});
it("scores rewrite tools by their original rank when earlier ones are rejected", async () => {
mocks.inferToolIntent.mockResolvedValue(intent);
mocks.discoverTools.mockImplementation(
async (input: { queries?: string[] }) =>
input.queries?.[0] === "who owns apple stock"
? { items: [tool("a"), tool("b")], semanticMatches: 2 }
: { items: [tool("x"), tool("y")], semanticMatches: 2 },
);
mocks.verifyTools.mockImplementation(async (_query, items) =>
items.filter((item: { provider: string }) => item.provider !== "x"),
);
const result = await fused("who owns apple stock");
expect(result.response.tools?.map(found => found.provider)).toEqual([
"a",
"b",
"y",
]);
});
it("waits up to the configured cap past the raw lookup for rewrite tools", async () => {
mocks.inferToolIntent.mockResolvedValue(intent);
mocks.discoverTools.mockImplementation(
(input: {
queries?: string[];
exchangeRequestIds?: { prefix: string; sent: string[] };
}) => {
input.exchangeRequestIds?.sent.push(
`${input.exchangeRequestIds.prefix}:1`,
);
if (input.queries?.[0] === "who owns apple stock")
return Promise.resolve({ items: [tool("a")], semanticMatches: 1 });
return new Promise(() => {});
},
);
vi.useFakeTimers();
try {
let done = false;
const pending = fused("who owns apple stock").finally(() => {
done = true;
});
await vi.advanceTimersByTimeAsync(999);
expect(done).toBe(false);
await vi.advanceTimersByTimeAsync(1);
const result = await pending;
expect(result.response.tools).toEqual([tool("a")]);
expect(result.toolFusion).toBe(false);
expect(impressions).toHaveBeenCalledWith(
"Search tool impression",
expect.objectContaining({
fusion: { enabled: true, ran: false },
rewrite: "late",
tools: [{ id: "a/data/get", rank: 1, source: "raw" }],
exchangeRequestIds: {
raw: ["job-1:tools:raw:1"],
rewrite: ["job-1:tools:rewrite:1"],
},
}),
);
} finally {
vi.useRealTimers();
}
});
});
it("never adds tools under zero data retention", async () => {
mocks.search.mockResolvedValue({ web: [webResult] });
await executeSearch(
{ ...options([]), autoTools: true },
{ ...context, zeroDataRetention: true },
logger,
);
expect(mocks.inferToolIntent).not.toHaveBeenCalled();
expect(mocks.discoverTools).not.toHaveBeenCalled();
expect(impressions).not.toHaveBeenCalledWith(
"Search tool impression",
expect.anything(),
);
});
});
describe("executeSearch safe search", () => {
const webResult = {
url: "https://example.com/",
title: "Example",
description: "An example page.",
};
it("bills and returns only the results the Jev filter keeps", async () => {
const safe = Array.from({ length: 10 }, (_, index) => ({
...webResult,
url: `https://safe${index}.example/`,
}));
const explicit = { ...webResult, url: "https://nsfw.example/" };
mocks.search.mockResolvedValue({ web: [...safe, explicit] });
mocks.removeExplicitResults.mockImplementationOnce(async response => {
response.web = response.web.filter(
(result: { url: string }) => result.url !== explicit.url,
);
});
const result = await executeSearch(
{ ...options([]), limit: 20, safe: true },
context,
logger,
);
expect(mocks.removeExplicitResults).toHaveBeenCalledWith(
expect.anything(),
20,
logger,
"team-1",
);
expect(result.response.web?.map(x => x.url)).toEqual(safe.map(x => x.url));
expect(result.totalResultsCount).toBe(10);
// 11 results would bill 4 credits; the 10 kept bill 2.
expect(result.searchCredits).toBe(2);
});
it("skips the Jev filter when safe is off or data must not be retained", async () => {
mocks.search.mockResolvedValue({ web: [webResult] });
await executeSearch(options([]), context, logger);
await executeSearch(
{ ...options([]), safe: true },
{ ...context, zeroDataRetention: true },
logger,
);
await executeSearch(
{ ...options([]), safe: true, enterprise: ["zdr"] },
context,
logger,
);
await executeSearch(
{ ...options([]), safe: true, enterprise: ["anon"] },
context,
logger,
);
expect(mocks.removeExplicitResults).not.toHaveBeenCalled();
});
});
describe("executeSearch zero data retention rate", () => {
const results = (count: number) =>
Array.from({ length: count }, (_, index) => ({
url: `https://result${index}.example/`,
title: "Result",
description: "A result.",
}));
it.each([
{ name: "a default search", enterprise: undefined, ten: 2, eleven: 4 },
{
name: "an enterprise anon search",
enterprise: ["anon"],
ten: 2,
eleven: 4,
},
{
name: "an enterprise zdr search",
enterprise: ["zdr"],
ten: 10,
eleven: 20,
},
])("bills $name per ten results", async ({ enterprise, ten, eleven }) => {
for (const [count, credits] of [
[10, ten],
[11, eleven],
]) {
mocks.search.mockResolvedValue({ web: results(count) });
const result = await executeSearch(
{ ...options([]), limit: 20, enterprise },
context,
logger,
);
expect(result.searchCredits).toBe(credits);
}
});
});
describe("executeSearch developer category", () => {
it("returns sole developer-category results in web without running SERP", async () => {
const result = await executeSearch(
options([{ type: "developer" }]),
context,
logger,
);
expect(mocks.search).not.toHaveBeenCalled();
expect(result.response).toEqual({ web: [developerResult] });
expect(result.response).not.toHaveProperty("developer");
expect(result.indexResultsCount).toBe(1);
// The vertical that served the result survives the response as a label
// keyed by the position the client sees.
expect(result.resultCategories).toEqual({ web: { "1": "developer" } });
});
it("filters blocked developer results via threat protection and renumbers", async () => {
mocks.searchDeveloperCategory.mockResolvedValue([
{
url: "https://ok.example/a",
title: "A",
description: "",
position: 1,
category: "developer",
},
{
url: "https://blocked.example/b",
title: "B",
description: "",
position: 2,
category: "developer",
},
{
url: "https://ok.example/c",
title: "C",
description: "",
position: 3,
category: "developer",
},
]);
mocks.checkUrlsAgainstThreatPolicy.mockResolvedValue({
decisionsByUrl: new Map([
["https://blocked.example/b", { allowed: false }],
]),
});
const result = await executeSearch(
options([{ type: "developer" }]),
{ ...context, threatProtectionPolicy: { mode: "block" } } as any,
logger,
);
expect(mocks.checkUrlsAgainstThreatPolicy).toHaveBeenCalledTimes(1);
expect(mocks.search).not.toHaveBeenCalled();
expect((result.response.web ?? []).map(x => [x.url, x.position])).toEqual([
["https://ok.example/a", 1],
["https://ok.example/c", 2],
]);
// Keyed by the renumbered positions, not the upstream ones — position 2 is
// the surviving third result.
expect(result.resultCategories).toEqual({
web: { "1": "developer", "2": "developer" },
});
});
it("returns an empty group and no categories when every result is blocked", async () => {
mocks.searchDeveloperCategory.mockResolvedValue([
{
url: "https://blocked.example/a",
title: "A",
description: "",
position: 1,
category: "developer",
},
{
url: "https://blocked.example/b",
title: "B",
description: "",
position: 2,
category: "developer",
},
]);
mocks.checkUrlsAgainstThreatPolicy.mockResolvedValue({
decisionsByUrl: new Map([
["https://blocked.example/a", { allowed: false }],
["https://blocked.example/b", { allowed: false }],
]),
});
const result = await executeSearch(
options([{ type: "developer" }]),
{ ...context, threatProtectionPolicy: { mode: "block" } } as any,
logger,
);
expect(result.response.web ?? []).toEqual([]);
// An empty map, not absent: the search ran and tagged nothing, which
// feedback must tell apart from a row that predates the column.
expect(result.resultCategories).toEqual({});
});
it.each([
{
name: "a forced team",
context: { zeroDataRetention: true },
enterprise: [],
},
{ name: "an enterprise zdr request", context: {}, enterprise: ["zdr"] },
{ name: "an enterprise anon request", context: {}, enterprise: ["anon"] },
])(
"marks the developer upstream call zero data retention for $name",
async c => {
await executeSearch(
{
...options([{ type: "developer" }]),
enterprise: c.enterprise,
} as any,
{ ...context, ...c.context } as any,
logger,
);
expect(mocks.searchDeveloperCategory).toHaveBeenCalledWith(
expect.objectContaining({ zeroDataRetention: true }),
logger,
);
},
);
it("rejects developer combined with other categories at the schema", () => {
const mixed = searchRequestSchema.safeParse({
query: "retries",
categories: ["developer", "pdf"],
});
expect(mixed.success).toBe(false);
if (!mixed.success) {
expect(JSON.stringify(mixed.error.issues)).toContain(
"cannot be combined",
);
}
const sole = searchRequestSchema.safeParse({
query: "retries",
categories: ["developer"],
});
expect(sole.success).toBe(true);
});
});
describe("executeSearch gov category", () => {
const govResult = {
url: "https://www.ecfr.gov/current/title-21/part-101",
title: "21 CFR Part 101",
description: "Food labeling",
position: 1,
category: "gov",
};
it("returns sole gov-category results in web without running SERP", async () => {
mocks.searchGovCategory.mockResolvedValue([govResult]);
const result = await executeSearch(
options([{ type: "gov" }]),
context,
logger,
);
expect(mocks.search).not.toHaveBeenCalled();
expect(mocks.searchDeveloperCategory).not.toHaveBeenCalled();
expect(mocks.searchGovCategory).toHaveBeenCalledWith(
{
query: "retries",
limit: 10,
teamId: "team-1",
timeout: 1_000,
zeroDataRetention: false,
},
logger,
);
expect(result.response).toEqual({ web: [govResult] });
expect(result.indexResultsCount).toBe(1);
expect(result.searchCredits).toBe(0);
});
});
describe("executeSearch gov routing", () => {
const govResult = {
url: "https://www.dol.gov/agencies/whd/fmla",
title: "FMLA",
description: "Family and Medical Leave Act",
position: 1,
};
const webResult = {
url: "https://example.com/",
title: "Example",
description: "",
};
it("serves a routed plain web search from the Government Index, skips the regular web search, and bills it as a web search", async () => {
mocks.search.mockResolvedValue({ web: [webResult] });
mocks.searchGovIfRouted.mockResolvedValue([govResult]);
const result = await executeSearch(options([]), context, logger);
expect(mocks.searchGovIfRouted).toHaveBeenCalledWith(
{
query: "retries",
limit: 10,
teamId: "team-1",
timeout: 1_000,
zeroDataRetention: false,
},
"job-1",
logger,
);
expect(mocks.searchGovCategory).not.toHaveBeenCalled();
expect(mocks.search).not.toHaveBeenCalled();
expect(result.response).toEqual({ web: [govResult] });
expect(result.searchCredits).toBe(2);
});
it("starts the regular web search only after the routing decision and serves it when the search is not routed", async () => {
mocks.search.mockResolvedValue({ web: [webResult] });
let webSearchCallsWhenRouting = -1;
mocks.searchGovIfRouted.mockImplementation(async () => {
webSearchCallsWhenRouting = mocks.search.mock.calls.length;
return null;
});
const result = await executeSearch(options([]), context, logger);
expect(webSearchCallsWhenRouting).toBe(0);
expect(mocks.search).toHaveBeenCalledTimes(1);
expect(result.response.web?.map(item => item.url)).toEqual([
"https://example.com/",
]);
});
it.each([
["a category", { categories: [{ type: "pdf" }] }],
["another source", { sources: [{ type: "web" }, { type: "news" }] }],
["included domains", { includeDomains: ["example.com"] }],
["excluded domains", { excludeDomains: ["example.com"] }],
["a time range", { tbs: "qdr:d" }],
["a result filter", { filter: "0" }],
["a country other than the US", { country: "gb" }],
["a site: operator", { query: "leave site:dol.gov" }],
[
"an operator the parser leaves in the text",
{ query: "fmla filetype:pdf" },
],
["an OR between terms", { query: "fmla OR overtime" }],
["a quoted phrase", { query: '"family leave" eligibility' }],
["a language other than English", { lang: "es" }],
["a location", { location: "Toronto, Ontario" }],
["a page larger than 10 results", { limit: 11 }],
["a blank query", { query: " " }],
])("never routes a search with %s", async (_case, overrides) => {
mocks.search.mockResolvedValue({ web: [] });
await executeSearch({ ...options([]), ...overrides }, context, logger);
expect(mocks.searchGovIfRouted).not.toHaveBeenCalled();
});
it.each([
["a zero data retention team", {}, { zeroDataRetention: true }],
["an enterprise zdr search", { enterprise: ["zdr"] }, {}],
["an enterprise anon search", { enterprise: ["anon"] }, {}],
])("never routes %s", async (_case, optionOverrides, contextOverrides) => {
mocks.search.mockResolvedValue({ web: [] });
await executeSearch(
{ ...options([]), ...optionOverrides },
{ ...context, ...contextOverrides } as any,
logger,
);
expect(mocks.searchGovIfRouted).not.toHaveBeenCalled();
expect(mocks.search).toHaveBeenCalledTimes(1);
});
it("never routes a US-only team", async () => {
mocks.search.mockResolvedValue({ web: [] });
await executeSearch(
options([]),
{ ...context, flags: { usOnly: true } } as any,
logger,
);
expect(mocks.searchGovIfRouted).not.toHaveBeenCalled();
});
});
describe("executeSearch query operators", () => {
const web = (url: string, title = "Result") => ({
url,
title,
description: "",
});
const news = (url: string, title: string) => ({ url, title, snippet: "" });
it("sends inurl: with site: as plain terms and enforces both on web results", async () => {
mocks.search.mockResolvedValue({
web: [
web(
"https://www.finance.example/2026/07/29/contoso-ctso-q4-earnings-report-2026.html",
),
web("https://www.finance.example/quotes/CTSO"),
web("https://www.stocks.example/stocks/xnas/ctso/earnings"),
web(
"https://www.finance.example/2026/04/29/contoso-ctso-q3-earnings-report-2026.html",
),
],
});
const result = await executeSearch(
{ ...options([]), query: "inurl:earnings Contoso site:finance.example" },
context,
logger,
);
expect(mocks.search).toHaveBeenCalledWith(
expect.objectContaining({
query: "earnings Contoso site:finance.example",
includeDomains: ["finance.example"],
}),
);
expect(result.response.web?.map(x => [x.position, x.url])).toEqual([
[
1,
"https://www.finance.example/2026/07/29/contoso-ctso-q4-earnings-report-2026.html",
],
[
2,
"https://www.finance.example/2026/04/29/contoso-ctso-q3-earnings-report-2026.html",
],
]);
});
it("bills nothing when the operators leave no results", async () => {
mocks.search.mockResolvedValue({
web: [web("https://www.finance.example/quotes/CTSO")],
});
const result = await executeSearch(
{ ...options([]), query: "inurl:earnings Contoso site:finance.example" },
context,
logger,
);
expect(result.response.web).toEqual([]);
expect(result.totalResultsCount).toBe(0);
expect(result.searchCredits).toBe(0);
});
it("applies both intitle: and site: to news results", async () => {
mocks.search.mockResolvedValue({
news: [
news(
"https://www.news.example/aktuell/wirtschaft/a.html",
"Acme: Quarterly results - News",
),
news(
"https://www.forum.example/r/insurance/comments/1/acme/",
"Acme denied claim",
),
news(
"https://www.news.example/agenturmeldungen/dpa/b.html",
"Local team wins again - News",
),
],
});
const result = await executeSearch(
{
...options([]),
query: '"Acme" intitle:Acme site:news.example',
sources: [{ type: "news" }],
tbs: "qdr:w",
},
context,
logger,
);
expect(mocks.search).toHaveBeenCalledWith(
expect.objectContaining({
query: '"Acme" Acme site:news.example',
includeDomains: ["news.example"],
tbs: "qdr:w",
}),
);
expect(result.response.news?.map(x => x.url)).toEqual([
"https://www.news.example/aktuell/wirtschaft/a.html",
]);
});
it("enforces site: alone on news results", async () => {
mocks.search.mockResolvedValue({
news: [
news("https://www.news.example/aktuell/a.html", "A"),
news("https://www.acmecare.example/en/blog.html", "B"),
],
});
const result = await executeSearch(
{
...options([]),
query: "Acme site:news.example",
sources: [{ type: "news" }],
},
context,
logger,
);
expect(mocks.search).toHaveBeenCalledWith(
expect.objectContaining({ query: "Acme site:news.example" }),
);
expect(result.response.news?.map(x => x.url)).toEqual([
"https://www.news.example/aktuell/a.html",
]);
});
it("enforces site: on image results", async () => {
mocks.search.mockResolvedValue({
images: [
{
url: "https://www.news.example/a.html",
title: "A",
imageUrl: "https://cdn.example/a.jpg",
},
{
url: "https://other.example/b.html",
title: "B",
imageUrl: "https://cdn.example/b.jpg",
},
],
});
const result = await executeSearch(
{
...options([]),
query: "Acme site:news.example",
sources: [{ type: "images" }],
},
context,
logger,
);
expect(result.response.images?.map(x => [x.position, x.url])).toEqual([
[1, "https://www.news.example/a.html"],
]);
});
it("enforces site: on category index results", async () => {
mocks.searchDeveloperCategory.mockResolvedValue([
developerResult,
{ ...developerResult, url: "https://docs.example/retries", position: 2 },
]);
const result = await executeSearch(
{
...options([{ type: "developer" }]),
query: "retries site:docs.example",
},
context,
logger,
);
expect(result.response.web?.map(x => [x.position, x.url])).toEqual([
[1, "https://docs.example/retries"],
]);
expect(result.indexResultsCount).toBe(1);
});
it("asks the provider for more results when it enforces inurl: or intitle: itself", async () => {
mocks.search.mockResolvedValue({ web: [] });
await executeSearch(
{ ...options([]), query: "inurl:earnings Contoso site:finance.example" },
context,
logger,
);
expect(mocks.search).toHaveBeenCalledWith(
expect.objectContaining({ num_results: 50 }),
);
});
it("forwards a custom date range tbs to the web provider unchanged", async () => {
mocks.search.mockResolvedValue({ web: [] });
const tbs = "cdr:1,cd_min:1/1/2024,cd_max:1/31/2024";
await executeSearch(
{ ...options([]), query: "Contoso earnings site:finance.example", tbs },
context,
logger,
);
expect(mocks.search).toHaveBeenCalledWith(
expect.objectContaining({ tbs, type: ["web"] }),
);
});
});
describe("executeSearch skill cards", () => {
const card = {
id: "official/search",
name: "Search",
description: "Find records",
source: "official" as const,
similarity: 0.5,
};
it("leaves skills off when the source was not requested", async () => {
mocks.search.mockResolvedValue({ web: [developerResult] });
const result = await executeSearch(options([]), context, logger);
expect(mocks.discoverSkills).not.toHaveBeenCalled();
expect(result.response).not.toHaveProperty("skills");
expect(result.searchCredits).toBe(2);
});
it("starts skill discovery before the web search and maps the cards", async () => {
const order: string[] = [];
let releaseSkills: (found: {
skills: unknown[];
succeeded: boolean;
}) => void = () => {};
mocks.discoverSkills.mockImplementation(
() =>
new Promise(resolve => {
order.push("skills");
releaseSkills = resolve;
}),
);
mocks.search.mockImplementation(async () => {
order.push("web");
releaseSkills({ skills: [card], succeeded: true });
return { web: [developerResult] };
});
const result = await executeSearch(
{
...options([]),
sources: [{ type: "web" }, { type: "skills" }],
},
context,
logger,
);
expect(order).toEqual(["skills", "web"]);
expect(mocks.discoverSkills).toHaveBeenCalledWith(
expect.objectContaining({
teamId: "team-1",
query: "retries",
timeoutMs: 1000,
usOnly: false,
}),
logger,
);
expect(mocks.search).toHaveBeenCalledWith(
expect.objectContaining({ type: ["web"] }),
);
expect(result.response.skills).toEqual([card]);
expect(result.skillsDiscovered).toBe(true);
expect(result.response.web).toHaveLength(1);
expect(result.searchCredits).toBe(2);
});
it("keeps web results and returns no cards when skill discovery fails", async () => {
mocks.search.mockResolvedValue({ web: [developerResult] });
mocks.discoverSkills.mockRejectedValue(new Error("timed out"));
const result = await executeSearch(
{
...options([]),
sources: [{ type: "web" }, { type: "skills" }],
},
context,
logger,
);
expect(result.response.web).toHaveLength(1);
expect(result.response.skills).toEqual([]);
expect(result.skillsDiscovered).toBe(false);
expect(result.searchCredits).toBe(2);
});
it("does not run or bill web search for a skills-only request", async () => {
mocks.discoverSkills.mockResolvedValue({
skills: [card],
succeeded: true,
});
const result = await executeSearch(
{ ...options([]), sources: [{ type: "skills" }] },
context,
logger,
);
expect(mocks.search).not.toHaveBeenCalled();
expect(result.response.skills).toEqual([card]);
expect(result.skillsDiscovered).toBe(true);
expect(result.searchCredits).toBe(0);
expect(result.totalCredits).toBe(0);
});
it.each([
["zero data retention", { zeroDataRetention: true }, {}],
["zdr enterprise mode", {}, { enterprise: ["zdr"] }],
["anon enterprise mode", {}, { enterprise: ["anon"] }],
])(
"skips skill discovery under %s",
async (_label, contextOverrides, optionOverrides) => {
mocks.search.mockResolvedValue({ web: [developerResult] });
const result = await executeSearch(
{
...options([]),
sources: [{ type: "web" }, { type: "skills" }],
...optionOverrides,
},
{ ...context, ...contextOverrides },
logger,
);
expect(mocks.discoverSkills).not.toHaveBeenCalled();
expect(result.response).not.toHaveProperty("skills");
expect(result.skillsDiscovered).toBe(false);
},
);
it("skips skill discovery when the query is empty", async () => {
const result = await executeSearch(
{
...options([]),
query: " ",
sources: [{ type: "skills" }],
},
context,
logger,
);
expect(mocks.discoverSkills).not.toHaveBeenCalled();
expect(mocks.search).not.toHaveBeenCalled();
expect(result.response).not.toHaveProperty("skills");
expect(result.skillsDiscovered).toBe(false);
});
it("forwards a US-only team to skill discovery", async () => {
mocks.discoverSkills.mockResolvedValue({ skills: [], succeeded: true });
await executeSearch(
{ ...options([]), sources: [{ type: "skills" }] },
{ ...context, flags: { usOnly: true } },
logger,
);
expect(mocks.discoverSkills).toHaveBeenCalledWith(
expect.objectContaining({ usOnly: true }),
logger,
);
});
});