@devries-cameron20 / composio Mirror · read-only / commits / 98f16febc
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, 14:45 UTC

test(core,providers): restore $ref contract and property suites

Regenerate the cross-provider $ref contract test, the dereferenceJsonSchema property tests, and the openai-agents $ref contract lost in a session handoff, ported from their surviving Python counterparts. The openai-agents non-strict ratchet flips to a plain it now that the fallback dereferences; the superseded openai-agents-ref.test.ts is removed in favor of the richer contract file.

jkomyno committed Aug 28, 2026 at 13:34 UTC 98f16febcdd2e28d42c12aa5af95ad350e3e5a8b
4 files changed +754 -154
ts/packages/core/test/providers/refContract.test.ts new
+196
@@ -0,0 +1,196 @@
1 +/**
2 + * Cross-provider `$ref` handling contract.
3 + *
4 + * The original bug was not that one provider mishandled `$ref` — it was that
5 + * *six* did, silently, for months, because nothing enumerated the providers and
6 + * asked the question. Two separate fixes (mastra, then anthropic) each solved it
7 + * locally and neither surfaced the rest.
8 + *
9 + * This test enumerates every provider in the repo and requires each one to be
10 + * classified below. Adding provider #11 without a classification fails the
11 + * suite. That is the whole point: the taxonomy stops being tribal knowledge and
12 + * becomes a build gate.
13 + *
14 + * It reads source text rather than importing the providers — importing all ten
15 + * would drag in every vendor SDK as a test dependency of `@composio/core`. The
16 + * behavioral assertions live in each provider's own package (see
17 + * `providers/openai-agents/test/openai-agents-ref-schemas.test.ts`); this test
18 + * owns *completeness*.
19 + *
20 + * Regenerated 2026-08-28 from its Python counterpart
21 + * (`python/tests/test_provider_ref_contract.py`) after the original was lost in
22 + * a session handoff; the original ratchets (`pending-plan-003`) were retired
23 + * when the fix landed on `fix/deref-ref-schemas-in-providers`.
24 + */
25 +import { describe, it, expect } from 'vitest';
26 +import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
27 +import path from 'node:path';
28 +import { fileURLToPath } from 'node:url';
29 +
30 +const here = path.dirname(fileURLToPath(import.meta.url));
31 +/** ts/packages/core/test/providers -> ts/packages */
32 +const packagesDir = path.resolve(here, '../../..');
33 +/** ts/packages -> repo root */
34 +const repoRoot = path.resolve(packagesDir, '../..');
35 +const providersDir = path.join(packagesDir, 'providers');
36 +
37 +/** A provider is "dereferencing" if its source calls this. */
38 +const DEREF_MARK = 'dereferenceJsonSchema';
39 +
40 +/**
41 + * How each provider treats a tool's input schema.
42 + *
43 + * - `needs-deref`: the provider rebuilds the schema root from
44 + * `properties`/`required`, or converts to Zod. Either way a `$ref` cannot
45 + * survive intact, so the schema must be dereferenced first.
46 + * - `passthrough`: the provider forwards the schema object whole. `$defs`
47 + * travels with `$ref` and the vendor resolves it. Dereferencing here would
48 + * cost tokens and, for vendors that support recursion, remove capability.
49 + *
50 + * `status` exists only for `needs-deref` entries that are not fixed yet; today
51 + * there are none, but the ratchet below stays so the mechanism does not rot.
52 + */
53 +type Treatment = 'needs-deref' | 'passthrough';
54 +
55 +interface Classification {
56 + treatment: Treatment;
57 + /** Present only while a needs-deref provider is known-broken. */
58 + status?: `pending-plan-${string}`;
59 + /** Why this provider is classified the way it is. */
60 + reason: string;
61 +}
62 +
63 +const PROVIDER_PACKAGES: Record<string, Classification> = {
64 + anthropic: {
65 + treatment: 'needs-deref',
66 + reason: 'sanitizes property keys, which requires keys behind a ref to be materialized',
67 + },
68 + mastra: {
69 + treatment: 'needs-deref',
70 + reason:
71 + '@mastra/schema-compat (AJV) refuses unresolved $ref; its converter degrades refs to permissive anyOf',
72 + },
73 + langchain: {
74 + treatment: 'needs-deref',
75 + reason: 'converts to Zod; the converter has no $ref branch (degrades to z.any())',
76 + },
77 + llamaindex: {
78 + treatment: 'needs-deref',
79 + reason: 'converts to Zod; the converter has no $ref branch (degrades to z.any())',
80 + },
81 + 'claude-agent-sdk': {
82 + treatment: 'needs-deref',
83 + reason: 'converts to Zod; the converter has no $ref branch (degrades to z.any())',
84 + },
85 + vercel: {
86 + treatment: 'needs-deref',
87 + reason: 'converts to Zod on every path, not just the strict rewrite',
88 + },
89 + google: {
90 + treatment: 'needs-deref',
91 + reason:
92 + 'rebuilds the root from properties/required; the @google/genai Schema proto has no ref/defs field',
93 + },
94 + 'openai-agents': {
95 + treatment: 'needs-deref',
96 + reason:
97 + 'non-strict fallback rebuilds the root; the strict branch keeps refs on purpose (OpenAI resolves them natively)',
98 + },
99 + openai: {
100 + treatment: 'passthrough',
101 + reason:
102 + 'forwards the whole schema; OpenAI resolves $defs/$ref natively (strict mode asserts this)',
103 + },
104 + cloudflare: {
105 + treatment: 'passthrough',
106 + reason: 'forwards the whole schema',
107 + },
108 +};
109 +
110 +/** Non-`providers/` sources that also hand schemas to vendors. */
111 +const EXTRA_PASSTHROUGH_SOURCES: Record<string, string> = {
112 + 'ts/packages/core/src/provider/OpenAIProvider.ts': 'forwards the whole schema',
113 + 'ts/packages/experimental/src/eve/provider.ts': 'forwards the whole schema',
114 +};
115 +
116 +function listSourceFiles(dir: string): string[] {
117 + const out: string[] = [];
118 + for (const entry of readdirSync(dir)) {
119 + const full = path.join(dir, entry);
120 + if (statSync(full).isDirectory()) {
121 + out.push(...listSourceFiles(full));
122 + } else if (entry.endsWith('.ts') && !entry.endsWith('.d.ts')) {
123 + out.push(full);
124 + }
125 + }
126 + return out;
127 +}
128 +
129 +function packageText(provider: string): string {
130 + return listSourceFiles(path.join(providersDir, provider, 'src'))
131 + .map(file => readFileSync(file, 'utf8'))
132 + .join('\n');
133 +}
134 +
135 +const DISCOVERED = readdirSync(providersDir).filter(
136 + entry =>
137 + statSync(path.join(providersDir, entry)).isDirectory() &&
138 + existsSync(path.join(providersDir, entry, 'package.json')) &&
139 + existsSync(path.join(providersDir, entry, 'src'))
140 +);
141 +
142 +describe('cross-provider $ref handling contract', () => {
143 + it('discovers the provider packages', () => {
144 + // Guards the test itself: a broken path would make everything below
145 + // vacuously pass.
146 + expect(DISCOVERED.length).toBeGreaterThanOrEqual(10);
147 + });
148 +
149 + it('classifies every provider package', () => {
150 + const unclassified = DISCOVERED.filter(name => !(name in PROVIDER_PACKAGES));
151 + expect(unclassified).toEqual([]);
152 + });
153 +
154 + it('does not classify providers that no longer exist', () => {
155 + const stale = Object.keys(PROVIDER_PACKAGES).filter(name => !DISCOVERED.includes(name));
156 + expect(stale).toEqual([]);
157 + });
158 +
159 + describe.each(Object.entries(PROVIDER_PACKAGES).filter(([, c]) => c.treatment === 'needs-deref'))(
160 + '%s',
161 + (provider, classification) => {
162 + it(`dereferences before translation (${classification.reason})`, () => {
163 + expect(packageText(provider)).toContain(DEREF_MARK);
164 + });
165 + }
166 + );
167 +
168 + describe.each(Object.entries(PROVIDER_PACKAGES).filter(([, c]) => c.treatment === 'passthrough'))(
169 + '%s',
170 + (provider, classification) => {
171 + it(`forwards the schema whole (${classification.reason})`, () => {
172 + expect(packageText(provider)).not.toContain(DEREF_MARK);
173 + });
174 + }
175 + );
176 +
177 + describe.each(Object.entries(EXTRA_PASSTHROUGH_SOURCES))('%s', (relPath, reason) => {
178 + it(`forwards the schema whole (${reason})`, () => {
179 + const full = path.join(repoRoot, relPath);
180 + expect(existsSync(full), `${relPath} not found — update this test`).toBe(true);
181 + expect(readFileSync(full, 'utf8')).not.toContain(DEREF_MARK);
182 + });
183 + });
184 +
185 + // Ratchet, currently empty: when a needs-deref provider is added without its
186 + // fix, give it `status: 'pending-plan-NNN'` and it is asserted NOT to
187 + // dereference here — so the fix cannot land and leave the taxonomy stale
188 + // (the assertion flips the moment the dereference call appears).
189 + describe.each(
190 + Object.entries(PROVIDER_PACKAGES).filter(([, c]) => c.status?.startsWith('pending-plan'))
191 + )('%s', (provider, classification) => {
192 + it(`is still pending (${classification.status})`, () => {
193 + expect(packageText(provider)).not.toContain(DEREF_MARK);
194 + });
195 + });
196 +});
ts/packages/core/test/utils/jsonSchema.deref.property.test.ts new
+374
@@ -0,0 +1,374 @@
1 +/**
2 + * Property tests for `dereferenceJsonSchema`.
3 + *
4 + * The example-based suite in `jsonSchema.test.ts` pins specific shapes. These
5 + * tests pin *invariants* over a generated space of schemas, which is where the
6 + * gaps were: sentinel-mode cycles, external refs surviving, `$ref`-shaped data
7 + * sitting inside instance-value keywords, idempotence, and — the failure that
8 + * originally motivated the helper — output that cannot be serialized.
9 + *
10 + * The generator is a small seeded PRNG rather than a property-testing library.
11 + * Neither SDK has one today, and the Python counterpart
12 + * (`python/tests/test_json_schema_properties.py`) mirrors this file's generator
13 + * and invariants exactly; a library in one ecosystem and not the other would
14 + * break that symmetry. Swapping in fast-check/hypothesis later is mechanical —
15 + * the invariants below are the durable part.
16 + *
17 + * Failures are reproducible: every case prints its seed.
18 + *
19 + * Regenerated 2026-08-28 from the Python counterpart after the original was
20 + * lost in a session handoff.
21 + */
22 +import { describe, it, expect } from 'vitest';
23 +import { dereferenceJsonSchema } from '../../src/utils/jsonSchema';
24 +import { JsonSchemaRefResolutionError } from '../../src/errors';
25 +
26 +/** Deterministic PRNG so a failing case can be replayed from its seed. */
27 +function mulberry32(seed: number): () => number {
28 + let a = seed >>> 0;
29 + return () => {
30 + a = (a + 0x6d2b79f5) >>> 0;
31 + let t = Math.imul(a ^ (a >>> 15), 1 | a);
32 + t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
33 + return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
34 + };
35 +}
36 +
37 +type Json = Record<string, unknown>;
38 +
39 +/** Keywords whose values are instance data — a `$ref` there is not a reference. */
40 +const INSTANCE_VALUE_KEYWORDS = new Set(['const', 'default', 'enum', 'examples']);
41 +
42 +const CASES = 300;
43 +const SEEDS = Array.from({ length: CASES }, (_, i) => 0x5eed + i * 7919);
44 +
45 +interface GeneratedDoc {
46 + schema: Json;
47 + /** True when the document contains at least one ref that cannot resolve. */
48 + hasUnresolvable: boolean;
49 +}
50 +
51 +const pick = <T>(rng: () => number, items: readonly T[]): T =>
52 + items[Math.floor(rng() * items.length)];
53 +
54 +/**
55 + * Build a schema exercising every branch the dereferencer has: resolvable refs,
56 + * chains, self-recursion, dangling pointers, external refs, legacy
57 + * `definitions`, Draft 2020-12 siblings next to `$ref`, and `$ref`-shaped data
58 + * parked inside instance-value keywords.
59 + */
60 +function generateDoc(rng: () => number, withInstanceValueRefs = false): GeneratedDoc {
61 + const chance = (p: number) => rng() < p;
62 +
63 + // Definition names include JSON-Pointer escapes (`~0`/`~1`) and prototype
64 + // keys; the clone step filters the latter (prototype pollution), so refs to
65 + // them degrade to sentinels — a documented divergence from Python, which has
66 + // no prototype to pollute.
67 + const defNames = ['Alpha', 'Beta', 'Gamma', 'a/b', 'c~d', '__proto__', 'constructor'].slice(
68 + 0,
69 + 1 + Math.floor(rng() * 7)
70 + );
71 +
72 + const escapePointer = (name: string) => name.replace(/~/g, '~0').replace(/\//g, '~1');
73 +
74 + const defsKey = chance(0.25) ? 'definitions' : '$defs';
75 + const pointerTo = (name: string) => `#/${defsKey}/${escapePointer(name)}`;
76 +
77 + const state = { hasUnresolvable: false };
78 +
79 + const leaf = (): Json => {
80 + const node: Json = { type: pick(rng, ['string', 'number', 'integer', 'boolean']) };
81 + // `$ref`-shaped *data*. Only injected for the dedicated test block, so the
82 + // other properties stay independent of the instance-value bug this module
83 + // documents.
84 + if (withInstanceValueRefs) {
85 + if (chance(0.4)) node.default = { $ref: '#/$defs/NotARealReference' };
86 + if (chance(0.4)) node.enum = [{ $ref: '#/$defs/AlsoNotOne' }];
87 + }
88 + return node;
89 + };
90 +
91 + const refNode = (): Json => {
92 + const kind = pick(rng, [
93 + 'resolvable',
94 + 'resolvable',
95 + 'resolvable',
96 + 'dangling',
97 + 'external',
98 + 'whole-document',
99 + 'deep',
100 + ]);
101 + let node: Json;
102 + if (kind === 'whole-document') {
103 + // `#` resolves to the root, always an ancestor, so this must come back
104 + // as a cycle sentinel rather than diverging.
105 + node = { $ref: '#' };
106 + } else if (kind === 'deep') {
107 + // Pointers are generic JSON Pointers, not `$defs`-only.
108 + node = { $ref: `#/${defsKey}/${escapePointer(defNames[0])}/properties/value` };
109 + } else if (kind === 'external') {
110 + node = {
111 + $ref: pick(rng, ['https://example.com/s.json', 'file:///tmp/s.json', 'other.json#/A']),
112 + };
113 + } else if (kind === 'dangling') {
114 + state.hasUnresolvable = true;
115 + node = { $ref: pointerTo('MissingDefinition') };
116 + } else {
117 + node = { $ref: pointerTo(pick(rng, defNames)) };
118 + }
119 + if (chance(0.3)) node.description = 'sibling description';
120 + return node;
121 + };
122 +
123 + const subschema = (depth: number): Json => {
124 + if (depth <= 0) return leaf();
125 + const kind = pick(rng, ['object', 'array', 'ref', 'combinator', 'leaf']);
126 + if (kind === 'object') {
127 + const properties: Record<string, Json> = {};
128 + const count = 1 + Math.floor(rng() * 3);
129 + for (let i = 0; i < count; i++) properties[`p${i}`] = subschema(depth - 1);
130 + const node: Json = { type: 'object', properties };
131 + // A `$defs` block below the root is not stripped — only the root.
132 + if (chance(0.2)) node.$defs = { Local: { type: 'string' } };
133 + if (chance(0.4)) node.required = Object.keys(properties).slice(0, 1);
134 + if (chance(0.3)) node.additionalProperties = subschema(depth - 1);
135 + return node;
136 + }
137 + if (kind === 'array') return { type: 'array', items: subschema(depth - 1) };
138 + if (kind === 'ref') return refNode();
139 + if (kind === 'combinator') {
140 + return { [pick(rng, ['anyOf', 'oneOf', 'allOf'])]: [subschema(depth - 1), leaf()] };
141 + }
142 + return leaf();
143 + };
144 +
145 + const defs: Record<string, Json> = {};
146 + for (const name of defNames) {
147 + const body: Json = { type: 'object', properties: { value: leaf() } };
148 + // Self-recursion and cross-definition chains: neither has a finite inlined
149 + // form, so the dereferencer must break them rather than diverge.
150 + if (chance(0.35)) body.properties = { ...body.properties, self: { $ref: pointerTo(name) } };
151 + if (chance(0.3)) {
152 + body.properties = { ...body.properties, other: { $ref: pointerTo(pick(rng, defNames)) } };
153 + }
154 + defs[name] = body;
155 + }
156 +
157 + const rootProperties: Record<string, Json> = {};
158 + const rootCount = 1 + Math.floor(rng() * 4);
159 + for (let i = 0; i < rootCount; i++) rootProperties[`f${i}`] = subschema(3);
160 +
161 + return {
162 + schema: {
163 + type: 'object',
164 + properties: rootProperties,
165 + required: Object.keys(rootProperties).slice(0, 2),
166 + [defsKey]: defs,
167 + },
168 + hasUnresolvable: state.hasUnresolvable,
169 + };
170 +}
171 +
172 +/** Yield every object reachable through *schema* positions only. */
173 +function* walkSchemaPositions(value: unknown): Generator<Json> {
174 + if (Array.isArray(value)) {
175 + for (const item of value) yield* walkSchemaPositions(item);
176 + return;
177 + }
178 + if (value === null || typeof value !== 'object') return;
179 + const node = value as Json;
180 + yield node;
181 + for (const [key, child] of Object.entries(node)) {
182 + if (INSTANCE_VALUE_KEYWORDS.has(key)) continue;
183 + yield* walkSchemaPositions(child);
184 + }
185 +}
186 +
187 +const internalRefs = (value: unknown): string[] =>
188 + [...walkSchemaPositions(value)]
189 + .map(node => node.$ref)
190 + .filter((ref): ref is string => typeof ref === 'string' && ref.startsWith('#'));
191 +
192 +const externalRefs = (value: unknown): string[] =>
193 + [...walkSchemaPositions(value)]
194 + .map(node => node.$ref)
195 + .filter((ref): ref is string => typeof ref === 'string' && !ref.startsWith('#'));
196 +
197 +const instanceValues = (value: unknown): unknown[] => {
198 + const found: unknown[] = [];
199 + for (const node of walkSchemaPositions(value)) {
200 + for (const [key, child] of Object.entries(node)) {
201 + if (INSTANCE_VALUE_KEYWORDS.has(key)) found.push(child);
202 + }
203 + }
204 + return found;
205 +};
206 +
207 +function forEachDoc(check: (doc: GeneratedDoc) => void, withInstanceValueRefs = false): void {
208 + /** Run *check* over every generated document, reporting the failing seed. */
209 + for (const seed of SEEDS) {
210 + const doc = generateDoc(mulberry32(seed), withInstanceValueRefs);
211 + try {
212 + check(doc);
213 + } catch (error) {
214 + throw new Error(
215 + `property failed for seed ${seed}\nschema: ${JSON.stringify(doc.schema, null, 2)}\n\n${String(error)}`
216 + );
217 + }
218 + }
219 +}
220 +
221 +describe('dereferenceJsonSchema — sentinel-mode properties', () => {
222 + it('never raises', () => {
223 + forEachDoc(doc => {
224 + dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
225 + });
226 + });
227 +
228 + it('leaves no internal ref', () => {
229 + forEachDoc(doc => {
230 + const out = dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
231 + expect(internalRefs(out)).toEqual([]);
232 + });
233 + });
234 +
235 + it('strips root definition blocks', () => {
236 + forEachDoc(doc => {
237 + const out = dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' }) as Json;
238 + expect('$defs' in out).toBe(false);
239 + expect('definitions' in out).toBe(false);
240 + });
241 + });
242 +
243 + it('preserves external refs', () => {
244 + forEachDoc(doc => {
245 + const before = new Set(externalRefs(doc.schema));
246 + const out = dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
247 + // Counts may grow (a def inlined at N sites carries its refs along),
248 + // but nothing reachable in the source may disappear.
249 + const after = new Set(externalRefs(out));
250 + for (const ref of before)
251 + expect(after.has(ref), `external ref disappeared: ${ref}`).toBe(true);
252 + });
253 + });
254 +
255 + it('never mutates its input', () => {
256 + forEachDoc(doc => {
257 + const snapshot = structuredClone(doc.schema);
258 + dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
259 + expect(doc.schema).toEqual(snapshot);
260 + });
261 + });
262 +
263 + it('returns serializable output', () => {
264 + // The failure this helper exists to prevent: a dereferencer that keeps
265 + // object identity on a recursive schema builds a real cycle, and
266 + // serializing it for the vendor raises.
267 + forEachDoc(doc => {
268 + JSON.stringify(dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' }));
269 + });
270 + });
271 +
272 + it('keeps definition blocks that are not at the root', () => {
273 + forEachDoc(doc => {
274 + // Only the root block is stripped. If a nested one was generated it
275 + // survives — the docs claim this and nothing else pins it.
276 + const input = JSON.stringify(doc.schema);
277 + if (!input.includes('"Local"')) return;
278 + const out = JSON.stringify(dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' }));
279 + expect(out.includes('"Local"')).toBe(true);
280 + });
281 + });
282 +
283 + it('does not blow up output size without bound', () => {
284 + // Inlining is depth-bounded but breadth-unbounded: a def referenced N
285 + // times is inlined N times. This does not assert a cap exists — it pins
286 + // the growth factor for the shapes we generate, so a change that makes
287 + // expansion dramatically worse is visible rather than silent.
288 + forEachDoc(doc => {
289 + const before = JSON.stringify(doc.schema).length;
290 + const after = JSON.stringify(
291 + dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' })
292 + ).length;
293 + expect(after).toBeLessThan(before * 50);
294 + });
295 + });
296 +
297 + it('is idempotent', () => {
298 + forEachDoc(doc => {
299 + const once = dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
300 + const twice = dereferenceJsonSchema(once, { onUnresolved: 'sentinel' });
301 + expect(twice).toEqual(once);
302 + });
303 + });
304 +});
305 +
306 +/** Number of unresolvable refs sentinel mode had to replace. */
307 +function countReplacements(schema: Json): number {
308 + let replacements = 0;
309 + dereferenceJsonSchema(schema, {
310 + onUnresolved: 'sentinel',
311 + onReplace: () => {
312 + replacements += 1;
313 + },
314 + });
315 + return replacements;
316 +}
317 +
318 +describe('dereferenceJsonSchema — throw-mode properties', () => {
319 + it('agrees with sentinel mode when everything resolves', () => {
320 + forEachDoc(doc => {
321 + if (countReplacements(doc.schema) > 0) return;
322 + const strict = dereferenceJsonSchema(doc.schema);
323 + const lenient = dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
324 + expect(strict).toEqual(lenient);
325 + });
326 + });
327 +
328 + it('raises exactly when sentinel mode replaced something', () => {
329 + forEachDoc(doc => {
330 + if (countReplacements(doc.schema) > 0) {
331 + expect(() => dereferenceJsonSchema(doc.schema)).toThrow(JsonSchemaRefResolutionError);
332 + } else {
333 + dereferenceJsonSchema(doc.schema);
334 + }
335 + });
336 + });
337 +});
338 +
339 +describe('dereferenceJsonSchema — instance-value keywords', () => {
340 + // KNOWN BROKEN — ratchets, do not delete.
341 + //
342 + // `const`, `default`, `enum` and `examples` hold *instance data*, not
343 + // subschemas, so a `{"$ref": ...}` inside one is an ordinary object that
344 + // happens to have a `$ref` key — not a reference to resolve.
345 + //
346 + // `dereferenceJsonSchema` walks containers with no keyword check, so a tool
347 + // whose schema carries `default: {"$ref": ...}` has that *value* rewritten
348 + // into the unresolved sentinel. `INSTANCE_VALUE_KEYWORDS` exists
349 + // (`jsonSchema.ts:36`) and is honored by `deduplicateJsonSchemaRequiredArrays`
350 + // and `toStrictJsonSchema`, but not by the dereferencer. The Python port has
351 + // the identical gap (`python/tests/test_json_schema_properties.py`).
352 + //
353 + // `it.fails` means these pass the suite while the bug exists; once the
354 + // dereferencer stops walking instance-value keywords they start failing with
355 + // "expected to fail but passed", forcing the marker's removal. A fix cannot
356 + // land silently.
357 + it.fails('does not rewrite $ref-shaped data', () => {
358 + forEachDoc(doc => {
359 + const out = dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
360 + for (const value of instanceValues(out)) {
361 + expect(JSON.stringify(value)).not.toContain('Schema shape unresolved at the source');
362 + }
363 + }, true);
364 + });
365 +
366 + it.fails('does not raise on $ref-shaped data', () => {
367 + forEachDoc(doc => {
368 + // Every pointer under the definitions block resolves; the only
369 + // unresolvable strings live in `default`/`enum`, which are data.
370 + if (doc.hasUnresolvable) return;
371 + dereferenceJsonSchema(doc.schema);
372 + }, true);
373 + });
374 +});
ts/packages/providers/openai-agents/test/openai-agents-ref-schemas.test.ts new
+184
@@ -0,0 +1,184 @@
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 +});
ts/packages/providers/openai-agents/test/openai-agents-ref.test.ts deleted
-154
@@ -1,154 +0,0 @@
1 -/**
2 - * Regression test: `OpenAIAgentsProvider.wrapTool`'s non-strict fallback
3 - * rebuilds the root schema from `properties`/`required`, which used to
4 - * discard the `$defs` block while `$ref` pointers inside `properties`
5 - * stayed dangling. `wrapTool` now dereferences `$ref`/`$defs` before that
6 - * rebuild.
7 - *
8 - * The strict branch is intentionally different: OpenAI's structured outputs
9 - * support `$defs`/`$ref` natively, including recursion, so `toStrictJsonSchema`
10 - * keeps local refs rather than inlining them. This file also guards that the
11 - * strict branch stays untouched by the fix applied to the fallback.
12 - */
13 -
14 -import { describe, it, expect, vi, beforeEach } from 'vitest';
15 -import type { Tool, ExecuteToolFn } from '@composio/core';
16 -import { OpenAIAgentsProvider } from '../src';
17 -
18 -interface MockedOpenAIAgentTool {
19 - name: string;
20 - description: string;
21 - parameters: Record<string, unknown>;
22 - strict: boolean;
23 - execute: Function;
24 - _isMockedOpenAIAgentTool: boolean;
25 -}
26 -
27 -// Mock the @openai/agents module (per-file scoping keeps this independent of
28 -// openai-agents.test.ts).
29 -vi.mock('@openai/agents', () => {
30 - return {
31 - tool: vi.fn().mockImplementation(toolConfig => {
32 - return {
33 - ...toolConfig,
34 - _isMockedOpenAIAgentTool: true,
35 - } as MockedOpenAIAgentTool;
36 - }),
37 - };
38 -});
39 -
40 -const containsInternalRef = (value: unknown): boolean => {
41 - if (value === null || typeof value !== 'object') return false;
42 - if (Array.isArray(value)) return value.some(containsInternalRef);
43 - const node = value as Record<string, unknown>;
44 - if (typeof node.$ref === 'string' && node.$ref.startsWith('#')) return true;
45 - return Object.values(node).some(containsInternalRef);
46 -};
47 -
48 -const refTool: Tool = {
49 - slug: 'TEST_REF_TOOL',
50 - name: 'Ref Tool',
51 - description: 'Tool whose schema carries internal $ref pointers',
52 - toolkit: { slug: 'reftoolkit', name: 'Ref Toolkit' },
53 - version: '20260828_00',
54 - availableVersions: ['20260828_00'],
55 - tags: [],
56 - inputParameters: {
57 - type: 'object',
58 - properties: {
59 - message: { $ref: '#/$defs/Message' },
60 - },
61 - required: ['message'],
62 - $defs: {
63 - Message: {
64 - type: 'object',
65 - properties: {
66 - subject: { type: 'string' },
67 - body: { type: 'string' },
68 - },
69 - required: ['subject', 'body'],
70 - additionalProperties: false,
71 - },
72 - },
73 - } as unknown as Tool['inputParameters'],
74 -} as unknown as Tool;
75 -
76 -const danglingRefTool: Tool = {
77 - ...refTool,
78 - slug: 'TEST_DANGLING_REF_TOOL',
79 - inputParameters: {
80 - type: 'object',
81 - properties: {
82 - message: { $ref: '#/$defs/Message' },
83 - },
84 - required: ['message'],
85 - } as unknown as Tool['inputParameters'],
86 -};
87 -
88 -const recursiveRefTool: Tool = {
89 - ...refTool,
90 - slug: 'TEST_RECURSIVE_REF_TOOL',
91 - inputParameters: {
92 - type: 'object',
93 - properties: {
94 - node: { $ref: '#/$defs/Node' },
95 - },
96 - required: ['node'],
97 - $defs: {
98 - Node: {
99 - type: 'object',
100 - properties: {
101 - value: { type: 'string' },
102 - child: { $ref: '#/$defs/Node' },
103 - },
104 - required: ['value'],
105 - },
106 - },
107 - } as unknown as Tool['inputParameters'],
108 -};
109 -
110 -describe('OpenAIAgentsProvider regression: $ref in JSON Schema', () => {
111 - let provider: OpenAIAgentsProvider;
112 - let executeToolFn: ExecuteToolFn;
113 -
114 - beforeEach(() => {
115 - provider = new OpenAIAgentsProvider();
116 - executeToolFn = vi.fn().mockResolvedValue({
117 - data: {},
118 - error: null,
119 - successful: true,
120 - }) as unknown as ExecuteToolFn;
121 - vi.clearAllMocks();
122 - });
123 -
124 - describe('non-strict fallback (bucket B fix)', () => {
125 - it('inlines internal $ref/$defs instead of stranding a dangling pointer', () => {
126 - const wrapped = provider.wrapTool(refTool, executeToolFn) as unknown as MockedOpenAIAgentTool;
127 -
128 - expect(containsInternalRef(wrapped.parameters)).toBe(false);
129 - expect(wrapped.parameters.required).toContain('message');
130 - });
131 -
132 - it('does not throw when $ref points into an undeclared $defs block', () => {
133 - expect(() => provider.wrapTool(danglingRefTool, executeToolFn)).not.toThrow();
134 - });
135 -
136 - it('does not throw on a self-referential $defs schema', () => {
137 - expect(() => provider.wrapTool(recursiveRefTool, executeToolFn)).not.toThrow();
138 - });
139 - });
140 -
141 - describe('strict branch (must stay untouched)', () => {
142 - it('keeps $defs and the $ref pointer intact under strict mode', () => {
143 - const strictProvider = new OpenAIAgentsProvider({ strict: true });
144 - const wrapped = strictProvider.wrapTool(
145 - refTool,
146 - executeToolFn
147 - ) as unknown as MockedOpenAIAgentTool;
148 -
149 - expect(wrapped.strict).toBe(true);
150 - expect(containsInternalRef(wrapped.parameters)).toBe(true);
151 - expect(wrapped.parameters.$defs).toBeDefined();
152 - });
153 - });
154 -});