# drharness

A C++23 LLM (Open AI Compatible) harness designed for agentic workflows, file
manipulation, and task delegation. It implements a tool-use loop that allows a
large language model to dynamically invoke shell commands, edit files, and
delegate sub-tasks to other specialized agents. (I wouldn't use the agents
feature yet as it is kind of half baked, and I'm not sure when I'll loop back
to it)

## 🏗️ Architectural Overview

`drharness` is built as a modular C++ application consisting of several key components:

*   **`Harness`**: The core orchestrator. It manages the conversation history (stored as a JSON array), the active tool registry, and the main execution loop. It repeatedly pushes messages to the LLM, parses tool calls, executes them locally, and appends the results back into the history until the model indicates a final response.
*   **`ToolRegistry`**: A dynamic system for managing available tools. The LLM receives the list of available tools in JSON format and can invoke them dynamically. The registry includes a base set of tools (file reading, editing, grepping, shell execution) and supports nested agent delegation.
*   **`Agent Profiles`**: Configurable definitions for specialized sub-agents (e.g., `shell_expert`). These allow the main agent to offload complex multi-step tasks to a dedicated model/agent instance.
*   **`Client Layer`**: 
    *   `OllamaClient`: Handles the actual communication with an Ollama-compatible API server via HTTP (using `libcurl`).
    *   `DebugClient`: A CLI-friendly mock client that reads a mock JSON response from `stdin`, allowing for deterministic testing of harness logic without relying on an external LLM.
*   **State Management**: Conversations are serialized to and deserialized from JSON files. This includes the full message history (`history`), the active tool registry (`tools`), and harness configuration (`config` including `base_url`, `model`, `max_tool_iterations`, `verbose`, and `depth`).

## 🛠️ How to Build

The project requires CMake version 3.16 or newer, C++23 support, `curl`, and the `nlohmann_json` library.

```bash
# Configure the build
cmake -B build -DCMAKE_BUILD_TYPE=Release .

# Build the binary
cmake --build build
```

## 🧪 How to Run Tests

To run tests first you have to build the project.  Then you can run ctest:

```bash
cd build
ctest
```

And it will run the entire test suite

## 💬 Starting & Continuing Conversations

The harness state is persisted in a JSON file specified by the `-F` flag.

### Starting a New Conversation
To start fresh, use the `-n` flag. If you don't specify a chat file with `-F`, the harness will automatically generate a unique, ephemeral JSON file in your system's temporary directory. If you do specify a file with `-F`, it must be new or empty. The harness will refuse to start a new conversation if the specified file already contains data.

#### Auto-generated temp file
```bash
./build/drharness -n -m "Let's start a new project."
```

#### Using a specific file
```bash
./build/drharness -F conversation.json -n -m "Let's start a new project."
```

### Continuing an Old Conversation
To continue a previous session, simply invoke the harness with the same `-F`
file. It will automatically deserialize the saved history, tool registry, and
configuration.

```bash
./build/drharness -F conversation.json -m "Can you now refactor the main loop?"
```

### Other Useful Flags
*   `-l`: List all available tools.
*   `-p <file>`: Pretty-print a conversation JSON file without running the harness.
*   `-t <tool>`: Manually constrain the harness to a specific subset of tools (by default no tools are provided to the model)
*   `-s <name>`: Manually constrain the harness to a specific subset of skills (can be specified multiple times)
*   `-i <path>`: Image file to attach to the prompt (can be specified multiple times)
*   `-m <prompt>`: The user prompt to send to the agent.
*   `-P <file>`: Read the prompt from a file instead of the command line.
*   `-M <model>`: Override the Ollama model (e.g., `mistral`, `llama3`).

## ✍️ Editor Integration

This harness supports an interactive editor mode that allows you to write multi-line prompts or complex instructions using your preferred terminal or GUI editor.

### Setup
To enable editor mode, simply set the `VISUAL` or `EDITOR` environment variable in your shell before running the harness:
```bash
export EDITOR=nvim  # or vscode, nano, vim, emacs, etc.
```

### Usage
1. When the harness launches the editor, it opens a temporary file in your configured editor.
2. The file contains the current conversation context (or the last AI response) followed by a separator line: `-- >8 --`
3. Type your new prompt **below** this separator line. You can write as much as you like!
4. Save the file and exit the editor.
5. The harness will automatically extract everything you typed after the separator as your prompt and continue the conversation.

*Note: If neither `VISUAL` nor `EDITOR` is set, the harness will refuse to launch the editor and throw an error instead.*


For detailed documentation on history editing, see [docs/history-editing.md](docs/history-editing.md).

## 🐳 Docker Isolation

The harness can be compiled and run inside an isolated Alpine Linux container.

### 1. Build the Docker Image
Use the provided script to build the image. It passes your local Ollama auth
token as a build-time argument.

```bash
./build_docker.sh
```

### 2. Run the Agent
Use the `dockerdrh` script. This script automatically maps the current working
directory to `/mnt` inside the container and runs the container with the host
user's UID/GID to preserve file permissions.

```bash
# Start a new conversation inside the container
./dockerdrh -F conversation.json -n -m "Initialize the project"
```

*Note: Inside the container, the working directory is `/mnt`. Always pass your
local JSON file relative to the mapped directory.*