klaude-code 1.2.23__py3-none-any.whl → 1.2.24__py3-none-any.whl

klaude_code/command/prompt-jj-describe.md

@@ -0,0 +1,32 @@
+---
+description: Add description for current jj change
+---
+
+Run `jj status` and `jj diff --git` to see the current changes and add a description for the it.
+
+In order to ensure good formatting, ALWAYS pass the commit message via a HEREDOC, a la this example:<example>
+jj describe -m "$(cat <<'EOF'
+   Commit message here.
+   EOF
+   )"
+</example>
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+```
+<type>(<scope>): <description>
+```
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, no logic change)
+- `refactor`: Code refactoring (no feature or fix)
+- `test`: Adding or updating tests
+- `chore`: Build process, dependencies, or tooling changes
+
+Examples:
+- `feat(cli): add --verbose flag for debug output`
+- `fix(llm): handle API timeout errors gracefully`
+- `docs(readme): update installation instructions`
+- `refactor(core): simplify session state management`

klaude_code/{const/__init__.py → const.py}

@@ -93,7 +93,7 @@ TRUNCATE_DISPLAY_MAX_LINE_LENGTH = 1000
 TRUNCATE_DISPLAY_MAX_LINES = 8
 
 # Maximum lines for sub-agent result display
-SUB_AGENT_RESULT_MAX_LINES = 20
+SUB_AGENT_RESULT_MAX_LINES = 50
 
 
 # UI refresh rate (frames per second) for debounced content streaming
@@ -111,6 +111,9 @@ MARKDOWN_RIGHT_MARGIN = 2
 # Status hint text shown after spinner status
 STATUS_HINT_TEXT = " (esc to interrupt)"
 
+# Default spinner status text when idle/thinking
+STATUS_DEFAULT_TEXT = "Thinking …"
+
 # Status shimmer animation
 # Horizontal padding used when computing shimmer band position
 STATUS_SHIMMER_PADDING = 10

klaude_code/core/executor.py

@@ -327,7 +327,7 @@ class ExecutorContext:
             log_debug(traceback.format_exc(), style="red", debug_type=DebugType.EXECUTION)
             await self.emit_event(
                 events.ErrorEvent(
-                    error_message=f"Agent task failed: [{e.__class__.__name__}] {e!s}",
+                    error_message=f"Agent task failed: [{e.__class__.__name__}] {e!s} {traceback.format_exc()}",
                     can_retry=False,
                 )
             )

klaude_code/core/tool/file/read_tool.py

@@ -25,6 +25,18 @@ _IMAGE_MIME_TYPES: dict[str, str] = {
     ".webp": "image/webp",
 }
 
+_BINARY_CHECK_SIZE = 8192
+
+
+def _is_binary_file(file_path: str) -> bool:
+    """Check if a file is binary by looking for null bytes in the first chunk."""
+    try:
+        with open(file_path, "rb") as f:
+            chunk = f.read(_BINARY_CHECK_SIZE)
+            return b"\x00" in chunk
+    except OSError:
+        return False
+
 
 def _format_numbered_line(line_no: int, content: str) -> str:
     # 6-width right-aligned line number followed by a right arrow
@@ -218,12 +230,22 @@ class ReadTool(ToolABC):
                 ),
             )
 
+        is_image_file = _is_supported_image_file(file_path)
+        # Check for binary files (skip for images which are handled separately)
+        if not is_image_file and _is_binary_file(file_path):
+            return model.ToolResultItem(
+                status="error",
+                output=(
+                    "<tool_use_error>This appears to be a binary file and cannot be read as text. "
+                    "Use appropriate tools or libraries to handle binary files.</tool_use_error>"
+                ),
+            )
+
         try:
             size_bytes = Path(file_path).stat().st_size
         except OSError:
             size_bytes = 0
 
-        is_image_file = _is_supported_image_file(file_path)
         if is_image_file:
             if size_bytes > const.READ_MAX_IMAGE_BYTES:
                 size_mb = size_bytes / (1024 * 1024)

klaude_code/core/tool/file/write_tool.py

@@ -124,9 +124,13 @@ class WriteTool(ToolABC):
                     is_memory=is_mem,
                 )
 
