@cleocode/adapters 2026.4.92 → 2026.4.94

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

@@ -1,15 +1,64 @@
 /**
- * CLEO permission rules mapped to OpenAI Agents SDK guardrails.
+ * CLEO permission rules for the OpenAI SDK adapter.
  *
- * CLEO ACLs (file-glob path allowlists, tool allowlists) are expressed as
- * `InputGuardrail` instances that run before agent execution. A path that
- * falls outside the allowed glob list causes the guardrail to trip and
- * the agent run is rejected.
+ * Historically these rules were expressed as `InputGuardrail` instances from
+ * `@openai/agents`. Post T933 (ADR-052 — Vercel AI SDK consolidation) they
+ * are CLEO-native objects with the same shape so provider code that relies on
+ * their behaviour does not need to change. The Vercel AI SDK does not ship an
+ * equivalent guardrail abstraction — CLEO implements its own path ACL and
+ * tool allowlist enforcement here.
  *
- * @task T582
+ * A guardrail evaluates the serialised agent input before the request is sent
+ * to the model. A path that falls outside the allowed glob list causes the
+ * guardrail to trip and the run is rejected.
+ *
+ * @task T582 (original)
+ * @task T933 (SDK consolidation — provider-neutral rewrite)
+ */
+
+// ---------------------------------------------------------------------------
+// CLEO-native guardrail contract
+// ---------------------------------------------------------------------------
+
+/** Arguments passed to a CLEO input guardrail. */
+export interface CleoInputGuardrailFunctionArgs {
+  /** The agent being invoked. Opaque to guardrails. */
+  agent: unknown;
+  /** Serialised input to scan — may be a string or arbitrary JSON value. */
+  input: unknown;
+  /** Per-run context (opaque). */
+  context: unknown;
+}
+
+/** Result of evaluating a CLEO input guardrail. */
+export interface CleoGuardrailResult {
+  /** When true, the guardrail has tripped and the run MUST be rejected. */
+  tripwireTriggered: boolean;
+  /** Free-form diagnostic payload for logging and trace spans. */
+  outputInfo: unknown;
+}
+
+/**
+ * CLEO-native replacement for `InputGuardrail` from `@openai/agents`.
+ *
+ * @remarks
+ * The shape is identical to the legacy SDK contract so downstream consumers
+ * do not require changes. CLEO enforces these guardrails in-process before
+ * dispatching a prompt to the Vercel AI SDK.
  */
+export interface CleoInputGuardrail {
+  /** Stable guardrail identifier for logs and trace metadata. */
+  name: string;
+  /** Execute the guardrail against the current run arguments. */
+  execute(args: CleoInputGuardrailFunctionArgs): Promise<CleoGuardrailResult>;
+}
 
