pi-py-sdk 0.1.0__py3-none-any.whl

pi_py_agent/__init__.py

@@ -0,0 +1,8 @@
+"""pi_py_agent: a Python coding agent built on the pi-py-sdk RPC bridge."""
+
+from __future__ import annotations
+
+from .app import run_once, run_repl
+from .render import Renderer
+
+__all__ = ["run_repl", "run_once", "Renderer"]

pi_py_agent/app.py

@@ -0,0 +1,337 @@
+"""Interactive REPL and one-shot runner for the Python coding agent.
+
+Built entirely on :class:`pi_py_sdk.PiAgent` — the agent loop, tools, and model calls
+all run inside Pi via the RPC bridge.
+
+The REPL multiplexes a single stdin source across three consumers — idle prompts,
+mid-turn steering, and approval dialogs — using one persistent reader thread feeding a
+single async dispatch loop. A turn runs as a background task so the loop stays free to
+route steering/abort input while the agent streams. SIGINT aborts the active turn.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import signal
+import sys
+import threading
+from typing import Any
+
+from pi_py_sdk import ExtensionUIRequest, PiAgent, PiConfig, PiTimeoutError
+
+from .render import Renderer
+
+_HELP = """\
+Commands (when idle):
+  /help                  show this help
+  /model | /models       show or list models
+  /new                   start a fresh session
+  /state                 model, message count, queue modes
+  /compact               compact the conversation now
+  /fork [n]              list forkable messages, or fork message n
+  /clone                 clone the current branch into a new session
+  /exit | /quit          leave
+
+While the agent is responding, type to steer it:
+  <text>                 steer (delivered after the current tool call)
+  +<text>                queue a follow-up (delivered after the turn)
+  /abort                 stop the current turn
+Ctrl-C aborts the active turn; Ctrl-D (EOF) exits."""
+
+_YES = {"y", "yes"}
+
+
+def classify_turn_input(line: str) -> tuple[str, str]:
+    """Classify a line typed during an active turn into (action, text)."""
+    if line in ("/exit", "/quit"):
+        return ("exit", "")
+    if line in ("/abort", "/stop"):
+        return ("abort", "")
+    if line.startswith("+"):
+        return ("follow_up", line[1:].strip())
+    return ("steer", line)
+
+
+def parse_approval(request: ExtensionUIRequest, line: str) -> Any:
+    """Map a typed line to the value the SDK expects for a dialog request."""
+    method = request.method
+    if method == "confirm":
+        return line.strip().lower() in _YES
+    if method == "select":
+        options = request.options or []
+        stripped = line.strip()
+        if stripped.isdigit() and int(stripped) < len(options):
+            return options[int(stripped)]
+        return None
+    if method in ("input", "editor"):
+        return line if line else None
+    return None
+
+
+class LineReader:
+    """Reads stdin lines on a daemon thread into an asyncio queue.
+
+    A daemon thread (not the loop executor) is used so a blocked ``readline`` never
+    prevents interpreter exit. EOF enqueues a ``None`` sentinel.
+    """
+
+    def __init__(self) -> None:
+        self.queue: asyncio.Queue[str | None] = asyncio.Queue()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        self._loop = asyncio.get_event_loop()
+        self._thread = threading.Thread(target=self._read_loop, daemon=True)
+        self._thread.start()
+
+    def _read_loop(self) -> None:
+        while True:
+            line = sys.stdin.readline()
+            assert self._loop is not None
+            if line == "":  # EOF
+                self._loop.call_soon_threadsafe(self.queue.put_nowait, None)
+                return
+            self._loop.call_soon_threadsafe(self.queue.put_nowait, line.rstrip("\n"))
+
+    async def get(self) -> str | None:
+        return await self.queue.get()
+
+
+class Repl:
+    def __init__(self, agent: PiAgent, *, color: bool = True) -> None:
+        self.agent = agent
+        self.renderer = Renderer(color=color)
+        self.color = color
+        self.reader = LineReader()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._turn_task: asyncio.Task[None] | None = None
+        self._pending_approval: tuple[ExtensionUIRequest, asyncio.Future[Any]] | None = None
+        self._fork_list: list[dict[str, Any]] = []
+        self._exit = False
+
+    # -- output helpers ---------------------------------------------------
+
+    def _out(self, text: str) -> None:
+        sys.stdout.write(text)
+        sys.stdout.flush()
+
+    def _idle_prompt(self) -> None:
+        if not self._exit:
+            self._out("\nYou: ")
+
+    def _turn_active(self) -> bool:
+        return self._turn_task is not None and not self._turn_task.done()
+
+    # -- lifecycle --------------------------------------------------------
+
+    async def run(self, initial: str | None = None) -> None:
+        self._loop = asyncio.get_event_loop()
+        self.reader.start()
+        self.agent.on_ui_request(self._approve)
+        self._install_sigint()
+        self._out(f"pi-py · {await self._model_label()} · /help for commands\n")
+
+        if initial:
+            self._out(f"You: {initial}\n")
+            self._start_turn(initial)
+        else:
+            self._idle_prompt()
+
+        try:
+            while not self._exit:
+                line = await self.reader.get()
+                if line is None:  # EOF
+                    break
+                await self._dispatch(line)
+        finally:
+            self._teardown()
+
+    def _install_sigint(self) -> None:
+        try:
+            assert self._loop is not None
+            self._loop.add_signal_handler(signal.SIGINT, self._on_sigint)
+        except (NotImplementedError, RuntimeError):
+            pass  # e.g. Windows / non-main thread — fall back to default behavior
+
+    def _on_sigint(self) -> None:
+        if self._turn_active():
+            self._out("\n[aborting]\n")
+            asyncio.ensure_future(self.agent.abort())
+        else:
+            self._exit = True
+            self.reader.queue.put_nowait(None)  # unblock the dispatch loop
+
+    def _teardown(self) -> None:
+        if self._turn_task and not self._turn_task.done():
+            self._turn_task.cancel()
+        if self._pending_approval and not self._pending_approval[1].done():
+            self._pending_approval[1].set_result(None)
+
+    # -- input dispatch ---------------------------------------------------
+
+    async def _dispatch(self, line: str) -> None:
+        # 1) An open approval dialog claims the next line.
+        if self._pending_approval is not None:
+            request, future = self._pending_approval
+            if not future.done():
+                future.set_result(parse_approval(request, line))
+            return
+
+        # 2) During a turn, input steers the agent.
+        if self._turn_active():
+            await self._route_steering(line)
+            return
+
+        # 3) Idle: blank, command, or a new prompt.
+        stripped = line.strip()
+        if not stripped:
+            self._idle_prompt()
+            return
+        if stripped.startswith("/"):
+            if await self._command(stripped):
+                self._exit = True
+                return
+            self._idle_prompt()
+            return
+        self._start_turn(stripped)
+
+    async def _route_steering(self, line: str) -> None:
+        stripped = line.strip()
+        if not stripped:
+            return
+        action, text = classify_turn_input(stripped)
+        if action == "exit":
+            await self.agent.abort()
+            self._exit = True
+        elif action == "abort":
+            await self.agent.abort()
+            self._out("[aborting]\n")
+        elif action == "follow_up" and text:
+            await self.agent.follow_up(text)
+            self._out(f"[queued follow-up: {text}]\n")
+        elif action == "steer":
+            await self.agent.steer(text)
+            self._out(f"[steered: {text}]\n")
+
+    # -- turns ------------------------------------------------------------
+
+    def _start_turn(self, message: str) -> None:
+        self._turn_task = asyncio.ensure_future(self._run_turn(message))
+        self._turn_task.add_done_callback(self._after_turn)
+
+    async def _run_turn(self, message: str) -> None:
+        try:
+            async for event in self.agent.prompt_stream(message):
+                self.renderer.handle(event)
+        except asyncio.CancelledError:
+            raise
+        except PiTimeoutError as exc:
+            self._out(f"\n[timeout] {exc}\n")
+        except Exception as exc:  # keep the REPL alive on agent errors
+            self._out(f"\n[error] {exc}\n")
+
+    def _after_turn(self, task: asyncio.Task[None]) -> None:
+        if not task.cancelled():
+            task.exception()  # retrieve to avoid "never retrieved" warnings
+        self._idle_prompt()
+
+    # -- approvals --------------------------------------------------------
+
+    async def _approve(self, request: ExtensionUIRequest) -> Any:
+        assert self._loop is not None
+        future: asyncio.Future[Any] = self._loop.create_future()
+        self._pending_approval = (request, future)
+        self._print_approval_prompt(request)
+        try:
+            return await future
+        finally:
+            self._pending_approval = None
+
+    def _print_approval_prompt(self, request: ExtensionUIRequest) -> None:
+        self.renderer._break()  # ensure we start on a fresh line
+        if request.method == "confirm":
+            self._out(f"\n[approve] {request.title or 'Confirm'}? [y/N] ")
+        elif request.method == "select":
+            self._out(f"\n{request.title or 'Choose'}:\n")
+            for i, option in enumerate(request.options or []):
+                self._out(f"  {i}) {option}\n")
+            self._out("[select] number: ")
+        elif request.method in ("input", "editor"):
+            self._out(f"\n[{request.method}] {request.title or 'Value'}: ")
+
+    # -- commands ---------------------------------------------------------
+
+    async def _model_label(self) -> str:
+        state = await self.agent.get_state()
+        model = state.get("model") or {}
+        return f"{model.get('provider')}/{model.get('id')}"
+
+    async def _command(self, line: str) -> bool:
+        """Handle a slash command. Return True to exit the REPL."""
+        parts = line.split()
+        cmd, args = parts[0].lower(), parts[1:]
+        if cmd in ("/exit", "/quit"):
+            return True
+        if cmd == "/help":
+            self._out(_HELP + "\n")
+        elif cmd == "/model":
+            self._out(await self._model_label() + "\n")
+        elif cmd == "/models":
+            for m in await self.agent.get_available_models():
+                self._out(f"  {m.get('provider')}/{m.get('id')}\n")
+        elif cmd == "/new":
+            await self.agent.new_session()
+            self._out("[new session]\n")
+        elif cmd == "/state":
+            st = await self.agent.get_state()
+            self._out(
+                f"model={await self._model_label()} thinking={st.get('thinkingLevel')} "
+                f"messages={st.get('messageCount')} steering={st.get('steeringMode')} "
+                f"follow-up={st.get('followUpMode')}\n"
+            )
+        elif cmd == "/compact":
+            self._out("[compacting…]\n")
+            await self.agent.compact()
+            self._out("[compacted]\n")
+        elif cmd == "/clone":
+            result = await self.agent.clone()
+            self._out("[cloned]\n" if not result.get("cancelled") else "[clone cancelled]\n")
+        elif cmd == "/fork":
+            await self._fork(args)
+        else:
+            self._out(f"unknown command: {cmd} (try /help)\n")
+        return False
+
+    async def _fork(self, args: list[str]) -> None:
+        if args and args[0].isdigit():
+            index = int(args[0])
+            if not self._fork_list:
+                self._fork_list = await self.agent.get_fork_messages()
+            if 0 <= index < len(self._fork_list):
+                await self.agent.fork(self._fork_list[index]["entryId"])
+                self._out(f"[forked at message {index}]\n")
+            else:
+                self._out(f"no message {index}; run /fork to list\n")
+            return
+        self._fork_list = await self.agent.get_fork_messages()
+        if not self._fork_list:
+            self._out("[no forkable messages]\n")
+            return
+        self._out("Forkable messages (use /fork <n>):\n")
+        for i, msg in enumerate(self._fork_list):
+            text = (msg.get("text") or "").replace("\n", " ")
+            self._out(f"  {i}) {text[:80]}\n")
+
+
+async def run_repl(config: PiConfig, *, color: bool = True, initial: str | None = None) -> None:
+    async with PiAgent(config=config) as agent:
+        await Repl(agent, color=color).run(initial=initial)
+
+
+async def run_once(config: PiConfig, message: str, *, color: bool = True) -> None:
+    renderer = Renderer(color=color)
+    async with PiAgent(config=config) as agent:
+        async for event in agent.prompt_stream(message):
+            renderer.handle(event)
+        print()

pi_py_agent/cli.py

@@ -0,0 +1,53 @@
+"""`pi-py` command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+from pi_py_sdk import PiConfig
+
+from .app import run_once, run_repl
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pi-py",
+        description="A Python coding agent built on the Pi RPC bridge.",
+    )
+    parser.add_argument("prompt", nargs="*", help="optional prompt; omit for an interactive REPL")
+    parser.add_argument("--model", help="model id, e.g. anthropic/claude-sonnet-4-20250514")
+    parser.add_argument("--provider", help="provider override")
+    parser.add_argument("--cwd", help="working directory for the agent")
+    parser.add_argument("--session-dir", help="directory for session persistence")
+    parser.add_argument("--no-session", action="store_true", help="disable session persistence")
+    parser.add_argument("--print", action="store_true", help="one-shot: print the response and exit")
+    parser.add_argument("--no-color", action="store_true", help="disable ANSI colors")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    config = PiConfig(
+        model=args.model,
+        provider=args.provider,
+        cwd=args.cwd,
+        session_dir=args.session_dir,
+        no_session=args.no_session,
+    )
+    color = sys.stdout.isatty() and not args.no_color
+    prompt = " ".join(args.prompt).strip()
+
+    try:
+        if prompt and args.print:
+            asyncio.run(run_once(config, prompt, color=color))
+        else:
+            asyncio.run(run_repl(config, color=color, initial=prompt or None))
+    except KeyboardInterrupt:
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pi_py_agent/render.py