-        # Build diff between previous and new content
-        after = args.content
-        ui_extra = build_structured_diff(before, after, file_path=file_path)
+        # For markdown files, use MarkdownDocUIExtra to render content as markdown
+        # Otherwise, build diff between previous and new content
+        ui_extra: model.ToolResultUIExtra | None
+        if file_path.endswith(".md"):
+            ui_extra = model.MarkdownDocUIExtra(file_path=file_path, content=args.content)
+        else:
+            ui_extra = build_structured_diff(before, args.content, file_path=file_path)
 
         message = f"File {'overwritten' if exists else 'created'} successfully at: {file_path}"
         return model.ToolResultItem(status="success", output=message, ui_extra=ui_extra)

klaude_code/llm/openai_compatible/client.py

@@ -1,6 +1,6 @@
 import json
 from collections.abc import AsyncGenerator
-from typing import override
+from typing import Any, override
 
 import httpx
 import openai
@@ -9,9 +9,9 @@ from openai.types.chat.completion_create_params import CompletionCreateParamsStr
 from klaude_code.llm.client import LLMClientABC
 from klaude_code.llm.input_common import apply_config_defaults
 from klaude_code.llm.openai_compatible.input import convert_history_to_input, convert_tool_schema
-from klaude_code.llm.openai_compatible.stream_processor import StreamStateManager
+from klaude_code.llm.openai_compatible.stream import DefaultReasoningHandler, parse_chat_completions_stream
 from klaude_code.llm.registry import register
-from klaude_code.llm.usage import MetadataTracker, convert_usage
+from klaude_code.llm.usage import MetadataTracker
 from klaude_code.protocol import llm_param, model
 from klaude_code.trace import DebugType, log_debug
 
@@ -86,107 +86,34 @@ class OpenAICompatibleClient(LLMClientABC):
             debug_type=DebugType.LLM_PAYLOAD,
         )
 
-        stream = self.client.chat.completions.create(
-            **payload,
-            extra_body=extra_body,
-            extra_headers=extra_headers,
-        )
-
-        state = StreamStateManager(param_model=str(param.model))
-
         try:
-            async for event in await stream:
-                log_debug(
-                    event.model_dump_json(exclude_none=True),
-                    style="blue",
-                    debug_type=DebugType.LLM_STREAM,
-                )
-                if not state.response_id and event.id:
-                    state.set_response_id(event.id)
-                    yield model.StartItem(response_id=event.id)
-                if event.usage is not None:
-                    metadata_tracker.set_usage(convert_usage(event.usage, param.context_limit, param.max_tokens))
-                if event.model:
-                    metadata_tracker.set_model_name(event.model)
-                if provider := getattr(event, "provider", None):
-                    metadata_tracker.set_provider(str(provider))
-
-                if len(event.choices) == 0:
-                    continue
-
-                # Support Moonshot Kimi K2's usage field in choice
-                if usage := getattr(event.choices[0], "usage", None):
-                    metadata_tracker.set_usage(
-                        convert_usage(
-                            openai.types.CompletionUsage.model_validate(usage),
-                            param.context_limit,
-                            param.max_tokens,
-                        )
-                    )
-
-                delta = event.choices[0].delta
-
-                # Reasoning
-                if (
-                    reasoning_content := getattr(delta, "reasoning_content", None)
-                    or getattr(delta, "reasoning", None)
-                    or ""
-                ):
-                    metadata_tracker.record_token()
-                    state.stage = "reasoning"
-                    state.accumulated_reasoning.append(reasoning_content)
-                    yield model.ReasoningTextDelta(
-                        content=reasoning_content,
-                        response_id=state.response_id,
-                    )
-
-                # Assistant
-                if delta.content and (
-                    state.stage == "assistant" or delta.content.strip()
-                ):  # Process all content in assistant stage, filter empty content in reasoning stage
-                    metadata_tracker.record_token()
-                    if state.stage == "reasoning":
-                        for item in state.flush_reasoning():
-                            yield item
-                    elif state.stage == "tool":
-                        for item in state.flush_tool_calls():
-                            yield item
-                    state.stage = "assistant"
-                    state.accumulated_content.append(delta.content)
-                    yield model.AssistantMessageDelta(
-                        content=delta.content,
-                        response_id=state.response_id,
-                    )
-
-                # Tool
-                if delta.tool_calls and len(delta.tool_calls) > 0:
-                    metadata_tracker.record_token()
-                    if state.stage == "reasoning":
-                        for item in state.flush_reasoning():
-                            yield item
-                    elif state.stage == "assistant":
-                        for item in state.flush_assistant():
-                            yield item
-                    state.stage = "tool"
-                    # Emit ToolCallStartItem for new tool calls
-                    for tc in delta.tool_calls:
-                        if tc.index not in state.emitted_tool_start_indices and tc.function and tc.function.name:
-                            state.emitted_tool_start_indices.add(tc.index)
-                            yield model.ToolCallStartItem(
-                                response_id=state.response_id,
-                                call_id=tc.id or "",
-                                name=tc.function.name,
-                            )
-                    state.accumulated_tool_calls.add(delta.tool_calls)
+            stream = await self.client.chat.completions.create(
+                **payload,
+                extra_body=extra_body,
+                extra_headers=extra_headers,
+            )
         except (openai.OpenAIError, httpx.HTTPError) as e:
             yield model.StreamErrorItem(error=f"{e.__class__.__name__} {e!s}")
