agentpool 2.1.9__py3-none-any.whl

agentpool/agents/claude_code_agent/converters.py

@@ -0,0 +1,243 @@
+"""Claude Agent SDK to native event converters.
+
+This module provides conversion from Claude Agent SDK message types to native
+agentpool streaming events, enabling ClaudeCodeAgent to yield the same
+event types as native agents.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from pydantic_ai import PartDeltaEvent, TextPartDelta, ThinkingPartDelta
+
+from agentpool.agents.events import (
+    DiffContentItem,
+    LocationContentItem,
+    ToolCallCompleteEvent,
+    ToolCallStartEvent,
+)
+
+
+if TYPE_CHECKING:
+    from claude_agent_sdk import ContentBlock, Message, ToolUseBlock
+
+    from agentpool.agents.events import RichAgentStreamEvent, ToolCallContentItem
+    from agentpool.tools.base import ToolKind
+
+
+@dataclass
+class RichToolInfo:
+    """Rich display information derived from tool name and input."""
+
+    title: str
+    """Human-readable title for the tool call."""
+    kind: ToolKind = "other"
+    """Category of tool operation."""
+    locations: list[LocationContentItem] = field(default_factory=list)
+    """File locations involved in the operation."""
+    content: list[ToolCallContentItem] = field(default_factory=list)
+    """Rich content items (diffs, text, etc.)."""
+
+
+def derive_rich_tool_info(name: str, input_data: dict[str, Any]) -> RichToolInfo:  # noqa: PLR0911, PLR0915
+    """Derive rich display info from tool name and input arguments.
+
+    Maps MCP tool names and their inputs to human-readable titles, kinds,
+    and location information for rich UI display. Handles both Claude Code
+    built-in tools and MCP bridge tools.
+
+    Args:
+        name: The tool name (e.g., "Read", "mcp__server__read_file")
+        input_data: The tool input arguments
+
+    Returns:
+        RichToolInfo with derived display information
+    """
+    # Extract the actual tool name if it's an MCP bridge tool
+    # Format: mcp__{server_name}__{tool_name}
+    actual_name = name
+    if name.startswith("mcp__") and "__" in name[5:]:
+        parts = name.split("__")
+        if len(parts) >= 3:  # noqa: PLR2004
+            actual_name = parts[-1]  # Get the last part (actual tool name)
+
+    # Normalize to lowercase for matching
+    tool_lower = actual_name.lower()
+    # Read operations
+    if tool_lower in ("read", "read_file"):
+        path = input_data.get("file_path") or input_data.get("path", "")
+        offset = input_data.get("offset") or input_data.get("line")
+        limit = input_data.get("limit")
+
+        suffix = ""
+        if limit:
+            start = (offset or 0) + 1
+            end = (offset or 0) + limit
+            suffix = f" ({start}-{end})"
+        elif offset:
+            suffix = f" (from line {offset + 1})"
+        title = f"Read {path}{suffix}" if path else "Read File"
+        locations = [LocationContentItem(path=path, line=offset or 0)] if path else []
+        return RichToolInfo(title=title, kind="read", locations=locations)
+
+    # Write operations
+    if tool_lower in ("write", "write_file"):
+        path = input_data.get("file_path") or input_data.get("path", "")
+        content = input_data.get("content", "")
+        return RichToolInfo(
+            title=f"Write {path}" if path else "Write File",
+            kind="edit",
+            locations=[LocationContentItem(path=path)] if path else [],
+            content=[DiffContentItem(path=path, old_text=None, new_text=content)] if path else [],
+        )
+    # Edit operations
+    if tool_lower in ("edit", "edit_file"):
+        path = input_data.get("file_path") or input_data.get("path", "")
+        old_string = input_data.get("old_string") or input_data.get("old_text", "")
+        new_string = input_data.get("new_string") or input_data.get("new_text", "")
+        return RichToolInfo(
+            title=f"Edit {path}" if path else "Edit File",
+            kind="edit",
+            locations=[LocationContentItem(path=path)] if path else [],
+            content=[DiffContentItem(path=path, old_text=old_string, new_text=new_string)]
+            if path
+            else [],
+        )
+    # Delete operations
+    if tool_lower in ("delete", "delete_path", "delete_file"):
+        path = input_data.get("file_path") or input_data.get("path", "")
+        locations = [LocationContentItem(path=path)] if path else []
+        title = f"Delete {path}" if path else "Delete"
+        return RichToolInfo(title=title, kind="delete", locations=locations)
+    # Bash/terminal operations
+    if tool_lower in ("bash", "execute", "run_command", "execute_command", "execute_code"):
+        command = input_data.get("command") or input_data.get("code", "")
+        # Escape backticks in command
+        escaped_cmd = command.replace("`", "\\`") if command else ""
+        title = f"`{escaped_cmd}`" if escaped_cmd else "Terminal"
+        return RichToolInfo(title=title, kind="execute")
+    # Search operations
+    if tool_lower in ("grep", "search", "glob", "find"):
+        pattern = input_data.get("pattern") or input_data.get("query", "")
+        path = input_data.get("path", "")
+        title = f"Search for '{pattern}'" if pattern else "Search"
+        if path:
+            title += f" in {path}"
+        locations = [LocationContentItem(path=path)] if path else []
+        return RichToolInfo(title=title, kind="search", locations=locations)
+    # List directory
+    if tool_lower in ("ls", "list", "list_directory"):
+        path = input_data.get("path", ".")
+        title = f"List {path}" if path != "." else "List current directory"
+        locations = [LocationContentItem(path=path)] if path else []
+        return RichToolInfo(title=title, kind="search", locations=locations)
+    # Web operations
+    if tool_lower in ("webfetch", "web_fetch", "fetch"):
+        url = input_data.get("url", "")
+        return RichToolInfo(title=f"Fetch {url}" if url else "Web Fetch", kind="fetch")
+    if tool_lower in ("websearch", "web_search", "search_web"):
+        query = input_data.get("query", "")
+        return RichToolInfo(title=f"Search: {query}" if query else "Web Search", kind="fetch")
+    # Task/subagent operations
+    if tool_lower == "task":
+        description = input_data.get("description", "")
+        return RichToolInfo(title=description if description else "Task", kind="think")
+    # Notebook operations
+    if tool_lower in ("notebookread", "notebook_read"):
+        path = input_data.get("notebook_path", "")
+        title = f"Read Notebook {path}" if path else "Read Notebook"
+        locations = [LocationContentItem(path=path)] if path else []
+        return RichToolInfo(title=title, kind="read", locations=locations)
+    if tool_lower in ("notebookedit", "notebook_edit"):
+        path = input_data.get("notebook_path", "")
+        title = f"Edit Notebook {path}" if path else "Edit Notebook"
+        locations = [LocationContentItem(path=path)] if path else []
+        return RichToolInfo(title=title, kind="edit", locations=locations)
+    # Default: use the tool name as title
+    return RichToolInfo(title=actual_name, kind="other")
+
+
+def content_block_to_event(block: ContentBlock, index: int = 0) -> RichAgentStreamEvent[Any] | None:
+    """Convert a Claude SDK ContentBlock to a streaming event.
+
+    Args:
+        block: Claude SDK content block
+        index: Part index for the event
+
+    Returns:
+        Corresponding streaming event, or None if not mappable
+    """
+    from claude_agent_sdk import TextBlock, ThinkingBlock, ToolUseBlock
+
+    match block:
+        case TextBlock(text=text):
+            return PartDeltaEvent(index=index, delta=TextPartDelta(content_delta=text))
+        case ThinkingBlock(thinking=thinking):
+            return PartDeltaEvent(index=index, delta=ThinkingPartDelta(content_delta=thinking))
+        case ToolUseBlock(id=tool_id, name=name, input=input_data):
+            rich_info = derive_rich_tool_info(name, input_data)
+            return ToolCallStartEvent(
+                tool_call_id=tool_id,
+                tool_name=name,
+                title=rich_info.title,
+                kind=rich_info.kind,
+                locations=rich_info.locations,
+                content=rich_info.content,
+                raw_input=input_data,
+            )
+        case _:
+            return None
+
+
+def claude_message_to_events(
+    message: Message,
+    agent_name: str = "",
+    pending_tool_calls: dict[str, ToolUseBlock] | None = None,
+) -> list[RichAgentStreamEvent[Any]]:
+    """Convert a Claude SDK Message to a list of streaming events.
+
+    Args:
+        message: Claude SDK message (UserMessage, AssistantMessage, etc.)
+        agent_name: Name of the agent for event attribution
+        pending_tool_calls: Dict to track tool calls awaiting results
+
+    Returns:
+        List of corresponding streaming events
+    """
+    from claude_agent_sdk import AssistantMessage, ToolResultBlock, ToolUseBlock
+
+    events: list[RichAgentStreamEvent[Any]] = []
+
+    match message:
+        case AssistantMessage(content=content):
+            for idx, block in enumerate(content):
+                # Track tool use blocks for later pairing with results
+                if isinstance(block, ToolUseBlock) and pending_tool_calls is not None:
+                    pending_tool_calls[block.id] = block
+
+                # Handle tool results - pair with pending tool call
+                if isinstance(block, ToolResultBlock) and pending_tool_calls is not None:
+                    tool_use = pending_tool_calls.pop(block.tool_use_id, None)
+                    if tool_use:
+                        complete_event = ToolCallCompleteEvent(
+                            tool_name=tool_use.name,
+                            tool_call_id=block.tool_use_id,
+                            tool_input=tool_use.input,
+                            tool_result=block.content,
+                            agent_name=agent_name,
+                            message_id="",
+                        )
+                        events.append(complete_event)
+                    continue
+
+                # Convert other blocks to events
+                if event := content_block_to_event(block, index=idx):
+                    events.append(event)
+
+        case _:
+            # UserMessage, SystemMessage, ResultMessage - no events to emit
+            pass
+
+    return events

agentpool/agents/context.py

@@ -0,0 +1,105 @@
+"""Runtime context models for Agents."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal
+
+from agentpool.log import get_logger
+from agentpool.messaging.context import NodeContext
+
+
+if TYPE_CHECKING:
+    from mcp import types
+
+    from agentpool import Agent
+    from agentpool.agents.events import StreamEventEmitter
+    from agentpool.models.acp_agents.base import BaseACPAgentConfig
+    from agentpool.models.agents import NativeAgentConfig
+    from agentpool.models.agui_agents import AGUIAgentConfig
+    from agentpool.models.claude_code_agents import ClaudeCodeAgentConfig
+    from agentpool.tools.base import Tool
+
+
+ConfirmationResult = Literal["allow", "skip", "abort_run", "abort_chain"]
+
+logger = get_logger(__name__)
+
+
+@dataclass(kw_only=True)
+class AgentContext[TDeps = Any](NodeContext[TDeps]):
+    """Runtime context for agent execution.
+
+    Generically typed with AgentContext[Type of Dependencies]
+    """
+
+    config: NativeAgentConfig | BaseACPAgentConfig | AGUIAgentConfig | ClaudeCodeAgentConfig
+    """Current agent's specific configuration."""
+
+    tool_name: str | None = None
+    """Name of the currently executing tool."""
+
+    tool_call_id: str | None = None
+    """ID of the current tool call."""
+
+    tool_input: dict[str, Any] = field(default_factory=dict)
+    """Input arguments for the current tool call."""
+
+    @property
+    def native_agent(self) -> Agent[TDeps, Any]:
+        """Current agent, type-narrowed to native pydantic-ai Agent."""
+        from agentpool import Agent
+
+        assert isinstance(self.node, Agent)
+        return self.node
+
+    async def handle_elicitation(
+        self,
+        params: types.ElicitRequestParams,
+    ) -> types.ElicitResult | types.ErrorData:
+        """Handle elicitation request for additional information."""
+        provider = self.get_input_provider()
+        return await provider.get_elicitation(params)
+
+    async def report_progress(self, progress: float, total: float | None, message: str) -> None:
+        """Report progress by emitting event into the agent's stream."""
+        from agentpool.agents.events import ToolCallProgressEvent
+
+        logger.info("Reporting tool call progress", progress=progress, total=total, message=message)
+        progress_event = ToolCallProgressEvent(
+            progress=int(progress),
+            total=int(total) if total is not None else 100,
+            message=message,
+            tool_name=self.tool_name or "",
+            tool_call_id=self.tool_call_id or "",
+            tool_input=self.tool_input,
+        )
+        await self.agent._event_queue.put(progress_event)
+
+    @property
+    def events(self) -> StreamEventEmitter:
+        """Get event emitter with context automatically injected."""
+        from agentpool.agents.events import StreamEventEmitter
+
+        return StreamEventEmitter(self)
+
+    async def handle_confirmation(self, tool: Tool, args: dict[str, Any]) -> ConfirmationResult:
+        """Handle tool execution confirmation.
+
+        Returns "allow" if:
+        - No confirmation handler is set
+        - Handler confirms the execution
+
+        Args:
+            tool: The tool being executed
+            args: Arguments passed to the tool
+
+        Returns:
+            Confirmation result indicating how to proceed
+        """
+        provider = self.get_input_provider()
+        mode = self.agent.tool_confirmation_mode
+        if (mode == "per_tool" and not tool.requires_confirmation) or mode == "never":
+            return "allow"
+        history = self.agent.conversation.get_history() if self.pool else []
+        return await provider.get_tool_confirmation(self, tool, args, history)

