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

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

## Summary 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 would silently round-trip `raw → applyCompatLayer → convertSchemaToZod (drops $ref → permissive anyOf) → zodToJsonSchema (no recovery)`. Customers reported the user-visible 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. This PR pre-processes the schema with a new `dereferenceJsonSchema` utility from `@composio/core` *before* it reaches `@mastra/schema-compat`, preserving the type information from `$defs`/`definitions` and avoiding the AJV failure entirely. Closes [PLEN-2244](https://linear.app/composio/issue/PLEN-2244/mastra-provider-schema-validation-error-cant-resolve-reference). ## What changed - **`@composio/core`** — new `dereferenceJsonSchema(schema)` helper (and `JsonSchemaRefResolutionError`): - 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` / `title`), - breaks recursive cycles with `{ type: 'object', additionalProperties: true }` (matches upstream guidance in [mastra-ai/mastra#15341](https://github.com/mastra-ai/mastra/issues/15341)), - strips `$defs` / `definitions` from the returned root once everything reachable is inlined, - leaves external (`http://`/`https://`) `$ref` pointers untouched so callers can still forward them, - throws `JsonSchemaRefResolutionError` on malformed pointers, missing targets, and over-cap chains. - **`@composio/mastra`** — `wrapTool` now runs `dereferenceJsonSchema` over both `inputParameters` and `outputParameters` before calling `applyCompatLayer`. - **`@mastra/schema-compat`** floor bumped to `^1.2.9` so consumers automatically pick up upstream [PR #15400](https://github.com/mastra-ai/mastra/pull/15400)'s recursive-`$ref` handling and [PR #14530](https://github.com/mastra-ai/mastra/pull/14530)'s Draft-2020-12 AJV switch. - Changeset: `.changeset/fix-mastra-ref-dereference.md` (patch bump for `@composio/core` and `@composio/mastra`). ## Test plan Red → green TDD across two commits — the `test:` commit reproduces PLEN-2244 against the real `@mastra/schema-compat` (no `vi.mock`), the `fix:` commit makes the regression tests pass. - [x] `ts/packages/core/test/utils/jsonSchema.test.ts` — 14 unit tests for `dereferenceJsonSchema` covering: basic resolution, chained refs, container coverage (items / oneOf / anyOf / allOf / not / additionalProperties / patternProperties / prefixItems), legacy `definitions` (Draft 7), `$defs`/`definitions` mixed transitively, sibling-keyword merge per Draft 2020-12, cycle break, `$defs`/`definitions` strip, missing-target error, depth-cap error, external `$ref` preserved, no input mutation, JSON Pointer escape decoding (`~0`/`~1`), array-index pointers. - [x] `ts/packages/providers/mastra/test/mastra-ref.test.ts` — un-mocked integration tests against real `@mastra/schema-compat`: wrapping does not throw, type info from `$defs` survives the round-trip (the `id` field stays `type: 'string'` instead of degrading to permissive `anyOf`), same for Draft-7 `definitions` on output schema, no remaining `$ref` in the produced schemas. - [x] `pnpm --filter @composio/core test` — 852/852 green. - [x] `pnpm --filter @composio/mastra test` — 43/43 green (39 legacy + 4 new). - [x] `pnpm --filter @composio/core --filter @composio/mastra typecheck` — clean. - [x] Existing `mastra.test.ts` (which mocks `@mastra/schema-compat`) is **untouched** and still green. - [x] Secret-hygiene scan: `git diff next..HEAD | grep -E 'sk-[A-Za-z0-9_-]{20,}|OPENAI_API_KEY=[A-Za-z]'` returns empty. ## Why it's a Mastra-only fix The Mastra path is unique in routing JSON Schema through `@mastra/schema-compat`, which embeds AJV. Sibling providers (`openai`, `anthropic`, `vercel`, `langchain`, `google`, `llamaindex`) forward Composio's JSON Schema through `@composio/json-schema-to-zod`, which silently no-ops on unknown nodes. They are not affected today; expanding pre-processing across providers is a separate PR if it ever becomes needed. ## Caveats - The cycle-break sentinel weakens type information for genuinely recursive tool schemas. This is the same trade-off Mastra itself made in [#15341](https://github.com/mastra-ai/mastra/issues/15341); without it the agent crashes entirely. - External `$ref` (`http://`/`https://`) is intentionally left untouched. If a real customer schema ever needs them resolved, that's an incremental follow-up that calls into `@apidevtools/json-schema-ref-parser` only when needed. - The cycle-break currently uses a single sentinel for any cycle; if review prefers the higher-fidelity "keep first expansion, only break on the recursion edge" pattern (mentioned in the research as a refinement), that's a small follow-up.

Alberto Schiabel committed May 6, 2026 at 11:17 UTC f5c5b84bd3e5601e4ca10a57affbd37830d46ae5

No changes.