+            yield metadata_tracker.finalize()
+            return
 
-        # Finalize
-        flushed_items = state.flush_all()
-        if flushed_items:
-            metadata_tracker.record_token()
-        for item in flushed_items:
-            yield item
+        reasoning_handler = DefaultReasoningHandler(
+            param_model=str(param.model),
+            response_id=None,
+        )
+
+        def on_event(event: Any) -> None:
+            log_debug(
+                event.model_dump_json(exclude_none=True),
+                style="blue",
+                debug_type=DebugType.LLM_STREAM,
+            )
 
-        metadata_tracker.set_response_id(state.response_id)
-        yield metadata_tracker.finalize()
+        async for item in parse_chat_completions_stream(
+            stream,
+            param=param,
+            metadata_tracker=metadata_tracker,
+            reasoning_handler=reasoning_handler,
+            on_event=on_event,
+        ):
+            yield item

klaude_code/llm/openai_compatible/stream.py

@@ -0,0 +1,272 @@
+"""Shared stream processing utilities for Chat Completions streaming.
+
+This module provides reusable primitives for OpenAI-compatible providers:
+
+- ``StreamStateManager``: accumulates assistant content and tool calls.
+- ``ReasoningHandlerABC``: provider-specific reasoning extraction + buffering.
+- ``parse_chat_completions_stream``: shared stream loop that emits ConversationItems.
+
+OpenRouter uses the same OpenAI Chat Completions API surface but differs in
+how reasoning is represented (``reasoning_details`` vs ``reasoning_content``).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator, Callable
+from dataclasses import dataclass
+from typing import Any, Literal, cast
+
+import httpx
+import openai
+import openai.types
+from openai import AsyncStream
+from openai.types.chat.chat_completion_chunk import ChatCompletionChunk
+
+from klaude_code.llm.openai_compatible.tool_call_accumulator import BasicToolCallAccumulator, ToolCallAccumulatorABC
+from klaude_code.llm.usage import MetadataTracker, convert_usage
+from klaude_code.protocol import llm_param, model
+
+StreamStage = Literal["waiting", "reasoning", "assistant", "tool"]
+
+
+class StreamStateManager:
+    """Manages streaming state and provides flush operations for accumulated content.
+
+    This class encapsulates the common state management logic used by both
+    OpenAI-compatible and OpenRouter clients, reducing code duplication.
+    """
+
+    def __init__(
+        self,
+        param_model: str,
+        response_id: str | None = None,
+        reasoning_flusher: Callable[[], list[model.ConversationItem]] | None = None,
+    ):
+        self.param_model = param_model
+        self.response_id = response_id
+        self.stage: StreamStage = "waiting"
+        self.accumulated_reasoning: list[str] = []
+        self.accumulated_content: list[str] = []
+        self.accumulated_tool_calls: ToolCallAccumulatorABC = BasicToolCallAccumulator()
+        self.emitted_tool_start_indices: set[int] = set()
+        self._reasoning_flusher = reasoning_flusher
+
+    def set_response_id(self, response_id: str) -> None:
+        """Set the response ID once received from the stream."""
+        self.response_id = response_id
+        self.accumulated_tool_calls.response_id = response_id  # pyright: ignore[reportAttributeAccessIssue]
+
+    def flush_reasoning(self) -> list[model.ConversationItem]:
+        """Flush accumulated reasoning content and return items."""
+        if self._reasoning_flusher is not None:
+            return self._reasoning_flusher()
+        if not self.accumulated_reasoning:
+            return []
+        item = model.ReasoningTextItem(
+            content="".join(self.accumulated_reasoning),
+            response_id=self.response_id,
+            model=self.param_model,
+        )
+        self.accumulated_reasoning = []
+        return [item]
+
+    def flush_assistant(self) -> list[model.ConversationItem]:
+        """Flush accumulated assistant content and return items."""
+        if not self.accumulated_content:
+            return []
+        item = model.AssistantMessageItem(
+            content="".join(self.accumulated_content),
+            response_id=self.response_id,
+        )
+        self.accumulated_content = []
+        return [item]
+
+    def flush_tool_calls(self) -> list[model.ToolCallItem]:
+        """Flush accumulated tool calls and return items."""
+        items: list[model.ToolCallItem] = self.accumulated_tool_calls.get()
+        if items:
+            self.accumulated_tool_calls.chunks_by_step = []  # pyright: ignore[reportAttributeAccessIssue]
+        return items
+
+    def flush_all(self) -> list[model.ConversationItem]:
+        """Flush all accumulated content in order: reasoning, assistant, tool calls."""
+        items: list[model.ConversationItem] = []
+        items.extend(self.flush_reasoning())
+        items.extend(self.flush_assistant())
+        if self.stage == "tool":
+            items.extend(self.flush_tool_calls())
+        return items
+
+
+@dataclass(slots=True)
+class ReasoningDeltaResult:
+    """Result of processing a single provider delta for reasoning signals."""
+
+    handled: bool
+    outputs: list[str | model.ConversationItem]
+
+
+class ReasoningHandlerABC(ABC):
+    """Provider-specific reasoning handler for Chat Completions streaming."""
+
+    @abstractmethod
+    def set_response_id(self, response_id: str | None) -> None:
+        """Update the response identifier used for emitted items."""
+
+    @abstractmethod
+    def on_delta(self, delta: object) -> ReasoningDeltaResult:
+        """Process a single delta and return ordered reasoning outputs."""
+
+    @abstractmethod
+    def flush(self) -> list[model.ConversationItem]:
+        """Flush buffered reasoning content (usually at stage transition/finalize)."""
+
+
+class DefaultReasoningHandler(ReasoningHandlerABC):
+    """Handles OpenAI-compatible reasoning fields (reasoning_content / reasoning)."""
+
+    def __init__(
+        self,
+        *,
+        param_model: str,
+        response_id: str | None,
+    ) -> None:
+        self._param_model = param_model
+        self._response_id = response_id
+        self._accumulated: list[str] = []
+
+    def set_response_id(self, response_id: str | None) -> None:
+        self._response_id = response_id
+
+    def on_delta(self, delta: object) -> ReasoningDeltaResult:
+        reasoning_content = getattr(delta, "reasoning_content", None) or getattr(delta, "reasoning", None) or ""
+        if not reasoning_content:
+            return ReasoningDeltaResult(handled=False, outputs=[])
+        text = str(reasoning_content)
+        self._accumulated.append(text)
+        return ReasoningDeltaResult(handled=True, outputs=[text])
+
+    def flush(self) -> list[model.ConversationItem]:
+        if not self._accumulated:
+            return []
+        item = model.ReasoningTextItem(
+            content="".join(self._accumulated),
+            response_id=self._response_id,
+            model=self._param_model,
+        )
+        self._accumulated = []
+        return [item]
+
+
+async def parse_chat_completions_stream(
+    stream: AsyncStream[ChatCompletionChunk],
+    *,
+    param: llm_param.LLMCallParameter,
+    metadata_tracker: MetadataTracker,
+    reasoning_handler: ReasoningHandlerABC,
+    on_event: Callable[[object], None] | None = None,
+) -> AsyncGenerator[model.ConversationItem]:
+    """Parse OpenAI Chat Completions stream into ConversationItems.
+
+    This is shared by OpenAI-compatible and OpenRouter clients.
+    """
+
+    state = StreamStateManager(
+        param_model=str(param.model),
+        reasoning_flusher=reasoning_handler.flush,
+    )
+
+    try:
+        async for event in stream:
+            if on_event is not None:
+                on_event(event)
+
+            if not state.response_id and (event_id := getattr(event, "id", None)):
+                state.set_response_id(str(event_id))
+                reasoning_handler.set_response_id(str(event_id))
+                yield model.StartItem(response_id=str(event_id))
+
+            if (event_usage := getattr(event, "usage", None)) is not None:
+                metadata_tracker.set_usage(convert_usage(event_usage, param.context_limit, param.max_tokens))
+            if event_model := getattr(event, "model", None):
+                metadata_tracker.set_model_name(str(event_model))
+            if provider := getattr(event, "provider", None):
+                metadata_tracker.set_provider(str(provider))
+
+            choices = cast(Any, getattr(event, "choices", None))
+            if not choices:
+                continue
+
+            # Support Moonshot Kimi K2's usage field in choice
+            choice0 = choices[0]
+            if choice_usage := getattr(choice0, "usage", None):
+                try:
+                    usage = openai.types.CompletionUsage.model_validate(choice_usage)
+                    metadata_tracker.set_usage(convert_usage(usage, param.context_limit, param.max_tokens))
+                except Exception:
+                    pass
+
+            delta = cast(Any, getattr(choice0, "delta", None))
+            if delta is None:
+                continue
+
+            # Reasoning
+            reasoning_result = reasoning_handler.on_delta(delta)
+            if reasoning_result.handled:
+                state.stage = "reasoning"
+                for output in reasoning_result.outputs:
+                    if isinstance(output, str):
+                        if not output:
+                            continue
+                        metadata_tracker.record_token()
+                        yield model.ReasoningTextDelta(content=output, response_id=state.response_id)
+                    else:
+                        yield output
+
+            # Assistant
+            if (content := getattr(delta, "content", None)) and (state.stage == "assistant" or str(content).strip()):
+                metadata_tracker.record_token()
+                if state.stage == "reasoning":
+                    for item in state.flush_reasoning():
+                        yield item
+                elif state.stage == "tool":
+                    for item in state.flush_tool_calls():
+                        yield item
+                state.stage = "assistant"
+                state.accumulated_content.append(str(content))
+                yield model.AssistantMessageDelta(
+                    content=str(content),
+                    response_id=state.response_id,
+                )
+
+            # Tool
+            if (tool_calls := getattr(delta, "tool_calls", None)) and len(tool_calls) > 0:
+                metadata_tracker.record_token()
+                if state.stage == "reasoning":
+                    for item in state.flush_reasoning():
+                        yield item
+                elif state.stage == "assistant":
+                    for item in state.flush_assistant():
+                        yield item
+                state.stage = "tool"
+                for tc in tool_calls:
+                    if tc.index not in state.emitted_tool_start_indices and tc.function and tc.function.name:
+                        state.emitted_tool_start_indices.add(tc.index)
+                        yield model.ToolCallStartItem(
+                            response_id=state.response_id,
+                            call_id=tc.id or "",
+                            name=tc.function.name,
+                        )
+                state.accumulated_tool_calls.add(tool_calls)
+    except (openai.OpenAIError, httpx.HTTPError) as e:
+        yield model.StreamErrorItem(error=f"{e.__class__.__name__} {e!s}")
+
+    flushed_items = state.flush_all()
+    if flushed_items:
+        metadata_tracker.record_token()
+    for item in flushed_items:
+        yield item
+
+    metadata_tracker.set_response_id(state.response_id)
+    yield metadata_tracker.finalize()