code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/acp/bridge.py

@@ -0,0 +1,309 @@
+"""``EventBridge`` — translate Code Puppy runtime events into ACP updates.
+
+While Code Puppy runs a turn, pydantic-ai's ``event_stream_handler`` fires the
+``stream_event`` callback for each streamed text/thinking delta, and the tool
+layer fires ``pre_tool_call`` / ``post_tool_call``. This bridge registers those
+hooks (the same seam the shipping ``frontend_emitter`` plugin uses) and maps
+each event to a ``session/update`` notification sent through the SDK's
+``AgentSideConnection.session_update``.
+
+We use hooks rather than consuming the ``MessageBus`` because the bus is
+single-consumer and buffers until a renderer attaches, and agent text does not
+arrive there as clean deltas. See ``README.md`` → *Event source*.
+
+Tool calls get human-friendly titles ("Edit foo.py", "Run: pytest"), a ``kind``
+so the client picks the right icon, file ``locations``, and — on completion —
+the unified diff as inline content so edits are visible in the client's UI.
+
+Routing/run-context (which session is active, whether text streamed, the
+open-tool-call stack) lives in ``state`` so the permission and I/O backends can
+share it. This bridge is pure translation.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+from acp.helpers import (
+    start_tool_call,
+    text_block,
+    tool_content,
+    update_agent_message_text,
+    update_agent_thought_text,
+    update_tool_call,
+)
+from acp.schema import ToolCallLocation
+
+from code_puppy.callbacks import register_callback, unregister_callback
+from code_puppy_core_plugins.acp import state
+from code_puppy.tools.common import resolve_path
+
+logger = logging.getLogger(__name__)
+
+# Map Code Puppy tool names to ACP tool-call ``kind`` values so the client
+# picks the right icon/affordance. Unknown tools fall back to "other".
+_TOOL_KINDS = {
+    "read_file": "read",
+    "list_files": "read",
+    "grep": "search",
+    "edit_file": "edit",
+    "create_file": "edit",
+    "replace_in_file": "edit",
+    "delete_snippet": "edit",
+    "delete_file": "delete",
+    "agent_run_shell_command": "execute",
+    "agent_share_your_reasoning": "think",
+}
+
+# Human-readable verbs for building tool-call titles like "Edit foo.py".
+_TOOL_VERBS = {
+    "read_file": "Read",
+    "list_files": "List",
+    "grep": "Search",
+    "edit_file": "Edit",
+    "create_file": "Create",
+    "replace_in_file": "Edit",
+    "delete_snippet": "Edit",
+    "delete_file": "Delete",
+}
+
+# Tool-arg keys that commonly carry the target file path, in priority order.
+_PATH_ARG_KEYS = ("file_path", "path", "target_file", "filename")
+
+# Cap on inline diff/output content so a huge edit never floods the client.
+_MAX_DIFF_CHARS = 8000
+
+# Interactive TUI tools that can't run headless over ACP (they'd render a terminal
+# picker + read stdin, the JSON-RPC pipe). Until ACP ratifies structured elicitation
+# (an RFD), block these and steer the model to plain-text questions instead.
+_INTERACTIVE_TOOLS = {"ask_user_question"}
+_INTERACTIVE_BLOCK = {
+    "blocked": True,
+    "error_message": (
+        "[BLOCKED] Interactive pickers aren't available over ACP. Ask the user "
+        "your question(s) directly in your normal text response and wait for "
+        "their reply — do not call this tool."
+    ),
+}
+
+
+class EventBridge:
+    """Forward Code Puppy runtime hook events to the client as updates."""
+
+    def register(self) -> None:
+        """Register the runtime hooks. Call once when the connection opens."""
+        register_callback("stream_event", self._on_stream_event)
+        register_callback("pre_tool_call", self._on_pre_tool_call)
+        register_callback("post_tool_call", self._on_post_tool_call)
+
+    def unregister(self) -> None:
+        """Remove the runtime hooks. Call on teardown so no callbacks leak.
+
+        Mirrors ``register`` so a closed connection leaves no dangling bridge
+        callbacks wired into the global registry (which would double-emit if a
+        second connection opened in the same process).
+        """
+        for phase, handler in (
+            ("stream_event", self._on_stream_event),
+            ("pre_tool_call", self._on_pre_tool_call),
+            ("post_tool_call", self._on_post_tool_call),
+        ):
+            try:
+                unregister_callback(phase, handler)
+            except Exception:  # noqa: BLE001
+                logger.debug(
+                    "ACP: bridge unregister failed for %s", phase, exc_info=True
+                )
+
+    # ---- Hook handlers ----------------------------------------------------
+    async def _on_stream_event(
+        self, event_type: str, event_data: Any, agent_session_id: Optional[str] = None
+    ) -> None:
+        """Map streamed text/thinking to message/thought chunks.
+
+        Two event shapes carry visible content and BOTH must be forwarded:
+
+        * ``part_start`` -- a new text/thinking part whose *initial* content
+          (``part.content``) is the opening of the message. pydantic-ai often
+          packs the first token(s) here rather than in the first delta.
+        * ``part_delta`` -- each subsequent chunk (``delta.content_delta``).
+
+        Start-content and delta-content are disjoint (deltas are only the
+        *additions* after the start), so emitting both reconstructs the full
+        message with no overlap. Forwarding only ``part_delta`` -- as this
+        bridge used to -- silently drops the opening chunk whenever the model
+        front-loads it into the start event.
+
+        The per-run ``state`` session id wins over ``agent_session_id``: the
+        former is a ``ContextVar`` isolated to this prompt's task, whereas
+        ``agent_session_id`` is derived from the process-wide message-bus
+        session context, which a concurrent prompt on the same connection can
+        overwrite. We only fall back to it when no run is active in this context.
+        """
+        session_id = state.get_active_session_id() or agent_session_id
+        if session_id is None:
+            return
+        data = event_data if isinstance(event_data, dict) else {}
+        if event_type == "part_start":
+            part = data.get("part")
+            content = getattr(part, "content", None)
+            is_thinking = "Thinking" in (data.get("part_type", "") or "")
+        elif event_type == "part_delta":
+            delta = data.get("delta")
+            content = (
+                getattr(delta, "content_delta", None) if delta is not None else None
+            )
+            is_thinking = "Thinking" in (data.get("delta_type", "") or "")
+        else:
+            return
+        if not content:
+            return
+        if is_thinking:
+            update = update_agent_thought_text(content)
+        else:
+            state.note_streamed_text()
+            update = update_agent_message_text(content)
+        await self._send(session_id, update)
+
+    async def _on_pre_tool_call(
+        self, tool_name: str, tool_args: Dict[str, Any], context: Any = None
+    ) -> Any:
+        """Announce a tool call starting (status ``in_progress``).
+
+        Interactive TUI tools that can't run over ACP are blocked here (via the
+        ``pre_tool_call`` blocking contract) *before* we open a tool-call entry,
+        so the client never sees a dangling in-progress call.
+        """
+        session_id = state.get_active_session_id()
+        if session_id is None:
+            return None
+        if tool_name in _INTERACTIVE_TOOLS:
+            return dict(_INTERACTIVE_BLOCK)
+        tool_call_id = state.push_tool_call(tool_name)
+        update = start_tool_call(
+            tool_call_id,
+            self._title_for(tool_name, tool_args),
+            kind=_TOOL_KINDS.get(tool_name, "other"),
+            status="in_progress",
+            locations=self._locations_for(tool_args) or None,
+            raw_input=tool_args if isinstance(tool_args, dict) else {},
+        )
+        await self._send(session_id, update)
+
+    async def _on_post_tool_call(
+        self,
+        tool_name: str,
+        tool_args: Dict[str, Any],
+        result: Any,
+        duration_ms: float,
+        context: Any = None,
+    ) -> None:
+        """Report a tool call finishing (status ``completed`` / ``failed``)."""
+        session_id = state.get_active_session_id()
+        if session_id is None:
+            return
+        tool_call_id = state.pop_tool_call(tool_name)
+        if tool_call_id is None:
+            return
+        status = "completed" if self._is_success(result) else "failed"
+        update = update_tool_call(
+            tool_call_id,
+            status=status,
+            content=self._content_for(result) or None,
+            raw_output=self._summarize(result),
+        )
+        await self._send(session_id, update)
+
+    # ---- Helpers ----------------------------------------------------------
+    @staticmethod
+    def _title_for(tool_name: str, tool_args: Any) -> str:
+        """Build a human-friendly tool-call title (e.g. ``Edit foo.py``)."""
+        if tool_name == "agent_run_shell_command" and isinstance(tool_args, dict):
+            command = str(tool_args.get("command", "")).strip()
+            if command:
+                short = command if len(command) <= 60 else command[:57] + "..."
+                return f"Run: {short}"
+        verb = _TOOL_VERBS.get(tool_name)
+        path = EventBridge._first_path(tool_args)
+        if verb and path:
+            return f"{verb} {os.path.basename(path)}"
+        return tool_name
+
+    @staticmethod
+    def _first_path(tool_args: Any) -> Optional[str]:
+        if not isinstance(tool_args, dict):
+            return None
+        for key in _PATH_ARG_KEYS:
+            value = tool_args.get(key)
+            if isinstance(value, str) and value:
+                return value
+        return None
+
+    @staticmethod
+    def _locations_for(tool_args: Any) -> List[ToolCallLocation]:
+        """Extract ACP ``locations`` (files this tool touches) from its args.
+
+        Lets the client highlight the affected file in the agent panel.
+        Best-effort: empty list when no recognizable path arg is present.
+
+        Uses ``resolve_path`` (not ``os.path.abspath``) so a relative tool-arg
+        path is absolutized against the *session's* cwd -- the same base the
+        tools themselves resolve against -- rather than the ACP process cwd,
+        which would point the client at the wrong file.
+        """
+        path = EventBridge._first_path(tool_args)
+        return [ToolCallLocation(path=resolve_path(path))] if path else []
+
+    @staticmethod
+    def _content_for(result: Any) -> list:
+        """Attach the unified diff (if any) as an inline content block.
+
+        File-edit tools return a ``diff`` (unified diff text). We surface it as
+        a fenced ``diff`` code block so the change is visible inline in the
+        client's tool-call entry, in every ACP client — independent of whether
+        filesystem delegation is rendering a native diff too.
+        """
+        if not isinstance(result, dict):
+            return []
+        diff = result.get("diff")
+        if not isinstance(diff, str) or not diff.strip():
+            return []
+        if len(diff) > _MAX_DIFF_CHARS:
+            diff = diff[: _MAX_DIFF_CHARS - 3] + "..."
+        return [tool_content(text_block(f"```diff\n{diff}\n```"))]
+
+    async def _send(self, session_id: str, update: Any) -> None:
+        """Emit one ``session/update`` notification, swallowing failures.
+
+        A translation/transport hiccup on one event must never abort the agent
+        run, so we log and move on.
+        """
+        connection = state.get_connection()
+        if connection is None:
+            return
+        try:
+            await connection.session_update(session_id, update)
+        except Exception:  # noqa: BLE001
+            logger.exception("Failed to emit session/update")
+
+    @staticmethod
+    def _is_success(result: Any) -> bool:
+        """Best-effort success check mirroring frontend_emitter's heuristic."""
+        if isinstance(result, dict):
+            if result.get("error"):
+                return False
+            if result.get("success") is False:
+                return False
+        return True
+
+    @staticmethod
+    def _summarize(result: Any) -> Any:
+        """Return a JSON-safe, size-bounded view of a tool result."""
+        if result is None or isinstance(result, (str, int, float, bool, dict, list)):
+            if isinstance(result, str) and len(result) > 4000:
+                return result[:3997] + "..."
+            return result
+        rendered = str(result)
+        return rendered[:3997] + "..." if len(rendered) > 4000 else rendered

