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(providers): dereference $ref/$defs schemas before translation

jkomyno9447932d9859
diff --git a/.changeset/deref-ref-schemas.md b/.changeset/deref-ref-schemas.md
new file mode 100644
index 000000000..331a9d647
--- /dev/null
+++ b/.changeset/deref-ref-schemas.md
@@ -0,0 +1,12 @@
+---
+'@composio/langchain': minor
+'@composio/llamaindex': minor
+'@composio/claude-agent-sdk': minor
+'@composio/vercel': minor
+'@composio/google': minor
+'@composio/openai-agents': minor
+---
+
+Dereference internal $ref/$defs in tool input schemas before provider translation, so properties reachable only through a reference keep their types and validation instead of degrading to untyped (z.any) or being emitted as a dangling reference.
+
+This changes the JSON Schema these providers emit for $ref-using tools. Downstream snapshot tests on tool definitions will see diffs. Schemas the Composio API ships with a $ref but no $defs block (e.g. GMAIL_FETCH_EMAILS) degrade to a permissive object schema rather than throwing. The strict-structured-outputs path of @composio/openai-agents is unchanged — OpenAI supports $defs/$ref natively, including recursion.
diff --git a/ts/packages/providers/claude-agent-sdk/src/index.ts b/ts/packages/providers/claude-agent-sdk/src/index.ts
index bb8380fc8..27233af37 100644
--- a/ts/packages/providers/claude-agent-sdk/src/index.ts
+++ b/ts/packages/providers/claude-agent-sdk/src/index.ts
@@ -14,6 +14,7 @@ import {
ExecuteToolFn,
McpUrlResponse,
McpServerGetResponse,
+ dereferenceJsonSchema,
normalizeToolArguments,
jsonSchemaToZodSchema,
} from '@composio/core';
@@ -111,11 +112,14 @@ export class ClaudeAgentSDKProvider extends BaseAgenticProvider<
// A tool with no input parameters stays closed: the fallback spells out
// `additionalProperties: false`, because a bare `properties: {}` is now an open object.
const inputZodSchema = jsonSchemaToZodSchema(
- composioTool.inputParameters ?? {
- type: 'object',
- properties: {},
- additionalProperties: false,
- }
+ dereferenceJsonSchema(
+ composioTool.inputParameters ?? {
+ type: 'object',
+ properties: {},
+ additionalProperties: false,
+ },
+ { onUnresolved: 'sentinel' }
+ )
);
// The SDK runtime accepts a complete schema, but `tool()` only exposes the raw-shape type, and
diff --git a/ts/packages/providers/claude-agent-sdk/test/claude-agent-sdk-ref.test.ts b/ts/packages/providers/claude-agent-sdk/test/claude-agent-sdk-ref.test.ts
new file mode 100644
index 000000000..ccbf90c19
--- /dev/null
+++ b/ts/packages/providers/claude-agent-sdk/test/claude-agent-sdk-ref.test.ts
@@ -0,0 +1,130 @@
+/**
+ * Regression test: `ClaudeAgentSDKProvider.wrapTool` must dereference internal
+ * `$ref`/`$defs` before handing the schema to `jsonSchemaToZodSchema`.
+ * Without dereferencing, a `$ref`-typed property degrades to `z.any()` and
+ * silently accepts any value.
+ */
+
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import type { Tool } from '@composio/core';
+import { ClaudeAgentSDKProvider } from '../src';
+
+// Mock the claude-agent-sdk module (per-file scoping keeps this independent of
+// claude-agent-sdk.test.ts).
+vi.mock('@anthropic-ai/claude-agent-sdk', () => {
+ return {
+ tool: vi.fn().mockImplementation((name, description, schema, handler) => {
+ return {
+ name,
+ description,
+ schema,
+ handler,
+ _isMockedClaudeAgentTool: true,
+ };
+ }),
+ };
+});
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+
+type MinimalZodSchema = {
+ safeParse: (value: unknown) => { success: boolean };
+};
+
+type MockedToolFn = Mock<
+ (
+ name: string,
+ description: string | undefined,
+ schema: MinimalZodSchema,
+ handler: unknown
+ ) => unknown
+>;
+
+const refTool: Tool = {
+ slug: 'TEST_REF_TOOL',
+ name: 'Ref Tool',
+ description: 'Tool whose schema carries internal $ref pointers',
+ toolkit: { slug: 'reftoolkit', name: 'Ref Toolkit' },
+ version: '20260828_00',
+ availableVersions: ['20260828_00'],
+ tags: [],
+ inputParameters: {
+ type: 'object',
+ properties: {
+ message: { $ref: '#/$defs/Message' },
+ },
+ required: ['message'],
+ $defs: {
+ Message: {
+ type: 'object',
+ properties: {
+ subject: { type: 'string' },
+ body: { type: 'string' },
+ },
+ required: ['subject', 'body'],
+ additionalProperties: false,
+ },
+ },
+ } as unknown as Tool['inputParameters'],
+} as unknown as Tool;
+
+const danglingRefTool: Tool = {
+ ...refTool,
+ slug: 'TEST_DANGLING_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: {
+ message: { $ref: '#/$defs/Message' },
+ },
+ required: ['message'],
+ } as unknown as Tool['inputParameters'],
+};
+
+const recursiveRefTool: Tool = {
+ ...refTool,
+ slug: 'TEST_RECURSIVE_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: {
+ node: { $ref: '#/$defs/Node' },
+ },
+ required: ['node'],
+ $defs: {
+ Node: {
+ type: 'object',
+ properties: {
+ value: { type: 'string' },
+ child: { $ref: '#/$defs/Node' },
+ },
+ required: ['value'],
+ },
+ },
+ } as unknown as Tool['inputParameters'],
+};
+
+describe('ClaudeAgentSDKProvider regression: $ref in JSON Schema', () => {
+ let provider: ClaudeAgentSDKProvider;
+ let executeToolFn: (toolSlug: string, params: Record<string, unknown>) => Promise<unknown>;
+
+ beforeEach(() => {
+ provider = new ClaudeAgentSDKProvider();
+ executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
+ vi.clearAllMocks();
+ });
+
+ it('produces a Zod schema that validates the $defs-described shape', () => {
+ provider.wrapTool(refTool, executeToolFn);
+ const schema = (tool as unknown as MockedToolFn).mock.calls[0][2];
+
+ expect(schema.safeParse({ message: { subject: 's', body: 'b' } }).success).toBe(true);
+ expect(schema.safeParse({ message: 42 }).success).toBe(false);
+ });
+
+ it('does not throw when $ref points into an undeclared $defs block', () => {
+ expect(() => provider.wrapTool(danglingRefTool, executeToolFn)).not.toThrow();
+ });
+
+ it('does not throw on a self-referential $defs schema', () => {
+ expect(() => provider.wrapTool(recursiveRefTool, executeToolFn)).not.toThrow();
+ });
+});
diff --git a/ts/packages/providers/google/src/index.ts b/ts/packages/providers/google/src/index.ts
index e5104821f..2066fbc99 100644
--- a/ts/packages/providers/google/src/index.ts
+++ b/ts/packages/providers/google/src/index.ts
@@ -17,6 +17,7 @@ import {
McpServerGetResponse,
normalizeToolArguments,
deduplicateJsonSchemaRequiredArrays,
+ dereferenceJsonSchema,
ensureObjectTypeOnProperties,
} from '@composio/core';
import { FunctionDeclaration, Schema } from '@google/genai';
@@ -130,7 +131,11 @@ export class GoogleProvider extends BaseNonAgenticProvider<
*/
wrapTool(tool: Tool): GoogleTool {
const inputParameters = ensureObjectTypeOnProperties(
- deduplicateJsonSchemaRequiredArrays(tool.inputParameters)
+ deduplicateJsonSchemaRequiredArrays(
+ dereferenceJsonSchema(tool.inputParameters ?? { type: 'object', properties: {} }, {
+ onUnresolved: 'sentinel',
+ })
+ )
);
return {
diff --git a/ts/packages/providers/google/test/google-ref.test.ts b/ts/packages/providers/google/test/google-ref.test.ts
new file mode 100644
index 000000000..629af977e
--- /dev/null
+++ b/ts/packages/providers/google/test/google-ref.test.ts
@@ -0,0 +1,105 @@
+/**
+ * Regression test: `GoogleProvider.wrapTool` rebuilds the root schema from
+ * `properties`/`required`, which used to discard the `$defs` block while
+ * `$ref` pointers inside `properties` stayed dangling. The Google GenAI
+ * `Schema` type has no `ref`/`defs` field, so a `$ref` on the `parameters`
+ * path is unrepresentable and the API answers 400. `wrapTool` now
+ * dereferences `$ref`/`$defs` before the rebuild.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { Tool } from '@composio/core';
+import { GoogleProvider } from '../src';
+
+const containsInternalRef = (value: unknown): boolean => {
+ if (value === null || typeof value !== 'object') return false;
+ if (Array.isArray(value)) return value.some(containsInternalRef);
+ const node = value as Record<string, unknown>;
+ if (typeof node.$ref === 'string' && node.$ref.startsWith('#')) return true;
+ return Object.values(node).some(containsInternalRef);
+};
+
+const refTool: Tool = {
+ slug: 'TEST_REF_TOOL',
+ name: 'Ref Tool',
+ description: 'Tool whose schema carries internal $ref pointers',
+ toolkit: { slug: 'reftoolkit', name: 'Ref Toolkit' },
+ version: '20260828_00',
+ availableVersions: ['20260828_00'],
+ tags: [],
+ inputParameters: {
+ type: 'object',
+ properties: {
+ message: { $ref: '#/$defs/Message' },
+ },
+ required: ['message'],
+ $defs: {
+ Message: {
+ type: 'object',
+ properties: {
+ subject: { type: 'string' },
+ body: { type: 'string' },
+ },
+ required: ['subject', 'body'],
+ additionalProperties: false,
+ },
+ },
+ } as unknown as Tool['inputParameters'],
+} as unknown as Tool;
+
+const danglingRefTool: Tool = {
+ ...refTool,
+ slug: 'TEST_DANGLING_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: {
+ message: { $ref: '#/$defs/Message' },
+ },
+ required: ['message'],
+ } as unknown as Tool['inputParameters'],
+};
+
+const recursiveRefTool: Tool = {
+ ...refTool,
+ slug: 'TEST_RECURSIVE_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: {
+ node: { $ref: '#/$defs/Node' },
+ },
+ required: ['node'],
+ $defs: {
+ Node: {
+ type: 'object',
+ properties: {
+ value: { type: 'string' },
+ child: { $ref: '#/$defs/Node' },
+ },
+ required: ['value'],
+ },
+ },
+ } as unknown as Tool['inputParameters'],
+};
+
+describe('GoogleProvider regression: $ref in JSON Schema', () => {
+ let provider: GoogleProvider;
+
+ beforeEach(() => {
+ provider = new GoogleProvider();
+ });
+
+ it('inlines internal $ref/$defs instead of stranding a dangling pointer', () => {
+ const wrapped = provider.wrapTool(refTool);
+
+ expect(containsInternalRef(wrapped.parameters)).toBe(false);
+ expect(wrapped.parameters?.required).toContain('message');
+ });
+
+ it('does not throw when $ref points into an undeclared $defs block', () => {
+ expect(() => provider.wrapTool(danglingRefTool)).not.toThrow();
+ });
+
+ it('does not throw on a self-referential $defs schema', () => {
+ expect(() => provider.wrapTool(recursiveRefTool)).not.toThrow();
+ });
+});
diff --git a/ts/packages/providers/langchain/src/index.ts b/ts/packages/providers/langchain/src/index.ts
index 7f2ed509f..b9ad69324 100644
--- a/ts/packages/providers/langchain/src/index.ts
+++ b/ts/packages/providers/langchain/src/index.ts
@@ -11,6 +11,7 @@
*/
import {
BaseAgenticProvider,
+ dereferenceJsonSchema,
jsonSchemaToZodSchema,
Tool,
ExecuteToolFn,
@@ -136,10 +137,12 @@ export class LangchainProvider extends BaseAgenticProvider<
if (!tool.inputParameters) {
throw new Error('Tool input parameters are not defined');
}
- const parameters = jsonSchemaToZodSchema(tool.inputParameters);
+ const parameters = jsonSchemaToZodSchema(
+ dereferenceJsonSchema(tool.inputParameters, { onUnresolved: 'sentinel' })
+ );
// See https://github.com/langchain-ai/langchainjs/issues/8468 and pnpm-workspace.yaml.
- // @ts-ignore: error TS2589: Type instantiation is excessively deep and possibly infinite.
+ // @ts-expect-error: error TS2589: Type instantiation is excessively deep and possibly infinite.
return new DynamicStructuredTool({
name: toolName,
description: description || '',
diff --git a/ts/packages/providers/langchain/test/langchain-ref.test.ts b/ts/packages/providers/langchain/test/langchain-ref.test.ts
new file mode 100644
index 000000000..a277bb189
--- /dev/null
+++ b/ts/packages/providers/langchain/test/langchain-ref.test.ts
@@ -0,0 +1,101 @@
+/**
+ * Regression test: `LangchainProvider.wrapTool` must dereference internal
+ * `$ref`/`$defs` before handing the schema to `jsonSchemaToZodSchema`.
+ * Without dereferencing, a `$ref`-typed property degrades to `z.any()` and
+ * silently accepts any value.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { Tool } from '@composio/core';
+import { LangchainProvider } from '../src';
+
+const refTool: Tool = {
+ slug: 'TEST_REF_TOOL',
+ name: 'Ref Tool',
+ description: 'Tool whose schema carries internal $ref pointers',
+ toolkit: { slug: 'reftoolkit', name: 'Ref Toolkit' },
+ version: '20260828_00',
+ availableVersions: ['20260828_00'],
+ tags: [],
+ inputParameters: {
+ type: 'object',
+ properties: {
+ message: { $ref: '#/$defs/Message' },
+ },
+ required: ['message'],
+ $defs: {
+ Message: {
+ type: 'object',
+ properties: {
+ subject: { type: 'string' },
+ body: { type: 'string' },
+ },
+ required: ['subject', 'body'],
+ additionalProperties: false,
+ },
+ },
+ } as unknown as Tool['inputParameters'],
+} as unknown as Tool;
+
+// Same tool but with the $defs block deleted — GMAIL_FETCH_EMAILS style.
+const danglingRefTool: Tool = {
+ ...refTool,
+ slug: 'TEST_DANGLING_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: {
+ message: { $ref: '#/$defs/Message' },
+ },
+ required: ['message'],
+ } as unknown as Tool['inputParameters'],
+};
+
+// A self-referential schema has no finite inlined form.
+const recursiveRefTool: Tool = {
+ ...refTool,
+ slug: 'TEST_RECURSIVE_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: {
+ node: { $ref: '#/$defs/Node' },
+ },
+ required: ['node'],
+ $defs: {
+ Node: {
+ type: 'object',
+ properties: {
+ value: { type: 'string' },
+ child: { $ref: '#/$defs/Node' },
+ },
+ required: ['value'],
+ },
+ },
+ } as unknown as Tool['inputParameters'],
+};
+
+describe('LangchainProvider regression: $ref in JSON Schema', () => {
+ let provider: LangchainProvider;
+ let executeToolFn: (toolSlug: string, params: Record<string, unknown>) => Promise<unknown>;
+
+ beforeEach(() => {
+ provider = new LangchainProvider();
+ executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
+ });
+
+ it('produces a Zod schema that validates the $defs-described shape', () => {
+ const wrapped = provider.wrapTool(refTool, executeToolFn);
+ const schema = wrapped.schema as { safeParse: (value: unknown) => { success: boolean } };
+
+ expect(schema.safeParse({ message: { subject: 's', body: 'b' } }).success).toBe(true);
+ // Before the fix, $ref degraded to z.any() and this would have passed.
+ expect(schema.safeParse({ message: 42 }).success).toBe(false);
+ });
+
+ it('does not throw when $ref points into an undeclared $defs block', () => {
+ expect(() => provider.wrapTool(danglingRefTool, executeToolFn)).not.toThrow();
+ });
+
+ it('does not throw on a self-referential $defs schema', () => {
+ expect(() => provider.wrapTool(recursiveRefTool, executeToolFn)).not.toThrow();
+ });
+});
diff --git a/ts/packages/providers/llamaindex/src/index.ts b/ts/packages/providers/llamaindex/src/index.ts
index a50db9b07..5820afd81 100644
--- a/ts/packages/providers/llamaindex/src/index.ts
+++ b/ts/packages/providers/llamaindex/src/index.ts
@@ -12,6 +12,7 @@ import {
ExecuteToolFn,
McpServerGetResponse,
McpUrlResponse,
+ dereferenceJsonSchema,
jsonSchemaToZodSchema,
normalizeToolArguments,
} from '@composio/core';
@@ -34,7 +35,9 @@ export class LlamaindexProvider extends BaseAgenticProvider<
*/
wrapTool(tool: Tool, executeTool: ExecuteToolFn): LlamaindexTool {
const inputParams = tool.inputParameters;
- const inputParametersSchema = jsonSchemaToZodSchema(inputParams ?? {});
+ const inputParametersSchema = jsonSchemaToZodSchema(
+ dereferenceJsonSchema(inputParams ?? {}, { onUnresolved: 'sentinel' })
+ );
return createLlamaindexTool({
name: tool.slug,
description: tool.description ?? tool.name ?? '',
diff --git a/ts/packages/providers/llamaindex/test/llamaindex-ref.test.ts b/ts/packages/providers/llamaindex/test/llamaindex-ref.test.ts
new file mode 100644
index 000000000..7db58752f
--- /dev/null
+++ b/ts/packages/providers/llamaindex/test/llamaindex-ref.test.ts
@@ -0,0 +1,117 @@
+/**
+ * Regression test: `LlamaindexProvider.wrapTool` must dereference internal
+ * `$ref`/`$defs` before handing the schema to `jsonSchemaToZodSchema`.
+ * Without dereferencing, a `$ref`-typed property degrades to `z.any()` and
+ * silently accepts any value.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { Tool } from '@composio/core';
+import { LlamaindexProvider } from '../src';
+
+// Mock the llamaindex module (per-file scoping keeps this independent of llamaindex.test.ts).
+vi.mock('llamaindex', () => {
+ return {
+ tool: vi.fn().mockImplementation(config => ({
+ metadata: {
+ name: config.name,
+ description: config.description,
+ parameters: config.parameters,
+ },
+ call: config.execute,
+ _type: 'llamaindex_tool',
+ _config: config,
+ })),
+ JSONValue: {},
+ };
+});
+
+const refTool: Tool = {
+ slug: 'TEST_REF_TOOL',
+ name: 'Ref Tool',
+ description: 'Tool whose schema carries internal $ref pointers',
+ toolkit: { slug: 'reftoolkit', name: 'Ref Toolkit' },
+ version: '20260828_00',
+ availableVersions: ['20260828_00'],
+ tags: [],
+ inputParameters: {
+ type: 'object',
+ properties: {
+ message: { $ref: '#/$defs/Message' },
+ },
+ required: ['message'],
+ $defs: {
+ Message: {
+ type: 'object',
+ properties: {
+ subject: { type: 'string' },
+ body: { type: 'string' },
+ },
+ required: ['subject', 'body'],
+ additionalProperties: false,
+ },
+ },
+ } as unknown as Tool['inputParameters'],
+} as unknown as Tool;
+
+const danglingRefTool: Tool = {
+ ...refTool,
+ slug: 'TEST_DANGLING_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: {
+ message: { $ref: '#/$defs/Message' },
+ },
+ required: ['message'],
+ } as unknown as Tool['inputParameters'],
+};
+
+const recursiveRefTool: Tool = {
+ ...refTool,
+ slug: 'TEST_RECURSIVE_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: {
+ node: { $ref: '#/$defs/Node' },
+ },
+ required: ['node'],
+ $defs: {
+ Node: {
+ type: 'object',
+ properties: {
+ value: { type: 'string' },
+ child: { $ref: '#/$defs/Node' },
+ },
+ required: ['value'],
+ },
+ },
+ } as unknown as Tool['inputParameters'],
+};
+
+describe('LlamaindexProvider regression: $ref in JSON Schema', () => {
+ let provider: LlamaindexProvider;
+ let executeToolFn: (toolSlug: string, params: Record<string, unknown>) => Promise<unknown>;
+
+ beforeEach(() => {
+ provider = new LlamaindexProvider();
+ executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
+ });
+
+ it('produces a Zod schema that validates the $defs-described shape', () => {
+ const wrapped = provider.wrapTool(refTool, executeToolFn);
+ const schema = wrapped.metadata.parameters as {
+ safeParse: (value: unknown) => { success: boolean };
+ };
+
+ expect(schema.safeParse({ message: { subject: 's', body: 'b' } }).success).toBe(true);
+ expect(schema.safeParse({ message: 42 }).success).toBe(false);
+ });
+
+ it('does not throw when $ref points into an undeclared $defs block', () => {
+ expect(() => provider.wrapTool(danglingRefTool, executeToolFn)).not.toThrow();
+ });
+
+ it('does not throw on a self-referential $defs schema', () => {
+ expect(() => provider.wrapTool(recursiveRefTool, executeToolFn)).not.toThrow();
+ });
+});
diff --git a/ts/packages/providers/openai-agents/src/index.ts b/ts/packages/providers/openai-agents/src/index.ts
index 68fb5aa7f..9629c7d17 100644
--- a/ts/packages/providers/openai-agents/src/index.ts
+++ b/ts/packages/providers/openai-agents/src/index.ts
@@ -18,6 +18,7 @@ import {
McpServerGetResponse,
normalizeToolArguments,
deduplicateJsonSchemaRequiredArrays,
+ dereferenceJsonSchema,
logger,
omitNullToolArguments,
toStrictJsonSchema,
@@ -140,7 +141,9 @@ export class OpenAIAgentsProvider extends BaseAgenticProvider<
* ```
*/
wrapTool(composioTool: ComposioTool, executeTool: ExecuteToolFn): OpenAIAgentTool {
- const inputParameters = deduplicateJsonSchemaRequiredArrays(composioTool.inputParameters);
+ const inputParameters = deduplicateJsonSchemaRequiredArrays(
+ dereferenceJsonSchema(composioTool.inputParameters ?? {}, { onUnresolved: 'sentinel' })
+ );
// Strict mode applies OpenAI's structured-output contract at every
// depth: all properties required, closed objects, optional properties
diff --git a/ts/packages/providers/openai-agents/test/openai-agents-ref.test.ts b/ts/packages/providers/openai-agents/test/openai-agents-ref.test.ts
new file mode 100644
index 000000000..4964ff376
--- /dev/null
+++ b/ts/packages/providers/openai-agents/test/openai-agents-ref.test.ts
@@ -0,0 +1,154 @@
+/**
+ * Regression test: `OpenAIAgentsProvider.wrapTool`'s non-strict fallback
+ * rebuilds the root schema from `properties`/`required`, which used to
+ * discard the `$defs` block while `$ref` pointers inside `properties`
+ * stayed dangling. `wrapTool` now dereferences `$ref`/`$defs` before that
+ * rebuild.
+ *
+ * The strict branch is intentionally different: OpenAI's structured outputs
+ * support `$defs`/`$ref` natively, including recursion, so `toStrictJsonSchema`
+ * keeps local refs rather than inlining them. This file also guards that the
+ * strict branch stays untouched by the fix applied to the fallback.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { Tool, ExecuteToolFn } from '@composio/core';
+import { OpenAIAgentsProvider } from '../src';
+
+interface MockedOpenAIAgentTool {
+ name: string;
+ description: string;
+ parameters: Record<string, unknown>;
+ strict: boolean;
+ execute: Function;
+ _isMockedOpenAIAgentTool: boolean;
+}
+
+// Mock the @openai/agents module (per-file scoping keeps this independent of
+// openai-agents.test.ts).
+vi.mock('@openai/agents', () => {
+ return {
+ tool: vi.fn().mockImplementation(toolConfig => {
+ return {
+ ...toolConfig,
+ _isMockedOpenAIAgentTool: true,
+ } as MockedOpenAIAgentTool;
+ }),
+ };
+});
+
+const containsInternalRef = (value: unknown): boolean => {
+ if (value === null || typeof value !== 'object') return false;
+ if (Array.isArray(value)) return value.some(containsInternalRef);
+ const node = value as Record<string, unknown>;
+ if (typeof node.$ref === 'string' && node.$ref.startsWith('#')) return true;
+ return Object.values(node).some(containsInternalRef);
+};
+
+const refTool: Tool = {
+ slug: 'TEST_REF_TOOL',
+ name: 'Ref Tool',
+ description: 'Tool whose schema carries internal $ref pointers',
+ toolkit: { slug: 'reftoolkit', name: 'Ref Toolkit' },
+ version: '20260828_00',
+ availableVersions: ['20260828_00'],
+ tags: [],
+ inputParameters: {
+ type: 'object',
+ properties: {
+ message: { $ref: '#/$defs/Message' },
+ },
+ required: ['message'],
+ $defs: {
+ Message: {
+ type: 'object',
+ properties: {
+ subject: { type: 'string' },
+ body: { type: 'string' },
+ },
+ required: ['subject', 'body'],
+ additionalProperties: false,
+ },
+ },
+ } as unknown as Tool['inputParameters'],
+} as unknown as Tool;
+
+const danglingRefTool: Tool = {
+ ...refTool,
+ slug: 'TEST_DANGLING_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: {
+ message: { $ref: '#/$defs/Message' },
+ },
+ required: ['message'],
+ } as unknown as Tool['inputParameters'],
+};
+
+const recursiveRefTool: Tool = {
+ ...refTool,
+ slug: 'TEST_RECURSIVE_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: {
+ node: { $ref: '#/$defs/Node' },
+ },
+ required: ['node'],
+ $defs: {
+ Node: {
+ type: 'object',
+ properties: {
+ value: { type: 'string' },
+ child: { $ref: '#/$defs/Node' },
+ },
+ required: ['value'],
+ },
+ },
+ } as unknown as Tool['inputParameters'],
+};
+
+describe('OpenAIAgentsProvider regression: $ref in JSON Schema', () => {
+ let provider: OpenAIAgentsProvider;
+ let executeToolFn: ExecuteToolFn;
+
+ beforeEach(() => {
+ provider = new OpenAIAgentsProvider();
+ executeToolFn = vi.fn().mockResolvedValue({
+ data: {},
+ error: null,
+ successful: true,
+ }) as unknown as ExecuteToolFn;
+ vi.clearAllMocks();
+ });
+
+ describe('non-strict fallback (bucket B fix)', () => {
+ it('inlines internal $ref/$defs instead of stranding a dangling pointer', () => {
+ const wrapped = provider.wrapTool(refTool, executeToolFn) as unknown as MockedOpenAIAgentTool;
+
+ expect(containsInternalRef(wrapped.parameters)).toBe(false);
+ expect(wrapped.parameters.required).toContain('message');
+ });
+
+ it('does not throw when $ref points into an undeclared $defs block', () => {
+ expect(() => provider.wrapTool(danglingRefTool, executeToolFn)).not.toThrow();
+ });
+
+ it('does not throw on a self-referential $defs schema', () => {
+ expect(() => provider.wrapTool(recursiveRefTool, executeToolFn)).not.toThrow();
+ });
+ });
+
+ describe('strict branch (must stay untouched)', () => {
+ it('keeps $defs and the $ref pointer intact under strict mode', () => {
+ const strictProvider = new OpenAIAgentsProvider({ strict: true });
+ const wrapped = strictProvider.wrapTool(
+ refTool,
+ executeToolFn
+ ) as unknown as MockedOpenAIAgentTool;
+
+ expect(wrapped.strict).toBe(true);
+ expect(containsInternalRef(wrapped.parameters)).toBe(true);
+ expect(wrapped.parameters.$defs).toBeDefined();
+ });
+ });
+});
diff --git a/ts/packages/providers/vercel/src/index.ts b/ts/packages/providers/vercel/src/index.ts
index 3acf22327..e2a27ae11 100644
--- a/ts/packages/providers/vercel/src/index.ts
+++ b/ts/packages/providers/vercel/src/index.ts
@@ -150,7 +150,7 @@ export class VercelProvider extends BaseAgenticProvider<
// The Zod converter does not follow $ref, so inline the definitions the
// strict rewrite keeps (cycles fall back to the permissive sentinel).
const inputParametersSchema = jsonSchemaToZodSchema(
- strictSource ? dereferenceJsonSchema(parameters, { onUnresolved: 'sentinel' }) : parameters
+ dereferenceJsonSchema(parameters, { onUnresolved: 'sentinel' })
);
return tool({
diff --git a/ts/packages/providers/vercel/test/vercel-ref.test.ts b/ts/packages/providers/vercel/test/vercel-ref.test.ts
new file mode 100644
index 000000000..e5995f313
--- /dev/null
+++ b/ts/packages/providers/vercel/test/vercel-ref.test.ts
@@ -0,0 +1,128 @@
+/**
+ * Regression test: `VercelProvider.wrapTool` must dereference internal
+ * `$ref`/`$defs` before handing the schema to `jsonSchemaToZodSchema`, on
+ * both the default and strict paths. Without dereferencing, a `$ref`-typed
+ * property degrades to `z.any()` and silently accepts any value.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { Tool } from '@composio/core';
+import { VercelProvider } from '../src';
+
+interface MockedVercelTool {
+ description: string;
+ inputSchema: unknown;
+ execute: Function;
+ _isMockedVercelTool: boolean;
+}
+
+// Mock the ai module (per-file scoping keeps this independent of vercel.test.ts).
+vi.mock('ai', () => {
+ return {
+ tool: vi.fn().mockImplementation(toolConfig => {
+ return {
+ ...toolConfig,
+ _isMockedVercelTool: true,
+ } as MockedVercelTool;
+ }),
+ jsonSchema: vi.fn().mockImplementation(schema => schema),
+ };
+});
+
+const refTool: Tool = {
+ slug: 'TEST_REF_TOOL',
+ name: 'Ref Tool',
+ description: 'Tool whose schema carries internal $ref pointers',
+ toolkit: { slug: 'reftoolkit', name: 'Ref Toolkit' },
+ version: '20260828_00',
+ availableVersions: ['20260828_00'],
+ tags: [],
+ inputParameters: {
+ type: 'object',
+ properties: {
+ message: { $ref: '#/$defs/Message' },
+ },
+ required: ['message'],
+ $defs: {
+ Message: {
+ type: 'object',
+ properties: {
+ subject: { type: 'string' },
+ body: { type: 'string' },
+ },
+ required: ['subject', 'body'],
+ additionalProperties: false,
+ },
+ },
+ } as unknown as Tool['inputParameters'],
+} as unknown as Tool;
+
+const danglingRefTool: Tool = {
+ ...refTool,
+ slug: 'TEST_DANGLING_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: {
+ message: { $ref: '#/$defs/Message' },
+ },
+ required: ['message'],
+ } as unknown as Tool['inputParameters'],
+};
+
+const recursiveRefTool: Tool = {
+ ...refTool,
+ slug: 'TEST_RECURSIVE_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: {
+ node: { $ref: '#/$defs/Node' },
+ },
+ required: ['node'],
+ $defs: {
+ Node: {
+ type: 'object',
+ properties: {
+ value: { type: 'string' },
+ child: { $ref: '#/$defs/Node' },
+ },
+ required: ['value'],
+ },
+ },
+ } as unknown as Tool['inputParameters'],
+};
+
+describe('VercelProvider regression: $ref in JSON Schema', () => {
+ let provider: VercelProvider;
+ let executeToolFn: (toolSlug: string, params: Record<string, unknown>) => Promise<unknown>;
+
+ beforeEach(() => {
+ provider = new VercelProvider();
+ executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
+ vi.clearAllMocks();
+ });
+
+ it('produces a Zod schema that validates the $defs-described shape (default path)', () => {
+ const wrapped = provider.wrapTool(refTool, executeToolFn) as unknown as MockedVercelTool;
+ const schema = wrapped.inputSchema as { safeParse: (value: unknown) => { success: boolean } };
+
+ expect(schema.safeParse({ message: { subject: 's', body: 'b' } }).success).toBe(true);
+ expect(schema.safeParse({ message: 42 }).success).toBe(false);
+ });
+
+ it('produces a Zod schema that validates the $defs-described shape (strict path)', () => {
+ const strictProvider = new VercelProvider({ strict: true });
+ const wrapped = strictProvider.wrapTool(refTool, executeToolFn) as unknown as MockedVercelTool;
+ const schema = wrapped.inputSchema as { safeParse: (value: unknown) => { success: boolean } };
+
+ expect(schema.safeParse({ message: { subject: 's', body: 'b' } }).success).toBe(true);
+ expect(schema.safeParse({ message: 42 }).success).toBe(false);
+ });
+
+ it('does not throw when $ref points into an undeclared $defs block', () => {
+ expect(() => provider.wrapTool(danglingRefTool, executeToolFn)).not.toThrow();
+ });
+
+ it('does not throw on a self-referential $defs schema', () => {
+ expect(() => provider.wrapTool(recursiveRefTool, executeToolFn)).not.toThrow();
+ });
+});