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

agentpool/agents/modes.py

@@ -0,0 +1,67 @@
+"""Mode definitions for agent behavior configuration.
+
+Modes represent switchable behaviors/configurations that agents can expose
+to clients. Each agent type can define its own mode categories.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass
+class ModeInfo:
+    """Information about a single mode option.
+
+    Represents one selectable option within a mode category.
+    """
+
+    id: str
+    """Unique identifier for this mode."""
+
+    name: str
+    """Human-readable display name."""
+
+    description: str = ""
+    """Optional description of what this mode does."""
+
+    category_id: str = ""
+    """ID of the category this mode belongs to."""
+
+
+@dataclass
+class ModeCategory:
+    """A category of modes that can be switched.
+
+    Represents a group of mutually exclusive modes. In the future,
+    ACP may support multiple categories rendered as separate dropdowns.
+
+    Examples:
+        - Permissions: default, acceptEdits
+        - Behavior: plan, code, architect
+    """
+
+    id: str
+    """Unique identifier for this category."""
+
+    name: str
+    """Human-readable display name for the category."""
+
+    available_modes: list[ModeInfo] = field(default_factory=list)
+    """List of available modes in this category."""
+
+    current_mode_id: str = ""
+    """ID of the currently active mode."""
+
+    category: Literal["mode", "model", "thought_level", "other"] | None = None
+    """Optional semantic category for UX purposes (keyboard shortcuts, icons, placement).
+
+    This helps clients distinguish common selector types:
+    - 'mode': Session mode selector
+    - 'model': Model selector
+    - 'thought_level': Thought/reasoning level selector
+    - 'other': Unknown/uncategorized
+
+    MUST NOT be required for correctness. Clients should handle gracefully.
+    """

agentpool/agents/slashed_agent.py

@@ -7,10 +7,6 @@ import re
 from typing import TYPE_CHECKING, Any, cast
 
 import anyio
-from slashed.events import (
-    CommandExecutedEvent,
-    CommandOutputEvent as SlashedCommandOutputEvent,
-)
 
 from agentpool.agents.events import CommandCompleteEvent, CommandOutputEvent
 from agentpool.log import get_logger
@@ -112,6 +108,11 @@ class SlashedAgent[TDeps, OutputDataT]:
         Yields:
             Command output and completion events
         """
+        from slashed.events import (
+            CommandExecutedEvent,
+            CommandOutputEvent as SlashedCommandOutputEvent,
+        )
+
         parsed = _parse_slash_command(command_text)
         if not parsed:
             logger.warning("Invalid slash command", command=command_text)

agentpool/agents/tool_call_accumulator.py

