klaude-code 1.2.6__py3-none-any.whl

klaude_code/core/tool/truncation.py

@@ -0,0 +1,170 @@
+import json
+import re
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlparse
+
+from klaude_code import const
+from klaude_code.protocol import model, tools
+
+
+@dataclass
+class TruncationResult:
+    """Result of truncation operation."""
+
+    output: str
+    was_truncated: bool
+    saved_file_path: str | None = None
+    original_length: int = 0
+    truncated_length: int = 0
+
+
+def _extract_url_filename(url: str) -> str:
+    """Extract a safe filename from a URL."""
+    parsed = urlparse(url)
+    # Combine host and path for a meaningful filename
+    host = parsed.netloc.replace(".", "_").replace(":", "_")
+    path = parsed.path.strip("/").replace("/", "_")
+    if path:
+        name = f"{host}_{path}"
+    else:
+        name = host
+    # Sanitize: keep only alphanumeric, underscore, hyphen
+    name = re.sub(r"[^a-zA-Z0-9_\-]", "_", name)
+    # Limit length
+    return name[:80] if len(name) > 80 else name
+
+
+class TruncationStrategy(ABC):
+    """Abstract base class for tool output truncation strategies."""
+
+    @abstractmethod
+    def truncate(self, output: str, tool_call: model.ToolCallItem | None = None) -> TruncationResult:
+        """Truncate the output according to the strategy."""
+        ...
+
+
+class SimpleTruncationStrategy(TruncationStrategy):
+    """Simple character-based truncation strategy."""
+
+    def __init__(self, max_length: int = const.TOOL_OUTPUT_MAX_LENGTH):
+        self.max_length = max_length
+
+    def truncate(self, output: str, tool_call: model.ToolCallItem | None = None) -> TruncationResult:
+        if len(output) > self.max_length:
+            truncated_length = len(output) - self.max_length
+            truncated_output = output[: self.max_length] + f"... (truncated {truncated_length} characters)"
+            return TruncationResult(
+                output=truncated_output,
+                was_truncated=True,
+                original_length=len(output),
+                truncated_length=truncated_length,
+            )
+        return TruncationResult(output=output, was_truncated=False, original_length=len(output))
+
+
+class SmartTruncationStrategy(TruncationStrategy):
+    """Smart truncation strategy that saves full output to file and shows head/tail."""
+
+    def __init__(
+        self,
+        max_length: int = const.TOOL_OUTPUT_MAX_LENGTH,
+        head_chars: int = const.TOOL_OUTPUT_DISPLAY_HEAD,
+        tail_chars: int = const.TOOL_OUTPUT_DISPLAY_TAIL,
+        truncation_dir: str = const.TOOL_OUTPUT_TRUNCATION_DIR,
+    ):
+        self.max_length = max_length
+        self.head_chars = head_chars
+        self.tail_chars = tail_chars
+        self.truncation_dir = Path(truncation_dir)
+
+    def _get_file_identifier(self, tool_call: model.ToolCallItem | None) -> str:
+        """Get a file identifier based on tool call. For WebFetch, use URL; otherwise use call_id."""
+        if tool_call and tool_call.name == tools.WEB_FETCH:
+            try:
+                args = json.loads(tool_call.arguments)
+                url = args.get("url", "")
+                if url:
+                    return _extract_url_filename(url)
+            except (json.JSONDecodeError, TypeError):
+                pass
+        # Fallback to call_id
+        if tool_call and tool_call.call_id:
+            return tool_call.call_id.replace("/", "_")
+        return "unknown"
+
+    def _save_to_file(self, output: str, tool_call: model.ToolCallItem | None) -> str | None:
+        """Save full output to file. Returns file path or None on failure."""
+        try:
+            self.truncation_dir.mkdir(parents=True, exist_ok=True)
+            timestamp = int(time.time())
+            tool_name = (tool_call.name if tool_call else "unknown").replace("/", "_")
+            identifier = self._get_file_identifier(tool_call)
+            filename = f"{tool_name}-{identifier}-{timestamp}.txt"
+            file_path = self.truncation_dir / filename
+            file_path.write_text(output, encoding="utf-8")
+            return str(file_path)
+        except (OSError, IOError):
+            return None
+
+    def truncate(self, output: str, tool_call: model.ToolCallItem | None = None) -> TruncationResult:
+        original_length = len(output)
+
+        if original_length <= self.max_length:
+            return TruncationResult(output=output, was_truncated=False, original_length=original_length)
+
+        # Save full output to file
+        saved_file_path = self._save_to_file(output, tool_call)
+
+        truncated_length = original_length - self.head_chars - self.tail_chars
+        head_content = output[: self.head_chars]
+        tail_content = output[-self.tail_chars :]
+
+        # Build truncated output with file info
+        if saved_file_path:
+            header = (
+                f"<system-reminder>Output truncated: {truncated_length} chars hidden. "
+                f"Full tool output saved to {saved_file_path}. "
+                f"Use Read with limit+offset or rg/grep to inspect.\n"
+                f"Showing first {self.head_chars} and last {self.tail_chars} chars:</system-reminder>\n\n"
+            )
+        else:
+            header = (
+                f"<system-reminder>Output truncated: {truncated_length} chars hidden. "
+                f"Showing first {self.head_chars} and last {self.tail_chars} chars:</system-reminder>\n\n"
+            )
+
+        truncated_output = (
+            f"{header}{head_content}\n\n"
+            f"<system-reminder>... {truncated_length} characters omitted ...</system-reminder>\n\n"
+            f"{tail_content}"
+        )
+
+        return TruncationResult(
+            output=truncated_output,
+            was_truncated=True,
+            saved_file_path=saved_file_path,
+            original_length=original_length,
+            truncated_length=truncated_length,
+        )
+
+
+_default_strategy: TruncationStrategy = SmartTruncationStrategy()
+
+
+def get_truncation_strategy() -> TruncationStrategy:
+    """Get the current truncation strategy."""
+    return _default_strategy
+
+
+def set_truncation_strategy(strategy: TruncationStrategy) -> None:
+    """Set the truncation strategy to use."""
+    global _default_strategy
+    _default_strategy = strategy
+
+
+def truncate_tool_output(output: str, tool_call: model.ToolCallItem | None = None) -> TruncationResult:
+    """Truncate tool output using the current strategy."""
+    return get_truncation_strategy().truncate(output, tool_call)

