@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 06:00 UTC

next
ts 184 lines 7.08 KB
Raw
1 /**
2 * `$ref` / `$defs` handling contract for OpenAIAgentsProvider.
3 *
4 * `wrapTool` has two independent branches with *opposite* correct behavior,
5 * and nothing previously pinned either of them:
6 *
7 * - the strict-structured-outputs branch must **keep** local `$ref`/`$defs`.
8 * OpenAI supports them natively, including recursion, and
9 * `toStrictJsonSchema` preserves them on purpose (see
10 * `ts/packages/core/src/utils/jsonSchema.ts`, "local `$ref`s into
11 * `$defs`/`definitions` are kept"). Inlining first would delete recursion
12 * support and multiply a shared `$def` against OpenAI's schema size caps.
13 * - the non-strict fallback rebuilds the root from `properties`/`required`,
14 * which drops `$defs` while leaving `$ref` pointers inside `properties`.
15 * That branch must therefore dereference *before* the rebuild.
16 *
17 * A change that "helpfully" dereferences everything up front satisfies the
18 * second requirement and silently violates the first. These tests exist to
19 * make that failure loud.
20 *
21 * Regenerated 2026-08-28 after the original was lost in a session handoff.
22 * The non-strict "resolves `$ref`" case below began life as an `it.fails`
23 * ratchet while the fallback still stranded pointers; landing
24 * `fix/deref-ref-schemas-in-providers` flipped it to a plain `it`, exactly as
25 * the ratchet's instructions required.
26 */
27 import { describe, it, expect, vi, beforeEach } from 'vitest';
28 import { OpenAIAgentsProvider } from '../src';
29 import { Tool, ExecuteToolFn } from '@composio/core';
30
31 interface MockedOpenAIAgentTool {
32 name: string;
33 description: string;
34 parameters: Record<string, unknown>;
35 strict: boolean;
36 execute: Function;
37 }
38
39 vi.mock('@openai/agents', () => ({
40 tool: vi.fn().mockImplementation(toolConfig => ({ ...toolConfig })),
41 }));
42
43 /** True when any node carries a `$ref` pointing inside this document. */
44 const containsInternalRef = (value: unknown): boolean => {
45 if (value === null || typeof value !== 'object') return false;
46 if (Array.isArray(value)) return value.some(containsInternalRef);
47 const node = value as Record<string, unknown>;
48 if (typeof node.$ref === 'string' && node.$ref.startsWith('#')) return true;
49 return Object.values(node).some(containsInternalRef);
50 };
51
52 const baseTool: Tool = {
53 slug: 'REF_TOOL',
54 name: 'Ref Tool',
55 description: 'Tool whose schema reaches a property through $ref',
56 version: '20260828_00',
57 availableVersions: ['20260828_00'],
58 tags: [],
59 inputParameters: {
60 type: 'object',
61 properties: { message: { $ref: '#/$defs/Message' } },
62 required: ['message'],
63 $defs: {
64 Message: {
65 type: 'object',
66 properties: { subject: { type: 'string' }, body: { type: 'string' } },
67 required: ['subject', 'body'],
68 },
69 },
70 },
71 } as unknown as Tool;
72
73 /** GMAIL_FETCH_EMAILS shape: a `$ref` into `$defs` that was never declared. */
74 const danglingTool: Tool = {
75 ...baseTool,
76 slug: 'DANGLING_REF_TOOL',
77 inputParameters: {
78 type: 'object',
79 properties: { message: { $ref: '#/$defs/Message' } },
80 required: ['message'],
81 },
82 } as unknown as Tool;
83
84 /** A legitimately recursive schema — no finite inlined form exists. */
85 const recursiveTool: Tool = {
86 ...baseTool,
87 slug: 'RECURSIVE_REF_TOOL',
88 inputParameters: {
89 type: 'object',
90 properties: { node: { $ref: '#/$defs/Node' } },
91 required: ['node'],
92 $defs: {
93 Node: {
94 type: 'object',
95 properties: { label: { type: 'string' }, child: { $ref: '#/$defs/Node' } },
96 required: ['label'],
97 },
98 },
99 },
100 } as unknown as Tool;
101
102 describe('OpenAIAgentsProvider $ref handling', () => {
103 let execute: ExecuteToolFn;
104
105 beforeEach(() => {
106 execute = vi.fn().mockResolvedValue({
107 data: {},
108 error: null,
109 successful: true,
110 }) as unknown as ExecuteToolFn;
111 vi.clearAllMocks();
112 });
113
114 describe('strict mode must preserve references', () => {
115 it('keeps $defs and the $ref pointer instead of inlining them', () => {
116 const provider = new OpenAIAgentsProvider({ strict: true });
117 provider._setExecuteToolFn(execute);
118
119 const wrapped = provider.wrapTool(baseTool, execute) as unknown as MockedOpenAIAgentTool;
120
121 expect(wrapped.strict).toBe(true);
122 // The reference itself survives — OpenAI resolves it.
123 expect(wrapped.parameters.properties).toEqual({ message: { $ref: '#/$defs/Message' } });
124 // And the definition it points at travels with it.
125 expect(wrapped.parameters.$defs).toBeDefined();
126 expect((wrapped.parameters.$defs as Record<string, unknown>).Message).toMatchObject({
127 type: 'object',
128 });
129 });
130
131 it('keeps recursion expressible — a recursive $defs is not flattened', () => {
132 const provider = new OpenAIAgentsProvider({ strict: true });
133 provider._setExecuteToolFn(execute);
134
135 const wrapped = provider.wrapTool(recursiveTool, execute) as unknown as MockedOpenAIAgentTool;
136
137 // Dereferencing a recursive schema replaces the recursive branch with a
138 // permissive `{ type: 'object', additionalProperties: true }` sentinel.
139 // Strict mode must not pay that price: the self-reference stays intact.
140 const defs = wrapped.parameters.$defs as Record<string, Record<string, unknown>> | undefined;
141 expect(defs?.Node).toBeDefined();
142 const child = (defs?.Node.properties as Record<string, unknown>).child;
143 // `child` is optional, so strict mode widens it to an `anyOf` with a
144 // null branch. What matters is that the self-reference survives at all —
145 // an inlining pass would have replaced it with a permissive sentinel.
146 expect(containsInternalRef(child)).toBe(true);
147 expect(JSON.stringify(child)).toContain('#/$defs/Node');
148 });
149
150 it('falls back to non-strict on a dangling ref rather than throwing', () => {
151 const provider = new OpenAIAgentsProvider({ strict: true });
152 provider._setExecuteToolFn(execute);
153
154 expect(() => provider.wrapTool(danglingTool, execute)).not.toThrow();
155 });
156 });
157
158 describe('non-strict mode must not emit a dangling reference', () => {
159 it('resolves $ref into a real property instead of stranding the pointer', () => {
160 const provider = new OpenAIAgentsProvider();
161 provider._setExecuteToolFn(execute);
162
163 const wrapped = provider.wrapTool(baseTool, execute) as unknown as MockedOpenAIAgentTool;
164
165 // The non-strict branch rebuilds `{ type, properties, required }`, so a
166 // surviving `$ref` here would point at a `$defs` block that no longer
167 // exists in the emitted schema.
168 expect(containsInternalRef(wrapped.parameters)).toBe(false);
169 expect(wrapped.parameters.required).toContain('message');
170
171 const message = (wrapped.parameters.properties as Record<string, Record<string, unknown>>)
172 .message;
173 expect(message.type).toBe('object');
174 expect(Object.keys(message.properties as object)).toEqual(['subject', 'body']);
175 });
176
177 it('does not throw when the schema references undeclared $defs', () => {
178 const provider = new OpenAIAgentsProvider();
179 provider._setExecuteToolFn(execute);
180
181 expect(() => provider.wrapTool(danglingTool, execute)).not.toThrow();
182 });
183 });
184 });