Metadata-Version: 2.4
Name: x2harness
Version: 0.1.0
Summary: XuanXin Harness: Production-grade Reference Architecture for Autonomous Coding Agents
Author: Xuan Xin
Author-email: xuanxinjushi@gmail.com
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyzipper>=0.3.6
Requires-Dist: pydantic>=2.0.0
Requires-Dist: openai>=1.0.0
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# x2harness (玄芯 Harness)

**Production-grade Reference Architecture for Autonomous Coding Agents**

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/)

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

```bash
# Install from PyPI
pip install x2harness

# Or install editable from repository
pip install -e .
```

### Python API

```python
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`)

```bash
# 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.