klaude_code/core/tool/web/mermaid_tool.md

@@ -0,0 +1,21 @@
+Renders a Mermaid diagram from the provided code.
+
+PROACTIVELY USE DIAGRAMS when they would better convey information than prose alone. The diagrams produced by this tool are shown to the user..
+
+You should create diagrams WITHOUT being explicitly asked in these scenarios:
+- When explaining system architecture or component relationships
+- When describing workflows, data flows, or user journeys
+- When explaining algorithms or complex processes
+- When illustrating class hierarchies or entity relationships
+- When showing state transitions or event sequences
+
+Diagrams are especially valuable for visualizing:
+- Application architecture and dependencies
+- API interactions and data flow
+- Component hierarchies and relationships
+- State machines and transitions
+- Sequence and timing of operations
+- Decision trees and conditional logic
+
+# Styling
+- When defining custom classDefs, always define fill color, stroke color, and text color ("fill", "stroke", "color") explicitly

klaude_code/core/tool/web/mermaid_tool.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import base64
+import json
+import zlib
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from klaude_code.core.tool.tool_abc import ToolABC, load_desc
+from klaude_code.core.tool.tool_registry import register
+from klaude_code.protocol import llm_param, model, tools
+
+_MERMAID_LIVE_PREFIX = "https://mermaid.live/view#pako:"
+
+
+@register(tools.MERMAID)
+class MermaidTool(ToolABC):
+    """Create shareable Mermaid.live links for diagram rendering."""
+
+    class MermaidArguments(BaseModel):
+        code: str = Field(description="The Mermaid diagram code to render")
+
+    @classmethod
+    def schema(cls) -> llm_param.ToolSchema:
+        return llm_param.ToolSchema(
+            name=tools.MERMAID,
+            type="function",
+            description=load_desc(Path(__file__).parent / "mermaid_tool.md"),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "code": {
+                        "description": "The Mermaid diagram code to render (DO NOT override with custom colors or other styles, DO NOT use HTML tags in node labels)",
+                        "type": "string",
+                    },
+                },
+                "required": ["code"],
+                "additionalProperties": False,
+            },
+        )
+
+    @classmethod
+    async def call(cls, arguments: str) -> model.ToolResultItem:
+        try:
+            args = cls.MermaidArguments.model_validate_json(arguments)
+        except Exception as exc:  # pragma: no cover - defensive
+            return model.ToolResultItem(status="error", output=f"Invalid arguments: {exc}")
+
+        link = cls._build_link(args.code)
+        line_count = cls._count_lines(args.code)
+        ui_extra = model.ToolResultUIExtra(
+            type=model.ToolResultUIExtraType.MERMAID_LINK,
+            mermaid_link=model.MermaidLinkUIExtra(link=link, line_count=line_count),
+        )
+        output = f"Mermaid diagram rendered successfully ({line_count} lines)."
+        return model.ToolResultItem(status="success", output=output, ui_extra=ui_extra)
+
+    @staticmethod
+    def _build_link(code: str) -> str:
+        state = {
+            "code": code,
+            "mermaid": {"theme": "neutral"},
+            "autoSync": True,
+            "updateDiagram": True,
+        }
+        json_payload = json.dumps(state, ensure_ascii=False)
+        compressed = zlib.compress(json_payload.encode("utf-8"), level=9)
+        encoded = base64.urlsafe_b64encode(compressed).decode("ascii").rstrip("=")
+        return f"{_MERMAID_LIVE_PREFIX}{encoded}"
+
+    @staticmethod
+    def _count_lines(code: str) -> int:
+        if not code:
+            return 0
+        return len(code.splitlines()) or 0