code_puppy_core_plugins/acp/capabilities.py

@@ -0,0 +1,73 @@
+"""ACP capability negotiation, expressed in the official SDK models.
+
+Both sides of an ACP connection describe what they can do. The client sends its
+``ClientCapabilities`` (can it read/write files? run terminals?) and expects
+our ``AgentCapabilities`` back. The SDK provides typed models for both, so
+this module is a thin, declarative mapping — no hand-rolled JSON.
+
+Keeping the shapes here means ``agent.py`` stays about lifecycle, and the one
+place we decide "what does Code Puppy advertise" is obvious and reviewable.
+"""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+from acp.schema import (
+    AgentCapabilities,
+    ClientCapabilities,
+    PromptCapabilities,
+    SessionAdditionalDirectoriesCapabilities,
+    SessionCapabilities,
+    SessionCloseCapabilities,
+    SessionForkCapabilities,
+    SessionListCapabilities,
+    SessionResumeCapabilities,
+)
+
+
+def agent_capabilities() -> AgentCapabilities:
+    """Describe what Code Puppy can do, for the ``initialize`` response.
+
+    * ``prompt_capabilities.embedded_context`` — we splice embedded text
+      resources into the prompt (see ``content.py``), so this is honestly
+      ``True``. ``image`` is also ``True``: image blocks are decoded into
+      ``BinaryContent`` / ``ImageUrl`` attachments (see ``content.py``). Audio
+      input is not consumed yet, so ``audio`` stays ``False``.
+    * ``load_session`` — we accept ``session/load`` and rehydrate the
+      session's persisted history into a fresh agent, so re-opened threads
+      continue the real conversation.
+    * ``session_capabilities`` — we support ``list``, ``close``, ``fork``
+      (in-memory history duplication), ``resume`` (persisted rehydration), and
+      ``additional_directories`` (multi-root), all advertised via the SDK's
+      marker sub-models.
+    """
+    return AgentCapabilities(
+        prompt_capabilities=PromptCapabilities(
+            image=True, audio=False, embedded_context=True
+        ),
+        load_session=True,
+        session_capabilities=SessionCapabilities(
+            list=SessionListCapabilities(),
+            close=SessionCloseCapabilities(),
+            fork=SessionForkCapabilities(),
+            resume=SessionResumeCapabilities(),
+            additional_directories=SessionAdditionalDirectoriesCapabilities(),
+        ),
+    )
+
+
+def client_io_caps(caps: ClientCapabilities | None) -> Tuple[bool, bool, bool]:
+    """Return ``(fs_read, fs_write, terminal)`` from the client's capabilities.
+
+    Drives which I/O edges we delegate to the client vs run locally. Defensive: a
+    ``None`` blob or a newer client that omits fields degrades to "run
+    locally", never to a crash.
+    """
+    if caps is None:
+        return False, False, False
+    fs = getattr(caps, "fs", None)
+    fs_read = bool(getattr(fs, "read_text_file", False)) if fs else False
+    fs_write = bool(getattr(fs, "write_text_file", False)) if fs else False
+    terminal = bool(getattr(caps, "terminal", False))
+    return fs_read, fs_write, terminal

