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

{python_agent_harness-1.5.6.0/python_agent_harness.egg-info → python_agent_harness-1.5.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-agent-harness
-Version: 1.5.6.0
+Version: 1.5.6.1
 Summary: A lightweight, hackable mini-OpenCode written in Python.
 Author-email: Huming Chen <chenhuming@gmail.com>
 License-Expression: MIT
@@ -222,6 +222,8 @@ All LLM settings live in a single JSON configuration file. 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.
 - **`lsp.servers`** — optional per-extension LSP server overrides for the `LSP` code-intelligence tool. Keys are file extensions (e.g. `.py`, `.cpp`); each value has a `command` (the server argv) and an optional `language_id` (defaults to the extension without its dot). These layer on top of the built-in `DEFAULT_SERVERS` table in `lsp/manager.py`; an entry for an existing extension replaces its default. The server binary must be on `PATH`.
 - **`mcp.servers`** — MCP server configuration. Requires the `[mcp]` extra. Each server supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, and `enabled`.
+- **`headless`** — optional server-side limits for unattended `headless` runs: `max_rounds` caps LLM rounds and `timeout` caps wall-clock seconds. `--max-rounds` / `--timeout` override these per call; values `<= 0` or `null` disable. Unset = unlimited (interactive behavior).
+- **`serve`** — the same two keys for the resident `serve` server, applied to **each** run rather than the process: the server is resident, so every `submit` gets a fresh budget. Enforced in-process so a driving host cannot raise its own ceiling — the ceiling belongs to whoever starts the sandbox. A tripped budget ends the run with a normal `result` line carrying `errors[].code` of `budget` or `timeout` plus the token usage consumed. `--max-rounds` / `--timeout` override these; values `<= 0` or `null` disable. Unset = unlimited.
 - **Configuration precedence** — code defaults < config file < `OPENAI_*` environment variables. Sub-agent settings also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`).
 - **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.
@@ -271,9 +273,16 @@ Interactive prompts are auto-answered (`confirm` → yes, `ask` →
   one `{"type": ...}` object per line: `start` (echoes the prompt and
   submit warnings), `delta` (streamed text chunks), `notify` (tool and
   status events, with `kind`/`data`), `log`, and a final `result` (the
-  filtered answer plus any `errors`). Diagnostics (restore/model notes,
-  a plain-text echo of error events) still go to stderr, so one pipe
-  carries the structured stream. Exit codes are unchanged.
+  filtered answer plus any `errors`).  Every line carries `protocol`
+  (the wire schema version — reject an unknown version before
+  consuming events) and `seq` (a per-stream monotonic counter for
+  drop/reorder detection).  The `result` line reports `errors` as a
+  structured list of `{"code", "message"}` objects (codes: `budget`,
+  `timeout`, `nothing`, `restore`, `no_answer`, `unknown`, ...) with an
+  `error_messages` flat-string mirror for simple drivers.  Diagnostics
+  (restore/model notes, a plain-text echo of error events) still go to
+  stderr, so one pipe carries the structured stream.  Exit codes are
+  unchanged.
 
   ```sh
   python-agent-harness headless "fix it" --json | jq -c 'select(.type=="result")'
@@ -286,6 +295,7 @@ Interactive prompts are auto-answered (`confirm` → yes, `ask` →
 
 ```sh
 python-agent-harness serve [--project DIR] [--answer-timeout SECONDS]
+                           [--max-rounds N] [--timeout SECONDS]
 ```
 
 A persistent, bidirectional runtime boundary for hosting applications
@@ -306,23 +316,87 @@ Protocol (one JSON object per line):
 
 ```
 host → agent: {"op": "submit", "prompt": ..., "run_id": ...}
-              {"op": "answer", "run_id": ..., "answers": [...]}
+              {"op": "answer", "run_id": ..., "answers": [...], "ask_id": ...}
               {"op": "cancel", "run_id": ...}
+              {"op": "hello", "protocol_versions": [...]}
               {"op": "ping"} | {"op": "shutdown"}
-agent → host: {"type": "ready"}                       first line
-              {"seq": N, "type": "start"|"delta"|"notify"|"log", "run_id": ...}
-              {"seq": N, "type": "result", "run_id": ..., "answer": ...,
-               "errors": [...], "usage": {...}, "cancelled": bool}
-              {"type": "error", "error": ...}         protocol failures
+              ... any op may carry "op_id", echoed on what it causes
+agent → host: {"protocol": V, "type": "ready", "pid": ...,
+               "protocol_version": V, "capabilities": [...]}   first line
+              {"protocol": V, "type": "hello", "protocol_version": V,
+               "capabilities": [...], "op_id": ...}   negotiation reply
+              {"protocol": V, "seq": N, "type": "start"|"delta"|"notify"|"log",
+               "run_id": ...}
+              {"protocol": V, "seq": N, "type": "result", "run_id": ...,
+               "answer": ..., "errors": [{"code", "message"}],
+               "error_messages": [...], "usage": {...}, "cancelled": bool}
+              {"protocol": V, "type": "error",
+               "error": {"code": "protocol", "message": ...},
+               "message": ...}                      protocol failures
 ```
 
+Version negotiation runs both ways.  `ready` announces what the build
+speaks — a single integer a host can only accept or reject wholesale.
+`hello` is the other direction: the host states the versions *it* can
+parse and the server confirms a shared one or refuses with a
+`protocol` error, so a mismatch is settled once, before any run,
+rather than surfacing as misparsed events.  With one line shape today
+the only outcomes are "agreed" or "no overlap", but it is the hook a
+future version needs in order to downgrade instead of breaking an
+older host.  Both halves are advertised as the `hello` capability.
+
+There is no generic `ack`: each op is acknowledged by its own effect
+on the stream.  Failures are the exception, because an effect that
+never happened cannot be correlated — so an op may carry an `op_id`,
+echoed on the `error` (or `pong`) it causes.  A host that pipelined an
+`answer` and a `cancel` can then tell which one was refused instead of
+seeing two indistinguishable error lines.  Advertised as the `op_id`
+capability; omitting the field keeps the older behaviour.
+
 A mid-run question arrives as a `notify` with `kind: "ask"` (data has
-`kind: "ask"|"confirm"`); reply with `answer`.  One run at a time; a
-`submit` while one is active is rejected with an `error` line.
-`--answer-timeout SECONDS` bounds how long a pending question waits
-for the host's answer (default: forever).  The result line's shape is
-identical to `headless --json`'s, so a driver can speak both
-protocols with one parser.
+`kind: "ask"|"confirm"` and an `ask_id`); reply with `answer`, echoing
+the `ask_id` so the reply is matched to its question.  A mismatched id
+is refused rather than applied to whatever is pending — otherwise a
+reply sent for a question that has since timed out would resolve the
+*next* one.  Omitting `ask_id` keeps the older behaviour, except once
+some ask in the run has timed out, when an uncorrelated answer is
+ambiguous and is refused.
+
+One run at a time; a `submit` while one is active is rejected with an
+`error` line.  `--answer-timeout SECONDS` bounds how long a pending
+question waits for the host's answer (default: forever).  The result
+line's shape is identical to `headless --json`'s, so a driver can
+speak both protocols with one parser.
+
+`ready` carries a `capabilities` list naming the features the build
+supports, so a host can adapt instead of inferring a feature's absence
+from events that never arrive.  A `notify` of kind `usage` reports the
+run's running `{input, output, rounds}` after each round, so a host can
+meter mid-run and `cancel` a run that outruns its budget rather than
+learning the cost only from the terminal `result`.  Classified
+failures carry their code from the raise site (`errors[].code` of
+`budget` or `timeout`), so a driver never has to match words in a
+human-readable message.
+
+`--max-rounds N` and `--timeout SECONDS` (or the config file's `serve`
+section) bound **each** run rather than the process — the resident
+server grants every `submit` a fresh budget.  Both are off by default.
+They are deliberately not fields on the `submit` op: `serve` sandboxes
+untrusted agent code on a host's behalf, so the ceiling belongs to
+whoever starts the sandbox, not to the caller.  A tripped budget
+unwinds the agent loop through its normal path, so the run still ends
+with a `result` line carrying `errors[].code` of `budget` or `timeout`
+plus the token usage consumed — a host bills and reports it like any
+other outcome.
+
+`timeout` is **cooperative** — checked between rounds, not by a
+watchdog — so it bounds work at those checkpoints but does not
+forcibly interrupt a blocking operation mid-round (a hung tool, a slow
+network read, or a run parked on a mid-run question awaiting a human
+answer). Use `--answer-timeout` to cap how long an ask waits, and rely
+on the hosting process's own exec watchdog (which sends `cancel` then
+kills) as the hard wall-clock stop for anything the cooperative budget
+cannot reach.
 
 ### Slash commands
 