klaude_code/core/tool/web/web_fetch_tool.md

@@ -0,0 +1,8 @@
+Fetch content from a URL and return it in a readable format.
+
+The tool automatically processes the response based on Content-Type:
+- HTML pages are converted to Markdown for easier reading
+- JSON responses are formatted with indentation
+- Markdown and other text content is returned as-is
+
+Use this tool to retrieve web page content for analysis.

klaude_code/core/tool/web/web_fetch_tool.py

@@ -0,0 +1,159 @@
+import asyncio
+import json
+import urllib.error
+import urllib.request
+from http.client import HTTPResponse
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from klaude_code.core.tool.tool_abc import ToolABC, load_desc
+from klaude_code.core.tool.tool_registry import register
+from klaude_code.protocol import llm_param, model, tools
+
+DEFAULT_TIMEOUT_SEC = 30
+DEFAULT_USER_AGENT = "Mozilla/5.0 (compatible; KlaudeCode/1.0)"
+
+
+def _extract_content_type(response: HTTPResponse) -> str:
+    """Extract the base content type without charset parameters."""
+    content_type = response.getheader("Content-Type", "")
+    return content_type.split(";")[0].strip().lower()
+
+
+def _validate_utf8(data: bytes) -> str:
+    """Validate and decode bytes as UTF-8."""
+    return data.decode("utf-8")
+
+
+def _convert_html_to_markdown(html: str) -> str:
+    """Convert HTML to Markdown using trafilatura."""
+    import trafilatura
+
+    result = trafilatura.extract(html, output_format="markdown", include_links=True, include_images=True)
+    return result or ""
+
+
+def _format_json(text: str) -> str:
+    """Format JSON with indentation."""
+    try:
+        parsed = json.loads(text)
+        return json.dumps(parsed, indent=2, ensure_ascii=False)
+    except json.JSONDecodeError:
+        return text
+
+
+def _process_content(content_type: str, text: str) -> str:
+    """Process content based on Content-Type header."""
+    if content_type == "text/html":
+        return _convert_html_to_markdown(text)
+    elif content_type == "text/markdown":
+        return text
+    elif content_type in ("application/json", "text/json"):
+        return _format_json(text)
+    else:
+        return text
+
+
+def _fetch_url(url: str, timeout: int = DEFAULT_TIMEOUT_SEC) -> tuple[str, str]:
+    """
+    Fetch URL content synchronously.
+
+    Returns:
+        Tuple of (content_type, response_text)
+
+    Raises:
+        Various exceptions on failure
+    """
+    headers = {
+        "Accept": "text/markdown, */*",
+        "User-Agent": DEFAULT_USER_AGENT,
+    }
+    request = urllib.request.Request(url, headers=headers)
+
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        content_type = _extract_content_type(response)
+        data = response.read()
+        text = _validate_utf8(data)
+        return content_type, text
+
+
+@register(tools.WEB_FETCH)
+class WebFetchTool(ToolABC):
+    @classmethod
+    def schema(cls) -> llm_param.ToolSchema:
+        return llm_param.ToolSchema(
+            name=tools.WEB_FETCH,
+            type="function",
+            description=load_desc(Path(__file__).parent / "web_fetch_tool.md"),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "url": {
+                        "type": "string",
+                        "description": "The URL to fetch",
+                    },
+                },
+                "required": ["url"],
+            },
+        )
+
+    class WebFetchArguments(BaseModel):
+        url: str
+
+    @classmethod
+    async def call(cls, arguments: str) -> model.ToolResultItem:
+        try:
+            args = WebFetchTool.WebFetchArguments.model_validate_json(arguments)
+        except ValueError as e:
+            return model.ToolResultItem(
+                status="error",
+                output=f"Invalid arguments: {e}",
+            )
+        return await cls.call_with_args(args)
+
+    @classmethod
+    async def call_with_args(cls, args: WebFetchArguments) -> model.ToolResultItem:
+        url = args.url
+
+        # Basic URL validation
+        if not url.startswith(("http://", "https://")):
+            return model.ToolResultItem(
+                status="error",
+                output="Invalid URL: must start with http:// or https://",
+            )
+
+        try:
+            content_type, text = await asyncio.to_thread(_fetch_url, url)
+            processed = _process_content(content_type, text)
+
+            return model.ToolResultItem(
+                status="success",
+                output=processed,
+            )
+
+        except urllib.error.HTTPError as e:
+            return model.ToolResultItem(
+                status="error",
+                output=f"HTTP error {e.code}: {e.reason}",
+            )
+        except urllib.error.URLError as e:
+            return model.ToolResultItem(
+                status="error",
+                output=f"URL error: {e.reason}",
+            )
+        except UnicodeDecodeError as e:
+            return model.ToolResultItem(
+                status="error",
+                output=f"Content is not valid UTF-8: {e}",
+            )
+        except TimeoutError:
+            return model.ToolResultItem(
+                status="error",
+                output=f"Request timed out after {DEFAULT_TIMEOUT_SEC} seconds",
+            )
+        except Exception as e:
+            return model.ToolResultItem(
+                status="error",
+                output=f"Failed to fetch URL: {e}",
+            )

