@cleocode/adapters 2026.4.47 → 2026.4.48

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

@@ -0,0 +1,138 @@
+/**
+ * OpenAI Agents SDK Adapter.
+ *
+ * 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).
+ *
+ * @task T582
+ */
+
+import type {
+  AdapterCapabilities,
+  AdapterHealthStatus,
+  CLEOProviderAdapter,
+} from '@cleocode/contracts';
+import { OpenAiSdkInstallProvider } from './install.js';
+import { OpenAiSdkSpawnProvider } from './spawn.js';
+
+/**
+ * CLEO provider adapter for the OpenAI Agents SDK.
+ *
+ * Bridges CLEO's adapter system with the `@openai/agents` SDK:
+ * - Spawn: Launches agents via the SDK runner with 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`).
+ */
+export class OpenAiSdkAdapter implements CLEOProviderAdapter {
+  /** Unique provider identifier. */
+  readonly id = 'openai-sdk';
+  /** Human-readable provider name. */
+  readonly name = 'OpenAI Agents SDK';
+  /** Adapter version string. */
+  readonly version = '1.0.0';
+
+  /** Declared capabilities for this provider. */
+  capabilities: AdapterCapabilities = {
+    supportsHooks: false,
+    // The SDK does not expose CLI lifecycle hooks equivalent to Claude Code.
+    supportedHookEvents: [],
+    supportsSpawn: true,
+    supportsInstall: true,
+    supportsInstructionFiles: true,
+    instructionFilePattern: 'AGENTS.md',
+    supportsContextMonitor: false,
+    supportsStatusline: false,
+    supportsProviderPaths: false,
+    supportsTransport: false,
+    supportsTaskSync: false,
+  };
+
+  /** Spawn provider for SDK-backed agent runs with handoff topology. */
+  spawn: OpenAiSdkSpawnProvider;
+  /** Install provider for AGENTS.md and .openai/ config directory management. */
+  install: OpenAiSdkInstallProvider;
+
+  /** Project directory this adapter was initialized with, or null. */
+  private projectDir: string | null = null;
+  /** Whether {@link initialize} has been called. */
+  private initialized = false;
+
+  constructor() {
+    this.spawn = new OpenAiSdkSpawnProvider();
+    this.install = new OpenAiSdkInstallProvider();
+  }
+
+  /**
+   * Initialize the adapter for a given project directory.
+   *
+   * @param projectDir - Root directory of the project.
+   */
+  async initialize(projectDir: string): Promise<void> {
+    this.projectDir = projectDir;
+    this.initialized = true;
+  }
+
+  /**
+   * Dispose the adapter and release all resources.
+   */
+  async dispose(): Promise<void> {
+    this.initialized = false;
+    this.projectDir = null;
+  }
+
+  /**
+   * Run a health check to verify the OpenAI SDK is usable.
+   *
+   * Checks:
+   * 1. Adapter has been initialized
+   * 2. `OPENAI_API_KEY` is set in the environment
+   *
+   * @returns Health status with details about each check.
+   */
+  async healthCheck(): Promise<AdapterHealthStatus> {
+    if (!this.initialized) {
+      return {
+        healthy: false,
+        provider: this.id,
+        details: { error: 'Adapter not initialized' },
+      };
+    }
+
+    const apiKeyPresent =
+      typeof process.env.OPENAI_API_KEY === 'string' && process.env.OPENAI_API_KEY.length > 0;
+
+    return {
+      healthy: apiKeyPresent,
+      provider: this.id,
+      details: {
+        apiKeyPresent,
+        projectDir: this.projectDir,
+        sdkVersion: '0.8.3',
+      },
+    };
+  }
+
+  /**
+   * Check whether the adapter has been initialized.
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /**
+   * Get the project directory this adapter was initialized with.
+   */
+  getProjectDir(): string | null {
+    return this.projectDir;
+  }
+}

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