@@ -340,6 +414,7 @@ protocols with one parser.
 | `/clear` | Start a fresh conversation |
 | `/model [name]` | Switch LLM profiles; `default` restores the session's original model |
 | `/agent [name]` | Switch agent system prompt; `default` restores the built-in `agent.md` |
+| `/help` | List the available commands |
 | `/exit` | Quit |
 
 Custom commands from `prompts/commands/*.md` are registered as slash commands as well (TUI only).
@@ -384,12 +459,13 @@ Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13 on Linux a
 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 too)
 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.
+CI blocks on Ruff (lint **and** `format --check`) and Pyright failures.
 
 ## Design philosophy
 

{python_agent_harness-1.5.6.0 → python_agent_harness-1.5.6.1}/README.md

@@ -188,6 +188,8 @@ All LLM settings live in a single JSON configuration file. 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.
 - **`lsp.servers`** — optional per-extension LSP server overrides for the `LSP` code-intelligence tool. Keys are file extensions (e.g. `.py`, `.cpp`); each value has a `command` (the server argv) and an optional `language_id` (defaults to the extension without its dot). These layer on top of the built-in `DEFAULT_SERVERS` table in `lsp/manager.py`; an entry for an existing extension replaces its default. The server binary must be on `PATH`.
 - **`mcp.servers`** — MCP server configuration. Requires the `[mcp]` extra. Each server supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, and `enabled`.
