microharness 0.1.0__tar.gz

microharness-0.1.0/.env.example

@@ -0,0 +1,15 @@
+# Copy this file to .env and fill in your values
+# Note: MODEL_ENDPOINT accepts either the base URL or the full /chat/completions URL.
+#
+# For OpenRouter:
+# MODEL_ENDPOINT=https://openrouter.ai/api/v1/chat/completions
+# MODEL_NAME=anthropic/claude-5.5-sonnet
+# MODEL_API_KEY=sk-or-v1-...
+#
+# For Local Ollama:
+# MODEL_ENDPOINT=http://localhost:11434/v1
+# MODEL_NAME=qwen2.5-coder
+#
+# For Local vLLM:
+# MODEL_ENDPOINT=http://localhost:8000/v1
+# MODEL_NAME=mistralai/Mistral-7B-Instruct-v0.3

microharness-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+.runs/
+.DS_Store
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+.env.local
+.env.*.local
+!.env.example
+datasets/
+.microharness/
+BLOG_POST.md

microharness-0.1.0/AGENTS.md

@@ -0,0 +1,9 @@
+# AGENTS.md
+
+Instructions and project conventions for AI agents operating on `microharness`.
+
+## Guiding Principles
+- **Zero Runtime Dependencies**: The core harness must only rely on Python's standard library. Do not add runtime dependencies to `pyproject.toml`.
+- **Pluggability**: Components must implement minimal protocols (`Model`, `Tool`, `Evaluator`). Never introduce provider-specific subclasses or hardcoded branching.
+- **Testing Standard**: Every feature must include rigorous unit tests in `tests/`. Never write tautological "pass-through" assertions (`assertIn(result, [A, B, C])`). Always use strict equality and test negative failure cases.
+- **Verification**: Run `uv run pytest` before concluding any changes.

microharness-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dima Kagan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

microharness-0.1.0/PKG-INFO

