arabica-runtime 0.13.1

Headless Structure runtime with context management and runner output normalization
Documentation

Arabica

Website · Configuration · Apache-2.0 license

Arabica is a headless AI-agent runtime written in Rust. The project defines a canonical command/event protocol, session lifecycle, model-provider boundary, tool runner, memory policies, and an HTTP/SSE host.

Status: active development (0.1.1). A first native macOS client lives in apps/arabica-desktop. The Rust runtime remains headless.

Architecture

The Cargo workspace is split into small crates with explicit ownership:

Crate Responsibility
arabica-model Shared model-facing content and tool types
arabica-protocol Canonical commands, events, identifiers, and schema
arabica-provider Model-provider abstraction and API implementations
arabica-runner Local tool execution boundary
arabica-runner-remote Loop–Runner Protocol: remote runner client and runner host over WebSocket + mTLS
arabica-runtime Agent loop, long memory, and short-memory projection
arabica-session Session identity, sequencing, history, and lifecycle
arabica-server Axum HTTP and SSE protocol host
arabica-cli Stdio composition host: arabica acp (Agent Client Protocol) and arabica -p (one-shot)

The runtime is protocol-first: clients submit a CommandEnvelope, the session layer validates and sequences the operation, and the runtime emits canonical EventEnvelope values. The HTTP host exposes the same contract without adding client-specific state.

The macOS desktop client uses SwiftUI and AppKit. It launches the CLI's ACP agent as a bundled process and presents conversations, live updates, and tool permission requests. Build instructions are in its README.

HTTP API

arabica-server currently exposes:

Endpoint Purpose
GET /health Liveness check
GET /v1/schema Canonical protocol schema
POST /v1/commands Submit a command and receive emitted events
GET /v1/events Subscribe to events over SSE

The server listens on 127.0.0.1:4096 by default.

Requirements

  • Rust 1.88 or newer
  • A supported model-provider endpoint when running the HTTP server or the CLI

Install the CLI

On macOS or Linux, download the latest release with curl. The installer selects the matching CPU architecture, verifies the published SHA-256 checksum, and installs arabica to ~/.local/bin by default:

curl -fsSL https://haowei2000.github.io/Arabica/install.sh -o install-arabica.sh
sh install-arabica.sh
~/.local/bin/arabica --help

Set ARABICA_INSTALL_DIR to choose another directory or ARABICA_VERSION=v0.1.1 to pin a release. Windows ZIP archives are on GitHub Releases.

With Rust 1.88 or newer, install the published package from crates.io:

cargo install arabica-cli --locked
arabica --help

The package is named arabica-cli; its executable is arabica. See the configuration guide for provider credentials, precedence, Blend routing, MCP tools, and server settings.

Standalone releases support arabica update and daily background updates during interactive use. Use arabica update --auto off to opt out. The macOS app has Check for Updates… and Settings → Updates, including automatic download and installation on quit. See software updates for package manager support, signed downloads, and the one-time upgrade from older versions.

Build and Test

cargo build --workspace
cargo test --workspace
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings

Run the Server

Configure named provider and model candidates. Keys stay in the environment:

export ARABICA_PROVIDER_OPENAI_API_KEY="..."
export ARABICA_PROVIDER_ANTHROPIC_API_KEY="..."
export ARABICA__PROVIDERS_JSON='{"openai":{"api_type":"open_ai_responses","base_url":"https://api.openai.com/v1"},"anthropic":{"api_type":"anthropic_messages","base_url":"https://api.anthropic.com/v1"}}'
export ARABICA__BLEND_MODELS_JSON='{"fast":{"provider":"openai","model_id":"gpt-4.1-mini"},"strong":{"provider":"anthropic","model_id":"claude-sonnet-4-5"}}'
export ARABICA__BLEND_DEFAULT="fast"

Then start the host:

cargo run -p arabica-server

Session persistence

CLI, interactive chat, ACP, and the production HTTP server store session metadata and ordered events in $ARABICA_HOME/sessions.sqlite3 (default: ~/.arabica). The backend-independent SessionStore and SessionWriter ports and shared metadata types live in arabica-session. arabica-adapters::SqliteSessionRepository implements the repository port; CLI and server code select it during composition and use IDs through the port thereafter. SessionWriter keeps exclusive ownership until its final handle (including observer handles) is dropped. SQLite uses WAL and full synchronous transactions. Session ownership locks remain per session, preventing two processes from resuming the same session concurrently. Legacy sessions/<workspace>/<session>.jsonl files are imported transactionally on first access and retained unchanged. After import, SQLite is authoritative; older binaries must not be used to continue imported sessions.

Titles default to the first non-empty user message (up to 80 characters) and are returned in ACP session listings. To rename an inactive session in the current workspace, run:

arabica sessions rename <session-id> "My session title"

