Crate embacle 

Embacle — LLM Runners

Standalone library providing pluggable LlmProvider implementations that delegate to CLI tools (Claude Code, Copilot, Cursor Agent, OpenCode, Gemini, Codex, Goose, Cline, Continue, Warp, Kiro, Kilo Code), an HTTP API client (OpenAI-compatible), and ACP (Copilot Headless) for LLM completions.

CLI runners wrap a binary, build prompts from ChatMessage sequences, parse JSON output, and manage session continuity. The Copilot Headless runner communicates via NDJSON-framed JSON-RPC with copilot --acp.

Two companion binary crates build on this library:

• embacle-server — OpenAI-compatible REST API + MCP Streamable HTTP on a single port
• embacle-mcp — standalone MCP server over stdio or HTTP

Quick Start

use std::path::PathBuf;
use embacle::{ClaudeCodeRunner, RunnerConfig};
use embacle::types::{ChatMessage, ChatRequest, LlmProvider};

let config = RunnerConfig::new(PathBuf::from("claude"));
let runner = ClaudeCodeRunner::new(config);
let request = ChatRequest::new(vec![ChatMessage::user("Hello!")]);
let response = runner.complete(&request).await?;
println!("{}", response.content);

Fallback Chains

Try multiple providers in order — first success wins:

use std::path::PathBuf;
use embacle::{ClaudeCodeRunner, CopilotRunner, RunnerConfig};
use embacle::fallback::FallbackProvider;
use embacle::types::{ChatMessage, ChatRequest, LlmProvider};

let claude = ClaudeCodeRunner::new(RunnerConfig::new(PathBuf::from("claude")));
let copilot = CopilotRunner::new(RunnerConfig::new(PathBuf::from("copilot"))).await;

let provider = FallbackProvider::new(vec![
    Box::new(claude),
    Box::new(copilot),
])?;

// If claude fails, copilot handles it — same interface
let request = ChatRequest::new(vec![ChatMessage::user("Hello!")]);
let response = provider.complete(&request).await?;

Structured Output

Schema-validated JSON from any provider, with retry on validation failure:

use embacle::structured_output::{request_structured_output, StructuredOutputRequest};
use embacle::types::{ChatMessage, ChatRequest, LlmProvider};
use serde_json::json;

let schema = json!({
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "temperature": {"type": "number"}
    },
    "required": ["city", "temperature"]
});

let request = ChatRequest::new(vec![
    ChatMessage::user("What's the weather in Paris?"),
]);

let data = request_structured_output(
    runner,
    &StructuredOutputRequest { request, schema, max_retries: 2 },
).await?;

assert!(data["city"].is_string());
assert!(data["temperature"].is_number());

Modules

Core

• types — LlmProvider trait, messages, requests, responses, errors
• config — RunnerConfig, CliRunnerType enum
• factory — Runner factory, provider parsing, ALL_PROVIDERS constant

Higher-Level Features

• agent — Multi-turn agent loop with configurable tool calling
• fallback — Ordered provider failover chains
• metrics — Latency, token, and error tracking decorator
• quality_gate — Response validation with retry on refusal
• structured_output — Schema-enforced JSON extraction from any provider
• tool_simulation — XML-based text tool calling for CLI runners without native function calling
• mcp_tool_bridge — MCP tool definitions to text-tool-simulation bridge
• capability_guard — Request/provider capability validation
• guardrail — Pluggable pre/post request validation middleware
• cache — Response caching with TTL and capacity limits

Runner Infrastructure

• auth — Readiness and authentication checking
• discovery — Automatic binary detection on the host
• process — Subprocess spawning with timeout and output limits
• sandbox — Environment variable whitelisting and working directory control
• prompt — Prompt building from ChatMessage slices
• compat — Version compatibility and capability detection
• container — Container-based execution backend

CLI Runners

• claude_code — Claude Code CLI runner
• copilot — GitHub Copilot CLI runner
• cursor_agent — Cursor Agent CLI runner
• opencode — OpenCode CLI runner
• gemini_cli — Gemini CLI runner
• codex_cli — Codex CLI runner
• goose_cli — Goose CLI runner
• cline_cli — Cline CLI runner
• continue_cli — Continue CLI runner
• warp_cli — Warp terminal oz CLI runner
• kiro_cli — Kiro CLI runner
• kilo_cli — Kilo Code CLI runner

Feature-Flagged Runners

• openai_api — OpenAI-compatible HTTP API client (requires openai-api feature)
• copilot_headless — GitHub Copilot Headless ACP runner (requires copilot-headless feature)

Re-exports

pub use agent::AgentExecutor;

pub use agent::AgentResult;

pub use agent::OnTurnCallback;

pub use agent::TurnInfo;

pub use auth::ProviderReadiness;

pub use cache::CacheConfig;

pub use cache::CacheProvider;

pub use cache::CacheStats;

pub use capability_guard::validate_capabilities;

pub use claude_code::ClaudeCodeRunner;

pub use cli_common::CliRunnerBase;

pub use cline_cli::ClineCliRunner;

pub use codex_cli::CodexCliRunner;

pub use compat::CliCapabilities;

pub use config::CliRunnerType;

