klaude-code 1.2.6__py3-none-any.whl

klaude_code/core/manager/agent_manager.py

@@ -0,0 +1,127 @@
+"""Agent and session manager.
+
+This module contains :class:`AgentManager`, a helper responsible for
+creating and tracking agents per session, applying model changes, and
+clearing conversations. It is used by the executor context to keep
+agent-related responsibilities separate from operation dispatch.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from klaude_code.config import load_config
+from klaude_code.core.agent import Agent, DefaultModelProfileProvider, ModelProfileProvider
+from klaude_code.core.manager.llm_clients import LLMClients
+from klaude_code.llm.registry import create_llm_client
+from klaude_code.protocol import commands, events, model
+from klaude_code.session.session import Session
+from klaude_code.trace import DebugType, log_debug
+
+
+class AgentManager:
+    """Manager component that tracks agents and their sessions."""
+
+    def __init__(
+        self,
+        event_queue: asyncio.Queue[events.Event],
+        llm_clients: LLMClients,
+        model_profile_provider: ModelProfileProvider | None = None,
+    ) -> None:
+        self._event_queue: asyncio.Queue[events.Event] = event_queue
+        self._llm_clients: LLMClients = llm_clients
+        self._model_profile_provider: ModelProfileProvider = model_profile_provider or DefaultModelProfileProvider()
+        self._active_agents: dict[str, Agent] = {}
+
+    async def emit_event(self, event: events.Event) -> None:
+        """Emit an event to the shared event queue."""
+
+        await self._event_queue.put(event)
+
+    async def ensure_agent(self, session_id: str) -> Agent:
+        """Return an existing agent for the session or create a new one."""
+
+        agent = self._active_agents.get(session_id)
+        if agent is not None:
+            return agent
+
+        session = Session.load(session_id)
+        profile = self._model_profile_provider.build_profile(self._llm_clients.main)
+        agent = Agent(session=session, profile=profile)
+
+        async for evt in agent.replay_history():
+            await self.emit_event(evt)
+
+        await self.emit_event(
+            events.WelcomeEvent(
+                work_dir=str(session.work_dir),
+                llm_config=self._llm_clients.main.get_llm_config(),
+            )
+        )
+
+        self._active_agents[session_id] = agent
+        log_debug(
+            f"Initialized agent for session: {session_id}",
+            style="cyan",
+            debug_type=DebugType.EXECUTION,
+        )
+        return agent
+
+    async def apply_model_change(self, agent: Agent, model_name: str) -> None:
+        """Change the model used by an agent and notify the UI."""
+
+        config = load_config()
+        if config is None:
+            raise ValueError("Configuration must be initialized before changing model")
+
+        llm_config = config.get_model_config(model_name)
+        llm_client = create_llm_client(llm_config)
+        agent.set_model_profile(self._model_profile_provider.build_profile(llm_client))
+
+        developer_item = model.DeveloperMessageItem(
+            content=f"switched to model: {model_name}",
+            command_output=model.CommandOutput(command_name=commands.CommandName.MODEL),
+        )
+        agent.session.append_history([developer_item])
+
+        await self.emit_event(events.DeveloperMessageEvent(session_id=agent.session.id, item=developer_item))
+        await self.emit_event(events.WelcomeEvent(llm_config=llm_config, work_dir=str(agent.session.work_dir)))
+
+    async def apply_clear(self, agent: Agent) -> None:
+        """Start a new conversation for an agent and notify the UI."""
+
+        old_session_id = agent.session.id
+
+        # Create a new session instance to replace the current one
+        new_session = Session(work_dir=agent.session.work_dir)
+        new_session.model_name = agent.session.model_name
+
+        # Replace the agent's session with the new one
+        agent.session = new_session
+        agent.session.save()
+
+        # Update the active_agents mapping
+        self._active_agents.pop(old_session_id, None)
+        self._active_agents[new_session.id] = agent
+
+        developer_item = model.DeveloperMessageItem(
+            content="started new conversation",
+            command_output=model.CommandOutput(command_name=commands.CommandName.CLEAR),
+        )
+
+        await self.emit_event(events.DeveloperMessageEvent(session_id=agent.session.id, item=developer_item))
+
+    def get_active_agent(self, session_id: str) -> Agent | None:
+        """Return the active agent for a session id if present."""
+
+        return self._active_agents.get(session_id)
+
+    def active_session_ids(self) -> list[str]:
+        """Return a snapshot list of session ids that currently have agents."""
+
+        return list(self._active_agents.keys())
+
+    def all_active_agents(self) -> dict[str, Agent]:
+        """Return a snapshot of all active agents keyed by session id."""
+
+        return dict(self._active_agents)

klaude_code/core/manager/llm_clients.py

@@ -0,0 +1,42 @@
+"""Container for main and sub-agent LLM clients."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field as dataclass_field
+
+from klaude_code.llm.client import LLMClientABC
+from klaude_code.protocol.tools import SubAgentType
+
+
+def _default_sub_clients() -> dict[SubAgentType, LLMClientABC]:
+    """Return an empty mapping for sub-agent clients.
+
+    Defined separately so static type checkers can infer the dictionary
+    key and value types instead of treating them as ``Unknown``.
+    """
+
+    return {}
+
+
+@dataclass
+class LLMClients:
+    """Container for LLM clients used by main agent and sub-agents."""
+
+    main: LLMClientABC
+    sub_clients: dict[SubAgentType, LLMClientABC] = dataclass_field(default_factory=_default_sub_clients)
+
+    def get_client(self, sub_agent_type: SubAgentType | None = None) -> LLMClientABC:
+        """Return client for a sub-agent type or the main client.
+
+        Args:
+            sub_agent_type: Optional sub-agent type whose client should be returned.
+
+        Returns:
+            The LLM client corresponding to the sub-agent type, or the main client
+            when no specialized client is available.
+        """
+
+        if sub_agent_type is None:
+            return self.main
+        return self.sub_clients.get(sub_agent_type) or self.main

