klaude-code 1.4.3__py3-none-any.whl → 1.6.0__py3-none-any.whl

klaude_code/config/select_model.py

@@ -1,4 +1,4 @@
-import sys
+from dataclasses import dataclass
 
 from klaude_code.config.config import ModelEntry, load_config, print_no_available_models_hint
 from klaude_code.trace import log
@@ -17,15 +17,34 @@ def _normalize_model_key(value: str) -> str:
     return "".join(ch for ch in value.casefold() if ch.isalnum())
 
 
-def select_model_from_config(preferred: str | None = None) -> str | None:
+@dataclass
+class ModelMatchResult:
+    """Result of model matching.
+
+    Attributes:
+        matched_model: The single matched model name, or None if ambiguous/no match.
+        filtered_models: List of filtered models for interactive selection.
+        filter_hint: The filter hint to show (original preferred value), or None.
+        error_message: Error message if no models available, or None.
     """
-    Interactive single-choice model selector.
-    for `--select-model`
+
+    matched_model: str | None
+    filtered_models: list[ModelEntry]
+    filter_hint: str | None
+    error_message: str | None = None
+
+
+def match_model_from_config(preferred: str | None = None) -> ModelMatchResult:
+    """Match model from config without interactive selection.
 
     If preferred is provided:
-    - Exact match: return immediately
-    - Single partial match (case-insensitive): return immediately
-    - Otherwise: fall through to interactive selection
+    - Exact match: returns matched_model
+    - Single partial match (case-insensitive): returns matched_model
+    - Multiple matches: returns filtered_models for interactive selection
+    - No matches: returns all models with filter_hint=None
+
+    Returns:
+        ModelMatchResult with match state.
     """
     config = load_config()
 
@@ -36,17 +55,22 @@ def select_model_from_config(preferred: str | None = None) -> str | None:
 
     if not models:
         print_no_available_models_hint()
-        return None
+        return ModelMatchResult(
+            matched_model=None,
+            filtered_models=[],
+            filter_hint=None,
+            error_message="No models available",
+        )
 
     names: list[str] = [m.model_name for m in models]
 
     # Try to match preferred model name
-    filtered_models = models
+    filter_hint = preferred
     if preferred and preferred.strip():
         preferred = preferred.strip()
         # Exact match
         if preferred in names:
-            return preferred
+            return ModelMatchResult(matched_model=preferred, filtered_models=models, filter_hint=None)
 
         preferred_lower = preferred.lower()
         # Case-insensitive exact match (model_name or model_params.model)
@@ -56,7 +80,9 @@ def select_model_from_config(preferred: str | None = None) -> str | None:
             if preferred_lower == m.model_name.lower() or preferred_lower == (m.model_params.model or "").lower()
         ]
         if len(exact_ci_matches) == 1:
-            return exact_ci_matches[0].model_name
+            return ModelMatchResult(
+                matched_model=exact_ci_matches[0].model_name, filtered_models=models, filter_hint=None
+            )
 
         # Normalized matching (e.g. gpt52 == gpt-5.2, gpt52 in gpt-5.2-2025-...)
         preferred_norm = _normalize_model_key(preferred)
@@ -69,7 +95,9 @@ def select_model_from_config(preferred: str | None = None) -> str | None:
                 or preferred_norm == _normalize_model_key(m.model_params.model or "")
             ]
             if len(normalized_matches) == 1:
-                return normalized_matches[0].model_name
+                return ModelMatchResult(
+                    matched_model=normalized_matches[0].model_name, filtered_models=models, filter_hint=None
+                )
 
             if not normalized_matches and len(preferred_norm) >= 4:
                 normalized_matches = [
@@ -79,7 +107,9 @@ def select_model_from_config(preferred: str | None = None) -> str | None:
                     or preferred_norm in _normalize_model_key(m.model_params.model or "")
                 ]
                 if len(normalized_matches) == 1:
-                    return normalized_matches[0].model_name
+                    return ModelMatchResult(
+                        matched_model=normalized_matches[0].model_name, filtered_models=models, filter_hint=None
+                    )
 
         # Partial match (case-insensitive) on model_name or model_params.model.
         # If normalized matching found candidates (even if multiple), prefer those as the filter set.
