use std::collections::BTreeMap;
use std::collections::VecDeque;
use std::path::{Path, PathBuf};
use arabica_protocol::{RunId, SessionId};
use arabica_provider::{
ApiModelProvider, ApiProviderConfig, BlendProvider, ModelProgressSink, ModelProvider,
ModelRunRequest, ModelRunResult, ProviderError,
};
pub use arabica_runner::LocalRunnerPolicy;
use arabica_runner::{
LocalRunner, RunnerEnvironment, RunnerError, ToolExecutionRequest, ToolExecutionResult,
};
use arabica_runtime::{
CoreRuntime, RuntimeArchiveStore, RuntimeCompactionStrategy, ShortMemoryPolicy,
memory_read_definition, memory_search_definition,
};
use arabica_session::IdAllocator;
use clap::Args;
use sha2::{Digest, Sha256};
const MAX_MODEL_STEPS_PER_RUN: usize = 100;
#[derive(Debug, Default)]
pub struct UuidIds;
impl IdAllocator for UuidIds {
fn session_id(&mut self) -> SessionId {
SessionId::new(uuid::Uuid::now_v7().to_string())
}
fn run_id(&mut self) -> RunId {
RunId::new(uuid::Uuid::now_v7().to_string())
}
}
#[derive(Args, Clone, Debug, Default)]
pub struct HostConfigArgs {
#[arg(long)]
pub model: Option<String>,
#[arg(long, conflicts_with = "model")]
pub model_alias: Option<String>,
#[arg(long)]
pub policy: Option<String>,
#[arg(long)]
pub thinking: Option<String>,
#[arg(long)]
pub api_type: Option<String>,
#[arg(long)]
pub base_url: Option<String>,
}
#[derive(Clone, Debug)]
pub struct HostModelCatalog {
pub provider: ApiProviderConfig,
pub models: BTreeMap<String, String>,
pub blend_policy: Option<arabica_runtime::BlendRoutingPolicy>,
pub model_configs: BTreeMap<String, ApiProviderConfig>,
}
impl HostModelCatalog {
pub fn build_model(&self) -> Result<HostModel, ProviderError> {
if self.models.is_empty() {
return ApiModelProvider::new(self.provider.clone()).map(HostModel::Api);
}
let default_alias = self
.blend_policy
.as_ref()
.map(|policy| policy.default_model.as_str())
.unwrap_or_else(|| self.models.keys().next().expect("non-empty model catalog"));
if self.model_configs.is_empty() {
BlendProvider::from_shared_config(
self.provider.clone(),
default_alias,
self.models.clone(),
)
.map(HostModel::Blend)
} else {
BlendProvider::from_configs(default_alias, self.model_configs.clone())
.map(HostModel::Blend)
}
}
}
pub fn process_environment(name: &str) -> Option<String> {
std::env::var(name).ok()
}
#[derive(Debug)]
pub enum HostModel {
Api(ApiModelProvider),
Blend(BlendProvider),
StreamingApi(ApiModelProvider, ModelProgressSink),
Scripted(ScriptedModel),
}
impl ModelProvider for HostModel {
fn model_id(&self) -> Option<&str> {
match self {
Self::Api(model) | Self::StreamingApi(model, _) => model.model_id(),
Self::Blend(model) => model.model_id(),
Self::Scripted(model) => model.model_id(),
}
}
fn model_registry_snapshot(&self) -> String {
match self {
Self::Blend(model) => model.model_registry_snapshot(),
Self::Api(model) | Self::StreamingApi(model, _) => model.model_registry_snapshot(),
Self::Scripted(model) => model.model_registry_snapshot(),
}
}
fn supports_model_alias(&self, alias: &str) -> bool {
match self {
Self::Api(model) | Self::StreamingApi(model, _) => model.supports_model_alias(alias),
Self::Blend(model) => model.supports_model_alias(alias),
Self::Scripted(model) => model.supports_model_alias(alias),
}
}
async fn complete(
&mut self,
request: ModelRunRequest,
) -> Result<ModelRunResult, ProviderError> {
match self {
Self::Api(model) => model.complete(request).await,
Self::Blend(model) => model.complete(request).await,
Self::StreamingApi(model, progress) => {
model.complete_with_progress(request, progress).await
}
Self::Scripted(model) => model.complete(request).await,
}
}
async fn complete_with_model(
&mut self,
request: ModelRunRequest,
model_alias: &str,
) -> Result<ModelRunResult, ProviderError> {
match self {
Self::Blend(model) => model.complete_with_model(request, model_alias).await,
Self::Api(model) | Self::StreamingApi(model, _) => {
model.complete_with_model(request, model_alias).await
}
Self::Scripted(model) => model.complete_with_model(request, model_alias).await,
}
}
async fn cancel(&mut self, run_id: &RunId) -> Result<bool, ProviderError> {
match self {
Self::Api(model) => model.cancel(run_id).await,
Self::Blend(model) => model.cancel(run_id).await,
Self::StreamingApi(model, _) => model.cancel(run_id).await,
Self::Scripted(model) => model.cancel(run_id).await,
}
}
}
#[derive(Debug, Default)]
pub struct ScriptedModel {
results: VecDeque<ModelRunResult>,
}
impl ScriptedModel {
pub fn new(results: impl IntoIterator<Item = ModelRunResult>) -> Self {
Self {
results: results.into_iter().collect(),
}
}
}
impl ModelProvider for ScriptedModel {
async fn complete(
&mut self,
_request: ModelRunRequest,
) -> Result<ModelRunResult, ProviderError> {
self.results
.pop_front()
.ok_or_else(|| ProviderError::new("scripted model has no more responses"))
}
async fn cancel(&mut self, _run_id: &RunId) -> Result<bool, ProviderError> {
Ok(false)
}
}
#[derive(Debug)]
pub struct HostRunner {
local: LocalRunner,
remote: Option<arabica_runner_remote::RemoteRunner>,
remote_tools: (u64, Vec<String>),
mcp: crate::mcp::McpTools,
root: PathBuf,
writes: std::sync::Arc<std::sync::Mutex<crate::checkpoint::WriteJournal>>,
}
impl HostRunner {
pub(crate) fn write_journal(
&self,
) -> std::sync::Arc<std::sync::Mutex<crate::checkpoint::WriteJournal>> {
std::sync::Arc::clone(&self.writes)
}
pub fn remote_tool_names(&self) -> &[String] {
&self.remote_tools.1
}
async fn execute_with_checkpoint(
&mut self,
request: ToolExecutionRequest,
) -> Result<ToolExecutionResult, RunnerError> {
let paths = crate::checkpoint::mutating_paths(&request.call);
if paths.is_empty() {
return self.local.execute(request).await;
}
let call_id = request.call.call_id.clone();
let tool = request.call.name.clone();
let mut before = Vec::with_capacity(paths.len());
for path in &paths {
before.push(tokio::fs::read(self.root.join(path)).await.ok());
}
let result = self.local.execute(request).await;
let mut movements = Vec::with_capacity(paths.len());
for (path, before) in paths.iter().zip(before) {
let after = tokio::fs::read(self.root.join(path)).await.ok();
if before != after {
movements.push(crate::checkpoint::FileMovement {
path: path.clone(),
before,
after,
});
}
}
if !movements.is_empty() {
self.writes
.lock()
.expect("write journal lock poisoned")
.record(crate::checkpoint::WriteCheckpoint {
call_id,
tool,
movements,
});
}
result
}
}
impl RunnerEnvironment for HostRunner {
fn classify(
&self,
call: &arabica_model::ToolCallItem,
) -> arabica_protocol::ToolInteractionKind {
if matches!(
call.name.as_str(),
arabica_runtime::CREATE_PLAN_TOOL_NAME | arabica_runtime::UPDATE_PLAN_TOOL_NAME
) {
arabica_protocol::ToolInteractionKind::Plan
} else if self.mcp.contains(&call.name) {
self.mcp.classify(call)
} else if let Some(remote) = &self.remote {
remote.classify(call)
} else {
self.local.classify(call)
}
}
async fn execute(
&mut self,
request: ToolExecutionRequest,
) -> Result<ToolExecutionResult, RunnerError> {
if self.mcp.contains(&request.call.name) {
self.mcp.execute(request).await
} else if let Some(remote) = &mut self.remote {
remote.execute(request).await
} else {
self.execute_with_checkpoint(request).await
}
}
async fn cancel(&mut self, run_id: &RunId) -> Result<bool, RunnerError> {
let local = self.local.cancel(run_id).await?;
let mcp = self.mcp.cancel(run_id).await?;
let remote = match &mut self.remote {
Some(remote) => remote.cancel(run_id).await?,
None => false,
};
Ok(local || mcp || remote)
}
}
pub type HostRuntime = CoreRuntime<HostModel, HostRunner>;
pub fn sync_remote_tools(runtime: &mut HostRuntime) -> bool {
let runner = runtime.runner_mut();
let Some(remote) = &runner.remote else {
return false;
};
let (generation, definitions) = remote.tools_snapshot();
if generation == runner.remote_tools.0 {
return false;
}
let names = definitions.iter().map(|tool| tool.name.clone()).collect();
let (_, withdrawn) = std::mem::replace(&mut runner.remote_tools, (generation, names));
let mut tools = definitions;
tools.extend(
runtime
.tools()
.iter()
.filter(|tool| !withdrawn.contains(&tool.name))
.cloned(),
);
runtime.set_tools(tools);
true
}
pub fn coding_system_instructions(root: &Path) -> String {
format!(
"You are Arabica, an autonomous coding agent working in {}. \
The host operating system is {}. Use paths relative to that \
workspace root for every tool call; the tools refuse absolute \
paths and any path that would escape the root. A user may refer to \
workspace files as @path; inspect those files with read_file before \
relying on their contents.",
root.display(),
std::env::consts::OS,
)
}
pub fn system_instructions(root: &Path) -> Vec<String> {
let mut instructions = vec![coding_system_instructions(root)];
instructions.extend(crate::instructions::rendered(root, root));
instructions
}
pub fn workspace_id_for(cwd: &Path) -> arabica_protocol::WorkspaceId {
let digest = Sha256::digest(cwd.to_string_lossy().as_bytes());
arabica_protocol::WorkspaceId::new(format!("ws-{:.16}", hex::encode(digest)))
}
pub fn build_host_runtime(
model: HostModel,
runner_root: &Path,
tool_policy: LocalRunnerPolicy,
arabica_home: &Path,
) -> HostRuntime {
build_host_runtime_with_mcp(
model,
runner_root,
tool_policy,
arabica_home,
crate::mcp::McpTools::default(),
)
}
pub fn build_host_runtime_with_mcp(
model: HostModel,
runner_root: &Path,
tool_policy: LocalRunnerPolicy,
arabica_home: &Path,
mcp: crate::mcp::McpTools,
) -> HostRuntime {
build_host_runtime_with_runner(model, runner_root, tool_policy, arabica_home, mcp, None)
}
pub fn build_host_runtime_with_runner(
model: HostModel,
runner_root: &Path,
tool_policy: LocalRunnerPolicy,
arabica_home: &Path,
mcp: crate::mcp::McpTools,
remote: Option<arabica_runner_remote::RemoteRunner>,
) -> HostRuntime {
let (remote_generation, mut tools) = match &remote {
Some(remote) => remote.tools_snapshot(),
None => (0, arabica_runner::tool_definitions(&tool_policy)),
};
let remote_names = if remote.is_some() {
tools.iter().map(|tool| tool.name.clone()).collect()
} else {
Vec::new()
};
let remote_tools = (remote_generation, remote_names);
tools.extend(arabica_runtime::plan_tool_definitions());
tools.push(memory_search_definition());
tools.push(memory_read_definition());
tools.extend_from_slice(mcp.definitions());
let context_identities = mcp.context_identities();
let runner = HostRunner {
local: LocalRunner::with_policy(runner_root, tool_policy),
remote,
remote_tools,
mcp,
root: runner_root.to_path_buf(),
writes: std::sync::Arc::new(std::sync::Mutex::new(
crate::checkpoint::WriteJournal::default(),
)),
};
let archive_root = arabica_home
.join("runtime-memory")
.join(workspace_id_for(runner_root).to_string());
let mut runtime = CoreRuntime::with_memory_configuration(
model,
runner,
ShortMemoryPolicy::default(),
false,
RuntimeArchiveStore::File { root: archive_root },
);
runtime.set_compaction_strategy(RuntimeCompactionStrategy::FileBackedGc);
runtime.set_async_file_backed_gc(true);
runtime.set_tools(tools);
runtime.set_context_identities(context_identities);
runtime.set_max_model_steps_per_run(MAX_MODEL_STEPS_PER_RUN);
runtime.set_max_model_steps_without_progress(usize::MAX);
runtime.set_system_instructions(system_instructions(runner_root));
runtime
}
pub fn build_host_runtime_with_blend(
model: HostModel,
runner_root: &Path,
tool_policy: LocalRunnerPolicy,
arabica_home: &Path,
mcp: crate::mcp::McpTools,
blend_policy: Option<arabica_runtime::BlendRoutingPolicy>,
) -> Result<HostRuntime, arabica_runtime::RuntimeError> {
build_host_runtime_with_blend_and_runner(
model,
runner_root,
tool_policy,
arabica_home,
mcp,
None,
blend_policy,
)
}
pub fn build_host_runtime_with_blend_and_runner(
model: HostModel,
runner_root: &Path,
tool_policy: LocalRunnerPolicy,
arabica_home: &Path,
mcp: crate::mcp::McpTools,
remote: Option<arabica_runner_remote::RemoteRunner>,
blend_policy: Option<arabica_runtime::BlendRoutingPolicy>,
) -> Result<HostRuntime, arabica_runtime::RuntimeError> {
let mut runtime =
build_host_runtime_with_runner(model, runner_root, tool_policy, arabica_home, mcp, remote);
runtime.set_blend_policy(blend_policy)?;
let context_policy = crate::config::user_config_context(arabica_home).map_err(|_| {
arabica_runtime::RuntimeError::new(
arabica_runtime::RuntimeErrorKind::InvalidConfiguration,
"invalid context configuration",
)
})?;
runtime.set_context_policy(context_policy)?;
let roots = crate::config::user_config_skill_roots(arabica_home).map_err(|_| {
arabica_runtime::RuntimeError::new(
arabica_runtime::RuntimeErrorKind::InvalidConfiguration,
"invalid skill source configuration",
)
})?;
if !roots.is_empty() {
let source = crate::skills::LocalSkillSource::new(roots);
let _ = arabica_runtime::SkillSource::load(&source)?;
runtime.set_skill_source(Box::new(source));
}
Ok(runtime)
}
pub(crate) fn session_store(home: &Path) -> std::sync::Arc<dyn arabica_session::SessionStore> {
std::sync::Arc::new(arabica_adapters::SqliteSessionRepository::new(home))
}
#[cfg(test)]
mod tests {
use super::*;
use arabica_runtime::HistoryProjection;
#[tokio::test]
async fn host_model_dispatches_to_the_scripted_variant() {
let mut model = HostModel::Scripted(ScriptedModel::new([ModelRunResult {
final_output: Some("done".to_owned()),
prepared_request: None,
response: None,
}]));
let request = ModelRunRequest {
images: Vec::new(),
session_id: arabica_protocol::SessionId::new("s"),
run_id: RunId::new("r"),
input: "hi".to_owned(),
short_memory: Vec::new(),
run_memory: Vec::new(),
long_memory: Vec::new(),
tools: Vec::new(),
tool_choice: arabica_model::ToolChoice::Auto,
continuation: Vec::new(),
disclosure: arabica_protocol::DisclosureLevel::Detail,
system_instructions: Vec::new(),
};
let result = model.complete(request).await.expect("scripted response");
assert_eq!(result.final_output.as_deref(), Some("done"));
}
fn temp_root(label: &str) -> std::path::PathBuf {
let unique = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.expect("clock is valid")
.as_nanos();
let root = std::env::temp_dir().join(format!("arabica-cli-host-{label}-{unique}"));
std::fs::create_dir(&root).expect("test root is created");
root
}
#[test]
fn build_host_runtime_fixes_the_cli_profile() {
let root = temp_root("profile");
let runtime = build_host_runtime(
HostModel::Scripted(ScriptedModel::default()),
&root,
LocalRunnerPolicy::coding(),
&root.join("state"),
);
assert_eq!(
runtime.compaction_strategy(),
RuntimeCompactionStrategy::FileBackedGc
);
assert_eq!(runtime.history_projection(), HistoryProjection::Policy);
assert_eq!(
runtime.archive_store(),
&RuntimeArchiveStore::File {
root: root
.join("state/runtime-memory")
.join(workspace_id_for(&root).to_string()),
}
);
assert_eq!(runtime.max_model_steps_per_run(), MAX_MODEL_STEPS_PER_RUN);
assert_eq!(runtime.max_model_steps_without_progress(), usize::MAX);
assert_eq!(runtime.system_instructions().len(), 1);
assert!(runtime.system_instructions()[0].contains(&root.display().to_string()));
assert!(runtime.system_instructions()[0].contains(std::env::consts::OS));
let names: Vec<&str> = runtime
.tools()
.iter()
.map(|tool| tool.name.as_str())
.collect();
assert_eq!(
names,
vec![
"read_file",
"list_dir",
"grep",
"find_files",
"write_file",
"edit_files",
"delete_file",
"create_plan",
"update_plan",
"memory_search",
"memory_read",
]
);
assert!(!names.contains(&"runtime_complete"));
std::fs::remove_dir_all(root).expect("cleanup");
}
#[test]
fn build_host_runtime_includes_discovered_project_instructions() {
let root = temp_root("agents-md");
std::fs::write(root.join("AGENTS.md"), "Never edit generated files.\n")
.expect("instruction file is written");
let runtime = build_host_runtime(
HostModel::Scripted(ScriptedModel::default()),
&root,
LocalRunnerPolicy::coding(),
&root.join("state"),
);
let instructions = runtime.system_instructions();
assert_eq!(instructions.len(), 2);
assert!(
instructions[1].starts_with("Project instructions from AGENTS.md at AGENTS.md:\n\n")
);
assert!(instructions[1].contains("Never edit generated files."));
std::fs::remove_dir_all(root).expect("cleanup");
}
#[test]
fn build_host_runtime_honors_a_policy_without_shell() {
let root = temp_root("no-shell");
let runtime = build_host_runtime(
HostModel::Scripted(ScriptedModel::default()),
&root,
LocalRunnerPolicy::read_only(),
&root.join("state"),
);
assert!(!runtime.tools().iter().any(|tool| tool.name == "shell"));
std::fs::remove_dir_all(root).expect("cleanup");
}
#[tokio::test]
async fn a_local_write_is_checkpointed_and_undoable() {
let root = temp_root("checkpoint");
let mut runner = HostRunner {
local: arabica_runner::LocalRunner::with_policy(&root, LocalRunnerPolicy::coding()),
remote: None,
remote_tools: (0, Vec::new()),
mcp: crate::mcp::McpTools::default(),
root: root.clone(),
writes: std::sync::Arc::new(std::sync::Mutex::new(
crate::checkpoint::WriteJournal::default(),
)),
};
let request = ToolExecutionRequest {
run_id: RunId::new("r"),
call: arabica_model::ToolCallItem {
id: None,
call_id: "call-1".to_owned(),
name: "write_file".to_owned(),
arguments: serde_json::json!({
"path": "note.txt",
"content": "agent content"
}),
provider_state: None,
},
};
let result = runner.execute(request).await.expect("write executes");
assert!(!result.result.is_error);
assert!(root.join("note.txt").exists());
let journal = runner.write_journal();
let mut journal = journal.lock().expect("write journal lock poisoned");
assert!(!journal.is_empty());
assert!(matches!(
journal.undo_last(&root),
crate::checkpoint::UndoOutcome::Reverted { .. }
));
assert!(!root.join("note.txt").exists());
std::fs::remove_dir_all(root).expect("cleanup");
}
#[test]
fn workspace_id_is_stable_for_the_same_cwd_and_differs_for_another() {
let a = workspace_id_for(std::path::Path::new("/workspace/one"));
let a_again = workspace_id_for(std::path::Path::new("/workspace/one"));
let b = workspace_id_for(std::path::Path::new("/workspace/two"));
assert_eq!(a, a_again);
assert_ne!(a, b);
assert!(a.to_string().starts_with("ws-"));
}
}