alysis-code 0.13.0__py3-none-any.whl

alysis_code/cli_impl/chat/mid_turn_policy.py

@@ -0,0 +1,125 @@
+"""Classify submissions made while an agent turn is running.
+
+The policy is an allowlist. A command is safe mid-turn only when it does not
+mutate state read by the running turn, start or replace a turn or session, or
+tear down the application. New and unknown commands therefore block until they
+are reviewed explicitly.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+EXIT_WORDS = frozenset({"/exit", "/quit", ":q", "exit", "quit"})
+
+
+class MidTurnAction(Enum):
+    """How the TUI should route a submission made during a turn."""
+
+    MESSAGE = "message"
+    ALLOW = "allow"
+    DEFER = "defer"
+    BLOCK = "block"
+
+
+_ALLOWED_ALWAYS = frozenset(
+    {
+        "/help",
+        "/",
+        "/status",
+        "/subagents",
+        "/pwd",
+        "/context",
+        "/ctx",
+        "/usage",
+        "/model-info",
+        "/trace",
+        "/toolbar",
+        "/images",
+        "/image",
+        "/paste-image",
+        "/clear-images",
+        "/terminals",
+    }
+)
+
+_ALLOWED_BARE_ONLY = frozenset({"/skill"})
+
+_DEFERRED = frozenset({"/config", "/mode", "/model", "/persona"})
+
+_BLOCK_REASONS = {
+    "/clear": "clearing would discard the conversation this turn is writing to",
+    "/resume": "resuming replaces the session this turn is using",
+    "/compact": "compaction rewrites the history this turn is appending to",
+    "/plan": "plan mode changes the permissions this turn is using",
+    "/ask": "that starts a new turn",
+    "/forge": "Forge takes over the session",
+    ":forge": "Forge takes over the session",
+    "/login": "signing in replaces the active session",
+    "/logout": "signing out replaces the active session",
+    "/stream": "streaming is read at each step and would disrupt live output",
+    "/report": "report generation requires a settled session",
+    "/feedback": "feedback generation requires a settled session",
+    "/assets": "the assets view requires a settled Forge session",
+}
+
+_GENERIC_BLOCK_REASON = "that command cannot run while a turn is in flight"
+_ESCAPE_HATCH = "Esc to interrupt, or wait for the turn to finish."
+
+
+def _command_token(text: str) -> str:
+    stripped = str(text or "").strip()
+    if not stripped:
+        return ""
+    return stripped.split(maxsplit=1)[0].lower()
+
+
+def is_command(text: str) -> bool:
+    """Return whether text should be routed as a command rather than prose."""
+    stripped = str(text or "").strip()
+    if not stripped:
+        return False
+    if stripped.lower() in EXIT_WORDS:
+        return True
+    return stripped.startswith(("/", ":"))
+
+
+def classify_mid_turn(text: str) -> MidTurnAction:
+    """Classify text submitted while an agent turn is running."""
+    stripped = str(text or "").strip()
+    if not is_command(stripped):
+        return MidTurnAction.MESSAGE
+    if stripped.lower() in EXIT_WORDS:
+        return MidTurnAction.BLOCK
+
+    token = _command_token(stripped)
+    has_argument = len(stripped.split(maxsplit=1)) > 1
+    if token in _ALLOWED_ALWAYS:
+        return MidTurnAction.ALLOW
+    if token in _ALLOWED_BARE_ONLY and not has_argument:
+        return MidTurnAction.ALLOW
+    if token in _DEFERRED:
+        return MidTurnAction.DEFER
+    return MidTurnAction.BLOCK
+
+
+def defer_message(text: str) -> str:
+    """Explain that a state-changing command will run after this turn."""
+    token = _command_token(text) or "That command"
+    return f"{token} is staged and will apply when this turn finishes."
+
+
+def block_message(text: str) -> str:
+    """Explain why a submission is blocked and name the escape hatch."""
+    stripped = str(text or "").strip()
+    token = _command_token(stripped)
+
+    if stripped.lower() in EXIT_WORDS:
+        return f"Exit is unavailable while a turn is running. {_ESCAPE_HATCH}"
+    if token in _ALLOWED_BARE_ONLY:
+        reason = f"{token} with arguments changes what this turn is using"
+    else:
+        reason = _BLOCK_REASONS.get(token, _GENERIC_BLOCK_REASON)
+
+    label = token or "That"
+    return f"{label} is unavailable right now: {reason}. {_ESCAPE_HATCH}"

alysis_code/cli_impl/chat/rendering.py

@@ -0,0 +1,444 @@
+# ruff: noqa: F821
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from ...surface.styles import STYLE_CHROME, STYLE_CONTENT, STYLE_EMPHASIS
+
+_PROTECTED_RENDERING_GLOBAL_NAMES: set[str] = set()
+
+
+def _sync_rendering_globals(source_globals: dict[str, Any]) -> None:
+    module_globals = globals()
+    if not _PROTECTED_RENDERING_GLOBAL_NAMES:
+        for local_name, local_value in module_globals.items():
+            if callable(local_value):
+                _PROTECTED_RENDERING_GLOBAL_NAMES.add(local_name)
+    for name, value in source_globals.items():
+        if name.startswith("__") or name in _PROTECTED_RENDERING_GLOBAL_NAMES:
+            continue
+        module_globals[name] = value
+
+
+def _forge_plan_command_guidance_lines() -> tuple[str, ...]:
+    return (
+        "Chat Plan Mode is unavailable.",
+        "In Forge, use:",
+        "/back",
+        "Forge plan commands:",
+        "/show",
+        "/plan markdown",
+        "/plan edit",
+    )
+
+
+def _print_forge_plan_command_guidance(*, console: Any) -> None:
+    for line in _forge_plan_command_guidance_lines():
+        console.print(line)
+
+
+def _chat_skill_usage_lines() -> tuple[str, ...]:
+    return (
+        "[yellow]Usage:[/yellow] /skill",
+        "                 /skill <name>",
+        "                 /skill <name> <task>",
+    )
+
+
+def _artifact_display_ref(*, root: Path, store_obj: Any, artifact_path: Path | None) -> str:
+    if artifact_path is None:
+        return "-"
+    layout = getattr(store_obj, "session_artifact_layout", None)
+    display_fn = getattr(layout, "display_reference_for_path", None)
+    if callable(display_fn):
+        try:
+            return str(display_fn(artifact_path=artifact_path, workspace_root=root))
+        except Exception:  # noqa: BLE001
+            pass
+    try:
+        return artifact_path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return artifact_path.name
+
+
+def _render_planner_reply(
+    *, console: Any, message: str, questions: list[str] | None = None
+) -> None:
+    console.print("[bold]Planner:[/bold]")
+    console.print(message)
+    if questions:
+        console.print("[dim]Planner questions[/dim]")
+        for question in questions:
+            console.print(f"- {question}")
+
+
+def _render_labeled_chat_message(*, console: Any, label: str, message: str) -> None:
+    clean = str(message or "").strip() or "(empty message)"
+    prefix = ""
+    if label and str(label).strip().lower() not in {"you", "user"}:
+        prefix = f"{str(label).strip()} · "
+    console.print(
+        _forge_bar_text(
+            text=f"{prefix}{clean}",
+            style=STYLE_EMPHASIS,
+            bar_style=STYLE_EMPHASIS,
+        ),
+        highlight=False,
+    )
+
+
+def _render_plan_draft(*, console: Any, draft: str) -> None:
+    from rich.console import Group
+
+    clean = str(draft or "").strip() or "(empty plan)"
+    lines = [line.rstrip() for line in clean.splitlines() if line.strip()]
+    numbered_line_count = sum(1 for line in lines if re.match(r"^\s*\d+[\.\)]\s+", line))
+    header = "Plan (draft)"
+    if numbered_line_count > 0:
+        suffix = "step" if numbered_line_count == 1 else "steps"
+        header = f"{header}  {numbered_line_count} {suffix}"
+
+    renderables: list[Any] = [
+        _forge_bar_text(text=header, style=STYLE_EMPHASIS, bar_style=STYLE_CHROME)
+    ]
+    if not lines:
+        lines = ["(empty plan)"]
+    for line in lines:
+        renderables.append(
+            _forge_bar_text(
+                text=f"  {line}",
+                style=STYLE_CONTENT,
+                bar_style=STYLE_CHROME,
+            )
+        )
+    console.print(Group(*renderables), highlight=False)
+
+
+def _render_chat_plan_mode_status(*, console: Console, plan_mode_state: Any) -> None:
+    if _chat_plan_mode_enabled(plan_mode_state):
+        restore_mode = _chat_plan_mode_restore_mode(plan_mode_state) or "readonly"
+        console.print(
+            "Plan Mode: on "
+            f"(persistent readonly planning overlay; /plan <task> stays the default draft/review/approve path; restores {_chat_mode_display(restore_mode)} on /plan off)"
+        )
+        latest_task = _chat_plan_mode_latest_task(plan_mode_state)
+        latest_draft = _chat_plan_mode_latest_draft(plan_mode_state)
+        if latest_draft is None or latest_task is None:
+            console.print(
+                "Stored draft: none yet. Draft here with a normal chat message, or use /plan off then /plan <task> for the default execution path."
+            )
+            return
+        console.print(f"Stored task: {_chat_plan_task_preview(latest_task)}")
+        if restore_mode == "readonly":
+            console.print(
+                "Stored draft: captured, but exact /plan approve cannot execute because this overlay started from Read-Only mode."
+            )
+            return
+        console.print(
+            f"Stored draft: ready for exact /plan approve (leaves readonly planning, restores {_chat_mode_display(restore_mode)}, and executes)."
+        )
+        return
+    console.print("Plan Mode: off")
+
+
+def _print_chat_context(*, console: Console, session: Any) -> None:
+    context_fn = getattr(session, "context_left", None)
+    if not callable(context_fn):
+        console.print("Context tracking unavailable for this session.")
+        return
+    _refresh_chat_hud_context_cache(session)
+    ctx = getattr(session, "_hud_context_cache", None)
+    if ctx is None:
+        console.print("Context tracking unavailable for this session.")
+        return
+    context_window_tokens = getattr(
+        ctx,
+        "context_window_tokens",
+        getattr(ctx, "max_input_tokens", "n/a"),
+    )
+    context_window_remaining = getattr(
+        ctx,
+        "context_window_remaining_tokens",
+        getattr(ctx, "remaining_tokens", "n/a"),
+    )
+    context_window_percent = getattr(
+        ctx,
+        "context_window_percent_left",
+        getattr(ctx, "percent_left", None),
+    )
+    table = _Table(title="Context Window Left")
+    table.add_column("field")
+    table.add_column("value")
+    table.add_row("model", str(getattr(ctx, "model_name", "-")))
+    table.add_row("model_metadata_source", str(getattr(ctx, "source", "-")))
+    table.add_row(
+        "capacity_provider_key",
+        str(getattr(ctx, "capacity_provider_key", None) or "-"),
+    )
+    table.add_row(
+        "context_window_source",
+        str(getattr(ctx, "context_window_source", None) or "-"),
+    )
+    table.add_row(
+        "max_output_source",
+        str(getattr(ctx, "max_output_source", None) or "-"),
+    )
+    table.add_row("token_count_source", str(getattr(ctx, "token_count_source", "-")))
+    table.add_row(
+        "token_count_confidence",
+        str(getattr(ctx, "token_count_confidence", "-")),
+    )
+    anchor_source = getattr(ctx, "anchor_token_count_source", None)
+    if anchor_source:
+        table.add_row("request_anchor_source", str(anchor_source))
+        table.add_row(
+            "request_anchor_confidence",
+            str(getattr(ctx, "anchor_token_count_confidence", "-")),
+        )
+    table.add_row("context_window_tokens", str(context_window_tokens))
+    table.add_row(
+        "projected_total_request_tokens",
+        str(getattr(ctx, "used_input_tokens", "n/a")),
+    )
+    table.add_row(
+        "local_request_estimate_tokens",
+        str(getattr(ctx, "local_request_estimate_tokens", "n/a")),
+    )
+    table.add_row("context_window_left_tokens", str(context_window_remaining))
+    table.add_row(
+        "context_window_left_percent",
+        f"{float(context_window_percent):.1f}%" if context_window_percent is not None else "n/a",
+    )
+    console.print(table)
+
+    messages_obj = getattr(session, "messages", [])
+    messages = messages_obj if isinstance(messages_obj, list) else []
+    tool_list_obj = getattr(session, "tool_list", None)
+    tool_list = tool_list_obj if isinstance(tool_list_obj, list) else None
+    compactor = getattr(session, "conversation_compactor", None)
+    registry = getattr(session, "model_registry", None)
+    model_name = str(getattr(getattr(session, "client", None), "model", "") or "").strip()
+    if not model_name:
+        model_name = str(getattr(ctx, "model_name", "") or "").strip()
+
+    cfg = getattr(session, "cfg", None)
+    if isinstance(cfg, AppConfig):
+        compaction_settings = _resolve_compaction_settings(cfg)
+    else:
+        compaction_settings = _resolve_compaction_settings(AppConfig())
+
+    model_meta = None
+    if registry is not None and model_name:
+        try:
+            model_meta = registry.get(model_name)
+        except Exception:  # noqa: BLE001
+            model_meta = None
+
+    model_context_window_tokens = getattr(model_meta, "context_window_tokens", None)
+    max_output_tokens = getattr(model_meta, "max_output_tokens", None)
+    safety_margin_tokens = compaction_settings.safety_margin_tokens
+    effective_input_budget = (
+        getattr(ctx, "effective_input_budget", None)
+        or compute_input_budget(model_meta, safety_margin=safety_margin_tokens)
+        if model_meta is not None
+        else None
+    )
+
+    pinned_prefix_len = int(getattr(session, "pinned_prefix_len", 0) or 0)
+    if pinned_prefix_len <= 0 and compactor is not None and hasattr(compactor, "state"):
+        pinned_prefix_len = int(getattr(compactor.state, "pinned_prefix_len", 0) or 0)
+    if pinned_prefix_len <= 0:
+        for idx, msg in enumerate(messages):
+            if str(msg.get("role") or "") != "user":
+                continue
+            content = msg.get("content")
+            if isinstance(content, str) and content.startswith("<environment_context>"):
+                pinned_prefix_len = idx + 1
+                break
+
+    request_breakdown = estimate_request_token_breakdown(
+        messages=messages,
+        tool_list=tool_list,
+        pinned_prefix_len=pinned_prefix_len,
+    )
+    try:
+        total_request_tokens = max(0, int(getattr(ctx, "used_input_tokens", None)))
+    except (TypeError, ValueError):
+        total_request_tokens = request_breakdown.total_tokens
+    tokens_tools = max(0, int(getattr(request_breakdown, "tool_schema_tokens", 0) or 0))
+    if tokens_tools > total_request_tokens:
+        tokens_tools = total_request_tokens
+    tokens_messages = max(0, total_request_tokens - tokens_tools)
+    remaining_to_budget = getattr(ctx, "effective_remaining_tokens", None)
+    if remaining_to_budget is None and effective_input_budget is not None:
+        remaining_to_budget = max(0, effective_input_budget - total_request_tokens)
+    percent_budget_left = getattr(ctx, "effective_percent_left", None)
+    if (
+        percent_budget_left is None
+        and effective_input_budget is not None
+        and effective_input_budget > 0
+        and remaining_to_budget is not None
+    ):
+        percent_budget_left = (remaining_to_budget / effective_input_budget) * 100.0
+
+    budget_table = _Table(title="Effective Input Budget")
+    budget_table.add_column("field")
+    budget_table.add_column("value")
+    budget_table.add_row("context_window_tokens", str(model_context_window_tokens or "n/a"))
+    budget_table.add_row("max_output_tokens", str(max_output_tokens or "n/a"))
+    budget_table.add_row("safety_margin_tokens", str(safety_margin_tokens))
+    budget_table.add_row(
+        "effective_input_budget",
+        str(effective_input_budget) if effective_input_budget is not None else "n/a",
+    )
+    budget_table.add_row("estimated_messages_tokens", str(tokens_messages))
+    budget_table.add_row("estimated_tools_tokens", str(tokens_tools))
+    budget_table.add_row("estimated_total_request_tokens", str(total_request_tokens))
+    budget_table.add_row(
+        "remaining_to_budget",
+        str(remaining_to_budget) if remaining_to_budget is not None else "n/a",
+    )
+    budget_table.add_row(
+        "percent_budget_left",
+        f"{percent_budget_left:.1f}%" if percent_budget_left is not None else "n/a",
+    )
+    console.print(budget_table)
+
+    dynamic_percent_left = getattr(ctx, "dynamic_context_percent_left", None)
+    dynamic_table = _Table(title="Conversation Context Left")
+    dynamic_table.add_column("field")
+    dynamic_table.add_column("value")
+    dynamic_table.add_row(
+        "startup_baseline_tokens",
+        str(getattr(ctx, "startup_baseline_tokens", "n/a")),
+    )
+    dynamic_table.add_row(
+        "dynamic_context_budget_tokens",
+        str(getattr(ctx, "dynamic_context_budget_tokens", "n/a")),
+    )
+    dynamic_table.add_row(
+        "dynamic_context_used_tokens",
+        str(getattr(ctx, "dynamic_context_used_tokens", "n/a")),
+    )
+    dynamic_table.add_row(
+        "dynamic_context_left_tokens",
+        str(getattr(ctx, "dynamic_context_remaining_tokens", "n/a")),
+    )
+    dynamic_table.add_row(
+        "dynamic_context_left_percent",
+        f"{dynamic_percent_left:.1f}%" if dynamic_percent_left is not None else "n/a",
+    )
+    console.print(dynamic_table)
+
+    if effective_input_budget is not None and total_request_tokens > effective_input_budget:
+        console.print(
+            "[yellow]Request estimate exceeds effective input budget.[/yellow] "
+            "Run /compact to reduce context."
+        )
+
+    sanitized_messages = _sanitize_messages_for_estimation(messages)
+    pinned_messages: list[dict[str, Any]] = []
+    memory_messages: list[dict[str, Any]] = []
+    pins_messages: list[dict[str, Any]] = []
+    conversation_messages: list[dict[str, Any]] = []
+    for idx, msg in enumerate(sanitized_messages):
+        if idx < pinned_prefix_len:
+            pinned_messages.append(msg)
+            continue
+        content = msg.get("content")
+        if isinstance(content, str) and content.startswith(_memory_marker()):
+            memory_messages.append(msg)
+            continue
+        if isinstance(content, str) and content.startswith(_pins_marker()):
+            pins_messages.append(msg)
+            continue
+        conversation_messages.append(msg)
+
+    def _bucket_tokens(bucket: list[dict[str, Any]]) -> int:
+        if not bucket:
+            return 0
+        return estimate_tokens(json.dumps(bucket, ensure_ascii=False, sort_keys=True))
+
+    pinned_tokens = _bucket_tokens(pinned_messages)
+    memory_tokens = _bucket_tokens(memory_messages)
+    pins_tokens = _bucket_tokens(pins_messages)
+    conversation_tokens = _bucket_tokens(conversation_messages)
+
+    breakdown_table = _Table(title="Context Breakdown")
+    breakdown_table.add_column("field")
+    breakdown_table.add_column("value")
+    breakdown_table.add_row("pinned_prefix_tokens", str(pinned_tokens))
+    breakdown_table.add_row("memory_tokens", str(memory_tokens))
+    breakdown_table.add_row("pins_tokens", str(pins_tokens))
+    breakdown_table.add_row("conversation_tokens", str(conversation_tokens))
+    breakdown_table.add_row("total_messages_count", str(len(messages)))
+    console.print(breakdown_table)
+
+    root = Path(getattr(session, "root", Path(".")))
+    store_obj = getattr(session, "store", None)
+    session_id = str(getattr(store_obj, "session_id", "") or "")
+    history_session_dir = None
+    if compactor is not None and hasattr(compactor, "history_dir"):
+        history_dir_obj = getattr(compactor, "history_dir", None)
+        if isinstance(history_dir_obj, Path):
+            history_session_dir = history_dir_obj.parent
+    if history_session_dir is None and session_id:
+        history_session_dir = root / ".alysis" / "sessions" / _safe_component(session_id)
+    tool_output_session_dir = getattr(store_obj, "session_artifact_root", None)
+    history_chunks_count = 0
+    offloaded_tool_outputs_count = 0
+    summary_exists = False
+    pins_file_exists = False
+    if history_session_dir is not None:
+        history_chunks_count = len(list((history_session_dir / "history").glob("chunk_*.jsonl")))
+        summary_exists = (history_session_dir / "memory" / "summary.json").exists()
+        pins_file_exists = (history_session_dir / "memory" / "pins.json").exists()
+    if (
+        history_session_dir is not None
+        and session_id
+        and history_chunks_count == 0
+        and not summary_exists
+        and not pins_file_exists
+    ):
+        legacy_history_session_dir = root / ".alysis" / "sessions" / _safe_component(session_id)
+        if legacy_history_session_dir != history_session_dir:
+            history_chunks_count = len(
+                list((legacy_history_session_dir / "history").glob("chunk_*.jsonl"))
+            )
+            summary_exists = (legacy_history_session_dir / "memory" / "summary.json").exists()
+            pins_file_exists = (legacy_history_session_dir / "memory" / "pins.json").exists()
+    if isinstance(tool_output_session_dir, Path):
+        offloaded_tool_outputs_count = len(
+            list((tool_output_session_dir / "tool_outputs").glob("*.json"))
+        )
+
+    pins_count = 0
+    if compactor is not None and hasattr(compactor, "state"):
+        history_chunks_count = max(
+            history_chunks_count,
+            int(getattr(compactor.state, "history_chunk_index", 0) or 0),
+        )
+        pins = getattr(compactor.state, "pins", [])
+        if isinstance(pins, list):
+            pins_count = len(pins)
+
+    compaction_table = _Table(title="Compaction Artifacts")
+    compaction_table.add_column("field")
+    compaction_table.add_column("value")
+    compaction_table.add_row("compaction_enabled", "yes" if compactor is not None else "no")
+    compaction_table.add_row(
+        "compaction_profile",
+        str(getattr(compactor, "profile_name", "-")) if compactor is not None else "-",
+    )
+    compaction_table.add_row(
+        "compactor_model",
+        str(getattr(getattr(compactor, "compactor_client", None), "model", "-")),
+    )
+    compaction_table.add_row("history_chunks_count", str(history_chunks_count))
+    compaction_table.add_row("pins_count", str(pins_count))
+    compaction_table.add_row("offloaded_tool_outputs_count", str(offloaded_tool_outputs_count))
+    compaction_table.add_row("summary_file_exists", "yes" if summary_exists else "no")
+    compaction_table.add_row("pins_file_exists", "yes" if pins_file_exists else "no")
+    console.print(compaction_table)

alysis_code/cli_impl/chat/state.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ...config import AppConfig
+from ...forge import RunPaths
+from ...plan_repair import ClarificationLoopTracker
+
+
+@dataclass
+class _ForgePlannerSessionState:
+    transcript: list[dict[str, str]] = field(default_factory=list)
+    cfg: AppConfig | None = None
+    workspace_context: dict[str, Any] | None = None
+    awaiting_clarification: bool = False
+    pending_questions: list[str] = field(default_factory=list)
+    # Consecutive clarification-only planner turns for the current goal. Past the
+    # policy cap the planner is made to draft a plan instead of asking again.
+    clarification_loop: ClarificationLoopTracker = field(default_factory=ClarificationLoopTracker)
+
+
+@dataclass(frozen=True)
+class _ForgeEnterCommand:
+    entry_mode: str
+    initial_goal: str = ""
+    usage_error: str | None = None
+    # Explicit plan-assistant choice carried by the ``/forge --planner`` /
+    # ``/forge --no-planner`` forms (emitted by the TUI intro popup's native
+    # "Use the planner?" prompt, and usable directly). ``None`` means "no
+    # explicit choice" — the caller falls back to its own default.
+    planner_assistant_default: bool | None = None
+
+
+@dataclass(frozen=True)
+class _ForgeChatEntrySelection:
+    paths: RunPaths
+    plan: dict[str, Any]
+    entry_kind: str
+
+
+@dataclass
+class _ForgeChatState:
+    ui_mode: str = "chat"
+    paths: RunPaths | None = None
+    plan: dict[str, Any] | None = None
+    assistant_enabled: bool = False
+    entry_request_mode: str = "plain"
+    entry_goal: str = ""
+    planner_session: _ForgePlannerSessionState = field(default_factory=_ForgePlannerSessionState)
+    # Swarm knobs chosen in the TUI launch gate (``/execute plan``), read by the
+    # ``/execute`` command handler when present. Empty dict → the handler's own
+    # defaults apply (so the classic, non-TUI path is unchanged). Recognised keys:
+    # ``parallel`` (int), ``scope_mode`` ("strict"|"warn"), ``verify_mode``
+    # ("warn"|"strict"|"off"), ``review`` (bool).
+    swarm_knobs: dict[str, Any] = field(default_factory=dict)
+    # True once the current ``/execute plan`` invocation actually reached
+    # ``run_swarm`` (reset at the top of each invocation). Lets the TUI worker
+    # distinguish "the handler rejected the execute before anything ran" from
+    # "a swarm ran" when finalizing the live forge view.
+    swarm_run_attempted: bool = False
+
+    @property
+    def planner_transcript(self) -> list[dict[str, str]]:
+        return self.planner_session.transcript
+
+    @planner_transcript.setter
+    def planner_transcript(self, value: list[dict[str, str]]) -> None:
+        self.planner_session.transcript = list(value)
+
+    @property
+    def planner_cfg(self) -> AppConfig | None:
+        return self.planner_session.cfg
+
+    @planner_cfg.setter
+    def planner_cfg(self, value: AppConfig | None) -> None:
+        self.planner_session.cfg = value
+
+    @property
+    def workspace_context(self) -> dict[str, Any] | None:
+        return self.planner_session.workspace_context
+
+    @workspace_context.setter
+    def workspace_context(self, value: dict[str, Any] | None) -> None:
+        self.planner_session.workspace_context = value
+
+    @property
+    def planner_awaiting_clarification(self) -> bool:
+        return bool(self.planner_session.awaiting_clarification)
+
+    @planner_awaiting_clarification.setter
+    def planner_awaiting_clarification(self, value: bool) -> None:
+        self.planner_session.awaiting_clarification = bool(value)
+
+    @property
+    def planner_pending_questions(self) -> list[str]:
+        return self.planner_session.pending_questions
+
+    @planner_pending_questions.setter
+    def planner_pending_questions(self, value: list[str]) -> None:
+        self.planner_session.pending_questions = list(value)
+
+
+@dataclass
+class _ChatPlanModeState:
+    enabled: bool = False
+    restore_mode: str | None = None
+    latest_task: str | None = None
+    latest_draft: str | None = None
+
+
+@dataclass(frozen=True)
+class _ChatExecutionRequest:
+    instruction: str
+    routing_mode_override: str | None = None
+    ephemeral_system_messages: tuple[str, ...] = ()
+    ephemeral_user_messages: tuple[str, ...] = ()
+    mode_override: str | None = None
+    restore_mode_after: str | None = None
+    plan_mode_capture_task: str | None = None
+    chat_only: bool = False
+
+
+__all__ = [name for name in globals() if not name.startswith("__") or name == "__version__"]