induscode 0.1.0__py3-none-any.whl

induscode/console/contract.py

@@ -0,0 +1,836 @@
+"""Console contract — the FROZEN type surface of the interactive terminal shell.
+
+Port of TS ``src/console/contract.ts``. This module is the single typed seam
+between the coding-agent *product* and the Textual front-end that drives a
+session from a live terminal. It declares *only* shapes plus a handful of tiny
+inert helpers (a scheme-name guard, a fresh empty-state constant, and a pure
+modal transition) — no rendering, no key handlers, no I/O. Every later console
+module (the reducer, the theme engine, the startup gatherer, and the M5-wave-2
+``ConsoleApp`` surface) is written against the names declared here, so the
+file is intentionally small, append-mostly, and stable.
+
+Design stance — the shell is *wiring*, not widgets:
+
+1. **One immutable reducer state.** The terminal surface's UI-local state is
+   reduced from a single :class:`ConsoleState` value mutated only through a
+   :data:`ConsoleEvent` action union dispatched into
+   :func:`induscode.console.reducer.console_reducer`. The discriminants are
+   the console's own ``domain:verb`` vocabulary, kept verbatim from TS.
+2. **A data-driven slash registry.** Slash commands are rows in a
+   :class:`SlashRegistry`, never an ``if``-ladder — the whole slash framework
+   already landed as :mod:`induscode.console_slash` (M1) and is re-exported
+   here so console consumers import one surface.
+3. **Theme behind the framework adapter.** The console speaks in semantic
+   :class:`ThemeTokens`; the concrete terminal colours are produced once, at
+   the config-load boundary, by mapping a :class:`ThemePalette` through the
+   framework ``create_theme_bundle``. The accent ramp is the console's own.
+4. **The console drives a conductor.** :class:`ConsoleProps` carries a
+   ``SessionConductor``; the surface subscribes to its ``SessionSignal``
+   stream and renders its ``ConductorState``. The conductor surface is the
+   runtime contract and is never re-declared here.
+
+Port deltas (locked by the port plan, analysis 02 §7):
+
+- **Composer buffer / caret / history are GONE.** The TS reducer owned a
+  hand-rolled single-line editor (``buffer``/``caret``/``history``/
+  ``historyAt``/``stash`` state; ``buffer:*``/``caret:*``/``history:*``
+  events). The Python build delegates all of that to the framework's
+  ``EditorCore``-backed ``PromptEditor``, so :class:`ConsoleState` keeps only
+  the rows/blocks/modal/status/scheme/toggles/busy slices and the event union
+  drops the editor families.
+- **``Themed`` / ``RenderSlot`` are dropped** — Textual CSS variables and
+  ``compose()`` replace the per-component theme prop and the ReactNode slot.
+- ``ConsoleEventOf`` (TS type-level extraction) is replaced by the
+  :data:`CONSOLE_EVENT_TYPES` tuple plus a reducer key-coverage test, per the
+  cross-cutting exhaustiveness rule.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import ClassVar, Final, Literal, Protocol, TypeAlias, TypeGuard
+
+from indusagi.react_ink import (
+    InkThemeAdapter,
+    SessionSnapshot,
+    StatusMessage,
+    ThemeBundle,
+    ToolExecutionState,
+    UiDisplayBlock,
+)
+
+from induscode.conductor import ConductorState, SessionConductor, SessionSignal
+from induscode.console_slash import (
+    Handled,
+    OpenModal,
+    Prompt,
+    SlashCommand,
+    SlashContext,
+    SlashOutcome,
+    SlashRegistry,
+    SlashRun,
+    Unknown,
+)
+from induscode.launch import (
+    AuthVault,
+    LoginProvider,
+    OAuthLoginCallbacks,
+    OAuthLoginResult,
+)
+from induscode.sessions import SessionLibrary
+from induscode.settings import PreferenceStore
+
+__all__ = [
+    "BlockAppend",
+    "BlocksClear",
+    "BusySet",
+    "CONSOLE_EVENT_TYPES",
+    "ConductorState",
+    "ConsoleDispatch",
+    "ConsoleEvent",
+    "ConsoleEventType",
+    "ConsoleHost",
+    "ConsoleProps",
+    "ConsoleReducer",
+    "ConsoleState",
+    "ConsoleTheme",
+    "DEFAULT_SCHEME",
+    "EMPTY_CONSOLE_STATE",
+    "Handled",
+    "InkThemeAdapter",
+    "MODAL_KINDS",
+    "ModalClose",
+    "ModalKind",
+    "ModalOpen",
+    "ModalState",
+    "NO_MODAL",
+    "OpenModal",
+    "OverlayServices",
+    "Prompt",
+    "RowsAppend",
+    "RowsPatch",
+    "RowsSet",
+    "SchemeSet",
+    "SessionConductor",
+    "SessionSignal",
+    "SessionSnapshot",
+    "SlashCommand",
+    "SlashContext",
+    "SlashOutcome",
+    "SlashRegistry",
+    "SlashRun",
+    "StartOAuthLogin",
+    "StatusClear",
+    "StatusMessage",
+    "StatusSet",
+    "THEME_TOKEN_ROLES",
+    "ThemePalette",
+    "ThemeScheme",
+    "ThemeToken",
+    "ThemeTokens",
+    "Tick",
+    "ToggleImages",
+    "ToggleReasoning",
+    "ToolExecutionState",
+    "UiDisplayBlock",
+    "Unknown",
+    "ViewRow",
+    "ViewRowKind",
+    "is_theme_scheme",
+    "transition_modal",
+]
+
+
+# ---------------------------------------------------------------------------
+# Theme — schemes, semantic tokens, and the accent palette
+# ---------------------------------------------------------------------------
+
+#: The built-in colour schemes the console ships with.
+#:
+#: Named for the time-of-day they evoke rather than a bare light/dark axis,
+#: with a daltonized (color-blind-friendly) variant of each:
+#:
+#: - ``midnight``    — a low-luminance scheme for dark terminals.
+#: - ``daylight``    — a high-luminance scheme for light terminals.
+#: - ``midnight-cb`` — the dark scheme re-derived so success vs failure
+#:   separates off the red-green axis (success → blue), deuteran/protan-safe.
+#: - ``daylight-cb`` — the light scheme's color-blind-safe counterpart.
+ThemeScheme: TypeAlias = Literal["midnight", "daylight", "midnight-cb", "daylight-cb"]
+
+#: The default scheme applied before any user preference is loaded.
+DEFAULT_SCHEME: Final[ThemeScheme] = "midnight"
+
+#: The closed scheme-name set the guard validates against.
+_SCHEME_NAMES: Final[frozenset[str]] = frozenset(
+    {"midnight", "daylight", "midnight-cb", "daylight-cb"}
+)
+
+
+def is_theme_scheme(value: str) -> TypeGuard[ThemeScheme]:
+    """Narrow an arbitrary string to a known :data:`ThemeScheme`.
+
+    The single sanctioned guard for scheme names, so every loader validates
+    the same way. Returns ``True`` only for a recognised scheme literal.
+
+    :param value: any candidate string read from settings or a slash argument
+    """
+    return value in _SCHEME_NAMES
+
+
+@dataclass(frozen=True, slots=True)
+class ThemeTokens:
+    """The semantic colour/style tokens the console renders in.
+
+    These are *roles*, not literals: a component asks for ``frame`` or
+    ``signal``, never a hex code. Each token is resolved to a concrete colour
+    by the framework :class:`~indusagi.react_ink.InkThemeAdapter` at the
+    boundary; the console body never touches a hex value directly. The token
+    set is closed (a frozen dataclass), so a scheme that omits one fails at
+    construction rather than rendering an undefined colour.
+    """
+
+    # The primary accent (active prompt, selection, focus).
+    signal: str
+    # Default panel/border lines and structural chrome.
+    frame: str
+    # De-emphasised borders and separators.
+    quiet_frame: str
+    # The composer's active background tint.
+    prompt_surface: str
+    # Accent applied to message-row gutters and headers.
+    card_accent: str
+    # Default foreground for assistant/answer text.
+    body_text: str
+    # Secondary/metadata text (timestamps, hints).
+    muted_text: str
+    # High-contrast text on an accented surface.
+    ink_text: str
+    # Informational status tone.
+    notice: str
+    # Success status tone.
+    affirm: str
+    # Warning status tone.
+    caution: str
+    # Error/fault status tone.
+    alarm: str
+    # Busy/in-flight status tone.
+    pending: str
+    # Rich-render roles (markdown / diff / syntax highlighting). These feed
+    # the framework adapter's markdown/diff/highlight accessors so the styled
+    # transcript, colored diffs, and fenced-code highlighting recolor for
+    # free with each scheme.
+    # Inline ``code`` foreground.
+    code_inline: str
+    # Markdown heading foreground.
+    heading: str
+    # The dim bar drawn beside a blockquote.
+    blockquote_bar: str
+    # Background tint for an added (``+``) diff line.
+    diff_added_bg: str
+    # Background tint for a removed (``-``) diff line.
+    diff_removed_bg: str
+    # Foreground for added-line content / ``+`` marker.
+    diff_added_text: str
+    # Foreground for removed-line content / ``-`` marker.
+    diff_removed_text: str
+    # Syntax scope: keywords.
+    syn_keyword: str
+    # Syntax scope: string literals.
+    syn_string: str
+    # Syntax scope: numeric literals.
+    syn_number: str
+    # Syntax scope: comments.
+    syn_comment: str
+    # Syntax scope: types / classes / built-ins.
+    syn_type: str
+
+
+#: One token role name (TS ``ThemeToken = keyof ThemeTokens``).
+ThemeToken: TypeAlias = Literal[
+    "signal",
+    "frame",
+    "quiet_frame",
+    "prompt_surface",
+    "card_accent",
+    "body_text",
+    "muted_text",
+    "ink_text",
+    "notice",
+    "affirm",
+    "caution",
+    "alarm",
+    "pending",
+    "code_inline",
+    "heading",
+    "blockquote_bar",
+    "diff_added_bg",
+    "diff_removed_bg",
+    "diff_added_text",
+    "diff_removed_text",
+    "syn_keyword",
+    "syn_string",
+    "syn_number",
+    "syn_comment",
+    "syn_type",
+]
+
+#: The closed set of token role names, for iteration and validation (the
+#: Python stand-in for TS ``keyof`` — tests fold over this).
+THEME_TOKEN_ROLES: Final[tuple[ThemeToken, ...]] = (
+    "signal",
+    "frame",
+    "quiet_frame",
+    "prompt_surface",
+    "card_accent",
+    "body_text",
+    "muted_text",
+    "ink_text",
+    "notice",
+    "affirm",
+    "caution",
+    "alarm",
+    "pending",
+    "code_inline",
+    "heading",
+    "blockquote_bar",
+    "diff_added_bg",
+    "diff_removed_bg",
+    "diff_added_text",
+    "diff_removed_text",
+    "syn_keyword",
+    "syn_string",
+    "syn_number",
+    "syn_comment",
+    "syn_type",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ThemePalette:
+    """The accent ramp a scheme is derived from — the console's own hex values.
+
+    A palette is the small raw-colour source from which the full
+    :class:`ThemeTokens` map is computed at load time. These nine stops are an
+    original ramp (re-derived for this console; they intentionally do not
+    reuse any upstream accent values) spanning a cool primary, a warm
+    secondary, and a neutral text gradient. The boundary adapter expands them
+    into the semantic token map and hands the result to the framework
+    ``create_theme_bundle``.
+    """
+
+    # Primary accent — the dominant cool hue.
+    primary: str
+    # Secondary accent — a complementary warm hue.
+    secondary: str
+    # Tertiary accent — a muted support hue.
+    tertiary: str
+    # Brightest neutral — high-contrast text.
+    ink: str
+    # Mid neutral — default body text.
+    body: str
+    # Dim neutral — secondary/metadata text.
+    muted: str
+    # Success hue.
+    affirm: str
+    # Warning hue.
+    caution: str
+    # Error hue.
+    alarm: str
+
+
+@dataclass(frozen=True, slots=True)
+class ConsoleTheme:
+    """A fully resolved scheme: identity, raw ramp, and the semantic token map
+    the console renders in.
+
+    The ``tokens`` are derived from ``palette`` at load time; ``bundle`` is
+    the framework projection produced from those tokens — the Rich-painting
+    adapter **plus** the registered Textual ``Theme`` and the Pygments style
+    (the Python boundary is ``create_theme_bundle``, not the bare adapter).
+    A scheme is the unit the theme picker selects.
+    """
+
+    # Which scheme this resolves.
+    scheme: ThemeScheme
+    # The raw accent ramp this scheme was derived from.
+    palette: ThemePalette
+    # The semantic token map components render against.
+    tokens: ThemeTokens
+    # The framework adapter that turns token roles into terminal colours.
+    adapter: InkThemeAdapter
+    # The full framework bundle: adapter + Textual Theme + Pygments style.
+    bundle: ThemeBundle
+
+
+# ---------------------------------------------------------------------------
+# Transcript view rows
+# ---------------------------------------------------------------------------
+
+#: The discriminant of a single rendered transcript row.
+#:
+#: The console renders its scrollback as a flat list of typed rows rather
+#: than a single message blob, so each kind can be width-packed and themed
+#: independently:
+#:
+#: - ``prompt``  — a user-submitted turn.
+#: - ``answer``  — streamed assistant answer text.
+#: - ``reason``  — streamed reasoning/thinking text (shown only when enabled).
+#: - ``toolRun`` — a tool invocation row, correlated by ``run_id``.
+#: - ``notice``  — an out-of-band notice (changelog, status, system note).
+ViewRowKind: TypeAlias = Literal["prompt", "answer", "reason", "toolRun", "notice"]
+
+
+@dataclass(frozen=True, slots=True)
+class ViewRow:
+    """One immutable row in the transcript view.
+
+    Rows are append-mostly and identity-stable: a streaming
+    ``answer``/``reason`` row keeps its ``id`` while its ``text`` grows, so
+    the renderer can reconcile in place. ``run_id`` correlates a ``toolRun``
+    row with its :class:`~indusagi.react_ink.ToolExecutionState` entry.
+    """
+
+    # Stable unique row id.
+    id: str
+    # Which kind of row this is.
+    kind: ViewRowKind
+    # The row's display text (may be partial while streaming).
+    text: str
+    # Tool-run correlation id, present only for ``toolRun`` rows.
+    run_id: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Modal / overlay state
+# ---------------------------------------------------------------------------
+
+#: The closed set of modal overlays the console can raise over the transcript.
+#:
+#: Exactly one modal is active at a time (or ``none``). The surface renders
+#: the matching framework dialog from a table keyed by this discriminant
+#: rather than a hand-written switch:
+#:
+#: - ``none``         — no overlay; the composer has focus.
+#: - ``settings``     — the settings list.
+#: - ``models``       — the single-model picker.
+#: - ``scopedModels`` — the per-scope model picker.
+#: - ``theme``        — the scheme picker.
+#: - ``sessions``     — the session resume/list picker.
+#: - ``tree``         — the transcript-tree navigator.
+#: - ``userTurns``    — the prior-user-turn picker (for branching/forking).
+#: - ``signIn``       — the provider sign-in launcher.
+#: - ``signOut``      — the provider sign-out confirmation.
+#: - ``oauth``        — the in-flight OAuth device/redirect flow.
+#: - ``plugin``       — a plugin-supplied select/confirm/input/custom overlay.
+ModalKind: TypeAlias = Literal[
+    "none",
+    "settings",
+    "models",
+    "scopedModels",
+    "theme",
+    "sessions",
+    "tree",
+    "userTurns",
+    "signIn",
+    "signOut",
+    "oauth",
+    "plugin",
+]
+
+#: The closed modal-kind set, for the overlay dispatch table and its
+#: key-coverage test (TS relied on union exhaustiveness).
+MODAL_KINDS: Final[tuple[ModalKind, ...]] = (
+    "none",
+    "settings",
+    "models",
+    "scopedModels",
+    "theme",
+    "sessions",
+    "tree",
+    "userTurns",
+    "signIn",
+    "signOut",
+    "oauth",
+    "plugin",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ModalState:
+    """The active modal plus any opaque payload the matching dialog needs.
+
+    ``payload`` is deliberately untyped at the contract layer: each dialog
+    narrows it at its own boundary (e.g. the OAuth flow state, a plugin
+    overlay request). ``none`` carries no payload.
+    """
+
+    # Which overlay is currently raised.
+    kind: ModalKind
+    # Opaque per-modal payload, narrowed by the rendering dialog.
+    payload: object | None = None
+
+
+#: The inert "no overlay" modal state.
+NO_MODAL: Final[ModalState] = ModalState(kind="none")
+
+
+def transition_modal(next_kind: ModalKind, payload: object | None = None) -> ModalState:
+    """Compute the next :class:`ModalState` for a requested transition.
+
+    A pure, inert helper so the open/close/replace logic lives in one place
+    rather than being re-derived per call site. Opening any kind other than
+    ``none`` raises that overlay (carrying the optional payload); opening
+    ``none`` (or closing) returns :data:`NO_MODAL`.
+
+    :param next_kind: the modal kind to transition to
+    :param payload: optional payload for the target overlay
+    """
+    if next_kind == "none":
+        return NO_MODAL
+    return ModalState(kind=next_kind, payload=payload)
+
+
+# ---------------------------------------------------------------------------
+# The reducer state
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ConsoleState:
+    """The immutable UI-local state the terminal surface is reduced from.
+
+    Every observable UI-local property of the console — what is on screen,
+    which overlay is up, and the display toggles — is one read-only field
+    here. The surface holds exactly one of these and never mutates it in
+    place; a :data:`ConsoleEvent` produces a fresh value. Live session data
+    (messages, usage, model) is *not* stored here — it is projected from the
+    conductor snapshot — and the composer text/caret/history live in the
+    framework editor (``EditorCore``), not in this state (port delta; see the
+    module docstring).
+    """
+
+    # The rendered transcript, newest row last.
+    rows: tuple[ViewRow, ...] = ()
+    # Out-of-band display blocks (changelog, etc.) interleaved with the rows.
+    blocks: tuple[UiDisplayBlock, ...] = ()
+    # The active modal overlay.
+    modal: ModalState = NO_MODAL
+    # The transient status line, when one is showing.
+    status: StatusMessage | None = None
+    # The active colour scheme.
+    scheme: ThemeScheme = DEFAULT_SCHEME
+    # Whether reasoning/thinking rows are shown.
+    show_reasoning: bool = False
+    # Whether inline images are rendered.
+    show_images: bool = True
+    # Whether a turn is in flight (input disabled / spinner shown).
+    busy: bool = False
+    # Monotonic tick that forces a status-bar re-render on data change.
+    tick: int = 0
+
+
+#: The freshly-seeded :class:`ConsoleState` a session opens with.
+#:
+#: A pure constant (no session data baked in) so the initial render is
+#: deterministic and the store can be re-seeded without consulting any
+#: runtime. Loaders overlay user preferences (scheme, toggles) on top of this
+#: base via :func:`induscode.console.reducer.init_console_state`.
+EMPTY_CONSOLE_STATE: Final[ConsoleState] = ConsoleState()
+
+
+# ---------------------------------------------------------------------------
+# The reducer event union
+# ---------------------------------------------------------------------------
+#
+# The closed action union the console reducer folds over ConsoleState. The
+# discriminants are the console's own ``domain:verb`` vocabulary, kept
+# verbatim from TS. The TS composer families (``buffer:*``, ``caret:*``,
+# ``history:*``) are dropped — the framework EditorCore owns those (port
+# delta; see the module docstring). Grouped by the slice each touches:
+#
+#   Transcript view
+#     - ``rows:set``       — replace the whole row list.
+#     - ``rows:append``    — append one row.
+#     - ``rows:patch``     — replace the text of the row matching an id.
+#     - ``block:append``   — append a display block.
+#     - ``blocks:clear``   — drop every display block (e.g. on a new session).
+#
+#   Overlays, status, theme, toggles, busy
+#     - ``modal:open``       — raise an overlay (with optional payload).
+#     - ``modal:close``      — drop back to the composer.
+#     - ``status:set``       — show a transient status message.
+#     - ``status:clear``     — clear the status line.
+#     - ``scheme:set``       — switch the active colour scheme.
+#     - ``toggle:reasoning`` — flip reasoning-row visibility.
+#     - ``toggle:images``    — flip inline-image rendering.
+#     - ``busy:set``         — set the in-flight flag.
+#     - ``tick``             — bump the status-bar re-render tick.
+
+
+@dataclass(frozen=True, slots=True)
+class RowsSet:
+    """Replace the whole row list."""
+
+    type: ClassVar[Literal["rows:set"]] = "rows:set"
+    rows: tuple[ViewRow, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class RowsAppend:
+    """Append one row."""
+
+    type: ClassVar[Literal["rows:append"]] = "rows:append"
+    row: ViewRow
+
+
+@dataclass(frozen=True, slots=True)
+class RowsPatch:
+    """Replace the text of the row matching ``id``."""
+
+    type: ClassVar[Literal["rows:patch"]] = "rows:patch"
+    id: str
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class BlockAppend:
+    """Append a display block."""
+
+    type: ClassVar[Literal["block:append"]] = "block:append"
+    block: UiDisplayBlock
+
+
+@dataclass(frozen=True, slots=True)
+class BlocksClear:
+    """Drop every display block (e.g. on a new session)."""
+
+    type: ClassVar[Literal["blocks:clear"]] = "blocks:clear"
+
+
+@dataclass(frozen=True, slots=True)
+class ModalOpen:
+    """Raise an overlay (with optional payload)."""
+
+    type: ClassVar[Literal["modal:open"]] = "modal:open"
+    kind: ModalKind
+    payload: object | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ModalClose:
+    """Drop back to the composer."""
+
+    type: ClassVar[Literal["modal:close"]] = "modal:close"
+
+
+@dataclass(frozen=True, slots=True)
+class StatusSet:
+    """Show a transient status message."""
+
+    type: ClassVar[Literal["status:set"]] = "status:set"
+    status: StatusMessage
+
+
+@dataclass(frozen=True, slots=True)
+class StatusClear:
+    """Clear the status line."""
+
+    type: ClassVar[Literal["status:clear"]] = "status:clear"
+
+
+@dataclass(frozen=True, slots=True)
+class SchemeSet:
+    """Switch the active colour scheme."""
+
+    type: ClassVar[Literal["scheme:set"]] = "scheme:set"
+    scheme: ThemeScheme
+
+
+@dataclass(frozen=True, slots=True)
+class ToggleReasoning:
+    """Flip reasoning-row visibility."""
+
+    type: ClassVar[Literal["toggle:reasoning"]] = "toggle:reasoning"
+
+
+@dataclass(frozen=True, slots=True)
+class ToggleImages:
+    """Flip inline-image rendering."""
+
+    type: ClassVar[Literal["toggle:images"]] = "toggle:images"
+
+
+@dataclass(frozen=True, slots=True)
+class BusySet:
+    """Set the in-flight flag."""
+
+    type: ClassVar[Literal["busy:set"]] = "busy:set"
+    busy: bool
+
+
+@dataclass(frozen=True, slots=True)
+class Tick:
+    """Bump the status-bar re-render tick."""
+
+    type: ClassVar[Literal["tick"]] = "tick"
+
+
+#: The closed action union the console reducer folds over ConsoleState.
+ConsoleEvent: TypeAlias = (
+    RowsSet
+    | RowsAppend
+    | RowsPatch
+    | BlockAppend
+    | BlocksClear
+    | ModalOpen
+    | ModalClose
+    | StatusSet
+    | StatusClear
+    | SchemeSet
+    | ToggleReasoning
+    | ToggleImages
+    | BusySet
+    | Tick
+)
+
+#: The discriminant literals of :data:`ConsoleEvent`, for filtering/logging.
+ConsoleEventType: TypeAlias = Literal[
+    "rows:set",
+    "rows:append",
+    "rows:patch",
+    "block:append",
+    "blocks:clear",
+    "modal:open",
+    "modal:close",
+    "status:set",
+    "status:clear",
+    "scheme:set",
+    "toggle:reasoning",
+    "toggle:images",
+    "busy:set",
+    "tick",
+]
+
+#: Every event discriminant, in declaration order — the reducer key-coverage
+#: test folds one event of each tag through the reducer (the Python analogue
+#: of TS union exhaustiveness; cross-cutting rule 1).
+CONSOLE_EVENT_TYPES: Final[tuple[ConsoleEventType, ...]] = (
+    "rows:set",
+    "rows:append",
+    "rows:patch",
+    "block:append",
+    "blocks:clear",
+    "modal:open",
+    "modal:close",
+    "status:set",
+    "status:clear",
+    "scheme:set",
+    "toggle:reasoning",
+    "toggle:images",
+    "busy:set",
+    "tick",
+)
+
+#: The reducer signature the console store is built from.
+ConsoleReducer: TypeAlias = Callable[[ConsoleState, ConsoleEvent], ConsoleState]
+
+#: The bound dispatch function the surface threads to its children.
+ConsoleDispatch: TypeAlias = Callable[[ConsoleEvent], None]
+
+
+# ---------------------------------------------------------------------------
+# The console host props
+# ---------------------------------------------------------------------------
+
+
+class StartOAuthLogin(Protocol):
+    """Drive a provider's browser sign-in and persist the result through the
+    vault: ``await start_oauth_login(provider_id, callbacks, vault, account)``.
+    """
+
+    def __call__(
+        self,
+        provider_id: str,
+        callbacks: OAuthLoginCallbacks,
+        vault: AuthVault,
+        account: str | None = None,
+    ) -> Awaitable[OAuthLoginResult]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class OverlayServices:
+    """The runtime handles the modal overlays reach for when they open.
+
+    The console surface itself stays UI-local — it knows nothing about
+    settings files, the session catalog, or the credential store. Each
+    overlay that needs to drive one of those is handed this bundle (threaded
+    through :attr:`ConsoleProps.services`), so a dialog body can read/write a
+    preference, list and open saved sessions, enumerate sign-in providers,
+    run a browser login, and persist credentials — all without prop-drilling
+    individual dependencies through the surface. It is optional on
+    :class:`ConsoleProps`: the headless and test mount paths run without it,
+    and an overlay group that finds it absent renders nothing.
+    """
+
+    # The session this console drives (model selection, branching, forking).
+    conductor: SessionConductor
+    # The two-tier preference reader/writer behind the settings overlays.
+    settings: PreferenceStore
+    # The catalog-and-navigation layer over persisted transcripts.
+    sessions: SessionLibrary
+    # Enumerate the merged sign-in directory (browser + api-key providers).
+    list_login_providers: Callable[[], list[LoginProvider]]
+    # Drive a provider's browser sign-in and persist the result via the vault.
+    start_oauth_login: StartOAuthLogin
+    # Open a sign-in url in the user's browser (Chrome-first per platform).
+    # Resolves True when a browser was launched, False otherwise — the OAuth
+    # overlay calls this so the consent page opens automatically, matching
+    # the CLI sign-in path.
+    open_login_url: Callable[[str], Awaitable[bool]]
+    # The credential store sign-in / sign-out overlays read and write.
+    vault: AuthVault
+
+
+@dataclass(frozen=True, slots=True)
+class ConsoleProps:
+    """What the root console surface receives at mount.
+
+    The console is a consumer: it is handed a fully-assembled
+    ``SessionConductor`` to drive, the resolved :class:`ConsoleTheme` to
+    render in, the :class:`SlashRegistry` to dispatch against, and a small
+    set of optional seeds (a first message, preloaded images, a request-exit
+    hook). It owns no runtime of its own.
+    """
+
+    # The session this console drives and renders.
+    conductor: SessionConductor
+    # The resolved colour scheme to render in.
+    theme: ConsoleTheme
+    # The slash-command registry the composer dispatches against.
+    slash: SlashRegistry
+    # An optional first user turn to submit on mount.
+    initial_input: str | None = None
+    # Optional local image paths to attach to the first turn.
+    initial_images: tuple[str, ...] = ()
+    # Whether to render verbose diagnostics in the banner.
+    verbose: bool = False
+    # Invoked when the console asks the host process to exit.
+    on_exit: Callable[[], None] | None = None
+    # The runtime handles the modal overlays drive; absent on headless paths.
+    services: OverlayServices | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ConsoleHost:
+    """The ambient context the surface threads to its descendants.
+
+    A narrow read-only handle on the things deep children need without prop
+    drilling: the conductor to drive and the exit request. Larger state flows
+    through the reducer, not this object.
+    """
+
+    # The session this console drives.
+    conductor: SessionConductor
+    # Ask the host process to exit the interactive console.
+    request_exit: Callable[[], None]