klaude-code 1.2.6__py3-none-any.whl

klaude_code/llm/responses/client.py

@@ -0,0 +1,216 @@
+import json
+import time
+from collections.abc import AsyncGenerator
+from typing import override
+
+import httpx
+from openai import AsyncAzureOpenAI, AsyncOpenAI, RateLimitError
+from openai.types import responses
+
+from klaude_code.llm.client import LLMClientABC, call_with_logged_payload
+from klaude_code.llm.input_common import apply_config_defaults
+from klaude_code.llm.registry import register
+from klaude_code.llm.responses.input import convert_history_to_input, convert_tool_schema
+from klaude_code.llm.usage import calculate_cost
+from klaude_code.protocol import llm_param, model
+from klaude_code.trace import DebugType, log_debug
+
+
+@register(llm_param.LLMClientProtocol.RESPONSES)
+class ResponsesClient(LLMClientABC):
+    def __init__(self, config: llm_param.LLMConfigParameter):
+        super().__init__(config)
+        if config.is_azure:
+            if not config.base_url:
+                raise ValueError("Azure endpoint is required")
+            client = AsyncAzureOpenAI(
+                api_key=config.api_key,
+                azure_endpoint=str(config.base_url),
+                api_version=config.azure_api_version,
+                timeout=httpx.Timeout(300.0, connect=15.0, read=285.0),
+            )
+        else:
+            client = AsyncOpenAI(
+                api_key=config.api_key,
+                base_url=config.base_url,
+                timeout=httpx.Timeout(300.0, connect=15.0, read=285.0),
+            )
+        self.client: AsyncAzureOpenAI | AsyncOpenAI = client
+
+    @classmethod
+    @override
+    def create(cls, config: llm_param.LLMConfigParameter) -> "LLMClientABC":
+        return cls(config)
+
+    @override
+    async def call(self, param: llm_param.LLMCallParameter) -> AsyncGenerator[model.ConversationItem, None]:
+        param = apply_config_defaults(param, self.get_llm_config())
+
+        request_start_time = time.time()
+        first_token_time: float | None = None
+        last_token_time: float | None = None
+        response_id: str | None = None
+
+        inputs = convert_history_to_input(param.input, param.model)
+        tools = convert_tool_schema(param.tools)
+
+        parallel_tool_calls = True
+
+        stream = call_with_logged_payload(
+            self.client.responses.create,
+            model=str(param.model),
+            tool_choice="auto",
+            parallel_tool_calls=parallel_tool_calls,  # OpenAI's Codex is always False, we try to enable it here. It seems gpt-5-codex has bugs when parallel_tool_calls is True.
+            include=[
+                "reasoning.encrypted_content",
+            ],
+            store=param.store,
+            previous_response_id=param.previous_response_id,
+            stream=True,
+            temperature=param.temperature,
+            max_output_tokens=param.max_tokens,
+            input=inputs,
+            instructions=param.system,
+            tools=tools,
+            text={
+                "verbosity": param.verbosity,
+            },
+            reasoning={
+                "effort": param.thinking.reasoning_effort,
+                "summary": param.thinking.reasoning_summary,
+            }
+            if param.thinking and param.thinking.reasoning_effort
+            else None,
+            extra_headers={"extra": json.dumps({"session_id": param.session_id})},
+        )
+
+        try:
+            async for event in await stream:
+                log_debug(
+                    f"[{event.type}]",
+                    event.model_dump_json(exclude_none=True),
+                    style="blue",
+                    debug_type=DebugType.LLM_STREAM,
+                )
+                match event:
+                    case responses.ResponseCreatedEvent() as event:
+                        response_id = event.response.id
+                        yield model.StartItem(response_id=response_id)
+                    case responses.ResponseReasoningSummaryTextDoneEvent() as event:
+                        if event.text:
+                            yield model.ReasoningTextItem(
+                                content=event.text,
+                                response_id=response_id,
+                                model=str(param.model),
+                            )
+                    case responses.ResponseTextDeltaEvent() as event:
+                        if first_token_time is None:
+                            first_token_time = time.time()
+                        last_token_time = time.time()
+                        yield model.AssistantMessageDelta(content=event.delta, response_id=response_id)
+                    case responses.ResponseOutputItemAddedEvent() as event:
+                        if isinstance(event.item, responses.ResponseFunctionToolCall):
+                            yield model.ToolCallStartItem(
+                                response_id=response_id,
+                                call_id=event.item.call_id,
+                                name=event.item.name,
+                            )
+                    case responses.ResponseOutputItemDoneEvent() as event:
+                        match event.item:
+                            case responses.ResponseReasoningItem() as item:
+                                if item.encrypted_content:
+                                    yield model.ReasoningEncryptedItem(
+                                        id=item.id,
+                                        encrypted_content=item.encrypted_content,
+                                        response_id=response_id,
+                                        model=str(param.model),
+                                    )
+                            case responses.ResponseOutputMessage() as item:
+                                yield model.AssistantMessageItem(
+                                    content="\n".join(
+                                        [
+                                            part.text
+                                            for part in item.content
+                                            if isinstance(part, responses.ResponseOutputText)
+                                        ]
+                                    ),
+                                    id=item.id,
+                                    response_id=response_id,
+                                )
+                            case responses.ResponseFunctionToolCall() as item:
+                                if first_token_time is None:
+                                    first_token_time = time.time()
+                                last_token_time = time.time()
+                                yield model.ToolCallItem(
+                                    name=item.name,
+                                    arguments=item.arguments.strip(),
+                                    call_id=item.call_id,
+                                    id=item.id,
+                                    response_id=response_id,
+                                )
+                            case _:
+                                pass
+                    case responses.ResponseCompletedEvent() as event:
+                        usage: model.Usage | None = None
+                        error_reason: str | None = None
+                        if event.response.incomplete_details is not None:
+                            error_reason = event.response.incomplete_details.reason
+                        if event.response.usage is not None:
+                            total_tokens = event.response.usage.total_tokens
+                            context_usage_percent = (
+                                (total_tokens / param.context_limit) * 100 if param.context_limit else None
+                            )
+
+                            throughput_tps: float | None = None
+                            first_token_latency_ms: float | None = None
+
+                            if first_token_time is not None:
+                                first_token_latency_ms = (first_token_time - request_start_time) * 1000
+
+                            if (
+                                first_token_time is not None
+                                and last_token_time is not None
+                                and event.response.usage.output_tokens > 0
+                            ):
+                                time_duration = last_token_time - first_token_time
+                                if time_duration >= 0.15:
+                                    throughput_tps = event.response.usage.output_tokens / time_duration
+
+                            usage = model.Usage(
+                                input_tokens=event.response.usage.input_tokens,
+                                cached_tokens=event.response.usage.input_tokens_details.cached_tokens,
+                                reasoning_tokens=event.response.usage.output_tokens_details.reasoning_tokens,
+                                output_tokens=event.response.usage.output_tokens,
+                                total_tokens=total_tokens,
+                                context_usage_percent=context_usage_percent,
+                                throughput_tps=throughput_tps,
+                                first_token_latency_ms=first_token_latency_ms,
+                            )
+                            calculate_cost(usage, self._config.cost)
+                        yield model.ResponseMetadataItem(
+                            usage=usage,
+                            response_id=response_id,
+                            model_name=str(param.model),
+                            status=event.response.status,
+                            error_reason=error_reason,
+                        )
+                        if event.response.status != "completed":
+                            error_message = f"LLM response finished with status '{event.response.status}'"
+                            if error_reason:
+                                error_message = f"{error_message}: {error_reason}"
+                            log_debug(
+                                "[LLM status warning]",
+                                error_message,
+                                style="red",
+                                debug_type=DebugType.LLM_STREAM,
+                            )
+                            yield model.StreamErrorItem(error=error_message)
+                    case _:
+                        log_debug(
+                            "[Unhandled stream event]",
+                            str(event),
+                            style="red",
+                            debug_type=DebugType.LLM_STREAM,
+                        )
+        except RateLimitError as e:
+            yield model.StreamErrorItem(error=f"{e.__class__.__name__} {str(e)}")

