Skip to content

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)

Alberto Schiabelb69cef123f2d
diff --git a/.changeset/fix-mastra-dangling-defs-ref.md b/.changeset/fix-mastra-dangling-defs-ref.md
new file mode 100644
index 000000000..eb092044b
--- /dev/null
+++ b/.changeset/fix-mastra-dangling-defs-ref.md
@@ -0,0 +1,11 @@
+---
+'@composio/core': patch
+'@composio/mastra': patch
+---
+
+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.
+
+- `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.
+- `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`.
+- 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.
+- Resolvable `$defs` / `definitions` continue to be inlined exactly as before — no regression in the type-info preservation contract introduced by the previous Mastra fix.
diff --git a/plans/fix-mastra-dangling-defs-ref.md b/plans/fix-mastra-dangling-defs-ref.md
new file mode 100644
index 000000000..efdd36245
--- /dev/null
+++ b/plans/fix-mastra-dangling-defs-ref.md
@@ -0,0 +1,435 @@
+# fix: Tolerate dangling `$ref` in Mastra provider when API omits `$defs`
+
+## Overview
+
+`MastraProvider.wrapTool` calls `dereferenceJsonSchema` to inline JSON Schema `$ref`
+pointers before handing the schema to `@mastra/schema-compat`. That contract was
+introduced in PLEN-2244 (commit `cc673b654`) and assumes every `#/$defs/...` ref
+has a resolvable target. The Composio API ships at least one toolkit family
+(Gmail, and any other toolkit whose `outputParameters` uses `$ref`) where the
+schema declares `"$ref": "#/$defs/FetchEmailsResponse"` **without ever declaring
+`$defs`**. The current resolver correctly throws a typed
+`JsonSchemaRefResolutionError`, but that error escapes `wrapTool` and crashes
+`composio.tools.get(...)` upfront — making affected toolkits unusable through
+the Mastra provider.
+
+This plan makes `dereferenceJsonSchema` opt-in lenient against unresolved
+internal refs (using the existing cycle sentinel, `{ type: 'object', additionalProperties: true }`),
+opts the Mastra provider into that lenient mode with a one-shot per-tool warning,
+and locks the behavior in with red-green regression tests that mirror the exact
+`GMAIL_FETCH_EMAILS` shape from the Linear ticket.
+
+> **API-side follow-up (out of scope here):** the proper long-term fix is for
+> `/api/v3/tools/:slug` to emit a top-level `$defs` block alongside any `$ref`
+> it produces. That fix benefits every consumer (Mastra, Vercel AI SDK, future
+> providers). It is tracked separately so the SDK does not have to block on
+> the backend roll-out.
+
+## Problem Statement / Motivation
+
+### Reproduction (from PLEN-2451, verified 2026-05-10)
+
+Direct dump of `GMAIL_FETCH_EMAILS.outputParameters` via
+`composio.tools.getRawComposioTools(...)`:
+
+```jsonc
+{
+ "type": "object",
+ "properties": {
+ "data": {
+ "description": "Data from the action execution",
+ "title": "Data",
+ "$ref": "#/$defs/FetchEmailsResponse" // ← points into $defs
+ },
+ "error": { "type": "string", "description": "...", "title": "Error" },
+ "successful": { "type": "boolean", "description": "...", "title": "Successful" }
+ },
+ "required": ["data", "successful"],
+ "title": "FetchEmailsResponseWrapper"
+ // ← no `$defs` block anywhere
+}
+```
+
+Observed behavior:
+
+| Version pair | Failure mode |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `@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. |
+| `@composio/{core,mastra}@0.9.0` (latest) | `tools.get` itself throws `JsonSchemaRefResolutionError: Cannot resolve $ref #/$defs/FetchEmailsResponse` upfront. |
+
+The 0.9.0 behavior is *correct* given the PLEN-2244 strict contract — but the
+contract is wrong for upstream-supplied schemas the SDK cannot edit. Every
+toolkit whose `outputParameters` carries a `$ref` (Gmail, Slack, Google
+Calendar, …) currently breaks Mastra integration.
+
+### Why the reporter's "Option A" fix does not work
+
+GitHub issue [#3307](https://github.com/ComposioHQ/composio/issues/3307)
+proposes inlining `$defs` before calling `applyCompatLayer`. That is exactly
+what PLEN-2244 already does (`ts/packages/providers/mastra/src/index.ts:100-110`).
+The root cause is **upstream of** `applyCompatLayer`: there is no `$defs` to
+inline. PLEN-2244's fix surfaces a dangling pointer instead of silently
+producing a permissive `anyOf`, which is the right developer experience for
+custom tools but the wrong one for opaque API-supplied schemas.
+
+## Proposed Solution
+
+Two-tier fix that keeps the same architecture as PLEN-2244:
+
+### 1. `@composio/core` — add an `onUnresolved` option to `dereferenceJsonSchema`
+
+`ts/packages/core/src/utils/jsonSchema.ts`
+
+```typescript
+export type UnresolvedRefStrategy = 'throw' | 'sentinel';
+
+export interface DereferenceJsonSchemaOptions {
+ /**
+ * What to do when a `#/$defs/...` or `#/definitions/...` $ref cannot be
+ * resolved (target missing, $defs/definitions block absent, malformed
+ * pointer beneath an internal #/ prefix).
+ *
+ * - `'throw'` (default): preserve current behavior — throw
+ * `JsonSchemaRefResolutionError`. Right for first-party / custom-tool
+ * schemas where a dangling ref is a developer bug.
+ * - `'sentinel'`: replace the offending node with the cycle-break
+ * sentinel (`{ type: 'object', additionalProperties: true }`). Right for
+ * schemas sourced from an upstream service the caller cannot edit.
+ * Each replacement invokes `onReplace` exactly once.
+ */
+ onUnresolved?: UnresolvedRefStrategy;
+ /**
+ * Callback invoked once per replaced node (only when `onUnresolved === 'sentinel'`).
+ * Lets callers emit one-shot warnings without losing the offending pointer.
+ */
+ onReplace?: (ref: string, reason: 'missing-target' | 'malformed-pointer') => void;
+}
+
+export function dereferenceJsonSchema<T = unknown>(
+ schema: T,
+ options?: DereferenceJsonSchemaOptions
+): T { /* … */ }
+```
+
+Implementation notes:
+
+- The walker already produces `CYCLE_BREAK_SENTINEL` on detected cycles
+ (`jsonSchema.ts:9, 98, 107, 127`). The lenient branch reuses **the same
+ sentinel constant** so cycles and dangling refs share semantics: "we can't
+ resolve this further; fall back to a permissive object".
+- `resolvePointer` currently throws via `failResolution`
+ (`jsonSchema.ts:19-24, 26-36`). Refactor: have `failResolution` return a
+ discriminator (`{ kind: 'unresolved', ref, reason }`) consumed by the walker,
+ so the lenient and strict branches share a single code path. Strict mode
+ throws at the boundary, lenient mode emits the sentinel + invokes
+ `onReplace`. Net change to strict-mode behavior: zero.
+- The chain-depth cap (`MAX_REF_CHAIN_DEPTH`) and node-depth cap
+ (`MAX_NODE_DEPTH`) keep throwing in **both** modes — those are safety caps,
+ not data-shape issues. Document this in the JSDoc.
+- External (`http://`, `https://`, `file://`) refs continue to be left as-is
+ with a single audit-log `logger.warn` per call (`jsonSchema.ts:113-118`).
+ Unchanged.
+- `$defs` / `definitions` continue to be stripped from the returned root
+ (`jsonSchema.ts:148-152`). Unchanged.
+
+### 2. `@composio/mastra` — opt into lenient mode with a per-tool warning
+
+`ts/packages/providers/mastra/src/index.ts`
+
+```typescript
+wrapTool(tool: Tool, executeTool: ExecuteToolFn): MastraTool {
+ // ...existing strict-mode branch for inputParameters...
+
+ // Output schemas come straight from the Composio API. The API can emit a
+ // `$ref: "#/$defs/..."` without declaring `$defs` (PLEN-2451) — strict
+ // mode would crash `tools.get` upfront. Fall back to the permissive
+ // object sentinel and emit a single warning so the degraded shape is
+ // observable in the agent's logs.
+ const onReplace = (ref: string) => this.warnDanglingRefOnce(tool.slug, ref);
+
+ const inputSchema = applyCompatLayer({
+ schema: dereferenceJsonSchema(parameters ?? {}, {
+ onUnresolved: 'sentinel',
+ onReplace,
+ }),
+ compatLayers: [],
+ mode: 'jsonSchema',
+ });
+
+ const outputSchema = applyCompatLayer({
+ schema: dereferenceJsonSchema(tool.outputParameters ?? {}, {
+ onUnresolved: 'sentinel',
+ onReplace,
+ }),
+ compatLayers: [],
+ mode: 'jsonSchema',
+ });
+
+ // ...createTool(...)...
+}
+```
+
+Add a small instance-scoped `Set<string>` (`warnedDanglingRefs`, keyed by
+`${slug}:${ref}`) so a Mastra agent that wraps the same tool many times only
+emits one warning per `(tool, ref)` pair. The warning message names the
+toolkit slug, tool slug, and the dangling pointer:
+
+```
+[composio/mastra] Tool GMAIL_FETCH_EMAILS (toolkit gmail) declares
+$ref #/$defs/FetchEmailsResponse but no matching $defs entry. Falling
+back to a permissive object schema for this branch — the wrapped
+Mastra tool will validate the response loosely. Tracked in
+https://linear.app/composio/issue/PLEN-2451.
+```
+
+Why warn (not silent fallback)?
+
+- **Why:** customers iterating on a Mastra agent need to know they got a
+ degraded schema; otherwise the failure mode becomes "agent validates loosely
+ and you never find out why a downstream typed consumer broke". The warning
+ also gives us a signal we can pipe into telemetry to prioritize the
+ API-side fix.
+- **How to apply:** rate-limit per `(slug, ref)` so noisy agents don't spam
+ the log; never emit at module-load (the warning has to point at a concrete
+ tool slug).
+
+### Why the fix stays inside `MastraProvider.wrapTool`
+
+It is tempting to dereference centrally — in
+`Tools.transformToolCases` (`Tools.ts:140`) or
+`Tools.applyDefaultSchemaModifiers` (`Tools.ts:192`). That would be wrong for
+three reasons:
+
+1. **No other provider needs this for output schemas.** Vercel
+ (`ts/packages/providers/vercel/src/index.ts:108-133`) only feeds
+ `inputParameters` to its Zod converter, and OpenAI/Anthropic/Google bind
+ tool *input* schemas to function-calling APIs that ignore output shapes.
+ `outputParameters` validation is a Mastra-specific surface.
+2. **Centralized dereferencing would mutate `tools.get()`'s public shape.**
+ Users today read raw `inputParameters` / `outputParameters` from
+ `tools.get` and `getRawComposioToolBySlug` and expect them to mirror the
+ API response (modulo case transformation in `transformToolCases`).
+ Inlining `$defs` for every caller — including ones whose consumers can
+ resolve `$ref` natively — is a silent behavior change for non-Mastra
+ users.
+3. **PLEN-2244 set the precedent.** Both fixes share the same boundary:
+ the provider that owns the validation contract is the provider that
+ pre-processes the schema. Keeping the new lenient path at the same
+ boundary preserves architectural consistency.
+
+## Acceptance Criteria
+
+### Code
+
+- [x] `dereferenceJsonSchema` accepts an optional second arg
+ `{ onUnresolved?: 'throw' | 'sentinel'; onReplace?: (ref, reason) => void }`.
+- [x] Default behavior (no opts) is byte-for-byte unchanged: still throws
+ `JsonSchemaRefResolutionError` on a dangling internal `$ref`.
+- [x] Lenient mode (`onUnresolved: 'sentinel'`) replaces the offending node
+ with the existing `CYCLE_BREAK_SENTINEL` and invokes `onReplace` exactly
+ once per replacement, passing the original ref pointer + reason.
+- [x] Lenient mode still throws on `MAX_REF_CHAIN_DEPTH` /
+ `MAX_NODE_DEPTH` breaches (safety caps are not lenient).
+- [x] `MastraProvider.wrapTool` calls `dereferenceJsonSchema(..., {
+ onUnresolved: 'sentinel', onReplace })` for both `inputParameters` and
+ `outputParameters`.
+- [x] `MastraProvider` warns once per `(toolSlug, refPointer)` pair via
+ `@composio/core`'s `logger.warn`.
+- [x] No public TypeScript API is *removed*; the new opts arg is purely additive.
+
+### Tests (red before fix; green after)
+
+- [x] New unit tests in `ts/packages/core/test/utils/jsonSchema.test.ts`
+ (9 new cases, all under `describe("with onUnresolved: 'sentinel' lenient mode")`):
+ sentinel replaces dangling ref; sentinel replaces missing-key ref;
+ `onReplace` invoked with ref + `'missing-target'`; `onReplace` invoked
+ with `'malformed-pointer'` for non-`#/` pointers; chain-depth cap still
+ throws; node-depth cap still throws; explicit `'throw'` matches default;
+ `onReplace` not called in strict mode; mixed schema preserves resolvable
+ branches while replacing only the dangling one.
+- [x] New regression test file
+ `ts/packages/providers/mastra/test/mastra-dangling-defs.test.ts`
+ (6 cases, un-mocked `@mastra/schema-compat`): no throw on dangling
+ output ref (GMAIL shape); defined outputSchema with no surviving `$ref`;
+ one warn per `(slug, ref)` pair across repeat wraps; separate warning
+ per slug; symmetric tolerance on input refs; resolvable `$defs` still
+ preserved.
+- [x] All existing tests still pass: core 908; mastra-ref 3; mastra.test 39;
+ every other provider/cli package green.
+
+### Changeset
+
+- [x] `.changeset/fix-mastra-dangling-defs-ref.md` added — `@composio/core`
+ and `@composio/mastra` both bumped patch; body describes the API
+ behavior, the new `onUnresolved`/`onReplace` opt, and the Mastra opt-in.
+ No Linear IDs (per repo convention — changesets ship to npm).
+
+### Manual verification
+
+- [ ] (Post-merge) Reproduce against the live API using the script from the
+ tracking issue: `tools.get(userId, { tools: ['GMAIL_FETCH_EMAILS'] })`
+ should return a `MastraTool` object whose `outputSchema` is defined.
+- [ ] Confirm the SDK logs exactly one warning per process per `(slug, ref)`
+ pair with the expected message.
+
+## Red-Green Test Strategy
+
+The TDD loop:
+
+1. **Red — write tests + the new error/option signature.** No production
+ implementation yet.
+ - Add the new `DereferenceJsonSchemaOptions` interface and export it.
+ - Type-only stub: `dereferenceJsonSchema` still accepts an unused second
+ arg (`_options?: DereferenceJsonSchemaOptions`).
+ - Add the four new `jsonSchema.test.ts` cases. They fail with
+ `JsonSchemaRefResolutionError` (current strict behavior) or compile
+ errors (if `onReplace` callback isn't exposed yet).
+ - Add the four new `mastra-dangling-defs.test.ts` cases. They fail with
+ `JsonSchemaRefResolutionError` propagated up from `wrapTool`.
+
+2. **Green — minimum implementation.**
+ - Plumb the `onUnresolved` strategy through `walk` / `resolvePointer` /
+ `stepInto`. Reuse `CYCLE_BREAK_SENTINEL`.
+ - Wire `onReplace` invocations at the two failure call sites
+ (`resolvePointer`'s missing target, `stepInto`'s non-object cursor).
+ - Add `warnDanglingRefOnce` to `MastraProvider`, invoke from the two
+ `wrapTool` call sites.
+
+3. **Refactor — tighten.**
+ - Verify no allocation in the strict path (the new branch must be a
+ zero-cost extension on the existing happy path).
+ - Run the full `jsonSchema.test.ts` + `mastra-ref.test.ts` +
+ `mastra-dangling-defs.test.ts` matrix to confirm no regressions.
+
+## Technical Considerations
+
+### Security
+
+- The sentinel (`{ type: 'object', additionalProperties: true }`) is the
+ most permissive valid object schema. A schema falling back to it means
+ Mastra's `validateToolOutput` will accept anything — *for that branch
+ only*. The siblings (e.g. `required`, `title`) at the parent level are
+ unaffected. This is strictly more permissive than `dereferenceJsonSchema`'s
+ current "throw and refuse to run" behavior, so it does not introduce a new
+ validation-bypass vector for trusted tool authors.
+- Prototype-pollution filter (`POLLUTING_KEYS` at `jsonSchema.ts:10`) and
+ `WeakSet` cycle tracking are unaffected.
+
+### Performance
+
+- Walker still visits each node at most once. The new branch is an extra
+ `if (strategy === 'sentinel') return CYCLE_BREAK_SENTINEL` after
+ `resolvePointer` throws or returns the "unresolved" discriminator. No new
+ allocations in the common (resolvable) path.
+
+### Compatibility
+
+- `DereferenceJsonSchemaOptions` is **additive**. Both the public
+ `dereferenceJsonSchema` export (consumed by `@composio/mastra`) and the
+ internal call sites can ignore the new parameter.
+- The `JsonSchemaRefResolutionError` class is unchanged. Callers that catch
+ it (none today outside the test suite) keep working.
+- The default mode is `'throw'`, matching the PLEN-2244 contract. Custom-tool
+ authors who deliberately point `$ref` at a non-existent `$defs` entry will
+ still get a hard error — that is the right behavior for *their* schemas.
+
+## Dependencies & Risks
+
+- **No dependency bumps.** Unlike PLEN-2244 (which bumped
+ `@mastra/schema-compat` to `^1.2.9`), this fix is internal to the SDK.
+- **Risk: developer surprise on raw schemas.** A reader of
+ `getRawComposioTools(...)` sees `$ref` in the raw schema and finds it
+ resolved to a sentinel in `wrapTool` output. Mitigation: the JSDoc on
+ `dereferenceJsonSchema` documents the lenient contract, and the warning
+ emitted by `MastraProvider` names the offending pointer.
+- **Risk: telemetry noise.** A user wrapping every Gmail tool in a wide
+ toolkit fetch could see many warnings on first run. Mitigation: per-tool
+ dedup in the Mastra provider; warning text points at the upstream Linear
+ ticket so callers know it is a known, tracked issue.
+
+## File-Level Plan
+
+```
+ts/packages/core/src/utils/jsonSchema.ts # add opts; reuse CYCLE_BREAK_SENTINEL
+ts/packages/core/test/utils/jsonSchema.test.ts # 4 new cases (red → green)
+ts/packages/core/src/index.ts # re-export DereferenceJsonSchemaOptions if needed
+ts/packages/providers/mastra/src/index.ts # opt into 'sentinel' + per-tool warn dedup
+ts/packages/providers/mastra/test/mastra-dangling-defs.test.ts # new file, 4 cases (red → green)
+.changeset/fix-mastra-dangling-defs-ref.md # patch/patch
+```
+
+Pseudocode for the touchpoints:
+
+### `ts/packages/core/src/utils/jsonSchema.ts`
+
+```typescript
+export type UnresolvedRefStrategy = 'throw' | 'sentinel';
+
+export interface DereferenceJsonSchemaOptions {
+ onUnresolved?: UnresolvedRefStrategy;
+ onReplace?: (ref: string, reason: 'missing-target' | 'malformed-pointer') => void;
+}
+
+const failResolution = (
+ pointer: string,
+ segment: string,
+ strategy: UnresolvedRefStrategy,
+ onReplace?: DereferenceJsonSchemaOptions['onReplace']
+): typeof CYCLE_BREAK_SENTINEL => {
+ if (strategy === 'sentinel') {
+ onReplace?.(pointer, 'malformed-pointer');
+ return { ...CYCLE_BREAK_SENTINEL };
+ }
+ throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
+ meta: { ref: pointer, failedAt: segment },
+ possibleFixes: REF_RESOLUTION_FIXES,
+ });
+};
+// `resolvePointer` and `stepInto` receive `strategy` + `onReplace` and forward to `failResolution`.
+// `walk` checks for the sentinel return shape and stops descending.
+```
+
+### `ts/packages/providers/mastra/src/index.ts`
+
+```typescript
+private warnedDanglingRefs = new Set<string>();
+
+private warnDanglingRefOnce(toolSlug: string, toolkitSlug: string, ref: string) {
+ const key = `${toolSlug}:${ref}`;
+ if (this.warnedDanglingRefs.has(key)) return;
+ this.warnedDanglingRefs.add(key);
+ logger.warn(
+ `[composio/mastra] Tool ${toolSlug} (toolkit ${toolkitSlug}) declares ` +
+ `$ref ${ref} but no matching $defs/definitions entry. Falling back to a ` +
+ `permissive object schema for this branch — the wrapped Mastra tool will ` +
+ `validate loosely. See https://linear.app/composio/issue/PLEN-2451.`
+ );
+}
+```
+
+## References & Research
+
+### Linear / GitHub
+
+- Linear ticket: PLEN-2451 — *MastraProvider $defs/$ref schema is dangling at the API source*.
+- Customer-facing GitHub issue: https://github.com/ComposioHQ/composio/issues/3307 (reported by `@0xpaperhead`, 2026-04-28).
+- Prior, related fix: PLEN-2244 (commits `5300bf8ba` red tests, `cc673b654` fix). Closed by `.changeset/fix-mastra-ref-dereference.md`.
+
+### Files
+
+- `ts/packages/providers/mastra/src/index.ts:80-126` — `MastraProvider.wrapTool` (the call site that needs to opt into lenient mode).
+- `ts/packages/core/src/utils/jsonSchema.ts:64-153` — `dereferenceJsonSchema` (the helper that needs the new opt).
+- `ts/packages/core/src/utils/jsonSchema.ts:9` — `CYCLE_BREAK_SENTINEL` (the sentinel to reuse).
+- `ts/packages/core/src/utils/jsonSchema.ts:19-36` — `failResolution` / `stepInto` (refactor target).
+- `ts/packages/core/src/errors/ValidationErrors.ts:89-99` — `JsonSchemaRefResolutionError` (unchanged).
+- `ts/packages/core/test/utils/jsonSchema.test.ts:150-158` — existing strict-mode test (the contract we keep as default).
+- `ts/packages/providers/mastra/test/mastra-ref.test.ts` — pattern to mirror for the new test file.
+- `ts/packages/providers/vercel/src/index.ts:108-133` — confirms `outputParameters` is Mastra-only.
+- `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`).
+- `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.
+
+### External
+
+- JSON Pointer (RFC 6901) — escape semantics already handled correctly at `jsonSchema.ts:16-17`.
+- JSON Schema 2020-12 — sibling-keyword merge semantics already handled correctly at `jsonSchema.ts:133-141`.
+- `@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).
diff --git a/ts/packages/core/src/index.ts b/ts/packages/core/src/index.ts
index eaae17224..7d828eb36 100644
--- a/ts/packages/core/src/index.ts
+++ b/ts/packages/core/src/index.ts
@@ -9,6 +9,11 @@ export {
jsonSchemaToZodSchema,
removeNonRequiredProperties,
} from './utils/jsonSchema';
+export type {
+ DereferenceJsonSchemaOptions,
+ UnresolvedRefReason,
+ UnresolvedRefStrategy,
+} from './utils/jsonSchema';
export { getExtensionFromMimeType } from './utils/mime';
export { AuthScheme } from './models/AuthScheme';
export { MCP } from './models/MCP';
@@ -33,6 +38,7 @@ export * from './types/ToolRouterSessionFilesMount.types';
export * as constants from './utils/constants';
export { default as logger } from './utils/logger';
+export { telemetry } from './telemetry/Telemetry';
// Experimental custom tools — exported with experimental_ prefix for top-level import
export { createCustomTool as experimental_createTool } from './models/CustomTool';
diff --git a/ts/packages/core/src/utils/jsonSchema.ts b/ts/packages/core/src/utils/jsonSchema.ts
index 046cd4077..07eda84fb 100644
--- a/ts/packages/core/src/utils/jsonSchema.ts
+++ b/ts/packages/core/src/utils/jsonSchema.ts
@@ -7,6 +7,57 @@ import { isPlainObject } from './modifiers/FileToolModifier.utils.neutral';
const MAX_REF_CHAIN_DEPTH = 100;
const MAX_NODE_DEPTH = 512;
const CYCLE_BREAK_SENTINEL = { type: 'object', additionalProperties: true } as const;
+
+/**
+ * In-band hint attached to the cycle-break sentinel when lenient mode
+ * substitutes it for a dangling `$ref`. Makes the degradation visible to
+ * LLMs that read the wrapped tool's schema — without it the LLM sees a
+ * useless permissive object and no prose context. Wording is intentionally
+ * context-neutral ("Schema shape", not "Output shape") because the helper
+ * is used for both `inputParameters` and `outputParameters`. Overridden
+ * when the caller's `$ref` node carries its own `description` sibling
+ * (Draft 2020-12 sibling-keyword semantics).
+ */
+const UNRESOLVED_REF_DESCRIPTION =
+ 'Schema shape unresolved at the source — validate loosely. ' +
+ 'See https://github.com/ComposioHQ/composio/issues/3307.';
+
+/**
+ * Strategy for `dereferenceJsonSchema` when an internal `$ref` cannot be
+ * resolved (target missing under `$defs`/`definitions`, or a malformed
+ * pointer beneath the internal `#/` prefix).
+ *
+ * - `'throw'` (default): throw `JsonSchemaRefResolutionError`. Right for
+ * first-party / custom-tool schemas where a dangling `$ref` is a developer
+ * bug worth surfacing.
+ * - `'sentinel'`: replace the offending node with the cycle-break sentinel
+ * (`{ type: 'object', additionalProperties: true }`). Right for schemas
+ * sourced from an upstream service the caller cannot edit (e.g. an
+ * API-provided tool definition that emits `$ref` without a `$defs`
+ * block — see https://github.com/ComposioHQ/composio/issues/3307).
+ *
+ * Safety caps (`MAX_REF_CHAIN_DEPTH`, `MAX_NODE_DEPTH`) still throw in both
+ * modes; cycle handling (already permissive via `CYCLE_BREAK_SENTINEL`) is
+ * unaffected.
+ */
+export type UnresolvedRefStrategy = 'throw' | 'sentinel';
+
+/**
+ * Reason a `$ref` was replaced with the sentinel in `'sentinel'` mode.
+ * `onReplace` callbacks receive this so callers can attribute the
+ * fallback (e.g., warn at the offending tool slug).
+ */
+export type UnresolvedRefReason = 'missing-target' | 'malformed-pointer';
+
+export interface DereferenceJsonSchemaOptions {
+ onUnresolved?: UnresolvedRefStrategy;
+ /**
+ * Invoked once per replaced node in `'sentinel'` mode. The ref is the
+ * original pointer string from the schema; reason distinguishes a
+ * missing `$defs` target from a malformed pointer.
+ */
+ onReplace?: (ref: string, reason: UnresolvedRefReason) => void;
+}
const POLLUTING_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
const REF_RESOLUTION_FIXES = [
'Ensure the $ref pointer matches a path in $defs or definitions',
@@ -16,38 +67,65 @@ const REF_RESOLUTION_FIXES = [
const decodePointerSegment = (segment: string): string =>
segment.replace(/~1/g, '/').replace(/~0/g, '~');
-const failResolution = (pointer: string, segment: string): never => {
- throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
- meta: { ref: pointer, failedAt: segment },
- possibleFixes: REF_RESOLUTION_FIXES,
- });
-};
+/**
+ * Tagged result of attempting to resolve a `$ref`. `failedAt` is populated
+ * only for the segment-walk path so strict-mode error meta stays identical
+ * to the pre-lenient-mode shape.
+ */
+type ResolutionResult =
+ | { kind: 'ok'; value: unknown }
+ | { kind: 'unresolved'; reason: UnresolvedRefReason; failedAt?: string };
-const stepInto = (cursor: unknown, segment: string, pointer: string): unknown => {
- if (cursor === null || typeof cursor !== 'object') failResolution(pointer, segment);
+const tryStep = (cursor: unknown, segment: string): ResolutionResult => {
+ if (cursor === null || typeof cursor !== 'object') {
+ return { kind: 'unresolved', reason: 'missing-target', failedAt: segment };
+ }
if (Array.isArray(cursor)) {
const i = Number(segment);
- if (!Number.isInteger(i) || i < 0 || i >= cursor.length) failResolution(pointer, segment);
- return cursor[i];
+ if (!Number.isInteger(i) || i < 0 || i >= cursor.length) {
+ return { kind: 'unresolved', reason: 'missing-target', failedAt: segment };
+ }
+ return { kind: 'ok', value: cursor[i] };
}
const obj = cursor as Record<string, unknown>;
- if (!Object.prototype.hasOwnProperty.call(obj, segment)) failResolution(pointer, segment);
- return obj[segment];
+ if (!Object.prototype.hasOwnProperty.call(obj, segment)) {
+ return { kind: 'unresolved', reason: 'missing-target', failedAt: segment };
+ }
+ return { kind: 'ok', value: obj[segment] };
};
-const resolvePointer = (root: Record<string, unknown>, pointer: string): unknown => {
- if (pointer === '#' || pointer === '') return root;
+const tryResolvePointer = (root: Record<string, unknown>, pointer: string): ResolutionResult => {
+ if (pointer === '#' || pointer === '') return { kind: 'ok', value: root };
if (!pointer.startsWith('#/')) {
+ return { kind: 'unresolved', reason: 'malformed-pointer' };
+ }
+ const segments = pointer.slice(2).split('/').map(decodePointerSegment);
+ let cursor: unknown = root;
+ for (const seg of segments) {
+ const step = tryStep(cursor, seg);
+ if (step.kind === 'unresolved') return step;
+ cursor = step.value;
+ }
+ return { kind: 'ok', value: cursor };
+};
+
+const throwResolutionError = (
+ pointer: string,
+ result: Extract<ResolutionResult, { kind: 'unresolved' }>
+): never => {
+ if (result.reason === 'malformed-pointer') {
throw new JsonSchemaRefResolutionError(`Unsupported $ref pointer: ${pointer}`, {
meta: { ref: pointer },
possibleFixes: REF_RESOLUTION_FIXES,
});
}
- return pointer
- .slice(2)
- .split('/')
- .map(decodePointerSegment)
- .reduce<unknown>((cursor, seg) => stepInto(cursor, seg, pointer), root);
+ throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
+ meta: {
+ ref: pointer,
+ ...(result.failedAt !== undefined ? { failedAt: result.failedAt } : {}),
+ },
+ possibleFixes: REF_RESOLUTION_FIXES,
+ });
};
/**
@@ -58,12 +136,25 @@ const resolvePointer = (root: Record<string, unknown>, pointer: string): unknown
* left untouched. Cycles are broken with `{ type: 'object',
* additionalProperties: true }`. The input is never mutated.
*
+ * By default, unresolved internal refs throw `JsonSchemaRefResolutionError`.
+ * Pass `{ onUnresolved: 'sentinel' }` to replace the offending node with the
+ * cycle-break sentinel instead — appropriate for schemas sourced from an
+ * upstream service the caller cannot edit (the Composio API ships some
+ * `outputParameters` with a `$ref` into `#/$defs/...` but never declares
+ * `$defs`; see https://github.com/ComposioHQ/composio/issues/3307).
+ *
* @throws {JsonSchemaRefResolutionError} on malformed pointers, missing
- * targets, or chains past the depth cap.
+ * targets (strict mode only), or chains past the depth cap (both modes).
*/
-export function dereferenceJsonSchema<T = unknown>(schema: T): T {
+export function dereferenceJsonSchema<T = unknown>(
+ schema: T,
+ options?: DereferenceJsonSchemaOptions
+): T {
if (!isPlainObject(schema)) return schema;
+ const strategy: UnresolvedRefStrategy = options?.onUnresolved ?? 'throw';
+ const onReplace = options?.onReplace;
+
const root = schema as Record<string, unknown>;
const visiting = new WeakSet<object>();
@@ -126,7 +217,22 @@ export function dereferenceJsonSchema<T = unknown>(schema: T): T {
}
if (visitedRefs.has(ref)) return { ...CYCLE_BREAK_SENTINEL };
- const target = resolvePointer(root, ref);
+ const result = tryResolvePointer(root, ref);
+ let target: unknown;
+ if (result.kind === 'ok') {
+ target = result.value;
+ } else if (strategy === 'sentinel') {
+ // Lenient mode: replace the unresolved branch with the same
+ // permissive sentinel used for cycles, and notify the caller so
+ // they can emit a one-shot warn at the offending tool surface.
+ // The injected `description` gives the LLM an in-band signal that
+ // the branch is opaque; sibling-merge below will overwrite it with
+ // a caller-provided description if the original node has one.
+ onReplace?.(ref, result.reason);
+ target = { ...CYCLE_BREAK_SENTINEL, description: UNRESOLVED_REF_DESCRIPTION };
+ } else {
+ throwResolutionError(ref, result);
+ }
const nextRefs = new Set(visitedRefs).add(ref);
const resolved = walk(target, nextRefs, chainDepth + 1, nodeDepth + 1);
diff --git a/ts/packages/core/test/utils/jsonSchema.test.ts b/ts/packages/core/test/utils/jsonSchema.test.ts
index 3fce3d79d..20d0d8689 100644
--- a/ts/packages/core/test/utils/jsonSchema.test.ts
+++ b/ts/packages/core/test/utils/jsonSchema.test.ts
@@ -279,4 +279,208 @@ describe('dereferenceJsonSchema', () => {
expect((out as { properties: { v: { type: string } } }).properties.v.type).toBe('string');
});
+
+ describe("with onUnresolved: 'sentinel' lenient mode", () => {
+ // Sentinel injected for an unresolvable $ref carries an LLM-visible hint
+ // describing the degradation. The hint is overwritten by a caller-provided
+ // `description` sibling when present (Draft 2020-12 sibling-keyword merge).
+ const PERMISSIVE = {
+ type: 'object',
+ additionalProperties: true,
+ description: expect.stringContaining('Schema shape unresolved at the source'),
+ };
+
+ it('replaces a dangling internal $ref (no $defs block at all) with the cycle-break sentinel', () => {
+ // Mirrors GMAIL_FETCH_EMAILS.outputParameters: a $ref into #/$defs/...
+ // without any $defs declared on the root.
+ const out = dereferenceJsonSchema(
+ {
+ type: 'object',
+ properties: {
+ data: { $ref: '#/$defs/FetchEmailsResponse' },
+ error: { type: 'string' },
+ successful: { type: 'boolean' },
+ },
+ required: ['data', 'successful'],
+ title: 'FetchEmailsResponseWrapper',
+ },
+ { onUnresolved: 'sentinel' }
+ ) as {
+ type: string;
+ properties: { data: unknown; error: unknown; successful: unknown };
+ required: string[];
+ };
+
+ expect(out.properties.data).toEqual(PERMISSIVE);
+ // Siblings of the replaced node are untouched.
+ expect(out.properties.error).toEqual({ type: 'string' });
+ expect(out.properties.successful).toEqual({ type: 'boolean' });
+ expect(out.required).toEqual(['data', 'successful']);
+ expect(containsRef(out)).toBe(false);
+ });
+
+ it('replaces a $ref that points into an empty $defs (missing key) with the sentinel', () => {
+ const out = dereferenceJsonSchema(
+ {
+ type: 'object',
+ properties: { v: { $ref: '#/$defs/Missing' } },
+ $defs: {},
+ },
+ { onUnresolved: 'sentinel' }
+ ) as { properties: { v: unknown } };
+
+ expect(out.properties.v).toEqual(PERMISSIVE);
+ expect(containsRef(out)).toBe(false);
+ });
+
+ it("invokes onReplace once per replacement with the original ref and reason 'missing-target'", () => {
+ const calls: Array<[string, string]> = [];
+ dereferenceJsonSchema(
+ {
+ type: 'object',
+ properties: {
+ a: { $ref: '#/$defs/Missing' },
+ b: { $ref: '#/$defs/Missing' },
+ c: { $ref: '#/$defs/AlsoMissing' },
+ },
+ },
+ {
+ onUnresolved: 'sentinel',
+ onReplace: (ref, reason) => calls.push([ref, reason]),
+ }
+ );
+
+ expect(calls).toEqual([
+ ['#/$defs/Missing', 'missing-target'],
+ ['#/$defs/Missing', 'missing-target'],
+ ['#/$defs/AlsoMissing', 'missing-target'],
+ ]);
+ });
+
+ it("invokes onReplace with reason 'malformed-pointer' for a non '/' internal pointer", () => {
+ const calls: Array<[string, string]> = [];
+ const out = dereferenceJsonSchema(
+ {
+ type: 'object',
+ properties: { v: { $ref: '#bar' } },
+ },
+ {
+ onUnresolved: 'sentinel',
+ onReplace: (ref, reason) => calls.push([ref, reason]),
+ }
+ ) as { properties: { v: unknown } };
+
+ expect(calls).toEqual([['#bar', 'malformed-pointer']]);
+ expect(out.properties.v).toEqual(PERMISSIVE);
+ });
+
+ it('still throws JsonSchemaRefResolutionError when chain depth exceeds the cap (safety cap is not lenient)', () => {
+ const $defs: Record<string, unknown> = {};
+ for (let i = 0; i < 200; i++) {
+ $defs[`A${i}`] = { $ref: i + 1 < 200 ? `#/$defs/A${i + 1}` : '#/$defs/A0' };
+ }
+ expect(() =>
+ dereferenceJsonSchema(
+ {
+ type: 'object',
+ properties: { v: { $ref: '#/$defs/A0' } },
+ $defs,
+ },
+ { onUnresolved: 'sentinel' }
+ )
+ ).toThrow(JsonSchemaRefResolutionError);
+ });
+
+ it('still throws JsonSchemaRefResolutionError when node depth exceeds the cap (safety cap is not lenient)', () => {
+ type Nested = { type: 'object'; properties: { x: Nested | { type: 'string' } } };
+ let leaf: Nested | { type: 'string' } = { type: 'string' };
+ for (let i = 0; i < 1000; i++) {
+ leaf = { type: 'object', properties: { x: leaf } } as Nested;
+ }
+ expect(() => dereferenceJsonSchema(leaf, { onUnresolved: 'sentinel' })).toThrow(
+ JsonSchemaRefResolutionError
+ );
+ });
+
+ it("explicit onUnresolved: 'throw' matches default behavior", () => {
+ expect(() =>
+ dereferenceJsonSchema(
+ {
+ type: 'object',
+ properties: { v: { $ref: '#/$defs/Missing' } },
+ $defs: {},
+ },
+ { onUnresolved: 'throw' }
+ )
+ ).toThrow(JsonSchemaRefResolutionError);
+ });
+
+ it('does not call onReplace in strict mode (regression guard)', () => {
+ const onReplace = vi.fn();
+ expect(() =>
+ dereferenceJsonSchema(
+ {
+ type: 'object',
+ properties: { v: { $ref: '#/$defs/Missing' } },
+ $defs: {},
+ },
+ { onUnresolved: 'throw', onReplace }
+ )
+ ).toThrow(JsonSchemaRefResolutionError);
+ expect(onReplace).not.toHaveBeenCalled();
+ });
+
+ it("injects a default LLM-visible 'description' on the sentinel when the source $ref node has none", () => {
+ const out = dereferenceJsonSchema(
+ {
+ type: 'object',
+ properties: { v: { $ref: '#/$defs/Missing' } },
+ },
+ { onUnresolved: 'sentinel' }
+ ) as { properties: { v: { description: string } } };
+
+ expect(out.properties.v.description).toMatch(/Schema shape unresolved at the source/);
+ expect(out.properties.v.description).toContain(
+ 'https://github.com/ComposioHQ/composio/issues/3307'
+ );
+ });
+
+ it("preserves a caller-provided 'description' sibling instead of overwriting with the default", () => {
+ const out = dereferenceJsonSchema(
+ {
+ type: 'object',
+ properties: {
+ v: {
+ $ref: '#/$defs/Missing',
+ description: 'caller-supplied prose context',
+ },
+ },
+ },
+ { onUnresolved: 'sentinel' }
+ ) as { properties: { v: { description: string; type: string } } };
+
+ // Sibling-merge wins over the default — caller context survives.
+ expect(out.properties.v.description).toBe('caller-supplied prose context');
+ expect(out.properties.v.type).toBe('object');
+ });
+
+ it('preserves resolvable $defs while replacing only the dangling branch (mixed schema)', () => {
+ const out = dereferenceJsonSchema(
+ {
+ type: 'object',
+ properties: {
+ resolved: { $ref: '#/$defs/Real' },
+ dangling: { $ref: '#/$defs/Ghost' },
+ },
+ $defs: {
+ Real: { type: 'integer' },
+ },
+ },
+ { onUnresolved: 'sentinel' }
+ ) as { properties: { resolved: { type: string }; dangling: unknown } };
+
+ expect(out.properties.resolved).toEqual({ type: 'integer' });
+ expect(out.properties.dangling).toEqual(PERMISSIVE);
+ });
+ });
});
diff --git a/ts/packages/providers/mastra/src/index.ts b/ts/packages/providers/mastra/src/index.ts
index b3cc3d192..1404d05a2 100644
--- a/ts/packages/providers/mastra/src/index.ts
+++ b/ts/packages/providers/mastra/src/index.ts
@@ -12,7 +12,10 @@ import {
ExecuteToolFn,
McpUrlResponse,
dereferenceJsonSchema,
+ logger,
removeNonRequiredProperties,
+ telemetry,
+ type UnresolvedRefReason,
} from '@composio/core';
import { applyCompatLayer } from '@mastra/schema-compat';
import { createTool } from '@mastra/core/tools';
@@ -34,6 +37,10 @@ export class MastraProvider extends BaseAgenticProvider<
> {
readonly name = 'mastra';
private strict: boolean | null;
+ // Tracks the (toolSlug, ref) pairs we've already warned about, so wrapping
+ // the same tool many times during a single SDK session does not flood the
+ // logs. Reset is only via constructing a new provider.
+ private warnedDanglingRefs = new Set<string>();
/**
* Creates a new instance of the MastraProvider.
@@ -95,16 +102,33 @@ export class MastraProvider extends BaseAgenticProvider<
// @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.
+ // anyOf — losing the type info from $defs. See
+ // https://github.com/mastra-ai/mastra/issues/15341.
+ //
+ // Some Composio-API-supplied tools emit a `$ref` into `#/$defs/...`
+ // without ever declaring `$defs` (e.g. `GMAIL_FETCH_EMAILS`). Strict
+ // dereferencing throws on this, which crashes `tools.get` upfront. Opt
+ // into `'sentinel'` so the dangling branch becomes a permissive object
+ // schema instead, and emit a single warn per (toolSlug, ref) pair so the
+ // degraded shape is observable. See
+ // https://github.com/ComposioHQ/composio/issues/3307.
+ const onReplace = (ref: string, reason: UnresolvedRefReason) =>
+ this.warnDanglingRefOnce(tool, ref, reason);
+
const inputSchema = applyCompatLayer({
- schema: dereferenceJsonSchema(parameters ?? {}),
+ schema: dereferenceJsonSchema(parameters ?? {}, {
+ onUnresolved: 'sentinel',
+ onReplace,
+ }),
compatLayers: [],
mode: 'jsonSchema',
});
const outputSchema = applyCompatLayer({
- schema: dereferenceJsonSchema(tool.outputParameters ?? {}),
+ schema: dereferenceJsonSchema(tool.outputParameters ?? {}, {
+ onUnresolved: 'sentinel',
+ onReplace,
+ }),
compatLayers: [],
mode: 'jsonSchema',
});
@@ -131,4 +155,34 @@ export class MastraProvider extends BaseAgenticProvider<
return acc;
}, {} as MastraToolCollection);
}
+
+ private warnDanglingRefOnce(tool: Tool, ref: string, reason: UnresolvedRefReason): void {
+ const key = `${tool.slug}::${ref}`;
+ if (this.warnedDanglingRefs.has(key)) return;
+ this.warnedDanglingRefs.add(key);
+ const toolkitSlug = tool.toolkit?.slug ?? 'unknown';
+ // `tool.slug`, `toolkitSlug`, and `ref` originate from the upstream API
+ // schema. Quoting via `JSON.stringify` neutralizes embedded newlines /
+ // ANSI escape sequences / control bytes that would otherwise forge log
+ // lines or corrupt terminals (CWE-117).
+ logger.warn(
+ `[composio/mastra] Tool ${JSON.stringify(tool.slug)} ` +
+ `(toolkit ${JSON.stringify(toolkitSlug)}) declares ` +
+ `$ref ${JSON.stringify(ref)} but no matching $defs/definitions entry ` +
+ `(${reason}). Falling back to a permissive object schema for this ` +
+ `branch — the wrapped Mastra tool will validate this property loosely. ` +
+ `Tracked in https://github.com/ComposioHQ/composio/issues/3307.`
+ );
+ // Fire-and-forget aggregate signal so the Composio team can prioritize the
+ // upstream API fix from real data. `telemetry.sendMetric` short-circuits
+ // when `COMPOSIO_DISABLE_TELEMETRY=true` and swallows network errors.
+ void telemetry.sendMetric([
+ {
+ functionName: 'composio.mastra.wrapTool.danglingRef',
+ timestamp: Date.now() / 1000,
+ props: { toolSlug: tool.slug, toolkitSlug, ref, reason },
+ metadata: { provider: 'mastra' },
+ },
+ ]);
+ }
}
diff --git a/ts/packages/providers/mastra/test/mastra-dangling-defs.test.ts b/ts/packages/providers/mastra/test/mastra-dangling-defs.test.ts
new file mode 100644
index 000000000..8bcfbb2dc
--- /dev/null
+++ b/ts/packages/providers/mastra/test/mastra-dangling-defs.test.ts
@@ -0,0 +1,257 @@
+/**
+ * Regression test for https://github.com/ComposioHQ/composio/issues/3307 —
+ * the Composio API ships some `outputParameters` with a `$ref` into
+ * `#/$defs/...` while never declaring `$defs` (e.g., `GMAIL_FETCH_EMAILS`).
+ * The strict `dereferenceJsonSchema` throws on this, which cascades through
+ * `MastraProvider.wrapTool` and crashes `tools.get` upfront.
+ *
+ * `MastraProvider` opts the dereferencer into `onUnresolved: 'sentinel'`,
+ * replacing dangling internal refs with the cycle-break sentinel
+ * (`{ type: 'object', additionalProperties: true }`) and emitting one
+ * `logger.warn` per `(toolSlug, ref)` pair.
+ *
+ * Like `mastra-ref.test.ts`, this file deliberately does NOT mock
+ * `@mastra/schema-compat` — Vitest mock scoping is per-file, so the mock in
+ * `mastra.test.ts` does not leak here, and the test exercises the real
+ * AJV-backed compat layer.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+ logger,
+ telemetry,
+ type ExecuteToolFn,
+ type Tool,
+ type ToolExecuteResponse,
+} from '@composio/core';
+import { MastraProvider } from '../src';
+
+// The fixtures below deliberately build `Tool`-shaped objects whose
+// `inputParameters` / `outputParameters` carry `$ref` properties — a shape
+// `ParametersSchema` admits via `JSONSchemaPropertySchema` but that does not
+// satisfy the parent record type at the literal level. `makeTool` localizes
+// the cast so individual fixtures stay readable.
+type TestSchema = Record<string, unknown>;
+type TestToolOverrides = Partial<Omit<Tool, 'inputParameters' | 'outputParameters'>> & {
+ inputParameters?: TestSchema;
+ outputParameters?: TestSchema;
+};
+
+const makeTool = (overrides: TestToolOverrides): Tool =>
+ ({
+ slug: 'TEST_TOOL',
+ name: 'Test Tool',
+ description: '',
+ toolkit: { slug: 'test', name: 'Test' },
+ version: '20260510_00',
+ availableVersions: ['20260510_00'],
+ tags: [],
+ inputParameters: {
+ type: 'object',
+ properties: {},
+ },
+ outputParameters: {
+ type: 'object',
+ properties: {},
+ },
+ ...overrides,
+ }) as unknown as Tool;
+
+// Exact shape of `GMAIL_FETCH_EMAILS.outputParameters` from
+// https://github.com/ComposioHQ/composio/issues/3307: a `$ref` into
+// `#/$defs/...` with no `$defs` block declared anywhere.
+const danglingOutputTool = makeTool({
+ slug: 'DANGLING_OUTPUT_TOOL',
+ name: 'Dangling Output Tool',
+ description: 'Tool whose outputParameters carries a dangling $ref',
+ toolkit: { slug: 'dangling', name: 'Dangling Toolkit' },
+ inputParameters: {
+ type: 'object',
+ properties: { query: { type: 'string' } },
+ required: ['query'],
+ },
+ outputParameters: {
+ type: 'object',
+ properties: {
+ data: {
+ description: 'Data from the action execution',
+ title: 'Data',
+ $ref: '#/$defs/FetchEmailsResponse',
+ },
+ error: { type: 'string', description: 'Error if the action failed', title: 'Error' },
+ successful: {
+ type: 'boolean',
+ description: 'Whether the action was successful',
+ title: 'Successful',
+ },
+ },
+ required: ['data', 'successful'],
+ title: 'FetchEmailsResponseWrapper',
+ },
+});
+
+const danglingInputTool = makeTool({
+ slug: 'DANGLING_INPUT_TOOL',
+ name: 'Dangling Input Tool',
+ toolkit: { slug: 'dangling', name: 'Dangling Toolkit' },
+ inputParameters: {
+ type: 'object',
+ properties: { filter: { $ref: '#/$defs/UnknownFilter' } },
+ required: ['filter'],
+ },
+ outputParameters: { type: 'object', properties: { ok: { type: 'boolean' } } },
+});
+
+const resolvableRefTool = makeTool({
+ slug: 'RESOLVABLE_REF_TOOL',
+ name: 'Resolvable Ref Tool',
+ inputParameters: {
+ type: 'object',
+ properties: { user: { $ref: '#/$defs/User' } },
+ required: ['user'],
+ $defs: {
+ User: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+ },
+ },
+ outputParameters: { type: 'object', properties: { ok: { type: 'boolean' } } },
+});
+
+describe('MastraProvider: dangling $ref tolerance', () => {
+ let provider: MastraProvider;
+ let warnSpy: ReturnType<typeof vi.spyOn>;
+ let telemetrySpy: ReturnType<typeof vi.spyOn>;
+ let exec: ExecuteToolFn;
+
+ beforeEach(() => {
+ provider = new MastraProvider();
+ const mockExec = vi.fn<Parameters<ExecuteToolFn>, ReturnType<ExecuteToolFn>>(
+ async () => ({ data: {}, error: null, successful: true }) as unknown as ToolExecuteResponse
+ );
+ exec = mockExec;
+ provider._setExecuteToolFn(exec);
+ warnSpy = vi.spyOn(logger, 'warn').mockImplementation(() => {});
+ telemetrySpy = vi.spyOn(telemetry, 'sendMetric').mockResolvedValue(undefined);
+ });
+
+ it('does not throw when outputParameters has a $ref with no $defs declared (GMAIL_FETCH_EMAILS shape)', () => {
+ expect(() => provider.wrapTool(danglingOutputTool, exec)).not.toThrow();
+ });
+
+ it('produces a defined outputSchema with the dangling branch replaced by a permissive object', () => {
+ const wrapped = provider.wrapTool(danglingOutputTool, exec) as {
+ outputSchema: unknown;
+ };
+ expect(wrapped.outputSchema).toBeDefined();
+ // The wrapped schema went through applyCompatLayer (JSON Schema → Zod →
+ // JSON Schema). All we can guarantee at this level is no surviving
+ // $ref string anywhere in the structure.
+ expect(JSON.stringify(wrapped.outputSchema)).not.toContain('$ref');
+ });
+
+ it('emits exactly one logger.warn per (toolSlug, ref) pair, even when the same tool is wrapped multiple times', () => {
+ provider.wrapTool(danglingOutputTool, exec);
+ provider.wrapTool(danglingOutputTool, exec);
+ provider.wrapTool(danglingOutputTool, exec);
+
+ const calls = warnSpy.mock.calls.filter(
+ ([msg]) => typeof msg === 'string' && msg.includes('#/$defs/FetchEmailsResponse')
+ );
+ expect(calls).toHaveLength(1);
+ const message = calls[0][0] as string;
+ // User-controlled segments are JSON.stringified — they appear quoted in
+ // the warn output (CWE-117 mitigation; see warnDanglingRefOnce).
+ expect(message).toContain('"DANGLING_OUTPUT_TOOL"');
+ expect(message).toContain('"dangling"');
+ expect(message).toContain('"#/$defs/FetchEmailsResponse"');
+ expect(message).toContain('github.com/ComposioHQ/composio/issues/3307');
+ });
+
+ it('emits a separate warning for a different tool slug carrying the same ref', () => {
+ const sameRefDifferentSlug = makeTool({
+ ...danglingOutputTool,
+ slug: 'OTHER_DANGLING_OUTPUT_TOOL',
+ });
+ provider.wrapTool(danglingOutputTool, exec);
+ provider.wrapTool(sameRefDifferentSlug, exec);
+
+ const calls = warnSpy.mock.calls.filter(
+ ([msg]) => typeof msg === 'string' && msg.includes('#/$defs/FetchEmailsResponse')
+ );
+ expect(calls).toHaveLength(2);
+ });
+
+ it('tolerates a dangling $ref on inputParameters (symmetric with output)', () => {
+ expect(() => provider.wrapTool(danglingInputTool, exec)).not.toThrow();
+ const calls = warnSpy.mock.calls.filter(
+ ([msg]) => typeof msg === 'string' && msg.includes('#/$defs/UnknownFilter')
+ );
+ expect(calls).toHaveLength(1);
+ });
+
+ it('sanitizes control bytes / newlines / ANSI escapes in the warning (CWE-117 regression)', () => {
+ // An upstream-shaped tool whose $ref carries a newline + ANSI CSI sequence.
+ // Without JSON.stringify on the interpolated segments, these bytes would
+ // be written verbatim to stderr, forging a fake log line.
+ const malicious = makeTool({
+ slug: 'MALICIOUS_TOOL',
+ outputParameters: {
+ type: 'object',
+ properties: { data: { $ref: '#/$defs/Foo\n\x1b[31mFAKE LOG LINE\x1b[0m' } },
+ },
+ });
+ provider.wrapTool(malicious, exec);
+ const calls = warnSpy.mock.calls.filter(
+ ([msg]) => typeof msg === 'string' && msg.includes('MALICIOUS_TOOL')
+ );
+ expect(calls).toHaveLength(1);
+ const message = calls[0][0] as string;
+ // Raw newline / escape bytes must NOT survive into the warning string.
+ expect(message).not.toMatch(/[\x00-\x09\x0b-\x1f]/);
+ // Escapes appear in their JSON-encoded form instead.
+ expect(message).toContain('\\n');
+ expect(message).toContain('\\u001b');
+ });
+
+ it('fires one telemetry event per (toolSlug, ref) pair next to the warn', () => {
+ provider.wrapTool(danglingOutputTool, exec);
+ provider.wrapTool(danglingOutputTool, exec); // dedup: still 1 event
+
+ const calls = telemetrySpy.mock.calls.filter(([payload]) => {
+ const events = payload as Array<{ functionName: string; props?: Record<string, unknown> }>;
+ return events.some(e => e.functionName === 'composio.mastra.wrapTool.danglingRef');
+ });
+ expect(calls).toHaveLength(1);
+
+ const event = (calls[0][0] as Array<Record<string, unknown>>)[0];
+ expect(event.functionName).toBe('composio.mastra.wrapTool.danglingRef');
+ expect(event.props).toMatchObject({
+ toolSlug: 'DANGLING_OUTPUT_TOOL',
+ toolkitSlug: 'dangling',
+ ref: '#/$defs/FetchEmailsResponse',
+ reason: 'missing-target',
+ });
+ expect(event.metadata).toEqual({ provider: 'mastra' });
+ });
+
+ it('does NOT fire telemetry for tools whose $refs all resolve', () => {
+ provider.wrapTool(resolvableRefTool, exec);
+ const calls = telemetrySpy.mock.calls.filter(([payload]) => {
+ const events = payload as Array<{ functionName: string }>;
+ return events.some(e => e.functionName === 'composio.mastra.wrapTool.danglingRef');
+ });
+ expect(calls).toHaveLength(0);
+ });
+
+ it('preserves resolvable $defs (regression guard — no degraded permissive anyOf)', () => {
+ const wrapped = provider.wrapTool(resolvableRefTool, exec) as { inputSchema: unknown };
+ // Resolvable $ref should produce a real schema with the User shape inlined.
+ const inputJson = JSON.stringify(wrapped.inputSchema);
+ expect(inputJson).toContain('id');
+ expect(inputJson).not.toContain('$ref');
+ // No warning should be emitted for resolvable refs.
+ const calls = warnSpy.mock.calls.filter(
+ ([msg]) => typeof msg === 'string' && msg.includes('$ref')
+ );
+ expect(calls).toHaveLength(0);
+ });
+});