pcode 0.1.0__py3-none-any.whl

pcode/conversation_ids.py

@@ -0,0 +1,27 @@
+"""Conversation ids for runs on a model other than the conversation's.
+
+Meridian keys its session on the conversation id, so a request from another
+model under the conversation's id would move that session and force the
+conversation's next turn to replay cold. A run on another model (`/btw $MODEL`,
+a `$MODEL` prompt) carries an id of its own, derived from the conversation's so
+anything that needs the session it belongs to can still find it.
+"""
+
+import re
+from uuid import uuid4
+
+KINDS = ("btw", "turn")
+_SUFFIX = re.compile(rf"\.(?:{'|'.join(KINDS)})-[0-9a-f]{{8}}$")
+
+
+def model_conversation(conversation_id: str, kind: str) -> str:
+    """A fresh id for one run of `kind` on another model, within `conversation_id`."""
+    assert kind in KINDS
+    return f"{conversation_id}.{kind}-{uuid4().hex[:8]}"
+
+
+def base_conversation(conversation_id: str | None) -> str | None:
+    """The conversation (and saved session) a possibly per-model id belongs to."""
+    if conversation_id is None:
+        return None
+    return _SUFFIX.sub("", conversation_id)

pcode/conversation_tree.py

@@ -0,0 +1,160 @@
+"""Conversation paths, independent of model-message and tool-effect storage."""
+
+from copy import deepcopy
+from dataclasses import dataclass, field
+
+from pcode.links import Link, extract_links, remember_link
+
+
+@dataclass
+class TurnNode:
+    id: str
+    parent: str | None
+    prompt: str
+    status: str = "interrupted"
+    continuation: bool = False
+    resend_blocked: bool = False
+    response: str = ""
+    plan: list[dict] = field(default_factory=list)
+    # "turn", "compaction", or "aside": a side question merged from /btw, or a
+    # side thread's summary, recorded like a turn that ran no tools.
+    kind: str = "turn"
+    # Unsaved turns and durable compaction checkpoints carry message history.
+    history: list | None = None
+    links: dict[str, Link] = field(default_factory=dict)
+    message_links: dict[str, Link] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.add_links(self.prompt, "user")
+        self.add_links(self.response, "assistant")
+
+    def add_links(self, text: str, source: str, *, tool: bool = False) -> None:
+        # Keep URL recency in event order, including assistant text before tools.
+        for link in extract_links(text, source):
+            remember_link(self.links, link)
+            if not tool:
+                remember_link(self.message_links, link)
+
+
+class ConversationTree:
+    def __init__(self) -> None:
+        self.nodes: dict[str, TurnNode] = {}
+        self.active: str | None = None
+        # Which turn a record belongs to when it does not say. Older journals
+        # rely on this entirely; they could never have two turns open at once.
+        self.recording: str | None = None
+
+    def path(self, identity: str | None) -> list[str]:
+        path = []
+        while identity is not None:
+            if identity in path or identity not in self.nodes:
+                raise ValueError("Invalid conversation tree path.")
+            path.append(identity)
+            identity = self.nodes[identity].parent
+        return path[::-1]
+
+    def consume(self, record: dict) -> None:
+        kind = record.get("kind")
+        if kind == "turn_started" and record.get("run_id"):
+            identity = record["run_id"]
+            parent = record.get("parent_id", self.active)  # Old sessions form a linear tree.
+            self.path(parent)
+            self.nodes[identity] = TurnNode(
+                identity,
+                parent,
+                record["prompt"],
+                continuation=record.get("continuation", False),
+                plan=deepcopy(self.nodes[parent].plan) if parent else [],
+                kind="aside" if record.get("aside") else "turn",
+            )
+            self.active = self.recording = identity
+        elif kind == "compaction_checkpoint":
+            from pydantic_ai.messages import ModelMessagesTypeAdapter
+
+            identity, parent = record["node_id"], record["parent_id"]
+            self.path(parent)
+            history = ModelMessagesTypeAdapter.validate_python(record["messages"])
+            self.nodes[identity] = TurnNode(
+                identity,
+                parent,
+                record.get("focus", ""),
+                status="completed",
+                response=f"Context compacted: ~{record['before']} → ~{record['after']} tokens",
+                plan=deepcopy(record["plan"]),
+                history=history,
+                kind="compaction",
+            )
+            self.active = identity
+            self.recording = None
+        elif kind == "tree_selected":
+            self.path(record["node_id"])
+            self.active = record["node_id"]
+        # Attribute by the record's own run_id, not its position, so a record from
+        # another branch's turn is never absorbed into whichever turn started last.
+        # Journals from before run_id fall back to `recording` (see
+        # `SessionJournal.active_records`).
+        elif (node := self.nodes.get(record.get("run_id") or self.recording)) is not None:
+            if kind == "Message":
+                node.response = record["markdown"]
+                node.add_links(node.response, "assistant")
+            elif kind in {"ToolStarted", "ToolSummary"}:
+                # Keep only URLs, not another copy of potentially large payloads.
+                # The same journal events rebuild these on session resume.
+                source = record.get("name") or "tool"
+                for key in ("arguments", "result", "command", "detail", "error"):
+                    text = record.get(key)
+                    if isinstance(text, str):
+                        node.add_links(text, source, tool=True)
+            elif kind == "PlanUpdated":
+                node.plan = deepcopy(record["items"])
+            elif kind in {"turn_completed", "turn_failed", "turn_cancelled"}:
+                node.status = kind.removeprefix("turn_")
+                node.resend_blocked = record.get("resend_blocked", False)
+
+    def rows(self) -> list[tuple[tuple[str | None, bool], str]]:
+        """Depth-first user/edit and assistant/continue rows, with stable IDs."""
+        from pcode.diagnostics import redact
+        from pcode.ui import plain
+
+        def excerpt(text):
+            return plain(redact(" ".join(text.split())), 100)
+
+        rows = [
+            ((None, False), "Conversation start" + (" ← active" if self.active is None else ""))
+        ]
+        children: dict[str | None, list[TurnNode]] = {}
+        for node in self.nodes.values():
+            children.setdefault(node.parent, []).append(node)
+        # Iterative traversal also handles very long sessions. Only a fork adds
+        # a level: user/assistant pairs and single-child continuations stay aligned.
+        roots = children.get(None, [])
+        pending = [
+            (node, "", len(roots) > 1, i == len(roots) - 1)
+            for i, node in reversed(list(enumerate(roots)))
+        ]
+        while pending:
+            node, prefix, fork, last = pending.pop()
+            # Keep labels visible even with many nested forks.
+            if len(prefix) > 24:
+                prefix = "… " + prefix[-22:]
+            connector = ("└─ " if last else "├─ ") if fork else ""
+            if node.kind != "compaction":
+                who = "btw: " if node.kind == "aside" else "user: "
+                rows.append(((node.id, True), prefix + connector + who + excerpt(node.prompt)))
+            continuation = prefix + (("   " if last else "│  ") if fork else "")
+            rows.append(
+                (
+                    (node.id, False),
+                    continuation
+                    + ("compaction: " if node.kind == "compaction" else "assistant: ")
+                    + excerpt(node.response or f"[{node.status}; last safe checkpoint]")
+                    + (f" [{node.status}]" if node.response and node.status != "completed" else "")
+                    + (" ← active" if node.id == self.active else ""),
+                )
+            )
+            descendants = children.get(node.id, [])
+            pending.extend(
+                (child, continuation, len(descendants) > 1, i == len(descendants) - 1)
+                for i, child in reversed(list(enumerate(descendants)))
+            )
+        return rows

