@devries-cameron20 / composio Mirror · read-only / commits / cc673b654
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, 22:15 UTC

fix(mastra): resolve $ref in tool schemas before applyCompatLayer [PLEN-2244]

Composio tools whose JSON Schema uses internal `$ref` pointers (`#/$defs/...` or the legacy `#/definitions/...`) used to lose all type information when wrapped by `MastraProvider.wrapTool`. The schema went through: raw JSON Schema (with $ref) → applyCompatLayer → convertSchemaToZod (silently drops $ref, becomes a permissive anyOf) → zodToJsonSchema (no way to recover the lost types) Customers reported this surface as "schema validation error: can't resolve reference" — AJV (bundled inside @mastra/schema-compat) refusing to compile the schema downstream when validating tool input. Fix: pre-process the schema with a new `dereferenceJsonSchema` helper before handing it to `applyCompatLayer`. The helper: - walks the schema reflectively (no JSON-Schema-keyword allow-list, so future applicators are covered automatically), - inlines internal `$ref` pointers transitively, with a 100-hop depth cap, - shallow-merges sibling keywords next to `$ref` per Draft 2020-12 semantics (siblings win on collision — preserves caller's `description`/`default`), - breaks cycles with `{ type: 'object', additionalProperties: true }`, matching upstream guidance in mastra-ai/mastra#15341, - strips `$defs`/`definitions` from the returned root once everything reachable is inlined, - leaves external (`http://`/`https://`) `$ref` pointers untouched, - throws `JsonSchemaRefResolutionError` on malformed pointers, missing targets, or chains over the cap. Bumps the `@mastra/schema-compat` dependency floor to `^1.2.9` so users also pick up upstream PR #15400's recursive-`$ref` handling. The new red regression tests (committed in 5300bf8ba) now pass.

jkomyno committed Apr 30, 2026 at 01:33 UTC cc673b654cd2d24877e5b759ad008bc86c068702
6 files changed +211 -7
.changeset/fix-mastra-ref-dereference.md new
+12
@@ -0,0 +1,12 @@
1 +---
2 +'@composio/core': patch
3 +'@composio/mastra': patch
4 +---
5 +
6 +Resolve internal JSON Schema `$ref` pointers (`#/$defs/...` and `#/definitions/...`) before handing tool parameters to `@mastra/schema-compat`. Composio tools whose schemas use `$defs`/`definitions` — legal under Draft 7 and 2020-12 — no longer trigger the AJV `can't resolve reference …` error, and the resolved type information from `$defs` survives the JSON-Schema → Zod → JSON-Schema round-trip instead of being silently degraded to a permissive `anyOf`.
7 +
8 +- New `dereferenceJsonSchema` helper exported from `@composio/core` performs the inline expansion. It deep-clones the input, walks every applicator reflectively (so future JSON Schema keywords are covered), shallow-merges sibling keywords next to `$ref` per Draft 2020-12 semantics, breaks cycles with `{ type: 'object', additionalProperties: true }` (matching the upstream guidance in [mastra-ai/mastra#15341](https://github.com/mastra-ai/mastra/issues/15341)), and strips `$defs`/`definitions` once everything reachable is inlined. External (`http://`/`https://`) `$ref` pointers are left untouched.
9 +- `@composio/mastra` calls the helper inside `wrapTool` for both `inputParameters` and `outputParameters`.
10 +- `@mastra/schema-compat` dependency floor raised to `^1.2.9` so users automatically receive [PR #15400](https://github.com/mastra-ai/mastra/pull/15400)'s recursive-`$ref` handling.
11 +
12 +Closes [PLEN-2244](https://linear.app/composio/issue/PLEN-2244/mastra-provider-schema-validation-error-cant-resolve-reference).
pnpm-lock.yaml
+16 -2
@@ -1397,8 +1397,8 @@ importers:
1397 ts/packages/providers/mastra:
1398 dependencies:
1399 '@mastra/schema-compat':
1400 - specifier: ^1.0.0
1401 - version: 1.1.0(zod@4.3.6)
1400 + specifier: ^1.2.9
1401 + version: 1.2.9(zod@4.3.6)
1402 devDependencies:
1403 '@composio/core':
1404 specifier: workspace:*
@@ -3004,6 +3004,12 @@ packages:
3004 peerDependencies:
3005 zod: ^3.25.0 || ^4.0.0
3006
3007 + '@mastra/schema-compat@1.2.9':
3008 + resolution: {integrity: sha512-1/RgazXqi1Wdyx8aR81CVS+sRyzlTGUL1YhhHkSULoEY8aXs58bvWkH/6iixlYsY0xGvn+0OPLCeSRkBCtDx4Q==}
3009 + engines: {node: '>=22.13.0'}
3010 + peerDependencies:
3011 + zod: ^3.25.0 || ^4.0.0
3012 +
3013 '@modelcontextprotocol/sdk@1.26.0':
3014 resolution: {integrity: sha512-Y5RmPncpiDtTXDbLKswIJzTqu2hyBKxTNsgKqKclDbhIgg1wgtf1fRuvxgTnRfcnxtvvgbIEcqUOzZrJ6iSReg==}
3015 engines: {node: '>=18'}
@@ -8246,6 +8252,14 @@ snapshots:
8252 zod-from-json-schema-v3: zod-from-json-schema@0.0.5
8253 zod-to-json-schema: 3.25.1(zod@4.3.6)
8254
8255 + '@mastra/schema-compat@1.2.9(zod@4.3.6)':
8256 + dependencies:
8257 + json-schema-to-zod: 2.7.0
8258 + zod: 4.3.6
8259 + zod-from-json-schema: 0.5.2
8260 + zod-from-json-schema-v3: zod-from-json-schema@0.0.5
8261 + zod-to-json-schema: 3.25.2(zod@4.3.6)
8262 +
8263 '@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@3.25.76)':
8264 dependencies:
8265 '@hono/node-server': 1.19.9(hono@4.11.9)
ts/packages/core/src/index.ts
+5 -1
@@ -4,7 +4,11 @@ export { OpenAIProvider } from './provider/OpenAIProvider';
4 export { ComposioProvider } from './provider/ComposioProvider';
5 export { BaseNonAgenticProvider, BaseAgenticProvider } from './provider/BaseProvider';
6 export type { BaseComposioProvider } from './provider/BaseProvider';
7 -export { jsonSchemaToZodSchema, removeNonRequiredProperties } from './utils/jsonSchema';
7 +export {
8 + dereferenceJsonSchema,
9 + jsonSchemaToZodSchema,
10 + removeNonRequiredProperties,
11 +} from './utils/jsonSchema';
12 export { getExtensionFromMimeType } from './utils/mime';
13 export { AuthScheme } from './models/AuthScheme';
14 export { MCP } from './models/MCP';
ts/packages/core/src/utils/jsonSchema.ts
+168 -1
@@ -1,7 +1,174 @@
1 import { z } from 'zod/v3';
2 -import { JsonSchemaToZodError } from '../errors';
2 +import { JsonSchemaRefResolutionError, JsonSchemaToZodError } from '../errors';
3 import { jsonSchemaToZod } from '@composio/json-schema-to-zod';
4
5 +const MAX_REF_CHAIN_DEPTH = 100;
6 +const CYCLE_BREAK_SENTINEL = Object.freeze({ type: 'object', additionalProperties: true });
7 +const INTERNAL_REF_PREFIX = '#';
8 +
9 +const decodePointerSegment = (segment: string): string =>
10 + segment.replace(/~1/g, '/').replace(/~0/g, '~');
11 +
12 +const resolvePointer = (
13 + root: Record<string, unknown>,
14 + pointer: string
15 +): { target: unknown; canonical: string } => {
16 + if (pointer === '#' || pointer === '') {
17 + return { target: root, canonical: '#' };
18 + }
19 + if (!pointer.startsWith('#/')) {
20 + throw new JsonSchemaRefResolutionError(`Unsupported $ref pointer: ${pointer}`, {
21 + meta: { ref: pointer },
22 + });
23 + }
24 + const segments = pointer.slice(2).split('/').map(decodePointerSegment);
25 + let cursor: unknown = root;
26 + for (const segment of segments) {
27 + if (cursor === null || typeof cursor !== 'object') {
28 + throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
29 + meta: { ref: pointer, failedAt: segment },
30 + });
31 + }
32 + if (Array.isArray(cursor)) {
33 + const index = Number(segment);
34 + if (!Number.isInteger(index) || index < 0 || index >= cursor.length) {
35 + throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
36 + meta: { ref: pointer, failedAt: segment },
37 + });
38 + }
39 + cursor = cursor[index];
40 + } else {
41 + const obj = cursor as Record<string, unknown>;
42 + if (!Object.prototype.hasOwnProperty.call(obj, segment)) {
43 + throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
44 + meta: { ref: pointer, failedAt: segment },
45 + });
46 + }
47 + cursor = obj[segment];
48 + }
49 + }
50 + return { target: cursor, canonical: pointer };
51 +};
52 +
53 +const isPlainObject = (value: unknown): value is Record<string, unknown> =>
54 + value !== null && typeof value === 'object' && !Array.isArray(value);
55 +
56 +/**
57 + * Inlines internal JSON Schema `$ref` pointers (`#/$defs/...` and the
58 + * legacy `#/definitions/...`) so the returned schema can be safely handed
59 + * to consumers — like AJV in `@mastra/schema-compat` — that don't tolerate
60 + * unresolved references.
61 + *
62 + * The traversal is reflective (no allow-list of JSON Schema keywords), so
63 + * future applicators (`unevaluatedProperties`, `dependentSchemas`, …) are
64 + * covered automatically. Sibling keywords next to `$ref` are shallow-merged
65 + * per Draft 2020-12 semantics — the sibling wins on collision so a caller's
66 + * `description` or `default` overrides the target's. Recursive `$ref`
67 + * chains are broken with `{ type: 'object', additionalProperties: true }`,
68 + * matching the upstream Mastra recommendation in
69 + * {@link https://github.com/mastra-ai/mastra/issues/15341 mastra-ai/mastra#15341}.
70 + *
71 + * The input schema is not mutated: every node is deep-cloned. `$defs` and
72 + * `definitions` are stripped from the returned root once everything
73 + * reachable is inlined — AJV strict-mode otherwise complains about unused
74 + * definitions.
75 + *
76 + * External `$ref` pointers (`http://`, `https://`, `file://`, …) are left
77 + * untouched: the caller may forward them to a consumer that resolves them
78 + * natively.
79 + *
80 + * @param schema - The JSON Schema to dereference. May be any plain object.
81 + * @returns A new schema with internal `$ref` pointers inlined.
82 + *
83 + * @throws {JsonSchemaRefResolutionError} When an internal pointer is
84 + * malformed, points at a missing target, or chains past the depth cap.
85 + *
86 + * @example
87 + * ```ts
88 + * dereferenceJsonSchema({
89 + * type: 'object',
90 + * properties: { user: { $ref: '#/$defs/User' } },
91 + * $defs: { User: { type: 'object', properties: { id: { type: 'string' } } } },
92 + * });
93 + * // {
94 + * // type: 'object',
95 + * // properties: {
96 + * // user: { type: 'object', properties: { id: { type: 'string' } } },
97 + * // },
98 + * // }
99 + * ```
100 + */
101 +export function dereferenceJsonSchema<T = unknown>(schema: T): T {
102 + if (!isPlainObject(schema)) return schema;
103 +
104 + const root = schema as Record<string, unknown>;
105 +
106 + const walk = (node: unknown, path: string[], depth: number): unknown => {
107 + if (Array.isArray(node)) {
108 + return node.map((item, index) => walk(item, [...path, String(index)], depth));
109 + }
110 + if (!isPlainObject(node)) return node;
111 +
112 + if (typeof node.$ref === 'string') {
113 + const ref = node.$ref;
114 + // External refs are out of scope; leave them alone.
115 + if (!ref.startsWith(INTERNAL_REF_PREFIX)) {
116 + const cloned: Record<string, unknown> = {};
117 + for (const [key, value] of Object.entries(node)) {
118 + cloned[key] = walk(value, [...path, key], depth);
119 + }
120 + return cloned;
121 + }
122 +
123 + if (depth >= MAX_REF_CHAIN_DEPTH) {
124 + throw new JsonSchemaRefResolutionError(
125 + `JSON Schema $ref chain exceeded depth cap (${MAX_REF_CHAIN_DEPTH}): ${ref}`,
126 + { meta: { ref } }
127 + );
128 + }
129 +
130 + // Cycle detection: if `ref` already appears in the current path, this
131 + // resolution would re-enter itself. Break the cycle.
132 + if (path.includes(`@ref:${ref}`)) {
133 + return { ...CYCLE_BREAK_SENTINEL };
134 + }
135 +
136 + const { target } = resolvePointer(root, ref);
137 + const resolved = walk(target, [...path, `@ref:${ref}`], depth + 1);
138 +
139 + // Shallow-merge sibling keywords (Draft 2020-12 semantics: siblings win
140 + // on collision). Draft 7 ignores siblings entirely, but the Composio
141 + // tool surface admits both drafts so we honor siblings for safety.
142 + const { $ref: _omit, ...siblings } = node;
143 + void _omit;
144 + if (Object.keys(siblings).length === 0) {
145 + return resolved;
146 + }
147 + if (!isPlainObject(resolved)) {
148 + return resolved;
149 + }
150 + const merged: Record<string, unknown> = { ...resolved };
151 + for (const [key, value] of Object.entries(siblings)) {
152 + merged[key] = walk(value, [...path, key], depth);
153 + }
154 + return merged;
155 + }
156 +
157 + const cloned: Record<string, unknown> = {};
158 + for (const [key, value] of Object.entries(node)) {
159 + cloned[key] = walk(value, [...path, key], depth);
160 + }
161 + return cloned;
162 + };
163 +
164 + const out = walk(root, [], 0);
165 + if (isPlainObject(out)) {
166 + delete out.$defs;
167 + delete out.definitions;
168 + }
169 + return out as T;
170 +}
171 +
172 /**
173 * Removes all non-required properties from the schema
174 *
ts/packages/providers/mastra/package.json
+1 -1
@@ -57,6 +57,6 @@
57 "zod": "catalog:"
58 },
59 "dependencies": {
60 - "@mastra/schema-compat": "^1.0.0"
60 + "@mastra/schema-compat": "^1.2.9"
61 }
62 }
ts/packages/providers/mastra/src/index.ts
+9 -2
@@ -11,6 +11,7 @@ import {
11 Tool,
12 ExecuteToolFn,
13 McpUrlResponse,
14 + dereferenceJsonSchema,
15 removeNonRequiredProperties,
16 } from '@composio/core';
17 import { applyCompatLayer } from '@mastra/schema-compat';
@@ -90,14 +91,20 @@ export class MastraProvider extends BaseAgenticProvider<
91 )
92 : inputParams;
93
94 + // Inline internal $ref pointers before handing the schema to
95 + // @mastra/schema-compat. AJV (bundled inside schema-compat) refuses to
96 + // compile a schema with unresolved $ref, and the upstream JSON-Schema →
97 + // Zod converter silently degrades $ref-typed properties to a permissive
98 + // anyOf — losing the type info from $defs. See [PLEN-2244] and
99 + // mastra-ai/mastra#15341.
100 const inputSchema = applyCompatLayer({
94 - schema: parameters ?? {},
101 + schema: dereferenceJsonSchema(parameters ?? {}),
102 compatLayers: [],
103 mode: 'jsonSchema',
104 });
105
106 const outputSchema = applyCompatLayer({
100 - schema: tool.outputParameters ?? {},
107 + schema: dereferenceJsonSchema(tool.outputParameters ?? {}),
108 compatLayers: [],
109 mode: 'jsonSchema',
110 });