kolega-code 0.1.0__py3-none-any.whl

kolega_code/agent/browseragent.py

@@ -0,0 +1,123 @@
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .baseagent import BaseAgent
+from kolega_code.config import AgentConfig
+from kolega_code.events import AgentConnectionManager
+from kolega_code.llm.models import Message, TextBlock
+from .prompt_provider import AgentType, PromptExtension
+from .tools import ToolCollection
+
+
+class BrowserAgent(BaseAgent):
+    """
+    An AI coding agent that operates within a workspace to assist with programming tasks.
+
+    The agent has access to the project filesystem and can perform coding operations
+    like reading, analyzing, and modifying code files.
+    """
+
+    agent_name = "browser-agent"
+
+    def __init__(
+        self,
+        project_path: str | Path,
+        workspace_id: str,
+        thread_id: str,
+        connection_manager: AgentConnectionManager,
+        config: AgentConfig,
+        sub_agent: bool = True,
+        filesystem=None,
+        terminal_manager=None,
+        browser_manager=None,
+        langfuse_client=None,
+        user_id: Optional[str] = None,
+        user_email: Optional[str] = None,
+        project_template_slug: Optional[str] = None,
+        protected_files: Optional[List[str]] = None,
+        agent_mode: Optional["AgentMode"] = None,
+        workspace_env_var_descriptions: Optional[Dict[str, str]] = None,
+        workspace_memories: Optional[List[str]] = None,
+        prompt_extensions: Optional[List[PromptExtension]] = None,
+        tool_extensions: Optional[List[Any]] = None,
+        usage_recorder: Optional[Any] = None,
+        sub_agent_recorder: Optional[Any] = None,
+    ) -> None:
+        """
+        Initialize a new BrowserAgent instance.
+
+        Args:
+            project_path: File system path to the project root directory
+            workspace_id: Identifier for the workspace
+            thread_id: Identifier for the thread
+            connection_manager: Manager for handling agent connections
+            config: Agent configuration
+            sub_agent: Whether this agent is a sub-agent of another agent
+            filesystem: Optional filesystem implementation
+            terminal_manager: Optional terminal manager implementation
+            browser_manager: Optional browser manager implementation
+            langfuse_client: Optional Langfuse client for LLM observability
+            user_id: Optional ID of user who created this job
+            user_email: Optional email of user who created this job
+            project_template_slug: Optional slug of the project template being used
+            protected_files: Optional list of file basenames protected from edits in vibe mode
+            agent_mode: Optional agent mode (not used for BrowserAgent)
+            workspace_env_var_descriptions: Optional mapping of workspace environment variable descriptions
+            workspace_memories: Optional list of workspace memories to inject into prompts
+            prompt_extensions: Host-provided prompt sections for app-specific context
+            tool_extensions: Host-provided tool providers for app-specific tools
+            usage_recorder: Optional callback for recording normalized LLM usage
+            sub_agent_recorder: Optional callback for persisting sub-agent conversation state
+        """
+        super().__init__(
+            project_path,
+            workspace_id,
+            thread_id,
+            connection_manager,
+            config,
+            sub_agent=sub_agent,
+            filesystem=filesystem,
+            terminal_manager=terminal_manager,
+            browser_manager=browser_manager,
+            langfuse_client=langfuse_client,
+            user_id=user_id,
+            user_email=user_email,
+            project_template_slug=project_template_slug,
+            protected_files=protected_files,
+            agent_mode=agent_mode,
+            workspace_env_var_descriptions=workspace_env_var_descriptions,
+            workspace_memories=workspace_memories,
+            prompt_extensions=prompt_extensions,
+            tool_extensions=tool_extensions,
+            usage_recorder=usage_recorder,
+            sub_agent_recorder=sub_agent_recorder,
+        )
+
+        self.tool_collection = ToolCollection(
+            self.project_path,
+            self.workspace_id,
+            self.thread_id,
+            self.connection_manager,
+            self.config,
+            caller=self,
+            browser_only=True,
+            filesystem=self.filesystem,
+            terminal_manager=self.terminal_manager,
+            browser_manager=self.browser_manager,
+            langfuse_client=self.langfuse_client,
+            tool_extensions=self.tool_extensions,
+        )
+
+        self._initialize_system_prompt()
+
+    def _initialize_system_prompt(self):
+        """Initialize system prompt using PromptProvider."""
+        # Generate prompt using the shared prompt provider
+        prompt_text = self.prompt_provider.get_system_prompt(
+            agent_type=AgentType.BROWSER,
+            mode=self.agent_mode,
+            template_slug=self.project_template_slug,
+            prompt_extensions=self.prompt_extensions,
+            context=self.build_prompt_context(),
+        )
+        self.system_prompt = Message(role="system", content=[TextBlock(text=prompt_text)])