code_puppy_core_plugins/acp/commands.py

@@ -0,0 +1,116 @@
+"""Execute client-typed slash commands headless and return their output.
+
+The advertised ``available_commands_update`` tells the client which ``/commands``
+Code Puppy exposes; when the user picks one, the client sends it as a prompt.
+Rather than feed ``/help`` to the model, we route it through Code Puppy's
+``command_handler`` and forward whatever it emits on the message bus back as an
+``agent_message_chunk``.
+
+Command side-effects go to the ``MessageBus`` (``emit_info`` etc.), which has no
+renderer in ACP mode. We capture that output by attaching a listener + draining
+the queue around the call. We deliberately do **not** touch ``sys.stdin`` — the
+SDK reads the JSON-RPC pipe from it — so interactive prompt_toolkit menus (a TUI
+affordance) simply aren't driven over ACP; non-interactive commands (``/help``,
+status-style commands) work well. Everything is best-effort and never raises
+into the turn.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, List, Optional
+
+from code_puppy_core_plugins.acp import state
+
+logger = logging.getLogger(__name__)
+
+
+def is_command(text: str) -> bool:
+    """True if ``text`` is a leading ``/slash`` command."""
+    return text.strip().startswith("/")
+
+
+async def run(session_id: str, command: str) -> Optional[str]:
+    """Execute ``command`` and forward its bus output to the client.
+
+    Returns ``None`` when the command was fully handled (its output has been
+    forwarded to the client). Returns a **string** when the command handler
+    signalled "process this as user input" -- i.e. a custom/markdown command
+    that expands into a prompt for the model. The caller then runs the agent on
+    that string, exactly as ``cli_runner`` does with a string command result.
+    Internal ``__SENTINEL__`` strings (e.g. ``__AUTOSAVE_LOAD__``) are TUI-only
+    affordances with no ACP meaning, so they are treated as handled, not modelled.
+    """
+    from code_puppy.command_line.command_handler import handle_command
+    from code_puppy.messaging.message_queue import get_global_queue
+
+    queue = get_global_queue()
+    collected: List[Any] = []
+
+    def _listener(message: Any) -> None:
+        collected.append(message)
+
+    queue.add_listener(_listener)
+    result: Any = None
+    try:
+        result = await asyncio.to_thread(handle_command, command.strip())
+    except Exception:  # noqa: BLE001
+        logger.debug("ACP: slash command failed", exc_info=True)
+    finally:
+        # Drain anything still queued (no renderer thread runs in ACP mode).
+        while True:
+            message = queue.get_nowait()
+            if message is None:
+                break
+            collected.append(message)
+        queue.remove_listener(_listener)
+
+    text = _render(collected)
+    if _is_prompt_expansion(result):
+        # Handler expanded the command into a prompt: surface any incidental bus
+        # output first, then hand the prompt back to the caller to run through the
+        # agent (not display it as a canned answer).
+        if text:
+            await _emit(session_id, text)
+        return result.strip()
+    await _emit(session_id, text or f"Ran `{command.strip()}`.")
+    return None
+
+
+def _is_prompt_expansion(result: Any) -> bool:
+    """True if ``handle_command`` returned a string to be modelled as a prompt.
+
+    A non-empty string means "process as user input"; ``__SENTINEL__`` strings
+    are internal TUI markers (e.g. ``__AUTOSAVE_LOAD__``) that must not reach
+    the model.
+    """
+    if not isinstance(result, str):
+        return False
+    stripped = result.strip()
+    if not stripped:
+        return False
+    return not (stripped.startswith("__") and stripped.endswith("__"))
+
+
+def _render(messages: List[Any]) -> str:
+    """Flatten captured bus messages into display text."""
+    out: List[str] = []
+    for message in messages:
+        content = getattr(message, "content", None)
+        if content is None:
+            continue
+        out.append(content if isinstance(content, str) else str(content))
+    return "\n".join(s for s in out if s).strip()
+
+
+async def _emit(session_id: str, text: str) -> None:
+    from acp.helpers import update_agent_message_text
+
+    connection = state.get_connection()
+    if connection is None or not text:
+        return
+    try:
+        await connection.session_update(session_id, update_agent_message_text(text))
+    except Exception:  # noqa: BLE001
+        logger.debug("ACP: command output emit failed", exc_info=True)

code_puppy_core_plugins/acp/content.py

@@ -0,0 +1,115 @@
+"""Parse ACP prompt content blocks into a Code Puppy prompt.
+
+The client delivers a prompt as a list of typed content blocks. The SDK parses
+the wire into pydantic models before our ``prompt`` handler runs, so we work
+with objects (``TextContentBlock``, ``ImageContentBlock``,
+``EmbeddedResourceContentBlock``, …) rather than raw dicts.
+
+We split a prompt into three parts that map onto ``run_with_mcp``'s signature:
+
+* **text** — text blocks, embedded text resources (spliced in under a header,
+  honouring the advertised ``embeddedContext`` capability), and resource-link
+  references.
+* **attachments** — image blocks carrying base64 data → pydantic-ai
+  ``BinaryContent`` (honouring the advertised ``image`` capability).
+* **link_attachments** — image blocks carrying only a URI → ``ImageUrl``.
+
+Blocks are duck-typed (``getattr``) so a newer SDK adding fields never breaks
+parsing. Audio is not advertised, so audio blocks degrade to a text note.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+from dataclasses import dataclass, field
+from typing import Any, List
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ParsedPrompt:
+    """A prompt split into text + multimodal attachments for ``run_with_mcp``."""
+
+    text: str = ""
+    attachments: List[Any] = field(default_factory=list)  # BinaryContent
+    link_attachments: List[Any] = field(default_factory=list)  # ImageUrl
+
+
+def parse_prompt(blocks: List[Any]) -> ParsedPrompt:
+    """Split a list of ACP content blocks into text + attachments."""
+    parts: List[str] = []
+    result = ParsedPrompt()
+    for block in blocks or []:
+        text = _render_block(block, result)
+        if text:
+            parts.append(text)
+    result.text = "\n\n".join(parts)
+    return result
+
+
+def flatten_prompt(blocks: List[Any]) -> str:
+    """Back-compat text-only view (used where attachments aren't needed)."""
+    return parse_prompt(blocks).text
+
+
+def _render_block(block: Any, result: ParsedPrompt) -> str:
+    block_type = getattr(block, "type", None)
+
+    if block_type == "text":
+        return getattr(block, "text", "") or ""
+
+    if block_type == "resource":
+        return _render_embedded_resource(getattr(block, "resource", None))
+
+    if block_type == "resource_link":
+        uri = getattr(block, "uri", "") or ""
+        name = getattr(block, "name", "") or uri
+        return f"[Referenced resource: {name} ({uri})]" if uri else ""
+
+    if block_type == "image":
+        _collect_image(block, result)
+        return ""
+
+    if block_type == "audio":
+        return "[Audio attached]"
+
+    # Unknown/newer block type: fall back to any ``text`` it carries.
+    return getattr(block, "text", "") or ""
+
+
+def _collect_image(block: Any, result: ParsedPrompt) -> None:
+    """Turn an image block into a BinaryContent (data) or ImageUrl (uri)."""
+    data = getattr(block, "data", None)
+    mime = getattr(block, "mime_type", None) or "image/png"
+    if data:
+        try:
+            from pydantic_ai import BinaryContent
+
+            result.attachments.append(
+                BinaryContent(data=base64.b64decode(data), media_type=mime)
+            )
+            return
+        except Exception:  # noqa: BLE001
+            logger.debug("ACP: could not decode image data", exc_info=True)
+    uri = getattr(block, "uri", None)
+    if uri:
+        try:
+            from pydantic_ai import ImageUrl
+
+            result.link_attachments.append(ImageUrl(url=uri))
+        except Exception:  # noqa: BLE001
+            logger.debug("ACP: could not build ImageUrl", exc_info=True)
+
+
+def _render_embedded_resource(resource: Any) -> str:
+    """Render an embedded resource; only the text variant carries usable text."""
+    if resource is None:
+        return ""
+    text = getattr(resource, "text", None)
+    if not text:
+        uri = getattr(resource, "uri", "") or ""
+        return f"[Embedded binary resource: {uri}]" if uri else ""
+    uri = getattr(resource, "uri", "") or "embedded"
+    return f"<context uri={uri!r}>\n{text}\n</context>"