agentpool 2.1.9__py3-none-any.whl

acp/tool_call_reporter.py

@@ -0,0 +1,199 @@
+"""Stateful tool call progress reporter for ACP."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Self
+
+from acp.schema.tool_call import ToolCallLocation
+
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    import types
+
+    from acp.notifications import ACPNotifications
+    from acp.schema.tool_call import (
+        ToolCallContent,
+        ToolCallKind,
+        ToolCallStatus,
+    )
+
+
+class ToolCallReporter:
+    """Stateful reporter for tool call progress.
+
+    Maintains the current state of a tool call and sends updates
+    when fields are modified. This avoids having to repeat unchanged
+    fields on every progress update.
+
+    Example:
+        ```python
+        reporter = await notifications.create_tool_reporter(
+            tool_call_id="abc123",
+            title="Reading file",
+            kind="read",
+        )
+        await reporter.update(status="in_progress", message="Opening file...")
+        await reporter.update(progress=0.5)
+        await reporter.update(status="completed", message="Done!")
+        ```
+    """
+
+    def __init__(
+        self,
+        notifications: ACPNotifications,
+        tool_call_id: str,
+        title: str,
+        *,
+        kind: ToolCallKind | None = None,
+        status: ToolCallStatus = "pending",
+        locations: Sequence[ToolCallLocation] | None = None,
+        content: Sequence[ToolCallContent] | None = None,
+        raw_input: Any | None = None,
+        raw_output: Any | None = None,
+    ) -> None:
+        """Initialize the reporter with initial state.
+
+        Args:
+            notifications: The ACPNotifications instance to send updates through
+            tool_call_id: Unique identifier for this tool call
+            title: Human-readable title describing the tool action
+            kind: Category of tool being invoked
+            status: Initial execution status
+            locations: File locations affected by this tool call
+            content: Content produced by the tool call
+            raw_input: Raw input parameters sent to the tool
+            raw_output: Raw output returned by the tool
+        """
+        self._notifications = notifications
+        self.tool_call_id = tool_call_id
+        self.title = title
+        self.kind: ToolCallKind | None = kind
+        self.status: ToolCallStatus = status
+        self.locations: list[ToolCallLocation] = list(locations) if locations else []
+        self.content: list[ToolCallContent] = list(content) if content else []
+        self.raw_input = raw_input
+        self.raw_output = raw_output
+        self._started = False
+
+    async def start(self) -> None:
+        """Send the initial tool_call notification.
+
+        This is called automatically if you use `create_tool_reporter`,
+        but can be called manually if constructing the reporter directly.
+        """
+        if self._started:
+            return
+
+        await self._notifications.tool_call_start(
+            tool_call_id=self.tool_call_id,
+            title=self.title,
+            kind=self.kind,
+            locations=self.locations or None,
+            content=self.content or None,
+            raw_input=self.raw_input,
+        )
+        self._started = True
+
+    async def update(
+        self,
+        *,
+        title: str | None = None,
+        status: ToolCallStatus | None = None,
+        kind: ToolCallKind | None = None,
+        message: str | None = None,
+        raw_output: Any | None = None,
+        locations: Sequence[ToolCallLocation | str] | None = None,
+        content: Sequence[ToolCallContent | str] | None = None,
+        replace: bool = False,
+    ) -> None:
+        """Update one or more fields and send the updated state.
+
+        Args:
+            title: Update the human-readable title
+            status: Update the execution status
+            kind: Update the tool kind
+            message: Convenience for adding a text content block
+            raw_output: Update the raw output
+            locations: Locations to add or replace (path strings or ToolCallLocation)
+            content: Content blocks to add or replace
+            replace: If True, replace all content/locations; if False, append
+        """
+        if not self._started:
+            await self.start()
+
+        # Update stored state
+        if title is not None:
+            self.title = title
+        if status is not None:
+            self.status = status
+        if kind is not None:
+            self.kind = kind
+        if raw_output is not None:
+            self.raw_output = raw_output
+
+        # Handle locations
+        if locations is not None:
+            normalized = [
+                ToolCallLocation(path=loc) if isinstance(loc, str) else loc for loc in locations
+            ]
+            if replace:
+                self.locations = normalized
+            else:
+                self.locations.extend(normalized)
+
+        # Handle content (strings will be converted by tool_call_progress)
+        if content is not None:
+            content_list: list[ToolCallContent | str] = list(content)
+            if replace:
+                self.content = content_list  # type: ignore[assignment]
+            else:
+                self.content.extend(content_list)  # type: ignore[arg-type]
+
+        if message is not None:
+            self.content.append(message)  # type: ignore[arg-type]
+
+        await self._notifications.tool_call_progress(
+            tool_call_id=self.tool_call_id,
+            status=self.status,
+            title=self.title,
+            kind=self.kind,
+            locations=self.locations or None,
+            content=self.content or None,
+            raw_output=self.raw_output,
+        )
+
+    async def complete(self, *, message: str | None = None, raw_output: Any | None = None) -> None:
+        """Mark the tool call as completed.
+
+        Args:
+            message: Optional final message to add
+            raw_output: Optional final output
+        """
+        await self.update(status="completed", message=message, raw_output=raw_output)
+
+    async def fail(self, *, error: str | None = None, raw_output: Any | None = None) -> None:
+        """Mark the tool call as failed.
+
+        Args:
+            error: Optional error message to add
+            raw_output: Optional output (e.g., error details)
+        """
+        await self.update(status="failed", message=error, raw_output=raw_output)
+
+    async def __aenter__(self) -> Self:
+        """Enter async context, starting the tool call."""
+        await self.start()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: types.TracebackType | None,
+    ) -> None:
+        """Exit async context, marking complete or failed based on exception."""
+        if exc_type is not None:
+            await self.fail(error=str(exc_val) if exc_val else "Unknown error")
+        elif self.status not in ("completed", "failed"):
+            await self.complete()

acp/tool_call_state.py

@@ -0,0 +1,178 @@
+"""Stateful tool call tracker for ACP.
+
+This module provides a simple state tracker for tool calls that sends
+only changed fields in updates, following the ACP protocol spec.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from acp.notifications import ACPNotifications
+    from acp.schema.tool_call import ToolCallContent, ToolCallKind, ToolCallLocation, ToolCallStatus
+
+
+class ToolCallState:
+    """Tracks tool call state and sends delta updates.
+
+    Instead of accumulating all state and sending everything on each update,
+    this class tracks whether we've started and sends only the fields that
+    are explicitly provided in each update call.
+
+    The ACP protocol spec states:
+    "All fields except toolCallId are optional in updates.
+     Only the fields being changed need to be included."
+
+    Example flow:
+        1. Tool call starts → state.start() sends initial notification
+        2. Progress event → state.update(title="Running...") sends just title
+        3. More progress → state.update(content=[...]) sends just content
+        4. Tool completes → state.complete(raw_output=result) sends status + output
+    """
+
+    def __init__(
+        self,
+        notifications: ACPNotifications,
+        tool_call_id: str,
+        tool_name: str,
+        title: str,
+        kind: ToolCallKind,
+        raw_input: dict[str, Any],
+    ) -> None:
+        """Initialize tool call state.
+
+        Args:
+            notifications: ACPNotifications instance for sending updates
+            tool_call_id: Unique identifier for this tool call
+            tool_name: Name of the tool being called
+            title: Initial human-readable title
+            kind: Category of tool (read, edit, execute, etc.)
+            raw_input: Input parameters passed to the tool
+        """
+        self._notifications = notifications
+        self.tool_call_id = tool_call_id
+        self.tool_name = tool_name
+        self._initial_title = title
+        self._initial_kind: ToolCallKind = kind
+        self._raw_input = raw_input
+        self._started = False
+        self._has_content = False  # Track if content has been sent
+
+    @property
+    def has_content(self) -> bool:
+        """Whether content has been sent for this tool call."""
+        return self._has_content
+
+    async def start(self) -> None:
+        """Send initial tool_call notification.
+
+        This creates the tool call entry in the client UI. Subsequent calls
+        to update() will send tool_call_update notifications with only
+        the changed fields.
+        """
+        if self._started:
+            return
+
+        await self._notifications.tool_call_start(
+            tool_call_id=self.tool_call_id,
+            title=self._initial_title,
+            kind=self._initial_kind,
+            raw_input=self._raw_input,
+        )
+        self._started = True
+
+    async def update(
+        self,
+        *,
+        title: str | None = None,
+        status: ToolCallStatus | None = None,
+        kind: ToolCallKind | None = None,
+        content: Sequence[ToolCallContent] | None = None,
+        locations: Sequence[ToolCallLocation | str] | None = None,
+        raw_output: Any = None,
+    ) -> None:
+        """Send an update with only the provided fields.
+
+        Args:
+            title: Update the human-readable title
+            status: Update execution status
+            kind: Update tool kind
+            content: Content items (terminals, diffs, text) - replaces previous
+            locations: File locations - replaces previous
+            raw_output: Update raw output data
+
+        Note:
+            Only fields that are truthy (not None/empty) will be included
+            in the notification. This follows the ACP spec which states
+            that only changed fields need to be sent.
+        """
+        from acp.schema.tool_call import ToolCallLocation
+
+        if not self._started:
+            await self.start()
+        # Build kwargs with only the provided fields
+        kwargs: dict[str, Any] = {}
+        if title is not None:
+            kwargs["title"] = title
+        if status is not None:
+            kwargs["status"] = status
+        if kind is not None:
+            kwargs["kind"] = kind
+        if content:
+            kwargs["content"] = content
+            self._has_content = True
+        if locations:
+            # Normalize string paths to ToolCallLocation
+            kwargs["locations"] = [
+                ToolCallLocation(path=loc) if isinstance(loc, str) else loc for loc in locations
+            ]
+        if raw_output is not None:
+            kwargs["raw_output"] = raw_output
+
+        # Only send if there's something to update
+        if kwargs:
+            await self._notifications.tool_call_update(
+                tool_call_id=self.tool_call_id,
+                **kwargs,
+            )
+
+    async def complete(
+        self,
+        raw_output: Any = None,
+        *,
+        content: Sequence[ToolCallContent] | None = None,
+        title: str | None = None,
+    ) -> None:
+        """Mark tool call as completed.
+
+        Args:
+            raw_output: Final output data
+            content: Optional final content
+            title: Optional final title
+        """
+        await self.update(
+            status="completed",
+            raw_output=raw_output,
+            content=content,
+            title=title,
+        )
+
+    async def fail(self, error: str | None = None, *, raw_output: Any = None) -> None:
+        """Mark tool call as failed.
+
+        Args:
+            error: Error message to display
+            raw_output: Optional error details
+        """
+        from acp.schema import ContentToolCallContent
+
+        content = None
+        if error:
+            error_content = ContentToolCallContent.text(text=f"Error: {error}")
+            content = [error_content]
+
+        await self.update(status="failed", content=content, raw_output=raw_output)