pub use config::RunnerConfig;

pub use container::ContainerConfig;

pub use container::ContainerExecutor;

pub use container::NetworkMode;

pub use continue_cli::ContinueCliRunner;

pub use copilot::copilot_fallback_models;

pub use copilot::discover_copilot_models;

pub use copilot::CopilotRunner;

pub use cursor_agent::CursorAgentRunner;

pub use discovery::discover_runner;

pub use discovery::resolve_binary;

pub use factory::create_runner;

pub use factory::create_runner_with_config;

pub use factory::parse_runner_type;

pub use factory::valid_provider_names;

pub use factory::ALL_PROVIDERS;

pub use fallback::FallbackProvider;

pub use fallback::RetryConfig;

pub use gemini_cli::GeminiCliRunner;

pub use goose_cli::GooseCliRunner;

pub use guardrail::ContentLengthGuardrail;

pub use guardrail::Guardrail;

pub use guardrail::GuardrailProvider;

pub use guardrail::GuardrailViolation;

pub use guardrail::PiiScrubGuardrail;

pub use guardrail::TopicFilterGuardrail;

pub use kilo_cli::KiloCliRunner;

pub use kiro_cli::KiroCliRunner;

pub use mcp_tool_bridge::McpToolDefinition;

pub use mcp_tool_bridge::McpToolExecutor;

pub use metrics::default_pricing_table;

pub use metrics::MetricsProvider;

pub use metrics::MetricsReport;

pub use metrics::PricingTable;

pub use metrics::TokenPricing;

pub use opencode::OpenCodeRunner;

pub use quality_gate::QualityGateProvider;

pub use quality_gate::QualityPolicy;

pub use structured_output::request_structured_output;

pub use structured_output::StructuredOutputRequest;

pub use warp_cli::WarpCliRunner;

pub use types::ImagePart;

pub use types::ResponseFormat;

pub use types::ToolCallRequest;

pub use types::ToolChoice;

pub use types::ToolDefinition;

pub use tool_simulation::execute_with_text_tools;

pub use tool_simulation::format_tool_results_as_text;

pub use tool_simulation::generate_tool_catalog;

pub use tool_simulation::inject_tool_catalog;

pub use tool_simulation::parse_tool_call_blocks;

pub use tool_simulation::strip_tool_call_blocks;

pub use tool_simulation::FunctionCall;

pub use tool_simulation::FunctionDeclaration;

pub use tool_simulation::FunctionResponse;

pub use tool_simulation::TextToolHandler;

pub use tool_simulation::TextToolResponse;

pub use config_file::build_fallback_from_config;

pub use config_file::build_runner_config;

pub use config_file::load_config;

pub use config_file::load_config_from;

pub use config_file::resolve_alias;

pub use config_file::DefaultsConfig;

pub use config_file::EmbacleConfig;

pub use config_file::FallbackConfig;

pub use config_file::ProviderConfig;

pub use openai_api::OpenAiApiConfig;

pub use openai_api::OpenAiApiRunner;

pub use copilot_headless::CopilotHeadlessRunner;

pub use copilot_headless::HeadlessToolResponse;

pub use copilot_headless::ObservedToolCall;

pub use copilot_headless_config::CopilotHeadlessConfig;

pub use copilot_headless_config::PermissionPolicy;

Modules

agent

Configurable agent loop with multi-turn tool calling

auth

Auth readiness checking for CLI runners

cache

Response caching decorator

capability_guard

Request/provider capability validation

claude_code

Claude Code CLI runner

cli_common

Shared base struct and macro for CLI runner boilerplate

cline_cli

Cline CLI runner

codex_cli

Codex CLI runner

compat

Version compatibility and capability detection

config

Shared configuration types for CLI runners

config_file

TOML-based declarative configuration file loading

container

Container-based execution backend

continue_cli

Continue CLI runner

copilot

GitHub Copilot CLI runner

copilot_headless

Configuration for the Copilot Headless (ACP) provider

copilot_headless_config

Configuration types for the Copilot Headless provider

cursor_agent

Cursor Agent CLI runner

discovery

Binary auto-detection and discovery

factory

Runner factory, provider parsing, and provider enumeration

fallback

Provider fallback chains

gemini_cli

Gemini CLI runner

goose_cli

Goose CLI runner

guardrail

Pluggable guardrail middleware for request/response validation

kilo_cli

Kilo Code CLI runner

kiro_cli

Kiro CLI runner

mcp_tool_bridge

MCP tool definition to text-tool-simulation bridge

metrics

Cost/latency normalization decorator

openai_api

OpenAI-compatible HTTP API client runner

opencode

OpenCode CLI runner

process

Subprocess spawning with safety limits

prompt

Prompt construction from ChatMessage sequences

quality_gate

Response quality validation with retry

sandbox

Environment sandboxing and tool policy

stream

Stream wrapper for child process lifecycle management

structured_output

Schema-enforced JSON output from any provider

tool_simulation

Text-based tool simulation for CLI runners without native function calling

types

Core types: traits, messages, requests, responses, and errors

warp_cli

Warp terminal oz CLI runner

Macros

delegate_provider_base

Generate the boilerplate LlmProvider trait methods.