Architecture
System architecture, data flow, and design decisions
Architecture
Library-First Design
A3S Code is a library-first framework. The core (a3s-code-core) embeds directly in your application via native bindings — no server, no IPC overhead.
Your Application (Rust / TypeScript / Python)
│
▼ Agent::new("agent.hcl") / Agent.create("agent.hcl")
┌──────────────────────────────────────────────────────┐
│ Agent (config-driven, workspace-independent) │
│ ┌────────────┬──────────────┬─────────────────────┐ │
│ │ LlmClient │ CodeConfig │ SessionManager │ │
│ └────────────┴──────────────┴─────────────────────┘ │
│ │ │
│ agent.session("/workspace", options?) │
│ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ AgentSession (workspace-bound) │ │
│ │ ┌─────────┬──────────┬──────────┬─────────┐ │ │
│ │ │ Agent │ Tool │Permission│ LLM │ │ │
│ │ │ Loop │ Executor │ System │ Provider│ │ │
│ │ │ │ (10) │ │ │ │ │
│ │ ├─────────┼──────────┼──────────┼─────────┤ │ │
│ │ │ HITL │ Subagent │ Hook │ MCP │ │ │
│ │ │ │ │ Engine │ │ │ │
│ │ ├─────────┼──────────┼──────────┼─────────┤ │ │
│ │ │ Llm │ Security │ Memory │ File │ │ │
│ │ │ Planner │ Provider │ │ History │ │ │
│ │ ├─────────┼──────────┼──────────┼─────────┤ │ │
│ │ │ Wave │ Context │ Cost │Telemetry│ │ │
│ │ │Scheduler│Compactor │ Tracking │ │ │ │
│ │ └─────────┴──────────┴──────────┴─────────┘ │ │
│ └──────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘Native bindings:
Prop
Type
Core Concepts
Prop
Type
Agent Loop
The core execution cycle. Each round:
If LLM returns tool_use:
- PreToolUse hook fires (optional)
- Permission check — Deny → Allow → Ask → Default evaluation
- HITL confirmation — if required, wait for user approval (with timeout)
- SecurityProvider check — pluggable security logic via trait
- Tool execution — run the tool, capture output
- PostToolUse hook fires (optional)
Maximum rounds per generation configurable via max_tool_rounds (default: 50).
Security Layers
Two built-in layers, plus extensibility via traits:
Prop
Type
See Security for details.
Context Management
When context usage exceeds the threshold (default 80% of model's context window):
This keeps the session within context limits while preserving important context.
Planning & Parallel Execution
When planning is enabled:
tokio::JoinSetWave 1: [Analyze auth] + [Analyze DB schema] ← parallel
Wave 2: [Implement JWT integration] ← waits for wave 1
Wave 3: [Write tests] ← waits for wave 2See Tasks for details.
Lane Queue System
The lane queue routes tool calls to different execution strategies:
Prop
Type
Each lane can be switched to External mode to offload execution to remote workers. See Lane Queue for details.
Memory System
Four memory types with pluggable storage backends:
Prop
Type
Default backend: FileMemoryStore — one JSON file per item + compact index. Custom backends via MemoryStore trait.
See Memory for details.
Extensibility
A3S Code is designed for extensibility:
All core systems use trait-based interfaces for maximum flexibility.