klaude-code 1.2.1__py3-none-any.whl → 1.2.3__py3-none-any.whl

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/events.py

@@ -2,7 +2,7 @@ from typing import Literal
 
 from pydantic import BaseModel
 
-from klaude_code.protocol import llm_parameter, model
+from klaude_code.protocol import llm_param, model
 
 """
 Event is how Agent Executor and UI Display communicate.
@@ -103,11 +103,12 @@ class ResponseMetadataEvent(BaseModel):
 class UserMessageEvent(BaseModel):
     session_id: str
     content: str
+    images: list[model.ImageURLPart] | None = None
 
 
 class WelcomeEvent(BaseModel):
     work_dir: str
-    llm_config: llm_parameter.LLMConfigParameter
+    llm_config: llm_param.LLMConfigParameter
 
 
 class InterruptEvent(BaseModel):

klaude_code/protocol/{llm_parameter.py → llm_param.py}

@@ -4,7 +4,6 @@ from typing import Any, Literal
 from pydantic import BaseModel
 from pydantic.json_schema import JsonSchemaValue
 
-from klaude_code.const import DEFAULT_ANTHROPIC_THINKING_BUDGET_TOKENS, DEFAULT_MAX_TOKENS, DEFAULT_TEMPERATURE
 from klaude_code.protocol.model import ConversationItem
 
 
@@ -36,6 +35,15 @@ class Thinking(BaseModel):
     budget_tokens: int | None = None
 
 
+class Cost(BaseModel):
+    """Cost configuration per million tokens (USD)."""
+
+    input: float  # Input token price per million tokens
+    output: float  # Output token price per million tokens
+    cache_read: float = 0.0  # Cache read price per million tokens
+    cache_write: float = 0.0  # Cache write price per million tokens (ignored in calculation for now)
+
+
 class OpenRouterProviderRouting(BaseModel):
     """
     https://openrouter.ai/docs/features/provider-routing#json-schema-for-provider-preferences
@@ -100,6 +108,9 @@ class LLMConfigModelParameter(BaseModel):
     # OpenRouter Provider Routing Preferences
     provider_routing: OpenRouterProviderRouting | None = None
 
