@devries-cameron20 / composio Mirror · read-only / commits / 9447932d9
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 14:45 UTC

fix(providers): dereference $ref/$defs schemas before translation

jsonSchemaToZodSchema has no $ref branch, so a $ref node degrades to z.any() for langchain, llamaindex, claude-agent-sdk, and vercel's default path. google and openai-agents' non-strict fallback rebuild the root from properties/required, discarding $defs while dangling $ref pointers survive. Dereference internal $ref/$defs before translation in all six, using onUnresolved: 'sentinel' so a $ref into an undeclared $defs block (e.g. GMAIL_FETCH_EMAILS) degrades to a permissive schema instead of throwing. The mastra and anthropic providers already had this fix; openai-agents' strict branch is untouched since OpenAI's structured outputs support $defs/$ref natively, including recursion, and google's rebuild still drops additionalProperties/title/root oneOf-anyOf-allOf beyond the dangling-$ref class this fixes.

jkomyno committed Aug 28, 2026 at 11:40 UTC 9447932d985941668ac46ddcbd1be42403c1e789
13 files changed +776 -11
.changeset/deref-ref-schemas.md new
+12
@@ -0,0 +1,12 @@
1 +---
2 +'@composio/langchain': minor
3 +'@composio/llamaindex': minor
4 +'@composio/claude-agent-sdk': minor
5 +'@composio/vercel': minor
6 +'@composio/google': minor
7 +'@composio/openai-agents': minor
8 +---
9 +
10 +Dereference internal $ref/$defs in tool input schemas before provider translation, so properties reachable only through a reference keep their types and validation instead of degrading to untyped (z.any) or being emitted as a dangling reference.
11 +
12 +This changes the JSON Schema these providers emit for $ref-using tools. Downstream snapshot tests on tool definitions will see diffs. Schemas the Composio API ships with a $ref but no $defs block (e.g. GMAIL_FETCH_EMAILS) degrade to a permissive object schema rather than throwing. The strict-structured-outputs path of @composio/openai-agents is unchanged — OpenAI supports $defs/$ref natively, including recursion.
ts/packages/providers/claude-agent-sdk/src/index.ts
+9 -5
@@ -14,6 +14,7 @@ import {
14 ExecuteToolFn,
15 McpUrlResponse,
16 McpServerGetResponse,
17 + dereferenceJsonSchema,
18 normalizeToolArguments,
19 jsonSchemaToZodSchema,
20 } from '@composio/core';
@@ -111,11 +112,14 @@ export class ClaudeAgentSDKProvider extends BaseAgenticProvider<
112 // A tool with no input parameters stays closed: the fallback spells out
113 // `additionalProperties: false`, because a bare `properties: {}` is now an open object.
114 const inputZodSchema = jsonSchemaToZodSchema(
114 - composioTool.inputParameters ?? {
115 - type: 'object',
116 - properties: {},
117 - additionalProperties: false,
118 - }
115 + dereferenceJsonSchema(
116 + composioTool.inputParameters ?? {
117 + type: 'object',
118 + properties: {},
119 + additionalProperties: false,
120 + },
121 + { onUnresolved: 'sentinel' }
122 + )
123 );
124
125 // The SDK runtime accepts a complete schema, but `tool()` only exposes the raw-shape type, and
ts/packages/providers/claude-agent-sdk/test/claude-agent-sdk-ref.test.ts new
+130
@@ -0,0 +1,130 @@
1 +/**
2 + * Regression test: `ClaudeAgentSDKProvider.wrapTool` must dereference internal
3 + * `$ref`/`$defs` before handing the schema to `jsonSchemaToZodSchema`.
4 + * Without dereferencing, a `$ref`-typed property degrades to `z.any()` and
5 + * silently accepts any value.
6 + */
7 +
8 +import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
9 +import type { Tool } from '@composio/core';
10 +import { ClaudeAgentSDKProvider } from '../src';
11 +
12 +// Mock the claude-agent-sdk module (per-file scoping keeps this independent of
13 +// claude-agent-sdk.test.ts).
14 +vi.mock('@anthropic-ai/claude-agent-sdk', () => {
15 + return {
16 + tool: vi.fn().mockImplementation((name, description, schema, handler) => {
17 + return {
18 + name,
19 + description,
20 + schema,
21 + handler,
22 + _isMockedClaudeAgentTool: true,
23 + };
24 + }),
25 + };
26 +});
27 +
28 +import { tool } from '@anthropic-ai/claude-agent-sdk';
29 +
30 +type MinimalZodSchema = {
31 + safeParse: (value: unknown) => { success: boolean };
32 +};
33 +
34 +type MockedToolFn = Mock<
35 + (
36 + name: string,
37 + description: string | undefined,
38 + schema: MinimalZodSchema,
39 + handler: unknown
40 + ) => unknown
41 +>;
42 +
43 +const refTool: Tool = {
44 + slug: 'TEST_REF_TOOL',
45 + name: 'Ref Tool',
46 + description: 'Tool whose schema carries internal $ref pointers',
47 + toolkit: { slug: 'reftoolkit', name: 'Ref Toolkit' },
48 + version: '20260828_00',
49 + availableVersions: ['20260828_00'],
50 + tags: [],
51 + inputParameters: {
52 + type: 'object',
53 + properties: {
54 + message: { $ref: '#/$defs/Message' },
55 + },
56 + required: ['message'],
57 + $defs: {
58 + Message: {
59 + type: 'object',
60 + properties: {
61 + subject: { type: 'string' },
62 + body: { type: 'string' },
63 + },
64 + required: ['subject', 'body'],
65 + additionalProperties: false,
66 + },
67 + },
68 + } as unknown as Tool['inputParameters'],
69 +} as unknown as Tool;
70 +
71 +const danglingRefTool: Tool = {
72 + ...refTool,
73 + slug: 'TEST_DANGLING_REF_TOOL',
74 + inputParameters: {
75 + type: 'object',
76 + properties: {
77 + message: { $ref: '#/$defs/Message' },
78 + },
79 + required: ['message'],
80 + } as unknown as Tool['inputParameters'],
81 +};
82 +
83 +const recursiveRefTool: Tool = {
84 + ...refTool,
85 + slug: 'TEST_RECURSIVE_REF_TOOL',
86 + inputParameters: {
87 + type: 'object',
88 + properties: {
89 + node: { $ref: '#/$defs/Node' },
90 + },
91 + required: ['node'],
92 + $defs: {
93 + Node: {
94 + type: 'object',
95 + properties: {
96 + value: { type: 'string' },
97 + child: { $ref: '#/$defs/Node' },
98 + },
99 + required: ['value'],
100 + },
101 + },
102 + } as unknown as Tool['inputParameters'],
103 +};
104 +
105 +describe('ClaudeAgentSDKProvider regression: $ref in JSON Schema', () => {
106 + let provider: ClaudeAgentSDKProvider;
107 + let executeToolFn: (toolSlug: string, params: Record<string, unknown>) => Promise<unknown>;
108 +
109 + beforeEach(() => {
110 + provider = new ClaudeAgentSDKProvider();
111 + executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
112 + vi.clearAllMocks();
113 + });
114 +
115 + it('produces a Zod schema that validates the $defs-described shape', () => {
116 + provider.wrapTool(refTool, executeToolFn);
117 + const schema = (tool as unknown as MockedToolFn).mock.calls[0][2];
118 +
119 + expect(schema.safeParse({ message: { subject: 's', body: 'b' } }).success).toBe(true);
120 + expect(schema.safeParse({ message: 42 }).success).toBe(false);
121 + });
122 +
123 + it('does not throw when $ref points into an undeclared $defs block', () => {
124 + expect(() => provider.wrapTool(danglingRefTool, executeToolFn)).not.toThrow();
125 + });
126 +
127 + it('does not throw on a self-referential $defs schema', () => {
128 + expect(() => provider.wrapTool(recursiveRefTool, executeToolFn)).not.toThrow();
129 + });
130 +});
ts/packages/providers/google/src/index.ts
+6 -1
@@ -17,6 +17,7 @@ import {
17 McpServerGetResponse,
18 normalizeToolArguments,
19 deduplicateJsonSchemaRequiredArrays,
20 + dereferenceJsonSchema,
21 ensureObjectTypeOnProperties,
22 } from '@composio/core';
23 import { FunctionDeclaration, Schema } from '@google/genai';
@@ -130,7 +131,11 @@ export class GoogleProvider extends BaseNonAgenticProvider<
131 */
132 wrapTool(tool: Tool): GoogleTool {
133 const inputParameters = ensureObjectTypeOnProperties(
133 - deduplicateJsonSchemaRequiredArrays(tool.inputParameters)
134 + deduplicateJsonSchemaRequiredArrays(
135 + dereferenceJsonSchema(tool.inputParameters ?? { type: 'object', properties: {} }, {
136 + onUnresolved: 'sentinel',
137 + })
138 + )
139 );
140
141 return {
ts/packages/providers/google/test/google-ref.test.ts new
+105
@@ -0,0 +1,105 @@
1 +/**
2 + * Regression test: `GoogleProvider.wrapTool` rebuilds the root schema from
3 + * `properties`/`required`, which used to discard the `$defs` block while
4 + * `$ref` pointers inside `properties` stayed dangling. The Google GenAI
5 + * `Schema` type has no `ref`/`defs` field, so a `$ref` on the `parameters`
6 + * path is unrepresentable and the API answers 400. `wrapTool` now
7 + * dereferences `$ref`/`$defs` before the rebuild.
8 + */
9 +
10 +import { describe, it, expect, beforeEach } from 'vitest';
11 +import type { Tool } from '@composio/core';
12 +import { GoogleProvider } from '../src';
13 +
14 +const containsInternalRef = (value: unknown): boolean => {
15 + if (value === null || typeof value !== 'object') return false;
16 + if (Array.isArray(value)) return value.some(containsInternalRef);
17 + const node = value as Record<string, unknown>;
18 + if (typeof node.$ref === 'string' && node.$ref.startsWith('#')) return true;
19 + return Object.values(node).some(containsInternalRef);
20 +};
21 +
22 +const refTool: Tool = {
23 + slug: 'TEST_REF_TOOL',
24 + name: 'Ref Tool',
25 + description: 'Tool whose schema carries internal $ref pointers',
26 + toolkit: { slug: 'reftoolkit', name: 'Ref Toolkit' },
27 + version: '20260828_00',
28 + availableVersions: ['20260828_00'],
29 + tags: [],
30 + inputParameters: {
31 + type: 'object',
32 + properties: {
33 + message: { $ref: '#/$defs/Message' },
34 + },
35 + required: ['message'],
36 + $defs: {
37 + Message: {
38 + type: 'object',
39 + properties: {
40 + subject: { type: 'string' },
41 + body: { type: 'string' },
42 + },
43 + required: ['subject', 'body'],
44 + additionalProperties: false,
45 + },
46 + },
47 + } as unknown as Tool['inputParameters'],
48 +} as unknown as Tool;
49 +
50 +const danglingRefTool: Tool = {
51 + ...refTool,
52 + slug: 'TEST_DANGLING_REF_TOOL',
53 + inputParameters: {
54 + type: 'object',
55 + properties: {
56 + message: { $ref: '#/$defs/Message' },
57 + },
58 + required: ['message'],
59 + } as unknown as Tool['inputParameters'],
60 +};
61 +
62 +const recursiveRefTool: Tool = {
63 + ...refTool,
64 + slug: 'TEST_RECURSIVE_REF_TOOL',
65 + inputParameters: {
66 + type: 'object',
67 + properties: {
68 + node: { $ref: '#/$defs/Node' },
69 + },
70 + required: ['node'],
71 + $defs: {
72 + Node: {
73 + type: 'object',
74 + properties: {
75 + value: { type: 'string' },
76 + child: { $ref: '#/$defs/Node' },
77 + },
78 + required: ['value'],
79 + },
80 + },
81 + } as unknown as Tool['inputParameters'],
82 +};
83 +
84 +describe('GoogleProvider regression: $ref in JSON Schema', () => {
85 + let provider: GoogleProvider;
86 +
87 + beforeEach(() => {
88 + provider = new GoogleProvider();
89 + });
90 +
91 + it('inlines internal $ref/$defs instead of stranding a dangling pointer', () => {
92 + const wrapped = provider.wrapTool(refTool);
93 +
94 + expect(containsInternalRef(wrapped.parameters)).toBe(false);
95 + expect(wrapped.parameters?.required).toContain('message');
96 + });
97 +
98 + it('does not throw when $ref points into an undeclared $defs block', () => {
99 + expect(() => provider.wrapTool(danglingRefTool)).not.toThrow();
100 + });
101 +
102 + it('does not throw on a self-referential $defs schema', () => {
103 + expect(() => provider.wrapTool(recursiveRefTool)).not.toThrow();
104 + });
105 +});
ts/packages/providers/langchain/src/index.ts
+5 -2
@@ -11,6 +11,7 @@
11 */
12 import {
13 BaseAgenticProvider,
14 + dereferenceJsonSchema,
15 jsonSchemaToZodSchema,
16 Tool,
17 ExecuteToolFn,
@@ -136,10 +137,12 @@ export class LangchainProvider extends BaseAgenticProvider<
137 if (!tool.inputParameters) {
138 throw new Error('Tool input parameters are not defined');
139 }
139 - const parameters = jsonSchemaToZodSchema(tool.inputParameters);
140 + const parameters = jsonSchemaToZodSchema(
141 + dereferenceJsonSchema(tool.inputParameters, { onUnresolved: 'sentinel' })
142 + );
143
144 // See https://github.com/langchain-ai/langchainjs/issues/8468 and pnpm-workspace.yaml.
142 - // @ts-ignore: error TS2589: Type instantiation is excessively deep and possibly infinite.
145 + // @ts-expect-error: error TS2589: Type instantiation is excessively deep and possibly infinite.
146 return new DynamicStructuredTool({
147 name: toolName,
148 description: description || '',
ts/packages/providers/langchain/test/langchain-ref.test.ts new
+101
@@ -0,0 +1,101 @@
1 +/**
2 + * Regression test: `LangchainProvider.wrapTool` must dereference internal
3 + * `$ref`/`$defs` before handing the schema to `jsonSchemaToZodSchema`.
4 + * Without dereferencing, a `$ref`-typed property degrades to `z.any()` and
5 + * silently accepts any value.
6 + */
7 +
8 +import { describe, it, expect, vi, beforeEach } from 'vitest';
9 +import type { Tool } from '@composio/core';
10 +import { LangchainProvider } from '../src';
11 +
12 +const refTool: Tool = {
13 + slug: 'TEST_REF_TOOL',
14 + name: 'Ref Tool',
15 + description: 'Tool whose schema carries internal $ref pointers',
16 + toolkit: { slug: 'reftoolkit', name: 'Ref Toolkit' },
17 + version: '20260828_00',
18 + availableVersions: ['20260828_00'],
19 + tags: [],
20 + inputParameters: {
21 + type: 'object',
22 + properties: {
23 + message: { $ref: '#/$defs/Message' },
24 + },
25 + required: ['message'],
26 + $defs: {
27 + Message: {
28 + type: 'object',
29 + properties: {
30 + subject: { type: 'string' },
31 + body: { type: 'string' },
32 + },
33 + required: ['subject', 'body'],
34 + additionalProperties: false,
35 + },
36 + },
37 + } as unknown as Tool['inputParameters'],
38 +} as unknown as Tool;
39 +
40 +// Same tool but with the $defs block deleted — GMAIL_FETCH_EMAILS style.
41 +const danglingRefTool: Tool = {
42 + ...refTool,
43 + slug: 'TEST_DANGLING_REF_TOOL',
44 + inputParameters: {
45 + type: 'object',
46 + properties: {
47 + message: { $ref: '#/$defs/Message' },
48 + },
49 + required: ['message'],
50 + } as unknown as Tool['inputParameters'],
51 +};
52 +
53 +// A self-referential schema has no finite inlined form.
54 +const recursiveRefTool: Tool = {
55 + ...refTool,
56 + slug: 'TEST_RECURSIVE_REF_TOOL',
57 + inputParameters: {
58 + type: 'object',
59 + properties: {
60 + node: { $ref: '#/$defs/Node' },
61 + },
62 + required: ['node'],
63 + $defs: {
64 + Node: {
65 + type: 'object',
66 + properties: {
67 + value: { type: 'string' },
68 + child: { $ref: '#/$defs/Node' },
69 + },
70 + required: ['value'],
71 + },
72 + },
73 + } as unknown as Tool['inputParameters'],
74 +};
75 +
76 +describe('LangchainProvider regression: $ref in JSON Schema', () => {
77 + let provider: LangchainProvider;
78 + let executeToolFn: (toolSlug: string, params: Record<string, unknown>) => Promise<unknown>;
79 +
80 + beforeEach(() => {
81 + provider = new LangchainProvider();
82 + executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
83 + });
84 +
85 + it('produces a Zod schema that validates the $defs-described shape', () => {
86 + const wrapped = provider.wrapTool(refTool, executeToolFn);
87 + const schema = wrapped.schema as { safeParse: (value: unknown) => { success: boolean } };
88 +
89 + expect(schema.safeParse({ message: { subject: 's', body: 'b' } }).success).toBe(true);
90 + // Before the fix, $ref degraded to z.any() and this would have passed.
91 + expect(schema.safeParse({ message: 42 }).success).toBe(false);
92 + });
93 +
94 + it('does not throw when $ref points into an undeclared $defs block', () => {
95 + expect(() => provider.wrapTool(danglingRefTool, executeToolFn)).not.toThrow();
96 + });
97 +
98 + it('does not throw on a self-referential $defs schema', () => {
99 + expect(() => provider.wrapTool(recursiveRefTool, executeToolFn)).not.toThrow();
100 + });
101 +});
ts/packages/providers/llamaindex/src/index.ts
+4 -1
@@ -12,6 +12,7 @@ import {
12 ExecuteToolFn,
13 McpServerGetResponse,
14 McpUrlResponse,
15 + dereferenceJsonSchema,
16 jsonSchemaToZodSchema,
17 normalizeToolArguments,
18 } from '@composio/core';
@@ -34,7 +35,9 @@ export class LlamaindexProvider extends BaseAgenticProvider<
35 */
36 wrapTool(tool: Tool, executeTool: ExecuteToolFn): LlamaindexTool {
37 const inputParams = tool.inputParameters;
37 - const inputParametersSchema = jsonSchemaToZodSchema(inputParams ?? {});
38 + const inputParametersSchema = jsonSchemaToZodSchema(
39 + dereferenceJsonSchema(inputParams ?? {}, { onUnresolved: 'sentinel' })
40 + );
41 return createLlamaindexTool({
42 name: tool.slug,
43 description: tool.description ?? tool.name ?? '',
ts/packages/providers/llamaindex/test/llamaindex-ref.test.ts new
+117
@@ -0,0 +1,117 @@
1 +/**
2 + * Regression test: `LlamaindexProvider.wrapTool` must dereference internal
3 + * `$ref`/`$defs` before handing the schema to `jsonSchemaToZodSchema`.
4 + * Without dereferencing, a `$ref`-typed property degrades to `z.any()` and
5 + * silently accepts any value.
6 + */
7 +
8 +import { describe, it, expect, vi, beforeEach } from 'vitest';
9 +import type { Tool } from '@composio/core';
10 +import { LlamaindexProvider } from '../src';
11 +
12 +// Mock the llamaindex module (per-file scoping keeps this independent of llamaindex.test.ts).
13 +vi.mock('llamaindex', () => {
14 + return {
15 + tool: vi.fn().mockImplementation(config => ({
16 + metadata: {
17 + name: config.name,
18 + description: config.description,
19 + parameters: config.parameters,
20 + },
21 + call: config.execute,
22 + _type: 'llamaindex_tool',
23 + _config: config,
24 + })),
25 + JSONValue: {},
26 + };
27 +});
28 +
29 +const refTool: Tool = {
30 + slug: 'TEST_REF_TOOL',
31 + name: 'Ref Tool',
32 + description: 'Tool whose schema carries internal $ref pointers',
33 + toolkit: { slug: 'reftoolkit', name: 'Ref Toolkit' },
34 + version: '20260828_00',
35 + availableVersions: ['20260828_00'],
36 + tags: [],
37 + inputParameters: {
38 + type: 'object',
39 + properties: {
40 + message: { $ref: '#/$defs/Message' },
41 + },
42 + required: ['message'],
43 + $defs: {
44 + Message: {
45 + type: 'object',
46 + properties: {
47 + subject: { type: 'string' },
48 + body: { type: 'string' },
49 + },
50 + required: ['subject', 'body'],
51 + additionalProperties: false,
52 + },
53 + },
54 + } as unknown as Tool['inputParameters'],
55 +} as unknown as Tool;
56 +
57 +const danglingRefTool: Tool = {
58 + ...refTool,
59 + slug: 'TEST_DANGLING_REF_TOOL',
60 + inputParameters: {
61 + type: 'object',
62 + properties: {
63 + message: { $ref: '#/$defs/Message' },
64 + },
65 + required: ['message'],
66 + } as unknown as Tool['inputParameters'],
67 +};
68 +
69 +const recursiveRefTool: Tool = {
70 + ...refTool,
71 + slug: 'TEST_RECURSIVE_REF_TOOL',
72 + inputParameters: {
73 + type: 'object',
74 + properties: {
75 + node: { $ref: '#/$defs/Node' },
76 + },
77 + required: ['node'],
78 + $defs: {
79 + Node: {
80 + type: 'object',
81 + properties: {
82 + value: { type: 'string' },
83 + child: { $ref: '#/$defs/Node' },
84 + },
85 + required: ['value'],
86 + },
87 + },
88 + } as unknown as Tool['inputParameters'],
89 +};
90 +
91 +describe('LlamaindexProvider regression: $ref in JSON Schema', () => {
92 + let provider: LlamaindexProvider;
93 + let executeToolFn: (toolSlug: string, params: Record<string, unknown>) => Promise<unknown>;
94 +
95 + beforeEach(() => {
96 + provider = new LlamaindexProvider();
97 + executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
98 + });
99 +
100 + it('produces a Zod schema that validates the $defs-described shape', () => {
101 + const wrapped = provider.wrapTool(refTool, executeToolFn);
102 + const schema = wrapped.metadata.parameters as {
103 + safeParse: (value: unknown) => { success: boolean };
104 + };
105 +
106 + expect(schema.safeParse({ message: { subject: 's', body: 'b' } }).success).toBe(true);
107 + expect(schema.safeParse({ message: 42 }).success).toBe(false);
108 + });
109 +
110 + it('does not throw when $ref points into an undeclared $defs block', () => {
111 + expect(() => provider.wrapTool(danglingRefTool, executeToolFn)).not.toThrow();
112 + });
113 +
114 + it('does not throw on a self-referential $defs schema', () => {
115 + expect(() => provider.wrapTool(recursiveRefTool, executeToolFn)).not.toThrow();
116 + });
117 +});
ts/packages/providers/openai-agents/src/index.ts
+4 -1
@@ -18,6 +18,7 @@ import {
18 McpServerGetResponse,
19 normalizeToolArguments,
20 deduplicateJsonSchemaRequiredArrays,
21 + dereferenceJsonSchema,
22 logger,
23 omitNullToolArguments,
24 toStrictJsonSchema,
@@ -140,7 +141,9 @@ export class OpenAIAgentsProvider extends BaseAgenticProvider<
141 * ```
142 */
143 wrapTool(composioTool: ComposioTool, executeTool: ExecuteToolFn): OpenAIAgentTool {
143 - const inputParameters = deduplicateJsonSchemaRequiredArrays(composioTool.inputParameters);
144 + const inputParameters = deduplicateJsonSchemaRequiredArrays(
145 + dereferenceJsonSchema(composioTool.inputParameters ?? {}, { onUnresolved: 'sentinel' })
146 + );
147
148 // Strict mode applies OpenAI's structured-output contract at every
149 // depth: all properties required, closed objects, optional properties
ts/packages/providers/openai-agents/test/openai-agents-ref.test.ts new
+154
@@ -0,0 +1,154 @@
1 +/**
2 + * Regression test: `OpenAIAgentsProvider.wrapTool`'s non-strict fallback
3 + * rebuilds the root schema from `properties`/`required`, which used to
4 + * discard the `$defs` block while `$ref` pointers inside `properties`
5 + * stayed dangling. `wrapTool` now dereferences `$ref`/`$defs` before that
6 + * rebuild.
7 + *
8 + * The strict branch is intentionally different: OpenAI's structured outputs
9 + * support `$defs`/`$ref` natively, including recursion, so `toStrictJsonSchema`
10 + * keeps local refs rather than inlining them. This file also guards that the
11 + * strict branch stays untouched by the fix applied to the fallback.
12 + */
13 +
14 +import { describe, it, expect, vi, beforeEach } from 'vitest';
15 +import type { Tool, ExecuteToolFn } from '@composio/core';
16 +import { OpenAIAgentsProvider } from '../src';
17 +
18 +interface MockedOpenAIAgentTool {
19 + name: string;
20 + description: string;
21 + parameters: Record<string, unknown>;
22 + strict: boolean;
23 + execute: Function;
24 + _isMockedOpenAIAgentTool: boolean;
25 +}
26 +
27 +// Mock the @openai/agents module (per-file scoping keeps this independent of
28 +// openai-agents.test.ts).
29 +vi.mock('@openai/agents', () => {
30 + return {
31 + tool: vi.fn().mockImplementation(toolConfig => {
32 + return {
33 + ...toolConfig,
34 + _isMockedOpenAIAgentTool: true,
35 + } as MockedOpenAIAgentTool;
36 + }),
37 + };
38 +});
39 +
40 +const containsInternalRef = (value: unknown): boolean => {
41 + if (value === null || typeof value !== 'object') return false;
42 + if (Array.isArray(value)) return value.some(containsInternalRef);
43 + const node = value as Record<string, unknown>;
44 + if (typeof node.$ref === 'string' && node.$ref.startsWith('#')) return true;
45 + return Object.values(node).some(containsInternalRef);
46 +};
47 +
48 +const refTool: Tool = {
49 + slug: 'TEST_REF_TOOL',
50 + name: 'Ref Tool',
51 + description: 'Tool whose schema carries internal $ref pointers',
52 + toolkit: { slug: 'reftoolkit', name: 'Ref Toolkit' },
53 + version: '20260828_00',
54 + availableVersions: ['20260828_00'],
55 + tags: [],
56 + inputParameters: {
57 + type: 'object',
58 + properties: {
59 + message: { $ref: '#/$defs/Message' },
60 + },
61 + required: ['message'],
62 + $defs: {
63 + Message: {
64 + type: 'object',
65 + properties: {
66 + subject: { type: 'string' },
67 + body: { type: 'string' },
68 + },
69 + required: ['subject', 'body'],
70 + additionalProperties: false,
71 + },
72 + },
73 + } as unknown as Tool['inputParameters'],
74 +} as unknown as Tool;
75 +
76 +const danglingRefTool: Tool = {
77 + ...refTool,
78 + slug: 'TEST_DANGLING_REF_TOOL',
79 + inputParameters: {
80 + type: 'object',
81 + properties: {
82 + message: { $ref: '#/$defs/Message' },
83 + },
84 + required: ['message'],
85 + } as unknown as Tool['inputParameters'],
86 +};
87 +
88 +const recursiveRefTool: Tool = {
89 + ...refTool,
90 + slug: 'TEST_RECURSIVE_REF_TOOL',
91 + inputParameters: {
92 + type: 'object',
93 + properties: {
94 + node: { $ref: '#/$defs/Node' },
95 + },
96 + required: ['node'],
97 + $defs: {
98 + Node: {
99 + type: 'object',
100 + properties: {
101 + value: { type: 'string' },
102 + child: { $ref: '#/$defs/Node' },
103 + },
104 + required: ['value'],
105 + },
106 + },
107 + } as unknown as Tool['inputParameters'],
108 +};
109 +
110 +describe('OpenAIAgentsProvider regression: $ref in JSON Schema', () => {
111 + let provider: OpenAIAgentsProvider;
112 + let executeToolFn: ExecuteToolFn;
113 +
114 + beforeEach(() => {
115 + provider = new OpenAIAgentsProvider();
116 + executeToolFn = vi.fn().mockResolvedValue({
117 + data: {},
118 + error: null,
119 + successful: true,
120 + }) as unknown as ExecuteToolFn;
121 + vi.clearAllMocks();
122 + });
123 +
124 + describe('non-strict fallback (bucket B fix)', () => {
125 + it('inlines internal $ref/$defs instead of stranding a dangling pointer', () => {
126 + const wrapped = provider.wrapTool(refTool, executeToolFn) as unknown as MockedOpenAIAgentTool;
127 +
128 + expect(containsInternalRef(wrapped.parameters)).toBe(false);
129 + expect(wrapped.parameters.required).toContain('message');
130 + });
131 +
132 + it('does not throw when $ref points into an undeclared $defs block', () => {
133 + expect(() => provider.wrapTool(danglingRefTool, executeToolFn)).not.toThrow();
134 + });
135 +
136 + it('does not throw on a self-referential $defs schema', () => {
137 + expect(() => provider.wrapTool(recursiveRefTool, executeToolFn)).not.toThrow();
138 + });
139 + });
140 +
141 + describe('strict branch (must stay untouched)', () => {
142 + it('keeps $defs and the $ref pointer intact under strict mode', () => {
143 + const strictProvider = new OpenAIAgentsProvider({ strict: true });
144 + const wrapped = strictProvider.wrapTool(
145 + refTool,
146 + executeToolFn
147 + ) as unknown as MockedOpenAIAgentTool;
148 +
149 + expect(wrapped.strict).toBe(true);
150 + expect(containsInternalRef(wrapped.parameters)).toBe(true);
151 + expect(wrapped.parameters.$defs).toBeDefined();
152 + });
153 + });
154 +});
ts/packages/providers/vercel/src/index.ts
+1 -1
@@ -150,7 +150,7 @@ export class VercelProvider extends BaseAgenticProvider<
150 // The Zod converter does not follow $ref, so inline the definitions the
151 // strict rewrite keeps (cycles fall back to the permissive sentinel).
152 const inputParametersSchema = jsonSchemaToZodSchema(
153 - strictSource ? dereferenceJsonSchema(parameters, { onUnresolved: 'sentinel' }) : parameters
153 + dereferenceJsonSchema(parameters, { onUnresolved: 'sentinel' })
154 );
155
156 return tool({
ts/packages/providers/vercel/test/vercel-ref.test.ts new
+128
@@ -0,0 +1,128 @@
1 +/**
2 + * Regression test: `VercelProvider.wrapTool` must dereference internal
3 + * `$ref`/`$defs` before handing the schema to `jsonSchemaToZodSchema`, on
4 + * both the default and strict paths. Without dereferencing, a `$ref`-typed
5 + * property degrades to `z.any()` and silently accepts any value.
6 + */
7 +
8 +import { describe, it, expect, vi, beforeEach } from 'vitest';
9 +import type { Tool } from '@composio/core';
10 +import { VercelProvider } from '../src';
11 +
12 +interface MockedVercelTool {
13 + description: string;
14 + inputSchema: unknown;
15 + execute: Function;
16 + _isMockedVercelTool: boolean;
17 +}
18 +
19 +// Mock the ai module (per-file scoping keeps this independent of vercel.test.ts).
20 +vi.mock('ai', () => {
21 + return {
22 + tool: vi.fn().mockImplementation(toolConfig => {
23 + return {
24 + ...toolConfig,
25 + _isMockedVercelTool: true,
26 + } as MockedVercelTool;
27 + }),
28 + jsonSchema: vi.fn().mockImplementation(schema => schema),
29 + };
30 +});
31 +
32 +const refTool: Tool = {
33 + slug: 'TEST_REF_TOOL',
34 + name: 'Ref Tool',
35 + description: 'Tool whose schema carries internal $ref pointers',
36 + toolkit: { slug: 'reftoolkit', name: 'Ref Toolkit' },
37 + version: '20260828_00',
38 + availableVersions: ['20260828_00'],
39 + tags: [],
40 + inputParameters: {
41 + type: 'object',
42 + properties: {
43 + message: { $ref: '#/$defs/Message' },
44 + },
45 + required: ['message'],
46 + $defs: {
47 + Message: {
48 + type: 'object',
49 + properties: {
50 + subject: { type: 'string' },
51 + body: { type: 'string' },
52 + },
53 + required: ['subject', 'body'],
54 + additionalProperties: false,
55 + },
56 + },
57 + } as unknown as Tool['inputParameters'],
58 +} as unknown as Tool;
59 +
60 +const danglingRefTool: Tool = {
61 + ...refTool,
62 + slug: 'TEST_DANGLING_REF_TOOL',
63 + inputParameters: {
64 + type: 'object',
65 + properties: {
66 + message: { $ref: '#/$defs/Message' },
67 + },
68 + required: ['message'],
69 + } as unknown as Tool['inputParameters'],
70 +};
71 +
72 +const recursiveRefTool: Tool = {
73 + ...refTool,
74 + slug: 'TEST_RECURSIVE_REF_TOOL',
75 + inputParameters: {
76 + type: 'object',
77 + properties: {
78 + node: { $ref: '#/$defs/Node' },
79 + },
80 + required: ['node'],
81 + $defs: {
82 + Node: {
83 + type: 'object',
84 + properties: {
85 + value: { type: 'string' },
86 + child: { $ref: '#/$defs/Node' },
87 + },
88 + required: ['value'],
89 + },
90 + },
91 + } as unknown as Tool['inputParameters'],
92 +};
93 +
94 +describe('VercelProvider regression: $ref in JSON Schema', () => {
95 + let provider: VercelProvider;
96 + let executeToolFn: (toolSlug: string, params: Record<string, unknown>) => Promise<unknown>;
97 +
98 + beforeEach(() => {
99 + provider = new VercelProvider();
100 + executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
101 + vi.clearAllMocks();
102 + });
103 +
104 + it('produces a Zod schema that validates the $defs-described shape (default path)', () => {
105 + const wrapped = provider.wrapTool(refTool, executeToolFn) as unknown as MockedVercelTool;
106 + const schema = wrapped.inputSchema as { safeParse: (value: unknown) => { success: boolean } };
107 +
108 + expect(schema.safeParse({ message: { subject: 's', body: 'b' } }).success).toBe(true);
109 + expect(schema.safeParse({ message: 42 }).success).toBe(false);
110 + });
111 +
112 + it('produces a Zod schema that validates the $defs-described shape (strict path)', () => {
113 + const strictProvider = new VercelProvider({ strict: true });
114 + const wrapped = strictProvider.wrapTool(refTool, executeToolFn) as unknown as MockedVercelTool;
115 + const schema = wrapped.inputSchema as { safeParse: (value: unknown) => { success: boolean } };
116 +
117 + expect(schema.safeParse({ message: { subject: 's', body: 'b' } }).success).toBe(true);
118 + expect(schema.safeParse({ message: 42 }).success).toBe(false);
119 + });
120 +
121 + it('does not throw when $ref points into an undeclared $defs block', () => {
122 + expect(() => provider.wrapTool(danglingRefTool, executeToolFn)).not.toThrow();
123 + });
124 +
125 + it('does not throw on a self-referential $defs schema', () => {
126 + expect(() => provider.wrapTool(recursiveRefTool, executeToolFn)).not.toThrow();
127 + });
128 +});