python-agent-harness 1.5.0__tar.gz

python_agent_harness-1.5.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,230 @@
+<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/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-agent-harness"
+version = "1.5.0"
+description = "Python agent execution harness: agent loop, tools, plan/build modes, sessions"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "rich>=13.0",
+    "httpx>=0.27",
+    "prompt_toolkit>=3.0",
+]
+
+[project.optional-dependencies]
+# MCP (Model Context Protocol) client support: exposes MCP server tools to
+# the agent as namespaced mcp__<server>__<tool> tools.  Install with:
+#   pip install -e ".[mcp]"
+# The SDK is NOT a core dependency: the harness works without it, and the
+# mcp/ modules degrade gracefully (MCPUnavailableError) when it is absent.
+mcp = [
+    "mcp>=2.0,<3",
+]
+
+# Tooling used by CI (lint + type check + wheel build + coverage + audit).
+# Install with:  pip install -e ".[dev]"
+# The mcp extra is included so CI's type-check/lint jobs can resolve the
+# optional SDK imports in python_agent_harness/mcp/.
+dev = [
+    "ruff>=0.6",
+    "pyright>=1.1.380",
+    "build>=1.2",
+    "coverage[toml]>=7.0",
+    "pip-audit>=2.7",
+    "mcp>=2.0,<3",
+]
+
+[project.scripts]
+python-agent-harness = "python_agent_harness.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["python_agent_harness*"]
+
+[tool.setuptools.package-data]
+python_agent_harness = ["prompts/*.md", "prompts/commands/*.md"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+# Core pyflakes (F) + pycodestyle error (E), plus import sorting (I),
+# bugbears (B), pyupgrade (UP) and simplify (SIM).  The tree is clean
+# under this set (CI blocks on it).
+select = ["E", "F", "I", "B", "UP", "SIM"]
+# E501 (line-too-long) is left to the formatter.
+ignore = ["E501"]
+
+[tool.pyright]
+include = ["python_agent_harness"]
+pythonVersion = "3.11"
+# "basic" surfaces the real Optional-access issues without the full strict
+# firehose. The tree is clean under this mode and the CI type-check job
+# blocks on it.
+typeCheckingMode = "basic"
+
+[tool.coverage.run]
+source = ["python_agent_harness"]
+branch = true
+# The console/TUI entry points aren't exercised by unittest; omit the ones
+# that would otherwise drag the number down without adding signal.
+omit = ["python_agent_harness/__main__.py"]
+
+[tool.coverage.report]
+show_missing = true
+# Current line + branch coverage is ~98%. Gate at 90 to leave headroom for
+# small changes while still catching real regressions. Raise as coverage grows.
+fail_under = 90

python_agent_harness-1.5.0/python_agent_harness/__init__.py

@@ -0,0 +1,20 @@
+"""python-agent-harness: a Python port of the gptel-agent-harness."""
+
+from .mcp.config import MCPConfig, MCPServerConfig
+from .mcp.manager import MCPManager
+from .models import AgentMode, Message, ToolCall, ToolSpec
+from .session import Session
+
+__version__ = "1.5.0"
+
+__all__ = [
+    "Session",
+    "AgentMode",
+    "MCPConfig",
+    "MCPManager",
+    "MCPServerConfig",
+    "Message",
+    "ToolCall",
+    "ToolSpec",
+    "__version__",
+]

python_agent_harness-1.5.0/python_agent_harness/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())