agentpool/agents/events/__init__.py

@@ -0,0 +1,61 @@
+"""Agent events."""
+
+from .events import (
+    CommandCompleteEvent,
+    CommandOutputEvent,
+    CustomEvent,
+    DiffContentItem,
+    FileContentItem,
+    LocationContentItem,
+    PlanUpdateEvent,
+    RichAgentStreamEvent,
+    RunErrorEvent,
+    RunStartedEvent,
+    SlashedAgentStreamEvent,
+    StreamCompleteEvent,
+    TerminalContentItem,
+    TextContentItem,
+    ToolCallCompleteEvent,
+    ToolCallContentItem,
+    ToolCallProgressEvent,
+    ToolCallStartEvent,
+)
+from .event_emitter import StreamEventEmitter
+from .builtin_handlers import (
+    detailed_print_handler,
+    simple_print_handler,
+    resolve_event_handlers,
+)
+from .tts_handlers import (
+    BaseTTSEventHandler,
+    EdgeTTSEventHandler,
+    OpenAITTSEventHandler,
+)
+
+__all__ = [
+    "BaseTTSEventHandler",
+    "CommandCompleteEvent",
+    "CommandOutputEvent",
+    "CustomEvent",
+    "DiffContentItem",
+    "EdgeTTSEventHandler",
+    "FileContentItem",
+    "LocationContentItem",
+    "OpenAITTSEventHandler",
+    "PlanUpdateEvent",
+    "RichAgentStreamEvent",
+    "RunErrorEvent",
+    "RunStartedEvent",
+    "SlashedAgentStreamEvent",
+    "StreamCompleteEvent",
+    "StreamEventEmitter",
+    "TerminalContentItem",
+    "TextContentItem",
+    "ToolCallCompleteEvent",
+    "ToolCallContentItem",
+    "ToolCallProgressEvent",
+    "ToolCallStartEvent",
+    "detailed_print_handler",
+    "resolve_event_handlers",
+    "simple_print_handler",
+]

