klaude-code 1.2.8__py3-none-any.whl → 1.2.10__py3-none-any.whl

klaude_code/llm/responses/client.py

@@ -1,5 +1,4 @@
 import json
-import time
 from collections.abc import AsyncGenerator
 from typing import TYPE_CHECKING, override
 
@@ -12,7 +11,7 @@ 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.llm.usage import MetadataTracker, convert_responses_usage
 from klaude_code.protocol import llm_param, model
 from klaude_code.trace import DebugType, log_debug
 
@@ -24,12 +23,9 @@ if TYPE_CHECKING:
 async def parse_responses_stream(
     stream: "AsyncStream[ResponseStreamEvent]",
     param: llm_param.LLMCallParameter,
-    cost_config: llm_param.Cost | None,
-    request_start_time: float,
+    metadata_tracker: MetadataTracker,
 ) -> AsyncGenerator[model.ConversationItem, None]:
     """Parse OpenAI Responses API stream events into ConversationItems."""
-    first_token_time: float | None = None
-    last_token_time: float | None = None
     response_id: str | None = None
 
     try:
@@ -52,9 +48,7 @@ async def parse_responses_stream(
                             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()
+                    metadata_tracker.record_token()
                     yield model.AssistantMessageDelta(content=event.delta, response_id=response_id)
                 case responses.ResponseOutputItemAddedEvent() as event:
                     if isinstance(event.item, responses.ResponseFunctionToolCall):
@@ -86,9 +80,7 @@ async def parse_responses_stream(
                                 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()
+                            metadata_tracker.record_token()
                             yield model.ToolCallItem(
                                 name=item.name,
                                 arguments=item.arguments.strip(),
@@ -99,47 +91,23 @@ async def parse_responses_stream(
                         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(
+                        usage = convert_responses_usage(
                             input_tokens=event.response.usage.input_tokens,
+                            output_tokens=event.response.usage.output_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,
+                            total_tokens=event.response.usage.total_tokens,
+                            context_limit=param.context_limit,
+                            max_tokens=param.max_tokens,
                         )
-                        calculate_cost(usage, cost_config)
-                    yield model.ResponseMetadataItem(
-                        usage=usage,
-                        response_id=response_id,
-                        model_name=str(param.model),
-                    )
+                        metadata_tracker.set_usage(usage)
+                    metadata_tracker.set_model_name(str(param.model))
+                    metadata_tracker.set_response_id(response_id)
+                    yield metadata_tracker.finalize()
                     if event.response.status != "completed":
                         error_message = f"LLM response finished with status '{event.response.status}'"
                         if error_reason:
@@ -192,7 +160,7 @@ class ResponsesClient(LLMClientABC):
     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()
+        metadata_tracker = MetadataTracker(cost_config=self.get_llm_config().cost)
 
         inputs = convert_history_to_input(param.input, param.model)
         tools = convert_tool_schema(param.tools)
@@ -224,11 +192,11 @@ class ResponsesClient(LLMClientABC):
                 }
                 if param.thinking and param.thinking.reasoning_effort
                 else None,
-                extra_headers={"extra": json.dumps({"session_id": param.session_id})},
+                extra_headers={"extra": json.dumps({"session_id": param.session_id}, sort_keys=True)},
             )
         except (openai.OpenAIError, httpx.HTTPError) as e:
             yield model.StreamErrorItem(error=f"{e.__class__.__name__} {str(e)}")
             return
 
-        async for item in parse_responses_stream(stream, param, self._config.cost, request_start_time):
+        async for item in parse_responses_stream(stream, param, metadata_tracker):
             yield item

klaude_code/llm/responses/input.py

@@ -34,7 +34,7 @@ def _build_tool_result_item(tool: model.ToolResultItem) -> responses.ResponseInp
         "call_id": tool.call_id,
         "output": content_parts,
     }
-    return item  # type: ignore[return-value]
+    return item
 
 
 def convert_history_to_input(

klaude_code/llm/usage.py

@@ -27,9 +27,6 @@ def calculate_cost(usage: model.Usage, cost_config: llm_param.Cost | None) -> No
     # 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."""
@@ -95,18 +92,71 @@ class MetadataTracker:
         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
+def convert_usage(
+    usage: openai.types.CompletionUsage,
+    context_limit: int | None = None,
+    max_tokens: int | None = None,
+) -> model.Usage:
+    """Convert OpenAI CompletionUsage to internal Usage model.
+
+    context_token is set to total_tokens from the API response,
+    representing the actual context window usage for this turn.
+    """
     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,
+        context_token=usage.total_tokens,
+        context_limit=context_limit,
+        max_tokens=max_tokens,
+    )
+
+
+def convert_anthropic_usage(
+    input_tokens: int,
+    output_tokens: int,
+    cached_tokens: int,
+    context_limit: int | None = None,
+    max_tokens: int | None = None,
+) -> model.Usage:
+    """Convert Anthropic usage data to internal Usage model.
+
+    context_token is computed from input + cached + output tokens,
+    representing the actual context window usage for this turn.
+    """
+    context_token = input_tokens + cached_tokens + output_tokens
+    return model.Usage(
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cached_tokens=cached_tokens,
+        context_token=context_token,
+        context_limit=context_limit,
+        max_tokens=max_tokens,
+    )
+
+
+def convert_responses_usage(
+    input_tokens: int,
+    output_tokens: int,
+    cached_tokens: int,
+    reasoning_tokens: int,
+    total_tokens: int,
+    context_limit: int | None = None,
+    max_tokens: int | None = None,
+) -> model.Usage:
+    """Convert OpenAI Responses API usage data to internal Usage model.
+
+    context_token is set to total_tokens from the API response,
+    representing the actual context window usage for this turn.
+    """
+    return model.Usage(
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cached_tokens=cached_tokens,
+        reasoning_tokens=reasoning_tokens,
+        context_token=total_tokens,
+        context_limit=context_limit,
+        max_tokens=max_tokens,
     )

klaude_code/protocol/commands.py

@@ -12,6 +12,7 @@ class CommandName(str, Enum):
     TERMINAL_SETUP = "terminal-setup"
     EXPORT = "export"
     STATUS = "status"
+    RELEASE_NOTES = "release-notes"
     # 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"

klaude_code/protocol/events.py

@@ -91,15 +91,23 @@ class ToolResultEvent(BaseModel):
     ui_extra: model.ToolResultUIExtra | None = None
     status: Literal["success", "error"]
     is_replay: bool = False
+    task_metadata: model.TaskMetadata | None = None  # Sub-agent task metadata
 
 
 class ResponseMetadataEvent(BaseModel):
-    """Showing model name, usage tokens, task duration, and turn count."""
+    """Internal event for turn-level metadata. Not exposed to UI directly."""
 
     session_id: str
     metadata: model.ResponseMetadataItem
 
 
+class TaskMetadataEvent(BaseModel):
+    """Task-level aggregated metadata for UI display."""
+
+    session_id: str
+    metadata: model.TaskMetadataItem
+
+
 class UserMessageEvent(BaseModel):
     session_id: str
     content: str
@@ -127,7 +135,7 @@ HistoryItemEvent = (
     | ToolCallEvent
     | ToolResultEvent
     | UserMessageEvent
-    | ResponseMetadataEvent
+    | TaskMetadataEvent
     | InterruptEvent
     | DeveloperMessageEvent
     | ErrorEvent
@@ -150,6 +158,7 @@ Event = (
     | ToolCallEvent
     | ToolResultEvent
     | ResponseMetadataEvent
+    | TaskMetadataEvent
     | ReplayHistoryEvent
     | ErrorEvent
     | EndEvent

klaude_code/protocol/model.py

@@ -1,9 +1,10 @@
 from datetime import datetime
 from enum import Enum
-from typing import Literal
+from typing import Annotated, Literal
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field, computed_field
 
+from klaude_code import const
 from klaude_code.protocol.commands import CommandName
 from klaude_code.protocol.tools import SubAgentType
 
@@ -12,12 +13,17 @@ TodoStatusType = Literal["pending", "in_progress", "completed"]
 
 
 class Usage(BaseModel):
+    # Token Usage (primary state)
     input_tokens: int = 0
     cached_tokens: int = 0
     reasoning_tokens: int = 0
     output_tokens: int = 0
-    total_tokens: int = 0
-    context_usage_percent: float | None = None
+
+    # Context window tracking
+    context_token: int | None = None  # Peak total_tokens seen (for context usage display)
+    context_limit: int | None = None  # Model's context limit
+    max_tokens: int | None = None  # Max output tokens for this request
+
     throughput_tps: float | None = None
     first_token_latency_ms: float | None = None
 
@@ -25,14 +31,42 @@ class Usage(BaseModel):
     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)
     currency: str = "USD"  # Currency for cost display (USD or CNY)
 
+    @computed_field
+    @property
+    def total_tokens(self) -> int:
+        """Total tokens computed from input + output tokens."""
+        return self.input_tokens + self.output_tokens
+
+    @computed_field
+    @property
+    def total_cost(self) -> float | None:
+        """Total cost computed from input + output + cache_read costs."""
+        costs = [self.input_cost, self.output_cost, self.cache_read_cost]
+        non_none = [c for c in costs if c is not None]
+        return sum(non_none) if non_none else None
+
+    @computed_field
+    @property
+    def context_usage_percent(self) -> float | None:
+        """Context usage percentage computed from context_token / (context_limit - max_tokens)."""
+        if self.context_limit is None or self.context_limit <= 0:
+            return None
+        if self.context_token is None:
+            return None
+        effective_limit = self.context_limit - (self.max_tokens or const.DEFAULT_MAX_TOKENS)
+        if effective_limit <= 0:
+            return None
+        return (self.context_token / effective_limit) * 100
+
 
 class TodoItem(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
     content: str
     status: TodoStatusType
-    activeForm: str = ""
+    active_form: str = Field(default="", alias="activeForm")
 
 
 class TodoUIExtra(BaseModel):
@@ -40,43 +74,55 @@ class TodoUIExtra(BaseModel):
     new_completed: list[str]
 
 
-class ToolResultUIExtraType(str, Enum):
-    DIFF_TEXT = "diff_text"
-    TODO_LIST = "todo_list"
-    SESSION_ID = "session_id"
-    MERMAID_LINK = "mermaid_link"
-    TRUNCATION = "truncation"
-    SESSION_STATUS = "session_status"
-
-
 class ToolSideEffect(str, Enum):
     TODO_CHANGE = "todo_change"
 
 
+# Discriminated union types for ToolResultUIExtra
+class DiffTextUIExtra(BaseModel):
+    type: Literal["diff_text"] = "diff_text"
+    diff_text: str
+
+
+class TodoListUIExtra(BaseModel):
+    type: Literal["todo_list"] = "todo_list"
+    todo_list: TodoUIExtra
+
+
+class SessionIdUIExtra(BaseModel):
+    type: Literal["session_id"] = "session_id"
+    session_id: str
+
+
 class MermaidLinkUIExtra(BaseModel):
+    type: Literal["mermaid_link"] = "mermaid_link"
     link: str
     line_count: int
 
 
 class TruncationUIExtra(BaseModel):
+    type: Literal["truncation"] = "truncation"
     saved_file_path: str
     original_length: int
     truncated_length: int
 
 
 class SessionStatusUIExtra(BaseModel):
+    type: Literal["session_status"] = "session_status"
     usage: "Usage"
     task_count: int
+    by_model: list["TaskMetadata"] = []
 
 
-class ToolResultUIExtra(BaseModel):
-    type: ToolResultUIExtraType
-    diff_text: str | None = None
-    todo_list: TodoUIExtra | None = None
-    session_id: str | None = None
-    mermaid_link: MermaidLinkUIExtra | None = None
-    truncation: TruncationUIExtra | None = None
-    session_status: SessionStatusUIExtra | None = None
+ToolResultUIExtra = Annotated[
+    DiffTextUIExtra
+    | TodoListUIExtra
+    | SessionIdUIExtra
+    | MermaidLinkUIExtra
+    | TruncationUIExtra
+    | SessionStatusUIExtra,
+    Field(discriminator="type"),
+]
 
 
 class AtPatternParseResult(BaseModel):
@@ -240,6 +286,7 @@ 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
+    task_metadata: "TaskMetadata | None" = None  # Sub-agent task metadata for propagation to main agent
     created_at: datetime = Field(default_factory=datetime.now)
 
 
@@ -255,6 +302,8 @@ class StreamErrorItem(BaseModel):
 
 
 class ResponseMetadataItem(BaseModel):
+    """Metadata for a single LLM response (turn-level)."""
+
     response_id: str | None = None
     usage: Usage | None = None
     model_name: str = ""
@@ -263,6 +312,73 @@ class ResponseMetadataItem(BaseModel):
     created_at: datetime = Field(default_factory=datetime.now)
 
 
+class TaskMetadata(BaseModel):
+    """Base metadata for a task execution (used by both main and sub-agents)."""
+
+    usage: Usage | None = None
+    model_name: str = ""
+    provider: str | None = None
+    task_duration_s: float | None = None
+
+    @staticmethod
+    def aggregate_by_model(metadata_list: list["TaskMetadata"]) -> list["TaskMetadata"]:
+        """Aggregate multiple TaskMetadata by (model_name, provider).
+
+        Returns a list sorted by total_cost descending.
+
+        Note: total_tokens and total_cost are now computed fields,
+        so we only accumulate the primary state fields here.
+        """
+        aggregated: dict[tuple[str, str | None], TaskMetadata] = {}
+
+        for meta in metadata_list:
+            if not meta.usage:
+                continue
+
+            key = (meta.model_name, meta.provider)
+            usage = meta.usage
+
+            if key not in aggregated:
+                aggregated[key] = TaskMetadata(
+                    model_name=meta.model_name,
+                    provider=meta.provider,
+                    usage=Usage(currency=usage.currency),
+                )
+
+            agg = aggregated[key]
+            if agg.usage is None:
+                continue
+
+            # Accumulate primary token fields (total_tokens is computed)
+            agg.usage.input_tokens += usage.input_tokens
+            agg.usage.cached_tokens += usage.cached_tokens
+            agg.usage.reasoning_tokens += usage.reasoning_tokens
+            agg.usage.output_tokens += usage.output_tokens
+
+            # Accumulate cost components (total_cost is computed)
+            if usage.input_cost is not None:
+                agg.usage.input_cost = (agg.usage.input_cost or 0.0) + usage.input_cost
+            if usage.output_cost is not None:
+                agg.usage.output_cost = (agg.usage.output_cost or 0.0) + usage.output_cost
+            if usage.cache_read_cost is not None:
+                agg.usage.cache_read_cost = (agg.usage.cache_read_cost or 0.0) + usage.cache_read_cost
+
+        # Sort by total_cost descending
+        return sorted(
+            aggregated.values(),
+            key=lambda m: m.usage.total_cost if m.usage and m.usage.total_cost else 0.0,
+            reverse=True,
+        )
+
+
+class TaskMetadataItem(BaseModel):
+    """Aggregated metadata for a complete task, stored in conversation history."""
+
+    main: TaskMetadata = Field(default_factory=TaskMetadata)
+    sub_agent_task_metadata: list[TaskMetadata] = Field(default_factory=lambda: list[TaskMetadata]())
+    created_at: datetime = Field(default_factory=datetime.now)
+
+
 MessageItem = (
     UserMessageItem
     | AssistantMessageItem
@@ -278,7 +394,14 @@ MessageItem = (
 StreamItem = AssistantMessageDelta
 
 ConversationItem = (
-    StartItem | InterruptItem | StreamErrorItem | StreamItem | MessageItem | ResponseMetadataItem | ToolCallStartItem
+    StartItem
+    | InterruptItem
+    | StreamErrorItem
+    | StreamItem
+    | MessageItem
+    | ResponseMetadataItem
+    | TaskMetadataItem
+    | ToolCallStartItem
 )
 
 

klaude_code/protocol/op.py

@@ -67,6 +67,7 @@ class InitAgentOperation(Operation):
 
     type: OperationType = OperationType.INIT_AGENT
     session_id: str | None = None
+    is_new_session: bool = False
 
     async def execute(self, handler: OperationHandler) -> None:
         await handler.handle_init_agent(self)

klaude_code/protocol/sub_agent.py

@@ -1,10 +1,13 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any, Callable
+from typing import TYPE_CHECKING, Any, Callable
 
 from klaude_code.protocol import tools
 
+if TYPE_CHECKING:
+    from klaude_code.protocol import model
+
 AvailabilityPredicate = Callable[[str], bool]
 PromptBuilder = Callable[[dict[str, Any]], str]
 
@@ -14,6 +17,7 @@ class SubAgentResult:
     task_result: str
     session_id: str
     error: bool = False
+    task_metadata: model.TaskMetadata | None = None
 
 
 def _default_prompt_builder(args: dict[str, Any]) -> str: