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).