Add Serve mode.

Author: beacoder

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 |

pyproject.toml

@@ -27,6 +27,7 @@ classifiers = [
 dependencies = [
     "rich>=13.0",
     "httpx>=0.27",
+    "certifi>=2024.0",
     "prompt_toolkit>=3.0",
 ]
 

python_agent_harness/entry/cli.py

@@ -4,6 +4,8 @@
   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,
@@ -233,6 +235,24 @@ def cmd_headless(args: argparse.Namespace) -> int:
         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()
+
+
 def cmd_config(args: argparse.Namespace) -> int:
     path = config._config_path(args.path)
     if args.init:
@@ -424,6 +444,30 @@ def build_parser() -> argparse.ArgumentParser:
     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
 
 
@@ -434,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()