+- **`headless`** — optional server-side limits for unattended `headless` runs: `max_rounds` caps LLM rounds and `timeout` caps wall-clock seconds. `--max-rounds` / `--timeout` override these per call; values `<= 0` or `null` disable. Unset = unlimited (interactive behavior).
+- **`serve`** — the same two keys for the resident `serve` server, applied to **each** run rather than the process: the server is resident, so every `submit` gets a fresh budget. Enforced in-process so a driving host cannot raise its own ceiling — the ceiling belongs to whoever starts the sandbox. A tripped budget ends the run with a normal `result` line carrying `errors[].code` of `budget` or `timeout` plus the token usage consumed. `--max-rounds` / `--timeout` override these; values `<= 0` or `null` disable. Unset = unlimited.
 - **Configuration precedence** — code defaults < config file < `OPENAI_*` environment variables. Sub-agent settings also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`).
 - **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.
@@ -237,9 +239,16 @@ Interactive prompts are auto-answered (`confirm` → yes, `ask` →
   one `{"type": ...}` object per line: `start` (echoes the prompt and
   submit warnings), `delta` (streamed text chunks), `notify` (tool and
   status events, with `kind`/`data`), `log`, and a final `result` (the
-  filtered answer plus any `errors`). Diagnostics (restore/model notes,
-  a plain-text echo of error events) still go to stderr, so one pipe
-  carries the structured stream. Exit codes are unchanged.
+  filtered answer plus any `errors`).  Every line carries `protocol`
+  (the wire schema version — reject an unknown version before
+  consuming events) and `seq` (a per-stream monotonic counter for
+  drop/reorder detection).  The `result` line reports `errors` as a
+  structured list of `{"code", "message"}` objects (codes: `budget`,
+  `timeout`, `nothing`, `restore`, `no_answer`, `unknown`, ...) with an
+  `error_messages` flat-string mirror for simple drivers.  Diagnostics
+  (restore/model notes, a plain-text echo of error events) still go to
+  stderr, so one pipe carries the structured stream.  Exit codes are
+  unchanged.
 
   ```sh
   python-agent-harness headless "fix it" --json | jq -c 'select(.type=="result")'