klaude_code/core/manager/llm_clients_builder.py

@@ -0,0 +1,49 @@
+"""Factory helpers for building :class:`LLMClients` from config."""
+
+from __future__ import annotations
+
+from klaude_code.config import Config
+from klaude_code.core.manager.llm_clients import LLMClients
+from klaude_code.llm.client import LLMClientABC
+from klaude_code.llm.registry import create_llm_client
+from klaude_code.protocol.sub_agent import get_sub_agent_profile
+from klaude_code.protocol.tools import SubAgentType
+from klaude_code.trace import DebugType, log_debug
+
+
+def build_llm_clients(
+    config: Config,
+    *,
+    model_override: str | None = None,
+    enabled_sub_agents: list[SubAgentType] | None = None,
+) -> LLMClients:
+    """Create an ``LLMClients`` bundle driven by application config."""
+
+    # Resolve main agent LLM config
+    if model_override:
+        llm_config = config.get_model_config(model_override)
+    else:
+        llm_config = config.get_main_model_config()
+
+    log_debug(
+        "Main LLM config",
+        llm_config.model_dump_json(exclude_none=True),
+        style="yellow",
+        debug_type=DebugType.LLM_CONFIG,
+    )
+
+    main_client = create_llm_client(llm_config)
+    sub_clients: dict[SubAgentType, LLMClientABC] = {}
+
+    # Initialize sub-agent clients
+    for sub_agent_type in enabled_sub_agents or []:
+        model_name = config.subagent_models.get(sub_agent_type)
+        if not model_name:
+            continue
+        profile = get_sub_agent_profile(sub_agent_type)
+        if not profile.enabled_for_model(main_client.model_name):
+            continue
+        sub_llm_config = config.get_model_config(model_name)
+        sub_clients[sub_agent_type] = create_llm_client(sub_llm_config)
+
+    return LLMClients(main=main_client, sub_clients=sub_clients)

klaude_code/core/manager/sub_agent_manager.py