klaude_code/llm/responses/input.py

@@ -0,0 +1,167 @@
+# pyright: reportReturnType=false
+# pyright: reportArgumentType=false
+
+from typing import Any
+
+from openai.types import responses
+
+from klaude_code.protocol import llm_param, model
+
+
+def _build_user_content_parts(
+    user: model.UserMessageItem,
+) -> list[responses.ResponseInputContentParam]:
+    parts: list[responses.ResponseInputContentParam] = []
+    if user.content is not None:
+        parts.append({"type": "input_text", "text": user.content})
+    for image in user.images or []:
+        parts.append({"type": "input_image", "detail": "auto", "image_url": image.image_url.url})
+    if not parts:
+        parts.append({"type": "input_text", "text": ""})
+    return parts
+
+
+def _build_tool_result_item(tool: model.ToolResultItem) -> responses.ResponseInputItemParam:
+    content_parts: list[responses.ResponseInputContentParam] = []
+    text_output = tool.output or "<system-reminder>Tool ran without output or errors</system-reminder>"
+    if text_output:
+        content_parts.append({"type": "input_text", "text": text_output})
+    for image in tool.images or []:
+        content_parts.append({"type": "input_image", "detail": "auto", "image_url": image.image_url.url})
+
+    item: dict[str, Any] = {
+        "type": "function_call_output",
+        "call_id": tool.call_id,
+        "output": content_parts,
+    }
+    return item  # type: ignore[return-value]
+
+
+def convert_history_to_input(
+    history: list[model.ConversationItem],
+    model_name: str | None = None,
+) -> responses.ResponseInputParam:
+    """
+    Convert a list of conversation items to a list of response input params.
+
+    Args:
+        history: List of conversation items.
+        model_name: Model name. Used to verify that signatures are valid for the same model.
+    """
+    items: list[responses.ResponseInputItemParam] = []
+
+    pending_reasoning_text: str | None = None
+
+    for item in history:
+        match item:
+            case model.ReasoningTextItem() as item:
+                # For now, we only store the text. We wait for the encrypted item to output both.
+                # If no encrypted item follows (e.g. incomplete stream?), this text might be lost
+                # or we can choose to output it if the next item is NOT reasoning?
+                # For now, based on instructions, we pair them.
+                if model_name != item.model:
+                    continue
+                pending_reasoning_text = item.content
+
+            case model.ReasoningEncryptedItem() as item:
+                if item.encrypted_content and len(item.encrypted_content) > 0 and model_name == item.model:
+                    items.append(convert_reasoning_inputs(pending_reasoning_text, item))
+                # Reset pending text after consumption
+                pending_reasoning_text = None
+
+            case model.ToolCallItem() as t:
+                items.append(
+                    {
+                        "type": "function_call",
+                        "name": t.name,
+                        "arguments": t.arguments,
+                        "call_id": t.call_id,
+                        "id": t.id,
+                    }
+                )
+            case model.ToolResultItem() as t:
+                items.append(_build_tool_result_item(t))
+            case model.AssistantMessageItem() as a:
+                items.append(
+                    {
+                        "type": "message",
+                        "role": "assistant",
+                        "id": a.id,
+                        "content": [
+                            {
+                                "type": "output_text",
+                                "text": a.content,
+                            }
+                        ],
+                    }
+                )
+            case model.UserMessageItem() as u:
+                items.append(
+                    {
+                        "type": "message",
+                        "role": "user",
+                        "id": u.id,
+                        "content": _build_user_content_parts(u),
+                    }
+                )
+            case model.DeveloperMessageItem() as d:
+                dev_parts: list[responses.ResponseInputContentParam] = []
+                if d.content is not None:
+                    dev_parts.append({"type": "input_text", "text": d.content})
+                for image in d.images or []:
+                    dev_parts.append(
+                        {
+                            "type": "input_image",
+                            "detail": "auto",
+                            "image_url": image.image_url.url,
+                        }
+                    )
+                if not dev_parts:
+                    dev_parts.append({"type": "input_text", "text": ""})
+                items.append(
+                    {
+                        "type": "message",
+                        "role": "user",  # GPT-5 series do not support image in "developer" role, so we set it to "user"
+                        "id": d.id,
+                        "content": dev_parts,
+                    }
+                )
+            case _:
+                # Other items may be Metadata
+                continue
+
+    return items
+
+
+def convert_reasoning_inputs(
+    text_content: str | None, encrypted_item: model.ReasoningEncryptedItem
+) -> responses.ResponseInputItemParam:
+    result = {"type": "reasoning", "content": None}
+
+    result["summary"] = [
+        {
+            "type": "summary_text",
+            "text": text_content or "",
+        }
+    ]
+    if encrypted_item.encrypted_content:
+        result["encrypted_content"] = encrypted_item.encrypted_content
+    if encrypted_item.id is not None:
+        result["id"] = encrypted_item.id
+    return result
+
+
+def convert_tool_schema(
+    tools: list[llm_param.ToolSchema] | None,
+) -> list[responses.ToolParam]:
+    if tools is None:
+        return []
+    return [
+        {
+            "type": "function",
+            "name": tool.name,
+            "description": tool.description,
+            "parameters": tool.parameters,
+        }
+        for tool in tools
+    ]