@@ -252,6 +261,7 @@ Interactive prompts are auto-answered (`confirm` → yes, `ask` →
 
 ```sh
 python-agent-harness serve [--project DIR] [--answer-timeout SECONDS]
+                           [--max-rounds N] [--timeout SECONDS]
 ```
 
 A persistent, bidirectional runtime boundary for hosting applications
@@ -272,23 +282,87 @@ Protocol (one JSON object per line):
 
 ```
 host → agent: {"op": "submit", "prompt": ..., "run_id": ...}
-              {"op": "answer", "run_id": ..., "answers": [...]}
+              {"op": "answer", "run_id": ..., "answers": [...], "ask_id": ...}
               {"op": "cancel", "run_id": ...}
+              {"op": "hello", "protocol_versions": [...]}
               {"op": "ping"} | {"op": "shutdown"}
-agent → host: {"type": "ready"}                       first line
-              {"seq": N, "type": "start"|"delta"|"notify"|"log", "run_id": ...}
-              {"seq": N, "type": "result", "run_id": ..., "answer": ...,
-               "errors": [...], "usage": {...}, "cancelled": bool}
-              {"type": "error", "error": ...}         protocol failures
+              ... any op may carry "op_id", echoed on what it causes
+agent → host: {"protocol": V, "type": "ready", "pid": ...,
+               "protocol_version": V, "capabilities": [...]}   first line
+              {"protocol": V, "type": "hello", "protocol_version": V,
+               "capabilities": [...], "op_id": ...}   negotiation reply
+              {"protocol": V, "seq": N, "type": "start"|"delta"|"notify"|"log",
+               "run_id": ...}
+              {"protocol": V, "seq": N, "type": "result", "run_id": ...,
+               "answer": ..., "errors": [{"code", "message"}],
+               "error_messages": [...], "usage": {...}, "cancelled": bool}
+              {"protocol": V, "type": "error",
+               "error": {"code": "protocol", "message": ...},
+               "message": ...}                      protocol failures
 ```
 
+Version negotiation runs both ways.  `ready` announces what the build
+speaks — a single integer a host can only accept or reject wholesale.
+`hello` is the other direction: the host states the versions *it* can
+parse and the server confirms a shared one or refuses with a
+`protocol` error, so a mismatch is settled once, before any run,
+rather than surfacing as misparsed events.  With one line shape today
+the only outcomes are "agreed" or "no overlap", but it is the hook a
+future version needs in order to downgrade instead of breaking an
+older host.  Both halves are advertised as the `hello` capability.
+
+There is no generic `ack`: each op is acknowledged by its own effect
+on the stream.  Failures are the exception, because an effect that
+never happened cannot be correlated — so an op may carry an `op_id`,
+echoed on the `error` (or `pong`) it causes.  A host that pipelined an
+`answer` and a `cancel` can then tell which one was refused instead of
+seeing two indistinguishable error lines.  Advertised as the `op_id`
+capability; omitting the field keeps the older behaviour.
+
 A mid-run question arrives as a `notify` with `kind: "ask"` (data has
-`kind: "ask"|"confirm"`); reply with `answer`.  One run at a time; a
-`submit` while one is active is rejected with an `error` line.
-`--answer-timeout SECONDS` bounds how long a pending question waits
-for the host's answer (default: forever).  The result line's shape is
-identical to `headless --json`'s, so a driver can speak both
-protocols with one parser.
+`kind: "ask"|"confirm"` and an `ask_id`); reply with `answer`, echoing
+the `ask_id` so the reply is matched to its question.  A mismatched id
+is refused rather than applied to whatever is pending — otherwise a
+reply sent for a question that has since timed out would resolve the
+*next* one.  Omitting `ask_id` keeps the older behaviour, except once
+some ask in the run has timed out, when an uncorrelated answer is
+ambiguous and is refused.
+
+One run at a time; a `submit` while one is active is rejected with an
+`error` line.  `--answer-timeout SECONDS` bounds how long a pending
+question waits for the host's answer (default: forever).  The result
+line's shape is identical to `headless --json`'s, so a driver can
+speak both protocols with one parser.
+
+`ready` carries a `capabilities` list naming the features the build
+supports, so a host can adapt instead of inferring a feature's absence
+from events that never arrive.  A `notify` of kind `usage` reports the
+run's running `{input, output, rounds}` after each round, so a host can
+meter mid-run and `cancel` a run that outruns its budget rather than
+learning the cost only from the terminal `result`.  Classified
+failures carry their code from the raise site (`errors[].code` of
+`budget` or `timeout`), so a driver never has to match words in a
+human-readable message.
+
+`--max-rounds N` and `--timeout SECONDS` (or the config file's `serve`
+section) bound **each** run rather than the process — the resident
+server grants every `submit` a fresh budget.  Both are off by default.
+They are deliberately not fields on the `submit` op: `serve` sandboxes
+untrusted agent code on a host's behalf, so the ceiling belongs to
+whoever starts the sandbox, not to the caller.  A tripped budget
+unwinds the agent loop through its normal path, so the run still ends
+with a `result` line carrying `errors[].code` of `budget` or `timeout`
+plus the token usage consumed — a host bills and reports it like any
+other outcome.
+
+`timeout` is **cooperative** — checked between rounds, not by a
+watchdog — so it bounds work at those checkpoints but does not
+forcibly interrupt a blocking operation mid-round (a hung tool, a slow
+network read, or a run parked on a mid-run question awaiting a human
+answer). Use `--answer-timeout` to cap how long an ask waits, and rely
+on the hosting process's own exec watchdog (which sends `cancel` then
+kills) as the hard wall-clock stop for anything the cooperative budget
+cannot reach.
 
 ### Slash commands
 