acp/transports.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import contextlib
+from contextlib import asynccontextmanager
+import os
+import subprocess
+from typing import TYPE_CHECKING
+
+import anyio
+
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Mapping
+    from pathlib import Path
+
+    from anyio.abc import ByteReceiveStream, ByteSendStream, Process
+
+
+DEFAULT_INHERITED_ENV_VARS = (
+    [
+        "APPDATA",
+        "HOMEDRIVE",
+        "HOMEPATH",
+        "LOCALAPPDATA",
+        "PATH",
+        "PATHEXT",
+        "PROCESSOR_ARCHITECTURE",
+        "SYSTEMDRIVE",
+        "SYSTEMROOT",
+        "TEMP",
+        "USERNAME",
+        "USERPROFILE",
+    ]
+    if os.name == "nt"
+    else ["HOME", "LOGNAME", "PATH", "SHELL", "TERM", "USER"]
+)
+
+
+def default_environment() -> dict[str, str]:
+    """Return a trimmed environment based on MCP best practices."""
+    env: dict[str, str] = {}
+    for key in DEFAULT_INHERITED_ENV_VARS:
+        value = os.environ.get(key)
+        if value is None:
+            continue
+        # Skip function-style env vars on some shells (see MCP reference)
+        if value.startswith("()"):
+            continue
+        env[key] = value
+    return env
+
+
+@asynccontextmanager
+async def spawn_stdio_transport(
+    command: str,
+    *args: str,
+    env: Mapping[str, str] | None = None,
+    cwd: str | Path | None = None,
+    stderr: int | None = subprocess.PIPE,
+    shutdown_timeout: float = 2.0,
+) -> AsyncIterator[tuple[ByteReceiveStream, ByteSendStream, Process]]:
+    """Launch a subprocess and expose its stdio streams as anyio streams.
+
+    This mirrors the defensive shutdown behaviour used by the MCP Python SDK:
+    close stdin first, wait for graceful exit, then escalate to terminate/kill.
+    """
+    merged_env = default_environment()
+    if env:
+        merged_env.update(env)
+
+    process = await anyio.open_process(
+        [command, *args],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=stderr,
+        env=merged_env,
+        cwd=str(cwd) if cwd is not None else None,
+    )
+
+    if process.stdout is None or process.stdin is None:
+        process.kill()
+        await process.wait()
+        msg = "spawn_stdio_transport requires stdout/stdin pipes"
+        raise RuntimeError(msg)
+
+    try:
+        yield process.stdout, process.stdin, process
+    finally:
+        # Attempt graceful stdin shutdown first
+        if process.stdin is not None:
+            with contextlib.suppress(Exception):
+                await process.stdin.aclose()
+
+        try:
+            with anyio.fail_after(shutdown_timeout):
+                await process.wait()
+        except TimeoutError:
+            process.terminate()
+            try:
+                with anyio.fail_after(shutdown_timeout):
+                    await process.wait()
+            except TimeoutError:
+                process.kill()
+                await process.wait()