python-agent-harness 1.5.6.1__tar.gz → 1.5.6.3__tar.gz

python_agent_harness-1.5.6.3/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: python-agent-harness
+Version: 1.5.6.3
+Summary: A lightweight, hackable mini-OpenCode written in Python.
+Author-email: Huming Chen <chenhuming@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/beacoder/python-agent-harness
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: certifi>=2024.0
+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, hackable mini-OpenCode written in Python.**  
+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)
+[![PyPI](https://img.shields.io/pypi/v/python-agent-harness.svg)](https://pypi.org/project/python-agent-harness/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/python-agent-harness?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/python-agent-harness)
+[![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.
+
+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 — `AGENTS.md` discovery, plan/build modes, skills, sub-agents, todo tracking — into a lightweight Python implementation with only **three runtime dependencies**: `rich`, `httpx`, `prompt_toolkit`.
+
+Works with any **OpenAI-compatible API**.
+
+## Demo
+
+![python-agent-harness demo](https://raw.githubusercontent.com/beacoder/python-agent-harness/main/demo.png)
+
+## Quick start
+
+```sh
+pip install python-agent-harness          # or: pip install -e ".[dev]" from source
+python-agent-harness config --init
+python-agent-harness run
+```
+
+Optional extras: `[mcp]` for MCP server integration, `[dev]` for development tools.
+
+Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_key`, and `model`.
+
+## Features
+
+- **FSM-driven execution** — explicit `WAIT` / `TOOL` / `TRET` / `SUPERVISE` / `DONE` / `ERRS` / `ABRT` states. Completion supervision nudges the model when it stops early; failed tool calls are sanitized. Transient API failures (`429` / `5xx`) retry with exponential backoff. Auth-expired codes (configurable via `AUTH_REFRESH_STATUS_CODES` in `config.py`; defaults to `[401, 502]`) trigger automatic API key re-read from config/env.
+- **Context management** — CJK-aware token estimation, per-model context windows, automatic compaction at 70% usage.
+- **Image & text attachments** — attach with `@path` (e.g. `@screenshot.png`, `@README.md`): images (PNG/JPEG/GIF/WebP, up to 20 MB) become multimodal `image_url` parts; text files are inlined. Web URLs supported for images.
+- **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (incl. unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, `LSP`, `PlanExit`. Read-only tool rounds (`Read`, `Glob`, `Grep`, `Skill`, `LSP`) dispatch concurrently; async tools (`Bash`, `Agent`) can also run concurrently. Results always delivered in emitted order.
+- **Plan / Build modes** — plan mode is read-only except for the per-session plan file.
+- **Persistent sessions** — auto-saved after every response to `~/.local/share/python-agent-harness/sessions/`, with LLM-generated titles and `/restore --latest` / `/sessions`.
+- **Focused TUI** — Rich-based with pinned status bar, Todos panel, inline diff rendering, and a `prompt_toolkit` editor with history and completion. `Esc+Enter` submits, `Ctrl-D` quits, `Ctrl-C` cancels.
+- **MCP support** — optional via `[mcp]` extra. MCP tools become ordinary agent tools (`mcp__<server>__<tool>`). Supports `stdio`, `streamable-http`, and `sse` transports.
+- **Slash commands** — built-in `/init`, `/review`, `/explain`, etc., plus custom commands from `prompts/commands/*.md`.
+- **Custom agents** — switch the main agent's system prompt at runtime with `/agent`. Agent files live in `prompts/agents/*.md` and support `name:` and `exclude_tools:` frontmatter.
+- **Embeddable runtime boundaries** — `headless --json` for one-shot CI/scripting; `serve` for hosting apps (resident process, bidirectional protocol: multi-turn memory, mid-run Q&A, protocol-level cancel).
+
+## Usage
+
+### TUI mode
+
+```sh
+python-agent-harness run [--project DIR]
+```
+
+### Headless mode
+
+```sh
+python-agent-harness headless [prompt] [--project DIR] [--restore [SPEC]] [--model NAME] [--json]
+```
+
+Runs a single prompt without the TUI — for CI, scripting, and piping. The assistant's answer goes to stdout; tool/status events go to stderr. Interactive prompts are auto-answered (`confirm` → yes, `ask` → "Unanswered").
+
+- Prompt is a positional argument; when omitted, read from stdin.
+- `--restore` continues a saved session. Bare `--restore` uses the most recent; a SPEC may be a file path or title substring.
+- `--model NAME` selects a profile from the `models` config section, or a raw model name on the configured endpoint.
+- `--json` emits JSON lines on stdout: `start`, `delta`, `notify`, `log`, and a final `result` (with structured `errors`). Each line carries `protocol` (wire schema version) and `seq` (monotonic counter). Exit code 0 on success, 1 on error.
+
+### Serve mode
+
+```sh
+python-agent-harness serve [--project DIR] [--answer-timeout SECONDS] [--max-rounds N] [--timeout SECONDS]
+```
+
+A persistent, bidirectional runtime for hosting applications. Keeps the `Controller`/`Session` resident so the host can submit multiple prompts, answer mid-run questions, and cancel runs via protocol messages. See [docs/serve-protocol.md](docs/serve-protocol.md) for the full protocol specification.
+
+### 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 (substring search) |
+| `/clear` | Start a fresh conversation |
+| `/model [name]` | Switch LLM profiles; `default` restores original |
+| `/agent [name]` | Switch agent prompt; `default` restores built-in |
+| `/help` | List available commands |
+| `/exit` | Quit |
+
+Custom commands from `prompts/commands/*.md` are also registered (TUI only).
+
+### Custom agents
+
+Agent files are markdown (`.md`) in `prompts/agents/`. Each becomes a switchable profile via `/agent`. Optional YAML frontmatter:
+
+- `name:` — override the agent name (defaults to file stem)
+- `exclude_tools:` — list of tool names to hide. Matches by exact name, glob (`mcp__git__*`), or `__`-delimited prefix (`mcp__git` hides `mcp__git__list_repos` but `Write` does NOT hide `TodoWrite`).
+
+**Commands vs Agents:** Commands (`/review`) are one-shot with a hardcoded kickoff and reset after run. Agents (`/agent reviewer`) persist until the next `/agent`, let the user type their own prompt, and stay active after `Ctrl-C`.
+
+## Configuration
+
+All LLM settings live in `~/.config/python-agent-harness/config.json`. 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,
+    "supports_image_input": false
+  },
+  "models": {
+    "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" }
+  },
+  "context_windows": {
+    "deepseek-v4": 1000000
+  },
+  "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
+      }
+    }
+  }
+}
+```
+
+### Options
+
+- **`llm`** — main LLM config. Optional keys: `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, `stream`, `supports_image_input`. `run --no-stream` overrides `stream`. `supports_image_input` (default `false`) controls whether `@path` images are sent or stripped.
+- **`models`** — named LLM profiles for `/model` switching. Partial settings; unset keys inherit from `llm`. `default` restores the main config.
+- **`context_windows`** — per-model context-window overrides (tokens). Keys are model names or substrings; first match wins. Overrides `CONTEXT_WINDOWS` in `config.py`.
+- **`subagent_llm`** — LLM config for `Agent` tool. Unset values inherit from `llm`. Set `profile` to reuse a `models` entry. Precedence: profile > `subagent_llm` > `llm` > env vars.
+- **`default_agent`** — agent name to use at session start (must exist in `prompts/agents/`). `null` = built-in default.
+- **`paths.context_path` / `paths.skill_path`** — locations for context files and skills. Default: project-local `contexts/` and `skills/`.
+- **`lsp.servers`** — per-extension LSP server overrides for the `LSP` tool. Keys are extensions (`.py`, `.cpp`); each has `command` (argv) and optional `language_id`. Layers on top of `DEFAULT_SERVERS` in `lsp/manager.py`.
+- **`mcp.servers`** — MCP server config (requires `[mcp]` extra). Each supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, `enabled`.
+- **`headless` / `serve`** — optional budget limits: `max_rounds` (LLM rounds) and `timeout` (wall-clock seconds). `--max-rounds` / `--timeout` override per call; `<= 0` or `null` disables. Unset = unlimited.
+- **Precedence** — code defaults < config file < `OPENAI_*` env vars. Sub-agents also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`).
+- **Custom config** — `--config PATH` or `PYTHON_AGENT_HARNESS_CONFIG` env var.
+- **LLM logging** — request/response bodies logged as JSON to `/tmp/python-agent-harness-<date>-<id>.json`. Set `LLM_LOG_DIR` to change. Path printed at startup.
+
+## Inspired by opencode
+
+Most of [opencode](https://github.com/anomalyco/opencode)'s prompts and core behaviors have been ported. The goal: retain its practical coding-agent workflow while keeping the implementation small and easy to customize.
+
+| 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`) |
+
+## Development
+
+Requires Python ≥ 3.11. CI runs against 3.11, 3.12, and 3.13 on Linux and macOS.
+
+```sh
+make test                           # unit tests
+venv/bin/pip install -e ".[dev]"    # development tools
+venv/bin/ruff check .               # lint
+venv/bin/ruff format --check .      # formatting (CI blocks on this)
+venv/bin/pyright                    # type checking
+venv/bin/python -m build            # build sdist + wheel
+venv/bin/pip-audit                  # dependency audit
+```
+
+## 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.6.3/README.md

@@ -0,0 +1,205 @@
+<div align="center">
+
+# python-agent-harness
+
+**A lightweight, hackable mini-OpenCode written in Python.**  
+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)
+[![PyPI](https://img.shields.io/pypi/v/python-agent-harness.svg)](https://pypi.org/project/python-agent-harness/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/python-agent-harness?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/python-agent-harness)
+[![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.
+
+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 — `AGENTS.md` discovery, plan/build modes, skills, sub-agents, todo tracking — into a lightweight Python implementation with only **three runtime dependencies**: `rich`, `httpx`, `prompt_toolkit`.
+
+Works with any **OpenAI-compatible API**.
+
+## Demo
+
+![python-agent-harness demo](https://raw.githubusercontent.com/beacoder/python-agent-harness/main/demo.png)
+
+## Quick start
+
+```sh
+pip install python-agent-harness          # or: pip install -e ".[dev]" from source
+python-agent-harness config --init
+python-agent-harness run
+```
+
+Optional extras: `[mcp]` for MCP server integration, `[dev]` for development tools.
+
+Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_key`, and `model`.
+
+## Features
+
+- **FSM-driven execution** — explicit `WAIT` / `TOOL` / `TRET` / `SUPERVISE` / `DONE` / `ERRS` / `ABRT` states. Completion supervision nudges the model when it stops early; failed tool calls are sanitized. Transient API failures (`429` / `5xx`) retry with exponential backoff. Auth-expired codes (configurable via `AUTH_REFRESH_STATUS_CODES` in `config.py`; defaults to `[401, 502]`) trigger automatic API key re-read from config/env.
+- **Context management** — CJK-aware token estimation, per-model context windows, automatic compaction at 70% usage.
+- **Image & text attachments** — attach with `@path` (e.g. `@screenshot.png`, `@README.md`): images (PNG/JPEG/GIF/WebP, up to 20 MB) become multimodal `image_url` parts; text files are inlined. Web URLs supported for images.
+- **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (incl. unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, `LSP`, `PlanExit`. Read-only tool rounds (`Read`, `Glob`, `Grep`, `Skill`, `LSP`) dispatch concurrently; async tools (`Bash`, `Agent`) can also run concurrently. Results always delivered in emitted order.
+- **Plan / Build modes** — plan mode is read-only except for the per-session plan file.
+- **Persistent sessions** — auto-saved after every response to `~/.local/share/python-agent-harness/sessions/`, with LLM-generated titles and `/restore --latest` / `/sessions`.
+- **Focused TUI** — Rich-based with pinned status bar, Todos panel, inline diff rendering, and a `prompt_toolkit` editor with history and completion. `Esc+Enter` submits, `Ctrl-D` quits, `Ctrl-C` cancels.
+- **MCP support** — optional via `[mcp]` extra. MCP tools become ordinary agent tools (`mcp__<server>__<tool>`). Supports `stdio`, `streamable-http`, and `sse` transports.
+- **Slash commands** — built-in `/init`, `/review`, `/explain`, etc., plus custom commands from `prompts/commands/*.md`.
+- **Custom agents** — switch the main agent's system prompt at runtime with `/agent`. Agent files live in `prompts/agents/*.md` and support `name:` and `exclude_tools:` frontmatter.
+- **Embeddable runtime boundaries** — `headless --json` for one-shot CI/scripting; `serve` for hosting apps (resident process, bidirectional protocol: multi-turn memory, mid-run Q&A, protocol-level cancel).
+
+## Usage
+
+### TUI mode
+
+```sh
+python-agent-harness run [--project DIR]
+```
+
+### Headless mode
+
+```sh
+python-agent-harness headless [prompt] [--project DIR] [--restore [SPEC]] [--model NAME] [--json]
+```
+
+Runs a single prompt without the TUI — for CI, scripting, and piping. The assistant's answer goes to stdout; tool/status events go to stderr. Interactive prompts are auto-answered (`confirm` → yes, `ask` → "Unanswered").
+
+- Prompt is a positional argument; when omitted, read from stdin.
+- `--restore` continues a saved session. Bare `--restore` uses the most recent; a SPEC may be a file path or title substring.
+- `--model NAME` selects a profile from the `models` config section, or a raw model name on the configured endpoint.
+- `--json` emits JSON lines on stdout: `start`, `delta`, `notify`, `log`, and a final `result` (with structured `errors`). Each line carries `protocol` (wire schema version) and `seq` (monotonic counter). Exit code 0 on success, 1 on error.
+
+### Serve mode
+
+```sh
+python-agent-harness serve [--project DIR] [--answer-timeout SECONDS] [--max-rounds N] [--timeout SECONDS]
+```
+
+A persistent, bidirectional runtime for hosting applications. Keeps the `Controller`/`Session` resident so the host can submit multiple prompts, answer mid-run questions, and cancel runs via protocol messages. See [docs/serve-protocol.md](docs/serve-protocol.md) for the full protocol specification.
+
+### 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 (substring search) |
+| `/clear` | Start a fresh conversation |
+| `/model [name]` | Switch LLM profiles; `default` restores original |
+| `/agent [name]` | Switch agent prompt; `default` restores built-in |
+| `/help` | List available commands |
+| `/exit` | Quit |
+
+Custom commands from `prompts/commands/*.md` are also registered (TUI only).
+
+### Custom agents
+
+Agent files are markdown (`.md`) in `prompts/agents/`. Each becomes a switchable profile via `/agent`. Optional YAML frontmatter:
+
+- `name:` — override the agent name (defaults to file stem)
+- `exclude_tools:` — list of tool names to hide. Matches by exact name, glob (`mcp__git__*`), or `__`-delimited prefix (`mcp__git` hides `mcp__git__list_repos` but `Write` does NOT hide `TodoWrite`).
+
+**Commands vs Agents:** Commands (`/review`) are one-shot with a hardcoded kickoff and reset after run. Agents (`/agent reviewer`) persist until the next `/agent`, let the user type their own prompt, and stay active after `Ctrl-C`.
+
+## Configuration
+
+All LLM settings live in `~/.config/python-agent-harness/config.json`. 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,
+    "supports_image_input": false
+  },
+  "models": {
+    "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" }
+  },
+  "context_windows": {
+    "deepseek-v4": 1000000
+  },
+  "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
+      }
+    }
+  }
+}
+```
+
+### Options
+
+- **`llm`** — main LLM config. Optional keys: `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, `stream`, `supports_image_input`. `run --no-stream` overrides `stream`. `supports_image_input` (default `false`) controls whether `@path` images are sent or stripped.
+- **`models`** — named LLM profiles for `/model` switching. Partial settings; unset keys inherit from `llm`. `default` restores the main config.
+- **`context_windows`** — per-model context-window overrides (tokens). Keys are model names or substrings; first match wins. Overrides `CONTEXT_WINDOWS` in `config.py`.
+- **`subagent_llm`** — LLM config for `Agent` tool. Unset values inherit from `llm`. Set `profile` to reuse a `models` entry. Precedence: profile > `subagent_llm` > `llm` > env vars.
+- **`default_agent`** — agent name to use at session start (must exist in `prompts/agents/`). `null` = built-in default.
+- **`paths.context_path` / `paths.skill_path`** — locations for context files and skills. Default: project-local `contexts/` and `skills/`.
+- **`lsp.servers`** — per-extension LSP server overrides for the `LSP` tool. Keys are extensions (`.py`, `.cpp`); each has `command` (argv) and optional `language_id`. Layers on top of `DEFAULT_SERVERS` in `lsp/manager.py`.
+- **`mcp.servers`** — MCP server config (requires `[mcp]` extra). Each supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, `enabled`.
+- **`headless` / `serve`** — optional budget limits: `max_rounds` (LLM rounds) and `timeout` (wall-clock seconds). `--max-rounds` / `--timeout` override per call; `<= 0` or `null` disables. Unset = unlimited.
+- **Precedence** — code defaults < config file < `OPENAI_*` env vars. Sub-agents also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`).
+- **Custom config** — `--config PATH` or `PYTHON_AGENT_HARNESS_CONFIG` env var.
+- **LLM logging** — request/response bodies logged as JSON to `/tmp/python-agent-harness-<date>-<id>.json`. Set `LLM_LOG_DIR` to change. Path printed at startup.
+
+## Inspired by opencode
+
+Most of [opencode](https://github.com/anomalyco/opencode)'s prompts and core behaviors have been ported. The goal: retain its practical coding-agent workflow while keeping the implementation small and easy to customize.
+
+| 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`) |
+
+## Development
+
+Requires Python ≥ 3.11. CI runs against 3.11, 3.12, and 3.13 on Linux and macOS.
+
+```sh
+make test                           # unit tests
+venv/bin/pip install -e ".[dev]"    # development tools
+venv/bin/ruff check .               # lint
+venv/bin/ruff format --check .      # formatting (CI blocks on this)
+venv/bin/pyright                    # type checking
+venv/bin/python -m build            # build sdist + wheel
+venv/bin/pip-audit                  # dependency audit
+```
+
+## 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.6.1 → python_agent_harness-1.5.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-agent-harness"
-version = "1.5.6.1"
+version = "1.5.6.3"
 description = "A lightweight, hackable mini-OpenCode written in Python."
 authors = [
     {name = "Huming Chen", email = "chenhuming@gmail.com"}

{python_agent_harness-1.5.6.1 → python_agent_harness-1.5.6.3}/python_agent_harness/__init__.py

@@ -8,7 +8,7 @@ from .mcp.config import MCPConfig, MCPServerConfig
 from .mcp.manager import MCPManager
 from .session.session import Session
 
-__version__ = "1.5.6.1"
+__version__ = "1.5.6.3"
 
 __all__ = [
     "Client",

{python_agent_harness-1.5.6.1 → python_agent_harness-1.5.6.3}/python_agent_harness/core/agent.py

@@ -137,6 +137,20 @@ class AgentLoop:
         self._local = threading.local()
         self.terminal_text: str | None = None
         self.result: str | None = None
+        # True right after an auto-compaction: the next WAIT must send
+        # the request instead of compacting again.  Compaction keeps
+        # every user prompt verbatim, so when the irreducible part (the
+        # prompts, the system prompt, the tool specs) alone exceeds
+        # CONTEXT_TRIGGER, re-checking the ratio would compact forever
+        # -- one paid summary request per iteration.
+        self._just_compacted = False
+        # The context ratio measured right after a compaction that could
+        # NOT bring it below the trigger (None otherwise).  While set,
+        # compacting again only pays off once the conversation has grown
+        # well past that floor; without it every tool round would be
+        # compacted again -- doubling the requests and summarizing each
+        # fresh tool result away before the model ever saw it.
+        self._compaction_floor: float | None = None
         # Cancellation identity for this run: cancel() bumps the session
         # generation, so a stale worker from a cancelled run stays
         # cancelled even after the next run clears the shared event (and
@@ -512,10 +526,35 @@ class AgentLoop:
             # so their ratio/usage would skew the parent's
             self._update_context_ratio()
             if self._need_compaction():
-                session.log(f"compacting context {session.context_ratio:.1%}")
-                if self.compact():
-                    self.info["compacted"] = True
-                    return
+                ratio = session.context_ratio
+                floor = self._compaction_floor
+                if self._just_compacted:
+                    # Still above the trigger right after compacting:
+                    # what is left is (mostly) irreducible.  Send the
+                    # request -- it either fits, or fails with a
+                    # context-length error (ERRS) instead of looping --
+                    # and remember the floor so later rounds do not
+                    # compact again for nothing.
+                    self._compaction_floor = ratio
+                    session.log(
+                        f"context {ratio:.1%} still above the compaction "
+                        "trigger after compacting; sending anyway"
+                    )
+                elif floor is not None and ratio <= floor + max(0.0, 1.0 - floor) / 2:
+                    # Not yet grown by half the remaining headroom over
+                    # the post-compaction floor (any growth at all once
+                    # the floor is past the window): compacting now
+                    # could only reclaim the latest rounds' output.
+                    pass
+                else:
+                    session.log(f"compacting context {ratio:.1%}")
+                    if self.compact():
+                        self._just_compacted = True
+                        self.info["compacted"] = True
+                        return
+            else:
+                self._compaction_floor = None
+            self._just_compacted = False
 
         def safe_delta(text: str) -> None:
             # Snapshot: a host that swaps views per run unwires

{python_agent_harness-1.5.6.1 → python_agent_harness-1.5.6.3}/python_agent_harness/core/models.py

@@ -5,9 +5,30 @@ from __future__ import annotations
 import base64
 import enum
 import json
+import re
 from dataclasses import dataclass, field
 from typing import Any, Union
 
+# Lone surrogates (\ud800-\udfff) reach a str when a file is decoded with
+# errors="surrogateescape" — which every tool deliberately does, so a
+# non-UTF-8 source file round-trips instead of becoming U+FFFD.  Such a
+# string cannot be encoded to UTF-8, so anything that leaves the process
+# (a JSON request body, a terminal write) must replace them first.
+_SURROGATE_RE = re.compile(r"[\ud800-\udfff]")
+
+
+def api_safe(text: str) -> str:
+    """TEXT with lone surrogates replaced by U+FFFD, safe to serialize.
+
+    The tools read files with ``errors="surrogateescape"``, so a
+    conversation can carry lone surrogates from a non-UTF-8 (Latin-1,
+    GBK, ...) source.  A request body containing one cannot be encoded
+    to UTF-8 — ``httpx`` raised ``UnicodeEncodeError`` — so they are
+    replaced at the OUTBOUND boundary only: the stored history, the
+    session file and the file on disk keep the exact bytes.
+    """
+    return _SURROGATE_RE.sub("\ufffd", text)
+
 
 class AgentMode(enum.Enum):
     BUILD = "build"
@@ -136,7 +157,10 @@ class Message:
     def to_api(self) -> dict[str, Any]:
         d: dict[str, Any] = {"role": self.role}
         if self.content is not None:
-            d["content"] = self._api_content()
+            content = self._api_content()
+            # outbound boundary: a lone surrogate cannot be encoded into
+            # the JSON body (see api_safe)
+            d["content"] = api_safe(content) if isinstance(content, str) else content
         if self.tool_calls:
             d["tool_calls"] = [
                 {
@@ -144,9 +168,13 @@ class Message:
                     "type": "function",
                     "function": {
                         "name": tc.name,
-                        "arguments": tc.arguments
-                        if isinstance(tc.arguments, str)
-                        else json.dumps(tc.arguments, ensure_ascii=False),
+                        # ensure_ascii=False keeps non-ASCII readable;
+                        # api_safe then removes the unencodable surrogates
+                        "arguments": api_safe(
+                            tc.arguments
+                            if isinstance(tc.arguments, str)
+                            else json.dumps(tc.arguments, ensure_ascii=False)
+                        ),
                     },
                 }
                 for tc in self.tool_calls
@@ -188,7 +216,11 @@ class Message:
     @staticmethod
     def _part_to_api(part: ContentPart) -> Any:
         """Serialize one content part to its provider-specific dict."""
-        if isinstance(part, (TextPart, ImagePart)):
+        if isinstance(part, TextPart):
+            # text parts are a second carrier of file content into the
+            # payload, so they need the same outbound treatment
+            return {"type": "text", "text": api_safe(part.text)}
+        if isinstance(part, ImagePart):
             return part.to_api()
         return part
 

{python_agent_harness-1.5.6.1 → python_agent_harness-1.5.6.3}/python_agent_harness/core/tool_runner.py

@@ -76,8 +76,18 @@ class ToolRunner:
         if isinstance(args, str):
             try:
                 args = json.loads(args)
-            except json.JSONDecodeError:
-                args = {}
+            except json.JSONDecodeError as e:
+                # Do NOT fall back to {}: the required-argument check
+                # below would then report "missing required argument(s)"
+                # for arguments the model DID send -- typically a large
+                # Write/Edit cut off by max_tokens -- and the model tends
+                # to retry the identical oversized call.
+                return (
+                    f"Error: {call.name} arguments are not valid JSON ({e.msg} at char "
+                    f"{e.pos} of {len(args)}). If the arguments are large (e.g. a whole "
+                    "file), the response was probably truncated by the output token "
+                    "limit: split the change into smaller calls."
+                )
         if not isinstance(args, dict):
             args = {}
         # Validate required parameters from the tool schema