pcode 0.1.0__py3-none-any.whl

pcode/host_protocol.py

@@ -0,0 +1,291 @@
+"""Wire format and rendezvous for session hosts.
+
+A session host is a headless pcode process that owns one conversation: the
+agent, its tools, and the journal. Terminals attach to it over a Unix socket,
+send prompts, and render the same `pcode.runtime` events a local turn yields.
+Closing a terminal only detaches it; the host keeps working.
+
+Messages are one JSON object per line. Every running host leaves
+`<id>.sock` and `<id>.json` in `host_dir()`; the JSON is what `/switch` lists
+without connecting to anything. A host that stopped itself for being idle with
+a turn nobody has seen leaves its entry in `stopped/<session id>.json`, so
+`/switch` still lists the session and resumes it.
+"""
+
+import asyncio
+import json
+import os
+import time
+from dataclasses import asdict, dataclass, field, fields
+from pathlib import Path
+
+from pcode.runtime import (
+    CacheBust,
+    ChildPlan,
+    ChildText,
+    CommandOutput,
+    EditCompleted,
+    EditPreview,
+    JobFinished,
+    Message,
+    PlanPreview,
+    PlanUpdated,
+    RunStatus,
+    TextDelta,
+    Thinking,
+    ThinkingDelta,
+    ToolStarted,
+    ToolSummary,
+)
+
+# Bumped on any incompatible message change. An editable install lets a host
+# outlive the code that started it, so a mismatch is refused, not guessed at.
+PROTOCOL = 2
+
+# asyncio's default line limit is 64 KiB, and one tool result or an attach
+# snapshot of a long conversation is far larger than that.
+LINE_LIMIT = 256 * 1024 * 1024
+
+# macOS caps a Unix socket path (sun_path) at 104 bytes including the NUL.
+SOCKET_PATH_MAX = 103
+
+EVENT_TYPES = {
+    cls.__name__: cls
+    for cls in (
+        Message,
+        ToolStarted,
+        ToolSummary,
+        JobFinished,
+        TextDelta,
+        ThinkingDelta,
+        Thinking,
+        RunStatus,
+        CacheBust,
+        PlanUpdated,
+        PlanPreview,
+        ChildPlan,
+        ChildText,
+        CommandOutput,
+        EditCompleted,
+        EditPreview,
+    )
+}
+
+
+def encode_event(event) -> dict:
+    name = type(event).__name__
+    if name not in EVENT_TYPES:
+        raise TypeError(f"{name} is not a pcode runtime event")
+    # Nested, not spread beside "kind" the way the journal writes events:
+    # EditPreview has a `kind` field of its own that would overwrite it.
+    return {"kind": name, "fields": asdict(event)}
+
+
+def decode_event(data: dict):
+    cls = EVENT_TYPES[data["kind"]]
+    values = data["fields"]
+    # Fields a newer host added are dropped rather than rejected.
+    return cls(**{f.name: values[f.name] for f in fields(cls) if f.name in values})
+
+
+def dumps(message: dict) -> bytes:
+    return (json.dumps(message, ensure_ascii=False) + "\n").encode("utf-8")
+
+
+async def read_message(reader: asyncio.StreamReader) -> dict | None:
+    """The next message, or None once the peer has gone."""
+    try:
+        line = await reader.readline()
+    except (ConnectionError, asyncio.IncompleteReadError):
+        return None
+    if not line:
+        return None
+    message = json.loads(line)
+    if not isinstance(message, dict):
+        raise ValueError("Session host message is not an object.")
+    return message
+
+
+def host_dir() -> Path:
+    if value := os.environ.get("PCODE_HOST_DIR"):
+        return Path(value).expanduser()
+    state = Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local" / "state")
+    return state / "pcode" / "hosts"
+
+
+def socket_path(identity: str, directory: Path | None = None) -> Path:
+    path = (directory or host_dir()) / f"{identity}.sock"
+    if len(os.fsencode(path)) > SOCKET_PATH_MAX:
+        raise OSError(
+            f"Socket path {path} is longer than a Unix socket allows; "
+            "set PCODE_HOST_DIR to a shorter directory."
+        )
+    return path
+
+
+@dataclass
+class HostEntry:
+    """What a running host says about itself, read without connecting to it."""
+
+    id: str
+    pid: int
+    model: str
+    workspace: str
+    protocol: int = PROTOCOL
+    session_id: str = ""
+    # "starting", "idle", or "working"; "stopped" for one `list_stopped` remembers.
+    state: str = "starting"
+    # The first prompt names the conversation; the last one says what it is doing.
+    title: str = ""
+    last_prompt: str = ""
+    started: float = field(default_factory=time.time)
+    updated: float = field(default_factory=time.time)
+    log: str = ""
+    # Finished turns, so a watcher polling every few seconds cannot miss a
+    # short one; and how the last of them ended.
+    turns: int = 0
+    outcome: str = ""
+    # Terminals showing it now, and whether a turn finished with none watching.
+    attached: int = 0
+    unseen: bool = False
+    # `code_fingerprint()` when the host started, to spot hosts on older code.
+    code: str = ""
+
+    @property
+    def socket(self) -> Path:
+        return socket_path(self.id)
+
+    def label(self) -> str:
+        return self.title or "(no prompt yet)"
+
+    def stale(self, current: str | None = None) -> bool:
+        """Running code older than what is installed now (an editable install moves).
+
+        A host with no fingerprint predates fingerprints, so it is older too.
+        """
+        return self.code != (current or code_fingerprint())
+
+
+def code_fingerprint() -> str:
+    """Changes whenever pcode's source on disk does: the newest source mtime."""
+    package = Path(__file__).parent
+    newest = max((path.stat().st_mtime_ns for path in package.rglob("*.py")), default=0)
+    return str(newest)
+
+
+def claim(name: str, directory: Path | None = None) -> bool:
+    """True for exactly one caller per `name`, across processes (one notification per turn)."""
+    directory = directory or host_dir()
+    try:
+        os.close(os.open(directory / f"{name}.claim", os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600))
+    except FileExistsError:
+        return False
+    except OSError:
+        return False
+    return True
+
+
+def _write(entry: HostEntry, target: Path) -> None:
+    target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    temporary = target.with_suffix(".json.tmp")
+    fd = os.open(temporary, os.O_CREAT | os.O_TRUNC | os.O_WRONLY, 0o600)
+    with os.fdopen(fd, "w") as file:
+        json.dump(asdict(entry), file)
+    os.replace(temporary, target)
+
+
+def _read(path: Path) -> HostEntry | None:
+    try:
+        data = json.loads(path.read_text())
+        return HostEntry(**{f.name: data[f.name] for f in fields(HostEntry) if f.name in data})
+    except (OSError, ValueError, TypeError):
+        return None
+
+
+def write_entry(entry: HostEntry, directory: Path | None = None) -> None:
+    entry.updated = time.time()
+    _write(entry, (directory or host_dir()) / f"{entry.id}.json")
+
+
+def remove_entry(identity: str, directory: Path | None = None) -> None:
+    directory = directory or host_dir()
+    paths = [directory / f"{identity}{suffix}" for suffix in (".json", ".sock", ".json.tmp")]
+    for path in [*paths, *directory.glob(f"{identity}-*.claim")]:
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            pass
+
+
+def _alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def list_hosts(directory: Path | None = None) -> list[HostEntry]:
+    """Running hosts, most recently active first; a dead host's files are removed."""
+    directory = directory or host_dir()
+    entries = []
+    if not directory.is_dir():
+        return entries
+    for path in directory.glob("*.json"):
+        if (entry := _read(path)) is None:
+            continue
+        if not _alive(entry.pid):
+            remove_entry(entry.id, directory)
+            continue
+        entries.append(entry)
+    return sorted(entries, key=lambda entry: entry.updated, reverse=True)
+
+
+def _stopped_path(session_id: str, directory: Path | None) -> Path:
+    return (directory or host_dir()) / "stopped" / f"{session_id}.json"
+
+
+def remember_stopped(entry: HostEntry, directory: Path | None = None) -> None:
+    """Keep a stopped host's unseen result listed until the session is opened again."""
+    if not entry.session_id:
+        return
+    stopped = HostEntry(**{**asdict(entry), "state": "stopped", "attached": 0})
+    stopped.updated = entry.updated  # When it finished, not when it stopped.
+    _write(stopped, _stopped_path(entry.session_id, directory))
+
+
+def forget_stopped(session_id: str, directory: Path | None = None) -> None:
+    _stopped_path(session_id, directory).unlink(missing_ok=True)
+
+
+def list_stopped(directory: Path | None = None) -> list[HostEntry]:
+    """Sessions whose host stopped before anyone saw their last turn, newest first.
+
+    One whose session runs in a host again is left out; that host forgets it.
+    """
+    directory = directory or host_dir()
+    running = {entry.session_id for entry in list_hosts(directory)}
+    entries = []
+    for path in (directory / "stopped").glob("*.json"):
+        if (entry := _read(path)) is not None and entry.session_id not in running:
+            entries.append(entry)
+    return sorted(entries, key=lambda entry: entry.updated, reverse=True)
+
+
+def find_host(selector: str, directory: Path | None = None) -> HostEntry:
+    """A running host by ID or session ID prefix."""
+    matches = [
+        entry
+        for entry in list_hosts(directory)
+        if entry.id.startswith(selector)
+        or (entry.session_id and entry.session_id.startswith(selector))
+    ]
+    if len(matches) != 1:
+        raise LookupError(
+            f"No running session host matches {selector!r}."
+            if not matches
+            else f"{selector!r} matches {len(matches)} session hosts; use more characters."
+        )
+    return matches[0]

