@cleocode/adapters 2026.4.91 → 2026.4.94

package/src/providers/openai-sdk/__tests__/openai-sdk-spawn.test.ts

@@ -1,8 +1,8 @@
 /**
- * Tests for the OpenAI Agents SDK spawn provider.
+ * Tests for the OpenAI SDK spawn provider — Vercel AI SDK edition.
  *
- * All OpenAI SDK calls are mocked — no real API keys or network calls
- * are required to run this suite.
+ * All LLM calls are mocked — no real API keys or network calls are required
+ * to run this suite.
  *
  * Test coverage:
  * - GuardrailTests: path ACL logic and guardrail builders
@@ -11,9 +11,10 @@
  * - AdapterTests: identity, capabilities, initialize, dispose, healthCheck
  * - InstallProviderTests: isInstalled, install, uninstall
  * - TraceProcessorTests: onSpanEnd event capture
- * - HandoffIntegrationTest: lead + worker topology with mocked runner
+ * - HandoffIntegrationTest: lead + worker topology with mocked generateText
  *
- * @task T582
+ * @task T582 (original)
+ * @task T933 (SDK consolidation — Vercel AI SDK migration)
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -22,61 +23,33 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 // Hoist shared state so vi.mock factories can reference it
 // ---------------------------------------------------------------------------
 
-const { createdAgents, mockRunState, mockFsState } = vi.hoisted(() => {
+const { generateTextCalls, mockRunState, mockFsState } = vi.hoisted(() => {
   return {
-    createdAgents: [] as Array<{ name?: string; handoffs?: unknown[]; model?: string }>,
-    mockRunState: { result: { finalOutput: 'mock output' }, shouldThrow: false },
+    generateTextCalls: [] as Array<{ model: unknown; system?: string; prompt: string }>,
+    mockRunState: { output: 'mock output', shouldThrow: false },
     mockFsState: { exists: false, content: '' },
   };
 });
 
 // ---------------------------------------------------------------------------
-// Mock @openai/agents
+// Mock Vercel AI SDK surface — @ai-sdk/openai + ai/generateText
 // ---------------------------------------------------------------------------
 
-vi.mock('@openai/agents', () => {
-  class MockAgent {
-    name: string;
-    handoffs: unknown[];
-    model: string;
-    inputGuardrails: unknown[];
-    instructions: string;
-
-    constructor(opts: {
-      name?: string;
-      instructions?: string;
-      model?: string;
-      handoffs?: unknown[];
-      inputGuardrails?: unknown[];
-    }) {
-      this.name = opts.name ?? 'agent';
-      this.instructions = opts.instructions ?? '';
-      this.model = opts.model ?? 'gpt-4.1';
-      this.handoffs = opts.handoffs ?? [];
-      this.inputGuardrails = opts.inputGuardrails ?? [];
-      createdAgents.push({ name: this.name, handoffs: this.handoffs, model: this.model });
-    }
-  }
-
-  const mockRunFn = async (agent: { name: string }) => {
-    if (mockRunState.shouldThrow) throw new Error('mock SDK error');
-    return { ...mockRunState.result, _agent: agent };
-  };
-
-  class MockRunner {
-    run = vi.fn(mockRunFn);
-  }
-
-  class MockOpenAIProvider {}
+vi.mock('@ai-sdk/openai', () => ({
+  createOpenAI: vi.fn((_config: { apiKey: string }) => {
+    return (modelId: string) => ({ __cleoMockModel: true, modelId });
+  }),
+}));
 
-  return {
-    Agent: MockAgent,
-    Runner: MockRunner,
-    OpenAIProvider: MockOpenAIProvider,
-    addTraceProcessor: vi.fn(),
-    setTracingDisabled: vi.fn(),
-  };
-});
+vi.mock('ai', () => ({
+  generateText: vi.fn(
+    async ({ model, system, prompt }: { model: unknown; system?: string; prompt: string }) => {
+      generateTextCalls.push({ model, system, prompt });
+      if (mockRunState.shouldThrow) throw new Error('mock SDK error');
+      return { text: mockRunState.output };
+    },
+  ),
+}));
 
 // ---------------------------------------------------------------------------
 // Mock node:fs for install provider tests
@@ -124,6 +97,7 @@ import {
   buildDefaultGuardrails,
   buildPathGuardrail,
   buildToolAllowlistGuardrail,
+  evaluateGuardrails,
   isPathAllowed,
 } from '../guardrails.js';
 import {
@@ -131,17 +105,18 @@ import {
   buildLeadAgent,
   buildStandaloneAgent,
   buildWorkerAgent,
+  type CleoAgent,
   WORKER_ARCHETYPES,
 } from '../handoff.js';
 import { OpenAiSdkInstallProvider } from '../install.js';
 import { OpenAiSdkSpawnProvider } from '../spawn.js';
-import { CleoConduitTraceProcessor } from '../tracing.js';
+import { CleoConduitTraceProcessor, type CleoSpan } from '../tracing.js';
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-function makeSpanLike(overrides: Record<string, unknown> = {}): unknown {
+function makeSpanLike(overrides: Partial<CleoSpan> = {}): CleoSpan {
   return {
     spanId: 'span-001',
     startedAt: new Date().toISOString(),
@@ -186,9 +161,9 @@ describe('buildPathGuardrail', () => {
   it('passes when no path fields in input', async () => {
     const guard = buildPathGuardrail(['/allowed/**']);
     const result = await guard.execute({
-      agent: {} as never,
+      agent: {},
       input: 'Tell me about the project',
-      context: {} as never,
+      context: {},
     });
     expect(result.tripwireTriggered).toBe(false);
   });
@@ -196,9 +171,9 @@ describe('buildPathGuardrail', () => {
   it('trips when path field violates ACL', async () => {
     const guard = buildPathGuardrail(['/allowed/**']);
     const result = await guard.execute({
-      agent: {} as never,
+      agent: {},
       input: JSON.stringify({ path: '/etc/shadow' }),
-      context: {} as never,
+      context: {},
     });
     expect(result.tripwireTriggered).toBe(true);
     expect((result.outputInfo as Record<string, unknown>).deniedPath).toBe('/etc/shadow');
@@ -207,9 +182,9 @@ describe('buildPathGuardrail', () => {
   it('passes when path field is within ACL', async () => {
     const guard = buildPathGuardrail(['/allowed/**']);
     const result = await guard.execute({
-      agent: {} as never,
+      agent: {},
       input: JSON.stringify({ path: '/allowed/file.ts' }),
-      context: {} as never,
+      context: {},
     });
     expect(result.tripwireTriggered).toBe(false);
   });
@@ -224,9 +199,9 @@ describe('buildToolAllowlistGuardrail', () => {
   it('always passes (structural enforcement)', async () => {
     const guard = buildToolAllowlistGuardrail(['read', 'bash']);
     const result = await guard.execute({
-      agent: {} as never,
+      agent: {},
       input: 'run this',
-      context: {} as never,
+      context: {},
     });
     expect(result.tripwireTriggered).toBe(false);
     expect((result.outputInfo as Record<string, unknown>).checked).toBe(true);
@@ -257,6 +232,19 @@ describe('buildDefaultGuardrails', () => {
   });
 });
 
+describe('evaluateGuardrails', () => {
+  it('passes when no guardrails are provided', async () => {
+    const result = await evaluateGuardrails([], 'anything');
+    expect(result.tripwireTriggered).toBe(false);
+  });
+
+  it('returns the first tripwire result', async () => {
+    const guard = buildPathGuardrail(['/allowed/**']);
+    const result = await evaluateGuardrails([guard], JSON.stringify({ path: '/blocked/file.ts' }));
+    expect(result.tripwireTriggered).toBe(true);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Handoff topology
 // ---------------------------------------------------------------------------
@@ -278,29 +266,33 @@ describe('buildWorkerAgent', () => {
     expect(buildWorkerAgent('unknown-archetype', [])).toBeNull();
   });
 
-  it('returns an Agent for a known archetype', () => {
+  it('returns an agent for a known archetype', () => {
     const agent = buildWorkerAgent('worker-read', []);
     expect(agent).not.toBeNull();
+    expect(agent?.name).toBe('worker-read');
   });
 });
 
 describe('buildLeadAgent', () => {
   it('creates a lead agent with handoff workers', () => {
-    const worker = buildWorkerAgent('worker-read', [])!;
+    const worker = buildWorkerAgent('worker-read', []);
+    if (!worker) throw new Error('worker-read archetype missing');
     const lead = buildLeadAgent('You are a lead.', 'gpt-4.1', [worker], []);
-    expect(lead).not.toBeNull();
+    expect(lead.name).toBe('cleo-lead');
+    expect(lead.handoffs).toHaveLength(1);
   });
 });
 
 describe('buildStandaloneAgent', () => {
-  it('creates an agent instance', () => {
+  it('creates an agent descriptor', () => {
     const agent = buildStandaloneAgent('Instructions', 'gpt-4.1-mini', []);
-    expect(agent).not.toBeNull();
+    expect(agent.name).toBe('cleo-worker');
+    expect(agent.model).toBe('gpt-4.1-mini');
   });
 });
 
 describe('buildAgentTopology', () => {
-  it('returns an agent when tier is worker', () => {
+  it('returns a standalone agent when tier is worker', () => {
     const agent = buildAgentTopology({
       instructions: 'Do work',
       model: 'gpt-4.1-mini',
@@ -308,10 +300,11 @@ describe('buildAgentTopology', () => {
       handoffNames: ['worker-read'],
       guardrails: [],
     });
-    expect(agent).not.toBeNull();
+    expect(agent.name).toBe('cleo-worker');
+    expect(agent.handoffs).toBeUndefined();
   });
 
-  it('returns an agent when tier is lead', () => {
+  it('returns a lead agent with handoffs when tier is lead', () => {
     const agent = buildAgentTopology({
       instructions: 'Lead the team',
       model: 'gpt-4.1',
@@ -319,7 +312,8 @@ describe('buildAgentTopology', () => {
       handoffNames: ['worker-read', 'worker-write'],
       guardrails: [],
     });
-    expect(agent).not.toBeNull();
+    expect(agent.name).toBe('cleo-lead');
+    expect(agent.handoffs).toHaveLength(2);
   });
 
   it('handles unknown archetype names gracefully', () => {
@@ -330,10 +324,11 @@ describe('buildAgentTopology', () => {
       handoffNames: ['worker-read', 'nonexistent-worker'],
       guardrails: [],
     });
-    expect(agent).not.toBeNull();
+    expect(agent.name).toBe('cleo-lead');
+    expect(agent.handoffs).toHaveLength(1);
   });
 
-  it('returns agent when tier is lead but no valid handoffs', () => {
+  it('falls back to standalone when tier is lead but no valid handoffs', () => {
     const agent = buildAgentTopology({
       instructions: 'Lead',
       model: 'gpt-4.1',
@@ -341,7 +336,7 @@ describe('buildAgentTopology', () => {
       handoffNames: [],
       guardrails: [],
     });
-    expect(agent).not.toBeNull();
+    expect(agent.name).toBe('cleo-worker');
   });
 });
 
@@ -355,12 +350,14 @@ describe('OpenAiSdkSpawnProvider', () => {
   beforeEach(() => {
     provider = new OpenAiSdkSpawnProvider();
     mockRunState.shouldThrow = false;
-    mockRunState.result = { finalOutput: 'completed output' };
-    createdAgents.length = 0;
+    mockRunState.output = 'completed output';
+    generateTextCalls.length = 0;
+    process.env.OPENAI_API_KEY = 'sk-test-key';
   });
 
   afterEach(() => {
     vi.clearAllMocks();
+    delete process.env.OPENAI_API_KEY;
   });
 
   describe('canSpawn', () => {
@@ -376,7 +373,6 @@ describe('OpenAiSdkSpawnProvider', () => {
       process.env.OPENAI_API_KEY = 'sk-test-key';
       const result = await provider.canSpawn();
       expect(result).toBe(true);
-      delete process.env.OPENAI_API_KEY;
     });
   });
 
@@ -439,6 +435,27 @@ describe('OpenAiSdkSpawnProvider', () => {
         options: { model: 'gpt-4o', tier: 'worker', tracingDisabled: true },
       });
       expect(result.status).toBe('completed');
+      const model = generateTextCalls[0]?.model as
+        | { __cleoMockModel: true; modelId: string }
+        | undefined;
+      expect(model?.modelId).toBe('gpt-4o');
+    });
+  });
+
+  describe('spawn — guardrail tripwire', () => {
+    it('aborts with failed status when a guardrail trips', async () => {
+      const result = await provider.spawn({
+        taskId: 'T582-guard',
+        prompt: JSON.stringify({ path: '/etc/shadow' }),
+        options: {
+          allowedGlobs: ['/mnt/projects/**'],
+          tier: 'worker',
+          tracingDisabled: true,
+        },
+      });
+      expect(result.status).toBe('failed');
+      expect(result.error).toContain('guardrail tripped');
+      expect(generateTextCalls.length).toBe(0);
     });
   });
 });
@@ -461,8 +478,9 @@ describe('OpenAiSdkAdapter', () => {
 
   describe('identity', () => {
     it('has id openai-sdk', () => expect(adapter.id).toBe('openai-sdk'));
-    it('has name OpenAI Agents SDK', () => expect(adapter.name).toBe('OpenAI Agents SDK'));
-    it('has version 1.0.0', () => expect(adapter.version).toBe('1.0.0'));
+    it('has display name "OpenAI SDK (Vercel AI SDK)"', () =>
+      expect(adapter.name).toBe('OpenAI SDK (Vercel AI SDK)'));
+    it('has version 2.0.0', () => expect(adapter.version).toBe('2.0.0'));
   });
 
   describe('capabilities', () => {
@@ -602,30 +620,30 @@ describe('CleoConduitTraceProcessor', () => {
 
   describe('onTraceStart', () => {
     it('resolves without error', async () => {
-      await expect(processor.onTraceStart({} as never)).resolves.toBeUndefined();
+      await expect(processor.onTraceStart({})).resolves.toBeUndefined();
     });
   });
 
   describe('onTraceEnd', () => {
     it('resolves without error', async () => {
-      await expect(processor.onTraceEnd({} as never)).resolves.toBeUndefined();
+      await expect(processor.onTraceEnd({})).resolves.toBeUndefined();
     });
   });
 
   describe('onSpanStart', () => {
     it('resolves without error', async () => {
-      await expect(processor.onSpanStart({} as never)).resolves.toBeUndefined();
+      await expect(processor.onSpanStart(makeSpanLike())).resolves.toBeUndefined();
     });
   });
 
   describe('onSpanEnd', () => {
     it('does not throw for a well-formed span', async () => {
       const span = makeSpanLike();
-      await expect(processor.onSpanEnd(span as never)).resolves.toBeUndefined();
+      await expect(processor.onSpanEnd(span)).resolves.toBeUndefined();
     });
 
     it('does not throw for a span with missing fields', async () => {
-      await expect(processor.onSpanEnd({} as never)).resolves.toBeUndefined();
+      await expect(processor.onSpanEnd({ spanId: 'x' })).resolves.toBeUndefined();
     });
   });
 
@@ -643,24 +661,26 @@ describe('CleoConduitTraceProcessor', () => {
 });
 
 // ---------------------------------------------------------------------------
-// Handoff integration: lead + workers with mocked runner
+// Handoff integration: lead + workers with mocked generateText
 // ---------------------------------------------------------------------------
 
-describe('Handoff integration — lead routes to workers via SDK', () => {
+describe('Handoff integration — lead routes to workers via Vercel AI SDK', () => {
   let provider: OpenAiSdkSpawnProvider;
 
   beforeEach(() => {
     provider = new OpenAiSdkSpawnProvider();
     mockRunState.shouldThrow = false;
-    mockRunState.result = { finalOutput: 'handoff result' };
-    createdAgents.length = 0;
+    mockRunState.output = 'handoff result';
+    generateTextCalls.length = 0;
+    process.env.OPENAI_API_KEY = 'sk-test-key';
   });
 
   afterEach(() => {
     vi.clearAllMocks();
+    delete process.env.OPENAI_API_KEY;
   });
 
-  it('creates a lead agent when tier is lead with handoffs', async () => {
+  it('executes the lead then each handoff worker sequentially', async () => {
     const result = await provider.spawn({
       taskId: 'T582-handoff',
       prompt: 'Research and implement feature',
@@ -672,12 +692,8 @@ describe('Handoff integration — lead routes to workers via SDK', () => {
     });
 
     expect(result.status).toBe('completed');
-    expect(result.output).toBe('handoff result');
-
-    // A cleo-lead agent should have been created with 2 handoff workers
-    const leadAgent = createdAgents.find((a) => a.name === 'cleo-lead');
-    expect(leadAgent).toBeDefined();
-    expect(leadAgent?.handoffs).toHaveLength(2);
+    // 1 lead + 2 workers = 3 generateText calls
+    expect(generateTextCalls.length).toBe(3);
   });
 
   it('result reflects correct providerId and taskId', async () => {
@@ -693,7 +709,6 @@ describe('Handoff integration — lead routes to workers via SDK', () => {
   });
 
   it('handoff workers use worker archetype model (gpt-4.1-mini)', async () => {
-    createdAgents.length = 0;
     await provider.spawn({
       taskId: 'T582-model',
       prompt: 'Work',
@@ -704,13 +719,29 @@ describe('Handoff integration — lead routes to workers via SDK', () => {
       },
     });
 
-    // Worker archetypes should use gpt-4.1-mini
-    const workerAgents = createdAgents.filter(
-      (a) => a.name === 'worker-read' || a.name === 'worker-bash',
-    );
-    expect(workerAgents.length).toBe(2);
-    for (const worker of workerAgents) {
-      expect(worker.model).toBe('gpt-4.1-mini');
-    }
+    // Workers receive gpt-4.1-mini — calls[1] and calls[2] correspond to the two workers.
+    const workerCallA = generateTextCalls[1]?.model as
+      | { __cleoMockModel: true; modelId: string }
+      | undefined;
+    const workerCallB = generateTextCalls[2]?.model as
+      | { __cleoMockModel: true; modelId: string }
+      | undefined;
+    expect(workerCallA?.modelId).toBe('gpt-4.1-mini');
+    expect(workerCallB?.modelId).toBe('gpt-4.1-mini');
+  });
+
+  it('aggregates lead + worker outputs in the final SpawnResult', async () => {
+    mockRunState.output = 'step complete';
+    const result = await provider.spawn({
+      taskId: 'T582-output',
+      prompt: 'Do',
+      options: { tier: 'lead', handoffs: ['worker-read'], tracingDisabled: true },
+    });
+
+    expect(result.output).toContain('step complete');
+    expect(result.output).toContain('[worker-read]');
   });
 });
+
+// Dummy reference so type-only import doesn't get tree-shaken before test runs.
+void ({} as CleoAgent);

package/src/providers/openai-sdk/adapter.ts

@@ -1,11 +1,14 @@
 /**
- * OpenAI Agents SDK Adapter.
+ * OpenAI SDK Adapter — Vercel AI SDK edition.
  *
- * Main `CLEOProviderAdapter` implementation for the OpenAI Agents SDK.
- * Provides spawn and install capabilities. Hooks are not supported (the
- * SDK does not expose a CLI hook system equivalent to Claude Code's).
+ * Main `CLEOProviderAdapter` implementation for the OpenAI provider, backed
+ * by the Vercel AI SDK (`ai` v6 + `@ai-sdk/openai`). Provides spawn and
+ * install capabilities. Hooks are not supported — the Vercel AI SDK does not
+ * expose a CLI hook system equivalent to Claude Code's.
  *
- * @task T582
+ * @task T582 (original)
+ * @task T933 (SDK consolidation — Vercel AI SDK migration)
+ * @see ADR-052 — SDK consolidation decision
  */
 
 import type {
@@ -17,29 +20,27 @@ import { OpenAiSdkInstallProvider } from './install.js';
 import { OpenAiSdkSpawnProvider } from './spawn.js';
 
 /**
- * CLEO provider adapter for the OpenAI Agents SDK.
+ * CLEO provider adapter for the OpenAI provider.
  *
- * Bridges CLEO's adapter system with the `@openai/agents` SDK:
- * - Spawn: Launches agents via the SDK runner with handoff topology
+ * Bridges CLEO's adapter system with the Vercel AI SDK:
+ * - Spawn: Launches agents via the SDK with CLEO-native handoff topology
  * - Install: Manages AGENTS.md @-references and .openai/ config directory
  * - Tracing: Default-on conduit span persistence via `CleoConduitTraceProcessor`
  *
  * @remarks
- * This adapter is the only CLEO provider with first-class handoff support.
- * Team Lead → Worker topology is declared in `SpawnContext.options.handoffs`
- * and wired directly to SDK `Agent.handoffs`. The SDK handles routing
- * internally without any CLEO glue code.
- *
- * This is also the only provider supporting 100+ LLMs via the Vercel AI SDK
- * bridge (capability flag: `supportsMultiModel`).
+ * Handoff topology is CLEO-owned (see `handoff.ts`): lead agents delegate to
+ * worker archetypes in sequence, and the concatenated output is returned.
+ * The Vercel AI SDK surface (`generateText` / `streamText`) works uniformly
+ * across Anthropic, OpenAI, and compatible providers, so the provider keeps
+ * the `supportsMultiModel` capability flag.
  */
 export class OpenAiSdkAdapter implements CLEOProviderAdapter {
   /** Unique provider identifier. */
   readonly id = 'openai-sdk';
   /** Human-readable provider name. */
-  readonly name = 'OpenAI Agents SDK';
+  readonly name = 'OpenAI SDK (Vercel AI SDK)';
   /** Adapter version string. */
-  readonly version = '1.0.0';
+  readonly version = '2.0.0';
 
   /** Declared capabilities for this provider. */
   capabilities: AdapterCapabilities = {
@@ -117,7 +118,7 @@ export class OpenAiSdkAdapter implements CLEOProviderAdapter {
       details: {
         apiKeyPresent,
         projectDir: this.projectDir,
-        sdkVersion: '0.8.3',
+        sdkVersion: 'ai@6 + @ai-sdk/openai',
       },
     };
   }