pcode 0.1.0__py3-none-any.whl

pcode/remote_print.py

@@ -0,0 +1,125 @@
+"""`pcode --attach HOST --print PROMPT`: one message or command for a running host, no editor.
+
+It attaches like a terminal, sends the message (queued behind whatever the host
+is already doing) or the slash command, writes what that produces the way a
+local `--print` writes its turn (the reply on stdout, the rest on stderr), and
+detaches. The host keeps running, and every other terminal sees the turn too.
+
+The host tells this caller alone when its message's turn starts, or that it
+was dropped, in order with everything else it shows (`pcode.host._Owner`), so
+a turn another terminal started, or one already running, is never mistaken
+for it. Notes other terminals cause while it runs are written all the same.
+"""
+
+import asyncio
+import sys
+
+from pcode.controller import TERMINAL_COMMANDS
+from pcode.gateway import HeadlessView, attached, host_call, submit
+from pcode.host_protocol import HostEntry
+from pcode.remote import stop_entry
+from pcode.runtime import PlanUpdated
+from pcode.stream_display import PrintedReply
+
+
+class PrintView(HeadlessView):
+    """The view a `--print` attach gives the host: its own turn or command, written out."""
+
+    def __init__(self, transcript, reply: PrintedReply) -> None:
+        super().__init__()
+        self.transcript = transcript
+        self.reply = reply
+        # Busy while the host works, on this message or the turns ahead of it.
+        self.tab = reply.tab_progress(self.activity)
+
+    def gone(self, *, stopped: bool) -> None:
+        if self.ended:
+            self.transcript.note("The session ended, and its host stopped.")
+        else:
+            self.transcript.error(
+                "The session host stopped before this finished."
+                if stopped
+                else "The session host went away."
+            )
+
+    def event(self, event) -> None:
+        self.tab.turn_event()
+        if isinstance(event, PlanUpdated):
+            self.activity.plan = event.items
+        self.reply.event(event)
+
+    def retry(self, text: str) -> None:
+        self.tab.turn_retry()
+        self.reply.settle()
+        self.transcript.note(text)
+
+    def settle(self) -> None:
+        self.reply.settle()
+
+    def scrollback(self, name: str, args: tuple, kwargs: dict) -> None:
+        getattr(self.transcript, name)(*args, **kwargs)
+
+
+async def print_to_host(entry: HostEntry, prompt: str, *, transcript, present, stdout=None) -> bool:
+    """Send `prompt` to the host at `entry`, write what it produces; returns whether it worked."""
+    prompt = prompt.strip()
+    name = prompt.split(maxsplit=1)[0] if prompt.startswith("/") else ""
+    if name == "/stop":
+        return await _stop(entry, prompt, transcript)
+    if name in TERMINAL_COMMANDS:
+        transcript.error(f"{name} needs the interactive terminal: pcode --attach {entry.id}")
+        return False
+    reply = PrintedReply(
+        sys.stdout if stdout is None else stdout, transcript=transcript, present=present
+    )
+    view = PrintView(transcript, reply)
+    async with view.tab.shown():
+        return await _send(entry, prompt, name, view)
+
+
+async def _send(entry: HostEntry, prompt: str, name: str, view: PrintView) -> bool:
+    """Attach, send the message or command, and write what it produces."""
+    transcript, reply = view.transcript, view.reply
+    async with attached(entry, view) as controller:
+        if controller.startup_error is not None:
+            transcript.error(str(controller.startup_error), title="Agent startup failed")
+            return False
+        if name:
+            view.command = True
+            ran = await host_call(controller, "run", prompt, view)
+            view.command = False
+            if ran is False and not view.failed:
+                transcript.error(f"{name} did not run: the host's queue was cleared first.")
+                return False
+            # A host that went away has said whether that was a failure.
+            return not view.failed
+        try:
+            await submit(controller, prompt, view)
+        except asyncio.CancelledError:
+            # Ctrl+C only detaches: the host's own cancel would also clear
+            # every other terminal's queue. Attach to stop the turn there.
+            reply.settle()
+            where = "keeps running" if view.turn else "is still queued"
+            transcript.note(f"Detached; the message {where} in host {entry.id}.")
+            raise
+        if view.dropped:
+            # Startup can fail after this attached, and then drops the queue.
+            error = controller.startup_error
+            transcript.error(
+                str(error) if error else "The host dropped this message before it ran.",
+                title="Agent startup failed" if error else "Error",
+            )
+        return not view.failed
+
+
+async def _stop(entry: HostEntry, prompt: str, transcript) -> bool:
+    """`/stop`: end the host; it tidies its own worktree, as nobody is here to ask."""
+    if prompt != "/stop":
+        transcript.error("Usage: /stop")
+        return False
+    await stop_entry(entry)
+    line = f"Stopped session host {entry.id}."
+    if entry.session_id:
+        line += f" Continue with: pcode --continue {entry.session_id}"
+    transcript.note(line)
+    return True