kolega_code/agent/coder.py

@@ -0,0 +1,157 @@
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .baseagent import BaseAgent
+from .common import LogMixin
+from kolega_code.config import AgentConfig
+from kolega_code.events import AgentConnectionManager
+from kolega_code.llm.models import Message, TextBlock
+from .prompt_provider import AgentType, AgentMode, PromptExtension, PromptProvider
+from .tools import ToolCollection, ToolCollectionConfig
+from .utils.commands import CommandProcessor
+
+
+@CommandProcessor.process_commands
+class CoderAgent(BaseAgent, LogMixin):
+    """
+    An AI coding agent that operates within a workspace to assist with programming tasks.
+
+    The agent has access to the project filesystem and can perform coding operations
+    like reading, analyzing, and modifying code files.
+    """
+
+    agent_name = "coder"
+
+    def __init__(
+        self,
+        project_path: str | Path,
+        workspace_id: str,
+        thread_id: str,
+        connection_manager: AgentConnectionManager,
+        config: AgentConfig,
+        sub_agent: bool = False,
+        filesystem=None,
+        terminal_manager=None,
+        browser_manager=None,
+        langfuse_client=None,
+        user_id: Optional[str] = None,
+        user_email: Optional[str] = None,
+        project_template_slug: Optional[str] = None,
+        protected_files: Optional[List[str]] = None,
+        agent_mode: Optional[AgentMode] = None,
+        workspace_env_var_descriptions: Optional[Dict[str, str]] = None,
+        workspace_memories: Optional[List[str]] = None,
+        prompt_provider: Optional[PromptProvider] = None,
+        prompt_extensions: Optional[List[PromptExtension]] = None,
+        tool_extensions: Optional[List[Any]] = None,
+        usage_recorder: Optional[Any] = None,
+        sub_agent_recorder: Optional[Any] = None,
+    ) -> None:
+        """
+        Initialize a new CoderAgent instance.
+
+        Args:
+            project_path: File system path to the project root directory
+            workspace_id: Identifier for the workspace
+            thread_id: Identifier for the thread
+            connection_manager: Manager for handling agent connections
+            config: Agent configuration settings
+            sub_agent: Whether this is a sub-agent (default: False)
+            filesystem: File system implementation (optional)
+            terminal_manager: Terminal manager implementation (optional)
+            browser_manager: Browser manager implementation (optional)
+            langfuse_client: Optional Langfuse client for LLM observability
+            user_id: Optional ID of user who created this job
+            user_email: Optional email of user who created this job
+            project_template_slug: Optional slug of the project template being used
+            protected_files: Optional list of file basenames protected from edits in vibe mode
+            agent_mode: Optional agent mode (CLI, VIBE, CODE, or FIX)
+            workspace_env_var_descriptions: Optional mapping of workspace environment variable descriptions
+            workspace_memories: Optional list of workspace memories to inject into prompts
+            prompt_provider: Optional host-configured prompt provider
+            prompt_extensions: Host-provided prompt sections for app-specific context
+            tool_extensions: Host-provided tool providers for app-specific tools
+            usage_recorder: Optional callback for recording normalized LLM usage
+            sub_agent_recorder: Optional callback for persisting sub-agent conversation state
+        """
+        # Call parent constructor
+        super().__init__(
+            project_path,
+            workspace_id,
+            thread_id,
+            connection_manager,
+            config,
+            sub_agent,
+            filesystem=filesystem,
+            terminal_manager=terminal_manager,
+            browser_manager=browser_manager,
+            langfuse_client=langfuse_client,
+            user_id=user_id,
+            user_email=user_email,
+            project_template_slug=project_template_slug,
+            protected_files=protected_files,
+            agent_mode=agent_mode,
+            workspace_env_var_descriptions=workspace_env_var_descriptions,
+            workspace_memories=workspace_memories,
+            prompt_provider=prompt_provider,
+            prompt_extensions=prompt_extensions,
+            tool_extensions=tool_extensions,
+            usage_recorder=usage_recorder,
+            sub_agent_recorder=sub_agent_recorder,
+        )
+
+        # Configure tool collection with custom coder agent tools
+        tool_exclusions = [
+            "read_memory",
+            "write_memory",
+            "execute_terminal_command",
+            "replace_lines",
+            "apply_patch",
+            "edit_file",
+            "get_tool_list",
+            "log_error",
+            "log_info",
+            "run_command",  # Disabled: unreliable completion detection, use run_command_tracked instead
+            # Exclude task-specific dispatch tools since coder shouldn't call itself or other agents
+            "dispatch_coding_agent",
+        ]
+        mode_value = self.agent_mode.value if isinstance(self.agent_mode, AgentMode) else self.agent_mode
+        if mode_value == AgentMode.CLI.value:
+            tool_exclusions.extend(["build_backend", "build_frontend"])
+        if sub_agent:
+            # A dispatched coder must not fan out into further sub-agents
+            tool_exclusions.append("dispatch_general_agent")
+
+        tool_config = ToolCollectionConfig(
+            custom_tool_groups=["coder_agent_tools"],
+            tool_exclusions=tool_exclusions,
+        )
+
+        self.tool_collection = ToolCollection(
+            self.project_path,
+            self.workspace_id,
+            self.thread_id,
+            self.connection_manager,
+            self.config,
+            caller=self,
+            tool_config=tool_config,
+            filesystem=self.filesystem,
+            terminal_manager=self.terminal_manager,
+            browser_manager=self.browser_manager,
+            langfuse_client=self.langfuse_client,
+            tool_extensions=self.tool_extensions,
+        )
+
+        self._initialize_system_prompt()
+
+    def _initialize_system_prompt(self):
+        """Initialize system prompt using PromptProvider."""
+        # Generate prompt using the shared prompt provider
+        prompt_text = self.prompt_provider.get_system_prompt(
+            agent_type=AgentType.CODER,
+            mode=self.agent_mode,
+            template_slug=self.project_template_slug,
+            prompt_extensions=self.prompt_extensions,
+            context=self.build_prompt_context(),
+        )
+        self.system_prompt = Message(role="system", content=[TextBlock(text=prompt_text)])