The HTTP server restores sessions for its canonical tool root on startup; the embedding AppState::default() remains ephemeral unless with_session_store is called with an Arc<dyn SessionStore> and a tool root. The existing snapshot restore API accepts root sessions only; persisted forks currently cause an explicit startup restore error rather than losing their inherited history. Command deduplication remains in memory across a process lifetime. When backing up an active database, use SQLite's backup facilities so committed WAL data is included.

CLI model blend

The CLI reads ~/.arabica/config.toml. Define reusable provider settings under [providers.<name>]; each [models.<alias>] selects a provider and model ID. Blend routes continue to refer to aliases. Provider API keys come from the configured api_key_env, or by default from ARABICA_PROVIDER_<NAME>_API_KEY (provider name uppercased with non-alphanumeric characters replaced by underscores).

ACP tool permissions can be adjusted in the same file. Rules are allow, ask, or deny; tool-specific rules override default. Without this section, read-only tools remain allowed and other tools ask before running.

[permissions]
default = "ask"

[permissions.tools]
shell = "deny"
write_file = "allow"
edit_files = "ask"

[[permissions.rules]]
tool = "shell"
parameter = "command"
pattern = "(^|[;&|[:space:]])rm([[:space:]]|$)"
action = "deny"

Argument rules are checked in order before the per-tool and default rules. parameter accepts a dot-separated path into the tool arguments (for example command or options.path); * matches the serialized argument object. pattern is a Rust regular expression matched against that parameter's string value (or JSON representation for non-string values).

[providers.openai]
api_type = "open_ai_responses"
base_url = "https://api.openai.com/v1"
api_key_env = "ARABICA_PROVIDER_OPENAI_API_KEY"
max_tokens = 8192
thinking = "high"

[providers.anthropic]
api_type = "anthropic_messages"
base_url = "https://api.anthropic.com/v1"
api_key_env = "ARABICA_PROVIDER_ANTHROPIC_API_KEY"
max_tokens = 8192
request_timeout_secs = 180
anthropic_cache_static_prefix = true

[models.fast]
provider = "openai"
model_id = "gpt-4.1-mini"

[models.strong]
provider = "anthropic"
model_id = "claude-sonnet-4-5"

[blend]
default_policy = "coding"

[blend.policies.coding]
version = 1
default_model = "fast"
after_tool_success = "fast"
after_tool_error = "strong"
recovery_after_no_progress_steps = 2
recovery_model = "strong"
minimum_model_dwell_steps = 2
tool_call_capable_models = ["fast", "strong"]
typed_completion_capable_models = ["fast"]

[[blend.policies.coding.tool_routes]]
id = "sed-shell-route"
model = "strong"
matcher = { type = "event_trace_regex", value = "toolcall\\.shell\\.sed.*toolresult\\.shell\\.success" }

[blend.policies.precise]
version = 1
default_model = "strong"
after_tool_error = "strong"
minimum_model_dwell_steps = 2

The CLI validates every provider reference, alias, credential source, and API-specific setting at startup. A TOML api_key is accepted as a fallback to the environment variable; a config file containing keys must be owner-only (chmod 600). arabica auth login remains a saved-key fallback for the default provider. Open-source users can connect through the official Sign in with ChatGPT flow with the one-step command arabica auth chatgpt-login; after authorization, Arabica automatically configures its default model for ChatGPT plan usage. Tokens are saved under $ARABICA_HOME/chatgpt-auth.json with owner-only permissions and refreshed automatically. Blend routing is active in interactive chat, arabica -p, and ACP sessions. ACP exposes configured policy IDs and model aliases as session selectors. Selecting a policy changes the current session's routing rules; selecting a model changes that policy's session default. For one policy, the earlier flat [blend] fields remain accepted.

Example ChatGPT plan provider:

[providers.openai]
auth = "chatgpt"
api_type = "open_ai_responses"

[models.default]
provider = "openai"
model_id = "gpt-6.1-sol"

base_url defaults to https://api.openai.com/v1 for this auth mode and cannot be overridden. Choose a model available to the connected ChatGPT account. Manage the connection with arabica auth chatgpt-status and arabica auth chatgpt-logout.

The desktop composer exposes Default Model, Blend Policy, and Thinking selectors. Terminal chat offers /model [alias], /policy [name], and /thinking [level]; without an argument, these commands show current selections and available choices. Selections take effect on the next prompt and are saved for the workspace, with reasoning effort saved per alias. Startup flags --model-alias, --policy, and --thinking provide temporary overrides, including in one-shot mode. See the daily development configuration and CLI selection rules for planning, repair, and fixed-model routing.

Optional configuration:

