Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
ts 1,242 lines 47.9 KB
Raw
1 import { describe, expect, test } from 'bun:test';
2 import { existsSync, readFileSync } from 'node:fs';
3 import { join } from 'node:path';
4 import type { AlgoliaDocsRecord } from '@/lib/search-index';
5 import {
6 algoliaFacetFilters,
7 filterLegacyReferenceRecords,
8 knowledgeSearchResultFromRecord,
9 plainKnowledgeExcerpt,
10 searchKnowledgeRecords,
11 } from '@/lib/knowledge/search';
12 import { createKnowledgeSearchHandler, GET } from '@/app/api/knowledge-search/route';
13 import { searchPublicKnowledge } from '@/lib/knowledge/search-service';
14 import * as searchServiceModule from '@/lib/knowledge/search-service';
15 import {
16 isStrongLexicalCandidate,
17 publicKbCandidateFromAlgolia,
18 publicKnowledgeCandidateFromSearchRecord,
19 } from '@/lib/knowledge/hybrid-search';
20 import type { KnowledgeSourceType } from '@/lib/knowledge/types';
21
22 const REPO_ROOT = join(import.meta.dir, '../../..');
23 const UNIFIED_SEARCH_ENDPOINT = 'https://docs.composio.dev/api/knowledge-search?q=<question>';
24 const PUBLIC_COMPOSIO_SKILL_SOURCES = [
25 join(REPO_ROOT, 'skills/composio/SKILL.md'),
26 join(REPO_ROOT, 'skills/composio/references/for-you.md'),
27 ];
28 const SEPARATE_SUPPORT_SKILL = join(REPO_ROOT, 'skills/composio-support');
29 const PRIMARY_SOURCES = /\bcurrent\b[\s\S]{0,120}\b(?:documentation|docs)\b[\s\S]{0,160}\bCLI\b[\s\S]{0,80}\btool schemas\b[\s\S]{0,100}\bprimary\b/i;
30 const PUBLIC_RESULT_BREADTH = /\bcanonical docs\b[\s\S]{0,80}\bKB\b[\s\S]{0,80}\btoolkit\b[\s\S]{0,80}\bexample\b[\s\S]{0,80}\breference pages\b/i;
31 const NO_LIVE_STATE_INFERENCE = /\b(?:do not|does not|cannot|never)\b[\s\S]{0,120}\b(?:infer|establish)\b[\s\S]{0,120}\blive state\b/i;
32
33 function record(input: {
34 id: string;
35 title: string;
36 sourceType: KnowledgeSourceType;
37 pageRank: number;
38 description?: string;
39 content?: string;
40 keywords?: string[];
41 }): AlgoliaDocsRecord {
42 const canonicalUrl = `/${input.sourceType}/${input.id}`;
43 return {
44 objectID: input.id,
45 title: input.title,
46 description: input.description ?? input.title,
47 breadcrumbs: ['Knowledge'],
48 url: canonicalUrl,
49 page_id: canonicalUrl,
50 content: input.content ?? input.description ?? input.title,
51 keywords: input.keywords ?? [],
52 slug: input.id,
53 headings: [],
54 type: input.sourceType,
55 lang: 'en',
56 page_rank: input.pageRank,
57 toolkit_popularity: 0,
58 section_rank: 120,
59 position: 0,
60 depth: 0,
61 source_type: input.sourceType,
62 canonical_url: canonicalUrl,
63 product_areas: input.sourceType === 'reference' || input.sourceType === 'legacy'
64 ? ['sdk-api-and-mcp']
65 : [],
66 toolkit_slugs: [],
67 intents: [],
68 last_verified_at: input.sourceType === 'kb' ? '2026-07-22' : null,
69 };
70 }
71
72 const closeMatchRecords = [
73 record({ id: 'docs', title: 'Connected account setup', sourceType: 'docs', pageRank: 2_000 }),
74 record({ id: 'kb', title: 'Connected account setup', sourceType: 'kb', pageRank: 1_900 }),
75 record({ id: 'oauth', title: 'Connected account setup', sourceType: 'oauth-guide', pageRank: 1_700 }),
76 record({ id: 'toolkit', title: 'Connected account setup', sourceType: 'toolkit', pageRank: 1_500 }),
77 record({ id: 'example', title: 'Connected account setup', sourceType: 'example', pageRank: 1_300 }),
78 record({ id: 'reference', title: 'Connected account setup', sourceType: 'reference', pageRank: 700 }),
79 record({ id: 'changelog', title: 'Connected account setup', sourceType: 'changelog', pageRank: 350 }),
80 record({ id: 'legacy', title: 'Connected account setup', sourceType: 'legacy', pageRank: 25 }),
81 ];
82
83 describe('public Composio unified support routing', () => {
84 test('uses unified public search only after primary sources and grounds answers in public evidence', () => {
85 expect(existsSync(SEPARATE_SUPPORT_SKILL)).toBe(false);
86
87 for (const sourceFile of PUBLIC_COMPOSIO_SKILL_SOURCES) {
88 const source = readFileSync(sourceFile, 'utf8');
89 const primarySourcesIndex = source.search(PRIMARY_SOURCES);
90 const unifiedSearchIndex = source.indexOf(UNIFIED_SEARCH_ENDPOINT);
91
92 expect(source).toContain(UNIFIED_SEARCH_ENDPOINT);
93 expect(source).not.toContain('filter=kb');
94 expect(source).not.toMatch(/\bcomposio-support\b/i);
95 expect(primarySourcesIndex).toBeGreaterThanOrEqual(0);
96 expect(primarySourcesIndex).toBeLessThan(unifiedSearchIndex);
97 expect(source).toMatch(PUBLIC_RESULT_BREADTH);
98 expect(source).toMatch(/\breturned evidence\b/i);
99 expect(source).toMatch(NO_LIVE_STATE_INFERENCE);
100 expect(source).toMatch(/\baccount\b/i);
101 expect(source).toMatch(/\bconnection\b/i);
102 expect(source).toMatch(/\btool call\b/i);
103 }
104 });
105 });
106
107 describe('plain knowledge excerpts', () => {
108 test('removes an unterminated HTML opener instead of returning active markup', () => {
109 expect(plainKnowledgeExcerpt('Safe text <script alert(1)')).toBe('Safe text');
110 });
111
112 test('removes entity-encoded markup before returning plain text', () => {
113 expect(plainKnowledgeExcerpt('&lt;script&gt;alert(1)&lt;/script&gt; trailing'))
114 .toBe('alert(1) trailing');
115 });
116
117 test('preserves comparison prose and angle-bracket placeholders', () => {
118 expect(plainKnowledgeExcerpt('Retry if latency < 500ms and depth > 2.'))
119 .toBe('Retry if latency < 500ms and depth > 2.');
120 expect(plainKnowledgeExcerpt('Send x-api-key: <key> and retry on 429.'))
121 .toBe('Send x-api-key: <key> and retry on 429.');
122 });
123
124 test('removes legacy and attribute-bearing HTML without consuming placeholders', () => {
125 expect(plainKnowledgeExcerpt('<image src=x onerror=alert(1)> caption')).toBe('caption');
126 expect(plainKnowledgeExcerpt('&lt;marquee onstart=alert(1)&gt;notice&lt;/marquee&gt; after'))
127 .toBe('notice after');
128 expect(plainKnowledgeExcerpt('<custom-element data-state=active>value</custom-element> tail'))
129 .toBe('value tail');
130 expect(plainKnowledgeExcerpt('Use <external-user-id> and <API key> placeholders.'))
131 .toBe('Use <external-user-id> and <API key> placeholders.');
132 });
133
134 test('sanitizes the record fallback excerpt as well as highlighted excerpts', () => {
135 const guide = record({
136 id: 'safe-fallback',
137 title: 'Safe fallback',
138 sourceType: 'kb',
139 pageRank: 1_900,
140 description: '&lt;em&gt;Reconnect&lt;/em&gt; the account.',
141 });
142
143 expect(knowledgeSearchResultFromRecord(guide).excerpt).toBe('Reconnect the account.');
144 });
145 });
146
147 describe('unified knowledge search', () => {
148 test('normalizes pre-migration Algolia hits across trustworthy type and path mappings', () => {
149 const normalizeAlgoliaSearchHits = (
150 searchServiceModule as {
151 normalizeAlgoliaSearchHits?: (hits: unknown[]) => AlgoliaDocsRecord[];
152 }
153 ).normalizeAlgoliaSearchHits;
154 expect(typeof normalizeAlgoliaSearchHits).toBe('function');
155 if (!normalizeAlgoliaSearchHits) return;
156
157 const normalized = normalizeAlgoliaSearchHits([
158 {
159 objectID: 'legacy-docs',
160 title: 'Configure sessions',
161 description: 'Configure a session.',
162 content: 'Configure a session with the SDK.',
163 url: '/docs/configuring-sessions#overview',
164 page_id: '/docs/configuring-sessions',
165 type: 'docs',
166 },
167 {
168 objectID: 'legacy-toolkit',
169 title: 'GitHub',
170 content: 'GitHub tools.',
171 url: '/toolkits/github',
172 page_id: '/toolkits/github',
173 type: 'toolkits',
174 },
175 {
176 objectID: 'legacy-reference',
177 title: 'List tools',
178 content: 'List tools reference.',
179 url: '/reference/api-reference/tools/getTools',
180 page_id: '/reference/api-reference/tools/getTools',
181 type: 'api-reference',
182 },
183 {
184 objectID: 'path-mapped-toolkit',
185 title: 'Slack',
186 content: 'Slack tools.',
187 url: '/toolkits/slack',
188 page_id: '/toolkits/slack',
189 type: 'unknown',
190 },
191 {
192 objectID: 'stale-toolkit',
193 title: 'Removed toolkit',
194 content: 'This toolkit was removed from the current public catalog.',
195 url: '/toolkits/removed_toolkit',
196 type: 'toolkits',
197 },
198 {
199 objectID: 'hidden-auth-operation',
200 title: 'Get current session',
201 content: 'Internal session lookup.',
202 url: '/reference/api-reference/authentication/getAuthSessionInfo',
203 page_id: '/reference/api-reference/authentication/getAuthSessionInfo',
204 type: 'api-reference',
205 },
206 ]);
207
208 expect(normalized.map((record) => ({
209 objectID: record.objectID,
210 sourceType: record.source_type,
211 canonicalUrl: record.canonical_url,
212 }))).toEqual([
213 {
214 objectID: 'legacy-docs',
215 sourceType: 'docs',
216 canonicalUrl: '/docs/configuring-sessions',
217 },
218 {
219 objectID: 'legacy-toolkit',
220 sourceType: 'toolkit',
221 canonicalUrl: '/toolkits/github',
222 },
223 {
224 objectID: 'legacy-reference',
225 sourceType: 'reference',
226 canonicalUrl: '/reference/api-reference/tools/getTools',
227 },
228 {
229 objectID: 'path-mapped-toolkit',
230 sourceType: 'toolkit',
231 canonicalUrl: '/toolkits/slack',
232 },
233 ]);
234 });
235
236 test('accepts an empty Algolia result but rejects a non-empty all-invalid result', () => {
237 const normalizeAlgoliaSearchHits = (
238 searchServiceModule as {
239 normalizeAlgoliaSearchHits?: (hits: unknown[]) => AlgoliaDocsRecord[];
240 }
241 ).normalizeAlgoliaSearchHits;
242 expect(typeof normalizeAlgoliaSearchHits).toBe('function');
243 if (!normalizeAlgoliaSearchHits) return;
244
245 expect(normalizeAlgoliaSearchHits([])).toEqual([]);
246 expect(() => normalizeAlgoliaSearchHits([
247 { objectID: 'missing-route', title: 'No public route', type: 'docs' },
248 { objectID: 'unclassified', title: 'Unknown source', url: '/unknown', type: 'unknown' },
249 ])).toThrow('keyword-request-failed');
250 });
251
252 test('preserves every public source type in keyword candidates and reserves strong lexical matches for exact identities', () => {
253 const calendly = publicKnowledgeCandidateFromSearchRecord(record({
254 id: 'calendly',
255 title: 'Calendly actions',
256 sourceType: 'toolkit',
257 pageRank: 1_500,
258 keywords: ['CALENDLY_POST_INVITEE'],
259 }));
260 const claudeDocs = publicKnowledgeCandidateFromSearchRecord(record({
261 id: 'claude-connect',
262 title: 'Connect Claude',
263 sourceType: 'docs',
264 pageRank: 2_000,
265 content: 'Learn how do I connect Claude to Composio from this guide.',
266 }));
267 const reference = publicKnowledgeCandidateFromSearchRecord(record({
268 id: 'reference', title: 'API reference', sourceType: 'reference', pageRank: 700,
269 }));
270 const exactTitle = publicKnowledgeCandidateFromSearchRecord(record({
271 id: 'exact-title', title: 'Create Connected Account', sourceType: 'docs', pageRank: 2_000,
272 }));
273 const toolSlugRecord = record({
274 id: 'tool-slug', title: 'Calendly actions', sourceType: 'toolkit', pageRank: 1_500,
275 });
276 toolSlugRecord.tool_slugs = ['CALENDLY_POST_INVITEE'];
277 const toolSlug = publicKnowledgeCandidateFromSearchRecord(toolSlugRecord);
278
279 expect(calendly).toMatchObject({ sourceType: 'toolkit', sourceLabel: 'Toolkit' });
280 expect(claudeDocs).toMatchObject({ sourceType: 'docs', sourceLabel: 'Docs' });
281 expect(reference).toMatchObject({ sourceType: 'reference', sourceLabel: 'Reference' });
282 expect(isStrongLexicalCandidate(exactTitle, ' create connected account ')).toBe(true);
283 expect(isStrongLexicalCandidate(calendly, 'CALENDLY_POST_INVITEE')).toBe(true);
284 expect(isStrongLexicalCandidate(calendly, 'calendly')).toBe(true);
285 expect(isStrongLexicalCandidate(toolSlug, 'CALENDLY_POST_INVITEE')).toBe(true);
286 expect(isStrongLexicalCandidate(claudeDocs, 'how do I connect claude')).toBe(false);
287 });
288
289 test('uses source rank only to break equally relevant close matches', () => {
290 const result = searchKnowledgeRecords(closeMatchRecords, {
291 query: 'connected account setup',
292 filter: 'all',
293 limit: 20,
294 });
295
296 expect(result.results.map((item) => item.sourceType)).toEqual([
297 'docs', 'kb', 'oauth-guide', 'toolkit', 'example', 'reference', 'changelog',
298 ]);
299 });
300
301 test('lets exact titles, action slugs, and error phrases beat page rank', () => {
302 const records = [
303 record({
304 id: 'generic-doc',
305 title: 'Troubleshoot toolkit actions',
306 sourceType: 'docs',
307 pageRank: 2_400,
308 content: 'Calendly and Odoo troubleshooting overview.',
309 }),
310 record({
311 id: 'calendly',
312 title: 'Use CALENDLY_POST_INVITEE for invitee creation',
313 sourceType: 'kb',
314 pageRank: 1_900,
315 keywords: ['CALENDLY_POST_INVITEE'],
316 }),
317 record({
318 id: 'odoo',
319 title: 'Inspect Odoo JSON-RPC errors inside HTTP 200 responses',
320 sourceType: 'kb',
321 pageRank: 1_900,
322 content: 'The response has HTTP 200 but contains an Odoo JSON-RPC error object.',
323 }),
324 record({
325 id: 'exact-reference',
326 title: 'Create a connected account',
327 sourceType: 'reference',
328 pageRank: 700,
329 }),
330 ];
331
332 expect(searchKnowledgeRecords(records, {
333 query: 'CALENDLY_POST_INVITEE', filter: 'all', limit: 10,
334 }).results[0]?.objectID).toBe('calendly');
335 expect(searchKnowledgeRecords(records, {
336 query: 'HTTP 200 but contains an Odoo JSON-RPC error', filter: 'all', limit: 10,
337 }).results[0]?.objectID).toBe('odoo');
338 expect(searchKnowledgeRecords(records, {
339 query: 'Create a connected account', filter: 'all', limit: 10,
340 }).results[0]?.objectID).toBe('exact-reference');
341 });
342
343 test('maps every source filter and keeps examples and changelog in All', () => {
344 expect(algoliaFacetFilters('all')).toEqual([]);
345 expect(algoliaFacetFilters('docs')).toEqual([['source_type:docs']]);
346 expect(algoliaFacetFilters('kb')).toEqual([['source_type:kb']]);
347 expect(algoliaFacetFilters('oauth')).toEqual([['source_type:oauth-guide']]);
348 expect(algoliaFacetFilters('toolkit')).toEqual([['source_type:toolkit']]);
349 expect(algoliaFacetFilters('toolkits')).toEqual([['source_type:toolkit']]);
350 expect(algoliaFacetFilters('reference')).toEqual([
351 ['source_type:reference', 'source_type:legacy'],
352 ]);
353
354 const all = searchKnowledgeRecords(closeMatchRecords, {
355 query: 'connected', filter: 'all', limit: 20,
356 });
357 expect(all.results.some((item) => item.sourceType === 'example')).toBe(true);
358 expect(all.results.some((item) => item.sourceType === 'changelog')).toBe(true);
359 expect(searchKnowledgeRecords(closeMatchRecords, {
360 query: 'connected', filter: 'oauth', limit: 20,
361 }).results.every((item) => item.sourceType === 'oauth-guide')).toBe(true);
362 });
363
364 test('hides legacy reference unless it is the only exact match', () => {
365 const records = [
366 record({
367 id: 'current-auth', title: 'Authentication reference', sourceType: 'reference', pageRank: 700,
368 }),
369 record({
370 id: 'legacy-token', title: 'Old token endpoint foo_unique', sourceType: 'legacy', pageRank: 25,
371 }),
372 ];
373
374 expect(searchKnowledgeRecords(records, {
375 query: 'reference', filter: 'reference', limit: 20,
376 }).results.map((item) => item.objectID)).toEqual(['current-auth']);
377 expect(searchKnowledgeRecords(records, {
378 query: 'Old token endpoint foo_unique', filter: 'reference', limit: 20,
379 }).results.map((item) => item.objectID)).toEqual(['legacy-token']);
380
381 const currentExact = record({
382 id: 'current-exact', title: 'Create connected account', sourceType: 'reference', pageRank: 700,
383 });
384 const legacyExact = record({
385 id: 'legacy-exact', title: 'Create connected account', sourceType: 'legacy', pageRank: 25,
386 });
387 expect(filterLegacyReferenceRecords(
388 [legacyExact, currentExact],
389 'Create connected account',
390 'reference',
391 ).map((item) => item.objectID)).toEqual(['current-exact']);
392 expect(searchKnowledgeRecords([legacyExact, currentExact], {
393 query: 'Create connected account', filter: 'reference', limit: 20,
394 }).results.map((item) => item.objectID)).toEqual(['current-exact']);
395 });
396
397 test('returns no documents for an empty query', () => {
398 expect(searchKnowledgeRecords(closeMatchRecords, {
399 query: ' ', filter: 'all', limit: 20,
400 })).toEqual({ query: '', filter: 'all', results: [], total: 0 });
401 });
402
403 test('does not let incidental stop-word matches outrank a meaningful partial match', () => {
404 const records = [
405 record({
406 id: 'generic',
407 title: 'Audit data handling',
408 sourceType: 'kb',
409 pageRank: 2_400,
410 content: 'The audit row is retained when data storage is disabled.',
411 }),
412 record({
413 id: 'calendar',
414 title: 'Google Calendar troubleshooting',
415 sourceType: 'kb',
416 pageRank: 1_900,
417 content: 'Use primary when the signed-in user alias fails as a calendar ID.',
418 }),
419 ];
420
421 expect(searchKnowledgeRecords(records, {
422 query: 'Why does the signed-in user alias fail when I pass it as a calendar id?',
423 filter: 'kb',
424 limit: 20,
425 }).results[0]?.objectID).toBe('calendar');
426 expect(searchKnowledgeRecords(records, {
427 query: 'the and when does it',
428 filter: 'kb',
429 limit: 20,
430 }).results).toEqual([]);
431 });
432
433 test('does not repeat the source badge as the first breadcrumb', () => {
434 const toolkit = record({
435 id: 'github', title: 'GitHub', sourceType: 'toolkit', pageRank: 1_500,
436 });
437 toolkit.breadcrumbs = ['Toolkit', 'Authentication'];
438 expect(knowledgeSearchResultFromRecord(toolkit).breadcrumbs).toEqual(['Authentication']);
439 });
440
441 test('returns plain-text excerpts from Algolia highlight markup', () => {
442 const docs = record({
443 id: 'auth', title: 'Authentication', sourceType: 'docs', pageRank: 2_000,
444 });
445 expect(knowledgeSearchResultFromRecord(
446 docs,
447 'Use &lt;managed&gt; <mark>OAuth</mark> &amp; API keys.',
448 ).excerpt).toBe('Use <managed> OAuth & API keys.');
449 });
450
451 test('removes markdown decoration from result excerpts', () => {
452 const guide = record({
453 id: 'oauth', title: 'OAuth setup', sourceType: 'kb', pageRank: 1_900,
454 });
455
456 expect(knowledgeSearchResultFromRecord(
457 guide,
458 '# Create an auth config\n\nUse **custom OAuth** credentials from `GitHub`.',
459 ).excerpt).toBe('Create an auth config Use custom OAuth credentials from GitHub.');
460 });
461
462 test('rejects invalid API filters', async () => {
463 const response = await GET(new Request(
464 'http://localhost/api/knowledge-search?q=github&filter=invalid',
465 ));
466 expect(response.status).toBe(400);
467 });
468
469 test('returns fused public KB results with provider-neutral retrieval metadata', async () => {
470 const github = publicKbCandidateFromAlgolia(record({
471 id: 'github-answer',
472 title: 'Reconnect GitHub',
473 sourceType: 'kb',
474 pageRank: 1_900,
475 }));
476 const oauth = publicKbCandidateFromAlgolia(record({
477 id: 'oauth-answer',
478 title: 'Refresh OAuth access',
479 sourceType: 'kb',
480 pageRank: 1_900,
481 }));
482 const handler = createKnowledgeSearchHandler({
483 hybridEnabled: () => true,
484 searchKeywordCandidates: async () => ({ candidates: [github, oauth] }),
485 searchSemanticCandidates: async () => [oauth, github],
486 });
487
488 const response = await handler(new Request(
489 'http://localhost/api/knowledge-search?q=revoked+access&filter=kb',
490 ));
491 const body = await response.json() as {
492 mode: string;
493 results: Array<{ objectID: string; sourceType: string }>;
494 };
495
496 expect(response.status).toBe(200);
497 expect(body.mode).toBe('hybrid');
498 expect(body.results.map(result => result.objectID)).toEqual(['github-answer', 'oauth-answer']);
499 expect(body.results.every(result => result.sourceType === 'kb')).toBe(true);
500 });
501
502 test('removes markdown decoration from hybrid result excerpts', async () => {
503 const github = publicKbCandidateFromAlgolia(record({
504 id: 'github-oauth',
505 title: 'Configure GitHub OAuth',
506 sourceType: 'kb',
507 pageRank: 1_900,
508 content: '# Create an auth config\n\nUse **custom OAuth** credentials from `GitHub`.',
509 }));
510 const handler = createKnowledgeSearchHandler({
511 hybridEnabled: () => true,
512 searchKeywordCandidates: async () => ({ candidates: [github] }),
513 searchSemanticCandidates: async () => [github],
514 });
515
516 const response = await handler(new Request(
517 'http://localhost/api/knowledge-search?q=github+oauth&filter=kb',
518 ));
519 const body = await response.json() as {
520 results: Array<{ excerpt: string }>;
521 };
522
523 expect(body.results[0]?.excerpt).toBe(
524 'Create an auth config Use custom OAuth credentials from GitHub.',
525 );
526 });
527
528 test('abstains when hybrid retrieval has neither semantic nor exact keyword evidence', async () => {
529 const incidentalKeywordMatch = publicKbCandidateFromAlgolia(record({
530 id: 'incidental',
531 title: 'Operational health checks',
532 sourceType: 'kb',
533 pageRank: 1_900,
534 content: 'A generic page sharing only incidental words with the query.',
535 }));
536 const handler = createKnowledgeSearchHandler({
537 hybridEnabled: () => true,
538 searchKeywordCandidates: async () => ({ candidates: [incidentalKeywordMatch] }),
539 searchSemanticCandidates: async () => [],
540 });
541
542 const response = await handler(new Request(
543 'http://localhost/api/knowledge-search?q=unrelated+request&filter=kb',
544 ));
545 const body = await response.json() as {
546 strongMatch?: boolean;
547 total: number;
548 results: unknown[];
549 };
550
551 expect(response.status).toBe(200);
552 expect(body.strongMatch).toBe(false);
553 expect(body.total).toBe(0);
554 expect(body.results).toEqual([]);
555 });
556
557 test('keeps an exact keyword identity when semantic retrieval abstains', async () => {
558 const exactKeywordMatch = publicKbCandidateFromAlgolia(record({
559 id: 'exact-identifier',
560 title: 'Action troubleshooting',
561 sourceType: 'kb',
562 pageRank: 1_900,
563 keywords: ['EXACT_ACTION_IDENTIFIER'],
564 }));
565 const handler = createKnowledgeSearchHandler({
566 hybridEnabled: () => true,
567 searchKeywordCandidates: async () => ({ candidates: [exactKeywordMatch] }),
568 searchSemanticCandidates: async () => [],
569 });
570
571 const response = await handler(new Request(
572 'http://localhost/api/knowledge-search?q=EXACT_ACTION_IDENTIFIER&filter=kb',
573 ));
574 const body = await response.json() as {
575 strongMatch?: boolean;
576 results: Array<{ objectID: string }>;
577 };
578
579 expect(body.strongMatch).toBe(true);
580 expect(body.results.map(result => result.objectID)).toEqual(['exact-identifier']);
581 });
582
583 test('allows a cold semantic request to finish without degrading', async () => {
584 const answer = publicKbCandidateFromAlgolia(record({
585 id: 'cold-answer',
586 title: 'Cold-start answer',
587 sourceType: 'kb',
588 pageRank: 1_900,
589 }));
590 const handler = createKnowledgeSearchHandler({
591 hybridEnabled: () => true,
592 searchKeywordCandidates: async () => ({ candidates: [answer] }),
593 searchSemanticCandidates: async () => {
594 await new Promise(resolve => setTimeout(resolve, 2_200));
595 return [answer];
596 },
597 });
598
599 const response = await handler(new Request(
600 'http://localhost/api/knowledge-search?q=why+is+cold+startup+slow&filter=kb',
601 ));
602 const body = await response.json() as { mode: string };
603
604 expect(body.mode).toBe('hybrid');
605 });
606
607 test('uses either available retriever without exposing its peer failure', async () => {
608 const answer = publicKbCandidateFromAlgolia(record({
609 id: 'answer',
610 title: 'Known answer',
611 sourceType: 'kb',
612 pageRank: 1_900,
613 }));
614 const semanticFailure = createKnowledgeSearchHandler({
615 hybridEnabled: () => true,
616 searchKeywordCandidates: async () => ({ candidates: [answer] }),
617 searchSemanticCandidates: async () => {
618 throw new Error('semantic-request-failed');
619 },
620 });
621 const keywordFailure = createKnowledgeSearchHandler({
622 hybridEnabled: () => true,
623 searchKeywordCandidates: async () => {
624 throw new Error('keyword-request-failed');
625 },
626 searchSemanticCandidates: async () => [answer],
627 });
628 const bothFail = createKnowledgeSearchHandler({
629 hybridEnabled: () => true,
630 searchKeywordCandidates: async () => {
631 throw new Error('keyword-request-failed');
632 },
633 searchSemanticCandidates: async () => {
634 throw new Error('semantic-request-failed');
635 },
636 });
637 const request = () => new Request(
638 'http://localhost/api/knowledge-search?q=known+answer&filter=kb',
639 );
640
641 const keywordResponse = await (await semanticFailure(request())).json() as Record<string, unknown>;
642 expect(keywordResponse).toMatchObject({ mode: 'keyword' });
643 expect(keywordResponse).not.toHaveProperty('degradedReason');
644
645 const semanticResponse = await (await keywordFailure(request())).json() as Record<string, unknown>;
646 expect(semanticResponse).toMatchObject({ mode: 'semantic' });
647 expect(semanticResponse).not.toHaveProperty('degradedReason');
648 expect((await bothFail(request())).status).toBe(503);
649 });
650
651 test('configures normalized search facets and retrieval fields', () => {
652 const syncSource = readFileSync(
653 join(import.meta.dir, '../../scripts/sync-algolia-search.ts'),
654 'utf8',
655 );
656 const retrievalFields = syncSource.slice(
657 syncSource.indexOf('attributesToRetrieve:'),
658 syncSource.indexOf('searchableAttributes:'),
659 );
660
661
662
663 for (const field of [
664 'source_type', 'canonical_url', 'product_areas', 'toolkit_slugs', 'intents',
665 'last_verified_at', 'keywords', 'slug', 'tool_names', 'tool_slugs',
666 ]) {
667 expect(retrievalFields).toContain(`'${field}'`);
668 }
669 expect(syncSource).toContain("customRanking: [\n 'desc(page_rank)',\n 'desc(section_rank)',\n ]");
670 });
671 });
672
673 describe('public knowledge search service', () => {
674 test('falls back to the full local corpus when every Algolia hit is invalid', async () => {
675 const normalizeAlgoliaSearchHits = (
676 searchServiceModule as {
677 normalizeAlgoliaSearchHits?: (hits: unknown[]) => AlgoliaDocsRecord[];
678 }
679 ).normalizeAlgoliaSearchHits;
680 expect(typeof normalizeAlgoliaSearchHits).toBe('function');
681 if (!normalizeAlgoliaSearchHits) return;
682
683 const toolkit = publicKnowledgeCandidateFromSearchRecord(record({
684 id: 'calendar-toolkit', title: 'Calendar toolkit', sourceType: 'toolkit', pageRank: 1_500,
685 }));
686 const reference = publicKnowledgeCandidateFromSearchRecord(record({
687 id: 'sessions-reference', title: 'Sessions reference', sourceType: 'reference', pageRank: 700,
688 }));
689
690 const execution = await searchPublicKnowledge({
691 query: 'sessions', filter: 'all', headers: new Headers(),
692 }, {
693 hybridEnabled: () => false,
694 searchKeywordCandidates: async () => ({
695 candidates: normalizeAlgoliaSearchHits([
696 { objectID: 'invalid', title: 'Invalid', type: 'unknown', url: '/unknown' },
697 ]).map(publicKnowledgeCandidateFromSearchRecord),
698 }),
699 searchSemanticCandidates: async () => [],
700 searchLocalCandidates: async () => [toolkit, reference],
701 previewOverlayEnabled: () => false,
702 });
703
704 expect(execution.status).toBe(200);
705 expect(execution.response).toMatchObject({
706 mode: 'keyword',
707 results: [
708 { objectID: 'calendar-toolkit', sourceType: 'toolkit' },
709 { objectID: 'sessions-reference', sourceType: 'reference' },
710 ],
711 });
712 });
713
714 test('uses normalized legacy canonical URLs for preview replacement only in preview', async () => {
715 const normalizeAlgoliaSearchHits = (
716 searchServiceModule as {
717 normalizeAlgoliaSearchHits?: (hits: unknown[]) => AlgoliaDocsRecord[];
718 }
719 ).normalizeAlgoliaSearchHits;
720 expect(typeof normalizeAlgoliaSearchHits).toBe('function');
721 if (!normalizeAlgoliaSearchHits) return;
722
723 const [legacyRecord] = normalizeAlgoliaSearchHits([{
724 objectID: 'legacy-doc',
725 title: 'Deployed title',
726 content: 'Deployed content.',
727 url: '/docs/configuring-sessions#overview',
728 page_id: '/docs/configuring-sessions',
729 type: 'docs',
730 }]);
731 expect(legacyRecord).toBeDefined();
732 const shared = publicKnowledgeCandidateFromSearchRecord(legacyRecord!);
733 const branchRecord = record({
734 id: 'branch-doc', title: 'Branch-current title', sourceType: 'docs', pageRank: 2_000,
735 });
736 branchRecord.url = '/docs/configuring-sessions';
737 branchRecord.canonical_url = '/docs/configuring-sessions';
738 const branch = publicKnowledgeCandidateFromSearchRecord(branchRecord);
739 const dependencies = (preview: boolean) => ({
740 hybridEnabled: () => false,
741 searchKeywordCandidates: async () => ({ candidates: [shared] }),
742 searchSemanticCandidates: async () => [],
743 searchPreviewCandidates: async () => [branch],
744 previewOverlayEnabled: () => preview,
745 });
746
747 const preview = await searchPublicKnowledge(
748 { query: 'sessions', filter: 'all', headers: new Headers() },
749 dependencies(true),
750 );
751 const production = await searchPublicKnowledge(
752 { query: 'sessions', filter: 'all', headers: new Headers() },
753 dependencies(false),
754 );
755
756 expect(preview.response).toMatchObject({ results: [{ title: 'Branch-current title' }] });
757 expect(production.response).toMatchObject({ results: [{ title: 'Deployed title' }] });
758 });
759
760 test('returns a full-corpus exact action result before semantic retrieval', async () => {
761 const action = publicKnowledgeCandidateFromSearchRecord(record({
762 id: 'create-invitee',
763 title: 'Create invitee',
764 sourceType: 'reference',
765 pageRank: 700,
766 keywords: ['CALENDLY_POST_INVITEE'],
767 }));
768 let semanticCalls = 0;
769 let keywordFilter = '';
770
771 const execution = await searchPublicKnowledge({
772 query: 'CALENDLY_POST_INVITEE',
773 filter: 'all',
774 headers: new Headers(),
775 }, {
776 hybridEnabled: () => true,
777 searchKeywordCandidates: async (_query, filter) => {
778 keywordFilter = filter;
779 return { candidates: [action] };
780 },
781 searchSemanticCandidates: async () => {
782 semanticCalls += 1;
783 return [];
784 },
785 searchLocalCandidates: async () => [],
786 previewOverlayEnabled: () => false,
787 });
788
789 expect(execution.status).toBe(200);
790 expect(keywordFilter).toBe('all');
791 expect(semanticCalls).toBe(0);
792 expect(execution.response).toMatchObject({
793 filter: 'all',
794 mode: 'keyword',
795 strongMatch: true,
796 results: [{ sourceType: 'reference' }],
797 });
798 expect(execution.timings.semanticDurationMs).toBeNull();
799 });
800
801 test('promotes exact page identities above incidental body matches', async () => {
802 const candidates = [
803 record({
804 id: 'gmail-toolkit',
805 title: 'Gmail',
806 sourceType: 'toolkit',
807 pageRank: 1_500,
808 }),
809 record({
810 id: 'configuring-sessions',
811 title: 'Configuring Sessions',
812 sourceType: 'docs',
813 pageRank: 2_000,
814 content: 'Use toolkits=["github", "gmail", "slack"] when creating a session.',
815 }),
816 record({
817 id: 'shared-connections',
818 title: 'Shared connections',
819 sourceType: 'docs',
820 pageRank: 2_000,
821 content: 'Create a shared Gmail connection that any user can use.',
822 }),
823 record({
824 id: 'gmail-kb',
825 title: 'Gmail',
826 sourceType: 'kb',
827 pageRank: 1_900,
828 }),
829 ].map(publicKnowledgeCandidateFromSearchRecord);
830 let semanticCalls = 0;
831
832 const execution = await searchPublicKnowledge({
833 query: 'gmail', filter: 'all', headers: new Headers(),
834 }, {
835 hybridEnabled: () => true,
836 searchKeywordCandidates: async () => ({ candidates }),
837 searchSemanticCandidates: async () => {
838 semanticCalls += 1;
839 return [];
840 },
841 previewOverlayEnabled: () => false,
842 });
843
844 const results = 'results' in execution.response ? execution.response.results : [];
845 expect(semanticCalls).toBe(0);
846 expect(results.map(result => result.objectID)).toEqual([
847 'gmail-toolkit',
848 'gmail-kb',
849 'configuring-sessions',
850 'shared-connections',
851 ]);
852 });
853
854 test('deduplicates exact keyword section chunks before returning results', async () => {
855 const gmailSections = Array.from({ length: 20 }, (_, index) => {
856 const section = record({
857 id: index === 0 ? 'gmail-attachments' : `gmail-section-${index}`,
858 title: 'Gmail',
859 sourceType: 'kb',
860 pageRank: 1_900,
861 content: index === 0
862 ? 'Send attachments safely with Gmail.'
863 : `Gmail support section ${index}.`,
864 });
865 section.url = '/kb/guide/toolkits-gmail';
866 section.page_id = '/kb/guide/toolkits-gmail';
867 section.canonical_url = '/kb/guide/toolkits-gmail';
868 section.section = index === 0 ? 'Send attachments safely' : `Gmail section ${index}`;
869 return publicKnowledgeCandidateFromSearchRecord(section);
870 });
871
872 const toolkit = publicKnowledgeCandidateFromSearchRecord(record({
873 id: 'gmail',
874 title: 'Gmail',
875 sourceType: 'toolkit',
876 pageRank: 1_500,
877 }));
878 let semanticCalls = 0;
879
880 const execution = await searchPublicKnowledge({
881 query: 'gmail', filter: 'all', headers: new Headers(),
882 }, {
883 hybridEnabled: () => true,
884 searchKeywordCandidates: async () => ({
885 candidates: gmailSections.concat(toolkit),
886 }),
887 searchSemanticCandidates: async () => {
888 semanticCalls += 1;
889 return [];
890 },
891 previewOverlayEnabled: () => false,
892 });
893
894 const results = 'results' in execution.response ? execution.response.results : [];
895 expect(semanticCalls).toBe(0);
896 expect(results.map(result => result.objectID)).toEqual(['gmail-attachments', 'gmail']);
897 expect(new Set(results.map(result => result.canonicalUrl)).size).toBe(results.length);
898 });
899
900 test('deduplicates section chunks when hybrid retrieval is disabled', async () => {
901 const attachmentsRecord = record({
902 id: 'gmail-attachments',
903 title: 'Gmail',
904 sourceType: 'kb',
905 pageRank: 1_900,
906 content: 'Use Gmail attachments safely.',
907 });
908 attachmentsRecord.url = '/kb/guide/toolkits-gmail';
909 attachmentsRecord.page_id = '/kb/guide/toolkits-gmail';
910 attachmentsRecord.canonical_url = '/kb/guide/toolkits-gmail';
911 attachmentsRecord.section = 'Send attachments safely';
912
913 const oauthRecord = record({
914 id: 'gmail-oauth',
915 title: 'Gmail',
916 sourceType: 'kb',
917 pageRank: 1_900,
918 content: 'Configure Gmail OAuth scopes.',
919 });
920 oauthRecord.url = '/kb/guide/toolkits-gmail';
921 oauthRecord.page_id = '/kb/guide/toolkits-gmail';
922 oauthRecord.canonical_url = '/kb/guide/toolkits-gmail';
923 oauthRecord.section = 'Configure Gmail OAuth';
924
925 const execution = await searchPublicKnowledge({
926 query: 'gmail attachments', filter: 'all', headers: new Headers(),
927 }, {
928 hybridEnabled: () => false,
929 searchKeywordCandidates: async () => ({
930 candidates: [attachmentsRecord, oauthRecord]
931 .map(publicKnowledgeCandidateFromSearchRecord),
932 }),
933 searchSemanticCandidates: async () => [],
934 previewOverlayEnabled: () => false,
935 });
936
937 const results = 'results' in execution.response ? execution.response.results : [];
938 expect(results.map(result => result.objectID)).toEqual(['gmail-attachments']);
939 expect(new Set(results.map(result => result.canonicalUrl)).size).toBe(results.length);
940 });
941
942 test('fuses docs and KB semantics with toolkit and reference keyword candidates', async () => {
943 const toolkit = publicKnowledgeCandidateFromSearchRecord(record({
944 id: 'calendar-toolkit', title: 'Calendar tools', sourceType: 'toolkit', pageRank: 1_500,
945 }));
946 const reference = publicKnowledgeCandidateFromSearchRecord(record({
947 id: 'sessions-reference', title: 'Sessions API', sourceType: 'reference', pageRank: 700,
948 }));
949 const docs = publicKnowledgeCandidateFromSearchRecord(record({
950 id: 'sessions-docs', title: 'Configure sessions', sourceType: 'docs', pageRank: 2_000,
951 }));
952 const kb = publicKnowledgeCandidateFromSearchRecord(record({
953 id: 'calendar-kb', title: 'Repair calendar authorization', sourceType: 'kb', pageRank: 1_900,
954 }));
955 let semanticCalls = 0;
956
957 const execution = await searchPublicKnowledge({
958 query: 'why did my calendar connection stop working',
959 filter: 'all',
960 headers: new Headers(),
961 }, {
962 hybridEnabled: () => true,
963 searchKeywordCandidates: async () => ({ candidates: [toolkit, reference] }),
964 searchSemanticCandidates: async () => {
965 semanticCalls += 1;
966 return [docs, kb];
967 },
968 searchLocalCandidates: async () => [],
969 previewOverlayEnabled: () => false,
970 });
971
972 expect(semanticCalls).toBe(1);
973 expect(execution.response).toMatchObject({ mode: 'hybrid', strongMatch: true });
974 expect('results' in execution.response
975 ? execution.response.results.map(result => result.sourceType)
976 : []).toEqual(['docs', 'toolkit', 'kb', 'reference']);
977 expect(execution.timings.semanticDurationMs).not.toBeNull();
978 });
979
980 test('keeps legacy reference exact-only across the unified corpus', async () => {
981 const current = publicKnowledgeCandidateFromSearchRecord(record({
982 id: 'current', title: 'Create connected account', sourceType: 'reference', pageRank: 700,
983 }));
984 const legacy = publicKnowledgeCandidateFromSearchRecord(record({
985 id: 'legacy', title: 'Create connected account', sourceType: 'legacy', pageRank: 25,
986 }));
987 const weakLegacy = publicKnowledgeCandidateFromSearchRecord(record({
988 id: 'legacy-weak', title: 'Old create account guide', sourceType: 'legacy', pageRank: 25,
989 content: 'Create connected account with the old endpoint.',
990 }));
991 const dependencies = {
992 hybridEnabled: () => false,
993 searchKeywordCandidates: async () => ({ candidates: [legacy, current, weakLegacy] }),
994 searchSemanticCandidates: async () => [],
995 searchLocalCandidates: async () => [],
996 previewOverlayEnabled: () => false,
997 };
998
999 const currentExecution = await searchPublicKnowledge({
1000 query: 'Create connected account', filter: 'all', headers: new Headers(),
1001 }, dependencies);
1002 expect('results' in currentExecution.response
1003 ? currentExecution.response.results.map(result => result.objectID)
1004 : []).toEqual(['current']);
1005
1006 const weakExecution = await searchPublicKnowledge({
1007 query: 'create account', filter: 'all', headers: new Headers(),
1008 }, dependencies);
1009 expect('results' in weakExecution.response
1010 ? weakExecution.response.results.some(result => result.sourceType === 'legacy')
1011 : true).toBe(false);
1012 });
1013
1014 test('uses the full local public corpus when shared keyword retrieval fails', async () => {
1015 const local = closeMatchRecords
1016 .filter(item => item.source_type !== 'legacy')
1017 .map(publicKnowledgeCandidateFromSearchRecord);
1018 const events: Array<{ degradationCategory: string | null; retrievalMode: string }> = [];
1019
1020 const execution = await searchPublicKnowledge({
1021 query: 'connected account setup', filter: 'all', headers: new Headers(),
1022 }, {
1023 hybridEnabled: () => false,
1024 searchKeywordCandidates: async () => { throw new Error('keyword-request-failed'); },
1025 searchSemanticCandidates: async () => { throw new Error('semantic-request-failed'); },
1026 searchLocalCandidates: async () => local,
1027 previewOverlayEnabled: () => false,
1028 captureSearch: event => events.push(event),
1029 });
1030
1031 expect(execution.status).toBe(200);
1032 expect('results' in execution.response
1033 ? execution.response.results.map(result => result.sourceType)
1034 : []).toEqual([
1035 'docs', 'kb', 'oauth-guide', 'toolkit', 'example', 'reference', 'changelog',
1036 ]);
1037 expect(events).toHaveLength(1);
1038 expect(events[0]).toMatchObject({
1039 degradationCategory: 'keyword-request-failed',
1040 retrievalMode: 'keyword',
1041 });
1042 });
1043
1044 test('overlays branch-local docs in preview and disables the overlay in production', async () => {
1045 const shared = publicKnowledgeCandidateFromSearchRecord(record({
1046 id: 'shared-doc', title: 'Shared title', sourceType: 'docs', pageRank: 2_000,
1047 }));
1048 const branchRecord = record({
1049 id: 'branch-doc', title: 'Branch-current title', sourceType: 'docs', pageRank: 2_000,
1050 });
1051 branchRecord.canonical_url = shared.canonicalUrl;
1052 branchRecord.url = shared.canonicalUrl;
1053 const branch = publicKnowledgeCandidateFromSearchRecord(branchRecord);
1054 let localCalls = 0;
1055 const dependencies = (preview: boolean) => ({
1056 hybridEnabled: () => false,
1057 searchKeywordCandidates: async () => ({ candidates: [shared] }),
1058 searchSemanticCandidates: async () => [],
1059 searchPreviewCandidates: async () => {
1060 localCalls += 1;
1061 return [branch];
1062 },
1063 previewOverlayEnabled: () => preview,
1064 });
1065
1066 const preview = await searchPublicKnowledge({
1067 query: 'Branch-current title', filter: 'all', headers: new Headers(),
1068 }, dependencies(true));
1069 expect(preview.response).toMatchObject({ results: [{ title: 'Branch-current title' }] });
1070 expect(preview.previewOverlayApplied).toBe(true);
1071
1072 const production = await searchPublicKnowledge({
1073 query: 'Shared title', filter: 'all', headers: new Headers(),
1074 }, dependencies(false));
1075 expect(production.response).toMatchObject({ results: [{ title: 'Shared title' }] });
1076 expect(production.previewOverlayApplied).toBe(false);
1077 expect(localCalls).toBe(1);
1078 });
1079
1080 test('removes a stale shared docs hit when the branch-local page no longer matches', async () => {
1081 const shared = publicKnowledgeCandidateFromSearchRecord(record({
1082 id: 'stale-doc', title: 'Removed setup wording', sourceType: 'docs', pageRank: 2_000,
1083 }));
1084
1085 const execution = await searchPublicKnowledge({
1086 query: 'Removed setup wording', filter: 'all', headers: new Headers(),
1087 }, {
1088 hybridEnabled: () => false,
1089 searchKeywordCandidates: async () => ({ candidates: [shared] }),
1090 searchSemanticCandidates: async () => [],
1091 searchPreviewCandidates: async () => ({
1092 candidates: [],
1093 canonicalUrls: [shared.canonicalUrl],
1094 }),
1095 previewOverlayEnabled: () => true,
1096 });
1097
1098 expect(execution.response).toMatchObject({ mode: 'keyword', results: [] });
1099 expect(execution.previewOverlayApplied).toBe(true);
1100 });
1101
1102 test('does not let a weak preview record hide a strong shared identity match', async () => {
1103 const exact = publicKnowledgeCandidateFromSearchRecord(record({
1104 id: 'exact-reference', title: 'Calendly action', sourceType: 'reference', pageRank: 700,
1105 keywords: ['CALENDLY_POST_INVITEE'],
1106 }));
1107 const weakLocal = publicKnowledgeCandidateFromSearchRecord(record({
1108 id: 'local-doc', title: 'Calendly overview', sourceType: 'docs', pageRank: 2_000,
1109 content: 'Learn about Calendly actions.',
1110 }));
1111 let semanticCalls = 0;
1112
1113 const execution = await searchPublicKnowledge({
1114 query: 'CALENDLY_POST_INVITEE', filter: 'all', headers: new Headers(),
1115 }, {
1116 hybridEnabled: () => true,
1117 searchKeywordCandidates: async () => ({ candidates: [exact] }),
1118 searchSemanticCandidates: async () => {
1119 semanticCalls += 1;
1120 return [];
1121 },
1122 searchPreviewCandidates: async () => [weakLocal],
1123 previewOverlayEnabled: () => true,
1124 });
1125
1126 expect(semanticCalls).toBe(0);
1127 expect(execution.response).toMatchObject({
1128 mode: 'keyword',
1129 results: [{ objectID: 'exact-reference' }, { objectID: 'local-doc' }],
1130 });
1131 });
1132
1133 test('uses matching full-corpus local candidates for explicit non-editorial filters', async () => {
1134 const toolkit = publicKnowledgeCandidateFromSearchRecord(record({
1135 id: 'calendar-toolkit', title: 'Calendar toolkit', sourceType: 'toolkit', pageRank: 1_500,
1136 }));
1137 const reference = publicKnowledgeCandidateFromSearchRecord(record({
1138 id: 'sessions-reference', title: 'Sessions reference', sourceType: 'reference', pageRank: 700,
1139 }));
1140 const oauth = publicKnowledgeCandidateFromSearchRecord(record({
1141 id: 'oauth-guide', title: 'OAuth guide', sourceType: 'oauth-guide', pageRank: 1_700,
1142 }));
1143 const cases = [
1144 { filter: 'toolkit' as const, query: 'Calendar toolkit', want: 'calendar-toolkit' },
1145 { filter: 'reference' as const, query: 'Sessions reference', want: 'sessions-reference' },
1146 { filter: 'oauth' as const, query: 'OAuth guide', want: 'oauth-guide' },
1147 ];
1148
1149 for (const item of cases) {
1150 let localFilter = '';
1151 const execution = await searchPublicKnowledge({
1152 query: item.query, filter: item.filter, headers: new Headers(),
1153 }, {
1154 hybridEnabled: () => true,
1155 searchKeywordCandidates: async () => { throw new Error('keyword-request-failed'); },
1156 searchSemanticCandidates: async () => [],
1157 searchLocalCandidates: async (_query, filter) => {
1158 localFilter = filter;
1159 return [toolkit, reference, oauth];
1160 },
1161 previewOverlayEnabled: () => false,
1162 });
1163
1164 expect(localFilter).toBe(item.filter);
1165 expect(execution.status).toBe(200);
1166 expect(execution.response).toMatchObject({ results: [{ objectID: item.want }] });
1167 }
1168 });
1169
1170 test('does not bypass semantics for an exact identity beyond the returned keyword window', async () => {
1171 const weak = Array.from({ length: 20 }, (_, index) =>
1172 publicKnowledgeCandidateFromSearchRecord(record({
1173 id: `weak-${index}`,
1174 title: `Weak result ${index}`,
1175 sourceType: 'docs',
1176 pageRank: 2_000 - index,
1177 })));
1178 const outOfWindowExact = publicKnowledgeCandidateFromSearchRecord(record({
1179 id: 'out-of-window-exact',
1180 title: 'Action reference',
1181 sourceType: 'reference',
1182 pageRank: 700,
1183 keywords: ['CALENDLY_POST_INVITEE'],
1184 }));
1185 let semanticCalls = 0;
1186
1187 const execution = await searchPublicKnowledge({
1188 query: 'CALENDLY_POST_INVITEE', filter: 'all', headers: new Headers(),
1189 }, {
1190 hybridEnabled: () => true,
1191 searchKeywordCandidates: async () => ({ candidates: [...weak, outOfWindowExact] }),
1192 searchSemanticCandidates: async () => {
1193 semanticCalls += 1;
1194 return [];
1195 },
1196 searchLocalCandidates: async () => [],
1197 previewOverlayEnabled: () => false,
1198 });
1199
1200 expect(semanticCalls).toBe(1);
1201 expect(execution.response).toMatchObject({ mode: 'hybrid', strongMatch: false, results: [] });
1202 });
1203
1204 test('reports preview overlay failure while preserving shared keyword results', async () => {
1205 const shared = publicKnowledgeCandidateFromSearchRecord(record({
1206 id: 'shared-doc', title: 'Shared title', sourceType: 'docs', pageRank: 2_000,
1207 }));
1208 const events: Array<{ degradationCategory: string | null }> = [];
1209
1210 const execution = await searchPublicKnowledge({
1211 query: 'Shared title', filter: 'all', headers: new Headers(),
1212 }, {
1213 hybridEnabled: () => true,
1214 searchKeywordCandidates: async () => ({ candidates: [shared] }),
1215 searchSemanticCandidates: async () => [],
1216 searchPreviewCandidates: async () => { throw new Error('local-index-failed'); },
1217 previewOverlayEnabled: () => true,
1218 captureSearch: event => events.push(event),
1219 });
1220
1221 expect(execution.status).toBe(200);
1222 expect(execution.response).toMatchObject({ mode: 'keyword', results: [{ title: 'Shared title' }] });
1223 expect(execution.previewOverlayApplied).toBe(false);
1224 expect(events).toHaveLength(1);
1225 expect(events[0]).toMatchObject({ degradationCategory: 'preview-overlay-failed' });
1226 });
1227
1228 test('returns 503 only when shared, local, and semantic retrieval all fail', async () => {
1229 const execution = await searchPublicKnowledge({
1230 query: 'unavailable answer', filter: 'all', headers: new Headers(),
1231 }, {
1232 hybridEnabled: () => true,
1233 searchKeywordCandidates: async () => { throw new Error('keyword-request-failed'); },
1234 searchSemanticCandidates: async () => { throw new Error('semantic-request-failed'); },
1235 searchLocalCandidates: async () => { throw new Error('local-index-failed'); },
1236 previewOverlayEnabled: () => false,
1237 });
1238
1239 expect(execution.status).toBe(503);
1240 expect(execution.response).toEqual({ error: 'Knowledge search is temporarily unavailable' });
1241 });
1242 });