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(mastra): resolve $ref in tool schemas before applyCompatLayer [PLEN-2244]
jkomynocc673b654cd2
diff --git a/.changeset/fix-mastra-ref-dereference.md b/.changeset/fix-mastra-ref-dereference.mdnew file mode 100644index 000000000..f3ab8ce4d--- /dev/null+++ b/.changeset/fix-mastra-ref-dereference.md@@ -0,0 +1,12 @@+---+'@composio/core': patch+'@composio/mastra': patch+---++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`.++- 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.+- `@composio/mastra` calls the helper inside `wrapTool` for both `inputParameters` and `outputParameters`.+- `@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.++Closes [PLEN-2244](https://linear.app/composio/issue/PLEN-2244/mastra-provider-schema-validation-error-cant-resolve-reference).diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 491570cb7..4207e2253 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -1397,8 +1397,8 @@ importers:ts/packages/providers/mastra:dependencies:'@mastra/schema-compat':- specifier: ^1.0.0- version: 1.1.0([email protected])+ specifier: ^1.2.9+ version: 1.2.9([email protected])devDependencies:'@composio/core':specifier: workspace:*@@ -3004,6 +3004,12 @@ packages:peerDependencies:zod: ^3.25.0 || ^4.0.0+ '@mastra/[email protected]':+ resolution: {integrity: sha512-1/RgazXqi1Wdyx8aR81CVS+sRyzlTGUL1YhhHkSULoEY8aXs58bvWkH/6iixlYsY0xGvn+0OPLCeSRkBCtDx4Q==}+ engines: {node: '>=22.13.0'}+ peerDependencies:+ zod: ^3.25.0 || ^4.0.0+'@modelcontextprotocol/[email protected]':resolution: {integrity: sha512-Y5RmPncpiDtTXDbLKswIJzTqu2hyBKxTNsgKqKclDbhIgg1wgtf1fRuvxgTnRfcnxtvvgbIEcqUOzZrJ6iSReg==}engines: {node: '>=18'}@@ -8246,6 +8252,14 @@ snapshots:zod-from-json-schema-v3: [email protected]zod-to-json-schema: 3.25.1([email protected])+ '@mastra/[email protected]([email protected])':+ dependencies:+ json-schema-to-zod: 2.7.0+ zod: 4.3.6+ zod-from-json-schema: 0.5.2+ zod-from-json-schema-v3: [email protected]+ zod-to-json-schema: 3.25.2([email protected])+dependencies:'@hono/node-server': 1.19.9([email protected])diff --git a/ts/packages/core/src/index.ts b/ts/packages/core/src/index.tsindex 02fcef40c..cdb8a9db2 100644--- a/ts/packages/core/src/index.ts+++ b/ts/packages/core/src/index.ts@@ -4,7 +4,11 @@ export { OpenAIProvider } from './provider/OpenAIProvider';export { ComposioProvider } from './provider/ComposioProvider';export { BaseNonAgenticProvider, BaseAgenticProvider } from './provider/BaseProvider';export type { BaseComposioProvider } from './provider/BaseProvider';-export { jsonSchemaToZodSchema, removeNonRequiredProperties } from './utils/jsonSchema';+export {+ dereferenceJsonSchema,+ jsonSchemaToZodSchema,+ removeNonRequiredProperties,+} from './utils/jsonSchema';export { getExtensionFromMimeType } from './utils/mime';export { AuthScheme } from './models/AuthScheme';export { MCP } from './models/MCP';diff --git a/ts/packages/core/src/utils/jsonSchema.ts b/ts/packages/core/src/utils/jsonSchema.tsindex 807be25f2..5747fa1dd 100644--- a/ts/packages/core/src/utils/jsonSchema.ts+++ b/ts/packages/core/src/utils/jsonSchema.ts@@ -1,7 +1,174 @@import { z } from 'zod/v3';-import { JsonSchemaToZodError } from '../errors';+import { JsonSchemaRefResolutionError, JsonSchemaToZodError } from '../errors';import { jsonSchemaToZod } from '@composio/json-schema-to-zod';+const MAX_REF_CHAIN_DEPTH = 100;+const CYCLE_BREAK_SENTINEL = Object.freeze({ type: 'object', additionalProperties: true });+const INTERNAL_REF_PREFIX = '#';++const decodePointerSegment = (segment: string): string =>+ segment.replace(/~1/g, '/').replace(/~0/g, '~');++const resolvePointer = (+ root: Record<string, unknown>,+ pointer: string+): { target: unknown; canonical: string } => {+ if (pointer === '#' || pointer === '') {+ return { target: root, canonical: '#' };+ }+ if (!pointer.startsWith('#/')) {+ throw new JsonSchemaRefResolutionError(`Unsupported $ref pointer: ${pointer}`, {+ meta: { ref: pointer },+ });+ }+ const segments = pointer.slice(2).split('/').map(decodePointerSegment);+ let cursor: unknown = root;+ for (const segment of segments) {+ if (cursor === null || typeof cursor !== 'object') {+ throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {+ meta: { ref: pointer, failedAt: segment },+ });+ }+ if (Array.isArray(cursor)) {+ const index = Number(segment);+ if (!Number.isInteger(index) || index < 0 || index >= cursor.length) {+ throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {+ meta: { ref: pointer, failedAt: segment },+ });+ }+ cursor = cursor[index];+ } else {+ const obj = cursor as Record<string, unknown>;+ if (!Object.prototype.hasOwnProperty.call(obj, segment)) {+ throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {+ meta: { ref: pointer, failedAt: segment },+ });+ }+ cursor = obj[segment];+ }+ }+ return { target: cursor, canonical: pointer };+};++const isPlainObject = (value: unknown): value is Record<string, unknown> =>+ value !== null && typeof value === 'object' && !Array.isArray(value);++/**+ * Inlines internal JSON Schema `$ref` pointers (`#/$defs/...` and the+ * legacy `#/definitions/...`) so the returned schema can be safely handed+ * to consumers — like AJV in `@mastra/schema-compat` — that don't tolerate+ * unresolved references.+ *+ * The traversal is reflective (no allow-list of JSON Schema keywords), so+ * future applicators (`unevaluatedProperties`, `dependentSchemas`, …) are+ * covered automatically. Sibling keywords next to `$ref` are shallow-merged+ * per Draft 2020-12 semantics — the sibling wins on collision so a caller's+ * `description` or `default` overrides the target's. Recursive `$ref`+ * chains are broken with `{ type: 'object', additionalProperties: true }`,+ * matching the upstream Mastra recommendation in+ * {@link https://github.com/mastra-ai/mastra/issues/15341 mastra-ai/mastra#15341}.+ *+ * The input schema is not mutated: every node is deep-cloned. `$defs` and+ * `definitions` are stripped from the returned root once everything+ * reachable is inlined — AJV strict-mode otherwise complains about unused+ * definitions.+ *+ * External `$ref` pointers (`http://`, `https://`, `file://`, …) are left+ * untouched: the caller may forward them to a consumer that resolves them+ * natively.+ *+ * @param schema - The JSON Schema to dereference. May be any plain object.+ * @returns A new schema with internal `$ref` pointers inlined.+ *+ * @throws {JsonSchemaRefResolutionError} When an internal pointer is+ * malformed, points at a missing target, or chains past the depth cap.+ *+ * @example+ * ```ts+ * dereferenceJsonSchema({+ * type: 'object',+ * properties: { user: { $ref: '#/$defs/User' } },+ * $defs: { User: { type: 'object', properties: { id: { type: 'string' } } } },+ * });+ * // {+ * // type: 'object',+ * // properties: {+ * // user: { type: 'object', properties: { id: { type: 'string' } } },+ * // },+ * // }+ * ```+ */+export function dereferenceJsonSchema<T = unknown>(schema: T): T {+ if (!isPlainObject(schema)) return schema;++ const root = schema as Record<string, unknown>;++ const walk = (node: unknown, path: string[], depth: number): unknown => {+ if (Array.isArray(node)) {+ return node.map((item, index) => walk(item, [...path, String(index)], depth));+ }+ if (!isPlainObject(node)) return node;++ if (typeof node.$ref === 'string') {+ const ref = node.$ref;+ // External refs are out of scope; leave them alone.+ if (!ref.startsWith(INTERNAL_REF_PREFIX)) {+ const cloned: Record<string, unknown> = {};+ for (const [key, value] of Object.entries(node)) {+ cloned[key] = walk(value, [...path, key], depth);+ }+ return cloned;+ }++ if (depth >= MAX_REF_CHAIN_DEPTH) {+ throw new JsonSchemaRefResolutionError(+ `JSON Schema $ref chain exceeded depth cap (${MAX_REF_CHAIN_DEPTH}): ${ref}`,+ { meta: { ref } }+ );+ }++ // Cycle detection: if `ref` already appears in the current path, this+ // resolution would re-enter itself. Break the cycle.+ if (path.includes(`@ref:${ref}`)) {+ return { ...CYCLE_BREAK_SENTINEL };+ }++ const { target } = resolvePointer(root, ref);+ const resolved = walk(target, [...path, `@ref:${ref}`], depth + 1);++ // Shallow-merge sibling keywords (Draft 2020-12 semantics: siblings win+ // on collision). Draft 7 ignores siblings entirely, but the Composio+ // tool surface admits both drafts so we honor siblings for safety.+ const { $ref: _omit, ...siblings } = node;+ void _omit;+ if (Object.keys(siblings).length === 0) {+ return resolved;+ }+ if (!isPlainObject(resolved)) {+ return resolved;+ }+ const merged: Record<string, unknown> = { ...resolved };+ for (const [key, value] of Object.entries(siblings)) {+ merged[key] = walk(value, [...path, key], depth);+ }+ return merged;+ }++ const cloned: Record<string, unknown> = {};+ for (const [key, value] of Object.entries(node)) {+ cloned[key] = walk(value, [...path, key], depth);+ }+ return cloned;+ };++ const out = walk(root, [], 0);+ if (isPlainObject(out)) {+ delete out.$defs;+ delete out.definitions;+ }+ return out as T;+}+/*** Removes all non-required properties from the schema*diff --git a/ts/packages/providers/mastra/package.json b/ts/packages/providers/mastra/package.jsonindex ed66e7fb6..acd45d9a4 100644--- a/ts/packages/providers/mastra/package.json+++ b/ts/packages/providers/mastra/package.json@@ -57,6 +57,6 @@"zod": "catalog:"},"dependencies": {- "@mastra/schema-compat": "^1.0.0"+ "@mastra/schema-compat": "^1.2.9"}}diff --git a/ts/packages/providers/mastra/src/index.ts b/ts/packages/providers/mastra/src/index.tsindex dccae6054..b3cc3d192 100644--- a/ts/packages/providers/mastra/src/index.ts+++ b/ts/packages/providers/mastra/src/index.ts@@ -11,6 +11,7 @@ import {Tool,ExecuteToolFn,McpUrlResponse,+ dereferenceJsonSchema,removeNonRequiredProperties,} from '@composio/core';import { applyCompatLayer } from '@mastra/schema-compat';@@ -90,14 +91,20 @@ export class MastraProvider extends BaseAgenticProvider<): inputParams;+ // Inline internal $ref pointers before handing the schema to+ // @mastra/schema-compat. AJV (bundled inside schema-compat) refuses to+ // compile a schema with unresolved $ref, and the upstream JSON-Schema →+ // Zod converter silently degrades $ref-typed properties to a permissive+ // anyOf — losing the type info from $defs. See [PLEN-2244] and+ // mastra-ai/mastra#15341.const inputSchema = applyCompatLayer({- schema: parameters ?? {},+ schema: dereferenceJsonSchema(parameters ?? {}),compatLayers: [],mode: 'jsonSchema',});const outputSchema = applyCompatLayer({- schema: tool.outputParameters ?? {},+ schema: dereferenceJsonSchema(tool.outputParameters ?? {}),compatLayers: [],mode: 'jsonSchema',});