pcode/copy_ui.py

@@ -0,0 +1,172 @@
+"""Copy a response, or one quote or code block out of it, to the clipboard.
+
+The transcript draws a Markdown quote with a `▌` rail and hard-wraps it to the
+terminal, so selecting it with the mouse picks up both. The source still has
+the text as written: this pulls each top-level quote and fenced code block out
+of it for a small picker, shared by `/copy` and `/tree`.
+"""
+
+import re
+from dataclasses import dataclass
+
+from markdown_it import MarkdownIt
+from prompt_toolkit.application import Application
+from prompt_toolkit.document import Document
+from prompt_toolkit.filters import Always
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.layout import HSplit, Layout
+from prompt_toolkit.layout.dimension import Dimension
+from prompt_toolkit.widgets import Label, TextArea
+
+from pcode.frame import Dialog
+from pcode.popup_ui import bind_list_paging, popup_container, popup_mouse, popup_style
+from pcode.prefix_keys import PrefixKeys
+
+_QUOTE_MARKER = re.compile(r"^[ \t]*> ?")
+_ROW_WIDTH = 80
+
+
+@dataclass(frozen=True)
+class Snippet:
+    kind: str  # "response", "quote", or "code"
+    text: str
+    language: str = ""
+
+    @property
+    def label(self) -> str:
+        if self.kind == "response":
+            return "Whole response"
+        if self.language:
+            return f"{self.kind.title()} ({self.language})"
+        return self.kind.title()
+
+
+def _unquote(lines: list[str]) -> str:
+    # A lazy continuation line has no marker; it only loses its indentation.
+    return "\n".join(
+        _QUOTE_MARKER.sub("", line, count=1) if _QUOTE_MARKER.match(line) else line.lstrip()
+        for line in lines
+    ).strip("\n")
+
+
+def snippets(markdown: str) -> list[Snippet]:
+    """The whole response, then each top-level quote and code block in order."""
+    if not markdown.strip():
+        return []
+    found = [Snippet("response", markdown)]
+    lines = markdown.splitlines()
+    depth = 0
+    for token in MarkdownIt("commonmark").parse(markdown):
+        if token.type == "blockquote_open":
+            if depth == 0 and token.map:
+                start, end = token.map
+                if text := _unquote(lines[start:end]):
+                    found.append(Snippet("quote", text))
+            depth += 1
+        elif token.type == "blockquote_close":
+            depth -= 1
+        elif token.type == "fence" and depth == 0 and token.content.strip():
+            language = token.info.split()[0] if token.info.strip() else ""
+            # No trailing newline: pasted into a shell, it would run the command.
+            text = token.content.rstrip("\n")
+            found.append(Snippet("code", text, language))
+    return found
+
+
+def last_response(tree) -> str:
+    """The newest assistant text on the active branch, skipping compactions."""
+    for identity in reversed(tree.path(tree.active)):
+        node = tree.nodes[identity]
+        if node.kind != "compaction" and node.response.strip():
+            return node.response
+    return ""
+
+
+def snippet_row(snippet: Snippet) -> str:
+    text = " ".join(snippet.text.split())
+    row = f"{snippet.label}: {text}"
+    return row if len(row) <= _ROW_WIDTH else row[: _ROW_WIDTH - 1] + "…"
+
+
+class SnippetPicker:
+    """A list of snippets; Enter picks one, Esc backs out.
+
+    ``container`` and ``key_bindings`` let a popup host it as an overlay, which
+    `/tree` does; ``snippet_dialog`` wraps it in an application of its own.
+    """
+
+    def __init__(self, choices: list[Snippet], on_pick, on_cancel, *, shortcuts=None) -> None:
+        self.choices = choices
+        self.on_pick = on_pick
+        self.list = TextArea(
+            read_only=True,
+            wrap_lines=False,
+            scrollbar=True,
+            width=Dimension(min=40, preferred=_ROW_WIDTH + 1),
+            height=Dimension(min=1, preferred=len(choices)),
+        )
+        self.list.window.cursorline = Always()
+        rows = [snippet_row(snippet) for snippet in choices]
+        # Start on the first quote or block: it is why the picker opened.
+        start = 1 if len(choices) > 1 else 0
+        position = sum(len(row) + 1 for row in rows[:start])
+        self.list.buffer.set_document(Document("\n".join(rows), position), bypass_readonly=True)
+        keys = self.key_bindings = KeyBindings()
+        bind_list_paging(keys, self.list, Always())
+
+        @keys.add("enter", eager=True)
+        def pick(event):
+            on_pick(self.selected())
+
+        @keys.add("escape", eager=True)
+        @keys.add("c-c")
+        def cancel(event):
+            on_cancel()
+
+        self.container = HSplit(
+            [self.list],
+            # Gated by the host's `PrefixKeys`, so a waiting leader owns Enter and Esc.
+            key_bindings=shortcuts.gate(keys) if shortcuts else keys,
+            modal=True,
+        )
+
+    def help(self) -> list[tuple[str, str]]:
+        return [
+            ("↑/↓", "Select snippet"),
+            ("PgUp/PgDn", "Page"),
+            ("Ctrl+U/D", "Half page"),
+            ("Enter", "Copy selected snippet"),
+            ("Esc / Ctrl+C", "Cancel"),
+        ]
+
+    def selected(self) -> Snippet:
+        row = self.list.document.cursor_position_row
+        return self.choices[min(row, len(self.choices) - 1)]
+
+
+def snippet_dialog(choices: list[Snippet], *, input=None, output=None, style=None):
+    """A popup application whose result is the picked snippet, or None."""
+    app: Application
+    shortcuts = PrefixKeys()
+
+    picker = SnippetPicker(
+        choices,
+        on_pick=lambda snippet: app.exit(result=snippet),
+        on_cancel=lambda: app.exit(result=None),
+        shortcuts=shortcuts,
+    )
+    shortcuts.set_help(picker.help)
+    dialog = Dialog(
+        title="Copy",
+        body=HSplit([picker.container, Label(shortcuts.summary)], padding=1),
+    )
+    app = Application(
+        layout=Layout(popup_container(dialog, shortcuts), focused_element=picker.list),
+        key_bindings=shortcuts.key_bindings(KeyBindings()),
+        full_screen=True,
+        mouse_support=popup_mouse(shortcuts),
+        input=input,
+        output=output,
+        style=popup_style(style),
+    )
+    return app