@@ -306,6 +380,7 @@ protocols with one parser.
 | `/clear` | Start a fresh conversation |
 | `/model [name]` | Switch LLM profiles; `default` restores the session's original model |
 | `/agent [name]` | Switch agent system prompt; `default` restores the built-in `agent.md` |
+| `/help` | List the available commands |
 | `/exit` | Quit |
 
 Custom commands from `prompts/commands/*.md` are registered as slash commands as well (TUI only).
@@ -350,12 +425,13 @@ Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13 on Linux a
 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 too)
 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.
+CI blocks on Ruff (lint **and** `format --check`) and Pyright failures.
 
 ## Design philosophy
 

{python_agent_harness-1.5.6.0 → python_agent_harness-1.5.6.1}/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.1"
 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.1}/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.1"
 
 __all__ = [
     "Client",

{python_agent_harness-1.5.6.0 → python_agent_harness-1.5.6.1}/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)
@@ -150,6 +150,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 +215,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
 
@@ -503,8 +518,12 @@ class AgentLoop:
                     return
 
         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 +600,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 +654,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.1}/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.

{python_agent_harness-1.5.6.0 → python_agent_harness-1.5.6.1}/python_agent_harness/entry/cli.py

@@ -195,6 +195,31 @@ def cmd_run(args: argparse.Namespace) -> int:
         session.close()
 
 
