Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
fix(mastra): 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.tsindex 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 importexport { createCustomTool as experimental_createTool } from './models/CustomTool';diff --git a/ts/packages/core/src/utils/jsonSchema.ts b/ts/packages/core/src/utils/jsonSchema.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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);+ });+});