agentpool 2.2.3__py3-none-any.whl → 2.5.0__py3-none-any.whl

agentpool/agents/events/builtin_handlers.py

@@ -120,6 +120,71 @@ async def detailed_print_handler(ctx: RunContext, event: RichAgentStreamEvent[An
             print(file=sys.stderr)  # Final newline
 
 
+def create_file_stream_handler(
+    path: str,
+    mode: str = "a",
+    include_tools: bool = False,
+    include_thinking: bool = False,
+) -> IndividualEventHandler:
+    """Create an event handler that streams text output to a file.
+
+    Args:
+        path: Path to the output file
+        mode: File open mode ('w' for overwrite, 'a' for append)
+        include_tools: Whether to include tool call/result information
+        include_thinking: Whether to include thinking content
+
+    Returns:
+        Event handler function that writes to the specified file
+    """
+    from pathlib import Path
+
+    file_path = Path(path).expanduser()
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Open file handle that persists across calls
+    file_handle = file_path.open(mode, encoding="utf-8")
+
+    async def file_stream_handler(ctx: RunContext, event: RichAgentStreamEvent[Any]) -> None:
+        """Stream agent output to file."""
+        match event:
+            case (
+                PartStartEvent(part=TextPart(content=delta))
+                | PartDeltaEvent(delta=TextPartDelta(content_delta=delta))
+            ):
+                file_handle.write(delta)
+                file_handle.flush()
+
+            case (
+                PartStartEvent(part=ThinkingPart(content=delta))
+                | PartDeltaEvent(delta=ThinkingPartDelta(content_delta=delta))
+            ):
+                if include_thinking and delta:
+                    file_handle.write(f"\n[thinking] {delta}")
+                    file_handle.flush()
+
+            case FunctionToolCallEvent(part=ToolCallPart() as part):
+                if include_tools:
+                    kwargs_str = ", ".join(f"{k}={v!r}" for k, v in safe_args_as_dict(part).items())
+                    file_handle.write(f"\n[tool] {part.tool_name}({kwargs_str})\n")
+                    file_handle.flush()
+
+            case FunctionToolResultEvent(result=ToolReturnPart() as return_part):
+                if include_tools:
+                    file_handle.write(f"[result] {return_part.content}\n")
+                    file_handle.flush()
+
+            case RunErrorEvent(message=message):
+                file_handle.write(f"\n[error] {message}\n")
+                file_handle.flush()
+
+            case StreamCompleteEvent():
+                file_handle.write("\n")
+                file_handle.flush()
+
+    return file_stream_handler
+
+
 def resolve_event_handlers(
     event_handlers: Sequence[IndividualEventHandler | BuiltinEventHandlerType] | None,
 ) -> list[IndividualEventHandler]:

agentpool/agents/events/event_emitter.py

@@ -146,6 +146,7 @@ class StreamEventEmitter:
         path: str,
         success: bool,
         error: str | None = None,
+        line: int = 0,
     ) -> None:
         """Emit file operation event.
 
@@ -154,6 +155,7 @@ class StreamEventEmitter:
             path: The file/directory path that was operated on
             success: Whether the operation completed successfully
             error: Error message if operation failed
+            line: Line number for navigation (0 = beginning)
         """
         event = ToolCallProgressEvent.file_operation(
             tool_call_id=self._context.tool_call_id or "",
@@ -162,6 +164,7 @@ class StreamEventEmitter:
             path=path,
             success=success,
             error=error,
+            line=line,
         )
         await self._emit(event)
 

agentpool/agents/events/events.py

@@ -20,7 +20,15 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Literal
 
-from pydantic_ai import AgentStreamEvent
+from pydantic_ai import (
+    AgentStreamEvent,
+    PartDeltaEvent as PyAIPartDeltaEvent,
+    PartStartEvent as PyAIPartStartEvent,
+    TextPart,
+    TextPartDelta,
+    ThinkingPart,
+    ThinkingPartDelta,
+)
 
 from agentpool.messaging import ChatMessage  # noqa: TC001
 
@@ -35,6 +43,30 @@ if TYPE_CHECKING:
 # Lifecycle events (aligned with AG-UI protocol)
 
 
+class PartStartEvent(PyAIPartStartEvent):
+    """Part start event."""
+
+    @classmethod
+    def thinking(cls, index: int, content: str) -> PartStartEvent:
+        return cls(index=index, part=ThinkingPart(content=content))
+
+    @classmethod
+    def text(cls, index: int, content: str) -> PartStartEvent:
+        return cls(index=index, part=TextPart(content=content))
+
+
+class PartDeltaEvent(PyAIPartDeltaEvent):
+    """Part start event."""
+
+    @classmethod
+    def thinking(cls, index: int, content: str) -> PartDeltaEvent:
+        return cls(index=index, delta=ThinkingPartDelta(content_delta=content))
+
+    @classmethod
+    def text(cls, index: int, content: str) -> PartDeltaEvent:
+        return cls(index=index, delta=TextPartDelta(content_delta=content))
+
+
 @dataclass(kw_only=True)
 class RunStartedEvent:
     """Signals the start of an agent run."""
@@ -409,6 +441,7 @@ class ToolCallProgressEvent:
         success: bool,
         error: str | None = None,
         tool_name: str | None = None,
+        line: int = 0,
     ) -> ToolCallProgressEvent:
         """Create event for file operation.
 
@@ -419,13 +452,14 @@ class ToolCallProgressEvent:
             success: Whether operation succeeded
             error: Error message if failed
             tool_name: Optional tool name
+            line: Line number for navigation (0 = beginning)
         """
         status: Literal["completed", "failed"] = "completed" if success else "failed"
         title = f"{operation.capitalize()}: {path}"
         if error:
             title = f"{title} - {error}"
 