@@ -0,0 +1,213 @@
+"""Tool call accumulator for streaming tool arguments.
+
+This module provides utilities for accumulating streamed tool call arguments
+from LLM APIs that stream JSON arguments incrementally (like Anthropic's
+input_json_delta or OpenAI's function call streaming).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import anyenv
+
+
+def repair_partial_json(buffer: str) -> str:
+    """Attempt to repair truncated JSON for preview purposes.
+
+    Handles common truncation cases:
+    - Unclosed strings
+    - Missing closing braces/brackets
+    - Trailing commas
+
+    Args:
+        buffer: Potentially incomplete JSON string
+
+    Returns:
+        Repaired JSON string (may still be invalid in edge cases)
+    """
+    if not buffer:
+        return "{}"
+
+    result = buffer.rstrip()
+
+    # Check if we're in the middle of a string by counting unescaped quotes
+    in_string = False
+    i = 0
+    while i < len(result):
+        char = result[i]
+        if char == "\\" and i + 1 < len(result):
+            i += 2  # Skip escaped character
+            continue
+        if char == '"':
+            in_string = not in_string
+        i += 1
+
+    # Close unclosed string
+    if in_string:
+        result += '"'
+
+    # Remove trailing comma (invalid JSON)
+    result = result.rstrip()
+    if result.endswith(","):
+        result = result[:-1]
+
+    # Balance braces and brackets
+    open_braces = result.count("{") - result.count("}")
+    open_brackets = result.count("[") - result.count("]")
+
+    result += "]" * max(0, open_brackets)
+    result += "}" * max(0, open_braces)
+
+    return result
+
+
+class ToolCallAccumulator:
+    """Accumulates streamed tool call arguments.
+
+    LLM APIs stream tool call arguments as deltas. This class accumulates them
+    and provides the complete arguments when the tool call ends, as well as
+    best-effort partial argument parsing during streaming.
+
+    Example:
+        ```python
+        accumulator = ToolCallAccumulator()
+
+        # On content_block_start with tool_use
+        accumulator.start("toolu_123", "write_file")
+
+        # On input_json_delta events
+        accumulator.add_args("toolu_123", '{"path": "/tmp/')
+        accumulator.add_args("toolu_123", 'test.txt", "content"')
+        accumulator.add_args("toolu_123", ': "hello"}')
+
+        # Get partial args for UI preview (repairs incomplete JSON)
+        partial = accumulator.get_partial_args("toolu_123")
+
+        # On content_block_stop, get final parsed args
+        name, args = accumulator.complete("toolu_123")
+        ```
+    """
+
+    def __init__(self) -> None:
+        self._calls: dict[str, dict[str, Any]] = {}
+
+    def start(self, tool_call_id: str, tool_name: str) -> None:
+        """Start tracking a new tool call.
+
+        Args:
+            tool_call_id: Unique identifier for the tool call
+            tool_name: Name of the tool being called
+        """
+        self._calls[tool_call_id] = {"name": tool_name, "args_buffer": ""}
+
+    def add_args(self, tool_call_id: str, delta: str) -> None:
+        """Add argument delta to a tool call.
+
+        Args:
+            tool_call_id: Tool call identifier
+            delta: JSON string fragment to append
+        """
+        if tool_call_id in self._calls:
+            self._calls[tool_call_id]["args_buffer"] += delta
+
+    def complete(self, tool_call_id: str) -> tuple[str, dict[str, Any]] | None:
+        """Complete a tool call and return (tool_name, parsed_args).
+
+        Removes the tool call from tracking and returns the final parsed arguments.
+
+        Args:
+            tool_call_id: Tool call identifier
+
+        Returns:
+            Tuple of (tool_name, args_dict) or None if call not found
+        """
+        if tool_call_id not in self._calls:
+            return None
+
+        call_data = self._calls.pop(tool_call_id)
+        args_str = call_data["args_buffer"]
+        try:
+            args = anyenv.load_json(args_str) if args_str else {}
+        except anyenv.JsonLoadError:
+            args = {"_raw": args_str}
+        return call_data["name"], args
+
+    def get_pending(self, tool_call_id: str) -> tuple[str, str] | None:
+        """Get pending call data (tool_name, args_buffer) without completing.
+
+        Args:
+            tool_call_id: Tool call identifier
+
+        Returns:
+            Tuple of (tool_name, args_buffer) or None if not found
+        """
+        if tool_call_id not in self._calls:
+            return None
+        data = self._calls[tool_call_id]
+        return data["name"], data["args_buffer"]
+
+    def get_partial_args(self, tool_call_id: str) -> dict[str, Any]:
+        """Get best-effort parsed args from incomplete JSON stream.
+
+        Uses heuristics to complete truncated JSON for preview purposes.
+        Handles unclosed strings, missing braces/brackets, and trailing commas.
+
+        Args:
+            tool_call_id: Tool call ID
+
+        Returns:
+            Partially parsed arguments or empty dict
+        """
+        if tool_call_id not in self._calls:
+            return {}
+
+        buffer = self._calls[tool_call_id]["args_buffer"]
+        if not buffer:
+            return {}
+
+        # Try direct parse first
+        try:
+            result: dict[str, Any] = anyenv.load_json(buffer)
+        except anyenv.JsonLoadError:
+            pass
+        else:
+            return result
+
+        # Try to repair truncated JSON
+        try:
+            repaired = repair_partial_json(buffer)
+            result = anyenv.load_json(repaired)
+        except anyenv.JsonLoadError:
+            return {}
+        else:
+            return result
+
+    def is_pending(self, tool_call_id: str) -> bool:
+        """Check if a tool call is being tracked.
+
+        Args:
+            tool_call_id: Tool call identifier
+
+        Returns:
+            True if the tool call is being accumulated
+        """
+        return tool_call_id in self._calls
+
+    def get_tool_name(self, tool_call_id: str) -> str | None:
+        """Get the tool name for a pending call.
+
+        Args:
+            tool_call_id: Tool call identifier
+
+        Returns:
+            Tool name or None if not found
+        """
+        if tool_call_id not in self._calls:
+            return None
+        name: str = self._calls[tool_call_id]["name"]
+        return name
+
+    def clear(self) -> None:
+        """Clear all pending tool calls."""
+        self._calls.clear()

agentpool/agents/tool_wrapping.py

@@ -9,9 +9,11 @@ import time
 from typing import TYPE_CHECKING, Any
 
 from pydantic_ai import RunContext
+from pydantic_ai.messages import ToolReturn
 
 from agentpool.agents.context import AgentContext
 from agentpool.tasks import ChainAbortedError, RunAbortedError, ToolSkippedError
+from agentpool.tools.base import ToolResult
 from agentpool.utils.inspection import execute, get_argument_key
 from agentpool.utils.signatures import create_modified_signature, update_signature
 
@@ -27,7 +29,7 @@ def wrap_tool[TReturn](  # noqa: PLR0915
     tool: Tool[TReturn],
     agent_ctx: AgentContext,
     hooks: AgentHooks | None = None,
-) -> Callable[..., Awaitable[TReturn | None]]:
+) -> Callable[..., Awaitable[TReturn | ToolReturn | None]]:
     """Wrap tool with confirmation handling and hooks.
 
     Strategy:
