python-agent-harness 1.5.6.0__tar.gz → 1.5.6.2__tar.gz

python_agent_harness-1.5.6.2/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: python-agent-harness
+Version: 1.5.6.2
+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.2/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.0 → python_agent_harness-1.5.6.2}/pyproject.toml

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

{python_agent_harness-1.5.6.0 → python_agent_harness-1.5.6.2}/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.0"
+__version__ = "1.5.6.2"
 
 __all__ = [
     "Client",

{python_agent_harness-1.5.6.0 → python_agent_harness-1.5.6.2}/python_agent_harness/core/agent.py

@@ -43,7 +43,7 @@ from ..llm.client import LLMClient
 from ..session import config
 from ..tools.base import PendingToolResult
 from .context_manager import ContextManager
-from .models import Message, ToolCall
+from .models import Message, ToolCall, display_args
 from .token_estimator import context_window_for, estimate_payload_tokens
 from .tool_runner import (
     NIL_RESULT_PLACEHOLDER,  # noqa: F401  (re-exported for backward compat)
@@ -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
@@ -150,6 +164,16 @@ class AgentLoop:
         # from cancellation: a cancelled run with no successor still
         # owns the session and may salvage its partial history.
         self._run_gen = session.run_generation
+        # Tag THIS thread (the one that will drive the loop — the run
+        # worker, or a sub-agent's own thread) with the run it belongs
+        # to, so the session can drop events from a superseded run
+        # instead of attributing them to the current one.  A detached
+        # sub-agent thread can outlive its run; see
+        # `Session._emit_superseded`.  Suppressed for session doubles
+        # that predate the hook.
+        mark = getattr(session, "mark_emit_generation", None)
+        if callable(mark):
+            mark(self._run_gen)
 
     def _is_cancelled(self) -> bool:
         """Whether THIS run must stop (cancelled or superseded).
@@ -205,14 +229,19 @@ class AgentLoop:
             if self.top_level:
                 self.error = "Error: round budget exhausted before the run finished"
                 self.info["error"] = self.error
-                self.session.notify("error", self.error)
+                # The code is assigned HERE, where the outcome is known.
+                # A driver reading the result line gets "budget" because
+                # the budget check said so — not because a downstream
+                # classifier matched words in this sentence, which would
+                # silently degrade to "unknown" if it were reworded.
+                self.session.notify("error", {"code": "budget", "message": self.error})
             else:
                 self.info["budget"] = True
             return True
         if self._deadline_exceeded():
             self.error = f"Error: {_deadline_message(self.timeout)}"
             self.info["error"] = self.error
-            self.session.notify("error", self.error)
+            self.session.notify("error", {"code": "timeout", "message": self.error})
             return True
         return False
 
@@ -497,14 +526,43 @@ 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:
-            if not self._is_cancelled() and session.on_delta is not None:
-                session.on_delta(text)
+            # Snapshot: a host that swaps views per run unwires
+            # on_delta at run teardown, so re-reading it after the
+            # None-test could call None (see Session.notify).
+            on_delta = session.on_delta
+            if not self._is_cancelled() and on_delta is not None:
+                on_delta(text)
 
         try:
             # sub-agents are one-shot tasks: they must not see (or
@@ -581,6 +639,20 @@ class AgentLoop:
                 totals["input"] = totals.get("input", 0) + usage.input_tokens
                 totals["output"] = totals.get("output", 0) + usage.output_tokens
                 totals["rounds"] = totals.get("rounds", 0) + 1
+                snapshot = {
+                    "input": totals["input"],
+                    "output": totals["output"],
+                    "rounds": totals["rounds"],
+                }
+            # Publish the running total so a host can meter DURING the
+            # run instead of only billing the terminal result line.
+            # Without this a run that outlives its user's allowance
+            # cannot be stopped until it finishes on its own — the host
+            # can now cancel mid-run.  Emitted from the top-level loop
+            # only (the snapshot already includes sub-agent tokens, so
+            # per-sub-agent lines would add noise, not information).
+            if self.top_level:
+                session.notify("usage", snapshot)
 
         # persist the assistant response in the conversation history
         # (text and/or tool calls) so later turns and the UI see it;
@@ -621,6 +693,15 @@ class AgentLoop:
             self.session.last_messages = list(self.messages)
             names = [tc.name for tc in self.pending]
             self.session.notify("tool_start", names)
+            # Additive companion event: the same round, but with each
+            # call's arguments so a hosting UI can show WHAT is about to
+            # run ("Bash(command='ls -la')"), which bare names cannot
+            # convey.  Kept separate from tool_start so the payload shape
+            # of the documented protocol stays backward compatible.
+            self.session.notify(
+                "tool_calls",
+                [{"name": tc.name, "args": display_args(tc.arguments)} for tc in self.pending],
+            )
         self._execute_pending()
 
     def _handle_tret(self) -> None:

{python_agent_harness-1.5.6.0 → python_agent_harness-1.5.6.2}/python_agent_harness/core/models.py

@@ -80,6 +80,39 @@ class ToolCall:
     elapsed: float | None = None  # execution wall-time in seconds (TUI display)
 
 
+def arg_repr(value: Any, limit: int = 100) -> str:
+    """repr() of a tool-call argument, truncated to LIMIT chars total.
+
+    Long values (a long Bash command, a big JSON payload) are cut with
+    an ellipsis instead of being dropped from the label entirely.
+    """
+    r = repr(value)
+    if len(r) <= limit:
+        return r
+    return r[: limit - 1] + "…"
+
+
+def display_args(arguments: dict[str, Any] | str, limit: int = 100) -> dict[str, str]:
+    """Tool-call arguments as short display strings, keyed by name.
+
+    ``arguments`` arrives either already decoded or as the raw JSON
+    string the model emitted (unparseable when the model truncated it).
+    ``content`` is skipped: a Write/Edit payload is far too large for a
+    one-line label, and it is shown as a diff instead.
+
+    Values are truncated, so the result is a display artifact -- never
+    the data a tool is executed with.
+    """
+    if isinstance(arguments, str):
+        try:
+            arguments = json.loads(arguments)
+        except (json.JSONDecodeError, ValueError):
+            return {}
+    if not isinstance(arguments, dict):
+        return {}
+    return {k: arg_repr(v, limit) for k, v in arguments.items() if k != "content"}
+
+
 @dataclass
 class Message:
     """One conversation message in OpenAI-compatible format.