+def _resolve_budgets(
+    args: argparse.Namespace, cfg_limits: tuple[int | None, float | None]
+) -> tuple[int | None, float | None]:
+    """Resolve ``(max_rounds, timeout)`` for an unattended run.
+
+    Precedence: an explicit CLI flag wins over the config file's
+    section default, which wins over unlimited.  A flag of 0/negative
+    is an explicit "disable", so it overrides a configured budget
+    rather than falling back to it.  Shared by ``headless`` and
+    ``serve``, whose budget flags are identical.
+    """
+    cfg_max_rounds, cfg_timeout = cfg_limits
+    max_rounds = getattr(args, "max_rounds", None)
+    if max_rounds is None:
+        max_rounds = cfg_max_rounds
+    elif max_rounds <= 0:
+        max_rounds = None
+    timeout = getattr(args, "timeout", None)
+    if timeout is None:
+        timeout = cfg_timeout
+    elif timeout <= 0:
+        timeout = None
+    return max_rounds, timeout
+
+
 def cmd_headless(args: argparse.Namespace) -> int:
     project_dir = getattr(args, "project", None) or os.getcwd()
     session = make_session_with_mcp(
@@ -211,17 +236,7 @@ def cmd_headless(args: argparse.Namespace) -> int:
         runner = run_headless_jsonl if getattr(args, "json", False) else run_headless
         # Unattended budgets: explicit flags win over the config file's
         # headless section (0/negative disables the budget entirely).
-        cfg_max_rounds, cfg_timeout = config.load_headless_limits(args.config)
-        max_rounds = getattr(args, "max_rounds", None)
-        if max_rounds is None:
-            max_rounds = cfg_max_rounds
-        elif max_rounds <= 0:
-            max_rounds = None
-        timeout = getattr(args, "timeout", None)
-        if timeout is None:
-            timeout = cfg_timeout
-        elif timeout <= 0:
-            timeout = None
+        max_rounds, timeout = _resolve_budgets(args, config.load_headless_limits(args.config))
         return runner(
             session,
             prompt,
@@ -245,9 +260,15 @@ def cmd_serve(args: argparse.Namespace) -> int:
     try:
         from .server import run_serve
 
+        # Per-run budgets: explicit flags win over the config file's
+        # serve section (0/negative disables).  Applied to EACH submit
+        # — the process is resident, so every run gets a fresh budget.
+        max_rounds, timeout = _resolve_budgets(args, config.load_serve_limits(args.config))
         return run_serve(
             session,
             answer_timeout=float(getattr(args, "answer_timeout", 0.0) or 0.0),
+            max_rounds=max_rounds,
+            timeout=timeout,
         )
     finally:
         session.close()
@@ -344,6 +365,14 @@ def cmd_config(args: argparse.Namespace) -> int:
         print(
             f"headless: max_rounds={max_rounds or '(unlimited)'}, timeout={timeout or '(unlimited)'}s"
         )
+    serve_rounds, serve_timeout = config.load_serve_limits(args.path)
+    if serve_rounds is None and serve_timeout is None:
+        print("serve: (unlimited — set serve.max_rounds/timeout or use --max-rounds/--timeout)")
+    else:
+        print(
+            f"serve: max_rounds={serve_rounds or '(unlimited)'}, "
+            f"timeout={serve_timeout or '(unlimited)'}s (per run)"
+        )
     return 0
 
 
@@ -468,6 +497,24 @@ def build_parser() -> argparse.ArgumentParser:
         help="give up waiting for a host answer after N seconds (0 = wait "
         'forever, the default; the host can answer via {"op": "answer"})',
     )
+    p_serve.add_argument(
+        "--max-rounds",
+        metavar="N",
+        type=int,
+        default=None,
+        help="cap EACH run at N LLM rounds (per-submit budget, not a "
+        "process cap; default: config serve.max_rounds, else unlimited)",
+    )
+    p_serve.add_argument(
+        "--timeout",
+        metavar="SECONDS",
+        type=float,
+        default=None,
+        help="wall-clock limit for EACH run in seconds (per-submit budget, "
+        "cooperative — checked between rounds, does not interrupt a run "
+        "blocked on a mid-run question; default: config serve.timeout, else "
+        "unlimited)",
+    )
     return parser
 
 

{python_agent_harness-1.5.6.0 → python_agent_harness-1.5.6.1}/python_agent_harness/entry/controller.py

@@ -83,6 +83,21 @@ class Controller:
         self.session.confirm_fn = view.confirm
         self.session.ask_fn = view.ask
 
+    def detach_view(self) -> None:
+        """Unwire the session's callbacks (no view attached).
+
+        The counterpart of ``attach_view``, for a host that swaps views
+        per run (``serve``): once a run's view is detached, a worker
+        still unwinding from that run emits into nothing instead of
+        into whichever view happens to be attached next — its events
+        would otherwise be attributed to a different run.
+        """
+        self.session.on_delta = None
+        self.session.notify_fn = None
+        self.session.log_fn = None
+        self.session.confirm_fn = None
+        self.session.ask_fn = None
+
     # ------------------------------------------------------------------
     # read-only state accessors
     # ------------------------------------------------------------------