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

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,45 @@ 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.
+
+    This is a semantic event that consumers (ACP, OpenCode) handle differently:
+    - ACP: Converts to a text message for display
+    - OpenCode: Emits session.compacted SSE event
+    """
+
+    session_id: str
+    """The session ID being compacted."""
+    trigger: Literal["auto", "manual"] = "auto"
+    """What triggered the compaction (auto = context overflow, manual = slash command)."""
+    phase: Literal["starting", "completed"] = "starting"
+    """Current phase of compaction."""
+    event_kind: Literal["compaction"] = "compaction"
+    """Event type identifier."""
+
+
 type RichAgentStreamEvent[OutputDataT] = (
     AgentStreamEvent
     | StreamCompleteEvent[OutputDataT]
@@ -552,6 +650,9 @@ type RichAgentStreamEvent[OutputDataT] = (
     | ToolCallProgressEvent
     | 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

agentpool/agents/interactions.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Mapping
+from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING, Any, Literal, cast, overload
 
 from schemez import Schema
@@ -12,7 +13,7 @@ from agentpool.messaging import ChatMessage
 
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import AsyncIterator, Sequence
 
     from toprompt import AnyPromptType
 
@@ -90,6 +91,33 @@ class Interactions:
     def __init__(self, agent: SupportsStructuredOutput) -> None:
         self.agent = agent
 
+    @asynccontextmanager
+    async def _with_structured_output[T](
+        self, output_type: type[T]
+    ) -> AsyncIterator[SupportsStructuredOutput]:
+        """Context manager to temporarily set structured output type and restore afterwards.
+
+        Args:
+            output_type: The type to structure output as
+
+        Yields:
+            The agent configured for structured output
+
+        Example:
+            async with interactions._with_structured_output(MyType) as agent:
+                result = await agent.run(prompt)
+        """
+        # Save original output type
+        old_output_type = getattr(self.agent, "_output_type", None)
+        try:
+            # Configure structured output
+            structured_agent = self.agent.to_structured(output_type)
+            yield structured_agent
+        finally:
+            # Restore original output type
+            if hasattr(self.agent, "_output_type"):
+                self.agent._output_type = old_output_type
+
     # async def conversation(
     #     self,
     #     other: MessageNode[Any, Any],
@@ -218,8 +246,9 @@ Available options:
 
 Select ONE option by its exact label."""
 
-        # Get LLM's string-based decision
-        result = await self.agent.run(prompt or default_prompt, output_type=LLMPick)
+        # Get LLM's string-based decision using structured output
+        async with self._with_structured_output(LLMPick) as structured_agent:
+            result = await structured_agent.run(prompt or default_prompt)
 
         # Convert to type-safe decision
         if result.content.selection not in label_map:
@@ -328,7 +357,9 @@ Available options:
 {picks_info} options by their exact labels.
 List your selections, one per line, followed by your reasoning."""
 
-        result = await self.agent.run(prompt or default_prompt, output_type=LLMMultiPick)
+        # Get LLM's multi-selection using structured output
+        async with self._with_structured_output(LLMMultiPick) as structured_agent:
+            result = await structured_agent.run(prompt or default_prompt)
 
         # Validate selections
         invalid = [s for s in result.content.selections if s not in label_map]
@@ -368,7 +399,9 @@ List your selections, one per line, followed by your reasoning."""
             instance: item_model  # type: ignore
             # explanation: str | None = None
 
-        result = await self.agent.run(final_prompt, output_type=Extraction)
+        # Use structured output via context manager
+        async with self._with_structured_output(Extraction) as structured_agent:
+            result = await structured_agent.run(final_prompt)
         return as_type(**result.content.instance.model_dump())
 
     async def extract_multiple[T](
@@ -404,7 +437,9 @@ List your selections, one per line, followed by your reasoning."""
             instances: list[item_model]  # type: ignore
             # explanation: str | None = None
 
-        result = await self.agent.run(final_prompt, output_type=Extraction)
+        # Use structured output via context manager
+        async with self._with_structured_output(Extraction) as structured_agent:
+            result = await structured_agent.run(final_prompt)
         num_instances = len(result.content.instances)  # Validate counts
         if len(result.content.instances) < min_items:
             msg = f"Found only {num_instances} instances, need {min_items}"