// 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/`.