@@ -89,93 +119,13 @@ def select_model_from_config(preferred: str | None = None) -> str | None:
             if preferred_lower in m.model_name.lower() or preferred_lower in (m.model_params.model or "").lower()
         ]
         if len(matches) == 1:
-            return matches[0].model_name
+            return ModelMatchResult(matched_model=matches[0].model_name, filtered_models=models, filter_hint=None)
         if matches:
             # Multiple matches: filter the list for interactive selection
-            filtered_models = matches
+            return ModelMatchResult(matched_model=None, filtered_models=matches, filter_hint=filter_hint)
         else:
             # No matches: show all models without filter hint
-            preferred = None
             log(("No matching models found. Showing all models.", "yellow"))
+            return ModelMatchResult(matched_model=None, filtered_models=models, filter_hint=None)
 
-    # Non-interactive environments (CI/pipes) should never enter an interactive prompt.
-    # If we couldn't resolve to a single model deterministically above, fail with a clear hint.
-    if not sys.stdin.isatty() or not sys.stdout.isatty():
-        log(("Error: cannot use interactive model selection without a TTY", "red"))
-        log(("Hint: pass --model <config-name> or set main_model in ~/.klaude/klaude-config.yaml", "yellow"))
-        if preferred:
-            log((f"Hint: '{preferred}' did not resolve to a single configured model", "yellow"))
-        return None
-
-    try:
-        from prompt_toolkit.styles import Style
-
-        from klaude_code.ui.terminal.selector import SelectItem, select_one
-
-        max_model_name_length = max(len(m.model_name) for m in filtered_models)
-
-        def _thinking_info(m: ModelEntry) -> str:
-            thinking = m.model_params.thinking
-            if not thinking:
-                return ""
-            if thinking.reasoning_effort:
-                return f"reasoning {thinking.reasoning_effort}"
-            if thinking.budget_tokens:
-                return f"thinking budget {thinking.budget_tokens}"
-            return "thinking (configured)"
-
-        items: list[SelectItem[str]] = []
-        for m in filtered_models:
-            model_id = m.model_params.model or "N/A"
-            first_line_prefix = f"{m.model_name:<{max_model_name_length}} → "
-            thinking_info = _thinking_info(m)
-            meta_parts: list[str] = [m.provider]
-            if thinking_info:
-                meta_parts.append(thinking_info)
-            if m.model_params.verbosity:
-                meta_parts.append(f"verbosity {m.model_params.verbosity}")
-            meta_str = " · ".join(meta_parts)
-            title = [
-                ("class:msg", first_line_prefix),
-                ("class:msg bold", model_id),
-                ("class:meta", f"  {meta_str}\n"),
-            ]
-            search_text = f"{m.model_name} {model_id} {m.provider}"
-            items.append(SelectItem(title=title, value=m.model_name, search_text=search_text))
-
-        try:
-            message = f"Select a model (filtered by '{preferred}'):" if preferred else "Select a model:"
-            result = select_one(
-                message=message,
-                items=items,
-                pointer="→",
-                use_search_filter=True,
-                initial_value=config.main_model,
-                style=Style(
-                    [
-                        ("pointer", "ansigreen"),
-                        ("highlighted", "ansigreen"),
-                        ("msg", ""),
-                        ("meta", "fg:ansibrightblack"),
-                        ("text", "ansibrightblack"),
-                        ("question", "bold"),
-                        ("search_prefix", "ansibrightblack"),
-                        # search filter colors at the bottom
-                        ("search_success", "noinherit fg:ansigreen"),
-                        ("search_none", "noinherit fg:ansired"),
-                    ]
-                ),
-            )
-            if isinstance(result, str) and result in names:
-                return result
-        except KeyboardInterrupt:
-            return None
-    except Exception as e:
-        log((f"Failed to use prompt_toolkit for model selection: {e}", "yellow"))
-        # Never return an unvalidated model name here.
-        # If we can't interactively select, fall back to a known configured model.
-        if isinstance(preferred, str) and preferred in names:
-            return preferred
-        if config.main_model and config.main_model in names:
-            return config.main_model
-        return None
+    return ModelMatchResult(matched_model=None, filtered_models=models, filter_hint=None)

klaude_code/config/thinking.py