+    # Cost configuration (USD per million tokens)
+    cost: Cost | None = None
+
 
 class LLMConfigParameter(LLMConfigProviderParameter, LLMConfigModelParameter):
     """
@@ -134,34 +145,3 @@ class LLMCallParameter(LLMConfigModelParameter):
     previous_response_id: str | None = None
 
     session_id: str | None = None
-
-
-def apply_config_defaults(param: LLMCallParameter, config: LLMConfigParameter) -> LLMCallParameter:
-    if param.model is None:
-        param.model = config.model
-    if param.temperature is None:
-        param.temperature = config.temperature
-    if param.max_tokens is None:
-        param.max_tokens = config.max_tokens
-    if param.context_limit is None:
-        param.context_limit = config.context_limit
-    if param.verbosity is None:
-        param.verbosity = config.verbosity
-    if param.thinking is None:
-        param.thinking = config.thinking
-    if param.provider_routing is None:
-        param.provider_routing = config.provider_routing
-
-    if param.model is None:
-        raise ValueError("Model is required")
-    if param.max_tokens is None:
-        param.max_tokens = DEFAULT_MAX_TOKENS
-    if param.temperature is None:
-        param.temperature = DEFAULT_TEMPERATURE
-    if param.thinking is not None and param.thinking.type == "enabled" and param.thinking.budget_tokens is None:
-        param.thinking.budget_tokens = DEFAULT_ANTHROPIC_THINKING_BUDGET_TOKENS
-
-    if param.model and "gpt-5" in param.model:
-        param.temperature = 1.0  # Required for GPT-5
-
-    return param

klaude_code/protocol/model.py

@@ -1,7 +1,8 @@
+from datetime import datetime
 from enum import Enum
 from typing import Literal
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from klaude_code.protocol.commands import CommandName
 from klaude_code.protocol.tools import SubAgentType
@@ -20,6 +21,12 @@ class Usage(BaseModel):
     throughput_tps: float | None = None
     first_token_latency_ms: float | None = None
 
+    # Cost in USD (calculated from token counts and cost config)
+    input_cost: float | None = None  # Cost for non-cached input tokens
+    output_cost: float | None = None  # Cost for output tokens (including reasoning)
+    cache_read_cost: float | None = None  # Cost for cached tokens
+    total_cost: float | None = None  # Total cost (input + output + cache_read)
+
 
 class TodoItem(BaseModel):
     content: str
@@ -113,16 +120,18 @@ When adding a new item, please also modify the following:
 
 class StartItem(BaseModel):
     response_id: str
+    created_at: datetime = Field(default_factory=datetime.now)
 
 
 class InterruptItem(BaseModel):
-    pass
+    created_at: datetime = Field(default_factory=datetime.now)
 
 
 class SystemMessageItem(BaseModel):
     id: str | None = None
     role: RoleType = "system"
     content: str | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
 
 
 class DeveloperMessageItem(BaseModel):
@@ -130,6 +139,7 @@ class DeveloperMessageItem(BaseModel):
     role: RoleType = "developer"
     content: str | None = None  # For LLM input
     images: list["ImageURLPart"] | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
 
     # Special fields for reminders UI
     memory_paths: list[str] | None = None
@@ -137,7 +147,7 @@ class DeveloperMessageItem(BaseModel):
     todo_use: bool | None = None
     at_files: list[AtPatternParseResult] | None = None
     command_output: CommandOutput | None = None
-    clipboard_images: list[str] | None = None
+    user_image_count: int | None = None
 
 
 class ImageURLPart(BaseModel):
@@ -148,11 +158,23 @@ class ImageURLPart(BaseModel):
     image_url: ImageURL
 
 
+class UserInputPayload(BaseModel):
+    """Structured payload for user input containing text and optional images.
+
+    This is the unified data structure for user input across the entire
+    UI -> CLI -> Executor -> Agent -> Task chain.
+    """
+
+    text: str
+    images: list["ImageURLPart"] | None = None
+
+
 class UserMessageItem(BaseModel):
     id: str | None = None
     role: RoleType = "user"
     content: str | None = None
     images: list[ImageURLPart] | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
 
 
 class AssistantMessageItem(BaseModel):
@@ -160,6 +182,7 @@ class AssistantMessageItem(BaseModel):
     role: RoleType = "assistant"
     content: str | None = None
     response_id: str | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
 
 
 class ReasoningTextItem(BaseModel):
@@ -167,6 +190,7 @@ class ReasoningTextItem(BaseModel):
     response_id: str | None = None
     content: str
     model: str | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
 
 
 class ReasoningEncryptedItem(BaseModel):
@@ -175,6 +199,20 @@ class ReasoningEncryptedItem(BaseModel):
     encrypted_content: str  # OpenAI encrypted content or Anthropic thinking signature
     format: str | None = None
     model: str | None
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
+class ToolCallStartItem(BaseModel):
+    """Transient streaming signal when LLM starts a tool call.
+
+    This is NOT persisted to conversation history. Used only for
+    real-time UI feedback (e.g., "Calling Bash ...").
+    """
+
+    response_id: str | None = None
+    call_id: str
+    name: str
+    created_at: datetime = Field(default_factory=datetime.now)
 
 
 class ToolCallItem(BaseModel):
@@ -183,6 +221,7 @@ class ToolCallItem(BaseModel):
     call_id: str
     name: str
     arguments: str
+    created_at: datetime = Field(default_factory=datetime.now)
 
 
 class ToolResultItem(BaseModel):
@@ -193,15 +232,18 @@ class ToolResultItem(BaseModel):
     ui_extra: ToolResultUIExtra | None = None  # Extra data for UI display, e.g. diff render
     images: list[ImageURLPart] | None = None
     side_effects: list[ToolSideEffect] | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
 
 
 class AssistantMessageDelta(BaseModel):
     response_id: str | None = None
     content: str
+    created_at: datetime = Field(default_factory=datetime.now)
 
 
 class StreamErrorItem(BaseModel):
     error: str
+    created_at: datetime = Field(default_factory=datetime.now)
 
 
 class ResponseMetadataItem(BaseModel):
@@ -212,6 +254,7 @@ class ResponseMetadataItem(BaseModel):
     task_duration_s: float | None = None
     status: str | None = None
     error_reason: str | None = None
+    created_at: datetime = Field(default_factory=datetime.now)
 
 
 MessageItem = (
@@ -228,7 +271,9 @@ MessageItem = (
 
 StreamItem = AssistantMessageDelta
 
-ConversationItem = StartItem | InterruptItem | StreamErrorItem | StreamItem | MessageItem | ResponseMetadataItem
+ConversationItem = (
+    StartItem | InterruptItem | StreamErrorItem | StreamItem | MessageItem | ResponseMetadataItem | ToolCallStartItem
+)
 
 
 def todo_list_str(todos: list[TodoItem]) -> str:

klaude_code/protocol/op.py

@@ -5,15 +5,18 @@ This module defines the operation types and submission structure
 that the executor uses to handle different types of requests.
 """
 
-from abc import ABC, abstractmethod
+from __future__ import annotations
+
 from enum import Enum
 from typing import TYPE_CHECKING
 from uuid import uuid4
 
 from pydantic import BaseModel, Field
 
+from klaude_code.protocol.model import UserInputPayload
+
 if TYPE_CHECKING:
-    from klaude_code.core.executor import ExecutorContext
+    from klaude_code.protocol.op_handler import OperationHandler
 
 
 class OperationType(Enum):
@@ -25,28 +28,27 @@ class OperationType(Enum):
     END = "end"
 
 
