x2harness (玄心 Harness)

Production-grade Reference Architecture for Autonomous Coding Agents

The companion Python library for the book Coding Agents: Foundations, Architecture, Harnesses, and Enterprise Practice.

$$\text{Coding Agent} = \text{Foundation Model} + \text{Agent Harness}$$

x2harness provides a modular, zero-magic implementation of the Seven Subsystems that make autonomous coding agents reliable on production repositories.

The 7 Subsystems Architecture

1. Model Policy Proposer (x2harness.providers): Adapters for DeepSeek, Claude, GPT, Ollama (Qwen2.5-Coder, MiniCPM5), SGLang, and deterministic mock providers.
2. Context Assembler (x2harness.context): AST skeletonization, PageRank repository maps, FastCDC content-defined chunking, and working set token budgeting.
3. Tool Dispatcher (x2harness.tools): Typed JSON Schema registry, Model Context Protocol (MCP) client, and ring-buffer output truncation.
4. Execution Loop & Verifier (x2harness.core & x2harness.verifier): Deterministic turn execution, 5-stage progressive verification, SBFL (Ochiai/$D^*$) fault localization, and reward-hacking guards.
5. Planning & Refactoring Engine (x2harness.planner & x2harness.engine): Spec-to-DAG topological wave solver, dynamic plan repair, and Tree-sitter AST surgery.
6. Scale & Enterprise Concurrency (x2harness.scale): Tarjan SCC condensation for cyclic dependency graphs, Test Impact Analysis (TIA), and ephemeral Git worktree pools.
7. Security, Policy & Telemetry (x2harness.security & x2harness.telemetry): Zero-trust process/bwrap sandbox, non-bypassable policy gates, hierarchical JSON-L tracing, and inference unit economics.

Quickstart

Installation

# Install from PyPI
pip install x2harness

# Or install editable from repository
pip install -e .

Python API

from x2harness import AgentHarness
from x2harness.providers import OllamaProvider, OpenAICompatProvider
from x2harness.context import RepoMapAssembler
from x2harness.verifier import TestPipelineVerifier
from x2harness.tools import ToolRegistry, make_file_tools

# 1. Choose your model provider (cloud or local)
provider = OllamaProvider(model="qwen2.5-coder:1.5b")

# 2. Assemble the harness
harness = AgentHarness(
    provider=provider,
    context_assembler=RepoMapAssembler(repo_root="."),
    tools=make_file_tools(workspace="."),
    verifier=TestPipelineVerifier(test_command="pytest tests/"),
    max_turns=10,
    cost_budget_usd=0.50
)

# 3. Run autonomous task with deterministic closed-loop verification
result = harness.run(task="Fix the ZeroDivisionError in math_utils.py")
print(f"Status: {result.status.value}, Verified: {result.verified}")

Command-Line Interface (x2)

# Run agent on a task
x2 run --model ollama/qwen2.5-coder:1.5b --task "Fix broken test in tests/test_db.py"

# Inspect execution trace
x2 trace runs/trace-20260908.jsonl

# Run deterministic benchmark
x2 bench --suite minibench

License

Apache-2.0 License.