@@ -41,7 +43,7 @@ def wrap_tool[TReturn](  # noqa: PLR0915
         agent_ctx: Agent context for confirmation handling and dependency injection.
         hooks: Optional AgentHooks for pre/post tool execution hooks.
     """
-    fn = tool.callable
+    fn = tool.get_callable()
     run_ctx_key = get_argument_key(fn, RunContext)
     agent_ctx_key = get_argument_key(fn, AgentContext)
 
@@ -58,7 +60,7 @@ def wrap_tool[TReturn](  # noqa: PLR0915
         tool_input: dict[str, Any],
         *args: Any,
         **kwargs: Any,
-    ) -> TReturn | None:
+    ) -> TReturn | None | ToolReturn:
         """Execute tool with pre/post hooks."""
         # Pre-tool hooks
         if hooks:
@@ -79,9 +81,17 @@ def wrap_tool[TReturn](  # noqa: PLR0915
 
         # Execute the tool
         start_time = time.perf_counter()
-        result = await execute_fn(*args, **kwargs)
+        result: TReturn | ToolResult | ToolReturn = await execute_fn(*args, **kwargs)
         duration_ms = (time.perf_counter() - start_time) * 1000
 
+        # Convert AgentPool ToolResult to pydantic-ai ToolReturn
+        if isinstance(result, ToolResult):
+            result = ToolReturn(
+                return_value=result.structured_content or result.content,
+                content=result.content,
+                metadata=result.metadata,
+            )
+
         # Post-tool hooks
         if hooks:
             await hooks.run_post_tool_hooks(
@@ -97,7 +107,9 @@ def wrap_tool[TReturn](  # noqa: PLR0915
 
     if run_ctx_key or agent_ctx_key:
         # Tool has RunContext and/or AgentContext
-        async def wrapped(ctx: RunContext, *args: Any, **kwargs: Any) -> TReturn | None:  # pyright: ignore
+        async def wrapped(
+            ctx: RunContext, *args: Any, **kwargs: Any
+        ) -> TReturn | None | ToolReturn:  # pyright: ignore
             result = await agent_ctx.handle_confirmation(tool, kwargs)
             if result == "allow":
                 # Populate AgentContext with RunContext data if needed
@@ -135,7 +147,7 @@ def wrap_tool[TReturn](  # noqa: PLR0915
 
     else:
         # Tool has no context - normal function call
-        async def wrapped(*args: Any, **kwargs: Any) -> TReturn | None:  # type: ignore[misc]
+        async def wrapped(*args: Any, **kwargs: Any) -> TReturn | None | ToolReturn:  # type: ignore[misc]
             result = await agent_ctx.handle_confirmation(tool, kwargs)
             if result == "allow":
                 tool_input = kwargs.copy()

agentpool/common_types.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -27,15 +28,13 @@ if TYPE_CHECKING:
     from uuid import UUID
 
     from agentpool.agents.events import RichAgentStreamEvent
-    from agentpool.messaging import ChatMessage
-    from agentpool.messaging.messagenode import MessageNode
     from agentpool.tools.base import Tool
 
-    # Type alias for team streaming return type (node + event tuples)
-    type TeamStreamEvent = tuple[MessageNode[Any, Any], RichAgentStreamEvent[Any]]
     type AnyTransformFn[T] = Callable[[T], T | Awaitable[T]]
     type OptionalAwaitable[T] = T | Awaitable[T]
-    type ToolType = str | AnyCallable | Tool
+    # Import path string for dynamic tool loading (e.g., "mymodule:my_tool")
+    type ImportPathString = str
+    type ToolType = ImportPathString | AnyCallable | Tool
     # Define what we consider JSON-serializable
     type JsonPrimitive = None | bool | int | float | str
     type SessionIdType = str | UUID | None
@@ -50,12 +49,32 @@ type JsonObject = dict[str, JsonValue]
 type JsonArray = list[JsonValue]
 
 
+MCPConnectionStatus = Literal["connected", "disconnected", "error"]
+
+
+@dataclass(frozen=True, slots=True)
+class MCPServerStatus:
+    """Status information for an MCP server.
+
+    Attributes:
+        name: Server name/identifier
+        status: Connection status
+        server_type: Transport type (stdio, sse, http)
+        error: Error message if status is "error"
+    """
+
+    name: str
+    status: MCPConnectionStatus
+    server_type: str = "unknown"
+    error: str | None = None
+
+
 NodeName = str
 TeamName = str
 AgentName = str
 MessageRole = Literal["user", "assistant"]
 PartType = Literal["text", "image", "audio", "video"]
-ModelType = Model | ModelId | str | None
+ModelType = Model | ModelId | str
 EnvironmentType = Literal["file", "inline"]
 ToolSource = Literal["agent", "builtin", "dynamic", "task", "mcp", "toolset"]
 AnyCallable = Callable[..., Any]
@@ -78,30 +97,46 @@ QueueStrategy = Literal["concat", "latest", "buffer"]
 """
 
 
-class SupportsStructuredOutput(Protocol):
-    """Protocol for nodes that support structured output via run().
-
-    This protocol is used for components that need to call run() with
-    an output_type parameter (e.g., picker agents, Interactions).
-    """
-
-    async def run(self, *prompts: Any, output_type: Any = ...) -> ChatMessage[Any]: ...
-
-
 @runtime_checkable
 class SupportsRunStream[TResult](Protocol):
     """Protocol for nodes that support streaming via run_stream().
 
     Used by Team and TeamRun to check if a node can be streamed.
-
-    Return type is a union because:
-    - Agent returns `AsyncIterator[RichAgentStreamEvent[TResult]]`
-    - Team/TeamRun return `AsyncIterator[tuple[MessageNode, RichAgentStreamEvent]]`
+    All streaming nodes return RichAgentStreamEvent, with subagent/team
+    activity wrapped in SubAgentEvent.
     """
 
     def run_stream(
         self, *prompts: Any, **kwargs: Any
-    ) -> AsyncIterator[RichAgentStreamEvent[TResult] | TeamStreamEvent]: ...
+    ) -> AsyncIterator[RichAgentStreamEvent[TResult]]: ...
+
+
+@runtime_checkable
+class SupportsStructuredOutput(Protocol):
+    """Protocol for agents that support structured output via to_structured().
+
+    Used by Interactions class for pick/extract operations that require
+    structured output from agents.
+    """
+
+    def to_structured[T](self, output_type: type[T]) -> SupportsStructuredOutput:
+        """Create a copy of this agent configured for structured output.
+
+        Args:
+            output_type: The type to structure output as
+
+        Returns:
+            New agent instance configured for structured output
+        """
+        ...
+
+    async def run(self, *prompts: Any, **kwargs: Any) -> Any:
+        """Run the agent with the given prompts.
+
+        Returns:
+            ChatMessage with content typed according to output_type from to_structured
+        """
+        ...
 
 
 class BaseCode(BaseModel):