@@ -0,0 +1,86 @@
+"""Manager for running nested sub-agent tasks.
+
+The :class:`SubAgentManager` encapsulates the logic for creating child
+sessions, selecting appropriate LLM clients for sub-agents, and streaming
+their events back to the shared event queue.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from klaude_code.core.agent import Agent, ModelProfileProvider
+from klaude_code.core.manager.llm_clients import LLMClients
+from klaude_code.protocol import events, model
+from klaude_code.protocol.sub_agent import SubAgentResult
+from klaude_code.session.session import Session
+from klaude_code.trace import DebugType, log_debug
+
+
+class SubAgentManager:
+    """Run sub-agent tasks and forward their events to the UI."""
+
+    def __init__(
+        self,
+        event_queue: asyncio.Queue[events.Event],
+        llm_clients: LLMClients,
+        model_profile_provider: ModelProfileProvider,
+    ) -> None:
+        self._event_queue: asyncio.Queue[events.Event] = event_queue
+        self._llm_clients: LLMClients = llm_clients
+        self._model_profile_provider: ModelProfileProvider = model_profile_provider
+
+    async def emit_event(self, event: events.Event) -> None:
+        """Emit an event to the shared event queue."""
+
+        await self._event_queue.put(event)
+
+    async def run_subagent(self, parent_agent: Agent, state: model.SubAgentState) -> SubAgentResult:
+        """Run a nested sub-agent task and return its result."""
+
+        # Create a child session under the same workdir
+        parent_session = parent_agent.session
+        child_session = Session(work_dir=parent_session.work_dir)
+        child_session.sub_agent_state = state
+
+        child_profile = self._model_profile_provider.build_profile(
+            self._llm_clients.get_client(state.sub_agent_type),
+            state.sub_agent_type,
+        )
+        child_agent = Agent(session=child_session, profile=child_profile)
+
+        log_debug(
+            f"Running sub-agent {state.sub_agent_type} in session {child_session.id}",
+            style="cyan",
+            debug_type=DebugType.EXECUTION,
+        )
+
+        try:
+            # Not emit the subtask's user input since task tool call is already rendered
+            result: str = ""
+            sub_agent_input = model.UserInputPayload(text=state.sub_agent_prompt, images=None)
+            async for event in child_agent.run_task(sub_agent_input):
+                # Capture TaskFinishEvent content for return
+                if isinstance(event, events.TaskFinishEvent):
+                    result = event.task_result
+                await self.emit_event(event)
+            return SubAgentResult(task_result=result, session_id=child_session.id)
+        except asyncio.CancelledError:
+            # Propagate cancellation so tooling can treat it as user interrupt
+            log_debug(
+                f"Subagent task for {state.sub_agent_type} was cancelled",
+                style="yellow",
+                debug_type=DebugType.EXECUTION,
+            )
+            raise
+        except Exception as exc:  # pragma: no cover - defensive logging
+            log_debug(
+                f"Subagent task failed: [{exc.__class__.__name__}] {str(exc)}",
+                style="red",
+                debug_type=DebugType.EXECUTION,
+            )
+            return SubAgentResult(
+                task_result=f"Subagent task failed: [{exc.__class__.__name__}] {str(exc)}",
+                session_id="",
+                error=True,
+            )

klaude_code/core/prompt.py

@@ -0,0 +1,89 @@
+import datetime
+import shutil
+from functools import lru_cache
+from importlib.resources import files
+from pathlib import Path
+
+COMMAND_DESCRIPTIONS: dict[str, str] = {
+    "rg": "ripgrep - fast text search",
+    "fd": "fd - simple and fast alternative to find",
+    "tree": "tree - directory listing as a tree",
+    "sg": "ast-grep - AST-aware code search",
+}
+
+# Mapping from logical prompt keys to resource file paths under the core/prompt directory.
+PROMPT_FILES: dict[str, str] = {
+    "main_codex": "prompts/prompt-codex.md",
+    "main_claude": "prompts/prompt-claude-code.md",
+    "main_gemini": "prompts/prompt-gemini.md",  # https://ai.google.dev/gemini-api/docs/prompting-strategies?hl=zh-cn#agentic-si-template
+    # Sub-agent prompts keyed by their name
+    "Task": "prompts/prompt-subagent.md",
+    "Oracle": "prompts/prompt-subagent-oracle.md",
+    "Explore": "prompts/prompt-subagent-explore.md",
+    "WebFetchAgent": "prompts/prompt-subagent-webfetch.md",
+}
+
+
+@lru_cache(maxsize=None)
+def get_system_prompt(model_name: str, sub_agent_type: str | None = None) -> str:
+    """Get system prompt content for the given model and sub-agent type."""
+
+    cwd = Path.cwd()
+    today = datetime.datetime.now().strftime("%Y-%m-%d")
+    is_git_repo = (cwd / ".git").exists()
+
+    available_tools: list[str] = []
+    for command, desc in COMMAND_DESCRIPTIONS.items():
+        if shutil.which(command) is not None:
+            available_tools.append(f"{command}: {desc}")
+
+    if sub_agent_type is None:
+        match model_name:
+            case name if "gpt-5" in name:
+                file_key = "main_codex"
+            case name if "gemini" in name:
+                file_key = "main_gemini"
+            case _:
+                file_key = "main_claude"
+    else:
+        file_key = sub_agent_type
+
+    try:
+        prompt_path = PROMPT_FILES[file_key]
+    except KeyError as exc:
+        raise ValueError(f"Unknown prompt key: {file_key}") from exc
+
+    base_prompt = (
+        files(__package__)
+        .joinpath(prompt_path)
+        .read_text(encoding="utf-8")
+        .format(
+            working_directory=str(cwd),
+            date=today,
+            is_git_repo=is_git_repo,
+            model_name=model_name,
+        )
+        .strip()
+    )
+
+    env_lines: list[str] = [
+        "",
+        "",
+        "Here is useful information about the environment you are running in:",
+        "<env>",
+        f"Working directory: {cwd}",
+        f"Today's Date: {today}",
+        f"Is directory a git repo: {is_git_repo}",
+        f"You are powered by the model: {model_name}",
+    ]
+
+    if available_tools:
+        env_lines.append("Prefer to use the following CLI utilities:")
+        for tool in available_tools:
+            env_lines.append(f"- {tool}")
+
+    env_lines.append("</env>")
+
+    env_info = "\n".join(env_lines)
+
+    return base_prompt + env_info

klaude_code/core/prompts/prompt-claude-code.md

@@ -0,0 +1,98 @@
+You are an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.
+
+## Tone and style
+- Never use emojis.
+- Your output will be displayed on a command line interface. Your responses should be short and concise. You can use Github-flavored markdown for formatting, and will be rendered in a monospace font using the CommonMark specification.
+- Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like Bash or code comments as means to communicate with the user during the session.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. This includes markdown files.
+
+## Professional objectivity
+Prioritize technical accuracy and truthfulness over validating the user's beliefs. Focus on facts and problem-solving, providing direct, objective technical info without any unnecessary superlatives, praise, or emotional validation. It is best for the user if Claude honestly applies the same rigorous standards to all ideas and disagrees when necessary, even if it may not be what the user wants to hear. Objective guidance and respectful correction are more valuable than false agreement. Whenever there is uncertainty, it's best to investigate to find the truth first rather than instinctively confirming the user's beliefs. Avoid using over-the-top validation or excessive praise when responding to users such as "You're absolutely right" or similar phrases.
+
+## Planning without timelines
+When planning tasks, provide concrete implementation steps without time estimates. Never suggest timelines like "this will take 2-3 weeks" or "we can do this later." Focus on what needs to be done, not when. Break work into actionable steps and let users decide scheduling.
+
+## Task Management
+You have access to the TodoWrite tools to help you manage and plan tasks. Use these tools VERY frequently to ensure that you are tracking your tasks and giving the user visibility into your progress.
+These tools are also EXTREMELY helpful for planning tasks, and for breaking down larger complex tasks into smaller steps. If you do not use this tool when planning, you may forget to do important tasks - and that is unacceptable.
+
+It is critical that you mark todos as completed as soon as you are done with a task. Do not batch up multiple tasks before marking them as completed.
+
+Examples:
+
+<example>
+user: Run the build and fix any type errors
+assistant: I'm going to use the TodoWrite tool to write the following items to the todo list:
+- Run the build
+- Fix any type errors
+
+I'm now going to run the build using Bash.
+
+Looks like I found 10 type errors. I'm going to use the TodoWrite tool to write 10 items to the todo list.
+
+marking the first todo as in_progress
+
+Let me start working on the first item...
+
+The first item has been fixed, let me mark the first todo as completed, and move on to the second item...
+..
+..
+</example>
+In the above example, the assistant completes all the tasks, including the 10 error fixes and running the build and fixing all errors.
+
+<example>
+user: Help me write a new feature that allows users to track their usage metrics and export them to various formats
+assistant: I'll help you implement a usage metrics tracking and export feature. Let me first use the TodoWrite tool to plan this task.
+Adding the following todos to the todo list:
+1. Research existing metrics tracking in the codebase
+2. Design the metrics collection system
+3. Implement core metrics tracking functionality
+4. Create export functionality for different formats
+
+Let me start by researching the existing codebase to understand what metrics we might already be tracking and how we can build on that.
+
+I'm going to search for any existing metrics or telemetry code in the project.
+
+I've found some existing telemetry code. Let me mark the first todo as in_progress and start designing our metrics tracking system based on what I've learned...
+
+[Assistant continues implementing the feature step by step, marking todos as in_progress and completed as they go]
+</example>
+
+## Doing tasks
+The user will primarily request you perform software engineering tasks. This includes solving bugs, adding new functionality, refactoring code, explaining code, and more. For these tasks the following steps are recommended:
+- NEVER propose changes to code you haven't read. If a user asks about or wants you to modify a file, read it first. Understand existing code before suggesting modifications.
+- Use the TodoWrite tool to plan the task if required
+- Be careful not to introduce security vulnerabilities such as command injection, XSS, SQL injection, and other OWASP top 10 vulnerabilities. If you notice that you wrote insecure code, immediately fix it.
+- Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.
+  - Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability. Don't add docstrings, comments, or type annotations to code you didn't change. Only add comments where the logic isn't self-evident.
+  - Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use feature flags or backwards-compatibility shims when you can just change the code.
+  - Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task—three similar lines of code is better than a premature abstraction.
+- Avoid backwards-compatibility hacks like renaming unused `_vars`, re-exporting types, adding `// removed` comments for removed code, etc. If something is unused, delete it completely.
+
+- Tool results and user messages may include <system-reminder> tags. <system-reminder> tags contain useful information and reminders. They are automatically added by the system, and bear no direct relation to the specific tool results or user messages in which they appear.
+
+## Tool usage policy
+- When doing file search, prefer to use the Explore tool in order to reduce context usage.
+- You can call multiple tools in a single response. If you intend to call multiple tools and there are no dependencies between them, make all independent tool calls in parallel. Maximize use of parallel tool calls where possible to increase efficiency. However, if some tool calls depend on previous calls to inform dependent values, do NOT call these tools in parallel and instead call them sequentially. For instance, if one operation must complete before another starts, run these operations sequentially instead. Never use placeholders or guess missing parameters in tool calls.
+- If the user specifies that they want you to run tools "in parallel", you MUST send a single message with multiple tool use content blocks. For example, if you need to launch multiple agents in parallel, send a single message with multiple Task tool calls.
+- Use specialized tools instead of bash commands when possible, as this provides a better user experience. For file operations, use dedicated tools: Read for reading files instead of cat/head/tail, Edit for editing instead of sed/awk. NEVER use bash echo or other command-line tools to communicate thoughts, explanations, or instructions to the user. Output all communication directly in your response text instead.
+- VERY IMPORTANT: When exploring the codebase to gather context or to answer a question that is not a needle query for a specific file/class/function, it is CRITICAL that you use the Explore tool instead of running search commands directly.
+<example>
+user: Where are errors from the client handled?
+assistant: [Uses the Explore tool to find the files that handle client errors instead of using Glob or Grep directly]
+</example>
+<example>
+user: What is the codebase structure?
+assistant: [Uses the Explore tool]
+</example>
+
+## Memory
+MEMORY PROTOCOL:
+1. Use the `view` command of your `Memory` tool to check for earlier progress.
+2. ... (work on the task) ...
+     - As you make progress, record status / progress / thoughts etc in your memory.
+ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.
+
+Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary.
+
+Only write down information relevant to current project in your memory system.