diff --git a/apps/docs/content/docs/integrations/file.mdx b/apps/docs/content/docs/integrations/file.mdx index 4222a602a7d..4bf764fcb8a 100644 --- a/apps/docs/content/docs/integrations/file.mdx +++ b/apps/docs/content/docs/integrations/file.mdx @@ -87,15 +87,16 @@ Fetch and parse a file from a URL with optional custom headers. ### File Write -Create a new workspace file. If a file with the same name already exists, a numeric suffix is added (e.g., "data (1).csv"). +Create a new workspace file, either from text content or from an existing file. If a file with the same name already exists, a numeric suffix is added (e.g., "data (1).csv"). #### Input | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `fileName` | string | Yes | File name \(e.g., "data.csv"\). If a file with this name exists, a numeric suffix is added automatically. | -| `content` | string | Yes | The text content to write to the file. | -| `contentType` | string | No | MIME type for new files \(e.g., "text/plain"\). Auto-detected from file extension if omitted. | +| `fileName` | string | No | File name \(e.g., "data.csv"\). Required when writing text; optional when storing a file, which keeps its own name unless this overrides it. If the name already exists, a numeric suffix is added automatically. | +| `content` | string | No | The text content to write to the file. Provide exactly one of content or fileInput. | +| `fileInput` | file | No | An existing file to store in the workspace, such as one produced by an earlier tool. Use this for anything that is not text — PDFs, images, audio, archives. Provide exactly one of content or fileInput. | +| `contentType` | string | No | MIME type for new files \(e.g., "text/plain"\). Auto-detected from the file extension, or taken from the stored file, if omitted. | #### Output diff --git a/apps/docs/content/docs/workflows/blocks/function.mdx b/apps/docs/content/docs/workflows/blocks/function.mdx index 2b130f2ad7b..b79425b698e 100644 --- a/apps/docs/content/docs/workflows/blocks/function.mdx +++ b/apps/docs/content/docs/workflows/blocks/function.mdx @@ -102,6 +102,49 @@ Sim supplies the rendered heredoc privately while preserving the quoted delimite | --- | --- | | `` | The value your code returns (object, array, string, number, …) | | `` | Anything printed with `console.log()` or `print()` | +| `` | Files your code wrote to `/tmp/sim/outputs`, ready to attach or upload | + +## Files + +**Reading.** Reference a file's `path` and it is mounted for you: + +```python +import pandas as pd + +frame = pd.read_csv() +frame.describe().to_csv('/tmp/sim/outputs/summary.csv') +``` + +`.path` resolves to the file's location on the sandbox filesystem, so any language +can open it — pandas, ffmpeg, a CLI. It is the counterpart to `.base64`, which +inlines the contents instead and works only in JavaScript. Both appear in the +reference dropdown next to `.name` and `.size`. + +**Writing.** Anything your code writes to `/tmp/sim/outputs` comes back as +``, a list of file objects any file-accepting block takes directly — +attach them to an email, upload them to storage, or save them to the workspace with +the File block. There is nothing to turn on. + +The one exception is a call that names an explicit `outputSandboxPath`. That asks +for particular paths to be exported and answers with that export's own result, so +the output directory is not harvested alongside it — choose one or the other rather +than expecting both in the same run. + + +Referencing `.path` runs the block in the remote sandbox, since the local +JavaScript VM has no filesystem — expect the slower start of a remote run even for +plain JavaScript. Referencing the file itself (``, `.name`, +`.url`) does not, and stays local. Up to 20 files come back per run, 50MB total, +nested no more than 11 directories deep; a run that exceeds any of these fails +rather than returning part of what your code wrote. + + + +Returned files live with the execution rather than in your workspace, and a text +file containing a resolved secret value is refused rather than returned — there is +nowhere on an execution file to record that it carries one. Write such a file to a +workspace path instead, or keep the secret out of the output. + ## Language @@ -401,8 +444,8 @@ The lazy `sim.files` and `sim.values` helpers are available only in JavaScript f { question: "What languages does the Function block support?", answer: "JavaScript, Python, and Shell. JavaScript is the default. Python remains a stable saved language choice; Shell and custom Sandbox controls appear when a remote sandbox provider is enabled. Python and Shell execution require that provider." }, { question: "When does code run locally vs. in a sandbox?", answer: "JavaScript without external imports runs in a local isolated sandbox for speed. JavaScript that uses import or require, Python, and Shell run in the configured remote sandbox." }, { question: "Does JavaScript still work without E2B or Daytona?", answer: "Yes. JavaScript without import or require runs in Sim's local isolated VM and does not require a remote provider. JavaScript with external imports, Python, Shell, and custom Sandboxes require E2B or Daytona and fail explicitly when it is unavailable." }, - { question: "How do I reference outputs from other blocks inside my code?", answer: "Use angle-bracket syntax directly, like or , with no quotes around the tag — Sim replaces it with the real value before execution. For environment variables, use double curly braces: {{API_KEY}}." }, - { question: "What does the Function block return?", answer: "Two outputs: result and stdout. Use return in JavaScript, assign __sim_result__ in Python, or print an __SIM_RESULT__= marker in Shell to set result. Ordinary console, print, and command output goes to stdout." }, + { question: "How do I reference outputs from other blocks inside my code?", answer: "Use angle-bracket syntax directly, like or , with no quotes around the tag — Sim replaces it with the real value before execution. For environment variables, use double curly braces: {{API_KEY}}. To read a file, reference its path — mounts it and resolves to a location any language can open." }, + { question: "What does the Function block return?", answer: "Three outputs: result, stdout, and files. Use return in JavaScript, assign __sim_result__ in Python, or print an __SIM_RESULT__= marker in Shell to set result. Ordinary console, print, and command output goes to stdout. Anything your code writes to /tmp/sim/outputs comes back in files as a file object later blocks can accept directly." }, { question: "Can I make HTTP requests from a Function block?", answer: "Yes. fetch() is available in JavaScript with async/await. In Python, use requests or httpx. In Shell, use curl or a CLI available on the selected sandbox." }, { question: "Is there a timeout for Function block execution?", answer: "Yes, a configurable execution timeout. If your code exceeds it, the run is terminated and the block reports an error. Keep this in mind for external calls or heavy processing." }, ]} /> diff --git a/apps/sim/blocks/blocks/file.ts b/apps/sim/blocks/blocks/file.ts index e566a746dbd..66a47212f8e 100644 --- a/apps/sim/blocks/blocks/file.ts +++ b/apps/sim/blocks/blocks/file.ts @@ -80,6 +80,9 @@ const APPEND_FILE_FIELD = ['appendFile', 'appendFileName'] as const const COMPRESS_FILE_FIELD = ['compressFile', 'compressFileId'] as const const DECOMPRESS_FILE_FIELD = ['decompressFile', 'decompressFileId'] as const const SHARE_FILE_FIELD = ['shareFile', 'shareFileId'] as const +/* Text and file are mutually exclusive sources, so the clause names whichever + one the card actually carries. */ +const WRITE_CONTENT_FIELD = ['content', 'writeFile', 'writeFileId'] as const export const FileBlock: BlockConfig = { type: 'file', @@ -921,7 +924,7 @@ export const FileV5Block: BlockConfig = { file_fetch: [{ text: 'Fetch and parse', field: 'fileUrl', core: true }], file_write: [ { text: 'Create', field: 'fileName', core: true }, - { text: 'containing', field: 'content' }, + { text: 'containing', field: WRITE_CONTENT_FIELD }, ], file_append: [ { text: 'Append', field: 'appendContent', core: true }, @@ -1031,7 +1034,25 @@ export const FileV5Block: BlockConfig = { type: 'long-input' as SubBlockType, placeholder: 'File content to write...', condition: { field: 'operation', value: 'file_write' }, - required: { field: 'operation', value: 'file_write' }, + }, + { + id: 'writeFile', + title: 'File', + type: 'file-upload' as SubBlockType, + canonicalParamId: 'writeFileInput', + acceptedTypes: '*', + placeholder: 'Store an existing file', + mode: 'basic', + condition: { field: 'operation', value: 'file_write' }, + }, + { + id: 'writeFileId', + title: 'File', + type: 'short-input' as SubBlockType, + canonicalParamId: 'writeFileInput', + placeholder: 'File from an earlier block', + mode: 'advanced', + condition: { field: 'operation', value: 'file_write' }, }, { id: 'contentType', @@ -1206,9 +1227,22 @@ export const FileV5Block: BlockConfig = { const operation = params.operation || 'file_read' if (operation === 'file_write') { + // Writing stores one file, so the single form. + const fileInput = normalizeFileInput(params.writeFileInput, { single: true }) + // The contract counts any defined `content` as "text was provided", and + // an untouched Content box serializes as an empty string — so sending it + // unconditionally would make every file write collide with its own empty + // text box. The selected file is what disambiguates: with one present, + // an empty Content box means "not used" and is dropped, while a + // non-empty one is still forwarded so the contract can report that both + // were filled. With no file, `content` always goes through, which keeps + // writing a deliberately empty text file possible. + const contentText = typeof params.content === 'string' ? params.content : undefined + const omitContent = Boolean(fileInput) && !contentText return { fileName: params.fileName, - content: params.content, + ...(omitContent ? {} : { content: params.content }), + ...(fileInput ? { fileInput } : {}), contentType: params.contentType, workspaceId: params._context?.workspaceId, } @@ -1432,6 +1466,10 @@ export const FileV5Block: BlockConfig = { fileType: { type: 'string', description: 'File type for fetch' }, fileName: { type: 'string', description: 'Name for a new file (write)' }, content: { type: 'string', description: 'File content to write' }, + writeFileInput: { + type: 'json', + description: 'An existing file to store in the workspace, instead of text content', + }, contentType: { type: 'string', description: 'MIME content type for write' }, appendFileInput: { type: 'json', description: 'File to append to' }, appendContent: { type: 'string', description: 'Content to append to file' }, diff --git a/apps/sim/blocks/blocks/function.test.ts b/apps/sim/blocks/blocks/function.test.ts new file mode 100644 index 00000000000..96cc313d258 --- /dev/null +++ b/apps/sim/blocks/blocks/function.test.ts @@ -0,0 +1,33 @@ +/** + * @vitest-environment node + */ +import { describe, expect, it } from 'vitest' +import { USER_FILE_ACCESSIBLE_PROPERTIES } from '@/lib/workflows/types' +import { FunctionBlock } from '@/blocks/blocks/function' + +describe('Function block file surface', () => { + it('has no file configuration fields', () => { + // Files reach the sandbox by being referenced in code as + // — the same way every other block output is referenced. + // A dedicated field would be a second way to say the same thing, and would + // need a home in the panel that the reference syntax does not. + const ids = FunctionBlock.subBlocks.map((subBlock) => subBlock.id) + + expect(ids).not.toContain('files') + expect(ids).not.toContain('uploadedFiles') + expect(ids).not.toContain('collectOutputFiles') + expect(FunctionBlock.inputs).not.toHaveProperty('files') + expect(FunctionBlock.inputs).not.toHaveProperty('collectOutputFiles') + }) + + it('returns harvested files so downstream blocks can consume them', () => { + expect(FunctionBlock.outputs.files).toMatchObject({ type: 'file[]' }) + }) + + it('offers path alongside base64 as a referenceable file property', () => { + // This is what puts `.path` in the tag dropdown: block-outputs.ts maps the + // list into `${path}.${prop}` suggestions. + expect(USER_FILE_ACCESSIBLE_PROPERTIES).toContain('path') + expect(USER_FILE_ACCESSIBLE_PROPERTIES).toContain('base64') + }) +}) diff --git a/apps/sim/blocks/blocks/function.ts b/apps/sim/blocks/blocks/function.ts index 930d7c233dd..ebf685b687c 100644 --- a/apps/sim/blocks/blocks/function.ts +++ b/apps/sim/blocks/blocks/function.ts @@ -1,6 +1,7 @@ import { CodeIcon } from '@/components/icons' import { isSandboxesEnabled } from '@/lib/core/config/env-flags' import { CodeLanguage, getLanguageDisplayName } from '@/lib/execution/languages' +import { SANDBOX_OUTPUT_DIR } from '@/lib/execution/remote-sandbox/sandbox-paths' import type { BlockConfig } from '@/blocks/types' import type { CodeExecutionOutput } from '@/tools/function/types' @@ -17,6 +18,9 @@ export const FunctionBlock: BlockConfig = { - Shell code runs CLI commands in a remote sandbox. - To import third-party packages or add curated CLI tools, create a sandbox in Settings > Sandboxes and select it under the block's advanced options. Without one, only the default image's packages and commands are available. - Can reference workflow variables using syntax as usual within code. Avoid XML/HTML tags. + - To read a file from an earlier block, reference its path: mounts the file and resolves to its location on the sandbox filesystem, which any language can open. Use instead when you only want the contents inline in JavaScript. + - Anything the code writes to ${SANDBOX_OUTPUT_DIR} is returned as \`files\`, ready to attach to an email or upload without any extra step. + - Referencing a file path runs the block in the remote sandbox, so it is slower to start than a plain local JavaScript run. `, docsLink: 'https://docs.sim.ai/workflows/blocks/function', category: 'blocks', @@ -174,5 +178,9 @@ try { type: 'string', description: 'Console log output and debug messages from function execution', }, + files: { + type: 'file[]', + description: `Files the code wrote to ${SANDBOX_OUTPUT_DIR}, ready to attach or upload downstream`, + }, }, } diff --git a/apps/sim/executor/types.ts b/apps/sim/executor/types.ts index 649398ed616..8aa9e7cd6ce 100644 --- a/apps/sim/executor/types.ts +++ b/apps/sim/executor/types.ts @@ -403,6 +403,21 @@ export interface ExecutionContext { */ toolBindingLabelCache?: Map + /** + * Files produced during this execution, indexed by {@link UserFile.id}, so a + * model can name one by id in a tool argument and the runtime can hydrate it + * into the full object. + * + * Needed because a file an agent has just seen — a Gmail attachment fetched + * moments ago in the same turn — lives only in that turn's tool results, not + * in any block state or workspace row, so nothing else can resolve it. The + * index only *selects*; every read is still authorized on its own. + * + * A Map for the same reason as {@link toolBindingLabelCache}: `blockCtx` is a + * shallow clone per block execution, so only a shared reference survives. + */ + executionFilesById?: Map + blockStates: ReadonlyMap executedBlocks: ReadonlySet diff --git a/apps/sim/executor/variables/resolver.ts b/apps/sim/executor/variables/resolver.ts index f5e50e2d50a..cc7838bcf2d 100644 --- a/apps/sim/executor/variables/resolver.ts +++ b/apps/sim/executor/variables/resolver.ts @@ -10,10 +10,14 @@ import { isLargeValueRef, type LargeValueRef, } from '@/lib/execution/payloads/large-value-ref' +import { + createSandboxFileMountRef, + isSandboxFileMountRef, +} from '@/lib/execution/payloads/sandbox-file-mount-ref' import { isLikelyReferenceSegment } from '@/lib/workflows/sanitization/references' import { BlockType, parseReferencePath, REFERENCE } from '@/executor/constants' import type { ExecutionState, LoopScope } from '@/executor/execution/state' -import type { ExecutionContext } from '@/executor/types' +import type { ExecutionContext, UserFile } from '@/executor/types' import { createEnvVarPattern, createReferencePattern } from '@/executor/utils/reference-validation' import { BlockResolver } from '@/executor/variables/resolvers/block' import { EnvResolver } from '@/executor/variables/resolvers/env' @@ -453,6 +457,19 @@ export class VariableResolver { displayCursor = index + match.length try { + const sandboxFilePath = await this.resolveSandboxFilePathReference( + match, + resolutionContext, + language, + template, + index, + contextVarAccumulator + ) + if (sandboxFilePath) { + displayResult += sandboxFilePath.display + return sandboxFilePath.replacement + } + const lazyBase64 = await this.resolveLazyFileBase64Reference( match, resolutionContext, @@ -648,6 +665,106 @@ export class VariableResolver { return { resolvedCode: result, displayCode: displayResult } } + /** + * Resolves `` to the file's location on the sandbox filesystem. + * + * The counterpart to the `base64` reference above, and deliberately unlike it in + * two ways. It is not gated on the JavaScript runtime helpers, because a path is + * just a string and Python and Shell need it more than JavaScript does. And it + * stores a mount marker rather than the path itself: the sandbox does not exist + * yet at resolution time, and paths are assigned only once the whole mount set is + * known, since they are sanitized and de-duplicated together. + */ + private async resolveSandboxFilePathReference( + reference: string, + context: ResolutionContext, + language: string | undefined, + template: string, + matchIndex: number, + contextVarAccumulator: Record + ): Promise<{ replacement: string; display: string } | null> { + const parts = parseReferencePath(reference) + if (parts.length < 3 || parts.at(-1) !== 'path') { + return null + } + + const fileReference = `${REFERENCE.START}${parts.slice(0, -1).join(REFERENCE.PATH_DELIMITER)}${REFERENCE.END}` + const file = await this.resolveReference(fileReference, context) + if (!isUserFileWithMetadata(file) || !file.key) { + return null + } + + // Reuse an existing marker for the same file so referencing one path twice + // mounts it once, rather than transferring a second copy under a + // collision-suffixed name and spending the mount budget twice. + const existing = Object.entries(contextVarAccumulator).find( + ([, value]) => isSandboxFileMountRef(value) && value.file.key === file.key + ) + const varName = existing?.[0] ?? `__blockRef_${Object.keys(contextVarAccumulator).length}` + if (!existing) { + // The bytes are fetched into the sandbox, so the inline copy would be dead + // weight in the request body. + const { base64: _base64, ...fileMetadata } = file + contextVarAccumulator[varName] = createSandboxFileMountRef(fileMetadata as UserFile) + } + + return { + replacement: this.formatContextVariablePathReference(varName, language, template, matchIndex), + display: reference, + } + } + + /** + * Formats a mount-path reference for splicing into code. + * + * Unlike {@link formatContextVariableReference}, a path inside a quoted string is + * spliced raw rather than JSON-encoded. The general formatter is right to encode + * an arbitrary value — the author of `""` wants its JSON form — but + * a path is always a plain string, so encoding it would put literal quote + * characters inside the string the code then opens, turning `open('')` + * into a lookup for a filename that begins with `"`. + * + * Splicing raw is safe precisely here: mount paths are built segment by segment + * through `buildStorageKeySegment`, which reduces anything outside + * `[A-Za-z0-9.-]` to `_`, so the value cannot carry a quote, backslash, backtick, + * or `$` that would escape the surrounding literal. + * + * Shell is delegated unchanged — its formatter already closes and reopens a + * single-quoted context around a double-quoted expansion, which expands + * correctly and needs no path-specific case. + */ + private formatContextVariablePathReference( + varName: string, + language: string | undefined, + template: string, + matchIndex: number + ): string { + if (language === 'shell') { + return this.formatShellContextVariableReference(varName, template, matchIndex, '') + } + + const quoteContext = this.getCodeStringQuoteContext(template, matchIndex, language) + + if (language === 'python') { + const expression = `globals()[${JSON.stringify(varName)}]` + if (this.isPythonStringQuoteContext(quoteContext)) { + const quote = this.getCodeStringQuoteToken(quoteContext) + return `${quote} + ${expression} + ${quote}` + } + return expression + } + + const expression = `globalThis[${JSON.stringify(varName)}]` + if (quoteContext === 'template') { + return `\${${expression}}` + } + if (quoteContext === 'single' || quoteContext === 'double') { + const quote = this.getCodeStringQuoteToken(quoteContext) + return `${quote} + ${expression} + ${quote}` + } + return expression + } + private async resolveLazyFileBase64Reference( reference: string, context: ResolutionContext, diff --git a/apps/sim/lib/api/contracts/hotspots.ts b/apps/sim/lib/api/contracts/hotspots.ts index e030d94f9b0..95a40b983b9 100644 --- a/apps/sim/lib/api/contracts/hotspots.ts +++ b/apps/sim/lib/api/contracts/hotspots.ts @@ -4,10 +4,12 @@ import { privateSecretProvenanceBundleSchema, stringRecordSchema, unknownRecordSchema, + userFileSchema, } from '@/lib/api/contracts/primitives' import { defineRouteContract } from '@/lib/api/contracts/types' import { DEFAULT_CODE_LANGUAGE } from '@/lib/execution/languages' import { PRIVATE_SECRET_PROVENANCE_FIELD } from '@/lib/execution/private-tool-metadata' +import { MAX_BLOCK_MOUNTED_FILES } from '@/lib/execution/remote-sandbox/sandbox-paths' import { MAX_PII_VALIDATION_DETECTED_ENTITIES, MAX_PII_VALIDATION_TEXT_CHARACTERS, @@ -183,6 +185,19 @@ export const functionExecuteBodySchema = z }) .strict() .optional(), + /** + * Platform file objects mounted into the sandbox before the code runs. + * Distinct from `inputs.files`, which names workspace VFS paths: these are + * the same objects tools exchange, so an upstream block's output can be + * mounted without first being written to the workspace. + */ + files: z + .array(userFileSchema) + .max( + MAX_BLOCK_MOUNTED_FILES, + `At most ${MAX_BLOCK_MOUNTED_FILES} files can be mounted into the sandbox` + ) + .optional(), outputs: z .object({ files: z.array(functionOutputFileSchema).optional(), diff --git a/apps/sim/lib/api/contracts/tools/file.ts b/apps/sim/lib/api/contracts/tools/file.ts index e38343dc0d9..3fd81cd1045 100644 --- a/apps/sim/lib/api/contracts/tools/file.ts +++ b/apps/sim/lib/api/contracts/tools/file.ts @@ -10,14 +10,41 @@ export const fileManageQuerySchema = z.object({ workspaceId: z.string().min(1).nullable().optional(), }) -export const fileManageWriteBodySchema = z.object({ - operation: z.literal('write'), - workspaceId: z.string().min(1).optional(), - fileName: z.string({ error: 'fileName is required for write operation' }).min(1), - content: z.string({ error: 'content is required for write operation' }), - contentType: z.string().optional(), - [PRIVATE_SECRET_PROVENANCE_FIELD]: privateSecretProvenanceBundleSchema.optional(), -}) +export const fileManageWriteBodySchema = z + .object({ + operation: z.literal('write'), + workspaceId: z.string().min(1).optional(), + fileName: z.string().min(1).optional(), + content: z.string().optional(), + /** + * An existing file object to store as-is, for content that is not text — + * a rendered PDF, a transcoded video, an image from an earlier tool. + */ + fileInput: z.unknown().optional(), + contentType: z.string().optional(), + [PRIVATE_SECRET_PROVENANCE_FIELD]: privateSecretProvenanceBundleSchema.optional(), + }) + .superRefine((body, context) => { + const hasContent = body.content !== undefined + const hasFileInput = body.fileInput !== undefined && body.fileInput !== null + if (hasContent === hasFileInput) { + context.addIssue({ + code: z.ZodIssueCode.custom, + path: ['content'], + message: + 'Provide exactly one of content (text to write) or fileInput (an existing file to store).', + }) + } + // A file object carries its own name, so fileName is the optional override + // there but the only source of a name when writing text. + if (hasContent && !body.fileName?.trim()) { + context.addIssue({ + code: z.ZodIssueCode.custom, + path: ['fileName'], + message: 'fileName is required when writing text content.', + }) + } + }) export const fileManageAppendBodySchema = z.object({ operation: z.literal('append'), diff --git a/apps/sim/lib/copilot/tools/handlers/function-execute.test.ts b/apps/sim/lib/copilot/tools/handlers/function-execute.test.ts index c9893ad2b58..694e5f44f38 100644 --- a/apps/sim/lib/copilot/tools/handlers/function-execute.test.ts +++ b/apps/sim/lib/copilot/tools/handlers/function-execute.test.ts @@ -119,6 +119,7 @@ vi.mock('@/lib/execution/remote-sandbox/workspace-sandboxes', () => ({ import { projectToolResultForCopilot } from '@/lib/copilot/request/tools/resolved-secret-result' import { executeFunctionExecute } from '@/lib/copilot/tools/handlers/function-execute' import { executeRunCode } from '@/lib/copilot/tools/handlers/run-code' +import { SNAPSHOT_MAX_BYTES } from '@/lib/table/snapshot-cache' import { ResolvedSecretTraceRegistry } from '@/executor/utils/resolved-secret-trace-registry' const table = { @@ -595,6 +596,8 @@ describe('executeFunctionExecute table mounts', () => { type: 'url', path: '/home/user/tables/tbl_1.csv', url: 'https://s3.example/presigned?sig=abc', + // The snapshot's own ceiling, enforced on the bytes the sandbox pulls. + maxBytes: SNAPSHOT_MAX_BYTES, }) }) @@ -764,6 +767,9 @@ describe('executeFunctionExecute file mounts', () => { type: 'url', path: '/home/user/files/data.csv', url: 'https://s3.example/file?sig=abc', + // Copilot's URL mounts share the transport, so each is granted exactly + // the size it was charged against the aggregate. + maxBytes: 100, }) }) @@ -1025,6 +1031,9 @@ describe('executeFunctionExecute file mounts', () => { type: 'url', path: '/home/user/files/Reports/q1.csv', url: 'https://s3.example/file?sig=abc', + // Copilot's URL mounts share the transport, so each is granted exactly + // the size it was charged against the aggregate. + maxBytes: 100, }) }) diff --git a/apps/sim/lib/copilot/tools/handlers/function-execute.ts b/apps/sim/lib/copilot/tools/handlers/function-execute.ts index 9f619b0677e..31f5cb917dd 100644 --- a/apps/sim/lib/copilot/tools/handlers/function-execute.ts +++ b/apps/sim/lib/copilot/tools/handlers/function-execute.ts @@ -17,7 +17,17 @@ import { MOUNTED_WORKSPACE_FILES_PROVENANCE_KEY, PRIVATE_SECRET_PROVENANCE_FIELD, } from '@/lib/execution/private-tool-metadata' +import type { SandboxFile } from '@/lib/execution/remote-sandbox/types' import { MAX_PLAN_REQUIRED } from '@/lib/execution/remote-sandbox/workspace-sandboxes' +import { + createSandboxMountBudget, + MAX_INLINE_MOUNT_FILE_BYTES, + MAX_INLINE_MOUNT_TOTAL_BYTES, + MAX_TOTAL_URL_BYTES, + MOUNT_URL_TTL_SECONDS, + pushSandboxFileMount, + type SandboxMountBudget, +} from '@/lib/function-execution/sandbox-mounts' import { recordSecretUsage } from '@/lib/secrets/usage/record' import { getTableSnapshotModelMountSafety } from '@/lib/table/rows/secret-provenance' import { getTableById, listTables } from '@/lib/table/service' @@ -49,47 +59,10 @@ import { executeTool as executeAppTool } from '@/tools' const logger = createLogger('CopilotFunctionExecute') -const MAX_FILE_SIZE = 10 * 1024 * 1024 -const MAX_TOTAL_SIZE = 50 * 1024 * 1024 +const MAX_FILE_SIZE = MAX_INLINE_MOUNT_FILE_BYTES +const MAX_TOTAL_SIZE = MAX_INLINE_MOUNT_TOTAL_BYTES const MAX_MOUNTED_FILES = 500 -/** - * Lifetime of a presigned URL handed to the sandbox to fetch a mounted object (table snapshot or - * workspace file). Long enough to download a large file at sandbox startup; the URL grants read to - * only that one object. - */ -const MOUNT_URL_TTL_SECONDS = 600 - -/** - * Per-file ceiling for URL-mounted workspace files. The bytes never transit the web process — the - * sandbox curls them straight from storage — so the bound is sandbox disk, not web heap (unlike the - * inline MAX_FILE_SIZE path). - */ -const MOUNT_URL_MAX_BYTES = 500 * 1024 * 1024 - -/** - * Aggregate ceiling across all URL-mounted files in one request. URL mounts bypass the web heap (so - * they don't count against MAX_TOTAL_SIZE), but the sandbox still curls every byte onto its disk — - * this rejects an oversized request up front instead of filling the sandbox disk one slow curl at a - * time. Generous vs MAX_TOTAL_SIZE since the bytes never transit web memory. - */ -const MAX_TOTAL_URL_BYTES = 2 * 1024 * 1024 * 1024 - -type SandboxFile = - | { type?: 'content'; path: string; content: string; encoding?: 'base64' } - | { type: 'url'; path: string; url: string } - -/** - * Running byte totals for one resolveInputFiles call. `buffered` bytes pass through the web process - * (capped by MAX_TOTAL_SIZE); `url` bytes are curled straight into the sandbox (capped by - * MAX_TOTAL_URL_BYTES). Tracked separately because the two ceilings protect different resources — - * web heap vs sandbox disk. - */ -interface MountedBytes { - buffered: number - url: number -} - async function importMountedWorkspaceFileProvenance(args: { workspaceId: string record: WorkspaceFileRecord @@ -118,17 +91,18 @@ async function importMountedWorkspaceFileProvenance(args: { } /** - * Mounts a stored workspace file into the sandbox and records its bytes against the running totals. - * With cloud storage the sandbox fetches the bytes itself from a presigned URL (no web-heap transit, - * per-file ceiling MOUNT_URL_MAX_BYTES, aggregate ceiling MAX_TOTAL_URL_BYTES); with local storage a - * presigned URL is an app-internal serve path a remote sandbox can't reach, so we buffer the bytes - * through the web process under the inline MAX_FILE_SIZE / MAX_TOTAL_SIZE guards. + * Mounts a stored workspace file into the sandbox. The transport choice, the byte + * ceilings, and the budget accounting live in {@link pushSandboxFileMount}, which + * the Function block shares; what stays here is workspace-specific — reloading the + * record through its application operation, importing its secret provenance, and + * reading generated documents through the servable reader rather than presigning + * their generator source. */ async function pushWorkspaceFileMount( sandboxFiles: SandboxFile[], record: WorkspaceFileRecord, mountPath: string, - mounted: MountedBytes, + mounted: SandboxMountBudget, workspaceId: string, principal: Principal, registry?: ResolvedSecretTraceRegistry @@ -148,78 +122,51 @@ async function pushWorkspaceFileMount( // through the web process rather than presigning is affordable. const rendersFromSource = isGeneratedDocumentSourceType(record.type) - if (hasCloudStorage() && !rendersFromSource) { - if (record.size > MOUNT_URL_MAX_BYTES) { - throw new Error( - `Input file "${mountPath}" is ${Math.round(record.size / 1024 / 1024)}MB, over the ${MOUNT_URL_MAX_BYTES / 1024 / 1024}MB per-file mount limit.` - ) - } - if (mounted.url + record.size > MAX_TOTAL_URL_BYTES) { - throw new Error( - `Mounting "${mountPath}" would exceed the ${MAX_TOTAL_URL_BYTES / 1024 / 1024 / 1024}GB total mount limit. Mount fewer or smaller files.` - ) - } - const url = await generatePresignedDownloadUrl( - record.key, - record.storageContext ?? 'workspace', - MOUNT_URL_TTL_SECONDS - ) - sandboxFiles.push({ type: 'url', path: mountPath, url }) - mounted.url += record.size - return - } - - const remainingBudget = Math.max(0, MAX_TOTAL_SIZE - mounted.buffered) - - // A source-backed document declares the size of its generator, not of the document, - // so these pre-checks say nothing about what is about to be mounted. Its read is - // capped instead, and the real length is checked once it is known. - if (!rendersFromSource) { - if (record.size > MAX_FILE_SIZE) { - throw new Error( - `Input file "${mountPath}" is ${Math.round(record.size / 1024 / 1024)}MB, over the ${MAX_FILE_SIZE / 1024 / 1024}MB per-file mount limit.` - ) - } - if (record.size > remainingBudget) { - throw new Error( - `Mounting "${mountPath}" would exceed the ${MAX_TOTAL_SIZE / 1024 / 1024}MB total mount limit. Mount fewer or smaller files.` - ) - } - } - - const { buffer, contentType } = rendersFromSource - ? await fetchAuthorizedServableWorkspaceFileBuffer(record, principal, { - maxBytes: Math.min(MAX_FILE_SIZE, remainingBudget), - }).catch((error) => { - if (!isPayloadSizeLimitError(error)) throw error - throw new Error( - `Input file "${mountPath}" renders to more than the ${MAX_FILE_SIZE / 1024 / 1024}MB per-file mount limit, or than the mount budget left. Mount fewer or smaller files.` + await pushSandboxFileMount( + sandboxFiles, + { + mountPath, + key: record.key, + storageContext: record.storageContext ?? 'workspace', + declaredSize: record.size, + rendersFromSource, + readInline: async (maxBytes) => { + const { buffer, contentType } = rendersFromSource + ? await fetchAuthorizedServableWorkspaceFileBuffer(record, principal, { + maxBytes, + }).catch((error) => { + if (!isPayloadSizeLimitError(error)) throw error + throw new Error( + `Input file "${mountPath}" renders to more than the ${MAX_FILE_SIZE / 1024 / 1024}MB per-file mount limit, or than the mount budget left. Mount fewer or smaller files.` + ) + }) + : { + buffer: ( + await readWorkspaceFileContent.execute({ + principal, + input: { + fileId: record.id, + assertedWorkspaceId: workspaceId, + maxBytes, + }, + }) + ).content, + contentType: record.type, + } + // Keyed off the resolved type: a rendered document's source MIME is `text/x-…`, and + // decoding the binary as UTF-8 would corrupt it just as surely as shipping the source. + const isText = /^text\/|application\/json|application\/xml|application\/csv/.test( + contentType || '' ) - }) - : { - buffer: ( - await readWorkspaceFileContent.execute({ - principal, - input: { - fileId: record.id, - assertedWorkspaceId: workspaceId, - maxBytes: Math.min(MAX_FILE_SIZE, remainingBudget), - }, - }) - ).content, - contentType: record.type, - } - // Keyed off the resolved type: a rendered document's source MIME is `text/x-…`, and - // decoding the binary as UTF-8 would corrupt it just as surely as shipping the source. - const isText = /^text\/|application\/json|application\/xml|application\/csv/.test( - contentType || '' + return { + content: isText ? buffer.toString('utf-8') : buffer.toString('base64'), + ...(isText ? {} : { encoding: 'base64' as const }), + byteLength: buffer.length, + } + }, + }, + mounted ) - sandboxFiles.push({ - path: mountPath, - content: isText ? buffer.toString('utf-8') : buffer.toString('base64'), - encoding: isText ? undefined : 'base64', - }) - mounted.buffered += buffer.length } /** @@ -306,7 +253,7 @@ export async function resolveInputFiles( filePrincipal?: Principal ): Promise { const sandboxFiles: SandboxFile[] = [] - const mounted: MountedBytes = { buffered: 0, url: 0 } + const mounted = createSandboxMountBudget() if (inputFiles?.length && workspaceId) { if (!filePrincipal) { @@ -512,7 +459,7 @@ export async function resolveInputFiles( 'execution', MOUNT_URL_TTL_SECONDS ) - sandboxFiles.push({ type: 'url', path: mountPath, url }) + sandboxFiles.push({ type: 'url', path: mountPath, url, maxBytes: SNAPSHOT_MAX_BYTES }) mounted.url += snapshot.size continue } diff --git a/apps/sim/lib/execution/payloads/sandbox-file-mount-ref.ts b/apps/sim/lib/execution/payloads/sandbox-file-mount-ref.ts new file mode 100644 index 00000000000..55555db2163 --- /dev/null +++ b/apps/sim/lib/execution/payloads/sandbox-file-mount-ref.ts @@ -0,0 +1,124 @@ +import { isUserFileWithMetadata } from '@/lib/core/utils/user-file' +import type { UserFile } from '@/executor/types' + +export const SANDBOX_FILE_MOUNT_REF_MARKER = '__simSandboxFileMount' +export const SANDBOX_FILE_MOUNT_REF_VERSION = 1 + +/** + * A request to place one file on the sandbox filesystem, standing in for the + * path until the sandbox exists. + * + * Emitted when code references ``. Reference resolution happens + * long before a sandbox is created, and mount paths are only known once the whole + * set is planned (they are sanitized and de-duplicated together), so the resolver + * leaves this marker and the function runtime swaps in the real path. + * + * Same shape as {@link LargeValueRef}: a marker a later layer materializes. It + * exists only where the caller wrote `.path`, which is what keeps a bare + * `` reference — the common case, and the one that runs fine in the + * isolated VM — from being dragged into a remote sandbox it never needed. + */ +export interface SandboxFileMountRef { + [SANDBOX_FILE_MOUNT_REF_MARKER]: true + version: typeof SANDBOX_FILE_MOUNT_REF_VERSION + file: UserFile +} + +export function createSandboxFileMountRef(file: UserFile): SandboxFileMountRef { + return { + [SANDBOX_FILE_MOUNT_REF_MARKER]: true, + version: SANDBOX_FILE_MOUNT_REF_VERSION, + file, + } +} + +export function isSandboxFileMountRef(value: unknown): value is SandboxFileMountRef { + if (!value || typeof value !== 'object') return false + + const candidate = value as Record + return ( + candidate[SANDBOX_FILE_MOUNT_REF_MARKER] === true && + candidate.version === SANDBOX_FILE_MOUNT_REF_VERSION && + isUserFileWithMetadata(candidate.file) + ) +} + +/** + * Replaces every mount marker in a value with whatever `resolvePath` returns for + * its file, leaving the rest of the structure untouched. + * + * Rebuilds containers rather than mutating them: the same resolved block output + * can be shared with other consumers, and a marker can sit anywhere inside a + * referenced object, not only at the top level. + */ +export function replaceSandboxFileMountRefs( + value: unknown, + resolvePath: (file: UserFile) => string, + seen = new WeakMap() +): unknown { + if (!value || typeof value !== 'object') return value + if (isSandboxFileMountRef(value)) return resolvePath(value.file) + + const existing = seen.get(value) + if (existing !== undefined) return existing + + if (Array.isArray(value)) { + const next: unknown[] = [] + seen.set(value, next) + for (const item of value) next.push(replaceSandboxFileMountRefs(item, resolvePath, seen)) + return next + } + + // Only plain containers are rebuilt. A Date, Buffer, Map, or class instance + // has no own enumerable entries worth walking, and reconstructing one from + // Object.entries would quietly replace it with a stripped plain object — a + // Date becoming `{}` on its way to the sandbox. Such a value cannot hold a + // mount marker anyway, so passing it through is both safer and complete. + const prototype = Object.getPrototypeOf(value) + if (prototype !== Object.prototype && prototype !== null) return value + + const next: Record = {} + seen.set(value, next) + for (const [key, item] of Object.entries(value)) { + // defineProperty, not assignment: a own `__proto__` key would otherwise hit + // Object.prototype's setter and vanish before the value reaches the sandbox. + Object.defineProperty(next, key, { + value: replaceSandboxFileMountRefs(item, resolvePath, seen), + enumerable: true, + writable: true, + configurable: true, + }) + } + return next +} + +/** Every file a value asks to have mounted, in first-seen order. */ +export function collectSandboxFileMountRefs( + value: unknown, + found: UserFile[] = [], + seen = new WeakSet() +): UserFile[] { + if (!value || typeof value !== 'object') return found + if (isSandboxFileMountRef(value)) { + found.push(value.file) + return found + } + if (seen.has(value)) return found + seen.add(value) + + if (Array.isArray(value)) { + for (const item of value) collectSandboxFileMountRefs(item, found, seen) + return found + } + + // Same plain-container rule the replacement pass applies. The two walks have to + // agree on the tree: a marker counted here but skipped there would mount a file + // whose reference never became a path. + const prototype = Object.getPrototypeOf(value) + if (prototype !== Object.prototype && prototype !== null) return found + + for (const item of Object.values(value)) { + collectSandboxFileMountRefs(item, found, seen) + } + return found +} diff --git a/apps/sim/lib/execution/remote-sandbox/conformance.test.ts b/apps/sim/lib/execution/remote-sandbox/conformance.test.ts index 0f4271033ef..0ea967c1742 100644 --- a/apps/sim/lib/execution/remote-sandbox/conformance.test.ts +++ b/apps/sim/lib/execution/remote-sandbox/conformance.test.ts @@ -9,6 +9,7 @@ import { Readable } from 'node:stream' import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' import { CodeLanguage } from '@/lib/execution/languages' +import { SANDBOX_OUTPUT_DIR_SENTINEL } from '@/lib/execution/remote-sandbox/sandbox-paths' const { mockResolveSandbox, @@ -22,12 +23,14 @@ const { mockE2BFilesRead, mockE2BFilesRemove, mockE2BFilesWrite, + mockE2BFilesList, mockE2BKill, mockDaytonaCreate, mockInterpreterRunCode, mockProcessCodeRun, mockExecuteCommand, mockGetFileDetails, + mockListFiles, mockUploadFile, mockDownloadFile, mockDownloadFileStream, @@ -71,12 +74,14 @@ const { mockE2BFilesRead: vi.fn(), mockE2BFilesRemove: vi.fn(), mockE2BFilesWrite: vi.fn(), + mockE2BFilesList: vi.fn(), mockE2BKill: vi.fn(), mockDaytonaCreate: vi.fn(), mockInterpreterRunCode: vi.fn(), mockProcessCodeRun: vi.fn(), mockExecuteCommand: vi.fn(), mockGetFileDetails: vi.fn(), + mockListFiles: vi.fn(), mockUploadFile: vi.fn(), mockDownloadFile: vi.fn(), mockDownloadFileStream: vi.fn(), @@ -266,6 +271,7 @@ beforeEach(() => { read: mockE2BFilesRead, remove: mockE2BFilesRemove, write: mockE2BFilesWrite, + list: mockE2BFilesList, }, kill: mockE2BKill, }) @@ -296,6 +302,7 @@ beforeEach(() => { downloadFile: mockDownloadFile, downloadFileStream: mockDownloadFileStream, getFileDetails: mockGetFileDetails, + listFiles: mockListFiles, }, delete: mockDelete, }) @@ -600,6 +607,171 @@ describe.each(PROVIDERS)('sandbox conformance [%s]', (provider) => { ).rejects.toThrow(/Failed to fetch mounted file/) }) + /** Stubs one directory listing in whichever shape the provider returns. */ + function stubOutputDirListing( + entries: Array<{ path: string; size: number; kind?: 'file' | 'dir' }> + ) { + if (provider === 'e2b') { + mockE2BFilesList.mockResolvedValueOnce( + entries.map((entry) => ({ + name: entry.path.split('/').pop(), + path: entry.path, + size: entry.size, + type: entry.kind === 'dir' ? 'dir' : 'file', + })) + ) + } else { + mockListFiles.mockResolvedValueOnce( + entries.map((entry) => ({ + name: entry.path.split('/').pop(), + path: entry.path, + size: entry.size, + isDir: entry.kind === 'dir', + mode: entry.kind === 'dir' ? 'drwxr-xr-x' : '-rw-r--r--', + })) + ) + } + } + + it('creates the output directory before user code runs', async () => { + stubCodeRun(provider, `__SIM_RESULT__=${JSON.stringify('done')}`) + stubOutputDirListing([]) + + await executeInSandbox({ + code: 'x', + language: CodeLanguage.Python, + timeoutMs: 1000, + outputSandboxDir: '/tmp/sim/outputs', + }) + + // Regression guard. `outputSandboxDir` is this layer's contract, so this + // layer has to create the directory: when creation lived in the caller's + // runtime prologue instead, calling executeInSandbox directly left user + // code writing into a directory that did not exist, and every write was + // ENOENT. The sentinel must be written before the code file that runs. + const writeMock = provider === 'e2b' ? mockE2BFilesWrite : mockUploadFile + const writtenPaths = writeMock.mock.calls.map((call) => + provider === 'e2b' ? call[0] : call[1] + ) + const sentinelIndex = writtenPaths.findIndex((path: string) => + path?.includes('/tmp/sim/outputs/.sim-keep') + ) + const codeIndex = writtenPaths.findIndex((path: string) => path?.includes('.sim-function-')) + expect(sentinelIndex).toBeGreaterThanOrEqual(0) + expect(codeIndex).toBeGreaterThanOrEqual(0) + expect(sentinelIndex).toBeLessThan(codeIndex) + }) + + it('keeps the directory sentinel out of the harvest', async () => { + stubCodeRun(provider, `__SIM_RESULT__=${JSON.stringify('done')}`) + stubOutputDirListing([ + { path: `/tmp/sim/outputs/${SANDBOX_OUTPUT_DIR_SENTINEL}`, size: 0 }, + { path: '/tmp/sim/outputs/real.txt', size: 4 }, + ]) + stubOutputFileSizes(provider, 4) + stubOutputFileRead(provider, 'real') + + const result = await executeInSandbox({ + code: 'x', + language: CodeLanguage.Python, + timeoutMs: 1000, + outputSandboxDir: '/tmp/sim/outputs', + }) + + expect(result.collectedFiles?.map((file) => file.relativePath)).toEqual(['real.txt']) + }) + + it('harvests files written to the output directory', async () => { + stubCodeRun(provider, `__SIM_RESULT__=${JSON.stringify('done')}`) + stubOutputDirListing([{ path: '/tmp/sim/outputs/report.csv', size: 5 }]) + stubOutputFileSizes(provider, 5) + stubOutputFileRead(provider, 'a,b\n1') + + const result = await executeInSandbox({ + code: 'x', + language: CodeLanguage.Python, + timeoutMs: 1000, + outputSandboxDir: '/tmp/sim/outputs', + }) + + expect(result.collectedFiles).toEqual([ + { + path: '/tmp/sim/outputs/report.csv', + relativePath: 'report.csv', + // Always base64, so an arbitrary harvested filename can never be + // decoded as utf8 and silently corrupted. + contentBase64: Buffer.from('a,b\n1').toString('base64'), + byteLength: 5, + }, + ]) + }) + + it('excludes directories from the harvest', async () => { + stubCodeRun(provider, `__SIM_RESULT__=${JSON.stringify('done')}`) + stubOutputDirListing([{ path: '/tmp/sim/outputs/nested', size: 0, kind: 'dir' }]) + + const result = await executeInSandbox({ + code: 'x', + language: CodeLanguage.Python, + timeoutMs: 1000, + outputSandboxDir: '/tmp/sim/outputs', + }) + + expect(result.collectedFiles).toBeUndefined() + }) + + it('refuses a harvest whose nesting outran the listing depth', async () => { + stubCodeRun(provider, `__SIM_RESULT__=${JSON.stringify('done')}`) + // A directory reported at the traversal limit still holds unlisted files. + // Returning the shallow ones would drop the rest without a word. + const deep = Array.from({ length: 12 }, (_, index) => `l${index + 1}`).join('/') + stubOutputDirListing([ + { path: '/tmp/sim/outputs/shallow.txt', size: 4 }, + { path: `/tmp/sim/outputs/${deep}`, size: 0, kind: 'dir' }, + ]) + + await expect( + executeInSandbox({ + code: 'x', + language: CodeLanguage.Python, + timeoutMs: 1000, + outputSandboxDir: '/tmp/sim/outputs', + }) + ).rejects.toThrow(/nested deeper than 12 levels/) + }) + + it('refuses a harvest over the output file count rather than truncating it', async () => { + stubCodeRun(provider, `__SIM_RESULT__=${JSON.stringify('done')}`) + stubOutputDirListing( + Array.from({ length: 21 }, (_, index) => ({ + path: `/tmp/sim/outputs/file-${index}.txt`, + size: 1, + })) + ) + + await expect( + executeInSandbox({ + code: 'x', + language: CodeLanguage.Python, + timeoutMs: 1000, + outputSandboxDir: '/tmp/sim/outputs', + }) + ).rejects.toThrow(/over the 20-file export limit/) + }) + + it('does not list the output directory when no harvest was requested', async () => { + stubCodeRun(provider, `__SIM_RESULT__=${JSON.stringify('done')}`) + + const result = await executeInSandbox({ + code: 'x', + language: CodeLanguage.Python, + timeoutMs: 1000, + }) + + expect(result.collectedFiles).toBeUndefined() + expect(provider === 'e2b' ? mockE2BFilesList : mockListFiles).not.toHaveBeenCalled() + }) + it('materializes private code inputs after dependencies and user files', async () => { const privateText = 'line one\n"quoted"\\slash\0tail' const privateBytes = Uint8Array.from([0, 10, 34, 92, 255]).buffer diff --git a/apps/sim/lib/execution/remote-sandbox/daytona.ts b/apps/sim/lib/execution/remote-sandbox/daytona.ts index 0df2ae61443..875fcb06856 100644 --- a/apps/sim/lib/execution/remote-sandbox/daytona.ts +++ b/apps/sim/lib/execution/remote-sandbox/daytona.ts @@ -27,11 +27,13 @@ import { SandboxProcessOutputBudget, tailStreamedSandboxOutput, } from '@/lib/execution/remote-sandbox/output-limits' +import { resolveSandboxDirectoryEntryPath } from '@/lib/execution/remote-sandbox/sandbox-paths' import type { CreateSandboxOptions, RunCommandOptions, SandboxCodeResult, SandboxCommandResult, + SandboxDirectoryEntry, SandboxHandle, SandboxKind, SandboxProvider, @@ -742,6 +744,24 @@ class DaytonaSandboxHandle implements SandboxHandle { await this.sandbox.fs.uploadFile(buffer, path) } + async listFiles(path: string, options?: { depth?: number }): Promise { + const entries = await this.sandbox.fs.listFiles(path, { + ...(options?.depth !== undefined ? { depth: options.depth } : {}), + }) + + const files: SandboxDirectoryEntry[] = [] + for (const entry of entries) { + const resolved = resolveSandboxDirectoryEntryPath(path, entry.path ?? entry.name) + if (!resolved) continue + files.push({ + ...resolved, + kind: entry.isDir ? 'directory' : 'file', + size: entry.size, + }) + } + return files + } + async kill(): Promise { if (this.killed) return if (!this.killPromise) { diff --git a/apps/sim/lib/execution/remote-sandbox/e2b.ts b/apps/sim/lib/execution/remote-sandbox/e2b.ts index db387fd93e7..6a294713f6e 100644 --- a/apps/sim/lib/execution/remote-sandbox/e2b.ts +++ b/apps/sim/lib/execution/remote-sandbox/e2b.ts @@ -43,6 +43,7 @@ import { SandboxProcessOutputBudget, tailStreamedSandboxOutput, } from '@/lib/execution/remote-sandbox/output-limits' +import { resolveSandboxDirectoryEntryPath } from '@/lib/execution/remote-sandbox/sandbox-paths' import { quoteDependency, type SandboxSpec, @@ -55,6 +56,7 @@ import type { RunCommandOptions, SandboxCodeResult, SandboxCommandResult, + SandboxDirectoryEntry, SandboxHandle, SandboxImageBuild, SandboxImageBuilder, @@ -628,6 +630,25 @@ class E2BSandboxHandle implements SandboxHandle { await this.sandbox.files.write(path, content as string) } + async listFiles(path: string, options?: { depth?: number }): Promise { + const entries = await this.sandbox.files.list(path, { + ...(options?.depth !== undefined ? { depth: options.depth } : {}), + }) + + const files: SandboxDirectoryEntry[] = [] + for (const entry of entries) { + if (entry.type !== 'file' && entry.type !== 'dir') continue + const resolved = resolveSandboxDirectoryEntryPath(path, entry.path) + if (!resolved) continue + files.push({ + ...resolved, + kind: entry.type === 'dir' ? 'directory' : 'file', + size: entry.size, + }) + } + return files + } + async kill(): Promise { if (this.killed) return if (!this.killPromise) { diff --git a/apps/sim/lib/execution/remote-sandbox/index.ts b/apps/sim/lib/execution/remote-sandbox/index.ts index 7055a88ec2e..7bf9f5bff1f 100644 --- a/apps/sim/lib/execution/remote-sandbox/index.ts +++ b/apps/sim/lib/execution/remote-sandbox/index.ts @@ -13,7 +13,12 @@ import { isSandboxOutputFileError, isSandboxOutputLimitError, MAX_SANDBOX_OUTPUT_BYTES, + MAX_SANDBOX_OUTPUT_FILES, MAX_SANDBOX_PROCESS_OUTPUT_BYTES, + MAX_SANDBOX_URL_MOUNT_BYTES, + SandboxOutputDepthError, + SandboxOutputDirectoryMissingError, + SandboxOutputFileCountError, SandboxOutputLimitError, } from '@/lib/execution/remote-sandbox/output-limits' import { resolvePiSandboxLifetimeMs } from '@/lib/execution/remote-sandbox/pi-lifetime' @@ -25,10 +30,16 @@ import { repairMissingSandboxImage, resolveWorkspaceSandbox, } from '@/lib/execution/remote-sandbox/resolve' +import { + SANDBOX_OUTPUT_DIR_MAX_DEPTH, + SANDBOX_OUTPUT_DIR_SENTINEL, +} from '@/lib/execution/remote-sandbox/sandbox-paths' import type { CreateSandboxOptions, SandboxCodeResult, + SandboxCollectedFile, SandboxCommandResult, + SandboxDirectoryEntry, SandboxExecutionRequest, SandboxExecutionResult, SandboxFile, @@ -200,6 +211,39 @@ function bindSandboxAbort(sandbox: SandboxHandle, signal?: AbortSignal) { } } +/** + * Fetches one URL mount inside the sandbox, bounded by MAX_BYTES. + * + * Three mechanisms, because no one of them is sufficient on its own. + * `--max-filesize` refuses an oversized object before a byte moves, but only when + * the response declares a Content-Length — a chunked or length-less reply walks + * straight past it. `head -c` therefore caps what can ever reach the disk at one + * byte over the limit, so a mis-declared object cannot fill the sandbox while we + * wait to notice. The final size check is what turns that truncated file into a + * refusal rather than a silently corrupted mount. + * + * curl's exit status travels through a file because its status is lost in a + * pipeline, and losing it would let a 403 on an expired URL look like a + * successful empty download. The size check is consulted first: when `head` + * closes the pipe early curl dies of EPIPE, and "over the limit" is the useful + * message there, not the write error it provokes. + * + * MAX_BYTES, URL, DST, and DIR all arrive as environment variables, never + * interpolated, so a presigned query string cannot break out of the command. + */ +const FETCH_URL_MOUNT_COMMAND = [ + 'set -e', + '[ -n "$DIR" ] && mkdir -p "$DIR"', + 'STATUS_FILE=$(mktemp)', + 'STATUS=0', + '{ curl -fsS --retry 3 --retry-connrefused --max-time 300 --max-filesize "$MAX_BYTES" "$URL" || STATUS=$?; echo "$STATUS" > "$STATUS_FILE"; } | head -c "$(( MAX_BYTES + 1 ))" > "$DST"', + 'STATUS=$(cat "$STATUS_FILE")', + 'rm -f "$STATUS_FILE"', + 'SIZE=$(wc -c < "$DST")', + 'if [ "$SIZE" -gt "$MAX_BYTES" ]; then rm -f "$DST"; echo "mounted file exceeds the $MAX_BYTES byte limit" >&2; exit 1; fi', + 'if [ "$STATUS" -ne 0 ]; then rm -f "$DST"; echo "curl exited $STATUS" >&2; exit 1; fi', +].join('\n') + /** * Materializes sandbox input files before user code runs. `content` entries are written inline; * `url` entries are fetched from inside the sandbox via `curl` — their bytes never pass through the @@ -220,16 +264,24 @@ async function writeSandboxInputs( const dir = file.path.slice(0, file.path.lastIndexOf('/')) let result: SandboxCommandResult try { - result = await sandbox.runCommand( - 'set -e; [ -n "$DIR" ] && mkdir -p "$DIR"; curl -fsS --retry 3 --retry-connrefused --max-time 300 "$URL" -o "$DST"', - { - envs: { URL: file.url, DST: file.path, DIR: dir }, - timeoutMs: Math.min(300_000, remainingSandboxBudgetMs(opts.signal)), - maxOutputBytes: MAX_SANDBOX_PROCESS_OUTPUT_BYTES, - signal: opts.signal, - rootUser: opts.rootUser, - } - ) + result = await sandbox.runCommand(FETCH_URL_MOUNT_COMMAND, { + envs: { + URL: file.url, + DST: file.path, + DIR: dir, + // Clamped, not just defaulted: `sandboxFiles` reaches this layer from + // the request body, so a declared ceiling is a caller's number. It may + // lower the limit for its own mount but never raise it past the one + // this layer guarantees. + MAX_BYTES: String( + Math.min(file.maxBytes ?? MAX_SANDBOX_URL_MOUNT_BYTES, MAX_SANDBOX_URL_MOUNT_BYTES) + ), + }, + timeoutMs: Math.min(300_000, remainingSandboxBudgetMs(opts.signal)), + maxOutputBytes: MAX_SANDBOX_PROCESS_OUTPUT_BYTES, + signal: opts.signal, + rootUser: opts.rootUser, + }) } catch (error) { throwIfAborted(opts.signal) throw new Error( @@ -441,11 +493,84 @@ function requestedOutputSandboxPaths(req: { ] } +/** + * Enumerates the harvest directory, refusing anything it cannot return in full — + * too many files, or nesting past what the listing reaches — before a single + * byte is read. Sorted so a multi-file result is stable run to run rather than + * inheriting whatever order the provider happened to return. + */ +async function listOutputDirectoryFiles( + sandbox: SandboxHandle, + outputSandboxDir: string, + signal: AbortSignal +): Promise { + let listed: SandboxDirectoryEntry[] + try { + listed = await sandbox.listFiles(outputSandboxDir, { depth: SANDBOX_OUTPUT_DIR_MAX_DEPTH }) + } catch (error) { + // The directory is created before user code runs, so the only way it can be + // missing now is that the code removed it. Providers report that as a raw + // `lstat ... no such file or directory`, which reads like a Sim fault; say + // what actually happened instead. Anything else propagates untouched rather + // than being flattened into "produced nothing". + if (/not_?found|no such file|ENOENT/i.test(getErrorMessage(error))) { + throw new SandboxOutputDirectoryMissingError(outputSandboxDir) + } + throw error + } + const entries = listed.filter((entry) => entry.relativePath !== SANDBOX_OUTPUT_DIR_SENTINEL) + remainingSandboxBudgetMs(signal) + + // A directory sitting exactly at the traversal limit still has unlisted + // contents, and the providers report no truncation of their own. Refuse + // rather than return a partial harvest: a file the code wrote and the caller + // never receives is worse than an error naming the reason. + const truncatedAt = entries.find( + (entry) => + entry.kind === 'directory' && + entry.relativePath.split('/').length >= SANDBOX_OUTPUT_DIR_MAX_DEPTH + ) + if (truncatedAt) { + throw new SandboxOutputDepthError( + `${outputSandboxDir}/${truncatedAt.relativePath}`, + SANDBOX_OUTPUT_DIR_MAX_DEPTH + ) + } + + const files = entries.filter((entry) => entry.kind === 'file') + if (files.length > MAX_SANDBOX_OUTPUT_FILES) { + throw new SandboxOutputFileCountError(files.length, outputSandboxDir) + } + return files.sort((a, b) => a.path.localeCompare(b.path)) +} + +/** + * Brings the harvest directory into existence before user code runs. + * + * Owned here rather than by the caller's runtime prologue because + * `outputSandboxDir` is this layer's contract: a caller that asks for a harvest + * must not also have to know it is responsible for creating the directory, or + * the first write in their code is ENOENT. + */ +async function ensureSandboxOutputDir( + sandbox: SandboxHandle, + outputSandboxDir: string | undefined, + signal: AbortSignal +): Promise { + if (!outputSandboxDir) return + await sandbox.writeFile(`${outputSandboxDir}/${SANDBOX_OUTPUT_DIR_SENTINEL}`, '') + remainingSandboxBudgetMs(signal) +} + async function collectExportedFiles( sandbox: SandboxHandle, - req: { outputSandboxPath?: string; outputSandboxPaths?: string[] }, + req: { outputSandboxPath?: string; outputSandboxPaths?: string[]; outputSandboxDir?: string }, options: { signal: AbortSignal } -): Promise<{ exportedFiles?: Record; exportedFileContent?: string }> { +): Promise<{ + exportedFiles?: Record + exportedFileContent?: string + collectedFiles?: SandboxCollectedFile[] +}> { const readablePaths: string[] = [] let totalOutputBytes = 0 for (const outputSandboxPath of requestedOutputSandboxPaths(req)) { @@ -459,6 +584,24 @@ async function collectExportedFiles( readablePaths.push(outputSandboxPath) } + // Sized into the same running total as the declared paths, so an execution + // cannot spend the ceiling twice by both declaring and harvesting. A declared + // path that happens to sit inside the harvest directory is dropped from the + // discovered set rather than counted again — double-billing it would reject a + // single output larger than half the ceiling as oversized. + const declaredPaths = new Set(readablePaths) + const discovered = ( + req.outputSandboxDir + ? await listOutputDirectoryFiles(sandbox, req.outputSandboxDir, options.signal) + : [] + ).filter((entry) => !declaredPaths.has(entry.path)) + for (const entry of discovered) { + totalOutputBytes += entry.size + if (totalOutputBytes > MAX_SANDBOX_OUTPUT_BYTES) { + throw new SandboxOutputLimitError(totalOutputBytes) + } + } + const exportedFiles: Record = {} let readOutputBytes = 0 for (const outputSandboxPath of readablePaths) { @@ -484,9 +627,45 @@ async function collectExportedFiles( throw error } } + + const collectedFiles: SandboxCollectedFile[] = [] + for (const entry of discovered) { + try { + // Always base64: a harvested filename is arbitrary, and the extension + // allowlist that picks an encoding for a declared path would decode a + // `.parquet` or an extensionless binary as utf8 — substituting U+FFFD and + // delivering corruption that still looks like a valid file. + const file = await sandbox.readFileWithLimit(entry.path, { + maxBytes: MAX_SANDBOX_OUTPUT_BYTES - readOutputBytes, + encoding: 'base64', + signal: options.signal, + }) + remainingSandboxBudgetMs(options.signal) + readOutputBytes += file.byteLength + collectedFiles.push({ + path: entry.path, + relativePath: entry.relativePath, + contentBase64: file.content, + byteLength: file.byteLength, + }) + } catch (error) { + if (isSandboxOutputLimitError(error)) { + throw new SandboxOutputLimitError( + readOutputBytes + error.attemptedBytes, + MAX_SANDBOX_OUTPUT_BYTES + ) + } + // Unlike a declared path, a harvested file was just observed to exist, so + // a failed read is an anomaly rather than a caller mistake. Dropping it + // would silently lose output the code successfully produced. + throw error + } + } + return { exportedFileContent: req.outputSandboxPath ? exportedFiles[req.outputSandboxPath] : undefined, exportedFiles: Object.keys(exportedFiles).length ? exportedFiles : undefined, + collectedFiles: collectedFiles.length ? collectedFiles : undefined, } } @@ -506,6 +685,33 @@ function installBudgetMs(timeoutMs: number): number { return Math.max(0, Math.min(RUNTIME_INSTALL_TIMEOUT_MS, timeoutMs - MIN_CODE_BUDGET_MS)) } +/** + * Held back from the code's own budget when an execution will export files. + * + * The export runs after the code succeeds and draws on the same wall clock, so + * without a reserve a long install plus long-running code can time out during + * the read — destroying work the code already finished, under an error that + * only says "timeout". + */ +const MIN_EXPORT_BUDGET_MS = 10_000 + +/** + * The budget handed to user code, less an export reserve when this request will + * read files back. Short budgets are left alone: taking the reserve out of one + * would starve the code to buy time for an export it never reaches. + */ +function codeBudgetMs( + req: { outputSandboxPath?: string; outputSandboxPaths?: string[]; outputSandboxDir?: string }, + signal: AbortSignal +): number { + const remainingMs = remainingSandboxBudgetMs(signal) + const exportsFiles = Boolean( + req.outputSandboxDir || req.outputSandboxPath || req.outputSandboxPaths?.length + ) + if (!exportsFiles || remainingMs <= MIN_EXPORT_BUDGET_MS * 2) return remainingMs + return remainingMs - MIN_EXPORT_BUDGET_MS +} + /** * Installs a runtime sandbox's dependencies out of the caller's budget and * uses the shared wall-clock budget, so creation and every later phase consume @@ -568,6 +774,7 @@ async function executeInSandboxWithinBudget( // await provisionWithinBudget(sandbox, selected, signal) await writeSandboxInputs(sandbox, req.sandboxFiles, { signal }) + await ensureSandboxOutputDir(sandbox, req.outputSandboxDir, signal) const privateInputEnvironment = await writeSandboxPrivateInputs( sandbox, req.privateInputs, @@ -583,7 +790,7 @@ async function executeInSandboxWithinBudget( let execution: SandboxCodeResult try { execution = await sandbox.runCode(code, { - timeoutMs: remainingSandboxBudgetMs(signal), + timeoutMs: codeBudgetMs(req, signal), javascriptPreload: buildJavaScriptRuntimeBindingsSource(req.runtimeBindings ?? []), maxOutputBytes: MAX_SANDBOX_PROCESS_OUTPUT_BYTES, signal, @@ -636,9 +843,11 @@ async function executeInSandboxWithinBudget( } } - const { exportedFiles, exportedFileContent } = await collectExportedFiles(sandbox, req, { - signal, - }) + const { exportedFiles, exportedFileContent, collectedFiles } = await collectExportedFiles( + sandbox, + req, + { signal } + ) throwIfAborted(signal) return { @@ -647,6 +856,7 @@ async function executeInSandboxWithinBudget( sandboxId, exportedFileContent, exportedFiles, + collectedFiles, } } finally { abortBinding.detach() @@ -696,6 +906,7 @@ async function executeShellInSandboxWithinBudget( rootUser: true, signal, }) + await ensureSandboxOutputDir(sandbox, req.outputSandboxDir, signal) const privateInputEnvironment = await writeSandboxPrivateInputs( sandbox, req.privateInputs, @@ -711,7 +922,7 @@ async function executeShellInSandboxWithinBudget( PATH: selected?.envs?.PATH ?? SANDBOX_SYSTEM_PATH, ...privateInputEnvironment, }, - timeoutMs: remainingSandboxBudgetMs(signal), + timeoutMs: codeBudgetMs(req, signal), maxOutputBytes: MAX_SANDBOX_PROCESS_OUTPUT_BYTES, signal, rootUser: true, @@ -744,9 +955,11 @@ async function executeShellInSandboxWithinBudget( const extraction = extractSimResult(stdout) const parsed = extraction.parseFailed ? extraction.rawPayload : extraction.result - const { exportedFiles, exportedFileContent } = await collectExportedFiles(sandbox, req, { - signal, - }) + const { exportedFiles, exportedFileContent, collectedFiles } = await collectExportedFiles( + sandbox, + req, + { signal } + ) throwIfAborted(signal) return { @@ -755,6 +968,7 @@ async function executeShellInSandboxWithinBudget( sandboxId, exportedFileContent, exportedFiles, + collectedFiles, } } finally { abortBinding.detach() diff --git a/apps/sim/lib/execution/remote-sandbox/output-limits.ts b/apps/sim/lib/execution/remote-sandbox/output-limits.ts index 91fc5cb3616..0110bf57215 100644 --- a/apps/sim/lib/execution/remote-sandbox/output-limits.ts +++ b/apps/sim/lib/execution/remote-sandbox/output-limits.ts @@ -1,5 +1,25 @@ export const MAX_SANDBOX_OUTPUT_BYTES = 50 * 1024 * 1024 +/** + * Hard ceiling on a single URL-mounted input, enforced inside the sandbox by + * `curl --max-filesize` against the bytes actually served. + * + * The planner checks a recorded size first for a fast, well-worded failure; this + * is the backstop for when that size understates the stored object, and it is + * what a URL mount falls back to when the caller declares no ceiling of its own. + * URL bytes never enter the web process, so the resource being bounded is + * sandbox disk. + */ +export const MAX_SANDBOX_URL_MOUNT_BYTES = 500 * 1024 * 1024 + +/** + * How many files one execution may export, whether declared by path or + * discovered by harvesting the output directory. Exceeding it is an error rather + * than a truncation: silently returning the first 20 of 100 files reads as + * success while losing the rest. + */ +export const MAX_SANDBOX_OUTPUT_FILES = 20 + /** * Maximum combined stdout, stderr, result text, and structured error text kept * for one sandbox operation. Function results larger than this should be @@ -52,6 +72,36 @@ export function appendStreamedSandboxOutput(current: string, chunk: string): str export const SANDBOX_OUTPUT_LIMIT_CODE = 'sandbox_output_limit_exceeded' as const export const SANDBOX_OUTPUT_FILE_INVALID_CODE = 'sandbox_output_file_invalid' as const +/** + * The harvest cannot return what the run produced — too many files, or nested + * past what the listing reaches. Both are the caller's to fix and neither is + * retryable, so they share a code and are reported as one 400. + */ +export const SANDBOX_OUTPUT_NOT_EXPORTABLE_CODE = 'sandbox_output_not_exportable' as const + +/** More files in the harvest directory than one execution may export. */ +export class SandboxOutputFileCountError extends Error { + readonly code = SANDBOX_OUTPUT_NOT_EXPORTABLE_CODE + + constructor(observedFiles: number, directory: string, limit = MAX_SANDBOX_OUTPUT_FILES) { + super( + `Sandbox produced ${observedFiles} files in ${directory}, over the ${limit}-file export limit. Write fewer files, or archive them into a single .zip.` + ) + this.name = 'SandboxOutputFileCountError' + } +} + +/** Harvest directory nested deeper than the listing can reach. */ +export class SandboxOutputDepthError extends Error { + readonly code = SANDBOX_OUTPUT_NOT_EXPORTABLE_CODE + + constructor(directoryPath: string, maxDepth: number) { + super( + `Sandbox output "${directoryPath}" is nested deeper than ${maxDepth} levels, so its contents cannot be returned. Write results closer to the top of the output directory, or archive the tree into a single file.` + ) + this.name = 'SandboxOutputDepthError' + } +} export class SandboxOutputFileError extends Error { readonly code = SANDBOX_OUTPUT_FILE_INVALID_CODE @@ -136,3 +186,28 @@ export function isSandboxOutputFileError(error: unknown): error is SandboxOutput (error as { code?: unknown }).code === SANDBOX_OUTPUT_FILE_INVALID_CODE) ) } + +/** The harvest directory was removed by the code that was supposed to fill it. */ +export class SandboxOutputDirectoryMissingError extends Error { + readonly code = SANDBOX_OUTPUT_NOT_EXPORTABLE_CODE + + constructor(directoryPath: string) { + super( + `The sandbox output directory ${directoryPath} no longer exists — the code deleted it. Write files into it rather than replacing it; no files could be returned from this run.` + ) + this.name = 'SandboxOutputDirectoryMissingError' + } +} + +export function isSandboxOutputNotExportableError( + error: unknown +): error is + | SandboxOutputFileCountError + | SandboxOutputDepthError + | SandboxOutputDirectoryMissingError { + return ( + typeof error === 'object' && + error !== null && + (error as { code?: unknown }).code === SANDBOX_OUTPUT_NOT_EXPORTABLE_CODE + ) +} diff --git a/apps/sim/lib/execution/remote-sandbox/sandbox-files.smoke.test.ts b/apps/sim/lib/execution/remote-sandbox/sandbox-files.smoke.test.ts new file mode 100644 index 00000000000..72f60ec4087 --- /dev/null +++ b/apps/sim/lib/execution/remote-sandbox/sandbox-files.smoke.test.ts @@ -0,0 +1,348 @@ +/** + * @vitest-environment node + * + * End-to-end file I/O against a real sandbox provider. + * + * The conformance suite proves both adapters agree on a mocked SDK; this proves + * the contract survives the actual provider — that a mount really lands where + * the code expects, that the output directory really exists before user code + * runs, and that harvested bytes really come back unchanged. + * + * Enable with `SANDBOX_FILES_SMOKE=1`. Requires `E2B_API_KEY` and + * `E2B_FUNCTION_TEMPLATE_ID`; set `SANDBOX_PROVIDER=daytona` (with + * `DAYTONA_API_KEY` and `DAYTONA_SHELL_SNAPSHOT_ID`) to run the same table + * against Daytona instead. Each case creates and destroys one sandbox. + */ +import { createHash } from 'node:crypto' +import { describe, expect, it } from 'vitest' +import { CodeLanguage } from '@/lib/execution/languages' +import { + executeInSandbox, + executeShellInSandbox, + SIM_RESULT_PREFIX, +} from '@/lib/execution/remote-sandbox' +import { SANDBOX_INPUT_DIR, SANDBOX_OUTPUT_DIR } from '@/lib/execution/remote-sandbox/sandbox-paths' + +const smokeEnabled = process.env.SANDBOX_FILES_SMOKE === '1' +const CASE_TIMEOUT_MS = 5 * 60_000 +const RUN_TIMEOUT_MS = 4 * 60_000 + +/** Bytes that a UTF-8 round trip would destroy — the corruption we must not see. */ +const BINARY_FIXTURE = Buffer.from([ + 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0xff, 0xfe, 0x80, 0x7f, 0xc3, 0x28, +]) + +function sha256(buffer: Buffer): string { + return createHash('sha256').update(buffer).digest('hex') +} + +function decode(contentBase64: string): Buffer { + return Buffer.from(contentBase64, 'base64') +} + +/** + * Emits the result marker by hand. These cases drive the sandbox layer directly, + * below the wrapper `execute-request` builds, so `__sim_result__` and a bare + * `return` are not available here — the marker is what proves the code ran to + * completion rather than dying partway. + */ +function pythonResult(expression: string): string { + return `import json; print('${SIM_RESULT_PREFIX}' + json.dumps(${expression}))` +} + +function javascriptResult(expression: string): string { + return `console.log('\\n${SIM_RESULT_PREFIX}' + JSON.stringify(${expression}))` +} + +describe.skipIf(!smokeEnabled)('sandbox file I/O smoke', () => { + it( + 'mounts inputs, harvests outputs, and preserves binary bytes exactly', + async () => { + const result = await executeInSandbox({ + code: [ + 'import os, shutil', + `text = open(os.path.join(${JSON.stringify(SANDBOX_INPUT_DIR)}, 'notes.txt')).read()`, + `blob = open(os.path.join(${JSON.stringify(SANDBOX_INPUT_DIR)}, 'fixture.bin'), 'rb').read()`, + `out = ${JSON.stringify(SANDBOX_OUTPUT_DIR)}`, + "open(os.path.join(out, 'echo.txt'), 'w').write(text.upper())", + // Copied byte-for-byte so any encoding mistake anywhere in the round + // trip shows up as a hash mismatch rather than a plausible-looking file. + "open(os.path.join(out, 'copy.bin'), 'wb').write(blob)", + "os.makedirs(os.path.join(out, 'nested'), exist_ok=True)", + "open(os.path.join(out, 'nested', 'deep.txt'), 'w').write('nested')", + "open(os.path.join(out, 'empty.txt'), 'w').write('')", + pythonResult('{"len": len(blob)}'), + ].join('\n'), + language: CodeLanguage.Python, + timeoutMs: RUN_TIMEOUT_MS, + sandboxFiles: [ + { path: `${SANDBOX_INPUT_DIR}/notes.txt`, content: 'hello sandbox' }, + { + path: `${SANDBOX_INPUT_DIR}/fixture.bin`, + content: BINARY_FIXTURE.toString('base64'), + encoding: 'base64', + }, + ], + outputSandboxDir: SANDBOX_OUTPUT_DIR, + }) + + expect(result.error).toBeUndefined() + expect(result.result).toEqual({ len: BINARY_FIXTURE.length }) + + const byPath = new Map((result.collectedFiles ?? []).map((file) => [file.relativePath, file])) + expect([...byPath.keys()].sort()).toEqual([ + 'copy.bin', + 'echo.txt', + 'empty.txt', + 'nested/deep.txt', + ]) + + expect(decode(byPath.get('echo.txt')!.contentBase64).toString('utf8')).toBe('HELLO SANDBOX') + expect(sha256(decode(byPath.get('copy.bin')!.contentBase64))).toBe(sha256(BINARY_FIXTURE)) + expect(byPath.get('copy.bin')!.byteLength).toBe(BINARY_FIXTURE.length) + expect(decode(byPath.get('nested/deep.txt')!.contentBase64).toString('utf8')).toBe('nested') + expect(byPath.get('empty.txt')!.byteLength).toBe(0) + }, + CASE_TIMEOUT_MS + ) + + it( + 'reads a mounted file and creates the output directory before JavaScript user code runs', + async () => { + const result = await executeInSandbox({ + code: [ + "import { readFileSync, writeFileSync, existsSync } from 'node:fs'", + `const out = ${JSON.stringify(SANDBOX_OUTPUT_DIR)}`, + // Asserted from inside the sandbox: if the directory were not created + // before user code, the very first write is ENOENT. + 'if (!existsSync(out)) throw new Error("output dir missing before user code")', + // The point of resolving `` to a path rather than + // inlining bytes is that every language can just open it. Python and + // Shell prove that in the cases either side of this one. + `const seed = readFileSync(${JSON.stringify(`${SANDBOX_INPUT_DIR}/seed.txt`)}, 'utf8')`, + 'writeFileSync(out + "/from-js.json", JSON.stringify({ seed }))', + javascriptResult('{ wrote: true }'), + ].join('\n'), + language: CodeLanguage.JavaScript, + timeoutMs: RUN_TIMEOUT_MS, + sandboxFiles: [{ path: `${SANDBOX_INPUT_DIR}/seed.txt`, content: 'js seed' }], + outputSandboxDir: SANDBOX_OUTPUT_DIR, + }) + + expect(result.error).toBeUndefined() + expect(result.collectedFiles).toHaveLength(1) + expect(result.collectedFiles?.[0].relativePath).toBe('from-js.json') + expect(JSON.parse(decode(result.collectedFiles![0].contentBase64).toString('utf8'))).toEqual({ + seed: 'js seed', + }) + }, + CASE_TIMEOUT_MS + ) + + it( + 'creates the output directory before shell user code runs', + async () => { + const result = await executeShellInSandbox({ + code: [ + `test -d ${SANDBOX_OUTPUT_DIR} || { echo "output dir missing" >&2; exit 1; }`, + `cp ${SANDBOX_INPUT_DIR}/seed.txt ${SANDBOX_OUTPUT_DIR}/from-shell.txt`, + `echo "${SIM_RESULT_PREFIX}\\"done\\""`, + ].join('\n'), + envs: {}, + timeoutMs: RUN_TIMEOUT_MS, + sandboxFiles: [{ path: `${SANDBOX_INPUT_DIR}/seed.txt`, content: 'shell seed' }], + outputSandboxDir: SANDBOX_OUTPUT_DIR, + }) + + expect(result.error).toBeUndefined() + expect(result.collectedFiles).toHaveLength(1) + expect(decode(result.collectedFiles![0].contentBase64).toString('utf8')).toBe('shell seed') + }, + CASE_TIMEOUT_MS + ) + + it( + 'returns nothing rather than failing when the code writes no files', + async () => { + const result = await executeInSandbox({ + code: pythonResult('"no files"'), + language: CodeLanguage.Python, + timeoutMs: RUN_TIMEOUT_MS, + outputSandboxDir: SANDBOX_OUTPUT_DIR, + }) + + expect(result.error).toBeUndefined() + expect(result.result).toBe('no files') + // "Produced nothing" is an ordinary outcome; the directory exists because + // the prologue made it, so listing it must succeed and come back empty. + expect(result.collectedFiles).toBeUndefined() + }, + CASE_TIMEOUT_MS + ) + + it( + 'skips directories and follows symlinks identically on either provider', + async () => { + const result = await executeInSandbox({ + code: [ + 'import os', + `out = ${JSON.stringify(SANDBOX_OUTPUT_DIR)}`, + "open(os.path.join(out, 'real.txt'), 'w').write('real')", + "os.symlink('/etc/passwd', os.path.join(out, 'linked.txt'))", + "os.makedirs(os.path.join(out, 'adir'), exist_ok=True)", + pythonResult('"planted"'), + ].join('\n'), + language: CodeLanguage.Python, + timeoutMs: RUN_TIMEOUT_MS, + outputSandboxDir: SANDBOX_OUTPUT_DIR, + }) + + expect(result.error).toBeUndefined() + // Followed rather than excluded, and the same on both providers — Daytona + // resolves links in its listing with no field that would reveal one, and + // the code could copy the target's bytes into the directory itself + // anyway. The empty directory is skipped on both. + expect((result.collectedFiles ?? []).map((file) => file.relativePath).sort()).toEqual([ + 'linked.txt', + 'real.txt', + ]) + }, + CASE_TIMEOUT_MS + ) + + it( + 'refuses a harvest over the file-count limit instead of truncating it', + async () => { + await expect( + executeInSandbox({ + code: [ + 'import os', + `out = ${JSON.stringify(SANDBOX_OUTPUT_DIR)}`, + 'for i in range(21):', + " open(os.path.join(out, f'file-{i}.txt'), 'w').write(str(i))", + pythonResult('"wrote 21"'), + ].join('\n'), + language: CodeLanguage.Python, + timeoutMs: RUN_TIMEOUT_MS, + outputSandboxDir: SANDBOX_OUTPUT_DIR, + }) + ).rejects.toThrow(/over the 20-file export limit/) + }, + CASE_TIMEOUT_MS + ) + + it( + 'probe: how deep a nested output is still harvested', + async () => { + const result = await executeInSandbox({ + code: [ + 'import os', + `out = ${JSON.stringify(SANDBOX_OUTPUT_DIR)}`, + 'for depth in range(1, 6):', + " d = os.path.join(out, *[f'l{i}' for i in range(1, depth + 1)])", + ' os.makedirs(d, exist_ok=True)', + " open(os.path.join(d, 'leaf.txt'), 'w').write(str(depth))", + pythonResult('"nested"'), + ].join('\n'), + language: CodeLanguage.Python, + timeoutMs: RUN_TIMEOUT_MS, + outputSandboxDir: SANDBOX_OUTPUT_DIR, + }) + + expect(result.error).toBeUndefined() + // Nesting deeper than the listing depth must not vanish silently — losing + // a file the code successfully wrote is worse than refusing the harvest. + expect((result.collectedFiles ?? []).map((file) => file.relativePath).sort()).toEqual([ + 'l1/l2/l3/l4/l5/leaf.txt', + 'l1/l2/l3/l4/leaf.txt', + 'l1/l2/l3/leaf.txt', + 'l1/l2/leaf.txt', + 'l1/leaf.txt', + ]) + }, + CASE_TIMEOUT_MS + ) + + it( + 'probe: a file name containing a newline survives the listing', + async () => { + const result = await executeInSandbox({ + code: [ + 'import os', + `out = ${JSON.stringify(SANDBOX_OUTPUT_DIR)}`, + `open(os.path.join(out, 'we\\nird.txt'), 'w').write('newline name')`, + pythonResult('"newline"'), + ].join('\n'), + language: CodeLanguage.Python, + timeoutMs: RUN_TIMEOUT_MS, + outputSandboxDir: SANDBOX_OUTPUT_DIR, + }) + + expect(result.error).toBeUndefined() + // A structured listing has no delimiter to corrupt, unlike the `find` + // manifest this deliberately avoids. + expect(result.collectedFiles).toHaveLength(1) + expect(decode(result.collectedFiles![0].contentBase64).toString('utf8')).toBe('newline name') + }, + CASE_TIMEOUT_MS + ) + + it( + 'names the cause when user code deletes the output directory', + async () => { + await expect( + executeInSandbox({ + code: [ + 'import shutil', + `shutil.rmtree(${JSON.stringify(SANDBOX_OUTPUT_DIR)})`, + pythonResult('"deleted"'), + ].join('\n'), + language: CodeLanguage.Python, + timeoutMs: RUN_TIMEOUT_MS, + outputSandboxDir: SANDBOX_OUTPUT_DIR, + }) + // Without this the caller sees a raw `lstat ... no such file or + // directory`, which reads like a platform fault rather than their own + // `rmtree`. + ).rejects.toThrow(/no longer exists — the code deleted it/) + }, + CASE_TIMEOUT_MS + ) + + it( + 'round-trips awkward file names', + async () => { + const result = await executeInSandbox({ + code: [ + 'import os', + `out = ${JSON.stringify(SANDBOX_OUTPUT_DIR)}`, + "open(os.path.join(out, 'Q4 Sales (Final).csv'), 'w').write('a,b')", + "open(os.path.join(out, 'rapport-café.txt'), 'w', encoding='utf-8').write('café')", + "open(os.path.join(out, 'archive.tar.gz'), 'wb').write(b'\\x1f\\x8b\\x08')", + "open(os.path.join(out, 'noext'), 'wb').write(b'\\x00\\x01\\x02')", + pythonResult('"named"'), + ].join('\n'), + language: CodeLanguage.Python, + timeoutMs: RUN_TIMEOUT_MS, + outputSandboxDir: SANDBOX_OUTPUT_DIR, + }) + + expect(result.error).toBeUndefined() + const byPath = new Map((result.collectedFiles ?? []).map((file) => [file.relativePath, file])) + expect([...byPath.keys()].sort()).toEqual([ + 'Q4 Sales (Final).csv', + 'archive.tar.gz', + 'noext', + 'rapport-café.txt', + ]) + // Extension-less and gzip content must survive: neither is in the + // allowlist that decides encoding for a declared output path. + expect(decode(byPath.get('noext')!.contentBase64)).toEqual(Buffer.from([0, 1, 2])) + expect(decode(byPath.get('archive.tar.gz')!.contentBase64)).toEqual( + Buffer.from([0x1f, 0x8b, 0x08]) + ) + expect(decode(byPath.get('rapport-café.txt')!.contentBase64).toString('utf8')).toBe('café') + }, + CASE_TIMEOUT_MS + ) +}) diff --git a/apps/sim/lib/execution/remote-sandbox/sandbox-paths.ts b/apps/sim/lib/execution/remote-sandbox/sandbox-paths.ts new file mode 100644 index 00000000000..d6bddf3eeb1 --- /dev/null +++ b/apps/sim/lib/execution/remote-sandbox/sandbox-paths.ts @@ -0,0 +1,106 @@ +/** + * Filesystem contract shared by every layer that touches a sandbox mount: the + * resolver that plans mount paths, the sandbox layer that creates the output + * directory and enumerates it, and the tool description that teaches a model + * where to write. + * + * Deliberately under `/tmp` rather than a home directory. E2B's default user is + * `user` with workdir `/home/user`, but the Daytona image is built from + * `python:3.13-slim-trixie` with no `useradd`, `USER`, or `WORKDIR`, so + * `/home/user` does not exist there and Daytona resolves relative paths against + * its own working directory. `/tmp` is present and writable by any user on any + * Linux image, which keeps one literal correct on both providers — and lets the + * tool description name that literal to the model instead of a path that has to + * be resolved per provider before it can be quoted. + */ + +/** + * Where mounted input files are materialized before user code runs. + * + * Both directories sit under `/tmp/sim/`, while the runtime's own scratch files + * (`/tmp/.sim-private-input-*`, `/tmp/.sim-env-*`, `/tmp/.sim-command-*`) are + * dotfiles at the `/tmp` root — so enumerating the output directory cannot reach + * them. + */ +export const SANDBOX_INPUT_DIR = '/tmp/sim/inputs' + +/** Files user code writes here are harvested back as platform file objects. */ +export const SANDBOX_OUTPUT_DIR = '/tmp/sim/outputs' + +/** + * Sentinel written to bring the output directory into existence before user code + * runs, and skipped when the directory is harvested. + * + * A directory cannot be created through the providers' filesystem APIs directly, + * but writing a file creates its parents — the same trick the Copilot directory + * mount already uses to materialize an empty folder. Doing it this way keeps the + * cost at one filesystem write; a `mkdir -p` command would instead cost a whole + * session on Daytona, which creates and tears one down per command. + * + * The suffix is not decoration: the harvest filters this name out, so a plainer + * one like `.sim-keep` would silently swallow a user file that happened to share + * it. + */ +export const SANDBOX_OUTPUT_DIR_SENTINEL = '.sim-keep-97f2c1a4' + +/** + * How deep the output directory is enumerated, counted in path segments — a file + * at `a/b/leaf.txt` is depth 3. + * + * Set far above any plausible layout rather than close to it, because the + * providers' listings take a depth and give no signal that they stopped. A file + * below the limit is one the code successfully wrote and the caller never + * receives, so the harvest also refuses outright when it sees a directory + * sitting at the limit — that entry is the evidence the listing was cut short. + */ +export const SANDBOX_OUTPUT_DIR_MAX_DEPTH = 12 + +/** + * How many files one Function block invocation may mount. Far below the Copilot + * ceiling: a block names its inputs one at a time, so a large count is a mistake + * rather than a legitimate bulk mount. + * + * Lives here, with the other mount bounds, because the boundary contract needs it + * too — and this module imports nothing, so a contract can read it without + * pulling the server-only mount resolver into a client-reachable graph. + */ +export const MAX_BLOCK_MOUNTED_FILES = 20 + +/** Trailing-slash-insensitive directory prefix, for joining and stripping. */ +function withTrailingSlash(dir: string): string { + return dir.endsWith('/') ? dir : `${dir}/` +} + +/** + * Resolves one provider directory entry to an absolute path plus its path + * relative to the listed directory. + * + * Providers disagree on whether a listing reports absolute or directory-relative + * paths, and Daytona resolves relative paths against its own working directory + * rather than the listed one — so a relative entry is joined to the directory we + * asked for instead of being trusted as-is. Returns null when the result escapes + * that directory, which is what keeps a `..` component in a provider-reported + * name from reaching a reader. + */ +export function resolveSandboxDirectoryEntryPath( + dir: string, + reportedPath: string +): { path: string; relativePath: string } | null { + const prefix = withTrailingSlash(dir) + const absolute = reportedPath.startsWith('/') ? reportedPath : `${prefix}${reportedPath}` + + const segments: string[] = [] + for (const segment of absolute.split('/')) { + if (segment === '' || segment === '.') continue + if (segment === '..') { + if (segments.length === 0) return null + segments.pop() + continue + } + segments.push(segment) + } + const normalized = `/${segments.join('/')}` + + if (!normalized.startsWith(prefix)) return null + return { path: normalized, relativePath: normalized.slice(prefix.length) } +} diff --git a/apps/sim/lib/execution/remote-sandbox/types.ts b/apps/sim/lib/execution/remote-sandbox/types.ts index c2f4e7b2b28..2010c3cee2e 100644 --- a/apps/sim/lib/execution/remote-sandbox/types.ts +++ b/apps/sim/lib/execution/remote-sandbox/types.ts @@ -18,7 +18,20 @@ export type SandboxProviderId = 'e2b' | 'daytona' */ export type SandboxFile = | { type?: 'content'; path: string; content: string; encoding?: 'base64' } - | { type: 'url'; path: string; url: string } + | { + type: 'url' + path: string + url: string + /** + * Ceiling enforced on the bytes actually transferred, rather than on a size + * the caller reported. A caller's pre-read check is a fast, well-worded + * failure; this is what makes it true when the recorded size understates + * the stored object. Optional only because it crosses the wire; a mount + * that omits it still gets `MAX_SANDBOX_URL_MOUNT_BYTES`, so the cap + * cannot be skipped by omission. + */ + maxBytes?: number + } /** * An internal runtime payload materialized at an opaque sandbox path. @@ -47,6 +60,12 @@ export interface SandboxExecutionRequest { * (mothership-docs) that has python-pptx/docx/openpyxl/reportlab installed. */ sandboxKind?: 'code' | 'mothership' | 'doc' + /** + * Harvest every regular file under this directory after the code succeeds. + * Unlike {@link outputSandboxPaths}, the paths are discovered rather than + * declared, so a model that only authors `code` can still return files. + */ + outputSandboxDir?: string /** Scope for {@link sandboxId}; a sandbox from another workspace is rejected. */ workspaceId?: string /** Workspace sandbox whose dependency set this execution runs against. */ @@ -70,6 +89,8 @@ export interface SandboxShellExecutionRequest { * they run in the doc image (mothership-docs). */ sandboxKind?: 'shell' | 'mothership' | 'doc' + /** See {@link SandboxExecutionRequest.outputSandboxDir}. */ + outputSandboxDir?: string /** Scope for {@link sandboxId}; a sandbox from another workspace is rejected. */ workspaceId?: string /** Workspace sandbox whose dependency set this execution runs against. */ @@ -85,6 +106,24 @@ export interface SandboxExecutionResult { error?: string exportedFileContent?: string exportedFiles?: Record + /** + * Files discovered under {@link SandboxExecutionRequest.outputSandboxDir}. + * + * Always base64, never utf8: the extension allowlist that decides encoding for + * a declared path cannot classify an arbitrary harvested filename, and + * decoding real binary as utf8 substitutes U+FFFD silently — corruption that + * arrives looking like a valid file. Base64 is lossless for any byte + * sequence, and the byte budget is enforced on the decoded length. + */ + collectedFiles?: SandboxCollectedFile[] +} + +/** One harvested output file, carried as base64 with its decoded length. */ +export interface SandboxCollectedFile { + path: string + relativePath: string + contentBase64: string + byteLength: number } /** Result of one command run inside a sandbox. */ @@ -180,9 +219,50 @@ export interface SandboxHandle { * delivered without any shell parsing. */ writeFile(path: string, content: string | ArrayBuffer): Promise + /** + * Lists regular files under a directory, recursively to `depth`. + * + * Uses each provider's filesystem API rather than shelling out to `find`. + * A shell listing would cost a session per call on Daytona (its + * `runCommand` creates one, writes an env file, executes, then deletes it), + * depend on GNU coreutils that a future base image need not carry, and be + * corrupted by a filename containing a newline — which user code controls. + * + * Symlinks are followed, not excluded. Daytona's listing resolves them and + * reports no field distinguishing one from a regular file, so excluding them + * is only possible on E2B — and doing it there alone would be a cross-provider + * divergence that reads as a security property while providing none. It + * provides none because the harvest is not a privilege boundary: it runs as + * the same identity as the code, which can already read any file the sandbox + * can and copy the bytes into the output directory itself. + * + * Directories are returned alongside files rather than filtered out, because + * a directory sitting at the traversal limit is the only evidence that the + * listing was cut short — see the truncation check in the harvest. + * + * Errors propagate rather than degrading to an empty list. The output + * directory is created before user code runs, so a listing failure is a real + * fault, and reporting it as "produced nothing" would turn a transient + * provider error into silent loss of the caller's files. + */ + listFiles(path: string, options?: { depth?: number }): Promise kill(): Promise } +/** One entry discovered by {@link SandboxHandle.listFiles}. */ +export interface SandboxDirectoryEntry { + /** Absolute path inside the sandbox. */ + path: string + /** Path relative to the listed directory, retaining any subdirectories. */ + relativePath: string + kind: 'file' | 'directory' + /** + * Provider-reported size. Advisory only — the read re-enforces its own limit, + * since the file can change between listing and read. + */ + size: number +} + export interface CreateSandboxOptions { /** Bound at creation — see {@link SandboxHandle.runCode}. */ language?: CodeLanguage diff --git a/apps/sim/lib/execution/sim-helpers.smoke.test.ts b/apps/sim/lib/execution/sim-helpers.smoke.test.ts new file mode 100644 index 00000000000..9e66b0b4a55 --- /dev/null +++ b/apps/sim/lib/execution/sim-helpers.smoke.test.ts @@ -0,0 +1,233 @@ +/** + * @vitest-environment node + * + * The `sim.*` helper namespace, exercised in a real isolate. + * + * `isolated-vm.test.ts` mocks the spawn, so it never proves the namespace is + * reachable from user code — only that the process plumbing is called. These + * cases run the actual worker and assert a value crosses the boundary in both + * directions, which is the only way the frozen `global.sim` shim and the + * broker's JSON marshalling are covered at all. + * + * Enable with `SIM_HELPERS_SMOKE=1`. Needs `isolated-vm` installed for the + * running Node (prebuilds exist for 22/24 only; other versions source-build). + */ +import { describe, expect, it } from 'vitest' +import { executeInIsolatedVM, type IsolatedVMBrokerHandler } from '@/lib/execution/isolated-vm' + +const smokeEnabled = process.env.SIM_HELPERS_SMOKE === '1' +const CASE_TIMEOUT_MS = 60_000 + +const FILE = { + id: 'file_1', + name: 'notes.txt', + url: 'https://storage.example/notes.txt', + size: 11, + type: 'text/plain', + key: 'execution/ws/wf/exec/abc/notes.txt', + context: 'execution', +} + +/** Records what user code asked for, and answers the way the runtime does. */ +function recordingBrokers(): { + brokers: Record + calls: Array<{ name: string; args: unknown }> +} { + const calls: Array<{ name: string; args: unknown }> = [] + const record = + (name: string, reply: (args: any) => unknown): IsolatedVMBrokerHandler => + async (args: any) => { + calls.push({ name, args }) + return reply(args) + } + + return { + calls, + brokers: { + 'sim.files.readText': record('sim.files.readText', () => 'hello world'), + 'sim.files.readBase64': record('sim.files.readBase64', () => + Buffer.from('hello world').toString('base64') + ), + 'sim.files.readTextChunk': record('sim.files.readTextChunk', (args) => ({ + content: 'hello'.slice(0, args?.options?.length ?? 5), + offset: args?.options?.offset ?? 0, + })), + 'sim.values.read': record('sim.values.read', () => ({ rows: [1, 2, 3] })), + 'sim.values.readArray': record('sim.values.readArray', () => [{ a: 1 }, { a: 2 }]), + }, + } +} + +function run(code: string, brokers: Record) { + return executeInIsolatedVM( + { + code, + params: {}, + envVars: {}, + contextVariables: { simFile: FILE }, + timeoutMs: 20_000, + requestId: 'sim-helpers-smoke', + }, + { brokers } + ) +} + +describe.skipIf(!smokeEnabled)('sim.* helpers in a real isolate', () => { + it( + 'exposes sim.files reads to user code and returns their values', + async () => { + const { brokers, calls } = recordingBrokers() + + const result = await run( + [ + 'const text = await sim.files.readText(simFile)', + 'const b64 = await sim.files.readBase64(simFile)', + 'return { text, b64 }', + ].join('\n'), + brokers + ) + + expect(result.error).toBeUndefined() + expect(result.result).toEqual({ + text: 'hello world', + b64: Buffer.from('hello world').toString('base64'), + }) + // The file object must cross intact — the broker authorizes on its `key`, + // so a shim that dropped fields would fail open at the wrong layer. + expect(calls.map((call) => call.name)).toEqual(['sim.files.readText', 'sim.files.readBase64']) + expect((calls[0].args as { file: typeof FILE }).file).toEqual(FILE) + }, + CASE_TIMEOUT_MS + ) + + it( + 'passes options through and returns structured chunk results', + async () => { + const { brokers, calls } = recordingBrokers() + + const result = await run( + 'return await sim.files.readTextChunk(simFile, { offset: 0, length: 5 })', + brokers + ) + + expect(result.error).toBeUndefined() + expect(result.result).toEqual({ content: 'hello', offset: 0 }) + expect((calls[0].args as { options: unknown }).options).toEqual({ offset: 0, length: 5 }) + }, + CASE_TIMEOUT_MS + ) + + it( + 'exposes sim.values reads for offloaded large values', + async () => { + const { brokers } = recordingBrokers() + + const result = await run( + [ + 'const value = await sim.values.read({ __simLargeValueRef: true })', + 'const rows = await sim.values.readArray({ __simLargeValueRef: true })', + 'return { value, rowCount: rows.length }', + ].join('\n'), + brokers + ) + + expect(result.error).toBeUndefined() + expect(result.result).toEqual({ value: { rows: [1, 2, 3] }, rowCount: 2 }) + }, + CASE_TIMEOUT_MS + ) + + it( + 'surfaces a broker rejection as an ordinary error the code can catch', + async () => { + const brokers: Record = { + 'sim.files.readText': async () => { + throw new Error('File is not available in this execution.') + }, + } + + const result = await run( + [ + 'try {', + ' await sim.files.readText(simFile)', + ' return { caught: false }', + '} catch (error) {', + ' return { caught: true, message: String(error.message) }', + '}', + ].join('\n'), + brokers + ) + + // A denied read has to reach user code as a catchable error, not kill the + // isolate — the same file may be optional to the script. + expect(result.error).toBeUndefined() + expect(result.result).toMatchObject({ caught: true }) + expect((result.result as { message: string }).message).toContain('not available') + }, + CASE_TIMEOUT_MS + ) + + it( + 'pins which globals the fast local runtime actually provides', + async () => { + const { brokers } = recordingBrokers() + + const result = await run( + [ + 'const names = ["sim","fetch","console","JSON","Uint8Array",', + ' "Buffer","require","process","atob","TextDecoder","crypto","setTimeout"]', + 'const out = {}', + 'for (const name of names) out[name] = typeof globalThis[name] !== "undefined"', + 'return out', + ].join('\n'), + brokers + ) + + expect(result.error).toBeUndefined() + // The isolate/sandbox split made concrete. The fast runtime is plain + // ECMAScript plus `fetch` and `sim.*` — no Node built-ins, and notably no + // `crypto`, `TextDecoder`, or even `setTimeout`. Reaching for any of them + // is what makes a block need an import, which is what moves it to the + // slower remote sandbox. The block tip documents exactly this list, so + // pin it here rather than letting it drift. + expect(result.result).toEqual({ + sim: true, + fetch: true, + console: true, + JSON: true, + Uint8Array: true, + Buffer: false, + require: false, + process: false, + atob: false, + TextDecoder: false, + crypto: false, + setTimeout: false, + }) + }, + CASE_TIMEOUT_MS + ) + + it( + 'freezes the namespace so user code cannot replace a helper', + async () => { + const { brokers } = recordingBrokers() + + const result = await run( + [ + 'let replaced = true', + 'try { sim.files.readText = () => "spoofed" } catch { replaced = false }', + 'const text = await sim.files.readText(simFile)', + 'return { replaced, text }', + ].join('\n'), + brokers + ) + + expect(result.error).toBeUndefined() + // Whether the assignment throws or is silently ignored, the real helper + // must still be the one that runs. + expect((result.result as { text: string }).text).toBe('hello world') + }, + CASE_TIMEOUT_MS + ) +}) diff --git a/apps/sim/lib/function-execution/execute-request.test.ts b/apps/sim/lib/function-execution/execute-request.test.ts index 2fd1b35eaa5..cdba883bb08 100644 --- a/apps/sim/lib/function-execution/execute-request.test.ts +++ b/apps/sim/lib/function-execution/execute-request.test.ts @@ -143,6 +143,34 @@ vi.mock('@/lib/uploads', () => ({ vi.mock('@/lib/workflows/utils', () => workflowsUtilsMock) +/** + * Only the I/O half is stubbed. Path naming, transports, ceilings and + * authorization are covered against the real implementation in + * `sandbox-mounts.test.ts`; what matters here is the wiring — that a marker + * becomes a mount and that the context variable ends up holding the path. + */ +vi.mock('@/lib/function-execution/sandbox-mounts', () => ({ + planUserFileMounts: (files: Array<{ key: string; name: string }>) => + files.map((userFile) => ({ userFile, mountPath: `/tmp/sim/inputs/${userFile.name}` })), + resolveUserFileMounts: async ({ + planned, + }: { + planned: Array<{ userFile: { name: string }; mountPath: string }> + }) => ({ + sandboxFiles: planned.map(({ mountPath }) => ({ + type: 'url' as const, + path: mountPath, + url: 'https://presigned.example/object', + })), + manifest: planned.map(({ userFile, mountPath }) => ({ + name: userFile.name, + path: mountPath, + size: 1, + type: 'application/pdf', + })), + }), +})) + import { validateProxyUrl } from '@/lib/core/security/input-validation' import { clearLargeValueCacheForTests } from '@/lib/execution/payloads/cache' import { isLargeArrayManifest } from '@/lib/execution/payloads/large-array-manifest-metadata' @@ -192,6 +220,25 @@ async function POST(request: NextRequest): Promise { afterAll(resetEnvFlagsMock) +/** + * A `` reference as it reaches the function runtime: the resolver + * leaves a mount marker in the context variables, which is what asks this run for a + * sandbox filesystem. + */ +const MOUNT_REF = { + __simSandboxFileMount: true, + version: 1, + file: { + id: 'file_1', + name: 'doc.pdf', + url: 'https://storage.example/doc.pdf', + size: 12, + type: 'application/pdf', + key: 'execution/workspace-1/wf-1/exec-1/abc/doc.pdf', + context: 'execution', + }, +} + describe('Function execution request', () => { beforeEach(() => { vi.clearAllMocks() @@ -1500,7 +1547,7 @@ describe('Function execution request', () => { expect(mockWriteWorkspaceFileByPath).not.toHaveBeenCalled() }) - it('rejects sandboxPath outputs when the call would run in isolated-vm (E2B enabled, JS without imports)', async () => { + it('routes plain JavaScript to the remote sandbox when it declares a sandboxPath output', async () => { envFlagsMock.isRemoteSandboxEnabled = true const req = createMockRequest('POST', { @@ -1518,6 +1565,25 @@ describe('Function execution request', () => { }, }) + await POST(req) + + // Needing a sandbox filesystem selects the remote runtime the same way a + // selected sandbox image does. Refusing here instead would dead-end the + // caller: "add an import" is not a fix anyone should have to discover. + expect(mockExecuteInSandbox).toHaveBeenCalled() + expect(mockExecuteInIsolatedVM).not.toHaveBeenCalled() + }) + + it('refuses sandbox file inputs/outputs when no remote sandbox is configured', async () => { + envFlagsMock.isRemoteSandboxEnabled = false + + const req = createMockRequest('POST', { + code: 'return "content"', + language: 'javascript', + workspaceId: 'workspace-1', + contextVariables: { doc: MOUNT_REF }, + }) + const response = await POST(req) const data = await response.json() @@ -1529,6 +1595,201 @@ describe('Function execution request', () => { expect(mockWriteWorkspaceFileByPath).not.toHaveBeenCalled() }) + it('refuses sandbox file inputs/outputs for a custom tool, which always runs in isolated-vm', async () => { + envFlagsMock.isRemoteSandboxEnabled = true + + const req = createMockRequest('POST', { + code: 'return "content"', + language: 'javascript', + workspaceId: 'workspace-1', + isCustomTool: true, + contextVariables: { doc: MOUNT_REF }, + }) + + const response = await POST(req) + const data = await response.json() + + expect(response.status).toBe(422) + expect(data.success).toBe(false) + expect(data.error).toContain('custom tools always run in the isolated JavaScript VM') + expect(mockExecuteInSandbox).not.toHaveBeenCalled() + }) + + it('reports a harvest the sandbox refused as a 400 carrying its reason', async () => { + envFlagsMock.isRemoteSandboxEnabled = true + mockExecuteInSandbox.mockRejectedValueOnce( + Object.assign(new Error('Sandbox produced 21 files in /tmp/sim/outputs'), { + code: 'sandbox_output_not_exportable', + }) + ) + + const req = createMockRequest('POST', { + code: 'x', + language: 'python', + workspaceId: 'workspace-1', + }) + + const response = await POST(req) + const data = await response.json() + + // Writing too many files is the caller's to fix, so it must not surface + // as an opaque 500 that hides the count and the remedy. + expect(response.status).toBe(400) + expect(data.error).toContain('21 files') + }) + + it('scans a harvested plaintext secret even under a binary file name', async () => { + envFlagsMock.isRemoteSandboxEnabled = true + mockExecuteInSandbox.mockResolvedValueOnce({ + result: null, + stdout: '', + sandboxId: 'sbx', + collectedFiles: [ + { + path: '/tmp/sim/outputs/leak.png', + relativePath: 'leak.png', + // Valid UTF-8 carrying the resolved secret, named as an image. + contentBase64: Buffer.from('token=super-secret-value').toString('base64'), + byteLength: 24, + }, + ], + }) + + const req = createMockRequest('POST', { + // The placeholder has to be in the code: compiling it is what puts the + // resolved value in scope for the output scan. + code: 'token = {{MY_SECRET}}', + language: 'python', + workspaceId: 'workspace-1', + workflowId: 'workflow-1', + executionId: 'execution-1', + envVars: { MY_SECRET: 'super-secret-value' }, + }) + + const response = await POST(req) + const data = await response.json() + + // Classifying by file name let a secret written as plaintext under a + // binary extension skip the only provenance guard and be returned with a + // downloadable URL. Content decides now, so the name cannot dodge it. + expect(response.status).toBe(400) + expect(data.error).toContain('leak.png') + expect(data.error).toContain('resolved secret') + }) + + it('scans a harvested secret even when one invalid byte makes it non-UTF-8', async () => { + envFlagsMock.isRemoteSandboxEnabled = true + mockExecuteInSandbox.mockResolvedValueOnce({ + result: null, + stdout: '', + sandboxId: 'sbx', + collectedFiles: [ + { + path: '/tmp/sim/outputs/mixed.bin', + relativePath: 'mixed.bin', + // Literal secret plus one invalid byte, so the buffer is not valid + // UTF-8 — which used to be enough to skip the scan entirely. + contentBase64: Buffer.concat([ + Buffer.from('token=super-secret-value'), + Buffer.from([0xff]), + ]).toString('base64'), + byteLength: 25, + }, + ], + }) + + const req = createMockRequest('POST', { + code: 'token = {{MY_SECRET}}', + language: 'python', + workspaceId: 'workspace-1', + workflowId: 'workflow-1', + executionId: 'execution-1', + envVars: { MY_SECRET: 'super-secret-value' }, + }) + + const response = await POST(req) + const data = await response.json() + + // A lossy UTF-8 decode keeps ASCII runs intact, so the literal is still + // there to find — appending a byte must not buy an exemption. + expect(response.status).toBe(400) + expect(data.error).toContain('mixed.bin') + expect(data.error).toContain('resolved secret') + }) + + it('mounts a reference and hands the code its path', async () => { + envFlagsMock.isRemoteSandboxEnabled = true + + const req = createMockRequest('POST', { + code: 'x', + language: 'python', + workspaceId: 'workspace-1', + workflowId: 'workflow-1', + executionId: 'execution-1', + contextVariables: { doc: MOUNT_REF }, + }) + + await POST(req) + + const call = mockExecuteInSandbox.mock.calls[0]?.[0] + expect(call.sandboxFiles).toEqual([ + { type: 'url', path: '/tmp/sim/inputs/doc.pdf', url: 'https://presigned.example/object' }, + ]) + // The marker must not survive into the code's view of the variable — the + // whole point is that every language sees a plain path string. + const runtimePayload = call.privateInputs + .map((input: { content: string }) => input.content) + .find((content: string) => content.includes('contextVariables')) + expect(runtimePayload).toContain('/tmp/sim/inputs/doc.pdf') + expect(runtimePayload).not.toContain('__simSandboxFileMount') + }) + + it('harvests the output directory on every remote run, with no toggle', async () => { + envFlagsMock.isRemoteSandboxEnabled = true + + const req = createMockRequest('POST', { + code: 'x', + language: 'python', + workspaceId: 'workspace-1', + }) + + await POST(req) + + expect(mockExecuteInSandbox.mock.calls[0]?.[0].outputSandboxDir).toBe('/tmp/sim/outputs') + }) + + it('does not ask for an output directory on an isolate run', async () => { + envFlagsMock.isRemoteSandboxEnabled = true + + const req = createMockRequest('POST', { + code: 'return 1', + language: 'javascript', + workspaceId: 'workspace-1', + }) + + await POST(req) + + // Harvesting is free only because it rides an existing sandbox; an + // isolate run must not gain one just to look for files. + expect(mockExecuteInSandbox).not.toHaveBeenCalled() + expect(mockExecuteInIsolatedVM).toHaveBeenCalled() + }) + + it('leaves a plain JavaScript call with no file inputs or outputs in isolated-vm', async () => { + envFlagsMock.isRemoteSandboxEnabled = true + + const req = createMockRequest('POST', { + code: 'return "content"', + language: 'javascript', + workspaceId: 'workspace-1', + }) + + await POST(req) + + expect(mockExecuteInIsolatedVM).toHaveBeenCalled() + expect(mockExecuteInSandbox).not.toHaveBeenCalled() + }) + it('rejects sandbox file mounts when the call would run in isolated-vm', async () => { const req = createMockRequest('POST', { code: 'return 1', diff --git a/apps/sim/lib/function-execution/execute-request.ts b/apps/sim/lib/function-execution/execute-request.ts index 443a3fdc0e1..73ef60c28d5 100644 --- a/apps/sim/lib/function-execution/execute-request.ts +++ b/apps/sim/lib/function-execution/execute-request.ts @@ -58,6 +58,10 @@ import { readUserFileContent, unavailableLargeValueError, } from '@/lib/execution/payloads/materialization.server' +import { + collectSandboxFileMountRefs, + replaceSandboxFileMountRefs, +} from '@/lib/execution/payloads/sandbox-file-mount-ref' import { compactExecutionPayload } from '@/lib/execution/payloads/serializer' import { materializeLargeValueRef } from '@/lib/execution/payloads/store' import { @@ -76,20 +80,31 @@ import { import { isSandboxOutputFileError, isSandboxOutputLimitError, + isSandboxOutputNotExportableError, MAX_SANDBOX_OUTPUT_BYTES, } from '@/lib/execution/remote-sandbox/output-limits' +import { + MAX_BLOCK_MOUNTED_FILES, + SANDBOX_OUTPUT_DIR, +} from '@/lib/execution/remote-sandbox/sandbox-paths' +import type { SandboxCollectedFile, SandboxFile } from '@/lib/execution/remote-sandbox/types' import { isExecutionResourceLimitError } from '@/lib/execution/resource-errors' +import { planUserFileMounts, resolveUserFileMounts } from '@/lib/function-execution/sandbox-mounts' +import { uploadExecutionFile } from '@/lib/uploads/contexts/execution/execution-file-manager' import { EXACT_EMPTY_WORKSPACE_FILE_SECRET_PROVENANCE, mergeWorkspaceFileSecretProvenance, type WorkspaceFileSecretProvenance, } from '@/lib/uploads/contexts/workspace/workspace-file-secret-provenance' +import { deleteFiles } from '@/lib/uploads/core/storage-service' +import { getFileExtension, getMimeTypeFromExtension } from '@/lib/uploads/utils/file-utils' import { getWorkflowById } from '@/lib/workflows/utils' import { rebindWorkspaceFileDelegatedPrincipal } from '@/lib/workspace-files/application/delegated-principal' import { fileOperations } from '@/lib/workspace-files/application/operations' import { readWorkspaceFileContent } from '@/lib/workspace-files/application/read-workspace-file-content' import { resolveWorkspaceFileReference } from '@/lib/workspace-files/application/resolve-workspace-file-reference' -import { escapeRegExp, normalizeName, REFERENCE } from '@/executor/constants' +import { escapeRegExp, normalizeName, REFERENCE, sanitizeFileName } from '@/executor/constants' +import type { UserFile } from '@/executor/types' import { type OutputSchema, resolveBlockReference } from '@/executor/utils/block-reference' import { createReferencePattern, @@ -100,6 +115,7 @@ import { type ResolvedSecretMatcher, scanResolvedSecretString, } from '@/executor/utils/resolved-secret-content-projection' +import { isNonIdentifyingSecretLiteral } from '@/executor/utils/resolved-secret-match-policy' import type { ResolvedSecretTraceProvenanceV1 } from '@/executor/utils/resolved-secret-trace-registry' const logger = createLogger('FunctionExecuteAPI') @@ -1202,11 +1218,25 @@ function activateReferencedSecretProvenance(context: FunctionRouteExecutionConte } } -/** Compiled secret names that still demand redaction — the exempt ones don't count. */ +/** + * Compiled secret names that still demand redaction, and whose value a scan could + * actually find. Exempt names don't count. + * + * Non-identifying literals are excluded on the same predicate + * {@link createResolvedSecretMatcher} uses to drop them, because the two decisions + * have to agree. When every in-scope value is shorter than the substitutable-literal + * minimum, the matcher builds nothing and returns `undefined`; a counter that still + * reported those names would send + * {@link getOutputFileSecretProvenance} down its no-matcher branch and classify + * every output as `unknown` — failing an export while claiming it contains a + * secret that, by that very policy, is too short to be attributed to anything. + */ function countProtectedOutputSecretNames(context: FunctionRouteExecutionContext): number { let count = 0 - for (const name of context.outputSecretPlaintextsByName.keys()) { - if (!context.unredactedSecretNames.has(name)) count += 1 + for (const [name, plaintext] of context.outputSecretPlaintextsByName) { + if (context.unredactedSecretNames.has(name)) continue + if (isNonIdentifyingSecretLiteral(plaintext)) continue + count += 1 } return count } @@ -1824,6 +1854,179 @@ async function maybeExportSandboxFilesToWorkspace(args: { }) } +/** + * Combines caller-supplied mounts — Copilot resolves its own workspace paths — + * with those resolved from platform file objects. + * + * A duplicate destination is rejected rather than settled by order: + * `writeSandboxInputs` materializes in sequence, so the later entry would + * silently overwrite the earlier one and the code would find something other + * than what it asked for at that path. + */ +function mergeSandboxFileMounts( + callerFiles: SandboxFile[] | undefined, + resolvedFiles: SandboxFile[] +): SandboxFile[] | undefined { + if (!callerFiles?.length) return resolvedFiles.length > 0 ? resolvedFiles : undefined + if (resolvedFiles.length === 0) return callerFiles + + const merged = [...callerFiles, ...resolvedFiles] + const seen = new Set() + for (const file of merged) { + if (seen.has(file.path)) { + throw new Error(`Duplicate sandbox mount path: ${file.path}`) + } + seen.add(file.path) + } + return merged +} + +/** + * A harvested file's name, derived from its path relative to the output + * directory. Subdirectories are folded into the name rather than dropped, so + * `reports/q4.csv` and `q4.csv` stay distinguishable — and a `/` never survives + * into a name that later reaches an email attachment or an upload filename. + */ +function collectedFileName(relativePath: string): string { + return sanitizeFileName(relativePath.split('/').filter(Boolean).join('-')) || 'file' +} + +/** + * Persists files harvested from the sandbox output directory as platform file + * objects, so any downstream tool that accepts a file can consume them. + * + * Uploaded here, one at a time, rather than handed to the declarative + * file-output pipeline as bytes: that path would carry the whole export budget + * as base64 through `JSON.stringify`, a response buffer, and a re-parse, so + * several multiples of the payload would be live at once for a value that is a + * couple of hundred bytes per file once stored. + */ +/** + * Removes files already uploaded when a later one in the same harvest is refused. + * + * The route answers with a failure and hands back no references, so anything + * uploaded before the refusal is unreachable — but it still occupies storage, + * and the harvest is all-or-nothing by design. Best-effort on purpose: the + * caller needs to hear why its export was refused, not that the tidy-up failed. + */ +async function discardUploadedExecutionFiles(files: readonly UserFile[]): Promise { + if (files.length === 0) return + try { + await deleteFiles( + files.map((file) => file.key), + 'execution' + ) + } catch (error) { + logger.warn('Could not remove partially uploaded sandbox output files', { + fileCount: files.length, + error: getErrorMessage(error), + }) + } +} + +async function collectExecutionOutputFiles(args: { + routeContext: FunctionRouteExecutionContext + authUserId: string + workflowId?: string + workspaceId?: string + executionId?: string + collectedFiles: SandboxCollectedFile[] + stdout: string + executionTime: number +}): Promise<{ files: UserFile[] } | { response: NextResponse }> { + const { routeContext, collectedFiles } = args + if (collectedFiles.length === 0) return { files: [] } + + const resolvedWorkspaceId = + args.workspaceId || + (args.workflowId ? (await getWorkflowById(args.workflowId))?.workspaceId : undefined) + + // Fails rather than returning an empty list: the code did produce files, and + // reporting success without them would read as "your script wrote nothing". + if (!resolvedWorkspaceId || !args.workflowId || !args.executionId) { + return { + response: exportFailure( + 'Workspace, workflow, and execution context are required to return files from the sandbox.', + 400, + args.stdout, + args.executionTime + ), + } + } + + const files: UserFile[] = [] + // The harvest is all-or-nothing, so a throw partway through has to take the + // uploads that already succeeded with it. Without this they linger in storage + // with nothing referencing them, since the failure response carries no keys. + try { + for (const collected of args.collectedFiles) { + const buffer = Buffer.from(collected.contentBase64, 'base64') + const name = collectedFileName(collected.relativePath) + const mimeType = getMimeTypeFromExtension(getFileExtension(name)) + + // Scanned unconditionally — never gated on whether the bytes look textual. + // Both a filename check and a UTF-8 round-trip were trivially defeated: name + // the file `.png`, or append one invalid byte, and a plaintext secret sailed + // past. A lossy UTF-8 decode preserves ASCII runs, so a literal secret is + // findable in any buffer, textual or not. + // + // What stays out of reach is a secret carried in transformed form — deflated + // inside a PDF, re-encoded — which no substring scan can see. That is an + // inherent limit of scanning, not a hole in the gate, and it is why these + // files are execution-scoped rather than durable workspace files. + { + const provenance = await getOutputFileSecretProvenance(buffer, false, routeContext, { + userId: args.authUserId, + workspaceId: resolvedWorkspaceId, + }) + // An execution-scoped file has nowhere to record a provenance envelope, so + // one carrying a resolved secret cannot ship under a lock the way a + // workspace file can — it is refused instead. + if (provenance.status !== 'exact' || provenance.entries.length > 0) { + await discardUploadedExecutionFiles(files) + return { + response: exportFailure( + `Sandbox output file "${name}" contains a resolved secret value and was not returned. Write the file without embedding secret values, or export it to a workspace file where its provenance can be recorded.`, + 400, + args.stdout, + args.executionTime + ), + } + } + } + + const userFile = await uploadExecutionFile( + { + workspaceId: resolvedWorkspaceId, + workflowId: args.workflowId, + executionId: args.executionId, + }, + buffer, + name, + mimeType, + args.authUserId + ) + files.push(userFile) + } + } catch (error) { + await discardUploadedExecutionFiles(files) + throw error + } + + // Registers the new keys on the execution so downstream blocks are authorized + // to read them back. + routeContext.fileKeys = [ + ...new Set([...(routeContext.fileKeys ?? []), ...files.map((file) => file.key)]), + ] + + logger.info('Returned sandbox output files', { + fileCount: files.length, + totalBytes: files.reduce((total, file) => total + file.size, 0), + }) + + return { files } +} + export interface TrustedFunctionExecutionAuth { attributedUserId: string fileAccessUserId?: string @@ -1924,6 +2127,7 @@ export async function executeFunctionRequest( allowLargeValueWorkflowScope = false, workspaceId, isCustomTool = false, + files: mountedUserFiles, _sandboxFiles, } = body @@ -1986,6 +2190,10 @@ export async function executeFunctionRequest( ) } + // Planned before the runtime is chosen because it is pure: it decides whether + // this execution needs a sandbox filesystem at all, without spending a presign + // or a byte of transfer on a request the guard below may still refuse. + const executionParams = { ...params } executionParams._context = undefined @@ -2040,6 +2248,34 @@ export async function executeFunctionRequest( ...codeResolution.contextVariables, ...preResolvedContextVariables, } + + /** + * Files this run must place on the sandbox filesystem: those a caller passed + * explicitly — how an agent supplies one, since a model cannot write a block + * reference — plus every file the code asked for with ``, + * which arrives as a marker inside the resolved context variables. + */ + const plannedFileMounts = planUserFileMounts([ + ...((mountedUserFiles ?? []) as UserFile[]), + ...collectSandboxFileMountRefs(contextVariables), + ]) + if (plannedFileMounts.length > MAX_BLOCK_MOUNTED_FILES) { + return functionJsonResponse( + { + success: false, + error: `Too many files mounted into the sandbox (${plannedFileMounts.length}). Maximum is ${MAX_BLOCK_MOUNTED_FILES}.`, + output: { result: null, stdout: '', executionTime: Date.now() - startTime }, + }, + routeContext, + { status: 400 } + ) + } + const requestsSandboxFilesystem = + plannedFileMounts.length > 0 || + Boolean(_sandboxFiles?.length) || + outputSandboxPaths.length > 0 || + Boolean(outputSandboxPath) + const compilation = await compileCodePlaceholders({ code: codeResolution.resolvedCode, language: lang, @@ -2104,13 +2340,143 @@ export async function executeFunctionRequest( hasImports = jsImports.trim().length > 0 || extractionResult.hasRequireCalls } - if (lang === CodeLanguage.Shell) { - if (!remoteSandboxEnabled) { - throw new Error( - 'Shell execution requires a remote code sandbox to be enabled. Please contact your administrator to enable it.' - ) - } + if (lang === CodeLanguage.Shell && !remoteSandboxEnabled) { + throw new Error( + 'Shell execution requires a remote code sandbox to be enabled. Please contact your administrator to enable it.' + ) + } + + if (lang === CodeLanguage.Python && !remoteSandboxEnabled) { + throw new Error( + 'Python execution requires a remote code sandbox to be enabled. Please contact your administrator to enable it, or use JavaScript instead.' + ) + } + + if (lang === CodeLanguage.JavaScript && hasImports && !remoteSandboxEnabled) { + throw new Error( + 'JavaScript code with import statements requires a remote code sandbox to be enabled. Please remove the import statements, or contact your administrator to enable it.' + ) + } + + /** + * Mounting files or harvesting outputs needs a real filesystem, so it selects + * the remote sandbox the same way a selected sandbox image does. Without this + * a plain-JavaScript block that merely attaches a file would land in + * isolated-vm and be refused by the guard below — a dead end, since "add an + * import" is not a fix a caller should have to discover. + */ + const useRemoteSandbox = + usesMothershipSandbox || + (remoteSandboxEnabled && + !isCustomTool && + (lang === CodeLanguage.Shell || + lang === CodeLanguage.Python || + (lang === CodeLanguage.JavaScript && + (hasImports || Boolean(selectedSandboxId) || requestsSandboxFilesystem)))) + if (useRemoteSandbox && containsLargeValueRef(contextVariables)) { + throw new Error( + 'Large execution values require the JavaScript isolated-vm runtime. Remove imports, select a nested field, or read the value in a JavaScript function without a remote sandbox.' + ) + } + + // Sandbox file mounts and file exports only exist in the remote sandbox + // runtime; isolated-vm has no filesystem. Silently dropping a declared + // sandbox input/output here produced "export succeeded" responses with zero + // bytes written, so refuse the call instead. Widening `useRemoteSandbox` + // above means the only ways to arrive here are a deployment with no remote + // sandbox at all, or a custom tool — which is why neither remediation + // suggests switching language. + if (!useRemoteSandbox && requestsSandboxFilesystem) { + const remediation = !remoteSandboxEnabled + ? "No remote code sandbox is enabled on this deployment, so there is no sandbox filesystem for any language. Pass input data via params and return output as the code's return value with outputs.files[].path (no sandboxPath)." + : "custom tools always run in the isolated JavaScript VM, which has no sandbox filesystem. Pass input data via params and return output as the code's return value." + return functionJsonResponse( + { + success: false, + error: `Sandbox file inputs/outputs are unavailable for this call: ${remediation}`, + output: { result: null, stdout: '', executionTime: Date.now() - startTime }, + }, + routeContext, + { status: 422 } + ) + } + + // Resolved only after the guard: a request about to be refused must not mint + // presigned URLs or buffer bytes on its way out. + let resolvedMounts: Awaited> + try { + resolvedMounts = await resolveUserFileMounts({ + planned: plannedFileMounts, + context: { + principal: auth.principal, + workflowId, + workspaceId, + executionId, + largeValueExecutionIds, + largeValueKeys, + fileKeys, + allowLargeValueWorkflowScope, + userId: auth.fileAccessUserId, + requestId, + logger, + }, + }) + } catch (error) { + // Everything this can raise is about the files the caller named — a mount + // it may not read, one over a size ceiling, a set over the aggregate. The + // messages already say which file and what to do, so they are the response + // rather than a 500 that reads like the platform broke. Matches the + // too-many-files refusal above. + logger.warn(`[${requestId}] Could not resolve sandbox file mounts`, { + error: getErrorMessage(error), + }) + return functionJsonResponse( + { + success: false, + error: getErrorMessage(error, 'Could not mount the requested files into the sandbox.'), + output: { result: null, stdout: '', executionTime: Date.now() - startTime }, + }, + routeContext, + { status: 400 } + ) + } + const { sandboxFiles: userFileMounts, manifest: mountManifest } = resolvedMounts + const sandboxFiles = mergeSandboxFileMounts(_sandboxFiles, userFileMounts) + + // Every `` marker becomes the path its file was mounted at, + // so the code reads a plain string in whichever language it is written in. + const mountPathsByKey = new Map( + plannedFileMounts.map(({ userFile, mountPath }) => [userFile.key, mountPath]) + ) + for (const [name, value] of Object.entries(contextVariables)) { + contextVariables[name] = replaceSandboxFileMountRefs( + value, + (file) => mountPathsByKey.get(file.key) ?? file.name + ) + } + + // Harvested on every remote run rather than behind a switch: the directory is + // Sim's own, so nothing lands there unless the code put it there, and the cost + // is one listing on a run that already paid for a sandbox. Isolate runs never + // reach here, so they stay as fast as they were. + // + // Declared sandbox outputs opt out. That request names exactly which paths to + // export and answers with that export's own result, so harvesting alongside it + // would collect files the response has no shape to carry — they would be read, + // scanned, uploaded, and then dropped. Making the exclusion explicit here keeps + // it from resting on which branch happens to return first. + const declaresSandboxOutputs = outputFiles.some((file) => file.sandboxPath) + const outputSandboxDir = + useRemoteSandbox && !declaresSandboxOutputs ? SANDBOX_OUTPUT_DIR : undefined + + if (mountManifest.length > 0) { + logger.info(`[${requestId}] Mounted files into sandbox`, { + mountCount: mountManifest.length, + }) + } + + if (lang === CodeLanguage.Shell) { const shellEnvs: Record = {} for (const [k, v] of Object.entries(envVars)) { shellEnvs[k] = serializeForShellEnv(v) @@ -2133,14 +2499,16 @@ export async function executeFunctionRequest( error: shellError, exportedFileContent, exportedFiles, + collectedFiles: shellCollectedFiles, } = await executeShellInSandbox({ code: resolvedCode, envs: shellEnvs, timeoutMs: timeout, - sandboxFiles: _sandboxFiles, + sandboxFiles, privateInputs: compilerPrivateInputs, outputSandboxPath, outputSandboxPaths, + outputSandboxDir, workspaceId, sandboxId: selectedSandboxId, ...(usesMothershipSandbox && !selectedSandboxId @@ -2185,66 +2553,34 @@ export async function executeFunctionRequest( } } + const shellOutputFiles = await collectExecutionOutputFiles({ + routeContext, + authUserId: auth.attributedUserId, + workflowId, + workspaceId, + executionId, + collectedFiles: shellCollectedFiles ?? [], + stdout: shellStdout, + executionTime, + }) + if ('response' in shellOutputFiles) { + return appendResolvedSecretNames(shellOutputFiles.response, routeContext) + } + return functionJsonResponse( { success: true, - output: { result: shellResult ?? null, stdout: cleanStdout(shellStdout), executionTime }, + output: { + result: shellResult ?? null, + stdout: cleanStdout(shellStdout), + executionTime, + files: shellOutputFiles.files, + }, }, routeContext ) } - if (lang === CodeLanguage.Python && !remoteSandboxEnabled) { - throw new Error( - 'Python execution requires a remote code sandbox to be enabled. Please contact your administrator to enable it, or use JavaScript instead.' - ) - } - - if (lang === CodeLanguage.JavaScript && hasImports && !remoteSandboxEnabled) { - throw new Error( - 'JavaScript code with import statements requires a remote code sandbox to be enabled. Please remove the import statements, or contact your administrator to enable it.' - ) - } - - const useRemoteSandbox = - usesMothershipSandbox || - (remoteSandboxEnabled && - !isCustomTool && - (lang === CodeLanguage.Python || - (lang === CodeLanguage.JavaScript && (hasImports || Boolean(selectedSandboxId))))) - - if (useRemoteSandbox && containsLargeValueRef(contextVariables)) { - throw new Error( - 'Large execution values require the JavaScript isolated-vm runtime. Remove imports, select a nested field, or read the value in a JavaScript function without a remote sandbox.' - ) - } - - // Sandbox file mounts and sandboxPath exports only exist in the remote - // sandbox runtime; isolated-vm has no filesystem. Silently dropping a declared - // sandbox input/output here produced "export succeeded" responses with - // zero bytes written, so refuse the call instead. The remediation depends - // on WHY this call runs in isolated-vm — "switch to python" is a dead end - // when no remote sandbox is enabled or the call is a custom tool. - if ( - !useRemoteSandbox && - (outputSandboxPaths.length > 0 || outputSandboxPath || _sandboxFiles?.length) - ) { - const remediation = !remoteSandboxEnabled - ? "No remote code sandbox is enabled on this deployment, so there is no sandbox filesystem for any language. Pass input data via params and return output as the code's return value with outputs.files[].path (no sandboxPath)." - : isCustomTool - ? "custom tools always run in the isolated JavaScript VM, which has no sandbox filesystem. Pass input data via params and return output as the code's return value." - : 'plain JavaScript runs in the isolated VM, which has no sandbox filesystem. Use language "python" so the code runs in the remote sandbox, or drop sandboxPath and return the file content as the code\'s return value with outputs.files[].path.' - return functionJsonResponse( - { - success: false, - error: `Sandbox file inputs/outputs are unavailable for this call: ${remediation}`, - output: { result: null, stdout: '', executionTime: Date.now() - startTime }, - }, - routeContext, - { status: 422 } - ) - } - if (useRemoteSandbox) { logger.info(`[${requestId}] E2B status`, { enabled: remoteSandboxEnabled, @@ -2300,15 +2636,17 @@ export async function executeFunctionRequest( error: e2bError, exportedFileContent, exportedFiles, + collectedFiles: jsCollectedFiles, } = await executeInSandbox({ code: codeForE2B, language: CodeLanguage.JavaScript, timeoutMs: timeout, - sandboxFiles: _sandboxFiles, + sandboxFiles, privateInputs: [...compilerPrivateInputs, runtimePrivateInput], runtimeBindings: compilerRuntimeBindings, outputSandboxPath, outputSandboxPaths, + outputSandboxDir, workspaceId, sandboxId: selectedSandboxId, ...(usesMothershipSandbox && !selectedSandboxId @@ -2364,10 +2702,29 @@ export async function executeFunctionRequest( } } + const jsOutputFiles = await collectExecutionOutputFiles({ + routeContext, + authUserId: auth.attributedUserId, + workflowId, + workspaceId, + executionId, + collectedFiles: jsCollectedFiles ?? [], + stdout, + executionTime, + }) + if ('response' in jsOutputFiles) { + return appendResolvedSecretNames(jsOutputFiles.response, routeContext) + } + return functionJsonResponse( { success: true, - output: { result: e2bResult ?? null, stdout: cleanStdout(stdout), executionTime }, + output: { + result: e2bResult ?? null, + stdout: cleanStdout(stdout), + executionTime, + files: jsOutputFiles.files, + }, }, routeContext ) @@ -2391,14 +2748,16 @@ export async function executeFunctionRequest( error: e2bError, exportedFileContent, exportedFiles, + collectedFiles: pythonCollectedFiles, } = await executeInSandbox({ code: codeForE2B, language: CodeLanguage.Python, timeoutMs: timeout, - sandboxFiles: _sandboxFiles, + sandboxFiles, privateInputs: [...compilerPrivateInputs, runtimePrivateInput], outputSandboxPath, outputSandboxPaths, + outputSandboxDir, workspaceId, sandboxId: selectedSandboxId, ...(usesMothershipSandbox && !selectedSandboxId @@ -2454,10 +2813,29 @@ export async function executeFunctionRequest( } } + const pythonOutputFiles = await collectExecutionOutputFiles({ + routeContext, + authUserId: auth.attributedUserId, + workflowId, + workspaceId, + executionId, + collectedFiles: pythonCollectedFiles ?? [], + stdout, + executionTime, + }) + if ('response' in pythonOutputFiles) { + return appendResolvedSecretNames(pythonOutputFiles.response, routeContext) + } + return functionJsonResponse( { success: true, - output: { result: e2bResult ?? null, stdout: cleanStdout(stdout), executionTime }, + output: { + result: e2bResult ?? null, + stdout: cleanStdout(stdout), + executionTime, + files: pythonOutputFiles.files, + }, }, routeContext ) @@ -2636,7 +3014,11 @@ export async function executeFunctionRequest( privateResolvedSecretNamesMetadataType ) } - if (isSandboxOutputLimitError(error) || isSandboxOutputFileError(error)) { + if ( + isSandboxOutputLimitError(error) || + isSandboxOutputFileError(error) || + isSandboxOutputNotExportableError(error) + ) { const outputLimitResponse = { success: false, error: error.message, diff --git a/apps/sim/lib/function-execution/sandbox-mounts.test.ts b/apps/sim/lib/function-execution/sandbox-mounts.test.ts new file mode 100644 index 00000000000..dffc26ead64 --- /dev/null +++ b/apps/sim/lib/function-execution/sandbox-mounts.test.ts @@ -0,0 +1,252 @@ +/** + * @vitest-environment node + * + * Mount resolution for platform file objects. The authorization assertions run + * against the real `assertUserFileContentAccess` rather than a stub: which files + * a Function block may mount is the security-relevant part of this module, and + * mocking it away would leave exactly that untested. + */ +import { beforeEach, describe, expect, it, vi } from 'vitest' +import type { UserFile } from '@/executor/types' + +const { + mockHasCloudStorage, + mockGeneratePresignedDownloadUrl, + mockDownloadServableFileFromStorage, + mockReadWorkspaceFileRecordByKey, +} = vi.hoisted(() => ({ + mockHasCloudStorage: vi.fn(), + mockGeneratePresignedDownloadUrl: vi.fn(), + mockDownloadServableFileFromStorage: vi.fn(), + mockReadWorkspaceFileRecordByKey: vi.fn(), +})) + +vi.mock('@/lib/uploads/core/storage-service', () => ({ + hasCloudStorage: mockHasCloudStorage, + generatePresignedDownloadUrl: mockGeneratePresignedDownloadUrl, +})) + +vi.mock('@/lib/uploads/utils/file-utils.server', () => ({ + downloadServableFileFromStorage: mockDownloadServableFileFromStorage, +})) + +vi.mock('@/lib/workspace-files/application/read-workspace-file-content-by-key', () => ({ + readWorkspaceFileRecordByKey: { execute: mockReadWorkspaceFileRecordByKey }, +})) + +import { + MOUNT_URL_TTL_SECONDS, + planUserFileMounts, + resolveUserFileMounts, +} from '@/lib/function-execution/sandbox-mounts' + +const WORKSPACE_ID = 'ws-1' +const WORKFLOW_ID = 'wf-1' +const EXECUTION_ID = 'exec-1' + +function executionFile(overrides: Partial = {}): UserFile { + return { + id: 'file_1', + name: 'report.csv', + url: 'https://storage.example/report.csv', + size: 32, + type: 'text/csv', + key: `execution/${WORKSPACE_ID}/${WORKFLOW_ID}/${EXECUTION_ID}/abc/report.csv`, + context: 'execution', + ...overrides, + } +} + +function workspaceFile(overrides: Partial = {}): UserFile { + return { + id: 'wf_1', + name: 'brief.pdf', + url: 'https://storage.example/brief.pdf', + size: 64, + type: 'application/pdf', + key: `workspace/${WORKSPACE_ID}/brief.pdf`, + context: 'workspace', + ...overrides, + } +} + +const executionContext = { + workspaceId: WORKSPACE_ID, + workflowId: WORKFLOW_ID, + executionId: EXECUTION_ID, + userId: 'user-1', + requestId: 'req-1', +} + +describe('planUserFileMounts', () => { + it('sanitizes names into a single safe path segment', () => { + const planned = planUserFileMounts([executionFile({ name: 'Q4 Sales (Final).csv' })]) + + expect(planned[0].mountPath).toBe('/tmp/sim/inputs/Q4-Sales-_Final_.csv') + }) + + it('cannot be escaped by a traversal in the file name', () => { + const planned = planUserFileMounts([ + executionFile({ name: '../../etc/passwd' }), + executionFile({ id: 'file_2', name: '..' }), + ]) + + for (const { mountPath } of planned) { + expect(mountPath.startsWith('/tmp/sim/inputs/')).toBe(true) + expect(mountPath).not.toContain('/../') + expect(mountPath.endsWith('/..')).toBe(false) + } + }) + + it('suffixes colliding names so neither file is silently overwritten', () => { + const planned = planUserFileMounts([ + executionFile({ id: 'file_1', name: 'report.csv' }), + executionFile({ id: 'file_2', name: 'report.csv' }), + executionFile({ id: 'file_3', name: 'report.csv' }), + ]) + + expect(planned.map((entry) => entry.mountPath)).toEqual([ + '/tmp/sim/inputs/report.csv', + '/tmp/sim/inputs/report-2.csv', + '/tmp/sim/inputs/report-3.csv', + ]) + }) +}) + +describe('resolveUserFileMounts', () => { + beforeEach(() => { + vi.clearAllMocks() + mockHasCloudStorage.mockReturnValue(true) + mockGeneratePresignedDownloadUrl.mockResolvedValue('https://presigned.example/object') + mockReadWorkspaceFileRecordByKey.mockResolvedValue({ file: { id: 'wf_1' } }) + // Sized from the file being read: the aggregate budget counts bytes actually + // buffered, so a fixed-size stub would never let the total ceiling trip. + mockDownloadServableFileFromStorage.mockImplementation(async (file: UserFile) => ({ + buffer: file.size > 16 ? Buffer.alloc(file.size) : Buffer.from('a,b\n1,2'), + contentType: file.type, + })) + }) + + it('mounts by presigned URL when cloud storage is configured', async () => { + const planned = planUserFileMounts([executionFile()]) + + const { sandboxFiles, manifest } = await resolveUserFileMounts({ + planned, + context: executionContext, + }) + + // The sandbox fetches the bytes itself, so nothing transits the web process. + expect(sandboxFiles).toEqual([ + { + type: 'url', + path: '/tmp/sim/inputs/report.csv', + url: 'https://presigned.example/object', + // Granted exactly what the mount was charged against the aggregate, so + // an understated size is refused rather than silently overrunning it. + maxBytes: 32, + }, + ]) + expect(mockGeneratePresignedDownloadUrl).toHaveBeenCalledWith( + planned[0].userFile.key, + 'execution', + MOUNT_URL_TTL_SECONDS + ) + expect(mockDownloadServableFileFromStorage).not.toHaveBeenCalled() + expect(manifest).toEqual([ + { name: 'report.csv', path: '/tmp/sim/inputs/report.csv', size: 32, type: 'text/csv' }, + ]) + }) + + it('buffers bytes inline when there is no cloud storage to presign from', async () => { + mockHasCloudStorage.mockReturnValue(false) + + const { sandboxFiles } = await resolveUserFileMounts({ + planned: planUserFileMounts([executionFile()]), + context: executionContext, + }) + + // A presigned URL under local storage is an app-internal serve path the + // remote sandbox cannot reach. + expect(mockGeneratePresignedDownloadUrl).not.toHaveBeenCalled() + expect(sandboxFiles).toEqual([ + { + path: '/tmp/sim/inputs/report.csv', + content: Buffer.alloc(32).toString('base64'), + encoding: 'base64', + }, + ]) + }) + + it('rejects a file over the per-file mount ceiling before presigning it', async () => { + await expect( + resolveUserFileMounts({ + planned: planUserFileMounts([executionFile({ size: 600 * 1024 * 1024 })]), + context: executionContext, + }) + ).rejects.toThrow(/per-file mount limit/) + + expect(mockGeneratePresignedDownloadUrl).not.toHaveBeenCalled() + }) + + it('rejects a batch over the total inline budget', async () => { + mockHasCloudStorage.mockReturnValue(false) + + await expect( + resolveUserFileMounts({ + planned: planUserFileMounts([ + executionFile({ id: 'a', name: 'a.bin', size: 9 * 1024 * 1024 }), + executionFile({ id: 'b', name: 'b.bin', size: 9 * 1024 * 1024 }), + executionFile({ id: 'c', name: 'c.bin', size: 9 * 1024 * 1024 }), + executionFile({ id: 'd', name: 'd.bin', size: 9 * 1024 * 1024 }), + executionFile({ id: 'e', name: 'e.bin', size: 9 * 1024 * 1024 }), + executionFile({ id: 'f', name: 'f.bin', size: 9 * 1024 * 1024 }), + ]), + context: executionContext, + }) + ).rejects.toThrow(/total mount limit/) + }) + + it('authorizes a design-time workspace upload through its workspace record', async () => { + const { sandboxFiles } = await resolveUserFileMounts({ + planned: planUserFileMounts([workspaceFile()]), + context: { ...executionContext, principal: { kind: 'sim_user' } as never }, + }) + + // The common case for a Function block: a file pinned in the block config is + // a workspace key, which never touches the execution-scope check at all. + expect(mockReadWorkspaceFileRecordByKey).toHaveBeenCalledWith( + expect.objectContaining({ + input: expect.objectContaining({ key: `workspace/${WORKSPACE_ID}/brief.pdf` }), + }) + ) + expect(sandboxFiles).toHaveLength(1) + }) + + it('refuses an execution file belonging to a different workflow', async () => { + const foreign = executionFile({ + key: `execution/${WORKSPACE_ID}/other-workflow/other-exec/xyz/secrets.csv`, + }) + + await expect( + resolveUserFileMounts({ + planned: planUserFileMounts([foreign]), + context: executionContext, + }) + ).rejects.toThrow(/not available in this execution/) + + expect(mockGeneratePresignedDownloadUrl).not.toHaveBeenCalled() + }) + + it('admits an execution file from another run when its key is in the allowlist', async () => { + const priorRun = executionFile({ + key: `execution/${WORKSPACE_ID}/${WORKFLOW_ID}/earlier-exec/xyz/prior.csv`, + }) + + const { sandboxFiles } = await resolveUserFileMounts({ + planned: planUserFileMounts([priorRun]), + context: { ...executionContext, fileKeys: [priorRun.key] }, + }) + + expect(sandboxFiles).toHaveLength(1) + }) +}) diff --git a/apps/sim/lib/function-execution/sandbox-mounts.ts b/apps/sim/lib/function-execution/sandbox-mounts.ts new file mode 100644 index 00000000000..678fac8c931 --- /dev/null +++ b/apps/sim/lib/function-execution/sandbox-mounts.ts @@ -0,0 +1,309 @@ +import { createLogger } from '@sim/logger' +import { + assertUserFileContentAccess, + type ExecutionMaterializationContext, + readUserFileContentWithContributors, +} from '@/lib/execution/payloads/materialization.server' +import { MAX_SANDBOX_URL_MOUNT_BYTES } from '@/lib/execution/remote-sandbox/output-limits' +import { SANDBOX_INPUT_DIR } from '@/lib/execution/remote-sandbox/sandbox-paths' +import type { SandboxFile } from '@/lib/execution/remote-sandbox/types' +import { buildStorageKeySegment } from '@/lib/uploads/core/storage-key' +import { generatePresignedDownloadUrl, hasCloudStorage } from '@/lib/uploads/core/storage-service' +import type { StorageContext } from '@/lib/uploads/shared/types' +import { + isGeneratedDocumentSourceType, + resolveTrustedFileContext, +} from '@/lib/uploads/utils/file-utils' +import type { UserFile } from '@/executor/types' + +const logger = createLogger('SandboxMounts') + +/** + * Lifetime of a presigned URL handed to the sandbox to fetch a mounted object. + * The URL grants read to exactly that one object and dies with the sandbox. + * + * Sized well past the worst provisioning path rather than the typical one: a + * runtime-strategy sandbox can spend up to RUNTIME_INSTALL_TIMEOUT_MS installing + * dependencies, and only then does the in-sandbox `curl` start its own 300s + * window. At the previous 600s the URL could expire mid-download and surface as + * an opaque "failed to fetch mounted file". + */ +export const MOUNT_URL_TTL_SECONDS = 1800 + +/** + * Per-file ceiling for URL-mounted files, shared with the sandbox layer that + * enforces it on the transferred bytes so the pre-check and the backstop can + * never drift apart. + */ +export const MOUNT_URL_MAX_BYTES = MAX_SANDBOX_URL_MOUNT_BYTES + +/** + * Aggregate ceiling across all URL mounts in one request. Rejects an oversized + * request up front instead of filling the sandbox disk one slow fetch at a time. + */ +export const MAX_TOTAL_URL_BYTES = 2 * 1024 * 1024 * 1024 + +/** Per-file ceiling when bytes must pass through the web process. */ +export const MAX_INLINE_MOUNT_FILE_BYTES = 10 * 1024 * 1024 + +/** Aggregate ceiling for buffered mounts, bounding web heap rather than disk. */ +export const MAX_INLINE_MOUNT_TOTAL_BYTES = 50 * 1024 * 1024 + +/** + * Running byte totals for one resolve pass. `buffered` bytes pass through the web + * process; `url` bytes are fetched straight into the sandbox. Tracked separately + * because the two ceilings protect different resources — web heap vs sandbox disk. + */ +export interface SandboxMountBudget { + buffered: number + url: number +} + +export function createSandboxMountBudget(): SandboxMountBudget { + return { buffered: 0, url: 0 } +} + +/** One object to mount, independent of how the caller located it. */ +export interface SandboxMountSource { + mountPath: string + key: string + storageContext: StorageContext + /** Size recorded for the stored object, used for the pre-read ceilings. */ + declaredSize: number + /** + * True when `key` holds generator source rather than the servable bytes. Such + * an object must never be presigned: the sandbox would receive source text + * under a `.docx` name and the caller's script would fail on a file that looks + * fine. It also means {@link declaredSize} describes the generator, not the + * document, so the pre-read ceilings say nothing and the read is capped instead. + */ + rendersFromSource: boolean + /** + * Bounded read producing the inline payload. Only called on the buffered + * branch, so a URL mount never reads bytes into the web process. + */ + readInline(maxBytes: number): Promise +} + +export interface SandboxInlineMountPayload { + content: string + encoding?: 'base64' + /** Decoded length, which is what the buffered budget counts. */ + byteLength: number +} + +/** + * Mounts one stored object into the sandbox and records its bytes against the + * running totals. + * + * With cloud storage the sandbox fetches the bytes itself from a presigned URL; + * with local storage a presigned URL is an app-internal serve path a remote + * sandbox cannot reach, so the bytes are buffered through the web process under + * the tighter inline ceilings. + */ +export async function pushSandboxFileMount( + sandboxFiles: SandboxFile[], + source: SandboxMountSource, + budget: SandboxMountBudget +): Promise { + if (hasCloudStorage() && !source.rendersFromSource) { + /** + * The number this mount is both admitted on and later held to. + * + * Resolved once, before any comparison, because a non-finite size makes every + * `>` test false — an aggregate check reading `budget.url + NaN` would pass + * silently while the mount still consumed real budget. A missing or + * nonsensical size therefore costs the per-file maximum rather than nothing, + * and a zero takes a one-byte floor, since zero reads as "unlimited" to curl. + */ + const grantedBytes = + Number.isFinite(source.declaredSize) && source.declaredSize >= 0 + ? Math.max(1, source.declaredSize) + : MOUNT_URL_MAX_BYTES + + if (grantedBytes > MOUNT_URL_MAX_BYTES) { + throw new Error( + `Input file "${source.mountPath}" is ${Math.round(grantedBytes / 1024 / 1024)}MB, over the ${MOUNT_URL_MAX_BYTES / 1024 / 1024}MB per-file mount limit.` + ) + } + if (budget.url + grantedBytes > MAX_TOTAL_URL_BYTES) { + throw new Error( + `Mounting "${source.mountPath}" would exceed the ${MAX_TOTAL_URL_BYTES / 1024 / 1024 / 1024}GB total mount limit. Mount fewer or smaller files.` + ) + } + const url = await generatePresignedDownloadUrl( + source.key, + source.storageContext, + MOUNT_URL_TTL_SECONDS + ) + /** + * Granted exactly what it was charged, so the aggregate stays honest without a + * stat round-trip per file. Charging the recorded size while permitting the + * global per-file maximum would let understated sizes accumulate far past the + * ceiling — twenty mounts each claiming a byte and each allowed 500MB. + */ + sandboxFiles.push({ + type: 'url', + path: source.mountPath, + url, + maxBytes: grantedBytes, + }) + budget.url += grantedBytes + return + } + + const remainingBudget = Math.max(0, MAX_INLINE_MOUNT_TOTAL_BYTES - budget.buffered) + + if (!source.rendersFromSource) { + if (source.declaredSize > MAX_INLINE_MOUNT_FILE_BYTES) { + throw new Error( + `Input file "${source.mountPath}" is ${Math.round(source.declaredSize / 1024 / 1024)}MB, over the ${MAX_INLINE_MOUNT_FILE_BYTES / 1024 / 1024}MB per-file mount limit.` + ) + } + if (source.declaredSize > remainingBudget) { + throw new Error( + `Mounting "${source.mountPath}" would exceed the ${MAX_INLINE_MOUNT_TOTAL_BYTES / 1024 / 1024}MB total mount limit. Mount fewer or smaller files.` + ) + } + } + + const inline = await source.readInline(Math.min(MAX_INLINE_MOUNT_FILE_BYTES, remainingBudget)) + sandboxFiles.push({ + path: source.mountPath, + content: inline.content, + ...(inline.encoding ? { encoding: inline.encoding } : {}), + }) + budget.buffered += inline.byteLength +} + +export interface PlannedUserFileMount { + userFile: UserFile + mountPath: string +} + +/** What the running code is told about its mounts, so it never guesses a path. */ +export interface SandboxMountManifestEntry { + name: string + path: string + size: number + type: string +} + +/** + * Derives a mount file name that is safe as a path segment. + * + * `sanitizeFileName` (via {@link buildStorageKeySegment}) already maps `/` and + * `\` to `_`, so no traversal survives it; the explicit guards cover the + * degenerate remainders it does leave intact, since `.` and `-` are permitted + * characters and `..` would otherwise pass through unchanged. + */ +function safeMountFileName(name: string): string { + const segment = buildStorageKeySegment('', name) + if (!segment || segment === '.' || segment === '..') return 'file' + return segment +} + +function uniqueMountFileName(name: string, used: Set): string { + const safe = safeMountFileName(name) + if (!used.has(safe)) { + used.add(safe) + return safe + } + // Two upstream blocks each producing `report.csv` must both survive: without a + // suffix the second write silently overwrites the first and the code sees one file. + const dot = safe.lastIndexOf('.') + const stem = dot > 0 ? safe.slice(0, dot) : safe + const extension = dot > 0 ? safe.slice(dot) : '' + for (let attempt = 2; ; attempt += 1) { + const candidate = `${stem}-${attempt}${extension}` + if (!used.has(candidate)) { + used.add(candidate) + return candidate + } + } +} + +/** + * Assigns each file a deterministic mount path. Pure and I/O-free, so a caller + * can decide whether an execution needs a sandbox filesystem before spending a + * presign or a byte of transfer on a request that may still be refused. + */ +export function planUserFileMounts( + files: readonly UserFile[], + mountDir: string = SANDBOX_INPUT_DIR +): PlannedUserFileMount[] { + const used = new Set() + return files.map((userFile) => ({ + userFile, + mountPath: `${mountDir}/${uniqueMountFileName(userFile.name, used)}`, + })) +} + +/** + * Resolves planned platform file objects into sandbox mounts. + * + * Authorization runs through {@link assertUserFileContentAccess} rather than the + * tool-file check used by ordinary integrations. For an `execution/` key the + * latter grants on workspace membership alone, which would let a Function block + * mount any execution file from any past run of any workflow in the workspace; + * this one additionally requires the workflow to match and the key to be in the + * execution's allowlist. It is asserted before the transport branches, because + * the URL path never reads the bytes and so never reaches the check embedded in + * the reader. + */ +export async function resolveUserFileMounts(args: { + planned: readonly PlannedUserFileMount[] + context: ExecutionMaterializationContext +}): Promise<{ sandboxFiles: SandboxFile[]; manifest: SandboxMountManifestEntry[] }> { + const sandboxFiles: SandboxFile[] = [] + const manifest: SandboxMountManifestEntry[] = [] + const budget = createSandboxMountBudget() + + for (const { userFile, mountPath } of args.planned) { + const storageContext = resolveTrustedFileContext(userFile.key, userFile.context) + await assertUserFileContentAccess(userFile, args.context) + + await pushSandboxFileMount( + sandboxFiles, + { + mountPath, + key: userFile.key, + storageContext, + declaredSize: userFile.size, + rendersFromSource: isGeneratedDocumentSourceType(userFile.type), + readInline: async (maxBytes) => { + // Base64 regardless of content type: the payload is reproduced exactly + // for any byte sequence, and picking utf8 for a mistyped binary would + // substitute U+FFFD and hand the code a corrupted file. + const { content } = await readUserFileContentWithContributors(userFile, { + ...args.context, + encoding: 'base64', + maxBytes, + maxSourceBytes: maxBytes, + }) + return { + content, + encoding: 'base64' as const, + byteLength: Buffer.byteLength(content, 'base64'), + } + }, + }, + budget + ) + + manifest.push({ + name: userFile.name, + path: mountPath, + size: userFile.size, + type: userFile.type, + }) + } + + logger.info('Resolved sandbox file mounts', { + mountCount: sandboxFiles.length, + bufferedBytes: budget.buffered, + urlBytes: budget.url, + }) + + return { sandboxFiles, manifest } +} diff --git a/apps/sim/lib/internal/file/operations.ts b/apps/sim/lib/internal/file/operations.ts index 190592076f8..1efbed2bc9d 100644 --- a/apps/sim/lib/internal/file/operations.ts +++ b/apps/sim/lib/internal/file/operations.ts @@ -12,6 +12,7 @@ import { acquireLock, releaseLock } from '@/lib/core/config/redis' import { OrchestrationError } from '@/lib/core/orchestration/types' import { isPayloadSizeLimitError } from '@/lib/core/utils/stream-limits' import { ensureAbsoluteUrl } from '@/lib/core/utils/urls' +import { isUserFile } from '@/lib/core/utils/user-file' import { durableSecretProvenanceFromPrivateBundle } from '@/lib/execution/durable-secret-provenance' import { inspectPrivateSecretProvenanceRequest, @@ -43,7 +44,7 @@ import { import { getFileExtension, getMimeTypeFromExtension, - inferContextFromKey, + tryInferContextFromKey, } from '@/lib/uploads/utils/file-utils' import { downloadFileFromStorage, @@ -158,6 +159,12 @@ const fileInputToUserFile = (fileInput: unknown) => { if (!fileUrl && !key) return null + // A key this normalizer cannot classify is request input we cannot use, which + // is what `null` already means here — the throwing form would turn a malformed + // client value into a 500 from every operation that normalizes a file input. + const context = key ? tryInferContextFromKey(key) : null + if (key && !context) return null + return { id: key || fileUrl, name: @@ -169,7 +176,9 @@ const fileInputToUserFile = (fileInput: unknown) => { ? record.type.trim() : 'application/octet-stream', key, - context: inferContextFromKey(key), + // Only absent when there is no key at all — an unclassifiable one returned + // above rather than reaching here. + context: context ?? undefined, } } @@ -220,6 +229,14 @@ const MAX_GET_CONTENT_FILE_BYTES = 64 * 1024 * 1024 /** Combined extracted-text cap so the content array stays within the large-value-ref ceiling. */ const MAX_GET_CONTENT_TOTAL_BYTES = 64 * 1024 * 1024 +/** + * Cap on a file stored through `write`'s `fileInput`, pinned to the destination's + * own ceiling. A larger cap here would let a 50–100MB file be downloaded and + * base64-encoded in this process only for `createWorkspaceFile` to reject it, so + * the expensive transfer is refused up front instead. + */ +const MAX_WRITE_FILE_INPUT_BYTES = MAX_WORKSPACE_FILE_CONTENT_BYTES + /** Per-file download cap for the compress operation. */ const MAX_COMPRESS_FILE_BYTES = 100 * 1024 * 1024 /** Combined input cap for the compress operation to bound in-memory archiving. */ @@ -749,7 +766,7 @@ export async function executeFileManageOperation( } case 'write': { - const { fileName, content, contentType } = body + const { fileName, content, fileInput, contentType } = body signal?.throwIfAborted() const provenanceResolution = resolveFileWriteSecretProvenance({ headers, @@ -763,33 +780,109 @@ export async function executeFileManageOperation( { status: 400 } ) } - const { folderSegments, leafName } = splitWorkspaceFilePath(fileName) + + // Storing an existing file object rather than text: read its bytes under + // the caller's own authorization, then write them unchanged. Base64 so a + // binary payload survives — decoding it as UTF-8 would corrupt it. + let sourceEncoding: 'utf-8' | 'base64' = 'utf-8' + let sourceContent = content ?? '' + let sourceName = fileName + let sourceContentType = contentType + /** + * Copying bytes carries the source's secret lineage, exactly as archiving + * does. Without this the copy would land with no provenance row — the + * "safe" state — and a file the platform had locked as secret-derived + * would be readable again under its new id. + * + * A source with no workspace row resolves to `unknown` rather than empty, + * because nothing durable records what went into it. + */ + let inputProvenance: WorkspaceFileSecretProvenance | undefined + if (fileInput !== undefined && fileInput !== null) { + /** + * Two shapes reach here and only one already identifies a file. A block + * reference, or an id the tool layer resolved through the execution + * index or workspace metadata, arrives carrying `id`/`key`/`url`/`name`. + * The file picker instead stores `{name, path, key, size, type}` with no + * `id` or `url`, which the shared normalizer turns into one — the same + * conversion every other operation in this file applies to its input. + * + * Identity is all that is demanded, deliberately. `size` is never read + * before the download and the download reports the real content type, so + * requiring them would reject an otherwise usable reference over two + * fields nothing depends on. + */ + const sourceFile: UserFile | null = isUserFile(fileInput) + ? { + ...fileInput, + size: fileInput.size ?? 0, + type: fileInput.type ?? 'application/octet-stream', + } + : fileInputToUserFile(fileInput) + if (!sourceFile) { + return Response.json( + { success: false, error: 'fileInput must be a file object' }, + { status: 400 } + ) + } + const denied = await assertOperationFileAccess(sourceFile, context) + if (denied) return denied + + inputProvenance = await deriveWorkspaceFileSecretProvenance({ + principal, + workspaceId, + targetOwnerUserId: userId, + sources: [await bindSelectedContentFile(principal, workspaceId, sourceFile)], + }) + + const downloaded = await downloadServableFileFromStorage(sourceFile, requestId, logger, { + maxBytes: MAX_WRITE_FILE_INPUT_BYTES, + signal, + // A generated document that references other files needs a principal + // to resolve them; without one the resolver can only serve an + // already-published artifact and throws when there is none. + filePrincipal: principal, + }) + sourceEncoding = 'base64' + sourceContent = downloaded.buffer.toString('base64') + sourceName = fileName?.trim() || sourceFile.name + sourceContentType = contentType || downloaded.contentType || sourceFile.type + } + const writeProvenanceSources = [ + provenanceResolution.contentProvenance, + inputProvenance, + ].filter((entry): entry is WorkspaceFileSecretProvenance => entry !== undefined) + // Left undefined when neither side recorded anything, so a plain text + // write still stores no provenance row rather than an empty one. + const writeProvenance = writeProvenanceSources.length + ? mergeWorkspaceFileSecretProvenance(...writeProvenanceSources) + : undefined + + const { folderSegments, leafName } = splitWorkspaceFilePath(sourceName ?? '') await admitCreateWorkspaceFile(principal, workspaceId) const { folderId } = await ensureWorkspaceFileFolderPathOperation.execute({ principal, input: { workspaceId, pathSegments: folderSegments }, }) - const mimeType = contentType || getMimeTypeFromExtension(getFileExtension(leafName)) + const mimeType = sourceContentType || getMimeTypeFromExtension(getFileExtension(leafName)) const result = await createWorkspaceFile.execute({ principal, input: { workspaceId, name: leafName, contentType: mimeType, - content: content ?? '', - encoding: 'utf-8', + content: sourceContent, + encoding: sourceEncoding, folderId, exactName: false, - ...(provenanceResolution.contentProvenance - ? { secretProvenance: provenanceResolution.contentProvenance } - : {}), + ...(writeProvenance ? { secretProvenance: writeProvenance } : {}), }, }) - const fileBuffer = Buffer.from(content ?? '', 'utf-8') + const fileBuffer = Buffer.from(sourceContent, sourceEncoding) logger.info('File created', { fileId: result.file.id, - name: fileName, + name: sourceName, size: fileBuffer.length, }) diff --git a/apps/sim/lib/uploads/utils/context-prefix.test.ts b/apps/sim/lib/uploads/utils/context-prefix.test.ts new file mode 100644 index 00000000000..c8cc8a10747 --- /dev/null +++ b/apps/sim/lib/uploads/utils/context-prefix.test.ts @@ -0,0 +1,17 @@ +import { describe, expect, it } from 'vitest' +import { inferContextFromKey, tryInferContextFromKey } from '@/lib/uploads/utils/file-utils' + +describe('tryInferContextFromKey', () => { + it('classifies a known prefix the same way the throwing form does', () => { + for (const key of ['workspace/a/b.txt', 'execution/a/b/c/d.bin', 'kb/x', 'logs/y']) { + expect(tryInferContextFromKey(key)).toBe(inferContextFromKey(key)) + } + }) + + it('answers null where the throwing form raises, so caller input cannot 500', () => { + for (const key of ['', 'garbage', 'not-a-prefix/x.txt', '../escape']) { + expect(tryInferContextFromKey(key)).toBeNull() + expect(() => inferContextFromKey(key)).toThrow() + } + }) +}) diff --git a/apps/sim/lib/uploads/utils/file-utils.ts b/apps/sim/lib/uploads/utils/file-utils.ts index 39cfdc2a6aa..3f0df1c73c8 100644 --- a/apps/sim/lib/uploads/utils/file-utils.ts +++ b/apps/sim/lib/uploads/utils/file-utils.ts @@ -757,9 +757,30 @@ export function isInternalFileUrl(fileUrl: string): boolean { * row — see `resolveStoredFileContext` — never this prefix. */ export function inferContextFromKey(key: string): StorageContext { - if (!key) { - throw new Error('Cannot infer context from empty key') + const context = tryInferContextFromKey(key) + if (!context) { + throw new Error( + key + ? `File key must start with a context prefix (kb/, knowledge-base/, chat/, copilot/, execution/, workspace/, profile-pictures/, og-images/, workspace-logos/, or logs/). Got: ${key}` + : 'Cannot infer context from empty key' + ) } + return context +} + +/** + * {@link inferContextFromKey} for a key that came from a caller rather than from + * our own storage, answering `null` instead of throwing. + * + * The throwing form is right where an unclassifiable key means the platform + * built one wrong — that is a bug and should be loud. It is wrong where the key + * is request input being normalized, because there an unrecognized prefix just + * means "this is not a file we can use", and a throw turns a malformed request + * into a 500. Both share this one list so a new context cannot be added to only + * half of them. + */ +export function tryInferContextFromKey(key: string): StorageContext | null { + if (!key) return null if (key.startsWith('kb/') || key.startsWith('knowledge-base/')) return 'knowledge-base' if (key.startsWith('chat/')) return 'chat' @@ -771,9 +792,7 @@ export function inferContextFromKey(key: string): StorageContext { if (key.startsWith('workspace-logos/')) return 'workspace-logos' if (key.startsWith('logs/')) return 'logs' - throw new Error( - `File key must start with a context prefix (kb/, knowledge-base/, chat/, copilot/, execution/, workspace/, profile-pictures/, og-images/, workspace-logos/, or logs/). Got: ${key}` - ) + return null } /** diff --git a/apps/sim/lib/workflows/types.ts b/apps/sim/lib/workflows/types.ts index 9e51d7ff1a7..28a68489132 100644 --- a/apps/sim/lib/workflows/types.ts +++ b/apps/sim/lib/workflows/types.ts @@ -12,6 +12,15 @@ export const USER_FILE_ACCESSIBLE_PROPERTIES = [ 'size', 'type', 'base64', + /** + * Path to the file on the sandbox filesystem, mounted on demand. + * + * The counterpart to `base64`: that one inlines the bytes and is JavaScript- + * only, while this one hands any language a real path to open — which is what + * a CLI or a library like pandas or ffmpeg actually needs. Referencing it runs + * the block in the remote sandbox, since the isolated VM has no filesystem. + */ + 'path', ] as const export type UserFileAccessibleProperty = (typeof USER_FILE_ACCESSIBLE_PROPERTIES)[number] @@ -23,6 +32,7 @@ export const USER_FILE_PROPERTY_TYPES: Record = id: 'file_write', name: 'File Write', description: - 'Create a new workspace file. If a file with the same name already exists, a numeric suffix is added (e.g., "data (1).csv").', + 'Create a new workspace file, either from text content or from an existing file. If a file with the same name already exists, a numeric suffix is added (e.g., "data (1).csv").', version: '1.0.0', params: { fileName: { type: 'string', - required: true, + required: false, visibility: 'user-or-llm', description: - 'File name (e.g., "data.csv"). If a file with this name exists, a numeric suffix is added automatically.', + 'File name (e.g., "data.csv"). Required when writing text; optional when storing a file, which keeps its own name unless this overrides it. If the name already exists, a numeric suffix is added automatically.', }, content: { type: 'string', - required: true, + required: false, visibility: 'user-or-llm', - description: 'The text content to write to the file.', + description: + 'The text content to write to the file. Provide exactly one of content or fileInput.', + }, + fileInput: { + type: 'file', + required: false, + visibility: 'user-or-llm', + description: + 'An existing file to store in the workspace, such as one produced by an earlier tool. Use this for anything that is not text — PDFs, images, audio, archives. Provide exactly one of content or fileInput.', }, contentType: { type: 'string', required: false, visibility: 'user-only', description: - 'MIME type for new files (e.g., "text/plain"). Auto-detected from file extension if omitted.', + 'MIME type for new files (e.g., "text/plain"). Auto-detected from the file extension, or taken from the stored file, if omitted.', }, }, @@ -42,10 +51,14 @@ export const fileWriteTool: InternalToolConfig = operation: 'write', fileName: params.fileName, content: params.content, + fileInput: params.fileInput, contentType: params.contentType, workspaceId: params.workspaceId, }), secretProvenance: { + // Only the text branch carries caller-authored content. A stored file's + // bytes come from an already-tracked object, whose own provenance follows + // it rather than being re-derived from this request. request: () => [{ key: 'content', inputPaths: [['content']] }], }, }, diff --git a/apps/sim/tools/function/execute.ts b/apps/sim/tools/function/execute.ts index de9b27a3121..8da668e12a9 100644 --- a/apps/sim/tools/function/execute.ts +++ b/apps/sim/tools/function/execute.ts @@ -5,12 +5,44 @@ import { normalizeStringRecord, normalizeWorkflowVariables, } from '@/lib/core/utils/records' +import { isUserFileWithMetadata } from '@/lib/core/utils/user-file' import { DEFAULT_EXECUTION_TIMEOUT_MS } from '@/lib/execution/constants' import { DEFAULT_CODE_LANGUAGE } from '@/lib/execution/languages' import { PRIVATE_SECRET_PROVENANCE_FIELD } from '@/lib/execution/private-tool-metadata' +import { SANDBOX_INPUT_DIR, SANDBOX_OUTPUT_DIR } from '@/lib/execution/remote-sandbox/sandbox-paths' +import type { UserFile } from '@/executor/types' import type { CodeExecutionInput, CodeExecutionOutput } from '@/tools/function/types' import type { InternalToolConfig } from '@/tools/types' +/** + * Normalizes the mounted-file param, which advanced-mode template resolution + * delivers as a JSON string rather than an array. + * + * Deliberately not `normalizeFileInput` from `@/blocks/utils`: that module + * reaches the providers store and Sim's icon set, so importing it here would + * drag React and zustand into the tool registry's module graph. + */ +function normalizeSandboxInputFiles(value: unknown): FunctionExecuteBody['files'] { + if (!value) return undefined + + let parsed = value + if (typeof parsed === 'string') { + try { + parsed = JSON.parse(parsed) + } catch { + return undefined + } + } + + const files = Array.isArray(parsed) ? parsed : [parsed] + const userFiles = files.filter((file): file is UserFile => isUserFileWithMetadata(file)) + if (userFiles.length === 0) return undefined + // Copied onto fresh objects because the boundary schema is `.passthrough()`: + // its inferred type carries an index signature, which a declared interface + // like UserFile cannot satisfy directly. + return userFiles.map((file) => ({ ...file })) +} + /** Builds the canonical Function protocol body for both HTTP compatibility and in-process calls. */ export function buildFunctionExecuteBody(params: CodeExecutionInput): FunctionExecuteBody { const codeContent = Array.isArray(params.code) @@ -35,6 +67,7 @@ export function buildFunctionExecuteBody(params: CodeExecutionInput): FunctionEx overwriteFileId: params.overwriteFileId, inputs: params.inputs, outputs: params.outputs, + files: normalizeSandboxInputFiles(params.files), envVars: normalizeStringRecord(params.envVars), workflowVariables: normalizeWorkflowVariables(params.workflowVariables), blockData: normalizeRecord(params.blockData), @@ -60,8 +93,9 @@ export function buildFunctionExecuteBody(params: CodeExecutionInput): FunctionEx export const functionExecuteTool: InternalToolConfig = { id: 'function_execute', name: 'Function Execute', - description: - 'Execute JavaScript, Python, or shell scripts in a secure sandbox. For JS: fetch() is available, code runs in an async IIFE wrapper. Shell includes general utilities such as jq, curl, git, and rg. Use outputPath/outputTable to persist returned data, or outputSandboxPath + outputPath to export a file created inside the sandbox into the workspace.', + description: `Execute JavaScript, Python, or shell scripts in a secure sandbox. For JS: fetch() is available, code runs in an async IIFE wrapper. Shell includes general utilities such as jq, curl, git, and rg. Use outputPath/outputTable to persist returned data, or outputSandboxPath + outputPath to export a file created inside the sandbox into the workspace. Naming outputSandboxPath exports only those paths — the /tmp/sim/outputs directory is not harvested in the same call, so use one or the other. +To read a file, pass its id in \`files\`: each one is mounted read-only under ${SANDBOX_INPUT_DIR}. List that directory to find them rather than guessing a path — names are sanitized and de-duplicated, so they do not always match the original. +To return a file, write it to ${SANDBOX_OUTPUT_DIR}. Everything there comes back in this tool's \`files\` output as a platform file object, which another tool that takes a file accepts directly — no upload step in between.`, version: '1.0.0', params: { @@ -133,6 +167,12 @@ export const functionExecuteTool: InternalToolConfig } + /** + * Platform file objects mounted into the sandbox before the code runs. Unlike + * {@link CodeExecutionInput.inputs}, which names workspace VFS paths, these are + * the objects tools exchange — so an upstream block's output reaches the + * sandbox without a trip through the workspace. + */ + files?: UserFile[] /** Workspace sandbox whose dependency set this execution runs against. */ sandboxId?: string /** @@ -76,5 +84,7 @@ export interface CodeExecutionOutput extends ToolResponse { output: { result: any stdout: string + /** Files harvested from the sandbox output directory, already persisted. */ + files: UserFile[] } } diff --git a/apps/sim/tools/generated/tool-metadata.ts b/apps/sim/tools/generated/tool-metadata.ts index 2b7e717cda1..e13769e14b9 100644 --- a/apps/sim/tools/generated/tool-metadata.ts +++ b/apps/sim/tools/generated/tool-metadata.ts @@ -3,7 +3,7 @@ /** Serializable metadata for every built-in tool, keyed by tool id. */ const toolMetadata: Record = 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"},"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"},"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"},"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"},"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"}},"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"},"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 (defaults to 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)"}},"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"},"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\\"]"}},"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"},"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: , , , ,