-import type { InputGuardrail, InputGuardrailFunctionArgs } from '@openai/agents';
+/**
+ * @deprecated Use {@link CleoInputGuardrail}. Kept as a named alias for
+ *   callers that previously imported the legacy `InputGuardrail` name from
+ *   this module. Removed in a future major.
+ */
+export type InputGuardrail = CleoInputGuardrail;
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -58,20 +107,18 @@ export function isPathAllowed(path: string, allowedGlobs: string[]): boolean {
  *
  * @param allowedGlobs - Glob patterns that tool path arguments must match.
  *   Pass an empty array to allow all paths (permissive mode).
- * @returns An {@link InputGuardrail} ready to attach to an `Agent`.
+ * @returns A {@link CleoInputGuardrail} ready to attach to an agent.
  *
  * @example
  * ```typescript
  * const guard = buildPathGuardrail(['/mnt/projects/**', '/tmp/**']);
- * const agent = new Agent({ ..., inputGuardrails: [guard] });
+ * const agent = buildStandaloneAgent('...', 'gpt-4.1', [guard]);
  * ```
  */
-export function buildPathGuardrail(allowedGlobs: string[]): InputGuardrail {
+export function buildPathGuardrail(allowedGlobs: string[]): CleoInputGuardrail {
   return {
     name: 'cleo_path_acl',
-    execute: async (
-      args: InputGuardrailFunctionArgs,
-    ): Promise<{ tripwireTriggered: boolean; outputInfo: unknown }> => {
+    execute: async (args: CleoInputGuardrailFunctionArgs): Promise<CleoGuardrailResult> => {
       // Serialise input to a string for heuristic path scanning.
       const inputStr = typeof args.input === 'string' ? args.input : JSON.stringify(args.input);
 
@@ -100,26 +147,23 @@ export function buildPathGuardrail(allowedGlobs: string[]): InputGuardrail {
 /**
  * Build an input guardrail that documents the tool allowlist for audit purposes.
  *
- * In the OpenAI Agents SDK, tool-name enforcement is primarily structural —
- * agents only receive the tools attached to their `tools` array. This guardrail
- * provides an additional audit layer that records the active allowlist in the
- * span metadata.
+ * Tool-name enforcement is primarily structural — agents only receive the
+ * tools declared by CLEO orchestration. This guardrail provides an additional
+ * audit layer that records the active allowlist in the span metadata.
  *
  * @param allowedTools - Exact tool names permitted for this agent.
  *   Pass an empty array to allow all tools (permissive mode).
- * @returns An {@link InputGuardrail} ready to attach to an `Agent`.
+ * @returns A {@link CleoInputGuardrail} ready to attach to an agent.
  *
  * @example
  * ```typescript
  * const guard = buildToolAllowlistGuardrail(['read', 'write']);
  * ```
  */
-export function buildToolAllowlistGuardrail(allowedTools: string[]): InputGuardrail {
+export function buildToolAllowlistGuardrail(allowedTools: string[]): CleoInputGuardrail {
   return {
     name: 'cleo_tool_allowlist',
-    execute: async (
-      _args: InputGuardrailFunctionArgs,
-    ): Promise<{ tripwireTriggered: boolean; outputInfo: unknown }> => {
+    execute: async (_args: CleoInputGuardrailFunctionArgs): Promise<CleoGuardrailResult> => {
       // Structural enforcement: only listed tools are attached to the agent.
       // This guardrail records the allowlist for audit and always passes.
       return {
@@ -134,7 +178,7 @@ export function buildToolAllowlistGuardrail(allowedTools: string[]): InputGuardr
  * Build the default CLEO guardrail set from spawn options.
  *
  * Combines path ACL and tool allowlist guards into a single array ready to
- * pass as `inputGuardrails` on an `Agent` or `RunConfig`.
+ * pass as `inputGuardrails` on an agent topology build.
  *
  * @param allowedGlobs - File-path glob allowlist.
  * @param allowedTools - Tool name allowlist.
@@ -143,8 +187,8 @@ export function buildToolAllowlistGuardrail(allowedTools: string[]): InputGuardr
 export function buildDefaultGuardrails(
   allowedGlobs: string[],
   allowedTools: string[],
-): InputGuardrail[] {
-  const guards: InputGuardrail[] = [];
+): CleoInputGuardrail[] {
+  const guards: CleoInputGuardrail[] = [];
 
   if (allowedGlobs.length > 0) {
     guards.push(buildPathGuardrail(allowedGlobs));
@@ -156,3 +200,40 @@ export function buildDefaultGuardrails(
 
   return guards;
 }
+
+/**
+ * Evaluate a set of CLEO input guardrails against an input payload.
+ *
+ * Runs every guardrail in sequence and returns the first tripwire result.
+ * When no guardrail trips, returns a passing result with diagnostic data
+ * aggregated from each guardrail's `outputInfo`.
+ *
+ * @param guardrails - Guardrails to evaluate.
+ * @param input - The input string to test (typically the enriched prompt).
+ * @returns Aggregated guardrail result.
+ */
+export async function evaluateGuardrails(
+  guardrails: CleoInputGuardrail[],
+  input: string,
+): Promise<CleoGuardrailResult> {
+  const aggregate: Array<{ name: string; outputInfo: unknown }> = [];
+
+  for (const guard of guardrails) {
+    const result = await guard.execute({
+      agent: null,
+      input,
+      context: null,
+    });
+
+    if (result.tripwireTriggered) {
+      return result;
+    }
+
+    aggregate.push({ name: guard.name, outputInfo: result.outputInfo });
+  }
+
+  return {
+    tripwireTriggered: false,
+    outputInfo: aggregate,
+  };
+}

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

@@ -1,20 +1,56 @@
 /**
- * CLEO Team topology → OpenAI Agents SDK handoff mapping.
+ * CLEO Team topology → lead/worker agent descriptors.
  *
- * CLEO agents are organised in a Lead → Worker hierarchy. This module maps
- * that topology to the SDK's first-class `handoffs` graph:
+ * CLEO agents are organised in a Lead → Worker hierarchy. Historically this
+ * was wired into the `@openai/agents` first-class `handoffs` graph. Post T933
+ * (ADR-052 — Vercel AI SDK consolidation) CLEO owns the topology entirely:
  *
- * - A Team Lead becomes an `Agent` whose `handoffs` array lists its workers.
+ * - A Team Lead is a {@link CleoAgent} whose `handoffs` array lists its workers.
  * - Each Worker archetype (read-only, write, bash) is declared in
  *   `WORKER_ARCHETYPES` and built on demand.
  * - The mapping is driven by `SpawnContext.options.handoffs`, which is an
  *   array of worker archetype names.
+ * - When a lead agent needs to delegate, the spawn provider runs a separate
+ *   `generateText` call for the selected worker and injects the result back
+ *   into the lead's context.
  *
- * @task T582
+ * @task T582 (original)
+ * @task T933 (SDK consolidation — CLEO-native topology)
  */
 
-import type { InputGuardrail } from '@openai/agents';
-import { Agent } from '@openai/agents';
+import type { CleoInputGuardrail } from './guardrails.js';
+
+// ---------------------------------------------------------------------------
+// CLEO-native agent shape
+// ---------------------------------------------------------------------------
+
+/**
+ * Agent descriptor used by the CLEO OpenAI adapter.
+ *
+ * @remarks
+ * Intentionally mirrors the subset of `@openai/agents`'s `Agent` that CLEO
+ * actually consumed. The Vercel AI SDK delivers model inference via
+ * `generateText` / `streamText`; handoffs are orchestrated by the spawn
+ * provider using this descriptor as input.
+ */
+export interface CleoAgent {
+  /** Agent identifier surfaced in trace spans. */
+  name: string;
+  /** System-level instructions fed to the model. */
+  instructions: string;
+  /** Vercel AI SDK model identifier (e.g. `gpt-4.1`, `gpt-4.1-mini`). */
+  model: string;
+  /** Workers this agent may delegate to. Undefined when the agent is a leaf. */
+  handoffs?: CleoAgent[];
+  /** Input guardrails evaluated before the model call. */
+  inputGuardrails?: CleoInputGuardrail[];
+}
+
+/**
+ * @deprecated Use {@link CleoAgent}. Legacy alias for callers that imported
+ *   the `Agent` type from this module. Removed in a future major.
+ */
+export type Agent = CleoAgent;
 
 // ---------------------------------------------------------------------------
 // Worker archetypes
@@ -24,12 +60,12 @@ import { Agent } from '@openai/agents';
  * Descriptor for a pre-configured worker agent archetype.
  *
  * Archetypes are declarative templates. `buildWorkerAgent` inflates them into
- * live SDK `Agent` instances.
+ * live {@link CleoAgent} instances.
  */
 export interface WorkerArchetype {
-  /** Archetype identifier (also used as SDK agent name). */
+  /** Archetype identifier (also used as agent name). */
   name: string;
-  /** Short description passed as the SDK agent instructions. */
+  /** Short description passed as the agent instructions. */
   instructions: string;
   /** Preferred model for this archetype. */
   model: string;
@@ -67,49 +103,49 @@ export const WORKER_ARCHETYPES: Record<string, WorkerArchetype> = {
 // ---------------------------------------------------------------------------
 
 /**
- * Build a worker `Agent` instance from a named archetype.
+ * Build a worker {@link CleoAgent} from a named archetype.
  *
  * @param archetypeName - Key in {@link WORKER_ARCHETYPES}.
  * @param guardrails - Input guardrails to attach to the worker agent.
- * @returns A configured SDK `Agent` or `null` when the archetype is unknown.
+ * @returns A configured agent descriptor or `null` when the archetype is unknown.
  */
 export function buildWorkerAgent(
   archetypeName: string,
-  guardrails: InputGuardrail[],
-): Agent | null {
+  guardrails: CleoInputGuardrail[],
+): CleoAgent | null {
   const archetype = WORKER_ARCHETYPES[archetypeName];
   if (!archetype) return null;
 
-  return new Agent({
+  return {
     name: archetype.name,
     instructions: archetype.instructions,
     model: archetype.model,
-    inputGuardrails: guardrails.length > 0 ? guardrails : undefined,
-  });
+    ...(guardrails.length > 0 ? { inputGuardrails: guardrails } : {}),
+  };
 }
 
 /**
- * Build a team lead `Agent` whose `handoffs` reference the given workers.
+ * Build a team lead {@link CleoAgent} whose `handoffs` reference the given workers.
  *
  * @param leadInstructions - System instructions for the lead agent.
  * @param leadModel - Model to use for the lead agent.
  * @param workers - Worker agents this lead can hand off to.
  * @param guardrails - Input guardrails to attach to the lead agent.
- * @returns A configured lead SDK `Agent`.
+ * @returns A configured lead agent descriptor.
  */
 export function buildLeadAgent(
   leadInstructions: string,
   leadModel: string,
-  workers: Agent[],
-  guardrails: InputGuardrail[],
-): Agent {
-  return new Agent({
+  workers: CleoAgent[],
+  guardrails: CleoInputGuardrail[],
+): CleoAgent {
+  return {
     name: 'cleo-lead',
     instructions: leadInstructions,
     model: leadModel,
-    handoffs: workers.length > 0 ? workers : undefined,
-    inputGuardrails: guardrails.length > 0 ? guardrails : undefined,
-  });
+    ...(workers.length > 0 ? { handoffs: workers } : {}),
+    ...(guardrails.length > 0 ? { inputGuardrails: guardrails } : {}),
+  };
 }
 
 /**
@@ -121,19 +157,19 @@ export function buildLeadAgent(
  * @param instructions - Agent system instructions.
  * @param model - Model identifier.
  * @param guardrails - Input guardrails.
- * @returns A configured SDK `Agent`.
+ * @returns A configured agent descriptor.
  */
 export function buildStandaloneAgent(
   instructions: string,
   model: string,
-  guardrails: InputGuardrail[],
-): Agent {
-  return new Agent({
+  guardrails: CleoInputGuardrail[],
+): CleoAgent {
+  return {
     name: 'cleo-worker',
     instructions,
     model,
-    inputGuardrails: guardrails.length > 0 ? guardrails : undefined,
-  });
+    ...(guardrails.length > 0 ? { inputGuardrails: guardrails } : {}),
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -151,7 +187,7 @@ export interface TopologyOptions {
   /** Names of worker archetypes to create and attach as handoffs. */
   handoffNames: string[];
   /** Input guardrails shared across all agents in the topology. */
-  guardrails: InputGuardrail[];
+  guardrails: CleoInputGuardrail[];
 }
 
 /**
@@ -164,9 +200,9 @@ export interface TopologyOptions {
  * Unknown archetype names in `handoffNames` are silently skipped.
  *
  * @param options - Topology build options.
- * @returns The entry-point agent to pass to `runner.run()`.
+ * @returns The entry-point agent descriptor.
  */
-export function buildAgentTopology(options: TopologyOptions): Agent {
+export function buildAgentTopology(options: TopologyOptions): CleoAgent {
   const { instructions, model, tier, handoffNames, guardrails } = options;
 
   if (tier === 'worker') {
@@ -174,9 +210,9 @@ export function buildAgentTopology(options: TopologyOptions): Agent {
   }
 
   // Build worker agents from archetype names; skip unknown names.
-  const workers: Agent[] = handoffNames
+  const workers: CleoAgent[] = handoffNames
     .map((name) => buildWorkerAgent(name, guardrails))
-    .filter((a): a is Agent => a !== null);
+    .filter((a): a is CleoAgent => a !== null);
 
   if (workers.length === 0) {
     // Lead with no workers — still usable as a standalone agent.

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

@@ -1,22 +1,30 @@
 /**
  * @packageDocumentation
  *
- * CLEO provider adapter for the OpenAI Agents SDK.
+ * CLEO provider adapter for the OpenAI provider, backed by the Vercel AI SDK.
  * Default export is the adapter class for dynamic loading by AdapterManager.
  *
- * @task T582
+ * @task T582 (original)
+ * @task T933 (SDK consolidation — Vercel AI SDK migration)
  */
 
 import { OpenAiSdkAdapter } from './adapter.js';
 
 export { OpenAiSdkAdapter } from './adapter.js';
+export type {
+  CleoGuardrailResult,
+  CleoInputGuardrail,
+  CleoInputGuardrailFunctionArgs,
+  InputGuardrail,
+} from './guardrails.js';
 export {
   buildDefaultGuardrails,
   buildPathGuardrail,
   buildToolAllowlistGuardrail,
+  evaluateGuardrails,
   isPathAllowed,
 } from './guardrails.js';
-export type { TopologyOptions, WorkerArchetype } from './handoff.js';
+export type { Agent, CleoAgent, TopologyOptions, WorkerArchetype } from './handoff.js';
 export {
   buildAgentTopology,
   buildLeadAgent,
@@ -26,7 +34,23 @@ export {
 } from './handoff.js';
 export { OpenAiSdkInstallProvider } from './install.js';
 export type { OpenAiSdkSpawnOptions } from './spawn.js';
-export { OpenAiSdkSpawnProvider } from './spawn.js';
+export {
+  OpenAiSdkSpawnProvider,
+  registerTraceProcessor,
+  setTracingDisabled,
+  unregisterTraceProcessor,
+} from './spawn.js';
+export type {
+  CleoAgentSpanData,
+  CleoFunctionSpanData,
+  CleoGenericSpanData,
+  CleoHandoffSpanData,
+  CleoSpan,
+  CleoSpanData,
+  CleoSpanKind,
+  CleoTrace,
+  CleoTraceProcessor,
+} from './tracing.js';
 export { CleoConduitTraceProcessor } from './tracing.js';
 
 export default OpenAiSdkAdapter;

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

@@ -16,7 +16,7 @@ import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cle
 const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
 
 /**
- * Install provider for the OpenAI Agents SDK.
+ * Install provider for the OpenAI SDK adapter (Vercel AI SDK).
  *
  * Manages CLEO's integration with OpenAI SDK projects by:
  * 1. Ensuring AGENTS.md contains @-references to CLEO instruction files

package/src/providers/openai-sdk/manifest.json

@@ -1,8 +1,8 @@
 {
   "id": "openai-sdk",
-  "name": "OpenAI Agents SDK Adapter",
-  "version": "1.0.0",
-  "description": "CLEO adapter for the OpenAI Agents SDK with first-class handoffs and multi-model support",
+  "name": "OpenAI SDK (Vercel AI SDK)",
+  "version": "2.0.0",
+  "description": "CLEO adapter for OpenAI via the Vercel AI SDK with CLEO-native handoffs and multi-model support",
   "provider": "openai-sdk",
   "entryPoint": "src/providers/openai-sdk/index.ts",
   "capabilities": {
@@ -35,7 +35,7 @@
     "provider.openai.tracingEnabled": {
       "type": "boolean",
       "default": true,
-      "description": "Whether to write SDK span events to conduit.db"
+      "description": "Whether to write adapter span events to conduit.db"
     }
   },
   "detectionPatterns": [