-        items: list[ToolCallContentItem] = [LocationContentItem(path=path)]
+        items: list[ToolCallContentItem] = [LocationContentItem(path=path, line=line)]
         if error:
             items.append(TextContentItem(text=f"Error: {error}"))
 
@@ -460,7 +494,6 @@ class ToolCallProgressEvent:
         """
         items: list[ToolCallContentItem] = [
             DiffContentItem(path=path, old_text=old_text, new_text=new_text),
-            LocationContentItem(path=path),
         ]
 
         return cls(
@@ -513,10 +546,36 @@ class ToolCallCompleteEvent:
     """The name of the agent that made the tool call."""
     message_id: str
     """The message ID associated with this tool call."""
+    metadata: dict[str, Any] | None = None
+    """Optional metadata for UI/client use (diffs, diagnostics, etc.)."""
     event_kind: Literal["tool_call_complete"] = "tool_call_complete"
     """Event type identifier."""
 
 
+@dataclass(kw_only=True)
+class ToolResultMetadataEvent:
+    """Sidechannel event carrying tool result metadata stripped by Claude SDK.
+
+    The Claude SDK strips the `_meta` field from MCP CallToolResult when converting
+    to ToolResultBlock, losing UI-only metadata (diffs, diagnostics, etc.).
+
+    This event provides a sidechannel to preserve that metadata:
+    - Tool returns ToolResult with metadata
+    - ToolManagerBridge emits this event with metadata before converting
+    - ClaudeCodeAgent correlates by tool_call_id and enriches ToolCallCompleteEvent
+    - Downstream consumers (OpenCode, ACP) receive complete events with metadata
+
+    This avoids polluting LLM context with UI-only data while preserving it for clients.
+    """
+
+    tool_call_id: str
+    """The ID of the tool call this metadata belongs to."""
+    metadata: dict[str, Any]
+    """Metadata for UI/client use (diffs, diagnostics, etc.)."""
+    event_kind: Literal["tool_result_metadata"] = "tool_result_metadata"
+    """Event type identifier."""
+
+
 @dataclass(kw_only=True)
 class CustomEvent[T]:
     """Generic custom event that can be emitted during tool execution."""
@@ -543,6 +602,26 @@ class PlanUpdateEvent:
     """Event type identifier."""
 
 
+@dataclass(kw_only=True)
+class SubAgentEvent:
+    """Event wrapping activity from a subagent or team member.
+
+    Used to propagate events from delegated agents/teams into the parent stream,
+    allowing the consumer (UI/server) to decide how to render nested activity.
+    """
+
+    source_name: str
+    """Name of the agent or team that produced this event."""
+    source_type: Literal["agent", "team_parallel", "team_sequential"]
+    """Type of source: agent, parallel team, or sequential team."""
+    event: RichAgentStreamEvent[Any]
+    """The actual event from the subagent/team."""
+    depth: int = 1
+    """Nesting depth (1 = direct child, 2 = grandchild, etc.)."""
+    event_kind: Literal["subagent"] = "subagent"
+    """Event type identifier."""
+
+
 @dataclass(kw_only=True)
 class CompactionEvent:
     """Event indicating context compaction is starting or completed.
