piocloop 0.1.0__py3-none-any.whl

piocloop/tui.py

@@ -0,0 +1,289 @@
+"""Textual TUI for piocloop — a thin view over LoopEngine.
+
+All orchestration lives in `loop.py` so it can be tested without a terminal;
+this module only renders state and translates key presses into engine calls.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import IO, Optional
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.widgets import Footer, RichLog, Static
+
+from .loop import (
+    STATE_COMPLETE,
+    STATE_ERROR,
+    STATE_PAUSED,
+    STATE_PAUSING,
+    STATE_READY,
+    STATE_RUNNING,
+    STATE_STALLED,
+    STATE_STARTING,
+    LoopConfig,
+    LoopEngine,
+)
+
+_STATE_ICONS = {
+    STATE_STARTING: "◐",
+    STATE_READY: "●",
+    STATE_RUNNING: "▶",
+    STATE_PAUSING: "◑",
+    STATE_PAUSED: "⏸",
+    STATE_STALLED: "⚠",
+    STATE_COMPLETE: "✓",
+    STATE_ERROR: "✗",
+}
+
+_STATE_COLORS = {
+    STATE_STARTING: "yellow",
+    STATE_READY: "cyan",
+    STATE_RUNNING: "green",
+    STATE_PAUSING: "yellow",
+    STATE_PAUSED: "yellow",
+    STATE_STALLED: "orange1",
+    STATE_COMPLETE: "bright_green",
+    STATE_ERROR: "red",
+}
+
+_LOG_COLORS = {
+    "start": "cyan", "idle": "cyan", "task": "yellow", "edit": "green",
+    "error": "red", "tool": "magenta", "read": "blue", "ai": "white",
+    "think": "dim", "info": "dim", "complete": "bright_green",
+    "warn": "orange1", "dialog": "orange1", "retry": "orange1",
+    "compaction": "blue", "status": "dim", "stderr": "dim",
+    "extension": "orange1", "protocol": "orange1",
+}
+
+
+def _escape(text: str) -> str:
+    """Agent output must never be interpreted as Rich markup."""
+    return text.replace("[", r"\[")
+
+
+class _Header(Static):
+    DEFAULT_CSS = """
+    _Header {
+        height: auto;
+        background: $panel;
+        border-bottom: solid $primary;
+        padding: 0 1;
+    }
+    """
+
+
+class PiloopApp(App):
+    CSS = """
+    Screen { layout: vertical; }
+    _Header { height: auto; min-height: 3; }
+    RichLog { height: 1fr; border: none; scrollbar-gutter: stable; }
+    Footer  { height: 1; }
+    """
+
+    BINDINGS = [
+        Binding("s", "start_loop", "Start", show=True),
+        Binding("space", "toggle_pause", "Pause", show=True),
+        Binding("a", "abort_now", "Abort iter", show=True),
+        Binding("r", "retry", "Retry", show=True),
+        Binding("q", "request_quit", "Quit", show=True),
+        Binding("ctrl+c", "request_quit", "Quit", show=False),
+    ]
+
+    def __init__(
+        self,
+        config: LoopConfig,
+        *,
+        model: Optional[str] = None,
+        auto_run: bool = False,
+        log_file: Optional[Path] = None,
+    ) -> None:
+        super().__init__()
+        self._config = config
+        self._model = model
+        self._auto_run = auto_run
+        self._log_fh: Optional[IO[str]] = (
+            open(log_file, "a", encoding="utf-8") if log_file else None
+        )
+        self.engine = LoopEngine(config, ui=self)
+
+    # ------------------------------------------------------------------
+    # Compose / lifecycle
+    # ------------------------------------------------------------------
+
+    def compose(self) -> ComposeResult:
+        yield _Header()
+        yield RichLog(id="log", auto_scroll=True, highlight=False, markup=True, wrap=True)
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self._refresh_header()
+        self.run_worker(self._worker_boot(), name="boot")
+        self.set_interval(1.0, self._refresh_header)
+        self.set_interval(4.0, self.engine.reload_plan)
+
+    async def _worker_boot(self) -> None:
+        try:
+            if not await self.engine.boot():
+                return
+            await self.engine.run(auto_start=self._auto_run)
+        finally:
+            await self.engine.shutdown()
+
+    async def on_unmount(self) -> None:
+        await self.engine.shutdown()
+        if self._log_fh:
+            self._log_fh.close()
+            self._log_fh = None
+
+    # ------------------------------------------------------------------
+    # LoopUI implementation
+    # ------------------------------------------------------------------
+
+    def log_line(self, kind: str, text: str, detail: str = "") -> None:
+        ts = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+        if self._log_fh:
+            suffix = f" | {detail}" if detail else ""
+            self._log_fh.write(f"{ts} [{kind}] {text}{suffix}\n")
+            self._log_fh.flush()
+        color = _LOG_COLORS.get(kind, "white")
+        detail_str = f" [dim]{_escape(detail[:100])}[/dim]" if detail else ""
+        with contextlib.suppress(Exception):
+            self.query_one(RichLog).write(
+                f"[dim]{ts}[/dim] [{color}][{kind}][/{color}] {_escape(text)}{detail_str}"
+            )
+
+    def set_state(self, state: str) -> None:
+        self._refresh_header()
+
+    def on_progress(self) -> None:
+        self._refresh_header()
+
+    def on_complete(self, summary: str) -> None:
+        with contextlib.suppress(Exception):
+            log = self.query_one(RichLog)
+            log.write("")
+            log.write("[bright_green bold]╔══════════════════════════════════════╗[/bright_green bold]")
+            log.write("[bright_green bold]║           PLAN COMPLETE              ║[/bright_green bold]")
+            log.write("[bright_green bold]╚══════════════════════════════════════╝[/bright_green bold]")
+            log.write("")
+            for line in summary.splitlines():
+                log.write(f"  {_escape(line)}")
+            log.write("")
+            log.write("[dim]Press Q to quit.[/dim]")
+
+    # ------------------------------------------------------------------
+    # Header
+    # ------------------------------------------------------------------
+
+    def _refresh_header(self) -> None:
+        with contextlib.suppress(Exception):
+            self.query_one(_Header).update(self._build_header())
+
+    def _build_header(self) -> str:
+        engine = self.engine
+        icon = _STATE_ICONS.get(engine.state, "?")
+        color = _STATE_COLORS.get(engine.state, "white")
+        state_str = f"[{color}]{icon} {engine.state.upper()}[/{color}]"
+
+        if engine.progress:
+            p = engine.progress
+            automatable = p.completed + p.pending
+            pct = p.percent_complete
+            filled = round(20 * pct / 100)
+            bar = "█" * filled + "░" * (20 - filled)
+            progress_str = f"[{p.completed}/{automatable}] [{bar}] {pct}%"
+            if p.blocked:
+                progress_str += f" [red]{p.blocked} blocked[/red]"
+        else:
+            progress_str = ""
+
+        iter_str = (
+            f"iter:{engine.iteration}/{engine.config.max_iterations}"
+            if engine.iteration
+            else ""
+        )
+
+        elapsed_str = ""
+        if engine.iter_start_time and engine.state in (STATE_RUNNING, STATE_PAUSING):
+            e = int(time.monotonic() - engine.iter_start_time)
+            elapsed_str = f"{e // 60}:{e % 60:02d}"
+        avg_str = ""
+        if engine.iter_times:
+            a = int(sum(engine.iter_times) / len(engine.iter_times))
+            avg_str = f"avg:{a // 60}:{a % 60:02d}"
+
+        model_str = f"[dim]{self._model}[/dim]" if self._model else ""
+        tok_str = f"[dim]tok:{engine.total_tokens:,}[/dim]" if engine.total_tokens else ""
+        cost_str = f"[dim]${engine.total_cost:.4f}[/dim]" if engine.total_cost else ""
+
+        if engine.state == STATE_COMPLETE:
+            task_str = "[bright_green]All tasks complete![/bright_green]"
+        elif engine.state == STATE_READY:
+            task_str = "[dim]Press [bold]S[/bold] to start[/dim]"
+        elif engine.state == STATE_STALLED:
+            task_str = (
+                f"[orange1]No progress for {engine.stall_count} iterations — "
+                f"press [bold]R[/bold] to continue or [bold]Q[/bold] to quit[/orange1]"
+            )
+        elif engine.state == STATE_ERROR:
+            task_str = "[dim]Press [bold]R[/bold] to retry or [bold]Q[/bold] to quit[/dim]"
+        elif engine.state == STATE_PAUSING:
+            task_str = (
+                "[yellow]Finishing current iteration — "
+                "press [bold]A[/bold] to abort it now[/yellow]"
+            )
+        elif engine.current_task:
+            task_str = f"[yellow]{_escape(engine.current_task[:100])}[/yellow]"
+        else:
+            task_str = ""
+
+        row1 = "  ".join(x for x in [state_str, progress_str, iter_str, elapsed_str, avg_str] if x)
+        row2 = "  ".join(x for x in [model_str, tok_str, cost_str] if x)
+        lines = [row1]
+        if row2:
+            lines.append(row2)
+        if task_str:
+            lines.append(task_str)
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # Actions
+    # ------------------------------------------------------------------
+
+    def action_start_loop(self) -> None:
+        if self.engine.state == STATE_READY:
+            self.engine.request_start()
+
+    def action_toggle_pause(self) -> None:
+        if self.engine.state == STATE_RUNNING:
+            self.engine.request_pause()
+            self.log_line("info", "Pause requested — will stop after this iteration")
+        elif self.engine.state in (STATE_PAUSED, STATE_PAUSING):
+            self.engine.request_resume()
+        self._refresh_header()
+
+    def action_abort_now(self) -> None:
+        if self.engine.state in (STATE_RUNNING, STATE_PAUSING):
+            self.log_line("warn", "Abort requested")
+            self.run_worker(self.engine.abort_current(), name="abort")
+
+    def action_retry(self) -> None:
+        if self.engine.state in (STATE_ERROR, STATE_STALLED):
+            self.log_line("info", "Retrying")
+            self.engine.request_retry()
+
+    def action_request_quit(self) -> None:
+        self.engine.request_stop()
+        self.run_worker(self._quit_soon(), name="quit")
+
+    async def _quit_soon(self) -> None:
+        with contextlib.suppress(Exception):
+            await asyncio.wait_for(self.engine.abort_current(), timeout=5.0)
+        await self.engine.shutdown()
+        self.exit()

piocloop-0.1.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: piocloop
+Version: 0.1.0
+Summary: TUI loop harness that orchestrates the PI coding agent to execute tasks from a PLAN.md file iteratively
+Project-URL: Homepage, https://github.com/rbarzic/piocloop
+Project-URL: Repository, https://github.com/rbarzic/piocloop
+Project-URL: Issues, https://github.com/rbarzic/piocloop/issues
+Author-email: Ronan Barzic <rbarzic@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,automation,pi,pi-coding-agent,textual,tui
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: textual>=0.80
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# piocloop
+
+A Python TUI that orchestrates the [PI coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
+to execute tasks from a `PLAN.md` file iteratively, one session at a time.
+
+piocloop is a port of [pyocloop](https://github.com/rbarzic/pyocloop) — same
+concept, but it drives `pi --mode rpc` over stdin/stdout JSONL instead of an
+OpenCode HTTP server plus SSE stream. That change, plus a real watchdog, fixes
+the hangs documented in [`ANALYSIS.md`](ANALYSIS.md).
+
+## How it works
+
+1. piocloop starts a `pi --mode rpc` subprocess
+2. On each iteration it starts a fresh session, sends your loop prompt (with the
+   plan file path injected), and waits for `agent_settled`
+3. PI reads the plan, executes the next task, marks it `[x]`, and appends
+   `<plan-complete>` when everything is done
+4. The TUI shows live progress: task counter, progress bar, current task, token
+   count, cost, and elapsed/average time per iteration
+5. The loop stops when PI writes `<plan-complete>` — or when the watchdog, an
+   error streak, a stall, or `--max-iterations` intervenes
+
+## Requirements
+
+- Python 3.11+
+- `pi` on your PATH, configured with a provider (developed against pi 0.82.1)
+
+```bash
+npm install -g @earendil-works/pi-coding-agent
+```
+
+## Installation
+
+```bash
+git clone https://github.com/rbarzic/piocloop
+cd piocloop
+pip install .
+```
+
+## Usage
+
+```bash
+piloop doctor                    # check pi is installed and reachable
+piloop bootstrap .               # create starter PLAN.md and .loop-prompt.md
+piloop run --model zai/glm-5.2
+```
+
+### Using an OpenRouter model
+
+Set your OpenRouter API key, then prefix the OpenRouter model ID with
+`openrouter/`. For example, Kimi K3 is `moonshotai/kimi-k3` on OpenRouter:
+
+```bash
+export OPENROUTER_API_KEY="your-openrouter-api-key"
+piloop run --model openrouter/moonshotai/kimi-k3
+```
+
+You can check that PI's model catalog contains it with:
+
+```bash
+pi --list-models openrouter | grep kimi-k3
+```
+
+### `piloop run`
+
+| Option | Default | Meaning |
+|---|---|---|
+| `-m, --model` | pi's default | Model pattern or `provider/id` |
+| `--thinking` | pi's default | `off\|minimal\|low\|medium\|high\|xhigh\|max` |
+| `--plan` | `PLAN.md` | Plan file |
+| `--prompt` | `.loop-prompt.md` | Loop prompt file |
+| `-r, --run` | off | Start iterating immediately |
+| `--max-iterations` | 100 | Hard stop |
+| `--iteration-timeout` | 1800 | Seconds before an iteration is aborted |
+| `--max-stalls` | 3 | Stop after N iterations with no plan progress (0 disables) |
+| `--dialog-policy` | `cancel` | How to answer blocking extension dialogs |
+| `--session-dir`, `--no-session` | — | Passed through to pi |
+| `--tools`, `--exclude-tools` | — | Passed through to pi |
+| `--append-system-prompt`, `--skill` | — | Passed through to pi (repeatable) |
+| `--approve / --no-approve` | pi's default | Project-local file trust |
+| `--verbose`, `--log`, `--debug` | — | Diagnostics |
+
+Keys: `S` start · `Space` pause · `A` abort current iteration · `R` retry ·
+`Q` quit.
+
+## Plan format
+
+```markdown
+- [ ] a task to do
+- [x] a completed task
+- [MANUAL] something a human must do — never attempted, excluded from progress
+- [BLOCKED: reason] something the agent could not finish
+```
+
+The run ends when the agent appends, at the start of a line:
+
+```
+<plan-complete>summary of what was done</plan-complete>
+```
+
+## Agent skill (optional)
+
+`skills/piocloop-setup/` is an [Agent Skills](https://agentskills.io/specification)
+package you can copy into your own agent so it can set up piocloop runs for you —
+turning "for each of these 40 items, do X" into a correctly formatted `PLAN.md`
+and `.loop-prompt.md`. It is not loaded automatically; install it only if you
+want it:
+
+```bash
+cp -r skills/piocloop-setup ~/.pi/agent/skills/     # PI
+cp -r skills/piocloop-setup ~/.claude/skills/       # Claude Code
+```
+
+See [`skills/README.md`](skills/README.md) for other harnesses and for pointing
+`pi` at this checkout without copying.
+
+## Differences from pyocloop
+
+| | pyocloop | piocloop |
+|---|---|---|
+| Agent | OpenCode | PI |
+| Transport | HTTP + SSE on port 4096 | stdin/stdout JSONL |
+| "Iteration done" signal | `session.idle` SSE event | `agent_settled` RPC event |
+| Idle fallback | polled a field that does not exist | polls `get_state().isStreaming` |
+| Iteration timeout | none | `--iteration-timeout`, then abort, then respawn |
+| Iteration cap | none | `--max-iterations` |
+| Progress stalls | undetected | `STALLED` state |
+| Repeated errors | looped forever | error-streak circuit breaker |
+| Blocking agent dialogs | n/a | auto-answered (`--dialog-policy`) |
+| Tests | none | 119 |
+
+`-a/--agent` and `-p/--port` are gone: PI has no named-agent concept (use
+`--append-system-prompt` / `--skill`) and no server to bind.
+
+## Why the rewrite is more reliable
+
+[`ANALYSIS.md`](ANALYSIS.md) documents the pyocloop defects that motivated this
+port — verified against a live OpenCode server, not inferred. The two that
+caused silent hangs:
+
+* the server's stdout pipe was never drained after startup, so the OS pipe
+  eventually filled and the server blocked in `write()` and stopped serving;
+* the loop's idle wait had no deadline, and its polling fallback tested a
+  `session.idle` field that OpenCode does not return — so a single missed SSE
+  event hung the run forever.
+
+piocloop's design rules ([`DESIGN.md`](DESIGN.md) §4) are the direct response:
+**every pipe gets a drainer, every wait gets a deadline, and lack of progress is
+a first-class state.** The test suite mutation-checks the first two — removing
+either fix makes the corresponding regression test hang.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest tests/ -q
+```
+
+Tests run against `tests/fake_pi.py`, a stub agent — no network, no API key and
+no LLM required.
+
+## License
+
+MIT

piocloop-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+piocloop/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+piocloop/__main__.py,sha256=wcCrL4PjG51r5wVKqJhcoJPTLfHW0wNbD31DrUN0MWI,28
+piocloop/cli.py,sha256=m9psKUKxvrlv37p6XDVmOfcJvLoFUWXNSkq-yvd5pdE,8396
+piocloop/loop.py,sha256=qQumOGiKmvRe2geIly2X7ejIXSv7NR1W3AXqj-AePdA,17197
+piocloop/pi_client.py,sha256=Oi6TzEY0owQ2qCjoQUIez4xMMsApy_wJnohU3ijMF8w,16626
+piocloop/pi_events.py,sha256=qnt150xdiupXDC_z-7-UUldbyjk-xGQSzQaORXthbzg,10996
+piocloop/plan_parser.py,sha256=4BnuxlpdagABFq6OL8z_3nlM9vnOzlVF4Rlxl4Sto88,3829
+piocloop/tui.py,sha256=AIL-XYgnedisNBdOdnk4C4xnd22Ikjnix2EPo50h-OY,10322
+piocloop-0.1.0.dist-info/METADATA,sha256=dOpDJF1wEHuv62mTbVrIv01mmVExFzu2x06WJriTJKg,6966
+piocloop-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+piocloop-0.1.0.dist-info/entry_points.txt,sha256=7IGl9ourUvFjrgIkZ8_BQ0rchCDn4XGjf93UEWIpON0,44
+piocloop-0.1.0.dist-info/licenses/LICENSE,sha256=JScIJvidHoMUZJO2hkFY2O7aMAqgckAUyZxAyhf839M,1069
+piocloop-0.1.0.dist-info/RECORD,,

piocloop-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

piocloop-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+piloop = piocloop.cli:app

piocloop-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ronan Barzic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.