pcode/remote_profile.py

@@ -0,0 +1,237 @@
+"""The fixed execution profile for a session host nobody is watching.
+
+A host started by a remote control (`pcode --email-listen`) runs turns with no
+one at the terminal to stop them, and pcode has no approval step. So the
+listener chooses a profile locally, before any message arrives, and nothing
+sent remotely can change it:
+
+- the bundled `sandbox` extension is on whatever `extensions_off` says, its
+  shell sandbox cannot be switched off, and it also refuses reads of the
+  listener's own state and credentials, and keychain lookups from the shell;
+- the host's environment is built from an allowlist, not inherited whole;
+- MCP servers stay off unless the profile opts in (they run unsandboxed);
+- each turn has a wall-clock limit and a budget of model requests and tool
+  calls, shared with its sub-agents; reaching one ends the turn with a status
+  that says so;
+- the session always gets a fresh worktree, which is kept when the host stops.
+
+`spawn_host(profile=...)` hands the profile to `pcode.host`, which calls
+`activate` before anything else is built; the rest of pcode asks `active()`.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass, field
+
+# What a turn ending at a limit says, first in its message: the gateway reads
+# a turn that failed or was cancelled with this as one that hit a limit.
+LIMIT_PREFIX = "Turn limit reached"
+
+# Exact names a remote host may inherit. Provider credentials come from
+# `pcode.models.ENV_PROVIDERS` as well (see `allowed_env_names`).
+_ENV_NAMES = frozenset(
+    {
+        "PATH",
+        "HOME",
+        "USER",
+        "LOGNAME",
+        "SHELL",
+        "TMPDIR",
+        "TERM",
+        "LANG",
+        "LANGUAGE",
+        "TZ",
+        "XDG_CONFIG_HOME",
+        "XDG_CACHE_HOME",
+        "XDG_STATE_HOME",
+        "XDG_DATA_HOME",
+        "ANTHROPIC_API_KEY",
+        "ANTHROPIC_AUTH_TOKEN",
+        "ANTHROPIC_BASE_URL",
+        "OPENAI_BASE_URL",
+        "AZURE_OPENAI_ENDPOINT",
+        "AWS_REGION",
+        "AWS_DEFAULT_REGION",
+        # Bedrock's key id is a provider variable; the rest of the credential with it.
+        "AWS_SECRET_ACCESS_KEY",
+        "AWS_SESSION_TOKEN",
+        "SSL_CERT_FILE",
+        "SSL_CERT_DIR",
+        "REQUESTS_CA_BUNDLE",
+        "PCODE_CONFIG_DIR",
+        "PCODE_SESSION_DIR",
+        "PCODE_CREDENTIALS_FILE",
+        "PCODE_CODEX_CREDENTIALS_FILE",
+        "PCODE_MERIDIAN_API_KEY",
+        "PCODE_MERIDIAN_BASE_URL",
+        "PCODE_MERIDIAN_MANAGED",
+        "PCODE_ANTHROPIC_AUTH",
+        "PCODE_LLM_PROXY",
+        "PCODE_MCP_CONFIG",
+        "PYDANTIC_AI_NO_BANNER",
+        # Which pcode the host imports, as for the listener.
+        "PYTHONPATH",
+        "VIRTUAL_ENV",
+    }
+)
+_ENV_PREFIXES = ("LC_",)
+
+# Mach services the shell sandbox may not reach: the keychain, where the
+# listener keeps its mailbox credential.
+KEYCHAIN_SERVICES = (
+    "com.apple.SecurityServer",
+    "com.apple.securityd",
+    "com.apple.security.keychaind",
+)
+
+
+@dataclass(frozen=True)
+class RemoteProfile:
+    """What a remote host may do; serialised onto its command line (no secrets)."""
+
+    # Extra unreadable paths (globs, `~` allowed): the listener's state, credentials.
+    deny_read: tuple[str, ...] = ()
+    # Default MCP servers start, as in a local session.
+    mcp: bool = False
+    # Per turn, sub-agents included; 0 is no limit.
+    turn_minutes: float = 30.0
+    max_requests: int = 100
+    max_tool_calls: int = 100
+    # The commit or branch the session's worktree starts from; None: the mainline.
+    base: str | None = None
+    # Who started it, for `pcode --hosts` and the host log.
+    origin: str = "remote"
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), sort_keys=True)
+
+    @classmethod
+    def from_json(cls, text: str) -> RemoteProfile:
+        data = json.loads(text)
+        if not isinstance(data, dict):
+            raise ValueError("A remote profile must be a JSON object.")
+        known = {name for name in cls.__dataclass_fields__}
+        if unknown := set(data) - known:
+            raise ValueError(f"Unknown remote profile keys: {', '.join(sorted(unknown))}")
+        if "deny_read" in data:
+            data["deny_read"] = tuple(str(entry) for entry in data["deny_read"])
+        return cls(**data)
+
+    def describe(self) -> list[str]:
+        """The profile as lines for a terminal or an email."""
+
+        def limit(value, unit: str) -> str:
+            return f"{value:g} {unit}" if value else "no limit"
+
+        return [
+            "Sandbox: on (writes confined to the session worktree and caches; "
+            "credentials and the listener's state unreadable; no keychain)",
+            "Worktree: a fresh one per session, kept afterwards; nothing is merged",
+            "Environment: allowlisted (provider keys, PATH, HOME, locale) only",
+            f"MCP servers: {'default servers start' if self.mcp else 'off'}",
+            "Per turn: "
+            + ", ".join(
+                (
+                    limit(self.turn_minutes, "min"),
+                    limit(self.max_requests, "model requests"),
+                    limit(self.max_tool_calls, "tool calls"),
+                )
+            ),
+            "Project extensions and worktree-setup: only if the repository is already trusted",
+        ]
+
+
+_ACTIVE: RemoteProfile | None = None
+
+
+def activate(profile: RemoteProfile | None) -> None:
+    """Apply `profile` to this process; a host calls it once, before building anything."""
+    global _ACTIVE
+    _ACTIVE = profile
+    BUDGET.profile = profile
+    BUDGET.start()
+
+
+def active() -> RemoteProfile | None:
+    return _ACTIVE
+
+
+def allowed_env_names(environ: Mapping[str, str]) -> set[str]:
+    from pcode.models import ENV_PROVIDERS
+
+    provider = {name for groups in ENV_PROVIDERS.values() for group in groups for name in group}
+    names = _ENV_NAMES | provider
+    return {
+        name for name in environ if name in names or any(name.startswith(p) for p in _ENV_PREFIXES)
+    }
+
+
+def scrubbed_env(environ: Mapping[str, str]) -> dict[str, str]:
+    """The environment a remote host starts with: allowlisted names only."""
+    return {name: environ[name] for name in sorted(allowed_env_names(environ))}
+
+
+class TurnLimitReached(RuntimeError):
+    """A remote turn used up a budget. Not transient, so no retry spends more."""
+
+    # Its message is fixed text: `error_message` shows it as is.
+    sanitized = True
+
+
+@dataclass
+class TurnBudget:
+    """What the running turn has used, across the agent and every sub-agent."""
+
+    profile: RemoteProfile | None = None
+    requests: int = 0
+    tool_calls: int = 0
+    started: float = field(default_factory=time.monotonic)
+    # Set once a limit is hit, so every later request or call fails at once.
+    reached: str = ""
+
+    def start(self) -> None:
+        self.requests = self.tool_calls = 0
+        self.started = time.monotonic()
+        self.reached = ""
+
+    def _check(self) -> None:
+        if self.reached:
+            raise TurnLimitReached(self.reached)
+
+    def _over(self, reason: str) -> None:
+        self.reached = f"{LIMIT_PREFIX}: {reason}. The turn was stopped."
+        raise TurnLimitReached(self.reached)
+
+    def charge_request(self) -> None:
+        self._check()
+        profile = self.profile
+        if profile is None:
+            return
+        if profile.turn_minutes and time.monotonic() - self.started > profile.turn_minutes * 60:
+            self._over(f"{profile.turn_minutes:g} minutes")
+        self.requests += 1
+        if profile.max_requests and self.requests > profile.max_requests:
+            self._over(f"{profile.max_requests} model requests")
+
+    def charge_tool_call(self) -> None:
+        self._check()
+        profile = self.profile
+        if profile is None:
+            return
+        self.tool_calls += 1
+        if profile.max_tool_calls and self.tool_calls > profile.max_tool_calls:
+            self._over(f"{profile.max_tool_calls} tool calls")
+
+    def expire(self) -> str:
+        """The wall clock ran out: later requests fail; returns what to show."""
+        profile = self.profile
+        minutes = profile.turn_minutes if profile is not None else 0
+        self.reached = f"{LIMIT_PREFIX}: {minutes:g} minutes. The turn was stopped."
+        return self.reached
+
+
+# One per process: a host runs one turn at a time, and sub-agents share it.
+BUDGET = TurnBudget()

pcode/replay_benchmark.py

@@ -0,0 +1,319 @@
+"""Read-only replay of journaled display events, never of model/tool execution."""
+
+import hashlib
+import json
+import os
+import stat
+import time
+from collections import Counter, deque
+from dataclasses import dataclass
+from functools import partial
+from pathlib import Path
+
+from pydantic import TypeAdapter, ValidationError
+
+from pcode import runtime
+from pcode.stream_display import present_events, present_stream_event
+from pcode.ui import Activity, TerminalOutput, Transcript
+
+MAX_RECORD_BYTES = 8 * 1024 * 1024
+EVENT_TYPES = (
+    runtime.Message,
+    runtime.TextDelta,
+    runtime.Thinking,
+    runtime.ThinkingDelta,
+    runtime.ToolStarted,
+    runtime.ToolSummary,
+    runtime.EditCompleted,
+    runtime.CacheBust,
+    runtime.RunStatus,
+    runtime.PlanUpdated,
+)
+ADAPTERS = {cls.__name__: TypeAdapter(cls) for cls in EVENT_TYPES}
+BOUNDARIES = {"turn_started", "turn_completed", "turn_cancelled", "turn_failed"}
+METADATA = {"tree_selected", "compaction_checkpoint"}
+
+
+class EndOnlyOutput(TerminalOutput):
+    """Experimental comparison only: parse at semantic finish boundaries, not per line."""
+
+    def _commit_blocks(self, *, thinking: bool = False) -> None:
+        pass
+
+
+class JournalSnapshot:
+    """Freeze the readable byte prefix without opening/locking/modifying a SavedSession."""
+
+    def __init__(self, path: Path):
+        if path.parent.is_symlink() or path.is_symlink():
+            raise ValueError("symlinked journals are not supported")
+        fd = os.open(
+            path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+        )
+        try:
+            info = os.fstat(fd)
+            if not stat.S_ISREG(info.st_mode):
+                raise ValueError("journal must be a regular file")
+            self.size = info.st_size
+            self.file = os.fdopen(fd, "rb")
+        except BaseException:
+            os.close(fd)
+            raise
+        self.expected_digest = None
+
+    def close(self):
+        self.file.close()
+
+    def records(self):
+        # A buffered seek within the previous read buffer can return stale bytes
+        # after an in-place edit. SEEK_END invalidates that buffer before rereading.
+        self.file.seek(0, os.SEEK_END)
+        self.file.seek(0)
+        remaining = self.size
+        digest = hashlib.sha256()
+        self.skipped = Counter()
+        while remaining:
+            line = self.file.readline(min(remaining, MAX_RECORD_BYTES + 1))
+            if not line:
+                raise ValueError("journal was truncated during replay")
+            remaining -= len(line)
+            digest.update(line)
+            if len(line) > MAX_RECORD_BYTES:
+                # Drain one oversized record in bounded chunks without decoding it.
+                while remaining and not line.endswith(b"\n"):
+                    line = self.file.readline(min(remaining, MAX_RECORD_BYTES + 1))
+                    if not line:
+                        raise ValueError("journal was truncated during replay")
+                    remaining -= len(line)
+                    digest.update(line)
+                self.skipped["oversized"] += 1
+                continue
+            try:
+                record = json.loads(line)
+            except (ValueError, UnicodeDecodeError):
+                self.skipped["malformed"] += 1
+                continue
+            if not isinstance(record, dict):
+                self.skipped["malformed"] += 1
+            elif record.get("version", 1) != 1:
+                self.skipped["unsupported_version"] += 1
+            else:
+                yield record
+        self.digest = digest.hexdigest()
+        if self.expected_digest is not None and self.digest != self.expected_digest:
+            raise ValueError("journal changed between replay passes")
+        self.expected_digest = self.digest
+
+
+@dataclass
+class ReplaySettings:
+    show_thinking: bool = True
+    command_scrollback: bool = False
+    start_turn: int = 1
+    max_turns: int | None = None
+
+
+async def replay_journal(
+    snapshot: JournalSnapshot, output: TerminalOutput, settings: ReplaySettings
+):
+    """Measure shared live presentation code; no prompt app, backend, or session writer."""
+    activity = Activity(thinking_mode="scrollback" if settings.show_thinking else "off")
+    transcript = Transcript(
+        output.console,
+        activity=activity,
+        preferences={"show_commands": "on" if settings.command_scrollback else "off"},
+        detected_theme="dark",
+    )
+    transcript.output = output
+    # Edits still render and are retained by Transcript; no diff-browser history is needed.
+    present = partial(
+        present_events, activity=activity, transcript=transcript, edits=deque(maxlen=0)
+    )
+    counts = Counter()
+    skipped = Counter()
+    turns = []
+    current = None
+    turn_index = 0
+    open_turn = False
+    render_cpu = render_wall = 0.0
+    started, cpu_started = time.perf_counter(), time.process_time()
+
+    def selected(index):
+        return index >= settings.start_turn and (
+            settings.max_turns is None or index < settings.start_turn + settings.max_turns
+        )
+
+    async def finish_turn():
+        nonlocal open_turn, render_cpu, render_wall
+        if not open_turn:
+            return
+        before, cpu_before = time.perf_counter(), time.process_time()
+        output.end_turn()
+        activity.tools.clear()
+        activity.status = ""
+        await output.flush()
+        render_wall += time.perf_counter() - before
+        cpu = time.process_time() - cpu_before
+        render_cpu += cpu
+        if current is not None:
+            current["render_cpu_seconds"] += cpu
+        open_turn = False
+
+    for record in snapshot.records():
+        kind = record.get("kind")
+        if not isinstance(kind, str):
+            skipped["malformed"] += 1
+            continue
+        if kind in METADATA:
+            skipped["metadata"] += 1
+            continue
+        if kind not in ADAPTERS and kind not in BOUNDARIES:
+            skipped["unknown_kind"] += 1
+            continue
+        if kind == "turn_started":
+            # Also settles an interrupted attempt without a closing journal record.
+            await finish_turn()
+            turn_index += 1
+            current = None
+            if selected(turn_index):
+                current = dict(turn=turn_index, events=0, characters=0, render_cpu_seconds=0.0)
+                turns.append(current)
+        elif turn_index == 0:
+            # Legacy journals can contain display events before a turn marker.
+            turn_index = 1
+            if selected(turn_index):
+                current = dict(turn=turn_index, events=0, characters=0, render_cpu_seconds=0.0)
+                turns.append(current)
+        if not selected(turn_index):
+            skipped["outside_turn_range"] += 1
+            continue
+        event = None
+        if kind in ADAPTERS:
+            try:
+                event = ADAPTERS[kind].validate_python(record)
+            except ValidationError:
+                skipped["invalid_event"] += 1
+                continue
+        elif kind == "turn_started" and not isinstance(record.get("prompt", ""), str):
+            skipped["invalid_event"] += 1
+            continue
+        counts[kind] += 1
+        if current is not None:
+            current["events"] += 1
+            if kind in {"TextDelta", "ThinkingDelta", "Message", "Thinking"}:
+                current["characters"] += len(getattr(event, "text", getattr(event, "markdown", "")))
+        if kind in BOUNDARIES and kind != "turn_started":
+            await finish_turn()
+            continue
+        open_turn = True
+        before, cpu_before = time.perf_counter(), time.process_time()
+        if kind == "turn_started":
+            output.begin_turn(record.get("prompt", ""))
+        else:
+            present_stream_event(
+                event, output=output, transcript=transcript, activity=activity, present=present
+            )
+        await output.flush()
+        elapsed, cpu = time.perf_counter() - before, time.process_time() - cpu_before
+        render_wall += elapsed
+        render_cpu += cpu
+        if current is not None:
+            current["render_cpu_seconds"] += cpu
+    await finish_turn()
+    return dict(
+        snapshot_bytes=snapshot.size,
+        journal_sha256=snapshot.digest,
+        turns=len(turns),
+        event_counts=dict(counts),
+        skipped_records=dict(snapshot.skipped + skipped),
+        render_cpu_seconds=render_cpu,
+        render_wall_seconds=render_wall,
+        cpu_seconds=time.process_time() - cpu_started,
+        wall_seconds=time.perf_counter() - started,
+        top_turns=sorted(turns, key=lambda item: item["render_cpu_seconds"], reverse=True)[:10],
+    )
+
+
+# Real journals pause for minutes while a tool runs or the user types; a live
+# replay is about render cost, so no single gap waits longer than this.
+MAX_GAP_SECONDS = 2.0
+
+
+@dataclass
+class JournalTurn:
+    prompt: str
+    events: list  # (seconds since the previous event, display event)
+
+
+def journal_turns(snapshot: JournalSnapshot) -> list[JournalTurn]:
+    """Split a journal into prompts and their timestamped display events."""
+    turns: list[JournalTurn] = []
+    previous = None
+    for record in snapshot.records():
+        kind = record.get("kind")
+        if kind == "turn_started":
+            prompt = record.get("prompt", "")
+            turns.append(JournalTurn(prompt if isinstance(prompt, str) else "", []))
+            previous = _record_time(record)
+            continue
+        if kind not in ADAPTERS:
+            continue
+        if not turns:
+            turns.append(JournalTurn("", []))
+        try:
+            event = ADAPTERS[kind].validate_python(record)
+        except ValidationError:
+            continue
+        stamp = _record_time(record)
+        gap = 0.0
+        if stamp is not None and previous is not None:
+            gap = min(max(0.0, (stamp - previous).total_seconds()), MAX_GAP_SECONDS)
+        if stamp is not None:
+            previous = stamp
+        turns[-1].events.append((gap, event))
+    return [turn for turn in turns if turn.events]
+
+
+def _record_time(record):
+    from datetime import datetime
+
+    value = record.get("time")
+    if not isinstance(value, str):
+        return None
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+class JournalRuntime:
+    """A runtime whose every ``stream`` call plays back the next journaled turn.
+
+    Only what ``PreviewApp.run_live`` reads is here; nothing contacts a model.
+    """
+
+    session = None
+    recovery_blocked = None
+    agent = None
+    inspections = None
+
+    def __init__(self, turns: list[JournalTurn], speed: float = 1.0):
+        self.turns = list(turns)
+        self.speed = speed
+        self.events_played = 0
+
+    async def stream(self, text):
+        import asyncio
+
+        turn = self.turns.pop(0)
+        for gap, event in turn.events:
+            if self.speed > 0 and gap > 0:
+                await asyncio.sleep(gap / self.speed)
+            else:
+                # Keep the editor responsive even at full speed.
+                await asyncio.sleep(0)
+            self.events_played += 1
+            yield event
+
+    def close(self) -> None:
+        pass