klaude_code/llm/usage.py

@@ -0,0 +1,109 @@
+import time
+
+import openai.types
+
+from klaude_code.protocol import llm_param, model
+
+
+def calculate_cost(usage: model.Usage, cost_config: llm_param.Cost | None) -> None:
+    """Calculate and set cost fields on usage based on cost configuration.
+
+    Note: input_tokens includes cached_tokens, so we need to subtract cached_tokens
+    to get the actual non-cached input tokens for cost calculation.
+    """
+    if cost_config is None:
+        return
+
+    # Non-cached input tokens cost
+    non_cached_input = usage.input_tokens - usage.cached_tokens
+    usage.input_cost = (non_cached_input / 1_000_000) * cost_config.input
+
+    # Output tokens cost (includes reasoning tokens)
+    usage.output_cost = (usage.output_tokens / 1_000_000) * cost_config.output
+
+    # Cache read cost
+    usage.cache_read_cost = (usage.cached_tokens / 1_000_000) * cost_config.cache_read
+
+    # Total cost
+    usage.total_cost = usage.input_cost + usage.output_cost + usage.cache_read_cost
+
+
+class MetadataTracker:
+    """Tracks timing and metadata for LLM responses."""
+
+    def __init__(self, cost_config: llm_param.Cost | None = None) -> None:
+        self._request_start_time: float = time.time()
+        self._first_token_time: float | None = None
+        self._last_token_time: float | None = None
+        self._metadata_item = model.ResponseMetadataItem()
+        self._cost_config = cost_config
+
+    @property
+    def metadata_item(self) -> model.ResponseMetadataItem:
+        return self._metadata_item
+
+    @property
+    def first_token_time(self) -> float | None:
+        return self._first_token_time
+
+    @property
+    def last_token_time(self) -> float | None:
+        return self._last_token_time
+
+    def record_token(self) -> None:
+        """Record a token arrival, updating first/last token times."""
+        now = time.time()
+        if self._first_token_time is None:
+            self._first_token_time = now
+        self._last_token_time = now
+
+    def set_usage(self, usage: model.Usage) -> None:
+        """Set the usage information."""
+        self._metadata_item.usage = usage
+
+    def set_model_name(self, model_name: str) -> None:
+        """Set the model name."""
+        self._metadata_item.model_name = model_name
+
+    def set_provider(self, provider: str) -> None:
+        """Set the provider name."""
+        self._metadata_item.provider = provider
+
+    def set_response_id(self, response_id: str | None) -> None:
+        """Set the response ID."""
+        self._metadata_item.response_id = response_id
+
+    def finalize(self) -> model.ResponseMetadataItem:
+        """Finalize and return the metadata item with calculated performance metrics."""
+        if self._metadata_item.usage and self._first_token_time is not None:
+            self._metadata_item.usage.first_token_latency_ms = (
+                self._first_token_time - self._request_start_time
+            ) * 1000
+
+            if self._last_token_time is not None and self._metadata_item.usage.output_tokens > 0:
+                time_duration = self._last_token_time - self._first_token_time
+                if time_duration >= 0.15:
+                    self._metadata_item.usage.throughput_tps = self._metadata_item.usage.output_tokens / time_duration
+
+        # Calculate cost if config is available
+        if self._metadata_item.usage:
+            calculate_cost(self._metadata_item.usage, self._cost_config)
+
+        return self._metadata_item
+
+
+def convert_usage(usage: openai.types.CompletionUsage, context_limit: int | None = None) -> model.Usage:
+    """Convert OpenAI CompletionUsage to internal Usage model."""
+    total_tokens = usage.total_tokens
+    context_usage_percent = (total_tokens / context_limit) * 100 if context_limit else None
+    return model.Usage(
+        input_tokens=usage.prompt_tokens,
+        cached_tokens=(usage.prompt_tokens_details.cached_tokens if usage.prompt_tokens_details else 0) or 0,
+        reasoning_tokens=(usage.completion_tokens_details.reasoning_tokens if usage.completion_tokens_details else 0)
+        or 0,
+        output_tokens=usage.completion_tokens,
+        total_tokens=total_tokens,
+        context_usage_percent=context_usage_percent,
+        throughput_tps=None,
+        first_token_latency_ms=None,
+    )

