Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
fix(core): resolve $ref/$defs so file flags behind a reference aren't dropped (#3566)
Serhii Zghama6a4cb542aed5
diff --git a/.changeset/file-modifier-dereference-ref.md b/.changeset/file-modifier-dereference-ref.mdnew file mode 100644index 000000000..b4a7012a9--- /dev/null+++ b/.changeset/file-modifier-dereference-ref.md@@ -0,0 +1,5 @@+---+'@composio/core': patch+---++Preserve root `$defs` / `definitions` blocks on tool parameter schemas and dereference them in the Node file modifier, so auto file upload/download detection works when `file_uploadable` or `file_downloadable` is hidden behind an internal `$ref`.diff --git a/ts/packages/core/src/types/tool.types.ts b/ts/packages/core/src/types/tool.types.tsindex 54762d690..ef67e4b68 100644--- a/ts/packages/core/src/types/tool.types.ts+++ b/ts/packages/core/src/types/tool.types.ts@@ -99,6 +99,24 @@ const ParametersSchema = z.object({nullable: z.boolean().optional(),description: z.string().optional(),additionalProperties: z.boolean().default(false).optional(),+ // Definition blocks targeted by `$ref` pointers. The Composio API ships+ // these at the parameters root (e.g. `data` → `$ref` → `#/$defs/...`), but+ // because `z.object` strips unknown keys they were being dropped on parse —+ // leaving every nested `$ref` dangling and unresolvable downstream+ // (providers, file modifiers). `JSONSchemaPropertySchema` already accepts+ // both keywords; the parameters root must too.+ $defs: z+ .record(+ z.string(),+ z.lazy(() => JSONSchemaPropertySchema)+ )+ .optional(),+ definitions: z+ .record(+ z.string(),+ z.lazy(() => JSONSchemaPropertySchema)+ )+ .optional(),});/**diff --git a/ts/packages/core/src/utils/modifiers/FileToolModifier.node.ts b/ts/packages/core/src/utils/modifiers/FileToolModifier.node.tsindex fd66a2576..501642351 100644--- a/ts/packages/core/src/utils/modifiers/FileToolModifier.node.ts+++ b/ts/packages/core/src/utils/modifiers/FileToolModifier.node.ts@@ -24,6 +24,22 @@ import {transformProperties,schemaHasFileProperty,} from './FileToolModifier.utils.neutral';+import { dereferenceJsonSchema } from '../jsonSchema';++/**+ * Inlines internal `$ref` pointers so the file walkers below can see the+ * `file_uploadable` / `file_downloadable` flags that live behind a+ * `$ref`/`$defs` indirection (e.g. `GMAIL_GET_ATTACHMENT`). The walkers only+ * recurse `properties`/`anyOf`/`oneOf`/`allOf`/`items` and never dereference,+ * so without this a flagged field reachable only through a `$ref` is silently+ * missed — the file is never staged/downloaded. `'sentinel'` mode keeps tools+ * whose schema omits the `$defs` target working (see+ * https://github.com/ComposioHQ/composio/issues/3307) instead of throwing.+ */+const resolveFileSchema = (+ schema: JSONSchemaProperty | undefined+): JSONSchemaProperty | undefined =>+ schema ? dereferenceJsonSchema(schema, { onUnresolved: 'sentinel' }) : schema;const getSchemaVariants = (schema: JSONSchemaProperty | undefined): JSONSchemaProperty[] => [...(schema?.anyOf ?? []),@@ -370,12 +386,14 @@ export class FileToolModifier {return schema;}- const properties = transformProperties(schema.inputParameters.properties);+ const inputParameters = resolveFileSchema(schema.inputParameters)!;+ const properties = transformProperties(inputParameters.properties!);return {...schema,inputParameters: {- ...schema.inputParameters,+ ...inputParameters,+ type: 'object',properties,},};@@ -396,7 +414,7 @@ export class FileToolModifier {// Recursively transform the arguments tree without mutating the caller’s copytry {- const newArgs = await hydrateFiles(args, tool.inputParameters, {+ const newArgs = await hydrateFiles(args, resolveFileSchema(tool.inputParameters), {toolSlug,toolkitSlug,client: this.client,@@ -429,10 +447,14 @@ export class FileToolModifier {const { result, toolSlug } = options;// Walk result.data without mutating the original, using output schema for guidance- const dataWithDownloads = await hydrateDownloads(result.data, tool.outputParameters, {- toolSlug,- fileDownloadDir: this.fileUploadPathOptions.fileDownloadDir,- });+ const dataWithDownloads = await hydrateDownloads(+ result.data,+ resolveFileSchema(tool.outputParameters),+ {+ toolSlug,+ fileDownloadDir: this.fileUploadPathOptions.fileDownloadDir,+ }+ );return { ...result, data: dataWithDownloads as typeof result.data };}diff --git a/ts/packages/core/test/tools/fileModifiers.test.ts b/ts/packages/core/test/tools/fileModifiers.test.tsindex 63781a502..600f03784 100644--- a/ts/packages/core/test/tools/fileModifiers.test.ts+++ b/ts/packages/core/test/tools/fileModifiers.test.ts@@ -1713,6 +1713,126 @@ describe('FileToolModifier', () => {expect(modifiedResult.data.fileOutput).toBeNull();});});++ // The schema walkers recurse properties/anyOf/oneOf/allOf/items but never+ // dereference `$ref`. Composio toolkits express file flags through a+ // `$ref`/`$defs` indirection (e.g. GMAIL_GET_ATTACHMENT), so without+ // dereferencing the flag is invisible and the file is silently skipped.+ // See https://github.com/ComposioHQ/composio/issues/3506.+ describe('$ref / $defs indirection', () => {+ it('marks a file_uploadable behind a $ref/$defs as format: "path" in modifyToolSchema', async () => {+ const schema: Tool = {+ slug: 'test-tool',+ name: 'Test Tool',+ description: 'A test tool',+ tags: ['test'],+ version: '20251201_01',+ availableVersions: ['20251201_01'],+ inputParameters: {+ type: 'object',+ properties: {+ attachment: { $ref: '#/$defs/Attachment' },+ legacyAttachment: { $ref: '#/definitions/LegacyAttachment' },+ text: { type: 'string' },+ },+ $defs: {+ Attachment: {+ type: 'string',+ file_uploadable: true,+ description: 'Local path to attach',+ },+ },+ definitions: {+ LegacyAttachment: {+ type: 'string',+ file_uploadable: true,+ description: 'Legacy local path to attach',+ },+ },+ },+ };++ const result = await fileToolModifier.modifyToolSchema(schema);++ expect(result.inputParameters?.properties?.attachment).toHaveProperty('format', 'path');+ expect(result.inputParameters?.properties?.attachment).toHaveProperty(+ 'file_uploadable',+ true+ );+ expect(result.inputParameters?.properties?.legacyAttachment).toHaveProperty('format', 'path');+ expect(result.inputParameters?.properties?.legacyAttachment).toHaveProperty(+ 'file_uploadable',+ true+ );+ expect(result.inputParameters?.properties?.text).not.toHaveProperty('format');+ });++ it('uploads a file whose file_uploadable flag is reachable only via $ref/$defs', async () => {+ const mockFileData = {+ name: 'doc.pdf',+ mimetype: 'application/pdf',+ s3key: 'uploads/doc.pdf',+ };+ vi.mocked(fileUtils.getFileDataAfterUploadingToS3).mockResolvedValue(mockFileData);++ const toolWithRef: Tool = {+ slug: 'test-tool',+ name: 'Test Tool',+ description: 'A test tool',+ tags: ['test'],+ version: '20251201_01',+ availableVersions: ['20251201_01'],+ inputParameters: {+ type: 'object',+ properties: {+ attachment: { $ref: '#/$defs/Attachment' },+ },+ $defs: {+ Attachment: { type: 'string', file_uploadable: true },+ },+ },+ };++ const result = await fileToolModifier.fileUploadModifier(toolWithRef, {+ toolSlug: 'test-tool',+ toolkitSlug: 'test-toolkit',+ params: {+ arguments: { attachment: '/path/to/doc.pdf' },+ userId: 'test-user',+ },+ });++ expect(fileUtils.getFileDataAfterUploadingToS3).toHaveBeenCalledWith('/path/to/doc.pdf', {+ toolSlug: 'test-tool',+ toolkitSlug: 'test-toolkit',+ client: mockClient,+ });+ expect(result.arguments?.attachment).toEqual(mockFileData);+ });++ it('degrades gracefully when a $ref has no matching $defs target', async () => {+ // Some toolkits ship a `$ref` without ever declaring `$defs`+ // (https://github.com/ComposioHQ/composio/issues/3307). The modifier+ // must not throw; the unresolved branch simply carries no file flag.+ const schema: Tool = {+ slug: 'test-tool',+ name: 'Test Tool',+ description: 'A test tool',+ tags: ['test'],+ version: '20251201_01',+ availableVersions: ['20251201_01'],+ inputParameters: {+ type: 'object',+ properties: {+ attachment: { $ref: '#/$defs/Missing' },+ },+ },+ };++ const result = await fileToolModifier.modifyToolSchema(schema);+ expect(result.inputParameters?.properties?.attachment).not.toHaveProperty('format');+ });+ });});describe('Tools with dangerouslyAllowAutoUploadDownloadFiles', () => {diff --git a/ts/packages/core/test/tools/tools.test.ts b/ts/packages/core/test/tools/tools.test.tsindex 5ff2defa7..994672d5f 100644--- a/ts/packages/core/test/tools/tools.test.ts+++ b/ts/packages/core/test/tools/tools.test.ts@@ -573,6 +573,76 @@ describe('Tools', () => {});});+ // `ParametersSchema` is a strict `z.object`, so any key it doesn't declare is+ // dropped on parse. It previously omitted `$defs`/`definitions`, so a tool+ // whose parameters root carries those blocks (the `$ref` targets) lost them —+ // leaving every nested `$ref` dangling and unresolvable for providers and the+ // file modifier. See https://github.com/ComposioHQ/composio/issues/3506.+ describe('$ref / $defs preservation on tool parameters', () => {+ const rawToolWithDefs = {+ slug: 'GMAIL_GET_ATTACHMENT',+ name: 'Get Attachment',+ description: 'Fetch a Gmail attachment',+ input_parameters: {+ type: 'object',+ properties: {+ message_id: { type: 'string' },+ },+ },+ output_parameters: {+ type: 'object',+ properties: {+ data: { $ref: '#/$defs/GetAttachmentResponse' },+ legacy_data: { $ref: '#/definitions/LegacyAttachmentResponse' },+ },+ $defs: {+ GetAttachmentResponse: {+ type: 'object',+ properties: { file: { $ref: '#/$defs/FileDownloadable' } },+ },+ FileDownloadable: {+ type: 'object',+ file_downloadable: true,+ properties: { s3url: { type: 'string' } },+ },+ },+ definitions: {+ LegacyAttachmentResponse: {+ type: 'object',+ properties: { file: { $ref: '#/definitions/LegacyFileDownloadable' } },+ },+ LegacyFileDownloadable: {+ type: 'object',+ file_downloadable: true,+ properties: { s3url: { type: 'string' } },+ },+ },+ },+ toolkit: { logo: 'https://example.com/gmail.png', slug: 'gmail', name: 'Gmail' },+ version: '20260515_00',+ };++ it('keeps the root $defs block so nested $ref pointers stay resolvable', async () => {+ mockClient.tools.retrieve.mockResolvedValueOnce(rawToolWithDefs);++ const tool = await context.tools.getRawComposioToolBySlug('GMAIL_GET_ATTACHMENT');++ expect(tool.outputParameters?.$defs).toBeDefined();+ expect(tool.outputParameters?.$defs?.FileDownloadable).toMatchObject({+ file_downloadable: true,+ });+ expect(tool.outputParameters?.definitions?.LegacyFileDownloadable).toMatchObject({+ file_downloadable: true,+ });+ expect(tool.outputParameters?.properties?.data).toEqual({+ $ref: '#/$defs/GetAttachmentResponse',+ });+ expect(tool.outputParameters?.properties?.legacy_data).toEqual({+ $ref: '#/definitions/LegacyAttachmentResponse',+ });+ });+ });+describe('get', () => {it('should get a single tool by slug and wrap it with provider as a collection', async () => {const userId = 'test-user';