klaude-code 2.5.3__py3-none-any.whl → 2.6.0__py3-none-any.whl

klaude_code/cli/main.py

@@ -7,52 +7,38 @@ from klaude_code.cli.auth_cmd import register_auth_commands
 from klaude_code.cli.config_cmd import register_config_commands
 from klaude_code.cli.cost_cmd import register_cost_commands
 from klaude_code.cli.debug import DEBUG_FILTER_HELP, prepare_debug_logging
-from klaude_code.cli.self_update import register_self_update_commands, version_option_callback
-from klaude_code.cli.session_cmd import register_session_commands
+from klaude_code.cli.self_update import register_self_upgrade_commands, version_option_callback
 from klaude_code.session import Session
 from klaude_code.tui.command.resume_cmd import select_session_sync
 from klaude_code.ui.terminal.title import update_terminal_title
 
-ENV_HELP_LINES = [
-    "Environment Variables:",
-    "",
-    "Provider API keys (built-in config):",
-    "  ANTHROPIC_API_KEY             Anthropic API key",
-    "  OPENAI_API_KEY                OpenAI API key",
-    "  OPENROUTER_API_KEY            OpenRouter API key",
-    "  GOOGLE_API_KEY                Google API key (Gemini)",
-    "  DEEPSEEK_API_KEY              DeepSeek API key",
-    "  MOONSHOT_API_KEY              Moonshot API key (Kimi)",
-    "",
-    "AWS credentials (Bedrock):",
-    "  AWS_ACCESS_KEY_ID             AWS access key id",
-    "  AWS_SECRET_ACCESS_KEY         AWS secret access key",
-    "  AWS_REGION                    AWS region",
-    "",
-    "Tool limits (Read):",
-    "  KLAUDE_READ_GLOBAL_LINE_CAP    Max lines to read (default: 2000)",
-    "  KLAUDE_READ_MAX_CHARS          Max total chars to read (default: 50000)",
-    "  KLAUDE_READ_MAX_IMAGE_BYTES    Max image bytes to read (default: 4MB)",
-    "  KLAUDE_IMAGE_OUTPUT_MAX_BYTES  Max decoded image bytes (default: 64MB)",
-    "",
-    "Notifications / testing:",
-    "  KLAUDE_NOTIFY                 Set to 0/off/false/disable(d) to disable task notifications",
-    "  KLAUDE_TEST_SIGNAL            In tmux, emit `tmux wait-for -S <channel>` on task completion",
-    "  TMUX                          Auto-detected; required for KLAUDE_TEST_SIGNAL",
-    "",
-    "Editor / terminal integration:",
-    "  EDITOR                        Preferred editor for `klaude config`",
-    "  TERM                          Terminal identification (auto-detected)",
-    "  TERM_PROGRAM                  Terminal identification (auto-detected)",
-    "  WT_SESSION                    Terminal hint (auto-detected)",
-    "  VTE_VERSION                   Terminal hint (auto-detected)",
-    "  GHOSTTY_RESOURCES_DIR         Ghostty detection (auto-detected)",
-    "",
-    "Compatibility:",
-    "  ANTHROPIC_AUTH_TOKEN          Reserved by anthropic SDK; temporarily unset during client init",
-]
-
-ENV_HELP = "\n\n".join(ENV_HELP_LINES)
+
+def _build_env_help() -> str:
+    from klaude_code.config.builtin_config import SUPPORTED_API_KEYS
+
+    lines = [
+        "Environment Variables:",
+        "",
+        "Provider API keys (built-in config):",
+    ]
+    # Calculate max env_var length for alignment
+    max_len = max(len(k.env_var) for k in SUPPORTED_API_KEYS)
+    for k in SUPPORTED_API_KEYS:
+        lines.append(f"  {k.env_var:<{max_len}}  {k.description}")
+    lines.extend(
+        [
+            "",
+            "Tool limits (Read):",
+            "  KLAUDE_READ_GLOBAL_LINE_CAP    Max lines to read (default: 2000)",
+            "  KLAUDE_READ_MAX_CHARS          Max total chars to read (default: 50000)",
+            "  KLAUDE_READ_MAX_IMAGE_BYTES    Max image bytes to read (default: 4MB)",
+            "  KLAUDE_IMAGE_OUTPUT_MAX_BYTES  Max decoded image bytes (default: 64MB)",
+        ]
+    )
+    return "\n\n".join(lines)
+
+
+ENV_HELP = _build_env_help()
 
 app = typer.Typer(
     add_completion=False,
@@ -60,55 +46,51 @@ app = typer.Typer(
     no_args_is_help=False,
     rich_markup_mode="rich",
     epilog=ENV_HELP,
+    context_settings={"help_option_names": ["-h", "--help"]},
 )
 
 # Register subcommands from modules
-register_session_commands(app)
 register_auth_commands(app)
 register_config_commands(app)
 register_cost_commands(app)
+register_self_upgrade_commands(app)
+
 
-register_self_update_commands(app)
+@app.command("help", hidden=True)
+def help_command(ctx: typer.Context) -> None:
+    """Show help message."""
+    print(ctx.parent.get_help() if ctx.parent else ctx.get_help())
 
 
 @app.callback(invoke_without_command=True)
 def main_callback(
     ctx: typer.Context,
-    version: bool = typer.Option(
-        False,
-        "--version",
-        "-V",
-        "-v",
-        help="Show version and exit",
-        callback=version_option_callback,
-        is_eager=True,
-    ),
     model: str | None = typer.Option(
         None,
         "--model",
         "-m",
-        help="Override model config name (uses main model by default)",
+        help="Select model by name",
         rich_help_panel="LLM",
     ),
-    continue_: bool = typer.Option(False, "--continue", "-c", help="Continue from latest session"),
-    resume: bool = typer.Option(False, "--resume", "-r", help="Select a session to resume for this project"),
+    continue_: bool = typer.Option(False, "--continue", "-c", help="Resume latest session"),
+    resume: bool = typer.Option(False, "--resume", "-r", help="Pick a session to resume"),
     resume_by_id: str | None = typer.Option(
         None,
         "--resume-by-id",
-        help="Resume a session by its ID (must exist)",
+        help="Resume session by ID",
     ),
     select_model: bool = typer.Option(
         False,
         "--select-model",
         "-s",
-        help="Interactively choose a model at startup",
+        help="Choose model interactively",
         rich_help_panel="LLM",
     ),
     debug: bool = typer.Option(
         False,
         "--debug",
         "-d",
-        help="Enable debug mode",
+        help="Enable debug logging",
         rich_help_panel="Debug",
     ),
     debug_filter: str | None = typer.Option(
@@ -120,14 +102,23 @@ def main_callback(
     vanilla: bool = typer.Option(
         False,
         "--vanilla",
-        help="Vanilla mode exposes the model's raw API behavior: it provides only minimal tools (Bash, Read, Write & Edit) and omits system prompts and reminders.",
+        help="Minimal mode: basic tools only, no system prompts",
     ),
     banana: bool = typer.Option(
         False,
         "--banana",
-        help="Image generation mode with Nano Banana",
+        help="Image generation mode",
         rich_help_panel="LLM",
     ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        "-v",
+        help="Show version and exit",
+        callback=version_option_callback,
+        is_eager=True,
+    ),
 ) -> None:
     # Only run interactive mode when no subcommand is invoked
     if ctx.invoked_subcommand is None:

klaude_code/cli/self_update.py

@@ -35,14 +35,14 @@ def version_command() -> None:
     _print_version()
 
 
-def update_command(
+def upgrade_command(
     check: bool = typer.Option(
         False,
         "--check",
-        help="Check for updates and exit without upgrading",
+        help="Check only, don't upgrade",
     ),
 ) -> None:
-    """Upgrade klaude-code when installed via `uv tool`."""
+    """Upgrade to latest version"""
 
     info = check_for_updates_blocking()
 
@@ -79,9 +79,9 @@ def update_command(
     log("Update complete. Please re-run `klaude` to use the new version.")
 
 
-def register_self_update_commands(app: typer.Typer) -> None:
+def register_self_upgrade_commands(app: typer.Typer) -> None:
     """Register self-update and version subcommands to the given Typer app."""
 
-    app.command("update")(update_command)
-    app.command("upgrade", help="Alias for `klaude update`.")(update_command)
-    app.command("version", help="Alias for `klaude --version`.")(version_command)
+    app.command("upgrade")(upgrade_command)
+    app.command("update", hidden=True)(upgrade_command)
+    app.command("version", hidden=True)(version_command)

klaude_code/config/builtin_config.py

@@ -5,6 +5,7 @@ environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) without
 manually configuring providers.
 """
 
+from dataclasses import dataclass
 from functools import lru_cache
 from importlib import resources
 from typing import TYPE_CHECKING, Any
@@ -14,15 +15,28 @@ import yaml
 if TYPE_CHECKING:
     from klaude_code.config.config import ProviderConfig
 
-# All supported API key environment variables
-SUPPORTED_API_KEY_ENVS = [
-    "ANTHROPIC_API_KEY",
-    "GOOGLE_API_KEY",
-    "OPENAI_API_KEY",
-    "OPENROUTER_API_KEY",
-    "DEEPSEEK_API_KEY",
-    "MOONSHOT_API_KEY",
-]
+
+@dataclass(frozen=True)
+class ApiKeyInfo:
+    """Information about a supported API key."""
+
+    env_var: str
+    name: str
+    description: str
+
+
+# All supported API keys with their metadata
+SUPPORTED_API_KEYS: tuple[ApiKeyInfo, ...] = (
+    ApiKeyInfo("ANTHROPIC_API_KEY", "Anthropic", "Anthropic API key"),
+    ApiKeyInfo("OPENAI_API_KEY", "OpenAI", "OpenAI API key"),
+    ApiKeyInfo("OPENROUTER_API_KEY", "OpenRouter", "OpenRouter API key"),
+    ApiKeyInfo("GOOGLE_API_KEY", "Google Gemini", "Google API key (Gemini)"),
+    ApiKeyInfo("DEEPSEEK_API_KEY", "DeepSeek", "DeepSeek API key"),
+    ApiKeyInfo("MOONSHOT_API_KEY", "Moonshot Kimi", "Moonshot API key (Kimi)"),
+)
+
+# For backwards compatibility
+SUPPORTED_API_KEY_ENVS = [k.env_var for k in SUPPORTED_API_KEYS]
 
 
 @lru_cache(maxsize=1)

klaude_code/config/config.py

@@ -8,8 +8,9 @@ from typing import Any, cast
 import yaml
 from pydantic import BaseModel, Field, ValidationError, model_validator
 
+from klaude_code.auth.env import get_auth_env
 from klaude_code.config.builtin_config import (
-    SUPPORTED_API_KEY_ENVS,
+    SUPPORTED_API_KEYS,
     get_builtin_provider_configs,
     get_builtin_sub_agent_models,
 )
@@ -26,7 +27,8 @@ def parse_env_var_syntax(value: str | None) -> tuple[str | None, str | None]:
 
     Returns:
         A tuple of (env_var_name, resolved_value).
-        - If value uses ${ENV_VAR} syntax: (env_var_name, os.environ.get(env_var_name))
+        - If value uses ${ENV_VAR} syntax: (env_var_name, resolved_value)
+          Priority: os.environ > klaude-auth.json env section
         - If value is a plain string: (None, value)
         - If value is None: (None, None)
     """
@@ -36,7 +38,9 @@ def parse_env_var_syntax(value: str | None) -> tuple[str | None, str | None]:
     match = _ENV_VAR_PATTERN.match(value)
     if match:
         env_var_name = match.group(1)
-        return env_var_name, os.environ.get(env_var_name)
+        # Priority: real env var > auth.json env section
+        resolved = os.environ.get(env_var_name) or get_auth_env(env_var_name)
+        return env_var_name, resolved
 
     return None, value
 
@@ -613,17 +617,23 @@ def load_config() -> Config:
 
 def print_no_available_models_hint() -> None:
     """Print helpful message when no models are available due to missing API keys."""
-    log("No available models. Please set one of the following environment variables:", style="yellow")
+    log("No available models. Configure an API key using one of these methods:", style="yellow")
     log("")
-    for env_var in SUPPORTED_API_KEY_ENVS:
-        current_value = os.environ.get(env_var)
+    log("Option 1: Use klaude auth login", style="bold")
+    # Use first word of name for brevity
+    names = [k.name.split()[0].lower() for k in SUPPORTED_API_KEYS]
+    log(f"  klaude auth login <provider>  (providers: {', '.join(names)})", style="dim")
+    log("")
+    log("Option 2: Set environment variables", style="bold")
+    max_len = max(len(k.env_var) for k in SUPPORTED_API_KEYS)
+    for key_info in SUPPORTED_API_KEYS:
+        current_value = os.environ.get(key_info.env_var) or get_auth_env(key_info.env_var)
         if current_value:
-            log(f"  {env_var} = (set)", style="green")
+            log(f"  {key_info.env_var:<{max_len}}  (set)", style="green")
         else:
-            log(f"  export {env_var}=<your-api-key>", style="dim")
+            log(f"  {key_info.env_var:<{max_len}}  {key_info.description}", style="dim")
     log("")
     log(f"Or add custom providers in: {config_path}", style="dim")
-    log(f"See example config: {example_config_path}", style="dim")
 
 
 # Expose cache control for tests and callers that need to invalidate the cache.

klaude_code/core/turn.py

@@ -25,10 +25,12 @@ from klaude_code.log import DebugType, log_debug
 from klaude_code.protocol import events, llm_param, message, model, tools
 
 # Protocols that support prefill (continuing from partial assistant message)
-_PREFILL_SUPPORTED_PROTOCOLS = frozenset({
-    "anthropic",
-    "claude_oauth",
-})
+_PREFILL_SUPPORTED_PROTOCOLS = frozenset(
+    {
+        "anthropic",
+        "claude_oauth",
+    }
+)
 
 
 class TurnError(Exception):
@@ -183,6 +185,7 @@ class TurnExecutor:
 
         if self._turn_result.stream_error is not None:
             # Save accumulated content for potential prefill on retry (only for supported protocols)
+            session_ctx.append_history([self._turn_result.stream_error])
             protocol = ctx.llm_client.get_llm_config().protocol
             supports_prefill = protocol.value in _PREFILL_SUPPORTED_PROTOCOLS
             if (
@@ -194,7 +197,6 @@ class TurnExecutor:
                 session_ctx.append_history([self._turn_result.assistant_message])
                 # Add continuation prompt to avoid Anthropic thinking block requirement
                 session_ctx.append_history([message.UserMessage(parts=[message.TextPart(text="continue")])])
-            session_ctx.append_history([self._turn_result.stream_error])
             yield events.TurnEndEvent(session_id=session_ctx.session_id)
             raise TurnError(self._turn_result.stream_error.error)
 
@@ -249,9 +251,6 @@ class TurnExecutor:
             image_size = generation.get("image_size")
             if image_size in SUPPORTED_IMAGE_SIZES:
                 image_config.image_size = image_size
-            extra = generation.get("extra")
-            if isinstance(extra, dict) and extra:
-                image_config.extra = extra
             if image_config.model_dump(exclude_none=True):
                 call_param.image_config = image_config
 

klaude_code/llm/google/client.py

@@ -25,6 +25,9 @@ from google.genai.types import (
     ThinkingLevel,
     ToolConfig,
 )
+from google.genai.types import (
+    ImageConfig as GoogleImageConfig,
+)
 
 from klaude_code.llm.client import LLMClientABC, LLMStreamABC
 from klaude_code.llm.google.input import convert_history_to_contents, convert_tool_schema
@@ -91,6 +94,14 @@ def _build_config(param: llm_param.LLMCallParameter) -> GenerateContentConfig:
             if param.thinking.reasoning_effort:
                 thinking_config.thinking_level = convert_gemini_thinking_level(param.thinking.reasoning_effort)
 
+    # ImageGen per-call overrides
+    image_config: GoogleImageConfig | None = None
+    if param.image_config is not None:
+        image_config = GoogleImageConfig(
+            aspect_ratio=param.image_config.aspect_ratio,
+            image_size=param.image_config.image_size,
+        )
+
     return GenerateContentConfig(
         system_instruction=param.system,
         temperature=param.temperature,
@@ -98,6 +109,7 @@ def _build_config(param: llm_param.LLMCallParameter) -> GenerateContentConfig:
         tools=cast(Any, tool_list) if tool_list else None,
         tool_config=tool_config,
         thinking_config=thinking_config,
+        image_config=image_config,
     )
 
 

klaude_code/llm/openai_compatible/stream.py

@@ -199,6 +199,7 @@ async def parse_chat_completions_stream(
     metadata_tracker: MetadataTracker,
     reasoning_handler: ReasoningHandlerABC,
     on_event: Callable[[object], None] | None = None,
+    provider_prefix: str = "",
 ) -> AsyncGenerator[message.LLMStreamItem]:
     """Parse OpenAI Chat Completions stream into stream items.
 
@@ -235,7 +236,7 @@ async def parse_chat_completions_stream(
             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))
+                metadata_tracker.set_provider(f"{provider_prefix}{provider}")
 
             choices = cast(Any, getattr(event, "choices", None))
             if not choices:
@@ -364,12 +365,14 @@ class OpenAILLMStream(LLMStreamABC):
         metadata_tracker: MetadataTracker,
         reasoning_handler: ReasoningHandlerABC,
         on_event: Callable[[object], None] | None = None,
+        provider_prefix: str = "",
     ) -> None:
         self._stream = stream
         self._param = param
         self._metadata_tracker = metadata_tracker
         self._reasoning_handler = reasoning_handler
         self._on_event = on_event
+        self._provider_prefix = provider_prefix
         self._state = StreamStateManager(
             param_model=str(param.model_id),
         )
@@ -386,6 +389,7 @@ class OpenAILLMStream(LLMStreamABC):
             metadata_tracker=self._metadata_tracker,
             reasoning_handler=self._reasoning_handler,
             on_event=self._on_event,
+            provider_prefix=self._provider_prefix,
         ):
             if isinstance(item, message.AssistantMessage):
                 self._completed = True

klaude_code/llm/openrouter/client.py

@@ -145,4 +145,5 @@ class OpenRouterClient(LLMClientABC):
             metadata_tracker=metadata_tracker,
             reasoning_handler=reasoning_handler,
             on_event=on_event,
+            provider_prefix="openrouter/",
         )

klaude_code/protocol/events.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import time
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from klaude_code.protocol import llm_param, message, model
+from klaude_code.protocol.commands import CommandName
+
+__all__ = [
+    "AssistantImageDeltaEvent",
+    "AssistantTextDeltaEvent",
+    "AssistantTextEndEvent",
+    "AssistantTextStartEvent",
+    "CommandOutputEvent",
+    "DeveloperMessageEvent",
+    "EndEvent",
+    "ErrorEvent",
+    "Event",
+    "InterruptEvent",
+    "ReplayEventUnion",
+    "ReplayHistoryEvent",
+    "ResponseCompleteEvent",
+    "ResponseEvent",
+    "TaskFinishEvent",
+    "TaskMetadataEvent",
+    "TaskStartEvent",
+    "ThinkingDeltaEvent",
+    "ThinkingEndEvent",
+    "ThinkingStartEvent",
+    "TodoChangeEvent",
+    "ToolCallEvent",
+    "ToolCallStartEvent",
+    "ToolResultEvent",
+    "TurnEndEvent",
+    "TurnStartEvent",
+    "UsageEvent",
+    "UserMessageEvent",
+    "WelcomeEvent",
+]
+
+
+class Event(BaseModel):
+    """Base event."""
+
+    session_id: str
+    timestamp: float = Field(default_factory=time.time)
+
+
+class ResponseEvent(Event):
+    """Event associated with a single model response."""
+
+    response_id: str | None = None
+
+
+class UserMessageEvent(Event):
+    content: str
+    images: list[message.ImageURLPart] | None = None
+
+
+class DeveloperMessageEvent(Event):
+    """DeveloperMessages are reminders in user messages or tool results."""
+
+    item: message.DeveloperMessage
+
+
+class TodoChangeEvent(Event):
+    todos: list[model.TodoItem]
+
+
+class CommandOutputEvent(Event):
+    """Event for command output display. Not persisted to session history."""
+
+    command_name: CommandName | str
+    content: str = ""
+    ui_extra: model.ToolResultUIExtra | None = None
+    is_error: bool = False
+
+
+class TaskStartEvent(Event):
+    sub_agent_state: model.SubAgentState | None = None
+    model_id: str | None = None
+
+
+class TaskFinishEvent(Event):
+    task_result: str
+    has_structured_output: bool = False
+
+
+class TurnStartEvent(Event):
+    pass
+
+
+class TurnEndEvent(Event):
+    pass
+
+
+class UsageEvent(ResponseEvent):
+    usage: model.Usage
+
+
+class TaskMetadataEvent(Event):
+    metadata: model.TaskMetadataItem
+    cancelled: bool = False
+
+
+class ThinkingStartEvent(ResponseEvent):
+    pass
+
+
+class ThinkingDeltaEvent(ResponseEvent):
+    content: str
+
+
+class ThinkingEndEvent(ResponseEvent):
+    pass
+
+
+class AssistantTextStartEvent(ResponseEvent):
+    pass
+
+
+class AssistantTextDeltaEvent(ResponseEvent):
+    content: str
+
+
+class AssistantTextEndEvent(ResponseEvent):
+    pass
+
+
+class AssistantImageDeltaEvent(ResponseEvent):
+    file_path: str
+
+
+class ToolCallStartEvent(ResponseEvent):
+    tool_call_id: str
+    tool_name: str
+
+
+class ResponseCompleteEvent(ResponseEvent):
+    """Final snapshot of the model response."""
+
+    content: str
+    thinking_text: str | None = None
+
+
+class WelcomeEvent(Event):
+    work_dir: str
+    llm_config: llm_param.LLMConfigParameter
+    show_klaude_code_info: bool = True
+    loaded_skills: dict[str, list[str]] = Field(default_factory=dict)
+
+
+class ErrorEvent(Event):
+    error_message: str
+    can_retry: bool = False
+
+
+class InterruptEvent(Event):
+    pass
+
+
+class EndEvent(Event):
+    """Global display shutdown."""
+
+    session_id: str = "__app__"
+
+
+type ReplayEventUnion = (
+    TaskStartEvent
+    | TaskFinishEvent
+    | TurnStartEvent
+    | ThinkingStartEvent
+    | ThinkingDeltaEvent
+    | ThinkingEndEvent
+    | AssistantTextStartEvent
+    | AssistantTextDeltaEvent
+    | AssistantTextEndEvent
+    | AssistantImageDeltaEvent
+    | ToolCallEvent
+    | ToolResultEvent
+    | UserMessageEvent
+    | TaskMetadataEvent
+    | InterruptEvent
+    | DeveloperMessageEvent
+    | ErrorEvent
+)
+
+
+class ReplayHistoryEvent(Event):
+    events: list[ReplayEventUnion]
+    updated_at: float
+    is_load: bool = True
+
+
+class ToolCallEvent(ResponseEvent):
+    tool_call_id: str
+    tool_name: str
+    arguments: str
+
+
+class ToolResultEvent(ResponseEvent):
+    tool_call_id: str
+    tool_name: str
+    result: str
+    ui_extra: model.ToolResultUIExtra | None = None
+    status: Literal["success", "error", "aborted"]
+    task_metadata: model.TaskMetadata | None = None
+    is_last_in_turn: bool = True
+
+    @property
+    def is_error(self) -> bool:
+        return self.status in ("error", "aborted")

klaude_code/protocol/sub_agent/image_gen.py

@@ -66,10 +66,6 @@ IMAGE_GEN_PARAMETERS: dict[str, Any] = {
                     "enum": ["1K", "2K", "4K"],
                     "description": "Output size for Nano Banana Pro (must use uppercase K).",
                 },
-                "extra": {
-                    "type": "object",
-                    "description": "Provider/model-specific extra parameters (future-proofing).",
-                },
             },
             "additionalProperties": False,
         },