pcode/host_ui.py

@@ -0,0 +1,225 @@
+"""The `/switch` chooser over running session hosts, and stopped ones nobody has seen."""
+
+import time
+from pathlib import Path
+
+from prompt_toolkit.application import Application
+from prompt_toolkit.document import Document
+from prompt_toolkit.filters import Always, has_focus
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.layout import Layout
+from prompt_toolkit.layout.containers import HSplit
+from prompt_toolkit.widgets import Label, TextArea
+
+from pcode.frame import Dialog
+from pcode.host_protocol import HostEntry, code_fingerprint
+from pcode.popup_ui import (
+    bind_list_paging,
+    fit_width,
+    popup_container,
+    popup_mouse,
+    popup_style,
+    steer_list_from_query,
+)
+from pcode.prefix_keys import PrefixKeys
+
+_TITLE_WIDTH = 40
+STATES = {"working": "● working", "idle": "○ idle   ", "starting": "◌ starting"}
+NEW = "✓ new    "
+
+
+def unseen(entry: HostEntry) -> bool:
+    """Finished while no terminal was showing it, and not looked at since."""
+    return entry.unseen and entry.state != "working"
+
+
+def ordered(entries: list[HostEntry]) -> list[HostEntry]:
+    """Finished-and-unseen first, then working, then the rest; newest activity first in each."""
+
+    def rank(entry: HostEntry) -> tuple[int, float]:
+        group = 0 if unseen(entry) else 1 if entry.state == "working" else 2
+        return group, -entry.updated
+
+    return sorted(entries, key=rank)
+
+
+def age(seconds: float) -> str:
+    if seconds < 60:
+        return "just now"
+    if seconds < 3600:
+        return f"{int(seconds // 60)}m ago"
+    if seconds < 86400:
+        return f"{int(seconds // 3600)}h ago"
+    return f"{int(seconds // 86400)}d ago"
+
+
+def host_row(
+    entry: HostEntry, current: str | None, now: float | None = None, *, code: str | None = None
+) -> str:
+    """One line per host; `code` is the installed fingerprint, to flag hosts on older code."""
+    now = time.time() if now is None else now
+    title = " ".join(entry.label().split())
+    if len(title) > _TITLE_WIDTH:
+        title = title[: _TITLE_WIDTH - 1] + "…"
+    marker = "▸" if entry.id == current else " "
+    state = NEW if unseen(entry) else STATES.get(entry.state, entry.state)
+    where = Path(entry.workspace).name
+    if entry.state == "stopped":
+        old = " · stopped"  # Enter starts it again on the code installed now.
+    else:
+        old = " · old code" if code is not None and entry.stale(code) else ""
+    return f"{marker} {state}  {title:<{_TITLE_WIDTH}}  {where} · {age(now - entry.updated)}{old}"
+
+
+def status_rows(entry: HostEntry, now: float | None = None, *, code: str | None = None):
+    """`/status` rows about the host itself, read from its status file."""
+    now = time.time() if now is None else now
+    terminals = f"{entry.attached} terminal{'s' if entry.attached != 1 else ''} attached"
+    rows = [("Host", f"{entry.id} · pid {entry.pid} · started {age(now - entry.started)}")]
+    rows.append(("Attached", terminals))
+    if entry.log:
+        rows.append(("Host log", entry.log))
+    if entry.stale(code):
+        rows.append(("Host code", "older than the pcode installed now; /restart updates it"))
+    return rows
+
+
+def hosts_dialog(
+    entries: list[HostEntry],
+    *,
+    current: str | None,
+    input=None,
+    output=None,
+    style=None,
+    key_prefix: str | None = None,
+):
+    """Returns ("attach", id), ("stop", id), ("new", None), or None when cancelled.
+
+    For a stopped entry "attach" means resume it, and "stop" forget it.
+    """
+    entries = ordered(entries)
+    code = code_fingerprint()
+    visible: list[HostEntry] = []
+    query = TextArea(height=1, prompt="Search: ", multiline=False)
+    choices = TextArea(
+        read_only=True,
+        wrap_lines=False,
+        scrollbar=True,
+        # Fit every row, not just the filtered ones, so searching does not resize the box.
+        width=fit_width([host_row(entry, current, code=code) for entry in entries]),
+    )
+    choices.window.cursorline = Always()
+    status = [""]
+    armed: list[str | None] = [None]
+    bindings = KeyBindings()
+
+    def selected() -> HostEntry | None:
+        row = choices.document.cursor_position_row
+        return visible[row] if row < len(visible) else None
+
+    def refresh():
+        previous = selected()
+        term = query.text.casefold()
+        visible[:] = [
+            entry
+            for entry in entries
+            if term in f"{entry.title} {entry.last_prompt} {entry.workspace} {entry.id}".casefold()
+        ]
+        index = next((i for i, entry in enumerate(visible) if entry is previous), 0)
+        lines = [host_row(entry, current, code=code) for entry in visible]
+        position = sum(len(line) + 1 for line in lines[:index])
+        choices.buffer.set_document(
+            Document("\n".join(lines) or "No matching sessions.", position), bypass_readonly=True
+        )
+
+    query.buffer.on_text_changed += lambda _: refresh()
+    steer_list_from_query(bindings, query, choices)
+    bind_list_paging(bindings, choices, has_focus(choices) | has_focus(query))
+
+    @bindings.add("enter", eager=True)
+    def accept(event):
+        entry = selected()
+        if entry is not None:
+            event.app.exit(result=("attach", entry.id))
+
+    shortcuts = PrefixKeys(key_prefix)
+    shortcuts.set_help(
+        lambda: [
+            ("Type", "Search in the search field"),
+            ("↑/↓", "Select session"),
+            ("PgUp/PgDn", "Page"),
+            ("Ctrl+U/D", "Half page"),
+            ("Enter", "Switch session"),
+            ("Tab/Shift+Tab", "Switch search / list"),
+            ("Delete", "Stop (or forget a stopped) session (twice; list focused)"),
+            ("Esc", "Clear search when focused, otherwise cancel"),
+            ("Ctrl+C", "Cancel"),
+        ]
+    )
+
+    @shortcuts.add("f", "Search")
+    def search(event):
+        event.app.layout.focus(query)
+
+    @shortcuts.add("n", "New session")
+    def new(event):
+        event.app.exit(result=("new", None))
+
+    @shortcuts.add("x", "Stop (twice)")
+    @bindings.add("delete", filter=has_focus(choices))
+    def stop(event):
+        entry = selected()
+        if entry is None:
+            return
+        if armed[0] == entry.id:
+            event.app.exit(result=("stop", entry.id))
+            return
+        armed[0] = entry.id
+        status[0] = (
+            f"Press {shortcuts.label('x')} again to remove {entry.label()[:40]} from this list. "
+            "/resume still opens it."
+            if entry.state == "stopped"
+            else f"Press {shortcuts.label('x')} again to stop {entry.id} ({entry.label()[:40]}). "
+            "Its turn is cancelled."
+        )
+
+    @bindings.add("escape", eager=True)
+    def escape(event):
+        if event.app.layout.has_focus(query) and query.text:
+            query.text = ""
+        else:
+            event.app.exit(result=None)
+
+    @bindings.add("c-c")
+    def cancel(event):
+        event.app.exit(result=None)
+
+    running = sum(entry.state != "stopped" for entry in entries)
+    working = sum(entry.state == "working" for entry in entries)
+    fresh = sum(unseen(entry) for entry in entries)
+    dialog = Dialog(
+        title="Sessions",
+        body=HSplit(
+            [
+                Label(
+                    f"{running} running · {working} working · {fresh} new · ▸ this terminal",
+                    dont_extend_height=True,
+                ),
+                query,
+                choices,
+                Label(lambda: status[0], dont_extend_height=True),
+                Label(shortcuts.summary),
+            ],
+            padding=1,
+        ),
+    )
+    refresh()
+    return Application(
+        layout=Layout(popup_container(dialog, shortcuts), focused_element=query),
+        key_bindings=shortcuts.key_bindings(bindings),
+        full_screen=True,
+        mouse_support=popup_mouse(shortcuts),
+        input=input,
+        output=output,
+        style=popup_style(style),
+    )

