Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsdeleted file mode 100644index 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();- });- });-});