From 2b651c995c2bfa80ccbea6831aeeaa8a9a99d73d Mon Sep 17 00:00:00 2001 From: Vikhyath Mondreti Date: Thu, 17 Sep 2026 14:12:36 -0700 Subject: [PATCH 1/5] improvement(file-search): publish complete indexes in bounded text chunks --- apps/docs/content/docs/integrations/file.mdx | 20 +- .../copilot/tools/server/files/doc-compile.ts | 25 +- .../server/files/doc-compiled-store.test.ts | 30 + .../tools/server/files/doc-compiled-store.ts | 55 +- .../tools/server/files/doc-servable.test.ts | 30 +- .../lib/file-parsers/complete-text.test.ts | 91 + apps/sim/lib/file-parsers/complete-text.ts | 37 + apps/sim/lib/file-parsers/csv-parser.ts | 21 +- apps/sim/lib/file-parsers/types.ts | 3 + apps/sim/lib/file-parsers/xlsx-parser.ts | 68 +- apps/sim/lib/workspace-files/search/README.md | 46 + .../lib/workspace-files/search/candidates.ts | 186 + .../search/chunks.integration.ts | 467 + .../lib/workspace-files/search/constants.ts | 30 +- .../search/dispatcher.integration.ts | 33 +- .../workspace-files/search/dispatcher.test.ts | 11 +- .../lib/workspace-files/search/dispatcher.ts | 164 +- .../workspace-files/search/extract.test.ts | 28 +- .../sim/lib/workspace-files/search/extract.ts | 27 +- .../workspace-files/search/index-plan.test.ts | 58 + .../lib/workspace-files/search/index-plan.ts | 105 + .../lib/workspace-files/search/index-state.ts | 293 + .../workspace-files/search/indexing.test.ts | 114 + .../lib/workspace-files/search/indexing.ts | 391 +- .../workspace-files/search/pattern.test.ts | 7 - .../sim/lib/workspace-files/search/pattern.ts | 33 +- .../lib/workspace-files/search/regex.test.ts | 28 + apps/sim/lib/workspace-files/search/regex.ts | 84 +- .../workspace-files/search/repository.test.ts | 4 + .../lib/workspace-files/search/repository.ts | 403 +- .../lib/workspace-files/search/sql-pattern.ts | 16 + .../lib/workspace-files/search/text.test.ts | 40 +- apps/sim/lib/workspace-files/search/text.ts | 80 +- apps/sim/tools/file/search.ts | 19 +- apps/sim/tools/generated/tool-metadata.ts | 2 +- apps/sim/tools/generated/tool-outputs.ts | 2 +- .../0359_workspace_file_search_chunks.sql | 81 + .../db/migrations/meta/0359_snapshot.json | 27925 ++++++++++++++++ packages/db/migrations/meta/_journal.json | 7 + packages/db/schema.ts | 97 +- ...ace_file_content_revision.postgres.test.ts | 17 + ..._repair_workspace_file_content_revision.ts | 22 +- packages/testing/src/mocks/schema.mock.ts | 18 + 43 files changed, 30372 insertions(+), 846 deletions(-) create mode 100644 apps/sim/lib/file-parsers/complete-text.test.ts create mode 100644 apps/sim/lib/file-parsers/complete-text.ts create mode 100644 apps/sim/lib/workspace-files/search/README.md create mode 100644 apps/sim/lib/workspace-files/search/candidates.ts create mode 100644 apps/sim/lib/workspace-files/search/chunks.integration.ts create mode 100644 apps/sim/lib/workspace-files/search/index-plan.test.ts create mode 100644 apps/sim/lib/workspace-files/search/index-plan.ts create mode 100644 apps/sim/lib/workspace-files/search/index-state.ts create mode 100644 apps/sim/lib/workspace-files/search/indexing.test.ts create mode 100644 apps/sim/lib/workspace-files/search/sql-pattern.ts create mode 100644 packages/db/migrations/0359_workspace_file_search_chunks.sql create mode 100644 packages/db/migrations/meta/0359_snapshot.json diff --git a/apps/docs/content/docs/integrations/file.mdx b/apps/docs/content/docs/integrations/file.mdx index f62a9765458..3319978c8ba 100644 --- a/apps/docs/content/docs/integrations/file.mdx +++ b/apps/docs/content/docs/integrations/file.mdx @@ -77,7 +77,7 @@ Extract the text content of workspace files selected directly, identified by can ### File Search -Search the indexed text of active workspace files for lines matching a query, and return each matching line once with its file ID and line number. By default the query is a regular expression; in exact mode it is matched verbatim and metacharacters are literal. Coverage is what the index currently holds. A term that is not found is only authoritative when "complete" is true AND "indexStatus" reports no skipped or partial files; otherwise it is unknown rather than absent, so re-check before creating something on the assumption it is missing. Narrow the search with folderPaths to confine it to one or more folder trees, which also narrows "indexStatus" to those trees. +Search the indexed text of active workspace files for lines matching a query, and return each matching line once with its file ID and line number. By default the query is a regular expression; in exact mode it is matched verbatim and metacharacters are literal. Coverage is what the index currently holds. A term that is not found is only authoritative when "complete" is true AND "indexStatus" reports no skipped files; otherwise it is unknown rather than absent, so re-check before creating something on the assumption it is missing. Narrow the search with folderPaths to confine it to one or more folder trees, which also narrows "indexStatus" to those trees. #### Input @@ -99,13 +99,13 @@ Search the indexed text of active workspace files for lines matching a query, an | ↳ `text` | string | Matching line or bounded match-centered preview. | | `count` | number | Number of returned matching lines. | | `truncated` | boolean | Whether more matching lines exist beyond the configured hard cap. | -| `complete` | boolean | Whether indexing has no pending or failed current revisions; skipped and partial coverage is reported separately. | +| `complete` | boolean | Whether indexing has no pending or failed current revisions; excluded files are reported separately. | | `indexStatus` | object | Current workspace search-index coverage by file status. | -| ↳ `readyFiles` | number | Files whose current revision is searchable. | +| ↳ `readyFiles` | number | Files whose entire current extracted text is searchable. | | ↳ `pendingFiles` | number | Files still waiting to be indexed. | | ↳ `failedFiles` | number | Files whose current indexing attempt failed. | -| ↳ `skippedFiles` | number | Files intentionally excluded because they are unsupported or oversized. | -| ↳ `partialFiles` | number | Searchable files whose extracted text was truncated by the parser or cap. | +| ↳ `skippedFiles` | number | Files excluded in full because they are oversized, unsupported, or cannot be completely extracted. | +| ↳ `partialFiles` | number | Always zero; retained for compatibility. Files are never partially indexed. | ### File Fetch @@ -380,4 +380,14 @@ Move an existing workspace file into a folder. Moves the file itself; use Move F | `fileId` | string | The file that was moved. | | `folderPath` | string | The folder the file now lives in. | +{/* MANUAL-CONTENT-START:search_limits */} +## Search coverage and limits +Search indexes the complete extracted text of each eligible file. The source file and its extracted UTF-8 text must each be at most **25 MiB (26,214,400 bytes)**. Oversized files, unsupported binary formats, and documents that cannot be completely extracted within parser safety limits are excluded as whole files and counted in `skippedFiles`. Search never indexes only the first rows, lines, or characters. CSV search preserves decoded source text; spreadsheet search includes populated cells beyond the preview limits. Image-only documents require searchable text; search does not perform OCR. + +Existing parser safeguards also apply to complete extraction. PDFs allow at most 10,000 pages, 20 MiB of extracted text, 250,000 characters on one page, and 60 seconds of extraction. Office archives allow at most 150 MiB expanded in total, 64 MiB for one archive entry, and 10,000 entries; malformed archives and excessive compression ratios are rejected. Hitting any of these limits excludes the whole file from search. + +Updates are indexed asynchronously. `pendingFiles` and `failedFiles` indicate revisions that are not yet searchable; a new revision becomes searchable only when its full index is ready. An empty result proves absence only within the searched scope when `complete` is true and `skippedFiles` is zero. + +Regex is evaluated against complete logical lines, including long lines, and cannot span line breaks. Returned lines may use a shortened preview. The result limit (up to 200 lines) and a 10-second query deadline limit an individual request, not the amount of text indexed. An expensive query fails explicitly instead of returning an apparently complete subset; narrow its literal text or folder scope and retry. +{/* MANUAL-CONTENT-END */} diff --git a/apps/sim/lib/copilot/tools/server/files/doc-compile.ts b/apps/sim/lib/copilot/tools/server/files/doc-compile.ts index 525be693b82..41900a665ab 100644 --- a/apps/sim/lib/copilot/tools/server/files/doc-compile.ts +++ b/apps/sim/lib/copilot/tools/server/files/doc-compile.ts @@ -3,6 +3,7 @@ import { createLogger } from '@sim/logger' import { sha256Hex } from '@sim/security/hash' import { DocCompileUserError } from '@/lib/copilot/tools/server/files/doc-compile-error' import { + type CompiledDocReadOptions, loadCompiledDoc, loadPublishedCompiledDoc, publishCompiledDocArtifact, @@ -736,7 +737,7 @@ export async function loadCompiledDocByExt( workspaceId: string, source: string, ext: string, - options: { + options: CompiledDocReadOptions & { allowLegacyReferencedArtifact?: boolean allowPublishedReferencedArtifact?: boolean filePrincipal?: Principal @@ -744,18 +745,24 @@ export async function loadCompiledDocByExt( ): Promise<{ buffer: Buffer; contentType: string } | null> { const fmt = await getE2BDocFormat(`x.${ext}`) if (!fmt) return null + const readOptions: CompiledDocReadOptions = { maxBytes: options.maxBytes, signal: options.signal } const referencedFileIds = collectReferencedFileIds(source) if (!options.filePrincipal) { if (referencedFileIds.size === 0) { - const buffer = await loadCompiledDoc(workspaceId, source, fmt.ext) + const buffer = await loadCompiledDoc(workspaceId, source, fmt.ext, undefined, readOptions) return buffer ? { buffer, contentType: fmt.contentType } : null } if (options.allowPublishedReferencedArtifact) { - const publishedBuffer = await loadPublishedCompiledDoc(workspaceId, source, fmt.ext) + const publishedBuffer = await loadPublishedCompiledDoc( + workspaceId, + source, + fmt.ext, + readOptions + ) if (publishedBuffer) return { buffer: publishedBuffer, contentType: fmt.contentType } } if (!options.allowLegacyReferencedArtifact) return null - const legacyBuffer = await loadCompiledDoc(workspaceId, source, fmt.ext) + const legacyBuffer = await loadCompiledDoc(workspaceId, source, fmt.ext, undefined, readOptions) return legacyBuffer ? { buffer: legacyBuffer, contentType: fmt.contentType } : null } const referencedImages = await resolveReferencedImages( @@ -768,11 +775,12 @@ export async function loadCompiledDocByExt( workspaceId, source, fmt.ext, - referencedImages.artifactIdentity + referencedImages.artifactIdentity, + readOptions ) if (buffer) return { buffer, contentType: fmt.contentType } if (referencedImages.artifactIdentity && options.allowLegacyReferencedArtifact) { - const legacyBuffer = await loadCompiledDoc(workspaceId, source, fmt.ext) + const legacyBuffer = await loadCompiledDoc(workspaceId, source, fmt.ext, undefined, readOptions) if (legacyBuffer) return { buffer: legacyBuffer, contentType: fmt.contentType } } return null @@ -799,7 +807,8 @@ export type ServableDoc = export async function resolveServableDoc( workspaceId: string, storedBytes: Buffer, - fileName: string + fileName: string, + options: CompiledDocReadOptions = {} ): Promise { const fmt = await getE2BDocFormat(fileName) if (!fmt) return { kind: 'passthrough' } @@ -810,7 +819,7 @@ export async function resolveServableDoc( workspaceId, storedBytes.toString('utf-8'), fmt.ext, - { allowLegacyReferencedArtifact: true, allowPublishedReferencedArtifact: true } + { ...options, allowLegacyReferencedArtifact: true, allowPublishedReferencedArtifact: true } ) return artifact ? { kind: 'artifact', ...artifact } : { kind: 'unavailable' } } catch (error) { diff --git a/apps/sim/lib/copilot/tools/server/files/doc-compiled-store.test.ts b/apps/sim/lib/copilot/tools/server/files/doc-compiled-store.test.ts index 5fbaa13dbfb..0dec4e4d2ce 100644 --- a/apps/sim/lib/copilot/tools/server/files/doc-compiled-store.test.ts +++ b/apps/sim/lib/copilot/tools/server/files/doc-compiled-store.test.ts @@ -16,6 +16,7 @@ vi.mock('@/lib/uploads/core/storage-service', () => ({ })) import { + loadCompiledDoc, loadPublishedCompiledDoc, storeCompiledDoc, } from '@/lib/copilot/tools/server/files/doc-compiled-store' @@ -105,6 +106,35 @@ describe('compiled document publication', () => { ) }) + it('applies the caller budget and cancellation to both pointer and artifact downloads', async () => { + const signal = new AbortController().signal + const maxBytes = 25 * 1024 * 1024 + mockHeadObject.mockResolvedValue({ size: 1 }) + mockDownloadFile + .mockResolvedValueOnce( + Buffer.from(JSON.stringify({ version: 1, referencedInputIdentity: 'x'.repeat(8192) })) + ) + .mockResolvedValueOnce(Buffer.from('%PDF-artifact')) + + await loadPublishedCompiledDoc('workspace-1', 'source', 'pdf', { maxBytes, signal }) + + expect(mockDownloadFile).toHaveBeenCalledTimes(2) + for (const [options] of mockDownloadFile.mock.calls) { + expect(options).toMatchObject({ maxBytes, signal }) + } + }) + + it('does not turn an interrupted artifact download into a cache miss', async () => { + const controller = new AbortController() + mockDownloadFile.mockImplementationOnce(async () => { + controller.abort() + throw new Error('download interrupted') + }) + await expect( + loadCompiledDoc('workspace-1', 'source', 'pdf', undefined, { signal: controller.signal }) + ).rejects.toMatchObject({ name: 'AbortError' }) + }) + it('still reports a missing artifact as not yet built', async () => { mockHeadObject.mockResolvedValue({ size: 1 }) mockDownloadFile.mockResolvedValueOnce( diff --git a/apps/sim/lib/copilot/tools/server/files/doc-compiled-store.ts b/apps/sim/lib/copilot/tools/server/files/doc-compiled-store.ts index a35cb3f10b2..21e51e3361f 100644 --- a/apps/sim/lib/copilot/tools/server/files/doc-compiled-store.ts +++ b/apps/sim/lib/copilot/tools/server/files/doc-compiled-store.ts @@ -37,15 +37,32 @@ function publishedArtifactPointerKey(workspaceId: string, source: string, ext: s return `copilot-doc-compiled/${workspaceId}/${sourceHash}.${ext}.published.json` } +export interface CompiledDocReadOptions { + maxBytes?: number + signal?: AbortSignal +} + interface PublishedArtifactPointer { version: 1 referencedInputIdentity: string } -async function loadPublishedArtifactPointer(key: string): Promise { +async function loadPublishedArtifactPointer( + key: string, + options: CompiledDocReadOptions = {} +): Promise { + options.signal?.throwIfAborted() const stored = await headObject(key, 'copilot') if (!stored) return null - const encoded = await downloadFile({ key, context: 'copilot' }) + const encoded = await downloadFile({ + key, + context: 'copilot', + maxBytes: Math.min( + options.maxBytes ?? MAX_BUFFERED_TRANSFER_BYTES, + MAX_BUFFERED_TRANSFER_BYTES + ), + signal: options.signal, + }) let decoded: unknown try { @@ -75,11 +92,8 @@ async function loadPublishedArtifactPointer(key: string): Promise { const key = compiledArtifactKey(workspaceId, source, ext, referencedInputIdentity) try { - return await downloadFile({ key, context: 'copilot', maxBytes: MAX_BUFFERED_TRANSFER_BYTES }) + return await downloadFile({ + key, + context: 'copilot', + maxBytes: Math.min( + options.maxBytes ?? MAX_BUFFERED_TRANSFER_BYTES, + MAX_BUFFERED_TRANSFER_BYTES + ), + signal: options.signal, + }) } catch (error) { + options.signal?.throwIfAborted() if (isPayloadSizeLimitError(error)) throw error return null } @@ -140,12 +164,19 @@ export async function publishCompiledDocArtifact( export async function loadPublishedCompiledDoc( workspaceId: string, source: string, - ext: string + ext: string, + options: CompiledDocReadOptions = {} ): Promise { const key = publishedArtifactPointerKey(workspaceId, source, ext) - const pointer = await loadPublishedArtifactPointer(key) + const pointer = await loadPublishedArtifactPointer(key, options) if (!pointer) return null - const artifact = await loadCompiledDoc(workspaceId, source, ext, pointer.referencedInputIdentity) + const artifact = await loadCompiledDoc( + workspaceId, + source, + ext, + pointer.referencedInputIdentity, + options + ) if (!artifact) throw new Error(`Published compiled document artifact is missing: ${key}`) return artifact } diff --git a/apps/sim/lib/copilot/tools/server/files/doc-servable.test.ts b/apps/sim/lib/copilot/tools/server/files/doc-servable.test.ts index 336ebe43491..87432887d62 100644 --- a/apps/sim/lib/copilot/tools/server/files/doc-servable.test.ts +++ b/apps/sim/lib/copilot/tools/server/files/doc-servable.test.ts @@ -96,7 +96,9 @@ describe('resolveServableDocBytes', () => { expect(mockLoadCompiledDoc).toHaveBeenCalledWith( WORKSPACE_ID, PDF_SOURCE.toString('utf-8'), - 'pdf' + 'pdf', + undefined, + { maxBytes: undefined, signal: undefined } ) expect(mockLoadCompiledDoc).toHaveBeenCalledTimes(1) }) @@ -123,7 +125,9 @@ describe('resolveServableDocBytes', () => { expect(mockLoadCompiledDoc).toHaveBeenCalledWith( WORKSPACE_ID, PDF_SOURCE.toString('utf-8'), - 'pdf' + 'pdf', + undefined, + { maxBytes: undefined, signal: undefined } ) }) @@ -202,7 +206,13 @@ describe('resolveServableDocBytes', () => { buffer: legacyArtifact, contentType: 'application/pdf', }) - expect(mockLoadCompiledDoc).toHaveBeenCalledWith(WORKSPACE_ID, source.toString('utf-8'), 'pdf') + expect(mockLoadCompiledDoc).toHaveBeenCalledWith( + WORKSPACE_ID, + source.toString('utf-8'), + 'pdf', + undefined, + { maxBytes: undefined, signal: undefined } + ) expect(mockReadWorkspaceFileMetadata).not.toHaveBeenCalled() expect(mockExecuteInSandbox).not.toHaveBeenCalled() expect(mockStoreCompiledDoc).not.toHaveBeenCalled() @@ -221,7 +231,8 @@ describe('resolveServableDocBytes', () => { expect(mockLoadPublishedCompiledDoc).toHaveBeenCalledWith( WORKSPACE_ID, source.toString('utf-8'), - 'pdf' + 'pdf', + { maxBytes: undefined, signal: undefined } ) expect(mockLoadCompiledDoc).not.toHaveBeenCalled() expect(mockReadWorkspaceFileMetadata).not.toHaveBeenCalled() @@ -242,7 +253,8 @@ describe('resolveServableDocBytes', () => { expect(mockLoadPublishedCompiledDoc).toHaveBeenCalledWith( WORKSPACE_ID, source.toString('utf-8'), - 'pdf' + 'pdf', + { maxBytes: undefined, signal: undefined } ) expect(mockLoadCompiledDoc).not.toHaveBeenCalled() }) @@ -307,7 +319,13 @@ describe('resolveServableDocBytes', () => { contentType: 'application/pdf', }) expect(mockReadWorkspaceFileMetadata).not.toHaveBeenCalled() - expect(mockLoadCompiledDoc).toHaveBeenCalledWith(WORKSPACE_ID, source.toString('utf-8'), 'pdf') + expect(mockLoadCompiledDoc).toHaveBeenCalledWith( + WORKSPACE_ID, + source.toString('utf-8'), + 'pdf', + undefined, + { maxBytes: undefined, signal: undefined } + ) expect(mockExecuteInSandbox).not.toHaveBeenCalled() }) diff --git a/apps/sim/lib/file-parsers/complete-text.test.ts b/apps/sim/lib/file-parsers/complete-text.test.ts new file mode 100644 index 00000000000..63397bdf795 --- /dev/null +++ b/apps/sim/lib/file-parsers/complete-text.test.ts @@ -0,0 +1,91 @@ +import JSZip from 'jszip' +import { describe, expect, it, vi } from 'vitest' +import * as XLSX from 'xlsx' +import { CompleteTextBuilder } from '@/lib/file-parsers/complete-text' +import { CsvParser } from '@/lib/file-parsers/csv-parser' +import { XlsxParser } from '@/lib/file-parsers/xlsx-parser' + +describe('complete extraction for search', () => { + it('counts UTF-8 bytes before retaining output', () => { + const text = new CompleteTextBuilder(8) + text.append('🙂🙂') + expect(() => text.append('a')).toThrow('byte budget') + expect(text.finish()).toBe('🙂🙂') + }) + it('preserves CSV rows after the preview boundary and duplicate columns', async () => { + const text = `name,name\n${'first,second\n'.repeat(1001)}last,tail\n` + const result = await new CsvParser().parseBuffer(Buffer.from(text), { + contentMode: 'complete', + maxTextBytes: 25000, + }) + expect(result.content).toContain('last,tail') + expect(result.content).toContain('first,second') + expect(result.metadata?.truncated).toBe(false) + expect(result.content.split('\n')).toHaveLength(1004) + }) + it('rejects CSV output instead of returning a prefix', async () => { + await expect( + new CsvParser().parseBuffer(Buffer.from('a,b\nc,d'), { + contentMode: 'complete', + maxTextBytes: 6, + }) + ).rejects.toThrow('byte budget') + }) + it('cancels complete CSV extraction', async () => { + await expect( + new CsvParser().parseBuffer(Buffer.from('a,b'), { + contentMode: 'complete', + signal: AbortSignal.abort(), + }) + ).rejects.toThrow() + }) + it('reads sparse spreadsheet cells beyond both preview limits without expanding the rectangle', async () => { + const sheet: XLSX.WorkSheet = { + A1: { t: 's', v: 'header' }, + ZZ1001: { t: 's', v: 'tail needle' }, + '!ref': 'A1:ZZ1001', + } + const workbook = XLSX.utils.book_new() + XLSX.utils.book_append_sheet(workbook, sheet, 'Data') + const zip = await JSZip.loadAsync(XLSX.write(workbook, { type: 'buffer', bookType: 'xlsx' })) + const xml = await zip.file('xl/worksheets/sheet1.xml')!.async('string') + zip.file( + 'xl/worksheets/sheet1.xml', + xml.replace(//, '') + ) + const buffer = await zip.generateAsync({ type: 'nodebuffer' }) + const result = await new XlsxParser().parseBuffer(buffer, { + contentMode: 'complete', + maxTextBytes: 25000, + }) + expect(result.content).toContain('tail needle') + expect(result.metadata?.truncated).toBe(false) + expect(result.content.length).toBeLessThan(25000) + }) + it('stops a shared-string row before materializing every expanded cell', async () => { + const workbook = XLSX.utils.book_new() + XLSX.utils.book_append_sheet( + workbook, + XLSX.utils.aoa_to_sheet([Array(20).fill('x'.repeat(20000))]), + 'Data' + ) + const buffer = XLSX.write(workbook, { type: 'buffer', bookType: 'xlsx', bookSST: true }) + const format = vi.spyOn(XLSX.utils, 'format_cell') + try { + await expect( + new XlsxParser().parseBuffer(buffer, { contentMode: 'complete', maxTextBytes: 50000 }) + ).rejects.toThrow('byte budget') + expect(format.mock.calls.length).toBeLessThan(20) + } finally { + format.mockRestore() + } + }) + it('rejects spreadsheet output exceeding the caller byte budget', async () => { + const workbook = XLSX.utils.book_new() + XLSX.utils.book_append_sheet(workbook, XLSX.utils.aoa_to_sheet([['hello', 'world']]), 'Data') + const buffer = XLSX.write(workbook, { type: 'buffer', bookType: 'xlsx' }) + await expect( + new XlsxParser().parseBuffer(buffer, { contentMode: 'complete', maxTextBytes: 10 }) + ).rejects.toThrow('byte budget') + }) +}) diff --git a/apps/sim/lib/file-parsers/complete-text.ts b/apps/sim/lib/file-parsers/complete-text.ts new file mode 100644 index 00000000000..661dc03d8fa --- /dev/null +++ b/apps/sim/lib/file-parsers/complete-text.ts @@ -0,0 +1,37 @@ +import { Buffer } from 'node:buffer' +import { FileParserError } from '@/lib/file-parsers/errors' + +/** Bounds both text bytes and retained string fragments while extracting complete documents. */ +export class CompleteTextBuilder { + private readonly parts: string[] = [] + private pending = '' + private pendingBytes = 0 + private bytes = 0 + + constructor(private readonly maxBytes = 25 * 1024 * 1024) { + if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) + throw new Error('Invalid extraction byte budget') + } + + append(text: string): void { + const bytes = Buffer.byteLength(text, 'utf8') + if (this.bytes + bytes > this.maxBytes) { + throw new FileParserError( + 'complexity_limit', + 'Complete text extraction exceeds its byte budget' + ) + } + this.bytes += bytes + this.pending += text + this.pendingBytes += bytes + if (this.pendingBytes >= 64 * 1024) { + this.parts.push(this.pending) + this.pending = '' + this.pendingBytes = 0 + } + } + + finish(): string { + return this.parts.join('') + this.pending + } +} diff --git a/apps/sim/lib/file-parsers/csv-parser.ts b/apps/sim/lib/file-parsers/csv-parser.ts index bec222e1f95..dc58b46a0c3 100644 --- a/apps/sim/lib/file-parsers/csv-parser.ts +++ b/apps/sim/lib/file-parsers/csv-parser.ts @@ -3,8 +3,9 @@ import { readFile } from 'fs/promises' import { Readable } from 'stream' import { createLogger } from '@sim/logger' import { type Options, parse } from 'csv-parse' +import { CompleteTextBuilder } from '@/lib/file-parsers/complete-text' import { FileParserError } from '@/lib/file-parsers/errors' -import type { FileParseResult, FileParser } from '@/lib/file-parsers/types' +import type { FileParseOptions, FileParseResult, FileParser } from '@/lib/file-parsers/types' import { type DecodedText, decodeTextBuffer, @@ -29,7 +30,7 @@ export class CsvParser implements FileParser { * caps already bound the file, and `parseBuffer` — the production path — * always held the full buffer. */ - async parseFile(filePath: string): Promise { + async parseFile(filePath: string, options: FileParseOptions = {}): Promise { if (!filePath) { throw new Error('No file path provided') } @@ -38,16 +39,17 @@ export class CsvParser implements FileParser { throw new Error(`File not found: ${filePath}`) } - return this.parseBuffer(await readFile(filePath)) + return this.parseBuffer(await readFile(filePath), options) } - async parseBuffer(buffer: Buffer): Promise { + async parseBuffer(buffer: Buffer, options: FileParseOptions = {}): Promise { const bufferSize = buffer.length logger.info( `Parsing CSV buffer, size: ${bufferSize} bytes (${(bufferSize / 1024 / 1024).toFixed(2)} MB)` ) const decoded = decodeTextBuffer(buffer) + if (options.contentMode === 'complete') return this.parseComplete(decoded, options) const stream = new Readable({ read() {} }) stream.push(decoded.text) stream.push(null) @@ -55,6 +57,17 @@ export class CsvParser implements FileParser { return this.parseStream(stream, decoded) } + /** Search preserves the source text without allocating a cell object for every CSV field. */ + private parseComplete(decoded: DecodedText, options: FileParseOptions): FileParseResult { + options.signal?.throwIfAborted() + const content = new CompleteTextBuilder(options.maxTextBytes) + content.append(sanitizeTextForUTF8(decoded.text)) + return { + content: content.finish(), + metadata: { encoding: decoded.encoding, truncated: false }, + } + } + private parseStream( inputStream: NodeJS.ReadableStream, decoded: DecodedText diff --git a/apps/sim/lib/file-parsers/types.ts b/apps/sim/lib/file-parsers/types.ts index 028e2e7382b..f2d44ecb3aa 100644 --- a/apps/sim/lib/file-parsers/types.ts +++ b/apps/sim/lib/file-parsers/types.ts @@ -33,6 +33,9 @@ export interface FileParseResult { export interface FileParseOptions { signal?: AbortSignal + /** Indexing callers require complete extraction; preview row limits must not discard content. */ + contentMode?: 'preview' | 'complete' + maxTextBytes?: number /** Preserve textual markup in a canonical .txt artifact instead of interpreting it as HTML or RTF. */ textMode?: 'literal' /** Complete PDF extraction rejects safety limits instead of returning preview text. */ diff --git a/apps/sim/lib/file-parsers/xlsx-parser.ts b/apps/sim/lib/file-parsers/xlsx-parser.ts index f3eef4566c7..05278f8aef5 100644 --- a/apps/sim/lib/file-parsers/xlsx-parser.ts +++ b/apps/sim/lib/file-parsers/xlsx-parser.ts @@ -3,6 +3,7 @@ import { readFile } from 'fs/promises' import { createLogger } from '@sim/logger' import { truncate } from '@sim/utils/string' import * as XLSX from 'xlsx' +import { CompleteTextBuilder } from '@/lib/file-parsers/complete-text' import { FileParserError, isEncryptedOfficeParserError, @@ -12,7 +13,7 @@ import { normalizeSheetDisplayText, SHEET_DISPLAY_READ_OPTIONS, } from '@/lib/file-parsers/sheet-display-text' -import type { FileParseResult, FileParser } from '@/lib/file-parsers/types' +import type { FileParseOptions, FileParseResult, FileParser } from '@/lib/file-parsers/types' import { sanitizeTextForUTF8, truncationNotice } from '@/lib/file-parsers/utils' import { assertOoxmlArchiveWithinLimits } from '@/lib/file-parsers/zip-guard' @@ -50,7 +51,7 @@ export class XlsxParser implements FileParser { * Read the file into a buffer and delegate to {@link parseBuffer} so the * decompression-bomb guard runs before SheetJS inflates the workbook. */ - async parseFile(filePath: string): Promise { + async parseFile(filePath: string, options: FileParseOptions = {}): Promise { if (!filePath) { throw new Error('No file path provided') } @@ -62,10 +63,10 @@ export class XlsxParser implements FileParser { logger.info(`Parsing XLSX file: ${filePath}`) const buffer = await readFile(filePath) - return this.parseBuffer(buffer) + return this.parseBuffer(buffer, options) } - async parseBuffer(buffer: Buffer): Promise { + async parseBuffer(buffer: Buffer, options: FileParseOptions = {}): Promise { try { const bufferSize = buffer.length logger.info( @@ -85,7 +86,9 @@ export class XlsxParser implements FileParser { ...SHEET_DISPLAY_READ_OPTIONS, }) - return this.processWorkbook(workbook) + return options.contentMode === 'complete' + ? this.processCompleteWorkbook(workbook, options) + : this.processWorkbook(workbook) } catch (error) { logger.error('XLSX buffer parsing error:', error) if (isEncryptedOfficeParserError(error)) { @@ -99,6 +102,61 @@ export class XlsxParser implements FileParser { } } + /** Visits populated cells, never the possibly enormous declared worksheet rectangle. */ + private processCompleteWorkbook( + workbook: XLSX.WorkBook, + options: FileParseOptions + ): FileParseResult { + const content = new CompleteTextBuilder(options.maxTextBytes) + let rowCount = 0 + for (const sheetName of workbook.SheetNames) { + options.signal?.throwIfAborted() + const sheet = workbook.Sheets[sheetName] + const data: (XLSX.CellObject[] | undefined)[] | undefined = sheet['!data'] + if (!data) { + if (!sheet['!ref']) continue + throw new FileParserError( + 'runtime_failure', + 'Complete spreadsheet extraction requires dense cell data' + ) + } + content.append(`\n=== Sheet: ${sanitizeTextForUTF8(sheetName)} ===\n`) + for (const rowKey in data) { + if (!Object.hasOwn(data, rowKey) || !/^\d+$/.test(rowKey)) continue + options.signal?.throwIfAborted() + const row = data[Number(rowKey)] + if (!row) continue + const rowText = new CompleteTextBuilder(options.maxTextBytes) + let previousColumn = -1 + let meaningful = false + for (const columnKey in row) { + if (!Object.hasOwn(row, columnKey) || !/^\d+$/.test(columnKey)) continue + const column = Number(columnKey) + if (column > 16383) + throw new FileParserError( + 'complexity_limit', + 'Spreadsheet column exceeds the Excel format limit' + ) + const cell = row[column] + if (!cell || cell.t === 'z') continue + const address = { r: Number(rowKey), c: column } + normalizeSheetDisplayText(sheet, { s: address, e: address }, XLSX.utils) + const value = this.truncateCell(XLSX.utils.format_cell(cell)) + rowText.append('\t'.repeat(previousColumn < 0 ? column : column - previousColumn)) + rowText.append(value) + previousColumn = column + meaningful ||= value.trim().length > 0 + } + if (meaningful) { + content.append(rowText.finish()) + content.append('\n') + rowCount++ + } + } + } + return { content: content.finish(), metadata: { rowCount, truncated: false } } + } + private processWorkbook(workbook: XLSX.WorkBook): FileParseResult { const sheetNames = workbook.SheetNames let content = '' diff --git a/apps/sim/lib/workspace-files/search/README.md b/apps/sim/lib/workspace-files/search/README.md new file mode 100644 index 00000000000..1795c3b0b7a --- /dev/null +++ b/apps/sim/lib/workspace-files/search/README.md @@ -0,0 +1,46 @@ +# Workspace file search + +PostgreSQL stores complete extracted text in bounded chunks. Object storage remains the source of truth. A source and its extracted UTF-8 text must each fit within 25 MiB. Unsupported, degraded, oversized, or partially extracted files are excluded in full. There is no row-count or line-count coverage limit. + +## Storage and publication + +- `workspace_file_search_revision` has one current state row per file. The `build_id` identifies the attempt; only `ready` builds are visible to search. +- `workspace_file_search_build` owns an immutable chunk set. Workers receive a fresh build ID on each attempt. An unpublished build has a 20-minute lease; a published build has no expiry. +- `workspace_file_search_chunk` packs complete short lines into at most 8 KiB of UTF-8 text. Long lines use fragments with a two-code-point overlap and the same logical line number. PostgreSQL enforces the byte bound. No large document is stored as one text value. + +8 KiB values may still use PostgreSQL TOAST. The bound controls the size of each logical value and detoast operation; avoiding TOAST entirely is not the objective. Tiny lines share rows, so row count scales with bytes instead of newline count. Worst-case line packing can leave roughly half a block unused; long-line overlap adds at most eight bytes per fragment. + +Workers download and extract outside database transactions, then insert batches of at most 250 rows / 1 MiB. Each batch checks the build token and lease. Publication locks the canonical file, build, and revision in that order, verifies the stored chunk count, and changes the visible pointer only after every batch succeeds. Old dispatch failure callbacks cannot overwrite newer dispatches or successful builds. + +File edits, context changes, and deletion invalidate metadata and expire builds. Chunks have no cascading foreign key to files or workspaces. Cleanup locks at most 100 expired builds with `SKIP LOCKED`, deletes at most 1,000 chunks per transaction, retires empty builds in the same batch, and stops after 10 batches or five seconds. Dispatch pauses while at least 10,000 expired chunks await cleanup, so sustained revisions cannot keep admitting new builds faster than retirement can drain them. Existing ready files remain searchable. Stale workers cannot revive a reclaimed build. + +## Search + +Search joins the current file revision and resolved workspace/folder scope. A repeatable-read transaction prevents a search from combining revisions while a file changes. The composite workspace/text GIN index supplies candidate chunks. An unordered probe retains at most 257 candidate headers. If it exhausts the candidates, those headers are sorted and verified. If it overflows, an ordered file scan retrieves at most 16 candidate headers per page using the build/line B-tree index. This avoids sorting or detoasting every matching chunk for common terms. Both paths return unique lines ordered by file name, file ID, and line number. + +For regular chunks, PostgreSQL checks the pattern with newline-aware semantics, then verifies individual logical lines. Long-line fragments use only necessary three-character literals as a conservative prefilter, including all required alternation branches. Two-code-point overlap preserves those literals at every boundary. PostgreSQL reconstructs the complete candidate line and evaluates the original regex, so anchors, word boundaries, repetitions, and arbitrarily long match spans retain line semantics. Fixed overlap alone is never treated as proof of a match. The supported regex grammar and minimum literal requirement are unchanged. + +Regular blocks are verified in batches of at most 16 (128 KiB of indexed text); long lines are reconstructed one at a time. Only bounded match-centered previews leave PostgreSQL: at most 201 rows to detect truncation, and at most 2 KiB per rendered result. A single search has a ten-second deadline. Transaction advisory locks admit at most two simultaneous searches per workspace and ten globally per database. Busy and timed-out searches fail explicitly; they never report an incomplete scan as an authoritative empty result. The reader uses the normal application database connection, so admission is coordinated on the same database as the index. + +Arbitrary regex cannot have a fixed latency guarantee. Common terms, broad alternatives, and punctuation-only literals may require scanning significant scoped text. Larger capacity decisions need representative query plans and workload measurements; neither a per-file byte cap nor a PostgreSQL row-count claim establishes a total corpus capacity. + +## Rollout and retirement + +1. Deploy the additive migration and new application/Trigger worker versions. Legacy index tables remain readable for the old deployment. The file trigger queues current revisions in the new table; this cutover intentionally allows temporary search unavailability while the new index builds. +2. The dispatcher uses a separate `workspace-file-search-chunks-v2` backfill cursor. It seeds at most 1,000 active files per pass under a shared file lock, with idempotent inserts. Normal dispatch caps remain two outstanding jobs per workspace, 100 outstanding globally, and ten running workers. Reconciliation repeats hourly after a complete pass to repair missing metadata. Failed revisions remain visible as failed; they are not silently declared covered. +3. Before retiring legacy storage, verify the new app and Trigger workers are fully deployed, old runs/retries have drained, the backfill cursor has completed, and scoped coverage is ready or explicitly excluded. Investigate failed or stale pending revisions. Check cleanup backlog and run representative exact/regex searches, including long lines and folder scopes. +4. After the rollback window, ship a separate contract PR removing the legacy schema and dropping `workspace_file_search_segment` / `workspace_file_search_index` with a short lock timeout. Do not delete the entire old index row-by-row or backfill it inside the schema migration. Dropping obsolete tables reclaims their heap, indexes, and TOAST together. The `contract-pending` marker in `packages/db/schema.ts` tracks this step. + +Until that contract deploy, legacy foreign-key cascades can still make a hard file/workspace deletion expensive. New-index cleanup is bounded; retaining the old schema cannot erase that legacy cost. The earlier timestamp-repair script detects the chunk schema and leaves obsolete legacy text for this contract step instead of deleting it in bulk. No production cleanup is part of this PR. + +Rollback before retirement requires restoring the old trigger function as well as the old app/worker version, and reconciling legacy revisions written during the cutover. Do not assume retained tables are automatically up to date. Canonical revision joins prevent stale content from being returned. + +## Verification + +Run unit tests in `apps/sim` with `bunx vitest run lib/workspace-files/search lib/file-parsers`. Run the PostgreSQL suites against a disposable local database through `KNOWLEDGE_ACL_TEST_DATABASE_URL` and `--mode integration`. `chunks.integration.ts` applies the actual trigger migrations in an isolated schema. It covers build fencing, revision changes, deletion, cleanup bounds, complete-line matching, UTF-8 boundaries, scope, and admission limits. + +Set `FILE_SEARCH_BENCHMARK_FILES` to change the synthetic file count (default 1,000, maximum 10,000). Set `FILE_SEARCH_BENCHMARK_OUTPUT` to an output path when running the chunk integration suite to record repeated end-to-end searches and `EXPLAIN (ANALYZE, BUFFERS)` plans on a synthetic multi-file corpus. The fixture is synthetic; it contains no production content. + +## PostgreSQL references + +The design uses PostgreSQL's documented [TOAST behavior](https://www.postgresql.org/docs/17/storage-toast.html), [trigram index support for LIKE and regex](https://www.postgresql.org/docs/17/pgtrgm.html), and [EXPLAIN guidance](https://www.postgresql.org/docs/17/using-explain.html). The chunk size and query paths are application choices validated by the synthetic fixture, not PostgreSQL hard limits. diff --git a/apps/sim/lib/workspace-files/search/candidates.ts b/apps/sim/lib/workspace-files/search/candidates.ts new file mode 100644 index 00000000000..8a218320055 --- /dev/null +++ b/apps/sim/lib/workspace-files/search/candidates.ts @@ -0,0 +1,186 @@ +import { + workspaceFileSearchChunk, + workspaceFileSearchRevision, + workspaceFiles, +} from '@sim/db/schema' +import { and, asc, eq, isNull, or, type SQL, sql } from 'drizzle-orm' +import type { DbTransaction } from '@/lib/db/types' +import { + FILE_SEARCH_CANDIDATE_PAGE_SIZE, + FILE_SEARCH_CANDIDATE_PROBE_SIZE, +} from '@/lib/workspace-files/search/constants' +import type { CompiledFileSearchPattern } from '@/lib/workspace-files/search/pattern' +import { buildMatchExpression } from '@/lib/workspace-files/search/sql-pattern' + +export interface FileSearchCandidate { + fileId: string + fileName: string + fileKey: string + ownerUserId: string + contentUpdatedAt: Date + buildId: string + ordinal: number + lineStart: number + fragment: boolean +} + +interface CandidateScope { + workspaceId: string + pattern: CompiledFileSearchPattern + folderPredicate?: SQL +} + +interface CandidateCursor { + name: string + id: string + lineStart: number +} + +/** Native regex on complete-line blocks; necessary literals across overlapping long-line fragments. */ +function candidatePredicate(pattern: CompiledFileSearchPattern): SQL { + const chunk = workspaceFileSearchChunk + const fragmentMatch = + pattern.candidatePatterns === null + ? sql`true` + : or( + ...pattern.candidatePatterns.map((seed) => + pattern.caseSensitive + ? sql`${chunk.content} LIKE ${seed}` + : sql`${chunk.content} ILIKE ${seed}` + ) + )! + return and( + fragmentMatch, + or(eq(chunk.fragment, true), buildMatchExpression(chunk.content, pattern, true)) + )! +} + +/** Bounded unordered probe avoids sorting all matching text for broad queries. */ +export async function probeFileSearchCandidates( + tx: DbTransaction, + { workspaceId, pattern, folderPredicate }: CandidateScope +): Promise { + const probe = tx + .select({ + fileId: workspaceFiles.id, + fileName: workspaceFiles.originalName, + fileKey: workspaceFiles.key, + ownerUserId: workspaceFiles.userId, + contentUpdatedAt: workspaceFiles.contentUpdatedAt, + buildId: workspaceFileSearchChunk.buildId, + ordinal: workspaceFileSearchChunk.ordinal, + lineStart: workspaceFileSearchChunk.lineStart, + fragment: workspaceFileSearchChunk.fragment, + }) + .from(workspaceFileSearchChunk) + .innerJoin( + workspaceFileSearchRevision, + and( + eq(workspaceFileSearchRevision.buildId, workspaceFileSearchChunk.buildId), + eq(workspaceFileSearchRevision.workspaceId, workspaceId), + eq(workspaceFileSearchRevision.status, 'ready') + ) + ) + .innerJoin( + workspaceFiles, + and( + eq(workspaceFiles.id, workspaceFileSearchRevision.fileId), + eq(workspaceFiles.contentUpdatedAt, workspaceFileSearchRevision.sourceContentUpdatedAt) + ) + ) + .where( + and( + eq(workspaceFileSearchChunk.workspaceId, workspaceId), + eq(workspaceFiles.workspaceId, workspaceId), + eq(workspaceFiles.context, 'workspace'), + isNull(workspaceFiles.deletedAt), + folderPredicate, + candidatePredicate(pattern) + ) + ) + .limit(FILE_SEARCH_CANDIDATE_PROBE_SIZE + 1) + .as('probe') + return tx + .select() + .from(probe) + .orderBy(asc(probe.fileName), asc(probe.fileId), asc(probe.lineStart), asc(probe.ordinal)) +} + +/** A parameterized build scan preserves file order and can stop after one candidate page. */ +export async function readOrderedFileSearchCandidates( + tx: DbTransaction, + { workspaceId, pattern, folderPredicate }: CandidateScope, + after?: CandidateCursor +): Promise { + /** OFFSET 0 preserves the ordered file input instead of flattening into a global text scan. */ + const files = tx + .select({ + fileId: workspaceFiles.id, + fileName: workspaceFiles.originalName, + fileKey: workspaceFiles.key, + ownerUserId: workspaceFiles.userId, + contentUpdatedAt: workspaceFiles.contentUpdatedAt, + buildId: workspaceFileSearchRevision.buildId, + }) + .from(workspaceFiles) + .innerJoin( + workspaceFileSearchRevision, + and( + eq(workspaceFileSearchRevision.fileId, workspaceFiles.id), + eq(workspaceFileSearchRevision.workspaceId, workspaceId), + eq(workspaceFileSearchRevision.sourceContentUpdatedAt, workspaceFiles.contentUpdatedAt), + eq(workspaceFileSearchRevision.status, 'ready') + ) + ) + .where( + and( + eq(workspaceFiles.workspaceId, workspaceId), + eq(workspaceFiles.context, 'workspace'), + isNull(workspaceFiles.deletedAt), + folderPredicate, + after + ? sql`(${workspaceFiles.originalName}, ${workspaceFiles.id}) >= (${after.name}, ${after.id})` + : undefined + ) + ) + .orderBy(asc(workspaceFiles.originalName), asc(workspaceFiles.id)) + .offset(0) + .as('files') + const chunks = tx + .select({ + buildId: workspaceFileSearchChunk.buildId, + ordinal: workspaceFileSearchChunk.ordinal, + lineStart: workspaceFileSearchChunk.lineStart, + fragment: workspaceFileSearchChunk.fragment, + }) + .from(workspaceFileSearchChunk) + .where( + and( + eq(workspaceFileSearchChunk.buildId, files.buildId), + eq(workspaceFileSearchChunk.workspaceId, workspaceId), + candidatePredicate(pattern), + after + ? sql`(${files.fileName}, ${files.fileId}, ${workspaceFileSearchChunk.lineStart}) > (${after.name}, ${after.id}, ${after.lineStart})` + : undefined + ) + ) + .orderBy(asc(workspaceFileSearchChunk.lineStart), asc(workspaceFileSearchChunk.ordinal)) + .limit(FILE_SEARCH_CANDIDATE_PAGE_SIZE) + .as('chunks') + return tx + .select({ + fileId: files.fileId, + fileName: files.fileName, + fileKey: files.fileKey, + ownerUserId: files.ownerUserId, + contentUpdatedAt: files.contentUpdatedAt, + buildId: chunks.buildId, + ordinal: chunks.ordinal, + lineStart: chunks.lineStart, + fragment: chunks.fragment, + }) + .from(files) + .innerJoinLateral(chunks, sql`true`) + .orderBy(asc(files.fileName), asc(files.fileId), asc(chunks.lineStart), asc(chunks.ordinal)) + .limit(FILE_SEARCH_CANDIDATE_PAGE_SIZE) +} diff --git a/apps/sim/lib/workspace-files/search/chunks.integration.ts b/apps/sim/lib/workspace-files/search/chunks.integration.ts new file mode 100644 index 00000000000..ad08bcf81d7 --- /dev/null +++ b/apps/sim/lib/workspace-files/search/chunks.integration.ts @@ -0,0 +1,467 @@ +import { createHash } from 'node:crypto' +import { readFileSync, writeFileSync } from 'node:fs' +import { resolve } from 'node:path' +import { withUtcTimestamps } from '@sim/db/timestamps' +import { generateId } from '@sim/utils/id' +import { drizzle, type PostgresJsDatabase } from 'drizzle-orm/postgres-js' +import postgres from 'postgres' +import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest' + +const database = vi.hoisted(() => ({ current: undefined as PostgresJsDatabase | undefined })) +vi.mock('@sim/db', () => ({ + get db() { + if (!database.current) throw new Error('Test database not initialized') + return database.current + }, +})) +vi.mock('@/lib/uploads/contexts/workspace', () => ({ + getWorkspaceFile: vi.fn(), + fetchWorkspaceFileBuffer: vi.fn(), +})) +vi.mock('@/lib/copilot/tools/server/files/doc-compile', () => ({ resolveServableDoc: vi.fn() })) +vi.mock('@/lib/file-parsers', () => ({ parseBuffer: vi.fn(), isSupportedFileType: vi.fn() })) + +import { + FILE_SEARCH_CLEANUP_BATCH_ROWS, + FILE_SEARCH_CLEANUP_MAX_BATCHES, +} from '@/lib/workspace-files/search/constants' +import { prepareWorkspaceFileSearchDispatch } from '@/lib/workspace-files/search/dispatcher' +import { + iterateFileSearchChunks, + planFileSearchIndex, +} from '@/lib/workspace-files/search/index-plan' +import { + appendFileSearchChunks, + beginFileSearchBuild, + cleanupFileSearchBuilds, + type FileSearchRevision, + failFileSearchRevision, + publishFileSearchBuild, +} from '@/lib/workspace-files/search/index-state' +import { compileFileSearchPattern } from '@/lib/workspace-files/search/pattern' +import { searchWorkspaceFileIndex } from '@/lib/workspace-files/search/repository' + +const signal = new AbortController().signal +const revision: FileSearchRevision = { + workspaceId: 'workspace-1', + fileId: 'file-1', + sourceContentUpdatedAt: new Date('2026-01-01T00:00:00Z'), +} + +describe('chunked workspace file search on PostgreSQL', () => { + const schema = `chunk_test_${generateId().replaceAll('-', '')}` + const databaseUrl = process.env.KNOWLEDGE_ACL_TEST_DATABASE_URL + if (!databaseUrl) throw new Error('Use a disposable local database') + const connection = postgres( + databaseUrl, + withUtcTimestamps({ + max: 4, + prepare: false, + fetch_types: false, + connection: { search_path: `${schema},public` }, + onnotice: () => {}, + }) + ) + + async function addFile( + fileId: string, + workspaceId = 'workspace-1', + name = fileId, + folder: string | null = null + ) { + await connection`INSERT INTO workspace (id) VALUES (${workspaceId}) ON CONFLICT DO NOTHING` + await connection`INSERT INTO workspace_files (id, workspace_id, context, content_updated_at, original_name, folder_id) + VALUES (${fileId}, ${workspaceId}, 'workspace', ${revision.sourceContentUpdatedAt.toISOString()}::timestamp, ${name}, ${folder})` + return { ...revision, fileId, workspaceId } + } + async function index(text: string, target = revision) { + const build = await beginFileSearchBuild(target) + expect(build).not.toBeNull() + const plan = planFileSearchIndex({ text, partial: false }, signal) + const chunks = [...iterateFileSearchChunks(plan, signal)] + for (let offset = 0; offset < chunks.length; offset += 100) + expect(await appendFileSearchChunks(build!, chunks.slice(offset, offset + 100), signal)).toBe( + true + ) + expect( + await publishFileSearchBuild( + build!, + { + status: 'ready', + chunkCount: chunks.length, + lineCount: plan.lineCount, + indexedBytes: plan.indexedBytes, + }, + signal + ) + ).toBe(true) + return build! + } + const search = (query: string, mode: 'exact' | 'regex' = 'exact', maxResults = 200) => + searchWorkspaceFileIndex({ + workspaceId: 'workspace-1', + pattern: compileFileSearchPattern(query, mode), + maxResults, + signal, + }) + + const capturedQueries = new Map() + let captureQuery = false + + beforeAll(async () => { + await connection`CREATE SCHEMA ${connection(schema)}` + await connection`CREATE TABLE workspace (id text PRIMARY KEY)` + await connection`CREATE TABLE workspace_files (id text PRIMARY KEY, workspace_id text REFERENCES workspace(id) ON DELETE CASCADE, + context text NOT NULL, content_updated_at timestamp NOT NULL, deleted_at timestamp, + original_name text NOT NULL, key text NOT NULL DEFAULT 'key', user_id text NOT NULL DEFAULT 'owner', folder_id text)` + for (const migration of [ + '0313_puzzling_zodiak.sql', + '0358_workspace_file_content_version_precision.sql', + '0359_workspace_file_search_chunks.sql', + ]) { + const source = readFileSync( + resolve(process.cwd(), '../../packages/db/migrations', migration), + 'utf8' + ).replaceAll('"public".', `"${schema}".`) + for (const statement of source.split('--> statement-breakpoint')) + if (statement.trim()) await connection.unsafe(statement) + } + database.current = drizzle(connection, { + logger: { + logQuery(query, params) { + if ( + captureQuery && + query.includes('from (select') && + query.includes('workspace_file_search_chunk') + ) { + const kind = query.includes('join lateral') ? 'ordered' : 'probe' + if (!capturedQueries.has(kind)) capturedQueries.set(kind, { sql: query, params }) + } + }, + }, + }) + }) + beforeEach(async () => { + await connection`TRUNCATE workspace, workspace_files, workspace_file_search_revision, workspace_file_search_build, + workspace_file_search_chunk, workspace_file_search_index, workspace_file_search_segment, workspace_file_search_dispatch_queue, workspace_file_search_backfill` + await connection`INSERT INTO workspace_file_search_backfill (id, completed_at) VALUES ('workspace-file-search-chunks-v2', now())` + await addFile('file-1') + }) + afterAll(async () => { + try { + await connection`DROP SCHEMA ${connection(schema)} CASCADE` + } finally { + database.current = undefined + await connection.end() + } + }) + + it('packs a million short lines without a million rows and bounds every stored value', async () => { + await index('abc\n'.repeat(1_000_000)) + const [row] = + await connection`SELECT count(*)::int AS count, max(octet_length(content)) AS largest FROM workspace_file_search_chunk` + expect(row.count).toBeLessThan(500) + expect(row.largest).toBeLessThanOrEqual(8192) + const result = await search('abc', 'exact', 3) + expect(result.results.map((r) => r.lineNumber)).toEqual([1, 2, 3]) + expect(result.truncated).toBe(true) + expect(result.indexStatus).toMatchObject({ readyFiles: 1, partialFiles: 0 }) + }) + it('publishes an empty file with no chunk rows', async () => { + await index('') + const result = await search('needle') + expect(result.results).toEqual([]) + expect(result.indexStatus).toMatchObject({ readyFiles: 1, pendingFiles: 0, partialFiles: 0 }) + }) + it('rejects publication when a chunk batch is missing', async () => { + const build = (await beginFileSearchBuild(revision))! + await expect( + publishFileSearchBuild( + build, + { status: 'ready', chunkCount: 1, lineCount: 1, indexedBytes: 6 }, + signal + ) + ).rejects.toThrow('incomplete') + expect((await search('needle')).indexStatus.pendingFiles).toBe(1) + }) + it('excludes an incomplete file in full and reclaims its unpublished chunks', async () => { + const build = (await beginFileSearchBuild(revision))! + const plan = planFileSearchIndex({ text: 'needle', partial: false }, signal) + await appendFileSearchChunks(build, [...iterateFileSearchChunks(plan, signal)], signal) + await publishFileSearchBuild( + build, + { status: 'skipped', failureReason: 'incomplete_extraction' }, + signal + ) + const result = await search('needle') + expect(result.results).toEqual([]) + expect(result.indexStatus).toMatchObject({ skippedFiles: 1, readyFiles: 0, partialFiles: 0 }) + await cleanupFileSearchBuilds() + expect( + (await connection`SELECT count(*)::int AS count FROM workspace_file_search_chunk`)[0].count + ).toBe(0) + }) + it('does not allow an expired worker to publish after cleanup', async () => { + const build = (await beginFileSearchBuild(revision))! + await connection`UPDATE workspace_file_search_build SET expires_at = now() - interval '1 second' WHERE id = ${build.id}` + await cleanupFileSearchBuilds() + expect( + await publishFileSearchBuild( + build, + { status: 'ready', chunkCount: 0, lineCount: 1, indexedBytes: 0 }, + signal + ) + ).toBe(false) + expect((await search('needle')).indexStatus.pendingFiles).toBe(1) + }) + it('reindexes restored files and files moved back into workspace context', async () => { + await index('needle') + await connection`UPDATE workspace_files SET context = 'chat' WHERE id = 'file-1'` + expect((await search('needle')).results).toEqual([]) + await connection`UPDATE workspace_files SET context = 'workspace' WHERE id = 'file-1'` + expect((await search('needle')).indexStatus.pendingFiles).toBe(1) + await index('needle') + await connection`UPDATE workspace_files SET deleted_at = now() WHERE id = 'file-1'` + await connection`UPDATE workspace_files SET deleted_at = NULL WHERE id = 'file-1'` + expect((await search('needle')).indexStatus.pendingFiles).toBe(1) + await index('needle') + expect((await search('needle')).results).toHaveLength(1) + }) + it('pages a broad query without losing or repeating logical lines', async () => { + await index(`needle ${'x'.repeat(8184)}\n`.repeat(300)) + const result = await search('needle') + expect(result.results.map((row) => row.lineNumber)).toEqual( + Array.from({ length: 200 }, (_, i) => i + 1) + ) + expect(result.truncated).toBe(true) + }) + it('keeps unfinished builds hidden and fences an overlapping retry', async () => { + const first = (await beginFileSearchBuild(revision))! + const plan = planFileSearchIndex({ text: 'needle', partial: false }, signal) + const chunks = [...iterateFileSearchChunks(plan, signal)] + await appendFileSearchChunks(first, chunks, signal) + expect((await search('needle')).results).toEqual([]) + const second = (await beginFileSearchBuild(revision))! + expect(await appendFileSearchChunks(first, chunks, signal)).toBe(false) + expect( + await publishFileSearchBuild( + first, + { status: 'ready', chunkCount: 1, lineCount: 1, indexedBytes: 6 }, + signal + ) + ).toBe(false) + await appendFileSearchChunks(second, chunks, signal) + expect( + await publishFileSearchBuild( + second, + { status: 'ready', chunkCount: 1, lineCount: 1, indexedBytes: 6 }, + signal + ) + ).toBe(true) + await cleanupFileSearchBuilds() + expect((await search('needle')).results).toHaveLength(1) + const builds = await connection`SELECT id FROM workspace_file_search_build` + expect(builds.map((b) => b.id)).toEqual([second.id]) + }) + it.each([ + ['^needle$', 'intro\nneedle\nlast', [2]], + ['alpha.*omega', 'alpha\nomega', []], + ['^alpha.*omega$', `intro\nalpha${'x'.repeat(25000)}omega\nlast`, [2]], + ['needle', `${'x'.repeat(8190)}needle${'x'.repeat(9000)}`, [1]], + ['^needle', `${'x'.repeat(8192)}needle`, []], + ['^alpha.*omega$', `intro\r\nalpha${'🙂'.repeat(524288)}omega\r\nlast`, [2]], + ['^needle$', '\r\n\r\nneedle\r\n\r\nneedle\r', [3, 5]], + ['^needle$', `${'x'.repeat(8192)}\nneedle`, [2]], + ['(alpha|omega)', `${'x'.repeat(8190)}omega${'x'.repeat(9000)}`, [1]], + ['(?:ab){2,5}', `${'x'.repeat(8191)}abab`, [1]], + ['\\bneedle\\b', 'x\nneedle\ny', [2]], + ['ab(?:😀|😁)cde', `${'x'.repeat(8189)}ab😁cde${'x'.repeat(9000)}`, [1]], + ['value=100%_ok', `${'x'.repeat(8190)}value=100%_ok`, [1]], + ])('verifies complete logical lines for %s', async (query, text, expected) => { + await index(text as string) + const result = await search(query as string, 'regex') + expect(result.results.map((row) => row.lineNumber)).toEqual(expected) + expect(result.results.every((row) => Buffer.byteLength(row.text) <= 2048)).toBe(true) + }) + it('finds literals across Unicode fragment boundaries without duplicate lines', async () => { + await index(`${'🙂'.repeat(2047)}🙂AbC${'x'.repeat(9000)}`) + expect((await search('🙂AbC')).results.map((row) => row.lineNumber)).toEqual([1]) + }) + it('continues after a full page of fragment false positives', async () => { + await index(`${(`alpha${'x'.repeat(17000)}\n`).repeat(130)}alpha omega`) + expect((await search('alpha.*omega', 'regex')).results.map((r) => r.lineNumber)).toEqual([131]) + }) + it('rejects publication after a concurrent revision change', async () => { + const build = (await beginFileSearchBuild(revision))! + await connection`UPDATE workspace_files SET content_updated_at = content_updated_at + interval '1 second' WHERE id = 'file-1'` + expect( + await publishFileSearchBuild( + build, + { status: 'ready', chunkCount: 0, lineCount: 1, indexedBytes: 0 }, + signal + ) + ).toBe(false) + expect((await search('needle')).indexStatus.pendingFiles).toBe(1) + }) + it.each(['soft', 'hard', 'workspace'])( + 'invalidates %s deletion before asynchronous cleanup', + async (kind) => { + await index('needle\n'.repeat(10000)) + if (kind === 'soft') + await connection`UPDATE workspace_files SET deleted_at = now() WHERE id = 'file-1'` + if (kind === 'hard') await connection`DELETE FROM workspace_files WHERE id = 'file-1'` + if (kind === 'workspace') await connection`DELETE FROM workspace WHERE id = 'workspace-1'` + expect((await search('needle')).results).toEqual([]) + expect( + (await connection`SELECT count(*)::int AS count FROM workspace_file_search_chunk`)[0].count + ).toBeGreaterThan(0) + await cleanupFileSearchBuilds() + expect( + (await connection`SELECT count(*)::int AS count FROM workspace_file_search_chunk`)[0].count + ).toBe(0) + } + ) + it('keeps cleanup to its batch/run budget and resumes', async () => { + const build = (await beginFileSearchBuild(revision))! + const count = FILE_SEARCH_CLEANUP_BATCH_ROWS * FILE_SEARCH_CLEANUP_MAX_BATCHES + 1 + await connection`INSERT INTO workspace_file_search_chunk (build_id, workspace_id, ordinal, line_start, fragment, content) + SELECT ${build.id}, 'workspace-1', n, n + 1, false, 'x' FROM generate_series(0, ${count - 1}) n` + await connection`UPDATE workspace_file_search_build SET expires_at = now() WHERE id = ${build.id}` + await addFile('file-2') + expect((await prepareWorkspaceFileSearchDispatch()).payloads).toEqual([]) + expect(await cleanupFileSearchBuilds()).toBeLessThanOrEqual(count - 1) + expect( + (await connection`SELECT count(*)::int AS count FROM workspace_file_search_chunk`)[0].count + ).toBeGreaterThan(0) + await cleanupFileSearchBuilds() + expect((await prepareWorkspaceFileSearchDispatch()).payloads.map((row) => row.fileId)).toEqual([ + 'file-2', + ]) + expect( + (await connection`SELECT count(*)::int AS count FROM workspace_file_search_chunk`)[0].count + ).toBe(0) + }) + it('retires many small builds within one cleanup run', async () => { + await connection`INSERT INTO workspace_file_search_build (id, file_id, workspace_id, source_content_updated_at, expires_at) + SELECT 'retired-' || n, 'file-1', 'workspace-1', now(), now() FROM generate_series(1, 100) n` + await connection`INSERT INTO workspace_file_search_chunk (build_id, workspace_id, ordinal, line_start, fragment, content) + SELECT 'retired-' || n, 'workspace-1', 0, 1, false, 'small' FROM generate_series(1, 100) n` + expect(await cleanupFileSearchBuilds()).toBe(100) + expect( + (await connection`SELECT count(*)::int AS count FROM workspace_file_search_build`)[0].count + ).toBe(0) + }) + it('scopes results, coverage, and deterministic ordering to current workspace folders', async () => { + const second = await addFile('file-2', 'workspace-1', 'A', 'folder-1') + const other = await addFile('file-3', 'workspace-2', 'A', 'folder-1') + await index('needle') + await index('needle', second) + await index('needle', other) + const scoped = await searchWorkspaceFileIndex({ + workspaceId: 'workspace-1', + pattern: compileFileSearchPattern('needle', 'exact'), + maxResults: 200, + folderScope: { folderIds: new Set(['folder-1']), includeRootItems: false }, + signal, + }) + expect(scoped.results.map((row) => row.fileId)).toEqual(['file-2']) + expect(scoped.indexStatus.readyFiles).toBe(1) + expect((await search('needle')).results.map((row) => row.fileId)).toEqual(['file-2', 'file-1']) + }) + it('backfills preexisting files idempotently and does not reset ready builds', async () => { + await index('needle') + await connection`DELETE FROM workspace_file_search_backfill` + const first = await prepareWorkspaceFileSearchDispatch() + const second = await prepareWorkspaceFileSearchDispatch() + expect(first.backfilledFiles).toBe(1) + expect(second.backfilledFiles).toBe(0) + expect(first.payloads).toEqual([]) + expect(await beginFileSearchBuild(revision)).toBeNull() + await cleanupFileSearchBuilds() + expect((await search('needle')).indexStatus.readyFiles).toBe(1) + }) + it('does not let an old dispatch callback fail a new claim', async () => { + const older = new Date('2026-01-01T01:00:00Z') + const newer = new Date('2026-01-01T02:00:00Z') + await connection`UPDATE workspace_file_search_revision SET dispatched_at = ${newer.toISOString()}::timestamp` + const active = (await beginFileSearchBuild(revision, newer.toISOString()))! + expect(await beginFileSearchBuild(revision, older.toISOString())).toBeNull() + expect( + ( + await connection`SELECT expires_at > now() AS live FROM workspace_file_search_build WHERE id = ${active.id}` + )[0].live + ).toBe(true) + await failFileSearchRevision(revision, older.toISOString()) + expect((await connection`SELECT status FROM workspace_file_search_revision`)[0].status).toBe( + 'pending' + ) + }) + + it('releases query admission slots after a busy response', async () => { + const held = await connection.reserve() + try { + await held`BEGIN` + await held`SELECT pg_advisory_xact_lock(hashtextextended('workspace-file-search-read:workspace:workspace-1:' || n::text, 0)) FROM generate_series(1, 2) n` + await expect(search('needle')).rejects.toThrow('busy') + } finally { + await held`ROLLBACK` + held.release() + } + expect((await search('needle')).results).toEqual([]) + }) + + it.runIf(Boolean(process.env.FILE_SEARCH_BENCHMARK_OUTPUT))( + 'measures the actual scoped reader on a synthetic multi-file index', + async () => { + const fileCount = Number(process.env.FILE_SEARCH_BENCHMARK_FILES ?? 1000) + if (!Number.isSafeInteger(fileCount) || fileCount < 1 || fileCount > 10000) + throw new Error('Invalid benchmark file count') + const content = Array.from( + { length: 90 }, + (_, n) => `common sample ${n} ${createHash('sha256').update(String(n)).digest('hex')}\n` + ).join('') + await connection`INSERT INTO workspace_files (id, workspace_id, context, content_updated_at, original_name) + SELECT 'bench-file-' || n, 'workspace-1', 'workspace', ${revision.sourceContentUpdatedAt.toISOString()}::timestamp, + 'sample-' || lpad(n::text, 4, '0') FROM generate_series(1, ${fileCount}) n` + await connection`INSERT INTO workspace_file_search_build (id, file_id, workspace_id, source_content_updated_at) + SELECT 'bench-build-' || n, 'bench-file-' || n, 'workspace-1', ${revision.sourceContentUpdatedAt.toISOString()}::timestamp FROM generate_series(1, ${fileCount}) n` + await connection`INSERT INTO workspace_file_search_chunk (build_id, workspace_id, ordinal, line_start, fragment, content) + SELECT 'bench-build-' || file, 'workspace-1', chunk, chunk * 90 + 1, false, + ${content} || CASE WHEN file = ${fileCount} AND chunk = 7 THEN 'unique-needle\n' ELSE '' END + FROM generate_series(1, ${fileCount}) file CROSS JOIN generate_series(0, 7) chunk` + await connection`UPDATE workspace_file_search_revision SET status = 'ready', build_id = replace(file_id, 'bench-file-', 'bench-build-'), chunk_count = 8 + WHERE file_id LIKE 'bench-file-%'` + await connection`SELECT gin_clean_pending_list('workspace_file_search_chunk_content_idx')` + await connection`ANALYZE workspace_file_search_chunk` + await connection`ANALYZE workspace_file_search_revision` + await connection`ANALYZE workspace_files` + const results: Array<{ query: string; samplesMs: number[]; plan: unknown }> = [] + for (const [query, expected] of [ + ['common', 200], + ['unique-needle', 1], + ['missing-marker', 0], + ] as const) { + const samplesMs: number[] = [] + capturedQueries.clear() + captureQuery = true + for (let i = 0; i < 5; i++) { + const start = performance.now() + const result = await search(query) + samplesMs.push(performance.now() - start) + expect(result.results).toHaveLength(expected) + } + captureQuery = false + const plan: Record = {} + for (const [kind, captured] of capturedQueries) { + plan[kind] = await connection.unsafe( + `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) ${captured.sql}`, + captured.params as Parameters[1] + ) + } + results.push({ query, samplesMs, plan }) + } + writeFileSync(process.env.FILE_SEARCH_BENCHMARK_OUTPUT!, JSON.stringify(results, null, 2)) + }, + 300000 + ) +}) diff --git a/apps/sim/lib/workspace-files/search/constants.ts b/apps/sim/lib/workspace-files/search/constants.ts index f4a2820e663..8cff0a3fb7b 100644 --- a/apps/sim/lib/workspace-files/search/constants.ts +++ b/apps/sim/lib/workspace-files/search/constants.ts @@ -1,9 +1,4 @@ -/** - * `pg_trgm` can only extract a trigram from three consecutive characters, so a - * shorter query has nothing for the segment GIN index to probe and degrades to a - * scan of every tenant's segments. It bounds the literal query length and, in - * regex mode, the shortest literal run every match is guaranteed to contain. - */ +/** Require enough literal characters for a selective trigram probe when the pattern permits one. */ export const FILE_SEARCH_MIN_QUERY_LENGTH = 3 export const FILE_SEARCH_MAX_QUERY_LENGTH = 512 @@ -16,12 +11,7 @@ export const FILE_SEARCH_PATTERN_LITERAL_CAP = 512 export const FILE_SEARCH_PATTERN_MAX_REPEAT = 1000 export const FILE_SEARCH_PATTERN_MAX_DEPTH = 20 -/** - * Backstop for a pattern whose trigrams the planner cannot use — a punctuation-only - * or non-ASCII literal, or a regex whose guaranteed run yields no trigram. Those - * plan as a sequential scan across every workspace's segments, so the search must - * not be able to hold a pooled connection open indefinitely. - */ +/** Total search deadline, including patterns whose literals cannot provide a selective trigram probe. */ export const FILE_SEARCH_STATEMENT_TIMEOUT_MS = 10 * 1000 export const FILE_SEARCH_LOCK_TIMEOUT_MS = 5 * 1000 export const FILE_SEARCH_DEFAULT_MAX_RESULTS = 50 @@ -30,9 +20,19 @@ export const FILE_SEARCH_MAX_RESULTS = 200 export const FILE_SEARCH_MAX_SOURCE_BYTES = 25 * 1024 * 1024 export const FILE_SEARCH_MAX_EXTRACTED_BYTES = 25 * 1024 * 1024 export const FILE_SEARCH_MAX_PREVIEW_BYTES = 2 * 1024 -export const FILE_SEARCH_SEGMENT_CHARS = 16 * 1024 -export const FILE_SEARCH_SEGMENT_OVERLAP_CHARS = - FILE_SEARCH_MAX_QUERY_LENGTH + FILE_SEARCH_MAX_PREVIEW_BYTES +export const FILE_SEARCH_CHUNK_BYTES = 8 * 1024 +export const FILE_SEARCH_CANDIDATE_PAGE_SIZE = 16 +export const FILE_SEARCH_CANDIDATE_PROBE_SIZE = 256 +export const FILE_SEARCH_QUERY_GLOBAL_CONCURRENCY = 10 +export const FILE_SEARCH_QUERY_WORKSPACE_CONCURRENCY = 2 +export const FILE_SEARCH_CANDIDATE_LITERAL_CHARS = 3 +export const FILE_SEARCH_BUILD_LEASE_MS = 20 * 60 * 1000 +export const FILE_SEARCH_CLEANUP_BATCH_ROWS = 1000 +export const FILE_SEARCH_CLEANUP_BATCH_BUILDS = 100 +export const FILE_SEARCH_CLEANUP_BACKLOG_ROWS = 10000 +export const FILE_SEARCH_CLEANUP_MAX_BATCHES = 10 +export const FILE_SEARCH_CLEANUP_BUDGET_MS = 5000 +export const FILE_SEARCH_RECONCILE_INTERVAL_MS = 60 * 60 * 1000 export const FILE_SEARCH_INSERT_BATCH_ROWS = 250 export const FILE_SEARCH_INSERT_BATCH_BYTES = 1024 * 1024 diff --git a/apps/sim/lib/workspace-files/search/dispatcher.integration.ts b/apps/sim/lib/workspace-files/search/dispatcher.integration.ts index afc6eee134c..b5384ec6f71 100644 --- a/apps/sim/lib/workspace-files/search/dispatcher.integration.ts +++ b/apps/sim/lib/workspace-files/search/dispatcher.integration.ts @@ -18,6 +18,9 @@ vi.mock('@/lib/workspace-files/search/indexing', () => ({ indexWorkspaceFileForSearch: vi.fn(), markWorkspaceFileSearchIndexFailed: vi.fn(), })) +vi.mock('@/lib/workspace-files/search/index-state', () => ({ + cleanupFileSearchBuilds: vi.fn().mockResolvedValue(0), +})) vi.mock('@trigger.dev/sdk', () => ({ tasks: { batchTrigger: mocks.batchTrigger } })) vi.mock('@/lib/core/config/env-flags', () => ({ isTriggerDevEnabled: true })) vi.mock('@/lib/core/async-jobs/region', () => ({ resolveTriggerRegion: async () => 'us-east-1' })) @@ -52,7 +55,7 @@ describe('workspace file search dispatch PostgreSQL deadlines', () => { id text PRIMARY KEY, workspace_id text NOT NULL, context text NOT NULL, deleted_at timestamp, content_updated_at timestamp NOT NULL )` - await connection`CREATE TABLE workspace_file_search_index ( + await connection`CREATE TABLE workspace_file_search_revision ( file_id text NOT NULL, workspace_id text NOT NULL, source_content_updated_at timestamp NOT NULL, status text NOT NULL, dispatched_at timestamp, updated_at timestamp NOT NULL, PRIMARY KEY (file_id, source_content_updated_at) @@ -61,20 +64,22 @@ describe('workspace file search dispatch PostgreSQL deadlines', () => { workspace_id text PRIMARY KEY, enqueued_at timestamp NOT NULL, updated_at timestamp NOT NULL, last_dispatched_at timestamp )` - await connection`CREATE INDEX ON workspace_file_search_index + await connection`CREATE INDEX ON workspace_file_search_revision (workspace_id, updated_at, file_id, source_content_updated_at) WHERE status = 'pending' AND dispatched_at IS NULL` - await connection`CREATE INDEX ON workspace_file_search_index (workspace_id, dispatched_at) + await connection`CREATE INDEX ON workspace_file_search_revision (workspace_id, dispatched_at) WHERE status = 'pending' AND dispatched_at IS NOT NULL` await connection`INSERT INTO workspace_file_search_backfill (id, updated_at) - VALUES ('workspace-file-search-v1', '2026-09-16 00:00:00')` + VALUES ('workspace-file-search-chunks-v2', '2026-09-16 00:00:00')` + await connection`CREATE TABLE workspace_file_search_build (id text PRIMARY KEY, expires_at timestamp)` + await connection`CREATE TABLE workspace_file_search_chunk (build_id text NOT NULL, ordinal integer NOT NULL, PRIMARY KEY(build_id, ordinal))` database.current = drizzle(connection) }) beforeEach(async () => { mocks.batchTrigger.mockReset() await connection`DROP TRIGGER IF EXISTS slow_backfill ON workspace_file_search_backfill` - await connection`TRUNCATE workspace_files, workspace_file_search_index, workspace_file_search_dispatch_queue` + await connection`TRUNCATE workspace_files, workspace_file_search_revision, workspace_file_search_dispatch_queue` await connection`UPDATE workspace_file_search_backfill SET updated_at = '2026-09-16 00:00:00', completed_at = NULL` }) @@ -102,7 +107,7 @@ describe('workspace file search dispatch PostgreSQL deadlines', () => { await connection`INSERT INTO workspace_files (id, workspace_id, context, content_updated_at) SELECT ${workspaceId} || '-' || lpad(n::text, 6, '0'), ${workspaceId}, 'workspace', '2026-09-16' FROM generate_series(1, ${queued + active}) n` - await connection`INSERT INTO workspace_file_search_index + await connection`INSERT INTO workspace_file_search_revision (file_id, workspace_id, source_content_updated_at, status, updated_at, dispatched_at) SELECT id, workspace_id, content_updated_at, 'pending', '2026-09-16', CASE WHEN row_number() OVER (ORDER BY id DESC) <= ${active} THEN now() ELSE NULL END @@ -114,7 +119,7 @@ describe('workspace file search dispatch PostgreSQL deadlines', () => { it('skips a locked candidate without losing it or exceeding workspace capacity', async () => { await seedQueue('workspace-1', 3, 1) await connection.begin(async (tx) => { - await tx`SELECT file_id FROM workspace_file_search_index + await tx`SELECT file_id FROM workspace_file_search_revision WHERE file_id = 'workspace-1-000001' FOR UPDATE` const results = await Promise.all([ prepareWorkspaceFileSearchDispatch(), @@ -123,12 +128,12 @@ describe('workspace file search dispatch PostgreSQL deadlines', () => { expect(results.flatMap((result) => result.payloads).map((payload) => payload.fileId)).toEqual( ['workspace-1-000002'] ) - const [locked] = await tx`SELECT dispatched_at FROM workspace_file_search_index + const [locked] = await tx`SELECT dispatched_at FROM workspace_file_search_revision WHERE file_id = 'workspace-1-000001'` expect(locked.dispatched_at).toBeNull() }) expect((await prepareWorkspaceFileSearchDispatch()).payloads).toEqual([]) - await connection`UPDATE workspace_file_search_index SET status = 'ready' + await connection`UPDATE workspace_file_search_revision SET status = 'ready' WHERE file_id = 'workspace-1-000002'` const retry = await prepareWorkspaceFileSearchDispatch() expect(retry.payloads.map((payload) => payload.fileId)).toEqual(['workspace-1-000001']) @@ -157,7 +162,8 @@ describe('workspace file search dispatch PostgreSQL deadlines', () => { const result = await prepareWorkspaceFileSearchDispatch() expect(result.payloads).toHaveLength(1) expect((await prepareWorkspaceFileSearchDispatch()).payloads).toEqual([]) - const [row] = await connection`SELECT count(*)::int AS active FROM workspace_file_search_index + const [row] = + await connection`SELECT count(*)::int AS active FROM workspace_file_search_revision WHERE status = 'pending' AND dispatched_at IS NOT NULL` expect(row.active).toBe(100) }) @@ -213,7 +219,7 @@ describe('workspace file search dispatch PostgreSQL deadlines', () => { await connection`UPDATE workspace_file_search_backfill SET completed_at = now()` await connection`INSERT INTO workspace_files (id, workspace_id, context, content_updated_at) VALUES (${fileId}, ${workspaceId}, 'workspace', '2026-09-16')` - await connection`INSERT INTO workspace_file_search_index + await connection`INSERT INTO workspace_file_search_revision (file_id, workspace_id, source_content_updated_at, status, updated_at) VALUES (${fileId}, ${workspaceId}, '2026-09-16', 'pending', now())` await connection`INSERT INTO workspace_file_search_dispatch_queue @@ -232,7 +238,7 @@ describe('workspace file search dispatch PostgreSQL deadlines', () => { END $$` await connection`CREATE TRIGGER record_cleanup_timeouts AFTER UPDATE OF dispatched_at - ON workspace_file_search_index FOR EACH ROW + ON workspace_file_search_revision FOR EACH ROW WHEN (OLD.dispatched_at IS NOT NULL AND NEW.dispatched_at IS NULL) EXECUTE FUNCTION record_cleanup_timeouts()` @@ -243,13 +249,14 @@ describe('workspace file search dispatch PostgreSQL deadlines', () => { expect(mocks.batchTrigger).toHaveBeenCalledWith('workspace-file-search-index', [ expect.objectContaining({ payload: { + dispatchToken: expect.any(String), fileId, workspaceId, sourceContentUpdatedAt: '2026-09-16T00:00:00.000Z', }, }), ]) - const [index] = await connection`SELECT dispatched_at FROM workspace_file_search_index + const [index] = await connection`SELECT dispatched_at FROM workspace_file_search_revision WHERE file_id = ${fileId}` expect(index.dispatched_at).toBeNull() const [queued] = await connection`SELECT workspace_id FROM workspace_file_search_dispatch_queue diff --git a/apps/sim/lib/workspace-files/search/dispatcher.test.ts b/apps/sim/lib/workspace-files/search/dispatcher.test.ts index 937c30f4277..84622570320 100644 --- a/apps/sim/lib/workspace-files/search/dispatcher.test.ts +++ b/apps/sim/lib/workspace-files/search/dispatcher.test.ts @@ -4,7 +4,7 @@ import { workspaceFileSearchBackfill, workspaceFileSearchDispatchQueue, - workspaceFileSearchIndex, + workspaceFileSearchRevision, } from '@sim/db/schema' import { dbChainMock, dbChainMockFns, queueTableRows, resetDbChainMock } from '@sim/testing' import { beforeEach, describe, expect, it, vi } from 'vitest' @@ -26,6 +26,9 @@ vi.mock('@sim/db/schema', async () => ({ })) vi.mock('@sim/logger', () => ({ createLogger: () => ({ info: mocks.info, error: mocks.error }) })) +vi.mock('@/lib/workspace-files/search/index-state', () => ({ + cleanupFileSearchBuilds: vi.fn().mockResolvedValue(0), +})) vi.mock('@trigger.dev/sdk', () => ({ tasks: { batchTrigger: mocks.batchTrigger } })) vi.mock('@/lib/core/config/env-flags', () => ({ isTriggerDevEnabled: true })) vi.mock('@/lib/core/async-jobs/region', () => ({ resolveTriggerRegion: async () => 'us-east-1' })) @@ -59,7 +62,7 @@ describe('workspace file search dispatch policy', () => { { payload, options: { - idempotencyKey: 'workspace-file-search:file-1:2026-08-29T12:00:00.000Z', + idempotencyKey: 'workspace-file-search-v2:file-1:2026-08-29T12:00:00.000Z:initial', idempotencyKeyTTL: '1h', tags: ['workspaceId:workspace-1', 'fileId:file-1'], region: 'us-east-1', @@ -142,12 +145,12 @@ describe('workspace file search dispatch deadlines', () => { 'preserves enqueue failures when claim release fails: %s', async (releaseFails) => { queueTableRows(workspaceFileSearchBackfill, [{ completedAt: new Date() }]) - queueTableRows(workspaceFileSearchIndex, []) - queueTableRows(workspaceFileSearchIndex, [{ active: 0 }]) + queueTableRows(workspaceFileSearchRevision, []) queueTableRows(workspaceFileSearchDispatchQueue, [{ workspaceId: 'workspace-1' }]) dbChainMockFns.execute .mockResolvedValueOnce([]) .mockResolvedValueOnce([{ acquired: true }]) + .mockResolvedValueOnce([{ active: 0 }]) .mockResolvedValueOnce([ { workspaceId: 'workspace-1', diff --git a/apps/sim/lib/workspace-files/search/dispatcher.ts b/apps/sim/lib/workspace-files/search/dispatcher.ts index a9346754a62..d0c3a1d0beb 100644 --- a/apps/sim/lib/workspace-files/search/dispatcher.ts +++ b/apps/sim/lib/workspace-files/search/dispatcher.ts @@ -2,8 +2,7 @@ import { db } from '@sim/db' import { workspaceFileSearchBackfill, workspaceFileSearchDispatchQueue, - workspaceFileSearchIndex, - workspaceFileSearchSegment, + workspaceFileSearchRevision, workspaceFiles, } from '@sim/db/schema' import { createLogger } from '@sim/logger' @@ -12,7 +11,6 @@ import { truncate } from '@sim/utils/string' import { and, asc, - count, eq, exists, gt, @@ -31,15 +29,20 @@ import { runDetached } from '@/lib/core/utils/background' import type { DbTransaction } from '@/lib/db/types' import { FILE_SEARCH_BACKFILL_PAGE_SIZE, + FILE_SEARCH_CLEANUP_BACKLOG_ROWS, FILE_SEARCH_DISPATCH_LOCK_TIMEOUT_MS, FILE_SEARCH_DISPATCH_STATEMENT_TIMEOUT_MS, FILE_SEARCH_DISPATCH_TRANSACTION_TIMEOUT_MS, FILE_SEARCH_INDEX_DISPATCH_WORKSPACES, + FILE_SEARCH_INDEX_GLOBAL_CONCURRENCY, + FILE_SEARCH_INDEX_MAX_DURATION_SECONDS, FILE_SEARCH_INDEX_MAX_OUTSTANDING, FILE_SEARCH_INDEX_STALE_DISPATCH_MS, FILE_SEARCH_INDEX_STALE_REAP_LIMIT, FILE_SEARCH_INDEX_WORKSPACE_OUTSTANDING, + FILE_SEARCH_RECONCILE_INTERVAL_MS, } from '@/lib/workspace-files/search/constants' +import { cleanupFileSearchBuilds } from '@/lib/workspace-files/search/index-state' import { indexWorkspaceFileForSearch, markWorkspaceFileSearchIndexFailed, @@ -49,7 +52,7 @@ import type { workspaceFileSearchIndexTask } from '@/background/workspace-file-s const logger = createLogger('WorkspaceFileSearchDispatcher') const DISPATCH_LOCK_NAME = 'workspace-file-search-dispatch' -const BACKFILL_CURSOR_ID = 'workspace-file-search-v1' +const BACKFILL_CURSOR_ID = 'workspace-file-search-chunks-v2' async function runDispatchPhase(phase: string, operation: () => Promise): Promise { const startedAt = Date.now() @@ -89,6 +92,7 @@ async function configureDispatchTimeouts(tx: DbTransaction): Promise { interface RevisionIdentity { fileId: string sourceContentUpdatedAt: Date + dispatchToken?: string } interface PreparedDispatch { @@ -119,7 +123,7 @@ export function buildWorkspaceFileSearchTriggerItems( return payloads.map((payload) => ({ payload, options: { - idempotencyKey: `workspace-file-search:${payload.fileId}:${payload.sourceContentUpdatedAt}`, + idempotencyKey: `workspace-file-search-v2:${payload.fileId}:${payload.sourceContentUpdatedAt}:${payload.dispatchToken ?? 'initial'}`, idempotencyKeyTTL: '1h' as const, tags: [`workspaceId:${payload.workspaceId}`, `fileId:${payload.fileId}`], region, @@ -131,8 +135,11 @@ function revisionFilter(rows: readonly RevisionIdentity[]): SQL | undefined { return or( ...rows.map((row) => and( - eq(workspaceFileSearchIndex.fileId, row.fileId), - eq(workspaceFileSearchIndex.sourceContentUpdatedAt, row.sourceContentUpdatedAt) + eq(workspaceFileSearchRevision.fileId, row.fileId), + eq(workspaceFileSearchRevision.sourceContentUpdatedAt, row.sourceContentUpdatedAt), + row.dispatchToken + ? eq(workspaceFileSearchRevision.dispatchedAt, new Date(row.dispatchToken)) + : undefined ) ) ) @@ -172,7 +179,14 @@ async function seedBackfillPage(tx: DbTransaction, now: Date): Promise { .where(eq(workspaceFileSearchBackfill.id, BACKFILL_CURSOR_ID)) .for('update') .limit(1) - if (!cursor || cursor.completedAt) return 0 + if ( + !cursor || + (cursor.completedAt && + now.getTime() - cursor.completedAt.getTime() < FILE_SEARCH_RECONCILE_INTERVAL_MS) + ) + return 0 + const afterWorkspaceId = cursor.completedAt ? null : cursor.afterWorkspaceId + const afterFileId = cursor.completedAt ? null : cursor.afterFileId const rows = await tx .select({ @@ -186,12 +200,12 @@ async function seedBackfillPage(tx: DbTransaction, now: Date): Promise { eq(workspaceFiles.context, 'workspace'), isNull(workspaceFiles.deletedAt), isNotNull(workspaceFiles.workspaceId), - cursor.afterWorkspaceId && cursor.afterFileId + afterWorkspaceId && afterFileId ? or( - gt(workspaceFiles.workspaceId, cursor.afterWorkspaceId), + gt(workspaceFiles.workspaceId, afterWorkspaceId), and( - eq(workspaceFiles.workspaceId, cursor.afterWorkspaceId), - gt(workspaceFiles.id, cursor.afterFileId) + eq(workspaceFiles.workspaceId, afterWorkspaceId), + gt(workspaceFiles.id, afterFileId) ) ) : undefined @@ -206,7 +220,7 @@ async function seedBackfillPage(tx: DbTransaction, now: Date): Promise { ) if (files.length > 0) { await tx - .insert(workspaceFileSearchIndex) + .insert(workspaceFileSearchRevision) .values( files.map((file) => ({ workspaceId: file.workspaceId, @@ -228,8 +242,8 @@ async function seedBackfillPage(tx: DbTransaction, now: Date): Promise { await tx .update(workspaceFileSearchBackfill) .set({ - afterWorkspaceId: last?.workspaceId ?? cursor.afterWorkspaceId, - afterFileId: last?.fileId ?? cursor.afterFileId, + afterWorkspaceId: last?.workspaceId ?? afterWorkspaceId, + afterFileId: last?.fileId ?? afterFileId, completedAt: rows.length < FILE_SEARCH_BACKFILL_PAGE_SIZE ? now : null, updatedAt: now, }) @@ -241,39 +255,39 @@ async function reapStaleClaims(tx: DbTransaction, now: Date): Promise { const staleBefore = new Date(now.getTime() - FILE_SEARCH_INDEX_STALE_DISPATCH_MS) const rows = await tx .select({ - workspaceId: workspaceFileSearchIndex.workspaceId, - fileId: workspaceFileSearchIndex.fileId, - sourceContentUpdatedAt: workspaceFileSearchIndex.sourceContentUpdatedAt, + workspaceId: workspaceFileSearchRevision.workspaceId, + fileId: workspaceFileSearchRevision.fileId, + sourceContentUpdatedAt: workspaceFileSearchRevision.sourceContentUpdatedAt, currentFileId: workspaceFiles.id, }) - .from(workspaceFileSearchIndex) + .from(workspaceFileSearchRevision) .leftJoin( workspaceFiles, and( - eq(workspaceFiles.id, workspaceFileSearchIndex.fileId), - eq(workspaceFiles.workspaceId, workspaceFileSearchIndex.workspaceId), + eq(workspaceFiles.id, workspaceFileSearchRevision.fileId), + eq(workspaceFiles.workspaceId, workspaceFileSearchRevision.workspaceId), eq(workspaceFiles.context, 'workspace'), isNull(workspaceFiles.deletedAt), - eq(workspaceFiles.contentUpdatedAt, workspaceFileSearchIndex.sourceContentUpdatedAt) + eq(workspaceFiles.contentUpdatedAt, workspaceFileSearchRevision.sourceContentUpdatedAt) ) ) .where( and( - eq(workspaceFileSearchIndex.status, 'pending'), - isNotNull(workspaceFileSearchIndex.dispatchedAt), - lt(workspaceFileSearchIndex.dispatchedAt, staleBefore) + eq(workspaceFileSearchRevision.status, 'pending'), + isNotNull(workspaceFileSearchRevision.dispatchedAt), + lt(workspaceFileSearchRevision.dispatchedAt, staleBefore) ) ) - .orderBy(asc(workspaceFileSearchIndex.dispatchedAt), asc(workspaceFileSearchIndex.fileId)) + .orderBy(asc(workspaceFileSearchRevision.dispatchedAt), asc(workspaceFileSearchRevision.fileId)) .limit(FILE_SEARCH_INDEX_STALE_REAP_LIMIT) - .for('update', { of: workspaceFileSearchIndex, skipLocked: true }) + .for('update', { of: workspaceFileSearchRevision, skipLocked: true }) const current = rows.filter((row) => row.currentFileId !== null) const obsolete = rows.filter((row) => row.currentFileId === null) const currentFilter = revisionFilter(current) if (currentFilter) { await tx - .update(workspaceFileSearchIndex) + .update(workspaceFileSearchRevision) .set({ dispatchedAt: null, updatedAt: now }) .where(currentFilter) await enqueueWorkspaces( @@ -284,19 +298,7 @@ async function reapStaleClaims(tx: DbTransaction, now: Date): Promise { } const obsoleteFilter = revisionFilter(obsolete) if (obsoleteFilter) { - await tx - .delete(workspaceFileSearchSegment) - .where( - or( - ...obsolete.map((row) => - and( - eq(workspaceFileSearchSegment.fileId, row.fileId), - eq(workspaceFileSearchSegment.sourceContentUpdatedAt, row.sourceContentUpdatedAt) - ) - ) - ) - ) - await tx.delete(workspaceFileSearchIndex).where(obsoleteFilter) + await tx.delete(workspaceFileSearchRevision).where(obsoleteFilter) } return rows.length } @@ -327,7 +329,7 @@ async function claimQueuedWorkspaceJobs( CROSS JOIN LATERAL ( SELECT count(*)::int AS active_count FROM ( - SELECT 1 FROM workspace_file_search_index AS active + SELECT 1 FROM workspace_file_search_revision AS active WHERE active.workspace_id = selected.workspace_id AND active.status = 'pending' AND active.dispatched_at IS NOT NULL LIMIT ${FILE_SEARCH_INDEX_WORKSPACE_OUTSTANDING} @@ -336,7 +338,7 @@ async function claimQueuedWorkspaceJobs( CROSS JOIN LATERAL ( SELECT search_index.workspace_id, search_index.file_id, search_index.source_content_updated_at, search_index.updated_at - FROM workspace_file_search_index AS search_index + FROM workspace_file_search_revision AS search_index INNER JOIN workspace_files AS file ON file.id = search_index.file_id AND file.workspace_id = search_index.workspace_id @@ -352,7 +354,7 @@ async function claimQueuedWorkspaceJobs( ORDER BY queued.updated_at, queued.workspace_id, queued.file_id, queued.source_content_updated_at LIMIT ${remainingGlobalCapacity} ) - UPDATE workspace_file_search_index AS search_index + UPDATE workspace_file_search_revision AS search_index SET dispatched_at = ${now.toISOString()}::timestamp FROM candidates WHERE search_index.file_id = candidates.file_id @@ -366,23 +368,23 @@ async function claimQueuedWorkspaceJobs( `) const remainingForWorkspace = tx - .select({ fileId: workspaceFileSearchIndex.fileId }) - .from(workspaceFileSearchIndex) + .select({ fileId: workspaceFileSearchRevision.fileId }) + .from(workspaceFileSearchRevision) .innerJoin( workspaceFiles, and( - eq(workspaceFiles.id, workspaceFileSearchIndex.fileId), + eq(workspaceFiles.id, workspaceFileSearchRevision.fileId), eq(workspaceFiles.workspaceId, workspaceFileSearchDispatchQueue.workspaceId), eq(workspaceFiles.context, 'workspace'), isNull(workspaceFiles.deletedAt), - eq(workspaceFiles.contentUpdatedAt, workspaceFileSearchIndex.sourceContentUpdatedAt) + eq(workspaceFiles.contentUpdatedAt, workspaceFileSearchRevision.sourceContentUpdatedAt) ) ) .where( and( - eq(workspaceFileSearchIndex.workspaceId, workspaceFileSearchDispatchQueue.workspaceId), - eq(workspaceFileSearchIndex.status, 'pending'), - isNull(workspaceFileSearchIndex.dispatchedAt) + eq(workspaceFileSearchRevision.workspaceId, workspaceFileSearchDispatchQueue.workspaceId), + eq(workspaceFileSearchRevision.status, 'pending'), + isNull(workspaceFileSearchRevision.dispatchedAt) ) ) await tx @@ -407,10 +409,13 @@ async function claimQueuedWorkspaceJobs( workspaceId: row.workspaceId, fileId: row.fileId, sourceContentUpdatedAt: new Date(row.sourceContentUpdatedAt).toISOString(), + dispatchToken: now.toISOString(), })) } -export async function prepareWorkspaceFileSearchDispatch(): Promise { +export async function prepareWorkspaceFileSearchDispatch( + maxOutstanding = FILE_SEARCH_INDEX_MAX_OUTSTANDING +): Promise { return runDispatchPhase('prepare-transaction', () => db.transaction(async (tx) => { await runDispatchPhase('configure-timeouts', () => configureDispatchTimeouts(tx)) @@ -425,19 +430,29 @@ export async function prepareWorkspaceFileSearchDispatch(): Promise seedBackfillPage(tx, now)) const reapedClaims = await runDispatchPhase('reap', () => reapStaleClaims(tx, now)) - const [{ active }] = await tx - .select({ active: count() }) - .from(workspaceFileSearchIndex) - .where( - and( - eq(workspaceFileSearchIndex.status, 'pending'), - isNotNull(workspaceFileSearchIndex.dispatchedAt) - ) - ) - const remainingGlobalCapacity = Math.max( - 0, - FILE_SEARCH_INDEX_MAX_OUTSTANDING - Number(active) - ) + const [{ active, cleanupBacklogged }] = await tx.execute<{ + active: number + cleanupBacklogged: boolean + }>(sql` + SELECT count(*)::int AS active, + (SELECT count(*) >= ${FILE_SEARCH_CLEANUP_BACKLOG_ROWS} FROM ( + SELECT 1 FROM workspace_file_search_build build + CROSS JOIN LATERAL ( + SELECT 1 FROM workspace_file_search_chunk chunk WHERE chunk.build_id = build.id + LIMIT ${FILE_SEARCH_CLEANUP_BACKLOG_ROWS} + ) retired_chunk + WHERE build.expires_at <= now() LIMIT ${FILE_SEARCH_CLEANUP_BACKLOG_ROWS} + ) retired) AS "cleanupBacklogged" + FROM ( + SELECT 1 FROM workspace_file_search_revision + WHERE status = 'pending' AND dispatched_at IS NOT NULL + LIMIT ${FILE_SEARCH_INDEX_MAX_OUTSTANDING} + ) AS active_claims`) + if (cleanupBacklogged) { + logger.info('Workspace file search dispatch paused for cleanup') + return { payloads: [], backfilledFiles, reapedClaims, lockAcquired: true } + } + const remainingGlobalCapacity = Math.max(0, maxOutstanding - Number(active)) if (remainingGlobalCapacity === 0) { return { payloads: [], backfilledFiles, reapedClaims, lockAcquired: true } } @@ -473,15 +488,16 @@ async function releaseDispatchClaims(payloads: readonly WorkspaceFileSearchIndex workspaceId: payload.workspaceId, fileId: payload.fileId, sourceContentUpdatedAt: new Date(payload.sourceContentUpdatedAt), + dispatchToken: payload.dispatchToken, })) await runDispatchPhase('release-claims', () => db.transaction(async (tx) => { const filter = revisionFilter(rows) if (filter) { await tx - .update(workspaceFileSearchIndex) + .update(workspaceFileSearchRevision) .set({ dispatchedAt: null, updatedAt: new Date() }) - .where(and(filter, eq(workspaceFileSearchIndex.status, 'pending'))) + .where(and(filter, eq(workspaceFileSearchRevision.status, 'pending'))) } await enqueueWorkspaces( tx, @@ -500,7 +516,10 @@ async function dispatchPreparedJobs( runDetached('workspace-file-search-index', async () => { for (const payload of payloads) { try { - await indexWorkspaceFileForSearch(payload, new AbortController().signal) + await indexWorkspaceFileForSearch( + payload, + AbortSignal.timeout(FILE_SEARCH_INDEX_MAX_DURATION_SECONDS * 1000) + ) } catch { await markWorkspaceFileSearchIndexFailed(payload) } @@ -526,7 +545,14 @@ async function dispatchPreparedJobs( } export async function dispatchWorkspaceFileSearchIndexJobs(): Promise { - const prepared = await prepareWorkspaceFileSearchDispatch() + await cleanupFileSearchBuilds().catch((error: unknown) => { + logger.warn('Workspace file search cleanup deferred', { code: getPostgresErrorCode(error) }) + }) + const prepared = await prepareWorkspaceFileSearchDispatch( + shouldUseWorkspaceFileSearchTrigger(isTriggerDevEnabled, isInsideTriggerRun()) + ? FILE_SEARCH_INDEX_MAX_OUTSTANDING + : FILE_SEARCH_INDEX_GLOBAL_CONCURRENCY + ) if (!prepared.lockAcquired || prepared.payloads.length === 0) { return { dispatchedFiles: 0, diff --git a/apps/sim/lib/workspace-files/search/extract.test.ts b/apps/sim/lib/workspace-files/search/extract.test.ts index 71215f8c87b..49ae8db022e 100644 --- a/apps/sim/lib/workspace-files/search/extract.test.ts +++ b/apps/sim/lib/workspace-files/search/extract.test.ts @@ -29,7 +29,10 @@ vi.mock('@/lib/file-parsers', () => ({ import { assertKnownSizeWithinLimit, isPayloadSizeLimitError } from '@/lib/core/utils/stream-limits' import { FileParserError } from '@/lib/file-parsers/errors' import type { WorkspaceFileRecord } from '@/lib/uploads/contexts/workspace' -import { FILE_SEARCH_MAX_SOURCE_BYTES } from '@/lib/workspace-files/search/constants' +import { + FILE_SEARCH_MAX_EXTRACTED_BYTES, + FILE_SEARCH_MAX_SOURCE_BYTES, +} from '@/lib/workspace-files/search/constants' import { extractIndexText, loadIndexableBytes } from '@/lib/workspace-files/search/extract' const FILE: WorkspaceFileRecord = { @@ -81,7 +84,10 @@ describe('loadIndexableBytes', () => { maxBytes: FILE_SEARCH_MAX_SOURCE_BYTES, signal, }) - expect(mockResolveServableDoc).toHaveBeenCalledWith(FILE.workspaceId, SOURCE, FILE.name) + expect(mockResolveServableDoc).toHaveBeenCalledWith(FILE.workspaceId, SOURCE, FILE.name, { + maxBytes: FILE_SEARCH_MAX_SOURCE_BYTES, + signal, + }) }) it('settles for the generation source when no artifact exists, without compiling', async () => { @@ -138,7 +144,12 @@ describe('extractIndexText', () => { await expect( extractIndexText({ buffer: FENCED_JSON, kind: 'stored' }, 'data.json', signal) ).resolves.toEqual({ text: 'hello world', partial: true }) - expect(mockParseBuffer).toHaveBeenCalledWith(FENCED_JSON, 'json', { signal }) + expect(mockParseBuffer).toHaveBeenCalledWith(FENCED_JSON, 'json', { + signal, + pdfTextMode: 'complete', + contentMode: 'complete', + maxTextBytes: FILE_SEARCH_MAX_EXTRACTED_BYTES, + }) }) it('indexes the raw text when the parser rejects a text file', async () => { @@ -223,6 +234,17 @@ describe('extractIndexText', () => { expect(mockParseBuffer).not.toHaveBeenCalled() }) + it('rejects the entire expanded document above the extraction budget', async () => { + mockParseBuffer.mockResolvedValue({ content: 'x'.repeat(FILE_SEARCH_MAX_EXTRACTED_BYTES + 1) }) + await expect( + extractIndexText( + { buffer: FENCED_JSON, kind: 'stored' }, + 'data.json', + new AbortController().signal + ) + ).rejects.toMatchObject({ reason: 'extracted_text_too_large' }) + }) + it('indexes an empty file as empty text', async () => { await expect( extractIndexText( diff --git a/apps/sim/lib/workspace-files/search/extract.ts b/apps/sim/lib/workspace-files/search/extract.ts index 7cf369c1c1a..589d54e13a9 100644 --- a/apps/sim/lib/workspace-files/search/extract.ts +++ b/apps/sim/lib/workspace-files/search/extract.ts @@ -1,9 +1,10 @@ -import { type Buffer, isUtf8 } from 'node:buffer' +import { Buffer, isUtf8 } from 'node:buffer' import { createLogger } from '@sim/logger' import { toError } from '@sim/utils/errors' import { resolveServableDoc } from '@/lib/copilot/tools/server/files/doc-compile' import { assertKnownSizeWithinLimit, isPayloadSizeLimitError } from '@/lib/core/utils/stream-limits' import { isSupportedFileType, parseBuffer } from '@/lib/file-parsers' +import { getFileParserErrorCode } from '@/lib/file-parsers/errors' import { fetchWorkspaceFileBuffer, type WorkspaceFileRecord, @@ -13,7 +14,7 @@ import { FILE_SEARCH_MAX_EXTRACTED_BYTES, FILE_SEARCH_MAX_SOURCE_BYTES, } from '@/lib/workspace-files/search/constants' -import { truncateUtf8ToBytes } from '@/lib/workspace-files/search/text' +import { FileSearchExclusionError } from '@/lib/workspace-files/search/index-plan' const logger = createLogger('WorkspaceFileSearchExtract') @@ -53,7 +54,10 @@ export async function loadIndexableBytes( signal, }) signal.throwIfAborted() - const servable = await resolveServableDoc(file.workspaceId, raw, file.name) + const servable = await resolveServableDoc(file.workspaceId, raw, file.name, { + maxBytes: FILE_SEARCH_MAX_SOURCE_BYTES, + signal, + }) if (servable.kind === 'artifact') { assertKnownSizeWithinLimit( servable.buffer.length, @@ -70,8 +74,10 @@ function isPlainText(buffer: Buffer): boolean { } function boundText(content: string, truncated: boolean): ExtractedIndexText { - const bounded = truncateUtf8ToBytes(content, FILE_SEARCH_MAX_EXTRACTED_BYTES) - return { text: bounded, partial: truncated || bounded.length < content.length } + if (Buffer.byteLength(content, 'utf8') > FILE_SEARCH_MAX_EXTRACTED_BYTES) { + throw new FileSearchExclusionError('extracted_text_too_large') + } + return { text: content, partial: truncated } } /** @@ -95,12 +101,19 @@ export async function extractIndexText( const extension = getFileExtension(fileName) if (bytes.kind !== 'source' && extension && isSupportedFileType(extension)) { try { - const parsed = await parseBuffer(buffer, extension, { signal }) + const parsed = await parseBuffer(buffer, extension, { + signal, + pdfTextMode: 'complete', + contentMode: 'complete', + maxTextBytes: FILE_SEARCH_MAX_EXTRACTED_BYTES, + }) if (parsed.metadata?.degraded) return null return boundText(parsed.content ?? '', parsed.metadata?.truncated === true) } catch (error) { signal.throwIfAborted() - if (isPayloadSizeLimitError(error)) throw error + if (isPayloadSizeLimitError(error) || error instanceof FileSearchExclusionError) throw error + if (getFileParserErrorCode(error) === 'complexity_limit') + throw new FileSearchExclusionError('incomplete_extraction') const plainText = isPlainText(buffer) logger.warn( plainText diff --git a/apps/sim/lib/workspace-files/search/index-plan.test.ts b/apps/sim/lib/workspace-files/search/index-plan.test.ts new file mode 100644 index 00000000000..c9c413f2931 --- /dev/null +++ b/apps/sim/lib/workspace-files/search/index-plan.test.ts @@ -0,0 +1,58 @@ +import { describe, expect, it } from 'vitest' +import { + iterateFileSearchChunks, + planFileSearchIndex, +} from '@/lib/workspace-files/search/index-plan' + +const signal = new AbortController().signal + +describe('file search chunk packing', () => { + it.each(['', 'abc', '\n\nabc\r\n', `${'x'.repeat(8192)}\nlast`, `${'🙂'.repeat(9000)}\r\nlast`])( + 'preserves every nonempty logical line and UTF-8 boundaries', + (text) => { + const plan = planFileSearchIndex({ text, partial: false }, signal) + const restored = new Map() + for (const chunk of iterateFileSearchChunks(plan, signal)) { + expect(Buffer.byteLength(chunk.content)).toBeLessThanOrEqual(8192) + expect(chunk.content).not.toContain('\ufffd') + if (chunk.fragment) + restored.set( + chunk.lineStart, + (restored.get(chunk.lineStart) ?? '') + [...chunk.content].slice(chunk.overlap).join('') + ) + else + chunk.content.split('\n').forEach((line, offset) => { + if (line) restored.set(chunk.lineStart + offset, line) + }) + } + const expected = new Map() + text + .replace(/\r(?=\n|$)/g, '') + .split('\n') + .forEach((line, index) => { + if (line) expected.set(index + 1, line) + }) + expect(restored).toEqual(expected) + } + ) + it('rejects incomplete extraction before producing any chunks', () => { + expect(() => planFileSearchIndex({ text: 'prefix', partial: true }, signal)).toThrow( + 'incomplete_extraction' + ) + }) + it('rejects oversize complete text without publishing a prefix', () => { + expect(() => + planFileSearchIndex({ text: 'x'.repeat(25 * 1024 * 1024 + 1), partial: false }, signal) + ).toThrow('extracted_text_too_large') + }) + it('stops iteration when aborted', () => { + const controller = new AbortController() + const chunks = iterateFileSearchChunks( + planFileSearchIndex({ text: 'abc\n'.repeat(10000), partial: false }, signal), + controller.signal + ) + expect(chunks.next().done).toBe(false) + controller.abort() + expect(() => chunks.next()).toThrow() + }) +}) diff --git a/apps/sim/lib/workspace-files/search/index-plan.ts b/apps/sim/lib/workspace-files/search/index-plan.ts new file mode 100644 index 00000000000..55f685106c5 --- /dev/null +++ b/apps/sim/lib/workspace-files/search/index-plan.ts @@ -0,0 +1,105 @@ +import { Buffer } from 'node:buffer' +import { + FILE_SEARCH_CANDIDATE_LITERAL_CHARS, + FILE_SEARCH_CHUNK_BYTES, + FILE_SEARCH_MAX_EXTRACTED_BYTES, +} from '@/lib/workspace-files/search/constants' +import type { ExtractedIndexText } from '@/lib/workspace-files/search/extract' + +export type FileSearchExclusionReason = 'extracted_text_too_large' | 'incomplete_extraction' + +export class FileSearchExclusionError extends Error { + constructor(readonly reason: FileSearchExclusionReason) { + super(`File cannot be fully indexed: ${reason}`) + this.name = 'FileSearchExclusionError' + } +} + +export interface FileSearchChunk { + ordinal: number + lineStart: number + fragment: boolean + /** Unicode characters repeated from the preceding fragment, excluded during reconstruction. */ + overlap: number + content: string +} + +export interface FileSearchIndexPlan { + bytes: Buffer + lineCount: number + indexedBytes: number +} + +/** Admission happens before any chunks are written; incomplete extraction never becomes searchable. */ +export function planFileSearchIndex( + extracted: ExtractedIndexText, + signal: AbortSignal +): FileSearchIndexPlan { + signal.throwIfAborted() + if (extracted.partial) throw new FileSearchExclusionError('incomplete_extraction') + if (Buffer.byteLength(extracted.text, 'utf8') > FILE_SEARCH_MAX_EXTRACTED_BYTES) { + throw new FileSearchExclusionError('extracted_text_too_large') + } + const bytes = Buffer.from(extracted.text.replace(/\r(?=\n|$)/g, ''), 'utf8') + let lineCount = 1 + for (const byte of bytes) if (byte === 10) lineCount++ + return { bytes, lineCount, indexedBytes: bytes.length } +} + +/** Packs short lines together and yields long-line fragments without accumulating a row per line. */ +export function* iterateFileSearchChunks( + plan: FileSearchIndexPlan, + signal: AbortSignal +): Generator { + const { bytes } = plan + let ordinal = 0 + let lineStart = 0 + let lineNumber = 1 + let blockStart = 0 + let blockLine = 1 + const chunk = ( + start: number, + end: number, + line: number, + fragment = false, + overlap = 0 + ): FileSearchChunk => ({ + ordinal: ordinal++, + lineStart: line, + fragment, + overlap, + content: bytes.subarray(start, end).toString('utf8'), + }) + while (lineStart < bytes.length) { + signal.throwIfAborted() + const newline = bytes.indexOf(10, lineStart) + const lineEnd = newline < 0 ? bytes.length : newline + const nextLine = newline < 0 ? bytes.length : newline + 1 + if (nextLine - lineStart > FILE_SEARCH_CHUNK_BYTES) { + if (lineStart > blockStart) yield chunk(blockStart, lineStart, blockLine) + let overlap = 0 + for (let position = lineStart; position < lineEnd; ) { + let end = Math.min(position + FILE_SEARCH_CHUNK_BYTES, lineEnd) + while (end < lineEnd && (bytes[end] & 0xc0) === 0x80) end-- + yield chunk(position, end, lineNumber, true, overlap) + if (end === lineEnd) break + position = end + overlap = 0 + while (overlap < FILE_SEARCH_CANDIDATE_LITERAL_CHARS - 1 && position > lineStart) { + position-- + while (position > lineStart && (bytes[position] & 0xc0) === 0x80) position-- + overlap++ + } + } + blockStart = nextLine + blockLine = lineNumber + 1 + } else if (nextLine - blockStart > FILE_SEARCH_CHUNK_BYTES) { + yield chunk(blockStart, lineStart, blockLine) + blockStart = lineStart + blockLine = lineNumber + } + lineStart = nextLine + lineNumber++ + } + if (bytes.length > blockStart) yield chunk(blockStart, bytes.length, blockLine) +} diff --git a/apps/sim/lib/workspace-files/search/index-state.ts b/apps/sim/lib/workspace-files/search/index-state.ts new file mode 100644 index 00000000000..8a17ff760f1 --- /dev/null +++ b/apps/sim/lib/workspace-files/search/index-state.ts @@ -0,0 +1,293 @@ +import { db } from '@sim/db' +import { + workspaceFileSearchBuild, + workspaceFileSearchChunk, + workspaceFileSearchRevision, + workspaceFiles, +} from '@sim/db/schema' +import { generateId } from '@sim/utils/id' +import { and, eq, sql } from 'drizzle-orm' +import type { DbTransaction } from '@/lib/db/types' +import { + FILE_SEARCH_BUILD_LEASE_MS, + FILE_SEARCH_CLEANUP_BATCH_BUILDS, + FILE_SEARCH_CLEANUP_BATCH_ROWS, + FILE_SEARCH_CLEANUP_BUDGET_MS, + FILE_SEARCH_CLEANUP_MAX_BATCHES, + FILE_SEARCH_INSERT_BATCH_BYTES, + FILE_SEARCH_INSERT_BATCH_ROWS, + FILE_SEARCH_LOCK_TIMEOUT_MS, + FILE_SEARCH_STATEMENT_TIMEOUT_MS, +} from '@/lib/workspace-files/search/constants' +import type { FileSearchChunk } from '@/lib/workspace-files/search/index-plan' + +export interface FileSearchRevision { + workspaceId: string + fileId: string + sourceContentUpdatedAt: Date +} + +export interface FileSearchBuild extends FileSearchRevision { + id: string +} + +function revisionFilter(revision: FileSearchRevision) { + return and( + eq(workspaceFileSearchRevision.fileId, revision.fileId), + eq(workspaceFileSearchRevision.workspaceId, revision.workspaceId), + eq(workspaceFileSearchRevision.sourceContentUpdatedAt, revision.sourceContentUpdatedAt) + ) +} + +async function configure(tx: DbTransaction, timeout = FILE_SEARCH_STATEMENT_TIMEOUT_MS) { + await tx.execute(sql`SELECT set_config('statement_timeout', ${`${timeout}ms`}, true), + set_config('transaction_timeout', ${`${timeout}ms`}, true), + set_config('lock_timeout', ${`${FILE_SEARCH_LOCK_TIMEOUT_MS}ms`}, true)`) +} + +async function lockCurrentFile(tx: DbTransaction, revision: FileSearchRevision): Promise { + const [file] = await tx + .select({ + workspaceId: workspaceFiles.workspaceId, + context: workspaceFiles.context, + deletedAt: workspaceFiles.deletedAt, + contentUpdatedAt: workspaceFiles.contentUpdatedAt, + }) + .from(workspaceFiles) + .where(eq(workspaceFiles.id, revision.fileId)) + .for('update') + .limit(1) + return Boolean( + file && + file.workspaceId === revision.workspaceId && + file.context === 'workspace' && + file.deletedAt === null && + file.contentUpdatedAt.getTime() === revision.sourceContentUpdatedAt.getTime() + ) +} + +/** Lock order is file, build, revision. Chunk batches need only the latter two locks. */ +async function lockBuild(tx: DbTransaction, build: FileSearchBuild): Promise { + const [lease] = await tx + .select({ expiresAt: workspaceFileSearchBuild.expiresAt }) + .from(workspaceFileSearchBuild) + .where(eq(workspaceFileSearchBuild.id, build.id)) + .for('update') + .limit(1) + if (!lease?.expiresAt || lease.expiresAt.getTime() <= Date.now()) return false + const [state] = await tx + .select({ fileId: workspaceFileSearchRevision.fileId }) + .from(workspaceFileSearchRevision) + .where( + and( + revisionFilter(build), + eq(workspaceFileSearchRevision.status, 'pending'), + eq(workspaceFileSearchRevision.buildId, build.id) + ) + ) + .for('update') + .limit(1) + return Boolean(state) +} + +/** A new attempt replaces the build token, never another attempt's chunks. */ +export async function beginFileSearchBuild( + revision: FileSearchRevision, + dispatchToken?: string +): Promise { + return db.transaction(async (tx) => { + await configure(tx) + if (!(await lockCurrentFile(tx, revision))) return null + const [observed] = await tx + .select({ + buildId: workspaceFileSearchRevision.buildId, + dispatchedAt: workspaceFileSearchRevision.dispatchedAt, + }) + .from(workspaceFileSearchRevision) + .where(and(revisionFilter(revision), eq(workspaceFileSearchRevision.status, 'pending'))) + .limit(1) + if (!observed || (dispatchToken && observed.dispatchedAt?.toISOString() !== dispatchToken)) + return null + if (observed?.buildId) { + await tx + .update(workspaceFileSearchBuild) + .set({ expiresAt: new Date() }) + .where(eq(workspaceFileSearchBuild.id, observed.buildId)) + } + const [state] = await tx + .select() + .from(workspaceFileSearchRevision) + .where(revisionFilter(revision)) + .for('update') + .limit(1) + if (!state || state.status !== 'pending') return null + if (dispatchToken && state.dispatchedAt?.toISOString() !== dispatchToken) return null + const build = { ...revision, id: generateId() } + const now = new Date() + await tx + .insert(workspaceFileSearchBuild) + .values({ ...build, expiresAt: new Date(now.getTime() + FILE_SEARCH_BUILD_LEASE_MS) }) + await tx + .update(workspaceFileSearchRevision) + .set({ + buildId: build.id, + failureReason: null, + chunkCount: 0, + indexedBytes: 0, + lineCount: 0, + dispatchedAt: state.dispatchedAt ?? now, + updatedAt: now, + }) + .where(revisionFilter(revision)) + return build + }) +} + +/** Each batch is fenced and byte-bounded; no file or parser work runs inside this transaction. */ +export async function appendFileSearchChunks( + build: FileSearchBuild, + chunks: readonly FileSearchChunk[], + signal: AbortSignal +): Promise { + signal.throwIfAborted() + if (!chunks.length) return true + if ( + chunks.length > FILE_SEARCH_INSERT_BATCH_ROWS || + chunks.reduce((sum, c) => sum + Buffer.byteLength(c.content), 0) > + FILE_SEARCH_INSERT_BATCH_BYTES + ) { + throw new Error('File search insert batch exceeds its budget') + } + return db.transaction(async (tx) => { + await configure(tx) + if (!(await lockBuild(tx, build))) return false + signal.throwIfAborted() + await tx + .insert(workspaceFileSearchChunk) + .values( + chunks.map((chunk) => ({ ...chunk, buildId: build.id, workspaceId: build.workspaceId })) + ) + return true + }) +} + +export type FileSearchPublication = + | { status: 'ready'; lineCount: number; indexedBytes: number; chunkCount: number } + | { status: 'skipped'; failureReason: string } + +/** Publication changes one pointer only after every chunk is durable and the file is still current. */ +export async function publishFileSearchBuild( + build: FileSearchBuild, + publication: FileSearchPublication, + signal: AbortSignal +): Promise { + return db.transaction(async (tx) => { + await configure(tx) + signal.throwIfAborted() + if (!(await lockCurrentFile(tx, build)) || !(await lockBuild(tx, build))) return false + if (publication.status === 'ready') { + const [stored] = await tx.execute<{ count: number; bytes: number }>(sql` + SELECT count(*)::int AS count, + coalesce(sum(octet_length(substring(content FROM overlap + 1))), 0)::int AS bytes + FROM workspace_file_search_chunk WHERE build_id = ${build.id}`) + /** Fragment delimiters are represented by line metadata, so stored bytes can be smaller. */ + if (stored.count !== publication.chunkCount || stored.bytes > publication.indexedBytes) { + throw new Error('File search build is incomplete') + } + } + await tx + .update(workspaceFileSearchBuild) + .set({ expiresAt: publication.status === 'ready' ? null : new Date() }) + .where(eq(workspaceFileSearchBuild.id, build.id)) + await tx + .update(workspaceFileSearchRevision) + .set({ + status: publication.status, + buildId: publication.status === 'ready' ? build.id : null, + failureReason: publication.status === 'skipped' ? publication.failureReason : null, + lineCount: publication.status === 'ready' ? publication.lineCount : 0, + indexedBytes: publication.status === 'ready' ? publication.indexedBytes : 0, + chunkCount: publication.status === 'ready' ? publication.chunkCount : 0, + updatedAt: new Date(), + }) + .where(revisionFilter(build)) + return true + }) +} + +/** Final failure callbacks cannot overwrite a later dispatch or a successful publication. */ +export async function failFileSearchRevision( + revision: FileSearchRevision, + dispatchToken?: string +): Promise { + await db.transaction(async (tx) => { + await configure(tx) + if (!(await lockCurrentFile(tx, revision))) return + const [state] = await tx + .select() + .from(workspaceFileSearchRevision) + .where(revisionFilter(revision)) + .limit(1) + if ( + !state || + state.status !== 'pending' || + (dispatchToken && state.dispatchedAt?.toISOString() !== dispatchToken) + ) + return + if (state.buildId) + await tx + .update(workspaceFileSearchBuild) + .set({ expiresAt: new Date() }) + .where(eq(workspaceFileSearchBuild.id, state.buildId)) + await tx + .update(workspaceFileSearchRevision) + .set({ + status: 'failed', + buildId: null, + failureReason: 'indexing_error', + updatedAt: new Date(), + }) + .where( + and( + revisionFilter(revision), + eq(workspaceFileSearchRevision.status, 'pending'), + dispatchToken + ? eq(workspaceFileSearchRevision.dispatchedAt, new Date(dispatchToken)) + : undefined + ) + ) + }) +} + +/** Expired and invalidated builds drain without cascading a large delete through file mutations. */ +export async function cleanupFileSearchBuilds(): Promise { + const deadline = Date.now() + FILE_SEARCH_CLEANUP_BUDGET_MS + let deleted = 0 + for (let batch = 0; batch < FILE_SEARCH_CLEANUP_MAX_BATCHES && Date.now() < deadline; batch++) { + const result = await db.transaction(async (tx) => { + await configure(tx, Math.max(1, deadline - Date.now())) + const builds = await tx.execute<{ + id: string + }>(sql`SELECT id FROM workspace_file_search_build + WHERE expires_at <= now() ORDER BY expires_at, id LIMIT ${FILE_SEARCH_CLEANUP_BATCH_BUILDS} FOR UPDATE SKIP LOCKED`) + if (!builds.length) return null + const buildIds = sql.join( + builds.map((build) => sql`${build.id}`), + sql`, ` + ) + const [rows] = await tx.execute<{ count: number }>(sql`WITH batch AS ( + SELECT build_id, ordinal FROM workspace_file_search_chunk WHERE build_id IN (${buildIds}) + ORDER BY build_id, ordinal LIMIT ${FILE_SEARCH_CLEANUP_BATCH_ROWS} + ), deleted AS ( + DELETE FROM workspace_file_search_chunk c USING batch + WHERE c.build_id = batch.build_id AND c.ordinal = batch.ordinal RETURNING 1 + ) SELECT count(*)::int AS count FROM deleted`) + await tx.execute(sql`DELETE FROM workspace_file_search_build build WHERE id IN (${buildIds}) + AND NOT EXISTS (SELECT 1 FROM workspace_file_search_chunk chunk WHERE chunk.build_id = build.id)`) + return rows.count + }) + if (result === null) break + deleted += result + } + return deleted +} diff --git a/apps/sim/lib/workspace-files/search/indexing.test.ts b/apps/sim/lib/workspace-files/search/indexing.test.ts new file mode 100644 index 00000000000..83b8bf55eb7 --- /dev/null +++ b/apps/sim/lib/workspace-files/search/indexing.test.ts @@ -0,0 +1,114 @@ +import { beforeEach, describe, expect, it, vi } from 'vitest' + +const mocks = vi.hoisted(() => ({ + begin: vi.fn(), + append: vi.fn(), + publish: vi.fn(), + fail: vi.fn(), + file: vi.fn(), + load: vi.fn(), + extract: vi.fn(), +})) +vi.mock('@/lib/workspace-files/search/index-state', () => ({ + beginFileSearchBuild: mocks.begin, + appendFileSearchChunks: mocks.append, + publishFileSearchBuild: mocks.publish, + failFileSearchRevision: mocks.fail, +})) +vi.mock('@/lib/uploads/contexts/workspace', () => ({ getWorkspaceFile: mocks.file })) +vi.mock('@/lib/workspace-files/search/extract', () => ({ + loadIndexableBytes: mocks.load, + extractIndexText: mocks.extract, +})) + +import { + FILE_SEARCH_INSERT_BATCH_BYTES, + FILE_SEARCH_INSERT_BATCH_ROWS, + FILE_SEARCH_MAX_SOURCE_BYTES, +} from '@/lib/workspace-files/search/constants' +import type { FileSearchChunk } from '@/lib/workspace-files/search/index-plan' +import { indexWorkspaceFileForSearch } from '@/lib/workspace-files/search/indexing' + +const payload = { + workspaceId: 'workspace', + fileId: 'file', + sourceContentUpdatedAt: '2026-01-01T00:00:00.000Z', + dispatchToken: '2026-01-02T00:00:00.000Z', +} +const signal = new AbortController().signal + +describe('complete-file indexing worker', () => { + beforeEach(() => { + vi.clearAllMocks() + mocks.begin.mockResolvedValue({ id: 'build', ...payload }) + mocks.append.mockResolvedValue(true) + mocks.publish.mockResolvedValue(true) + mocks.file.mockResolvedValue({ + name: 'sample.txt', + size: 6, + contentUpdatedAt: new Date(payload.sourceContentUpdatedAt), + }) + mocks.load.mockResolvedValue({ buffer: Buffer.from('needle') }) + mocks.extract.mockResolvedValue({ text: 'needle', partial: false }) + }) + it('ignores a legacy task without a dispatch token', async () => { + await indexWorkspaceFileForSearch({ ...payload, dispatchToken: undefined }, signal) + expect(mocks.begin).not.toHaveBeenCalled() + }) + it('does no storage work for an obsolete dispatch', async () => { + mocks.begin.mockResolvedValue(null) + await indexWorkspaceFileForSearch(payload, signal) + expect(mocks.load).not.toHaveBeenCalled() + expect(mocks.publish).not.toHaveBeenCalled() + }) + it('rejects an oversized source before downloading', async () => { + mocks.file.mockResolvedValue({ + size: FILE_SEARCH_MAX_SOURCE_BYTES + 1, + contentUpdatedAt: new Date(payload.sourceContentUpdatedAt), + }) + await indexWorkspaceFileForSearch(payload, signal) + expect(mocks.load).not.toHaveBeenCalled() + expect(mocks.publish).toHaveBeenCalledWith( + expect.anything(), + { status: 'skipped', failureReason: 'source_too_large' }, + signal + ) + }) + it('never publishes a parser prefix', async () => { + mocks.extract.mockResolvedValue({ text: 'needle', partial: true }) + await indexWorkspaceFileForSearch(payload, signal) + expect(mocks.append).not.toHaveBeenCalled() + expect(mocks.publish).toHaveBeenCalledWith( + expect.anything(), + { status: 'skipped', failureReason: 'incomplete_extraction' }, + signal + ) + }) + it('flushes byte-bounded batches before publishing all chunks', async () => { + mocks.extract.mockResolvedValue({ text: 'abc\n'.repeat(600_000), partial: false }) + await indexWorkspaceFileForSearch(payload, signal) + let rows = 0 + for (const [, chunks] of mocks.append.mock.calls as [unknown, FileSearchChunk[]][]) { + expect(chunks.length).toBeLessThanOrEqual(FILE_SEARCH_INSERT_BATCH_ROWS) + expect( + chunks.reduce((sum, chunk) => sum + Buffer.byteLength(chunk.content), 0) + ).toBeLessThanOrEqual(FILE_SEARCH_INSERT_BATCH_BYTES) + rows += chunks.length + } + expect(mocks.append.mock.calls.length).toBeGreaterThan(1) + expect(rows).toBeLessThan(300) + expect(mocks.publish).toHaveBeenCalledWith( + expect.anything(), + { status: 'ready', chunkCount: rows, lineCount: 600001, indexedBytes: 2400000 }, + signal + ) + expect(mocks.append.mock.invocationCallOrder.at(-1)).toBeLessThan( + mocks.publish.mock.invocationCallOrder[0] + ) + }) + it('stops immediately when a retry loses its build token', async () => { + mocks.append.mockResolvedValue(false) + await indexWorkspaceFileForSearch(payload, signal) + expect(mocks.publish).not.toHaveBeenCalled() + }) +}) diff --git a/apps/sim/lib/workspace-files/search/indexing.ts b/apps/sim/lib/workspace-files/search/indexing.ts index d62b56c065a..b35a02a3647 100644 --- a/apps/sim/lib/workspace-files/search/indexing.ts +++ b/apps/sim/lib/workspace-files/search/indexing.ts @@ -1,13 +1,6 @@ import { Buffer } from 'node:buffer' -import { db } from '@sim/db' -import { - workspaceFileSearchIndex, - workspaceFileSearchSegment, - workspaceFiles, -} from '@sim/db/schema' import { createLogger } from '@sim/logger' -import { toError } from '@sim/utils/errors' -import { and, eq, isNull, ne, or } from 'drizzle-orm' +import { describeError } from '@sim/utils/errors' import { isPayloadSizeLimitError } from '@/lib/core/utils/stream-limits' import { getWorkspaceFile } from '@/lib/uploads/contexts/workspace' import { @@ -16,7 +9,19 @@ import { FILE_SEARCH_MAX_SOURCE_BYTES, } from '@/lib/workspace-files/search/constants' import { extractIndexText, loadIndexableBytes } from '@/lib/workspace-files/search/extract' -import { iterateLogicalLines, segmentLogicalLine } from '@/lib/workspace-files/search/text' +import { + type FileSearchChunk, + FileSearchExclusionError, + iterateFileSearchChunks, + planFileSearchIndex, +} from '@/lib/workspace-files/search/index-plan' +import { + appendFileSearchChunks, + beginFileSearchBuild, + type FileSearchRevision, + failFileSearchRevision, + publishFileSearchBuild, +} from '@/lib/workspace-files/search/index-state' const logger = createLogger('WorkspaceFileSearchIndexer') @@ -24,196 +29,15 @@ export interface WorkspaceFileSearchIndexPayload { workspaceId: string fileId: string sourceContentUpdatedAt: string + /** Identifies the dispatch claim so stale callbacks cannot change a newer run. */ + dispatchToken?: string } -type SearchIndexStatus = 'ready' | 'skipped' | 'failed' - -function sameRevision(left: Date | null | undefined, right: Date): boolean { - return Boolean(left && left.getTime() === right.getTime()) -} - -async function clearRevision( - workspaceId: string, - fileId: string, - sourceContentUpdatedAt: Date -): Promise { - await db - .delete(workspaceFileSearchSegment) - .where( - and( - eq(workspaceFileSearchSegment.workspaceId, workspaceId), - eq(workspaceFileSearchSegment.fileId, fileId), - eq(workspaceFileSearchSegment.sourceContentUpdatedAt, sourceContentUpdatedAt) - ) - ) -} - -async function discardObsoleteRevision(options: { - workspaceId: string - fileId: string - sourceContentUpdatedAt: Date -}): Promise { - await db.transaction(async (tx) => { - await tx - .delete(workspaceFileSearchSegment) - .where( - and( - eq(workspaceFileSearchSegment.workspaceId, options.workspaceId), - eq(workspaceFileSearchSegment.fileId, options.fileId), - eq(workspaceFileSearchSegment.sourceContentUpdatedAt, options.sourceContentUpdatedAt) - ) - ) - await tx - .delete(workspaceFileSearchIndex) - .where( - and( - eq(workspaceFileSearchIndex.workspaceId, options.workspaceId), - eq(workspaceFileSearchIndex.fileId, options.fileId), - eq(workspaceFileSearchIndex.sourceContentUpdatedAt, options.sourceContentUpdatedAt) - ) - ) - }) -} - -async function markTerminal(options: { - workspaceId: string - fileId: string - sourceContentUpdatedAt: Date - status: SearchIndexStatus - partial?: boolean - failureReason?: string - lineCount?: number - indexedBytes?: number -}): Promise { - return db.transaction(async (tx) => { - const [current] = await tx - .select({ - contentUpdatedAt: workspaceFiles.contentUpdatedAt, - deletedAt: workspaceFiles.deletedAt, - context: workspaceFiles.context, - workspaceId: workspaceFiles.workspaceId, - }) - .from(workspaceFiles) - .where(eq(workspaceFiles.id, options.fileId)) - .for('update') - .limit(1) - - const isCurrent = - current?.workspaceId === options.workspaceId && - current.context === 'workspace' && - current.deletedAt === null && - sameRevision(current.contentUpdatedAt, options.sourceContentUpdatedAt) - if (!isCurrent) { - await tx - .delete(workspaceFileSearchSegment) - .where( - and( - eq(workspaceFileSearchSegment.workspaceId, options.workspaceId), - eq(workspaceFileSearchSegment.fileId, options.fileId), - eq(workspaceFileSearchSegment.sourceContentUpdatedAt, options.sourceContentUpdatedAt) - ) - ) - await tx - .delete(workspaceFileSearchIndex) - .where( - and( - eq(workspaceFileSearchIndex.workspaceId, options.workspaceId), - eq(workspaceFileSearchIndex.fileId, options.fileId), - eq(workspaceFileSearchIndex.sourceContentUpdatedAt, options.sourceContentUpdatedAt) - ) - ) - return false - } - - await tx - .insert(workspaceFileSearchIndex) - .values({ - fileId: options.fileId, - workspaceId: options.workspaceId, - sourceContentUpdatedAt: options.sourceContentUpdatedAt, - status: options.status, - partial: options.partial ?? false, - failureReason: options.failureReason, - lineCount: options.lineCount ?? 0, - indexedBytes: options.indexedBytes ?? 0, - dispatchedAt: new Date(), - }) - .onConflictDoUpdate({ - target: [workspaceFileSearchIndex.fileId, workspaceFileSearchIndex.sourceContentUpdatedAt], - set: { - status: options.status, - partial: options.partial ?? false, - failureReason: options.failureReason, - lineCount: options.lineCount ?? 0, - indexedBytes: options.indexedBytes ?? 0, - updatedAt: new Date(), - }, - }) - await tx - .delete(workspaceFileSearchSegment) - .where( - and( - eq(workspaceFileSearchSegment.fileId, options.fileId), - ne(workspaceFileSearchSegment.sourceContentUpdatedAt, options.sourceContentUpdatedAt) - ) - ) - await tx - .delete(workspaceFileSearchIndex) - .where( - and( - eq(workspaceFileSearchIndex.fileId, options.fileId), - ne(workspaceFileSearchIndex.sourceContentUpdatedAt, options.sourceContentUpdatedAt), - or( - ne(workspaceFileSearchIndex.status, 'pending'), - isNull(workspaceFileSearchIndex.dispatchedAt) - ) - ) - ) - return true - }) -} - -async function insertSearchSegments(options: { - workspaceId: string - fileId: string - sourceContentUpdatedAt: Date - text: string - signal: AbortSignal -}): Promise { - type SegmentInsert = typeof workspaceFileSearchSegment.$inferInsert - let batch: SegmentInsert[] = [] - let batchBytes = 0 - let lineCount = 0 - - const flush = async () => { - if (batch.length === 0) return - options.signal.throwIfAborted() - await db.insert(workspaceFileSearchSegment).values(batch) - batch = [] - batchBytes = 0 - } - - for (const line of iterateLogicalLines(options.text)) { - lineCount = line.lineNumber - for (const segment of segmentLogicalLine(line)) { - const segmentBytes = Buffer.byteLength(segment.content, 'utf8') - if ( - batch.length >= FILE_SEARCH_INSERT_BATCH_ROWS || - (batch.length > 0 && batchBytes + segmentBytes > FILE_SEARCH_INSERT_BATCH_BYTES) - ) { - await flush() - } - batch.push({ - workspaceId: options.workspaceId, - fileId: options.fileId, - sourceContentUpdatedAt: options.sourceContentUpdatedAt, - ...segment, - }) - batchBytes += segmentBytes - } - } - await flush() - return lineCount +function parseRevision(payload: WorkspaceFileSearchIndexPayload): FileSearchRevision { + const sourceContentUpdatedAt = new Date(payload.sourceContentUpdatedAt) + if (Number.isNaN(sourceContentUpdatedAt.getTime())) + throw new Error('Invalid workspace file search revision') + return { workspaceId: payload.workspaceId, fileId: payload.fileId, sourceContentUpdatedAt } } export async function indexWorkspaceFileForSearch( @@ -221,130 +45,91 @@ export async function indexWorkspaceFileForSearch( signal: AbortSignal ): Promise { signal.throwIfAborted() - const sourceContentUpdatedAt = new Date(payload.sourceContentUpdatedAt) - if (Number.isNaN(sourceContentUpdatedAt.getTime())) { - throw new Error('Workspace file search index payload has an invalid source revision') - } - - const file = await getWorkspaceFile(payload.workspaceId, payload.fileId, { - throwOnError: true, - }) - if (!file || !sameRevision(file.contentUpdatedAt, sourceContentUpdatedAt)) { - await discardObsoleteRevision({ ...payload, sourceContentUpdatedAt }) - return - } - - const [state] = await db - .select({ - status: workspaceFileSearchIndex.status, - workspaceId: workspaceFileSearchIndex.workspaceId, - }) - .from(workspaceFileSearchIndex) - .where( - and( - eq(workspaceFileSearchIndex.fileId, payload.fileId), - eq(workspaceFileSearchIndex.sourceContentUpdatedAt, sourceContentUpdatedAt) - ) - ) - .limit(1) - if (state && state.workspaceId !== payload.workspaceId) { - await discardObsoleteRevision({ ...payload, sourceContentUpdatedAt }) - return - } - if (state?.status === 'ready' || state?.status === 'skipped') return - - await db - .insert(workspaceFileSearchIndex) - .values({ - fileId: payload.fileId, - workspaceId: payload.workspaceId, - sourceContentUpdatedAt, - status: 'pending', - dispatchedAt: new Date(), - }) - .onConflictDoUpdate({ - target: [workspaceFileSearchIndex.fileId, workspaceFileSearchIndex.sourceContentUpdatedAt], - set: { - status: 'pending', - failureReason: null, - partial: false, - lineCount: 0, - indexedBytes: 0, - updatedAt: new Date(), - }, - }) - await clearRevision(payload.workspaceId, payload.fileId, sourceContentUpdatedAt) - - if (file.size > FILE_SEARCH_MAX_SOURCE_BYTES) { - await markTerminal({ - ...payload, - sourceContentUpdatedAt, - status: 'skipped', - failureReason: 'source_too_large', - }) - return - } - + if (!payload.dispatchToken) return + const revision = parseRevision(payload) + const build = await beginFileSearchBuild(revision, payload.dispatchToken) + if (!build) return + const startedAt = Date.now() try { + const file = await getWorkspaceFile(payload.workspaceId, payload.fileId, { throwOnError: true }) + if (!file || file.contentUpdatedAt?.getTime() !== revision.sourceContentUpdatedAt.getTime()) + return + if (file.size > FILE_SEARCH_MAX_SOURCE_BYTES) { + await publishFileSearchBuild( + build, + { status: 'skipped', failureReason: 'source_too_large' }, + signal + ) + return + } const bytes = await loadIndexableBytes(file, signal) - signal.throwIfAborted() const extracted = await extractIndexText(bytes, file.name, signal) if (!extracted) { - await markTerminal({ - ...payload, - sourceContentUpdatedAt, - status: 'skipped', - failureReason: 'binary_or_degraded', - }) + await publishFileSearchBuild( + build, + { status: 'skipped', failureReason: 'binary_or_degraded' }, + signal + ) return } - const lineCount = await insertSearchSegments({ - ...payload, - sourceContentUpdatedAt, - text: extracted.text, - signal, - }) - await markTerminal({ + const plan = planFileSearchIndex(extracted, signal) + let batch: FileSearchChunk[] = [] + let batchBytes = 0 + let chunkCount = 0 + for (const chunk of iterateFileSearchChunks(plan, signal)) { + const chunkBytes = Buffer.byteLength(chunk.content, 'utf8') + if ( + batch.length && + (batch.length >= FILE_SEARCH_INSERT_BATCH_ROWS || + batchBytes + chunkBytes > FILE_SEARCH_INSERT_BATCH_BYTES) + ) { + if (!(await appendFileSearchChunks(build, batch, signal))) return + batch = [] + batchBytes = 0 + } + batch.push(chunk) + batchBytes += chunkBytes + chunkCount++ + } + if (!(await appendFileSearchChunks(build, batch, signal))) return + const published = await publishFileSearchBuild( + build, + { status: 'ready', chunkCount, lineCount: plan.lineCount, indexedBytes: plan.indexedBytes }, + signal + ) + logger.info('Workspace file search build completed', { ...payload, - sourceContentUpdatedAt, - status: 'ready', - partial: extracted.partial, - lineCount, - indexedBytes: Buffer.byteLength(extracted.text, 'utf8'), + buildId: build.id, + published, + sourceBytes: bytes.buffer.length, + indexedBytes: plan.indexedBytes, + chunkCount, + lineCount: plan.lineCount, + durationMs: Date.now() - startedAt, }) } catch (error) { - if (signal.aborted) throw error - if (isPayloadSizeLimitError(error)) { - await clearRevision(payload.workspaceId, payload.fileId, sourceContentUpdatedAt) - await markTerminal({ - ...payload, - sourceContentUpdatedAt, - status: 'skipped', - failureReason: 'source_too_large', - }) + signal.throwIfAborted() + if (isPayloadSizeLimitError(error) || error instanceof FileSearchExclusionError) { + const failureReason = + error instanceof FileSearchExclusionError ? error.reason : 'source_too_large' + await publishFileSearchBuild(build, { status: 'skipped', failureReason }, signal) + logger.info('Workspace file excluded from search', { ...payload, reason: failureReason }) return } - await clearRevision(payload.workspaceId, payload.fileId, sourceContentUpdatedAt) logger.error('Workspace file search indexing failed', { - workspaceId: payload.workspaceId, - fileId: payload.fileId, - errorType: toError(error).name, + ...payload, + error: describeError(error), + durationMs: Date.now() - startedAt, }) throw error } } -/** Marks a revision failed only after Trigger.dev has exhausted every retry attempt. */ +/** Called only after the task exhausts its retries. */ export async function markWorkspaceFileSearchIndexFailed( payload: WorkspaceFileSearchIndexPayload ): Promise { - const sourceContentUpdatedAt = new Date(payload.sourceContentUpdatedAt) - if (Number.isNaN(sourceContentUpdatedAt.getTime())) return - await clearRevision(payload.workspaceId, payload.fileId, sourceContentUpdatedAt) - await markTerminal({ - ...payload, - sourceContentUpdatedAt, - status: 'failed', - failureReason: 'indexing_error', - }) + if (!payload.dispatchToken || Number.isNaN(new Date(payload.sourceContentUpdatedAt).getTime())) + return + await failFileSearchRevision(parseRevision(payload), payload.dispatchToken) } diff --git a/apps/sim/lib/workspace-files/search/pattern.test.ts b/apps/sim/lib/workspace-files/search/pattern.test.ts index f8ffeed686e..c98bf5639f9 100644 --- a/apps/sim/lib/workspace-files/search/pattern.test.ts +++ b/apps/sim/lib/workspace-files/search/pattern.test.ts @@ -38,7 +38,6 @@ describe('compileFileSearchPattern', () => { caseSensitive: false, sqlPattern: '%100\\%\\_done%', literalText: '100%_done', - wholeLineOnly: false, }) }) @@ -69,12 +68,6 @@ describe('compileFileSearchPattern', () => { expect(compileFileSearchPattern('Error \\d+', 'regex').caseSensitive).toBe(true) }) - it('restricts an anchored pattern to segments that hold a whole line', () => { - expect(compileFileSearchPattern('^import x', 'regex').wholeLineOnly).toBe(true) - expect(compileFileSearchPattern('import x;$', 'regex').wholeLineOnly).toBe(true) - expect(compileFileSearchPattern('import x', 'regex').wholeLineOnly).toBe(false) - }) - it('requires a literal run long enough for the trigram index to be used', () => { expect(() => compileFileSearchPattern('\\w+ \\d+', 'regex')).toThrow(FileSearchPatternError) expect(() => compileFileSearchPattern('\\w+ \\d+', 'regex')).toThrow( diff --git a/apps/sim/lib/workspace-files/search/pattern.ts b/apps/sim/lib/workspace-files/search/pattern.ts index 84105fdb19b..644db8c2910 100644 --- a/apps/sim/lib/workspace-files/search/pattern.ts +++ b/apps/sim/lib/workspace-files/search/pattern.ts @@ -1,5 +1,6 @@ import { getErrorMessage } from '@sim/utils/errors' import { + FILE_SEARCH_CANDIDATE_LITERAL_CHARS, FILE_SEARCH_MAX_QUERY_LENGTH, FILE_SEARCH_MIN_QUERY_LENGTH, } from '@/lib/workspace-files/search/constants' @@ -17,13 +18,7 @@ export interface FileSearchMatchRange { end: number } -/** - * One query, resolved into everything the rest of the search needs to know about - * it. Every mode-specific decision — how PostgreSQL matches a segment, whether - * the segment must be a whole logical line, where the match sits inside it — - * lives here, so the repository builds one query shape and the preview renderer - * one preview shape regardless of mode. - */ +/** Validated SQL matching semantics and bounded preview rendering for both search modes. */ export interface CompiledFileSearchPattern { mode: FileSearchMode /** @@ -34,20 +29,10 @@ export interface CompiledFileSearchPattern { caseSensitive: boolean /** The operand for `LIKE` / `ILIKE` in exact mode, or `~` / `~*` in regex mode. */ sqlPattern: string - /** - * The exact text every match equals, when there is one. A literal match has a - * known length and position, which is what lets a caller rank two segments of - * the same logical line by how much of it surrounds the match; a regex match - * has neither, so this is `null` in regex mode. - */ + /** OR-ed LIKE patterns used only to select conservative chunk candidates. */ + candidatePatterns: string[] | null + /** Exact text to locate for a literal query; regex offsets are resolved by PostgreSQL. */ literalText: string | null - /** - * Whether the pattern may only match a segment that holds its whole logical - * line. `^` and `$` bind to the segment PostgreSQL matches, so on a line long - * enough to have been split they would anchor mid-line; restricting the match - * to unsplit lines trades those matches for never reporting a false one. - */ - wholeLineOnly: boolean /** * Locates the match inside a segment PostgreSQL already matched — but only * where locating it is bounded work. Exact mode scans for a known string. @@ -124,8 +109,10 @@ function compileExactPattern(query: string): CompiledFileSearchPattern { mode: 'exact', caseSensitive, sqlPattern: `%${escapeFileSearchLikePattern(query)}%`, + candidatePatterns: [ + `%${escapeFileSearchLikePattern([...query].slice(0, FILE_SEARCH_CANDIDATE_LITERAL_CHARS).join(''))}%`, + ], literalText: query, - wholeLineOnly: false, findMatchRange: (segment) => findLiteralMatchRange(segment, query, caseSensitive), } } @@ -158,8 +145,10 @@ function compileRegexPattern(query: string): CompiledFileSearchPattern { mode: 'regex', caseSensitive, sqlPattern: analysis.postgresSource, + candidatePatterns: + analysis.candidateLiterals?.map((literal) => `%${escapeFileSearchLikePattern(literal)}%`) ?? + null, literalText: null, - wholeLineOnly: analysis.anchored, findMatchRange: () => null, } } diff --git a/apps/sim/lib/workspace-files/search/regex.test.ts b/apps/sim/lib/workspace-files/search/regex.test.ts index 943549f69d2..446cb23169b 100644 --- a/apps/sim/lib/workspace-files/search/regex.test.ts +++ b/apps/sim/lib/workspace-files/search/regex.test.ts @@ -122,6 +122,34 @@ describe('analyzeFileSearchRegex', () => { }) }) + describe('conservative fragment candidates', () => { + it.each([ + ['alpha|omega', ['alpha', 'omega']], + ['(?:alpha)?omega', ['omega', 'alphaomega']], + ['(?:ab){2,5}', ['abab', 'ababababab']], + ['(?:a(?:x|y)bc){2}', ['axb caybc'.replace(' ', ''), 'aybcaxbc']], + ['ab(?:😀|😁)cde', ['ab😀cde', 'ab😁cde']], + ['(?:🙂ab|🙃cd)+', ['🙂ab', '🙃cd', '🙂ab🙃cd']], + ['(?:ab🙂|cd🙂)ef', ['ab🙂ef', 'cd🙂ef']], + ['(?:abc|def){0,3}ghi', ['ghi', 'abcdefghi']], + ['(?:abc){1000}xyz', [`${'abc'.repeat(1000)}xyz`]], + ['a{1000}(?:bcd|efg)', [`${'a'.repeat(1000)}bcd`, `${'a'.repeat(1000)}efg`]], + ])('never excludes a matching line for %s', (source, matches) => { + const analysis = analyzeFileSearchRegex(source) + for (const match of matches) { + expect(new RegExp(source, 'u').test(match)).toBe(true) + if (analysis.candidateLiterals) { + expect(analysis.candidateLiterals.some((seed) => match.includes(seed))).toBe(true) + expect( + analysis.candidateLiterals.every( + (seed) => [...seed].length === 3 && seed.isWellFormed() + ) + ).toBe(true) + } + } + }) + }) + describe('accepted subset', () => { it.each([ 'error \\d+', diff --git a/apps/sim/lib/workspace-files/search/regex.ts b/apps/sim/lib/workspace-files/search/regex.ts index a37b9a962c7..34bcc1158ff 100644 --- a/apps/sim/lib/workspace-files/search/regex.ts +++ b/apps/sim/lib/workspace-files/search/regex.ts @@ -1,4 +1,5 @@ import { + FILE_SEARCH_CANDIDATE_LITERAL_CHARS, FILE_SEARCH_PATTERN_LITERAL_CAP, FILE_SEARCH_PATTERN_MAX_DEPTH, FILE_SEARCH_PATTERN_MAX_REPEAT, @@ -26,6 +27,8 @@ export interface FileSearchRegexAnalysis { literals: string /** Whether `^` or `$` appears outside a character class. */ anchored: boolean + /** Every match contains at least one of these literals; null means no safe prefilter. */ + candidateLiterals: string[] | null } /** @@ -44,6 +47,7 @@ interface LiteralGuarantee { suffix: string best: number zeroWidth: boolean + seeds: string[] | null } const EMPTY: LiteralGuarantee = { @@ -52,6 +56,7 @@ const EMPTY: LiteralGuarantee = { suffix: '', best: 0, zeroWidth: true, + seeds: null, } const OPAQUE: LiteralGuarantee = { @@ -60,6 +65,7 @@ const OPAQUE: LiteralGuarantee = { suffix: '', best: 0, zeroWidth: false, + seeds: null, } /** PostgreSQL bracket expressions, by the character that opens them after `[`. */ @@ -88,11 +94,7 @@ const POSTGRES_ONLY_ESCAPES: Record = { Z: '$', } -/** - * A run is measured in characters, because that is what `pg_trgm` indexes. The - * parser walks UTF-16 units, so an astral character arrives as two surrogate - * atoms whose concatenation is one character — counting units would score it two. - */ +/** PostgreSQL trigrams and fragment overlap count Unicode characters, not UTF-16 units. */ function runLength(text: string): number { return [...text].length } @@ -107,15 +109,11 @@ function boundedRun(text: string): number { } function head(text: string): string { - return text.length > FILE_SEARCH_PATTERN_LITERAL_CAP - ? text.slice(0, FILE_SEARCH_PATTERN_LITERAL_CAP) - : text + return [...text].slice(0, FILE_SEARCH_PATTERN_LITERAL_CAP).join('') } function tail(text: string): string { - return text.length > FILE_SEARCH_PATTERN_LITERAL_CAP - ? text.slice(text.length - FILE_SEARCH_PATTERN_LITERAL_CAP) - : text + return [...text].slice(-FILE_SEARCH_PATTERN_LITERAL_CAP).join('') } function literal(character: string): LiteralGuarantee { @@ -125,9 +123,24 @@ function literal(character: string): LiteralGuarantee { suffix: character, best: runLength(character), zeroWidth: false, + seeds: seed(character), } } +/** A three-character seed fits across the two-character fragment overlap. */ +function seed(text: string): string[] | null { + const characters = [...text] + return characters.length >= FILE_SEARCH_CANDIDATE_LITERAL_CHARS + ? [characters.slice(0, FILE_SEARCH_CANDIDATE_LITERAL_CHARS).join('')] + : null +} + +function bestSeeds(...options: Array): string[] | null { + let best: string[] | null = null + for (const option of options) if (option && (!best || option.length < best.length)) best = option + return best +} + /** * `left` then `right`. A side with a fixed `exact` string is transparent, so the * neighbouring runs join across it — that is what lets `foo(?:)bar` and `^foo` @@ -136,11 +149,17 @@ function literal(character: string): LiteralGuarantee { function concatenate(left: LiteralGuarantee, right: LiteralGuarantee): LiteralGuarantee { const joined = tail(left.suffix) + head(right.prefix) return { - exact: left.exact !== null && right.exact !== null ? head(left.exact + right.exact) : null, + exact: + left.exact !== null && + right.exact !== null && + runLength(left.exact + right.exact) <= FILE_SEARCH_PATTERN_LITERAL_CAP + ? left.exact + right.exact + : null, prefix: head(left.exact !== null ? left.exact + right.prefix : left.prefix), suffix: tail(right.exact !== null ? left.suffix + right.exact : right.suffix), best: Math.max(left.best, right.best, boundedRun(joined)), zeroWidth: left.zeroWidth && right.zeroWidth, + seeds: bestSeeds(left.seeds, right.seeds, seed(joined)), } } @@ -149,29 +168,28 @@ function concatenate(left: LiteralGuarantee, right: LiteralGuarantee): LiteralGu * the weaker branch is the run of the alternation. */ function alternate(left: LiteralGuarantee, right: LiteralGuarantee): LiteralGuarantee { + const leftPrefix = [...left.prefix] + const rightPrefix = [...right.prefix] + const leftSuffix = [...left.suffix] + const rightSuffix = [...right.suffix] let prefixLength = 0 - while ( - prefixLength < left.prefix.length && - prefixLength < right.prefix.length && - left.prefix[prefixLength] === right.prefix[prefixLength] - ) { - prefixLength += 1 - } + while (prefixLength < leftPrefix.length && leftPrefix[prefixLength] === rightPrefix[prefixLength]) + prefixLength++ let suffixLength = 0 while ( - suffixLength < left.suffix.length && - suffixLength < right.suffix.length && - left.suffix[left.suffix.length - 1 - suffixLength] === - right.suffix[right.suffix.length - 1 - suffixLength] - ) { - suffixLength += 1 - } + suffixLength < leftSuffix.length && + suffixLength < rightSuffix.length && + leftSuffix[leftSuffix.length - 1 - suffixLength] === + rightSuffix[rightSuffix.length - 1 - suffixLength] + ) + suffixLength++ return { exact: left.exact !== null && left.exact === right.exact ? left.exact : null, - prefix: left.prefix.slice(0, prefixLength), - suffix: suffixLength === 0 ? '' : left.suffix.slice(left.suffix.length - suffixLength), + prefix: leftPrefix.slice(0, prefixLength).join(''), + suffix: suffixLength === 0 ? '' : leftSuffix.slice(-suffixLength).join(''), best: Math.min(left.best, right.best), zeroWidth: left.zeroWidth && right.zeroWidth, + seeds: left.seeds && right.seeds ? [...new Set([...left.seeds, ...right.seeds])] : null, } } @@ -203,6 +221,7 @@ function repeat(atom: LiteralGuarantee, min: number, max: number): LiteralGuaran suffix: tail(expanded), best: Math.min(FILE_SEARCH_PATTERN_LITERAL_CAP, runLength(atom.exact) * min), zeroWidth: false, + seeds: seed(expanded), } } /** @@ -217,6 +236,7 @@ function repeat(atom: LiteralGuarantee, min: number, max: number): LiteralGuaran suffix: atom.suffix, best: Math.max(atom.best, acrossCopies), zeroWidth: atom.zeroWidth, + seeds: bestSeeds(atom.seeds, min >= 2 ? seed(tail(atom.suffix) + head(atom.prefix)) : null), } } @@ -262,6 +282,7 @@ class FileSearchRegexParser { longestLiteralRun: guarantee.best, literals: this.literalCharacters.join(''), anchored: this.anchored, + candidateLiterals: guarantee.seeds, } } @@ -347,9 +368,10 @@ class FileSearchRegexParser { `Unbalanced ")" at position ${this.index + 1} in the search pattern` ) } - this.index += 1 - this.literalCharacters.push(character as string) - return literal(character as string) + const codePoint = String.fromCodePoint(this.source.codePointAt(this.index)!) + this.index += codePoint.length + this.literalCharacters.push(codePoint) + return literal(codePoint) } private parseGroup(): LiteralGuarantee { diff --git a/apps/sim/lib/workspace-files/search/repository.test.ts b/apps/sim/lib/workspace-files/search/repository.test.ts index 073d1a00298..2cb40bf2c2e 100644 --- a/apps/sim/lib/workspace-files/search/repository.test.ts +++ b/apps/sim/lib/workspace-files/search/repository.test.ts @@ -83,6 +83,10 @@ describe('searchWorkspaceFileIndex fault mapping', () => { }) it('caps how long a search may hold its connection', async () => { + dbChainMockFns.execute + .mockResolvedValueOnce([]) + .mockResolvedValueOnce([{ slot: 1 }]) + .mockResolvedValueOnce([{ slot: 1 }]) await searchWorkspaceFileIndex({ workspaceId: 'workspace-1', pattern: compileFileSearchPattern('needle', 'exact'), diff --git a/apps/sim/lib/workspace-files/search/repository.ts b/apps/sim/lib/workspace-files/search/repository.ts index 6a8a34a84cf..c0f28cd7ad0 100644 --- a/apps/sim/lib/workspace-files/search/repository.ts +++ b/apps/sim/lib/workspace-files/search/repository.ts @@ -1,15 +1,23 @@ import { db } from '@sim/db' -import { - workspaceFileSearchIndex, - workspaceFileSearchSegment, - workspaceFiles, -} from '@sim/db/schema' -import { and, desc, eq, inArray, isNull, lte, or, type SQL, sql } from 'drizzle-orm' +import { workspaceFileSearchRevision, workspaceFiles } from '@sim/db/schema' +import { getPostgresErrorCode } from '@sim/utils/errors' +import { and, eq, inArray, isNull, or, type SQL, type SQLWrapper, sql } from 'drizzle-orm' +import type { DbTransaction } from '@/lib/db/types' import type { FolderIdScope } from '@/lib/folders/scope' import type { WorkspaceFileSecretProvenanceIdentity } from '@/lib/uploads/contexts/workspace/workspace-file-secret-provenance' import { + probeFileSearchCandidates, + readOrderedFileSearchCandidates, + type FileSearchCandidate as SearchCandidate, +} from '@/lib/workspace-files/search/candidates' +import { + FILE_SEARCH_CANDIDATE_PAGE_SIZE, + FILE_SEARCH_CANDIDATE_PROBE_SIZE, FILE_SEARCH_LOCK_TIMEOUT_MS, - FILE_SEARCH_SEGMENT_CHARS, + FILE_SEARCH_MAX_PREVIEW_BYTES, + FILE_SEARCH_MAX_RESULTS, + FILE_SEARCH_QUERY_GLOBAL_CONCURRENCY, + FILE_SEARCH_QUERY_WORKSPACE_CONCURRENCY, FILE_SEARCH_STATEMENT_TIMEOUT_MS, } from '@/lib/workspace-files/search/constants' import { @@ -18,6 +26,7 @@ import { type FileSearchMatchRange, FileSearchPatternError, } from '@/lib/workspace-files/search/pattern' +import { buildMatchExpression } from '@/lib/workspace-files/search/sql-pattern' import { createFileSearchPreview } from '@/lib/workspace-files/search/text' export interface WorkspaceFileSearchIndexStatus { @@ -71,40 +80,9 @@ export class WorkspaceFileSearchUnavailableError extends Error { } } -/** - * Walks to the driver error. Drizzle wraps a failed query in a `DrizzleQueryError` - * that carries no `code` of its own, so reading the top-level error alone finds - * no SQLSTATE and every fault below would fall through as an unexplained one. - */ -function sqlStateOf(error: unknown): string | undefined { - let current: unknown = error - while (current instanceof Error) { - const code = (current as { code?: unknown }).code - if (typeof code === 'string') return code - current = current.cause - } - return undefined -} - -/** - * Rewrites the database faults this read can raise into faults a caller can act - * on, separating the two it causes from the one it merely waits on. - * - * `pg_trgm` only indexes a pattern it can extract trigrams from; a - * punctuation-only, non-ASCII, or too-general one plans as a scan across every - * workspace's segments, so {@link FILE_SEARCH_STATEMENT_TIMEOUT_MS} is what - * stops one search holding a pooled connection. PostgreSQL is also the last of - * the engines a regex passes through, so a construct that slipped the pattern - * analyzer and `RegExp` surfaces here rather than as an unexplained failure. - * - * {@link FILE_SEARCH_LOCK_TIMEOUT_MS} is different in kind: it fires while - * waiting on a conflicting lock — DDL against the segment tables — which no - * query can be rewritten to avoid. Without this arm it would reach the caller as - * an unclassified server error, and folding it in with the two above would tell - * them to fix a pattern that is already correct. - */ +/** Query deadlines cover expensive patterns; lock and transaction faults are retryable. */ function asFileSearchFault(error: unknown): Error | null { - const sqlState = sqlStateOf(error) + const sqlState = getPostgresErrorCode(error) if (sqlState === QUERY_CANCELED) { return new FileSearchPatternError( 'Search timed out. Narrow the search by adding more literal characters to the pattern.' @@ -113,7 +91,7 @@ function asFileSearchFault(error: unknown): Error | null { if (sqlState === INVALID_REGULAR_EXPRESSION) { return new FileSearchPatternError('Invalid search pattern.') } - if (sqlState === LOCK_NOT_AVAILABLE) { + if (sqlState === LOCK_NOT_AVAILABLE || sqlState === '25P04') { return new WorkspaceFileSearchUnavailableError( 'Workspace file search is briefly unavailable while its index is being updated. Try again shortly.' ) @@ -121,34 +99,11 @@ function asFileSearchFault(error: unknown): Error | null { return null } -type SegmentContent = typeof workspaceFileSearchSegment.content - -function buildMatchExpression(content: SegmentContent, pattern: CompiledFileSearchPattern) { - if (pattern.mode === 'regex') { - return pattern.caseSensitive - ? sql`${content} ~ ${pattern.sqlPattern}` - : sql`${content} ~* ${pattern.sqlPattern}` - } - return pattern.caseSensitive - ? sql`${content} LIKE ${pattern.sqlPattern} ESCAPE '\\'` - : sql`${content} ILIKE ${pattern.sqlPattern} ESCAPE '\\'` -} - /** - * Where the match sits inside the segment, located by PostgreSQL. - * - * A regex is never run against a segment in JavaScript: `RegExp` matches by - * backtracking, so an admitted pattern like `(a+)+bcd` takes seconds on one long - * segment and grows exponentially with it, on the event loop, once per returned - * row. PostgreSQL's engine does not backtrack — the same pattern resolves in - * under a millisecond — and this runs inside the read's statement timeout, so - * the cost of locating a match can never exceed the cost of having found it. - * - * Exact mode locates its own match in JavaScript, where scanning for a known - * string is linear, so it selects a constant here rather than paying for a - * second pass. + * PostgreSQL locates regex matches under the request deadline. Never execute user regexes + * in JavaScript against file content: that would put backtracking work on the event loop. */ -function buildMatchOffsets(content: SegmentContent, pattern: CompiledFileSearchPattern) { +function buildMatchOffsets(content: SQLWrapper, pattern: CompiledFileSearchPattern) { if (pattern.mode !== 'regex') { return { matchStart: sql`0`, matchEnd: sql`0` } } @@ -161,10 +116,10 @@ function buildMatchOffsets(content: SegmentContent, pattern: CompiledFileSearchP /** * PostgreSQL counts characters and JavaScript slices by UTF-16 unit, so an - * astral character shifts every offset after it by one. Walking the segment + * astral character shifts every offset after it by one. Walking the bounded preview * converts between them without assuming either width. */ -function toSegmentRange( +function toPreviewRange( content: string, matchStart: number, matchEnd: number @@ -183,21 +138,6 @@ function toSegmentRange( return alignToCodePoints(content, { start, end: units }) } -/** How much of the logical line surrounds a literal match, in the narrower direction. */ -function buildSurroundingContext( - content: SegmentContent, - literalText: string, - caseSensitive: boolean -) { - const matchPosition = caseSensitive - ? sql`strpos(${content}, ${literalText})` - : sql`strpos(lower(${content}), lower(${literalText}))` - return sql`least( - ${matchPosition} - 1, - char_length(${content}) - (${matchPosition} - 1) - char_length(${literalText}) - )` -} - /** * The `workspaceFiles` predicate for a resolved folder scope. * @@ -214,6 +154,68 @@ function buildFolderPredicate(scope: FolderIdScope): SQL | undefined { return inScope ?? atRoot ?? sql`false` } +type SearchLine = { + lineNumber: number + content: string + matchStart: number + matchEnd: number + prefixOmitted: boolean + suffixOmitted: boolean +} + +type SearchRow = SearchCandidate & SearchLine + +/** Complete logical lines stay in PostgreSQL; only bounded previews cross the connection. */ +async function readCandidateLines( + tx: DbTransaction, + candidates: readonly SearchCandidate[], + pattern: CompiledFileSearchPattern, + limit: number +): Promise { + const content = sql`line.content` + const match = buildMatchExpression(content, pattern) + const regexOffsets = buildMatchOffsets(content, pattern) + const matchStart = + pattern.mode === 'regex' + ? regexOffsets.matchStart + : pattern.caseSensitive + ? sql`strpos(${content}, ${pattern.literalText})` + : sql`strpos(lower(${content}), lower(${pattern.literalText}))` + const matchEnd = + pattern.mode === 'regex' + ? regexOffsets.matchEnd + : sql`${matchStart} + char_length(${pattern.literalText})` + const candidate = candidates[0] + const blocks = sql.join( + candidates.map( + (row, position) => + sql`(${position}::int, ${row.buildId}::text, ${row.ordinal}::int, ${row.lineStart}::int)` + ), + sql`, ` + ) + const logicalLines = candidate.fragment + ? sql`SELECT 0::int AS candidate, ${candidate.lineStart}::int AS line_number, string_agg(substring(content FROM overlap + 1), '' ORDER BY ordinal) AS content + FROM workspace_file_search_chunk WHERE build_id = ${candidate.buildId} AND line_start = ${candidate.lineStart} AND fragment` + : sql`SELECT block.position AS candidate, (block.line_start + line.ordinality - 1)::int AS line_number, line.content + FROM (VALUES ${blocks}) AS block(position, build_id, ordinal, line_start) + INNER JOIN workspace_file_search_chunk chunk ON chunk.build_id = block.build_id AND chunk.ordinal = block.ordinal AND NOT chunk.fragment + CROSS JOIN LATERAL string_to_table(chunk.content, E'\\n') WITH ORDINALITY line(content, ordinality)` + const previewCharacters = Math.floor(FILE_SEARCH_MAX_PREVIEW_BYTES / 4) + const lines = await tx.execute(sql` + WITH logical_lines AS MATERIALIZED (${logicalLines}), matched AS MATERIALIZED ( + SELECT line.candidate, line.content, line.line_number, ${matchStart} AS match_start, ${matchEnd} AS match_end + FROM logical_lines line WHERE ${match} ORDER BY line.candidate, line.line_number LIMIT ${limit} + ), preview AS ( + SELECT *, greatest(1, match_start - ${Math.floor(previewCharacters / 4)}) AS preview_start FROM matched + ) + SELECT candidate, line_number AS "lineNumber", substring(content FROM preview_start FOR ${previewCharacters}) AS content, + (match_start - preview_start + 1)::int AS "matchStart", + least(match_end - preview_start + 1, ${previewCharacters + 1})::int AS "matchEnd", + preview_start > 1 AS "prefixOmitted", preview_start + ${previewCharacters} <= char_length(content) AS "suffixOmitted" + FROM preview ORDER BY candidate, line_number`) + return lines.map((line) => ({ ...candidates[line.candidate], ...line })) +} + export async function searchWorkspaceFileIndex({ workspaceId, pattern, @@ -222,9 +224,14 @@ export async function searchWorkspaceFileIndex({ signal, }: SearchWorkspaceFileIndexInput): Promise { signal?.throwIfAborted() + if (!Number.isInteger(maxResults) || maxResults < 1 || maxResults > FILE_SEARCH_MAX_RESULTS) { + throw new FileSearchPatternError( + `Search result limit must be between 1 and ${FILE_SEARCH_MAX_RESULTS}` + ) + } /** - * The segment table carries no folder id, so a scope has to travel through + * The chunk table carries no folder id, so a scope has to travel through * the `workspaceFiles` join both queries already make. A scope that resolved * to nothing must match nothing: `inArray` with an empty list would be a * SQL error, and omitting the predicate would silently search everything, @@ -232,128 +239,123 @@ export async function searchWorkspaceFileIndex({ */ const folderPredicate = folderScope ? buildFolderPredicate(folderScope) : undefined - const content = workspaceFileSearchSegment.content - const matchExpression = buildMatchExpression(content, pattern) - const { matchStart, matchEnd } = buildMatchOffsets(content, pattern) - - /** - * A logical line longer than {@link FILE_SEARCH_SEGMENT_CHARS} is stored as - * several overlapping segments, and `segmentLogicalLine` splits at exactly - * that width — so this predicate selects the segments that are a whole line. - */ - const segmentScope = pattern.wholeLineOnly - ? and( - eq(workspaceFileSearchSegment.workspaceId, workspaceId), - lte(workspaceFileSearchSegment.lineLength, FILE_SEARCH_SEGMENT_CHARS) - ) - : eq(workspaceFileSearchSegment.workspaceId, workspaceId) - - /** - * Which segment of a split line best represents its match. An exact match has - * one length, so the segment with the most text on both sides of it is the - * most readable excerpt. A regex match has no fixed length, so the earliest - * segment wins instead — locating each candidate match in SQL to rank them - * would cost a second regex pass over every matched row. - */ - const segmentPreference = - pattern.literalText === null - ? [workspaceFileSearchSegment.segmentNumber] - : [ - desc(buildSurroundingContext(content, pattern.literalText, pattern.caseSensitive)), - workspaceFileSearchSegment.segmentNumber, - ] - try { - /** - * Both statements run under one set of guards, so neither the match nor the - * coverage count can outlive the timeout. `set_config(..., true)` is - * transaction-local and takes bound parameters, which `SET LOCAL` cannot. - */ - const { rows, coverageRows } = await db.transaction(async (tx) => { - await tx.execute(sql` + /** Metadata pages and line reads share one deadline and a consistent revision snapshot. */ + const { rows, coverageRows } = await db.transaction( + async (tx) => { + await tx.execute(sql` select set_config('statement_timeout', ${`${FILE_SEARCH_STATEMENT_TIMEOUT_MS}ms`}, true), + set_config('transaction_timeout', ${`${FILE_SEARCH_STATEMENT_TIMEOUT_MS}ms`}, true), set_config('lock_timeout', ${`${FILE_SEARCH_LOCK_TIMEOUT_MS}ms`}, true) `) - const matchedRows = await tx - .selectDistinctOn( - [workspaceFiles.originalName, workspaceFiles.id, workspaceFileSearchSegment.lineNumber], - { - fileId: workspaceFiles.id, - fileName: workspaceFiles.originalName, - fileKey: workspaceFiles.key, - ownerUserId: workspaceFiles.userId, - contentUpdatedAt: workspaceFiles.contentUpdatedAt, - lineNumber: workspaceFileSearchSegment.lineNumber, - segmentNumber: workspaceFileSearchSegment.segmentNumber, - segmentStart: workspaceFileSearchSegment.segmentStart, - lineLength: workspaceFileSearchSegment.lineLength, - content: workspaceFileSearchSegment.content, - matchStart, - matchEnd, - } - ) - .from(workspaceFileSearchSegment) - .innerJoin( - workspaceFileSearchIndex, - and( - eq(workspaceFileSearchIndex.fileId, workspaceFileSearchSegment.fileId), - eq( - workspaceFileSearchIndex.sourceContentUpdatedAt, - workspaceFileSearchSegment.sourceContentUpdatedAt - ), - eq(workspaceFileSearchIndex.status, 'ready') - ) - ) - .innerJoin( - workspaceFiles, - and( - eq(workspaceFiles.id, workspaceFileSearchSegment.fileId), - eq(workspaceFiles.workspaceId, workspaceId), - eq(workspaceFiles.context, 'workspace'), - isNull(workspaceFiles.deletedAt), - eq(workspaceFiles.contentUpdatedAt, workspaceFileSearchSegment.sourceContentUpdatedAt), - folderPredicate - ) - ) - .where(and(segmentScope, matchExpression)) - .orderBy( - workspaceFiles.originalName, - workspaceFiles.id, - workspaceFileSearchSegment.lineNumber, - ...segmentPreference - ) - .limit(maxResults + 1) + /** Transaction-owned slots release on completion, cancellation, or connection loss. */ + for (const [scope, capacity] of [ + [`workspace:${workspaceId}`, FILE_SEARCH_QUERY_WORKSPACE_CONCURRENCY], + ['global', FILE_SEARCH_QUERY_GLOBAL_CONCURRENCY], + ] as const) { + const slots = await tx.execute(sql`SELECT slot FROM generate_series(1, ${capacity}) slot + WHERE pg_try_advisory_xact_lock(hashtextextended('workspace-file-search-read:' || ${scope} || ':' || slot::text, 0)) LIMIT 1`) + if (!slots.length) + throw new WorkspaceFileSearchUnavailableError( + 'Workspace file search is busy. Retry shortly.' + ) + } - signal?.throwIfAborted() - const coverage = await tx - .select({ - readyFiles: sql`count(*) filter (where ${workspaceFileSearchIndex.status} = 'ready')::int`, - pendingFiles: sql`count(*) filter (where ${workspaceFileSearchIndex.status} is null or ${workspaceFileSearchIndex.status} = 'pending')::int`, - failedFiles: sql`count(*) filter (where ${workspaceFileSearchIndex.status} = 'failed')::int`, - skippedFiles: sql`count(*) filter (where ${workspaceFileSearchIndex.status} = 'skipped')::int`, - partialFiles: sql`count(*) filter (where ${workspaceFileSearchIndex.partial} is true)::int`, + const deadline = Date.now() + FILE_SEARCH_STATEMENT_TIMEOUT_MS + const guardRemainingTime = async () => { + signal?.throwIfAborted() + const remaining = deadline - Date.now() + if (remaining <= 0) + throw new WorkspaceFileSearchUnavailableError( + 'Search timed out. Narrow the query or folder scope.' + ) + await tx.execute(sql`SELECT set_config('statement_timeout', ${`${remaining}ms`}, true)`) + } + /** Probe without a global sort. Rare queries finish here; broad queries scan files in order. */ + const probed = await probeFileSearchCandidates(tx, { + workspaceId, + pattern, + folderPredicate, }) - .from(workspaceFiles) - .leftJoin( - workspaceFileSearchIndex, - and( - eq(workspaceFileSearchIndex.fileId, workspaceFiles.id), - eq(workspaceFileSearchIndex.sourceContentUpdatedAt, workspaceFiles.contentUpdatedAt) + const broad = probed.length > FILE_SEARCH_CANDIDATE_PROBE_SIZE + const matchedRows: SearchRow[] = [] + let after: { name: string; id: string; lineStart: number } | undefined + while (matchedRows.length <= maxResults) { + await guardRemainingTime() + let candidates = probed + if (broad) { + candidates = await readOrderedFileSearchCandidates( + tx, + { workspaceId, pattern, folderPredicate }, + after + ) + } + for ( + let position = 0; + position < candidates.length && matchedRows.length <= maxResults; + ) { + const first = candidates[position++] + const batch = [first] + if (first.fragment) { + while ( + position < candidates.length && + candidates[position].buildId === first.buildId && + candidates[position].lineStart === first.lineStart + ) + position++ + } else { + while ( + position < candidates.length && + batch.length < FILE_SEARCH_CANDIDATE_PAGE_SIZE && + !candidates[position].fragment + ) + batch.push(candidates[position++]) + } + await guardRemainingTime() + matchedRows.push( + ...(await readCandidateLines(tx, batch, pattern, maxResults + 1 - matchedRows.length)) + ) + } + if (!broad || candidates.length < FILE_SEARCH_CANDIDATE_PAGE_SIZE) break + const last = candidates.at(-1)! + after = { name: last.fileName, id: last.fileId, lineStart: last.lineStart } + } + await guardRemainingTime() + signal?.throwIfAborted() + const coverage = await tx + .select({ + readyFiles: sql`count(*) filter (where ${workspaceFileSearchRevision.status} = 'ready' AND ${workspaceFileSearchRevision.buildId} IS NOT NULL)::int`, + pendingFiles: sql`count(*) filter (where ${workspaceFileSearchRevision.status} is null or ${workspaceFileSearchRevision.status} = 'pending' or (${workspaceFileSearchRevision.status} = 'ready' AND ${workspaceFileSearchRevision.buildId} IS NULL))::int`, + failedFiles: sql`count(*) filter (where ${workspaceFileSearchRevision.status} = 'failed')::int`, + skippedFiles: sql`count(*) filter (where ${workspaceFileSearchRevision.status} = 'skipped')::int`, + partialFiles: sql`0::int`, + }) + .from(workspaceFiles) + .leftJoin( + workspaceFileSearchRevision, + and( + eq(workspaceFileSearchRevision.fileId, workspaceFiles.id), + eq( + workspaceFileSearchRevision.sourceContentUpdatedAt, + workspaceFiles.contentUpdatedAt + ) + ) ) - ) - .where( - and( - eq(workspaceFiles.workspaceId, workspaceId), - eq(workspaceFiles.context, 'workspace'), - isNull(workspaceFiles.deletedAt), - folderPredicate + .where( + and( + eq(workspaceFiles.workspaceId, workspaceId), + eq(workspaceFiles.context, 'workspace'), + isNull(workspaceFiles.deletedAt), + folderPredicate + ) ) - ) - return { rows: matchedRows, coverageRows: coverage } - }) + return { rows: matchedRows, coverageRows: coverage } + }, + { isolationLevel: 'repeatable read', accessMode: 'read only' } + ) signal?.throwIfAborted() const resultRows = rows.slice(0, maxResults) @@ -381,12 +383,9 @@ export async function searchWorkspaceFileIndex({ fileId: row.fileId, lineNumber: row.lineNumber, text: createFileSearchPreview(row.content, pattern, undefined, { - prefixOmitted: row.segmentStart > 0, - suffixOmitted: row.segmentStart + row.content.length < row.lineLength, - matchRange: - pattern.mode === 'regex' - ? toSegmentRange(row.content, row.matchStart, row.matchEnd) - : undefined, + prefixOmitted: row.prefixOmitted, + suffixOmitted: row.suffixOmitted, + matchRange: toPreviewRange(row.content, row.matchStart, row.matchEnd), }), })) signal?.throwIfAborted() diff --git a/apps/sim/lib/workspace-files/search/sql-pattern.ts b/apps/sim/lib/workspace-files/search/sql-pattern.ts new file mode 100644 index 00000000000..f0d07c9eb4f --- /dev/null +++ b/apps/sim/lib/workspace-files/search/sql-pattern.ts @@ -0,0 +1,16 @@ +import { type SQLWrapper, sql } from 'drizzle-orm' +import type { CompiledFileSearchPattern } from '@/lib/workspace-files/search/pattern' + +export function buildMatchExpression( + content: SQLWrapper, + pattern: CompiledFileSearchPattern, + multiline = false +) { + if (pattern.mode === 'regex') { + const source = multiline ? `(?n)${pattern.sqlPattern}` : pattern.sqlPattern + return pattern.caseSensitive ? sql`${content} ~ ${source}` : sql`${content} ~* ${source}` + } + return pattern.caseSensitive + ? sql`${content} LIKE ${pattern.sqlPattern} ESCAPE '\\'` + : sql`${content} ILIKE ${pattern.sqlPattern} ESCAPE '\\'` +} diff --git a/apps/sim/lib/workspace-files/search/text.test.ts b/apps/sim/lib/workspace-files/search/text.test.ts index 86759b42ab9..5a6111e8a45 100644 --- a/apps/sim/lib/workspace-files/search/text.test.ts +++ b/apps/sim/lib/workspace-files/search/text.test.ts @@ -1,41 +1,11 @@ import { Buffer } from 'node:buffer' import { describe, expect, it, vi } from 'vitest' -import { FILE_SEARCH_SEGMENT_CHARS } from '@/lib/workspace-files/search/constants' import { compileFileSearchPattern } from '@/lib/workspace-files/search/pattern' -import { - createFileSearchPreview, - iterateLogicalLines, - segmentLogicalLine, - truncateUtf8ToBytes, -} from '@/lib/workspace-files/search/text' +import { createFileSearchPreview } from '@/lib/workspace-files/search/text' const literal = (query: string) => compileFileSearchPattern(query, 'exact') describe('workspace file search text utilities', () => { - it('normalizes CRLF and preserves one-based logical line numbers', () => { - expect([...iterateLogicalLines('first\r\nsecond\n')]).toEqual([ - { lineNumber: 1, text: 'first' }, - { lineNumber: 2, text: 'second' }, - { lineNumber: 3, text: '' }, - ]) - }) - - it('splits a logical line into one segment exactly when it fits the segment width', () => { - const fits = { lineNumber: 1, text: 'a'.repeat(FILE_SEARCH_SEGMENT_CHARS) } - const overflows = { lineNumber: 1, text: 'a'.repeat(FILE_SEARCH_SEGMENT_CHARS + 1) } - - expect([...segmentLogicalLine(fits)]).toHaveLength(1) - expect([...segmentLogicalLine(overflows)].length).toBeGreaterThan(1) - }) - - it('creates overlapping segments that preserve boundary matches', () => { - const segments = [...segmentLogicalLine({ lineNumber: 3, text: 'abcdefghijklmnop' }, 10, 4)] - expect(segments.map(({ content }) => content)).toEqual(['abcdefghij', 'ghijklmnop']) - expect(segments[1]).toMatchObject({ lineNumber: 3, segmentNumber: 1, segmentStart: 6 }) - expect(segments[0].content).toContain('ghij') - expect(segments[1].content).toContain('ghij') - }) - it('returns a match-centered UTF-8-safe bounded preview', () => { const line = `${'🙂'.repeat(800)}needle${'é'.repeat(800)}` const preview = createFileSearchPreview(line, literal('needle')) @@ -70,7 +40,7 @@ describe('workspace file search text utilities', () => { } }) - it('shows omitted logical-line content beyond the selected segment', () => { + it('shows omitted logical-line content beyond the selected preview', () => { expect( createFileSearchPreview('needle and nearby text', literal('needle'), 2048, { prefixOmitted: true, @@ -100,10 +70,4 @@ describe('workspace file search text utilities', () => { expect(preview).toContain('abc') expect(preview).not.toContain('\uFFFD') }) - - it('truncates extracted text on a UTF-8 boundary', () => { - const truncated = truncateUtf8ToBytes('abc🙂def', 6) - expect(truncated).toBe('abc') - expect(Buffer.byteLength(truncated, 'utf8')).toBeLessThanOrEqual(6) - }) }) diff --git a/apps/sim/lib/workspace-files/search/text.ts b/apps/sim/lib/workspace-files/search/text.ts index 47c1a04079a..24978d2e632 100644 --- a/apps/sim/lib/workspace-files/search/text.ts +++ b/apps/sim/lib/workspace-files/search/text.ts @@ -1,73 +1,10 @@ -import { Buffer, isUtf8 } from 'node:buffer' -import { - FILE_SEARCH_MAX_PREVIEW_BYTES, - FILE_SEARCH_SEGMENT_CHARS, - FILE_SEARCH_SEGMENT_OVERLAP_CHARS, -} from '@/lib/workspace-files/search/constants' +import { Buffer } from 'node:buffer' +import { FILE_SEARCH_MAX_PREVIEW_BYTES } from '@/lib/workspace-files/search/constants' import type { CompiledFileSearchPattern, FileSearchMatchRange, } from '@/lib/workspace-files/search/pattern' -export interface LogicalLine { - lineNumber: number - text: string -} - -export interface SearchSegment { - lineNumber: number - segmentNumber: number - segmentStart: number - lineLength: number - content: string -} - -export function* iterateLogicalLines(text: string): Generator { - let lineStart = 0 - let lineNumber = 1 - for (let index = 0; index <= text.length; index += 1) { - if (index !== text.length && text.charCodeAt(index) !== 10) continue - const hasCarriageReturn = index > lineStart && text.charCodeAt(index - 1) === 13 - yield { - lineNumber, - text: text.slice(lineStart, hasCarriageReturn ? index - 1 : index), - } - lineStart = index + 1 - lineNumber += 1 - } -} - -function safeSegmentEnd(text: string, requestedEnd: number): number { - if (requestedEnd >= text.length) return text.length - const previousCodeUnit = text.charCodeAt(requestedEnd - 1) - const nextCodeUnit = text.charCodeAt(requestedEnd) - return previousCodeUnit >= 0xd800 && previousCodeUnit <= 0xdbff && nextCodeUnit >= 0xdc00 - ? requestedEnd - 1 - : requestedEnd -} - -export function* segmentLogicalLine( - line: LogicalLine, - segmentChars = FILE_SEARCH_SEGMENT_CHARS, - overlapChars = FILE_SEARCH_SEGMENT_OVERLAP_CHARS -): Generator { - if (line.text.length === 0) return - const step = Math.max(1, segmentChars - overlapChars) - let segmentNumber = 0 - for (let start = 0; start < line.text.length; start += step) { - const end = safeSegmentEnd(line.text, Math.min(line.text.length, start + segmentChars)) - yield { - lineNumber: line.lineNumber, - segmentNumber, - segmentStart: start, - lineLength: line.text.length, - content: line.text.slice(start, end), - } - segmentNumber += 1 - if (end === line.text.length) break - } -} - function utf8PrefixWithinBudget(text: string, maxBytes: number): string { let low = 0 let high = text.length @@ -97,23 +34,14 @@ function utf8SuffixWithinBudget(text: string, maxBytes: number): string { return [...utf8PrefixWithinBudget(reversedCodePoints, maxBytes)].reverse().join('') } -export function truncateUtf8ToBytes(text: string, maxBytes: number): string { - const candidate = text.length > maxBytes ? text.slice(0, maxBytes) : text - const encoded = Buffer.from(candidate, 'utf8') - if (encoded.length <= maxBytes) return candidate - let end = maxBytes - while (end > 0 && !isUtf8(encoded.subarray(0, end))) end -= 1 - return encoded.subarray(0, end).toString('utf8') -} - /** - * Renders one matching segment as a bounded, match-centred excerpt. + * Renders one matching line preview as a bounded, match-centred excerpt. * * The excerpt is cut around the match rather than at the head of the line. * `matchRange` carries a match the caller already located — which is how a * regex match arrives, since only PostgreSQL may run one — and otherwise the * pattern locates its own. A match that neither can place still renders, - * anchored at the start of the segment. + * anchored at the start of the preview. */ export function createFileSearchPreview( line: string, diff --git a/apps/sim/tools/file/search.ts b/apps/sim/tools/file/search.ts index 0fe07314b6b..df587b08389 100644 --- a/apps/sim/tools/file/search.ts +++ b/apps/sim/tools/file/search.ts @@ -23,9 +23,9 @@ interface FileSearchResponse extends ToolResponse { */ const TOOL_DESCRIPTIONS: Record = { regex: - 'Search the indexed text of active workspace files for lines matching a regular expression, and return each matching line once with its file ID and line number. Coverage is what the index currently holds. A term that is not found is only authoritative when "complete" is true AND "indexStatus" reports no skipped or partial files; otherwise it is unknown rather than absent, so re-check before creating something on the assumption it is missing. Narrow the search with folderPaths to confine it to one or more folder trees, which also narrows "indexStatus" to those trees.', + 'Search the indexed text of active workspace files for lines matching a regular expression, and return each matching line once with its file ID and line number. Coverage is what the index currently holds. A term that is not found is only authoritative when "complete" is true AND "indexStatus" reports no skipped files; otherwise it is unknown rather than absent, so re-check before creating something on the assumption it is missing. Narrow the search with folderPaths to confine it to one or more folder trees, which also narrows "indexStatus" to those trees.', exact: - 'Search the indexed text of active workspace files for lines containing an exact piece of text, and return each matching line once with its file ID and line number. Coverage is what the index currently holds. A term that is not found is only authoritative when "complete" is true AND "indexStatus" reports no skipped or partial files; otherwise it is unknown rather than absent, so re-check before creating something on the assumption it is missing. Narrow the search with folderPaths to confine it to one or more folder trees, which also narrows "indexStatus" to those trees.', + 'Search the indexed text of active workspace files for lines containing an exact piece of text, and return each matching line once with its file ID and line number. Coverage is what the index currently holds. A term that is not found is only authoritative when "complete" is true AND "indexStatus" reports no skipped files; otherwise it is unknown rather than absent, so re-check before creating something on the assumption it is missing. Narrow the search with folderPaths to confine it to one or more folder trees, which also narrows "indexStatus" to those trees.', } const QUERY_DESCRIPTIONS: Record = { @@ -50,7 +50,7 @@ const DECLARED_QUERY_DESCRIPTION = `${QUERY_DESCRIPTIONS.regex} When the workflo * tell which mode a given block is set to. */ const DECLARED_TOOL_DESCRIPTION = - 'Search the indexed text of active workspace files for lines matching a query, and return each matching line once with its file ID and line number. By default the query is a regular expression; in exact mode it is matched verbatim and metacharacters are literal. Coverage is what the index currently holds. A term that is not found is only authoritative when "complete" is true AND "indexStatus" reports no skipped or partial files; otherwise it is unknown rather than absent, so re-check before creating something on the assumption it is missing. Narrow the search with folderPaths to confine it to one or more folder trees, which also narrows "indexStatus" to those trees.' + 'Search the indexed text of active workspace files for lines matching a query, and return each matching line once with its file ID and line number. By default the query is a regular expression; in exact mode it is matched verbatim and metacharacters are literal. Coverage is what the index currently holds. A term that is not found is only authoritative when "complete" is true AND "indexStatus" reports no skipped files; otherwise it is unknown rather than absent, so re-check before creating something on the assumption it is missing. Narrow the search with folderPaths to confine it to one or more folder trees, which also narrows "indexStatus" to those trees.' export const fileSearchTool: InternalToolConfig = { id: 'file_search', @@ -178,13 +178,16 @@ export const fileSearchTool: InternalToolConfig = JSON.parse( - '{"a2a_cancel_task":{"id":"a2a_cancel_task","name":"A2A Cancel Task","description":"Request cancellation of an in-progress A2A task.","version":"1.0.0","params":{"agentUrl":{"type":"string","required":true,"visibility":"user-only","description":"The A2A agent endpoint URL"},"taskId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The task ID to cancel"},"apiKey":{"type":"string","required":false,"visibility":"user-only","description":"API key for authentication (if required)"}},"hostedApiKey":"none"},"a2a_get_agent_card":{"id":"a2a_get_agent_card","name":"A2A Get Agent Card","description":"Fetch the Agent Card (discovery document) for an external A2A agent.","version":"1.0.0","params":{"agentUrl":{"type":"string","required":true,"visibility":"user-only","description":"The A2A agent endpoint URL"},"apiKey":{"type":"string","required":false,"visibility":"user-only","description":"API key for authentication (if required)"}},"hostedApiKey":"none"},"a2a_get_task":{"id":"a2a_get_task","name":"A2A Get Task","description":"Retrieve the current state and result of an A2A task.","version":"1.0.0","params":{"agentUrl":{"type":"string","required":true,"visibility":"user-only","description":"The A2A agent endpoint URL"},"taskId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The task ID to retrieve"},"historyLength":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of history messages to include"},"apiKey":{"type":"string","required":false,"visibility":"user-only","description":"API key for authentication (if required)"}},"hostedApiKey":"none"},"a2a_send_message":{"id":"a2a_send_message","name":"A2A Send Message","description":"Send a message to an external A2A agent and return its response.","version":"1.0.0","params":{"agentUrl":{"type":"string","required":true,"visibility":"user-only","description":"The A2A agent endpoint URL"},"message":{"type":"string","required":true,"visibility":"user-or-llm","description":"The message text to send"},"data":{"type":"json","required":false,"visibility":"user-or-llm","description":"Optional structured JSON data to attach"},"files":{"type":"json","required":false,"visibility":"user-or-llm","description":"Optional files to attach"},"taskId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Existing task ID to continue"},"contextId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Conversation context ID to continue"},"apiKey":{"type":"string","required":false,"visibility":"user-only","description":"API key for authentication (if required)"}},"hostedApiKey":"none"},"affinity_batch_update_entity_fields":{"id":"affinity_batch_update_entity_fields","name":"Affinity Batch Update Entity Fields","description":"Write up to 100 non-list field values on one company or person in a single request.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which entity to write the fields on: companies or persons"},"entityId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of that company or person"},"updates":{"type":"json","required":true,"visibility":"user-or-llm","description":"Up to 100 field updates as [{\\"id\\":\\"\\",\\"value\\":{\\"type\\":\\"…\\",\\"data\\":…}}], using the same value shapes as a single field update"}},"hostedApiKey":"none"},"affinity_batch_update_list_entry_fields":{"id":"affinity_batch_update_list_entry_fields","name":"Affinity Batch Update List Entry Fields","description":"Write up to 100 field values on one list row in a single request. Requires the \\"Export data from Lists\\" permission.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"listEntryId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list entry ID"},"updates":{"type":"json","required":true,"visibility":"user-or-llm","description":"Up to 100 field updates as [{\\"id\\":\\"\\",\\"value\\":{\\"type\\":\\"…\\",\\"data\\":…}}], using the same value shapes as a single field update"}},"hostedApiKey":"none"},"affinity_create_list":{"id":"affinity_create_list","name":"Affinity Create List","description":"Create a list. Its type fixes which entities it can hold, and the API key holder becomes its creator and owner.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"name":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the new list"},"type":{"type":"string","required":true,"visibility":"user-or-llm","description":"Entity kind the list holds: company, opportunity, or person"},"isPublic":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Whether everyone in the organization can see the list"}},"hostedApiKey":"none"},"affinity_create_list_field_dropdown_option":{"id":"affinity_create_list_field_dropdown_option","name":"Affinity Create List Field Dropdown Option","description":"Add a selectable option to a dropdown field on a list. A ranked or status option also needs a rank and a color.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"fieldId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The dropdown field ID on that list"},"type":{"type":"string","required":true,"visibility":"user-or-llm","description":"Kind of option to create, matching the field. dropdown takes only a label; ranked-dropdown also requires rank and color; status-dropdown additionally requires a status category. Sending a field the kind does not accept is rejected"},"text":{"type":"string","required":true,"visibility":"user-or-llm","description":"The option label"},"rank":{"type":"number","required":false,"visibility":"user-or-llm","description":"Sort order. Required on a ranked-dropdown or status-dropdown option"},"color":{"type":"string","required":false,"visibility":"user-or-llm","description":"Option color: white, gray, blue, green, purple, orange, or red. Required on a ranked-dropdown or status-dropdown option"},"statusCategory":{"type":"string","required":false,"visibility":"user-or-llm","description":"Pipeline meaning of the option: open, won, lost, or on-hold. Status-dropdown options only"},"winRate":{"type":"number","required":false,"visibility":"user-or-llm","description":"Expected win rate of the status. Status-dropdown options only"}},"hostedApiKey":"none"},"affinity_create_merge":{"id":"affinity_create_merge","name":"Affinity Create Merge","description":"Fold a duplicate company or person into the record you are keeping. The merge runs asynchronously — poll the returned task to see it finish. Requires the \\"Manage duplicates\\" permission and an admin role.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"What to merge: companies or persons"},"primaryId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the record to keep"},"duplicateId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the duplicate record to fold in"}},"hostedApiKey":"none"},"affinity_create_note":{"id":"affinity_create_note","name":"Affinity Create Note","description":"Write a note — attached to companies, persons, and opportunities, anchored to a meeting, call, or chat message, or posted as a reply to an existing note.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"type":{"type":"string","required":true,"visibility":"user-or-llm","description":"Note shape: entities to attach it to records, interaction to anchor it to a meeting, call, or chat message, or user-reply to reply to a note"},"html":{"type":"string","required":true,"visibility":"user-or-llm","description":"The note body as HTML"},"companyIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Companies to attach the note to, e.g. [1, 2]. Not used on a reply"},"personIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Persons to attach the note to, e.g. [1, 2]. Not used on a reply"},"opportunityIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Opportunities to attach the note to, e.g. [1, 2]. Not used on a reply"},"interactionId":{"type":"string","required":false,"visibility":"user-or-llm","description":"The interaction to anchor the note to. Required for an interaction note"},"interactionType":{"type":"string","required":false,"visibility":"user-or-llm","description":"Kind of the anchoring interaction: meeting, call, or chat-message. Required for an interaction note"},"parentId":{"type":"string","required":false,"visibility":"user-or-llm","description":"The note being replied to. Required for a user-reply note"},"creatorId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Attribute the note to another internal person. Defaults to the API key holder"},"createdAt":{"type":"string","required":false,"visibility":"user-or-llm","description":"Backdate the note to this ISO 8601 timestamp"}},"hostedApiKey":"none"},"affinity_create_reminder":{"id":"affinity_create_reminder","name":"Affinity Create Reminder","description":"Create a reminder on one company, person, or opportunity. A recurring reminder resets whenever the chosen signal happens instead of firing once.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"type":{"type":"string","required":true,"visibility":"user-or-llm","description":"one-time to fire once, or recurring to reset on a signal"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"What the reminder is about: company, person, or opportunity"},"entityId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of that company, person, or opportunity"},"dueDate":{"type":"string","required":false,"visibility":"user-or-llm","description":"When the reminder is due, as an ISO 8601 timestamp. Required for a one-time reminder; on a recurring one Affinity computes it from the period when omitted"},"content":{"type":"string","required":false,"visibility":"user-or-llm","description":"What the reminder says"},"ownerId":{"type":"string","required":true,"visibility":"user-or-llm","description":"User the reminder is assigned to. Must be an internal user. The API key holder is recorded as the creator, which is a separate field"},"resetTrigger":{"type":"string","required":false,"visibility":"user-or-llm","description":"What restarts a recurring reminder: interaction, email, or event. Required when the type is recurring"},"periodDays":{"type":"number","required":false,"visibility":"user-or-llm","description":"Days between firings of a recurring reminder. Required when the type is recurring"}},"hostedApiKey":"none"},"affinity_delete_list_field_dropdown_option":{"id":"affinity_delete_list_field_dropdown_option","name":"Affinity Delete List Field Dropdown Option","description":"Permanently delete a dropdown option on a list field. Every list entry currently set to it is cleared, and those values cannot be recovered.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"fieldId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The dropdown field ID on that list"},"dropdownOptionId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The dropdown option ID to delete"}},"hostedApiKey":"none"},"affinity_delete_note":{"id":"affinity_delete_note","name":"Affinity Delete Note","description":"Delete a note you created. Deleting a root note also deletes its replies; deleting a reply removes only that reply.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"noteId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The note ID to delete"}},"hostedApiKey":"none"},"affinity_get_company":{"id":"affinity_get_company","name":"Affinity Get Company","description":"Look up one company by ID. Field data is returned only for the Field IDs or Field Types asked for.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"companyId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The company ID"},"fieldIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field IDs to return values for, e.g. [\\"affinity-data-location\\"]. Mutually exclusive with Field Types"},"fieldTypes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field categories to return values for: enriched, global, or relationship-intelligence. Mutually exclusive with Field IDs"}},"hostedApiKey":"none"},"affinity_get_current_user":{"id":"affinity_get_current_user","name":"Affinity Get Current User","description":"Verify an Affinity API key and return the tenant, the user behind the key, and the scopes the grant carries.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"}},"hostedApiKey":"none"},"affinity_get_entity_field_value":{"id":"affinity_get_entity_field_value","name":"Affinity Get Entity Field Value","description":"Read one non-list field value from a company or person.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which entity to read the field from: companies or persons"},"entityId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of that company or person"},"fieldId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The field ID to read"}},"hostedApiKey":"none"},"affinity_get_list":{"id":"affinity_get_list","name":"Affinity Get List","description":"Read one list — its name, type, owner, and privacy setting.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"}},"hostedApiKey":"none"},"affinity_get_list_entry":{"id":"affinity_get_list_entry","name":"Affinity Get List Entry","description":"Read one row of a list with its entity. Field data is returned only for the Field IDs or Field Types asked for.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"listEntryId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list entry ID"},"fieldIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field IDs to return values for, e.g. [\\"affinity-data-location\\"]. Mutually exclusive with Field Types"},"fieldTypes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field categories to return values for: enriched, global, list, or relationship-intelligence. Mutually exclusive with Field IDs"}},"hostedApiKey":"none"},"affinity_get_list_entry_field":{"id":"affinity_get_list_entry_field","name":"Affinity Get List Entry Field","description":"Read one field value on a list row.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"listEntryId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list entry ID"},"fieldId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The field ID to read"}},"hostedApiKey":"none"},"affinity_get_list_field_dropdown_option":{"id":"affinity_get_list_field_dropdown_option","name":"Affinity Get List Field Dropdown Option","description":"Read one dropdown option on a list field.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"fieldId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The dropdown field ID on that list"},"dropdownOptionId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The dropdown option ID"}},"hostedApiKey":"none"},"affinity_get_merge":{"id":"affinity_get_merge","name":"Affinity Get Merge","description":"Read the status of one company or person merge, including why it failed if it did.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which merge to read: companies or persons"},"mergeId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The merge ID"}},"hostedApiKey":"none"},"affinity_get_merge_task":{"id":"affinity_get_merge_task","name":"Affinity Get Merge Task","description":"Read one merge task and how its merges are progressing. Poll this after starting a merge.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which merge task to read: companies or persons"},"taskId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The merge task ID"}},"hostedApiKey":"none"},"affinity_get_note":{"id":"affinity_get_note","name":"Affinity Get Note","description":"Read one note with its body, author, mentions, and attached records.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"noteId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The note ID"},"includes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Extra properties to return, e.g. [\\"repliesCount\\",\\"personsPreview\\",\\"companiesPreview\\",\\"opportunitiesPreview\\"]. Those four fields are omitted unless requested here"}},"hostedApiKey":"none"},"affinity_get_opportunity":{"id":"affinity_get_opportunity","name":"Affinity Get Opportunity","description":"Read one opportunity and the list it belongs to. Its field data lives on the list entry.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"opportunityId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The opportunity ID"}},"hostedApiKey":"none"},"affinity_get_person":{"id":"affinity_get_person","name":"Affinity Get Person","description":"Look up one person by ID. Field data is returned only for the Field IDs or Field Types asked for.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"personId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The person ID"},"fieldIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field IDs to return values for, e.g. [\\"affinity-data-location\\"]. Mutually exclusive with Field Types"},"fieldTypes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field categories to return values for: enriched, global, or relationship-intelligence. Mutually exclusive with Field IDs"}},"hostedApiKey":"none"},"affinity_get_saved_view":{"id":"affinity_get_saved_view","name":"Affinity Get Saved View","description":"Read one saved view — its name, kind, and creation date.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"viewId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The saved view ID"}},"hostedApiKey":"none"},"affinity_get_transcript":{"id":"affinity_get_transcript","name":"Affinity Get Transcript","description":"Read one transcript with its first 100 fragments. Page the fragments endpoint for a longer meeting.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"transcriptId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The transcript ID"}},"hostedApiKey":"none"},"affinity_get_user":{"id":"affinity_get_user","name":"Affinity Get User","description":"Read one internal user. A user and their person record share the same numeric ID, so a person ID works here.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"userId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The user ID, which is also their person ID"}},"hostedApiKey":"none"},"affinity_list_calls":{"id":"affinity_list_calls","name":"Affinity List Calls","description":"Page through logged calls and their participants. Only calls the API key holder can see are returned.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression, e.g. \\"createdAt>=2026-01-01\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_chat_messages":{"id":"affinity_list_chat_messages","name":"Affinity List Chat Messages","description":"Page through logged chat messages and their participants. Only messages the API key holder can see are returned.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression, e.g. \\"createdAt>=2026-01-01\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_companies":{"id":"affinity_list_companies","name":"Affinity List Companies","description":"Page through companies. Companies come back without field data unless Field IDs or Field Types asks for it.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"ids":{"type":"json","required":false,"visibility":"user-or-llm","description":"Restrict the page to these company IDs, e.g. [1, 2, 3]"},"fieldIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field IDs to return values for, e.g. [\\"affinity-data-location\\"]. Mutually exclusive with Field Types"},"fieldTypes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field categories to return values for: enriched, global, or relationship-intelligence. Mutually exclusive with Field IDs"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_coworker_connections":{"id":"affinity_list_coworker_connections","name":"Affinity List Coworker Connections","description":"Find warm paths into a company through shared work history: who in your Affinity data once worked alongside the people you want to reach. Grouped by target, strongest first.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"filter":{"type":"string","required":true,"visibility":"user-or-llm","description":"Required scope. The only supported filter is target.currentCompany.id, e.g. \\"target.currentCompany.id=123\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of targets to return per page, 1-50. Defaults to 20"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_list_emails":{"id":"affinity_list_emails","name":"Affinity List Emails","description":"Page through email metadata — subject, participants, and timestamps. Affinity never exposes email bodies through the API.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression, e.g. \\"createdAt>=2026-01-01\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_entity_field_values":{"id":"affinity_list_entity_field_values","name":"Affinity List Entity Field Values","description":"Page through a company\'s or person\'s non-list field values. List fields are not returned here — read those through the list entry.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which entity to read field values from: companies or persons"},"entityId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of that company or person"},"ids":{"type":"json","required":false,"visibility":"user-or-llm","description":"Restrict to these field IDs. Mutually exclusive with Field Types"},"types":{"type":"json","required":false,"visibility":"user-or-llm","description":"Restrict to these field categories: enriched, global, relationship-intelligence. Mutually exclusive with Field IDs"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 20"}},"hostedApiKey":"none"},"affinity_list_entity_list_entries":{"id":"affinity_list_entity_list_entries","name":"Affinity List Entity List Entries","description":"Page through a company\'s or person\'s rows across every list, each carrying that list\'s field values and when the entity was added.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which entity to look up the rows of: companies or persons"},"entityId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of that company or person"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_entity_lists":{"id":"affinity_list_entity_lists","name":"Affinity List Entity Lists","description":"List every list a company or person appears on that the caller can view.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which entity to look up the lists of: companies or persons"},"entityId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of that company or person"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_entity_notes":{"id":"affinity_list_entity_notes","name":"Affinity List Entity Notes","description":"List the notes relevant to one company, person, or opportunity — directly attached notes plus notes reaching it through its people and meetings.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which entity the notes hang off: companies, persons, or opportunities"},"entityId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of that company, person, or opportunity"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression, e.g. \\"createdAt>=2026-01-01\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_list_entity_relationships":{"id":"affinity_list_entity_relationships","name":"Affinity List Entity Relationships","description":"List who knows a company or person, scored 0.0 to 1.0 by how much the two actually interact. Strongest first by default.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which entity to look up relationships for: companies or persons"},"entityId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of that company or person"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression. This endpoint filters on interactionScore only, e.g. \\"interactionScore>=0.5\\""},"orderBy":{"type":"json","required":false,"visibility":"user-or-llm","description":"Sort order: [\\"interactionScore\\"] for weakest first, [\\"-interactionScore\\"] for strongest first (the default)"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_list_field_dropdown_options":{"id":"affinity_list_field_dropdown_options","name":"Affinity List Field Dropdown Options","description":"List the selectable options on a dropdown or ranked-dropdown company or person field. Writing such a field needs the option ID, not its text.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which field family the field belongs to: companies or persons"},"fieldId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The dropdown or ranked-dropdown field ID"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_field_metadata":{"id":"affinity_list_field_metadata","name":"Affinity List Field Metadata","description":"List the non-list company or person fields, with the value type, filter operators, and sort support of each. Start here to find the Field IDs the read and write tools take.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which fields to describe: companies or persons"},"includes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Extra properties to return: [\\"filterability\\",\\"sortability\\"]. Both are omitted unless requested here"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression. This endpoint filters on name only, e.g. \\"name=~Status\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_field_value_changes":{"id":"affinity_list_field_value_changes","name":"Affinity List Field Value Changes","description":"Page through field value changes across the whole workspace. Built for delta sync: follow nextCursor to the end of a run, then resume from the last cursor next time.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression over field.id, listEntry.id, changer.id, changedAt, or actionType. Resume a sync with e.g. \\"changedAt>2026-06-01T12:00:00Z\\""},"orderBy":{"type":"json","required":false,"visibility":"user-or-llm","description":"Sort order: [\\"changedAt\\"] for oldest first (the default), [\\"-changedAt\\"] for newest first"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_investor_executive_connections":{"id":"affinity_list_investor_executive_connections","name":"Affinity List Investor Executive Connections","description":"Find warm paths into a company through investment history: which investors in your Affinity data backed a company the people you want to reach once led. Grouped by target, strongest first.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"filter":{"type":"string","required":true,"visibility":"user-or-llm","description":"Required scope. The only supported filter is target.currentCompany.id, e.g. \\"target.currentCompany.id=123\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of targets to return per page, 1-50. Defaults to 20"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_list_list_entries":{"id":"affinity_list_list_entries","name":"Affinity List List Entries","description":"Page through the rows of a list. Rows come back without field data unless Field IDs or Field Types asks for it.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"fieldIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field IDs to return values for, e.g. [\\"affinity-data-location\\"]. Mutually exclusive with Field Types"},"fieldTypes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field categories to return values for: enriched, global, list, or relationship-intelligence. Mutually exclusive with Field IDs"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_list_entry_field_value_changes":{"id":"affinity_list_list_entry_field_value_changes","name":"Affinity List List Entry Field Value Changes","description":"Page through the history of one list row — who changed which field, when, and to what.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"listEntryId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list entry ID"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression over field.id, changer.id, changedAt, or actionType, e.g. \\"field.id=field-1234\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_list_entry_fields":{"id":"affinity_list_list_entry_fields","name":"Affinity List List Entry Fields","description":"Page through every field value on one list row, including the list-specific columns. All fields are returned unless narrowed.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"listEntryId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list entry ID"},"ids":{"type":"json","required":false,"visibility":"user-or-llm","description":"Restrict to these field IDs. Mutually exclusive with Field Types"},"types":{"type":"json","required":false,"visibility":"user-or-llm","description":"Restrict to these field categories: enriched, global, list, relationship-intelligence. Mutually exclusive with Field IDs"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 20"}},"hostedApiKey":"none"},"affinity_list_list_field_dropdown_options":{"id":"affinity_list_list_field_dropdown_options","name":"Affinity List List Field Dropdown Options","description":"List the selectable options on a dropdown, ranked-dropdown, or status-dropdown field of a list.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"fieldId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The dropdown field ID on that list"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_list_fields":{"id":"affinity_list_list_fields","name":"Affinity List List Fields","description":"List the fields available on one list, including its list-specific columns. Use these Field IDs when reading or writing list entries.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"includes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Extra properties to return: [\\"filterability\\",\\"sortability\\"]. Both are omitted unless requested here"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression. This endpoint filters on name only, e.g. \\"name=~Stage\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_lists":{"id":"affinity_list_lists","name":"Affinity List Lists","description":"Page through the lists in the organization that the caller can view.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"term":{"type":"string","required":false,"visibility":"user-or-llm","description":"Case-insensitive substring match on the list name"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_meetings":{"id":"affinity_list_meetings","name":"Affinity List Meetings","description":"Page through past and upcoming meetings with their organizer and attendees.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression, e.g. \\"createdAt>=2026-01-01\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_merge_tasks":{"id":"affinity_list_merge_tasks","name":"Affinity List Merge Tasks","description":"Page through merge tasks, each summarizing how many of its merges are in progress, succeeded, or failed.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which merge tasks to list: companies or persons"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression. This endpoint filters on status only, e.g. \\"status=in-progress\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_merges":{"id":"affinity_list_merges","name":"Affinity List Merges","description":"Page through the company or person merges the organization has run, with the status and the records involved in each.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which merges to list: companies or persons"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression over status or taskId, e.g. \\"status=failed\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_note_attached_companies":{"id":"affinity_list_note_attached_companies","name":"Affinity List Note Attached Companies","description":"List the companies directly attached to one note.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"noteId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The note ID"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_list_note_attached_opportunities":{"id":"affinity_list_note_attached_opportunities","name":"Affinity List Note Attached Opportunities","description":"List the opportunities directly attached to one note.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"noteId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The note ID"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_list_note_attached_persons":{"id":"affinity_list_note_attached_persons","name":"Affinity List Note Attached Persons","description":"List the persons directly attached to one note.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"noteId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The note ID"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_list_note_replies":{"id":"affinity_list_note_replies","name":"Affinity List Note Replies","description":"Page through the replies on one note, including AI Notetaker replies.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"noteId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The note ID whose replies to read"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression, e.g. \\"createdAt>=2026-01-01\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_list_notes":{"id":"affinity_list_notes","name":"Affinity List Notes","description":"Page through every note the caller can see. Replies are excluded.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"includes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Extra properties to return, e.g. [\\"repliesCount\\",\\"personsPreview\\",\\"companiesPreview\\",\\"opportunitiesPreview\\"]. Those four fields are omitted unless requested here"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression, e.g. \\"createdAt>=2026-01-01\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_list_opportunities":{"id":"affinity_list_opportunities","name":"Affinity List Opportunities","description":"Page through opportunities. Field data lives on the list entry, not here — read it through the list or saved view the opportunity belongs to.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"ids":{"type":"json","required":false,"visibility":"user-or-llm","description":"Restrict the page to these opportunity IDs, e.g. [1, 2, 3]"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_persons":{"id":"affinity_list_persons","name":"Affinity List Persons","description":"Page through persons. Persons come back without field data unless Field IDs or Field Types asks for it.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"ids":{"type":"json","required":false,"visibility":"user-or-llm","description":"Restrict the page to these person IDs, e.g. [1, 2, 3]"},"fieldIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field IDs to return values for, e.g. [\\"affinity-data-location\\"]. Mutually exclusive with Field Types"},"fieldTypes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field categories to return values for: enriched, global, or relationship-intelligence. Mutually exclusive with Field IDs"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_reminders":{"id":"affinity_list_reminders","name":"Affinity List Reminders","description":"Page through the reminders the caller can see. Filter by status to surface what is overdue.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression, e.g. \\"createdAt>=2026-01-01\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_list_saved_view_entries":{"id":"affinity_list_saved_view_entries","name":"Affinity List Saved View Entries","description":"Page through the rows of a saved view. The view\'s own filters and columns decide which rows and which field data come back.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"viewId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The saved view ID"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_saved_views":{"id":"affinity_list_saved_views","name":"Affinity List Saved Views","description":"List the saved views on a list that the caller can view.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_list_transcript_fragments":{"id":"affinity_list_transcript_fragments","name":"Affinity List Transcript Fragments","description":"Page through everything said in a meeting, segment by segment with the speaker.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"transcriptId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The transcript ID"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_list_transcripts":{"id":"affinity_list_transcripts","name":"Affinity List Transcripts","description":"Page through meeting transcript metadata. Read one transcript to get what was actually said.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression, e.g. \\"createdAt>=2026-01-01\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_list_users":{"id":"affinity_list_users","name":"Affinity List Users","description":"Page through the internal users in the organization. Email addresses and roles are returned only to callers with the \\"Manage Users\\" permission.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"term":{"type":"string","required":false,"visibility":"user-or-llm","description":"Case-insensitive match across first name, last name, and primary email"},"filter":{"type":"string","required":false,"visibility":"user-or-llm","description":"Affinity Filtering Language expression over id or status, e.g. \\"status=active\\""},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_search_companies":{"id":"affinity_search_companies","name":"Affinity Search Companies","description":"Search companies by filters, sorts, and a free-text term. Requires the \\"Export All Organizations directory\\" permission.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"filters":{"type":"json","required":false,"visibility":"user-or-llm","description":"Filter group as {operator: \\"and\\"|\\"or\\", filters: [...]}, at most 50 leaves. Each leaf is {valueType, fieldId, operator, value}, and a leaf may itself be a nested group"},"searchTerm":{"type":"string","required":false,"visibility":"user-or-llm","description":"Free-text term matched against the searchable fields. At least 3 characters"},"searchFieldIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field IDs the search term is matched against. Defaults to the searchable fields"},"sorts":{"type":"json","required":false,"visibility":"user-or-llm","description":"Sort order as [{fieldId, direction: \\"asc\\"|\\"desc\\", attributeId?}], up to 5, applied in order"},"fieldIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field IDs to return values for, e.g. [\\"affinity-data-location\\"]. Mutually exclusive with Field Types"},"fieldTypes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field categories to return values for: enriched, global, or relationship-intelligence. Mutually exclusive with Field IDs"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_search_files":{"id":"affinity_search_files","name":"Affinity Search Files","description":"Search files by keyword, ordered by relevance. Narrow to specific files or to one company, or leave both unset to search the whole account.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"prompt":{"type":"string","required":true,"visibility":"user-or-llm","description":"What to search for. Between 3 and 500 characters"},"ids":{"type":"json","required":false,"visibility":"user-or-llm","description":"Restrict the search to these file IDs. Cannot be combined with Company ID"},"companyId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Restrict the search to one company\'s files. Cannot be combined with file IDs"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of files to return, 1-100. Defaults to 20"}},"hostedApiKey":"none"},"affinity_search_list_entries":{"id":"affinity_search_list_entries","name":"Affinity Search List Entries","description":"Search the rows of one list by filters, sorts, and a free-text term. Requires the \\"Export data from Lists\\" permission.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID to search"},"filters":{"type":"json","required":false,"visibility":"user-or-llm","description":"Filter group as {operator: \\"and\\"|\\"or\\", filters: [...]}, at most 50 leaves. Each leaf is {valueType, fieldId, operator, value}, and a leaf may itself be a nested group"},"searchTerm":{"type":"string","required":false,"visibility":"user-or-llm","description":"Free-text term matched against the searchable fields. At least 3 characters"},"searchFieldIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field IDs the search term is matched against. Defaults to the searchable fields"},"sorts":{"type":"json","required":false,"visibility":"user-or-llm","description":"Sort order as [{fieldId, direction: \\"asc\\"|\\"desc\\", attributeId?}], up to 5, applied in order"},"fieldIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field IDs to return values for, e.g. [\\"affinity-data-location\\"]. Mutually exclusive with Field Types"},"fieldTypes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field categories to return values for: enriched, global, list, or relationship-intelligence. Mutually exclusive with Field IDs"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_search_notes":{"id":"affinity_search_notes","name":"Affinity Search Notes","description":"Search notes by keyword, ordered by relevance. Narrow to specific notes or to one company, or leave both unset to search the whole account.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"prompt":{"type":"string","required":true,"visibility":"user-or-llm","description":"What to search for. Between 3 and 500 characters"},"ids":{"type":"json","required":false,"visibility":"user-or-llm","description":"Restrict the search to these note IDs. Cannot be combined with Company ID"},"companyId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Restrict the search to one company\'s notes. Cannot be combined with note IDs"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of notes to return, 1-100. Defaults to 20"}},"hostedApiKey":"none"},"affinity_search_persons":{"id":"affinity_search_persons","name":"Affinity Search Persons","description":"Search persons by filters, sorts, and a free-text term. Requires the \\"Export All People directory\\" permission.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"filters":{"type":"json","required":false,"visibility":"user-or-llm","description":"Filter group as {operator: \\"and\\"|\\"or\\", filters: [...]}, at most 50 leaves. Each leaf is {valueType, fieldId, operator, value}, and a leaf may itself be a nested group"},"searchTerm":{"type":"string","required":false,"visibility":"user-or-llm","description":"Free-text term matched against the searchable fields. At least 3 characters"},"searchFieldIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field IDs the search term is matched against. Defaults to the searchable fields"},"sorts":{"type":"json","required":false,"visibility":"user-or-llm","description":"Sort order as [{fieldId, direction: \\"asc\\"|\\"desc\\", attributeId?}], up to 5, applied in order"},"fieldIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field IDs to return values for, e.g. [\\"affinity-data-location\\"]. Mutually exclusive with Field Types"},"fieldTypes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Field categories to return values for: enriched, global, or relationship-intelligence. Mutually exclusive with Field IDs"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous page, returned as nextCursor or prevCursor"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to return per page, 1-100. Defaults to 100"},"totalCount":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the total size of the collection. Costs an extra query"}},"hostedApiKey":"none"},"affinity_semantic_search":{"id":"affinity_semantic_search","name":"Affinity Semantic Search","description":"Find companies from a description in plain language — industry, technology, stage, or business model. Currently searches companies only.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"prompt":{"type":"string","required":true,"visibility":"user-or-llm","description":"What to look for, in plain language, e.g. \\"climate tech companies in our pipeline\\". Up to 500 characters"},"listIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Restrict the search to companies on these lists, e.g. [1, 2]"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of companies to return, 1-100. Defaults to 100"}},"hostedApiKey":"none"},"affinity_update_entity_field_value":{"id":"affinity_update_entity_field_value","name":"Affinity Update Entity Field Value","description":"Write one non-list field value on a company or person. The value type must match how the field is defined.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"entityType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Which entity to write the field on: companies or persons"},"entityId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of that company or person"},"fieldId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The field ID to write"},"value":{"type":"json","required":true,"visibility":"user-or-llm","description":"The new value as {type, data}, where type matches the field\'s value type. Examples: {\\"type\\":\\"text\\",\\"data\\":\\"Series B\\"}, {\\"type\\":\\"number\\",\\"data\\":42}, {\\"type\\":\\"dropdown\\",\\"data\\":{\\"dropdownOptionId\\":7}}, {\\"type\\":\\"person\\",\\"data\\":{\\"id\\":123}}, {\\"type\\":\\"person-multi\\",\\"data\\":[{\\"id\\":123}]}. Pass data as null to clear the field"}},"hostedApiKey":"none"},"affinity_update_list_entry_field":{"id":"affinity_update_list_entry_field","name":"Affinity Update List Entry Field","description":"Write one field value on a list row. Requires the \\"Export data from Lists\\" permission.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"listEntryId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list entry ID"},"fieldId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The field ID to write"},"value":{"type":"json","required":true,"visibility":"user-or-llm","description":"The new value as {type, data}, where type matches the field\'s value type. Examples: {\\"type\\":\\"text\\",\\"data\\":\\"Series B\\"}, {\\"type\\":\\"number\\",\\"data\\":42}, {\\"type\\":\\"dropdown\\",\\"data\\":{\\"dropdownOptionId\\":7}}, {\\"type\\":\\"person\\",\\"data\\":{\\"id\\":123}}, {\\"type\\":\\"person-multi\\",\\"data\\":[{\\"id\\":123}]}. Pass data as null to clear the field"}},"hostedApiKey":"none"},"affinity_update_list_field_dropdown_option":{"id":"affinity_update_list_field_dropdown_option","name":"Affinity Update List Field Dropdown Option","description":"Change a dropdown option on a list field. Every field is optional — supply only what should change, and only fields the option\'s kind actually has.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"listId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The list ID"},"fieldId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The dropdown field ID on that list"},"dropdownOptionId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The dropdown option ID to update"},"text":{"type":"string","required":false,"visibility":"user-or-llm","description":"Replacement option label. Supply at least one field to change"},"rank":{"type":"number","required":false,"visibility":"user-or-llm","description":"Sort order. Required on a ranked-dropdown or status-dropdown option"},"color":{"type":"string","required":false,"visibility":"user-or-llm","description":"Option color: white, gray, blue, green, purple, orange, or red. Required on a ranked-dropdown or status-dropdown option"},"statusCategory":{"type":"string","required":false,"visibility":"user-or-llm","description":"Pipeline meaning of the option: open, won, lost, or on-hold. Status-dropdown options only"},"winRate":{"type":"number","required":false,"visibility":"user-or-llm","description":"Expected win rate of the status. Status-dropdown options only"}},"hostedApiKey":"none"},"affinity_update_note":{"id":"affinity_update_note","name":"Affinity Update Note","description":"Rewrite a note\'s body or replace which records it is attached to. Each list of IDs replaces that association wholesale, an empty list clears it, and omitting one leaves it untouched. A note\'s type cannot be changed.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Affinity API key, sent as a bearer token"},"noteId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The note ID to update"},"html":{"type":"string","required":false,"visibility":"user-or-llm","description":"Replacement note body as HTML"},"companyIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Replacement set of attached companies, e.g. [1, 2]. Send [] to detach every company; omit to leave them unchanged"},"personIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Replacement set of attached persons, e.g. [1, 2]. Send [] to detach every person; omit to leave them unchanged"},"opportunityIds":{"type":"json","required":false,"visibility":"user-or-llm","description":"Replacement set of attached opportunities, e.g. [1, 2]. Send [] to detach every opportunity; omit to leave them unchanged"}},"hostedApiKey":"none"},"agentmail_create_draft":{"id":"agentmail_create_draft","name":"Create Draft","description":"Create a new email draft in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox to create the draft in"},"to":{"type":"string","required":false,"visibility":"user-or-llm","description":"Recipient email addresses (comma-separated)"},"subject":{"type":"string","required":false,"visibility":"user-or-llm","description":"Draft subject line"},"text":{"type":"string","required":false,"visibility":"user-or-llm","description":"Plain text draft body"},"html":{"type":"string","required":false,"visibility":"user-or-llm","description":"HTML draft body"},"cc":{"type":"string","required":false,"visibility":"user-or-llm","description":"CC recipient email addresses (comma-separated)"},"bcc":{"type":"string","required":false,"visibility":"user-or-llm","description":"BCC recipient email addresses (comma-separated)"},"inReplyTo":{"type":"string","required":false,"visibility":"user-or-llm","description":"ID of message being replied to"},"sendAt":{"type":"string","required":false,"visibility":"user-or-llm","description":"ISO 8601 timestamp to schedule sending"}},"hostedApiKey":"none"},"agentmail_create_inbox":{"id":"agentmail_create_inbox","name":"Create Inbox","description":"Create a new email inbox with AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"username":{"type":"string","required":false,"visibility":"user-or-llm","description":"Username for the inbox email address"},"domain":{"type":"string","required":false,"visibility":"user-or-llm","description":"Domain for the inbox email address"},"displayName":{"type":"string","required":false,"visibility":"user-or-llm","description":"Display name for the inbox"}},"hostedApiKey":"none"},"agentmail_delete_draft":{"id":"agentmail_delete_draft","name":"Delete Draft","description":"Delete an email draft in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox containing the draft"},"draftId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the draft to delete"}},"hostedApiKey":"none"},"agentmail_delete_inbox":{"id":"agentmail_delete_inbox","name":"Delete Inbox","description":"Delete an email inbox in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox to delete"}},"hostedApiKey":"none"},"agentmail_delete_thread":{"id":"agentmail_delete_thread","name":"Delete Thread","description":"Delete an email thread in AgentMail (moves to trash, or permanently deletes if already in trash)","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox containing the thread"},"threadId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the thread to delete"},"permanent":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Force permanent deletion instead of moving to trash"}},"hostedApiKey":"none"},"agentmail_forward_message":{"id":"agentmail_forward_message","name":"Forward Message","description":"Forward an email message to new recipients in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox containing the message"},"messageId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the message to forward"},"to":{"type":"string","required":true,"visibility":"user-or-llm","description":"Recipient email addresses (comma-separated)"},"subject":{"type":"string","required":false,"visibility":"user-or-llm","description":"Override subject line"},"text":{"type":"string","required":false,"visibility":"user-or-llm","description":"Additional plain text to prepend"},"html":{"type":"string","required":false,"visibility":"user-or-llm","description":"Additional HTML to prepend"},"cc":{"type":"string","required":false,"visibility":"user-or-llm","description":"CC recipient email addresses (comma-separated)"},"bcc":{"type":"string","required":false,"visibility":"user-or-llm","description":"BCC recipient email addresses (comma-separated)"}},"hostedApiKey":"none"},"agentmail_get_draft":{"id":"agentmail_get_draft","name":"Get Draft","description":"Get details of a specific email draft in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox the draft belongs to"},"draftId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the draft to retrieve"}},"hostedApiKey":"none"},"agentmail_get_inbox":{"id":"agentmail_get_inbox","name":"Get Inbox","description":"Get details of a specific email inbox in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox to retrieve"}},"hostedApiKey":"none"},"agentmail_get_message":{"id":"agentmail_get_message","name":"Get Message","description":"Get details of a specific email message in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox containing the message"},"messageId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the message to retrieve"}},"hostedApiKey":"none"},"agentmail_get_thread":{"id":"agentmail_get_thread","name":"Get Thread","description":"Get details of a specific email thread including messages in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox containing the thread"},"threadId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the thread to retrieve"}},"hostedApiKey":"none"},"agentmail_list_drafts":{"id":"agentmail_list_drafts","name":"List Drafts","description":"List email drafts in an inbox in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox to list drafts from"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of drafts to return"},"pageToken":{"type":"string","required":false,"visibility":"user-or-llm","description":"Pagination token for next page of results"}},"hostedApiKey":"none"},"agentmail_list_inboxes":{"id":"agentmail_list_inboxes","name":"List Inboxes","description":"List all email inboxes in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of inboxes to return"},"pageToken":{"type":"string","required":false,"visibility":"user-or-llm","description":"Pagination token for next page of results"}},"hostedApiKey":"none"},"agentmail_list_messages":{"id":"agentmail_list_messages","name":"List Messages","description":"List messages in an inbox in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox to list messages from"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of messages to return"},"pageToken":{"type":"string","required":false,"visibility":"user-or-llm","description":"Pagination token for next page of results"}},"hostedApiKey":"none"},"agentmail_list_threads":{"id":"agentmail_list_threads","name":"List Threads","description":"List email threads in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox to list threads from"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of threads to return"},"pageToken":{"type":"string","required":false,"visibility":"user-or-llm","description":"Pagination token for next page of results"},"labels":{"type":"string","required":false,"visibility":"user-or-llm","description":"Comma-separated labels to filter threads by"},"before":{"type":"string","required":false,"visibility":"user-or-llm","description":"Filter threads before this ISO 8601 timestamp"},"after":{"type":"string","required":false,"visibility":"user-or-llm","description":"Filter threads after this ISO 8601 timestamp"}},"hostedApiKey":"none"},"agentmail_reply_message":{"id":"agentmail_reply_message","name":"Reply to Message","description":"Reply to an existing email message in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox to reply from"},"messageId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the message to reply to"},"text":{"type":"string","required":false,"visibility":"user-or-llm","description":"Plain text reply body"},"html":{"type":"string","required":false,"visibility":"user-or-llm","description":"HTML reply body"},"to":{"type":"string","required":false,"visibility":"user-or-llm","description":"Override recipient email addresses (comma-separated)"},"cc":{"type":"string","required":false,"visibility":"user-or-llm","description":"CC email addresses (comma-separated)"},"bcc":{"type":"string","required":false,"visibility":"user-or-llm","description":"BCC email addresses (comma-separated)"},"replyAll":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Reply to all recipients of the original message"}},"hostedApiKey":"none"},"agentmail_send_draft":{"id":"agentmail_send_draft","name":"Send Draft","description":"Send an existing email draft in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox containing the draft"},"draftId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the draft to send"}},"hostedApiKey":"none"},"agentmail_send_message":{"id":"agentmail_send_message","name":"Send Message","description":"Send an email message from an AgentMail inbox","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox to send from"},"to":{"type":"string","required":true,"visibility":"user-or-llm","description":"Recipient email address (comma-separated for multiple)"},"subject":{"type":"string","required":true,"visibility":"user-or-llm","description":"Email subject line"},"text":{"type":"string","required":false,"visibility":"user-or-llm","description":"Plain text email body"},"html":{"type":"string","required":false,"visibility":"user-or-llm","description":"HTML email body"},"cc":{"type":"string","required":false,"visibility":"user-or-llm","description":"CC recipient email addresses (comma-separated)"},"bcc":{"type":"string","required":false,"visibility":"user-or-llm","description":"BCC recipient email addresses (comma-separated)"}},"hostedApiKey":"none"},"agentmail_update_draft":{"id":"agentmail_update_draft","name":"Update Draft","description":"Update an existing email draft in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox containing the draft"},"draftId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the draft to update"},"to":{"type":"string","required":false,"visibility":"user-or-llm","description":"Recipient email addresses (comma-separated)"},"subject":{"type":"string","required":false,"visibility":"user-or-llm","description":"Draft subject line"},"text":{"type":"string","required":false,"visibility":"user-or-llm","description":"Plain text draft body"},"html":{"type":"string","required":false,"visibility":"user-or-llm","description":"HTML draft body"},"cc":{"type":"string","required":false,"visibility":"user-or-llm","description":"CC recipient email addresses (comma-separated)"},"bcc":{"type":"string","required":false,"visibility":"user-or-llm","description":"BCC recipient email addresses (comma-separated)"},"sendAt":{"type":"string","required":false,"visibility":"user-or-llm","description":"ISO 8601 timestamp to schedule sending"}},"hostedApiKey":"none"},"agentmail_update_inbox":{"id":"agentmail_update_inbox","name":"Update Inbox","description":"Update the display name of an email inbox in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox to update"},"displayName":{"type":"string","required":true,"visibility":"user-or-llm","description":"New display name for the inbox"}},"hostedApiKey":"none"},"agentmail_update_message":{"id":"agentmail_update_message","name":"Update Message","description":"Add or remove labels on an email message in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox containing the message"},"messageId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the message to update"},"addLabels":{"type":"string","required":false,"visibility":"user-or-llm","description":"Comma-separated labels to add to the message"},"removeLabels":{"type":"string","required":false,"visibility":"user-or-llm","description":"Comma-separated labels to remove from the message"}},"hostedApiKey":"none"},"agentmail_update_thread":{"id":"agentmail_update_thread","name":"Update Thread Labels","description":"Add or remove labels on an email thread in AgentMail","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentMail API key"},"inboxId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the inbox containing the thread"},"threadId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the thread to update"},"addLabels":{"type":"string","required":false,"visibility":"user-or-llm","description":"Comma-separated labels to add to the thread"},"removeLabels":{"type":"string","required":false,"visibility":"user-or-llm","description":"Comma-separated labels to remove from the thread"}},"hostedApiKey":"none"},"agentphone_create_call":{"id":"agentphone_create_call","name":"Create Outbound Call","description":"Initiate an outbound voice call from an AgentPhone agent","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"agentId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Agent that will handle the call"},"toNumber":{"type":"string","required":true,"visibility":"user-or-llm","description":"Phone number to call in E.164 format (e.g. +14155551234)"},"fromNumberId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Phone number ID to use as caller ID. Must belong to the agent. If omitted, the agent\'s first assigned number is used."},"initialGreeting":{"type":"string","required":false,"visibility":"user-or-llm","description":"Optional greeting spoken when the recipient answers"},"voice":{"type":"string","required":false,"visibility":"user-or-llm","description":"Voice ID override for this call (defaults to the agent\'s configured voice)"},"systemPrompt":{"type":"string","required":false,"visibility":"user-or-llm","description":"When provided, uses a built-in LLM for the conversation instead of forwarding to your webhook"}},"hostedApiKey":"none"},"agentphone_create_contact":{"id":"agentphone_create_contact","name":"Create Contact","description":"Create a new contact in AgentPhone","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"phoneNumber":{"type":"string","required":true,"visibility":"user-or-llm","description":"Phone number in E.164 format (e.g. +14155551234)"},"name":{"type":"string","required":true,"visibility":"user-or-llm","description":"Contact\'s full name"},"email":{"type":"string","required":false,"visibility":"user-or-llm","description":"Contact\'s email address"},"notes":{"type":"string","required":false,"visibility":"user-or-llm","description":"Freeform notes stored on the contact"}},"hostedApiKey":"none"},"agentphone_create_number":{"id":"agentphone_create_number","name":"Create Phone Number","description":"Provision a new SMS- and voice-enabled phone number","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"country":{"type":"string","required":false,"visibility":"user-or-llm","description":"Two-letter country code (e.g. US, CA). Defaults to US."},"areaCode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Preferred area code (US/CA only, e.g. \\"415\\"). Best-effort — may be ignored if unavailable."},"agentId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Optionally attach the number to an agent immediately"}},"hostedApiKey":"none"},"agentphone_delete_contact":{"id":"agentphone_delete_contact","name":"Delete Contact","description":"Delete a contact by ID","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"contactId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Contact ID"}},"hostedApiKey":"none"},"agentphone_get_call":{"id":"agentphone_get_call","name":"Get Call","description":"Fetch a call and its full transcript","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"callId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the call to retrieve"}},"hostedApiKey":"none"},"agentphone_get_call_transcript":{"id":"agentphone_get_call_transcript","name":"Get Call Transcript","description":"Get the full ordered transcript for a call","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"callId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the call to retrieve the transcript for"}},"hostedApiKey":"none"},"agentphone_get_contact":{"id":"agentphone_get_contact","name":"Get Contact","description":"Fetch a single contact by ID","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"contactId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Contact ID"}},"hostedApiKey":"none"},"agentphone_get_conversation":{"id":"agentphone_get_conversation","name":"Get Conversation","description":"Get a conversation along with its recent messages","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"conversationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Conversation ID"},"messageLimit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of recent messages to include (default 50, max 100)"}},"hostedApiKey":"none"},"agentphone_get_conversation_messages":{"id":"agentphone_get_conversation_messages","name":"Get Conversation Messages","description":"Get paginated messages for a conversation","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"conversationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Conversation ID"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of messages to return (default 50, max 200)"},"before":{"type":"string","required":false,"visibility":"user-or-llm","description":"Return messages received before this ISO 8601 timestamp"},"after":{"type":"string","required":false,"visibility":"user-or-llm","description":"Return messages received after this ISO 8601 timestamp"}},"hostedApiKey":"none"},"agentphone_get_number_messages":{"id":"agentphone_get_number_messages","name":"Get Phone Number Messages","description":"Fetch messages received on a specific phone number","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"numberId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the phone number"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of messages to return (default 50, max 200)"},"before":{"type":"string","required":false,"visibility":"user-or-llm","description":"Return messages received before this ISO 8601 timestamp"},"after":{"type":"string","required":false,"visibility":"user-or-llm","description":"Return messages received after this ISO 8601 timestamp"}},"hostedApiKey":"none"},"agentphone_get_usage":{"id":"agentphone_get_usage","name":"Get Usage","description":"Retrieve current usage statistics for the AgentPhone account","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"}},"hostedApiKey":"none"},"agentphone_get_usage_daily":{"id":"agentphone_get_usage_daily","name":"Get Daily Usage","description":"Get a daily breakdown of usage (messages, calls, webhooks) for the last N days","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"days":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of days to return (1-365, default 30)"}},"hostedApiKey":"none"},"agentphone_get_usage_monthly":{"id":"agentphone_get_usage_monthly","name":"Get Monthly Usage","description":"Get monthly usage aggregation (messages, calls, webhooks) for the last N months","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"months":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of months to return (1-24, default 6)"}},"hostedApiKey":"none"},"agentphone_list_calls":{"id":"agentphone_list_calls","name":"List Calls","description":"List voice calls for this AgentPhone account","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of results to return (default 20, max 100)"},"offset":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of results to skip (min 0)"},"status":{"type":"string","required":false,"visibility":"user-or-llm","description":"Filter by status (completed, in-progress, failed)"},"direction":{"type":"string","required":false,"visibility":"user-or-llm","description":"Filter by direction (inbound, outbound)"},"type":{"type":"string","required":false,"visibility":"user-or-llm","description":"Filter by call type (pstn, web)"},"search":{"type":"string","required":false,"visibility":"user-or-llm","description":"Search by phone number (matches fromNumber or toNumber)"}},"hostedApiKey":"none"},"agentphone_list_contacts":{"id":"agentphone_list_contacts","name":"List Contacts","description":"List contacts for this AgentPhone account","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"search":{"type":"string","required":false,"visibility":"user-or-llm","description":"Filter by name or phone number (case-insensitive contains)"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of results to return (default 50, max 200)"},"offset":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of results to skip (min 0)"}},"hostedApiKey":"none"},"agentphone_list_conversations":{"id":"agentphone_list_conversations","name":"List Conversations","description":"List conversations (message threads) for this AgentPhone account","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of results to return (default 20, max 100)"},"offset":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of results to skip (min 0)"}},"hostedApiKey":"none"},"agentphone_list_numbers":{"id":"agentphone_list_numbers","name":"List Phone Numbers","description":"List all phone numbers provisioned for this AgentPhone account","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of results to return (default 20, max 100)"},"offset":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of results to skip (min 0)"}},"hostedApiKey":"none"},"agentphone_react_to_message":{"id":"agentphone_react_to_message","name":"React to Message","description":"Send an iMessage tapback reaction to a message (iMessage only)","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"messageId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the message to react to"},"reaction":{"type":"string","required":true,"visibility":"user-or-llm","description":"Reaction type: love, like, dislike, laugh, emphasize, or question"}},"hostedApiKey":"none"},"agentphone_release_number":{"id":"agentphone_release_number","name":"Release Phone Number","description":"Release (delete) a phone number. This action is irreversible.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"numberId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the phone number to release"}},"hostedApiKey":"none"},"agentphone_send_message":{"id":"agentphone_send_message","name":"Send Message","description":"Send an outbound SMS or iMessage from an AgentPhone agent","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"agentId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Agent sending the message"},"toNumber":{"type":"string","required":true,"visibility":"user-or-llm","description":"Recipient phone number in E.164 format (e.g. +14155551234)"},"body":{"type":"string","required":true,"visibility":"user-or-llm","description":"Message text to send"},"mediaUrl":{"type":"string","required":false,"visibility":"user-or-llm","description":"Optional URL of an image, video, or file to attach"},"numberId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Phone number ID to send from. If omitted, the agent\'s first assigned number is used."}},"hostedApiKey":"none"},"agentphone_update_contact":{"id":"agentphone_update_contact","name":"Update Contact","description":"Update a contact\'s fields","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"contactId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Contact ID"},"phoneNumber":{"type":"string","required":false,"visibility":"user-or-llm","description":"New phone number in E.164 format"},"name":{"type":"string","required":false,"visibility":"user-or-llm","description":"New contact name"},"email":{"type":"string","required":false,"visibility":"user-or-llm","description":"New email address"},"notes":{"type":"string","required":false,"visibility":"user-or-llm","description":"New freeform notes"}},"hostedApiKey":"none"},"agentphone_update_conversation":{"id":"agentphone_update_conversation","name":"Update Conversation","description":"Update conversation metadata (stored state). Pass null to clear existing metadata.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"AgentPhone API key"},"conversationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Conversation ID"},"metadata":{"type":"json","required":false,"visibility":"user-or-llm","description":"Custom key-value metadata to store on the conversation. Pass null to clear existing metadata."}},"hostedApiKey":"none"},"agiloft_async_status":{"id":"agiloft_async_status","name":"Agiloft Async Status","description":"Check whether an asynchronous Agiloft call, such as a run action button, has completed.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table the asynchronous call was made against"},"callbackId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Callback ID returned by the asynchronous call, e.g. from Run Action Button"}},"hostedApiKey":"none"},"agiloft_attach_file":{"id":"agiloft_attach_file","name":"Agiloft Attach File","description":"Attach a file to a field in an Agiloft record.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name (e.g., \\"contracts\\")"},"recordId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the record to attach the file to"},"fieldName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the attachment field"},"file":{"type":"file","required":true,"visibility":"user-or-llm","description":"File to attach"},"fileName":{"type":"string","required":false,"visibility":"user-or-llm","description":"Name to assign to the file (defaults to original file name)"},"overwrite":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Replace the contents of the field instead of adding another file to it"}},"hostedApiKey":"none"},"agiloft_attachment_info":{"id":"agiloft_attachment_info","name":"Agiloft Attachment Info","description":"Get information about file attachments on a record field.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name (e.g., \\"contracts\\")"},"recordId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the record to check attachments on"},"fieldName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the attachment field to inspect"}},"hostedApiKey":"none"},"agiloft_create_record":{"id":"agiloft_create_record","name":"Agiloft Create Record","description":"Create a new record in an Agiloft table.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name (e.g., \\"contracts\\", \\"contacts.employees\\")"},"data":{"type":"string","required":true,"visibility":"user-or-llm","description":"Record field values as a JSON object (e.g., {\\"first_name\\": \\"John\\", \\"status\\": \\"Active\\"})"}},"hostedApiKey":"none"},"agiloft_delete_record":{"id":"agiloft_delete_record","name":"Agiloft Delete Record","description":"Delete a record from an Agiloft table.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name (e.g., \\"contracts\\", \\"contacts.employees\\")"},"recordId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the record to delete"},"substituteIds":{"type":"string","required":false,"visibility":"user-or-llm","description":"Comma-separated IDs of records that adopt the dependants of the deleted record. Read only when the delete rule is REPLACE_WITH_ANOTHER."},"deleteRule":{"type":"string","required":false,"visibility":"user-or-llm","description":"How to treat records that depend on this one: ERROR_IF_DEPENDANTS (default — fails rather than cascading), APPLY_DELETE_WHERE_POSSIBLE, DELETE_WHERE_POSSIBLE_OTHERWISE_UNLINK, APPLY_UNLINK, UNLINK_WHERE_POSSIBLE_OTHERWISE_DELETE, or REPLACE_WITH_ANOTHER"}},"hostedApiKey":"none"},"agiloft_get_choice_line_id":{"id":"agiloft_get_choice_line_id","name":"Agiloft Get Choice Line ID","description":"Resolve the internal numeric ID of a choice-list value, for use in EWSelect WHERE clauses against choice fields.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name (e.g., \\"case\\", \\"contracts\\")"},"fieldName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Choice field name (e.g., \\"priority\\", \\"status\\")"},"value":{"type":"string","required":true,"visibility":"user-or-llm","description":"Choice display value to resolve (e.g., \\"High\\", \\"Active\\")"}},"hostedApiKey":"none"},"agiloft_list_tables":{"id":"agiloft_list_tables","name":"Agiloft List Tables","description":"List the tables and fields in an Agiloft knowledge base, to discover the logical names other operations need.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":false,"visibility":"user-or-llm","description":"Logical name of a single table to describe (e.g., \\"contacts\\"). Leave empty to list every table in the knowledge base."},"includeLinkedInfo":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Include the source table and column behind each linked field"},"skipColumnsInfo":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Return table names only, omitting field details, for a much smaller response"}},"hostedApiKey":"none"},"agiloft_lock_record":{"id":"agiloft_lock_record","name":"Agiloft Lock Record","description":"Lock, unlock, or check the lock status of an Agiloft record.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name (e.g., \\"contracts\\")"},"recordId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the record to lock, unlock, or check"},"lockAction":{"type":"string","required":true,"visibility":"user-or-llm","description":"Action to perform: \\"lock\\", \\"unlock\\", or \\"check\\""},"force":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Unlock only: release a lock held by another user."}},"hostedApiKey":"none"},"agiloft_nlp_search":{"id":"agiloft_nlp_search","name":"Agiloft Natural Language Search","description":"Search Agiloft records by describing what you want in plain language, such as \\"active NDAs submitted last month\\".","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"nlpQuery":{"type":"string","required":true,"visibility":"user-or-llm","description":"The request in plain language, e.g. \\"Show me open, high-priority contracts\\". Structured field filters are not accepted — use Search Records for those."},"fields":{"type":"string","required":true,"visibility":"user-or-llm","description":"Comma-separated field names to return, e.g. \\"id, contract_title1, company_name\\""},"page":{"type":"string","required":false,"visibility":"user-or-llm","description":"Page number, starting from 0"},"limit":{"type":"string","required":false,"visibility":"user-or-llm","description":"Records per page"}},"hostedApiKey":"none"},"agiloft_read_record":{"id":"agiloft_read_record","name":"Agiloft Read Record","description":"Read a record by ID from an Agiloft table.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name (e.g., \\"contracts\\", \\"contacts.employees\\")"},"recordId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the record to read"},"fields":{"type":"string","required":false,"visibility":"user-or-llm","description":"Comma-separated list of field names to include in the response"}},"hostedApiKey":"none"},"agiloft_remove_attachment":{"id":"agiloft_remove_attachment","name":"Agiloft Remove Attachment","description":"Remove an attached file from a field in an Agiloft record.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name (e.g., \\"contracts\\")"},"recordId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the record containing the attachment"},"fieldName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the attachment field"},"position":{"type":"string","required":true,"visibility":"user-or-llm","description":"Position index of the file to remove (starting from 0)"}},"hostedApiKey":"none"},"agiloft_retrieve_attachment":{"id":"agiloft_retrieve_attachment","name":"Agiloft Retrieve Attachment","description":"Download an attached file from an Agiloft record field.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name (e.g., \\"contracts\\")"},"recordId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the record containing the attachment"},"fieldName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the attachment field"},"position":{"type":"string","required":true,"visibility":"user-or-llm","description":"Position index of the file in the field (starting from 0)"}},"hostedApiKey":"none"},"agiloft_run_action_button":{"id":"agiloft_run_action_button","name":"Agiloft Run Action Button","description":"Run an action button on an Agiloft record, such as an approval or send-for-signature step.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name (e.g., \\"contracts\\", \\"case\\")"},"recordId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the record to run the action button on"},"actionButtonField":{"type":"string","required":true,"visibility":"user-or-llm","description":"Logical name of the field holding the action button (e.g., \\"ab_field\\")"}},"hostedApiKey":"none"},"agiloft_saved_search":{"id":"agiloft_saved_search","name":"Agiloft Saved Search","description":"List the saved searches defined for an Agiloft table.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Logical table name to list saved searches for (e.g., \\"contract\\")"}},"hostedApiKey":"none"},"agiloft_search_records":{"id":"agiloft_search_records","name":"Agiloft Search Records","description":"Search for records in an Agiloft table using a query.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name to search in (e.g., \\"contracts\\", \\"contacts.employees\\")"},"query":{"type":"string","required":false,"visibility":"user-or-llm","description":"Ad hoc EWSearch query. Combine conditions with && (and) or || (or) and quote every value — e.g. \\"summary~=\'test\'&&priority=\'High\'\\". Required unless a saved search is given."},"search":{"type":"string","required":false,"visibility":"user-or-llm","description":"Label of a saved search defined on the table (e.g., \\"C: Status is Closed\\"). Can be combined with a query to narrow it further."},"fields":{"type":"string","required":false,"visibility":"user-or-llm","description":"Comma-separated list of field names to include in the results"},"page":{"type":"string","required":false,"visibility":"user-or-llm","description":"Page number for paginated results (starting from 0)"},"limit":{"type":"string","required":false,"visibility":"user-or-llm","description":"Maximum number of records to return per page. Agiloft treats 0 as \\"all records\\", so leave it unset or use a positive value to keep result sizes bounded."}},"hostedApiKey":"none"},"agiloft_select_records":{"id":"agiloft_select_records","name":"Agiloft Select Records","description":"Select record IDs matching a SQL WHERE clause from an Agiloft table.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name (e.g., \\"contracts\\", \\"contacts.employees\\")"},"where":{"type":"string","required":true,"visibility":"user-or-llm","description":"SQL WHERE clause using database column names (e.g., \\"summary like \'%new%\'\\" or \\"assigned_person=\'John Doe\'\\"). EWSelect has no page size and returns every matching ID, so append a database limit such as \\"limit 0,200\\" to bound the result."}},"hostedApiKey":"none"},"agiloft_update_record":{"id":"agiloft_update_record","name":"Agiloft Update Record","description":"Update an existing record in an Agiloft table.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name (e.g., \\"contracts\\", \\"contacts.employees\\")"},"recordId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the record to update"},"data":{"type":"string","required":true,"visibility":"user-or-llm","description":"Updated field values as a JSON object (e.g., {\\"status\\": \\"Active\\", \\"priority\\": \\"High\\"})"}},"hostedApiKey":"none"},"agiloft_upsert_record":{"id":"agiloft_upsert_record","name":"Agiloft Upsert Record","description":"Create an Agiloft record, or update it when a record already matches the given fields.","version":"1.0.0","params":{"instanceUrl":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft instance URL (e.g., https://mycompany.agiloft.com)"},"knowledgeBase":{"type":"string","required":true,"visibility":"user-only","description":"Knowledge base name"},"login":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft username"},"password":{"type":"string","required":true,"visibility":"user-only","description":"Agiloft password"},"table":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table name (e.g., \\"contracts\\", \\"contacts.employees\\")"},"match":{"type":"string","required":true,"visibility":"user-or-llm","description":"Field used to find an existing record (e.g., \\"ext_id\\"). Pick something that identifies a record uniquely — if more than one record matches, Agiloft writes nothing and returns a conflict."},"async":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Queue the write instead of waiting for it. Returns a callback ID instead of a record ID; pass that to Async Status to poll the result."},"data":{"type":"string","required":true,"visibility":"user-or-llm","description":"Field values as a JSON object. On create these populate the new record; on update only the supplied fields change."}},"hostedApiKey":"none"},"ahrefs_anchors":{"id":"ahrefs_anchors","name":"Ahrefs Anchors","description":"Get the anchor text distribution for a target domain or URL\'s backlinks, showing how many links and referring domains use each anchor text.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain or URL to analyze. Example: \\"example.com\\" or \\"https://example.com/page\\""},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match)"},"history":{"type":"string","required":false,"visibility":"user-or-llm","description":"Historical scope: \\"live\\" (currently live), \\"all_time\\" (default, includes lost backlinks), or \\"since:YYYY-MM-DD\\" (backlinks found since a date)"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of results to return. Example: 50 (default: 1000)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_backlinks":{"id":"ahrefs_backlinks","name":"Ahrefs Backlinks","description":"Get a list of backlinks pointing to a target domain or URL. Returns details about each backlink including source URL, anchor text, and domain rating.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain or URL to analyze. Example: \\"example.com\\" or \\"https://example.com/page\\""},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match). Example: \\"domain\\""},"history":{"type":"string","required":false,"visibility":"user-or-llm","description":"Historical scope: \\"live\\" (currently live backlinks), \\"all_time\\" (default, includes lost backlinks), or \\"since:YYYY-MM-DD\\" (backlinks found since a date)."},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of results to return. Example: 50 (default: 1000)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_backlinks_stats":{"id":"ahrefs_backlinks_stats","name":"Ahrefs Backlinks Stats","description":"Get backlink and referring domain totals for a target domain or URL, both currently live and across all time.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain or URL to analyze. Example: \\"example.com\\" or \\"https://example.com/page\\""},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match). Example: \\"domain\\""},"date":{"type":"string","required":false,"visibility":"user-only","description":"Date to report metrics on, in YYYY-MM-DD format (defaults to today)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_batch_analysis":{"id":"ahrefs_batch_analysis","name":"Ahrefs Batch Analysis","description":"Get bulk SEO metrics (Domain Rating, backlinks, referring domains, organic traffic, and more) for multiple domains or URLs in a single request. Useful for comparing many competitors at once.","version":"1.0.0","params":{"targets":{"type":"string","required":true,"visibility":"user-or-llm","description":"Comma-separated list of domains or URLs to analyze. Example: \\"example.com,competitor.com\\""},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode applied to every target: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match)"},"protocol":{"type":"string","required":false,"visibility":"user-or-llm","description":"Protocol applied to every target: \\"both\\" (default), \\"http\\", or \\"https\\""},"country":{"type":"string","required":false,"visibility":"user-or-llm","description":"Country code for traffic data. Example: \\"us\\", \\"gb\\", \\"de\\" (default: \\"us\\")"},"volumeMode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Search volume calculation: \\"monthly\\" or \\"average\\" (default: \\"monthly\\")"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_broken_backlinks":{"id":"ahrefs_broken_backlinks","name":"Ahrefs Broken Backlinks","description":"Get a list of broken backlinks pointing to a target domain or URL. Useful for identifying link reclamation opportunities.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain or URL to analyze. Example: \\"example.com\\" or \\"https://example.com/page\\""},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match). Example: \\"domain\\""},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of results to return. Example: 50 (default: 1000)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_domain_rating":{"id":"ahrefs_domain_rating","name":"Ahrefs Domain Rating","description":"Get the Domain Rating (DR) and Ahrefs Rank for a target domain. Domain Rating shows the strength of a website\'s backlink profile on a scale from 0 to 100.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain to analyze (e.g., example.com)"},"date":{"type":"string","required":false,"visibility":"user-only","description":"Date for historical data in YYYY-MM-DD format (defaults to today)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_domain_rating_history":{"id":"ahrefs_domain_rating_history","name":"Ahrefs Domain Rating History","description":"Get the historical Domain Rating (DR) trend for a target domain or URL over a date range, grouped daily, weekly, or monthly.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain or URL to analyze. Example: \\"example.com\\""},"dateFrom":{"type":"string","required":true,"visibility":"user-only","description":"Start date of the historical period, in YYYY-MM-DD format"},"dateTo":{"type":"string","required":false,"visibility":"user-only","description":"End date of the historical period, in YYYY-MM-DD format (defaults to today)"},"historyGrouping":{"type":"string","required":false,"visibility":"user-or-llm","description":"Time interval for grouping data points: \\"daily\\", \\"weekly\\", or \\"monthly\\" (default: \\"monthly\\")"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_keyword_overview":{"id":"ahrefs_keyword_overview","name":"Ahrefs Keyword Overview","description":"Get detailed metrics for a keyword including search volume, keyword difficulty, CPC, clicks, and traffic potential.","version":"1.0.0","params":{"keyword":{"type":"string","required":true,"visibility":"user-or-llm","description":"The keyword to analyze"},"country":{"type":"string","required":false,"visibility":"user-or-llm","description":"Country code for keyword data. Example: \\"us\\", \\"gb\\", \\"de\\" (default: \\"us\\")"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_keywords_history":{"id":"ahrefs_keywords_history","name":"Ahrefs Keywords History","description":"Get the historical organic keyword ranking distribution for a target domain or URL over a date range: how many keywords rank in each position bucket at each point in time.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain or URL to analyze. Example: \\"example.com\\""},"dateFrom":{"type":"string","required":true,"visibility":"user-only","description":"Start date of the historical period, in YYYY-MM-DD format"},"dateTo":{"type":"string","required":false,"visibility":"user-only","description":"End date of the historical period, in YYYY-MM-DD format (defaults to today)"},"historyGrouping":{"type":"string","required":false,"visibility":"user-or-llm","description":"Time interval for grouping data points: \\"daily\\", \\"weekly\\", or \\"monthly\\" (default: \\"monthly\\")"},"country":{"type":"string","required":false,"visibility":"user-or-llm","description":"Country code for search results. Example: \\"us\\", \\"gb\\", \\"de\\" (default: \\"us\\")"},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_metrics":{"id":"ahrefs_metrics","name":"Ahrefs Metrics","description":"Get a one-call organic and paid search overview for a target domain or URL: organic traffic, organic keywords, paid traffic, paid keywords, and estimated traffic cost.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain or URL to analyze. Example: \\"example.com\\""},"country":{"type":"string","required":false,"visibility":"user-or-llm","description":"Country code for traffic data. Example: \\"us\\", \\"gb\\", \\"de\\""},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match). Example: \\"domain\\""},"date":{"type":"string","required":false,"visibility":"user-only","description":"Date to report metrics on, in YYYY-MM-DD format (defaults to today)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_metrics_history":{"id":"ahrefs_metrics_history","name":"Ahrefs Metrics History","description":"Get the historical organic and paid traffic trend for a target domain or URL over a date range: organic traffic/cost and paid traffic/cost at each point in time.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain or URL to analyze. Example: \\"example.com\\""},"dateFrom":{"type":"string","required":true,"visibility":"user-only","description":"Start date of the historical period, in YYYY-MM-DD format"},"dateTo":{"type":"string","required":false,"visibility":"user-only","description":"End date of the historical period, in YYYY-MM-DD format (defaults to today)"},"volumeMode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Search volume calculation: \\"monthly\\" or \\"average\\" (default: \\"monthly\\")"},"historyGrouping":{"type":"string","required":false,"visibility":"user-or-llm","description":"Time interval for grouping data points: \\"daily\\", \\"weekly\\", or \\"monthly\\" (default: \\"monthly\\")"},"country":{"type":"string","required":false,"visibility":"user-or-llm","description":"Country code for traffic data. Example: \\"us\\", \\"gb\\", \\"de\\" (default: \\"us\\")"},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_organic_competitors":{"id":"ahrefs_organic_competitors","name":"Ahrefs Organic Competitors","description":"Get domains that compete with a target domain or URL for the same organic keywords, ranked by keyword overlap.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain or URL to analyze. Example: \\"example.com\\""},"country":{"type":"string","required":false,"visibility":"user-or-llm","description":"Country code for search results. Example: \\"us\\", \\"gb\\", \\"de\\" (default: \\"us\\")"},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match). Example: \\"domain\\""},"date":{"type":"string","required":false,"visibility":"user-only","description":"Date to report metrics on, in YYYY-MM-DD format (defaults to today)"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of results to return. Example: 50 (default: 1000)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_organic_keywords":{"id":"ahrefs_organic_keywords","name":"Ahrefs Organic Keywords","description":"Get organic keywords that a target domain or URL ranks for in Google search results. Returns keyword details including search volume, ranking position, and estimated traffic.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain or URL to analyze. Example: \\"example.com\\" or \\"https://example.com/page\\""},"country":{"type":"string","required":false,"visibility":"user-or-llm","description":"Country code for search results. Example: \\"us\\", \\"gb\\", \\"de\\" (default: \\"us\\")"},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match). Example: \\"domain\\""},"date":{"type":"string","required":false,"visibility":"user-only","description":"Date to report metrics on, in YYYY-MM-DD format (defaults to today)"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of results to return. Example: 50 (default: 1000)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_paid_pages":{"id":"ahrefs_paid_pages","name":"Ahrefs Paid Pages","description":"Get a target domain\'s pages that receive paid search traffic, sorted by estimated paid traffic. Returns page URLs with their paid traffic, keyword counts, and estimated spend.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain or URL to analyze. Example: \\"example.com\\""},"country":{"type":"string","required":false,"visibility":"user-or-llm","description":"Country code for traffic data. Example: \\"us\\", \\"gb\\", \\"de\\" (default: \\"us\\")"},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match)"},"date":{"type":"string","required":false,"visibility":"user-only","description":"Date to report metrics on, in YYYY-MM-DD format (defaults to today)"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of results to return. Example: 50 (default: 1000)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_rank_tracker_competitors_overview":{"id":"ahrefs_rank_tracker_competitors_overview","name":"Ahrefs Rank Tracker Competitors Overview","description":"Get competitor rankings for the keywords tracked in an Ahrefs Rank Tracker project: each tracked keyword\'s volume and difficulty alongside every competitor\'s position, traffic, and traffic value. This endpoint is free and does not consume API units.","version":"1.0.0","params":{"projectId":{"type":"number","required":true,"visibility":"user-or-llm","description":"The Rank Tracker project ID (found in the project URL in Ahrefs)"},"date":{"type":"string","required":true,"visibility":"user-only","description":"Date to report rankings for, in YYYY-MM-DD format"},"device":{"type":"string","required":true,"visibility":"user-or-llm","description":"Rankings device type: \\"desktop\\" or \\"mobile\\""},"dateCompared":{"type":"string","required":false,"visibility":"user-only","description":"Comparison date in YYYY-MM-DD format, to compute position/traffic deltas"},"volumeMode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Search volume calculation: \\"monthly\\" or \\"average\\" (default: \\"monthly\\")"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of results to return. Example: 50 (default: 1000)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_rank_tracker_competitors_stats":{"id":"ahrefs_rank_tracker_competitors_stats","name":"Ahrefs Rank Tracker Competitors Stats","description":"Get aggregate competitor stats for an Ahrefs Rank Tracker project: each competitor\'s traffic, traffic value, average position, and share of voice across all tracked keywords. This endpoint is free and does not consume API units.","version":"1.0.0","params":{"projectId":{"type":"number","required":true,"visibility":"user-or-llm","description":"The Rank Tracker project ID (found in the project URL in Ahrefs)"},"date":{"type":"string","required":true,"visibility":"user-only","description":"Date to report metrics for, in YYYY-MM-DD format"},"device":{"type":"string","required":true,"visibility":"user-or-llm","description":"Rankings device type: \\"desktop\\" or \\"mobile\\""},"volumeMode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Search volume calculation: \\"monthly\\" or \\"average\\" (default: \\"monthly\\")"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_rank_tracker_overview":{"id":"ahrefs_rank_tracker_overview","name":"Ahrefs Rank Tracker Overview","description":"Get ranking overview metrics for the keywords tracked in an Ahrefs Rank Tracker project: position, search volume, keyword difficulty, and estimated traffic. This endpoint is free and does not consume API units.","version":"1.0.0","params":{"projectId":{"type":"number","required":true,"visibility":"user-or-llm","description":"The Rank Tracker project ID (found in the project URL in Ahrefs)"},"date":{"type":"string","required":true,"visibility":"user-only","description":"Date to report rankings for, in YYYY-MM-DD format"},"device":{"type":"string","required":true,"visibility":"user-or-llm","description":"Rankings device type: \\"desktop\\" or \\"mobile\\""},"dateCompared":{"type":"string","required":false,"visibility":"user-only","description":"Comparison date in YYYY-MM-DD format, to compute position/traffic deltas"},"volumeMode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Search volume calculation: \\"monthly\\" or \\"average\\" (default: \\"monthly\\")"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of results to return. Example: 50 (default: 1000)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_rank_tracker_serp_overview":{"id":"ahrefs_rank_tracker_serp_overview","name":"Ahrefs Rank Tracker SERP Overview","description":"Get the full SERP (search engine results page) for a keyword tracked in an Ahrefs Rank Tracker project, including every ranking URL with its position, title, and authority metrics. This endpoint is free and does not consume API units.","version":"1.0.0","params":{"projectId":{"type":"number","required":true,"visibility":"user-or-llm","description":"The Rank Tracker project ID (found in the project URL in Ahrefs)"},"keyword":{"type":"string","required":true,"visibility":"user-or-llm","description":"The tracked keyword to retrieve SERP data for"},"country":{"type":"string","required":true,"visibility":"user-or-llm","description":"Country code for the tracked keyword. Example: \\"us\\", \\"gb\\", \\"de\\""},"device":{"type":"string","required":true,"visibility":"user-or-llm","description":"Rankings device type: \\"desktop\\" or \\"mobile\\""},"topPositions":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of top organic positions to return (defaults to all available)"},"date":{"type":"string","required":false,"visibility":"user-only","description":"Timestamp to return the last available SERP Overview at, in YYYY-MM-DDThh:mm:ss format"},"locationId":{"type":"number","required":false,"visibility":"user-or-llm","description":"Location ID of the tracked keyword, if tracked at a specific location"},"languageCode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Language code of the tracked keyword"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_refdomains_history":{"id":"ahrefs_refdomains_history","name":"Ahrefs Referring Domains History","description":"Get the historical referring domains trend for a target domain or URL over a date range, grouped daily, weekly, or monthly.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain or URL to analyze. Example: \\"example.com\\""},"dateFrom":{"type":"string","required":true,"visibility":"user-only","description":"Start date of the historical period, in YYYY-MM-DD format"},"dateTo":{"type":"string","required":false,"visibility":"user-only","description":"End date of the historical period, in YYYY-MM-DD format (defaults to today)"},"historyGrouping":{"type":"string","required":false,"visibility":"user-or-llm","description":"Time interval for grouping data points: \\"daily\\", \\"weekly\\", or \\"monthly\\" (default: \\"monthly\\")"},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_referring_domains":{"id":"ahrefs_referring_domains","name":"Ahrefs Referring Domains","description":"Get a list of domains that link to a target domain or URL. Returns unique referring domains with their domain rating, backlink counts, and discovery dates.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain or URL to analyze. Example: \\"example.com\\" or \\"https://example.com/page\\""},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match). Example: \\"domain\\""},"history":{"type":"string","required":false,"visibility":"user-or-llm","description":"Historical scope: \\"live\\" (currently live), \\"all_time\\" (default, includes lost domains), or \\"since:YYYY-MM-DD\\" (domains found since a date)."},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of results to return. Example: 50 (default: 1000)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_related_terms":{"id":"ahrefs_related_terms","name":"Ahrefs Related Terms","description":"Get keyword ideas related to a seed keyword: terms the same top-ranking pages also rank for (\\"also rank for\\") or also discuss (\\"also talk about\\"), with volume, difficulty, and CPC.","version":"1.0.0","params":{"keyword":{"type":"string","required":true,"visibility":"user-or-llm","description":"The seed keyword to find related terms for"},"country":{"type":"string","required":false,"visibility":"user-or-llm","description":"Country code for keyword data. Example: \\"us\\", \\"gb\\", \\"de\\" (default: \\"us\\")"},"terms":{"type":"string","required":false,"visibility":"user-or-llm","description":"Type of related keywords to return: \\"also_rank_for\\", \\"also_talk_about\\", or \\"all\\" (default: \\"all\\")"},"viewFor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Whether to derive related terms from the top 10 or top 100 ranking pages (default: \\"top_10\\")"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of results to return. Example: 50 (default: 1000)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_site_audit_page_explorer":{"id":"ahrefs_site_audit_page_explorer","name":"Ahrefs Site Audit Page Explorer","description":"Get crawled pages from an Ahrefs Site Audit project with health and SEO metrics: HTTP status, title, link counts, backlinks, indexability, and traffic. Optionally filter to pages affected by a specific issue.","version":"1.0.0","params":{"projectId":{"type":"number","required":true,"visibility":"user-or-llm","description":"The Site Audit project ID (found in the project URL in Ahrefs)"},"date":{"type":"string","required":false,"visibility":"user-only","description":"Crawl date in YYYY-MM-DDThh:mm:ss format (defaults to the most recent crawl)"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of results to return. Example: 50 (default: 1000)"},"offset":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of results to skip, for pagination"},"issueId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Only return pages affected by this issue ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"ahrefs_top_pages":{"id":"ahrefs_top_pages","name":"Ahrefs Top Pages","description":"Get the top pages of a target domain sorted by organic traffic. Returns page URLs with their traffic, keyword counts, and estimated traffic value.","version":"1.0.0","params":{"target":{"type":"string","required":true,"visibility":"user-or-llm","description":"The target domain to analyze. Example: \\"example.com\\""},"country":{"type":"string","required":false,"visibility":"user-or-llm","description":"Country code for traffic data. Example: \\"us\\", \\"gb\\", \\"de\\" (default: \\"us\\")"},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match). Example: \\"domain\\""},"date":{"type":"string","required":false,"visibility":"user-only","description":"Date to report metrics on, in YYYY-MM-DD format (defaults to today)"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of results to return. Example: 50 (default: 1000)"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ahrefs API Key"}},"hostedApiKey":"none"},"airtable_create_records":{"id":"airtable_create_records","name":"Airtable Create Records","description":"Write new records to an Airtable table","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token"},"baseId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Airtable base ID (starts with \\"app\\", e.g., \\"appXXXXXXXXXXXXXX\\")"},"tableId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table ID (starts with \\"tbl\\") or table name"},"records":{"type":"json","required":true,"visibility":"user-or-llm","description":"Array of records to create, each with a `fields` object"},"typecast":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"When true, Airtable automatically converts string values to the field type"}},"oauth":{"required":true,"provider":"airtable"},"hostedApiKey":"none"},"airtable_delete_records":{"id":"airtable_delete_records","name":"Airtable Delete Records","description":"Delete one or more records from an Airtable table by ID","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token"},"baseId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Airtable base ID (starts with \\"app\\", e.g., \\"appXXXXXXXXXXXXXX\\")"},"tableId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table ID (starts with \\"tbl\\") or table name"},"recordIds":{"type":"json","required":true,"visibility":"user-or-llm","description":"Array of record IDs to delete (each starts with \\"rec\\", e.g., [\\"recXXXXXXXXXXXXXX\\"]). Pass a single-element array to delete one record."}},"oauth":{"required":true,"provider":"airtable"},"hostedApiKey":"none"},"airtable_get_base_schema":{"id":"airtable_get_base_schema","name":"Airtable Get Base Schema","description":"Get the schema of all tables, fields, and views in an Airtable base","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token"},"baseId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Airtable base ID (starts with \\"app\\", e.g., \\"appXXXXXXXXXXXXXX\\")"}},"oauth":{"required":true,"provider":"airtable"},"hostedApiKey":"none"},"airtable_get_record":{"id":"airtable_get_record","name":"Airtable Get Record","description":"Retrieve a single record from an Airtable table by its ID","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token"},"baseId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Airtable base ID (starts with \\"app\\", e.g., \\"appXXXXXXXXXXXXXX\\")"},"tableId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table ID (starts with \\"tbl\\") or table name"},"recordId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Record ID to retrieve (starts with \\"rec\\", e.g., \\"recXXXXXXXXXXXXXX\\")"}},"oauth":{"required":true,"provider":"airtable"},"hostedApiKey":"none"},"airtable_list_bases":{"id":"airtable_list_bases","name":"Airtable List Bases","description":"List all bases the authenticated user has access to","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token"},"offset":{"type":"string","required":false,"visibility":"user-or-llm","description":"Pagination offset for retrieving additional bases"}},"oauth":{"required":true,"provider":"airtable"},"hostedApiKey":"none"},"airtable_list_records":{"id":"airtable_list_records","name":"Airtable List Records","description":"Read records from an Airtable table","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token"},"baseId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Airtable base ID (starts with \\"app\\", e.g., \\"appXXXXXXXXXXXXXX\\")"},"tableId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table ID (starts with \\"tbl\\") or table name"},"maxRecords":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of records to return (default: all records)"},"filterFormula":{"type":"string","required":false,"visibility":"user-or-llm","description":"Formula to filter records (e.g., \\"({Field Name} = \'Value\')\\")"}},"oauth":{"required":true,"provider":"airtable"},"hostedApiKey":"none"},"airtable_list_tables":{"id":"airtable_list_tables","name":"Airtable List Tables","description":"List all tables and their schema in an Airtable base","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token"},"baseId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Airtable base ID (starts with \\"app\\", e.g., \\"appXXXXXXXXXXXXXX\\")"}},"oauth":{"required":true,"provider":"airtable"},"hostedApiKey":"none"},"airtable_update_multiple_records":{"id":"airtable_update_multiple_records","name":"Airtable Update Multiple Records","description":"Update multiple existing records in an Airtable table","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token"},"baseId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Airtable base ID (starts with \\"app\\", e.g., \\"appXXXXXXXXXXXXXX\\")"},"tableId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table ID (starts with \\"tbl\\") or table name"},"records":{"type":"json","required":true,"visibility":"user-or-llm","description":"Array of records to update, each with an `id` and a `fields` object"},"typecast":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"When true, Airtable automatically converts string values to the field type"}},"oauth":{"required":true,"provider":"airtable"},"hostedApiKey":"none"},"airtable_update_record":{"id":"airtable_update_record","name":"Airtable Update Record","description":"Update an existing record in an Airtable table by ID","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token"},"baseId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Airtable base ID (starts with \\"app\\", e.g., \\"appXXXXXXXXXXXXXX\\")"},"tableId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table ID (starts with \\"tbl\\") or table name"},"recordId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Record ID to update (starts with \\"rec\\", e.g., \\"recXXXXXXXXXXXXXX\\")"},"fields":{"type":"json","required":true,"visibility":"user-or-llm","description":"An object containing the field names and their new values"},"typecast":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"When true, Airtable automatically converts string values to the field type"}},"oauth":{"required":true,"provider":"airtable"},"hostedApiKey":"none"},"airtable_upsert_records":{"id":"airtable_upsert_records","name":"Airtable Upsert Records","description":"Update existing records or create new ones in an Airtable table, matching on the specified merge fields","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token"},"baseId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Airtable base ID (starts with \\"app\\", e.g., \\"appXXXXXXXXXXXXXX\\")"},"tableId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Table ID (starts with \\"tbl\\") or table name"},"records":{"type":"json","required":true,"visibility":"user-or-llm","description":"Array of records to upsert, each with a `fields` object"},"fieldsToMergeOn":{"type":"json","required":true,"visibility":"user-or-llm","description":"Array of field names used to match existing records (max 3). A record is updated when all merge fields match, otherwise it is created. Example: [\\"Name\\"]"},"typecast":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"When true, Airtable automatically converts string values to the field type"}},"oauth":{"required":true,"provider":"airtable"},"hostedApiKey":"none"},"airweave_search":{"id":"airweave_search","name":"Airweave Search","description":"Search your synced data collections using Airweave. Supports semantic search with hybrid, neural, or keyword retrieval strategies. Optionally generate AI-powered answers from search results.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Airweave API Key for authentication"},"collectionId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The readable ID of the collection to search"},"query":{"type":"string","required":true,"visibility":"user-or-llm","description":"The search query text"},"limit":{"type":"number","required":false,"visibility":"user-only","description":"Maximum number of results to return (default: 100)"},"retrievalStrategy":{"type":"string","required":false,"visibility":"user-or-llm","description":"Retrieval strategy: hybrid (default), neural, or keyword"},"expandQuery":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Generate query variations to improve recall"},"rerank":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Reorder results for improved relevance using LLM"},"generateAnswer":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Generate a natural-language answer to the query"}},"hostedApiKey":"none"},"algolia_add_record":{"id":"algolia_add_record","name":"Algolia Add Record","description":"Add or replace a record in an Algolia index","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Admin API Key"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the Algolia index"},"objectID":{"type":"string","required":false,"visibility":"user-or-llm","description":"Object ID for the record (auto-generated if not provided)"},"record":{"type":"json","required":true,"visibility":"user-or-llm","description":"JSON object representing the record to add"}},"hostedApiKey":"none"},"algolia_batch_operations":{"id":"algolia_batch_operations","name":"Algolia Batch Operations","description":"Perform batch add, update, partial update, or delete operations on records in an Algolia index","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Admin API Key"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the Algolia index"},"requests":{"type":"json","required":true,"visibility":"user-or-llm","description":"Array of batch operations. Each item has \\"action\\" (addObject, updateObject, partialUpdateObject, partialUpdateObjectNoCreate, deleteObject, delete, clear) and \\"body\\" (the record data; must include objectID for update/delete; use an empty object {} for the index-level delete/clear actions)"}},"hostedApiKey":"none"},"algolia_browse_records":{"id":"algolia_browse_records","name":"Algolia Browse Records","description":"Browse and iterate over all records in an Algolia index using cursor pagination","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia API Key (must have browse ACL)"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the Algolia index to browse"},"query":{"type":"string","required":false,"visibility":"user-or-llm","description":"Search query to filter browsed records"},"filters":{"type":"string","required":false,"visibility":"user-or-llm","description":"Filter string to narrow down results"},"attributesToRetrieve":{"type":"string","required":false,"visibility":"user-or-llm","description":"Comma-separated list of attributes to retrieve"},"hitsPerPage":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of hits per page (default: 1000, max: 1000)"},"cursor":{"type":"string","required":false,"visibility":"user-or-llm","description":"Cursor from a previous browse response for pagination"},"aroundLatLng":{"type":"string","required":false,"visibility":"user-or-llm","description":"Coordinates for geo-search (e.g., \\"40.71,-74.01\\")"},"aroundRadius":{"type":"string","required":false,"visibility":"user-or-llm","description":"Maximum radius in meters for geo-search, or \\"all\\" for unlimited"},"insideBoundingBox":{"type":"json","required":false,"visibility":"user-or-llm","description":"Bounding box coordinates as [[lat1, lng1, lat2, lng2]] for geo-search"},"insidePolygon":{"type":"json","required":false,"visibility":"user-or-llm","description":"Polygon coordinates as [[lat1, lng1, lat2, lng2, lat3, lng3, ...]] for geo-search"}},"hostedApiKey":"none"},"algolia_clear_records":{"id":"algolia_clear_records","name":"Algolia Clear Records","description":"Clear all records from an Algolia index while keeping settings, synonyms, and rules","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Admin API Key (must have deleteIndex ACL)"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the Algolia index to clear"}},"hostedApiKey":"none"},"algolia_copy_move_index":{"id":"algolia_copy_move_index","name":"Algolia Copy/Move Index","description":"Copy or move an Algolia index to a new destination","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Admin API Key"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the source index"},"operation":{"type":"string","required":true,"visibility":"user-or-llm","description":"Operation to perform: \\"copy\\" or \\"move\\""},"destination":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the destination index"},"scope":{"type":"json","required":false,"visibility":"user-or-llm","description":"Array of scopes to copy (only for \\"copy\\" operation): [\\"settings\\", \\"synonyms\\", \\"rules\\"]. Omit to copy everything including records."}},"hostedApiKey":"none"},"algolia_delete_by_filter":{"id":"algolia_delete_by_filter","name":"Algolia Delete By Filter","description":"Delete all records matching a filter from an Algolia index","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Admin API Key (must have deleteIndex ACL)"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the Algolia index"},"filters":{"type":"string","required":false,"visibility":"user-or-llm","description":"Filter expression to match records for deletion (e.g., \\"category:outdated\\")"},"facetFilters":{"type":"json","required":false,"visibility":"user-or-llm","description":"Array of facet filters (e.g., [\\"brand:Acme\\"])"},"numericFilters":{"type":"json","required":false,"visibility":"user-or-llm","description":"Array of numeric filters (e.g., [\\"price > 100\\"])"},"tagFilters":{"type":"json","required":false,"visibility":"user-or-llm","description":"Array of tag filters using the _tags attribute (e.g., [\\"published\\"])"},"aroundLatLng":{"type":"string","required":false,"visibility":"user-or-llm","description":"Coordinates for geo-search filter (e.g., \\"40.71,-74.01\\")"},"aroundRadius":{"type":"string","required":false,"visibility":"user-or-llm","description":"Maximum radius in meters for geo-search, or \\"all\\" for unlimited"},"insideBoundingBox":{"type":"json","required":false,"visibility":"user-or-llm","description":"Bounding box coordinates as [[lat1, lng1, lat2, lng2]] for geo-search filter"},"insidePolygon":{"type":"json","required":false,"visibility":"user-or-llm","description":"Polygon coordinates as [[lat1, lng1, lat2, lng2, lat3, lng3, ...]] for geo-search filter"}},"hostedApiKey":"none"},"algolia_delete_index":{"id":"algolia_delete_index","name":"Algolia Delete Index","description":"Delete an entire Algolia index and all its records","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Admin API Key (must have deleteIndex ACL)"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the Algolia index to delete"}},"hostedApiKey":"none"},"algolia_delete_record":{"id":"algolia_delete_record","name":"Algolia Delete Record","description":"Delete a record by objectID from an Algolia index","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Admin API Key"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the Algolia index"},"objectID":{"type":"string","required":true,"visibility":"user-or-llm","description":"The objectID of the record to delete"}},"hostedApiKey":"none"},"algolia_get_record":{"id":"algolia_get_record","name":"Algolia Get Record","description":"Get a record by objectID from an Algolia index","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia API Key"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the Algolia index"},"objectID":{"type":"string","required":true,"visibility":"user-or-llm","description":"The objectID of the record to retrieve"},"attributesToRetrieve":{"type":"string","required":false,"visibility":"user-or-llm","description":"Comma-separated list of attributes to retrieve"}},"hostedApiKey":"none"},"algolia_get_records":{"id":"algolia_get_records","name":"Algolia Get Records","description":"Retrieve multiple records by objectID from one or more Algolia indices","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia API Key"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Default index name for all requests"},"requests":{"type":"json","required":true,"visibility":"user-or-llm","description":"Array of objects specifying records to retrieve. Each must have \\"objectID\\" and optionally \\"indexName\\" and \\"attributesToRetrieve\\"."}},"hostedApiKey":"none"},"algolia_get_settings":{"id":"algolia_get_settings","name":"Algolia Get Settings","description":"Retrieve the settings of an Algolia index","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia API Key"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the Algolia index"}},"hostedApiKey":"none"},"algolia_get_task_status":{"id":"algolia_get_task_status","name":"Algolia Get Task Status","description":"Check whether an Algolia indexing task has finished publishing","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia API Key"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the Algolia index the task ran against"},"taskID":{"type":"number","required":true,"visibility":"user-or-llm","description":"The taskID returned by a previous write operation"}},"hostedApiKey":"none"},"algolia_list_indices":{"id":"algolia_list_indices","name":"Algolia List Indices","description":"List all indices in an Algolia application","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia API Key"},"page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Page number for paginating indices (default: not paginated)"},"hitsPerPage":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of indices per page (default: 100)"}},"hostedApiKey":"none"},"algolia_partial_update_record":{"id":"algolia_partial_update_record","name":"Algolia Partial Update Record","description":"Partially update a record in an Algolia index without replacing it entirely","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Admin API Key"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the Algolia index"},"objectID":{"type":"string","required":true,"visibility":"user-or-llm","description":"The objectID of the record to update"},"attributes":{"type":"json","required":true,"visibility":"user-or-llm","description":"JSON object with attributes to update. Supports built-in operations like {\\"stock\\": {\\"_operation\\": \\"Decrement\\", \\"value\\": 1}}"},"createIfNotExists":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Whether to create the record if it does not exist (default: true)"}},"hostedApiKey":"none"},"algolia_search":{"id":"algolia_search","name":"Algolia Search","description":"Search an Algolia index","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia API Key"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the Algolia index to search"},"query":{"type":"string","required":true,"visibility":"user-or-llm","description":"Search query text"},"hitsPerPage":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of hits per page (default: 20)"},"page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Page number to retrieve (default: 0)"},"filters":{"type":"string","required":false,"visibility":"user-or-llm","description":"Filter string (e.g., \\"category:electronics AND price < 100\\")"},"attributesToRetrieve":{"type":"string","required":false,"visibility":"user-or-llm","description":"Comma-separated list of attributes to retrieve"},"facets":{"type":"string","required":false,"visibility":"user-or-llm","description":"Comma-separated list of facet attribute names to retrieve counts for (use \\"*\\" for all)"},"getRankingInfo":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Whether to include detailed ranking information in each hit"},"aroundLatLng":{"type":"string","required":false,"visibility":"user-or-llm","description":"Coordinates for geo-search (e.g., \\"40.71,-74.01\\")"},"aroundRadius":{"type":"string","required":false,"visibility":"user-or-llm","description":"Maximum radius in meters for geo-search, or \\"all\\" for unlimited"},"insideBoundingBox":{"type":"json","required":false,"visibility":"user-or-llm","description":"Bounding box coordinates as [[lat1, lng1, lat2, lng2]] for geo-search"},"insidePolygon":{"type":"json","required":false,"visibility":"user-or-llm","description":"Polygon coordinates as [[lat1, lng1, lat2, lng2, lat3, lng3, ...]] for geo-search"}},"hostedApiKey":"none"},"algolia_update_settings":{"id":"algolia_update_settings","name":"Algolia Update Settings","description":"Update the settings of an Algolia index","version":"1.0","params":{"applicationId":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Application ID"},"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Algolia Admin API Key (must have editSettings ACL)"},"indexName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the Algolia index"},"settings":{"type":"json","required":true,"visibility":"user-or-llm","description":"JSON object with settings to update (e.g., {\\"searchableAttributes\\": [\\"name\\", \\"description\\"], \\"customRanking\\": [\\"desc(popularity)\\"]})"},"forwardToReplicas":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Whether to apply changes to replica indices (default: false)"}},"hostedApiKey":"none"},"amplitude_event_segmentation":{"id":"amplitude_event_segmentation","name":"Amplitude Event Segmentation","description":"Query event analytics data with segmentation. Get event counts, uniques, averages, and more.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude API Key"},"secretKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude Secret Key"},"eventType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Event type name to analyze"},"start":{"type":"string","required":true,"visibility":"user-or-llm","description":"Start date in YYYYMMDD format"},"end":{"type":"string","required":true,"visibility":"user-or-llm","description":"End date in YYYYMMDD format"},"metric":{"type":"string","required":false,"visibility":"user-or-llm","description":"Metric type: uniques, totals, pct_dau, average, histogram, sums, value_avg, or formula (default: uniques)"},"interval":{"type":"string","required":false,"visibility":"user-or-llm","description":"Time interval: 1 (daily), 7 (weekly), or 30 (monthly)"},"groupBy":{"type":"string","required":false,"visibility":"user-or-llm","description":"Property name to group by (prefix custom user properties with \\"gp:\\")"},"groupBy2":{"type":"string","required":false,"visibility":"user-or-llm","description":"Second property name to group by (prefix custom user properties with \\"gp:\\")"},"limit":{"type":"string","required":false,"visibility":"user-or-llm","description":"Maximum number of group-by values (max 1000)"},"filters":{"type":"string","required":false,"visibility":"user-or-llm","description":"JSON array of filter objects applied to the event, e.g. [{\\"subprop_type\\":\\"event\\",\\"subprop_key\\":\\"city\\",\\"subprop_op\\":\\"is\\",\\"subprop_value\\":[\\"San Francisco\\"]}]"},"formula":{"type":"string","required":false,"visibility":"user-or-llm","description":"Required when metric is \\"formula\\", e.g. \\"UNIQUES(A)/UNIQUES(B)\\""},"segment":{"type":"string","required":false,"visibility":"user-or-llm","description":"JSON segment definition(s) applied to the query"},"dataResidency":{"type":"string","required":false,"visibility":"user-or-llm","description":"Data residency region: \\"us\\" (default) or \\"eu\\""}},"hostedApiKey":"none"},"amplitude_funnels":{"id":"amplitude_funnels","name":"Amplitude Funnels","description":"Analyze conversion rates and drop-off between a sequence of events.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude API Key"},"secretKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude Secret Key"},"events":{"type":"string","required":true,"visibility":"user-or-llm","description":"JSON array of event objects, one per funnel step in order, e.g. [{\\"event_type\\":\\"signup\\"},{\\"event_type\\":\\"purchase\\"}]"},"start":{"type":"string","required":true,"visibility":"user-or-llm","description":"Start date in YYYYMMDD format"},"end":{"type":"string","required":true,"visibility":"user-or-llm","description":"End date in YYYYMMDD format"},"mode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Funnel ordering: \\"ordered\\", \\"unordered\\", or \\"sequential\\" (default: ordered)"},"userType":{"type":"string","required":false,"visibility":"user-or-llm","description":"User type: \\"new\\" or \\"active\\" (default: active)"},"interval":{"type":"string","required":false,"visibility":"user-or-llm","description":"Time interval: -300000 (real-time), -3600000 (hourly), 1 (daily), 7 (weekly), or 30 (monthly)"},"conversionWindowSeconds":{"type":"string","required":false,"visibility":"user-or-llm","description":"Conversion window in seconds (default: 2592000, i.e. 30 days)"},"groupBy":{"type":"string","required":false,"visibility":"user-or-llm","description":"Property to group by (limit: one; prefix custom properties with \\"gp:\\")"},"limit":{"type":"string","required":false,"visibility":"user-or-llm","description":"Maximum number of group-by values (default: 100, max: 1000)"},"segment":{"type":"string","required":false,"visibility":"user-or-llm","description":"JSON segment definition(s) applied to the query"},"dataResidency":{"type":"string","required":false,"visibility":"user-or-llm","description":"Data residency region: \\"us\\" (default) or \\"eu\\""}},"hostedApiKey":"none"},"amplitude_get_active_users":{"id":"amplitude_get_active_users","name":"Amplitude Get Active Users","description":"Get active or new user counts over a date range from the Dashboard REST API.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude API Key"},"secretKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude Secret Key"},"start":{"type":"string","required":true,"visibility":"user-or-llm","description":"Start date in YYYYMMDD format"},"end":{"type":"string","required":true,"visibility":"user-or-llm","description":"End date in YYYYMMDD format"},"metric":{"type":"string","required":false,"visibility":"user-or-llm","description":"Metric type: \\"active\\" or \\"new\\" (default: active)"},"interval":{"type":"string","required":false,"visibility":"user-or-llm","description":"Time interval: 1 (daily), 7 (weekly), or 30 (monthly)"},"groupBy":{"type":"string","required":false,"visibility":"user-or-llm","description":"Property name to group by"},"segment":{"type":"string","required":false,"visibility":"user-or-llm","description":"JSON segment definition(s) applied to the query"},"dataResidency":{"type":"string","required":false,"visibility":"user-or-llm","description":"Data residency region: \\"us\\" (default) or \\"eu\\""}},"hostedApiKey":"none"},"amplitude_get_revenue":{"id":"amplitude_get_revenue","name":"Amplitude Get Revenue","description":"Get revenue LTV data including ARPU, ARPPU, total revenue, and paying user counts.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude API Key"},"secretKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude Secret Key"},"start":{"type":"string","required":true,"visibility":"user-or-llm","description":"Start date in YYYYMMDD format"},"end":{"type":"string","required":true,"visibility":"user-or-llm","description":"End date in YYYYMMDD format"},"metric":{"type":"string","required":false,"visibility":"user-or-llm","description":"Metric: 0 (ARPU), 1 (ARPPU), 2 (Total Revenue), 3 (Paying Users)"},"interval":{"type":"string","required":false,"visibility":"user-or-llm","description":"Time interval: 1 (daily), 7 (weekly), or 30 (monthly)"},"groupBy":{"type":"string","required":false,"visibility":"user-or-llm","description":"Property name to group by (limit: one)"},"segment":{"type":"string","required":false,"visibility":"user-or-llm","description":"JSON segment definition(s) applied to the query"},"dataResidency":{"type":"string","required":false,"visibility":"user-or-llm","description":"Data residency region: \\"us\\" (default) or \\"eu\\""}},"hostedApiKey":"none"},"amplitude_group_identify":{"id":"amplitude_group_identify","name":"Amplitude Group Identify","description":"Set group-level properties in Amplitude. Supports $set, $setOnce, $add, $append, $unset operations.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude API Key"},"groupType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Group classification (e.g., \\"company\\", \\"org_id\\")"},"groupValue":{"type":"string","required":true,"visibility":"user-or-llm","description":"Specific group identifier (e.g., \\"Acme Corp\\")"},"groupProperties":{"type":"string","required":true,"visibility":"user-or-llm","description":"JSON object of group properties. Use operations like $set, $setOnce, $add, $append, $unset."},"dataResidency":{"type":"string","required":false,"visibility":"user-or-llm","description":"Data residency region: \\"us\\" (default) or \\"eu\\""}},"hostedApiKey":"none"},"amplitude_identify_user":{"id":"amplitude_identify_user","name":"Amplitude Identify User","description":"Set user properties in Amplitude using the Identify API. Supports $set, $setOnce, $add, $append, $unset operations.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude API Key"},"userId":{"type":"string","required":false,"visibility":"user-or-llm","description":"User ID (required if no device_id)"},"deviceId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Device ID (required if no user_id)"},"userProperties":{"type":"string","required":true,"visibility":"user-or-llm","description":"JSON object of user properties. Use operations like $set, $setOnce, $add, $append, $unset."},"dataResidency":{"type":"string","required":false,"visibility":"user-or-llm","description":"Data residency region: \\"us\\" (default) or \\"eu\\""}},"hostedApiKey":"none"},"amplitude_list_events":{"id":"amplitude_list_events","name":"Amplitude List Events","description":"List all event types in the Amplitude project with their weekly totals and unique counts.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude API Key"},"secretKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude Secret Key"},"dataResidency":{"type":"string","required":false,"visibility":"user-or-llm","description":"Data residency region: \\"us\\" (default) or \\"eu\\""}},"hostedApiKey":"none"},"amplitude_realtime_active_users":{"id":"amplitude_realtime_active_users","name":"Amplitude Real-time Active Users","description":"Get real-time active user counts at 5-minute granularity for the last 2 days.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude API Key"},"secretKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude Secret Key"},"dataResidency":{"type":"string","required":false,"visibility":"user-or-llm","description":"Data residency region: \\"us\\" (default) or \\"eu\\""}},"hostedApiKey":"none"},"amplitude_retention":{"id":"amplitude_retention","name":"Amplitude Retention","description":"Measure how many users return to perform an action after a starting action.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude API Key"},"secretKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude Secret Key"},"startEvent":{"type":"string","required":true,"visibility":"user-or-llm","description":"JSON starting event object, e.g. {\\"event_type\\":\\"_new\\"} or {\\"event_type\\":\\"_active\\"}"},"returnEvent":{"type":"string","required":true,"visibility":"user-or-llm","description":"JSON returning event object, e.g. {\\"event_type\\":\\"_all\\"} or {\\"event_type\\":\\"_active\\"}"},"start":{"type":"string","required":true,"visibility":"user-or-llm","description":"Start date in YYYYMMDD format"},"end":{"type":"string","required":true,"visibility":"user-or-llm","description":"End date in YYYYMMDD format"},"retentionMode":{"type":"string","required":false,"visibility":"user-or-llm","description":"Retention type: \\"bracket\\", \\"rolling\\", or \\"n-day\\" (default: n-day)"},"retentionBrackets":{"type":"string","required":false,"visibility":"user-or-llm","description":"Required when Retention Mode is \\"bracket\\". Day ranges, e.g. [[0,4]]"},"interval":{"type":"string","required":false,"visibility":"user-or-llm","description":"Time interval: 1 (daily), 7 (weekly), or 30 (monthly)"},"groupBy":{"type":"string","required":false,"visibility":"user-or-llm","description":"Property to group by (limit: one; prefix custom properties with \\"gp:\\")"},"segment":{"type":"string","required":false,"visibility":"user-or-llm","description":"JSON segment definition(s) applied to the query"},"dataResidency":{"type":"string","required":false,"visibility":"user-or-llm","description":"Data residency region: \\"us\\" (default) or \\"eu\\""}},"hostedApiKey":"none"},"amplitude_send_event":{"id":"amplitude_send_event","name":"Amplitude Send Event","description":"Track an event in Amplitude using the HTTP V2 API.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude API Key"},"userId":{"type":"string","required":false,"visibility":"user-or-llm","description":"User ID (required if no device_id)"},"deviceId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Device ID (required if no user_id)"},"eventType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the event (e.g., \\"page_view\\", \\"purchase\\")"},"eventProperties":{"type":"string","required":false,"visibility":"user-or-llm","description":"JSON object of custom event properties"},"userProperties":{"type":"string","required":false,"visibility":"user-or-llm","description":"JSON object of user properties to set (supports $set, $setOnce, $add, $append, $unset)"},"time":{"type":"string","required":false,"visibility":"user-or-llm","description":"Event timestamp in milliseconds since epoch"},"sessionId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Session start time in milliseconds since epoch"},"insertId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Unique ID for deduplication (within 7-day window)"},"appVersion":{"type":"string","required":false,"visibility":"user-or-llm","description":"Application version string"},"platform":{"type":"string","required":false,"visibility":"user-or-llm","description":"Platform (e.g., \\"Web\\", \\"iOS\\", \\"Android\\")"},"country":{"type":"string","required":false,"visibility":"user-or-llm","description":"Two-letter country code"},"language":{"type":"string","required":false,"visibility":"user-or-llm","description":"Language code (e.g., \\"en\\")"},"ip":{"type":"string","required":false,"visibility":"user-or-llm","description":"IP address for geo-location"},"price":{"type":"string","required":false,"visibility":"user-or-llm","description":"Price of the item purchased"},"quantity":{"type":"string","required":false,"visibility":"user-or-llm","description":"Quantity of items purchased"},"revenue":{"type":"string","required":false,"visibility":"user-or-llm","description":"Revenue amount"},"productId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Product identifier"},"revenueType":{"type":"string","required":false,"visibility":"user-or-llm","description":"Revenue type (e.g., \\"purchase\\", \\"refund\\")"},"dataResidency":{"type":"string","required":false,"visibility":"user-or-llm","description":"Data residency region: \\"us\\" (default) or \\"eu\\""}},"hostedApiKey":"none"},"amplitude_user_activity":{"id":"amplitude_user_activity","name":"Amplitude User Activity","description":"Get the event stream for a specific user by their Amplitude ID.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude API Key"},"secretKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude Secret Key"},"amplitudeId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Amplitude internal user ID"},"offset":{"type":"string","required":false,"visibility":"user-or-llm","description":"Offset for pagination (default 0)"},"limit":{"type":"string","required":false,"visibility":"user-or-llm","description":"Maximum number of events to return (default 1000, max 1000)"},"direction":{"type":"string","required":false,"visibility":"user-or-llm","description":"Sort direction: \\"latest\\" or \\"earliest\\" (default: latest)"},"dataResidency":{"type":"string","required":false,"visibility":"user-or-llm","description":"Data residency region: \\"us\\" (default) or \\"eu\\""}},"hostedApiKey":"none"},"amplitude_user_profile":{"id":"amplitude_user_profile","name":"Amplitude User Profile","description":"Get a user profile including properties, cohort memberships, and computed properties. Not available for EU data-residency projects.","version":"1.0.0","params":{"secretKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude Secret Key"},"userId":{"type":"string","required":false,"visibility":"user-or-llm","description":"External user ID (required if no device_id)"},"deviceId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Device ID (required if no user_id)"},"getAmpProps":{"type":"string","required":false,"visibility":"user-or-llm","description":"Include Amplitude user properties (true/false, default: false)"},"getCohortIds":{"type":"string","required":false,"visibility":"user-or-llm","description":"Include cohort IDs the user belongs to (true/false, default: false)"},"getComputations":{"type":"string","required":false,"visibility":"user-or-llm","description":"Include computed user properties (true/false, default: false)"}},"hostedApiKey":"none"},"amplitude_user_search":{"id":"amplitude_user_search","name":"Amplitude User Search","description":"Search for a user by User ID, Device ID, or Amplitude ID using the Dashboard REST API.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude API Key"},"secretKey":{"type":"string","required":true,"visibility":"user-only","description":"Amplitude Secret Key"},"user":{"type":"string","required":true,"visibility":"user-or-llm","description":"User ID, Device ID, or Amplitude ID to search for"},"dataResidency":{"type":"string","required":false,"visibility":"user-or-llm","description":"Data residency region: \\"us\\" (default) or \\"eu\\""}},"hostedApiKey":"none"},"apify_get_dataset_items":{"id":"apify_get_dataset_items","name":"APIFY Get Dataset Items","description":"Retrieve items stored in an APIFY dataset","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"APIFY API token from console.apify.com/account#/integrations"},"datasetId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Dataset ID to read items from. Example: \\"9RnD3Pql2vGZkc5H5\\""},"itemLimit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Max items to return (1-250000). Default: all items. Example: 500"},"offset":{"type":"number","required":false,"visibility":"user-or-llm","description":"Number of items to skip at the start. Default: 0"},"fields":{"type":"string","required":false,"visibility":"user-or-llm","description":"Comma-separated list of fields to include. Example: \\"title,url,price\\""}},"hostedApiKey":"none"},"apify_get_run":{"id":"apify_get_run","name":"APIFY Get Run","description":"Get the status and details of an APIFY actor run","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"APIFY API token from console.apify.com/account#/integrations"},"runId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Actor run ID to fetch. Example: \\"HG7ML7M8z78YcAPEB\\""}},"hostedApiKey":"none"},"apify_run_actor_async":{"id":"apify_run_actor_async","name":"APIFY Run Actor (Async)","description":"Run an APIFY actor asynchronously with polling for long-running tasks","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"APIFY API token from console.apify.com/account#/integrations"},"actorId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Actor ID or username/actor-name. Examples: \\"apify/web-scraper\\", \\"janedoe/my-actor\\", \\"moJRLRc85AitArpNN\\""},"input":{"type":"string","required":false,"visibility":"user-or-llm","description":"Actor input as JSON string. Example: { \\"startUrls\\": [ { \\"url\\": \\"https://example.com\\" } ], \\"maxPages\\": 10 }"},"waitForFinish":{"type":"number","required":false,"visibility":"user-or-llm","description":"Initial wait time in seconds (0-60) before polling starts. Example: 30"},"itemLimit":{"type":"number","required":false,"default":100,"visibility":"user-or-llm","description":"Max dataset items to fetch (1-250000). Default: 100. Example: 500"},"memory":{"type":"number","required":false,"visibility":"user-or-llm","description":"Memory in megabytes allocated for the actor run (128-32768). Example: 1024 for 1GB, 2048 for 2GB"},"timeout":{"type":"number","required":false,"visibility":"user-or-llm","description":"Timeout in seconds for the actor run. Example: 300 for 5 minutes, 3600 for 1 hour"},"build":{"type":"string","required":false,"visibility":"user-or-llm","description":"Actor build to run. Examples: \\"latest\\", \\"beta\\", \\"1.2.3\\", \\"build-tag-name\\""}},"hostedApiKey":"none"},"apify_run_actor_sync":{"id":"apify_run_actor_sync","name":"APIFY Run Actor (Sync)","description":"Run an APIFY actor synchronously and get results (max 5 minutes)","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"APIFY API token from console.apify.com/account#/integrations"},"actorId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Actor ID or username/actor-name. Examples: \\"apify/web-scraper\\", \\"janedoe/my-actor\\", \\"moJRLRc85AitArpNN\\""},"input":{"type":"string","required":false,"visibility":"user-or-llm","description":"Actor input as JSON string. Example: { \\"startUrls\\": [ { \\"url\\": \\"https://example.com\\" } ], \\"maxPages\\": 10 }"},"memory":{"type":"number","required":false,"visibility":"user-or-llm","description":"Memory in megabytes allocated for the actor run (128-32768). Example: 1024 for 1GB, 2048 for 2GB"},"timeout":{"type":"number","required":false,"visibility":"user-or-llm","description":"Timeout in seconds for the actor run. Example: 300 for 5 minutes, 3600 for 1 hour"},"build":{"type":"string","required":false,"visibility":"user-or-llm","description":"Actor build to run. Examples: \\"latest\\", \\"beta\\", \\"1.2.3\\", \\"build-tag-name\\""}},"hostedApiKey":"none"},"apify_run_task":{"id":"apify_run_task","name":"APIFY Run Task","description":"Run a saved APIFY actor task synchronously and get dataset items (max 5 minutes)","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"APIFY API token from console.apify.com/account#/integrations"},"taskId":{"type":"string","required":true,"visibility":"user-or-llm","description":"Task ID or username/task-name. Examples: \\"janedoe/my-task\\", \\"moJRLRc85AitArpNN\\""},"input":{"type":"string","required":false,"visibility":"user-or-llm","description":"JSON string that overrides the task\'s saved input. Example: { \\"startUrls\\": [ { \\"url\\": \\"https://example.com\\" } ] }"},"itemLimit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Max dataset items to return (1-250000). Example: 500"},"memory":{"type":"number","required":false,"visibility":"user-or-llm","description":"Memory in megabytes allocated for the run (128-32768). Example: 1024 for 1GB"},"timeout":{"type":"number","required":false,"visibility":"user-or-llm","description":"Timeout in seconds for the run. Example: 300 for 5 minutes"},"build":{"type":"string","required":false,"visibility":"user-or-llm","description":"Actor build to run. Examples: \\"latest\\", \\"beta\\", \\"1.2.3\\""}},"hostedApiKey":"none"},"apollo_account_bulk_create":{"id":"apollo_account_bulk_create","name":"Apollo Bulk Create Accounts","description":"Create up to 100 accounts at once in your Apollo database. Set run_dedupe=true to deduplicate by domain, organization_id, and name. Master key required.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key (master key required)"},"accounts":{"type":"array","required":true,"visibility":"user-or-llm","description":"Array of accounts to create (max 100). Each account should include a name, and may optionally include domain, phone, phone_status_cd, raw_address, owner_id, linkedin_url, facebook_url, twitter_url, salesforce_id, and hubspot_id."},"append_label_names":{"type":"array","required":false,"visibility":"user-only","description":"Array of label names to add to ALL accounts in this request"},"run_dedupe":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"When true, performs aggressive deduplication by domain, organization_id, and name (defaults to false)"}},"hostedApiKey":"none"},"apollo_account_bulk_update":{"id":"apollo_account_bulk_update","name":"Apollo Bulk Update Accounts","description":"Update up to 1000 existing accounts at once in your Apollo database (higher limit than contacts!). Each account must include an id field. Master key required.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key (master key required)"},"account_ids":{"type":"array","required":false,"visibility":"user-or-llm","description":"Array of account IDs to update with the same values (max 1000). Use with name/owner_id for uniform updates. Use either this OR account_attributes."},"name":{"type":"string","required":false,"visibility":"user-or-llm","description":"When using account_ids, apply this name to all accounts"},"owner_id":{"type":"string","required":false,"visibility":"user-or-llm","description":"When using account_ids, apply this owner to all accounts"},"account_stage_id":{"type":"string","required":false,"visibility":"user-or-llm","description":"When using account_ids, apply this account stage to all accounts"},"account_attributes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Array of account objects with individual updates (each must include id). Example: [{\\"id\\": \\"acc1\\", \\"name\\": \\"Acme\\", \\"owner_id\\": \\"u1\\", \\"account_stage_id\\": \\"s1\\", \\"typed_custom_fields\\": {\\"field_id\\": \\"value\\"}}]"},"async":{"type":"boolean","required":false,"visibility":"user-only","description":"When true, processes the update asynchronously. Only supported when using account_ids; returns 422 if used with account_attributes."}},"hostedApiKey":"none"},"apollo_account_create":{"id":"apollo_account_create","name":"Apollo Create Account","description":"Create a new account (company) in your Apollo database","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key (master key required)"},"name":{"type":"string","required":true,"visibility":"user-or-llm","description":"Company name (e.g., \\"Acme Corporation\\")"},"domain":{"type":"string","required":false,"visibility":"user-or-llm","description":"Company domain without www. prefix (e.g., \\"acme.com\\")"},"phone":{"type":"string","required":false,"visibility":"user-or-llm","description":"Primary phone number for the account"},"owner_id":{"type":"string","required":false,"visibility":"user-only","description":"Apollo user ID of the account owner"},"account_stage_id":{"type":"string","required":false,"visibility":"user-only","description":"Apollo ID for the account stage to assign this account to"},"raw_address":{"type":"string","required":false,"visibility":"user-or-llm","description":"Corporate location (e.g., \\"San Francisco, CA, USA\\")"},"typed_custom_fields":{"type":"json","required":false,"visibility":"user-only","description":"Custom field values as { custom_field_id: value } map"}},"hostedApiKey":"none"},"apollo_account_search":{"id":"apollo_account_search","name":"Apollo Search Accounts","description":"Search your team\'s accounts in Apollo. Display limit: 50,000 records (100 records per page, 500 pages max). Use filters to narrow results. Master key required.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key (master key required)"},"q_organization_name":{"type":"string","required":false,"visibility":"user-or-llm","description":"Filter accounts by organization name (partial-match search)"},"account_stage_ids":{"type":"array","required":false,"visibility":"user-only","description":"Filter by account stage IDs"},"account_label_ids":{"type":"array","required":false,"visibility":"user-only","description":"Filter by account label IDs"},"sort_by_field":{"type":"string","required":false,"visibility":"user-or-llm","description":"Sort field: \\"account_last_activity_date\\", \\"account_created_at\\", or \\"account_updated_at\\""},"sort_ascending":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Sort ascending when true. Defaults to descending."},"page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Page number for pagination (e.g., 1, 2, 3)"},"per_page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Results per page, max 100 (e.g., 25, 50, 100)"}},"hostedApiKey":"none"},"apollo_account_update":{"id":"apollo_account_update","name":"Apollo Update Account","description":"Update an existing account in your Apollo database","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key"},"account_id":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the account to update (e.g., \\"acc_abc123\\")"},"name":{"type":"string","required":false,"visibility":"user-or-llm","description":"Company name (e.g., \\"Acme Corporation\\")"},"domain":{"type":"string","required":false,"visibility":"user-or-llm","description":"Company domain (e.g., \\"acme.com\\")"},"phone":{"type":"string","required":false,"visibility":"user-or-llm","description":"Company phone number"},"owner_id":{"type":"string","required":false,"visibility":"user-only","description":"Apollo user ID of the account owner"},"account_stage_id":{"type":"string","required":false,"visibility":"user-only","description":"Apollo ID for the account stage to assign this account to"},"raw_address":{"type":"string","required":false,"visibility":"user-or-llm","description":"Corporate location (e.g., \\"San Francisco, CA, USA\\")"},"typed_custom_fields":{"type":"json","required":false,"visibility":"user-only","description":"Custom field values as { custom_field_id: value } map"}},"hostedApiKey":"none"},"apollo_contact_bulk_create":{"id":"apollo_contact_bulk_create","name":"Apollo Bulk Create Contacts","description":"Create up to 100 contacts at once in your Apollo database. Supports deduplication to prevent creating duplicate contacts. Master key required.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key (master key required)"},"contacts":{"type":"array","required":true,"visibility":"user-or-llm","description":"Array of contacts to create (max 100). Each contact may include first_name, last_name, email, title, organization_name, account_id, owner_id, contact_stage_id, linkedin_url, phone (single string) or phone_numbers (array of {raw_number, position}), contact_emails, typed_custom_fields, and CRM IDs (salesforce_contact_id, hubspot_id, team_id) for cross-system matching"},"append_label_names":{"type":"array","required":false,"visibility":"user-or-llm","description":"Label names to add to all contacts in this request (e.g., [\\"Hot Lead\\"])"},"run_dedupe":{"type":"boolean","required":false,"visibility":"user-only","description":"Enable deduplication to prevent creating duplicate contacts. When true, existing contacts are returned without modification"}},"hostedApiKey":"none"},"apollo_contact_bulk_update":{"id":"apollo_contact_bulk_update","name":"Apollo Bulk Update Contacts","description":"Update up to 100 existing contacts at once in your Apollo database. Each contact must include an id field. Master key required.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key (master key required)"},"contact_ids":{"type":"array","required":false,"visibility":"user-or-llm","description":"Array of contact IDs to update. Must be paired with an object-form contact_attributes specifying the fields to apply uniformly to all listed contacts."},"contact_attributes":{"type":"json","required":false,"visibility":"user-or-llm","description":"Required. Either an array of per-contact updates (each with id) — used standalone — or a single object of attributes to apply to all contact_ids. Supported fields: owner_id, email, organization_name, title, first_name, last_name, account_id, present_raw_address, linkedin_url, typed_custom_fields"},"async":{"type":"boolean","required":false,"visibility":"user-only","description":"Force asynchronous processing. Automatically enabled for >100 contacts"}},"hostedApiKey":"none"},"apollo_contact_create":{"id":"apollo_contact_create","name":"Apollo Create Contact","description":"Create a new contact in your Apollo database","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key"},"first_name":{"type":"string","required":true,"visibility":"user-or-llm","description":"First name of the contact"},"last_name":{"type":"string","required":true,"visibility":"user-or-llm","description":"Last name of the contact"},"email":{"type":"string","required":false,"visibility":"user-or-llm","description":"Email address of the contact"},"title":{"type":"string","required":false,"visibility":"user-or-llm","description":"Job title (e.g., \\"VP of Sales\\", \\"Software Engineer\\")"},"account_id":{"type":"string","required":false,"visibility":"user-or-llm","description":"Apollo account ID to associate with (e.g., \\"acc_abc123\\")"},"owner_id":{"type":"string","required":false,"visibility":"user-only","description":"User ID of the contact owner (accepted by Apollo but not officially documented for POST /contacts)"},"organization_name":{"type":"string","required":false,"visibility":"user-or-llm","description":"Name of the contact\'s employer (e.g., \\"Apollo\\")"},"website_url":{"type":"string","required":false,"visibility":"user-or-llm","description":"Corporate website URL (e.g., \\"https://www.apollo.io/\\")"},"label_names":{"type":"array","required":false,"visibility":"user-or-llm","description":"Lists/labels to add the contact to (e.g., [\\"Prospects\\"])"},"contact_stage_id":{"type":"string","required":false,"visibility":"user-or-llm","description":"Apollo ID for the contact stage"},"present_raw_address":{"type":"string","required":false,"visibility":"user-or-llm","description":"Personal location for the contact (e.g., \\"Atlanta, United States\\")"},"direct_phone":{"type":"string","required":false,"visibility":"user-or-llm","description":"Primary phone number"},"corporate_phone":{"type":"string","required":false,"visibility":"user-or-llm","description":"Work/office phone number"},"mobile_phone":{"type":"string","required":false,"visibility":"user-or-llm","description":"Mobile phone number"},"home_phone":{"type":"string","required":false,"visibility":"user-or-llm","description":"Home phone number"},"other_phone":{"type":"string","required":false,"visibility":"user-or-llm","description":"Alternative phone number"},"typed_custom_fields":{"type":"json","required":false,"visibility":"user-or-llm","description":"Custom field values keyed by custom field ID"},"run_dedupe":{"type":"boolean","required":false,"visibility":"user-only","description":"When true, Apollo deduplicates against existing contacts"}},"hostedApiKey":"none"},"apollo_contact_search":{"id":"apollo_contact_search","name":"Apollo Search Contacts","description":"Search your team\'s contacts in Apollo","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key"},"q_keywords":{"type":"string","required":false,"visibility":"user-or-llm","description":"Keywords to search for"},"contact_stage_ids":{"type":"array","required":false,"visibility":"user-only","description":"Filter by contact stage IDs"},"contact_label_ids":{"type":"array","required":false,"visibility":"user-only","description":"Filter by Apollo label IDs (lists)"},"sort_by_field":{"type":"string","required":false,"visibility":"user-only","description":"Sort field: contact_last_activity_date, contact_email_last_opened_at, contact_email_last_clicked_at, contact_created_at, or contact_updated_at"},"sort_ascending":{"type":"boolean","required":false,"visibility":"user-only","description":"When true, sort ascending. Must be used together with sort_by_field"},"page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Page number for pagination (e.g., 1, 2, 3)"},"per_page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Results per page, max 100 (e.g., 25, 50, 100)"}},"hostedApiKey":"none"},"apollo_contact_update":{"id":"apollo_contact_update","name":"Apollo Update Contact","description":"Update an existing contact in your Apollo database","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key"},"contact_id":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the contact to update (e.g., \\"con_abc123\\")"},"first_name":{"type":"string","required":false,"visibility":"user-or-llm","description":"First name of the contact"},"last_name":{"type":"string","required":false,"visibility":"user-or-llm","description":"Last name of the contact"},"email":{"type":"string","required":false,"visibility":"user-or-llm","description":"Email address"},"title":{"type":"string","required":false,"visibility":"user-or-llm","description":"Job title (e.g., \\"VP of Sales\\", \\"Software Engineer\\")"},"account_id":{"type":"string","required":false,"visibility":"user-or-llm","description":"Apollo account ID (e.g., \\"acc_abc123\\")"},"owner_id":{"type":"string","required":false,"visibility":"user-only","description":"User ID of the contact owner (accepted by Apollo but not officially documented for PATCH /contacts/{id})"},"organization_name":{"type":"string","required":false,"visibility":"user-or-llm","description":"Name of the contact\'s employer (e.g., \\"Apollo\\")"},"website_url":{"type":"string","required":false,"visibility":"user-or-llm","description":"Corporate website URL (e.g., \\"https://www.apollo.io/\\")"},"label_names":{"type":"array","required":false,"visibility":"user-or-llm","description":"Lists/labels to add the contact to (e.g., [\\"Prospects\\"])"},"contact_stage_id":{"type":"string","required":false,"visibility":"user-or-llm","description":"Apollo ID for the contact stage"},"present_raw_address":{"type":"string","required":false,"visibility":"user-or-llm","description":"Personal location for the contact (e.g., \\"Atlanta, United States\\")"},"direct_phone":{"type":"string","required":false,"visibility":"user-or-llm","description":"Primary phone number"},"corporate_phone":{"type":"string","required":false,"visibility":"user-or-llm","description":"Work/office phone number"},"mobile_phone":{"type":"string","required":false,"visibility":"user-or-llm","description":"Mobile phone number"},"home_phone":{"type":"string","required":false,"visibility":"user-or-llm","description":"Home phone number"},"other_phone":{"type":"string","required":false,"visibility":"user-or-llm","description":"Alternative phone number"},"typed_custom_fields":{"type":"json","required":false,"visibility":"user-or-llm","description":"Custom field values keyed by custom field ID"}},"hostedApiKey":"none"},"apollo_email_accounts":{"id":"apollo_email_accounts","name":"Apollo Get Email Accounts","description":"Get list of team\'s linked email accounts in Apollo","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key (master key required)"}},"hostedApiKey":"none"},"apollo_opportunity_create":{"id":"apollo_opportunity_create","name":"Apollo Create Opportunity","description":"Create a new deal for an account in your Apollo database (master key required)","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key (master key required)"},"name":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the opportunity/deal (e.g., \\"Enterprise License - Q1\\")"},"account_id":{"type":"string","required":false,"visibility":"user-or-llm","description":"ID of the account this opportunity belongs to (e.g., \\"acc_abc123\\")"},"amount":{"type":"string","required":false,"visibility":"user-or-llm","description":"Monetary value as a plain number string with no commas or currency symbols"},"opportunity_stage_id":{"type":"string","required":false,"visibility":"user-only","description":"ID of the opportunity stage"},"owner_id":{"type":"string","required":false,"visibility":"user-only","description":"User ID of the opportunity owner"},"closed_date":{"type":"string","required":false,"visibility":"user-or-llm","description":"Expected close date in YYYY-MM-DD format"},"typed_custom_fields":{"type":"json","required":false,"visibility":"user-only","description":"Custom field values as { custom_field_id: value } map"}},"hostedApiKey":"none"},"apollo_opportunity_get":{"id":"apollo_opportunity_get","name":"Apollo Get Opportunity","description":"Retrieve complete details of a specific deal/opportunity by ID","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key"},"opportunity_id":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the opportunity to retrieve (e.g., \\"opp_abc123\\")"}},"hostedApiKey":"none"},"apollo_opportunity_search":{"id":"apollo_opportunity_search","name":"Apollo Search Opportunities","description":"Search and list all deals/opportunities in your team\'s Apollo account","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key"},"sort_by_field":{"type":"string","required":false,"visibility":"user-or-llm","description":"Sort field: \\"amount\\", \\"is_closed\\", or \\"is_won\\""},"page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Page number for pagination (e.g., 1, 2, 3)"},"per_page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Results per page, max 100 (e.g., 25, 50, 100)"}},"hostedApiKey":"none"},"apollo_opportunity_update":{"id":"apollo_opportunity_update","name":"Apollo Update Opportunity","description":"Update an existing deal/opportunity in your Apollo database","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key"},"opportunity_id":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the opportunity to update (e.g., \\"opp_abc123\\")"},"name":{"type":"string","required":false,"visibility":"user-or-llm","description":"Name of the opportunity/deal (e.g., \\"Enterprise License - Q1\\")"},"amount":{"type":"string","required":false,"visibility":"user-or-llm","description":"Monetary value as a plain number string with no commas or currency symbols"},"opportunity_stage_id":{"type":"string","required":false,"visibility":"user-only","description":"ID of the opportunity stage"},"owner_id":{"type":"string","required":false,"visibility":"user-only","description":"User ID of the opportunity owner"},"closed_date":{"type":"string","required":false,"visibility":"user-or-llm","description":"Expected close date in YYYY-MM-DD format"},"typed_custom_fields":{"type":"json","required":false,"visibility":"user-only","description":"Custom field values as { custom_field_id: value } map"}},"hostedApiKey":"none"},"apollo_organization_bulk_enrich":{"id":"apollo_organization_bulk_enrich","name":"Apollo Bulk Organization Enrichment","description":"Enrich data for up to 10 organizations at once using Apollo","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key"},"domains":{"type":"array","required":true,"visibility":"user-or-llm","description":"Array of company domains to enrich (max 10, no www. or @, e.g., [\\"apollo.io\\", \\"stripe.com\\"])"}},"hostedApiKey":"none"},"apollo_organization_enrich":{"id":"apollo_organization_enrich","name":"Apollo Organization Enrichment","description":"Enrich data for a single organization using Apollo","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key"},"domain":{"type":"string","required":true,"visibility":"user-or-llm","description":"Company domain (e.g., \\"apollo.io\\", \\"acme.com\\")"}},"hostedApiKey":"none"},"apollo_organization_search":{"id":"apollo_organization_search","name":"Apollo Organization Search","description":"Search Apollo\'s database for companies using filters","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key"},"organization_locations":{"type":"array","required":false,"visibility":"user-or-llm","description":"Company HQ locations (cities, US states, or countries)"},"organization_not_locations":{"type":"array","required":false,"visibility":"user-or-llm","description":"Exclude companies whose HQ is in these locations"},"organization_num_employees_ranges":{"type":"array","required":false,"visibility":"user-or-llm","description":"Employee count ranges as \\"min,max\\" strings (e.g., [\\"1,10\\", \\"250,500\\", \\"10000,20000\\"])"},"q_organization_keyword_tags":{"type":"array","required":false,"visibility":"user-or-llm","description":"Industry or keyword tags"},"q_organization_name":{"type":"string","required":false,"visibility":"user-or-llm","description":"Organization name to search for (e.g., \\"Acme\\", \\"TechCorp\\")"},"organization_ids":{"type":"array","required":false,"visibility":"user-or-llm","description":"Apollo organization IDs to include (e.g., [\\"5e66b6381e05b4008c8331b8\\"])"},"q_organization_domains_list":{"type":"array","required":false,"visibility":"user-or-llm","description":"Domain names to filter by (no www. or @, up to 1,000)"},"page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Page number for pagination (e.g., 1, 2, 3)"},"per_page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Results per page, max 100 (e.g., 25, 50, 100)"}},"hostedApiKey":"none"},"apollo_people_bulk_enrich":{"id":"apollo_people_bulk_enrich","name":"Apollo Bulk People Enrichment","description":"Enrich data for up to 10 people at once using Apollo","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key"},"people":{"type":"array","required":true,"visibility":"user-or-llm","description":"Array of people to enrich (max 10)"},"reveal_personal_emails":{"type":"boolean","required":false,"visibility":"user-only","description":"Reveal personal email addresses (uses credits)"},"reveal_phone_number":{"type":"boolean","required":false,"visibility":"user-only","description":"Reveal phone numbers (uses credits, requires webhook_url)"},"webhook_url":{"type":"string","required":false,"visibility":"user-only","description":"Webhook URL for async phone number delivery (required when reveal_phone_number is true)"}},"hostedApiKey":"none"},"apollo_people_enrich":{"id":"apollo_people_enrich","name":"Apollo People Enrichment","description":"Enrich data for a single person using Apollo","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key"},"first_name":{"type":"string","required":false,"visibility":"user-or-llm","description":"First name of the person"},"last_name":{"type":"string","required":false,"visibility":"user-or-llm","description":"Last name of the person"},"name":{"type":"string","required":false,"visibility":"user-or-llm","description":"Full name of the person (alternative to first_name/last_name)"},"id":{"type":"string","required":false,"visibility":"user-or-llm","description":"Apollo ID for the person"},"hashed_email":{"type":"string","required":false,"visibility":"user-or-llm","description":"MD5 or SHA-256 hashed email"},"email":{"type":"string","required":false,"visibility":"user-or-llm","description":"Email address of the person"},"organization_name":{"type":"string","required":false,"visibility":"user-or-llm","description":"Company name where the person works"},"domain":{"type":"string","required":false,"visibility":"user-or-llm","description":"Company domain (e.g., \\"apollo.io\\", \\"acme.com\\")"},"linkedin_url":{"type":"string","required":false,"visibility":"user-or-llm","description":"LinkedIn profile URL"},"reveal_personal_emails":{"type":"boolean","required":false,"visibility":"user-only","description":"Reveal personal email addresses (uses credits)"},"reveal_phone_number":{"type":"boolean","required":false,"visibility":"user-only","description":"Reveal phone numbers (uses credits, requires webhook_url)"},"webhook_url":{"type":"string","required":false,"visibility":"user-only","description":"Webhook URL for async phone number delivery (required when reveal_phone_number is true)"}},"hostedApiKey":"none"},"apollo_people_search":{"id":"apollo_people_search","name":"Apollo People Search","description":"Search Apollo\'s database for people using demographic filters","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key"},"person_titles":{"type":"array","required":false,"visibility":"user-or-llm","description":"Job titles to search for (e.g., [\\"CEO\\", \\"VP of Sales\\"])"},"include_similar_titles":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Whether to return people with job titles similar to person_titles"},"person_locations":{"type":"array","required":false,"visibility":"user-or-llm","description":"Locations to search in (e.g., [\\"San Francisco, CA\\", \\"New York, NY\\"])"},"person_seniorities":{"type":"array","required":false,"visibility":"user-or-llm","description":"Seniority levels (one of: owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern)"},"organization_ids":{"type":"array","required":false,"visibility":"user-or-llm","description":"Apollo organization IDs to filter by (e.g., [\\"5e66b6381e05b4008c8331b8\\"])"},"organization_names":{"type":"array","required":false,"visibility":"user-or-llm","description":"Company names to search within (legacy filter)"},"organization_locations":{"type":"array","required":false,"visibility":"user-or-llm","description":"Headquarters locations of the people\'s current employer (e.g., [\'texas\', \'tokyo\', \'spain\'])"},"q_organization_domains_list":{"type":"array","required":false,"visibility":"user-or-llm","description":"Employer domain names (e.g., [\\"apollo.io\\", \\"microsoft.com\\"]) — up to 1,000, no www. or @"},"organization_num_employees_ranges":{"type":"array","required":false,"visibility":"user-or-llm","description":"Employee count ranges for the person\'s current employer. Each entry is \\"min,max\\" (e.g., [\\"1,10\\", \\"250,500\\", \\"10000,20000\\"])"},"contact_email_status":{"type":"array","required":false,"visibility":"user-or-llm","description":"Email statuses to filter by: \\"verified\\", \\"unverified\\", \\"likely to engage\\", \\"unavailable\\""},"q_keywords":{"type":"string","required":false,"visibility":"user-or-llm","description":"Keywords to search for"},"page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Page number for pagination, default 1 (e.g., 1, 2, 3)"},"per_page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Results per page, default 25, max 100 (e.g., 25, 50, 100)"}},"hostedApiKey":"none"},"apollo_sequence_add_contacts":{"id":"apollo_sequence_add_contacts","name":"Apollo Add Contacts to Sequence","description":"Add contacts to an Apollo sequence","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key (master key required)"},"sequence_id":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the sequence to add contacts to (e.g., \\"seq_abc123\\")"},"contact_ids":{"type":"array","required":false,"visibility":"user-or-llm","description":"Array of contact IDs to add to the sequence (e.g., [\\"con_abc123\\", \\"con_def456\\"]). Either contact_ids or label_names must be provided."},"label_names":{"type":"array","required":false,"visibility":"user-or-llm","description":"Array of label names to identify contacts to add to the sequence. Either contact_ids or label_names must be provided."},"send_email_from_email_account_id":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the email account to send from. Use the Get Email Accounts operation to look this up."},"send_email_from_email_address":{"type":"string","required":false,"visibility":"user-only","description":"Specific email address to send from within the email account."},"sequence_no_email":{"type":"boolean","required":false,"visibility":"user-only","description":"Add contacts even if they have no email address"},"sequence_unverified_email":{"type":"boolean","required":false,"visibility":"user-only","description":"Add contacts with unverified email addresses"},"sequence_job_change":{"type":"boolean","required":false,"visibility":"user-only","description":"Add contacts who recently changed jobs"},"sequence_active_in_other_campaigns":{"type":"boolean","required":false,"visibility":"user-only","description":"Add contacts active in other campaigns"},"sequence_finished_in_other_campaigns":{"type":"boolean","required":false,"visibility":"user-only","description":"Add contacts who finished other campaigns"},"sequence_same_company_in_same_campaign":{"type":"boolean","required":false,"visibility":"user-only","description":"Add contacts even if others from the same company are in the sequence"},"contacts_without_ownership_permission":{"type":"boolean","required":false,"visibility":"user-only","description":"Add contacts without ownership permission"},"add_if_in_queue":{"type":"boolean","required":false,"visibility":"user-only","description":"Add contacts even if they are in the queue"},"contact_verification_skipped":{"type":"boolean","required":false,"visibility":"user-only","description":"Skip contact verification when adding"},"user_id":{"type":"string","required":false,"visibility":"user-only","description":"ID of the user performing the action"},"status":{"type":"string","required":false,"visibility":"user-only","description":"Initial status for added contacts: \\"active\\" or \\"paused\\""},"auto_unpause_at":{"type":"string","required":false,"visibility":"user-only","description":"ISO 8601 datetime to automatically unpause contacts"}},"hostedApiKey":"none"},"apollo_sequence_search":{"id":"apollo_sequence_search","name":"Apollo Search Sequences","description":"Search for sequences/campaigns in your team\'s Apollo account (master key required)","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key (master key required)"},"q_name":{"type":"string","required":false,"visibility":"user-or-llm","description":"Search sequences by name (e.g., \\"Outbound Q1\\", \\"Follow-up\\")"},"page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Page number for pagination (e.g., 1, 2, 3)"},"per_page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Results per page, max 100 (e.g., 25, 50, 100)"}},"hostedApiKey":"none"},"apollo_task_create":{"id":"apollo_task_create","name":"Apollo Create Task","description":"Create one or more tasks in Apollo (one task per contact_id, master key required)","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key (master key required)"},"user_id":{"type":"string","required":true,"visibility":"user-or-llm","description":"ID of the Apollo user the task is assigned to"},"contact_ids":{"type":"array","required":true,"visibility":"user-or-llm","description":"Array of contact IDs. One task is created per contact."},"priority":{"type":"string","required":false,"visibility":"user-or-llm","description":"Task priority: \\"high\\", \\"medium\\", or \\"low\\" (defaults to \\"medium\\")"},"due_at":{"type":"string","required":true,"visibility":"user-or-llm","description":"Due date/time in ISO 8601 format (e.g., \\"2024-12-31T23:59:59Z\\")"},"type":{"type":"string","required":true,"visibility":"user-or-llm","description":"Task type: \\"call\\", \\"outreach_manual_email\\", \\"linkedin_step_connect\\", \\"linkedin_step_message\\", \\"linkedin_step_view_profile\\", \\"linkedin_step_interact_post\\", or \\"action_item\\""},"status":{"type":"string","required":true,"visibility":"user-or-llm","description":"Task status: \\"scheduled\\", \\"completed\\", or \\"skipped\\""},"note":{"type":"string","required":false,"visibility":"user-or-llm","description":"Free-form note providing context for the task"}},"hostedApiKey":"none"},"apollo_task_search":{"id":"apollo_task_search","name":"Apollo Search Tasks","description":"Search for tasks in Apollo","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Apollo API key (master key required)"},"sort_by_field":{"type":"string","required":false,"visibility":"user-or-llm","description":"Sort field: \\"task_due_at\\" or \\"task_priority\\""},"open_factor_names":{"type":"array","required":false,"visibility":"user-or-llm","description":"Filter by status. Common values: [\\"task_types\\"] for open tasks, [\\"task_completed_at\\"] for completed tasks."},"page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Page number for pagination (e.g., 1, 2, 3)"},"per_page":{"type":"number","required":false,"visibility":"user-or-llm","description":"Results per page, max 100 (e.g., 25, 50, 100)"}},"hostedApiKey":"none"},"appconfig_create_application":{"id":"appconfig_create_application","name":"AppConfig Create Application","description":"Create an application in AWS AppConfig","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"name":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the application to create"},"description":{"type":"string","required":false,"visibility":"user-or-llm","description":"Description of the application"}},"hostedApiKey":"none"},"appconfig_create_configuration_profile":{"id":"appconfig_create_configuration_profile","name":"AppConfig Create Configuration Profile","description":"Create a configuration profile in an AWS AppConfig application","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID to create the configuration profile in"},"name":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the configuration profile"},"locationUri":{"type":"string","required":true,"visibility":"user-or-llm","description":"Where the configuration is stored. Use \\"hosted\\" for AppConfig-hosted configurations, or an SSM/S3 URI"},"description":{"type":"string","required":false,"visibility":"user-or-llm","description":"Description of the configuration profile"},"retrievalRoleArn":{"type":"string","required":false,"visibility":"user-or-llm","description":"ARN of an IAM role to retrieve the configuration (required for non-hosted URIs)"},"type":{"type":"string","required":false,"visibility":"user-or-llm","description":"Profile type: AWS.Freeform (default) or AWS.AppConfig.FeatureFlags"}},"hostedApiKey":"none"},"appconfig_create_environment":{"id":"appconfig_create_environment","name":"AppConfig Create Environment","description":"Create an environment for an AWS AppConfig application","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID to create the environment in"},"name":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the environment to create"},"description":{"type":"string","required":false,"visibility":"user-or-llm","description":"Description of the environment"}},"hostedApiKey":"none"},"appconfig_create_hosted_configuration_version":{"id":"appconfig_create_hosted_configuration_version","name":"AppConfig Create Hosted Configuration Version","description":"Create a new hosted configuration version for an AppConfig configuration profile","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID that owns the configuration profile"},"configurationProfileId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The configuration profile ID to add the version to"},"content":{"type":"string","required":true,"visibility":"user-or-llm","description":"The configuration content (e.g., a JSON or YAML document)"},"contentType":{"type":"string","required":true,"visibility":"user-or-llm","description":"Content type of the configuration (e.g., application/json, text/plain)"},"description":{"type":"string","required":false,"visibility":"user-or-llm","description":"Description of the configuration version"},"latestVersionNumber":{"type":"number","required":false,"visibility":"user-or-llm","description":"The version number of the latest version, used for optimistic concurrency"},"versionLabel":{"type":"string","required":false,"visibility":"user-or-llm","description":"A user-defined label for the configuration version"}},"hostedApiKey":"none"},"appconfig_delete_application":{"id":"appconfig_delete_application","name":"AppConfig Delete Application","description":"Delete an AWS AppConfig application","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID to delete"}},"hostedApiKey":"none"},"appconfig_delete_configuration_profile":{"id":"appconfig_delete_configuration_profile","name":"AppConfig Delete Configuration Profile","description":"Delete an AWS AppConfig configuration profile","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID that owns the configuration profile"},"configurationProfileId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The configuration profile ID to delete"}},"hostedApiKey":"none"},"appconfig_delete_environment":{"id":"appconfig_delete_environment","name":"AppConfig Delete Environment","description":"Delete an AWS AppConfig environment","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID that owns the environment"},"environmentId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The environment ID to delete"}},"hostedApiKey":"none"},"appconfig_delete_hosted_configuration_version":{"id":"appconfig_delete_hosted_configuration_version","name":"AppConfig Delete Hosted Configuration Version","description":"Delete a specific hosted configuration version from an AppConfig profile","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID that owns the configuration profile"},"configurationProfileId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The configuration profile ID that owns the version"},"versionNumber":{"type":"number","required":true,"visibility":"user-or-llm","description":"The version number to delete"}},"hostedApiKey":"none"},"appconfig_get_application":{"id":"appconfig_get_application","name":"AppConfig Get Application","description":"Get details about a single AWS AppConfig application","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID to retrieve"}},"hostedApiKey":"none"},"appconfig_get_configuration":{"id":"appconfig_get_configuration","name":"AppConfig Get Configuration","description":"Retrieve the latest deployed configuration for an AppConfig application, environment, and profile","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID or name to retrieve configuration for"},"environmentId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The environment ID or name to retrieve configuration for"},"configurationProfileId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The configuration profile ID or name to retrieve"}},"hostedApiKey":"none"},"appconfig_get_configuration_profile":{"id":"appconfig_get_configuration_profile","name":"AppConfig Get Configuration Profile","description":"Get details about a single AWS AppConfig configuration profile","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID that owns the configuration profile"},"configurationProfileId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The configuration profile ID to retrieve"}},"hostedApiKey":"none"},"appconfig_get_deployment":{"id":"appconfig_get_deployment","name":"AppConfig Get Deployment","description":"Get details about a specific AWS AppConfig deployment","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID of the deployment"},"environmentId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The environment ID of the deployment"},"deploymentNumber":{"type":"number","required":true,"visibility":"user-or-llm","description":"The sequence number of the deployment"}},"hostedApiKey":"none"},"appconfig_get_environment":{"id":"appconfig_get_environment","name":"AppConfig Get Environment","description":"Get details about a single AWS AppConfig environment","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID that owns the environment"},"environmentId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The environment ID to retrieve"}},"hostedApiKey":"none"},"appconfig_get_hosted_configuration_version":{"id":"appconfig_get_hosted_configuration_version","name":"AppConfig Get Hosted Configuration Version","description":"Retrieve a specific hosted configuration version from an AppConfig profile","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID that owns the configuration profile"},"configurationProfileId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The configuration profile ID to read the version from"},"versionNumber":{"type":"number","required":true,"visibility":"user-or-llm","description":"The version number to retrieve"}},"hostedApiKey":"none"},"appconfig_list_applications":{"id":"appconfig_list_applications","name":"AppConfig List Applications","description":"List applications in AWS AppConfig","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"maxResults":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of applications to return (1-50)"},"nextToken":{"type":"string","required":false,"visibility":"user-or-llm","description":"Pagination token from a previous response"}},"hostedApiKey":"none"},"appconfig_list_configuration_profiles":{"id":"appconfig_list_configuration_profiles","name":"AppConfig List Configuration Profiles","description":"List configuration profiles for an AWS AppConfig application","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID that owns the configuration profiles"},"maxResults":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of configuration profiles to return (1-50)"},"nextToken":{"type":"string","required":false,"visibility":"user-or-llm","description":"Pagination token from a previous response"}},"hostedApiKey":"none"},"appconfig_list_deployment_strategies":{"id":"appconfig_list_deployment_strategies","name":"AppConfig List Deployment Strategies","description":"List deployment strategies available in AWS AppConfig","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"maxResults":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of deployment strategies to return (1-50)"},"nextToken":{"type":"string","required":false,"visibility":"user-or-llm","description":"Pagination token from a previous response"}},"hostedApiKey":"none"},"appconfig_list_deployments":{"id":"appconfig_list_deployments","name":"AppConfig List Deployments","description":"List deployments for an AWS AppConfig environment","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID of the deployments"},"environmentId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The environment ID of the deployments"},"maxResults":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of deployments to return (1-50)"},"nextToken":{"type":"string","required":false,"visibility":"user-or-llm","description":"Pagination token from a previous response"}},"hostedApiKey":"none"},"appconfig_list_environments":{"id":"appconfig_list_environments","name":"AppConfig List Environments","description":"List environments for an AWS AppConfig application","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID that owns the environments"},"maxResults":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of environments to return (1-50)"},"nextToken":{"type":"string","required":false,"visibility":"user-or-llm","description":"Pagination token from a previous response"}},"hostedApiKey":"none"},"appconfig_list_hosted_configuration_versions":{"id":"appconfig_list_hosted_configuration_versions","name":"AppConfig List Hosted Configuration Versions","description":"List hosted configuration versions for an AWS AppConfig configuration profile","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID that owns the configuration profile"},"configurationProfileId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The configuration profile ID to list versions for"},"maxResults":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of versions to return (1-50)"},"nextToken":{"type":"string","required":false,"visibility":"user-or-llm","description":"Pagination token from a previous response"}},"hostedApiKey":"none"},"appconfig_start_deployment":{"id":"appconfig_start_deployment","name":"AppConfig Start Deployment","description":"Start deploying a configuration version to an AWS AppConfig environment","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID to deploy in"},"environmentId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The environment ID to deploy to"},"deploymentStrategyId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The deployment strategy ID to use"},"configurationProfileId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The configuration profile ID to deploy"},"configurationVersion":{"type":"string","required":true,"visibility":"user-or-llm","description":"The configuration version to deploy"},"description":{"type":"string","required":false,"visibility":"user-or-llm","description":"Description of the deployment"}},"hostedApiKey":"none"},"appconfig_stop_deployment":{"id":"appconfig_stop_deployment","name":"AppConfig Stop Deployment","description":"Stop an in-progress AWS AppConfig deployment","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID of the deployment"},"environmentId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The environment ID of the deployment"},"deploymentNumber":{"type":"number","required":true,"visibility":"user-or-llm","description":"The sequence number of the deployment to stop"}},"hostedApiKey":"none"},"appconfig_update_application":{"id":"appconfig_update_application","name":"AppConfig Update Application","description":"Update the name or description of an AWS AppConfig application","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID to update"},"name":{"type":"string","required":false,"visibility":"user-or-llm","description":"New name for the application"},"description":{"type":"string","required":false,"visibility":"user-or-llm","description":"New description for the application"}},"hostedApiKey":"none"},"appconfig_update_configuration_profile":{"id":"appconfig_update_configuration_profile","name":"AppConfig Update Configuration Profile","description":"Update the name, description, or retrieval role of an AppConfig configuration profile","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID that owns the configuration profile"},"configurationProfileId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The configuration profile ID to update"},"name":{"type":"string","required":false,"visibility":"user-or-llm","description":"New name for the configuration profile"},"description":{"type":"string","required":false,"visibility":"user-or-llm","description":"New description for the configuration profile"},"retrievalRoleArn":{"type":"string","required":false,"visibility":"user-or-llm","description":"New ARN of the IAM role used to retrieve the configuration"}},"hostedApiKey":"none"},"appconfig_update_environment":{"id":"appconfig_update_environment","name":"AppConfig Update Environment","description":"Update the name or description of an AWS AppConfig environment","version":"1.0","params":{"region":{"type":"string","required":true,"visibility":"user-only","description":"AWS region (e.g., us-east-1)"},"accessKeyId":{"type":"string","required":true,"visibility":"user-only","description":"AWS access key ID"},"secretAccessKey":{"type":"string","required":true,"visibility":"user-only","description":"AWS secret access key"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The application ID that owns the environment"},"environmentId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The environment ID to update"},"name":{"type":"string","required":false,"visibility":"user-or-llm","description":"New name for the environment"},"description":{"type":"string","required":false,"visibility":"user-or-llm","description":"New description for the environment"}},"hostedApiKey":"none"},"arxiv_get_author_papers":{"id":"arxiv_get_author_papers","name":"ArXiv Get Author Papers","description":"Search for papers by a specific author on ArXiv.","version":"1.0.0","params":{"authorName":{"type":"string","required":true,"visibility":"user-or-llm","description":"Author name to search for"},"maxResults":{"type":"number","required":false,"visibility":"user-only","description":"Maximum number of results to return (default: 10, max: 2000)"}},"hostedApiKey":"none"},"arxiv_get_paper":{"id":"arxiv_get_paper","name":"ArXiv Get Paper","description":"Get detailed information about a specific ArXiv paper by its ID.","version":"1.0.0","params":{"paperId":{"type":"string","required":true,"visibility":"user-or-llm","description":"ArXiv paper ID (e.g., \\"1706.03762\\")"}},"hostedApiKey":"none"},"arxiv_search":{"id":"arxiv_search","name":"ArXiv Search","description":"Search for academic papers on ArXiv by keywords, authors, titles, or other fields.","version":"1.0.0","params":{"searchQuery":{"type":"string","required":true,"visibility":"user-or-llm","description":"The search query to execute"},"searchField":{"type":"string","required":false,"visibility":"user-only","description":"Field to search in: all, ti (title), au (author), abs (abstract), co (comment), jr (journal), cat (category), rn (report number)"},"maxResults":{"type":"number","required":false,"visibility":"user-only","description":"Maximum number of results to return (default: 10, max: 2000)"},"sortBy":{"type":"string","required":false,"visibility":"user-only","description":"Sort by: relevance, lastUpdatedDate, submittedDate (default: relevance)"},"sortOrder":{"type":"string","required":false,"visibility":"user-only","description":"Sort order: ascending, descending (default: descending)"}},"hostedApiKey":"none"},"asana_add_comment":{"id":"asana_add_comment","name":"Asana Add Comment","description":"Add a comment (story) to an Asana task","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"},"taskGid":{"type":"string","required":true,"visibility":"user-or-llm","description":"Asana task GID (numeric string)"},"text":{"type":"string","required":true,"visibility":"user-or-llm","description":"The text content of the comment"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"asana_add_followers":{"id":"asana_add_followers","name":"Asana Add Followers","description":"Add one or more followers to an Asana task","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"},"taskGid":{"type":"string","required":true,"visibility":"user-or-llm","description":"GID of the Asana task (numeric string)"},"followers":{"type":"array","required":true,"visibility":"user-or-llm","description":"Array of user GIDs to add as followers to the task"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"asana_create_project":{"id":"asana_create_project","name":"Asana Create Project","description":"Create a new project in an Asana workspace","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"},"workspace":{"type":"string","required":true,"visibility":"user-or-llm","description":"Asana workspace GID (numeric string) where the project will be created"},"name":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the project"},"notes":{"type":"string","required":false,"visibility":"user-or-llm","description":"Notes or description for the project"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"asana_create_section":{"id":"asana_create_section","name":"Asana Create Section","description":"Create a new section in an Asana project","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"},"projectGid":{"type":"string","required":true,"visibility":"user-or-llm","description":"GID of the Asana project (numeric string) to add the section to"},"name":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the section"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"asana_create_subtask":{"id":"asana_create_subtask","name":"Asana Create Subtask","description":"Create a subtask under an existing Asana task","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"},"taskGid":{"type":"string","required":true,"visibility":"user-or-llm","description":"GID of the parent Asana task (numeric string)"},"name":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the subtask"},"notes":{"type":"string","required":false,"visibility":"user-or-llm","description":"Notes or description for the subtask"},"assignee":{"type":"string","required":false,"visibility":"user-or-llm","description":"User GID to assign the subtask to"},"due_on":{"type":"string","required":false,"visibility":"user-or-llm","description":"Due date in YYYY-MM-DD format"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"asana_create_task":{"id":"asana_create_task","name":"Asana Create Task","description":"Create a new task in Asana","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"},"workspace":{"type":"string","required":true,"visibility":"user-or-llm","description":"Asana workspace GID (numeric string) where the task will be created"},"name":{"type":"string","required":true,"visibility":"user-or-llm","description":"Name of the task"},"notes":{"type":"string","required":false,"visibility":"user-or-llm","description":"Notes or description for the task"},"assignee":{"type":"string","required":false,"visibility":"user-or-llm","description":"User GID to assign the task to"},"due_on":{"type":"string","required":false,"visibility":"user-or-llm","description":"Due date in YYYY-MM-DD format"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"asana_delete_task":{"id":"asana_delete_task","name":"Asana Delete Task","description":"Delete an Asana task by its GID (moves it to the trash)","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"},"taskGid":{"type":"string","required":true,"visibility":"user-or-llm","description":"GID of the Asana task to delete (numeric string)"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"asana_get_project":{"id":"asana_get_project","name":"Asana Get Project","description":"Retrieve a single Asana project by its GID","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"},"projectGid":{"type":"string","required":true,"visibility":"user-or-llm","description":"Asana project GID (numeric string) to retrieve"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"asana_get_projects":{"id":"asana_get_projects","name":"Asana Get Projects","description":"Retrieve all projects from an Asana workspace","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"},"workspace":{"type":"string","required":true,"visibility":"user-or-llm","description":"Asana workspace GID (numeric string) to retrieve projects from"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"asana_get_task":{"id":"asana_get_task","name":"Asana Get Task","description":"Retrieve a single task by GID or get multiple tasks with filters","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"},"taskGid":{"type":"string","required":false,"visibility":"user-or-llm","description":"The globally unique identifier (GID) of the task. If not provided, will get multiple tasks."},"workspace":{"type":"string","required":false,"visibility":"user-or-llm","description":"Asana workspace GID (numeric string) to filter tasks (required when not using taskGid)"},"project":{"type":"string","required":false,"visibility":"user-or-llm","description":"Asana project GID (numeric string) to filter tasks"},"limit":{"type":"number","required":false,"visibility":"user-or-llm","description":"Maximum number of tasks to return (default: 50)"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"asana_list_sections":{"id":"asana_list_sections","name":"Asana List Sections","description":"List all sections in an Asana project","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"},"projectGid":{"type":"string","required":true,"visibility":"user-or-llm","description":"GID of the Asana project (numeric string) to list sections from"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"asana_list_workspaces":{"id":"asana_list_workspaces","name":"Asana List Workspaces","description":"List all Asana workspaces and organizations the authenticated user belongs to","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"asana_search_tasks":{"id":"asana_search_tasks","name":"Asana Search Tasks","description":"Search for tasks in an Asana workspace","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"},"workspace":{"type":"string","required":true,"visibility":"user-or-llm","description":"Asana workspace GID (numeric string) to search tasks in"},"text":{"type":"string","required":false,"visibility":"user-or-llm","description":"Text to search for in task names"},"assignee":{"type":"string","required":false,"visibility":"user-or-llm","description":"Filter tasks by assignee user GID"},"projects":{"type":"array","required":false,"visibility":"user-or-llm","description":"Array of Asana project GIDs (numeric strings) to filter tasks by"},"completed":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Filter by completion status"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"asana_update_task":{"id":"asana_update_task","name":"Asana Update Task","description":"Update an existing task in Asana","version":"1.0.0","params":{"accessToken":{"type":"string","required":true,"visibility":"hidden","description":"OAuth access token for Asana"},"taskGid":{"type":"string","required":true,"visibility":"user-or-llm","description":"Asana task GID (numeric string) of the task to update"},"name":{"type":"string","required":false,"visibility":"user-or-llm","description":"Updated name for the task"},"notes":{"type":"string","required":false,"visibility":"user-or-llm","description":"Updated notes or description for the task"},"assignee":{"type":"string","required":false,"visibility":"user-or-llm","description":"Updated assignee user GID"},"completed":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Mark task as completed or not completed"},"due_on":{"type":"string","required":false,"visibility":"user-or-llm","description":"Updated due date in YYYY-MM-DD format"}},"oauth":{"required":true,"provider":"asana"},"hostedApiKey":"none"},"ashby_add_candidate_tag":{"id":"ashby_add_candidate_tag","name":"Ashby Add Candidate Tag","description":"Adds a tag to a candidate in Ashby and returns the updated candidate.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ashby API Key"},"onBehalfOfUserId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Active Ashby user UUID to attribute this mutation to; the API key must permit on-behalf-of calls"},"candidateId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The UUID of the candidate to add the tag to"},"tagId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The UUID of the tag to add"}},"hostedApiKey":"none"},"ashby_anonymize_candidate":{"id":"ashby_anonymize_candidate","name":"Ashby Anonymize Candidate","description":"Strips personally identifiable information from a candidate in Ashby. This does not delete the candidate - the record and its applications remain, with the PII removed. Ashby exposes no candidate deletion endpoint; true deletion is UI-only, restricted by role, and limited to a 10-day window. Requires the candidatesWrite permission.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ashby API Key"},"onBehalfOfUserId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Active Ashby user UUID to attribute this mutation to; the API key must permit on-behalf-of calls"},"candidateId":{"type":"string","required":true,"visibility":"user-or-llm","description":"UUID of the candidate to anonymize"}},"hostedApiKey":"none"},"ashby_change_application_source":{"id":"ashby_change_application_source","name":"Ashby Change Application Source","description":"Changes the source attributed to an existing application, so programmatically created applications report correctly on the recruiting side. Requires the candidatesWrite permission.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ashby API Key"},"onBehalfOfUserId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Active Ashby user UUID to attribute this mutation to; the API key must permit on-behalf-of calls"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"UUID of the application whose source should change"},"sourceId":{"type":"string","required":false,"visibility":"user-or-llm","description":"UUID of the source to attribute the application to, as returned by List Sources. Omit only when unsetSource is true."},"unsetSource":{"type":"boolean","required":false,"visibility":"user-or-llm","description":"Set true to deliberately clear the application source. Required to unset, so that a missing or empty sourceId cannot wipe attribution by accident."}},"hostedApiKey":"none"},"ashby_change_application_stage":{"id":"ashby_change_application_stage","name":"Ashby Change Application Stage","description":"Moves an application to a different interview stage. Requires an archive reason when moving to an Archived stage.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ashby API Key"},"onBehalfOfUserId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Active Ashby user UUID to attribute this mutation to; the API key must permit on-behalf-of calls"},"applicationId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The UUID of the application to update the stage of"},"interviewStageId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The UUID of the interview stage to move the application to"},"archiveReasonId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Archive reason UUID. Required when moving to an Archived stage, ignored otherwise"},"archiveEmail":{"type":"json","required":false,"visibility":"user-or-llm","description":"Archive email configuration with communicationTemplateId and optional sendAt ISO 8601 timestamp. Pass null or omit to send no archive email."}},"hostedApiKey":"none"},"ashby_create_application":{"id":"ashby_create_application","name":"Ashby Create Application","description":"Creates a new application for a candidate on a job. Optionally specify interview plan, stage, source, and credited user.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ashby API Key"},"onBehalfOfUserId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Active Ashby user UUID to attribute this mutation to; the API key must permit on-behalf-of calls"},"candidateId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The UUID of the candidate to consider for the job"},"jobId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The UUID of the job to consider the candidate for"},"interviewPlanId":{"type":"string","required":false,"visibility":"user-or-llm","description":"UUID of the interview plan to use (defaults to the job default plan)"},"interviewStageId":{"type":"string","required":false,"visibility":"user-or-llm","description":"UUID of the interview stage to place the application in, or FirstPreInterviewScreen (defaults to the first Lead stage)"},"sourceId":{"type":"string","required":false,"visibility":"user-or-llm","description":"UUID of the source to set on the application"},"creditedToUserId":{"type":"string","required":false,"visibility":"user-or-llm","description":"UUID of the user the application is credited to"},"createdAt":{"type":"string","required":false,"visibility":"user-or-llm","description":"ISO 8601 timestamp to set as the application creation date (defaults to now)"},"applicationHistory":{"type":"json","required":false,"visibility":"user-or-llm","description":"Optional documented application history entries to create with the application"}},"hostedApiKey":"none"},"ashby_create_candidate":{"id":"ashby_create_candidate","name":"Ashby Create Candidate","description":"Creates a new candidate record in Ashby.","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ashby API Key"},"onBehalfOfUserId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Active Ashby user UUID to attribute this mutation to; the API key must permit on-behalf-of calls"},"name":{"type":"string","required":true,"visibility":"user-or-llm","description":"The candidate full name"},"email":{"type":"string","required":false,"visibility":"user-or-llm","description":"Primary email address for the candidate"},"phoneNumber":{"type":"string","required":false,"visibility":"user-or-llm","description":"Primary phone number for the candidate"},"linkedInUrl":{"type":"string","required":false,"visibility":"user-or-llm","description":"LinkedIn profile URL"},"githubUrl":{"type":"string","required":false,"visibility":"user-or-llm","description":"GitHub profile URL"},"website":{"type":"string","required":false,"visibility":"user-or-llm","description":"Personal website URL"},"sourceId":{"type":"string","required":false,"visibility":"user-or-llm","description":"UUID of the source to attribute the candidate to"},"creditedToUserId":{"type":"string","required":false,"visibility":"user-or-llm","description":"UUID of the Ashby user to credit with sourcing this candidate"},"createdAt":{"type":"string","required":false,"visibility":"user-or-llm","description":"Backdated creation timestamp in ISO 8601 (e.g. 2024-01-01T00:00:00Z). Defaults to now."},"alternateEmailAddresses":{"type":"json","required":false,"visibility":"user-or-llm","description":"Array of additional email address strings to add to the candidate, e.g. [\\"a@x.com\\",\\"b@y.com\\"]"},"location":{"type":"json","required":false,"visibility":"user-or-llm","description":"Candidate location object with optional city, region, and country"}},"hostedApiKey":"none"},"ashby_create_note":{"id":"ashby_create_note","name":"Ashby Create Note","description":"Creates a note on a candidate in Ashby. Supports plain text and HTML content (bold, italic, underline, links, lists, code).","version":"1.0.0","params":{"apiKey":{"type":"string","required":true,"visibility":"user-only","description":"Ashby API Key"},"onBehalfOfUserId":{"type":"string","required":false,"visibility":"user-or-llm","description":"Active Ashby user UUID to attribute this mutation to; the API key must permit on-behalf-of calls"},"candidateId":{"type":"string","required":true,"visibility":"user-or-llm","description":"The UUID of the candidate to add the note to"},"note":{"type":"string","required":true,"visibility":"user-or-llm","description":"The note content. If noteType is text/html, supports: , , , ,