pcode/input_keys.py

@@ -0,0 +1,35 @@
+"""Normalize explicit terminal newline chords before vi sees Escape.
+
+prompt_toolkit 3.0.53 does not decode CSI-u Ctrl+J/Shift+Enter and maps
+xterm's modified Shift+Enter to ControlM (submit). Ctrl+/, the help key, gets
+the same treatment so it still reaches pcode as Ctrl+_ in those modes. Keep this narrow: we do
+not enable the Kitty keyboard protocol or claim general CSI-u support.
+"""
+
+from prompt_toolkit.input.ansi_escape_sequences import ANSI_SEQUENCES
+from prompt_toolkit.input.vt100_parser import _IS_PREFIX_OF_LONGER_MATCH_CACHE
+from prompt_toolkit.keys import Keys
+
+_NEWLINE_SEQUENCES = (
+    "\x1b[106;5u",  # CSI-u Ctrl+J
+    "\x1b[27;5;106~",  # xterm modifyOtherKeys Ctrl+J
+    "\x1b[13;2u",  # CSI-u Shift+Enter
+    "\x1b[27;2;13~",  # xterm modifyOtherKeys Shift+Enter
+)
+_HELP_SEQUENCES = (
+    "\x1b[47;5u",  # CSI-u Ctrl+/
+    "\x1b[27;5;47~",  # xterm modifyOtherKeys Ctrl+/
+)
+_ALIASES = {
+    **dict.fromkeys(_NEWLINE_SEQUENCES, Keys.ControlJ),
+    **dict.fromkeys(_HELP_SEQUENCES, Keys.ControlUnderscore),
+}
+
+
+def configure_newline_keys() -> None:
+    """Register process-wide VT100 aliases, including for pipe-input tests."""
+    if any(ANSI_SEQUENCES.get(sequence) != key for sequence, key in _ALIASES.items()):
+        ANSI_SEQUENCES.update(_ALIASES)
+        # The parser caches prefixes globally; an earlier prompt may already
+        # have classified these sequences as unknown. Recompute after updates.
+        _IS_PREFIX_OF_LONGER_MATCH_CACHE.clear()