kolega_code/agent/common.py

@@ -0,0 +1,41 @@
+from kolega_code.events import AgentEvent
+
+
+class LogMixin:
+    """
+    A mixin class providing logging functionality to agents.
+
+    This mixin expects the implementing class to have a connection_manager attribute,
+    a workspace_id attribute, and a thread_id attribute.
+    """
+
+    async def log_info(self, message: str, sender: str = "agent") -> None:
+        """
+        Log an informational message to the logs panel.
+
+        Args:
+            message: The information message to log
+        """
+        log_event = AgentEvent(event_type="log_message", sender=sender, content={"text": message, "level": "info"})
+
+        await self.connection_manager.broadcast_event(log_event, self.workspace_id, self.thread_id)
+
+    async def log_error(self, message: str, sender: str = "agent") -> None:
+        """
+        Log an error message to the logs panel.
+
+        Args:
+            message: The error message to log
+        """
+        log_event = AgentEvent(event_type="log_message", sender=sender, content={"text": message, "level": "error"})
+        await self.connection_manager.broadcast_event(log_event, self.workspace_id, self.thread_id)
+
+    async def log_warning(self, message: str, sender: str = "agent") -> None:
+        """
+        Log a warning message to the logs panel.
+
+        Args:
+            message: The warning message to log
+        """
+        log_event = AgentEvent(event_type="log_message", sender=sender, content={"text": message, "level": "warning"})
+        await self.connection_manager.broadcast_event(log_event, self.workspace_id, self.thread_id)

