use std::collections::VecDeque;
use std::path::{Path, PathBuf};
use arabica_protocol::{RunId, SessionId};
use arabica_provider::{
ApiModelProvider, ApiProviderConfig, ApiType, 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())
}
}
mod env {
pub const API_KEY: &str = "OPENAI__API_KEY";
pub const BASE_URL: &str = "OPENAI__BASE_URL";
pub const MODEL: &str = "OPENAI__MODEL";
pub const API_TYPE: &str = "ARABICA__API_TYPE";
}
#[derive(Args, Clone, Debug, Default)]
pub struct HostConfigArgs {
#[arg(long)]
pub model: Option<String>,
#[arg(long)]
pub api_type: Option<String>,
#[arg(long)]
pub base_url: Option<String>,
}
fn require(value: Option<String>, var: &str, flag: &str) -> Result<String, ProviderError> {
value.ok_or_else(|| ProviderError::new(format!("{var} is required (or pass --{flag})")))
}
pub fn resolve_provider_config(
args: &HostConfigArgs,
lookup: impl Fn(&str) -> Option<String>,
) -> Result<ApiProviderConfig, ProviderError> {
let api_type = args
.api_type
.clone()
.or_else(|| lookup(env::API_TYPE))
.unwrap_or_else(|| ApiType::OpenAiChatCompletions.to_string())
.parse::<ApiType>()?;
let api_key = lookup(env::API_KEY).ok_or_else(|| {
ProviderError::new(format!(
"{} is required; export it in your shell, it is never a flag",
env::API_KEY
))
})?;
let base_url = require(
args.base_url.clone().or_else(|| lookup(env::BASE_URL)),
env::BASE_URL,
"base-url",
)?;
let model = require(
args.model.clone().or_else(|| lookup(env::MODEL)),
env::MODEL,
"model",
)?;
Ok(ApiProviderConfig::new(api_type, api_key, base_url, model))
}
pub fn process_environment(name: &str) -> Option<String> {
std::env::var(name).ok()
}
#[derive(Debug)]
pub enum HostModel {
Api(ApiModelProvider),
StreamingApi(ApiModelProvider, ModelProgressSink),
Scripted(ScriptedModel),
}
impl ModelProvider for HostModel {
async fn complete(
&mut self,
request: ModelRunRequest,
) -> Result<ModelRunResult, ProviderError> {
match self {
Self::Api(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 cancel(&mut self, run_id: &RunId) -> Result<bool, ProviderError> {
match self {
Self::Api(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,
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)
}
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 self.mcp.contains(&call.name) {
self.mcp.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 {
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?;
Ok(local || mcp)
}
}
pub type HostRuntime = CoreRuntime<HostModel, HostRunner>;
pub fn coding_system_instructions(root: &Path) -> String {
format!(
"You are Structure, 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}", format!("{digest:x}")))
}
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 {
let mut tools = arabica_runner::tool_definitions(&tool_policy);
tools.push(memory_search_definition());
tools.push(memory_read_definition());
tools.extend_from_slice(mcp.definitions());
let runner = HostRunner {
local: LocalRunner::with_policy(runner_root, tool_policy),
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_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
}
#[cfg(test)]
mod tests {
use super::*;
use arabica_runtime::HistoryProjection;
fn args(model: Option<&str>, api_type: Option<&str>, base_url: Option<&str>) -> HostConfigArgs {
HostConfigArgs {
model: model.map(str::to_owned),
api_type: api_type.map(str::to_owned),
base_url: base_url.map(str::to_owned),
}
}
fn env_map(vars: &[(&str, &str)]) -> impl Fn(&str) -> Option<String> + use<> {
let vars: std::collections::HashMap<String, String> = vars
.iter()
.map(|(name, value)| ((*name).to_owned(), (*value).to_owned()))
.collect();
move |name: &str| vars.get(name).cloned()
}
#[test]
fn a_cli_flag_overrides_its_matching_environment_variable() {
let lookup = env_map(&[
(env::API_KEY, "test-key"),
(env::BASE_URL, "https://env.example/v1"),
(env::MODEL, "env-model"),
]);
let config = resolve_provider_config(&args(Some("flag-model"), None, None), lookup)
.expect("config resolves");
assert_eq!(config.model, "flag-model");
assert_eq!(config.base_url, "https://env.example/v1");
assert_eq!(config.api_type, ApiType::OpenAiChatCompletions);
}
#[test]
fn a_missing_flag_falls_back_to_the_environment_variable() {
let lookup = env_map(&[
(env::API_KEY, "test-key"),
(env::BASE_URL, "u"),
(env::MODEL, "env-model"),
]);
let config = resolve_provider_config(&args(None, None, None), lookup)
.expect("config resolves from the environment alone");
assert_eq!(config.model, "env-model");
}
#[test]
fn a_missing_required_setting_names_both_the_variable_and_the_flag() {
let lookup = env_map(&[(env::API_KEY, "test-key"), (env::MODEL, "m")]);
let error = resolve_provider_config(&args(None, None, None), lookup)
.expect_err("base_url is missing");
let message = error.to_string();
assert!(message.contains("OPENAI__BASE_URL"), "{message}");
assert!(message.contains("--base-url"), "{message}");
}
#[test]
fn the_api_key_has_no_flag_and_must_come_from_the_environment() {
let lookup = env_map(&[(env::BASE_URL, "u"), (env::MODEL, "m")]);
let error = resolve_provider_config(&args(None, None, None), lookup)
.expect_err("the key is missing");
assert!(error.to_string().contains("OPENAI__API_KEY"));
}
#[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 {
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",
"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()),
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-"));
}
}