pcode 0.1.0__py3-none-any.whl

pcode/stall_log.py

@@ -0,0 +1,187 @@
+"""Log event-loop stalls in the terminal: the moments typed keys wait to be read.
+
+Keystrokes and model output share one asyncio loop. When synchronous work holds
+it, keys queue in the tty and land together once it frees, so typing seems to
+freeze and then a whole word pops up. A heartbeat task notes when the loop last
+ran; a watcher thread samples the loop thread's stack while the heartbeat is
+overdue and appends one JSON line per stall to `stalls.jsonl` in the state
+directory. A freeze with no stall logged at that time means the loop was free
+and the terminal itself held the frame back.
+
+A stall that holds the GIL throughout (garbage collection, one long C call)
+leaves the watcher no chance to sample, so it is logged from the late heartbeat
+alone, with no stacks; `gc_ms` says how much of it was collection.
+
+Records hold file names, line numbers, and function names, never arguments or
+locals, as `pcode.profiling` does.
+"""
+
+import asyncio
+import gc
+import json
+import os
+import sys
+import threading
+import time
+from collections import Counter
+from pathlib import Path
+
+THRESHOLD = 0.1
+"""Seconds late before a heartbeat counts as a stall; ~100 ms is where typing visibly lags."""
+BEAT = 0.05
+POLL = 0.02
+MAX_BYTES = 1_000_000
+"""The log is renamed to `stalls.jsonl.1` past this size, replacing the previous one."""
+FRAMES_KEPT = 30
+STACKS_KEPT = 3
+BUSY_SHARE = 0.1
+"""Process CPU per wall second above which an unsampled stall was work, not a suspended
+process (Ctrl+Z, a sleeping laptop), which stops the watcher thread as well. Low,
+because a busy process on a loaded machine is still a stall the user feels yet may
+get only a fraction of a core (a quarter was measured); a suspended one gets none."""
+
+
+def stall_log_path() -> Path:
+    state = Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local" / "state")
+    return state / "pcode" / "stalls.jsonl"
+
+
+def _where(frame) -> str:
+    path = frame.f_code.co_filename
+    for marker in ("site-packages/", "/src/"):
+        if marker in path:
+            path = path.rsplit(marker, 1)[1]
+            break
+    else:
+        path = os.path.basename(path)
+    return f"{path}:{frame.f_lineno} {frame.f_code.co_qualname}"
+
+
+def _idle(frame) -> bool:
+    """The event loop waiting for I/O, so it is late only because the process was
+    suspended. A blocking `subprocess.run` also waits in a selector, but not one
+    the loop called, and that is a stall."""
+    caller = frame.f_back
+    return (
+        frame.f_code.co_filename.endswith("selectors.py")
+        and caller is not None
+        and caller.f_code.co_name == "_run_once"
+    )
+
+
+class StallWatch:
+    """Run `heartbeat()` as a task on the loop to watch; `stop()` when done."""
+
+    def __init__(self, path: Path | None = None, *, threshold: float = THRESHOLD, context=None):
+        self.path = path or stall_log_path()
+        self.threshold = threshold
+        # Called from the watcher thread when a stall begins; must only read.
+        self.context = context
+        self._due: float | None = None
+        # The latest late beat, (due, how late it ran); beats that late are at
+        # least `threshold` apart, so the watcher sees every one.
+        self._late: tuple[float, float] | None = None
+        self._loop_thread: int | None = None
+        self._gc_started = 0.0
+        self._gc_seconds = 0.0
+        self._stop = threading.Event()
+        self._watcher: threading.Thread | None = None
+
+    async def heartbeat(self) -> None:
+        self._loop_thread = threading.get_ident()
+        if self._watcher is None:
+            gc.callbacks.append(self._gc)
+            self._watcher = threading.Thread(target=self._watch, name="stall-watch", daemon=True)
+            self._watcher.start()
+        try:
+            while True:
+                now = time.monotonic()
+                if self._due is not None and now - self._due >= self.threshold:
+                    self._late = (self._due, now - self._due)
+                self._due = now + BEAT
+                await asyncio.sleep(BEAT)
+        finally:
+            # Shutdown work after cancellation is not a stall.
+            self._due = None
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._watcher is not None:
+            self._watcher.join(timeout=1)
+        if self._gc in gc.callbacks:
+            gc.callbacks.remove(self._gc)
+
+    def _gc(self, phase: str, info: dict) -> None:
+        if phase == "start":
+            self._gc_started = time.monotonic()
+        else:
+            self._gc_seconds += time.monotonic() - self._gc_started
+
+    def _watch(self) -> None:
+        stalled = None  # The overdue `_due` being sampled.
+        samples: Counter[tuple[str, ...]] = Counter()
+        context: dict = {}
+        settled = None  # The late beat last accounted for.
+        # (wall, process CPU, GC seconds) at the last poll before the stall.
+        mark = (time.monotonic(), time.process_time(), self._gc_seconds)
+        while not self._stop.wait(POLL):
+            now = time.monotonic()
+            late = self._late
+            if late is not None and late[0] != settled:
+                settled = late[0]
+                wall, cpu, _ = mark
+                busy = time.process_time() - cpu >= BUSY_SHARE * (now - wall)
+                if samples or busy:
+                    self._write(late[1], samples, context or self._context(), mark)
+                stalled, samples, context = None, Counter(), {}
+            due = self._due
+            overdue = due is not None and now >= due + self.threshold
+            if overdue:
+                frame = sys._current_frames().get(self._loop_thread)
+                if frame is not None and not _idle(frame):
+                    if stalled is None:
+                        stalled, context = due, self._context()
+                    stack = []
+                    while frame is not None and len(stack) < FRAMES_KEPT:
+                        stack.append(_where(frame))
+                        frame = frame.f_back
+                    samples[tuple(stack)] += 1
+            # Hold the mark while overdue: the first poll after a GIL-held stall
+            # can run before the heartbeat does, with the loop already idle.
+            if stalled is None and not overdue:
+                mark = (now, time.process_time(), self._gc_seconds)
+        if samples:
+            # Stopped mid-stall: the loop is late by at least this much.
+            self._write(time.monotonic() - stalled, samples, context, mark)
+
+    def _context(self) -> dict:
+        if self.context is None:
+            return {}
+        try:
+            return dict(self.context())
+        except Exception:
+            return {}
+
+    def _write(self, late: float, samples: Counter, context: dict, mark: tuple) -> None:
+        record = {
+            "at": time.strftime("%Y-%m-%dT%H:%M:%S%z", time.localtime(time.time() - late)),
+            "pid": os.getpid(),
+            "stall_ms": round(late * 1000),
+            "gc_ms": round((self._gc_seconds - mark[2]) * 1000, 1),
+            "samples": sum(samples.values()),
+            **context,
+            # Innermost frame first: the top line is what was running. Empty
+            # when the stall held the GIL throughout.
+            "stacks": [
+                {"samples": count, "frames": list(stack)}
+                for stack, count in samples.most_common(STACKS_KEPT)
+            ],
+        }
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            if self.path.exists() and self.path.stat().st_size > MAX_BYTES:
+                os.replace(self.path, self.path.with_name(self.path.name + ".1"))
+            with self.path.open("a") as file:
+                file.write(json.dumps(record) + "\n")
+        except OSError:
+            pass  # Diagnostics must never disturb the session.