agentpool/agents/events/builtin_handlers.py

@@ -0,0 +1,129 @@
+"""Built-in event handlers for simple console output."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Any
+
+from pydantic_ai import (
+    FunctionToolCallEvent,
+    FunctionToolResultEvent,
+    PartDeltaEvent,
+    PartStartEvent,
+    TextPart,
+    TextPartDelta,
+    ThinkingPart,
+    ThinkingPartDelta,
+    ToolCallPart,
+    ToolReturnPart,
+)
+
+from agentpool.agents.events import (
+    RunErrorEvent,
+    StreamCompleteEvent,
+    ToolCallProgressEvent,
+    ToolCallStartEvent,
+)
+
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from pydantic_ai import RunContext
+
+    from agentpool.agents.events import RichAgentStreamEvent
+    from agentpool.common_types import BuiltinEventHandlerType, IndividualEventHandler
+
+
+async def simple_print_handler(ctx: RunContext, event: RichAgentStreamEvent[Any]) -> None:
+    """Simple event handler that prints text and basic tool information.
+
+    Focus: Core text output and minimal tool notifications.
+    Prints:
+    - Text content (streaming)
+    - Tool calls (name only)
+    - Errors
+    """
+    match event:
+        case (
+            PartStartEvent(part=TextPart(content=delta))
+            | PartDeltaEvent(delta=TextPartDelta(content_delta=delta))
+        ):
+            print(delta, end="", flush=True, file=sys.stderr)
+
+        case FunctionToolCallEvent(part=ToolCallPart() as part):
+            kwargs_str = ", ".join(f"{k}={v!r}" for k, v in part.args_as_dict().items())
+            print(f"\n🔧 {part.tool_name}({kwargs_str})", flush=True, file=sys.stderr)
+
+        case FunctionToolResultEvent(result=ToolReturnPart() as return_part):
+            print(f"Result: {return_part.content}", file=sys.stderr)
+
+        case RunErrorEvent(message=message):
+            print(f"\n❌ Error: {message}", flush=True, file=sys.stderr)
+
+        case StreamCompleteEvent():
+            print(file=sys.stderr)  # Final newline
+
+
+async def detailed_print_handler(ctx: RunContext, event: RichAgentStreamEvent[Any]) -> None:
+    """Detailed event handler with rich tool execution information.
+
+    Focus: Comprehensive execution visibility.
+    Prints:
+    - Text content (streaming)
+    - Thinking content
+    - Tool calls with inputs
+    - Tool results
+    - Tool progress with title
+    - Errors
+    """
+    match event:
+        case (
+            PartStartEvent(part=TextPart(content=delta))
+            | PartDeltaEvent(delta=TextPartDelta(content_delta=delta))
+        ):
+            print(delta, end="", flush=True, file=sys.stderr)
+
+        case (
+            PartStartEvent(part=ThinkingPart(content=delta))
+            | PartDeltaEvent(delta=ThinkingPartDelta(content_delta=delta))
+        ):
+            if delta:
+                print(f"\n💭 {delta}", end="", flush=True, file=sys.stderr)
+
+        case ToolCallStartEvent(tool_name=tool_name, title=title, tool_call_id=call_id):
+            print(f"\n🔧 {tool_name}: {title} (#{call_id[:8]})", flush=True, file=sys.stderr)
+
+        case FunctionToolCallEvent(part=ToolCallPart(tool_name=tool_name, args=args)):
+            args_str = str(args)
+            if len(args_str) > 100:  # noqa: PLR2004
+                args_str = args_str[:97] + "..."
+            print(f"  📝 Input: {args_str}", flush=True, file=sys.stderr)
+
+        case FunctionToolResultEvent(result=ToolReturnPart(content=content, tool_name=tool_name)):
+            result_str = str(content)
+            if len(result_str) > 150:  # noqa: PLR2004
+                result_str = result_str[:147] + "..."
+            print(f"  ✅ {tool_name}: {result_str}", flush=True, file=sys.stderr)
+
+        case ToolCallProgressEvent(title=title, status=status):
+            if title:
+                emoji = {"completed": "✅", "failed": "❌"}.get(status, "⏳")
+                print(f"  {emoji} {title}", flush=True, file=sys.stderr)
+
+        case RunErrorEvent(message=message, code=code):
+            error_info = f" [{code}]" if code else ""
+            print(f"\n❌ Error{error_info}: {message}", flush=True, file=sys.stderr)
+
+        case StreamCompleteEvent():
+            print(file=sys.stderr)  # Final newline
+
+
+def resolve_event_handlers(
+    event_handlers: Sequence[IndividualEventHandler | BuiltinEventHandlerType] | None,
+) -> list[IndividualEventHandler]:
+    """Resolve event handlers, converting builtin handler names to actual handlers."""
+    if not event_handlers:
+        return []
+    builtin_map = {"simple": simple_print_handler, "detailed": detailed_print_handler}
+    return [builtin_map[h] if isinstance(h, str) else h for h in event_handlers]