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) 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.

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

• types — Core types: LlmProvider trait, messages, requests, errors
• config — Runner types and configuration
• agent — Configurable agent loop with multi-turn tool calling
• fallback — Provider fallback chains (try providers in order)
• mcp_tool_bridge — MCP tool definition to text-tool-simulation bridge
• metrics — Cost/latency normalization decorator
• quality_gate — Response quality validation with retry
• structured_output — Schema-enforced JSON output from any provider
• compat — Version compatibility and capability detection
• container — Container-based execution backend
• discovery — Automatic binary detection on the host
• capability_guard — Request/provider capability validation
• auth — Readiness and authentication checking
• process — Subprocess spawning with timeout and output limits
• sandbox — Environment variable whitelisting and working directory control
• prompt — Prompt building from ChatMessage slices
• 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
• 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 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::parse_runner_type;

pub use factory::valid_provider_names;

pub use factory::ALL_PROVIDERS;

pub use fallback::FallbackProvider;

pub use gemini_cli::GeminiCliRunner;

pub use goose_cli::GooseCliRunner;

pub use mcp_tool_bridge::McpToolDefinition;

pub use mcp_tool_bridge::McpToolExecutor;

pub use metrics::MetricsProvider;

pub use metrics::MetricsReport;

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::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;

Modules

agent

Configurable agent loop with multi-turn tool calling

auth

Auth readiness checking for CLI runners

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

container

Container-based execution backend

continue_cli

Continue CLI runner

copilot

GitHub Copilot CLI runner

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

mcp_tool_bridge

MCP tool definition to text-tool-simulation bridge

metrics

Cost/latency normalization decorator

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.