@devries-cameron20 / composio-1 / commits / b69cef123
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): tolerate dangling $ref in tool schemas [PLEN-2451] (#3400)

## Summary Closes [PLEN-2451](https://linear.app/composio/issue/PLEN-2451/mastraprovider-dollardefsdollarref-schema-is-dangling-at-the-api). Fixes https://github.com/ComposioHQ/composio/issues/3307. The Composio API ships some tools (e.g. `GMAIL_FETCH_EMAILS`) with `outputParameters` like: ```jsonc { "type": "object", "properties": { "data": { "$ref": "#/$defs/FetchEmailsResponse" }, // ← points into $defs "error": { "type": "string" }, "successful": { "type": "boolean" } }, "required": ["data", "successful"] // ← no `$defs` block anywhere } ``` Since [PLEN-2244](https://linear.app/composio/issue/PLEN-2244) introduced strict `dereferenceJsonSchema`, this caused `composio.tools.get(...)` to throw `JsonSchemaRefResolutionError: Cannot resolve $ref #/$defs/FetchEmailsResponse` upfront via `MastraProvider.wrapTool`, making every Gmail / Slack / Google Calendar tool unusable through the Mastra integration. ### Approach Two-tier fix that keeps the architectural boundary from PLEN-2244 (only the provider that owns the validation contract pre-processes the schema): 1. **`@composio/core`** — add an additive opt-in to `dereferenceJsonSchema`: ```ts dereferenceJsonSchema(schema, { onUnresolved: 'sentinel', // default 'throw' unchanged onReplace: (ref, reason) => { /* observe */ }, }) ``` In `'sentinel'` mode the unresolvable branch is replaced with the same `{ type: 'object', additionalProperties: true }` cycle-break sentinel the resolver already uses for `$ref` cycles. Safety caps (`MAX_REF_CHAIN_DEPTH`, `MAX_NODE_DEPTH`) keep throwing in both modes. Default behavior is byte-for-byte unchanged — first-party / custom-tool authors who typo a `$ref` still see a hard error. 2. **`@composio/mastra`** — opt `wrapTool` into sentinel mode for both `inputParameters` and `outputParameters` and emit one `logger.warn` per `(toolSlug, ref)` pair via a provider-scoped dedup `Set`. The warning names the tool / toolkit / pointer and links to https://github.com/ComposioHQ/composio/issues/3307. ### Why not centralize the dereferencing in `Tools.ts`? - Mastra is the only provider that wraps `outputParameters`. Vercel / OpenAI / Anthropic / Google bind tool input schemas to function-calling APIs that ignore output shapes. - Centralized dereferencing would silently mutate `tools.get()`'s public output shape for callers iterating raw schemas. - PLEN-2244 set the precedent — the provider that owns the validation contract pre-processes its own schemas. This PR mirrors that boundary. ### API-side follow-up The proper long-term fix is for the Composio API to emit a top-level `$defs` block alongside any `$ref` it produces. That belongs in a separate backend ticket — the SDK fix is intentionally independent so we don't block on a backend rollout. The SDK now degrades gracefully regardless of which API version it talks to. ## Test plan Red-green TDD — every new test was confirmed red against the pre-fix `dereferenceJsonSchema` / `MastraProvider`, then green after the fix. - [x] **Core** — 9 new cases in `ts/packages/core/test/utils/jsonSchema.test.ts` under `describe("with onUnresolved: 'sentinel' lenient mode")` covering: missing-target, missing-key, malformed-pointer (non-`#/` ref), mixed schema (resolvable + dangling siblings), `onReplace` reasons, safety-cap-still-throws (chain & node depth), explicit `'throw'` matches default, `onReplace` not called in strict mode. - [x] **Mastra** — new file `ts/packages/providers/mastra/test/mastra-dangling-defs.test.ts` (6 cases, un-mocked `@mastra/schema-compat`): replicates the exact `GMAIL_FETCH_EMAILS.outputParameters` shape; verifies no throw, no surviving `$ref` in the produced schema, exactly one warn per `(slug, ref)` pair across repeat wraps, a separate warn per slug, symmetric tolerance on `inputParameters`, and a regression guard for resolvable `$defs` (PLEN-2244 contract). - [x] **Regression** — all 908 core tests, all 39 existing `mastra.test.ts` cases, and all 3 `mastra-ref.test.ts` cases continue to pass. Full TS workspace test run: 14 packages green, 1322 tests total. - [x] `pnpm typecheck` passes in both `@composio/core` and `@composio/mastra`. - [x] `pnpm lint` on touched files produces no new warnings. - [ ] **Manual** (post-merge, against live API): `composio.tools.get(userId, { tools: ['GMAIL_FETCH_EMAILS'] })` returns a `MastraTool` whose `outputSchema` is defined; SDK logs exactly one warning per process per `(slug, ref)` pair. ## Files ``` ts/packages/core/src/index.ts # new type exports ts/packages/core/src/utils/jsonSchema.ts # opts + lenient branch ts/packages/core/test/utils/jsonSchema.test.ts # 9 new cases ts/packages/providers/mastra/src/index.ts # opt-in + dedup warn ts/packages/providers/mastra/test/mastra-dangling-defs.test.ts # 6 new cases .changeset/fix-mastra-dangling-defs-ref.md # core/mastra patch plans/fix-mastra-dangling-defs-ref.md # design + acceptance log ``` --------- Co-authored-by: jkomyno <12381818+jkomyno@users.noreply.github.com>

Alberto Schiabel committed Jun 5, 2026 at 10:53 UTC b69cef123f2dd30791905004a940778d809e7fd9
7 files changed +1099 -26
.changeset/fix-mastra-dangling-defs-ref.md new
+11
@@ -0,0 +1,11 @@
1 +---
2 +'@composio/core': patch
3 +'@composio/mastra': patch
4 +---
5 +
6 +Tolerate dangling `$ref` pointers in tool schemas the Composio API ships without a matching `$defs` entry. Some toolkits (e.g. `GMAIL_FETCH_EMAILS`) emit `outputParameters` with `"$ref": "#/$defs/FetchEmailsResponse"` while never declaring a top-level `$defs` block. After the strict resolver shipped with the previous Mastra fix, this caused `composio.tools.get(...)` to throw `JsonSchemaRefResolutionError` upfront, making every Gmail / Slack / Google-Calendar tool unusable through `MastraProvider`. The SDK now degrades the unresolvable branch to a permissive object schema and surfaces a single observability warning per `(toolSlug, ref)` pair instead of crashing.
7 +
8 +- `dereferenceJsonSchema` accepts a new optional second argument `{ onUnresolved?: 'throw' | 'sentinel'; onReplace?: (ref, reason) => void }`. Default behavior is unchanged (`'throw'`) — first-party / custom-tool schemas with a typo'd `$ref` still surface as a hard error. Pass `'sentinel'` to replace unresolved branches with the cycle-break sentinel (`{ type: 'object', additionalProperties: true }`) that the resolver already uses for `$ref` cycles. The replaced sentinel carries a default `description` hint so LLMs consuming the wrapped tool's schema get an in-band signal that the branch is opaque; a caller-provided `description` sibling overrides the default (Draft 2020-12 sibling-keyword merge). Safety caps (`MAX_REF_CHAIN_DEPTH`, `MAX_NODE_DEPTH`) keep throwing in both modes. New `UnresolvedRefStrategy`, `UnresolvedRefReason`, and `DereferenceJsonSchemaOptions` type exports.
9 +- `MastraProvider.wrapTool` opts both `inputParameters` and `outputParameters` into `'sentinel'` mode and emits one `logger.warn` per `(toolSlug, ref)` pair via the provider-scoped dedup `Set`. User-controlled segments in the warning (`tool.slug`, `toolkit.slug`, `ref`) are `JSON.stringify`d to neutralize embedded newlines / ANSI escapes / control bytes that could otherwise forge log lines (CWE-117). A matching one-shot telemetry event (`composio.mastra.wrapTool.danglingRef`) fires next to the warn so the Composio team has aggregate visibility into which toolkits are affected; the event respects `COMPOSIO_DISABLE_TELEMETRY=true`.
10 +- The `telemetry` instance from `@composio/core` is now publicly re-exported alongside `logger`, so providers can emit aggregate signals without reaching into the package's internals.
11 +- Resolvable `$defs` / `definitions` continue to be inlined exactly as before — no regression in the type-info preservation contract introduced by the previous Mastra fix.
plans/fix-mastra-dangling-defs-ref.md new
+435
@@ -0,0 +1,435 @@
1 +# fix: Tolerate dangling `$ref` in Mastra provider when API omits `$defs`
2 +
3 +## Overview
4 +
5 +`MastraProvider.wrapTool` calls `dereferenceJsonSchema` to inline JSON Schema `$ref`
6 +pointers before handing the schema to `@mastra/schema-compat`. That contract was
7 +introduced in PLEN-2244 (commit `cc673b654`) and assumes every `#/$defs/...` ref
8 +has a resolvable target. The Composio API ships at least one toolkit family
9 +(Gmail, and any other toolkit whose `outputParameters` uses `$ref`) where the
10 +schema declares `"$ref": "#/$defs/FetchEmailsResponse"` **without ever declaring
11 +`$defs`**. The current resolver correctly throws a typed
12 +`JsonSchemaRefResolutionError`, but that error escapes `wrapTool` and crashes
13 +`composio.tools.get(...)` upfront — making affected toolkits unusable through
14 +the Mastra provider.
15 +
16 +This plan makes `dereferenceJsonSchema` opt-in lenient against unresolved
17 +internal refs (using the existing cycle sentinel, `{ type: 'object', additionalProperties: true }`),
18 +opts the Mastra provider into that lenient mode with a one-shot per-tool warning,
19 +and locks the behavior in with red-green regression tests that mirror the exact
20 +`GMAIL_FETCH_EMAILS` shape from the Linear ticket.
21 +
22 +> **API-side follow-up (out of scope here):** the proper long-term fix is for
23 +> `/api/v3/tools/:slug` to emit a top-level `$defs` block alongside any `$ref`
24 +> it produces. That fix benefits every consumer (Mastra, Vercel AI SDK, future
25 +> providers). It is tracked separately so the SDK does not have to block on
26 +> the backend roll-out.
27 +
28 +## Problem Statement / Motivation
29 +
30 +### Reproduction (from PLEN-2451, verified 2026-05-10)
31 +
32 +Direct dump of `GMAIL_FETCH_EMAILS.outputParameters` via
33 +`composio.tools.getRawComposioTools(...)`:
34 +
35 +```jsonc
36 +{
37 + "type": "object",
38 + "properties": {
39 + "data": {
40 + "description": "Data from the action execution",
41 + "title": "Data",
42 + "$ref": "#/$defs/FetchEmailsResponse" // ← points into $defs
43 + },
44 + "error": { "type": "string", "description": "...", "title": "Error" },
45 + "successful": { "type": "boolean", "description": "...", "title": "Successful" }
46 + },
47 + "required": ["data", "successful"],
48 + "title": "FetchEmailsResponseWrapper"
49 + // ← no `$defs` block anywhere
50 +}
51 +```
52 +
53 +Observed behavior:
54 +
55 +| Version pair | Failure mode |
56 +| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
57 +| `@composio/{core,mastra}@0.6.11` | `tools.get` returns a degraded Standard Schema whose `output()` crashes at runtime; agent sees a ~600B validation-error stub. |
58 +| `@composio/{core,mastra}@0.9.0` (latest) | `tools.get` itself throws `JsonSchemaRefResolutionError: Cannot resolve $ref #/$defs/FetchEmailsResponse` upfront. |
59 +
60 +The 0.9.0 behavior is *correct* given the PLEN-2244 strict contract — but the
61 +contract is wrong for upstream-supplied schemas the SDK cannot edit. Every
62 +toolkit whose `outputParameters` carries a `$ref` (Gmail, Slack, Google
63 +Calendar, …) currently breaks Mastra integration.
64 +
65 +### Why the reporter's "Option A" fix does not work
66 +
67 +GitHub issue [#3307](https://github.com/ComposioHQ/composio/issues/3307)
68 +proposes inlining `$defs` before calling `applyCompatLayer`. That is exactly
69 +what PLEN-2244 already does (`ts/packages/providers/mastra/src/index.ts:100-110`).
70 +The root cause is **upstream of** `applyCompatLayer`: there is no `$defs` to
71 +inline. PLEN-2244's fix surfaces a dangling pointer instead of silently
72 +producing a permissive `anyOf`, which is the right developer experience for
73 +custom tools but the wrong one for opaque API-supplied schemas.
74 +
75 +## Proposed Solution
76 +
77 +Two-tier fix that keeps the same architecture as PLEN-2244:
78 +
79 +### 1. `@composio/core` — add an `onUnresolved` option to `dereferenceJsonSchema`
80 +
81 +`ts/packages/core/src/utils/jsonSchema.ts`
82 +
83 +```typescript
84 +export type UnresolvedRefStrategy = 'throw' | 'sentinel';
85 +
86 +export interface DereferenceJsonSchemaOptions {
87 + /**
88 + * What to do when a `#/$defs/...` or `#/definitions/...` $ref cannot be
89 + * resolved (target missing, $defs/definitions block absent, malformed
90 + * pointer beneath an internal #/ prefix).
91 + *
92 + * - `'throw'` (default): preserve current behavior — throw
93 + * `JsonSchemaRefResolutionError`. Right for first-party / custom-tool
94 + * schemas where a dangling ref is a developer bug.
95 + * - `'sentinel'`: replace the offending node with the cycle-break
96 + * sentinel (`{ type: 'object', additionalProperties: true }`). Right for
97 + * schemas sourced from an upstream service the caller cannot edit.
98 + * Each replacement invokes `onReplace` exactly once.
99 + */
100 + onUnresolved?: UnresolvedRefStrategy;
101 + /**
102 + * Callback invoked once per replaced node (only when `onUnresolved === 'sentinel'`).
103 + * Lets callers emit one-shot warnings without losing the offending pointer.
104 + */
105 + onReplace?: (ref: string, reason: 'missing-target' | 'malformed-pointer') => void;
106 +}
107 +
108 +export function dereferenceJsonSchema<T = unknown>(
109 + schema: T,
110 + options?: DereferenceJsonSchemaOptions
111 +): T { /* … */ }
112 +```
113 +
114 +Implementation notes:
115 +
116 +- The walker already produces `CYCLE_BREAK_SENTINEL` on detected cycles
117 + (`jsonSchema.ts:9, 98, 107, 127`). The lenient branch reuses **the same
118 + sentinel constant** so cycles and dangling refs share semantics: "we can't
119 + resolve this further; fall back to a permissive object".
120 +- `resolvePointer` currently throws via `failResolution`
121 + (`jsonSchema.ts:19-24, 26-36`). Refactor: have `failResolution` return a
122 + discriminator (`{ kind: 'unresolved', ref, reason }`) consumed by the walker,
123 + so the lenient and strict branches share a single code path. Strict mode
124 + throws at the boundary, lenient mode emits the sentinel + invokes
125 + `onReplace`. Net change to strict-mode behavior: zero.
126 +- The chain-depth cap (`MAX_REF_CHAIN_DEPTH`) and node-depth cap
127 + (`MAX_NODE_DEPTH`) keep throwing in **both** modes — those are safety caps,
128 + not data-shape issues. Document this in the JSDoc.
129 +- External (`http://`, `https://`, `file://`) refs continue to be left as-is
130 + with a single audit-log `logger.warn` per call (`jsonSchema.ts:113-118`).
131 + Unchanged.
132 +- `$defs` / `definitions` continue to be stripped from the returned root
133 + (`jsonSchema.ts:148-152`). Unchanged.
134 +
135 +### 2. `@composio/mastra` — opt into lenient mode with a per-tool warning
136 +
137 +`ts/packages/providers/mastra/src/index.ts`
138 +
139 +```typescript
140 +wrapTool(tool: Tool, executeTool: ExecuteToolFn): MastraTool {
141 + // ...existing strict-mode branch for inputParameters...
142 +
143 + // Output schemas come straight from the Composio API. The API can emit a
144 + // `$ref: "#/$defs/..."` without declaring `$defs` (PLEN-2451) — strict
145 + // mode would crash `tools.get` upfront. Fall back to the permissive
146 + // object sentinel and emit a single warning so the degraded shape is
147 + // observable in the agent's logs.
148 + const onReplace = (ref: string) => this.warnDanglingRefOnce(tool.slug, ref);
149 +
150 + const inputSchema = applyCompatLayer({
151 + schema: dereferenceJsonSchema(parameters ?? {}, {
152 + onUnresolved: 'sentinel',
153 + onReplace,
154 + }),
155 + compatLayers: [],
156 + mode: 'jsonSchema',
157 + });
158 +
159 + const outputSchema = applyCompatLayer({
160 + schema: dereferenceJsonSchema(tool.outputParameters ?? {}, {
161 + onUnresolved: 'sentinel',
162 + onReplace,
163 + }),
164 + compatLayers: [],
165 + mode: 'jsonSchema',
166 + });
167 +
168 + // ...createTool(...)...
169 +}
170 +```
171 +
172 +Add a small instance-scoped `Set<string>` (`warnedDanglingRefs`, keyed by
173 +`${slug}:${ref}`) so a Mastra agent that wraps the same tool many times only
174 +emits one warning per `(tool, ref)` pair. The warning message names the
175 +toolkit slug, tool slug, and the dangling pointer:
176 +
177 +```
178 +[composio/mastra] Tool GMAIL_FETCH_EMAILS (toolkit gmail) declares
179 +$ref #/$defs/FetchEmailsResponse but no matching $defs entry. Falling
180 +back to a permissive object schema for this branch — the wrapped
181 +Mastra tool will validate the response loosely. Tracked in
182 +https://linear.app/composio/issue/PLEN-2451.
183 +```
184 +
185 +Why warn (not silent fallback)?
186 +
187 +- **Why:** customers iterating on a Mastra agent need to know they got a
188 + degraded schema; otherwise the failure mode becomes "agent validates loosely
189 + and you never find out why a downstream typed consumer broke". The warning
190 + also gives us a signal we can pipe into telemetry to prioritize the
191 + API-side fix.
192 +- **How to apply:** rate-limit per `(slug, ref)` so noisy agents don't spam
193 + the log; never emit at module-load (the warning has to point at a concrete
194 + tool slug).
195 +
196 +### Why the fix stays inside `MastraProvider.wrapTool`
197 +
198 +It is tempting to dereference centrally — in
199 +`Tools.transformToolCases` (`Tools.ts:140`) or
200 +`Tools.applyDefaultSchemaModifiers` (`Tools.ts:192`). That would be wrong for
201 +three reasons:
202 +
203 +1. **No other provider needs this for output schemas.** Vercel
204 + (`ts/packages/providers/vercel/src/index.ts:108-133`) only feeds
205 + `inputParameters` to its Zod converter, and OpenAI/Anthropic/Google bind
206 + tool *input* schemas to function-calling APIs that ignore output shapes.
207 + `outputParameters` validation is a Mastra-specific surface.
208 +2. **Centralized dereferencing would mutate `tools.get()`'s public shape.**
209 + Users today read raw `inputParameters` / `outputParameters` from
210 + `tools.get` and `getRawComposioToolBySlug` and expect them to mirror the
211 + API response (modulo case transformation in `transformToolCases`).
212 + Inlining `$defs` for every caller — including ones whose consumers can
213 + resolve `$ref` natively — is a silent behavior change for non-Mastra
214 + users.
215 +3. **PLEN-2244 set the precedent.** Both fixes share the same boundary:
216 + the provider that owns the validation contract is the provider that
217 + pre-processes the schema. Keeping the new lenient path at the same
218 + boundary preserves architectural consistency.
219 +
220 +## Acceptance Criteria
221 +
222 +### Code
223 +
224 +- [x] `dereferenceJsonSchema` accepts an optional second arg
225 + `{ onUnresolved?: 'throw' | 'sentinel'; onReplace?: (ref, reason) => void }`.
226 +- [x] Default behavior (no opts) is byte-for-byte unchanged: still throws
227 + `JsonSchemaRefResolutionError` on a dangling internal `$ref`.
228 +- [x] Lenient mode (`onUnresolved: 'sentinel'`) replaces the offending node
229 + with the existing `CYCLE_BREAK_SENTINEL` and invokes `onReplace` exactly
230 + once per replacement, passing the original ref pointer + reason.
231 +- [x] Lenient mode still throws on `MAX_REF_CHAIN_DEPTH` /
232 + `MAX_NODE_DEPTH` breaches (safety caps are not lenient).
233 +- [x] `MastraProvider.wrapTool` calls `dereferenceJsonSchema(..., {
234 + onUnresolved: 'sentinel', onReplace })` for both `inputParameters` and
235 + `outputParameters`.
236 +- [x] `MastraProvider` warns once per `(toolSlug, refPointer)` pair via
237 + `@composio/core`'s `logger.warn`.
238 +- [x] No public TypeScript API is *removed*; the new opts arg is purely additive.
239 +
240 +### Tests (red before fix; green after)
241 +
242 +- [x] New unit tests in `ts/packages/core/test/utils/jsonSchema.test.ts`
243 + (9 new cases, all under `describe("with onUnresolved: 'sentinel' lenient mode")`):
244 + sentinel replaces dangling ref; sentinel replaces missing-key ref;
245 + `onReplace` invoked with ref + `'missing-target'`; `onReplace` invoked
246 + with `'malformed-pointer'` for non-`#/` pointers; chain-depth cap still
247 + throws; node-depth cap still throws; explicit `'throw'` matches default;
248 + `onReplace` not called in strict mode; mixed schema preserves resolvable
249 + branches while replacing only the dangling one.
250 +- [x] New regression test file
251 + `ts/packages/providers/mastra/test/mastra-dangling-defs.test.ts`
252 + (6 cases, un-mocked `@mastra/schema-compat`): no throw on dangling
253 + output ref (GMAIL shape); defined outputSchema with no surviving `$ref`;
254 + one warn per `(slug, ref)` pair across repeat wraps; separate warning
255 + per slug; symmetric tolerance on input refs; resolvable `$defs` still
256 + preserved.
257 +- [x] All existing tests still pass: core 908; mastra-ref 3; mastra.test 39;
258 + every other provider/cli package green.
259 +
260 +### Changeset
261 +
262 +- [x] `.changeset/fix-mastra-dangling-defs-ref.md` added — `@composio/core`
263 + and `@composio/mastra` both bumped patch; body describes the API
264 + behavior, the new `onUnresolved`/`onReplace` opt, and the Mastra opt-in.
265 + No Linear IDs (per repo convention — changesets ship to npm).
266 +
267 +### Manual verification
268 +
269 +- [ ] (Post-merge) Reproduce against the live API using the script from the
270 + tracking issue: `tools.get(userId, { tools: ['GMAIL_FETCH_EMAILS'] })`
271 + should return a `MastraTool` object whose `outputSchema` is defined.
272 +- [ ] Confirm the SDK logs exactly one warning per process per `(slug, ref)`
273 + pair with the expected message.
274 +
275 +## Red-Green Test Strategy
276 +
277 +The TDD loop:
278 +
279 +1. **Red — write tests + the new error/option signature.** No production
280 + implementation yet.
281 + - Add the new `DereferenceJsonSchemaOptions` interface and export it.
282 + - Type-only stub: `dereferenceJsonSchema` still accepts an unused second
283 + arg (`_options?: DereferenceJsonSchemaOptions`).
284 + - Add the four new `jsonSchema.test.ts` cases. They fail with
285 + `JsonSchemaRefResolutionError` (current strict behavior) or compile
286 + errors (if `onReplace` callback isn't exposed yet).
287 + - Add the four new `mastra-dangling-defs.test.ts` cases. They fail with
288 + `JsonSchemaRefResolutionError` propagated up from `wrapTool`.
289 +
290 +2. **Green — minimum implementation.**
291 + - Plumb the `onUnresolved` strategy through `walk` / `resolvePointer` /
292 + `stepInto`. Reuse `CYCLE_BREAK_SENTINEL`.
293 + - Wire `onReplace` invocations at the two failure call sites
294 + (`resolvePointer`'s missing target, `stepInto`'s non-object cursor).
295 + - Add `warnDanglingRefOnce` to `MastraProvider`, invoke from the two
296 + `wrapTool` call sites.
297 +
298 +3. **Refactor — tighten.**
299 + - Verify no allocation in the strict path (the new branch must be a
300 + zero-cost extension on the existing happy path).
301 + - Run the full `jsonSchema.test.ts` + `mastra-ref.test.ts` +
302 + `mastra-dangling-defs.test.ts` matrix to confirm no regressions.
303 +
304 +## Technical Considerations
305 +
306 +### Security
307 +
308 +- The sentinel (`{ type: 'object', additionalProperties: true }`) is the
309 + most permissive valid object schema. A schema falling back to it means
310 + Mastra's `validateToolOutput` will accept anything — *for that branch
311 + only*. The siblings (e.g. `required`, `title`) at the parent level are
312 + unaffected. This is strictly more permissive than `dereferenceJsonSchema`'s
313 + current "throw and refuse to run" behavior, so it does not introduce a new
314 + validation-bypass vector for trusted tool authors.
315 +- Prototype-pollution filter (`POLLUTING_KEYS` at `jsonSchema.ts:10`) and
316 + `WeakSet` cycle tracking are unaffected.
317 +
318 +### Performance
319 +
320 +- Walker still visits each node at most once. The new branch is an extra
321 + `if (strategy === 'sentinel') return CYCLE_BREAK_SENTINEL` after
322 + `resolvePointer` throws or returns the "unresolved" discriminator. No new
323 + allocations in the common (resolvable) path.
324 +
325 +### Compatibility
326 +
327 +- `DereferenceJsonSchemaOptions` is **additive**. Both the public
328 + `dereferenceJsonSchema` export (consumed by `@composio/mastra`) and the
329 + internal call sites can ignore the new parameter.
330 +- The `JsonSchemaRefResolutionError` class is unchanged. Callers that catch
331 + it (none today outside the test suite) keep working.
332 +- The default mode is `'throw'`, matching the PLEN-2244 contract. Custom-tool
333 + authors who deliberately point `$ref` at a non-existent `$defs` entry will
334 + still get a hard error — that is the right behavior for *their* schemas.
335 +
336 +## Dependencies & Risks
337 +
338 +- **No dependency bumps.** Unlike PLEN-2244 (which bumped
339 + `@mastra/schema-compat` to `^1.2.9`), this fix is internal to the SDK.
340 +- **Risk: developer surprise on raw schemas.** A reader of
341 + `getRawComposioTools(...)` sees `$ref` in the raw schema and finds it
342 + resolved to a sentinel in `wrapTool` output. Mitigation: the JSDoc on
343 + `dereferenceJsonSchema` documents the lenient contract, and the warning
344 + emitted by `MastraProvider` names the offending pointer.
345 +- **Risk: telemetry noise.** A user wrapping every Gmail tool in a wide
346 + toolkit fetch could see many warnings on first run. Mitigation: per-tool
347 + dedup in the Mastra provider; warning text points at the upstream Linear
348 + ticket so callers know it is a known, tracked issue.
349 +
350 +## File-Level Plan
351 +
352 +```
353 +ts/packages/core/src/utils/jsonSchema.ts # add opts; reuse CYCLE_BREAK_SENTINEL
354 +ts/packages/core/test/utils/jsonSchema.test.ts # 4 new cases (red → green)
355 +ts/packages/core/src/index.ts # re-export DereferenceJsonSchemaOptions if needed
356 +ts/packages/providers/mastra/src/index.ts # opt into 'sentinel' + per-tool warn dedup
357 +ts/packages/providers/mastra/test/mastra-dangling-defs.test.ts # new file, 4 cases (red → green)
358 +.changeset/fix-mastra-dangling-defs-ref.md # patch/patch
359 +```
360 +
361 +Pseudocode for the touchpoints:
362 +
363 +### `ts/packages/core/src/utils/jsonSchema.ts`
364 +
365 +```typescript
366 +export type UnresolvedRefStrategy = 'throw' | 'sentinel';
367 +
368 +export interface DereferenceJsonSchemaOptions {
369 + onUnresolved?: UnresolvedRefStrategy;
370 + onReplace?: (ref: string, reason: 'missing-target' | 'malformed-pointer') => void;
371 +}
372 +
373 +const failResolution = (
374 + pointer: string,
375 + segment: string,
376 + strategy: UnresolvedRefStrategy,
377 + onReplace?: DereferenceJsonSchemaOptions['onReplace']
378 +): typeof CYCLE_BREAK_SENTINEL => {
379 + if (strategy === 'sentinel') {
380 + onReplace?.(pointer, 'malformed-pointer');
381 + return { ...CYCLE_BREAK_SENTINEL };
382 + }
383 + throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
384 + meta: { ref: pointer, failedAt: segment },
385 + possibleFixes: REF_RESOLUTION_FIXES,
386 + });
387 +};
388 +// `resolvePointer` and `stepInto` receive `strategy` + `onReplace` and forward to `failResolution`.
389 +// `walk` checks for the sentinel return shape and stops descending.
390 +```
391 +
392 +### `ts/packages/providers/mastra/src/index.ts`
393 +
394 +```typescript
395 +private warnedDanglingRefs = new Set<string>();
396 +
397 +private warnDanglingRefOnce(toolSlug: string, toolkitSlug: string, ref: string) {
398 + const key = `${toolSlug}:${ref}`;
399 + if (this.warnedDanglingRefs.has(key)) return;
400 + this.warnedDanglingRefs.add(key);
401 + logger.warn(
402 + `[composio/mastra] Tool ${toolSlug} (toolkit ${toolkitSlug}) declares ` +
403 + `$ref ${ref} but no matching $defs/definitions entry. Falling back to a ` +
404 + `permissive object schema for this branch — the wrapped Mastra tool will ` +
405 + `validate loosely. See https://linear.app/composio/issue/PLEN-2451.`
406 + );
407 +}
408 +```
409 +
410 +## References & Research
411 +
412 +### Linear / GitHub
413 +
414 +- Linear ticket: PLEN-2451 — *MastraProvider $defs/$ref schema is dangling at the API source*.
415 +- Customer-facing GitHub issue: https://github.com/ComposioHQ/composio/issues/3307 (reported by `@0xpaperhead`, 2026-04-28).
416 +- Prior, related fix: PLEN-2244 (commits `5300bf8ba` red tests, `cc673b654` fix). Closed by `.changeset/fix-mastra-ref-dereference.md`.
417 +
418 +### Files
419 +
420 +- `ts/packages/providers/mastra/src/index.ts:80-126` — `MastraProvider.wrapTool` (the call site that needs to opt into lenient mode).
421 +- `ts/packages/core/src/utils/jsonSchema.ts:64-153` — `dereferenceJsonSchema` (the helper that needs the new opt).
422 +- `ts/packages/core/src/utils/jsonSchema.ts:9` — `CYCLE_BREAK_SENTINEL` (the sentinel to reuse).
423 +- `ts/packages/core/src/utils/jsonSchema.ts:19-36` — `failResolution` / `stepInto` (refactor target).
424 +- `ts/packages/core/src/errors/ValidationErrors.ts:89-99` — `JsonSchemaRefResolutionError` (unchanged).
425 +- `ts/packages/core/test/utils/jsonSchema.test.ts:150-158` — existing strict-mode test (the contract we keep as default).
426 +- `ts/packages/providers/mastra/test/mastra-ref.test.ts` — pattern to mirror for the new test file.
427 +- `ts/packages/providers/vercel/src/index.ts:108-133` — confirms `outputParameters` is Mastra-only.
428 +- `ts/packages/core/src/types/tool.types.ts:29-102` — `JSONSchemaPropertySchema` admits `$ref` / `$defs` / `definitions` (so the raw shape we test against is valid against `ToolSchema`).
429 +- `ts/packages/core/src/models/Tools.ts:140-150, 192-198` — confirms the central pipeline does *not* pre-process schemas and that the provider boundary is the right one.
430 +
431 +### External
432 +
433 +- JSON Pointer (RFC 6901) — escape semantics already handled correctly at `jsonSchema.ts:16-17`.
434 +- JSON Schema 2020-12 — sibling-keyword merge semantics already handled correctly at `jsonSchema.ts:133-141`.
435 +- `@mastra/schema-compat` — AJV-backed; refuses to compile schemas with unresolved internal `$ref`. Bundles `convertSchemaToZod` which silently degrades `$ref` → permissive `anyOf` when AJV is bypassed (the pre-PLEN-2244 failure mode).
ts/packages/core/src/index.ts
+6
@@ -9,6 +9,11 @@ export {
9 jsonSchemaToZodSchema,
10 removeNonRequiredProperties,
11 } from './utils/jsonSchema';
12 +export type {
13 + DereferenceJsonSchemaOptions,
14 + UnresolvedRefReason,
15 + UnresolvedRefStrategy,
16 +} from './utils/jsonSchema';
17 export { getExtensionFromMimeType } from './utils/mime';
18 export { AuthScheme } from './models/AuthScheme';
19 export { MCP } from './models/MCP';
@@ -33,6 +38,7 @@ export * from './types/ToolRouterSessionFilesMount.types';
38 export * as constants from './utils/constants';
39
40 export { default as logger } from './utils/logger';
41 +export { telemetry } from './telemetry/Telemetry';
42
43 // Experimental custom tools — exported with experimental_ prefix for top-level import
44 export { createCustomTool as experimental_createTool } from './models/CustomTool';
ts/packages/core/src/utils/jsonSchema.ts
+128 -22
@@ -7,6 +7,57 @@ import { isPlainObject } from './modifiers/FileToolModifier.utils.neutral';
7 const MAX_REF_CHAIN_DEPTH = 100;
8 const MAX_NODE_DEPTH = 512;
9 const CYCLE_BREAK_SENTINEL = { type: 'object', additionalProperties: true } as const;
10 +
11 +/**
12 + * In-band hint attached to the cycle-break sentinel when lenient mode
13 + * substitutes it for a dangling `$ref`. Makes the degradation visible to
14 + * LLMs that read the wrapped tool's schema — without it the LLM sees a
15 + * useless permissive object and no prose context. Wording is intentionally
16 + * context-neutral ("Schema shape", not "Output shape") because the helper
17 + * is used for both `inputParameters` and `outputParameters`. Overridden
18 + * when the caller's `$ref` node carries its own `description` sibling
19 + * (Draft 2020-12 sibling-keyword semantics).
20 + */
21 +const UNRESOLVED_REF_DESCRIPTION =
22 + 'Schema shape unresolved at the source — validate loosely. ' +
23 + 'See https://github.com/ComposioHQ/composio/issues/3307.';
24 +
25 +/**
26 + * Strategy for `dereferenceJsonSchema` when an internal `$ref` cannot be
27 + * resolved (target missing under `$defs`/`definitions`, or a malformed
28 + * pointer beneath the internal `#/` prefix).
29 + *
30 + * - `'throw'` (default): throw `JsonSchemaRefResolutionError`. Right for
31 + * first-party / custom-tool schemas where a dangling `$ref` is a developer
32 + * bug worth surfacing.
33 + * - `'sentinel'`: replace the offending node with the cycle-break sentinel
34 + * (`{ type: 'object', additionalProperties: true }`). Right for schemas
35 + * sourced from an upstream service the caller cannot edit (e.g. an
36 + * API-provided tool definition that emits `$ref` without a `$defs`
37 + * block — see https://github.com/ComposioHQ/composio/issues/3307).
38 + *
39 + * Safety caps (`MAX_REF_CHAIN_DEPTH`, `MAX_NODE_DEPTH`) still throw in both
40 + * modes; cycle handling (already permissive via `CYCLE_BREAK_SENTINEL`) is
41 + * unaffected.
42 + */
43 +export type UnresolvedRefStrategy = 'throw' | 'sentinel';
44 +
45 +/**
46 + * Reason a `$ref` was replaced with the sentinel in `'sentinel'` mode.
47 + * `onReplace` callbacks receive this so callers can attribute the
48 + * fallback (e.g., warn at the offending tool slug).
49 + */
50 +export type UnresolvedRefReason = 'missing-target' | 'malformed-pointer';
51 +
52 +export interface DereferenceJsonSchemaOptions {
53 + onUnresolved?: UnresolvedRefStrategy;
54 + /**
55 + * Invoked once per replaced node in `'sentinel'` mode. The ref is the
56 + * original pointer string from the schema; reason distinguishes a
57 + * missing `$defs` target from a malformed pointer.
58 + */
59 + onReplace?: (ref: string, reason: UnresolvedRefReason) => void;
60 +}
61 const POLLUTING_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
62 const REF_RESOLUTION_FIXES = [
63 'Ensure the $ref pointer matches a path in $defs or definitions',
@@ -16,38 +67,65 @@ const REF_RESOLUTION_FIXES = [
67 const decodePointerSegment = (segment: string): string =>
68 segment.replace(/~1/g, '/').replace(/~0/g, '~');
69
19 -const failResolution = (pointer: string, segment: string): never => {
20 - throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
21 - meta: { ref: pointer, failedAt: segment },
22 - possibleFixes: REF_RESOLUTION_FIXES,
23 - });
24 -};
70 +/**
71 + * Tagged result of attempting to resolve a `$ref`. `failedAt` is populated
72 + * only for the segment-walk path so strict-mode error meta stays identical
73 + * to the pre-lenient-mode shape.
74 + */
75 +type ResolutionResult =
76 + | { kind: 'ok'; value: unknown }
77 + | { kind: 'unresolved'; reason: UnresolvedRefReason; failedAt?: string };
78
26 -const stepInto = (cursor: unknown, segment: string, pointer: string): unknown => {
27 - if (cursor === null || typeof cursor !== 'object') failResolution(pointer, segment);
79 +const tryStep = (cursor: unknown, segment: string): ResolutionResult => {
80 + if (cursor === null || typeof cursor !== 'object') {
81 + return { kind: 'unresolved', reason: 'missing-target', failedAt: segment };
82 + }
83 if (Array.isArray(cursor)) {
84 const i = Number(segment);
30 - if (!Number.isInteger(i) || i < 0 || i >= cursor.length) failResolution(pointer, segment);
31 - return cursor[i];
85 + if (!Number.isInteger(i) || i < 0 || i >= cursor.length) {
86 + return { kind: 'unresolved', reason: 'missing-target', failedAt: segment };
87 + }
88 + return { kind: 'ok', value: cursor[i] };
89 }
90 const obj = cursor as Record<string, unknown>;
34 - if (!Object.prototype.hasOwnProperty.call(obj, segment)) failResolution(pointer, segment);
35 - return obj[segment];
91 + if (!Object.prototype.hasOwnProperty.call(obj, segment)) {
92 + return { kind: 'unresolved', reason: 'missing-target', failedAt: segment };
93 + }
94 + return { kind: 'ok', value: obj[segment] };
95 };
96
38 -const resolvePointer = (root: Record<string, unknown>, pointer: string): unknown => {
39 - if (pointer === '#' || pointer === '') return root;
97 +const tryResolvePointer = (root: Record<string, unknown>, pointer: string): ResolutionResult => {
98 + if (pointer === '#' || pointer === '') return { kind: 'ok', value: root };
99 if (!pointer.startsWith('#/')) {
100 + return { kind: 'unresolved', reason: 'malformed-pointer' };
101 + }
102 + const segments = pointer.slice(2).split('/').map(decodePointerSegment);
103 + let cursor: unknown = root;
104 + for (const seg of segments) {
105 + const step = tryStep(cursor, seg);
106 + if (step.kind === 'unresolved') return step;
107 + cursor = step.value;
108 + }
109 + return { kind: 'ok', value: cursor };
110 +};
111 +
112 +const throwResolutionError = (
113 + pointer: string,
114 + result: Extract<ResolutionResult, { kind: 'unresolved' }>
115 +): never => {
116 + if (result.reason === 'malformed-pointer') {
117 throw new JsonSchemaRefResolutionError(`Unsupported $ref pointer: ${pointer}`, {
118 meta: { ref: pointer },
119 possibleFixes: REF_RESOLUTION_FIXES,
120 });
121 }
46 - return pointer
47 - .slice(2)
48 - .split('/')
49 - .map(decodePointerSegment)
50 - .reduce<unknown>((cursor, seg) => stepInto(cursor, seg, pointer), root);
122 + throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
123 + meta: {
124 + ref: pointer,
125 + ...(result.failedAt !== undefined ? { failedAt: result.failedAt } : {}),
126 + },
127 + possibleFixes: REF_RESOLUTION_FIXES,
128 + });
129 };
130
131 /**
@@ -58,12 +136,25 @@ const resolvePointer = (root: Record<string, unknown>, pointer: string): unknown
136 * left untouched. Cycles are broken with `{ type: 'object',
137 * additionalProperties: true }`. The input is never mutated.
138 *
139 + * By default, unresolved internal refs throw `JsonSchemaRefResolutionError`.
140 + * Pass `{ onUnresolved: 'sentinel' }` to replace the offending node with the
141 + * cycle-break sentinel instead — appropriate for schemas sourced from an
142 + * upstream service the caller cannot edit (the Composio API ships some
143 + * `outputParameters` with a `$ref` into `#/$defs/...` but never declares
144 + * `$defs`; see https://github.com/ComposioHQ/composio/issues/3307).
145 + *
146 * @throws {JsonSchemaRefResolutionError} on malformed pointers, missing
62 - * targets, or chains past the depth cap.
147 + * targets (strict mode only), or chains past the depth cap (both modes).
148 */
64 -export function dereferenceJsonSchema<T = unknown>(schema: T): T {
149 +export function dereferenceJsonSchema<T = unknown>(
150 + schema: T,
151 + options?: DereferenceJsonSchemaOptions
152 +): T {
153 if (!isPlainObject(schema)) return schema;
154
155 + const strategy: UnresolvedRefStrategy = options?.onUnresolved ?? 'throw';
156 + const onReplace = options?.onReplace;
157 +
158 const root = schema as Record<string, unknown>;
159 const visiting = new WeakSet<object>();
160
@@ -126,7 +217,22 @@ export function dereferenceJsonSchema<T = unknown>(schema: T): T {
217 }
218 if (visitedRefs.has(ref)) return { ...CYCLE_BREAK_SENTINEL };
219
129 - const target = resolvePointer(root, ref);
220 + const result = tryResolvePointer(root, ref);
221 + let target: unknown;
222 + if (result.kind === 'ok') {
223 + target = result.value;
224 + } else if (strategy === 'sentinel') {
225 + // Lenient mode: replace the unresolved branch with the same
226 + // permissive sentinel used for cycles, and notify the caller so
227 + // they can emit a one-shot warn at the offending tool surface.
228 + // The injected `description` gives the LLM an in-band signal that
229 + // the branch is opaque; sibling-merge below will overwrite it with
230 + // a caller-provided description if the original node has one.
231 + onReplace?.(ref, result.reason);
232 + target = { ...CYCLE_BREAK_SENTINEL, description: UNRESOLVED_REF_DESCRIPTION };
233 + } else {
234 + throwResolutionError(ref, result);
235 + }
236 const nextRefs = new Set(visitedRefs).add(ref);
237 const resolved = walk(target, nextRefs, chainDepth + 1, nodeDepth + 1);
238
ts/packages/core/test/utils/jsonSchema.test.ts
+204
@@ -279,4 +279,208 @@ describe('dereferenceJsonSchema', () => {
279
280 expect((out as { properties: { v: { type: string } } }).properties.v.type).toBe('string');
281 });
282 +
283 + describe("with onUnresolved: 'sentinel' lenient mode", () => {
284 + // Sentinel injected for an unresolvable $ref carries an LLM-visible hint
285 + // describing the degradation. The hint is overwritten by a caller-provided
286 + // `description` sibling when present (Draft 2020-12 sibling-keyword merge).
287 + const PERMISSIVE = {
288 + type: 'object',
289 + additionalProperties: true,
290 + description: expect.stringContaining('Schema shape unresolved at the source'),
291 + };
292 +
293 + it('replaces a dangling internal $ref (no $defs block at all) with the cycle-break sentinel', () => {
294 + // Mirrors GMAIL_FETCH_EMAILS.outputParameters: a $ref into #/$defs/...
295 + // without any $defs declared on the root.
296 + const out = dereferenceJsonSchema(
297 + {
298 + type: 'object',
299 + properties: {
300 + data: { $ref: '#/$defs/FetchEmailsResponse' },
301 + error: { type: 'string' },
302 + successful: { type: 'boolean' },
303 + },
304 + required: ['data', 'successful'],
305 + title: 'FetchEmailsResponseWrapper',
306 + },
307 + { onUnresolved: 'sentinel' }
308 + ) as {
309 + type: string;
310 + properties: { data: unknown; error: unknown; successful: unknown };
311 + required: string[];
312 + };
313 +
314 + expect(out.properties.data).toEqual(PERMISSIVE);
315 + // Siblings of the replaced node are untouched.
316 + expect(out.properties.error).toEqual({ type: 'string' });
317 + expect(out.properties.successful).toEqual({ type: 'boolean' });
318 + expect(out.required).toEqual(['data', 'successful']);
319 + expect(containsRef(out)).toBe(false);
320 + });
321 +
322 + it('replaces a $ref that points into an empty $defs (missing key) with the sentinel', () => {
323 + const out = dereferenceJsonSchema(
324 + {
325 + type: 'object',
326 + properties: { v: { $ref: '#/$defs/Missing' } },
327 + $defs: {},
328 + },
329 + { onUnresolved: 'sentinel' }
330 + ) as { properties: { v: unknown } };
331 +
332 + expect(out.properties.v).toEqual(PERMISSIVE);
333 + expect(containsRef(out)).toBe(false);
334 + });
335 +
336 + it("invokes onReplace once per replacement with the original ref and reason 'missing-target'", () => {
337 + const calls: Array<[string, string]> = [];
338 + dereferenceJsonSchema(
339 + {
340 + type: 'object',
341 + properties: {
342 + a: { $ref: '#/$defs/Missing' },
343 + b: { $ref: '#/$defs/Missing' },
344 + c: { $ref: '#/$defs/AlsoMissing' },
345 + },
346 + },
347 + {
348 + onUnresolved: 'sentinel',
349 + onReplace: (ref, reason) => calls.push([ref, reason]),
350 + }
351 + );
352 +
353 + expect(calls).toEqual([
354 + ['#/$defs/Missing', 'missing-target'],
355 + ['#/$defs/Missing', 'missing-target'],
356 + ['#/$defs/AlsoMissing', 'missing-target'],
357 + ]);
358 + });
359 +
360 + it("invokes onReplace with reason 'malformed-pointer' for a non '/' internal pointer", () => {
361 + const calls: Array<[string, string]> = [];
362 + const out = dereferenceJsonSchema(
363 + {
364 + type: 'object',
365 + properties: { v: { $ref: '#bar' } },
366 + },
367 + {
368 + onUnresolved: 'sentinel',
369 + onReplace: (ref, reason) => calls.push([ref, reason]),
370 + }
371 + ) as { properties: { v: unknown } };
372 +
373 + expect(calls).toEqual([['#bar', 'malformed-pointer']]);
374 + expect(out.properties.v).toEqual(PERMISSIVE);
375 + });
376 +
377 + it('still throws JsonSchemaRefResolutionError when chain depth exceeds the cap (safety cap is not lenient)', () => {
378 + const $defs: Record<string, unknown> = {};
379 + for (let i = 0; i < 200; i++) {
380 + $defs[`A${i}`] = { $ref: i + 1 < 200 ? `#/$defs/A${i + 1}` : '#/$defs/A0' };
381 + }
382 + expect(() =>
383 + dereferenceJsonSchema(
384 + {
385 + type: 'object',
386 + properties: { v: { $ref: '#/$defs/A0' } },
387 + $defs,
388 + },
389 + { onUnresolved: 'sentinel' }
390 + )
391 + ).toThrow(JsonSchemaRefResolutionError);
392 + });
393 +
394 + it('still throws JsonSchemaRefResolutionError when node depth exceeds the cap (safety cap is not lenient)', () => {
395 + type Nested = { type: 'object'; properties: { x: Nested | { type: 'string' } } };
396 + let leaf: Nested | { type: 'string' } = { type: 'string' };
397 + for (let i = 0; i < 1000; i++) {
398 + leaf = { type: 'object', properties: { x: leaf } } as Nested;
399 + }
400 + expect(() => dereferenceJsonSchema(leaf, { onUnresolved: 'sentinel' })).toThrow(
401 + JsonSchemaRefResolutionError
402 + );
403 + });
404 +
405 + it("explicit onUnresolved: 'throw' matches default behavior", () => {
406 + expect(() =>
407 + dereferenceJsonSchema(
408 + {
409 + type: 'object',
410 + properties: { v: { $ref: '#/$defs/Missing' } },
411 + $defs: {},
412 + },
413 + { onUnresolved: 'throw' }
414 + )
415 + ).toThrow(JsonSchemaRefResolutionError);
416 + });
417 +
418 + it('does not call onReplace in strict mode (regression guard)', () => {
419 + const onReplace = vi.fn();
420 + expect(() =>
421 + dereferenceJsonSchema(
422 + {
423 + type: 'object',
424 + properties: { v: { $ref: '#/$defs/Missing' } },
425 + $defs: {},
426 + },
427 + { onUnresolved: 'throw', onReplace }
428 + )
429 + ).toThrow(JsonSchemaRefResolutionError);
430 + expect(onReplace).not.toHaveBeenCalled();
431 + });
432 +
433 + it("injects a default LLM-visible 'description' on the sentinel when the source $ref node has none", () => {
434 + const out = dereferenceJsonSchema(
435 + {
436 + type: 'object',
437 + properties: { v: { $ref: '#/$defs/Missing' } },
438 + },
439 + { onUnresolved: 'sentinel' }
440 + ) as { properties: { v: { description: string } } };
441 +
442 + expect(out.properties.v.description).toMatch(/Schema shape unresolved at the source/);
443 + expect(out.properties.v.description).toContain(
444 + 'https://github.com/ComposioHQ/composio/issues/3307'
445 + );
446 + });
447 +
448 + it("preserves a caller-provided 'description' sibling instead of overwriting with the default", () => {
449 + const out = dereferenceJsonSchema(
450 + {
451 + type: 'object',
452 + properties: {
453 + v: {
454 + $ref: '#/$defs/Missing',
455 + description: 'caller-supplied prose context',
456 + },
457 + },
458 + },
459 + { onUnresolved: 'sentinel' }
460 + ) as { properties: { v: { description: string; type: string } } };
461 +
462 + // Sibling-merge wins over the default — caller context survives.
463 + expect(out.properties.v.description).toBe('caller-supplied prose context');
464 + expect(out.properties.v.type).toBe('object');
465 + });
466 +
467 + it('preserves resolvable $defs while replacing only the dangling branch (mixed schema)', () => {
468 + const out = dereferenceJsonSchema(
469 + {
470 + type: 'object',
471 + properties: {
472 + resolved: { $ref: '#/$defs/Real' },
473 + dangling: { $ref: '#/$defs/Ghost' },
474 + },
475 + $defs: {
476 + Real: { type: 'integer' },
477 + },
478 + },
479 + { onUnresolved: 'sentinel' }
480 + ) as { properties: { resolved: { type: string }; dangling: unknown } };
481 +
482 + expect(out.properties.resolved).toEqual({ type: 'integer' });
483 + expect(out.properties.dangling).toEqual(PERMISSIVE);
484 + });
485 + });
486 });
ts/packages/providers/mastra/src/index.ts
+58 -4
@@ -12,7 +12,10 @@ import {
12 ExecuteToolFn,
13 McpUrlResponse,
14 dereferenceJsonSchema,
15 + logger,
16 removeNonRequiredProperties,
17 + telemetry,
18 + type UnresolvedRefReason,
19 } from '@composio/core';
20 import { applyCompatLayer } from '@mastra/schema-compat';
21 import { createTool } from '@mastra/core/tools';
@@ -34,6 +37,10 @@ export class MastraProvider extends BaseAgenticProvider<
37 > {
38 readonly name = 'mastra';
39 private strict: boolean | null;
40 + // Tracks the (toolSlug, ref) pairs we've already warned about, so wrapping
41 + // the same tool many times during a single SDK session does not flood the
42 + // logs. Reset is only via constructing a new provider.
43 + private warnedDanglingRefs = new Set<string>();
44
45 /**
46 * Creates a new instance of the MastraProvider.
@@ -95,16 +102,33 @@ export class MastraProvider extends BaseAgenticProvider<
102 // @mastra/schema-compat. AJV (bundled inside schema-compat) refuses to
103 // compile a schema with unresolved $ref, and the upstream JSON-Schema →
104 // 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.
105 + // anyOf — losing the type info from $defs. See
106 + // https://github.com/mastra-ai/mastra/issues/15341.
107 + //
108 + // Some Composio-API-supplied tools emit a `$ref` into `#/$defs/...`
109 + // without ever declaring `$defs` (e.g. `GMAIL_FETCH_EMAILS`). Strict
110 + // dereferencing throws on this, which crashes `tools.get` upfront. Opt
111 + // into `'sentinel'` so the dangling branch becomes a permissive object
112 + // schema instead, and emit a single warn per (toolSlug, ref) pair so the
113 + // degraded shape is observable. See
114 + // https://github.com/ComposioHQ/composio/issues/3307.
115 + const onReplace = (ref: string, reason: UnresolvedRefReason) =>
116 + this.warnDanglingRefOnce(tool, ref, reason);
117 +
118 const inputSchema = applyCompatLayer({
101 - schema: dereferenceJsonSchema(parameters ?? {}),
119 + schema: dereferenceJsonSchema(parameters ?? {}, {
120 + onUnresolved: 'sentinel',
121 + onReplace,
122 + }),
123 compatLayers: [],
124 mode: 'jsonSchema',
125 });
126
127 const outputSchema = applyCompatLayer({
107 - schema: dereferenceJsonSchema(tool.outputParameters ?? {}),
128 + schema: dereferenceJsonSchema(tool.outputParameters ?? {}, {
129 + onUnresolved: 'sentinel',
130 + onReplace,
131 + }),
132 compatLayers: [],
133 mode: 'jsonSchema',
134 });
@@ -131,4 +155,34 @@ export class MastraProvider extends BaseAgenticProvider<
155 return acc;
156 }, {} as MastraToolCollection);
157 }
158 +
159 + private warnDanglingRefOnce(tool: Tool, ref: string, reason: UnresolvedRefReason): void {
160 + const key = `${tool.slug}::${ref}`;
161 + if (this.warnedDanglingRefs.has(key)) return;
162 + this.warnedDanglingRefs.add(key);
163 + const toolkitSlug = tool.toolkit?.slug ?? 'unknown';
164 + // `tool.slug`, `toolkitSlug`, and `ref` originate from the upstream API
165 + // schema. Quoting via `JSON.stringify` neutralizes embedded newlines /
166 + // ANSI escape sequences / control bytes that would otherwise forge log
167 + // lines or corrupt terminals (CWE-117).
168 + logger.warn(
169 + `[composio/mastra] Tool ${JSON.stringify(tool.slug)} ` +
170 + `(toolkit ${JSON.stringify(toolkitSlug)}) declares ` +
171 + `$ref ${JSON.stringify(ref)} but no matching $defs/definitions entry ` +
172 + `(${reason}). Falling back to a permissive object schema for this ` +
173 + `branch — the wrapped Mastra tool will validate this property loosely. ` +
174 + `Tracked in https://github.com/ComposioHQ/composio/issues/3307.`
175 + );
176 + // Fire-and-forget aggregate signal so the Composio team can prioritize the
177 + // upstream API fix from real data. `telemetry.sendMetric` short-circuits
178 + // when `COMPOSIO_DISABLE_TELEMETRY=true` and swallows network errors.
179 + void telemetry.sendMetric([
180 + {
181 + functionName: 'composio.mastra.wrapTool.danglingRef',
182 + timestamp: Date.now() / 1000,
183 + props: { toolSlug: tool.slug, toolkitSlug, ref, reason },
184 + metadata: { provider: 'mastra' },
185 + },
186 + ]);
187 + }
188 }
ts/packages/providers/mastra/test/mastra-dangling-defs.test.ts new
+257
@@ -0,0 +1,257 @@
1 +/**
2 + * Regression test for https://github.com/ComposioHQ/composio/issues/3307 —
3 + * the Composio API ships some `outputParameters` with a `$ref` into
4 + * `#/$defs/...` while never declaring `$defs` (e.g., `GMAIL_FETCH_EMAILS`).
5 + * The strict `dereferenceJsonSchema` throws on this, which cascades through
6 + * `MastraProvider.wrapTool` and crashes `tools.get` upfront.
7 + *
8 + * `MastraProvider` opts the dereferencer into `onUnresolved: 'sentinel'`,
9 + * replacing dangling internal refs with the cycle-break sentinel
10 + * (`{ type: 'object', additionalProperties: true }`) and emitting one
11 + * `logger.warn` per `(toolSlug, ref)` pair.
12 + *
13 + * Like `mastra-ref.test.ts`, this file deliberately does NOT mock
14 + * `@mastra/schema-compat` — Vitest mock scoping is per-file, so the mock in
15 + * `mastra.test.ts` does not leak here, and the test exercises the real
16 + * AJV-backed compat layer.
17 + */
18 +
19 +import { describe, it, expect, vi, beforeEach } from 'vitest';
20 +import {
21 + logger,
22 + telemetry,
23 + type ExecuteToolFn,
24 + type Tool,
25 + type ToolExecuteResponse,
26 +} from '@composio/core';
27 +import { MastraProvider } from '../src';
28 +
29 +// The fixtures below deliberately build `Tool`-shaped objects whose
30 +// `inputParameters` / `outputParameters` carry `$ref` properties — a shape
31 +// `ParametersSchema` admits via `JSONSchemaPropertySchema` but that does not
32 +// satisfy the parent record type at the literal level. `makeTool` localizes
33 +// the cast so individual fixtures stay readable.
34 +type TestSchema = Record<string, unknown>;
35 +type TestToolOverrides = Partial<Omit<Tool, 'inputParameters' | 'outputParameters'>> & {
36 + inputParameters?: TestSchema;
37 + outputParameters?: TestSchema;
38 +};
39 +
40 +const makeTool = (overrides: TestToolOverrides): Tool =>
41 + ({
42 + slug: 'TEST_TOOL',
43 + name: 'Test Tool',
44 + description: '',
45 + toolkit: { slug: 'test', name: 'Test' },
46 + version: '20260510_00',
47 + availableVersions: ['20260510_00'],
48 + tags: [],
49 + inputParameters: {
50 + type: 'object',
51 + properties: {},
52 + },
53 + outputParameters: {
54 + type: 'object',
55 + properties: {},
56 + },
57 + ...overrides,
58 + }) as unknown as Tool;
59 +
60 +// Exact shape of `GMAIL_FETCH_EMAILS.outputParameters` from
61 +// https://github.com/ComposioHQ/composio/issues/3307: a `$ref` into
62 +// `#/$defs/...` with no `$defs` block declared anywhere.
63 +const danglingOutputTool = makeTool({
64 + slug: 'DANGLING_OUTPUT_TOOL',
65 + name: 'Dangling Output Tool',
66 + description: 'Tool whose outputParameters carries a dangling $ref',
67 + toolkit: { slug: 'dangling', name: 'Dangling Toolkit' },
68 + inputParameters: {
69 + type: 'object',
70 + properties: { query: { type: 'string' } },
71 + required: ['query'],
72 + },
73 + outputParameters: {
74 + type: 'object',
75 + properties: {
76 + data: {
77 + description: 'Data from the action execution',
78 + title: 'Data',
79 + $ref: '#/$defs/FetchEmailsResponse',
80 + },
81 + error: { type: 'string', description: 'Error if the action failed', title: 'Error' },
82 + successful: {
83 + type: 'boolean',
84 + description: 'Whether the action was successful',
85 + title: 'Successful',
86 + },
87 + },
88 + required: ['data', 'successful'],
89 + title: 'FetchEmailsResponseWrapper',
90 + },
91 +});
92 +
93 +const danglingInputTool = makeTool({
94 + slug: 'DANGLING_INPUT_TOOL',
95 + name: 'Dangling Input Tool',
96 + toolkit: { slug: 'dangling', name: 'Dangling Toolkit' },
97 + inputParameters: {
98 + type: 'object',
99 + properties: { filter: { $ref: '#/$defs/UnknownFilter' } },
100 + required: ['filter'],
101 + },
102 + outputParameters: { type: 'object', properties: { ok: { type: 'boolean' } } },
103 +});
104 +
105 +const resolvableRefTool = makeTool({
106 + slug: 'RESOLVABLE_REF_TOOL',
107 + name: 'Resolvable Ref Tool',
108 + inputParameters: {
109 + type: 'object',
110 + properties: { user: { $ref: '#/$defs/User' } },
111 + required: ['user'],
112 + $defs: {
113 + User: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
114 + },
115 + },
116 + outputParameters: { type: 'object', properties: { ok: { type: 'boolean' } } },
117 +});
118 +
119 +describe('MastraProvider: dangling $ref tolerance', () => {
120 + let provider: MastraProvider;
121 + let warnSpy: ReturnType<typeof vi.spyOn>;
122 + let telemetrySpy: ReturnType<typeof vi.spyOn>;
123 + let exec: ExecuteToolFn;
124 +
125 + beforeEach(() => {
126 + provider = new MastraProvider();
127 + const mockExec = vi.fn<Parameters<ExecuteToolFn>, ReturnType<ExecuteToolFn>>(
128 + async () => ({ data: {}, error: null, successful: true }) as unknown as ToolExecuteResponse
129 + );
130 + exec = mockExec;
131 + provider._setExecuteToolFn(exec);
132 + warnSpy = vi.spyOn(logger, 'warn').mockImplementation(() => {});
133 + telemetrySpy = vi.spyOn(telemetry, 'sendMetric').mockResolvedValue(undefined);
134 + });
135 +
136 + it('does not throw when outputParameters has a $ref with no $defs declared (GMAIL_FETCH_EMAILS shape)', () => {
137 + expect(() => provider.wrapTool(danglingOutputTool, exec)).not.toThrow();
138 + });
139 +
140 + it('produces a defined outputSchema with the dangling branch replaced by a permissive object', () => {
141 + const wrapped = provider.wrapTool(danglingOutputTool, exec) as {
142 + outputSchema: unknown;
143 + };
144 + expect(wrapped.outputSchema).toBeDefined();
145 + // The wrapped schema went through applyCompatLayer (JSON Schema → Zod →
146 + // JSON Schema). All we can guarantee at this level is no surviving
147 + // $ref string anywhere in the structure.
148 + expect(JSON.stringify(wrapped.outputSchema)).not.toContain('$ref');
149 + });
150 +
151 + it('emits exactly one logger.warn per (toolSlug, ref) pair, even when the same tool is wrapped multiple times', () => {
152 + provider.wrapTool(danglingOutputTool, exec);
153 + provider.wrapTool(danglingOutputTool, exec);
154 + provider.wrapTool(danglingOutputTool, exec);
155 +
156 + const calls = warnSpy.mock.calls.filter(
157 + ([msg]) => typeof msg === 'string' && msg.includes('#/$defs/FetchEmailsResponse')
158 + );
159 + expect(calls).toHaveLength(1);
160 + const message = calls[0][0] as string;
161 + // User-controlled segments are JSON.stringified — they appear quoted in
162 + // the warn output (CWE-117 mitigation; see warnDanglingRefOnce).
163 + expect(message).toContain('"DANGLING_OUTPUT_TOOL"');
164 + expect(message).toContain('"dangling"');
165 + expect(message).toContain('"#/$defs/FetchEmailsResponse"');
166 + expect(message).toContain('github.com/ComposioHQ/composio/issues/3307');
167 + });
168 +
169 + it('emits a separate warning for a different tool slug carrying the same ref', () => {
170 + const sameRefDifferentSlug = makeTool({
171 + ...danglingOutputTool,
172 + slug: 'OTHER_DANGLING_OUTPUT_TOOL',
173 + });
174 + provider.wrapTool(danglingOutputTool, exec);
175 + provider.wrapTool(sameRefDifferentSlug, exec);
176 +
177 + const calls = warnSpy.mock.calls.filter(
178 + ([msg]) => typeof msg === 'string' && msg.includes('#/$defs/FetchEmailsResponse')
179 + );
180 + expect(calls).toHaveLength(2);
181 + });
182 +
183 + it('tolerates a dangling $ref on inputParameters (symmetric with output)', () => {
184 + expect(() => provider.wrapTool(danglingInputTool, exec)).not.toThrow();
185 + const calls = warnSpy.mock.calls.filter(
186 + ([msg]) => typeof msg === 'string' && msg.includes('#/$defs/UnknownFilter')
187 + );
188 + expect(calls).toHaveLength(1);
189 + });
190 +
191 + it('sanitizes control bytes / newlines / ANSI escapes in the warning (CWE-117 regression)', () => {
192 + // An upstream-shaped tool whose $ref carries a newline + ANSI CSI sequence.
193 + // Without JSON.stringify on the interpolated segments, these bytes would
194 + // be written verbatim to stderr, forging a fake log line.
195 + const malicious = makeTool({
196 + slug: 'MALICIOUS_TOOL',
197 + outputParameters: {
198 + type: 'object',
199 + properties: { data: { $ref: '#/$defs/Foo\n\x1b[31mFAKE LOG LINE\x1b[0m' } },
200 + },
201 + });
202 + provider.wrapTool(malicious, exec);
203 + const calls = warnSpy.mock.calls.filter(
204 + ([msg]) => typeof msg === 'string' && msg.includes('MALICIOUS_TOOL')
205 + );
206 + expect(calls).toHaveLength(1);
207 + const message = calls[0][0] as string;
208 + // Raw newline / escape bytes must NOT survive into the warning string.
209 + expect(message).not.toMatch(/[\x00-\x09\x0b-\x1f]/);
210 + // Escapes appear in their JSON-encoded form instead.
211 + expect(message).toContain('\\n');
212 + expect(message).toContain('\\u001b');
213 + });
214 +
215 + it('fires one telemetry event per (toolSlug, ref) pair next to the warn', () => {
216 + provider.wrapTool(danglingOutputTool, exec);
217 + provider.wrapTool(danglingOutputTool, exec); // dedup: still 1 event
218 +
219 + const calls = telemetrySpy.mock.calls.filter(([payload]) => {
220 + const events = payload as Array<{ functionName: string; props?: Record<string, unknown> }>;
221 + return events.some(e => e.functionName === 'composio.mastra.wrapTool.danglingRef');
222 + });
223 + expect(calls).toHaveLength(1);
224 +
225 + const event = (calls[0][0] as Array<Record<string, unknown>>)[0];
226 + expect(event.functionName).toBe('composio.mastra.wrapTool.danglingRef');
227 + expect(event.props).toMatchObject({
228 + toolSlug: 'DANGLING_OUTPUT_TOOL',
229 + toolkitSlug: 'dangling',
230 + ref: '#/$defs/FetchEmailsResponse',
231 + reason: 'missing-target',
232 + });
233 + expect(event.metadata).toEqual({ provider: 'mastra' });
234 + });
235 +
236 + it('does NOT fire telemetry for tools whose $refs all resolve', () => {
237 + provider.wrapTool(resolvableRefTool, exec);
238 + const calls = telemetrySpy.mock.calls.filter(([payload]) => {
239 + const events = payload as Array<{ functionName: string }>;
240 + return events.some(e => e.functionName === 'composio.mastra.wrapTool.danglingRef');
241 + });
242 + expect(calls).toHaveLength(0);
243 + });
244 +
245 + it('preserves resolvable $defs (regression guard — no degraded permissive anyOf)', () => {
246 + const wrapped = provider.wrapTool(resolvableRefTool, exec) as { inputSchema: unknown };
247 + // Resolvable $ref should produce a real schema with the User shape inlined.
248 + const inputJson = JSON.stringify(wrapped.inputSchema);
249 + expect(inputJson).toContain('id');
250 + expect(inputJson).not.toContain('$ref');
251 + // No warning should be emitted for resolvable refs.
252 + const calls = warnSpy.mock.calls.filter(
253 + ([msg]) => typeof msg === 'string' && msg.includes('$ref')
254 + );
255 + expect(calls).toHaveLength(0);
256 + });
257 +});