|
// retoor <retoor@molodetz.nl>
|
|
# R - Autonomous Terminal AI Agent
|
|
|
|
## Project Overview
|
|
**R** is a high-performance, autonomous AI agent written in C. It leverages the ReAct pattern to navigate complex system-level tasks by iteratively executing native tools and analyzing their output. Designed for Lead Orchestration, it manages specialized workers and background processes with high precision.
|
|
|
|
### Key Capabilities
|
|
* **Asynchronous Engine:** Robust fork/exec mechanism with real-time log tailing and PID management.
|
|
* **Sequence-Aware Context:** Advanced management of conversation history that preserves the structural integrity of message pairs (Assistant/Tool) and system prompts.
|
|
* **Professional UI:** Integrated Markdown and code renderers providing syntax highlighting and indented process output for superior DX.
|
|
* **Benchmarking:** Python-based integration suite with real-time persistent logging for debugging complex agent logic.
|
|
|
|
## Architecture
|
|
The project has evolved from a header-only design to a modular, professional C structure with clear separation of concerns.
|
|
|
|
### Core Implementation (`src/`)
|
|
* **`main.c`**: Orchestration logic, REPL loop, and Lead Orchestrator system prompt injection.
|
|
* **`agent.c`**: Core agentic loop with support for sub-agent spawning and verbose LLM logging.
|
|
* **`bash_executor.c`**: Advanced process control using non-blocking `waitpid` and log file monitoring.
|
|
* **`context_manager.c`**: Holy-sequence-aware shrinking logic that maintains API compatibility during context overflows.
|
|
* **`markdown.c`**: ANSI-based rendering engine for Markdown and Python syntax highlighting.
|
|
* **`tools/`**: Universal process tools and specialized worker logic.
|
|
|
|
### Data & State
|
|
* **SQLite Persistence:** `~/.r.db` manages key-value state and file versioning.
|
|
* **Session History:** Managed via `src/messages.c` with support for loading/saving separate contexts.
|
|
* **Background Logs:** Persistent task output stored in `/tmp/r_process_<pid>.log`.
|
|
|
|
## Development & Testing
|
|
|
|
### Strict Mode Compliance
|
|
All tools follow strict JSON schema definitions:
|
|
* `additionalProperties: false`
|
|
* All properties explicitly listed in the `required` array.
|
|
* Type-safe return objects (exit codes, booleans, strings).
|
|
|
|
### Testing Protocol
|
|
The `agent_benchmark.py` script provides 20 detailed test cases covering:
|
|
1. **Parallel Execution:** Multiple Python/Shell tasks running async.
|
|
2. **Process Lifecycle:** Termination, exit code capture, and backgrounding.
|
|
3. **Complex Orchestration:** Web research handover to developers.
|
|
4. **System Maintenance:** Codebase indexing and header verification.
|
|
|
|
```bash
|
|
# Safe test execution
|
|
python3 agent_benchmark.py
|
|
```
|
|
|
|
## Conventions
|
|
* **Header Style:** Every file must begin with `// retoor <retoor@molodetz.nl>`.
|
|
* **Defensive C:** Strict buffer management, mandatory `malloc` checks, and `NULL` pointer safety.
|
|
* **Logging:** LLM requests and responses go to `stderr` in verbose mode for auditability.
|
|
* **Modularity:** Prioritize small, focused files and clear interface definitions in `include/`. |