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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-agent-harness
-Version: 1.5.5.9
+Version: 1.5.6.0
 Summary: A lightweight, hackable mini-OpenCode written in Python.
 Author-email: Huming Chen <chenhuming@gmail.com>
 License-Expression: MIT
@@ -9,7 +9,6 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: MacOS
-Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -20,6 +19,7 @@ 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"
@@ -113,6 +113,7 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 - **MCP support** — optional MCP integration through the `[mcp]` extra. MCP tools become ordinary agent tools such as `mcp__<server>__<tool>`. Supports `stdio`, `streamable-http`, and `sse` transports.
 - **Slash commands** — built-in `/init`, `/review`, `/explain`, and other commands, plus custom commands loaded from `prompts/commands/*.md`.
 - **Custom agents** — switch the main agent's system prompt at runtime with `/agent`. Agent prompt files live in `prompts/agents/*.md`. Use `default_agent` in the config file to start sessions with a specific agent.
+- **Embeddable runtime boundaries** — drive the agent from programs: `headless --json` for one-shot CI/scripting (write-only JSONL stream), `serve` for hosting apps (resident process, bidirectional protocol: multi-turn memory, mid-run Q&A, protocol-level cancel).
 
 ## Inspired by opencode
 
@@ -281,6 +282,48 @@ Interactive prompts are auto-answered (`confirm` → yes, `ask` →
 - Exit code is 0 on success, 1 when the prompt was empty (only failed
   `@file` references), the run raised an agent error, or the restore failed.
 
+### Serve mode (resident JSONL server)
+
+```sh
+python-agent-harness serve [--project DIR] [--answer-timeout SECONDS]
+```
+
+A persistent, bidirectional runtime boundary for hosting applications
+(a web backend, an IDE, a CI driver).  Unlike `headless --json` (one
+prompt per process, write-only stream), `serve` keeps the
+`Controller`/`Session` resident and speaks a request/response protocol
+over stdin/stdout — the same process boundary (containerizable), but
+the host can:
+
+- submit multiple prompts over the process's lifetime — no per-turn
+  interpreter spawn, and conversation history is retained between them
+  (multi-turn memory);
+- answer the agent's mid-run questions (the `Question` tool and
+  plan-exit confirmation) via an `answer` op;
+- cancel a run as a protocol message (no signal semantics).
+
+Protocol (one JSON object per line):
+
+```
+host → agent: {"op": "submit", "prompt": ..., "run_id": ...}
+              {"op": "answer", "run_id": ..., "answers": [...]}
+              {"op": "cancel", "run_id": ...}
+              {"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
+```
+
+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.
+
 ### Slash commands
 
 | Command | Description |
@@ -335,7 +378,7 @@ You are a personal assistant. You do NOT modify files or run shell commands.
 
 ## Development
 
-Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13 on Linux, MacOS and Windows.
+Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13 on Linux and MacOS.
 
 ```sh
 make test                           # unit tests

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

@@ -79,6 +79,7 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 - **MCP support** — optional MCP integration through the `[mcp]` extra. MCP tools become ordinary agent tools such as `mcp__<server>__<tool>`. Supports `stdio`, `streamable-http`, and `sse` transports.
 - **Slash commands** — built-in `/init`, `/review`, `/explain`, and other commands, plus custom commands loaded from `prompts/commands/*.md`.
 - **Custom agents** — switch the main agent's system prompt at runtime with `/agent`. Agent prompt files live in `prompts/agents/*.md`. Use `default_agent` in the config file to start sessions with a specific agent.
+- **Embeddable runtime boundaries** — drive the agent from programs: `headless --json` for one-shot CI/scripting (write-only JSONL stream), `serve` for hosting apps (resident process, bidirectional protocol: multi-turn memory, mid-run Q&A, protocol-level cancel).
 
 ## Inspired by opencode
 
@@ -247,6 +248,48 @@ Interactive prompts are auto-answered (`confirm` → yes, `ask` →
 - Exit code is 0 on success, 1 when the prompt was empty (only failed
   `@file` references), the run raised an agent error, or the restore failed.
 
+### Serve mode (resident JSONL server)
+
+```sh
+python-agent-harness serve [--project DIR] [--answer-timeout SECONDS]
+```
+
+A persistent, bidirectional runtime boundary for hosting applications
+(a web backend, an IDE, a CI driver).  Unlike `headless --json` (one
+prompt per process, write-only stream), `serve` keeps the
+`Controller`/`Session` resident and speaks a request/response protocol
+over stdin/stdout — the same process boundary (containerizable), but
+the host can:
+
+- submit multiple prompts over the process's lifetime — no per-turn
+  interpreter spawn, and conversation history is retained between them
+  (multi-turn memory);
+- answer the agent's mid-run questions (the `Question` tool and
+  plan-exit confirmation) via an `answer` op;
+- cancel a run as a protocol message (no signal semantics).
+
+Protocol (one JSON object per line):
+
+```
+host → agent: {"op": "submit", "prompt": ..., "run_id": ...}
+              {"op": "answer", "run_id": ..., "answers": [...]}
+              {"op": "cancel", "run_id": ...}
+              {"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
+```
+
+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.
+
 ### Slash commands
 
 | Command | Description |
@@ -301,7 +344,7 @@ You are a personal assistant. You do NOT modify files or run shell commands.
 
 ## Development
 
-Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13 on Linux, MacOS and Windows.
+Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13 on Linux and MacOS.
 
 ```sh
 make test                           # unit tests

{python_agent_harness-1.5.5.9 → python_agent_harness-1.5.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-agent-harness"
-version = "1.5.5.9"
+version = "1.5.6.0"
 description = "A lightweight, hackable mini-OpenCode written in Python."
 authors = [
     {name = "Huming Chen", email = "chenhuming@gmail.com"}
@@ -17,7 +17,6 @@ classifiers = [
     "Environment :: Console",
     "Intended Audience :: Developers",
     "Operating System :: MacOS",
-    "Operating System :: Microsoft :: Windows",
     "Operating System :: POSIX :: Linux",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -27,6 +26,7 @@ classifiers = [
 dependencies = [
     "rich>=13.0",
     "httpx>=0.27",
+    "certifi>=2024.0",
     "prompt_toolkit>=3.0",
 ]
 
@@ -96,8 +96,4 @@ omit = [
 
 [tool.coverage.report]
 show_missing = true
-# Linux/macOS gate: 95%.  Windows CI enforces 94% with tools/bash.py
-# omitted instead (see .github/workflows/ci.yml): that module is the
-# posix PTY/spawn backend whose body cannot execute on Windows, where
-# tools/bash_win.py runs in its place.
 fail_under = 95

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

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

@@ -35,6 +35,8 @@ to them via ``_tool_runner`` / ``_context_manager``.
 
 from __future__ import annotations
 
+import threading
+import time
 from typing import Any, Protocol
 
 from ..llm.client import LLMClient
@@ -50,6 +52,13 @@ from .tool_runner import (
 )
 
 
+def _deadline_message(timeout: float | None) -> str:
+    """Result text for a wall-clock abort."""
+    if timeout:
+        return f"run exceeded the {timeout:g}s wall-clock limit"
+    return "run exceeded its wall-clock limit"
+
+
 class _SupervisorSession(Protocol):
     """The slice of an agent session the Supervisor reads."""
 
@@ -76,6 +85,8 @@ class AgentLoop:
         system: str | None = None,
         max_rounds: int = 60,
         client: LLMClient | None = None,
+        budget_top_level: bool = False,
+        timeout: float | None = None,
     ) -> None:
         self.session = session
         self.messages: list[Message] = messages if messages is not None else []
@@ -96,6 +107,13 @@ class AgentLoop:
         # max_rounds only bounds sub-agent loops: the main agent runs until
         # the model gives a terminal response or the user aborts it (Ctrl-C)
         self.max_rounds = max_rounds if not top_level else None
+        if top_level and budget_top_level:
+            # unattended (headless/CI) top-level runs may opt in to a
+            # round budget: an interactive TUI run still runs until the
+            # model finishes or the user aborts
+            self.max_rounds = max_rounds
+        # Optional wall-clock budget for unattended runs (None = off)
+        self.timeout = timeout
         self.pending: list[ToolCall] = []
         self.error: str | None = None
         self.harness_injected: bool = False
@@ -114,6 +132,9 @@ class AgentLoop:
         self.info: dict[str, Any] = {}
         self.history: list[str] = []
         self.rounds = 0
+        # Thread-local wall-clock deadline bookkeeping: sub-agent loops
+        # run in their own threads, so a shared attribute would race
+        self._local = threading.local()
         self.terminal_text: str | None = None
         self.result: str | None = None
         # Cancellation identity for this run: cancel() bumps the session
@@ -132,7 +153,6 @@ class AgentLoop:
 
     def _is_cancelled(self) -> bool:
         """Whether THIS run must stop (cancelled or superseded).
-
         The plain event is not enough: `_start_agent` clears it before
         every run, so a worker from a cancelled run that finishes late
         (e.g. after a long tool call) would otherwise see it cleared and
@@ -156,6 +176,46 @@ class AgentLoop:
         """
         return self.session.run_generation != self._run_gen
 
+    @property
+    def _deadline(self) -> float | None:
+        """This thread's wall-clock deadline (None = unbounded).
+
+        Sub-agent loops run in their own threads; the thread-local keeps
+        the parent's deadline from leaking into (or being cleared by)
+        their bookkeeping, while sibling sub-agents under one session
+        each read their own entry.
+        """
+        return getattr(self._local, "deadline", None)
+
+    def _deadline_exceeded(self) -> bool:
+        """Whether this thread's wall-clock budget has run out."""
+        deadline = self._deadline
+        return deadline is not None and time.monotonic() >= deadline
+
+    def _check_budget_at_wait(self) -> bool:
+        """WAIT-entry budget enforcement; True when a budget tripped.
+
+        Sub-agent exhaustion keeps the historical soft path (``info[
+        "budget"]`` -> DONE with a best-effort final answer).  An
+        opted-in top-level budget (headless/CI) is a hard stop: it
+        routes ERRS with an explicit error so the driving process gets
+        a failed exit code instead of silently truncated work.
+        """
+        if self.max_rounds is not None and self.rounds >= self.max_rounds:
+            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)
+            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)
+            return True
+        return False
+
     # ------------------------------------------------------------------
     # finite state machine
     #
@@ -346,6 +406,11 @@ class AgentLoop:
         handler.
         """
         session = self.session
+        if self.timeout is not None:
+            # Wall-clock budget for THIS run's thread.  Thread-local on
+            # purpose: sub-agent loops run in sibling threads and must
+            # not inherit (or clear) the parent's deadline.
+            self._local.deadline = time.monotonic() + self.timeout
         try:
             # The machine starts directly in WAIT — an asynchronous
             # INIT state is not needed for the synchronous driver.
@@ -420,8 +485,7 @@ class AgentLoop:
         """
         session = self.session
         self.info.clear()
-        if self.max_rounds is not None and self.rounds >= self.max_rounds:
-            self.info["budget"] = True
+        if self._check_budget_at_wait():
             return
         self.rounds += 1
         if self._is_cancelled():
@@ -506,6 +570,18 @@ class AgentLoop:
         if self._is_cancelled():
             return  # response arrived after cancel: drop it
 
+        # Usage accounting: every loop under this session (main and
+        # sub-agents alike — sub-agent tokens spend the same API key)
+        # adds its per-round usage; a run's driver reads the totals
+        # when the run finishes.  Sessions without the attribute (test
+        # doubles) skip silently.
+        totals = getattr(session, "usage_totals", None)
+        if isinstance(totals, dict):
+            with totals.setdefault("_lock", threading.Lock()):
+                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
+
         # persist the assistant response in the conversation history
         # (text and/or tool calls) so later turns and the UI see it;
         # always append to maintain role alternation — a missing
@@ -636,11 +712,17 @@ def run_agent_loop(
     system: str | None = None,
     max_rounds: int = 60,
     client: LLMClient | None = None,
+    budget_top_level: bool = False,
+    timeout: float | None = None,
 ) -> str | None:
     """Convenience wrapper running a full agent run (FSM).
 
     ``client`` (when given) overrides the session's client for this
-    run — the per-invocation sub-agent clone."""
+    run — the per-invocation sub-agent clone.  ``budget_top_level``
+    opts an unattended top-level run into the ``max_rounds`` budget;
+    ``timeout`` adds a wall-clock limit (both default off, matching
+    the interactive TUI behavior).
+    """
     loop = AgentLoop(
         session,
         messages=messages,
@@ -648,6 +730,8 @@ def run_agent_loop(
         system=system,
         max_rounds=max_rounds,
         client=client,
+        budget_top_level=budget_top_level,
+        timeout=timeout,
     )
     result = loop.run()
     # Notify run_done only for a successfully completed top-level run:

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

@@ -4,6 +4,8 @@ Commands:
   run                      interactive TUI agent session (default)
   headless [prompt]        non-interactive: submit one prompt, print the result
                            (--json emits the run as JSON lines instead)
+  serve                    resident JSONL server over stdin/stdout: submit
+                           runs repeatedly, answer mid-run questions, cancel
   config [--init]          show effective LLM config / write a template file
 
 Custom commands (prompts/commands/*.md) — like init, review,
@@ -207,11 +209,45 @@ def cmd_headless(args: argparse.Namespace) -> int:
         if prompt is None:
             prompt = sys.stdin.read()
         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
         return runner(
             session,
             prompt,
             restore=getattr(args, "restore", None),
             model=getattr(args, "model", None),
+            run_id=getattr(args, "run_id", None),
+            max_rounds=max_rounds,
+            timeout=timeout,
+        )
+    finally:
+        session.close()
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    project_dir = getattr(args, "project", None) or os.getcwd()
+    session = make_session_with_mcp(
+        project_dir,
+        config_path=args.config,
+        stream=False if getattr(args, "no_stream", False) else None,
+    )
+    try:
+        from .server import run_serve
+
+        return run_serve(
+            session,
+            answer_timeout=float(getattr(args, "answer_timeout", 0.0) or 0.0),
         )
     finally:
         session.close()
@@ -299,6 +335,15 @@ def cmd_config(args: argparse.Namespace) -> int:
     # Show default agent
     default_agent = config.load_default_agent(args.path)
     print(f"default_agent: {default_agent or '(default: agent.md)'}")
+    max_rounds, timeout = config.load_headless_limits(args.path)
+    if max_rounds is None and timeout is None:
+        print(
+            "headless: (unlimited — set headless.max_rounds/timeout or use --max-rounds/--timeout)"
+        )
+    else:
+        print(
+            f"headless: max_rounds={max_rounds or '(unlimited)'}, timeout={timeout or '(unlimited)'}s"
+        )
     return 0
 
 
@@ -372,11 +417,57 @@ def build_parser() -> argparse.ArgumentParser:
         help="emit the run as JSON lines on stdout (start/delta/notify/log/"
         "result events) for programmatic driving; diagnostics stay on stderr",
     )
+    p_headless.add_argument(
+        "--run-id",
+        metavar="ID",
+        default=None,
+        help="correlation id echoed on every --json line (e.g. the controller's exec id)",
+    )
+    p_headless.add_argument(
+        "--max-rounds",
+        metavar="N",
+        type=int,
+        default=None,
+        help="cap the run at N LLM rounds (unattended budget; default: config "
+        "headless.max_rounds, else unlimited)",
+    )
+    p_headless.add_argument(
+        "--timeout",
+        metavar="SECONDS",
+        type=float,
+        default=None,
+        help="wall-clock limit for the run in seconds (unattended budget; "
+        "default: config headless.timeout, else unlimited)",
+    )
 
     p_config = sub.add_parser("config", help="show effective LLM config or write a template file")
     p_config.add_argument("--init", action="store_true", help="write a config template")
     p_config.add_argument("--path", metavar="PATH", help="config file path")
     p_config.set_defaults(func=cmd_config)
+
+    p_serve = sub.add_parser(
+        "serve",
+        help="resident JSONL server: multiple runs per process, mid-run Q&A",
+    )
+    _add_config_arg(p_serve, suppress=True)
+    p_serve.add_argument(
+        "--no-stream",
+        action="store_true",
+        help="disable streaming (one-shot responses; overrides config file)",
+    )
+    p_serve.add_argument(
+        "--project",
+        metavar="DIR",
+        help="project directory (default: cwd)",
+    )
+    p_serve.add_argument(
+        "--answer-timeout",
+        metavar="SECONDS",
+        type=float,
+        default=0.0,
+        help="give up waiting for a host answer after N seconds (0 = wait "
+        'forever, the default; the host can answer via {"op": "answer"})',
+    )
     return parser
 
 
@@ -387,6 +478,8 @@ def main(argv: list[str] | None = None) -> int:
         return cmd_run(args)
     if args.command == "headless":
         return cmd_headless(args)
+    if args.command == "serve":
+        return cmd_serve(args)
     if args.command == "config":
         return cmd_config(args)
     parser.print_help()

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

@@ -219,6 +219,8 @@ class Controller:
         text: str | Message,
         system: str | None = None,
         restore: Any = None,
+        max_rounds: int | None = None,
+        timeout: float | None = None,
     ) -> RunHandle | None:
         """Start an agent run in a worker thread; return its handle.
 
@@ -228,7 +230,10 @@ class Controller:
         directly).  SYSTEM overrides the session's system prompt for
         this run only.  RESTORE (if given) runs when the run finishes
         — used by slash commands to put back state they borrowed
-        (e.g. project_dir).
+        (e.g. project_dir).  MAX_ROUNDS (when given) opts this
+        unattended run into a round budget; TIMEOUT sets a wall-clock
+        limit — both default to the interactive behavior (unbounded),
+        and both apply to the top-level loop only.
 
         Returns None when the text was only failed ``@file``
         references with nothing else to send (the view surfaces the
@@ -249,9 +254,19 @@ class Controller:
         self.session.run_generation += 1
         self.session.cancel_event.clear()
         seq = self.session.run_generation
+        # Fresh usage accounting for this run (the previous run's totals
+        # were already emitted on its result line): a fresh dict, not a
+        # clear(), so a late sub-agent still writing into the old dict
+        # cannot pollute this run's numbers.
+        self.session.usage_totals = {
+            "input": 0,
+            "output": 0,
+            "rounds": 0,
+            "_lock": threading.Lock(),
+        }
         worker = threading.Thread(
             target=self._run_worker,
-            args=(user_msg, seq, system, restore),
+            args=(user_msg, seq, system, restore, max_rounds, timeout),
             daemon=True,
         )
         worker.start()
@@ -324,6 +339,8 @@ class Controller:
         seq: int,
         system: str | None = None,
         restore: Any = None,
+        max_rounds: int | None = None,
+        timeout: float | None = None,
     ) -> None:
         """Worker-thread body of a submitted run: drive the agent loop.
 
@@ -342,6 +359,9 @@ class Controller:
                 messages=list(self.conversation_history),
                 top_level=True,
                 system=system or self.system_prompt,
+                budget_top_level=max_rounds is not None,
+                max_rounds=max_rounds if max_rounds is not None else 60,
+                timeout=timeout,
             )
             if seq == self.session.run_generation and self.session.last_messages:
                 self.conversation_history = list(self.session.last_messages)