@malayvuong/agent-orchestra-providers 2026.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nguyen Minh Vuong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,249 @@
+import { ProviderOutput } from '@malayvuong/agent-orchestra-core';
+
+/**
+ * Input to an LLM provider adapter.
+ *
+ * Spec v1.3 §23.3 — the provider adapter receives this and returns
+ * a ProviderOutput after calling the upstream API.
+ */
+type ProviderInput = {
+    /** System-level instructions for the model */
+    systemPrompt: string;
+    /** User-facing prompt content */
+    userPrompt: string;
+    /** Model identifier (e.g. 'gpt-4o', 'claude-sonnet-4-20250514') */
+    model: string;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Sampling temperature (0-2) */
+    temperature?: number;
+    /** Request timeout in milliseconds */
+    timeoutMs?: number;
+    /** Abort signal for cancellation support */
+    abortSignal?: AbortSignal;
+};
+/**
+ * Contract for LLM provider adapters.
+ *
+ * Spec v1.3 §23.3 — each provider handles its own response format
+ * internally and returns a consistent ProviderOutput.
+ */
+interface AgentProvider {
+    /** Execute a prompt against the provider and return normalized output */
+    run(input: ProviderInput): Promise<ProviderOutput>;
+}
+/**
+ * Configuration for provider error responses.
+ */
+type ProviderErrorCode = 'rate_limit' | 'auth_error' | 'server_error' | 'timeout' | 'network_error' | 'invalid_response';
+/**
+ * Structured error thrown by provider adapters.
+ */
+declare class ProviderError extends Error {
+    readonly code: ProviderErrorCode;
+    readonly statusCode?: number | undefined;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, code: ProviderErrorCode, statusCode?: number | undefined, retryable?: boolean, retryAfterMs?: number | undefined);
+}
+
+/**
+ * Configuration options for the OpenAI provider adapter.
+ */
+type OpenAIProviderConfig = {
+    /** API key; defaults to process.env.OPENAI_API_KEY */
+    apiKey?: string;
+    /** Base URL for the API; defaults to 'https://api.openai.com' */
+    baseUrl?: string;
+    /** Default model to use when not specified in ProviderInput */
+    defaultModel?: string;
+};
+/**
+ * OpenAI-compatible provider adapter.
+ *
+ * Spec v1.3 §13.1 — covers OpenAI, Azure, and local proxies via
+ * configurable baseUrl. Uses native fetch (Node 20+), no SDK dependency.
+ */
+declare class OpenAIProvider implements AgentProvider {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly defaultModel;
+    constructor(config?: OpenAIProviderConfig);
+    /**
+     * Execute a chat completion request against the OpenAI API.
+     *
+     * @param input - The provider input containing prompts and parameters
+     * @returns ProviderOutput with rawText, usage data, and optional structured sections
+     * @throws ProviderError on rate limit (429), auth failure (401), server error (5xx), or timeout
+     */
+    run(input: ProviderInput): Promise<ProviderOutput>;
+    /**
+     * Parse the OpenAI API response into a ProviderOutput.
+     */
+    private parseResponse;
+    /**
+     * Handle non-OK HTTP responses from the OpenAI API.
+     */
+    private handleErrorResponse;
+    /**
+     * Estimate cost based on model pricing and token usage.
+     */
+    private estimateCost;
+}
+
+/**
+ * Configuration options for the Anthropic provider adapter.
+ */
+type AnthropicProviderConfig = {
+    /** API key; defaults to process.env.ANTHROPIC_API_KEY */
+    apiKey?: string;
+    /** Default model to use when not specified in ProviderInput */
+    defaultModel?: string;
+};
+/**
+ * Anthropic Messages API provider adapter.
+ *
+ * Spec v1.3 §13.1 — native Anthropic adapter for non-OpenAI-compatible
+ * features. Uses native fetch (Node 20+), no SDK dependency.
+ */
+declare class AnthropicProvider implements AgentProvider {
+    private readonly apiKey;
+    private readonly defaultModel;
+    constructor(config?: AnthropicProviderConfig);
+    /**
+     * Execute a message request against the Anthropic Messages API.
+     *
+     * @param input - The provider input containing prompts and parameters
+     * @returns ProviderOutput with rawText, usage data, and optional structured sections
+     * @throws ProviderError on rate limit (429), auth failure (401), server error (5xx), or timeout
+     */
+    run(input: ProviderInput): Promise<ProviderOutput>;
+    /**
+     * Parse the Anthropic Messages API response into a ProviderOutput.
+     */
+    private parseResponse;
+    /**
+     * Handle non-OK HTTP responses from the Anthropic API.
+     */
+    private handleErrorResponse;
+    /**
+     * Estimate cost based on model pricing and token usage.
+     */
+    private estimateCost;
+}
+
+/**
+ * Configuration options for the Claude CLI provider.
+ */
+type ClaudeCliProviderConfig = {
+    /** Path to the claude binary; defaults to 'claude' (from PATH) */
+    command?: string;
+    /** Default model; defaults to 'sonnet' */
+    defaultModel?: string;
+};
+/**
+ * Provider adapter that uses the Claude Code CLI (`claude`) as the LLM backend.
+ *
+ * Invokes `claude -p <prompt> --model <model> --output-format text` as a subprocess.
+ * The CLI handles its own authentication — no API key required if already logged in.
+ *
+ * Prompts are piped via stdin to avoid shell escaping issues with large content.
+ */
+declare class ClaudeCliProvider implements AgentProvider {
+    private readonly command;
+    private readonly defaultModel;
+    constructor(config?: ClaudeCliProviderConfig);
+    run(input: ProviderInput): Promise<ProviderOutput>;
+}
+
+/**
+ * Configuration options for the Codex CLI provider.
+ */
+type CodexCliProviderConfig = {
+    /** Path to the codex binary; defaults to 'codex' (from PATH) */
+    command?: string;
+    /** Default model; defaults to 'o4-mini' */
+    defaultModel?: string;
+};
+/**
+ * Provider adapter that uses the OpenAI Codex CLI (`codex`) as the LLM backend.
+ *
+ * Invokes `codex -p <prompt> --model <model>` as a subprocess.
+ * The CLI handles its own authentication — no API key required if already logged in.
+ *
+ * Prompts are passed via the -p flag with the full combined prompt.
+ */
+declare class CodexCliProvider implements AgentProvider {
+    private readonly command;
+    private readonly defaultModel;
+    constructor(config?: CodexCliProviderConfig);
+    run(input: ProviderInput): Promise<ProviderOutput>;
+}
+
+/**
+ * Check whether a CLI command is available on the system PATH.
+ */
+declare function isCommandAvailable(command: string): Promise<boolean>;
+/** Result of detecting available CLI providers */
+type DetectedProviders = {
+    claudeCli: boolean;
+    codexCli: boolean;
+    preferred: 'claude-cli' | 'codex-cli' | null;
+};
+/**
+ * Detect which CLI-based LLM tools are available on the system.
+ * Returns the preferred provider (claude-cli first, then codex-cli).
+ */
+declare function detectCliProviders(): Promise<DetectedProviders>;
+
+/**
+ * Minimal agent shape needed for provider routing.
+ * Matches AgentAssignment from core without importing it.
+ */
+interface AgentRef {
+    id: string;
+    providerKey: string;
+    modelOrCommand: string;
+}
+/**
+ * ProviderRouter dispatches provider calls to per-agent provider instances.
+ *
+ * The protocol runner calls `router.forAgent(agent).run(input)` instead of
+ * calling a single provider directly. This enables different agents to use
+ * different LLM backends (CLI tools, API providers, etc.)
+ *
+ * Backward-compatible: when constructed with only a default provider,
+ * `forAgent()` always returns that default.
+ */
+declare class ProviderRouter {
+    private readonly providers;
+    private readonly defaultProvider;
+    constructor(defaultProvider: AgentProvider);
+    /**
+     * Register a provider for a specific agent ID.
+     */
+    setProvider(agentId: string, provider: AgentProvider): void;
+    /**
+     * Register a provider for agents matching a provider key.
+     * This is a convenience for config-driven setups where the agent ID
+     * isn't known yet but the provider key is.
+     */
+    setProviderByKey(providerKey: string, provider: AgentProvider): void;
+    /**
+     * Resolve the provider for a given agent.
+     *
+     * Lookup order:
+     * 1. Exact agent ID match
+     * 2. Provider key match (via setProviderByKey)
+     * 3. Default provider
+     */
+    forAgent(agent: AgentRef): AgentProvider;
+    /**
+     * Also implement the AgentProvider interface directly so the router
+     * can be used as a drop-in replacement for a single provider.
+     * Uses the default provider.
+     */
+    run(input: ProviderInput): Promise<ProviderOutput>;
+}
+
+export { type AgentProvider, AnthropicProvider, type AnthropicProviderConfig, ClaudeCliProvider, type ClaudeCliProviderConfig, CodexCliProvider, type CodexCliProviderConfig, type DetectedProviders, OpenAIProvider, type OpenAIProviderConfig, ProviderError, type ProviderErrorCode, type ProviderInput, ProviderRouter, detectCliProviders, isCommandAvailable };

