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.

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

jkomyno98f16febcdd2
diff --git a/ts/packages/core/test/providers/refContract.test.ts b/ts/packages/core/test/providers/refContract.test.ts
new file mode 100644
index 000000000..375e6df89
--- /dev/null
+++ b/ts/packages/core/test/providers/refContract.test.ts
@@ -0,0 +1,196 @@
+/**
+ * Cross-provider `$ref` handling contract.
+ *
+ * The original bug was not that one provider mishandled `$ref` — it was that
+ * *six* did, silently, for months, because nothing enumerated the providers and
+ * asked the question. Two separate fixes (mastra, then anthropic) each solved it
+ * locally and neither surfaced the rest.
+ *
+ * This test enumerates every provider in the repo and requires each one to be
+ * classified below. Adding provider #11 without a classification fails the
+ * suite. That is the whole point: the taxonomy stops being tribal knowledge and
+ * becomes a build gate.
+ *
+ * It reads source text rather than importing the providers — importing all ten
+ * would drag in every vendor SDK as a test dependency of `@composio/core`. The
+ * behavioral assertions live in each provider's own package (see
+ * `providers/openai-agents/test/openai-agents-ref-schemas.test.ts`); this test
+ * owns *completeness*.
+ *
+ * Regenerated 2026-08-28 from its Python counterpart
+ * (`python/tests/test_provider_ref_contract.py`) after the original was lost in
+ * a session handoff; the original ratchets (`pending-plan-003`) were retired
+ * when the fix landed on `fix/deref-ref-schemas-in-providers`.
+ */
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+/** ts/packages/core/test/providers -> ts/packages */
+const packagesDir = path.resolve(here, '../../..');
+/** ts/packages -> repo root */
+const repoRoot = path.resolve(packagesDir, '../..');
+const providersDir = path.join(packagesDir, 'providers');
+
+/** A provider is "dereferencing" if its source calls this. */
+const DEREF_MARK = 'dereferenceJsonSchema';
+
+/**
+ * How each provider treats a tool's input schema.
+ *
+ * - `needs-deref`: the provider rebuilds the schema root from
+ * `properties`/`required`, or converts to Zod. Either way a `$ref` cannot
+ * survive intact, so the schema must be dereferenced first.
+ * - `passthrough`: the provider forwards the schema object whole. `$defs`
+ * travels with `$ref` and the vendor resolves it. Dereferencing here would
+ * cost tokens and, for vendors that support recursion, remove capability.
+ *
+ * `status` exists only for `needs-deref` entries that are not fixed yet; today
+ * there are none, but the ratchet below stays so the mechanism does not rot.
+ */
+type Treatment = 'needs-deref' | 'passthrough';
+
+interface Classification {
+ treatment: Treatment;
+ /** Present only while a needs-deref provider is known-broken. */
+ status?: `pending-plan-${string}`;
+ /** Why this provider is classified the way it is. */
+ reason: string;
+}
+
+const PROVIDER_PACKAGES: Record<string, Classification> = {
+ anthropic: {
+ treatment: 'needs-deref',
+ reason: 'sanitizes property keys, which requires keys behind a ref to be materialized',
+ },
+ mastra: {
+ treatment: 'needs-deref',
+ reason:
+ '@mastra/schema-compat (AJV) refuses unresolved $ref; its converter degrades refs to permissive anyOf',
+ },
+ langchain: {
+ treatment: 'needs-deref',
+ reason: 'converts to Zod; the converter has no $ref branch (degrades to z.any())',
+ },
+ llamaindex: {
+ treatment: 'needs-deref',
+ reason: 'converts to Zod; the converter has no $ref branch (degrades to z.any())',
+ },
+ 'claude-agent-sdk': {
+ treatment: 'needs-deref',
+ reason: 'converts to Zod; the converter has no $ref branch (degrades to z.any())',
+ },
+ vercel: {
+ treatment: 'needs-deref',
+ reason: 'converts to Zod on every path, not just the strict rewrite',
+ },
+ google: {
+ treatment: 'needs-deref',
+ reason:
+ 'rebuilds the root from properties/required; the @google/genai Schema proto has no ref/defs field',
+ },
+ 'openai-agents': {
+ treatment: 'needs-deref',
+ reason:
+ 'non-strict fallback rebuilds the root; the strict branch keeps refs on purpose (OpenAI resolves them natively)',
+ },
+ openai: {
+ treatment: 'passthrough',
+ reason:
+ 'forwards the whole schema; OpenAI resolves $defs/$ref natively (strict mode asserts this)',
+ },
+ cloudflare: {
+ treatment: 'passthrough',
+ reason: 'forwards the whole schema',
+ },
+};
+
+/** Non-`providers/` sources that also hand schemas to vendors. */
+const EXTRA_PASSTHROUGH_SOURCES: Record<string, string> = {
+ 'ts/packages/core/src/provider/OpenAIProvider.ts': 'forwards the whole schema',
+ 'ts/packages/experimental/src/eve/provider.ts': 'forwards the whole schema',
+};
+
+function listSourceFiles(dir: string): string[] {
+ const out: string[] = [];
+ for (const entry of readdirSync(dir)) {
+ const full = path.join(dir, entry);
+ if (statSync(full).isDirectory()) {
+ out.push(...listSourceFiles(full));
+ } else if (entry.endsWith('.ts') && !entry.endsWith('.d.ts')) {
+ out.push(full);
+ }
+ }
+ return out;
+}
+
+function packageText(provider: string): string {
+ return listSourceFiles(path.join(providersDir, provider, 'src'))
+ .map(file => readFileSync(file, 'utf8'))
+ .join('\n');
+}
+
+const DISCOVERED = readdirSync(providersDir).filter(
+ entry =>
+ statSync(path.join(providersDir, entry)).isDirectory() &&
+ existsSync(path.join(providersDir, entry, 'package.json')) &&
+ existsSync(path.join(providersDir, entry, 'src'))
+);
+
+describe('cross-provider $ref handling contract', () => {
+ it('discovers the provider packages', () => {
+ // Guards the test itself: a broken path would make everything below
+ // vacuously pass.
+ expect(DISCOVERED.length).toBeGreaterThanOrEqual(10);
+ });
+
+ it('classifies every provider package', () => {
+ const unclassified = DISCOVERED.filter(name => !(name in PROVIDER_PACKAGES));
+ expect(unclassified).toEqual([]);
+ });
+
+ it('does not classify providers that no longer exist', () => {
+ const stale = Object.keys(PROVIDER_PACKAGES).filter(name => !DISCOVERED.includes(name));
+ expect(stale).toEqual([]);
+ });
+
+ describe.each(Object.entries(PROVIDER_PACKAGES).filter(([, c]) => c.treatment === 'needs-deref'))(
+ '%s',
+ (provider, classification) => {
+ it(`dereferences before translation (${classification.reason})`, () => {
+ expect(packageText(provider)).toContain(DEREF_MARK);
+ });
+ }
+ );
+
+ describe.each(Object.entries(PROVIDER_PACKAGES).filter(([, c]) => c.treatment === 'passthrough'))(
+ '%s',
+ (provider, classification) => {
+ it(`forwards the schema whole (${classification.reason})`, () => {
+ expect(packageText(provider)).not.toContain(DEREF_MARK);
+ });
+ }
+ );
+
+ describe.each(Object.entries(EXTRA_PASSTHROUGH_SOURCES))('%s', (relPath, reason) => {
+ it(`forwards the schema whole (${reason})`, () => {
+ const full = path.join(repoRoot, relPath);
+ expect(existsSync(full), `${relPath} not found — update this test`).toBe(true);
+ expect(readFileSync(full, 'utf8')).not.toContain(DEREF_MARK);
+ });
+ });
+
+ // Ratchet, currently empty: when a needs-deref provider is added without its
+ // fix, give it `status: 'pending-plan-NNN'` and it is asserted NOT to
+ // dereference here — so the fix cannot land and leave the taxonomy stale
+ // (the assertion flips the moment the dereference call appears).
+ describe.each(
+ Object.entries(PROVIDER_PACKAGES).filter(([, c]) => c.status?.startsWith('pending-plan'))
+ )('%s', (provider, classification) => {
+ it(`is still pending (${classification.status})`, () => {
+ expect(packageText(provider)).not.toContain(DEREF_MARK);
+ });
+ });
+});
diff --git a/ts/packages/core/test/utils/jsonSchema.deref.property.test.ts b/ts/packages/core/test/utils/jsonSchema.deref.property.test.ts
new file mode 100644
index 000000000..b08c0c04a
--- /dev/null
+++ b/ts/packages/core/test/utils/jsonSchema.deref.property.test.ts
@@ -0,0 +1,374 @@
+/**
+ * Property tests for `dereferenceJsonSchema`.
+ *
+ * The example-based suite in `jsonSchema.test.ts` pins specific shapes. These
+ * tests pin *invariants* over a generated space of schemas, which is where the
+ * gaps were: sentinel-mode cycles, external refs surviving, `$ref`-shaped data
+ * sitting inside instance-value keywords, idempotence, and — the failure that
+ * originally motivated the helper — output that cannot be serialized.
+ *
+ * The generator is a small seeded PRNG rather than a property-testing library.
+ * Neither SDK has one today, and the Python counterpart
+ * (`python/tests/test_json_schema_properties.py`) mirrors this file's generator
+ * and invariants exactly; a library in one ecosystem and not the other would
+ * break that symmetry. Swapping in fast-check/hypothesis later is mechanical —
+ * the invariants below are the durable part.
+ *
+ * Failures are reproducible: every case prints its seed.
+ *
+ * Regenerated 2026-08-28 from the Python counterpart after the original was
+ * lost in a session handoff.
+ */
+import { describe, it, expect } from 'vitest';
+import { dereferenceJsonSchema } from '../../src/utils/jsonSchema';
+import { JsonSchemaRefResolutionError } from '../../src/errors';
+
+/** Deterministic PRNG so a failing case can be replayed from its seed. */
+function mulberry32(seed: number): () => number {
+ let a = seed >>> 0;
+ return () => {
+ a = (a + 0x6d2b79f5) >>> 0;
+ let t = Math.imul(a ^ (a >>> 15), 1 | a);
+ t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+ };
+}
+
+type Json = Record<string, unknown>;
+
+/** Keywords whose values are instance data — a `$ref` there is not a reference. */
+const INSTANCE_VALUE_KEYWORDS = new Set(['const', 'default', 'enum', 'examples']);
+
+const CASES = 300;
+const SEEDS = Array.from({ length: CASES }, (_, i) => 0x5eed + i * 7919);
+
+interface GeneratedDoc {
+ schema: Json;
+ /** True when the document contains at least one ref that cannot resolve. */
+ hasUnresolvable: boolean;
+}
+
+const pick = <T>(rng: () => number, items: readonly T[]): T =>
+ items[Math.floor(rng() * items.length)];
+
+/**
+ * Build a schema exercising every branch the dereferencer has: resolvable refs,
+ * chains, self-recursion, dangling pointers, external refs, legacy
+ * `definitions`, Draft 2020-12 siblings next to `$ref`, and `$ref`-shaped data
+ * parked inside instance-value keywords.
+ */
+function generateDoc(rng: () => number, withInstanceValueRefs = false): GeneratedDoc {
+ const chance = (p: number) => rng() < p;
+
+ // Definition names include JSON-Pointer escapes (`~0`/`~1`) and prototype
+ // keys; the clone step filters the latter (prototype pollution), so refs to
+ // them degrade to sentinels — a documented divergence from Python, which has
+ // no prototype to pollute.
+ const defNames = ['Alpha', 'Beta', 'Gamma', 'a/b', 'c~d', '__proto__', 'constructor'].slice(
+ 0,
+ 1 + Math.floor(rng() * 7)
+ );
+
+ const escapePointer = (name: string) => name.replace(/~/g, '~0').replace(/\//g, '~1');
+
+ const defsKey = chance(0.25) ? 'definitions' : '$defs';
+ const pointerTo = (name: string) => `#/${defsKey}/${escapePointer(name)}`;
+
+ const state = { hasUnresolvable: false };
+
+ const leaf = (): Json => {
+ const node: Json = { type: pick(rng, ['string', 'number', 'integer', 'boolean']) };
+ // `$ref`-shaped *data*. Only injected for the dedicated test block, so the
+ // other properties stay independent of the instance-value bug this module
+ // documents.
+ if (withInstanceValueRefs) {
+ if (chance(0.4)) node.default = { $ref: '#/$defs/NotARealReference' };
+ if (chance(0.4)) node.enum = [{ $ref: '#/$defs/AlsoNotOne' }];
+ }
+ return node;
+ };
+
+ const refNode = (): Json => {
+ const kind = pick(rng, [
+ 'resolvable',
+ 'resolvable',
+ 'resolvable',
+ 'dangling',
+ 'external',
+ 'whole-document',
+ 'deep',
+ ]);
+ let node: Json;
+ if (kind === 'whole-document') {
+ // `#` resolves to the root, always an ancestor, so this must come back
+ // as a cycle sentinel rather than diverging.
+ node = { $ref: '#' };
+ } else if (kind === 'deep') {
+ // Pointers are generic JSON Pointers, not `$defs`-only.
+ node = { $ref: `#/${defsKey}/${escapePointer(defNames[0])}/properties/value` };
+ } else if (kind === 'external') {
+ node = {
+ $ref: pick(rng, ['https://example.com/s.json', 'file:///tmp/s.json', 'other.json#/A']),
+ };
+ } else if (kind === 'dangling') {
+ state.hasUnresolvable = true;
+ node = { $ref: pointerTo('MissingDefinition') };
+ } else {
+ node = { $ref: pointerTo(pick(rng, defNames)) };
+ }
+ if (chance(0.3)) node.description = 'sibling description';
+ return node;
+ };
+
+ const subschema = (depth: number): Json => {
+ if (depth <= 0) return leaf();
+ const kind = pick(rng, ['object', 'array', 'ref', 'combinator', 'leaf']);
+ if (kind === 'object') {
+ const properties: Record<string, Json> = {};
+ const count = 1 + Math.floor(rng() * 3);
+ for (let i = 0; i < count; i++) properties[`p${i}`] = subschema(depth - 1);
+ const node: Json = { type: 'object', properties };
+ // A `$defs` block below the root is not stripped — only the root.
+ if (chance(0.2)) node.$defs = { Local: { type: 'string' } };
+ if (chance(0.4)) node.required = Object.keys(properties).slice(0, 1);
+ if (chance(0.3)) node.additionalProperties = subschema(depth - 1);
+ return node;
+ }
+ if (kind === 'array') return { type: 'array', items: subschema(depth - 1) };
+ if (kind === 'ref') return refNode();
+ if (kind === 'combinator') {
+ return { [pick(rng, ['anyOf', 'oneOf', 'allOf'])]: [subschema(depth - 1), leaf()] };
+ }
+ return leaf();
+ };
+
+ const defs: Record<string, Json> = {};
+ for (const name of defNames) {
+ const body: Json = { type: 'object', properties: { value: leaf() } };
+ // Self-recursion and cross-definition chains: neither has a finite inlined
+ // form, so the dereferencer must break them rather than diverge.
+ if (chance(0.35)) body.properties = { ...body.properties, self: { $ref: pointerTo(name) } };
+ if (chance(0.3)) {
+ body.properties = { ...body.properties, other: { $ref: pointerTo(pick(rng, defNames)) } };
+ }
+ defs[name] = body;
+ }
+
+ const rootProperties: Record<string, Json> = {};
+ const rootCount = 1 + Math.floor(rng() * 4);
+ for (let i = 0; i < rootCount; i++) rootProperties[`f${i}`] = subschema(3);
+
+ return {
+ schema: {
+ type: 'object',
+ properties: rootProperties,
+ required: Object.keys(rootProperties).slice(0, 2),
+ [defsKey]: defs,
+ },
+ hasUnresolvable: state.hasUnresolvable,
+ };
+}
+
+/** Yield every object reachable through *schema* positions only. */
+function* walkSchemaPositions(value: unknown): Generator<Json> {
+ if (Array.isArray(value)) {
+ for (const item of value) yield* walkSchemaPositions(item);
+ return;
+ }
+ if (value === null || typeof value !== 'object') return;
+ const node = value as Json;
+ yield node;
+ for (const [key, child] of Object.entries(node)) {
+ if (INSTANCE_VALUE_KEYWORDS.has(key)) continue;
+ yield* walkSchemaPositions(child);
+ }
+}
+
+const internalRefs = (value: unknown): string[] =>
+ [...walkSchemaPositions(value)]
+ .map(node => node.$ref)
+ .filter((ref): ref is string => typeof ref === 'string' && ref.startsWith('#'));
+
+const externalRefs = (value: unknown): string[] =>
+ [...walkSchemaPositions(value)]
+ .map(node => node.$ref)
+ .filter((ref): ref is string => typeof ref === 'string' && !ref.startsWith('#'));
+
+const instanceValues = (value: unknown): unknown[] => {
+ const found: unknown[] = [];
+ for (const node of walkSchemaPositions(value)) {
+ for (const [key, child] of Object.entries(node)) {
+ if (INSTANCE_VALUE_KEYWORDS.has(key)) found.push(child);
+ }
+ }
+ return found;
+};
+
+function forEachDoc(check: (doc: GeneratedDoc) => void, withInstanceValueRefs = false): void {
+ /** Run *check* over every generated document, reporting the failing seed. */
+ for (const seed of SEEDS) {
+ const doc = generateDoc(mulberry32(seed), withInstanceValueRefs);
+ try {
+ check(doc);
+ } catch (error) {
+ throw new Error(
+ `property failed for seed ${seed}\nschema: ${JSON.stringify(doc.schema, null, 2)}\n\n${String(error)}`
+ );
+ }
+ }
+}
+
+describe('dereferenceJsonSchema — sentinel-mode properties', () => {
+ it('never raises', () => {
+ forEachDoc(doc => {
+ dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
+ });
+ });
+
+ it('leaves no internal ref', () => {
+ forEachDoc(doc => {
+ const out = dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
+ expect(internalRefs(out)).toEqual([]);
+ });
+ });
+
+ it('strips root definition blocks', () => {
+ forEachDoc(doc => {
+ const out = dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' }) as Json;
+ expect('$defs' in out).toBe(false);
+ expect('definitions' in out).toBe(false);
+ });
+ });
+
+ it('preserves external refs', () => {
+ forEachDoc(doc => {
+ const before = new Set(externalRefs(doc.schema));
+ const out = dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
+ // Counts may grow (a def inlined at N sites carries its refs along),
+ // but nothing reachable in the source may disappear.
+ const after = new Set(externalRefs(out));
+ for (const ref of before)
+ expect(after.has(ref), `external ref disappeared: ${ref}`).toBe(true);
+ });
+ });
+
+ it('never mutates its input', () => {
+ forEachDoc(doc => {
+ const snapshot = structuredClone(doc.schema);
+ dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
+ expect(doc.schema).toEqual(snapshot);
+ });
+ });
+
+ it('returns serializable output', () => {
+ // The failure this helper exists to prevent: a dereferencer that keeps
+ // object identity on a recursive schema builds a real cycle, and
+ // serializing it for the vendor raises.
+ forEachDoc(doc => {
+ JSON.stringify(dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' }));
+ });
+ });
+
+ it('keeps definition blocks that are not at the root', () => {
+ forEachDoc(doc => {
+ // Only the root block is stripped. If a nested one was generated it
+ // survives — the docs claim this and nothing else pins it.
+ const input = JSON.stringify(doc.schema);
+ if (!input.includes('"Local"')) return;
+ const out = JSON.stringify(dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' }));
+ expect(out.includes('"Local"')).toBe(true);
+ });
+ });
+
+ it('does not blow up output size without bound', () => {
+ // Inlining is depth-bounded but breadth-unbounded: a def referenced N
+ // times is inlined N times. This does not assert a cap exists — it pins
+ // the growth factor for the shapes we generate, so a change that makes
+ // expansion dramatically worse is visible rather than silent.
+ forEachDoc(doc => {
+ const before = JSON.stringify(doc.schema).length;
+ const after = JSON.stringify(
+ dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' })
+ ).length;
+ expect(after).toBeLessThan(before * 50);
+ });
+ });
+
+ it('is idempotent', () => {
+ forEachDoc(doc => {
+ const once = dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
+ const twice = dereferenceJsonSchema(once, { onUnresolved: 'sentinel' });
+ expect(twice).toEqual(once);
+ });
+ });
+});
+
+/** Number of unresolvable refs sentinel mode had to replace. */
+function countReplacements(schema: Json): number {
+ let replacements = 0;
+ dereferenceJsonSchema(schema, {
+ onUnresolved: 'sentinel',
+ onReplace: () => {
+ replacements += 1;
+ },
+ });
+ return replacements;
+}
+
+describe('dereferenceJsonSchema — throw-mode properties', () => {
+ it('agrees with sentinel mode when everything resolves', () => {
+ forEachDoc(doc => {
+ if (countReplacements(doc.schema) > 0) return;
+ const strict = dereferenceJsonSchema(doc.schema);
+ const lenient = dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
+ expect(strict).toEqual(lenient);
+ });
+ });
+
+ it('raises exactly when sentinel mode replaced something', () => {
+ forEachDoc(doc => {
+ if (countReplacements(doc.schema) > 0) {
+ expect(() => dereferenceJsonSchema(doc.schema)).toThrow(JsonSchemaRefResolutionError);
+ } else {
+ dereferenceJsonSchema(doc.schema);
+ }
+ });
+ });
+});
+
+describe('dereferenceJsonSchema — instance-value keywords', () => {
+ // KNOWN BROKEN — ratchets, do not delete.
+ //
+ // `const`, `default`, `enum` and `examples` hold *instance data*, not
+ // subschemas, so a `{"$ref": ...}` inside one is an ordinary object that
+ // happens to have a `$ref` key — not a reference to resolve.
+ //
+ // `dereferenceJsonSchema` walks containers with no keyword check, so a tool
+ // whose schema carries `default: {"$ref": ...}` has that *value* rewritten
+ // into the unresolved sentinel. `INSTANCE_VALUE_KEYWORDS` exists
+ // (`jsonSchema.ts:36`) and is honored by `deduplicateJsonSchemaRequiredArrays`
+ // and `toStrictJsonSchema`, but not by the dereferencer. The Python port has
+ // the identical gap (`python/tests/test_json_schema_properties.py`).
+ //
+ // `it.fails` means these pass the suite while the bug exists; once the
+ // dereferencer stops walking instance-value keywords they start failing with
+ // "expected to fail but passed", forcing the marker's removal. A fix cannot
+ // land silently.
+ it.fails('does not rewrite $ref-shaped data', () => {
+ forEachDoc(doc => {
+ const out = dereferenceJsonSchema(doc.schema, { onUnresolved: 'sentinel' });
+ for (const value of instanceValues(out)) {
+ expect(JSON.stringify(value)).not.toContain('Schema shape unresolved at the source');
+ }
+ }, true);
+ });
+
+ it.fails('does not raise on $ref-shaped data', () => {
+ forEachDoc(doc => {
+ // Every pointer under the definitions block resolves; the only
+ // unresolvable strings live in `default`/`enum`, which are data.
+ if (doc.hasUnresolvable) return;
+ dereferenceJsonSchema(doc.schema);
+ }, true);
+ });
+});
diff --git a/ts/packages/providers/openai-agents/test/openai-agents-ref-schemas.test.ts b/ts/packages/providers/openai-agents/test/openai-agents-ref-schemas.test.ts
new file mode 100644
index 000000000..923b05b68
--- /dev/null
+++ b/ts/packages/providers/openai-agents/test/openai-agents-ref-schemas.test.ts
@@ -0,0 +1,184 @@
+/**
+ * `$ref` / `$defs` handling contract for OpenAIAgentsProvider.
+ *
+ * `wrapTool` has two independent branches with *opposite* correct behavior,
+ * and nothing previously pinned either of them:
+ *
+ * - the strict-structured-outputs branch must **keep** local `$ref`/`$defs`.
+ * OpenAI supports them natively, including recursion, and
+ * `toStrictJsonSchema` preserves them on purpose (see
+ * `ts/packages/core/src/utils/jsonSchema.ts`, "local `$ref`s into
+ * `$defs`/`definitions` are kept"). Inlining first would delete recursion
+ * support and multiply a shared `$def` against OpenAI's schema size caps.
+ * - the non-strict fallback rebuilds the root from `properties`/`required`,
+ * which drops `$defs` while leaving `$ref` pointers inside `properties`.
+ * That branch must therefore dereference *before* the rebuild.
+ *
+ * A change that "helpfully" dereferences everything up front satisfies the
+ * second requirement and silently violates the first. These tests exist to
+ * make that failure loud.
+ *
+ * Regenerated 2026-08-28 after the original was lost in a session handoff.
+ * The non-strict "resolves `$ref`" case below began life as an `it.fails`
+ * ratchet while the fallback still stranded pointers; landing
+ * `fix/deref-ref-schemas-in-providers` flipped it to a plain `it`, exactly as
+ * the ratchet's instructions required.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { OpenAIAgentsProvider } from '../src';
+import { Tool, ExecuteToolFn } from '@composio/core';
+
+interface MockedOpenAIAgentTool {
+ name: string;
+ description: string;
+ parameters: Record<string, unknown>;
+ strict: boolean;
+ execute: Function;
+}
+
+vi.mock('@openai/agents', () => ({
+ tool: vi.fn().mockImplementation(toolConfig => ({ ...toolConfig })),
+}));
+
+/** True when any node carries a `$ref` pointing inside this document. */
+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 baseTool: Tool = {
+ slug: 'REF_TOOL',
+ name: 'Ref Tool',
+ description: 'Tool whose schema reaches a property through $ref',
+ 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'],
+ },
+ },
+ },
+} as unknown as Tool;
+
+/** GMAIL_FETCH_EMAILS shape: a `$ref` into `$defs` that was never declared. */
+const danglingTool: Tool = {
+ ...baseTool,
+ slug: 'DANGLING_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: { message: { $ref: '#/$defs/Message' } },
+ required: ['message'],
+ },
+} as unknown as Tool;
+
+/** A legitimately recursive schema — no finite inlined form exists. */
+const recursiveTool: Tool = {
+ ...baseTool,
+ slug: 'RECURSIVE_REF_TOOL',
+ inputParameters: {
+ type: 'object',
+ properties: { node: { $ref: '#/$defs/Node' } },
+ required: ['node'],
+ $defs: {
+ Node: {
+ type: 'object',
+ properties: { label: { type: 'string' }, child: { $ref: '#/$defs/Node' } },
+ required: ['label'],
+ },
+ },
+ },
+} as unknown as Tool;
+
+describe('OpenAIAgentsProvider $ref handling', () => {
+ let execute: ExecuteToolFn;
+
+ beforeEach(() => {
+ execute = vi.fn().mockResolvedValue({
+ data: {},
+ error: null,
+ successful: true,
+ }) as unknown as ExecuteToolFn;
+ vi.clearAllMocks();
+ });
+
+ describe('strict mode must preserve references', () => {
+ it('keeps $defs and the $ref pointer instead of inlining them', () => {
+ const provider = new OpenAIAgentsProvider({ strict: true });
+ provider._setExecuteToolFn(execute);
+
+ const wrapped = provider.wrapTool(baseTool, execute) as unknown as MockedOpenAIAgentTool;
+
+ expect(wrapped.strict).toBe(true);
+ // The reference itself survives — OpenAI resolves it.
+ expect(wrapped.parameters.properties).toEqual({ message: { $ref: '#/$defs/Message' } });
+ // And the definition it points at travels with it.
+ expect(wrapped.parameters.$defs).toBeDefined();
+ expect((wrapped.parameters.$defs as Record<string, unknown>).Message).toMatchObject({
+ type: 'object',
+ });
+ });
+
+ it('keeps recursion expressible — a recursive $defs is not flattened', () => {
+ const provider = new OpenAIAgentsProvider({ strict: true });
+ provider._setExecuteToolFn(execute);
+
+ const wrapped = provider.wrapTool(recursiveTool, execute) as unknown as MockedOpenAIAgentTool;
+
+ // Dereferencing a recursive schema replaces the recursive branch with a
+ // permissive `{ type: 'object', additionalProperties: true }` sentinel.
+ // Strict mode must not pay that price: the self-reference stays intact.
+ const defs = wrapped.parameters.$defs as Record<string, Record<string, unknown>> | undefined;
+ expect(defs?.Node).toBeDefined();
+ const child = (defs?.Node.properties as Record<string, unknown>).child;
+ // `child` is optional, so strict mode widens it to an `anyOf` with a
+ // null branch. What matters is that the self-reference survives at all —
+ // an inlining pass would have replaced it with a permissive sentinel.
+ expect(containsInternalRef(child)).toBe(true);
+ expect(JSON.stringify(child)).toContain('#/$defs/Node');
+ });
+
+ it('falls back to non-strict on a dangling ref rather than throwing', () => {
+ const provider = new OpenAIAgentsProvider({ strict: true });
+ provider._setExecuteToolFn(execute);
+
+ expect(() => provider.wrapTool(danglingTool, execute)).not.toThrow();
+ });
+ });
+
+ describe('non-strict mode must not emit a dangling reference', () => {
+ it('resolves $ref into a real property instead of stranding the pointer', () => {
+ const provider = new OpenAIAgentsProvider();
+ provider._setExecuteToolFn(execute);
+
+ const wrapped = provider.wrapTool(baseTool, execute) as unknown as MockedOpenAIAgentTool;
+
+ // The non-strict branch rebuilds `{ type, properties, required }`, so a
+ // surviving `$ref` here would point at a `$defs` block that no longer
+ // exists in the emitted schema.
+ expect(containsInternalRef(wrapped.parameters)).toBe(false);
+ expect(wrapped.parameters.required).toContain('message');
+
+ const message = (wrapped.parameters.properties as Record<string, Record<string, unknown>>)
+ .message;
+ expect(message.type).toBe('object');
+ expect(Object.keys(message.properties as object)).toEqual(['subject', 'body']);
+ });
+
+ it('does not throw when the schema references undeclared $defs', () => {
+ const provider = new OpenAIAgentsProvider();
+ provider._setExecuteToolFn(execute);
+
+ expect(() => provider.wrapTool(danglingTool, execute)).not.toThrow();
+ });
+ });
+});
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
deleted file mode 100644
index 4964ff376..000000000
--- a/ts/packages/providers/openai-agents/test/openai-agents-ref.test.ts
+++ /dev/null
@@ -1,154 +0,0 @@
-/**
- * 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();
- });
- });
-});