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