agentpool/config_resources/__init__.py

@@ -7,10 +7,47 @@ from typing import Final
 
 _RESOURCES = importlib.resources.files("agentpool.config_resources")
 
+# Template configuration
 AGENTS_TEMPLATE: Final[str] = str(_RESOURCES / "agents_template.yml")
 """Path to the agents template configuration."""
 
+# Pool configurations
 ACP_ASSISTANT: Final[str] = str(_RESOURCES / "acp_assistant.yml")
 """Path to default ACP assistant configuration."""
 
-__all__ = ["ACP_ASSISTANT", "AGENTS_TEMPLATE"]
+AGENTS: Final[str] = str(_RESOURCES / "agents.yml")
+"""Path to the main agents configuration."""
+
+AGUI_TEST: Final[str] = str(_RESOURCES / "agui_test.yml")
+"""Path to AGUI test configuration."""
+
+CLAUDE_CODE_ASSISTANT: Final[str] = str(_RESOURCES / "claude_code_agent.yml")
+"""Path to default Claude code assistant configuration."""
+
+EXTERNAL_ACP_AGENTS: Final[str] = str(_RESOURCES / "external_acp_agents.yml")
+"""Path to external ACP agents configuration."""
+
+TTS_TEST_AGENTS: Final[str] = str(_RESOURCES / "tts_test_agents.yml")
+"""Path to TTS test agents configuration."""
+
+# All pool configuration paths for validation
+ALL_POOL_CONFIGS: Final[tuple[str, ...]] = (
+    ACP_ASSISTANT,
+    AGENTS,
+    AGUI_TEST,
+    CLAUDE_CODE_ASSISTANT,
+    EXTERNAL_ACP_AGENTS,
+    TTS_TEST_AGENTS,
+)
+"""All pool configuration file paths."""
+
+__all__ = [
+    "ACP_ASSISTANT",
+    "AGENTS",
+    "AGENTS_TEMPLATE",
+    "AGUI_TEST",
+    "ALL_POOL_CONFIGS",
+    "CLAUDE_CODE_ASSISTANT",
+    "EXTERNAL_ACP_AGENTS",
+    "TTS_TEST_AGENTS",
+]