kolega_code/agent/compression.py

@@ -0,0 +1,81 @@
+"""History compression: summarize a conversation when it outgrows the context window."""
+
+import logging
+from typing import Awaitable, Callable, Optional
+
+from .conversation import Conversation
+from kolega_code.llm.models import Message, MessageHistory, TextBlock
+from .prompts import (
+    COMPRESSION_SUMMARY_SYSTEM_PROMPT,
+    COMPRESSION_SUMMARY_USER_PROMPT_TEMPLATE,
+)
+
+logger = logging.getLogger(__name__)
+
+LogCallback = Callable[[str], Awaitable[None]]
+
+
+class HistoryCompressor:
+    """Summarizes a conversation non-destructively when it crosses the budget threshold."""
+
+    MIN_MESSAGES_TO_COMPRESS = 5
+
+    def __init__(self, threshold: float = 0.8) -> None:
+        # Fraction of the model context window above which compression kicks in
+        self.threshold = threshold
+
+    def over_budget(self, input_tokens: int, model_context_length: int) -> bool:
+        return input_tokens > model_context_length * self.threshold
+
+    async def summarize(
+        self,
+        conversation: Conversation,
+        *,
+        llm,
+        model: str,
+        max_completion_tokens: int,
+        temperature: float,
+        thinking,
+        on_info: Optional[LogCallback] = None,
+        on_error: Optional[LogCallback] = None,
+    ) -> bool:
+        """
+        Non-destructively summarize the conversation and mark a compression boundary.
+
+        Returns True if a summary was recorded.
+        """
+        if not conversation.history or len(conversation.history) < self.MIN_MESSAGES_TO_COMPRESS:
+            return False
+
+        if on_info:
+            await on_info("Compressing message history...")
+
+        try:
+            conversation_markdown = conversation.history.get_markdown_conversation()
+            user_prompt_filled = COMPRESSION_SUMMARY_USER_PROMPT_TEMPLATE.replace("{HISTORY}", conversation_markdown)
+
+            messages = MessageHistory([Message(role="user", content=[TextBlock(text=user_prompt_filled)])])
+            system_message = Message(role="system", content=[TextBlock(text=COMPRESSION_SUMMARY_SYSTEM_PROMPT)])
+
+            response = await llm.generate(
+                messages=messages,
+                system=system_message,
+                temperature=temperature,
+                model=model,
+                max_completion_tokens=max_completion_tokens,
+                thinking=thinking,
+            )
+
+            summary = response.get_text_content()
+            conversation.record_compression(Message(role="user", content=[TextBlock(text=summary)]))
+
+            if on_info:
+                await on_info("Message history compressed (non-destructive).")
+            return True
+
+        except Exception as e:
+            if on_error:
+                await on_error(f"Failed to compress message history: {str(e)}")
+            else:
+                logger.error("Failed to compress message history: %s", e)
+            return False

kolega_code/agent/context.py

