@devries-cameron20 / composio-1 / commits / 5300bf8ba
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.

test(mastra): add red regression tests for $ref handling [PLEN-2244]

Adds a new `JsonSchemaRefResolutionError` and two failing test files that demonstrate the bug: - `ts/packages/core/test/utils/jsonSchema.test.ts` — unit tests for an upcoming `dereferenceJsonSchema` utility (currently missing): basic resolution, chained refs, container coverage (items / oneOf / anyOf / allOf / not / additionalProperties / patternProperties / prefixItems), legacy `definitions` (Draft 7), sibling-keyword merge per Draft 2020-12, cycle-break with a permissive object, missing-target error, depth-cap error, external `$ref` left untouched, no input mutation, JSON Pointer escape decoding, and array-index pointers. - `ts/packages/providers/mastra/test/mastra-ref.test.ts` — un-mocked integration test against the real `@mastra/schema-compat`. Today, `applyCompatLayer` silently degrades a `\$ref`-typed property to a permissive `anyOf` of all primitives — losing the type info from `\$defs` entirely. The test asserts the resolved type structure survives the wrap. The green commit follows.

jkomyno committed Apr 30, 2026 at 01:29 UTC 5300bf8ba7cacc9328af7f1f781dae55943538a2
3 files changed +380
ts/packages/core/src/errors/ValidationErrors.ts
+18
@@ -9,6 +9,7 @@ import { ComposioError, ComposioErrorOptions } from './ComposioError';
9 export const ValidationErrorCodes = {
10 VALIDATION_ERROR: 'VALIDATION_ERROR',
11 JSON_SCHEMA_TO_ZOD_ERROR: 'JSON_SCHEMA_TO_ZOD_ERROR',
12 + JSON_SCHEMA_REF_RESOLUTION_ERROR: 'JSON_SCHEMA_REF_RESOLUTION_ERROR',
13 } as const;
14
15 export class ValidationError extends ComposioError {
@@ -79,3 +80,20 @@ export class JsonSchemaToZodError extends ComposioError {
80 });
81 }
82 }
83 +
84 +/**
85 + * Thrown when a JSON Schema `$ref` pointer cannot be resolved against the
86 + * document. Used by `dereferenceJsonSchema` to surface malformed pointers,
87 + * missing `$defs`/`definitions` targets, or chains exceeding the depth cap.
88 + */
89 +export class JsonSchemaRefResolutionError extends ComposioError {
90 + constructor(
91 + message: string = 'Failed to resolve JSON Schema $ref',
92 + options: ComposioErrorOptions = {}
93 + ) {
94 + super(message, {
95 + ...options,
96 + code: options.code || ValidationErrorCodes.JSON_SCHEMA_REF_RESOLUTION_ERROR,
97 + });
98 + }
99 +}
ts/packages/core/test/utils/jsonSchema.test.ts new
+227
@@ -0,0 +1,227 @@
1 +import { describe, it, expect } from 'vitest';
2 +import { dereferenceJsonSchema } from '../../src/utils/jsonSchema';
3 +import { JsonSchemaRefResolutionError } from '../../src/errors/ValidationErrors';
4 +
5 +const containsRef = (value: unknown): boolean => {
6 + if (value === null || typeof value !== 'object') return false;
7 + if (Array.isArray(value)) return value.some(containsRef);
8 + if ('$ref' in (value as Record<string, unknown>)) return true;
9 + return Object.values(value as Record<string, unknown>).some(containsRef);
10 +};
11 +
12 +describe('dereferenceJsonSchema', () => {
13 + it('inlines a single internal $ref under $defs', () => {
14 + const out = dereferenceJsonSchema({
15 + type: 'object',
16 + properties: { user: { $ref: '#/$defs/User' } },
17 + required: ['user'],
18 + $defs: { User: { type: 'string' } },
19 + });
20 +
21 + expect(out).toEqual({
22 + type: 'object',
23 + properties: { user: { type: 'string' } },
24 + required: ['user'],
25 + });
26 + expect(containsRef(out)).toBe(false);
27 + });
28 +
29 + it('resolves a chain of refs A -> B -> C', () => {
30 + const out = dereferenceJsonSchema({
31 + type: 'object',
32 + properties: { v: { $ref: '#/$defs/A' } },
33 + $defs: {
34 + A: { $ref: '#/$defs/B' },
35 + B: { $ref: '#/$defs/C' },
36 + C: { type: 'integer' },
37 + },
38 + });
39 +
40 + expect(containsRef(out)).toBe(false);
41 + expect((out as { properties: { v: unknown } }).properties.v).toEqual({ type: 'integer' });
42 + });
43 +
44 + it('walks containers reflectively (items, oneOf, anyOf, allOf, not, additionalProperties, patternProperties, prefixItems)', () => {
45 + const out = dereferenceJsonSchema({
46 + type: 'object',
47 + properties: {
48 + a: { type: 'array', items: { $ref: '#/$defs/Leaf' } },
49 + b: { oneOf: [{ $ref: '#/$defs/Leaf' }, { type: 'null' }] },
50 + c: { anyOf: [{ $ref: '#/$defs/Leaf' }] },
51 + d: { allOf: [{ $ref: '#/$defs/Leaf' }] },
52 + e: { not: { $ref: '#/$defs/Leaf' } },
53 + f: { type: 'object', additionalProperties: { $ref: '#/$defs/Leaf' } },
54 + g: {
55 + type: 'object',
56 + patternProperties: { '^x_': { $ref: '#/$defs/Leaf' } },
57 + },
58 + h: { type: 'array', prefixItems: [{ $ref: '#/$defs/Leaf' }] },
59 + },
60 + $defs: { Leaf: { type: 'string' } },
61 + });
62 +
63 + expect(containsRef(out)).toBe(false);
64 + });
65 +
66 + it('resolves Draft 7 legacy `definitions`', () => {
67 + const out = dereferenceJsonSchema({
68 + type: 'object',
69 + properties: { name: { $ref: '#/definitions/Name' } },
70 + definitions: { Name: { type: 'string', minLength: 1 } },
71 + });
72 +
73 + expect(containsRef(out)).toBe(false);
74 + expect((out as { properties: { name: unknown } }).properties.name).toEqual({
75 + type: 'string',
76 + minLength: 1,
77 + });
78 + });
79 +
80 + it('mixes $defs and definitions transitively', () => {
81 + const out = dereferenceJsonSchema({
82 + type: 'object',
83 + properties: { v: { $ref: '#/definitions/A' } },
84 + definitions: { A: { $ref: '#/$defs/B' } },
85 + $defs: { B: { type: 'boolean' } },
86 + });
87 +
88 + expect(containsRef(out)).toBe(false);
89 + expect((out as { properties: { v: unknown } }).properties.v).toEqual({ type: 'boolean' });
90 + });
91 +
92 + it('shallow-merges sibling keywords next to $ref (Draft 2020-12 semantics; siblings win on collision)', () => {
93 + const out = dereferenceJsonSchema({
94 + type: 'object',
95 + properties: {
96 + v: {
97 + $ref: '#/$defs/Foo',
98 + description: 'caller override',
99 + default: null,
100 + },
101 + },
102 + $defs: {
103 + Foo: { type: 'string', description: 'target description' },
104 + },
105 + });
106 +
107 + const v = (out as { properties: { v: Record<string, unknown> } }).properties.v;
108 + expect(v.type).toBe('string');
109 + expect(v.description).toBe('caller override');
110 + expect(v.default).toBeNull();
111 + expect(containsRef(out)).toBe(false);
112 + });
113 +
114 + it('breaks recursive $ref cycles with a permissive object sentinel', () => {
115 + const out = dereferenceJsonSchema({
116 + $ref: '#/$defs/Tree',
117 + $defs: {
118 + Tree: {
119 + type: 'object',
120 + properties: {
121 + children: { type: 'array', items: { $ref: '#/$defs/Tree' } },
122 + },
123 + },
124 + },
125 + });
126 +
127 + expect((out as { type: string }).type).toBe('object');
128 + const children = (
129 + out as {
130 + properties: { children: { items: { type: string; additionalProperties: boolean } } };
131 + }
132 + ).properties.children;
133 + expect(children.items).toEqual({ type: 'object', additionalProperties: true });
134 + expect(containsRef(out)).toBe(false);
135 + });
136 +
137 + it('strips $defs and definitions from the returned root schema', () => {
138 + const out = dereferenceJsonSchema({
139 + type: 'object',
140 + properties: { x: { $ref: '#/$defs/Foo' } },
141 + $defs: { Foo: { type: 'integer' } },
142 + definitions: { Bar: { type: 'string' } },
143 + }) as Record<string, unknown>;
144 +
145 + expect(out.$defs).toBeUndefined();
146 + expect(out.definitions).toBeUndefined();
147 + });
148 +
149 + it('throws JsonSchemaRefResolutionError when target is missing', () => {
150 + expect(() =>
151 + dereferenceJsonSchema({
152 + type: 'object',
153 + properties: { v: { $ref: '#/$defs/Missing' } },
154 + $defs: {},
155 + })
156 + ).toThrow(JsonSchemaRefResolutionError);
157 + });
158 +
159 + it('throws JsonSchemaRefResolutionError when chain depth exceeds the cap', () => {
160 + const $defs: Record<string, unknown> = {};
161 + for (let i = 0; i < 200; i++) {
162 + $defs[`A${i}`] = { $ref: i + 1 < 200 ? `#/$defs/A${i + 1}` : '#/$defs/A0' };
163 + }
164 + expect(() =>
165 + dereferenceJsonSchema({
166 + type: 'object',
167 + properties: { v: { $ref: '#/$defs/A0' } },
168 + $defs,
169 + })
170 + ).toThrow(JsonSchemaRefResolutionError);
171 + });
172 +
173 + it('leaves external $ref pointers untouched', () => {
174 + const out = dereferenceJsonSchema({
175 + type: 'object',
176 + properties: { v: { $ref: 'https://example.com/Foo' } },
177 + });
178 +
179 + expect((out as { properties: { v: { $ref: string } } }).properties.v.$ref).toBe(
180 + 'https://example.com/Foo'
181 + );
182 + });
183 +
184 + it('does not mutate the input schema', () => {
185 + const input = {
186 + type: 'object',
187 + properties: { v: { $ref: '#/$defs/Foo' } },
188 + $defs: { Foo: { type: 'string' } },
189 + };
190 + const snapshot = structuredClone(input);
191 + dereferenceJsonSchema(input);
192 + expect(input).toEqual(snapshot);
193 + });
194 +
195 + it('decodes JSON Pointer escape sequences (~1 -> /, ~0 -> ~) in the correct order', () => {
196 + const out = dereferenceJsonSchema({
197 + type: 'object',
198 + properties: {
199 + a: { $ref: '#/$defs/with~1slash' },
200 + b: { $ref: '#/$defs/with~0tilde' },
201 + c: { $ref: '#/$defs/tilde-then-slash~01' },
202 + },
203 + $defs: {
204 + 'with/slash': { type: 'string' },
205 + 'with~tilde': { type: 'integer' },
206 + 'tilde-then-slash~1': { type: 'boolean' },
207 + },
208 + } as unknown as Record<string, unknown>);
209 +
210 + const props = (out as { properties: Record<string, { type: string }> }).properties;
211 + expect(props.a.type).toBe('string');
212 + expect(props.b.type).toBe('integer');
213 + expect(props.c.type).toBe('boolean');
214 + });
215 +
216 + it('resolves array-index pointers (#/$defs/foo/oneOf/0)', () => {
217 + const out = dereferenceJsonSchema({
218 + type: 'object',
219 + properties: { v: { $ref: '#/$defs/foo/oneOf/0' } },
220 + $defs: {
221 + foo: { oneOf: [{ type: 'string' }, { type: 'number' }] },
222 + },
223 + } as unknown as Record<string, unknown>);
224 +
225 + expect((out as { properties: { v: { type: string } } }).properties.v.type).toBe('string');
226 + });
227 +});
ts/packages/providers/mastra/test/mastra-ref.test.ts new
+135
@@ -0,0 +1,135 @@
1 +/**
2 + * Integration test for the Mastra provider against the **real**
3 + * `@mastra/schema-compat` package (no `vi.mock` for it). This is the regression
4 + * test for [PLEN-2244]: a Composio tool whose `inputParameters` carry a `$ref`
5 + * (legal under both Draft 7 and 2020-12).
6 + *
7 + * Without dereferencing, `applyCompatLayer` silently *degrades* the `$ref`-typed
8 + * property to a permissive `anyOf` of all primitives — losing the type
9 + * information from `$defs`. This test asserts the post-wrap `inputSchema`
10 + * preserves the structure described by `$defs`, which is only possible if
11 + * `$ref` is resolved before the conversion.
12 + *
13 + * Vitest mock scoping is per-file by default, so the top-level `vi.mock` for
14 + * `@mastra/schema-compat` in `mastra.test.ts` does **not** leak into this file.
15 + */
16 +
17 +import { describe, it, expect, vi } from 'vitest';
18 +import type { Tool } from '@composio/core';
19 +import { MastraProvider } from '../src';
20 +
21 +const containsRef = (value: unknown): boolean => {
22 + if (value === null || typeof value !== 'object') return false;
23 + if (Array.isArray(value)) return value.some(containsRef);
24 + if ('$ref' in (value as Record<string, unknown>)) return true;
25 + return Object.values(value as Record<string, unknown>).some(containsRef);
26 +};
27 +
28 +const findProperty = (schema: unknown, key: string): Record<string, unknown> | undefined => {
29 + if (schema === null || typeof schema !== 'object') return undefined;
30 + const node = schema as Record<string, unknown>;
31 + if (node.properties && typeof node.properties === 'object') {
32 + const props = node.properties as Record<string, unknown>;
33 + if (key in props) return props[key] as Record<string, unknown>;
34 + for (const value of Object.values(props)) {
35 + const found = findProperty(value, key);
36 + if (found) return found;
37 + }
38 + }
39 + for (const value of Object.values(node)) {
40 + if (Array.isArray(value)) {
41 + for (const item of value) {
42 + const found = findProperty(item, key);
43 + if (found) return found;
44 + }
45 + } else if (typeof value === 'object' && value !== null) {
46 + const found = findProperty(value, key);
47 + if (found) return found;
48 + }
49 + }
50 + return undefined;
51 +};
52 +
53 +const refTool: Tool = {
54 + slug: 'PLEN_2244_TOOL',
55 + name: 'PLEN-2244 Tool',
56 + description: 'Tool whose schema carries internal $ref pointers',
57 + toolkit: { slug: 'plen2244', name: 'PLEN 2244' },
58 + version: '20260430_00',
59 + availableVersions: ['20260430_00'],
60 + tags: [],
61 + inputParameters: {
62 + type: 'object',
63 + properties: { user: { $ref: '#/$defs/User' } as never },
64 + required: ['user'],
65 + $defs: {
66 + User: {
67 + type: 'object',
68 + properties: { id: { type: 'string' } },
69 + required: ['id'],
70 + },
71 + },
72 + } as unknown as Tool['inputParameters'],
73 + outputParameters: {
74 + type: 'object',
75 + properties: { item: { $ref: '#/definitions/Item' } as never },
76 + definitions: {
77 + Item: {
78 + type: 'object',
79 + properties: { sku: { type: 'string' } },
80 + required: ['sku'],
81 + },
82 + },
83 + } as unknown as Tool['outputParameters'],
84 +};
85 +
86 +describe('MastraProvider regression: PLEN-2244 ($ref in JSON Schema)', () => {
87 + it('does not throw when wrapping a tool whose schema uses $ref / $defs', () => {
88 + const provider = new MastraProvider();
89 + const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
90 + provider._setExecuteToolFn(executeToolFn);
91 +
92 + expect(() => provider.wrapTool(refTool, executeToolFn)).not.toThrow();
93 + });
94 +
95 + it('preserves type information from $defs (does not degrade $ref to permissive anyOf)', () => {
96 + const provider = new MastraProvider();
97 + const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
98 + provider._setExecuteToolFn(executeToolFn);
99 +
100 + const wrapped = provider.wrapTool(refTool, executeToolFn) as { inputSchema: unknown };
101 +
102 + // Without the dereference step, `$ref` is silently dropped during
103 + // JSON-Schema → Zod → JSON-Schema round-trip and the `id` field disappears
104 + // entirely (the property gets degraded to a permissive `anyOf`).
105 + const idProp = findProperty(wrapped.inputSchema, 'id');
106 + expect(idProp).toBeDefined();
107 + expect(idProp?.type).toBe('string');
108 + });
109 +
110 + it('preserves type information from `definitions` on outputParameters (Draft 7)', () => {
111 + const provider = new MastraProvider();
112 + const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
113 + provider._setExecuteToolFn(executeToolFn);
114 +
115 + const wrapped = provider.wrapTool(refTool, executeToolFn) as { outputSchema: unknown };
116 +
117 + const skuProp = findProperty(wrapped.outputSchema, 'sku');
118 + expect(skuProp).toBeDefined();
119 + expect(skuProp?.type).toBe('string');
120 + });
121 +
122 + it('does not leave any $ref in the produced schemas', () => {
123 + const provider = new MastraProvider();
124 + const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
125 + provider._setExecuteToolFn(executeToolFn);
126 +
127 + const wrapped = provider.wrapTool(refTool, executeToolFn) as {
128 + inputSchema: unknown;
129 + outputSchema: unknown;
130 + };
131 +
132 + expect(containsRef(wrapped.inputSchema)).toBe(false);
133 + expect(containsRef(wrapped.outputSchema)).toBe(false);
134 + });
135 +});