agentpool 2.1.9__py3-none-any.whl

agentpool/messaging/processing.py

@@ -0,0 +1,76 @@
+"""Helper functions for common message processing logic."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from agentpool.messaging import ChatMessage
+from agentpool.prompts.convert import convert_prompts
+
+
+if TYPE_CHECKING:
+    from pydantic_ai import UserContent
+
+    from agentpool.common_types import PromptCompatible
+    from agentpool.messaging import MessageNode
+    from agentpool.messaging.connection_manager import ConnectionManager
+
+
+async def prepare_prompts(
+    *prompt: PromptCompatible | ChatMessage[Any],
+) -> tuple[ChatMessage[Any], list[UserContent], ChatMessage[Any] | None]:
+    """Prepare prompts for processing.
+
+    Extracted from MessageNode.pre_run logic.
+
+    Args:
+        *prompt: The prompt(s) to prepare.
+
+    Returns:
+        A tuple of:
+            - Either incoming message, or a constructed incoming message based
+              on the prompt(s).
+            - A list of prompts to be sent to the model.
+            - The original ChatMessage if forwarded, None otherwise
+    """
+    if len(prompt) == 1 and isinstance(prompt[0], ChatMessage):
+        original_msg = prompt[0]
+        # Update received message's chain to show it came through its source
+        user_msg = original_msg.forwarded(original_msg).to_request()
+        prompts = await convert_prompts([user_msg.content])
+        # clear cost info to avoid double-counting
+        return user_msg, prompts, original_msg
+    prompts = await convert_prompts(prompt)
+    user_msg = ChatMessage.user_prompt(message=prompts)
+    return user_msg, prompts, None
+
+
+async def finalize_message(
+    message: ChatMessage[Any],
+    previous_message: ChatMessage[Any] | None,
+    node: MessageNode[Any, Any],
+    connections: ConnectionManager,
+    original_message: ChatMessage[Any] | None,
+    wait_for_connections: bool | None = None,
+) -> ChatMessage[Any]:
+    """Handle message finalization and routing.
+
+    Args:
+        message: The response message to finalize
+        previous_message: The original user message (if any)
+        node: The message node that produced the message
+        connections: Connection manager for routing
+        original_message: The original ChatMessage if forwarded, None otherwise
+        wait_for_connections: Whether to wait for connected nodes
+
+    Returns:
+        The finalized message
+    """
+    # For chain processing, update the response's chain if input was forwarded
+    if original_message:
+        message = message.forwarded(original_message)
+    node.message_sent.emit(message)  # Emit signals
+    await node.log_message(message)  # Log message if enabled
+    # Route to connections
+    await connections.route_message(message, wait=wait_for_connections)
+    return message

agentpool/mime_utils.py

@@ -0,0 +1,95 @@
+"""Centralized MIME type utilities for agentpool.
+
+Uses pydantic-ai's enhanced MimeTypes instance for better cross-platform
+coverage of modern file types (.xlsx, .docx, .webp, .mkv, etc.).
+"""
+
+from __future__ import annotations
+
+from pydantic_ai.messages import _mime_types
+
+
+# MIME type prefixes that are definitely binary (no need to probe content)
+BINARY_MIME_PREFIXES = (
+    "image/",
+    "audio/",
+    "video/",
+    "application/octet-stream",
+    "application/zip",
+    "application/gzip",
+    "application/x-tar",
+    "application/pdf",
+    "application/x-executable",
+    "application/x-sharedlib",
+)
+
+# MIME type prefixes that should be treated as text
+TEXT_MIME_PREFIXES = (
+    "text/",
+    "application/json",
+    "application/xml",
+    "application/javascript",
+)
+
+# How many bytes to probe for binary detection
+BINARY_PROBE_SIZE = 8192
+
+
+def guess_type(path: str) -> str | None:
+    """Guess the MIME type of a file based on its path/extension.
+
+    Uses pydantic-ai's enhanced MimeTypes instance which has better
+    coverage for modern file types across platforms.
+
+    Args:
+        path: File path or URL to guess type for
+
+    Returns:
+        MIME type string or None if unknown
+    """
+    mime_type, _ = _mime_types.guess_type(path)
+    return mime_type
+
+
+def is_binary_mime(mime_type: str | None) -> bool:
+    """Check if MIME type is known to be binary (skip content probing).
+
+    Args:
+        mime_type: MIME type string or None
+
+    Returns:
+        True if the MIME type is definitely binary
+    """
+    if mime_type is None:
+        return False
+    return any(mime_type.startswith(prefix) for prefix in BINARY_MIME_PREFIXES)
+
+
+def is_text_mime(mime_type: str | None) -> bool:
+    """Check if a MIME type represents text content.
+
+    Args:
+        mime_type: MIME type string or None
+
+    Returns:
+        True if the MIME type is text-based (defaults to True for unknown)
+    """
+    if mime_type is None:
+        return True  # Default to text for unknown types
+    return any(mime_type.startswith(prefix) for prefix in TEXT_MIME_PREFIXES)
+
+
+def is_binary_content(data: bytes) -> bool:
+    """Detect binary content by probing for null bytes.
+
+    Uses the same heuristic as git: if the first ~8KB contains a null byte,
+    the content is considered binary.
+
+    Args:
+        data: Raw bytes to check
+
+    Returns:
+        True if content appears to be binary
+    """
+    probe = data[:BINARY_PROBE_SIZE]
+    return b"\x00" in probe

agentpool/models/__init__.py

@@ -0,0 +1,21 @@
+"""Core data models for AgentPool."""
+
+from __future__ import annotations
+
+from agentpool.models.acp_agents import ACPAgentConfig, ACPAgentConfigTypes, BaseACPAgentConfig
+from agentpool.models.agents import NativeAgentConfig
+from agentpool.models.agui_agents import AGUIAgentConfig
+from agentpool.models.claude_code_agents import ClaudeCodeAgentConfig
+from agentpool.models.manifest import AgentsManifest, AnyAgentConfig
+
+
+__all__ = [
+    "ACPAgentConfig",
+    "ACPAgentConfigTypes",
+    "AGUIAgentConfig",
+    "AgentsManifest",
+    "AnyAgentConfig",
+    "BaseACPAgentConfig",
+    "ClaudeCodeAgentConfig",
+    "NativeAgentConfig",
+]

agentpool/models/acp_agents/__init__.py

@@ -0,0 +1,22 @@
+"""ACP Agets."""
+
+from typing import Annotated
+from .non_mcp import RegularACPAgentConfigTypes
+from .mcp_capable import MCPCapableACPAgentConfigTypes, MCPCapableACPAgentConfig
+from .base import BaseACPAgentConfig, ACPAgentConfig
+from pydantic import Field
+
+# Union of all ACP agent config types (discriminated by 'provider')
+ACPAgentConfigTypes = Annotated[
+    ACPAgentConfig | RegularACPAgentConfigTypes | MCPCapableACPAgentConfigTypes,
+    Field(discriminator="provider"),
+]
+
+__all__ = [
+    "ACPAgentConfig",
+    "ACPAgentConfigTypes",
+    "BaseACPAgentConfig",
+    "MCPCapableACPAgentConfig",
+    "MCPCapableACPAgentConfigTypes",
+    "RegularACPAgentConfigTypes",
+]

agentpool/models/acp_agents/base.py

@@ -0,0 +1,308 @@
+"""Configuration models for ACP (Agent Client Protocol) agents."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence  # noqa: TC003
+import os
+import tempfile
+from typing import TYPE_CHECKING, Annotated, Any, Literal
+
+from exxec import ExecutionEnvironmentStr, get_environment  # noqa: TC002
+from exxec.configs import (
+    E2bExecutionEnvironmentConfig,
+    ExecutionEnvironmentConfig,  # noqa: TC002
+)
+from pydantic import ConfigDict, Field
+from tokonomics.model_discovery import ProviderType  # noqa: TC002
+
+from agentpool_config.nodes import NodeConfig
+from agentpool_config.system_prompts import PromptConfig  # noqa: TC001
+
+
+if TYPE_CHECKING:
+    from exxec import ExecutionEnvironment
+
+    from agentpool.prompts.manager import PromptManager
+
+
+class BaseACPAgentConfig(NodeConfig):
+    """Base configuration for all ACP agents.
+
+    Provides common fields and the interface for building commands.
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "x-icon": "octicon:terminal-16",
+            "x-doc-title": "ACP Agent Configuration",
+        }
+    )
+
+    type: Literal["acp"] = Field("acp", init=False)
+    """Top-level discriminator for agent type."""
+
+    cwd: str | None = Field(
+        default=None,
+        title="Working Directory",
+        examples=["/path/to/project", ".", "/home/user/myproject"],
+    )
+    """Working directory for the session."""
+
+    env: dict[str, str] = Field(
+        default_factory=dict,
+        title="Environment Variables",
+        examples=[{"PATH": "/usr/local/bin:/usr/bin", "DEBUG": "1"}],
+    )
+    """Environment variables to set."""
+
+    execution_environment: Annotated[
+        ExecutionEnvironmentStr | ExecutionEnvironmentConfig,
+        Field(
+            default="local",
+            title="Execution Environment",
+            examples=[
+                "docker",
+                E2bExecutionEnvironmentConfig(template="python-sandbox"),
+            ],
+        ),
+    ] = "local"
+    """Execution environment config for the agent's own toolsets."""
+
+    client_execution_environment: Annotated[
+        ExecutionEnvironmentStr | ExecutionEnvironmentConfig | None,
+        Field(
+            default=None,
+            title="Client Execution Environment",
+            examples=[
+                "local",
+                "docker",
+                E2bExecutionEnvironmentConfig(template="python-sandbox"),
+            ],
+        ),
+    ] = None
+    """Execution environment for handling subprocess requests (filesystem, terminals).
+
+    When the ACP subprocess requests file/terminal operations, this environment
+    determines where those operations execute. Falls back to execution_environment
+    if not set.
+
+    Use cases:
+    - None (default): Use same env as toolsets (execution_environment)
+    - "local": Subprocess operates on its own local filesystem
+    - Remote config: Subprocess operates in a specific remote environment
+    """
+
+    allow_file_operations: bool = Field(default=True, title="Allow File Operations")
+    """Whether to allow file read/write operations."""
+
+    allow_terminal: bool = Field(default=True, title="Allow Terminal")
+    """Whether to allow terminal operations."""
+
+    requires_tool_confirmation: Literal["never", "always"] = Field(
+        default="always", title="Tool confirmation mode"
+    )
+    """Whether to automatically grant all permission requests."""
+
+    system_prompt: str | Sequence[str | PromptConfig] | None = Field(
+        default=None,
+        title="System Prompt",
+        examples=[
+            "You are a helpful coding assistant.",
+            ["Always write tests.", "Focus on Python."],
+        ],
+        json_schema_extra={
+            "documentation_url": "https://phil65.github.io/agentpool/YAML%20Configuration/system_prompts_configuration/"
+        },
+    )
+    """System prompt for the agent. Can be a string or list of strings/prompt configs.
+
+    Support varies by agent:
+    - Claude: passed via --system-prompt
+    - Auggie: passed via --instruction-file
+    - Stakpak: passed via --system-prompt-file
+    - Others: may not support system prompts
+
+    Docs: https://phil65.github.io/agentpool/YAML%20Configuration/system_prompts_configuration/
+    """
+
+    def get_command(self) -> str:
+        """Get the command to spawn the ACP server."""
+        raise NotImplementedError
+
+    async def get_args(self, prompt_manager: PromptManager | None = None) -> list[str]:
+        """Get command arguments."""
+        raise NotImplementedError
+
+    async def render_system_prompt(
+        self,
+        prompt_manager: PromptManager | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> str | None:
+        """Render system prompt to a single string.
+
+        Resolves library references and renders templates.
+
+        Args:
+            prompt_manager: Optional prompt manager for resolving library references
+            context: Optional context for template rendering
+
+        Returns:
+            Rendered system prompt string, or None if no prompt configured
+        """
+        from toprompt import render_prompt
+
+        from agentpool_config.system_prompts import (
+            FilePromptConfig,
+            FunctionPromptConfig,
+            LibraryPromptConfig,
+            StaticPromptConfig,
+        )
+
+        if self.system_prompt is None:
+            return None
+
+        context = context or {"name": self.name}
+        prompt_list = (
+            [self.system_prompt] if isinstance(self.system_prompt, str) else self.system_prompt
+        )
+
+        rendered_parts: list[str] = []
+        for prompt in prompt_list:
+            match prompt:
+                case str() as content:
+                    rendered_parts.append(render_prompt(content, {"agent": context}))
+                case StaticPromptConfig(content=content):
+                    rendered_parts.append(render_prompt(content, {"agent": context}))
+                case FilePromptConfig(path=path, variables=variables):
+                    from pathlib import Path
+
+                    template_path = Path(path)
+                    if not template_path.is_absolute() and self.config_file_path:
+                        base_path = Path(self.config_file_path).parent
+                        template_path = base_path / path
+                    template_content = template_path.read_text("utf-8")
+                    template_ctx = {"agent": context, **variables}
+                    rendered_parts.append(render_prompt(template_content, template_ctx))
+                case LibraryPromptConfig(reference=reference):
+                    if prompt_manager:
+                        resolved = await prompt_manager.get_from(reference)
+                        rendered_parts.append(render_prompt(resolved, {"agent": context}))
+                    else:
+                        # Fallback: include reference marker
+                        rendered_parts.append(f"[LIBRARY:{reference}]")
+                case FunctionPromptConfig(function=function, arguments=arguments):
+                    content = function(**arguments)
+                    rendered_parts.append(render_prompt(content, {"agent": context}))
+
+        return "\n\n".join(rendered_parts) if rendered_parts else None
+
+    async def write_system_prompt_file(
+        self,
+        prompt_manager: PromptManager | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> str | None:
+        """Write system prompt to a temporary file.
+
+        Creates a temp file in the system temp directory that will be
+        cleaned up on system restart.
+
+        Args:
+            prompt_manager: Optional prompt manager for resolving library references
+            context: Optional context for template rendering
+
+        Returns:
+            Path to the temp file, or None if no prompt configured
+        """
+        content = await self.render_system_prompt(prompt_manager, context)
+        if not content:
+            return None
+
+        fd, path = tempfile.mkstemp(prefix="agentpool_prompt_", suffix=".txt")
+        with os.fdopen(fd, "w") as f:
+            f.write(content)
+        return path
+
+    def get_execution_environment(self) -> ExecutionEnvironment:
+        """Create execution environment from config."""
+        if isinstance(self.execution_environment, str):
+            return get_environment(self.execution_environment)
+        return self.execution_environment.get_provider()
+
+    def get_client_execution_environment(self) -> ExecutionEnvironment | None:
+        """Create client execution environment from config.
+
+        Returns None if not configured (caller should fall back to main env).
+        """
+        if self.client_execution_environment is None:
+            return None
+        if isinstance(self.client_execution_environment, str):
+            return get_environment(self.client_execution_environment)
+        return self.client_execution_environment.get_provider()
+
+    @property
+    def model_providers(self) -> list[ProviderType]:
+        """Return the model providers used by this ACP agent.
+
+        Override in subclasses to specify which providers the agent uses.
+        Used for intelligent model discovery and fallback configuration.
+        """
+        return []
+
+
+class ACPAgentConfig(BaseACPAgentConfig):
+    """Configuration for a custom ACP agent with explicit command.
+
+    Use this for ACP servers that don't have a preset, or when you need
+    full control over the command and arguments.
+
+    Example:
+        ```yaml
+        agents:
+          custom_agent:
+            type: acp
+            provider: custom
+            command: my-acp-server
+            args: ["--mode", "coding"]
+            cwd: /path/to/project
+        ```
+    """
+
+    model_config = ConfigDict(json_schema_extra={"title": "Custom ACP Agent Configuration"})
+
+    provider: Literal["custom"] = Field("custom", init=False)
+    """Discriminator for custom ACP agent."""
+
+    command: str = Field(
+        ...,
+        title="Command",
+        examples=["claude-code-acp", "aider", "my-custom-acp"],
+    )
+    """Command to spawn the ACP server."""
+
+    args: list[str] = Field(
+        default_factory=list,
+        title="Arguments",
+        examples=[["--mode", "coding"], ["--debug", "--verbose"]],
+    )
+    """Arguments to pass to the command."""
+
+    providers: list[ProviderType] = Field(
+        default_factory=list,
+        title="Providers",
+        examples=[["openai", "anthropic"], ["gemini"]],
+    )
+    """Model providers this agent can use."""
+
+    @property
+    def model_providers(self) -> list[ProviderType]:
+        """Return configured providers for custom ACP agents."""
+        return list(self.providers)
+
+    def get_command(self) -> str:
+        """Get the command to spawn the ACP server."""
+        return self.command
+
+    async def get_args(self, prompt_manager: PromptManager | None = None) -> list[str]:
+        """Get command arguments."""
+        _ = prompt_manager  # Custom agents use explicit args
+        return self.args