For parallel local development, see the worktree setup guide.

  • ARABICA__PORT: listening port, default 4096
  • ARABICA__PROVIDERS_JSON: server provider definitions, keyed by provider name
  • ARABICA__BLEND_MODELS_JSON: server alias entries with provider and model_id
  • ARABICA__BLEND_DEFAULT: default alias, defaults to the first alias in sorted order
  • ARABICA__BLEND_AFTER_TOOL_SUCCESS: optional alias for the next call after a successful tool result
  • ARABICA__BLEND_AFTER_TOOL_ERROR: optional alias after a tool error
  • ARABICA__BLEND_RECOVERY_MODEL: optional alias after repeated no-progress steps (threshold defaults to 2 and is set by ARABICA__BLEND_RECOVERY_AFTER_NO_PROGRESS_STEPS)
  • ARABICA__BLEND_MINIMUM_MODEL_DWELL_STEPS: minimum consecutive calls to keep a selected model before ordinary routing can switch; error and recovery routes bypass this hold, default 1
  • ARABICA__BLEND_TOOL_CALL_MODELS: comma-separated aliases certified for tool calling
  • ARABICA__BLEND_TYPED_COMPLETION_MODELS: comma-separated aliases certified for typed terminal completion
  • ARABICA__BLEND_POLICY_ID and ARABICA__BLEND_POLICY_VERSION: immutable policy identity recorded with each route
  • ARABICA__TOOL_ROOT: root directory available to the local runner
  • ARABICA__COMPACTION_STRATEGY: file_backed_gc (default), pointer_gc, or disabled
  • ARABICA__ARCHIVE_ROOT: local lossless-compaction archive directory, default target/arabica-runtime-memory
  • COMPACTION_EFFORT: minimum expected return over one cache reset; legacy PGC_EFFORT remains accepted

The current server and Harbor benchmark entry points use the atomic local-file archive adapter. SQLite remains available as an explicit Runtime adapter but is not selected by either executable.

Run the CLI

arabica-cli builds a structure binary with two entry points: structure acp (Agent Client Protocol v1 over stdio, for editors like Zed) and structure -p "task" (one-shot execution). Both read provider-specific key environment variables and the model configuration from ~/.arabica/config.toml. See docs/cli.md for flags, exit codes, and a Zed configuration snippet.

cargo build -p arabica-cli --release
./target/release/arabica -p "explain this repository's crate layout"

Benchmarks

The Rust short-memory benchmark is a workspace member:

cargo run -p structure-short-memory-benchmark

Benchmark inputs, policies, and evidence gates live under benchmarks/runtime-short-memory/.

Repository Status

The Python service, memory benchmark framework, and Harbor Python orchestration have been removed. The Rust workspace is the single maintained implementation; structure-short-memory-benchmark is the single experiment package. JavaScript fixtures and the CLI proxy remain supporting tools for that package.

Run make check for Rust checks and offline benchmark/proxy tests (Node.js is required for proxy tests). See benchmarks/README.md for available entry points. The old Python CLI and import interfaces are no longer available. The former Python container deployment workflow was removed; tags do not deploy a service.

The paper, reports and frozen protocols preserve historical evidence and may refer to removed runners. They do not establish reproducibility on this commit. Local datasets, experiment outputs and archived binaries remain untouched.

No browser UI, React application, or other frontend is currently maintained.

License

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE. Contributions are accepted under the same license unless explicitly stated otherwise.

Versioned event trace routes

Use event_trace_v1_regex for newline-delimited canonical event records. Each record begins with its path followed by |key=value fields. Values and dynamic path segments use UTF-8 percent encoding; arbitrary arguments and tool output are excluded. Routes inspect the preceding model step in the current run.

[[blend.policies.coding.tool_routes]]
id = "shell-text-tools"
model = "strong"
priority = 10
matcher = { type = "event_trace_v1_regex", value = '(?m)^toolcall\.shell\.(sed|grep|rg)\|' }

For trajectories across records, use (?ms) so . includes newlines. Shell results inherit executable labels through their run and call IDs. Compound or expanding shell commands receive no executable label. Existing exact-name, regex-name, kind, and legacy trace routes retain their precedence; recovery and error handling still take precedence over tool routes. Oversized V1 traces do not match. This is a routing signal, not a shell authorization mechanism.

Run acceptance and policy campaigns

Terminal runs now include per-run timing and immutable evidence in background reports. Explicit acceptance specifications provide completion and coverage; unspecified tasks remain unverified. The desktop evaluation panel displays these results. Use arabica evaluations runs, score, and compare, or run isolated real policy trials with the existing benchmark's policy_campaign binary. See run evaluation for formats and examples.

Image input

The macOS client's paperclip accepts PNG, JPEG, WebP, and GIF images (up to four per message, 5 MiB each). Choose a vision-capable model. ACP advertises the image prompt capability and forwards image bytes through the canonical message and session history to OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, or Gemini Generate Content. Ordinary file attachments remain resource links. Image generation and editing are not built-in tools.

The message.send payload and message.accepted event accept an optional images array of { "media_type": "image/png", "data_base64": "..." } objects. Omitting it retains the existing text-only wire format. Image bytes are persisted with the session and sent to the configured provider for their own turn only; later requests replace them with a short note so request size stays bounded.