@@ -0,0 +1,158 @@
+/**
+ * CLEO permission rules mapped to OpenAI Agents SDK guardrails.
+ *
+ * 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.
+ *
+ * @task T582
+ */
+
+import type { InputGuardrail, InputGuardrailFunctionArgs } from '@openai/agents';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Converts a simple glob pattern to a RegExp.
+ *
+ * Supports `*` (any chars within a segment) and `**` (any chars including `/`).
+ * This is a lightweight alternative to the `minimatch` package so no extra
+ * dependency is required in the adapters package.
+ *
+ * @param glob - Glob pattern to convert (e.g. `/mnt/projects/**`).
+ * @returns A RegExp that matches paths conforming to the glob.
+ */
+function globToRegex(glob: string): RegExp {
+  // Escape regex metacharacters except * and ?
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  // Replace ** first (order matters), then *
+  const pattern = escaped.replace(/\*\*/g, '.+').replace(/\*/g, '[^/]*');
+  return new RegExp(`^${pattern}$`);
+}
+
+/**
+ * Check whether a file-system path is covered by at least one glob pattern.
+ *
+ * @param path - The absolute or relative path to test.
+ * @param allowedGlobs - Array of glob patterns (supports `*` and `**`).
+ * @returns `true` when the path matches at least one pattern.
+ */
+export function isPathAllowed(path: string, allowedGlobs: string[]): boolean {
+  if (allowedGlobs.length === 0) return true;
+  return allowedGlobs.some((glob) => globToRegex(glob).test(path));
+}
+
+// ---------------------------------------------------------------------------
+// Guardrail builders
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an input guardrail that enforces CLEO file-glob path ACLs.
+ *
+ * Inspects the serialised agent input for embedded `"path":"..."` fields
+ * and rejects the run when a path falls outside the allowlist. This provides
+ * an early-exit safety fence before the agent starts consuming model tokens.
+ *
+ * @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`.
+ *
+ * @example
+ * ```typescript
+ * const guard = buildPathGuardrail(['/mnt/projects/**', '/tmp/**']);
+ * const agent = new Agent({ ..., inputGuardrails: [guard] });
+ * ```
+ */
+export function buildPathGuardrail(allowedGlobs: string[]): InputGuardrail {
+  return {
+    name: 'cleo_path_acl',
+    execute: async (
+      args: InputGuardrailFunctionArgs,
+    ): Promise<{ tripwireTriggered: boolean; outputInfo: unknown }> => {
+      // Serialise input to a string for heuristic path scanning.
+      const inputStr = typeof args.input === 'string' ? args.input : JSON.stringify(args.input);
+
+      // Scan for JSON-encoded `"path":"..."` occurrences in the input text.
+      // This is conservative: if no path field is found the guardrail passes.
+      const pathMatches = inputStr.matchAll(/"path"\s*:\s*"([^"]+)"/g);
+      for (const match of pathMatches) {
+        const candidate = match[1];
+        if (candidate && !isPathAllowed(candidate, allowedGlobs)) {
+          return {
+            tripwireTriggered: true,
+            outputInfo: {
+              reason: `cleo_path_acl: path denied by ACL — ${candidate}`,
+              deniedPath: candidate,
+              allowedGlobs,
+            },
+          };
+        }
+      }
+
+      return { tripwireTriggered: false, outputInfo: null };
+    },
+  };
+}
+
+/**
+ * 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.
+ *
+ * @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`.
+ *
+ * @example
+ * ```typescript
+ * const guard = buildToolAllowlistGuardrail(['read', 'write']);
+ * ```
+ */
+export function buildToolAllowlistGuardrail(allowedTools: string[]): InputGuardrail {
+  return {
+    name: 'cleo_tool_allowlist',
+    execute: async (
+      _args: InputGuardrailFunctionArgs,
+    ): Promise<{ tripwireTriggered: boolean; outputInfo: unknown }> => {
+      // Structural enforcement: only listed tools are attached to the agent.
+      // This guardrail records the allowlist for audit and always passes.
+      return {
+        tripwireTriggered: false,
+        outputInfo: { allowedTools, checked: true },
+      };
+    },
+  };
+}
+
+/**
+ * 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`.
+ *
+ * @param allowedGlobs - File-path glob allowlist.
+ * @param allowedTools - Tool name allowlist.
+ * @returns Array of input guardrails to attach to the agent.
+ */
+export function buildDefaultGuardrails(
+  allowedGlobs: string[],
+  allowedTools: string[],
+): InputGuardrail[] {
+  const guards: InputGuardrail[] = [];
+
+  if (allowedGlobs.length > 0) {
+    guards.push(buildPathGuardrail(allowedGlobs));
+  }
+
+  if (allowedTools.length > 0) {
+    guards.push(buildToolAllowlistGuardrail(allowedTools));
+  }
+
+  return guards;
+}

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

