pi-sdk-web 0.3.13 → 0.4.1

package/dist/pi-bin/pii

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""pii - pi session helper.
+
+  pii list          Show all sessions (name, id, cwd), newest first
+  pii list -l       Also show session file paths
+  pii r <name>      Resume the session with the given name via `pi --session <id>`
+  pii r <name> --web [port]   Start web mode (default port 4080)
+  pii delete <name> Delete all sessions with the given name (asks for confirmation)
+"""
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(os.environ.get("PI_SESSION_DIR", Path.home() / ".pi" / "agent" / "sessions"))
+# Project root: prefer PI_WEB_DIR env, then script location if inside project,
+# then fall back to ~/pi-web (when installed globally as /usr/local/bin/pii).
+def _resolve_project_root() -> Path:
+    env_dir = os.environ.get("PI_WEB_DIR")
+    if env_dir:
+        return Path(env_dir).expanduser().resolve()
+    script_dir = Path(__file__).resolve().parent
+    # If this script lives in <project>/pii/, the parent has server/
+    if (script_dir.parent / "server").is_dir():
+        return script_dir.parent
+    # Common install location fallback
+    home_pi_web = Path.home() / "pi-web"
+    if (home_pi_web / "server").is_dir():
+        return home_pi_web
+    return script_dir.parent.parent
+
+PROJECT_ROOT = _resolve_project_root()
+
+
+def sessions():
+    rows = []
+    for d in ROOT.iterdir() if ROOT.is_dir() else []:
+        if not d.is_dir():
+            continue
+        for f in d.glob("*.jsonl"):
+            try:
+                lines = f.read_text(errors="replace").splitlines()
+            except OSError:
+                continue
+            header = None
+            name = ""
+            for line in lines:
+                if not line.strip():
+                    continue
+                try:
+                    e = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if header is None and e.get("type") == "session":
+                    header = e
+                elif e.get("type") == "session_info":
+                    n = e.get("name")
+                    name = n.strip() if isinstance(n, str) else ""
+            if header is None:
+                continue
+            try:
+                mtime = f.stat().st_mtime
+            except OSError:
+                mtime = 0
+            rows.append({"name": name, "id": header.get("id", ""), "cwd": header.get("cwd", ""), "file": str(f), "mtime": mtime})
+    rows.sort(key=lambda r: r["mtime"], reverse=True)
+    return rows
+
+
+def cmd_list(show_files=False):
+    rows = sessions()
+    if not rows:
+        print("(no sessions)")
+        return
+    width = max(len(r["name"] or "(unnamed)") for r in rows)
+    for r in rows:
+        line = f"{(r['name'] or '(unnamed)').ljust(width)}  {r['id']}  {r['cwd']}"
+        if show_files:
+            line += f"  {r['file']}"
+        print(line)
+
+
+def cmd_resume(name, web=False, port=None):
+    hits = [r for r in sessions() if r["name"] == name]
+    if not hits:
+        print(f"No session named '{name}'", file=sys.stderr)
+        names = sorted({r["name"] for r in sessions()})
+        if names:
+            print(f"Available names: {', '.join(names)}", file=sys.stderr)
+        sys.exit(1)
+    if len(hits) > 1:
+        print(f"Multiple sessions named '{name}', using most recent: {hits[0]['id']}", file=sys.stderr)
+    target = hits[0]
+    # cd into the session's project first, otherwise `pi --session` treats it
+    # as a foreign session and prompts to fork into the current directory.
+    cwd = target["cwd"]
+    if cwd and os.path.isdir(cwd):
+        os.chdir(cwd)
+    else:
+        print(f"Session cwd not found ({cwd}), keeping current directory", file=sys.stderr)
+
+    if web:
+        server_script = PROJECT_ROOT / "server" / "server.py"
+        if not server_script.is_file():
+            print(f"Web server not found: {server_script}", file=sys.stderr)
+            sys.exit(1)
+        cmd = [sys.executable, str(server_script), target["id"], target["cwd"], "--port", str(port or 4080)]
+        try:
+            sys.exit(subprocess.call(cmd))
+        except KeyboardInterrupt:
+            print()
+            sys.exit(130)
+    else:
+        try:
+            sys.exit(subprocess.call(["pi", "--session", target["id"]]))
+        except KeyboardInterrupt:
+            print()
+            sys.exit(130)
+
+
+def confirm(prompt):
+    try:
+        answer = input(prompt)
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return False
+    return answer.strip().lower() in ("y", "yes")
+
+
+def cmd_delete(name):
+    hits = [r for r in sessions() if r["name"] == name]
+    if not hits:
+        print(f"No session named '{name}'", file=sys.stderr)
+        names = sorted({r["name"] for r in sessions()})
+        if names:
+            print(f"Available names: {', '.join(names)}", file=sys.stderr)
+        sys.exit(1)
+    if len(hits) == 1:
+        print(f"Deleting session '{name}':")
+    else:
+        print(f"{len(hits)} sessions named '{name}':")
+    for r in hits:
+        print(f"  {r['id']}  {r['cwd']}  {r['file']}")
+        if not confirm(f"Delete {r['id']}? [y/N] "):
+            print(f"  Skipped {r['id']}")
+            continue
+        try:
+            os.remove(r["file"])
+            print(f"  Deleted {r['file']}")
+        except OSError as e:
+            print(f"  Failed to delete {r['file']}: {e}", file=sys.stderr)
+            sys.exit(1)
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(1)
+    cmd = sys.argv[1]
+    if cmd in ("help", "-h", "--help"):
+        print(__doc__)
+        return
+    if cmd == "list":
+        cmd_list("-l" in sys.argv[2:])
+    elif cmd in ("r", "resume"):
+        args = sys.argv[2:]
+        name = None
+        web = False
+        port = None
+        i = 0
+        while i < len(args):
+            arg = args[i]
+            if arg == "--web":
+                web = True
+                # If next arg is a number, treat it as the port
+                if i + 1 < len(args) and args[i + 1].isdigit():
+                    port = int(args[i + 1])
+                    i += 1
+            elif name is None:
+                name = arg
+            else:
+                print(f"unexpected argument: {arg}", file=sys.stderr)
+                print("usage: pii r <name> [--web [port]]", file=sys.stderr)
+                sys.exit(1)
+            i += 1
+
+        if not name:
+            print("usage: pii r <name> [--web [port]]", file=sys.stderr)
+            sys.exit(1)
+
+        if port is not None and not (1 <= port <= 65535):
+            print(f"Invalid port: {port} (must be 1-65535)", file=sys.stderr)
+            sys.exit(1)
+
+        cmd_resume(name, web, port)
+    elif cmd == "delete":
+        if len(sys.argv) < 3:
+            print("usage: pii delete <name>", file=sys.stderr)
+            sys.exit(1)
+        cmd_delete(sys.argv[2])
+    else:
+        print(f"unknown command: {cmd}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/dist/pi-bin/pii-cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * pii - pi session helper (RPC bridge launcher).
+ *
+ * This is the npm bin wrapper: pi-sdk-web ships the Python launcher
+ * (pi-bin/pii) plus the Python bridge (pi-bin/server/*.py, stdlib only).
+ * We spawn python3 with the bundled script and forward args/stdin/stdout/
+ * stderr, exiting with its code.
+ *
+ * Usage (same as the original script):
+ *   pii list [-l]
+ *   pii r <name> [--web [port]]
+ *   pii delete <name>
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const piiDir = dirname(fileURLToPath(import.meta.url)); // dist/pi-bin
+const piiScript = join(piiDir, "pii");
+if (!existsSync(piiScript)) {
+    console.error(`pii: bundled launcher not found at ${piiScript}`);
+    process.exit(1);
+}
+// Locate the Python interpreter (same resolution the original shell
+// used: python3 on PATH; fall back to the `python` alias).
+const pyCandidates = ["python3", "python"];
+let python = undefined;
+for (const candidate of pyCandidates) {
+    const probe = spawnSync(candidate, ["--version"], { stdio: "ignore" });
+    if (probe.status === 0) {
+        python = candidate;
+        break;
+    }
+}
+if (!python) {
+    console.error("pii: python3 not found on PATH (required to run the RPC bridge)");
+    process.exit(1);
+}
+// The bundled launcher resolves its project root via script location:
+// dist/pi-bin/pi-bin/pii -> parent resolves to dist/pi-bin, whose parent
+// is dist/ (no server/ there). The bridge lives at dist/pi-bin/server/,
+// so export PI_WEB_DIR pointing at pi-bin so _resolve_project_root() picks
+// the right server/ directory (its env_dir branch).
+const result = spawnSync(python, [piiScript, ...process.argv.slice(2)], {
+    env: { ...process.env, PI_WEB_DIR: piiDir },
+    stdio: "inherit",
+});
+process.exit(result.status ?? 1);

package/dist/pi-bin/server/rpc_client.py

@@ -0,0 +1,361 @@
+"""
+Pi RPC client for the pi-web server.
+
+Wraps a `pi --session <id> --mode rpc` subprocess, speaking the JSON-line protocol
+over stdin/stdout.
+
+Protocol (per pi-web-design.md and Pi source):
+- Commands sent to stdin as JSON lines: {"id": "...", "type": "prompt", ...}
+- Responses from stdout: {"id": "...", "type": "response", "command": ..., "success": true, "data": ...}
+- Events from stdout: {"type": "message_start", ...} etc.
+- Extension UI requests from stdout: {"type": "extension_ui_request", ...}
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import queue
+import subprocess
+import threading
+import time
+import uuid
+from typing import Any, Callable, Optional
+
+logger = logging.getLogger("rpc_client")
+
+
+class RpcClient:
+    """Manages a Pi RPC subprocess and provides a command/event interface."""
+
+    def __init__(
+        self,
+        session_id: str,
+        cwd: str,
+        *,
+        port: Optional[int] = None,
+        env: Optional[dict] = None,
+        on_event: Optional[Callable[[dict], None]] = None,
+        on_exit: Optional[Callable[[int | None], None]] = None,
+        pi_cmd: str = "pi",
+    ) -> None:
+        self.session_id = session_id
+        self.cwd = cwd
+        self.on_event = on_event
+        self.on_exit = on_exit
+        self.pi_cmd = pi_cmd
+        self._env = env
+
+        self.proc: subprocess.Popen | None = None
+        self._pending: dict[str, dict] = {}  # id -> holder dict (response stored here)
+        self._pending_events: dict[str, threading.Event] = {}  # id -> event
+        self._lock = threading.Lock()
+        self._reader_thread: threading.Thread | None = None
+        self._writer_lock = threading.Lock()
+        self._stopped = threading.Event()
+        self._stderr_lines: list[str] = []
+        self._ready_event = threading.Event()  # set once first event is seen
+        self._ready_lock = threading.Lock()
+        self._ready_seen = False
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def start(self) -> None:
+        """Start the pi RPC subprocess and begin reading stdout."""
+        cmd = [self.pi_cmd, "--session", self.session_id, "--mode", "rpc"]
+        env = dict(os.environ)
+        if self._env:
+            env.update(self._env)
+
+        self.proc = subprocess.Popen(
+            cmd,
+            cwd=self.cwd,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=0,  # unbuffered; line-buffered (1) breaks stdin writes to pi RPC
+            encoding="utf-8",
+            errors="replace",
+        )
+        self._reader_thread = threading.Thread(target=self._read_loop, daemon=True)
+        self._reader_thread.start()
+        self._start_stderr_reader()
+
+    def _start_stderr_reader(self) -> None:
+        """Drain stderr so the pi process never blocks. Surface to a logger."""
+        def run() -> None:
+            assert self.proc and self.proc.stderr
+            for line in self.proc.stderr:
+                line = line.rstrip()
+                self._stderr_lines.append(line)
+                if logger.isEnabledFor(logging.DEBUG):
+                    logger.debug("pi stderr: %s", line)
+        threading.Thread(target=run, daemon=True).start()
+
+    def wait_ready(
+        self,
+        timeout: float = 40.0,
+        interval: float = 2.0,
+        post_ready_delay: float = 0.5,
+    ) -> None:
+        """
+        Wait until the pi RPC process is ready to accept commands.
+
+        Empirically, Pi needs several seconds after emitting its first startup
+        events before it will reliably process stdin commands. So we:
+          1. wait for the first event on stdout (RPC loop is running), then
+          2. wait an additional ``post_ready_delay`` for startup to settle, then
+          3. poll get_state until it responds successfully.
+
+        Raises RuntimeError if the process exits or times out.
+        """
+        deadline = time.time() + timeout
+        eyes_open = self._ready_event.wait(timeout=timeout)
+        if not eyes_open:
+            raise RuntimeError(
+                f"Timed out waiting for Pi RPC to become ready. "
+                f"Stderr: {'; '.join(self._stderr_lines[-5:])}"
+            )
+
+        # Give Pi time to finish initializing after it starts emitting events.
+        time.sleep(post_ready_delay)
+
+        # Now poll get_state until it responds.
+        last_err = ""
+        while time.time() < deadline:
+            if self.proc is not None and self.proc.poll() is not None:
+                raise RuntimeError(
+                    f"Pi RPC process exited prematurely (code={self.proc.returncode}). "
+                    f"Stderr: {'; '.join(self._stderr_lines[-5:])}"
+                )
+            try:
+                self.send("get_state", timeout=max(1.0, interval))
+                logger.info("Pi RPC ready (session %s)", self.session_id)
+                return
+            except RuntimeError as e:
+                last_err = str(e)
+                time.sleep(interval)
+        raise RuntimeError(f"Timed out waiting for Pi RPC to be ready. {last_err}")
+
+    def stop(self) -> None:
+        """Terminate the pi subprocess."""
+        if self._stopped.is_set():
+            return
+        self._stopped.set()
+        if self.proc is None:
+            return
+
+        # Try graceful terminate, then escalate to kill
+        if self.proc.poll() is None:
+            self.proc.terminate()
+            try:
+                self.proc.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                self.proc.kill()
+                self.proc.wait(timeout=3)
+
+    # ------------------------------------------------------------------
+    # Sending commands
+    # ------------------------------------------------------------------
+
+    def send(self, cmd_type: str, timeout: float = 120.0, **params: Any) -> dict:
+        """
+        Send a command and wait for its response synchronously.
+
+        Throws an exception if the pi process exited or the command errored.
+        Returns the response dict on success.
+
+        ``timeout`` bounds how long we wait for the command response.
+        """
+        cmd_id = uuid.uuid4().hex
+        payload: dict[str, Any] = {"id": cmd_id, "type": cmd_type, **params}
+
+        done = threading.Event()
+        holder: dict = {}  # will hold the response; same reference stored in _pending
+        with self._lock:
+            # Store the holder dict directly (not a nested dict) so that
+            # _handle_response's writes to holder["response"] are visible here.
+            self._pending[cmd_id] = holder
+            # keep event separately for correlation in _handle_response
+            self._pending_events[cmd_id] = done
+
+        self._write(payload)
+
+        # Wait for response (bounded; agent may take a while to idle, but the
+        # response to most commands is immediate once the process is ready).
+        done.wait(timeout=timeout)
+        with self._lock:
+            self._pending.pop(cmd_id, None)
+            self._pending_events.pop(cmd_id, None)
+
+        response = holder.get("response")
+        if response is None:
+            raise RuntimeError(f"No response for command {cmd_type} (process may have exited)")
+
+        if not response.get("success", False):
+            raise RuntimeError(response.get("error", f"Command {cmd_type} failed"))
+        return response
+
+    def send_async(self, cmd_type: str, **params: Any) -> str:
+        """
+        Send a command without waiting for its response. Used for commands whose
+        response is handled by the event loop (e.g. prompt, which emits events
+        and an async response).
+
+        Returns the command id so callers can correlate if needed.
+        """
+        cmd_id = uuid.uuid4().hex
+        payload: dict[str, Any] = {"id": cmd_id, "type": cmd_type, **params}
+        self._write(payload)
+        return cmd_id
+
+    def _write(self, payload: dict) -> None:
+        if self.proc is None or self.proc.stdin is None or self.proc.poll() is not None:
+            raise RuntimeError("Pi RPC process is not running")
+        line = json.dumps(payload, ensure_ascii=False) + "\n"
+        with self._writer_lock:
+            self.proc.stdin.write(line)
+            self.proc.stdin.flush()
+
+    # ------------------------------------------------------------------
+    # Reading stdout
+    # ------------------------------------------------------------------
+
+    def _read_loop(self) -> None:
+        assert self.proc and self.proc.stdout
+        for line in self.proc.stdout:
+            if self._stopped.is_set():
+                break
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                data = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            # Mark readiness once the first event (e.g. extension_ui_request/setStatus)
+            # or response arrives on stdout. This signals that the Pi RPC loop has
+            # taken over and is ready to process commands.
+            with self._ready_lock:
+                if not self._ready_seen:
+                    self._ready_seen = True
+                    self._ready_event.set()
+                    logger.info("First stdout line received from pi (ready signal)")
+
+            if data.get("type") == "response":
+                self._handle_response(data)
+            else:
+                # Event or extension_ui_request -> broadcast
+                if self.on_event:
+                    try:
+                        self.on_event(data)
+                    except Exception:
+                        pass
+
+        # Process exited
+        if self.on_exit:
+            try:
+                self.on_exit(self.proc.returncode if self.proc else None)
+            except Exception:
+                pass
+
+    def _handle_response(self, data: dict) -> None:
+        cmd_id = data.get("id")
+        if not cmd_id:
+            return
+        with self._lock:
+            holder = self._pending.get(cmd_id)
+            done = self._pending_events.get(cmd_id)
+            logger.debug("handle_response id=%s in_pending=%s", cmd_id, holder is not None)
+        if holder is None:
+            # Async response for a command we don't track (e.g. prompt) - still broadcast
+            if self.on_event:
+                try:
+                    self.on_event(data)
+                except Exception:
+                    pass
+            return
+        # holder is the same dict reference returned by send(); store the response
+        # so send() can read it after the event fires.
+        holder["response"] = data
+        if done is not None:
+            done.set()
+
+
+# Convenience command wrappers
+class RpcCommands:
+    """Thin wrappers around common RPC commands."""
+
+    def __init__(self, client: RpcClient):
+        self._c = client
+
+    def get_state(self) -> dict:
+        return self._c.send("get_state")
+
+    def get_session_stats(self) -> dict:
+        return self._c.send("get_session_stats")
+
+    def get_messages(self) -> list:
+        resp = self._c.send("get_messages")
+        return resp.get("data", {}).get("messages", [])
+
+    def get_entries(self, since: str | None = None) -> dict:
+        params = {}
+        if since is not None:
+            params["since"] = since
+        resp = self._c.send("get_entries", **params)
+        return resp.get("data", {})
+
+    def prompt(self, message: str) -> str:
+        return self._c.send_async("prompt", message=message)
+
+    def abort(self) -> None:
+        self._c.send("abort")
+
+    def get_available_models(self) -> list:
+        resp = self._c.send("get_available_models")
+        return resp.get("data", {}).get("models", [])
+
+    def set_model(self, provider: str, model_id: str) -> dict:
+        return self._c.send("set_model", provider=provider, modelId=model_id)
+
+    def cycle_model(self) -> dict:
+        return self._c.send("cycle_model")
+
+    def get_available_thinking_levels(self) -> list:
+        resp = self._c.send("get_available_thinking_levels")
+        return resp.get("data", {}).get("levels", [])
+
+    def set_thinking_level(self, level: str) -> None:
+        self._c.send("set_thinking_level", level=level)
+
+    def cycle_thinking_level(self) -> dict:
+        return self._c.send("cycle_thinking_level")
+
+    def get_commands(self) -> list:
+        resp = self._c.send("get_commands")
+        return resp.get("data", {}).get("commands", [])
+
+    def bash(self, command: str) -> dict:
+        resp = self._c.send("bash", command=command)
+        return resp.get("data", {})
+
+    def compact(self, custom_instructions: str | None = None) -> dict:
+        params = {}
+        if custom_instructions:
+            params["customInstructions"] = custom_instructions
+        resp = self._c.send("compact", **params)
+        return resp.get("data", {})
+
+    def set_session_name(self, name: str) -> None:
+        self._c.send("set_session_name", name=name)
+
+    def extension_ui_response(self, response_id: str, **data) -> None:
+        """Send a response to a pending extension UI request (select/confirm/input/editor)."""
+        payload = {"type": "extension_ui_response", "id": response_id, **data}
+        self._c._write(payload)

