fix(copilot): harden docs context retrieval

Author: j15z

apps/sim/lib/copilot/chat/post.test.ts

@@ -384,7 +384,8 @@ describe('handleUnifiedChatPost', () => {
       'user-1',
       'Hello',
       'ws-1',
-      expect.anything()
+      expect.anything(),
+      expect.any(ResolvedSecretTraceRegistry)
     )
   })
 
@@ -448,7 +449,8 @@ describe('handleUnifiedChatPost', () => {
       'user-1',
       'Explain these selections',
       'ws-1',
-      'chat-1'
+      'chat-1',
+      expect.any(ResolvedSecretTraceRegistry)
     )
   })
 

apps/sim/lib/copilot/chat/process-contents.test.ts

@@ -373,6 +373,34 @@ describe('processContextsServer - docs contexts', () => {
       expect.objectContaining({ workspaceId: 'ws-1', chatId: 'chat-1' })
     )
   })
+
+  it('preserves an explicit unavailable note when docs search fails', async () => {
+    searchDocsExecute.mockRejectedValue(new Error('embedding service unavailable'))
+
+    const result = await processContextsServer(
+      [{ kind: 'docs', label: 'Docs' }],
+      'user-1',
+      '@Docs explain schedules',
+      'ws-1',
+      'chat-1',
+      new ResolvedSecretTraceRegistry()
+    )
+
+    expect(result).toEqual([
+      {
+        type: 'docs',
+        tag: '@Docs',
+        content: JSON.stringify({
+          results: [],
+          note: 'Documentation search is temporarily unavailable. Do not infer that the docs lack this topic; retry search_docs or browse docs/** later.',
+        }),
+      },
+    ])
+    expect(mockProcessContentsLogger.error).toHaveBeenCalledWith(
+      'Failed to process docs context',
+      expect.any(Error)
+    )
+  })
 })
 
 describe('processContextsServer - MCP contexts', () => {

apps/sim/lib/copilot/chat/process-contents.ts

@@ -338,7 +338,14 @@ export async function processContextsServer(
           return { type: 'docs', tag: ctx.label ? `@${ctx.label}` : '@', content }
         } catch (e) {
           logger.error('Failed to process docs context', e)
-          return null
+          return {
+            type: 'docs',
+            tag: ctx.label ? `@${ctx.label}` : '@',
+            content: JSON.stringify({
+              results: [],
+              note: 'Documentation search is temporarily unavailable. Do not infer that the docs lack this topic; retry search_docs or browse docs/** later.',
+            }),
+          }
         }
       }
       return null

apps/sim/lib/copilot/docs/docs-corpus.test.ts

@@ -3,8 +3,12 @@
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
+const { mockSleep } = vi.hoisted(() => ({
+  mockSleep: vi.fn(() => Promise.resolve()),
+}))
+
 vi.mock('@sim/utils/helpers', () => ({
-  sleep: vi.fn(() => Promise.resolve()),
+  sleep: mockSleep,
 }))
 
 import {
@@ -19,6 +23,15 @@ import { DOCS_MANIFEST } from '@/lib/copilot/generated/docs-manifest'
 
 const SAMPLE_PAGE = DOCS_MANIFEST.find((path) => path === 'workflows/blocks/agent.mdx')
 
+function fetchResponse(status: number, content = '', headers: HeadersInit = {}) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    headers: new Headers(headers),
+    text: async () => content,
+  }
+}
+
 describe('docs corpus scoping', () => {
   it('recognizes docs paths', () => {
     expect(isDocsPath('docs/workflows.mdx')).toBe(true)
@@ -75,6 +88,8 @@ describe('readDocsPage', () => {
 
   beforeEach(() => {
     fetchMock.mockReset()
+    mockSleep.mockReset()
+    mockSleep.mockResolvedValue(undefined)
     vi.stubGlobal('fetch', fetchMock)
   })
 
@@ -84,7 +99,7 @@ describe('readDocsPage', () => {
 
   it('fetches the manifest path verbatim from the docs site', async () => {
     expect(SAMPLE_PAGE).toBeDefined()
-    fetchMock.mockResolvedValue({ ok: true, status: 200, text: async () => '# Agent\n\nbody' })
+    fetchMock.mockResolvedValue(fetchResponse(200, '# Agent\n\nbody'))
 
     const page = await readDocsPage(`docs/${SAMPLE_PAGE}`)
 
@@ -104,7 +119,7 @@ describe('readDocsPage', () => {
   })
 
   it('surfaces a docs-site outage as a retryable error after exhausting retries', async () => {
-    fetchMock.mockResolvedValue({ ok: false, status: 502, text: async () => '' })
+    fetchMock.mockResolvedValue(fetchResponse(502))
     await expect(readDocsPage(`docs/${SAMPLE_PAGE}`)).rejects.toThrow(/could not be reached/)
     expect(fetchMock).toHaveBeenCalledTimes(3)
   })
@@ -118,7 +133,7 @@ describe('readDocsPage', () => {
   it('recovers when a transient failure clears on retry', async () => {
     fetchMock
       .mockRejectedValueOnce(new Error('socket hang up'))
-      .mockResolvedValue({ ok: true, status: 200, text: async () => '# Agent\n\nbody' })
+      .mockResolvedValue(fetchResponse(200, '# Agent\n\nbody'))
 
     const page = await readDocsPage(`docs/${SAMPLE_PAGE}`)
 
@@ -127,7 +142,7 @@ describe('readDocsPage', () => {
   })
 
   it('reports a page the site no longer serves as permanent, without retrying', async () => {
-    fetchMock.mockResolvedValue({ ok: false, status: 404, text: async () => '' })
+    fetchMock.mockResolvedValue(fetchResponse(404))
     const error = await readDocsPage(`docs/${SAMPLE_PAGE}`).catch((e) => e)
     expect(error).toBeInstanceOf(DocsCorpusError)
     expect(error.message).toMatch(/does not serve it/)
@@ -136,17 +151,50 @@ describe('readDocsPage', () => {
     expect(fetchMock).toHaveBeenCalledOnce()
   })
 
-  it('still treats 429 as retryable rather than permanent', async () => {
-    fetchMock.mockResolvedValue({ ok: false, status: 429, text: async () => '' })
+  it('honors Retry-After while retrying a 429 response', async () => {
+    fetchMock.mockResolvedValue(fetchResponse(429, '', { 'Retry-After': '7' }))
     await expect(readDocsPage(`docs/${SAMPLE_PAGE}`)).rejects.toThrow(/could not be reached/)
     expect(fetchMock).toHaveBeenCalledTimes(3)
+    expect(mockSleep).toHaveBeenNthCalledWith(1, 7_000)
+    expect(mockSleep).toHaveBeenNthCalledWith(2, 7_000)
   })
 
   it('treats 408 as retryable rather than a missing page', async () => {
-    fetchMock.mockResolvedValue({ ok: false, status: 408, text: async () => '' })
+    fetchMock.mockResolvedValue(fetchResponse(408))
     await expect(readDocsPage(`docs/${SAMPLE_PAGE}`)).rejects.toThrow(/could not be reached/)
     expect(fetchMock).toHaveBeenCalledTimes(3)
   })
+
+  it('aborts an in-flight fetch without retrying', async () => {
+    const controller = new AbortController()
+    fetchMock.mockImplementation((_url: string, init: RequestInit) => {
+      const signal = init.signal as AbortSignal
+      return new Promise((_resolve, reject) => {
+        signal.addEventListener('abort', () => reject(signal.reason), { once: true })
+      })
+    })
+
+    const request = readDocsPage(`docs/${SAMPLE_PAGE}`, controller.signal)
+    await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledOnce())
+    controller.abort(new Error('user stopped docs read'))
+
+    await expect(request).rejects.toThrow('user stopped docs read')
+    expect(fetchMock).toHaveBeenCalledOnce()
+    expect(mockSleep).not.toHaveBeenCalled()
+  })
+
+  it('aborts retry backoff before starting another fetch', async () => {
+    const controller = new AbortController()
+    fetchMock.mockResolvedValue(fetchResponse(502))
+    mockSleep.mockImplementationOnce(() => new Promise<void>(() => {}))
+
+    const request = readDocsPage(`docs/${SAMPLE_PAGE}`, controller.signal)
+    await vi.waitFor(() => expect(mockSleep).toHaveBeenCalledOnce())
+    controller.abort(new Error('user stopped docs retry'))
+
+    await expect(request).rejects.toThrow('user stopped docs retry')
+    expect(fetchMock).toHaveBeenCalledOnce()
+  })
 })
 
 describe('grepDocs', () => {
@@ -163,11 +211,7 @@ describe('grepDocs', () => {
   })
 
   it('greps exactly one page for a page path', async () => {
-    fetchMock.mockResolvedValue({
-      ok: true,
-      status: 200,
-      text: async () => 'intro line\nsystemPrompt matters\ntail',
-    })
+    fetchMock.mockResolvedValue(fetchResponse(200, 'intro line\nsystemPrompt matters\ntail'))
 
     const matches = await grepDocs(`docs/${SAMPLE_PAGE}`, 'systemPrompt')
 

apps/sim/lib/copilot/docs/docs-corpus.ts

@@ -1,7 +1,7 @@
 import { createLogger } from '@sim/logger'
 import { toError } from '@sim/utils/errors'
 import { sleep } from '@sim/utils/helpers'
-import { backoffWithJitter } from '@sim/utils/retry'
+import { backoffWithJitter, parseRetryAfter } from '@sim/utils/retry'
 import { foldDocsIndexPath } from '@/lib/copilot/docs/docs-path'
 import { DOCS_MANIFEST } from '@/lib/copilot/generated/docs-manifest'
 import type { GrepCountEntry, GrepMatch, GrepOptions } from '@/lib/copilot/vfs/operations'
@@ -121,12 +121,43 @@ type DocsFetchResult =
   /** The site will not serve this path however many times we ask. */
   | { outcome: 'missing' }
   /** Transient: 5xx, 429, network error, or timeout. */
-  | { outcome: 'unavailable' }
+  | { outcome: 'unavailable'; retryAfterMs: number | null }
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw toError(signal.reason ?? 'Docs request aborted')
+  }
+}
+
+async function sleepForRetry(delayMs: number, signal?: AbortSignal): Promise<void> {
+  if (!signal) {
+    await sleep(delayMs)
+    return
+  }
+
+  throwIfAborted(signal)
+  let abortListener: (() => void) | undefined
+  const aborted = new Promise<never>((_resolve, reject) => {
+    abortListener = () => reject(toError(signal.reason ?? 'Docs request aborted'))
+    signal.addEventListener('abort', abortListener, { once: true })
+    if (signal.aborted) abortListener()
+  })
+
+  try {
+    await Promise.race([sleep(delayMs), aborted])
+  } finally {
+    if (abortListener) signal.removeEventListener('abort', abortListener)
+  }
+}
+
+async function fetchDocsPageOnce(url: string, signal?: AbortSignal): Promise<DocsFetchResult> {
+  throwIfAborted(signal)
+  const timeoutSignal = AbortSignal.timeout(FETCH_ATTEMPT_TIMEOUT_MS)
+  const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal
 
-async function fetchDocsPageOnce(url: string): Promise<DocsFetchResult> {
   try {
     const response = await fetch(url, {
-      signal: AbortSignal.timeout(FETCH_ATTEMPT_TIMEOUT_MS),
+      signal: requestSignal,
       headers: { Accept: 'text/markdown, text/plain' },
     })
     if (!response.ok) {
@@ -136,23 +167,30 @@ async function fetchDocsPageOnce(url: string): Promise<DocsFetchResult> {
         response.status < 500 &&
         response.status !== 408 &&
         response.status !== 429
-      return { outcome: permanent ? 'missing' : 'unavailable' }
+      if (permanent) return { outcome: 'missing' }
+      return {
+        outcome: 'unavailable',
+        retryAfterMs: parseRetryAfter(response.headers.get('retry-after')),
+      }
     }
     return { outcome: 'ok', content: await response.text() }
   } catch (err) {
+    throwIfAborted(signal)
     logger.warn('Docs page fetch failed', { url, error: toError(err).message })
-    return { outcome: 'unavailable' }
+    return { outcome: 'unavailable', retryAfterMs: null }
   }
 }
 
-async function fetchDocsPage(path: string): Promise<DocsFetchResult> {
+async function fetchDocsPage(path: string, signal?: AbortSignal): Promise<DocsFetchResult> {
   const key = normalizeDocsPath(path)
   if (!docsKeyView.has(key)) return { outcome: 'missing' }
   const url = `${DOCS_BASE_URL}/${key.slice(DOCS_PREFIX.length)}`
   for (let attempt = 1; ; attempt++) {
-    const result = await fetchDocsPageOnce(url)
+    throwIfAborted(signal)
+    const result = await fetchDocsPageOnce(url, signal)
+    throwIfAborted(signal)
     if (result.outcome !== 'unavailable' || attempt >= FETCH_MAX_ATTEMPTS) return result
-    await sleep(backoffWithJitter(attempt, null))
+    await sleepForRetry(backoffWithJitter(attempt, result.retryAfterMs), signal)
   }
 }
 
@@ -161,7 +199,7 @@ async function fetchDocsPage(path: string): Promise<DocsFetchResult> {
  * conditions (directory path, unknown page, site unreachable) so the handler can
  * surface the message verbatim.
  */
-export async function readDocsPage(path: string): Promise<DocsPage> {
+export async function readDocsPage(path: string, signal?: AbortSignal): Promise<DocsPage> {
   const key = normalizeDocsPath(path)
   if (!docsKeyView.has(key)) {
     if (isDocsDir(key)) {
@@ -172,7 +210,7 @@ export async function readDocsPage(path: string): Promise<DocsPage> {
       `Docs page not found: ${path}. Use glob("docs/**") to list the docs corpus.`
     )
   }
-  const result = await fetchDocsPage(key)
+  const result = await fetchDocsPage(key, signal)
   if (result.outcome === 'missing') {
     throw new DocsCorpusError(
       `${key} is in the docs index but ${DOCS_BASE_URL} does not serve it — the page was likely moved or removed. Use glob("docs/**") to find the current path; retrying will not help.`
@@ -194,7 +232,8 @@ export async function readDocsPage(path: string): Promise<DocsPage> {
 export async function grepDocs(
   path: string,
   pattern: string,
-  options?: GrepOptions
+  options?: GrepOptions,
+  signal?: AbortSignal
 ): Promise<GrepMatch[] | string[] | GrepCountEntry[]> {
   const key = normalizeDocsPath(path)
   if (!docsKeyView.has(key)) {
@@ -207,6 +246,6 @@ export async function grepDocs(
       `"${path}" is not a docs page. Use glob("docs/**") to list the docs corpus.`
     )
   }
-  const page = await readDocsPage(key)
+  const page = await readDocsPage(key, signal)
   return grepReadResult(key, page, pattern, key, options)
 }