pcode/delegation.py

@@ -0,0 +1,236 @@
+"""Forward child activity; child prose goes to the worker viewer, never the transcript.
+
+Harness 0.31 supplies delegation lifecycle events and a child stream handler, but
+not the parent's call identity in that handler. A context-local execution wrapper
+pairs concurrent children with their own parent tool call. No global event queue
+or mutable per-agent handler is needed, and cancellation resets the binding.
+"""
+
+import asyncio
+import logging
+from contextvars import ContextVar
+from dataclasses import dataclass, replace
+from datetime import datetime, timezone
+from time import monotonic
+
+from pydantic_ai import CapabilityEvent, RunContext
+from pydantic_ai.agent import WrapperAgent
+from pydantic_ai.capabilities import AbstractCapability
+from pydantic_ai.messages import (
+    FunctionToolCallEvent,
+    FunctionToolResultEvent,
+    PartDeltaEvent,
+    PartStartEvent,
+    RetryPromptPart,
+    TextPart,
+    TextPartDelta,
+    ThinkingPart,
+    ThinkingPartDelta,
+)
+
+from pcode import retries
+from pcode.cache_warnings import CacheBustEvent
+from pcode.diagnostics import transient
+from pcode.error_report import error_message
+from pcode.filesystem import FileChangeEvent
+from pcode.inspection import capture
+from pcode.jobs import registry
+from pcode.planning import PlanSnapshot
+from pcode.preferences import SETTINGS, load_preferences
+from pcode.retries import RequestCheckpoint
+from pcode.runtime import ToolStarted, ToolSummary
+from pcode.shell import result_projection
+from pcode.tool_display import (
+    COMMAND_TOOLS,
+    assignment,
+    command_error,
+    execution_mode,
+    invocation,
+    result_detail,
+    stated_purpose,
+    stored_source,
+    subject,
+    target,
+)
+
+_parent: ContextVar[RunContext | None] = ContextVar("delegation_parent", default=None)
+logger = logging.getLogger(__name__)
+
+
+@dataclass(kw_only=True)
+class ChildActivity(CapabilityEvent, namespace="pcode_delegation", name="activity"):
+    activity: str
+    child: ToolStarted | ToolSummary | None = None
+    # The child's whole plan, sent only when it changed.
+    plan: list[dict] | None = None
+
+
+@dataclass(kw_only=True)
+class ChildOutput(CapabilityEvent, namespace="pcode_delegation", name="output"):
+    """A slice of the child's prose or reasoning; `start` opens a new part."""
+
+    text: str
+    thinking: bool = False
+    start: bool = False
+
+
+def _output(event) -> ChildOutput | None:
+    """The prose or reasoning a streamed part carries, if any."""
+    if isinstance(event, PartStartEvent) and isinstance(event.part, TextPart | ThinkingPart):
+        return ChildOutput(
+            text=event.part.content, thinking=isinstance(event.part, ThinkingPart), start=True
+        )
+    if isinstance(event, PartDeltaEvent) and isinstance(event.delta, TextPartDelta):
+        return ChildOutput(text=event.delta.content_delta)
+    if isinstance(event, PartDeltaEvent) and isinstance(event.delta, ThinkingPartDelta):
+        if event.delta.content_delta:
+            return ChildOutput(text=event.delta.content_delta, thinking=True)
+    return None
+
+
+class DelegationReporting(AbstractCapability):
+    async def wrap_tool_execute(self, ctx, *, call, tool_def, args, handler):
+        if call.tool_name != "delegate_task":
+            return await handler(args)
+        token = _parent.set(ctx)
+        try:
+            return await handler(args)
+        finally:
+            _parent.reset(token)
+
+
+class ResumableAgent(WrapperAgent):
+    """Resend a sub-agent's request after a dropped connection, as a turn does.
+
+    Without this, one child's ECONNRESET fails its delegation outright. The
+    resend reuses `AgentRuntime.stream`'s rule: only a request that never got an
+    answer goes again, from the exact messages it carried, so no tool the child
+    already ran is run twice. A drop anywhere else still ends the child.
+    """
+
+    async def run(self, user_prompt=None, *, message_history=None, capabilities=None, **kwargs):
+        attempts = int(load_preferences().get("retry_attempts", SETTINGS["retry_attempts"].default))
+        attempt = 0
+        while True:
+            checkpoint = RequestCheckpoint()
+            try:
+                return await self.wrapped.run(
+                    user_prompt,
+                    message_history=message_history,
+                    capabilities=[*(capabilities or ()), checkpoint],
+                    **kwargs,
+                )
+            except Exception as error:
+                if attempt >= attempts or checkpoint.messages is None or not transient(error):
+                    raise
+                attempt += 1
+                user_prompt, message_history = None, checkpoint.messages
+                # The panel shows the reconnect; a warning would print over it.
+                logger.debug(
+                    "Sub-agent %r: %s Retrying %d/%d",
+                    self.name,
+                    error_message(error),
+                    attempt,
+                    attempts,
+                )
+                if (parent := _parent.get()) is not None:
+                    await parent.emit(ChildActivity(activity=f"Reconnecting {attempt}/{attempts}"))
+                await asyncio.sleep(retries.RETRY_DELAY)
+
+
+async def stream_child_activity(_ctx, events):
+    """Consume child streams: tool boundaries, phase changes, plans and prose."""
+    parent = _parent.get()
+    plan_items: list[dict] = []
+    tools = {}
+    # The child's calls by id, so its `read_tool_result` rows name what spilled.
+    called: dict[str, str] = {}
+    phase = ""
+    async for event in events:
+        if parent is None:
+            continue
+        if isinstance(event, FileChangeEvent):
+            await parent.emit(
+                FileChangeEvent(
+                    change=replace(
+                        event.change,
+                        call_id=f"{parent.tool_call_id or ''}:{event.change.call_id}",
+                    )
+                )
+            )
+            continue
+        if isinstance(event, CacheBustEvent):
+            await parent.emit(CacheBustEvent(text=f"Sub-agent: {event.text}"))
+            continue
+        if isinstance(event, PlanSnapshot):
+            # Its own planning announces the plan; the store stays private to it.
+            if event.items != plan_items:
+                plan_items = event.items
+                await parent.emit(ChildActivity(activity=phase, plan=event.items))
+            continue
+        if (output := _output(event)) is not None:
+            await parent.emit(output)
+        child = None
+        activity = phase
+        parent_id = parent.tool_call_id or ""
+        if isinstance(event, FunctionToolCallEvent):
+            part = event.part
+            try:
+                args = part.args_as_dict()
+            except (TypeError, ValueError):
+                args = {}
+            tools[part.tool_call_id] = (part.tool_name, args, monotonic())
+            called[part.tool_call_id] = part.tool_name
+            agent, task = assignment(part.tool_name, args)
+            # Resolved here, in the child's context, so an isolated worker's
+            # job ids are looked up among its own jobs, not the parent's.
+            command, purpose = subject(part.tool_name, args, registry())
+            child = ToolStarted(
+                part.tool_name,
+                target(part.tool_name, args, stored_source(args, called)),
+                f"{parent_id}:{part.tool_call_id}",
+                arguments=capture(args),
+                run_id=parent.run_id or "",
+                started_at=datetime.now(timezone.utc).isoformat(),
+                parent_call_id=parent_id,
+                command=command,
+                purpose=purpose,
+                execution=execution_mode(part.tool_name, args),
+                agent=agent,
+                task=task,
+            )
+            activity = "Working"
+        elif isinstance(event, FunctionToolResultEvent):
+            name, args, started = tools.pop(
+                event.tool_call_id, (event.part.tool_name or "tool", {}, monotonic())
+            )
+            outcome = "retry" if isinstance(event.part, RetryPromptPart) else event.part.outcome
+            detail, failed = result_detail(
+                name, args, event.part.content, outcome, stored_source(args, called)
+            )
+            content = (
+                result_projection(event.part.content) if name == "shell" else event.part.content
+            )
+            child = ToolSummary(
+                name,
+                detail,
+                failed=failed,
+                call_id=f"{parent_id}:{event.tool_call_id}",
+                elapsed_seconds=max(0, monotonic() - started),
+                command=invocation(name, args),
+                purpose=stated_purpose(args),
+                error=command_error(content) if failed and name in COMMAND_TOOLS else "",
+                result=capture(content),
+                run_id=parent.run_id or "",
+                outcome=outcome,
+                parent_call_id=parent_id,
+            )
+            activity = "Working" if tools else "Waiting for model"
+        elif isinstance(event, PartStartEvent):
+            if isinstance(event.part, ThinkingPart):
+                activity = "Thinking"
+            elif isinstance(event.part, TextPart):
+                activity = "Responding"
+        if child is not None or activity != phase:
+            await parent.emit(ChildActivity(activity=activity, child=child))
+            phase = activity