python-agent-harness 1.5.0__py3-none-any.whl

python_agent_harness-1.5.0.dist-info/METADATA

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: python-agent-harness
+Version: 1.5.0
+Summary: Python agent execution harness: agent loop, tools, plan/build modes, sessions
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: prompt_toolkit>=3.0
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: pyright>=1.1.380; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: coverage[toml]>=7.0; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Requires-Dist: mcp<3,>=2.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# python-agent-harness
+
+**A lightweight Python coding-agent harness for reliable autonomous coding.**  
+FSM-driven execution · OpenAI-compatible · built for daily use and easy customization
+
+[![CI](https://github.com/beacoder/python-agent-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/beacoder/python-agent-harness/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+</div>
+
+A terminal coding agent that reads your codebase, plans changes, edits files, runs commands, and verifies its work.
+
+`python-agent-harness` is inspired by [gptel-agent-harness](https://github.com/beacoder/gptel-agent-harness) and [opencode](https://github.com/anomalyco/opencode). It brings opencode's prompts and core behaviors—such as `AGENTS.md` discovery, plan/build modes, skills, sub-agents, and todo tracking—into a lightweight Python implementation with only **three runtime dependencies**:
+
+- `rich`
+- `httpx`
+- `prompt_toolkit`
+
+It works with any **OpenAI-compatible API** and is designed to be easy to inspect, customize, and use for everyday software development.
+
+## Demo
+
+![python-agent-harness demo](demo.png)
+
+## Quick start
+
+```sh
+git clone git@github.com:beacoder/python-agent-harness.git
+cd python-agent-harness
+
+make install
+. venv/bin/activate
+
+python-agent-harness config --init
+python-agent-harness run
+```
+
+Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_key`, and `model`.
+
+Optional extras:
+
+```sh
+pip install -e ".[mcp]"   # MCP server integration
+pip install -e ".[dev]"   # development tools
+```
+
+## Features
+
+- **FSM-driven execution** — explicit `WAIT` / `TOOL` / `TRET` / `SUPERVISE` / `DONE` / `ERRS` / `ABRT` states. Completion supervision nudges the model when it stops early, while failed tool calls are sanitized so they never strand the agent. Transient API failures (`429` / `5xx`) retry with exponential backoff and jitter.
+- **Context management** — CJK-aware token estimation, per-model context windows, and automatic compaction at 70% usage.
+- **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (including unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, and `PlanExit`. Synchronous tools execute sequentially; asynchronous tools such as `Bash` and `Agent` can run concurrently while preserving emitted order.
+- **Plan / Build modes** — plan mode is read-only except for the per-session plan file.
+- **Persistent sessions** — sessions are automatically saved after every response to `~/.local/share/python-agent-harness/sessions/`, with LLM-generated titles and support for `/restore --latest` and `/sessions`.
+- **Focused TUI** — a Rich-based interface with a pinned status bar, Todos panel, inline red/green diff rendering for `Edit` and `Write`, and a `prompt_toolkit` editor with history and completion. `Esc+Enter` submits, `Ctrl-D` quits, and `Ctrl-C` cancels without leaving the application.
+- **MCP support** — optional MCP integration through the `[mcp]` extra. MCP tools become ordinary agent tools such as `mcp__<server>__<tool>`. Supports `stdio`, `streamable-http`, and `sse` transports.
+- **Slash commands** — built-in `/init`, `/review`, `/explain`, and other commands, plus custom commands loaded from `prompts/commands/*.md`.
+
+## Inspired by opencode
+
+Most of [opencode](https://github.com/anomalyco/opencode)'s prompts and core behaviors have been ported to this project. The goal is to retain its practical coding-agent workflow while keeping the implementation small, dependency-light, and easy to customize.
+
+### Prompt and behavior mapping
+
+The following opencode prompts have corresponding implementations in `python-agent-harness`:
+
+| opencode | python-agent-harness |
+|---|---|
+| `default.txt` (main agent) | `agent.md` |
+| `plan.txt` / `plan-mode.txt` / `build-switch.txt` | `plan.md` / `plan-mode.md` / `build-switch.md` |
+| `task.txt` (sub-agent) | `subagent.md` + `Agent` tool |
+| `todowrite.txt` / `question.txt` / `skill.txt` | `TodoWrite` / `Question` / `Skill` tools |
+| `read.txt` / `write.txt` / `edit.txt` / `grep.txt` / `glob.txt` | `Read` / `Write` / `Edit` / `Grep` / `Glob` tools |
+| `shell.txt` | `Bash` tool + `agent.md` Git/GitHub guidance |
+| `plan-enter.txt` / `plan-exit.txt` | `PlanExit` tool |
+| `initialize.txt` / `review.txt` / `explain` | `initialize.md` / `review.md` / `commands/explain.md` |
+| compaction / summary / title | `compact.md` / `summary.md` / `title.md` |
+| `AGENTS.md` handling | `prompts.py` (`find_agents_md_files`, `load_context_files`, per-file resolution) |
+
+## Configuration
+
+All LLM settings live in a single JSON configuration file. Environment variables are optional.
+
+```json
+{
+  "llm": {
+    "base_url": "https://api.openai.com/v1",
+    "api_key": "sk-...",
+    "model": "gpt-5-mini",
+    "reasoning_effort": null,
+    "stream": true
+  },
+  "models": {
+    "_comment": "Named LLM profiles for /model switching. Partial settings; unset keys inherit the main llm.",
+    "deepseek": {
+      "base_url": "https://api.deepseek.com/v1",
+      "model": "deepseek-chat"
+    },
+    "qwen": {
+      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      "model": "qwen3.5-coder"
+    }
+  },
+  "subagent_llm": {
+    "profile": null,
+    "base_url": null,
+    "api_key": null,
+    "model": null,
+    "temperature": null,
+    "max_tokens": null,
+    "timeout": null,
+    "reasoning_effort": null,
+    "stream": null
+  },
+  "paths": {
+    "context_path": null,
+    "skill_path": null
+  },
+  "mcp": {
+    "servers": {
+      "example": {
+        "transport": "stdio",
+        "command": "npx",
+        "args": [
+          "-y",
+          "@modelcontextprotocol/server-filesystem",
+          "/tmp"
+        ],
+        "env": [],
+        "parallel": false,
+        "timeout": null,
+        "enabled": false
+      }
+    }
+  }
+}
+```
+
+### Configuration options
+
+- **`llm`** — main LLM configuration. Optional keys include `backend`, `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, and `stream`. Values such as `reasoning_effort` are passed to the API as-is when set. `run --no-stream` overrides `stream`.
+- **`models`** — named LLM profiles for runtime switching with `/model`. A profile is a partial settings dictionary; unset keys inherit from the main `llm`. `default` restores the main LLM configuration.
+- **`subagent_llm`** — LLM configuration for `Agent` tool requests. Unset values inherit from the main `llm`. Set `profile` to reuse a profile from `models`. Precedence is: profile settings > explicit `subagent_llm` settings > main `llm` > environment variables.
+- **`paths.context_path` / `paths.skill_path`** — locations from which to load context files and skills. When unset, the project-local `<project>/contexts` and `<project>/skills` directories are used.
+- **`mcp.servers`** — MCP server configuration. Requires the `[mcp]` extra. Each server supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, and `enabled`.
+- **Configuration precedence** — code defaults < config file < `OPENAI_*` environment variables. Sub-agent settings also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`, `_BACKEND`).
+- **Custom config** — use `--config PATH` or `PYTHON_AGENT_HARNESS_CONFIG`.
+- **LLM logging** — request and response bodies are logged as JSON to `/tmp/python-agent-harness-<date>-<id>.json`. Set `LLM_LOG_DIR` to change the directory. The log path is printed at startup.
+
+## Usage
+
+```sh
+python-agent-harness run [project-dir]
+```
+
+Launches the interactive TUI agent. If `project-dir` is omitted, the current directory is used.
+
+### Slash commands
+
+| Command | Description |
+|---|---|
+| `/plan` / `/build` | Switch between read-only plan mode and build mode |
+| `/init` | Create or update `AGENTS.md` |
+| `/review` | Review uncommitted changes, commits, branches, or pull requests |
+| `/explain [project] [target]` | Explain code |
+| `/compact` | Compact the conversation |
+| `/summary` | Append a conversation summary |
+| `/save` | Save the current session |
+| `/sessions` | List saved sessions |
+| `/restore [path\|title\|--latest\|latest]` | Restore a session; title matching uses substring search |
+| `/clear` | Start a fresh conversation |
+| `/model [name]` | Switch LLM profiles; `default` restores the session's original model |
+| `/exit` | Quit |
+
+Custom commands from `prompts/commands/*.md` are registered as slash commands as well (TUI only).
+
+## Project layout
+
+```text
+python_agent_harness/
+├── agent.py           # Agent FSM core: states, transitions, supervision
+├── tool_runner.py     # Tool-call execution/delivery + history salvage
+├── context_manager.py # Context-ratio tracking + compaction
+├── client.py          # OpenAI-compatible streaming client (httpx)
+├── models.py          # Message / ToolCall / ToolSpec data classes
+├── token_estimator.py # CJK-aware token estimation + calibration
+├── planmode.py        # Plan/build modes + plan-file lifecycle
+├── prompts.py         # Prompt loading + system-prompt assembly
+├── persistence.py     # Session persistence + titles
+├── session.py         # Session wiring hub + MCP lifecycle
+├── subagent.py        # Sub-agent runner + error containment
+├── commands.py        # Init/review/custom command definitions
+├── cli.py             # CLI entry points
+├── tui/               # Rich + prompt_toolkit TUI (package)
+├── diffrender.py      # Unified diff generation + Rich rendering
+├── mcp/               # Optional MCP client
+└── tools/             # Tool implementations + registry
+```
+
+## Development
+
+Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13.
+
+```sh
+make test                           # unit tests
+venv/bin/pip install -e ".[dev]"    # development tools
+venv/bin/ruff check .               # lint
+venv/bin/pyright                    # type checking
+venv/bin/python -m build            # build sdist + wheel
+venv/bin/pip-audit                  # dependency audit
+```
+
+CI blocks on Ruff and Pyright failures.
+
+## Design philosophy
+
+**Keep it intact, not bloated.**
+
+The project aims to provide a capable coding-agent within a lightweight framework.
+
+## Related projects
+
+- [gptel-agent-harness](https://github.com/beacoder/gptel-agent-harness) — the Emacs-based implementation that inspired this project.
+- [opencode](https://github.com/anomalyco/opencode) — the primary source of many prompts and coding-agent behaviors.
+
+## License
+
+MIT

python_agent_harness-1.5.0.dist-info/RECORD

@@ -0,0 +1,61 @@
+python_agent_harness/__init__.py,sha256=hC8AyhcWRemBxbFb9gGCBwwBc45PoR4FtfGk20qhw2o,440
+python_agent_harness/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+python_agent_harness/agent.py,sha256=TuWc5wfK3JgqUXeSVPHw8fsbo1WRfDbQsry8nBMWDqw,30533
+python_agent_harness/cli.py,sha256=mp-cvQh0DVkO-dgEMERkOoLkjkoABWXWykFm_HaTx2g,11120
+python_agent_harness/client.py,sha256=anwHo23zzINLfb9r0WEW8ZDwYMBe48sbEOq3ZRVv1o0,34907
+python_agent_harness/commands.py,sha256=g1fYoybaWlyCH-7n3htgxY6xtMwHP7m7-G0br4Kjkdk,5721
+python_agent_harness/config.py,sha256=BrfZxZKW-WMyj_-_wqaW4LNfAI7vPdZ272lMfyYWQio,17709
+python_agent_harness/context_manager.py,sha256=FyjkIXd7idKQ_yU6neDcsEIRAz_v2ECrcyvxPBgt5iw,4157
+python_agent_harness/diffrender.py,sha256=k7pJzJtn2eT7BZI6i83moVzPKrRXp8Q6XVmF8zJZLRo,2946
+python_agent_harness/models.py,sha256=NZPFdTaAmAN3HjZQnzZ1sqTvzDVhvl-qahYDxz-64TA,5115
+python_agent_harness/persistence.py,sha256=yHUJqy9mWmlzF_efhRosuBuAJNng2lR7Laz2zQuoUqw,10843
+python_agent_harness/planmode.py,sha256=9wrSEg5YtS9II-SOL08XTOEFSiKtdF0fS05JlXxLqM4,3909
+python_agent_harness/prompts.py,sha256=3kZZwQ1tUQ7NiRLryxrOQqgBPaskNPIfKdIMCDjg_N8,18445
+python_agent_harness/session.py,sha256=CFIzws6Upvdw8gHT93a-C5TGh8rFQYtyTugpWjYiT60,34915
+python_agent_harness/subagent.py,sha256=ptiETpsjgVyXybSr9yTHsNHrIx8gy_awrMOWepBwxj4,2292
+python_agent_harness/token_estimator.py,sha256=VRmBrFK9906nmpaLPTqtggZbCGx6AhE_VJpFba9uc5U,4555
+python_agent_harness/tool_runner.py,sha256=f18-g7UKEe_pjdgI3fnhkxj-RnkTeoPiXo0SJpft91Y,10487
+python_agent_harness/mcp/__init__.py,sha256=dlgZRr_pljESu-aJfo3aq_fLDkZN7quwrPUR112Kohw,535
+python_agent_harness/mcp/client.py,sha256=Z738VBsD_-I8bMD24TTEGoWglVkwAtBl6lFDPeNsx1Y,6234
+python_agent_harness/mcp/config.py,sha256=XpeB0AzWTCI6BoDqScsKzjBt5BPHgaCc58WEJfsvPRM,4894
+python_agent_harness/mcp/manager.py,sha256=0s34NfFmfJdVZmIy39fCGtrWbagYfz1CP6yHYgL3lp0,11570
+python_agent_harness/prompts/agent.md,sha256=sP8ZLVR8F5ut5C-vNWfBQL3mULPWFzQ4I8lgo1gaO5g,21061
+python_agent_harness/prompts/build-switch.md,sha256=Xj22FqaFo9-q-V-4aubirPvfUgvaYPeyf3J9Koi6iiU,233
+python_agent_harness/prompts/compact.md,sha256=hz2yNyp-RteD5fUKqDfyPbM3SOhjEoinRLYSx1htXNo,978
+python_agent_harness/prompts/initialize.md,sha256=kgnEjtFqnKXLg38Jgxgnzhhn7B3bM8ahrRl3kypnkyg,3492
+python_agent_harness/prompts/plan-mode.md,sha256=ExEfFuukjzMQiUEYOccLleOO1S5tJDo-Hdi8IC_blow,4551
+python_agent_harness/prompts/plan.md,sha256=NJWArCzBzXOvJssCrbFfoGdzf0s6k3Qtlz_dO8hjf9Y,1479
+python_agent_harness/prompts/review.md,sha256=LU-Pz9sQsL4xPHsBKvaA9Xe_ApZ4W2nePgaunxcU_HI,4535
+python_agent_harness/prompts/subagent.md,sha256=dJ3RYaW2mwpsu6JM1bftxfUHvc-DDkTRviyVqzjACEs,9874
+python_agent_harness/prompts/summary.md,sha256=MHMU60HMOKkIga6fJuBALO7tBOcQRgFEhqmQitRSAjM,648
+python_agent_harness/prompts/task-completion-rules.md,sha256=VrwpiSL98GCYGuph9f2qVs-tFFfLBUUmmq3w_zJEHrE,1437
+python_agent_harness/prompts/title.md,sha256=56aEjroyjyjH6HCHTPBZHk7br5DXYCrY_f6QYBxuZW8,2120
+python_agent_harness/prompts/commands/explain.md,sha256=RMmP9L3TfPpW0dthlGobWbgqBIc7H2LJIMIJT2JDN3Y,539
+python_agent_harness/tools/__init__.py,sha256=CiJMKQoHKeESYId5JdmUPgkfvW8SPxrgV4isBEtnOqo,1142
+python_agent_harness/tools/agent_tool.py,sha256=NX5EIAOp4gxHkN5fs_ARaRRN0PoWwQVQWwUetRgfBMo,3054
+python_agent_harness/tools/base.py,sha256=tQ61t57yX8Iwjv-VkZdO7HZuUUvS6KJa9fj6TSGDYHg,5321
+python_agent_harness/tools/bash.py,sha256=Sco7uQQ2AMKKKKzho7yAxkO3nVY0NCMYQc7Hts7lCuc,11532
+python_agent_harness/tools/edit.py,sha256=wTTgBYYaOT3U1ffV5tMjP8CLwECUZ6tuUBML6OxRnk8,11320
+python_agent_harness/tools/filesystem.py,sha256=KbQtThQWpXuJ31aiGJJYEgCBOTI923VHP2eugVTex2I,6472
+python_agent_harness/tools/glob.py,sha256=dxWdzc30KmXsOhz3TaA2CgXahyq-whYaurOatFp_hVc,6000
+python_agent_harness/tools/grep.py,sha256=mDpAFQKuIKiLN-CuzlLzdenUVJgQx9xyOYi_WyX-260,5112
+python_agent_harness/tools/insert.py,sha256=AXC1S7pcvD0n3cpw9ALO7hLcCSOiIcaqk4rUVQXQ0-0,2027
+python_agent_harness/tools/mcp.py,sha256=v_XMOfxGpaJ3xw3i4j3HOz03qhMluGfLotLZSQPD_Ac,7489
+python_agent_harness/tools/mkdir.py,sha256=OU5YwCd5soNXXqAKEev93NJHRvDwGKEXcQjgsCIuzAQ,914
+python_agent_harness/tools/planexit.py,sha256=ogmoTBBQ0klNe0ktLiVn6dEU4j3J8CdqS7UwvKMZLxY,1935
+python_agent_harness/tools/question.py,sha256=yTvNkCmT3M1kphh4ZX3-Yis9yQnnj314-AF5Xkp2Fr4,2547
+python_agent_harness/tools/read.py,sha256=Mpl0SEeXGYtu-HV3Za5A9OPuGARAYAfjIjrCyu_s0kk,4278
+python_agent_harness/tools/skill.py,sha256=L-3guW86Lo360SmiCT5Z9612z2Kj9UZTHHrO4BAYQMo,1063
+python_agent_harness/tools/todo.py,sha256=xmQwcF_LhP9q9MAGVMgL8WmdqKyRLMpCcmv1chDAGTo,1988
+python_agent_harness/tools/write.py,sha256=nhhc-he1pPwJGU7ltJCZ2lcCTJwQbV4s7XlMjPOvozM,1995
+python_agent_harness/tui/__init__.py,sha256=SD8kGsTgroNz2D9gbSG_FGA-f6fsLCwBtQZeTMHiLq8,1451
+python_agent_harness/tui/commands.py,sha256=IB8wHu8rGnVFbJXtpHqW5unmwY45T-4O47JRWsszEtU,27470
+python_agent_harness/tui/core.py,sha256=tajeohfdd_2zyvLZKgHb4pSSwBdSZrZMsFYspLgWaRo,17006
+python_agent_harness/tui/input.py,sha256=XlOjJv_gvJOV4oK-CIv7T0uT12PWoK77Wg-futEYcw0,14491
+python_agent_harness/tui/render.py,sha256=9YbybpcAzhtWKaXZqtxbvjW2IkXiocHTCpkkwaCSWL0,22705
+python_agent_harness-1.5.0.dist-info/licenses/LICENSE,sha256=TiuVaM7FrBunbEua5l_01IT-mwccvS51CLrDLuKW96g,1066
+python_agent_harness-1.5.0.dist-info/METADATA,sha256=XSq4bipgaiKBqtGBmdIjN4KqEfM78j05KvVtRSjFDgQ,11418
+python_agent_harness-1.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_agent_harness-1.5.0.dist-info/entry_points.txt,sha256=3PV6goY2PUr9LjVRhDzCEE5fFCJGavuVOrqOTWNnmHE,71
+python_agent_harness-1.5.0.dist-info/top_level.txt,sha256=MQXIVidl0IBeeKnLHhy1JfzXNQMBKAehpdkqHVvIfwM,21
+python_agent_harness-1.5.0.dist-info/RECORD,,

python_agent_harness-1.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_agent_harness-1.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+python-agent-harness = python_agent_harness.cli:main

python_agent_harness-1.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 陈虎明
+
+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.

python_agent_harness-1.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+python_agent_harness