@@ -0,0 +1,491 @@
+Metadata-Version: 2.5
+Name: microharness
+Version: 0.1.0
+Summary: A minimal, zero-dependency, and pluggable AI agent microframework in Python
+Project-URL: Homepage, https://github.com/Kagandi/microharness
+Project-URL: Repository, https://github.com/Kagandi/microharness
+Project-URL: Issues, https://github.com/Kagandi/microharness/issues
+Author: Dima Kagan
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,coding-agent,harness,llm,microframework,swe-bench,zero-dependency
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# microharness
+
+A minimalist, zero-dependency, and fully pluggable AI agent microframework in Python.
+
+Built with **zero external runtime dependencies** (standard library only) to teach the core architectural boundaries of agentic systems. Compatible with modern packaging tools like [`uv`](https://github.com/astral-sh/uv).
+
+---
+
+## The Core Mental Model: Harness vs. Loop
+
+| Component | Responsibility | Location in `microharness` |
+| :--- | :--- | :--- |
+| **Agent Loop** *(The Engine)* | Pure Thought $\to$ Action $\to$ Observation cycle. Agnostic to benchmarks, sandboxes, and models. | [`core/loop.py`](core/loop.py) (~40 LOC) |
+| **Harness** *(The Chassis)* | The outer environment: workspace directory, sandboxing, budgets, memory compaction, telemetry/tracing, and grading. | [`core/harness.py`](core/harness.py) |
+| **Interactive Router** | One command table (`/model`, `/resume`, `/compact`, `/skill`, ...) shared by the CLI session and the TUI, so the two frontends cannot drift. | [`core/interactive.py`](core/interactive.py) |
+
+---
+
+## Configuration, Steering, Skills, Commands & Tool Plugins
+
+`microharness` supports cascading configuration at two distinct scopes:
+1. **Global User Baseline** (`~/.microharness/` or `--global-dir`)
+2. **Project-Local Scope** (`.microharness/` in current workspace root)
+
+### 1. Configuration Files (`config.json`)
+Configure your baseline model, endpoint, API key, and limits globally or override them per project:
+* **Global Baseline**: `~/.microharness/config.json`
+* **Project Override**: `.microharness/config.json`
+
+```json
+{
+  "default_model": "smart",
+  "max_context_tokens": 64000,
+  "trigger_ratio": 0.80,
+  "max_tool_tokens": 8000,
+  "sandbox": false,
+  "models": {
+    "fast": {
+      "model": "gemini-2.5-flash",
+      "provider": "google",
+      "description": "Fast flash model"
+    },
+    "smart": {
+      "model": "anthropic/claude-5.5-sonnet",
+      "provider": "openrouter",
+      "description": "Frontier reasoning model"
+    },
+    "local": {
+      "model": "local-model",
+      "provider": "lmstudio",
+      "endpoint": "http://localhost:1234/v1",
+      "description": "Local offline LLM"
+    }
+  }
+}
+```
+
+Per-model context caps: a `models` entry may declare `max_context_tokens`, and a provider profile in `providers.json` may declare `context_tokens` (entry > profile > global `max_context_tokens`/`max_tokens`/`context_tokens`); switching models applies the cap live.
+
+Legacy `max_context_chars`/`max_tool_chars` keys are removed; old char budgets converted as `chars//4` (e.g. 4000 chars behaved as 1000 tokens).
+To preserve prior behavior, set `max_tool_tokens`/`max_context_tokens` explicitly (e.g. `"max_tool_tokens": 1000` replaces a former 4000-char tool limit).
+
+#### Precedence Hierarchy:
+1. **CLI Flags** (`--model`, `--endpoint`, `--api-key`, `--sandbox`, `-d`) — *Highest priority*
+2. **Environment Variables / Local `.env`** (`MODEL_ENDPOINT`, `MODEL_NAME`, `MODEL_API_KEY`)
+3. **Project Config** (`.microharness/config.json`) — *Project overrides*
+4. **Global Config** (`~/.microharness/config.json`) — *Machine baseline*
+5. **Hardcoded Fallbacks** (`MockModel`, default prompts) — *Lowest priority*
+
+#### Amazon Bedrock
+`bedrock` is a built-in provider that targets Bedrock's official OpenAI-compatible endpoint.
+On a machine with active AWS SSO (`aws sso login`) it works with zero config:
+
+```bash
+uv run microharness --model "bedrock/us.openai.gpt-5.6-sol" "Refactor auth.py"
+```
+
+Credentials resolve from the standard chain (environment, `~/.aws/credentials`, SSO
+cache), and requests are SigV4-signed with the standard library; the harness never
+shells out to the AWS CLI. The region resolves from `config.json` `"region"`, then
+`AWS_REGION`, then `AWS_DEFAULT_REGION`, then the `~/.aws/config` profile region
+(profile from `config.json` `"aws_profile"` or `AWS_PROFILE`, default `default`).
+Without credentials or region the spec falls back to `MockModel` with a hint
+(`aws sso login`). A `BEDROCK_API_KEY` bearer token still overrides SSO when set.
+Only models whose Bedrock model card lists Chat Completions are served on this
+endpoint (Claude/Nova IDs return `model_not_found`); the registry default is
+`us.openai.gpt-5.6-sol`.
+
+Auth schemes are pluggable: built-ins are `none`, `bearer`, `header`, and `sigv4`
+(see `core/auth.py`), and extra single-file plugins can be installed as
+`~/.microharness/auth/<scheme>.py` (global dir only, never project-local).
+
+The shim exposes no prompt-cache or reasoning parameters, so the Bedrock profile runs with `cache_strategy: "openai_breakpoint"` and `reasoning_format: "none"`: with `cache_ttl` on, the first system text part carries an explicit `prompt_cache_breakpoint` (sub-1024-token prefixes are a server-side no-op); a stale user `providers.json` keeps `"none"` and simply skips breakpoints.
+
+### 2. Cascading Instructions (`AGENTS.md`)
+You can provide personal agent preferences globally, while projects can specialize or override them:
+* **Global Baseline**: `~/.microharness/AGENTS.md` (e.g., your personal coding habits, formatting preferences).
+* **Project Conventions**: `.microharness/AGENTS.md` or `./AGENTS.md` in the repo root (e.g., repo-specific test commands, architecture rules).
+
+The harness loads both in cascading order (Global baseline first, Project local second) into the system prompt.
+
+### 3. Progressive Skills Disclosure (`.microharness/skills/` & Shadowing) — Agent-Facing
+Define reusable task workflows for the **agent** in `.microharness/skills/<skill_name>/SKILL.md`:
+* **Global Skills** (`~/.microharness/skills/`): Available across all projects on your machine.
+* **Project Skills** (`.microharness/skills/`): Project-specific tools and workflows (namespaced cleanly without polluting the project root).
+* **Skill Shadowing**: If a project defines a skill with the same name as a global skill, the project version cleanly overrides it.
+* **Progressive Disclosure**: Full skill files are never dumped into the prompt. Instead, the harness injects a 1-line index with scope badges (`[global]` or `[project]`).
+* **Lazy Loading & Security**: The agent reads full instructions on demand via `read_file`. Global skills are authorized for reading, while all file writes remain strictly sandboxed to the project directory.
+
+### 4. Custom Slash Commands (`.microharness/commands/*.md`) — User-Facing
+Define reusable prompt templates and macros for the **user** in `.microharness/commands/<name>.md`:
+```markdown
+# Review code changes
+Review the git diff or specified files: $ARGUMENTS.
+Check for:
+1. Correctness and edge-case logic bugs
+2. Unit test coverage
+3. Adherence to conventions in AGENTS.md
+```
+* **Skills vs. Commands**: Skills teach the **agent** how to perform complex workflows; Commands give the **user** prompt shortcuts.
+* **Invocation**: Type `/review src/auth.py` in interactive chat or pass `microharness "/review src/auth.py"`.
+* **Argument Substitution**: `$ARGUMENTS` or `{args}` is substituted with your trailing arguments.
+* **Dynamic Help & Shadowing**: `/help` lists all discovered custom commands with their descriptions and scopes (`[project]` or `[global]`). Project commands shadow global ones.
+ 
+### 5. Custom Tool Plugins (`.microharness/tools/*.py`) — Zero-Commit Extensibility
+Add new capabilities to the agent dynamically without modifying harness core code or making git commits:
+* **Global Tools** (`~/.microharness/tools/*.py`): Available across all projects on your machine (always trusted and loaded automatically).
+* **Project Tools** (`.microharness/tools/*.py`): Scoped to the current repository. Requires explicit opt-in via `--trust-project-tools` (or `"trust_project_tools": true` in `~/.microharness/config.json`) to prevent untrusted code execution from cloned repositories.
+* **Tool Shadowing & Overrides**: A project tool with the same `name` overrides the global version. If a custom plugin shares a name with a built-in tool (e.g. `bash`), it will override it and emit a warning to ensure full visibility.
+
+#### Authoring Conventions
+A tool plugin file can follow any of these patterns:
+
+##### Option A: Standalone Tool Class (Simplest)
+Any class conforming to the `Tool` protocol (`name`, `description`, `parameters`, `execute`):
+```python
+# ~/.microharness/tools/web_fetch.py or .microharness/tools/calculator.py
+class CalculatorTool:
+    name = "calculate"
+    description = "Evaluates basic math expressions safely"
+    parameters = {
+        "type": "object",
+        "properties": {
+            "expression": {"type": "string", "description": "The math expression (e.g. '24 * 7')"}
+        },
+        "required": ["expression"],
+    }
+
+    def execute(self, expression: str) -> tuple[int, str]:
+        try:
+            return 0, str(eval(expression, {"__builtins__": {}}, {}))
+        except Exception as exc:
+            return 1, f"Error: {exc}"
+```
+
+##### Option B: Environment-Aware Factory (`get_tools`)
+Use `get_tools(env)` if your tool needs access to the harness execution environment (e.g. `env.workspace_dir`):
+```python
+# .microharness/tools/db_tool.py
+class DatabaseTool:
+    name = "query_db"
+    description = "Queries a project SQLite database"
+    parameters = {
+        "type": "object",
+        "properties": {"query": {"type": "string"}},
+        "required": ["query"],
+    }
+
+    def __init__(self, env=None):
+        self.workspace = env.workspace_dir if env else "."
+
+    def execute(self, query: str) -> tuple[int, str]:
+        # Query local database in self.workspace
+        return 0, "Query results..."
+
+def get_tools(env=None):
+    return [DatabaseTool(env)]
+```
+
+##### Option C: Module-Level `tools` List
+Export an explicit list of pre-instantiated tool instances:
+```python
+# .microharness/tools/helpers.py
+tools = [ToolOne(), ToolTwo()]
+```
+
+---
+
+## Working on Existing Projects
+
+By default, the agent runs directly in your **current working directory** (like Claude Code or Aider). It sees all your existing files, respects git, and resumes right where you left off:
+
+```bash
+# Operates directly on the current directory:
+uv run microharness "Inspect the files in this directory and explain the architecture"
+
+# Or point to any other project directory with -d:
+uv run microharness -d /path/to/my-project "Fix the bug in auth.py"
+```
+
+If you ever want an isolated disposable scratchpad (e.g. for testing without touching real files), pass `--sandbox`:
+```bash
+uv run microharness --sandbox "Experiment with writing a new scraper"
+```
+
+### Docker Sandboxing (via OrbStack or Docker Desktop)
+For 100% containerized process, operating system, and filesystem isolation (e.g. running untrusted code, heavy test suites, or SWE benchmarks), pass `--docker`:
+```bash
+# Run educational demo inside an isolated Linux Docker container
+uv run microharness --demo calculator --docker
+
+# Run the Mini-SWE benchmark suite inside Docker
+uv run microharness --benchmark mini-swe --docker
+
+# Specify a custom Docker image (default: python:3.11)
+uv run microharness --docker --docker-image python:3.11 "Run pytest and fix bugs"
+```
+* **Instant Hybrid I/O**: The workspace directory is mounted at `/workspace`. File reading, writing, and editing occur on the host filesystem with zero container latency, while all bash commands execute inside the isolated Docker Linux container via `docker exec`.
+* **Zero Runtime Dependencies**: Operates entirely via Python's standard library `subprocess` without third-party Docker SDKs. Works out of the box with **OrbStack** or standard Docker Desktop.
+* **Automatic Teardown**: Containers are automatically stopped and removed upon task completion with zero orphaned background containers.
+
+If you prefer a one-and-done batch run (e.g. for CI), pass `--batch`:
+```bash
+uv run microharness "Run pytest and fix any failures" --batch
+```
+
+---
+
+## Continuous Interactive Chat & Meta-Commands
+
+When you chat with the agent, the harness maintains persistent memory and renders a clean **context budget status line** before every turn:
+
+```text
+─── Context: 1.4k / 8k (17.8%) ───
+You: 
+```
+
+### Slash Commands (No Model Call)
+You can inspect or control the harness runtime directly:
+
+* **`/model [name|number]`**: Inspect available models or switch active model dynamically on the fly (e.g. `/model fast` or `/model 2`). In TUI mode, Tab autocompletes configured model names. A name is matched against the `models` aliases in `config.json`, their underlying model ids, and the provider registry (`openai` or `openai/gpt-4o` both work). An unrecognized name is **rejected with the list of valid models** rather than silently constructing a client for a model that does not exist. The `--model` startup flag applies the same recognition rules but only warns on stderr, so it remains usable for endpoints whose provider is not in the registry.
+* **`/resume [id|number]`**: List previous sessions in `~/.microharness/runs/` (with workspace affinity) or resume conversation history from an earlier session in-place. Discovery reads only the newest sessions first and falls back to a full scan when your repository has no recent session, so an older session for the same repo stays reachable.
+* **`/cache [5m|1h|off]`**: Inspect or switch prompt caching duration on the fly (`5m` standard ephemeral, `1h` extended beta, or `off`).
+* **`/status`**: Displays detailed memory metrics (system, user, assistant, and tool counts + budget percentage) and prompt cache hit rates.
+* **`/compact`**: Manually triggers memory compaction to prune older tool observations and reclaim context space.
+* **`/new`**: Starts a fresh conversation context while keeping all your project files intact.
+* **`/help`**: Lists available commands.
+* **`/exit`**: Finalizes and exports the session trace.
+
+### Cancelling a Running Turn
+
+The two cancel keys are **not** equivalent, and the status bar says so while a turn runs:
+
+* **`Ctrl+C`** aborts the active step immediately, including a request that is already in flight. The incomplete tool turn is dropped and the session stays usable.
+* **`Esc`** is a cooperative cancel. It takes effect at the next step boundary and while the model waits between retries (for example during a throttle backoff). The moment it is seen the UI prints `Cancelling… aborting the pending model request` and abandons the wait.
+
+`Esc` cannot abort a request that is currently waiting on the provider, because the HTTP timeout covers time-to-first-byte and shortening it would break slow models. Use `Ctrl+C` for that. See SPEC.md §5.2 for the planned work to unify the two.
+
+---
+
+## Quickstart with `uv`
+
+### 1. Install & Sync Environment
+```bash
+uv sync
+```
+
+### 2. Run the Test Suite
+```bash
+uv run pytest
+```
+*(All 250+ unit and integration tests run in ~7s. Correctness guarantees are enforced by mutation testing — see SPEC.md §4.)*
+
+### 3. Interactive and TUI Sessions
+```bash
+# Launch interactive mode (full-screen TUI):
+uv run microharness
+
+# Resume previous interactive session:
+uv run microharness --resume
+
+# Resume a specific session by ID:
+uv run microharness --resume run-2026-10-03-xxxx
+```
+
+### 4. Run Mini-SWE for Rapid Sanity Testing
+Run the lightweight 5-task sanity test suite before launching heavy benchmarks:
+```bash
+# Run the entire Mini-SWE sanity benchmark suite:
+uv run microharness --benchmark mini-swe
+
+# Filter to a specific challenge (e.g. rate_limiter or query_builder):
+uv run microharness --benchmark mini-swe --task rate_limiter
+
+# Built-in demo tasks:
+uv run microharness --demo calculator
+uv run microharness --demo greeting
+```
+
+---
+
+## Mini-SWE Benchmark Suite (Sanity & Smoke Testing)
+
+`microharness` includes **Mini-SWE**, a fast, lightweight, pure-Python benchmark designed primarily for **rapid sanity testing, local iteration, and CI smoke testing**:
+
+* **Sanity Testing Focus**: Validates the agent's tool-calling loop, multi-turn file editing, memory compaction, and test assertion grading in seconds—without burning model quota or waiting on multi-hour containerized benchmarks.
+* **Pure Python & Zero Docker**: Operates entirely with Python's standard library. No multi-gigabyte container downloads, instant startup.
+* **Anti-Cheating Evaluator (`PristineTestEvaluator`)**: Evaluators restore pristine test files prior to running verification. An agent cannot bypass tests by deleting or rewriting assertions in the test suite.
+* **5 Realistic Engineering Challenges**:
+  1. `rate_limiter`: Token Bucket rate limiter losing fractional refills under rapid polling.
+  2. `circular_serializer`: Circular JSON serializer cycle detection & ISO-8601 formatting.
+  3. `auth_middleware`: HTTP auth middleware case-insensitive headers & whitespace tolerance.
+  4. `lru_ttl_cache`: LRU cache with TTL updating existing keys & refreshing MRU order.
+  5. `query_builder`: SQL query builder AST precedence grouping & single-quote escaping.
+* **Automated Scorecard & JSON Telemetry**: Generates a formatted summary table in the terminal and exports comprehensive JSON results to `~/.microharness/runs/benchmark_report.json`.
+
+---
+
+## DeepSWE-mini Benchmark Suite (Harbor Format & Docker)
+
+`microharness` natively supports **DeepSWE-mini** (curated from [Datacurve-AI DeepSWE](https://github.com/datacurve-ai/deep-swe) and [`LocalLLaMA/deepswe-mini`](https://huggingface.co/datasets/LocalLLaMA/deepswe-mini)):
+
+* **16 Curated Real-World Repositories**: Across Python, Go, and TypeScript (e.g. `aiomonitor`, `bandit`, `ipython`, `narwhals`, `textual`, `prometheus`, `valibot`, `dasel`).
+* **Harbor Standard Compliance**: Automatically parses `task.toml` metadata (via Python 3.11's standard library `tomllib`), pulls task ECR container images, mounts behavioral verifiers, and grades via `tests/grader.py`.
+* **Zero Dependency Container Sandboxing**: Spawns isolated Docker containers via **OrbStack** or Docker Desktop, syncs repo code at NVMe speed, and automatically captures `model.patch` diffs.
+
+```bash
+# Clone tasks once (only ~3.5MB repository metadata):
+git clone --depth 1 https://github.com/datacurve-ai/deep-swe datasets/deep-swe
+
+# Run the entire 16-task DeepSWE-mini benchmark suite in Docker:
+uv run main.py --benchmark deepswe-mini --docker
+
+# Run a specific task with custom step & timeout budgets:
+uv run main.py --benchmark deepswe-mini --task aiomonitor --max-steps 500 --timeout 7200 --docker
+
+# Run with official Datacurve Pier framework using microharness adapter:
+uvx --from datacurve-pier pier run -p datasets/deep-swe/tasks/aiomonitor-task-snapshots-diff \
+  --agent-import-path benchmarks.pier_agent:MicroharnessAgent --env docker
+```
+
+---
+
+## True Pluggability (Zero Code Modifications)
+
+Because components follow minimal Python `Protocols`, you can plug in any Model, Tool, or Evaluator from the outside without touching a single line of harness code:
+
+```python
+from core.harness import Harness
+
+# In-place coding agent on your repo with global and project steering:
+harness = Harness(
+    model=my_custom_model,  # Or HttpChatModel(endpoint, model, key)
+    workspace_dir=".",  # Works directly on your project
+    global_dir="~/.microharness",  # Global config, instructions & skills
+    tools=[bash_tool, my_tool],  # Custom tools (dynamically documented in system prompt)
+)
+harness.run_tui("Help me refactor the database layer")
+```
+
+---
+
+## Key Educational Paradigms Demonstrated
+
+1. **In-Place Project Operation vs. Sandboxing (`core/environment.py`)**
+   - By default, operates directly on existing project files with zero root directory pollution.
+   - Optional `--sandbox` creates an isolated scratchpad in `~/.microharness/runs/` (or `--runs-dir`).
+   - Prevents path traversal outside project boundaries while permitting read access to authorized global directories (`allowed_read_dirs`).
+   - Executes bash with timeouts and combined stdout/stderr.
+
+2. **Cascading Configuration & Steering (`core/harness.py`)**
+   - Loads global defaults from `~/.microharness/config.json`.
+   - Injects global user instructions (`~/.microharness/AGENTS.md`) and project instructions (`./AGENTS.md`) in cascading order.
+   - Discovers `skills/` and `commands/` globally and locally; project definitions cleanly shadow global ones.
+   - Indexes skills lazily with scope badges to conserve context tokens.
+
+3. **Targeted File Editing vs. Full Rewrites (`core/tools.py`)**
+   - Built-in `edit_file(path, old_str, new_str)` enforces exact, unique string replacement.
+   - Prevents token wastage and LLM hallucination bugs common when rewriting large files with `write_file`.
+
+4. **Dynamic Tool Introspection (`core/tools.py`)**
+   - `ToolRegistry.to_system_prompt_snippet()` automatically reflects registered tools in the system prompt. Custom tools require zero prompt tweaking.
+
+5. **Large Log Handling & Spillover (`core/tools.py`)**
+   - Massive command outputs are head + tail truncated.
+   - The full, raw output is spilled to `~/.microharness/runs/<run_id>/logs/` so it never pollutes the user's project root.
+
+6. **Proactive 80% Context Compaction & Memory Optimization (`core/memory.py`)**
+   - Proactively prunes older tool observations at an 80% high-water mark (`trigger_ratio = 0.80`), keeping 20% reserved for output tokens and model reasoning.
+   - **Enriched Tombstones with Log Pointers**: Collapsed tool outputs embed the exact spilled log file path (`Full log: <path>. Use read_file to inspect if needed.`), giving the agent a deterministic bridge to inspect full outputs.
+   - **Historical Reasoning Pruning**: Automatically prunes transient `<think>...</think>` and `<thinking>...</thinking>` reasoning streams from older assistant turns to reclaim thousands of tokens for reasoning models (DeepSeek-R1, Claude Thinking, o1/o3).
+   - **Session Files Modified Ledger**: Injects and maintains an active session ledger (`[Session Files Modified: file1.py, file2.py]`) across compactions at the safe prefix.
+   - Preserves system prompt, initial task, and recent working turns.
+
+7. **Git Patch Export (`patch.diff`) & Modern CLI Tracing (`core/tracer.py`)**
+   - Automatic git diff extraction: generates `patch.diff` for coding tasks in git repositories.
+   - **Modern Developer CLI Output**: Eliminates academic ReAct tags (`Thought:` / `Action:` / `Observation:`) in favor of natural assistant speech, `$ <command>` execution, `● Read/Write/Edit <path>`, real-time duration headers, and clean output gutters.
+   - Persists machine-readable `trace.json` and human-readable `trace.md` in `~/.microharness/runs/<run_id>/` for every run.
+
+8. **Automated Evaluation (`core/evaluator.py`)**
+   - Evaluators test whether the agent actually succeeded (e.g. running test commands, asserting file contents, or Docker-based SWE-bench graders).
+
+---
+
+## Project Structure
+
+```
+microharness/
+├── pyproject.toml      # Modern PEP 621 packaging for uv & hatchling
+├── uv.lock             # Deterministic lockfile generated by uv
+├── SPEC.md             # Detailed specification & design rationale
+├── README.md           # Quickstart and overview
+├── AGENTS.md           # Project conventions for agents
+├── .microharness/      # Clean project-level configuration namespace
+│   ├── skills/         # Progressive disclosure skills
+│   │   └── run-tests/
+│   │       └── SKILL.md
+│   └── commands/       # Custom slash commands (user prompt shortcuts)
+│       └── review.md
+├── .env.example        # Environment variable template
+├── main.py             # Runnable demonstration & CLI entrypoint
+├── benchmarks/         # SWE benchmark suites & runners
+│   ├── mini_swe.py     # 5 real-world pure-Python SWE tasks & PristineTestEvaluator
+│   ├── harbor.py       # Harbor / DeepSWE-mini benchmark loader & Docker verifier adapter
+│   ├── pier_agent.py   # Datacurve Pier framework agent adapter (MicroharnessAgent)
+│   └── runner.py       # Benchmark orchestrator, scorecard table & incremental JSON report export
+├── core/
+│   ├── types.py        # Clean dataclasses (Message, ToolCall, Task, Trajectory, RunResult)
+│   ├── prompts.py      # System prompt templates & prompt assembly
+│   ├── environment.py  # Workspace & bash runner (supports in-place and sandbox)
+│   ├── tools.py        # Pluggable tool protocol & built-ins (bash, read_file, write_file)
+│   ├── memory.py       # Context manager & 80% high-water mark compaction
+│   ├── protocols.py    # Model protocol, capability protocols (cache, deadline, cancel) & cancellation
+│   ├── usage.py        # Token normalization, per-model telemetry & run-level totals
+│   ├── providers.py    # Provider registry, model-spec resolution & client construction
+│   ├── model.py        # Generic HttpChatModel & MockModel clients
+│   ├── config.py       # Cascading configuration, JSONC reading & setting resolution
+│   ├── skills.py       # Progressive-disclosure skills (discovery, summaries, activation)
+│   ├── commands.py     # Custom slash commands & slash-input resolution
+│   ├── discovery.py    # Hierarchical resource discovery & @file-tagging
+│   ├── interactive.py  # Interactive command router shared by the CLI session & the TUI
+│   ├── session.py      # Step driver, session index, resumption & trace reconstruction
+│   ├── loop.py         # Native tool-calling loop (~40 lines)
+│   ├── evaluator.py    # Automated graders (CommandTestEvaluator, FileContentEvaluator)
+│   ├── tracer.py       # Telemetry collector, modern CLI renderer & trace exporter
+│   ├── tui.py          # Full-screen curses TUI (markdown rendering, autocomplete)
+│   ├── tui_session.py  # TUI turn driver: step rendering & cooperative cancellation
+│   └── harness.py      # Harness orchestrator wiring the chassis together
+└── tests/
+    ├── test_benchmarks.py  # Mini-SWE baseline failure, anti-cheating & reference tests
+    ├── test_harbor.py      # Harbor task parsing, Docker image validation & evaluator tests
+    ├── test_environment.py # Path sandboxing & bash timeout tests
+    ├── test_tools.py       # Tools, truncation & disk spillover tests
+    ├── test_memory.py      # Conversation history, stats & 80% compaction tests
+    ├── test_model.py       # Endpoint normalization, serialization & mock model tests
+    ├── test_evaluator.py   # Grader assertions tests
+    ├── test_config.py      # Config cascade, JSONC parsing & tool-trust boundary tests
+    ├── test_protocols.py   # Capability protocol detection tests
+    ├── test_usage.py       # Token normalization & telemetry accounting tests
+    ├── test_providers.py   # Provider registry, model specs & available-model tests
+    ├── test_skills.py      # Skill discovery, summaries & activation tests
+    ├── test_commands.py    # Slash-command discovery, expansion & resolution tests
+    ├── test_prompts.py     # Prompt assembly & AGENTS.md cascading tests
+    ├── test_session.py     # Step driver retries, deadlines & session resumption tests
+    ├── test_interactive.py # Command router & rendering tests
+    ├── test_tui_session.py # TUI turn rendering & cancellation tests
+    └── test_harness.py     # End-to-end lifecycle, global config, commands & guardrails tests
+```

microharness-0.1.0/PR_DESCRIPTION.md

@@ -0,0 +1,75 @@
+# feat: make TUI default, add local providers, non-blocking execution, and token limits
+
+## Summary of Changes
+
+This PR modernizes the interactive developer experience, provider registry, and context limits across `microharness`:
+
+1. **TUI as Default Interactive Interface**:
+   - `Harness.run_interactive()` launches the full-screen Curses TUI by default.
+   - Removed legacy `ConsoleUI`; interactive mode is now 100% full-screen TUI.
+   - Headless execution is strictly handled via `--batch` (or `Harness.run(task)` in code). If an interactive run is attempted without a TTY, the CLI provides helpful guidance to use `--batch`.
+   - Single entrypoint in `main.py` without introducing extra CLI modules into `core/`.
+
+2. **Non-Blocking Curses Execution & Thread-Safe Redraw**:
+   - Agent turns run asynchronously on a background worker thread (`worker_thread`), with non-blocking key polling (`stdscr.timeout(50)`).
+   - Thread-safe drawing synchronization using `_draw_lock` prevents curses race conditions and display corruption.
+   - Status spinner and UI remain responsive while model/tool execution takes place.
+
+3. **Safe Escape Key Handling**:
+   - Pressing <kbd>Esc</kbd> during an active turn signals execution cancellation (`_cancel_requested = True`).
+   - Pressing <kbd>Esc</kbd> when idle dismisses menus, clears autocomplete queries, or clears input buffer.
+   - **Never exits the session on an empty prompt** when pressing <kbd>Esc</kbd> (exit is via `/exit` or <kbd>Ctrl+C</kbd> / <kbd>Ctrl+D</kbd>).
+
+4. **Interactive Reasoning / Thinking Effort Control**:
+   - Added interactive `/reasoning` popup menu in TUI with choices: `off`, `low`, `medium`, `high`, `xhigh`, `max`.
+   - Dynamic update of active reasoning effort in TUI header and model serialization.
+   - Support for `xhigh` and `max` levels across model payloads (OpenAI and OpenRouter specs).
+
+5. **First-Class Local Provider Presets & Scoped Endpoints**:
+   - Added built-in presets for local inference engines in [`core/providers.json`](file:///Users/dimakagan/Projects/mini-harness/core/providers.json): `lmstudio` (`http://localhost:1234/v1`), `vllm` (`http://localhost:8000/v1`), `llamacpp` (`http://localhost:8080/v1`), `ollama` (`http://localhost:11434/v1`), and generic `local`.
+   - Added provider aliases (`lm-studio`, `llama-cpp`, `llama.cpp`).
+   - Preserved `LAST_RESORT_MODEL = "cohere/north-mini-code:free"` and configured `anthropic/claude-5.5-sonnet` / `claude-5.5-sonnet` frontier models.
+   - Fixed endpoint scoping: models defined under `models: { ... }` in config retain their provider-specific endpoints without being overwritten by top-level defaults.
+
+6. **Unified Model Naming (`default_model` / `defaultModel`)**:
+   - Supports `default_model` and `defaultModel` keys with precedence over legacy `model` in configuration.
+   - Clean documentation and schema examples throughout README.
+
+7. **Token-Only Context and Tool Limits**:
+   - Fully replaced `max_context_chars` and `max_tool_chars` with `max_context_tokens` (default 64,000 tokens ≈ 256k chars) and `max_tool_tokens` (default 8,000 tokens ≈ 32k chars).
+   - `HarnessConfig`, `ResolvedConfig`, `Harness`, `Memory`, and `ToolRegistry` expose only token limits.
+   - Legacy character settings from old config files are automatically converted to tokens during resolution.
+   - Head (1/3 ≈ 10.6k chars) + Tail (2/3 ≈ 21.3k chars) preservation for tool outputs (at default 8,000 tokens) with disk log spillover.
+
+8. **Robust TUI Thread Safety & Cancellation UX**:
+   - `TUIState` protects transcript mutations and line slices under `threading.RLock()`.
+   - Curses rendering calls are kept strictly on the main thread via `request_redraw()` across both `TuiUI` and `TuiTurnRunner.refresh()`, eliminating background thread curses calls.
+   - Submitting Enter while a turn is running gives immediate feedback (`⏳ Turn is running (press Esc or Ctrl+C to cancel)`).
+   - `Harness.run_tui(task_id="interactive_session")` standardizes run-directory naming, with `allow_bare_words=True` enabled for interactive shell commands.
+
+9. **Configuration Migration & Backward Compatibility**:
+   - `get_default_global_dir()` gracefully falls back to `~/.mini-harness` if `~/.microharness` does not exist.
+   - Legacy `max_tool_chars` and `max_context_chars` in configuration files are automatically converted to tokens (`chars // 4`).
+   - Re-exported `find_recent_sessions`, `load_session_messages`, and `reconstruct_messages_from_steps` in `core.tracer` for backward compatibility.
+
+10. **Portable Reasoning Effort**:
+    - Maps `xhigh` and `max` to `"high"` on standard OpenAI endpoints to prevent API validation 400 errors, while preserving full values on OpenRouter endpoints.
+
+11. **Offline Interactive Guidance**:
+    - Interactive TUI launch verifies endpoint and credentials via `Connection.missing_credentials` (handling local vs cloud providers uniformly) and fails fast with setup instructions, while headless batch and benchmark runs continue using `MockModel` when offline.
+
+## Verification & Testing
+
+- **Zero Runtime Dependencies**: Standard library only (`pyproject.toml` dependencies remain empty).
+- **Correct Repository URLs**: Pointing to `https://github.com/Kagandi/microharness`.
+- **Unit Test Suite**: 557 passing tests (`uv run pytest`):
+  - `tests/test_config.py` (token limits, legacy char migration, global dir fallback, cascade priority, reasoning choices)
+  - `tests/test_harness.py` (TUI defaults, headless NullUI, session handling)
+  - `tests/test_interactive.py` (model switching runner synchronization, reasoning status update)
+  - `tests/test_memory.py` (token limits, high-water mark compaction)
+  - `tests/test_model.py` (reasoning effort mapping for OpenAI vs OpenRouter)
+  - `tests/test_providers.py` (local provider presets, scoped endpoints)
+  - `tests/test_tools.py` (token limits and spillover)
+  - `tests/test_tui.py` (Esc key safety, reasoning subcommand menus, non-blocking threading)
+  - `tests/test_tui_session.py` (turn runner lifecycle, request_redraw dispatching, Esc cancellation)
+- **Lint & Style**: Passed `uv run ruff check` with 0 warnings.