Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 | }); |