package/dist/index.js

@@ -0,0 +1,695 @@
+// src/types.ts
+var ProviderError = class extends Error {
+  constructor(message, code, statusCode, retryable = false, retryAfterMs) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.retryable = retryable;
+    this.retryAfterMs = retryAfterMs;
+    this.name = "ProviderError";
+  }
+};
+
+// src/openai/adapter.ts
+var MODEL_PRICING = {
+  "gpt-4o": { input: 2.5, output: 10 },
+  "gpt-4o-mini": { input: 0.15, output: 0.6 },
+  "gpt-4-turbo": { input: 10, output: 30 },
+  "gpt-4": { input: 30, output: 60 },
+  "gpt-3.5-turbo": { input: 0.5, output: 1.5 }
+};
+var DEFAULT_TIMEOUT_MS = 12e4;
+var DEFAULT_MAX_TOKENS = 4096;
+var OpenAIProvider = class {
+  apiKey;
+  baseUrl;
+  defaultModel;
+  constructor(config = {}) {
+    this.apiKey = config.apiKey ?? process.env.OPENAI_API_KEY ?? "";
+    this.baseUrl = (config.baseUrl ?? "https://api.openai.com").replace(/\/+$/, "");
+    this.defaultModel = config.defaultModel ?? "gpt-4o";
+    if (!this.apiKey) {
+      throw new ProviderError(
+        "OpenAI API key is required. Set OPENAI_API_KEY environment variable or pass apiKey in config.",
+        "auth_error"
+      );
+    }
+  }
+  /**
+   * Execute a chat completion request against the OpenAI API.
+   *
+   * @param input - The provider input containing prompts and parameters
+   * @returns ProviderOutput with rawText, usage data, and optional structured sections
+   * @throws ProviderError on rate limit (429), auth failure (401), server error (5xx), or timeout
+   */
+  async run(input) {
+    const model = input.model || this.defaultModel;
+    const maxTokens = input.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const requestBody = {
+      model,
+      messages: [
+        { role: "system", content: input.systemPrompt },
+        { role: "user", content: input.userPrompt }
+      ],
+      max_tokens: maxTokens,
+      ...input.temperature !== void 0 && { temperature: input.temperature }
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    if (input.abortSignal) {
+      if (input.abortSignal.aborted) {
+        controller.abort();
+      } else {
+        input.abortSignal.addEventListener("abort", () => controller.abort(), { once: true });
+      }
+    }
+    const startTime = Date.now();
+    try {
+      const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify(requestBody),
+        signal: controller.signal
+      });
+      const latencyMs = Date.now() - startTime;
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+      const data = await response.json();
+      return this.parseResponse(data, model, latencyMs);
+    } catch (error) {
+      if (error instanceof ProviderError) {
+        throw error;
+      }
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new ProviderError(
+          `OpenAI request timed out after ${timeoutMs}ms`,
+          "timeout",
+          void 0,
+          true
+        );
+      }
+      throw new ProviderError(
+        `OpenAI request failed: ${error instanceof Error ? error.message : String(error)}`,
+        "network_error",
+        void 0,
+        true
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Parse the OpenAI API response into a ProviderOutput.
+   */
+  parseResponse(data, model, latencyMs) {
+    const choices = data.choices;
+    if (!choices || choices.length === 0) {
+      throw new ProviderError("OpenAI response contained no choices", "invalid_response");
+    }
+    const rawText = choices[0]?.message?.content ?? "";
+    const usage = data.usage;
+    const inputTokens = usage?.prompt_tokens;
+    const outputTokens = usage?.completion_tokens;
+    const cost = this.estimateCost(model, inputTokens, outputTokens);
+    const warnings = [];
+    if (choices[0]?.finish_reason === "length") {
+      warnings.push("Response was truncated due to max_tokens limit");
+    }
+    return {
+      rawText,
+      warnings: warnings.length > 0 ? warnings : void 0,
+      usage: {
+        inputTokens,
+        outputTokens,
+        cost,
+        latencyMs
+      }
+    };
+  }
+  /**
+   * Handle non-OK HTTP responses from the OpenAI API.
+   */
+  async handleErrorResponse(response) {
+    let errorMessage;
+    try {
+      const errorData = await response.json();
+      errorMessage = errorData.error?.message ?? response.statusText;
+    } catch {
+      errorMessage = response.statusText;
+    }
+    switch (response.status) {
+      case 401:
+        throw new ProviderError(`OpenAI authentication failed: ${errorMessage}`, "auth_error", 401);
+      case 429: {
+        const retryAfter = response.headers.get("retry-after");
+        const retryAfterMs = retryAfter ? parseInt(retryAfter, 10) * 1e3 : void 0;
+        throw new ProviderError(
+          `OpenAI rate limit exceeded: ${errorMessage}`,
+          "rate_limit",
+          429,
+          true,
+          retryAfterMs
+        );
+      }
+      default:
+        if (response.status >= 500) {
+          throw new ProviderError(
+            `OpenAI server error (${response.status}): ${errorMessage}`,
+            "server_error",
+            response.status,
+            true
+          );
+        }
+        throw new ProviderError(
+          `OpenAI request failed (${response.status}): ${errorMessage}`,
+          "server_error",
+          response.status
+        );
+    }
+  }
+  /**
+   * Estimate cost based on model pricing and token usage.
+   */
+  estimateCost(model, inputTokens, outputTokens) {
+    const pricing = MODEL_PRICING[model];
+    if (!pricing || inputTokens === void 0 || outputTokens === void 0) {
+      return void 0;
+    }
+    return inputTokens / 1e6 * pricing.input + outputTokens / 1e6 * pricing.output;
+  }
+};
+
+// src/anthropic/adapter.ts
+var ANTHROPIC_API_URL = "https://api.anthropic.com";
+var ANTHROPIC_VERSION = "2023-06-01";
+var MODEL_PRICING2 = {
+  "claude-sonnet-4-20250514": { input: 3, output: 15 },
+  "claude-opus-4-20250514": { input: 15, output: 75 },
+  "claude-3-5-sonnet-20241022": { input: 3, output: 15 },
+  "claude-3-5-haiku-20241022": { input: 0.8, output: 4 },
+  "claude-3-opus-20240229": { input: 15, output: 75 },
+  "claude-3-haiku-20240307": { input: 0.25, output: 1.25 }
+};
+var DEFAULT_TIMEOUT_MS2 = 12e4;
+var DEFAULT_MAX_TOKENS2 = 4096;
+var AnthropicProvider = class {
+  apiKey;
+  defaultModel;
+  constructor(config = {}) {
+    this.apiKey = config.apiKey ?? process.env.ANTHROPIC_API_KEY ?? "";
+    this.defaultModel = config.defaultModel ?? "claude-sonnet-4-20250514";
+    if (!this.apiKey) {
+      throw new ProviderError(
+        "Anthropic API key is required. Set ANTHROPIC_API_KEY environment variable or pass apiKey in config.",
+        "auth_error"
+      );
+    }
+  }
+  /**
+   * Execute a message request against the Anthropic Messages API.
+   *
+   * @param input - The provider input containing prompts and parameters
+   * @returns ProviderOutput with rawText, usage data, and optional structured sections
+   * @throws ProviderError on rate limit (429), auth failure (401), server error (5xx), or timeout
+   */
+  async run(input) {
+    const model = input.model || this.defaultModel;
+    const maxTokens = input.maxTokens ?? DEFAULT_MAX_TOKENS2;
+    const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+    const requestBody = {
+      model,
+      max_tokens: maxTokens,
+      system: input.systemPrompt,
+      messages: [{ role: "user", content: input.userPrompt }],
+      ...input.temperature !== void 0 && { temperature: input.temperature }
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    if (input.abortSignal) {
+      if (input.abortSignal.aborted) {
+        controller.abort();
+      } else {
+        input.abortSignal.addEventListener("abort", () => controller.abort(), { once: true });
+      }
+    }
+    const startTime = Date.now();
+    try {
+      const response = await fetch(`${ANTHROPIC_API_URL}/v1/messages`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.apiKey,
+          "anthropic-version": ANTHROPIC_VERSION
+        },
+        body: JSON.stringify(requestBody),
+        signal: controller.signal
+      });
+      const latencyMs = Date.now() - startTime;
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+      const data = await response.json();
+      return this.parseResponse(data, model, latencyMs);
+    } catch (error) {
+      if (error instanceof ProviderError) {
+        throw error;
+      }
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new ProviderError(
+          `Anthropic request timed out after ${timeoutMs}ms`,
+          "timeout",
+          void 0,
+          true
+        );
+      }
+      throw new ProviderError(
+        `Anthropic request failed: ${error instanceof Error ? error.message : String(error)}`,
+        "network_error",
+        void 0,
+        true
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Parse the Anthropic Messages API response into a ProviderOutput.
+   */
+  parseResponse(data, model, latencyMs) {
+    const content = data.content;
+    if (!content || content.length === 0) {
+      throw new ProviderError("Anthropic response contained no content blocks", "invalid_response");
+    }
+    const textBlock = content.find((block) => block.type === "text");
+    const rawText = textBlock?.text ?? "";
+    const usage = data.usage;
+    const inputTokens = usage?.input_tokens;
+    const outputTokens = usage?.output_tokens;
+    const cost = this.estimateCost(model, inputTokens, outputTokens);
+    const warnings = [];
+    const stopReason = data.stop_reason;
+    if (stopReason === "max_tokens") {
+      warnings.push("Response was truncated due to max_tokens limit");
+    }
+    return {
+      rawText,
+      warnings: warnings.length > 0 ? warnings : void 0,
+      usage: {
+        inputTokens,
+        outputTokens,
+        cost,
+        latencyMs
+      }
+    };
+  }
+  /**
+   * Handle non-OK HTTP responses from the Anthropic API.
+   */
+  async handleErrorResponse(response) {
+    let errorMessage;
+    try {
+      const errorData = await response.json();
+      errorMessage = errorData.error?.message ?? response.statusText;
+    } catch {
+      errorMessage = response.statusText;
+    }
+    switch (response.status) {
+      case 401:
+        throw new ProviderError(
+          `Anthropic authentication failed: ${errorMessage}`,
+          "auth_error",
+          401
+        );
+      case 429: {
+        const retryAfter = response.headers.get("retry-after");
+        const retryAfterMs = retryAfter ? parseInt(retryAfter, 10) * 1e3 : void 0;
+        throw new ProviderError(
+          `Anthropic rate limit exceeded: ${errorMessage}`,
+          "rate_limit",
+          429,
+          true,
+          retryAfterMs
+        );
+      }
+      default:
+        if (response.status >= 500) {
+          throw new ProviderError(
+            `Anthropic server error (${response.status}): ${errorMessage}`,
+            "server_error",
+            response.status,
+            true
+          );
+        }
+        throw new ProviderError(
+          `Anthropic request failed (${response.status}): ${errorMessage}`,
+          "server_error",
+          response.status
+        );
+    }
+  }
+  /**
+   * Estimate cost based on model pricing and token usage.
+   */
+  estimateCost(model, inputTokens, outputTokens) {
+    const pricing = MODEL_PRICING2[model];
+    if (!pricing || inputTokens === void 0 || outputTokens === void 0) {
+      return void 0;
+    }
+    return inputTokens / 1e6 * pricing.input + outputTokens / 1e6 * pricing.output;
+  }
+};
+
+// src/cli/claude-cli.ts
+import { spawn } from "child_process";
+var DEFAULT_TIMEOUT_MS3 = 9e5;
+var ClaudeCliProvider = class {
+  command;
+  defaultModel;
+  constructor(config = {}) {
+    this.command = config.command ?? "claude";
+    this.defaultModel = config.defaultModel ?? "sonnet";
+  }
+  async run(input) {
+    const model = input.model || this.defaultModel;
+    const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS3;
+    const startTime = Date.now();
+    const combinedPrompt = `${input.systemPrompt}
+
+---
+
+${input.userPrompt}`;
+    const args = ["-p", "--model", model, "--output-format", "text"];
+    if (input.maxTokens) {
+      args.push("--max-tokens", String(input.maxTokens));
+    }
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const resolveOnce = (value) => {
+        if (settled) return;
+        settled = true;
+        resolve(value);
+      };
+      const rejectOnce = (error) => {
+        if (settled) return;
+        settled = true;
+        reject(error);
+      };
+      const child = spawn(this.command, args, {
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: timeoutMs
+      });
+      child.stdin.on("error", (err) => {
+        const code = err.code;
+        if (code === "EPIPE" || code === "ERR_STREAM_DESTROYED") {
+          return;
+        }
+        rejectOnce(
+          new ProviderError(
+            `Claude CLI stdin error: ${err.message}`,
+            "server_error",
+            void 0,
+            true
+          )
+        );
+      });
+      child.stdin.end(combinedPrompt);
+      let stdout = "";
+      let stderr = "";
+      child.stdout.on("data", (chunk) => {
+        stdout += chunk.toString();
+      });
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk.toString();
+      });
+      if (input.abortSignal) {
+        if (input.abortSignal.aborted) {
+          child.kill("SIGTERM");
+        } else {
+          input.abortSignal.addEventListener(
+            "abort",
+            () => {
+              child.kill("SIGTERM");
+            },
+            { once: true }
+          );
+        }
+      }
+      child.on("error", (err) => {
+        if (err.code === "ENOENT") {
+          rejectOnce(
+            new ProviderError(
+              `Claude CLI not found. Install it from https://claude.ai/download or check your PATH.`,
+              "auth_error"
+            )
+          );
+        } else {
+          rejectOnce(
+            new ProviderError(`Claude CLI error: ${err.message}`, "server_error", void 0, true)
+          );
+        }
+      });
+      child.on("close", (code) => {
+        const latencyMs = Date.now() - startTime;
+        if (code !== 0) {
+          if (stderr.includes("authentication") || stderr.includes("login") || stderr.includes("not logged in")) {
+            rejectOnce(
+              new ProviderError(
+                `Claude CLI authentication failed. Run 'claude login' first. stderr: ${stderr.slice(0, 300)}`,
+                "auth_error"
+              )
+            );
+            return;
+          }
+          if (code === null) {
+            rejectOnce(
+              new ProviderError(
+                `Claude CLI timed out after ${timeoutMs}ms`,
+                "timeout",
+                void 0,
+                true
+              )
+            );
+            return;
+          }
+          rejectOnce(
+            new ProviderError(
+              `Claude CLI exited with code ${code}. stderr: ${stderr.slice(0, 500)}`,
+              "server_error",
+              code,
+              true
+            )
+          );
+          return;
+        }
+        const warnings = [];
+        if (stderr && !stderr.startsWith("[")) {
+          const filtered = stderr.trim();
+          if (filtered) warnings.push(filtered.slice(0, 300));
+        }
+        resolveOnce({
+          rawText: stdout.trim(),
+          warnings: warnings.length > 0 ? warnings : void 0,
+          usage: {
+            latencyMs
+          },
+          exitCode: code,
+          stderrText: stderr || void 0
+        });
+      });
+    });
+  }
+};
+
+// src/cli/codex-cli.ts
+import { spawn as spawn2 } from "child_process";
+var DEFAULT_TIMEOUT_MS4 = 3e5;
+var CodexCliProvider = class {
+  command;
+  defaultModel;
+  constructor(config = {}) {
+    this.command = config.command ?? "codex";
+    this.defaultModel = config.defaultModel ?? "o4-mini";
+  }
+  async run(input) {
+    const model = input.model || this.defaultModel;
+    const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS4;
+    const startTime = Date.now();
+    const combinedPrompt = `${input.systemPrompt}
+
+---
+
+${input.userPrompt}`;
+    const args = ["-p", combinedPrompt, "--model", model];
+    return new Promise((resolve, reject) => {
+      const child = spawn2(this.command, args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: timeoutMs
+      });
+      let stdout = "";
+      let stderr = "";
+      child.stdout.on("data", (chunk) => {
+        stdout += chunk.toString();
+      });
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk.toString();
+      });
+      if (input.abortSignal) {
+        if (input.abortSignal.aborted) {
+          child.kill("SIGTERM");
+        } else {
+          input.abortSignal.addEventListener(
+            "abort",
+            () => {
+              child.kill("SIGTERM");
+            },
+            { once: true }
+          );
+        }
+      }
+      child.on("error", (err) => {
+        if (err.code === "ENOENT") {
+          reject(
+            new ProviderError(
+              `Codex CLI not found. Install it with 'npm install -g @openai/codex' or check your PATH.`,
+              "auth_error"
+            )
+          );
+        } else {
+          reject(
+            new ProviderError(`Codex CLI error: ${err.message}`, "server_error", void 0, true)
+          );
+        }
+      });
+      child.on("close", (code) => {
+        const latencyMs = Date.now() - startTime;
+        if (code !== 0) {
+          if (stderr.includes("authentication") || stderr.includes("API key") || stderr.includes("login")) {
+            reject(
+              new ProviderError(
+                `Codex CLI authentication failed. Run 'codex login' or set OPENAI_API_KEY. stderr: ${stderr.slice(0, 300)}`,
+                "auth_error"
+              )
+            );
+            return;
+          }
+          if (code === null) {
+            reject(
+              new ProviderError(
+                `Codex CLI timed out after ${timeoutMs}ms`,
+                "timeout",
+                void 0,
+                true
+              )
+            );
+            return;
+          }
+          reject(
+            new ProviderError(
+              `Codex CLI exited with code ${code}. stderr: ${stderr.slice(0, 500)}`,
+              "server_error",
+              code,
+              true
+            )
+          );
+          return;
+        }
+        const warnings = [];
+        if (stderr) {
+          const filtered = stderr.trim();
+          if (filtered) warnings.push(filtered.slice(0, 300));
+        }
+        resolve({
+          rawText: stdout.trim(),
+          warnings: warnings.length > 0 ? warnings : void 0,
+          usage: {
+            latencyMs
+          },
+          exitCode: code,
+          stderrText: stderr || void 0
+        });
+      });
+    });
+  }
+};
+
+// src/cli/detect.ts
+import { execFile } from "child_process";
+async function isCommandAvailable(command) {
+  const whichCmd = process.platform === "win32" ? "where" : "which";
+  return new Promise((resolve) => {
+    execFile(whichCmd, [command], (error) => {
+      resolve(!error);
+    });
+  });
+}
+async function detectCliProviders() {
+  const [claudeCli, codexCli] = await Promise.all([
+    isCommandAvailable("claude"),
+    isCommandAvailable("codex")
+  ]);
+  let preferred = null;
+  if (claudeCli) preferred = "claude-cli";
+  else if (codexCli) preferred = "codex-cli";
+  return { claudeCli, codexCli, preferred };
+}
+
+// src/router.ts
+var ProviderRouter = class {
+  providers = /* @__PURE__ */ new Map();
+  defaultProvider;
+  constructor(defaultProvider) {
+    this.defaultProvider = defaultProvider;
+  }
+  /**
+   * Register a provider for a specific agent ID.
+   */
+  setProvider(agentId, provider) {
+    this.providers.set(agentId, provider);
+  }
+  /**
+   * Register a provider for agents matching a provider key.
+   * This is a convenience for config-driven setups where the agent ID
+   * isn't known yet but the provider key is.
+   */
+  setProviderByKey(providerKey, provider) {
+    this.providers.set(`key:${providerKey}`, provider);
+  }
+  /**
+   * Resolve the provider for a given agent.
+   *
+   * Lookup order:
+   * 1. Exact agent ID match
+   * 2. Provider key match (via setProviderByKey)
+   * 3. Default provider
+   */
+  forAgent(agent) {
+    const byId = this.providers.get(agent.id);
+    if (byId) return byId;
+    const byKey = this.providers.get(`key:${agent.providerKey}`);
+    if (byKey) return byKey;
+    return this.defaultProvider;
+  }
+  /**
+   * Also implement the AgentProvider interface directly so the router
+   * can be used as a drop-in replacement for a single provider.
+   * Uses the default provider.
+   */
+  async run(input) {
+    return this.defaultProvider.run(input);
+  }
+};
+export {
+  AnthropicProvider,
+  ClaudeCliProvider,
+  CodexCliProvider,
+  OpenAIProvider,
+  ProviderError,
+  ProviderRouter,
+  detectCliProviders,
+  isCommandAvailable
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@malayvuong/agent-orchestra-providers",
+  "version": "2026.3.2",
+  "description": "LLM provider adapters for Agent Orchestra",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicemvp/agent-orchestra.git",
+    "directory": "packages/providers"
+  },
+  "homepage": "https://github.com/nicemvp/agent-orchestra#readme",
+  "bugs": {
+    "url": "https://github.com/nicemvp/agent-orchestra/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@malayvuong/agent-orchestra-core": "2026.3.2",
+    "@malayvuong/agent-orchestra-shared": "2026.3.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}