@@ -0,0 +1,255 @@
+"""Thinking level configuration data and helpers.
+
+This module contains thinking level definitions and helper functions
+that are shared between command layer and UI layer.
+"""
+
+from dataclasses import dataclass
+from typing import Literal
+
+from klaude_code.protocol import llm_param
+
+ReasoningEffort = Literal["high", "medium", "low", "minimal", "none", "xhigh"]
+
+# Thinking level options for different protocols
+RESPONSES_LEVELS = ["low", "medium", "high"]
+RESPONSES_GPT51_LEVELS = ["none", "low", "medium", "high"]
+RESPONSES_GPT52_LEVELS = ["none", "low", "medium", "high", "xhigh"]
+RESPONSES_CODEX_MAX_LEVELS = ["medium", "high", "xhigh"]
+RESPONSES_GEMINI_FLASH_LEVELS = ["minimal", "low", "medium", "high"]
+
+ANTHROPIC_LEVELS: list[tuple[str, int | None]] = [
+    ("off", 0),
+    ("low (2048 tokens)", 2048),
+    ("medium (8192 tokens)", 8192),
+    ("high (31999 tokens)", 31999),
+]
+
+
+def is_openrouter_model_with_reasoning_effort(model_name: str | None) -> bool:
+    """Check if the model is GPT series, Grok or Gemini 3."""
+    if not model_name:
+        return False
+    model_lower = model_name.lower()
+    return model_lower.startswith(("openai/gpt-", "x-ai/grok-", "google/gemini-3"))
+
+
+def _is_gpt51_model(model_name: str | None) -> bool:
+    """Check if the model is GPT-5.1."""
+    if not model_name:
+        return False
+    return model_name.lower() in ["gpt-5.1", "openai/gpt-5.1", "gpt-5.1-codex-2025-11-13"]
+
+
+def _is_gpt52_model(model_name: str | None) -> bool:
+    """Check if the model is GPT-5.2."""
+    if not model_name:
+        return False
+    return model_name.lower() in ["gpt-5.2", "openai/gpt-5.2"]
+
+
+def _is_codex_max_model(model_name: str | None) -> bool:
+    """Check if the model is GPT-5.1-codex-max."""
+    if not model_name:
+        return False
+    return "codex-max" in model_name.lower()
+
+
+def _is_gemini_flash_model(model_name: str | None) -> bool:
+    """Check if the model is Gemini 3 Flash."""
+    if not model_name:
+        return False
+    return "gemini-3-flash" in model_name.lower()
+
+
+def should_auto_trigger_thinking(model_name: str | None) -> bool:
+    """Check if model should auto-trigger thinking selection on switch."""
+    if not model_name:
+        return False
+    model_lower = model_name.lower()
+    return "gpt-5" in model_lower or "gemini-3" in model_lower or "opus" in model_lower
+
+
+def get_levels_for_responses(model_name: str | None) -> list[str]:
+    """Get thinking levels for responses protocol."""
+    if _is_codex_max_model(model_name):
+        return RESPONSES_CODEX_MAX_LEVELS
+    if _is_gpt52_model(model_name):
+        return RESPONSES_GPT52_LEVELS
+    if _is_gpt51_model(model_name):
+        return RESPONSES_GPT51_LEVELS
+    if _is_gemini_flash_model(model_name):
+        return RESPONSES_GEMINI_FLASH_LEVELS
+    return RESPONSES_LEVELS
+
+
+def format_current_thinking(config: llm_param.LLMConfigParameter) -> str:
+    """Format the current thinking configuration for display."""
+    thinking = config.thinking
+    if not thinking:
+        return "not configured"
+
+    protocol = config.protocol
+
+    if protocol in (llm_param.LLMClientProtocol.RESPONSES, llm_param.LLMClientProtocol.CODEX):
+        if thinking.reasoning_effort:
+            return f"reasoning_effort={thinking.reasoning_effort}"
+        return "not set"
+
+    if protocol == llm_param.LLMClientProtocol.ANTHROPIC:
+        if thinking.type == "disabled":
+            return "off"
+        if thinking.type == "enabled":
+            return f"enabled (budget_tokens={thinking.budget_tokens})"
+        return "not set"
+
+    if protocol == llm_param.LLMClientProtocol.OPENROUTER:
+        if is_openrouter_model_with_reasoning_effort(config.model):
+            if thinking.reasoning_effort:
+                return f"reasoning_effort={thinking.reasoning_effort}"
+        else:
+            if thinking.type == "disabled":
+                return "off"
+            if thinking.type == "enabled":
+                return f"enabled (budget_tokens={thinking.budget_tokens})"
+        return "not set"
+
+    if protocol == llm_param.LLMClientProtocol.OPENAI:
+        if thinking.type == "disabled":
+            return "off"
+        if thinking.type == "enabled":
+            return f"enabled (budget_tokens={thinking.budget_tokens})"
+        return "not set"
+
+    return "unknown protocol"
+
+
+# ---------------------------------------------------------------------------
+# Thinking picker data structures
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ThinkingOption:
+    """A thinking option for selection.
+
+    Attributes:
+        label: Display label for this option (e.g., "low", "medium (8192 tokens)").
+        value: Encoded value string (e.g., "effort:low", "budget:2048").
+    """
+
+    label: str
+    value: str
+
+
+@dataclass
+class ThinkingPickerData:
+    """Data for building thinking picker UI.
+
+    Attributes:
+        options: List of thinking options.
+        message: Prompt message (e.g., "Select reasoning effort:").
+        current_value: Currently selected value, or None.
+    """
+
+    options: list[ThinkingOption]
+    message: str
+    current_value: str | None
+
+
+def _build_effort_options(levels: list[str]) -> list[ThinkingOption]:
+    """Build effort-based thinking options."""
+    return [ThinkingOption(label=level, value=f"effort:{level}") for level in levels]
+
+
+def _build_budget_options() -> list[ThinkingOption]:
+    """Build budget-based thinking options."""
+    return [ThinkingOption(label=label, value=f"budget:{tokens or 0}") for label, tokens in ANTHROPIC_LEVELS]
+
+
+def _get_current_effort_value(thinking: llm_param.Thinking | None) -> str | None:
+    """Get current value for effort-based thinking."""
+    if thinking and thinking.reasoning_effort:
+        return f"effort:{thinking.reasoning_effort}"
+    return None
+
+
+def _get_current_budget_value(thinking: llm_param.Thinking | None) -> str | None:
+    """Get current value for budget-based thinking."""
+    if thinking:
+        if thinking.type == "disabled":
+            return "budget:0"
+        if thinking.budget_tokens:
+            return f"budget:{thinking.budget_tokens}"
+    return None
+
+
+def get_thinking_picker_data(config: llm_param.LLMConfigParameter) -> ThinkingPickerData | None:
+    """Get thinking picker data based on LLM config.
+
+    Returns:
+        ThinkingPickerData with options and current value, or None if protocol doesn't support thinking.
+    """
+    protocol = config.protocol
+    model_name = config.model
+    thinking = config.thinking
+
+    if protocol in (llm_param.LLMClientProtocol.RESPONSES, llm_param.LLMClientProtocol.CODEX):
+        levels = get_levels_for_responses(model_name)
+        return ThinkingPickerData(
+            options=_build_effort_options(levels),
+            message="Select reasoning effort:",
+            current_value=_get_current_effort_value(thinking),
+        )
+
+    if protocol == llm_param.LLMClientProtocol.ANTHROPIC:
+        return ThinkingPickerData(
+            options=_build_budget_options(),
+            message="Select thinking level:",
+            current_value=_get_current_budget_value(thinking),
+        )
+
+    if protocol == llm_param.LLMClientProtocol.OPENROUTER:
+        if is_openrouter_model_with_reasoning_effort(model_name):
+            levels = get_levels_for_responses(model_name)
+            return ThinkingPickerData(
+                options=_build_effort_options(levels),
+                message="Select reasoning effort:",
+                current_value=_get_current_effort_value(thinking),
+            )
+        return ThinkingPickerData(
+            options=_build_budget_options(),
+            message="Select thinking level:",
+            current_value=_get_current_budget_value(thinking),
+        )
+
+    if protocol == llm_param.LLMClientProtocol.OPENAI:
+        return ThinkingPickerData(
+            options=_build_budget_options(),
+            message="Select thinking level:",
+            current_value=_get_current_budget_value(thinking),
+        )
+
+    return None
+
+
+def parse_thinking_value(value: str) -> llm_param.Thinking | None:
+    """Parse a thinking value string into a Thinking object.
+
+    Args:
+        value: Encoded value string (e.g., "effort:low", "budget:2048").
+
+    Returns:
+        Thinking object, or None if invalid format.
+    """
+    if value.startswith("effort:"):
+        effort = value[7:]
+        return llm_param.Thinking(reasoning_effort=effort)  # type: ignore[arg-type]
+
+    if value.startswith("budget:"):
+        budget = int(value[7:])
+        if budget == 0:
+            return llm_param.Thinking(type="disabled", budget_tokens=0)
+        return llm_param.Thinking(type="enabled", budget_tokens=budget)
+
+    return None