@@ -0,0 +1,137 @@
+"""Render streamed agent events to a terminal.
+
+Pure and testable: construct with a ``write`` callable and a ``color`` flag, then feed
+it :class:`~pi_py_sdk.Event` objects. State is tracked only to insert sensible line
+breaks between assistant text, thinking, and tool activity.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from pi_py_sdk import Event
+
+_RESET = "\033[0m"
+_DIM = "\033[2m"
+_CYAN = "\033[36m"
+_YELLOW = "\033[33m"
+_GREEN = "\033[32m"
+_RED = "\033[31m"
+
+# Keys whose value best summarizes a tool call, in priority order.
+_ARG_KEYS = ("command", "path", "file_path", "pattern", "query", "url")
+# Keys that typically carry a tool's textual result, in priority order.
+_RESULT_KEYS = ("output", "stdout", "content", "text", "result", "message")
+
+_PREVIEW_LINES = 8
+_PREVIEW_WIDTH = 100
+
+
+def _summarize_args(args: Any, limit: int = 80) -> str:
+    if isinstance(args, dict):
+        for key in _ARG_KEYS:
+            if key in args and args[key] is not None:
+                value = str(args[key]).replace("\n", " ")
+                return value if len(value) <= limit else value[: limit - 1] + "…"
+    return ""
+
+
+def _result_text(result: Any) -> str:
+    """Best-effort extraction of human-readable text from a tool result."""
+    if result is None:
+        return ""
+    if isinstance(result, str):
+        return result
+    if isinstance(result, dict):
+        for key in _RESULT_KEYS:
+            value = result.get(key)
+            if isinstance(value, str) and value.strip():
+                return value
+            if isinstance(value, list):  # content-block array
+                parts = [
+                    item["text"]
+                    for item in value
+                    if isinstance(item, dict) and isinstance(item.get("text"), str)
+                ]
+                if parts:
+                    return "\n".join(parts)
+    return ""
+
+
+class Renderer:
+    def __init__(self, write: Callable[[str], Any] | None = None, *, color: bool = True):
+        if write is None:
+            import sys
+
+            write = sys.stdout.write
+        self._write = write
+        self.color = color
+        self._mode: str | None = None  # "text" | "thinking" | None
+
+    def _c(self, code: str, text: str) -> str:
+        return f"{code}{text}{_RESET}" if self.color else text
+
+    def handle(self, event: Event) -> None:
+        kind = event.type
+        if kind == "message_update":
+            self._on_message_update(event)
+        elif kind == "tool_execution_start":
+            self._break()
+            name = getattr(event, "toolName", None) or "tool"
+            summary = _summarize_args(getattr(event, "args", None))
+            line = self._c(_CYAN, f"→ {name}") + (f" {summary}" if summary else "")
+            self._write(line + "\n")
+        elif kind == "tool_execution_end":
+            mark = self._c(_RED, "✗") if getattr(event, "isError", False) else self._c(_GREEN, "✓")
+            self._write(f"  {mark}\n")
+            self._write_result_preview(getattr(event, "result", None))
+        elif kind == "queue_update":
+            steering = len(getattr(event, "steering", None) or [])
+            follow_up = len(getattr(event, "followUp", None) or [])
+            if steering or follow_up:
+                self._break()
+                self._write(self._c(_DIM, f"[queued: steering={steering} follow-up={follow_up}]") + "\n")
+        elif kind == "auto_retry_start":
+            self._break()
+            a, m = getattr(event, "attempt", "?"), getattr(event, "maxAttempts", "?")
+            self._write(self._c(_YELLOW, f"[retrying {a}/{m}…]") + "\n")
+        elif kind == "compaction_start":
+            self._break()
+            self._write(self._c(_YELLOW, "[compacting context…]") + "\n")
+        elif kind == "agent_end":
+            self._break()
+
+    def _on_message_update(self, event: Event) -> None:
+        ame = getattr(event, "assistantMessageEvent", None)
+        if ame is None or not getattr(ame, "delta", None):
+            return
+        if ame.type == "text_delta":
+            if self._mode != "text":
+                if self._mode == "thinking":
+                    self._write("\n")
+                self._mode = "text"
+            self._write(ame.delta)
+        elif ame.type == "thinking_delta":
+            if self._mode != "thinking":
+                if self._mode == "text":
+                    self._write("\n")
+                self._write(self._c(_DIM, "(thinking) "))
+                self._mode = "thinking"
+            self._write(self._c(_DIM, ame.delta))
+
+    def _write_result_preview(self, result: Any) -> None:
+        text = _result_text(result).strip("\n")
+        if not text:
+            return
+        lines = text.split("\n")
+        for line in lines[:_PREVIEW_LINES]:
+            clipped = line if len(line) <= _PREVIEW_WIDTH else line[: _PREVIEW_WIDTH - 1] + "…"
+            self._write(self._c(_DIM, f"  │ {clipped}") + "\n")
+        if len(lines) > _PREVIEW_LINES:
+            extra = len(lines) - _PREVIEW_LINES
+            self._write(self._c(_DIM, f"  │ … (+{extra} more lines)") + "\n")
+
+    def _break(self) -> None:
+        if self._mode is not None:
+            self._write("\n")
+            self._mode = None

pi_py_sdk/__init__.py

@@ -0,0 +1,104 @@
+"""pi-py-sdk: Python SDK for the Pi coding agent over its RPC bridge.
+
+Drives ``pi --mode rpc`` (the well-tested ``pi-agent-core`` runtime) as a subprocess,
+exposing an async Python API. No agent logic is reimplemented in Python.
+"""
+
+from __future__ import annotations
+
+from .client import PiAgent, UiHandler, UiResult
+from .config import PiConfig
+from .sync import PiAgentSync
+from .errors import (
+    PiCommandError,
+    PiError,
+    PiNotStartedError,
+    PiProcessError,
+    PiTimeoutError,
+)
+from .protocol import (
+    DIALOG_METHODS,
+    AgentEndEvent,
+    AgentStartEvent,
+    AssistantMessage,
+    AssistantMessageEvent,
+    AutoRetryEndEvent,
+    AutoRetryStartEvent,
+    BashExecutionMessage,
+    CompactionEndEvent,
+    CompactionStartEvent,
+    Event,
+    ExtensionErrorEvent,
+    ExtensionUIRequest,
+    ImageContent,
+    MessageEndEvent,
+    MessageStartEvent,
+    MessageUpdateEvent,
+    QueueUpdateEvent,
+    Response,
+    SessionInfoChangedEvent,
+    TextContent,
+    ThinkingContent,
+    ThinkingLevelChangedEvent,
+    ToolCall,
+    ToolExecutionEndEvent,
+    ToolExecutionStartEvent,
+    ToolExecutionUpdateEvent,
+    ToolResultMessage,
+    TurnEndEvent,
+    UserMessage,
+    message_text,
+    parse_event,
+    parse_message,
+    parse_messages,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PiAgent",
+    "PiAgentSync",
+    "PiConfig",
+    "UiHandler",
+    "UiResult",
+    "PiError",
+    "PiNotStartedError",
+    "PiProcessError",
+    "PiTimeoutError",
+    "PiCommandError",
+    "Event",
+    "AgentStartEvent",
+    "AgentEndEvent",
+    "AssistantMessageEvent",
+    "MessageStartEvent",
+    "MessageUpdateEvent",
+    "MessageEndEvent",
+    "TurnEndEvent",
+    "ToolExecutionStartEvent",
+    "ToolExecutionUpdateEvent",
+    "ToolExecutionEndEvent",
+    "QueueUpdateEvent",
+    "CompactionStartEvent",
+    "CompactionEndEvent",
+    "AutoRetryStartEvent",
+    "AutoRetryEndEvent",
+    "SessionInfoChangedEvent",
+    "ThinkingLevelChangedEvent",
+    "ExtensionErrorEvent",
+    "ExtensionUIRequest",
+    "DIALOG_METHODS",
+    "Response",
+    "parse_event",
+    "TextContent",
+    "ThinkingContent",
+    "ImageContent",
+    "ToolCall",
+    "UserMessage",
+    "AssistantMessage",
+    "ToolResultMessage",
+    "BashExecutionMessage",
+    "parse_message",
+    "parse_messages",
+    "message_text",
+    "__version__",
+]

pi_py_sdk/_discovery.py

@@ -0,0 +1,41 @@
+"""Locate the Pi runtime.
+
+Resolution order (confirmed project decision):
+  1. An explicit ``bin`` (path or command name), if provided.
+  2. ``pi`` discovered on ``PATH``.
+  3. ``npx --yes @earendil-works/pi-coding-agent@<pinned>`` as a fallback.
+"""
+
+from __future__ import annotations
+
+import shutil
+
+from .errors import PiProcessError
+
+#: Pinned Pi package + version this SDK was developed and tested against.
+PINNED_PI_PACKAGE = "@earendil-works/pi-coding-agent"
+PINNED_PI_VERSION = "0.79.9"
+
+
+def resolve_pi_command(bin: str | None = None) -> list[str]:
+    """Return the argv prefix that launches Pi (before ``--mode rpc`` args).
+
+    Raises:
+        PiProcessError: if neither an explicit/`PATH` binary nor ``npx`` is available.
+    """
+    if bin:
+        resolved = shutil.which(bin) or bin
+        return [resolved]
+
+    on_path = shutil.which("pi")
+    if on_path:
+        return [on_path]
+
+    npx = shutil.which("npx")
+    if npx:
+        return [npx, "--yes", f"{PINNED_PI_PACKAGE}@{PINNED_PI_VERSION}"]
+
+    raise PiProcessError(
+        "Could not find the `pi` binary on PATH and `npx` is unavailable. "
+        f"Install it with `npm i -g {PINNED_PI_PACKAGE}` (or ensure Node/npx is installed)."
+    )