pcode/startup_input.py

@@ -0,0 +1,96 @@
+"""Return startup probe bytes through prompt_toolkit's normal input callback."""
+
+import asyncio
+import re
+from collections.abc import Callable
+from contextlib import contextmanager
+
+from prompt_toolkit.input.vt100 import Vt100Input
+from prompt_toolkit.input.vt100_parser import Vt100Parser
+
+# An OSC 11 background reply, or a mode 2031 color-scheme report (1 dark, 2 light).
+_REPLY = re.compile(r"\x1b\]11;[^\x07\x1b]{0,64}(?:\x07|\x1b\\)|\x1b\[\?997;([12])n")
+# A tail that may still become one of those: held until the next read. Only
+# characters a color reply contains, so typing after a truncated reply is
+# released at its first keystroke instead of being held for the flush to drop.
+_OPEN = re.compile(r"\x1b\]11;[0-9A-Fa-f:/rgb]{0,40}\x1b?|\x1b\[\?997;[12]?")
+_HEADERS = ("\x1b]11;", "\x1b[?997;")
+
+
+class TerminalReplyParser(Vt100Parser):
+    """Take terminal appearance replies out of the key stream, even split across reads.
+
+    The startup probe's reply can arrive after the editor starts, and later
+    queries (see `pcode.appearance`) always do. A terminated OSC 11 reply is
+    dropped even when its color can't be read; anything else, including an
+    overlong or unterminated reply, reaches prompt_toolkit as ordinary input.
+    """
+
+    def __init__(self, callback, on_theme: Callable[[str], None] | None = None):
+        super().__init__(callback)
+        self.pending = ""
+        self.on_theme = on_theme
+
+    def feed(self, data: str) -> None:
+        text, self.pending = self.pending + data, ""
+        while match := _REPLY.search(text):
+            super().feed(text[: match.start()])
+            text = text[match.end() :]
+            self._report(match)
+        hold = _held(text)
+        super().feed(text[:hold])
+        self.pending = text[hold:]
+
+    def _report(self, match: re.Match) -> None:
+        from pcode.theme import background_theme
+
+        if match.group(1):
+            detected = "dark" if match.group(1) == "1" else "light"
+        else:
+            detected = background_theme(match.group().encode())
+        if detected is not None and self.on_theme is not None:
+            self.on_theme(detected)
+
+    def flush(self) -> None:
+        text, self.pending = self.pending, ""
+        # An incomplete terminal reply must not hold the next prompt hostage.
+        # Anything shorter than a whole header (Escape, Alt-], Alt-[ then ?)
+        # is more likely typing, and must reach the parser.
+        if not text.startswith(_HEADERS):
+            super().feed(text)
+        super().flush()
+
+
+def _held(text: str) -> int:
+    """Where an unfinished reply may start in `text`; len(text) when none can."""
+    start = text.find("\x1b")
+    while start >= 0:
+        tail = text[start:]
+        if any(header.startswith(tail) for header in _HEADERS) or _OPEN.fullmatch(tail):
+            return start
+        start = text.find("\x1b", start + 1)
+    return len(text)
+
+
+class StartupInput(Vt100Input):
+    def __init__(self, stdin, pending: bytes, on_theme: Callable[[str], None] | None = None):
+        super().__init__(stdin)
+        self.pending = pending
+        self.vt100_parser = TerminalReplyParser(lambda key: self._buffer.append(key), on_theme)
+
+    @contextmanager
+    def attach(self, input_ready_callback):
+        with super().attach(input_ready_callback):
+            if self.pending:
+                # Use the application's callback so it also schedules its normal
+                # escape timeout. Feeding keys in pre_run would bypass that timer.
+                asyncio.get_running_loop().call_soon(input_ready_callback)
+            yield
+
+    def read_keys(self):
+        if self.pending:
+            # Keep the decoder shared with later reads, including split UTF-8.
+            text = self.stdin_reader._stdin_decoder.decode(self.pending)
+            self.pending = b""
+            self.vt100_parser.feed(text)
+        return super().read_keys()