klaude_code/core/turn.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable, MutableMapping, Sequence
+from dataclasses import dataclass
+
+from klaude_code.core.tool import TodoContext, ToolABC, tool_context
+from klaude_code.core.tool.tool_runner import (
+    ToolExecutionCallStarted,
+    ToolExecutionResult,
+    ToolExecutionTodoChange,
+    ToolExecutor,
+    ToolExecutorEvent,
+)
+from klaude_code.llm import LLMClientABC
+from klaude_code.protocol import events, llm_param, model
+from klaude_code.trace import DebugType, log_debug
+
+
+class TurnError(Exception):
+    """Raised when a turn fails and should be retried."""
+
+    pass
+
+
+@dataclass
+class TurnExecutionContext:
+    """Execution context required to run a single turn."""
+
+    session_id: str
+    get_conversation_history: Callable[[], list[model.ConversationItem]]
+    append_history: Callable[[Sequence[model.ConversationItem]], None]
+    llm_client: LLMClientABC
+    system_prompt: str | None
+    tools: list[llm_param.ToolSchema]
+    tool_registry: dict[str, type[ToolABC]]
+    # For tool context
+    file_tracker: MutableMapping[str, float]
+    todo_context: TodoContext
+
+
+def build_events_from_tool_executor_event(session_id: str, event: ToolExecutorEvent) -> list[events.Event]:
+    """Translate internal tool executor events into public protocol events."""
+
+    ui_events: list[events.Event] = []
+
+    match event:
+        case ToolExecutionCallStarted(tool_call=tool_call):
+            ui_events.append(
+                events.ToolCallEvent(
+                    session_id=session_id,
+                    response_id=tool_call.response_id,
+                    tool_call_id=tool_call.call_id,
+                    tool_name=tool_call.name,
+                    arguments=tool_call.arguments,
+                )
+            )
+        case ToolExecutionResult(tool_call=tool_call, tool_result=tool_result):
+            ui_events.append(
+                events.ToolResultEvent(
+                    session_id=session_id,
+                    response_id=tool_call.response_id,
+                    tool_call_id=tool_call.call_id,
+                    tool_name=tool_call.name,
+                    result=tool_result.output or "",
+                    ui_extra=tool_result.ui_extra,
+                    status=tool_result.status,
+                )
+            )
+        case ToolExecutionTodoChange(todos=todos):
+            ui_events.append(
+                events.TodoChangeEvent(
+                    session_id=session_id,
+                    todos=todos,
+                )
+            )
+
+    return ui_events
+
+
+class TurnExecutor:
+    """Executes a single model turn including tool calls.
+
+    Manages the lifecycle of tool execution and tool context internally.
+    Raises TurnError on failure.
+    """
+
+    def __init__(self, context: TurnExecutionContext) -> None:
+        self._context = context
+        self._tool_executor: ToolExecutor | None = None
+        self._has_tool_call: bool = False
+
+    @property
+    def has_tool_call(self) -> bool:
+        return self._has_tool_call
+
+    def cancel(self) -> list[events.Event]:
+        """Cancel running tools and return any resulting events."""
+        ui_events: list[events.Event] = []
+        if self._tool_executor is not None:
+            for exec_event in self._tool_executor.cancel():
+                for ui_event in build_events_from_tool_executor_event(self._context.session_id, exec_event):
+                    ui_events.append(ui_event)
+            self._tool_executor = None
+        return ui_events
+
+    async def run(self) -> AsyncGenerator[events.Event, None]:
+        """Execute the turn, yielding events as they occur.
+
+        Raises:
+            TurnError: If the turn fails (stream error or non-completed status).
+        """
+        ctx = self._context
+
+        yield events.TurnStartEvent(session_id=ctx.session_id)
+
+        turn_reasoning_items: list[model.ReasoningTextItem | model.ReasoningEncryptedItem] = []
+        turn_assistant_message: model.AssistantMessageItem | None = None
+        turn_tool_calls: list[model.ToolCallItem] = []
+        response_failed = False
+        error_message: str | None = None
+
+        async for response_item in ctx.llm_client.call(
+            llm_param.LLMCallParameter(
+                input=ctx.get_conversation_history(),
+                system=ctx.system_prompt,
+                tools=ctx.tools,
+                store=False,
+                session_id=ctx.session_id,
+            )
+        ):
+            log_debug(
+                f"[{response_item.__class__.__name__}]",
+                response_item.model_dump_json(exclude_none=True),
+                style="green",
+                debug_type=DebugType.RESPONSE,
+            )
+            match response_item:
+                case model.StartItem():
+                    pass
+                case model.ReasoningTextItem() as item:
+                    turn_reasoning_items.append(item)
+                    yield events.ThinkingEvent(
+                        content=item.content,
+                        response_id=item.response_id,
+                        session_id=ctx.session_id,
+                    )
+                case model.ReasoningEncryptedItem() as item:
+                    turn_reasoning_items.append(item)
+                case model.AssistantMessageDelta() as item:
+                    yield events.AssistantMessageDeltaEvent(
+                        content=item.content,
+                        response_id=item.response_id,
+                        session_id=ctx.session_id,
+                    )
+                case model.AssistantMessageItem() as item:
+                    turn_assistant_message = item
+                    yield events.AssistantMessageEvent(
+                        content=item.content or "",
+                        response_id=item.response_id,
+                        session_id=ctx.session_id,
+                    )
+                case model.ResponseMetadataItem() as item:
+                    yield events.ResponseMetadataEvent(
+                        session_id=ctx.session_id,
+                        metadata=item,
+                    )
+                    status = item.status
+                    if status is not None and status != "completed":
+                        response_failed = True
+                        error_message = f"Response status: {status}"
+                case model.StreamErrorItem() as item:
+                    response_failed = True
+                    error_message = item.error
+                    log_debug(
+                        "[StreamError]",
+                        item.error,
+                        style="red",
+                        debug_type=DebugType.RESPONSE,
+                    )
+                case model.ToolCallStartItem() as item:
+                    yield events.TurnToolCallStartEvent(
+                        session_id=ctx.session_id,
+                        response_id=item.response_id,
+                        tool_call_id=item.call_id,
+                        tool_name=item.name,
+                        arguments="",
+                    )
+                case model.ToolCallItem() as item:
+                    turn_tool_calls.append(item)
+                case _:
+                    pass
+
+        if response_failed:
+            yield events.TurnEndEvent(session_id=ctx.session_id)
+            raise TurnError(error_message or "Turn failed")
+
+        # Append to history only on success
+        if turn_reasoning_items:
+            ctx.append_history(turn_reasoning_items)
+        if turn_assistant_message:
+            ctx.append_history([turn_assistant_message])
+        if turn_tool_calls:
+            ctx.append_history(turn_tool_calls)
+            self._has_tool_call = True
+
+        # Execute tools
+        if turn_tool_calls:
+            with tool_context(ctx.file_tracker, ctx.todo_context):
+                executor = ToolExecutor(
+                    registry=ctx.tool_registry,
+                    append_history=ctx.append_history,
+                )
+                self._tool_executor = executor
+
+                async for exec_event in executor.run_tools(turn_tool_calls):
+                    for ui_event in build_events_from_tool_executor_event(ctx.session_id, exec_event):
+                        yield ui_event
+                self._tool_executor = None
+
+        yield events.TurnEndEvent(session_id=ctx.session_id)

klaude_code/llm/__init__.py

@@ -0,0 +1,21 @@
+"""LLM package init.
+
+Imports built-in LLM clients so their ``@register`` decorators run and they
+become available via the registry.
+"""
+
+from .anthropic import AnthropicClient
+from .client import LLMClientABC
+from .openai_compatible import OpenAICompatibleClient
+from .openrouter import OpenRouterClient
+from .registry import create_llm_client
+from .responses import ResponsesClient
+
+__all__ = [
+    "LLMClientABC",
+    "ResponsesClient",
+    "OpenAICompatibleClient",
+    "OpenRouterClient",
+    "AnthropicClient",
+    "create_llm_client",
+]

klaude_code/llm/anthropic/__init__.py

@@ -0,0 +1,3 @@
+from .client import AnthropicClient
+
+__all__ = ["AnthropicClient"]