@@ -0,0 +1,187 @@
+/**
+ * CLEO Team topology → OpenAI Agents SDK handoff mapping.
+ *
+ * CLEO agents are organised in a Lead → Worker hierarchy. This module maps
+ * that topology to the SDK's first-class `handoffs` graph:
+ *
+ * - A Team Lead becomes an `Agent` 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.
+ *
+ * @task T582
+ */
+
+import type { InputGuardrail } from '@openai/agents';
+import { Agent } from '@openai/agents';
+
+// ---------------------------------------------------------------------------
+// Worker archetypes
+// ---------------------------------------------------------------------------
+
+/**
+ * Descriptor for a pre-configured worker agent archetype.
+ *
+ * Archetypes are declarative templates. `buildWorkerAgent` inflates them into
+ * live SDK `Agent` instances.
+ */
+export interface WorkerArchetype {
+  /** Archetype identifier (also used as SDK agent name). */
+  name: string;
+  /** Short description passed as the SDK agent instructions. */
+  instructions: string;
+  /** Preferred model for this archetype. */
+  model: string;
+}
+
+/**
+ * Registry of built-in CLEO worker archetypes.
+ *
+ * Callers reference these by name in `SpawnContext.options.handoffs`.
+ * New archetypes can be added here without changing the spawn provider.
+ */
+export const WORKER_ARCHETYPES: Record<string, WorkerArchetype> = {
+  'worker-read': {
+    name: 'worker-read',
+    instructions:
+      'You are a read-only CLEO worker. You may only read files and return findings. Never write, modify, or delete files.',
+    model: 'gpt-4.1-mini',
+  },
+  'worker-write': {
+    name: 'worker-write',
+    instructions:
+      'You are a CLEO write worker. You implement code changes directed by the lead agent. Follow the lead agent instructions precisely.',
+    model: 'gpt-4.1-mini',
+  },
+  'worker-bash': {
+    name: 'worker-bash',
+    instructions:
+      'You are a CLEO bash worker. You run shell commands directed by the lead agent. Only execute commands explicitly requested.',
+    model: 'gpt-4.1-mini',
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Agent builders
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a worker `Agent` instance 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.
+ */
+export function buildWorkerAgent(
+  archetypeName: string,
+  guardrails: InputGuardrail[],
+): Agent | null {
+  const archetype = WORKER_ARCHETYPES[archetypeName];
+  if (!archetype) return null;
+
+  return new Agent({
+    name: archetype.name,
+    instructions: archetype.instructions,
+    model: archetype.model,
+    inputGuardrails: guardrails.length > 0 ? guardrails : undefined,
+  });
+}
+
+/**
+ * Build a team lead `Agent` 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`.
+ */
+export function buildLeadAgent(
+  leadInstructions: string,
+  leadModel: string,
+  workers: Agent[],
+  guardrails: InputGuardrail[],
+): Agent {
+  return new Agent({
+    name: 'cleo-lead',
+    instructions: leadInstructions,
+    model: leadModel,
+    handoffs: workers.length > 0 ? workers : undefined,
+    inputGuardrails: guardrails.length > 0 ? guardrails : undefined,
+  });
+}
+
+/**
+ * Build a simple single-tier agent (no handoffs) from prompt and model.
+ *
+ * Used when `SpawnContext.options.tier` is `'worker'` or when no handoff
+ * names are provided.
+ *
+ * @param instructions - Agent system instructions.
+ * @param model - Model identifier.
+ * @param guardrails - Input guardrails.
+ * @returns A configured SDK `Agent`.
+ */
+export function buildStandaloneAgent(
+  instructions: string,
+  model: string,
+  guardrails: InputGuardrail[],
+): Agent {
+  return new Agent({
+    name: 'cleo-worker',
+    instructions,
+    model,
+    inputGuardrails: guardrails.length > 0 ? guardrails : undefined,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Topology builder
+// ---------------------------------------------------------------------------
+
+/** Options for building the agent topology from a spawn context. */
+export interface TopologyOptions {
+  /** Prompt / instructions for the entry-point agent. */
+  instructions: string;
+  /** Model to use for the lead / standalone agent. */
+  model: string;
+  /** Agent tier determines whether workers and handoffs are wired. */
+  tier: 'lead' | 'worker' | 'orchestrator';
+  /** Names of worker archetypes to create and attach as handoffs. */
+  handoffNames: string[];
+  /** Input guardrails shared across all agents in the topology. */
+  guardrails: InputGuardrail[];
+}
+
+/**
+ * Build the entry-point agent and its worker topology from spawn options.
+ *
+ * - `tier === 'lead'` or `tier === 'orchestrator'`: creates a lead agent with
+ *   worker handoffs derived from `handoffNames`.
+ * - `tier === 'worker'`: creates a standalone agent with no handoffs.
+ *
+ * Unknown archetype names in `handoffNames` are silently skipped.
+ *
+ * @param options - Topology build options.
+ * @returns The entry-point agent to pass to `runner.run()`.
+ */
+export function buildAgentTopology(options: TopologyOptions): Agent {
+  const { instructions, model, tier, handoffNames, guardrails } = options;
+
+  if (tier === 'worker') {
+    return buildStandaloneAgent(instructions, model, guardrails);
+  }
+
+  // Build worker agents from archetype names; skip unknown names.
+  const workers: Agent[] = handoffNames
+    .map((name) => buildWorkerAgent(name, guardrails))
+    .filter((a): a is Agent => a !== null);
+
+  if (workers.length === 0) {
+    // Lead with no workers — still usable as a standalone agent.
+    return buildStandaloneAgent(instructions, model, guardrails);
+  }
+
+  return buildLeadAgent(instructions, model, workers, guardrails);
+}

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

@@ -0,0 +1,55 @@
+/**
+ * @packageDocumentation
+ *
+ * CLEO provider adapter for the OpenAI Agents SDK.
+ * Default export is the adapter class for dynamic loading by AdapterManager.
+ *
+ * @task T582
+ */
+
+import { OpenAiSdkAdapter } from './adapter.js';
+
+export { OpenAiSdkAdapter } from './adapter.js';
+export {
+  buildDefaultGuardrails,
+  buildPathGuardrail,
+  buildToolAllowlistGuardrail,
+  isPathAllowed,
+} from './guardrails.js';
+export type { TopologyOptions, WorkerArchetype } from './handoff.js';
+export {
+  buildAgentTopology,
+  buildLeadAgent,
+  buildStandaloneAgent,
+  buildWorkerAgent,
+  WORKER_ARCHETYPES,
+} from './handoff.js';
+export { OpenAiSdkInstallProvider } from './install.js';
+export type { OpenAiSdkSpawnOptions } from './spawn.js';
+export { OpenAiSdkSpawnProvider } from './spawn.js';
+export { CleoConduitTraceProcessor } from './tracing.js';
+
+export default OpenAiSdkAdapter;
+
+/**
+ * Factory function for creating adapter instances.
+ * Used by AdapterManager's dynamic import fallback.
+ *
+ * @remarks
+ * This is the primary entry point for dynamic adapter loading.
+ * AdapterManager calls this function when it resolves the openai-sdk
+ * provider via its import-based discovery mechanism.
+ *
+ * @returns A new {@link OpenAiSdkAdapter} instance ready for initialization.
+ *
+ * @example
+ * ```typescript
+ * import { createAdapter } from '@cleocode/adapters/providers/openai-sdk';
+ *
+ * const adapter = createAdapter();
+ * await adapter.initialize('/path/to/project');
+ * ```
+ */
+export function createAdapter(): OpenAiSdkAdapter {
+  return new OpenAiSdkAdapter();
+}

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

@@ -0,0 +1,135 @@
+/**
+ * OpenAI SDK Install Provider.
+ *
+ * Handles CLEO installation into OpenAI SDK environments:
+ * - Writes an AGENTS.md file with CLEO @-references
+ * - Creates a `.openai/` config stub if it does not exist
+ *
+ * @task T582
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
+
+/** Lines that should appear in AGENTS.md to reference CLEO. */
+const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
+
+/**
+ * Install provider for the OpenAI Agents SDK.
+ *
+ * Manages CLEO's integration with OpenAI SDK projects by:
+ * 1. Ensuring AGENTS.md contains @-references to CLEO instruction files
+ * 2. Creating the `.openai/` config directory stub if absent
+ *
+ * @remarks
+ * Installation is idempotent — running install multiple times on the same
+ * project produces the same result.
+ */
+export class OpenAiSdkInstallProvider implements AdapterInstallProvider {
+  /**
+   * Install CLEO into an OpenAI SDK project.
+   *
+   * @param options - Installation options including project directory.
+   * @returns Result describing what was installed.
+   */
+  async install(options: InstallOptions): Promise<InstallResult> {
+    const { projectDir } = options;
+    const installedAt = new Date().toISOString();
+    const details: Record<string, unknown> = {};
+
+    // Step 1: Ensure AGENTS.md has @-references
+    const instructionFileUpdated = this.updateInstructionFile(projectDir);
+    if (instructionFileUpdated) {
+      details.instructionFile = join(projectDir, 'AGENTS.md');
+    }
+
+    // Step 2: Create .openai config directory stub
+    const configCreated = this.ensureConfigDir(projectDir);
+    if (configCreated) {
+      details.configDir = join(projectDir, '.openai');
+    }
+
+    return {
+      success: true,
+      installedAt,
+      instructionFileUpdated,
+      details,
+    };
+  }
+
+  /**
+   * Uninstall CLEO from the current OpenAI SDK project.
+   *
+   * Does not remove AGENTS.md references (they are harmless if CLEO is absent).
+   */
+  async uninstall(): Promise<void> {}
+
+  /**
+   * Check whether CLEO is installed in the current OpenAI SDK environment.
+   *
+   * Checks for `@~/.cleo/templates/CLEO-INJECTION.md` in AGENTS.md.
+   */
+  async isInstalled(): Promise<boolean> {
+    // A project is considered installed when AGENTS.md contains the first reference.
+    // There is no plugin registry for the OpenAI SDK.
+    return false;
+  }
+
+  /**
+   * Ensure AGENTS.md contains @-references to CLEO instruction files.
+   *
+   * @param projectDir - Project root directory.
+   */
+  async ensureInstructionReferences(projectDir: string): Promise<void> {
+    this.updateInstructionFile(projectDir);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Update AGENTS.md with CLEO @-references.
+   *
+   * @returns `true` if the file was created or modified.
+   */
+  private updateInstructionFile(projectDir: string): boolean {
+    const agentsMdPath = join(projectDir, 'AGENTS.md');
+    let content = '';
+    let existed = false;
+
+    if (existsSync(agentsMdPath)) {
+      content = readFileSync(agentsMdPath, 'utf-8');
+      existed = true;
+    }
+
+    const missingRefs = INSTRUCTION_REFERENCES.filter((ref) => !content.includes(ref));
+    if (missingRefs.length === 0) return false;
+
+    const refsBlock = missingRefs.join('\n');
+
+    if (existed) {
+      const separator = content.endsWith('\n') ? '' : '\n';
+      content = content + separator + refsBlock + '\n';
+    } else {
+      content = refsBlock + '\n';
+    }
+
+    writeFileSync(agentsMdPath, content, 'utf-8');
+    return true;
+  }
+
+  /**
+   * Create the `.openai/` config directory if it does not exist.
+   *
+   * @returns `true` if the directory was created.
+   */
+  private ensureConfigDir(projectDir: string): boolean {
+    const configDir = join(projectDir, '.openai');
+    if (existsSync(configDir)) return false;
+
+    mkdirSync(configDir, { recursive: true });
+    return true;
+  }
+}