pcode/steering.py

@@ -0,0 +1,27 @@
+"""Deliver pending steering between model requests; never skip tools."""
+
+from pydantic_ai.capabilities import AbstractCapability
+from pydantic_ai.messages import UserPromptPart
+
+
+class Steering(AbstractCapability):
+    def __init__(self, take_messages, has_messages=lambda: False):
+        self.take_messages = take_messages
+        # A peek that consumes nothing, for waits that should hand back early.
+        self.has_messages = has_messages
+
+    async def before_model_request(self, ctx, request_context):
+        # Append to the framework's request so tool results remain ahead of the
+        # new user input and the input is included in persisted message history.
+        for text in self.take_messages():
+            request_context.messages[-1].parts.append(UserPromptPart(text))
+        return request_context
+
+
+def steering_pending(ctx) -> bool:
+    """Inspect this run only, never a parent's or a concurrent side question's input."""
+    return any(
+        capability.has_messages()
+        for capability in ctx.capabilities.values()
+        if isinstance(capability, Steering)
+    )

pcode/stream_display.py

@@ -0,0 +1,188 @@
+"""Presentation-only event routing, shared by live streaming and offline benchmarks."""
+
+from rich.console import Console
+from rich.markdown import Markdown
+
+from pcode.runtime import (
+    CacheBust,
+    ChildPlan,
+    ChildText,
+    CommandOutput,
+    EditCompleted,
+    EditPreview,
+    Message,
+    PlanPreview,
+    PlanUpdated,
+    RunStatus,
+    TextDelta,
+    Thinking,
+    ThinkingDelta,
+    ToolStarted,
+    ToolSummary,
+)
+from pcode.terminal_notify import TabProgress, terminal_fd
+
+
+def present_events(events, *, activity, transcript, edits) -> None:
+    """Route live tool activity separately from permanent transcript writes."""
+    for event in events:
+        if isinstance(event, EditPreview):
+            activity.edit_previews.pop(event.call_id, None)
+            if event.path:
+                activity.edit_previews[event.call_id] = event
+        elif isinstance(event, EditCompleted):
+            edits.append(event)
+            activity.tools.record_edit(event)
+            transcript.edit(event)
+        elif isinstance(event, CommandOutput):
+            activity.command_outputs.pop(event.call_id, None)
+            activity.command_outputs[event.call_id] = event
+        elif isinstance(event, (ToolStarted, ToolSummary)):
+            activity.tools.record(event)
+            activity.workers.record(event)
+            if transcript.output is not None:
+                transcript.output.app.invalidate()
+            # The adapter's failed flag includes non-zero exits and tool retries.
+            if isinstance(event, ToolSummary):
+                activity.command_outputs.pop(event.call_id, None)
+                transcript.tool_result(event)
+        else:
+            transcript.events((event,))
+
+
+class PrintedReply:
+    """`--print`'s output: the reply on `stdout`, every other event through `present`.
+
+    The transcript is expected to be on stderr, so a pipe reading stdout sees
+    the reply alone. A terminal gets rendered Markdown; a pipe gets its source,
+    which is what a reader downstream can work with.
+    """
+
+    # Live-panel state, with no live panel to show it.
+    SKIPPED = (ThinkingDelta, RunStatus, PlanPreview, PlanUpdated, ChildPlan, ChildText)
+
+    def __init__(self, stdout, *, transcript, present) -> None:
+        self.stdout = stdout
+        self.transcript = transcript
+        self.present = present
+        reply = Console(file=stdout, theme=transcript.rich_theme)
+        # Rendering replaces token-by-token output with settled blocks, so it
+        # must not be chosen for a destination that cannot display it.
+        self.console = reply if reply.is_terminal else None
+        # Text streamed since the last settled message, so a turn that ends
+        # mid-block still prints what arrived.
+        self.block = ""
+
+    def tab_progress(self, activity) -> TabProgress:
+        """The terminal's tab progress, following `activity`, as the editor shows it.
+
+        Sent to the transcript's stream first: a reply piped elsewhere leaves
+        that one on the terminal. Neither being one sends nothing.
+        """
+        from pcode.preferences import load_preferences
+
+        fd = terminal_fd(self.transcript.console.file, self.stdout)
+        return TabProgress(activity, fd, load_preferences().get("terminal_progress", "auto"))
+
+    def write(self, markdown: str, *, streamed: bool = False) -> None:
+        """Settle one block of reply text; `streamed` means its source is already out."""
+        # The reply goes elsewhere, so close the run of calls it follows first.
+        self.transcript.settle_tools()
+        if self.console is not None:
+            self.console.print(Markdown(markdown, code_theme=self.transcript.code_theme))
+            self.console.print()
+            return
+        if not streamed:
+            self.stdout.write(markdown)
+        if not markdown.endswith("\n"):
+            self.stdout.write("\n")
+        self.stdout.write("\n")
+        self.stdout.flush()
+
+    def event(self, event) -> None:
+        if isinstance(event, TextDelta):
+            self.block += event.text
+            if self.console is None:
+                self.stdout.write(event.text)
+                self.stdout.flush()
+        elif isinstance(event, Message):
+            # Deltas usually carried this text already; a message without them
+            # (a structured result) is written whole.
+            self.write(
+                event.markdown or self.block,
+                streamed=self.console is None and bool(self.block),
+            )
+            self.block = ""
+        elif isinstance(event, Thinking):
+            self.transcript.events((event,))
+        elif not isinstance(event, self.SKIPPED):
+            self.present((event,))
+
+    def settle(self) -> None:
+        """Write out a block the turn ended (or failed, or retried) in the middle of."""
+        self.transcript.settle_tools()
+        if self.block:
+            self.write(self.block, streamed=self.console is None)
+            self.block = ""
+
+
+def present_stream_event(event, *, output, transcript, activity, present) -> None:
+    """Apply one display event without contacting a model or executing a tool."""
+    if isinstance(event, ThinkingDelta):
+        output.finish()
+        output.thinking_delta(event.text)
+        activity.think(event.text)
+    elif isinstance(event, Thinking):
+        output.finish_thinking(event.text)
+        if activity.thought_done and event.text:
+            # A block that arrived whole, with no deltas before it.
+            activity.think(event.text)
+        # Held on the thinking rows through the tool calls it explains; the
+        # next block, or the answer, replaces it.
+        activity.thought_done = True
+    elif isinstance(event, TextDelta):
+        output.finish_thinking()
+        output.delta(event.text)
+        activity.status = "Responding…"
+        if event.text.strip():  # An empty part start says nothing yet.
+            activity.forget_thought()
+    elif isinstance(event, CacheBust):
+        # A footer note, not a scrollback line: the session journal keeps the
+        # full notice (and its cause) for anyone diagnosing it later.
+        from pcode.cache_warnings import footer_label
+
+        activity.cache_note = footer_label(event.text)
+    elif isinstance(event, EditCompleted):
+        output.finish_thinking()
+        output.finish()
+        present((event,))
+    elif isinstance(event, (CommandOutput, EditPreview)):
+        present((event,))
+    elif isinstance(event, RunStatus):
+        activity.status = event.text
+    elif isinstance(event, PlanUpdated):
+        activity.plan = event.items
+    elif isinstance(event, PlanPreview):
+        activity.plan_preview = event.items
+    elif isinstance(event, ChildPlan):
+        activity.tools.record_plan(event.call_id, event.items)
+        activity.workers.record(event)
+    elif isinstance(event, ChildText):
+        # A worker's own prose feeds `/agents`; the transcript never shows it.
+        activity.workers.record(event)
+        return
+    elif isinstance(event, (ToolStarted, ToolSummary)):
+        output.finish_thinking()
+        # Settled calls land in scrollback, so prose must be committed first.
+        # Suppressed calls, such as successful planning, do not interrupt it.
+        if transcript.writes_tool_result(event):
+            output.finish()
+        present((event,))
+    elif isinstance(event, Message):
+        output.finish(event.markdown)
+        if event.markdown.strip():  # An answer that arrived whole, with no deltas before it.
+            activity.forget_thought()
+    else:
+        output.finish()
+        transcript.events((event,))
+    output.app.invalidate()