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
docs(core): trim verbose JSDoc and consolidate mastra-ref test setup
jkomyno90680d796586
diff --git a/ts/packages/core/src/utils/jsonSchema.ts b/ts/packages/core/src/utils/jsonSchema.tsindex 153e755d1..046cd4077 100644--- a/ts/packages/core/src/utils/jsonSchema.ts+++ b/ts/packages/core/src/utils/jsonSchema.ts@@ -51,49 +51,15 @@ const resolvePointer = (root: Record<string, unknown>, pointer: string): unknown};/**- * Inlines internal JSON Schema `$ref` pointers (`#/$defs/...` and the- * legacy `#/definitions/...`) so the returned schema can be safely handed- * to consumers — like AJV in `@mastra/schema-compat` — that don't tolerate- * unresolved references.+ * Inlines internal JSON Schema `$ref` pointers (`#/$defs/...` and legacy+ * `#/definitions/...`) so the returned schema can be safely handed to+ * consumers that don't tolerate unresolved references (e.g. AJV in+ * `@mastra/schema-compat`). External (`http://`, `https://`, …) refs are+ * left untouched. Cycles are broken with `{ type: 'object',+ * additionalProperties: true }`. The input is never mutated.*- * The traversal is reflective (no allow-list of JSON Schema keywords), so- * future applicators (`unevaluatedProperties`, `dependentSchemas`, …) are- * covered automatically. Sibling keywords next to `$ref` are shallow-merged- * per Draft 2020-12 semantics — the sibling wins on collision so a caller's- * `description` or `default` overrides the target's. Recursive `$ref`- * chains are broken with `{ type: 'object', additionalProperties: true }`,- * matching the upstream Mastra recommendation in- * {@link https://github.com/mastra-ai/mastra/issues/15341 mastra-ai/mastra#15341}.- *- * The input schema is not mutated: every node is deep-cloned. `$defs` and- * `definitions` are stripped from the returned root once everything- * reachable is inlined — AJV strict-mode otherwise complains about unused- * definitions.- *- * External `$ref` pointers (`http://`, `https://`, `file://`, …) are left- * untouched: the caller may forward them to a consumer that resolves them- * natively.- *- * @param schema - The JSON Schema to dereference. May be any plain object.- * @returns A new schema with internal `$ref` pointers inlined.- *- * @throws {JsonSchemaRefResolutionError} When an internal pointer is- * malformed, points at a missing target, or chains past the depth cap.- *- * @example- * ```ts- * dereferenceJsonSchema({- * type: 'object',- * properties: { user: { $ref: '#/$defs/User' } },- * $defs: { User: { type: 'object', properties: { id: { type: 'string' } } } },- * });- * // {- * // type: 'object',- * // properties: {- * // user: { type: 'object', properties: { id: { type: 'string' } } },- * // },- * // }- * ```+ * @throws {JsonSchemaRefResolutionError} on malformed pointers, missing+ * targets, or chains past the depth cap.*/export function dereferenceJsonSchema<T = unknown>(schema: T): T {if (!isPlainObject(schema)) return schema;@@ -101,9 +67,8 @@ export function dereferenceJsonSchema<T = unknown>(schema: T): T {const root = schema as Record<string, unknown>;const visiting = new WeakSet<object>();- // Filter `__proto__`/`constructor`/`prototype` keys to avoid altering the- // prototype of the cloned output node (which can break downstream- // `Object.keys` / `in` checks even though the global prototype is safe).+ // POLLUTING_KEYS filter prevents an attacker-shaped $defs entry from altering+ // the cloned node's prototype.const cloneChildren = (obj: Record<string, unknown>,visitedRefs: ReadonlySet<string>,@@ -116,8 +81,7 @@ export function dereferenceJsonSchema<T = unknown>(schema: T): T {.map(([k, v]) => [k, walk(v, visitedRefs, chainDepth, nodeDepth + 1)]));- // Function declaration so `cloneChildren` can reference `walk` despite being- // declared earlier (function declarations are hoisted within the closure).+ // `function` (not `const`) so `cloneChildren` above can call it via hoisting.function walk(node: unknown,visitedRefs: ReadonlySet<string>,diff --git a/ts/packages/providers/mastra/test/mastra-ref.test.ts b/ts/packages/providers/mastra/test/mastra-ref.test.tsindex fbdfce1e8..8a28bd381 100644--- a/ts/packages/providers/mastra/test/mastra-ref.test.ts+++ b/ts/packages/providers/mastra/test/mastra-ref.test.ts@@ -1,20 +1,15 @@/**- * Integration test for the Mastra provider against the **real**- * `@mastra/schema-compat` package (no `vi.mock` for it). This is the regression- * test for [PLEN-2244]: a Composio tool whose `inputParameters` carry a `$ref`- * (legal under both Draft 7 and 2020-12).+ * Regression test for the Mastra provider against the **real**+ * `@mastra/schema-compat` (no `vi.mock` for it). Without dereferencing,+ * `applyCompatLayer` silently degrades a `$ref`-typed property to a permissive+ * `anyOf` of all primitives — losing the type info from `$defs`. We assert+ * the post-wrap schemas preserve the structure described by `$defs`.*- * Without dereferencing, `applyCompatLayer` silently *degrades* the `$ref`-typed- * property to a permissive `anyOf` of all primitives — losing the type- * information from `$defs`. This test asserts the post-wrap `inputSchema`- * preserves the structure described by `$defs`, which is only possible if- * `$ref` is resolved before the conversion.- *- * Vitest mock scoping is per-file by default, so the top-level `vi.mock` for- * `@mastra/schema-compat` in `mastra.test.ts` does **not** leak into this file.+ * Vitest mock scoping is per-file by default, so the top-level `vi.mock`+ * for `@mastra/schema-compat` in `mastra.test.ts` does not leak here.*/-import { describe, it, expect, vi } from 'vitest';+import { describe, it, expect, vi, beforeEach } from 'vitest';import type { Tool } from '@composio/core';import { MastraProvider } from '../src';@@ -27,22 +22,17 @@ const containsRef = (value: unknown): boolean => {const findProperty = (schema: unknown, key: string): Record<string, unknown> | undefined => {if (schema === null || typeof schema !== 'object') return undefined;- const node = schema as Record<string, unknown>;- if (node.properties && typeof node.properties === 'object') {- const props = node.properties as Record<string, unknown>;- if (key in props) return props[key] as Record<string, unknown>;- for (const value of Object.values(props)) {- const found = findProperty(value, key);- if (found) return found;- }- }- for (const value of Object.values(node)) {+ for (const value of Object.values(schema as Record<string, unknown>)) {if (Array.isArray(value)) {for (const item of value) {const found = findProperty(item, key);if (found) return found;}} else if (typeof value === 'object' && value !== null) {+ const props = value as Record<string, unknown> as Record<string, unknown>;+ if (key in props && typeof props[key] === 'object') {+ return props[key] as Record<string, unknown>;+ }const found = findProperty(value, key);if (found) return found;}@@ -63,72 +53,41 @@ const refTool: Tool = {properties: { user: { $ref: '#/$defs/User' } as never },required: ['user'],$defs: {- User: {- type: 'object',- properties: { id: { type: 'string' } },- required: ['id'],- },+ User: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },},} as unknown as Tool['inputParameters'],outputParameters: {type: 'object',properties: { item: { $ref: '#/definitions/Item' } as never },definitions: {- Item: {- type: 'object',- properties: { sku: { type: 'string' } },- required: ['sku'],- },+ Item: { type: 'object', properties: { sku: { type: 'string' } }, required: ['sku'] },},} as unknown as Tool['outputParameters'],};-describe('MastraProvider regression: PLEN-2244 ($ref in JSON Schema)', () => {- it('does not throw when wrapping a tool whose schema uses $ref / $defs', () => {- const provider = new MastraProvider();- const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });- provider._setExecuteToolFn(executeToolFn);-- expect(() => provider.wrapTool(refTool, executeToolFn)).not.toThrow();- });+describe('MastraProvider regression: $ref in JSON Schema', () => {+ let wrapped: { inputSchema: unknown; outputSchema: unknown };- it('preserves type information from $defs (does not degrade $ref to permissive anyOf)', () => {+ beforeEach(() => {const provider = new MastraProvider();- const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });- provider._setExecuteToolFn(executeToolFn);-- const wrapped = provider.wrapTool(refTool, executeToolFn) as { inputSchema: unknown };+ const exec = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });+ provider._setExecuteToolFn(exec);+ wrapped = provider.wrapTool(refTool, exec) as typeof wrapped;+ });- // Without the dereference step, `$ref` is silently dropped during- // JSON-Schema → Zod → JSON-Schema round-trip and the `id` field disappears- // entirely (the property gets degraded to a permissive `anyOf`).+ it('preserves type info from $defs (no degraded permissive anyOf)', () => {const idProp = findProperty(wrapped.inputSchema, 'id');expect(idProp).toBeDefined();expect(idProp?.type).toBe('string');});- it('preserves type information from `definitions` on outputParameters (Draft 7)', () => {- const provider = new MastraProvider();- const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });- provider._setExecuteToolFn(executeToolFn);-- const wrapped = provider.wrapTool(refTool, executeToolFn) as { outputSchema: unknown };-+ it('preserves type info from Draft-7 `definitions` on the output schema', () => {const skuProp = findProperty(wrapped.outputSchema, 'sku');expect(skuProp).toBeDefined();expect(skuProp?.type).toBe('string');});- it('does not leave any $ref in the produced schemas', () => {- const provider = new MastraProvider();- const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });- provider._setExecuteToolFn(executeToolFn);-- const wrapped = provider.wrapTool(refTool, executeToolFn) as {- inputSchema: unknown;- outputSchema: unknown;- };-+ it('leaves no $ref in the produced schemas', () => {expect(containsRef(wrapped.inputSchema)).toBe(false);expect(containsRef(wrapped.outputSchema)).toBe(false);});