package/dist/pi-bin/server/server.py

@@ -0,0 +1,467 @@
+"""
+pi-web server
+
+Bridges a browser (via WebSocket) to a Pi RPC subprocess.
+
+Run standalone:
+    python3 server.py <session_id> <cwd> [--port <port>]
+
+The pii script will eventually invoke this server after resolving the session
+name to a session id + cwd.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import socket
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Optional
+
+logging.basicConfig(level=logging.DEBUG)
+
+from rpc_client import RpcClient, RpcCommands
+from websocket import WebSocketConnection, WebSocketServer
+
+DEFAULT_PORT = 4080
+
+
+def _resolve_static_dir() -> Path:
+    """Find the static/ directory: the repo layout keeps it next to the
+    project root (server.py's parent.parent), while the npm package layout
+    ships it at dist/static (server.py lives at dist/pi-bin/server/). Search
+    upward so both layouts resolve."""
+    d = Path(__file__).resolve().parent
+    for _ in range(4):
+        candidate = d / "static"
+        if candidate.is_dir():
+            return candidate
+        d = d.parent
+    return Path(__file__).resolve().parent / "static"
+
+
+STATIC_DIR = _resolve_static_dir()
+
+
+class Peripheral:
+    """Holds the Pi RPC client and manages WebSocket clients."""
+
+    def __init__(self, session_id: str, cwd: str):
+        self.session_id = session_id
+        self.cwd = cwd
+        self.client = RpcClient(session_id, cwd, on_event=self._on_rpc_event, on_exit=self._on_rpc_exit)
+        self.commands = RpcCommands(self.client)
+        self._clients: set[WebSocketConnection] = set()
+        self._clients_lock = threading.Lock()
+        self._exit_error: Optional[str] = None
+        self._version = self._get_pi_version()
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def start(self) -> None:
+        self.client.start()
+        self.client.wait_ready()
+
+    def stop(self) -> None:
+        self.client.stop()
+
+    # ------------------------------------------------------------------
+    # WebSocket client management
+    # ------------------------------------------------------------------
+
+    def add_client(self, conn: WebSocketConnection) -> None:
+        with self._clients_lock:
+            self._clients.add(conn)
+        # Send initial state to the new client
+        self._send_initial_state(conn)
+
+    def remove_client(self, conn: WebSocketConnection) -> None:
+        with self._clients_lock:
+            self._clients.discard(conn)
+
+    def _broadcast(self, obj: object) -> None:
+        message = json.dumps(obj, ensure_ascii=False)
+        dead: list[WebSocketConnection] = []
+        with self._clients_lock:
+            for conn in list(self._clients):
+                try:
+                    conn.send_text(message)
+                except Exception:
+                    dead.append(conn)
+        for conn in dead:
+            self.remove_client(conn)
+
+    # ------------------------------------------------------------------
+    # RPC event -> broadcast
+    # ------------------------------------------------------------------
+
+    # Events after which footer stats should be refreshed (TUI does this too)
+    _STATS_REFRESH_EVENTS = {
+        "agent_settled",
+        "turn_end",
+        "tool_execution_end",
+        "compaction_end",
+        "entry_appended",
+        "session_info_changed",
+        "thinking_level_changed",
+    }
+
+    def _on_rpc_event(self, data: dict) -> None:
+        self._broadcast(data)
+        if data.get("type") in self._STATS_REFRESH_EVENTS:
+            self._schedule_stats_refresh()
+
+    def _schedule_stats_refresh(self) -> None:
+        """Fetch and broadcast latest session stats in a background thread.
+
+        This must not run in the RPC read-loop thread, because get_session_stats
+        is a synchronous command that would deadlock if issued from there.
+        """
+        def run() -> None:
+            try:
+                stats = self.commands.get_session_stats().get("data", {})
+                self._broadcast({"type": "stats", "data": stats})
+            except Exception:
+                pass
+        threading.Thread(target=run, daemon=True).start()
+
+    def _on_rpc_exit(self, code: int | None) -> None:
+        logging.warning("Pi RPC process exited with code=%s stderr=%s", code, self.client._stderr_lines[-5:])
+        self._exit_error = f"Pi RPC process exited (code={code})"
+        self._broadcast({"type": "pi_error", "error": self._exit_error})
+
+    # ------------------------------------------------------------------
+    # Initial state for new clients
+    # ------------------------------------------------------------------
+
+    def _send_initial_state(self, conn: WebSocketConnection) -> None:
+        """Send history + state to a newly connected browser client."""
+        try:
+            conn.send_json({"type": "state", "data": self._build_state()})
+            self._send_history(conn)
+        except RuntimeError as e:
+            conn.send_json({"type": "error", "error": str(e)})
+
+    def _build_state(self) -> dict:
+        """Build the full session state dict (model/thinking/stats/version/...)."""
+        state = self.commands.get_state()
+        data = state.get("data", {})
+        data["cwd"] = self._format_cwd_for_footer(self.cwd)
+        data["gitBranch"] = self._get_git_branch()
+        data["sessionStats"] = self.commands.get_session_stats().get("data", {})
+        data["version"] = self._version
+        data["commands"] = self.commands.get_commands()
+        return data
+
+    def _broadcast_state(self) -> None:
+        """Broadcast the full state after mutations (model/thinking/session name)."""
+        try:
+            self._broadcast({"type": "state", "data": self._build_state()})
+        except Exception:
+            pass
+
+    def _get_pi_version(self) -> str:
+        """Get the installed pi version once."""
+        try:
+            import subprocess
+
+            result = subprocess.run(
+                ["pi", "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if result.returncode == 0:
+                return result.stdout.strip()
+        except Exception:
+            pass
+        return ""
+
+    def _format_cwd_for_footer(self, cwd: str) -> str:
+        """Show home directory as ~ like the TUI footer."""
+        home = os.path.expanduser("~")
+        try:
+            rel = os.path.relpath(cwd, home)
+            if rel == ".":
+                return "~"
+            if not rel.startswith(".."):
+                return f"~/{rel}"
+        except Exception:
+            pass
+        return cwd
+
+    def _get_git_branch(self) -> str | None:
+        """Return the current git branch of the session cwd, if any."""
+        try:
+            import subprocess
+
+            result = subprocess.run(
+                ["git", "branch", "--show-current"],
+                cwd=self.cwd,
+                capture_output=True,
+                text=True,
+                timeout=3,
+            )
+            if result.returncode == 0:
+                branch = result.stdout.strip()
+                return branch or None
+        except Exception:
+            pass
+        return None
+
+    def _send_history(self, conn: WebSocketConnection) -> None:
+        try:
+            entries = self.commands.get_entries()
+            conn.send_json({"type": "history", "data": entries})
+        except RuntimeError as e:
+            conn.send_json({"type": "error", "error": str(e)})
+
+    # ------------------------------------------------------------------
+    # Handle incoming WebSocket messages (browser -> Pi)
+    # ------------------------------------------------------------------
+
+    def handle_client_message(self, conn: WebSocketConnection, raw: str) -> None:
+        logging.debug("WS message: %s", raw[:200])
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError:
+            conn.send_json({"type": "error", "error": "Invalid JSON"})
+            return
+
+        cmd_type = data.get("type")
+        if not cmd_type:
+            conn.send_json({"type": "error", "error": "Missing 'type'"})
+            return
+
+        try:
+            self._dispatch_command(cmd_type, data)
+        except RuntimeError as e:
+            conn.send_json({"type": "error", "error": str(e)})
+
+    def _dispatch_command(self, cmd_type: str, data: dict) -> None:
+        if cmd_type == "prompt":
+            message = data.get("message", "")
+            if not message:
+                raise RuntimeError("Missing 'message'")
+            self.commands.prompt(message)
+        elif cmd_type == "abort":
+            self.commands.abort()
+        elif cmd_type == "get_state":
+            pass  # broadcast via client init; ignore
+        elif cmd_type == "get_stats":
+            stats = self.commands.get_session_stats().get("data", {})
+            self._broadcast({"type": "stats", "data": stats})
+        elif cmd_type == "bash":
+            command = data.get("command", "")
+            if not command:
+                raise RuntimeError("Missing 'command'")
+            result = self.commands.bash(command)
+            self._broadcast({"type": "bash_result", "command": command, "data": result})
+        elif cmd_type == "cycle_model":
+            self.commands.cycle_model()
+            self._broadcast_state()
+        elif cmd_type == "set_model":
+            provider = data.get("provider")
+            model_id = data.get("modelId")
+            if not provider or not model_id:
+                raise RuntimeError("Missing 'provider' or 'modelId'")
+            self.commands.set_model(provider, model_id)
+            self._broadcast_state()
+        elif cmd_type == "get_available_models":
+            models = self.commands.get_available_models()
+            self._broadcast({"type": "models", "data": models})
+        elif cmd_type == "cycle_thinking_level":
+            self.commands.cycle_thinking_level()
+            self._broadcast_state()
+        elif cmd_type == "set_thinking_level":
+            level = data.get("level")
+            if not level:
+                raise RuntimeError("Missing 'level'")
+            self.commands.set_thinking_level(level)
+            self._broadcast_state()
+        elif cmd_type == "get_available_thinking_levels":
+            levels = self.commands.get_available_thinking_levels()
+            self._broadcast({"type": "thinking_levels", "data": levels})
+        elif cmd_type == "compact":
+            custom_instructions = data.get("customInstructions")
+            self.commands.compact(custom_instructions)
+        elif cmd_type == "set_session_name":
+            name = data.get("name", "")
+            if not name:
+                raise RuntimeError("Missing 'name'")
+            self.commands.set_session_name(name)
+            self._broadcast_state()
+        elif cmd_type == "extension_ui_response":
+            response_id = data.get("id")
+            if not response_id:
+                raise RuntimeError("Missing 'id'")
+            # Pass through all remaining fields (value/confirmed/cancelled)
+            extra = {k: v for k, v in data.items() if k not in ("type", "id")}
+            self.commands.extension_ui_response(response_id, **extra)
+        else:
+            raise RuntimeError(f"Unsupported command: {cmd_type}")
+
+
+class ServerContext:
+    """Shared state accessible from HTTP request handlers."""
+
+    def __init__(self, peripheral: Peripheral):
+        self.peripheral = peripheral
+        self.ws = WebSocketServer(self._on_ws_connection)
+
+    def _on_ws_connection(self, conn: WebSocketConnection, request_headers: dict) -> None:
+        pass
+
+
+class HTTPHandler(BaseHTTPRequestHandler):
+    """Serves static files and upgrades WebSocket connections."""
+
+    context: ServerContext = None  # type: ignore
+
+    def log_message(self, format: str, *args) -> None:
+        # Quiet by default
+        pass
+
+    def finish(self) -> None:
+        # For WebSocket upgrades we hand the raw socket to a WebSocketConnection
+        # and must NOT let BaseHTTPRequestHandler close it.
+        if getattr(self, "_ws_upgraded", False):
+            return
+        super().finish()
+
+    def _send_file(self, path: Path, content_type: str) -> None:
+        try:
+            data = path.read_bytes()
+            self.send_response(200)
+            self.send_header("Content-Type", content_type)
+            self.send_header("Content-Length", str(len(data)))
+            self.end_headers()
+            self.wfile.write(data)
+        except OSError:
+            self.send_error(404)
+
+    def do_GET(self) -> None:  # noqa: N802
+        # WebSocket upgrade
+        if self.headers.get("Upgrade", "").lower() == "websocket":
+            self._handle_ws_upgrade()
+            return
+
+        path = self.path.split("?")[0]
+        if path == "/":
+            path = "/index.html"
+
+        # Resolve static path safely
+        rel = path.lstrip("/")
+        file_path = (STATIC_DIR / rel).resolve()
+        if not str(file_path).startswith(str(STATIC_DIR.resolve())):
+            self.send_error(403)
+            return
+
+        if not file_path.exists():
+            self.send_error(404)
+            return
+
+        ext = file_path.suffix.lower()
+        content_type = {
+            ".html": "text/html; charset=utf-8",
+            ".css": "text/css; charset=utf-8",
+            ".js": "application/javascript; charset=utf-8",
+            ".json": "application/json; charset=utf-8",
+            ".svg": "image/svg+xml",
+            ".png": "image/png",
+            ".jpg": "image/jpeg",
+            ".ico": "image/x-icon",
+        }.get(ext, "application/octet-stream")
+        self._send_file(file_path, content_type)
+
+    def _handle_ws_upgrade(self) -> None:
+        ctx = self.server.ws_context
+        key = self.headers.get("Sec-WebSocket-Key")
+
+        import base64
+        import hashlib
+
+        accept = base64.b64encode(
+            hashlib.sha1((key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11").encode()).digest()
+        ).decode()
+
+        self.send_response(101)
+        self.send_header("Upgrade", "websocket")
+        self.send_header("Connection", "Upgrade")
+        self.send_header("Sec-WebSocket-Accept", accept)
+        self.end_headers()
+
+        # Take over the socket. We detach the underlying fd so that when the
+        # HTTP handler/server finishes it cannot close the live WebSocket.
+        fd = self.connection.detach()
+        sock = socket.socket(fileno=fd)
+        self._ws_upgraded = True
+        self.close_connection = True
+
+        peripheral = ctx.peripheral
+
+        def on_message(msg: str) -> None:
+            peripheral.handle_client_message(conn, msg)
+
+        def on_close() -> None:
+            peripheral.remove_client(conn)
+
+        conn = WebSocketConnection(sock, on_message, on_close)
+        ctx.clients.append(conn)
+        peripheral.add_client(conn)
+        conn.start_reading()
+
+
+class PiWebHTTPServer(ThreadingHTTPServer):
+    daemon_threads = True
+
+    def __init__(self, addr: tuple, handler_cls, peripheral: Peripheral):
+        super().__init__(addr, handler_cls)
+        self.ws_context = ServerContext(peripheral)
+        self.ws_context.clients = []
+        handler_cls.context = self.ws_context
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="pi-web server")
+    parser.add_argument("session_id", help="Pi session id")
+    parser.add_argument("cwd", help="Session working directory")
+    parser.add_argument("--port", type=int, default=DEFAULT_PORT, help="Port to bind (default: 4080)")
+    args = parser.parse_args()
+
+    if not (1 <= args.port <= 65535):
+        print(f"Invalid port: {args.port}", file=os.sys.stderr)
+        os.sys.exit(1)
+
+    if not os.path.isdir(args.cwd):
+        print(f"Working directory not found: {args.cwd}", file=os.sys.stderr)
+        os.sys.exit(1)
+
+    peripheral = Peripheral(args.session_id, args.cwd)
+
+    try:
+        httpd = PiWebHTTPServer(("127.0.0.1", args.port), HTTPHandler, peripheral)
+    except OSError as e:
+        print(f"Failed to bind 127.0.0.1:{args.port}: {e}", file=os.sys.stderr)
+        os.sys.exit(1)
+
+    peripheral.start()
+    print(f"server at http://127.0.0.1:{args.port}/", flush=True)
+
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        peripheral.stop()
+        httpd.server_close()
+
+
+if __name__ == "__main__":
+    main()

package/dist/pi-bin/server/websocket.py

@@ -0,0 +1,204 @@
+"""
+Simple WebSocket server implementation using only the Python standard library.
+
+Supports:
+- HTTP handshake (RFC 6455)
+- Text and binary frames
+- Ping/Pong keepalive
+- Fragmented message reassembly
+- Client close handling
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import socket
+import struct
+import threading
+from typing import Callable, Optional
+
+MAGIC = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+OP_CONT = 0x0
+OP_TEXT = 0x1
+OP_BINARY = 0x2
+OP_CLOSE = 0x8
+OP_PING = 0x9
+OP_PONG = 0xA
+
+
+class WebSocketError(Exception):
+    pass
+
+
+class WebSocketConnection:
+    """A single WebSocket client connection."""
+
+    def __init__(
+        self,
+        sock: socket.socket,
+        on_message: Callable[[str], None],
+        on_close: Callable[[], None],
+    ) -> None:
+        self.sock = sock
+        self.on_message = on_message
+        self.on_close = on_close
+        self._lock = threading.Lock()
+        self._closed = False
+        self._reader_thread: Optional[threading.Thread] = None
+
+    # ------------------------------------------------------------------
+    # Reading
+    # ------------------------------------------------------------------
+
+    def start_reading(self) -> None:
+        self._reader_thread = threading.Thread(target=self._read_loop, daemon=True)
+        self._reader_thread.start()
+
+    def _read_exact(self, n: int) -> bytes:
+        buf = b""
+        while len(buf) < n:
+            chunk = self.sock.recv(n - len(buf))
+            if not chunk:
+                raise WebSocketError("connection closed")
+            buf += chunk
+        return buf
+
+    def _read_loop(self) -> None:
+        try:
+            while not self._closed:
+                self._read_frame()
+        except (WebSocketError, socket.error, OSError):
+            pass
+        finally:
+            self.close()
+            if self.on_close:
+                try:
+                    self.on_close()
+                except Exception:
+                    pass
+
+    def _read_frame(self) -> None:
+        header = self._read_exact(2)
+        fin = (header[0] >> 7) & 0x01
+        opcode = header[0] & 0x0F
+        masked = (header[1] >> 7) & 0x01
+        length = header[1] & 0x7F
+
+        if length == 126:
+            length = struct.unpack(">H", self._read_exact(2))[0]
+        elif length == 127:
+            length = struct.unpack(">Q", self._read_exact(8))[0]
+
+        mask_key = self._read_exact(4) if masked else None
+        payload = self._read_exact(length)
+        if mask_key:
+            payload = bytes(
+                b ^ mask_key[i % 4] for i, b in enumerate(payload)
+            )
+
+        if opcode == OP_TEXT:
+            self.on_message(payload.decode("utf-8", errors="replace"))
+        elif opcode == OP_BINARY:
+            self.on_message(payload.decode("utf-8", errors="replace"))
+        elif opcode == OP_PING:
+            self._send_frame(OP_PONG, payload)
+        elif opcode == OP_PONG:
+            pass
+        elif opcode == OP_CLOSE:
+            self.close()
+        elif opcode == OP_CONT:
+            # For simplicity, treat continuation frames as pass-through text.
+            self.on_message(payload.decode("utf-8", errors="replace"))
+        else:
+            raise WebSocketError(f"unsupported opcode {opcode}")
+
+    # ------------------------------------------------------------------
+    # Writing
+    # ------------------------------------------------------------------
+
+    def _send_frame(self, opcode: int, payload: bytes) -> None:
+        if self._closed:
+            return
+        with self._lock:
+            header = bytearray()
+            header.append(0x80 | opcode)
+            length = len(payload)
+            if length < 126:
+                header.append(length)
+            elif length < 65536:
+                header.append(126)
+                header.extend(struct.pack(">H", length))
+            else:
+                header.append(127)
+                header.extend(struct.pack(">Q", length))
+            try:
+                self.sock.sendall(bytes(header) + payload)
+            except (socket.error, OSError):
+                self.close()
+
+    def send_text(self, message: str) -> None:
+        self._send_frame(OP_TEXT, message.encode("utf-8"))
+
+    def send_json(self, obj: object) -> None:
+        import json
+
+        self.send_text(json.dumps(obj, ensure_ascii=False))
+
+    # ------------------------------------------------------------------
+    # Close
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            self.sock.close()
+        except OSError:
+            pass
+
+
+class WebSocketServer:
+    """Minimal WebSocket server that handles one handshake per incoming connection."""
+
+    def __init__(
+        self,
+        handle_connection: Callable[[WebSocketConnection, dict], None],
+    ) -> None:
+        self.handle_connection = handle_connection
+
+    def upgrade(self, sock: socket.socket, request: bytes) -> Optional[WebSocketConnection]:
+        """Perform the WebSocket handshake and return a connection, or None on failure."""
+        try:
+            key = self._extract_key(request)
+            if not key:
+                sock.close()
+                return None
+
+            accept = base64.b64encode(
+                hashlib.sha1((key + MAGIC).encode()).digest()
+            ).decode()
+
+            response = (
+                "HTTP/1.1 101 Switching Protocols\r\n"
+                "Upgrade: websocket\r\n"
+                "Connection: Upgrade\r\n"
+                f"Sec-WebSocket-Accept: {accept}\r\n"
+                "\r\n"
+            )
+            sock.sendall(response.encode())
+        except (socket.error, OSError):
+            return None
+
+        conn = WebSocketConnection(sock, lambda msg: None, lambda: None)
+        return conn
+
+    @staticmethod
+    def _extract_key(request: bytes) -> Optional[str]:
+        text = request.decode("utf-8", errors="replace")
+        for line in text.split("\r\n"):
+            if line.lower().startswith("sec-websocket-key:"):
+                return line.split(":", 1)[1].strip()
+        return None

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "pi-sdk-web",
-  "version": "0.3.13",
+  "version": "0.4.1",
   "description": "Browser Web access for Pi (AI coding agent) via the Pi SDK - standalone module, zero modification to Pi itself",
   "type": "module",
   "bin": {
-    "pi-web": "./dist/cli.js"
+    "pi-web": "./dist/cli.js",
+    "pii": "./dist/pi-bin/pii-cli.js"
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json && node -e \"require('node:fs').cpSync('../static', 'dist/static', { recursive: true })\"",
+    "build": "tsc -p tsconfig.json && node -e \"require('node:fs').cpSync('../static', 'dist/static', { recursive: true }); require('node:fs').mkdirSync('dist/pi-bin', { recursive: true }); require('node:fs').renameSync('dist/pii-cli.js', 'dist/pi-bin/pii-cli.js'); require('node:fs').cpSync('../pii/pii', 'dist/pi-bin/pii'); require('node:fs').cpSync('../server', 'dist/pi-bin/server', { recursive: true, filter: (s) => !s.includes('__pycache__') })\"",
     "dev": "tsx src/cli.ts",
     "verify": "tsx src/verify-sdk.ts",
     "prepublishOnly": "npm run build"