edict-rs

High-performance multi-agent orchestration engine with hierarchical governance

Why This Exists

Edict (14K+ stars) is a Python multi-agent orchestration framework inspired by ancient Chinese imperial bureaucracy. It implements hierarchical governance with mandatory review gates, permission-based routing, and full audit trails.

edict-rs reimplements the core orchestration engine in Rust for:

• Type safety: State machine transitions enforced at compile time
• Performance: Zero-copy operations, no GC pauses, async I/O
• Single binary: No Python runtime, no pip dependencies
• Concurrency: Tokio async runtime with proper file locking
• Cross-platform: Windows, macOS, Linux from one codebase

Core Architecture

Emperor (User)
    |
    v
Crown Prince (Taizi) -----> Central Secretariat (Zhongshu) - Planning
                                       |
                                       v
                              Chancellery (Menxia) - Review Gate
                                    |         |
                                 approve    reject --> back to Planning
                                    |
                                    v
                        Dept of State Affairs (Shangshu) - Dispatch
                          /    |    |    |    |    \
                         v     v    v    v    v     v
                       Hubu  Libu Bingbu Xingbu Gongbu LibuHr
                       (Data)(Docs)(Eng) (Audit)(Infra)(HR)

Key Components

Component	Description
State Machine	13 states with strict transition validation. No shortcuts.
Permission Matrix	19 routes. Agents can only communicate with explicitly permitted targets.
Task Store	CRUD with search, filtering, archival, and JSON persistence.
Scheduler	Stall detection, retry dispatch, escalation, rollback with snapshots.
Sanitizer	Removes file paths, URLs, UUIDs, metadata, code blocks from input.
Atomic File Ops	Exclusive locking with temp-file-and-rename for corruption-free writes.
REST API	Full Axum-based API server with 25+ endpoints.
CLI	Task management, agent inspection, state machine visualization.

Installation

cargo install edict-rs

Or build from source:

git clone https://github.com/JSLEEKR/edict-rs
cd edict-rs
cargo build --release

Usage

CLI

# Show state machine transitions
edict states

# Show permission matrix (19 inter-agent routes)
edict permissions

# List all agents
edict agent list

# Show agent details with communication permissions
edict agent show bingbu

# Create a task
edict task create "Build authentication module"

# Transition task state
edict task transition <id> triaged --agent taizi

# List tasks
edict task list --state pending

# Validate a task title
edict validate "Implement OAuth2 flow"

# Sanitize input text
edict sanitize "Conversation: Deploy /Users/admin/app to https://prod.example.com"

API Server

# Start server on port 18789
edict serve

# Custom configuration
edict serve --port 8080 --bind 0.0.0.0 --stall-threshold 60 --max-retries 5

API Endpoints

Method	Path	Description
GET	/healthz	Health check
GET	/api/tasks	List tasks (filter by state, org, assignee)
POST	/api/tasks	Create task
GET	/api/tasks/{id}	Get task details
POST	/api/tasks/{id}/transition	Transition task state
POST	/api/tasks/{id}/progress	Record progress
POST	/api/tasks/{id}/todos	Update todo list
POST	/api/tasks/{id}/complete	Mark complete
POST	/api/tasks/{id}/cancel	Cancel task
POST	/api/tasks/{id}/archive	Archive terminal task
GET	/api/tasks/search?q=	Search tasks
GET	/api/tasks/stats	Task statistics by state
GET	/api/agents	List agents with status
GET	/api/agents/{id}/status	Agent status
POST	/api/agents/{id}/heartbeat	Record heartbeat
POST	/api/agents/{id}/model	Set LLM model
GET	/api/permissions	List all permission routes
POST	/api/permissions/check	Check if route is allowed
POST	/api/permissions/validate-path	Validate agent chain
POST	/api/scheduler/scan	Scan for stalled tasks
POST	/api/scheduler/retry/{id}	Retry stalled dispatch
POST	/api/scheduler/escalate/{id}	Escalate to higher level
POST	/api/scheduler/rollback/{id}	Rollback to snapshot
GET	/api/scheduler/state/{id}	Task scheduler state
GET	/api/scheduler/summary	Scheduler overview
GET	/api/state-machine/transitions	Full transition graph
POST	/api/state-machine/validate	Validate a transition

State Machine

Tasks follow a strict governance workflow with 13 states:

pending -> triaged -> planning -> reviewing -> approved -> assigned -> executing -> review -> completed
                                     |                                    |
                                  rejected -> planning (re-plan)       blocked -> executing (resume)
                                                                          |
                                                                        next -> executing

• Any non-terminal state can transition to cancelled
• Terminal states (completed, cancelled) have no outgoing transitions
• Review gate (menxia) can reject back to planning or approve forward

Permission Matrix

Communication is whitelist-based. Only explicitly permitted routes are allowed:

From	Can Reach
Taizi	Zhongshu
Zhongshu	Menxia, Shangshu
Menxia	Zhongshu (reject), Shangshu (approve)
Shangshu	All 6 ministries + Zhongshu + Menxia
Ministries	Shangshu only
Zaochao	(isolated)

This prevents governance bypass -- a ministry cannot communicate directly with another ministry, and triage cannot skip to dispatch.

Comparison with Original

Feature	edict (Python)	edict-rs (Rust)
Language	Python 3.9+	Rust
Dependencies	Zero (stdlib only)	Minimal (serde, tokio, axum)
Binary size	N/A (interpreter)	~5MB single binary
Concurrency	File-based locking	tokio async + fs2 locking
State machine	Dict-based	Enum-based with compile-time safety
Permission matrix	Runtime checks	Type-safe role validation
API server	http.server (stdlib)	Axum (production-grade)
Tests	17	184
CLI	kanban_update.py scripts	Unified edict binary
Task persistence	JSON files	Atomic JSON with file locking
Input sanitization	Regex pipeline	Pre-compiled regex (LazyLock)
Health monitoring	pgrep + session files	Heartbeat-based with status derivation
Scheduler	Shell script loop	In-process with retry/escalation/rollback

What We Kept

• The governance model (hierarchical approval chain)
• State machine transitions (same valid paths)
• Permission matrix (same routing rules)
• Data sanitization pipeline (same cleaning rules)
• Atomic file operations (same temp-and-rename pattern)

What We Improved

• Type safety: States and roles are enums, not strings
• Performance: Pre-compiled regexes, zero-copy where possible
• API: Full REST API with 25+ endpoints vs. custom server
• Scheduler: In-process stall detection, retry, escalation, rollback with snapshots
• Testing: 184 tests (11x more than original's 17)
• CLI: Unified binary with subcommands vs. scattered Python scripts
• Cross-platform: Native Windows support (no WSL needed)

License

MIT