# BoteX: Execution Harness for AI Coding Agents

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](pyproject.toml)
[![CI](https://github.com/kubainter/botex-harness/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kubainter/botex-harness/actions/workflows/ci.yml)
[![BoteX MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/kubainter/botex-harness/badges/card.svg)](https://glama.ai/mcp/servers/kubainter/botex-harness)

Giving an LLM direct, unrestricted access to your repository usually ends the same way: it hallucinates line numbers, corrupts indentation, writes broken syntax, eats your token budget reading thousands of irrelevant lines, or gets stuck in an infinite fix-break loop.

**BoteX** is a guardrail harness designed specifically for autonomous code-editing agents. It sits between an MCP client (such as Devin, Antigravity, Claude Desktop, or Cursor) and your codebase, enforcing deterministic safeguards before any code ever touches your disk.

---

## Why BoteX?

Instead of trusting the model to behave, BoteX wraps every action in safety gates:

* **Outline-first inspection**: Agents inspect symbol skeletons (`get_outline`) before asking for specific line ranges. This prevents dumping massive files into context and slashes token waste.
* **Prompt Injection & Untrusted Data Isolation (OWASP LLM01: Prompt Injection)**: External content retrieved by tools (file contents, web pages, memory notes) is automatically wrapped in XML-like untrusted data boundary tags (`<untrusted_file_content>`, `<untrusted_web_content>`, `<untrusted_memory_content>`). System prompt rules instruct the LLM to treat bounded content strictly as data, significantly reducing prompt injection risks.
* **Sensitive Information Disclosure & Secret Guardrails (OWASP LLM02: Sensitive Information Disclosure)**: Prevents accidental leaks by blocking access to environment files (`.env*`), SSH keys, credentials, and local configurations (`botex.config.local.json`). Automatically redacts API keys, Bearer tokens, private keys, and provider secrets in tool outputs and logs.
* **Read-before-write gate**: Models cannot patch a file they haven't inspected in the current session. No blind edits, no guessing.
* **Pre-write syntax validation**: Code modifications are validated in memory (e.g. `ast.parse` for Python) *before* saving. If the patch breaks syntax, it gets rejected on the spot.
* **Multi-tier fuzzy patching**: Patches are whitespace- and newline-resilient (CRLF/LF agnostic with indentation detection), so minor formatting mismatches don't break execution.
* **Unbounded Consumption Protection (OWASP LLM06: Unbounded Consumption)**: Prevents "Denial of Wallet" and infinite loop resource exhaustion. BoteX evaluates USD spend dynamically mid-loop to enforce the budget cap instantly, and aborts with an automatic rollback if the agent falls into a mutation streak or stagnation loop.
* **Misinformation Protection (OWASP LLM07: Misinformation)**: Generated code undergoes rigorous in-memory AST and syntax validation (including `ruff` for Python and `bash -n` for shell scripts) to reject hallucinated or invalid code before touching disk. Post-write `verify_command` acts as a mandatory final test gate.
* **Improper Output Handling (OWASP LLM10: Improper Output Handling)**: Strict Read-Before-Write gates ensure no blind writes occur, and every touched file is backed by a pre-mutation snapshot. If an agent hits an error, the automatic snapshot rollback reverts the workspace cleanly.
* **Hard budget & pricing caps**: Pre-flight checks verify model pricing against live provider catalogs. If a task exceeds its budget or a model is overpriced, BoteX aborts before spending a cent.
* **Strict privacy & Zero Data Retention (ZDR)**: Enforces `provider.data_collection: deny` on OpenRouter calls, blocks `.env`/secrets, masks API keys in logs, and prevents path traversal attacks. Free (`:free`) models that cannot guarantee ZDR are rejected locally. Opt out explicitly per run (`allow_non_zdr`) or via the `openrouter-free` provider preset.
* **Enhanced Permission Controls (OWASP LLM03: Excessive Agency)**: BoteX protects against Excessive Agency via a centralized Agency Middleware. Tools are strictly defined with Risk Levels (LOW, MEDIUM, HIGH) and required scopes. High-risk destructive actions automatically require explicit interactive operator approval (or pre-authorized task scopes in headless mode), limiting the potential damage of prompt injections or hallucinations.

---

## Quickstart

### 1. Installation

Requires Python 3.10+:

```bash
pip install -r requirements.txt
```

*(Optional: install globally via `pip install .` to get the `botex` CLI command).*

### 2. Add your API key

BoteX handles provider keys internally, so calling MCP clients don't need to pass credentials on every request. Create a `.env` file next to `server.py`:

```env
OPENROUTER_API_KEY=sk-or-v1-...
```

*Key lookup order: `OPENROUTER_API_KEY` env var → local `.env` → custom `paths.env_file` → `botex.config.local.json` (gitignored).*

### 3. Connect to your MCP client

You can run BoteX as a local stdio process or as a remote service over SSE.

#### Option A: Local Process (stdio)
Register BoteX using the included zero-install launchers (`botex.cmd` on Windows, `botex.sh` on Linux/macOS) or directly with Python:

```json
{
  "mcpServers": {
    "botex": {
      "command": "C:/path/to/harness/botex.cmd"
    }
  }
}
```

#### Option B: Remote MCP via SSE (Cloud or VPS)
Start the gateway with `botex cloud` and connect via Server-Sent Events (SSE):

```json
{
  "mcpServers": {
    "botex-cloud": {
      "url": "http://127.0.0.1:8000/mcp/sse",
      "headers": {
        "Authorization": "Bearer <your_token>"
      }
    }
  }
}
```

---

## How It Works

Every delegated task goes through an explicit contract-driven lifecycle:

```
Delegated Task
     │
     ▼
[Pre-flight check] ──► Validate budget, model capabilities & price cap
     │
     ▼
[Tool Loop]        ──► Symbol outline ─► Target read ─► In-memory patch ─► Syntax check
     │
     ├─► Success   ──► Verify contract (file exists, syntax valid, verify_command passed) ─► DONE
     │
     └─► Failure   ──► Rollback snapshots ─► Try next candidate (model_fallbacks) or abort
```

A task returns `ok: true` **only when its completion is verified on disk**, not just because an LLM said "I'm done".

---

## MCP Tools Reference

BoteX exposes a focused set of MCP tools:

### Task Execution
* **`run_subagent(task, ...)`**: Runs a full coding task synchronously and blocks until finished. Returns both human-readable text and detailed structured metadata.
* **`start_task(task, ...)`**: Launches a task asynchronously in the background and returns a `task_id`.
* **`get_task_status(task_id)`**: Polls progress, logs, and results for a background task.

### Two-Tier Memory Vault
* **`save_memory(title, content, workspace_dir, kind, tags, memory_id, scope)`**: Saves persistent notes, decisions, handoffs, or lessons. Scope can be `"local"` (`<workspace_dir>/.botex/memory/`) or `"global"` (`~/.botex/memory/`).
* **`read_memory(memory_id, workspace_dir, scope)`** / **`search_memory(workspace_dir, query, tag, kind, scope)`**: Retrieves saved memory across local or global storage (`scope="all"` searches both).

### Diagnostics & Utility
* **`get_outline(path, workspace_dir)`**: Returns a high-level symbol outline of a file without reading all lines.
* **`get_stats(period)`**: Generates token usage and cost reports from the local analytics ledger.
* **`check_health()`**: Checks readiness of providers, models, keys, and budget limits.
* **`clean_snapshots(max_age_days, max_total_mb)`**: Prunes old workspace backup snapshots.
* **`recommend_models(task_type, limit, include_free, provider, profile, tier)`**: Queries `/api/v1/models` with authenticated headers, classifies models into `high` / `standard` / `budget` tiers, filters for tool-calling support (`require_tools=true`) and interactive endpoints (excluding `:batch`), and ranks models by task aptitude and token cost. `include_free=true` admits `:free` variants.
* **`fetch_url(url, max_bytes)`**: Safe, caller-side URL fetching with strict host and size filters.

---

## Task Delegation & Parameters

Example payload for `run_subagent`:

```json
{
  "task": "Add email validation to auth/validators.py and cover it with unit tests",
  "files": ["auth/validators.py"],
  "workspace_dir": "./my-project",
  "profile": "coding"
}
```

### Key Parameters

| Parameter | Default | Description |
|---|---|---|
| `task` | *(required)* | Clear description of what needs to be implemented or fixed. |
| `files` | `[]` | List of primary target files to nudge the agent toward. |
| `workspace_dir` | `""` | Root directory the agent is restricted to. Empty = `engine.default_workspace` from config, else the server's current directory. An explicit value (including `.`) always wins. |
| `provider` | `""` | API provider from `botex.config.json` (`openrouter`, `nvidia`, `openrouter-free`; empty = configured default or `BOTEX_PROVIDER`). |
| `model` | `""` | Explicit provider model ID; overrides `profile`. |
| `profile` | `""` | Model profile from `botex.config.json` (`default`, `coding`, `auto-beta`, `fast`). Empty = picked per mode via `engine.mode_profiles`. |
| `api_key` | `""` | Provider API key per-request; highest priority (overrides env/.env/config). |
| `mode` | `"edit"` | Capability preset: `readonly`, `edit`, `destructive`, `full` (empty = `engine.default_mode`). |
| `recipe` | `""` | Specialized workflow persona (`planner`, `code-explorer`, `reviewer`, `security-reviewer`, `build-resolver`, `tdd`). |
| `max_turns` | `0` | Max tool-loop iterations (`0` uses `engine.max_turns`, usually 15, overridable per mode via `engine.mode_max_turns`). |
| `max_tokens` | `0` | Per-turn completion cap (`0` = config value; reasoning models need ~8000+). |
| `max_duration_s` | `0` | Total wall-clock limit in seconds (`0` = config value). |
| `budget_limit_usd`| `-1` | Hard spend limit for this task (`-1` uses global config, `0` = unlimited). |
| `allow_destructive`| `false` | Explicit opt-in for `delete_file` and `move_file`. |
| `allow_exec` | `false` | Explicit opt-in for `run_command` (requires `exec.enabled: true` in config). |
| `allow_net` | `false` | Explicit opt-in for web access via `read_url`. |
| `net_allowed_hosts` | `[]` | Per-run host authorization for `read_url` (interacts with `net.policy`). |
| `net_allowed_urls` | `[]` | Per-run URL authorization; a trailing `/` authorizes that subtree. |
| `allow_non_zdr` | `false` | Per-run consent to relax the ZDR gate; required for `:free` models (provider may log/train on prompts). The result carries `zdr_enforced: false`. |
| `output_path` | `""` | Enforce that this exact file must be written and non-empty for `DONE` status. |
| `verify_command` | `""` | Verification command (e.g. `pytest tests/test_auth.py`) that must pass before completion. Requires `exec.enabled: true` and exec authorization. |

---

## Recipes & System Prompts

BoteX builds the API **System Prompt** dynamically for each run. It fuses a hardcoded operational core (tool rules, syntax validation checks, output formats) with an optional **Recipe** (a markdown file).
This means that providing a `--recipe <name>` (or the `"recipe": "<name>"` JSON parameter) acts as an injection mechanism for your custom System Prompts, giving the agent specialized personas or specific constraints.

Recipes live in the `botex/recipes/` directory.

### Examples of custom System Prompts for Modding and Analysis

If you are using BoteX as an MCP Server to analyze game mods or reverse-engineer engine behavior, you can create custom recipes like `botex/recipes/ue4.md` or `botex/recipes/lua_audit.md`.

* **Unreal Engine 4 Modding (`--recipe ue4`)**
  ```text
  You are an expert C++ and UE4 Blueprint reverse engineer. Your primary goal is to identify memory leaks in object instantiation and unsafe cast operations. Always prioritize stability over performance optimizations. Adhere strictly to Epic Games naming conventions.
  ```

* **Security Audit (`--recipe lua_audit`)**
  ```text
  You are a strict security auditor analyzing game mods. Review this Lua codebase for potential sandbox escapes, arbitrary file read/write vulnerabilities, and networking exploits. Do not attempt to fix logic bugs; focus only on security vulnerabilities.
  ```

* **Code Refactoring & Optimization (`--recipe optimize`)**
  ```text
  You are an optimization expert. The target codebase runs in a heavily restricted environment. Identify inefficient loops, excessive global variable usage, and unnecessary memory allocations. Suggest changes using only standard libraries.
  ```

When provided, BoteX automatically appends your recipe to the system instructions before starting the LLM loop.

---

## Safety & Capability Modes

Permissions follow the principle of least privilege. Modes are presets over core capabilities:

| Mode | Allowed Operations | Typical Use Case |
|---|---|---|
| `readonly` | Outline inspection, ranged file reads, memory search. | Architecture reviews, exploratory passes. |
| `edit` *(default)* | Read tools + `apply_patch` + `create_file`. | Standard feature work and bug fixing. |
| `destructive` | Edit tools + `delete_file` + `move_file`. | Refactoring, renaming, file reorganizations. |
| `full` | Destructive tools + gated `run_command` execution. | Full autonomous loop (edit → test → fix). |

> [!NOTE]
> Network access (`allow_net`) is **never** enabled by default in any preset. It must be explicitly enabled per request or configured via `net.allowed_hosts`.

### Command Execution (`run_command`) Safety

BoteX is **not a full OS sandbox**. When `allow_exec` is granted, processes run under the operator's account. However, BoteX guards execution with multiple layers:
1. **Disabled by default**: Requires `exec.enabled: true` in configuration.
2. **Binary allowlist**: Only pre-approved executables (`pytest`, `python`, `ruff`, `git`, etc.) can be called.
3. **Deny rules**: Blocks dangerous arguments (`python -c`, `git push`, `rm`, shell piping, network downloads).
4. **Isolated environment**: Executes directly (`shell=False`), workspace set as cwd, secret environment variables stripped, and execution timeouts strictly enforced.

### Human-in-the-Loop (HITL) Approvals

BoteX integrates an interactive approval manager for high-risk operations. Configure the policy in `botex.config.json` under `approval.policy`:
* `NONE`: Auto-approves operations permitted by the capability mode.
* `HIGH_RISK` *(default)*: Blocks destructive actions (`delete_file`, `move_file`) and shell execution (`run_command`) until an operator approves.
* `MUTATIONS`: Requires operator approval for any file modifications (`create_file`, `apply_patch`).
* `ALL_RISKY`: Intercepts all mutating tools and system execution commands.

In REPL mode, BoteX prompts for interactive confirmation. In Cloud Gateway mode, actions enter a pending approval queue and can be approved or rejected via REST API (`POST /api/approvals/{id}/decide`).

---

## Model Fallbacks & OpenRouter Live Routing

If a model refuses a task, burns its token limit without output, or hits provider rate limits, BoteX falls back to alternative models defined in `botex.config.json`:

```json
"model_fallbacks": {
  "default": ["deepseek/deepseek-v3.2", "anthropic/claude-sonnet-4", "openai/gpt-5.4-mini"],
  "coding": ["deepseek/deepseek-v3.2", "anthropic/claude-sonnet-4", "openai/gpt-5.4-mini"],
  "auto-beta": ["qwen/qwen3-coder", "deepseek/deepseek-v3.2", "anthropic/claude-sonnet-4"],
  "fast": ["google/gemini-2.5-flash-lite", "deepseek/deepseek-v3.2"]
}
```

BoteX uses two complementary failover layers:

1. **In-Payload OpenRouter Failovers (`extra_body.models`)**: Before sending the first turn to OpenRouter, BoteX runs each fallback candidate through all five safety gates (`Denylist`, `Decisions`, `ZDR`, `Price`, `Tools`) and passes up to three validated slugs in `extra_body["models"]`. If the primary endpoint is overloaded on the initial request, OpenRouter switches to the next validated model on the wire without an extra client round-trip. Meta-routers (`openrouter/auto`, `openrouter/pareto-code`, `openrouter/free`) are excluded from `models: [...]`, and once a run modifies any file (`files_touched`) or executes a command (`exec_ran`), BoteX strips `models` from subsequent turns so a different model never takes over a mutated workspace mid-task.
2. **Engine-Level Rollback & Retry**: If an attempt fails mid-run, **BoteX verifies that all partial file changes from the failed attempt were rolled back** before starting the next candidate model. A fallback model never inherits a dirty workspace.

For OpenRouter runs, BoteX also sets `extra_body.provider` (`data_collection: "deny"` when ZDR is active, `require_parameters: true` when tools or `response_format` are present, `allow_fallbacks: true`, and `sort: "throughput"`), automatically stripping `reasoning` parameters for non-reasoning model slugs so `require_parameters: true` never triggers HTTP 404 rejections. On `DONE`, BoteX queries `GET /api/v1/generation?id=...` in parallel (with a short 404 retry) to record official billing (`total_cost`), queue latency (`queue_time_ms`), inference time (`generation_time_ms`), and prompt cache read/write tokens in `.agent_analytics.json` and `.botex/memory/` task receipts.

---

## Free Models (Non-ZDR Opt-in)

ZDR is on by default and `:free` slugs are rejected pre-flight with `ZDR_VIOLATION`. Operators without a paid subscription (or anyone who accepts that free endpoints may log/train on prompts) can opt in two ways; both leave an audit trail (`zdr_enforced: false` in the result and a stderr warning):

```bash
# Persistent: switch to the bundled free-tier provider preset
# (all profiles resolve to tool-capable :free models)
botex config provider openrouter-free          # or BOTEX_PROVIDER=openrouter-free

# or relax ZDR on the current provider (keeps paid models, widens routing)
botex config zdr off                            # 'on' restores enforcement

# Per-run only, no config change:
botex run "task" --provider openrouter-free
botex run "task" --model qwen/qwen3.8-27b:free --allow-non-zdr
```

```json
{"task": "...", "provider": "openrouter-free"}
{"task": "...", "model": "qwen/qwen3.8-27b:free", "allow_non_zdr": true}
```

> [!NOTE]
> `:free` variants also require the OpenRouter **account-level** free-model opt-in (privacy settings); without it requests surface as `provider_policy_denied`. Free models carry per-day rate limits. The `model_fallbacks` chains in the preset stay entirely on `:free` slugs.

---

## Configuration

Settings are resolved hierarchically (lowest to highest priority):
1. `botex.config.json`: committed defaults (provider profiles, engine limits, security lists).
2. `botex.config.local.json`: machine-local overrides (**gitignored**; place custom keys or limits here).
3. `BOTEX_*` environment variables.

Config files are re-read automatically when they change (file `mtime` check on every access), so edits to `botex.config.local.json` - manual or via `botex config ...` - take effect on the next call, including in a running MCP server; no restart is needed. Environment variables are read from the server process environment, so changing them requires a restart.

Example `botex.config.local.json`:

```json
{
  "engine": {
    "budget_limit_usd": 1.0,
    "max_turns": 20,
    "default_workspace": "C:/projects/my-project"
  },
  "pricing": {
    "max_input_per_mtok": 3.0,
    "max_output_per_mtok": 6.0
  }
}
```

---

## Standalone CLI & REPL

BoteX can be run directly from your terminal without any MCP client:

### Interactive REPL

```bash
botex repl -w ./my-project --profile coding
```
*Prompts for `[y/N]` confirmation whenever the agent wants to delete or move files.*

The startup banner shows the resolved absolute workspace and where it came from (`explicit`, `default_workspace` or `cwd`), and warns when it is the BoteX repository itself. Inside the REPL, `workspace` (or `cd`) prints the current workspace, and `workspace <DIR>` / `cd <DIR>` switches the target project for the rest of the session (relative paths are resolved against the current workspace; the directory must exist).

Set a persistent default so that running `botex` without `-w` never targets the harness itself:

```bash
botex config workspace C:/projects/my-project   # writes engine.default_workspace
botex config workspace none                      # clear it (falls back to cwd)
```

Workspace resolution: explicit `-w` / `workspace_dir` > `engine.default_workspace` > current directory. `BOTEX_DEFAULT_WORKSPACE` overrides the config value.

### Headless One-Shot Tasks

```bash
# Run a specific task
botex run "Add --verbose flag to cli.py" -w ./my-project --profile coding

# Fix a bug with a tight turn budget
botex run "Fix the failing auth test" --files tests/test_auth.py --max-turns 15

# Refactoring with destructive permissions
botex run "Clean up legacy modules" -w ./my-project --allow-destructive
```

### Conversational Chat Mode

Multi-turn discussion with token streaming, read-only tools, and automatic context pruning:

```bash
# Start interactive chat in the terminal
botex chat --model openrouter/auto

# With a custom system prompt and temperature
botex chat --system "Focus on security analysis" --temp 0.2
```
*In-chat commands: `/clear` (reset session), `/history` (review transcript), `/help`, `/exit`.*

### Cloud Gateway & Remote MCP (FastAPI)

Run BoteX as a background cloud daemon with SSE transport, WebSocket chat, and REST endpoints:

```bash
# Start cloud server on default port 8000
botex cloud --host 0.0.0.0 --port 8000
```
*Zero-Friction Local mode runs unauthenticated when `BOTEX_ACCESS_TOKEN` is unset. Set `BOTEX_ACCESS_TOKEN` in `.env` to enforce Bearer token verification on all protected endpoints.*

### Maintenance & Observability

```bash
botex health               # Verify API keys, provider connectivity, and model pricing
botex wallet               # Check OpenRouter balance, key limits, and daily query caps
botex config               # Inspect or modify local configuration defaults
botex --stats              # View weekly token consumption and spend per model
botex --stats --month      # Monthly cost report
botex --history <task_id>  # Inspect exact prompts, tool calls, and diffs for a run
botex --snapshots          # Check disk usage of backup snapshots
botex --clean-snapshots    # Prune old snapshot backups
botex models [--refresh]   # List configured provider models (refresh catalog)
botex serve                # Force MCP stdio server mode explicitly
```

---

## Project Structure

```
server.py              MCP server entry point & CLI dispatcher
botex.cmd / botex.sh   Zero-install launchers (auto-detects python environment)
pyproject.toml         Package configuration (exposes `botex` CLI command)
requirements.txt       Runtime dependencies
botex.config.json      Committed defaults (providers, engine limits, exec/net policy)
ROADMAP.md             Deferred features & technical rationale
botex/
  approval.py          Human-in-the-loop approval manager, async actions, and rollback integration
  chat.py              Conversational chat sessions, token streaming, and read-only sandbox
  server_cloud.py      FastAPI cloud gateway, Remote MCP SSE, WebSocket chat, and REST API
  catalog.py           Dynamic model catalog, TTL caching, and live provider query
  denylist.py          Hierarchical model exclusions (globs and regex)
  wallet.py            Key credits, spend analytics, and daily query limits
  engine.py            Autonomous execution loop, context management & rollback triggers
  file_tools.py        Safe outline-first reading, file creation, moving & deletion
  patch_engine.py      Fuzzy patch matching, syntax validation & snapshot management
  security.py          Path traversal defenses, secret masking & gitignore filtering
  exec_tools.py        Policy-controlled command execution & argument filtering
  capabilities.py      Permission presets (readonly, edit, destructive, full)
  config.py            Layered config loader (defaults < local < env)
  net_tools.py         Net policy enforcement (read_url / fetch_url)
  memory.py            Two-tier memory vault (local .botex/memory/ and global ~/.botex/memory/)
  analytics.py         Cost/token ledger, budgeting & summary reporting
  pricing.py           Live model price guardrail & catalog checks
  providers.py         Provider adapters (OpenRouter, NVIDIA, etc.) & request normalizer
  benchmarks.py        Live model recommendations (recommend_models)
  contracts.py         Task completion verification & status taxonomy
  recipes.py           Recipe loading & system-prompt injection
  i18n.py / ui.py      CLI language & status rendering
  recipes/             Specialized agent personas (planner, reviewer, tdd, etc.)
skills/botex/          Caller-side SKILL.md (delegation patterns)
tests/                 Comprehensive test suite (unit, cloud gateway, chat, approvals)
docs/
  TUTORIAL.md          Architecture deep dive and technical walkthrough
```

---

## Testing

Run the full local test suite (no API key required):

```bash
python -m pytest tests/
```

All unit, approval, chat, memory, and cloud gateway tests run hermetically in offline mode.

---

## License & Trademark

BoteX is licensed under the **Apache License 2.0**. See [LICENSE](LICENSE) for details. Derivative works must retain attribution notices as specified in [NOTICE](NOTICE).

**The BoteX name and logo are trademarks of Jakub Grzesiak** ([jg-webtech.pl](https://jg-webtech.pl)). You are free to fork and modify the code under Apache-2.0, but forks or derived distributions should not use the name "BoteX" or suggest official endorsement without prior written consent.