Architecture

Architecture (Kernel Perspective)

This page is primarily based on the official Architecture documentation (docs/architecture).

14-crate Cargo Workspace (Downward Layered Dependencies)

OpenFang is organized as a Cargo workspace with 14 crates (13 code + xtask). The dependencies are structured top-down, strictly relying on layers below them.

openfang-cli      CLI interface, daemon auto-detect, MCP serveropenfang-desktop  Tauri 2.0 desktop appopenfang-api      REST/WS/SSE API server (Axum 0.8)openfang-kernel   Kernel: assembles subsystems, workflows, RBAC, metering  ├─ openfang-runtime   Agent loop, LLM drivers, tools, WASM sandbox, MCP/A2A  ├─ openfang-channels  40 channel adapters  ├─ openfang-wire      OFP networking (HMAC-SHA256)  ├─ openfang-migrate   migration engine (OpenClaw YAML -> TOML)  └─ openfang-skills    60 skills, marketplace clients, SKILL.md parseropenfang-memory   SQLite memory substrateopenfang-types    shared types (Agent, Capability, Event, ...)

Kernel Boot Sequence

OpenFangKernel::boot_with_config() (The documentation lists 14 steps, summarizing the core sequence below):

1. Read and validate config.toml (#[serde(default)] ensures forward compatibility).
2. Initialize data directories.
3. Initialize SQLite memory substrate, and execute schema migrations.
4. Initialize LLM driver (reading keys from environment variables).
5. Initialize model catalog (includes models/providers/aliases).
6. Initialize metering engine (cost tracking/billing).
7. Initialize model router (routes based on task complexity).
8. Assemble core subsystems: registry/scheduler/capability/eventbus/supervisor/workflow/trigger/background executor/wasm sandbox…
9. Setup RBAC auth manager.
10. Setup skill registry (load bundled + disk-installed skills).
11. Setup web tools context (search + SSRF-protected fetch).
12. Restore agents from persistent storage.
13. Publish KernelStarted event.
14. Return the kernel instance.

Agent Lifecycle (spawn / message / kill)

State Machine

• Running: Can receive messages and tick events.
• Suspended: Paused during situations like daemon shutdown; can be resumed after state persistence.
• Terminated: Killed, final state.

Core Spawn Flow

1. Allocate AgentId / SessionId.
2. Create session.
3. Parse manifest and extract capabilities.
4. Validate capability inheritance (preventing sub-agents from privilege escalation).
5. Authorize capabilities.
6. Register with scheduler (quota management).
7. Register with registry.
8. Persist to SQLite.
9. If there is a parent, update its children.
10. Register proactive triggers.
11. Publish Lifecycle::Spawned event.

Core Message Flow (Highly Systematized)

1. RBAC check (AuthManager).
2. Channel policy check.
3. Quota check (AgentScheduler).
4. Dispatch according to manifest.module: builtin chat / wasm / python subprocess.
5. LLM loop: Load session, inject canonical summary, collect available tools, loop guard, session repair, iterate through tool calls, perform auto compaction, write back to storage.
6. Metering cost estimation + usage record.

Stability Subsystems (Preventing "Runaway Intelligent Agents")

The documentation outlines multiple hardening layers in the Agent Loop Stability section:

• LoopGuard: Warns, blocks, or circuit-breaks repeated tool calls (SHA-256 based).
• Session repair: Fixes unpaired tool_use/tool_result, merges consecutive roles, etc.
• Tool timeout: Global 60-second timeout.
• Tool output truncation: Upper limit of 50,000 characters for output.
• Max continuations: Limits "please continue" loops.
• Inter-agent depth limit: Restricts recursive calling depth.
• Block-aware compaction: Compresses sessions containing tool/image blocks strategically.

Memory Substrate (SQLite)

Details are available in the "Core Concepts / Memory" section. One key emphasis: OpenFang unifies "sessions, embeddings, knowledge graphs, usage, and canonical sessions" onto a single SQLite schema, handling version migrations seamlessly.