@@ -0,0 +1,112 @@
+"""AgentContext: everything an agent needs, grouped by concern.
+
+Replaces the long flat constructor signature on BaseAgent. Hosts build one
+AgentContext and hand it to any agent class; the legacy keyword signature
+remains supported on BaseAgent and converts to an AgentContext internally.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from langfuse import Langfuse
+
+from kolega_code.config import AgentConfig
+from kolega_code.events import AgentConnectionManager
+from kolega_code.llm.client import LLMClient
+from kolega_code.llm.instrumented_client import InstrumentedLLMClient
+from .prompt_provider import AgentMode, PromptExtension, PromptProvider
+from kolega_code.services.base import BrowserManager, TerminalManager
+from kolega_code.services.browser import PlaywrightBrowserManager
+from kolega_code.services.file_system import FileSystem, LocalFileSystem
+from kolega_code.services.terminal import LocalTerminalManager
+
+
+@dataclass
+class WorkspaceInfo:
+    """Identity and content of the workspace the agent operates in."""
+
+    project_path: Path
+    workspace_id: str
+    thread_id: str
+    project_template_slug: Optional[str] = None
+    protected_files: List[str] = field(default_factory=list)
+    env_var_descriptions: Dict[str, str] = field(default_factory=dict)
+    memories: List[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if isinstance(self.project_path, str):
+            self.project_path = Path(self.project_path)
+
+
+@dataclass
+class AgentServices:
+    """The environment abstractions the agent works through."""
+
+    filesystem: FileSystem
+    terminal_manager: TerminalManager
+    browser_manager: BrowserManager
+
+    @classmethod
+    def local(cls, workspace: WorkspaceInfo, connection_manager: AgentConnectionManager) -> "AgentServices":
+        """Default local-machine services rooted at the workspace project path."""
+        return cls(
+            filesystem=LocalFileSystem(root_path=workspace.project_path),
+            terminal_manager=LocalTerminalManager(workspace.workspace_id, workspace.thread_id, connection_manager),
+            browser_manager=PlaywrightBrowserManager(),
+        )
+
+
+@dataclass
+class Telemetry:
+    """Observability and usage-recording hooks provided by the host."""
+
+    langfuse_client: Optional[Langfuse] = None
+    user_id: Optional[str] = None
+    user_email: Optional[str] = None
+    usage_recorder: Optional[Any] = None
+    sub_agent_recorder: Optional[Any] = None
+
+
+@dataclass
+class AgentContext:
+    """Everything an agent needs to run, grouped by concern."""
+
+    workspace: WorkspaceInfo
+    config: AgentConfig
+    connection_manager: AgentConnectionManager
+    services: AgentServices
+    telemetry: Telemetry = field(default_factory=Telemetry)
+    agent_mode: Optional[AgentMode] = None
+    prompt_provider: Optional[PromptProvider] = None
+    prompt_extensions: List[PromptExtension] = field(default_factory=list)
+    tool_extensions: List[Any] = field(default_factory=list)
+
+    def create_llm_client(self, agent_name: str) -> LLMClient:
+        """Create the LLM client, instrumented when a Langfuse client is available."""
+        model_config = self.config.long_context_config
+
+        if self.telemetry.langfuse_client:
+            return InstrumentedLLMClient(
+                provider=model_config.provider,
+                api_key=self.config.get_api_key(model_config.provider),
+                max_retries=model_config.rate_limits.max_retries,
+                requests_per_minute=model_config.rate_limits.requests_per_minute,
+                tokens_per_minute=model_config.rate_limits.tokens_per_minute,
+                langfuse_client=self.telemetry.langfuse_client,
+                workspace_id=self.workspace.workspace_id,
+                thread_id=self.workspace.thread_id,
+                agent_type=agent_name,
+                environment=self.config.environment,
+                user_id=self.telemetry.user_id,
+                user_email=self.telemetry.user_email,
+                usage_recorder=self.telemetry.usage_recorder,
+            )
+
+        return LLMClient(
+            provider=model_config.provider,
+            api_key=self.config.get_api_key(model_config.provider),
+            max_retries=model_config.rate_limits.max_retries,
+            requests_per_minute=model_config.rate_limits.requests_per_minute,
+            tokens_per_minute=model_config.rate_limits.tokens_per_minute,
+        )