klaude_code/core/executor.py

@@ -13,18 +13,13 @@ from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
 
-from klaude_code.command import dispatch_command
-from klaude_code.command.thinking_cmd import (
-    format_current_thinking,
-    select_thinking_for_protocol,
-    should_auto_trigger_thinking,
-)
 from klaude_code.config import load_config
 from klaude_code.core.agent import Agent, DefaultModelProfileProvider, ModelProfileProvider
 from klaude_code.core.manager import LLMClients, SubAgentManager
 from klaude_code.core.tool import current_run_subtask_callback
 from klaude_code.llm.registry import create_llm_client
 from klaude_code.protocol import commands, events, model, op
+from klaude_code.protocol.llm_param import Thinking
 from klaude_code.protocol.op_handler import OperationHandler
 from klaude_code.protocol.sub_agent import SubAgentResult
 from klaude_code.session.export import build_export_html, get_default_export_path
@@ -181,7 +176,11 @@ class ExecutorContext:
         await self._ensure_agent(operation.session_id)
 
     async def handle_user_input(self, operation: op.UserInputOperation) -> None:
-        """Handle a user input operation by dispatching it into operations."""
+        """Handle a user input operation.
+
+        Core should not parse slash commands. The UI/CLI layer is responsible for
+        turning raw user input into one or more operations.
+        """
 
         if operation.session_id is None:
             raise ValueError("session_id cannot be None")
