Skip to content

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

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.md
new file mode 100644
index 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.ts
index 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.ts
index 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 copy
try {
- 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.ts
index 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.ts
index 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';