@@ -572,6 +651,8 @@ type RichAgentStreamEvent[OutputDataT] = (
     | ToolCallCompleteEvent
     | PlanUpdateEvent
     | CompactionEvent
+    | SubAgentEvent
+    | ToolResultMetadataEvent
     | CustomEvent[Any]
 )
 

agentpool/agents/events/infer_info.py

@@ -0,0 +1,145 @@
+"""AgentPool event helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from agentpool.agents.events import DiffContentItem, LocationContentItem
+
+
+if TYPE_CHECKING:
+    from agentpool.agents.events import 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")
+        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")

agentpool/agents/events/processors.py

@@ -0,0 +1,254 @@
+"""Stream processors for event pipelines.
+
+This module provides composable processors that can transform, filter, or observe
+event streams. Processors wrap AsyncIterators and can be chained together.
+
+Example:
+    ```python
+    # Simple function processor
+    async def log_events(stream):
+        async for event in stream:
+            print(f"Event: {type(event).__name__}")
+            yield event
+
+    # Class-based processor with state
+    tracker = FileTrackingProcessor()
+
+    # Compose into pipeline
+    pipeline = StreamPipeline([tracker, log_events])
+
+    async for event in pipeline(raw_events):
+        yield event
+
+    # Access state directly
+    print(tracker.get_metadata())
+    ```
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Coroutine
+
+    from agentpool.agents.events.events import RichAgentStreamEvent
+    from agentpool.common_types import SimpleJsonType
+
+
+# Type alias for processor callables
+type StreamProcessorCallable = Callable[
+    [AsyncIterator[RichAgentStreamEvent[Any]]], AsyncIterator[RichAgentStreamEvent[Any]]
+]
+
+
+@runtime_checkable
+class StreamProcessor(Protocol):
+    """Protocol for stream processors.
+
+    Processors can be:
+    - Callables: `(AsyncIterator[RichAgentStreamEvent]) -> AsyncIterator[RichAgentStreamEvent]`
+    - Classes with `__call__`: Same signature, but can hold state
+    """
+
+    def __call__(
+        self, stream: AsyncIterator[RichAgentStreamEvent[Any]]
+    ) -> AsyncIterator[RichAgentStreamEvent[Any]]:
+        """Process an event stream.
+
+        Args:
+            stream: Input event stream
+
+        Returns:
+            Transformed/filtered event stream
+        """
+        ...
+
+
+@dataclass
+class StreamPipeline:
+    """Composable pipeline for processing event streams.
+
+    Chains multiple processors together, passing the output of each
+    to the input of the next.
+
+    Example:
+        ```python
+        tracker = FileTrackingProcessor()
+        pipeline = StreamPipeline([
+            tracker,
+            event_handler_processor(handler),
+        ])
+
+        async for event in pipeline(raw_events):
+            yield event
+
+        # Access state directly from processor instances
+        print(tracker.get_metadata())
+        ```
+    """
+
+    processors: list[StreamProcessorCallable | StreamProcessor] = field(default_factory=list)
+
+    def __call__(
+        self, stream: AsyncIterator[RichAgentStreamEvent[Any]]
+    ) -> AsyncIterator[RichAgentStreamEvent[Any]]:
+        """Run events through all processors in sequence.
+
+        Args:
+            stream: Input event stream
+
+        Returns:
+            Processed event stream
+        """
+        result = stream
+        for processor in self.processors:
+            result = processor(result)
+        return result
+
+    def add(self, processor: StreamProcessorCallable | StreamProcessor) -> None:
+        """Add a processor to the pipeline.
+
+        Args:
+            processor: Processor to add
+        """
+        self.processors.append(processor)
+
+
+def extract_file_path_from_tool_call(tool_name: str, raw_input: dict[str, Any]) -> str | None:
+    """Extract file path from a tool call if it's a file-writing tool.
+
+    Uses simple heuristics:
+    - Tool name contains 'write' or 'edit' (case-insensitive)
+    - Input contains 'path' or 'file_path' key
+
+    Args:
+        tool_name: Name of the tool being called
+        raw_input: Tool call arguments
+
+    Returns:
+        File path if this is a file-writing tool, None otherwise
+    """
+    name_lower = tool_name.lower()
+    if "write" not in name_lower and "edit" not in name_lower:
+        return None
+
+    # Try common path argument names
+    for key in ("file_path", "path", "filepath", "filename", "file"):
+        if key in raw_input and isinstance(val := raw_input[key], str):
+            return val
+
+    return None
+
+
+@dataclass
+class FileTrackingProcessor:
+    """Tracks files modified during a stream of events.
+
+    Observes ToolCallStartEvent and extracts file paths from write/edit operations.
+    Does not modify events - just passes them through while collecting metadata.
+
+    Example:
+        ```python
+        tracker = FileTrackingProcessor()
+
+        async for event in tracker(events):
+            yield event
+
+        print(f"Modified files: {tracker.touched_files}")
+        print(f"Metadata: {tracker.get_metadata()}")
+        ```
+    """
+
+    touched_files: set[str] = field(default_factory=set)
+    """Set of file paths that were modified by tool calls."""
+
+    extractor: Callable[[str, dict[str, Any]], str | None] = extract_file_path_from_tool_call
+    """Function to extract file path from tool call. Can be customized."""
+
+    def process_event(self, event: RichAgentStreamEvent[Any]) -> None:
+        """Process an event and track any file modifications.
+
+        Args:
+            event: The event to process (checks for ToolCallStartEvent)
+        """
+        from agentpool.agents.events import ToolCallStartEvent
+
+        if isinstance(event, ToolCallStartEvent) and (
+            file_path := self.extractor(event.tool_name or "", event.raw_input or {})
+        ):
+            self.touched_files.add(file_path)
+
+    def __call__(
+        self, stream: AsyncIterator[RichAgentStreamEvent[Any]]
+    ) -> AsyncIterator[RichAgentStreamEvent[Any]]:
+        """Wrap a stream to track file modifications.
+
+        Args:
+            stream: Input event stream
+
+        Returns:
+            Same events, unmodified
+        """
+        return self._process(stream)
+
+    async def _process(
+        self, stream: AsyncIterator[RichAgentStreamEvent[Any]]
+    ) -> AsyncIterator[RichAgentStreamEvent[Any]]:
+        """Internal async generator for processing."""
+        async for event in stream:
+            self.process_event(event)
+            yield event
+
+    def get_metadata(self) -> SimpleJsonType:
+        """Get metadata dict with touched files (if any).
+
+        Returns:
+            Dict with 'touched_files' key if files were modified, else empty dict
+        """
+        if self.touched_files:
+            return {"touched_files": sorted(self.touched_files)}
+        return {}
+
+    def reset(self) -> None:
+        """Clear tracked files for reuse."""
+        self.touched_files.clear()
+
+
+def event_handler_processor(
+    handler: Callable[[Any, RichAgentStreamEvent[Any]], Coroutine[Any, Any, None]],
+) -> StreamProcessorCallable:
+    """Create a processor that calls an event handler for each event.
+
+    The handler is called with (None, event) to match the existing
+    MultiEventHandler signature.
+
+    Args:
+        handler: Async callable with signature (ctx, event) -> None
+
+    Returns:
+        Processor function that calls the handler
+
+    Example:
+        ```python
+        pipeline = StreamPipeline([
+            event_handler_processor(self.event_handler),
+        ])
+        ```
+    """
+
+    async def process(
+        stream: AsyncIterator[RichAgentStreamEvent[Any]],
+    ) -> AsyncIterator[RichAgentStreamEvent[Any]]:
+        async for event in stream:
+            await handler(None, event)
+            yield event
+
+    return process
+
+
+# Convenience alias for backwards compatibility with existing FileTracker usage
+FileTracker = FileTrackingProcessor