@@ -190,33 +189,18 @@ class ExecutorContext:
         agent = await self._ensure_agent(session_id)
         user_input = operation.input
 
-        # Emit the original user input to UI (even if the persisted text differs).
         await self.emit_event(
             events.UserMessageEvent(content=user_input.text, session_id=session_id, images=user_input.images)
         )
+        agent.session.append_history([model.UserMessageItem(content=user_input.text, images=user_input.images)])
 
-        result = await dispatch_command(user_input, agent, submission_id=operation.id)
-        ops: list[op.Operation] = list(result.operations or [])
-
-        run_ops = [candidate for candidate in ops if isinstance(candidate, op.RunAgentOperation)]
-        if len(run_ops) > 1:
-            raise ValueError("Multiple RunAgentOperation results are not supported")
-
-        persisted_user_input = run_ops[0].input if run_ops else user_input
-
-        if result.persist_user_input:
-            agent.session.append_history(
-                [model.UserMessageItem(content=persisted_user_input.text, images=persisted_user_input.images)]
+        await self.handle_run_agent(
+            op.RunAgentOperation(
+                id=operation.id,
+                session_id=session_id,
+                input=user_input,
             )
-
-        if result.events:
-            for evt in result.events:
-                if result.persist_events and isinstance(evt, events.DeveloperMessageEvent):
-                    agent.session.append_history([evt.item])
-                await self.emit_event(evt)
-
-        for operation_item in ops:
-            await operation_item.execute(handler=self)
+        )
 
     async def handle_run_agent(self, operation: op.RunAgentOperation) -> None:
         agent = await self._ensure_agent(operation.session_id)
@@ -243,56 +227,62 @@ class ExecutorContext:
             config.main_model = operation.model_name
             await config.save()
 
-        default_note = " (saved as default)" if operation.save_as_default else ""
-        developer_item = model.DeveloperMessageItem(
-            content=f"Switched to: {llm_config.model}{default_note}",
-            command_output=model.CommandOutput(command_name=commands.CommandName.MODEL),
-        )
-        agent.session.append_history([developer_item])
-
-        await self.emit_event(events.DeveloperMessageEvent(session_id=agent.session.id, item=developer_item))
+        if operation.emit_switch_message:
+            default_note = " (saved as default)" if operation.save_as_default else ""
+            developer_item = model.DeveloperMessageItem(
+                content=f"Switched to: {llm_config.model}{default_note}",
+                command_output=model.CommandOutput(command_name=commands.CommandName.MODEL),
+            )
+            agent.session.append_history([developer_item])
+            await self.emit_event(events.DeveloperMessageEvent(session_id=agent.session.id, item=developer_item))
 
         if self._on_model_change is not None:
             self._on_model_change(llm_client.model_name)
 
-        if should_auto_trigger_thinking(llm_config.model):
-            thinking_op = op.ChangeThinkingOperation(session_id=operation.session_id)
-            await thinking_op.execute(handler=self)
-            # WelcomeEvent is already handled by the thinking change
-        else:
+        if operation.emit_welcome_event:
             await self.emit_event(events.WelcomeEvent(llm_config=llm_config, work_dir=str(agent.session.work_dir)))
 
     async def handle_change_thinking(self, operation: op.ChangeThinkingOperation) -> None:
-        """Handle a change thinking operation by prompting user to select thinking level."""
+        """Handle a change thinking operation.
+
+        Interactive thinking selection must happen in the UI/CLI layer. Core only
+        applies a concrete thinking configuration.
+        """
         agent = await self._ensure_agent(operation.session_id)
-        if not agent.profile:
-            return
 
         config = agent.profile.llm_client.get_llm_config()
-        current = format_current_thinking(config)
-
-        new_thinking = await select_thinking_for_protocol(config)
 
-        if new_thinking is None:
+        def _format_thinking_for_display(thinking: Thinking | None) -> str:
+            if thinking is None:
+                return "not configured"
+            if thinking.reasoning_effort:
+                return f"reasoning_effort={thinking.reasoning_effort}"
+            if thinking.type == "disabled":
+                return "off"
+            if thinking.type == "enabled":
+                if thinking.budget_tokens is None:
+                    return "enabled"
+                return f"enabled (budget_tokens={thinking.budget_tokens})"
+            return "not set"
+
+        if operation.thinking is None:
+            raise ValueError("thinking must be provided; interactive selection belongs to UI")
+
+        current = _format_thinking_for_display(config.thinking)
+        config.thinking = operation.thinking
+        agent.session.model_thinking = operation.thinking
+        new_status = _format_thinking_for_display(config.thinking)
+
+        if operation.emit_switch_message:
             developer_item = model.DeveloperMessageItem(
-                content="(thinking unchanged)",
+                content=f"Thinking changed: {current} -> {new_status}",
                 command_output=model.CommandOutput(command_name=commands.CommandName.THINKING),
             )
+            agent.session.append_history([developer_item])
             await self.emit_event(events.DeveloperMessageEvent(session_id=agent.session.id, item=developer_item))
-            return
-
-        config.thinking = new_thinking
-        agent.session.model_thinking = new_thinking
-        new_status = format_current_thinking(config)
-
-        developer_item = model.DeveloperMessageItem(
-            content=f"Thinking changed: {current} -> {new_status}",
-            command_output=model.CommandOutput(command_name=commands.CommandName.THINKING),
-        )
-        agent.session.append_history([developer_item])
 
-        await self.emit_event(events.DeveloperMessageEvent(session_id=agent.session.id, item=developer_item))
-        await self.emit_event(events.WelcomeEvent(work_dir=str(agent.session.work_dir), llm_config=config))
+        if operation.emit_welcome_event:
+            await self.emit_event(events.WelcomeEvent(work_dir=str(agent.session.work_dir), llm_config=config))
 
     async def handle_clear_session(self, operation: op.ClearSessionOperation) -> None:
         agent = await self._ensure_agent(operation.session_id)

klaude_code/llm/usage.py

@@ -81,7 +81,7 @@ class MetadataTracker:
             ) * 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
+                time_duration = self._last_token_time - self._request_start_time
                 if time_duration >= 0.15:
                     self._metadata_item.usage.throughput_tps = self._metadata_item.usage.output_tokens / time_duration
 

klaude_code/protocol/commands.py

@@ -1,6 +1,17 @@
+from dataclasses import dataclass
 from enum import Enum
 
 
+@dataclass(frozen=True, slots=True)
+class CommandInfo:
+    """Lightweight command metadata for UI purposes (no logic)."""
+
+    name: str
+    summary: str
+    support_addition_params: bool = False
+    placeholder: str = ""
+
+
 class CommandName(str, Enum):
     INIT = "init"
     DEBUG = "debug"