agentpool/config_resources/acp_assistant.yml

@@ -17,8 +17,8 @@ agents:
         You are a helpful AI assistant with access to the file system and can execute code.
         You can help with coding, writing, analysis, file operations, and more.
         Be concise but thorough in your responses.
-    toolsets:
-      - type: execution
+    tools:
+      - type: process_management
       - type: file_access
       - type: code
       - type: search

agentpool/config_resources/agents.yml

@@ -47,6 +47,7 @@ responses:
 
 agents:
   url_opener:
+    type: native
     tools:
       - type: import
         import_path: "webbrowser.open"
@@ -63,6 +64,7 @@ agents:
         Always confirm what you're about to open.
 
   system_inspector:
+    type: native
     tools:
       - type: import
         import_path: "platform.platform"
@@ -84,6 +86,7 @@ agents:
         Format it using the template from the system_template resource.
 
   file_explorer:
+    type: native
     tools:
       - type: import
         import_path: "os.listdir"

agentpool/config_resources/agents_template.yml

@@ -1,6 +1,7 @@
 # yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json
 agents:
   simple_agent:
+    type: native
     description: "Basic agent with one tool to open webbrowsers."
     model: openai:gpt-5-mini
     tools:

agentpool/config_resources/claude_code_agent.yml

@@ -1,16 +1,20 @@
 # yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json
-# Default ACP assistant configuration
-# Used when starting ACP server without explicit config file
 
 agents:
   claude:
     type: claude_code
     display_name: "AI Assistant"
-    builtin_tools: []
+    builtin_tools: [] # we use our own tools.
+    use_subscription: true
     description: "Claude code agent with enhanced tools"
-    toolsets:
-      - type: execution
+    tools:
+      - type: bash
+      - type: agent_cli
+      - type: process_management
       - type: file_access
-      - type: code
+        edit_tool: batch
+      # - type: code
       - type: search
       - type: plan
+      - type: question
+      # - type: debug

agentpool/config_resources/external_acp_agents.yml

@@ -9,9 +9,10 @@ agents:
     env: # override to make sure subscription is used
       ANTHROPIC_API_KEY: ""
 
-    toolsets:
+    tools:
       - type: code
       - type: subagent
+      - type: plan
   codex:
     type: acp
     provider: codex