-class Operation(BaseModel, ABC):
+class Operation(BaseModel):
     """Base class for all operations that can be submitted to the executor."""
 
     type: OperationType
     id: str = Field(default_factory=lambda: uuid4().hex)
 
-    @abstractmethod
-    async def execute(self, context: "ExecutorContext") -> None:
-        """Execute this operation within the given executor context."""
-        pass
+    async def execute(self, handler: OperationHandler) -> None:
+        """Execute this operation using the given handler."""
+        raise NotImplementedError("Subclasses must implement execute()")
 
 
 class UserInputOperation(Operation):
-    """Operation for handling user text input that should be processed by an agent."""
+    """Operation for handling user input (text and optional images) that should be processed by an agent."""
 
     type: OperationType = OperationType.USER_INPUT
-    content: str
+    input: UserInputPayload
     session_id: str | None = None
 
-    async def execute(self, context: "ExecutorContext") -> None:
+    async def execute(self, handler: OperationHandler) -> None:
         """Execute user input by running it through an agent."""
-        await context.handle_user_input(self)
+        await handler.handle_user_input(self)
 
 
 class InterruptOperation(Operation):
@@ -55,9 +57,9 @@ class InterruptOperation(Operation):
     type: OperationType = OperationType.INTERRUPT
     target_session_id: str | None = None  # If None, interrupt all sessions
 
-    async def execute(self, context: "ExecutorContext") -> None:
+    async def execute(self, handler: OperationHandler) -> None:
         """Execute interrupt by cancelling active tasks."""
-        await context.handle_interrupt(self)
+        await handler.handle_interrupt(self)
 
 
 class InitAgentOperation(Operation):
@@ -66,8 +68,8 @@ class InitAgentOperation(Operation):
     type: OperationType = OperationType.INIT_AGENT
     session_id: str | None = None
 
-    async def execute(self, context: "ExecutorContext") -> None:
-        await context.handle_init_agent(self)
+    async def execute(self, handler: OperationHandler) -> None:
+        await handler.handle_init_agent(self)
 
 
 class EndOperation(Operation):
@@ -75,7 +77,7 @@ class EndOperation(Operation):
 
     type: OperationType = OperationType.END
 
-    async def execute(self, context: "ExecutorContext") -> None:
+    async def execute(self, handler: OperationHandler) -> None:
         """Execute end operation - this is a no-op, just signals the executor to stop."""
         pass
 

klaude_code/protocol/op_handler.py

@@ -0,0 +1,28 @@
+"""
+Operation handler protocol for the executor system.
+
+This module defines the protocol that operation handlers must implement.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from klaude_code.protocol.op import InitAgentOperation, InterruptOperation, UserInputOperation
+
+
+class OperationHandler(Protocol):
+    """Protocol defining the interface for handling operations."""
+
+    async def handle_user_input(self, operation: UserInputOperation) -> None:
+        """Handle a user input operation."""
+        ...
+
+    async def handle_interrupt(self, operation: InterruptOperation) -> None:
+        """Handle an interrupt operation."""
+        ...
+
+    async def handle_init_agent(self, operation: InitAgentOperation) -> None:
+        """Handle an init agent operation."""
+        ...

klaude_code/{core → protocol}/sub_agent.py

@@ -44,6 +44,9 @@ class SubAgentProfile:
     tool_set: tuple[str, ...] = ()  # Tools available to this sub agent
     prompt_builder: PromptBuilder = _default_prompt_builder  # Builds the sub agent prompt from tool arguments
 
+    # UI display
+    active_form: str = ""  # Active form for spinner status (e.g., "Tasking", "Exploring")
+
     # Availability
     enabled_by_default: bool = True
     show_in_main_agent: bool = True
@@ -141,6 +144,7 @@ register_sub_agent(
         description=TASK_DESCRIPTION,
         parameters=TASK_PARAMETERS,
         tool_set=(tools.BASH, tools.READ, tools.EDIT, tools.WRITE),
+        active_form="Tasking",
     )
 )
 
@@ -228,6 +232,7 @@ register_sub_agent(
         parameters=ORACLE_PARAMETERS,
         tool_set=(tools.READ, tools.BASH),
         prompt_builder=_oracle_prompt_builder,
+        active_form="Consulting Oracle",
         target_model_filter=lambda model: ("gpt-5" not in model) and ("gemini-3" not in model),
     )
 )
@@ -279,6 +284,7 @@ register_sub_agent(
         parameters=EXPLORE_PARAMETERS,
         tool_set=(tools.BASH, tools.READ),
         prompt_builder=_explore_prompt_builder,
+        active_form="Exploring",
     )
 )
 
@@ -337,5 +343,6 @@ register_sub_agent(
         parameters=WEB_FETCH_AGENT_PARAMETERS,
         tool_set=(tools.BASH, tools.READ, tools.WEB_FETCH),
         prompt_builder=_web_fetch_prompt_builder,
+        active_form="Fetching Web",
     )
 )