klaude_code/protocol/__init__.py

@@ -0,0 +1,4 @@
+from klaude_code.protocol import commands as commands
+from klaude_code.protocol import events as events
+from klaude_code.protocol import model as model
+from klaude_code.protocol import op as op

klaude_code/protocol/commands.py

@@ -0,0 +1,21 @@
+from enum import Enum
+
+
+class CommandName(str, Enum):
+    INIT = "init"
+    DIFF = "diff"
+    HELP = "help"
+    MODEL = "model"
+    COMPACT = "compact"
+    REFRESH_TERMINAL = "refresh-terminal"
+    CLEAR = "clear"
+    TERMINAL_SETUP = "terminal-setup"
+    EXPORT = "export"
+    STATUS = "status"
+    # PLAN and DOC are dynamically registered now, but kept here if needed for reference
+    # or we can remove them if no code explicitly imports them.
+    # PLAN = "plan"
+    # DOC = "doc"
+
+    def __str__(self) -> str:
+        return self.value

klaude_code/protocol/events.py

@@ -0,0 +1,163 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+from klaude_code.protocol import llm_param, model
+
+"""
+Event is how Agent Executor and UI Display communicate.
+"""
+
+
+class EndEvent(BaseModel):
+    pass
+
+
+class ErrorEvent(BaseModel):
+    error_message: str
+    can_retry: bool = False
+
+
+class TaskStartEvent(BaseModel):
+    session_id: str
+    sub_agent_state: model.SubAgentState | None = None
+
+
+class TaskFinishEvent(BaseModel):
+    session_id: str
+    task_result: str
+
+
+class TurnStartEvent(BaseModel):
+    """For now, this event is used for UI to flush developer message buffer and print an empty line"""
+
+    session_id: str
+
+
+class TurnEndEvent(BaseModel):
+    session_id: str
+
+
+class TurnToolCallStartEvent(BaseModel):
+    """For UI changing status text"""
+
+    session_id: str
+    response_id: str | None = None
+    tool_call_id: str
+    tool_name: str
+    arguments: str
+
+
+class ThinkingEvent(BaseModel):
+    session_id: str
+    response_id: str | None = None
+    content: str
+
+
+class AssistantMessageDeltaEvent(BaseModel):
+    session_id: str
+    response_id: str | None = None
+    content: str
+
+
+class AssistantMessageEvent(BaseModel):
+    response_id: str | None = None
+    session_id: str
+    content: str
+
+
+class DeveloperMessageEvent(BaseModel):
+    """DeveloperMessages are reminders in user messages or tool results, see: core/reminders.py"""
+
+    session_id: str
+    item: model.DeveloperMessageItem
+
+
+class ToolCallEvent(BaseModel):
+    session_id: str
+    response_id: str | None = None
+    tool_call_id: str
+    tool_name: str
+    arguments: str
+    is_replay: bool = False
+
+
+class ToolResultEvent(BaseModel):
+    session_id: str
+    response_id: str | None = None
+    tool_call_id: str
+    tool_name: str
+    result: str
+    ui_extra: model.ToolResultUIExtra | None = None
+    status: Literal["success", "error"]
+    is_replay: bool = False
+
+
+class ResponseMetadataEvent(BaseModel):
+    """Showing model name, usage tokens, task duration, and turn count."""
+
+    session_id: str
+    metadata: model.ResponseMetadataItem
+
+
+class UserMessageEvent(BaseModel):
+    session_id: str
+    content: str
+    images: list[model.ImageURLPart] | None = None
+
+
+class WelcomeEvent(BaseModel):
+    work_dir: str
+    llm_config: llm_param.LLMConfigParameter
+
+
+class InterruptEvent(BaseModel):
+    session_id: str
+
+
+class TodoChangeEvent(BaseModel):
+    session_id: str
+    todos: list[model.TodoItem]
+
+
+HistoryItemEvent = (
+    ThinkingEvent
+    | TurnStartEvent  # This event is used for UI to print new empty line
+    | AssistantMessageEvent
+    | ToolCallEvent
+    | ToolResultEvent
+    | UserMessageEvent
+    | ResponseMetadataEvent
+    | InterruptEvent
+    | DeveloperMessageEvent
+)
+
+
+class ReplayHistoryEvent(BaseModel):
+    session_id: str
+    events: list[HistoryItemEvent]
+    updated_at: float
+    is_load: bool = True
+
+
+Event = (
+    TaskStartEvent
+    | TaskFinishEvent
+    | ThinkingEvent
+    | AssistantMessageDeltaEvent
+    | AssistantMessageEvent
+    | ToolCallEvent
+    | ToolResultEvent
+    | ResponseMetadataEvent
+    | ReplayHistoryEvent
+    | ErrorEvent
+    | EndEvent
+    | WelcomeEvent
+    | UserMessageEvent
+    | InterruptEvent
+    | DeveloperMessageEvent
+    | TodoChangeEvent
+    | TurnStartEvent
+    | TurnEndEvent
+    | TurnToolCallStartEvent
+)