algo-cli-runtime 0.14.0__py3-none-any.whl

algo_cli/agent_threads.py

@@ -0,0 +1,308 @@
+"""Persistent thread records for Agent Block and multi-agent runs."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+from . import config
+
+
+THREADS_FILE_NAME = "agent_threads.json"
+THREADS_SCHEMA_VERSION = 1
+MAX_THREAD_RECORDS = 100
+MAX_THREAD_TURNS = 16
+MAX_THREAD_OUTPUT_CHARS = 12_000
+_VALID_STATUSES = frozenset({"queued", "running", "complete", "partial", "failed", "cancelled"})
+
+
+def threads_path() -> Path:
+    """Resolve lazily so test/runtime config-directory changes are honored."""
+
+    return config.CONFIG_DIR / THREADS_FILE_NAME
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _clean_text(value: Any, limit: int) -> str:
+    text = str(value or "").strip()
+    return text[:limit]
+
+
+def _empty_store() -> dict[str, Any]:
+    return {"version": THREADS_SCHEMA_VERSION, "threads": []}
+
+
+def _normalize_record(raw: Any) -> dict[str, Any] | None:
+    if not isinstance(raw, dict):
+        return None
+    thread_id = _clean_text(raw.get("id"), 64)
+    if not thread_id:
+        return None
+    status = _clean_text(raw.get("status"), 24).lower()
+    if status not in _VALID_STATUSES:
+        status = "failed"
+    turns = raw.get("turns", [])
+    blocks = raw.get("blocks", [])
+    children = raw.get("children", [])
+    return {
+        "id": thread_id,
+        "parent_id": _clean_text(raw.get("parent_id"), 64),
+        "title": _clean_text(raw.get("title"), 120),
+        "task": _clean_text(raw.get("task"), 8_000),
+        "role": _clean_text(raw.get("role"), 80) or "orchestrator",
+        "pipeline": _clean_text(raw.get("pipeline"), 80) or "default",
+        "model": _clean_text(raw.get("model"), 120),
+        "status": status,
+        "created_at": _clean_text(raw.get("created_at"), 64) or _now(),
+        "updated_at": _clean_text(raw.get("updated_at"), 64) or _now(),
+        "output": _clean_text(raw.get("output"), MAX_THREAD_OUTPUT_CHARS),
+        "error": _clean_text(raw.get("error"), 2_000),
+        "children": [str(item)[:64] for item in children if str(item).strip()]
+        if isinstance(children, list)
+        else [],
+        "turns": [item for item in turns[-MAX_THREAD_TURNS:] if isinstance(item, dict)]
+        if isinstance(turns, list)
+        else [],
+        "blocks": [item for item in blocks if isinstance(item, dict)]
+        if isinstance(blocks, list)
+        else [],
+    }
+
+
+def load_threads(path: Path | None = None) -> list[dict[str, Any]]:
+    target = path or threads_path()
+    loaded = config._load_json_file(target, _empty_store())
+    if not isinstance(loaded, dict) or loaded.get("version") != THREADS_SCHEMA_VERSION:
+        return []
+    records = loaded.get("threads", [])
+    if not isinstance(records, list):
+        return []
+    normalized = [_normalize_record(record) for record in records]
+    return [record for record in normalized if record is not None]
+
+
+def _mutate(
+    callback: Callable[[list[dict[str, Any]]], Any],
+    *,
+    path: Path | None = None,
+) -> Any:
+    target = path or threads_path()
+    with config._exclusive_state_lock(target):
+        records = load_threads(target)
+        result = callback(records)
+        records.sort(key=lambda item: item.get("updated_at", ""), reverse=True)
+        del records[MAX_THREAD_RECORDS:]
+        payload = {"version": THREADS_SCHEMA_VERSION, "threads": records}
+        config._atomic_write_text(target, json.dumps(payload, indent=2))
+        return result
+
+
+def _new_id(existing: set[str]) -> str:
+    while True:
+        candidate = uuid.uuid4().hex[:8]
+        if candidate not in existing:
+            return candidate
+
+
+def create_thread(
+    task: str,
+    *,
+    role: str = "orchestrator",
+    pipeline: str = "default",
+    model: str = "",
+    parent_id: str = "",
+    title: str = "",
+    status: str = "queued",
+    start_turn: bool = False,
+    path: Path | None = None,
+) -> dict[str, Any]:
+    if status not in _VALID_STATUSES:
+        raise ValueError(f"Invalid agent thread status: {status}")
+    clean_task = _clean_text(task, 8_000)
+    clean_title = _clean_text(title, 120) or " ".join(clean_task.split())[:80] or "Agent task"
+
+    def add(records: list[dict[str, Any]]) -> dict[str, Any]:
+        thread_id = _new_id({record["id"] for record in records})
+        now = _now()
+        record = {
+            "id": thread_id,
+            "parent_id": _clean_text(parent_id, 64),
+            "title": clean_title,
+            "task": clean_task,
+            "role": _clean_text(role, 80) or "orchestrator",
+            "pipeline": _clean_text(pipeline, 80) or "default",
+            "model": _clean_text(model, 120),
+            "status": "running" if start_turn else status,
+            "created_at": now,
+            "updated_at": now,
+            "output": "",
+            "error": "",
+            "children": [],
+            "turns": (
+                [{"task": clean_task, "status": "running", "started_at": now, "output": ""}]
+                if start_turn
+                else []
+            ),
+            "blocks": [],
+        }
+        records.append(record)
+        if parent_id:
+            for parent in records:
+                if parent["id"] == parent_id and thread_id not in parent["children"]:
+                    parent["children"].append(thread_id)
+                    parent["updated_at"] = now
+                    break
+        return dict(record)
+
+    return _mutate(add, path=path)
+
+
+def update_thread(thread_id: str, *, path: Path | None = None, **changes: Any) -> dict[str, Any]:
+    allowed = {"title", "task", "role", "pipeline", "model", "status", "output", "error", "blocks"}
+    unknown = set(changes) - allowed
+    if unknown:
+        raise ValueError(f"Unsupported agent thread fields: {', '.join(sorted(unknown))}")
+    if "status" in changes and changes["status"] not in _VALID_STATUSES:
+        raise ValueError(f"Invalid agent thread status: {changes['status']}")
+
+    def update(records: list[dict[str, Any]]) -> dict[str, Any]:
+        for record in records:
+            if record["id"] != thread_id:
+                continue
+            for key, value in changes.items():
+                if key == "output":
+                    record[key] = _clean_text(value, MAX_THREAD_OUTPUT_CHARS)
+                elif key == "error":
+                    record[key] = _clean_text(value, 2_000)
+                elif key == "blocks":
+                    record[key] = [item for item in value if isinstance(item, dict)] if isinstance(value, list) else []
+                else:
+                    record[key] = _clean_text(value, 8_000 if key == "task" else 120)
+            record["updated_at"] = _now()
+            return dict(record)
+        raise KeyError(f"Unknown agent thread '{thread_id}'.")
+
+    return _mutate(update, path=path)
+
+
+def begin_turn(
+    thread_id: str,
+    task: str,
+    *,
+    pipeline: str | None = None,
+    model: str | None = None,
+    path: Path | None = None,
+) -> dict[str, Any]:
+    def begin(records: list[dict[str, Any]]) -> dict[str, Any]:
+        for record in records:
+            if record["id"] != thread_id:
+                continue
+            now = _now()
+            record["status"] = "running"
+            record["updated_at"] = now
+            if not record["task"]:
+                record["task"] = _clean_text(task, 8_000)
+            if pipeline:
+                record["pipeline"] = _clean_text(pipeline, 80)
+            if model:
+                record["model"] = _clean_text(model, 120)
+            record["turns"].append(
+                {"task": _clean_text(task, 8_000), "status": "running", "started_at": now, "output": ""}
+            )
+            record["turns"] = record["turns"][-MAX_THREAD_TURNS:]
+            return dict(record)
+        raise KeyError(f"Unknown agent thread '{thread_id}'.")
+
+    return _mutate(begin, path=path)
+
+
+def finish_turn(
+    thread_id: str,
+    *,
+    status: str,
+    output: str = "",
+    error: str = "",
+    blocks: list[dict[str, Any]] | None = None,
+    pipeline: str | None = None,
+    path: Path | None = None,
+) -> dict[str, Any]:
+    if status not in _VALID_STATUSES - {"queued", "running"}:
+        raise ValueError(f"Invalid terminal agent thread status: {status}")
+
+    def finish(records: list[dict[str, Any]]) -> dict[str, Any]:
+        for record in records:
+            if record["id"] != thread_id:
+                continue
+            now = _now()
+            record["status"] = status
+            record["updated_at"] = now
+            record["output"] = _clean_text(output, MAX_THREAD_OUTPUT_CHARS)
+            record["error"] = _clean_text(error, 2_000)
+            if blocks is not None:
+                record["blocks"] = [item for item in blocks if isinstance(item, dict)]
+            if pipeline:
+                record["pipeline"] = _clean_text(pipeline, 80)
+            if record["turns"]:
+                turn = record["turns"][-1]
+                if turn.get("status") == "running":
+                    turn.update(
+                        {
+                            "status": status,
+                            "finished_at": now,
+                            "output": _clean_text(output, MAX_THREAD_OUTPUT_CHARS),
+                            "error": _clean_text(error, 2_000),
+                        }
+                    )
+            return dict(record)
+        raise KeyError(f"Unknown agent thread '{thread_id}'.")
+
+    return _mutate(finish, path=path)
+
+
+def resolve_thread(thread_ref: str, *, path: Path | None = None) -> dict[str, Any]:
+    ref = _clean_text(thread_ref, 64).lower()
+    if not ref:
+        raise KeyError("Agent thread ID is required.")
+    records = load_threads(path)
+    exact = [record for record in records if record["id"].lower() == ref]
+    if exact:
+        return exact[0]
+    matches = [record for record in records if record["id"].lower().startswith(ref)]
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        raise KeyError(f"Agent thread prefix '{thread_ref}' is ambiguous.")
+    raise KeyError(f"Unknown agent thread '{thread_ref}'. Use /agent threads to list runs.")
+
+
+def list_threads(*, limit: int = 20, path: Path | None = None) -> list[dict[str, Any]]:
+    return load_threads(path)[: max(1, min(int(limit), 100))]
+
+
+def context_handoff(record: dict[str, Any], *, limit: int = 8_000) -> str:
+    """Produce bounded, explicit evidence context for resume/fork operations."""
+
+    blocks = record.get("blocks", [])
+    block_lines = []
+    if isinstance(blocks, list):
+        for block in blocks[-8:]:
+            if not isinstance(block, dict):
+                continue
+            code = f" ({block.get('status_code')})" if block.get("status_code") else ""
+            block_lines.append(
+                f"- {block.get('role', '?')}: {block.get('status', '?')}{code}"
+            )
+    text = (
+        f"Thread: {record.get('id', '?')}\n"
+        f"Original task: {record.get('task', '')}\n"
+        f"Last status: {record.get('status', '?')}\n"
+        f"Block evidence:\n{chr(10).join(block_lines) or '- none'}\n\n"
+        f"Last output:\n{record.get('output', '') or '(no output)'}"
+    )
+    return text[:limit]

algo_cli/animations.py

@@ -0,0 +1,316 @@
+"""Redeye companion — Unicode state animations for the Algo CLI display.
+
+The CLI has a *buddy*: a red scanning eye (think KITT / Cylon) that lives in
+the status line and reacts to what the agent is doing. Every state has its
+own motion signature so you can read the agent's mode from across the room:
+
+    THINKING   the eye sweeps left-right across a track   ▰▰●▰▰  (scanning)
+    DOING      a bolt strikes across a progress rail      ⚡▰▰▱▱  (striking)
+    ANSWERING  the eye emits chevrons toward you          ◉ ❯❯❯  (speaking)
+    IDLE       the eye breathes, with a slow blink        ◉ … ─  (watching)
+    ERROR      the eye locks wide open, no motion         ⊘      (alarmed)
+
+Architecture
+------------
+- Pure rich + stdlib; zero threads of our own. Two animation channels:
+  1. ``animate()`` / ``spinner_name()`` — registered rich spinners, animated
+     by rich's status refresh thread.
+  2. ``current_frame()`` / ``buddy_frame()`` — wall-clock frame pickers for
+     callers that already re-render (Live panels, prompt redraws). Each call
+     returns the frame for *now*, so motion is free wherever updates happen.
+- Windows-safe: ``force_utf8()`` switches the console to UTF-8 (code page
+  65001 + stream reconfigure); if that fails, every frame set has an ASCII
+  twin chosen at import so nothing ever renders as mojibake.
+- Styles are theme style *names* (primary/accent/error/...), so the buddy
+  automatically wears whatever palette is active — it bleeds red under the
+  ``redeye`` theme and adapts elsewhere.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Iterator
+
+from rich.spinner import SPINNERS
+from rich.text import Text
+
+
+# ---------------------------------------------------------------------------
+# Console capability
+# ---------------------------------------------------------------------------
+
+def force_utf8() -> bool:
+    """Switch the Windows console + Python streams to UTF-8.
+
+    prompt_toolkit and rich both emit UTF-8; on a cp1252 console that turns
+    into mojibake (``â<9d>¯`` instead of ``❯``). Returns True when the
+    console can take full Unicode afterwards.
+    """
+    if sys.platform == "win32":
+        try:
+            import ctypes
+
+            ctypes.windll.kernel32.SetConsoleOutputCP(65001)
+            ctypes.windll.kernel32.SetConsoleCP(65001)
+        except Exception:
+            pass
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
+        except Exception:
+            pass
+    return supports_unicode()
+
+
+def supports_unicode() -> bool:
+    """True when stdout's encoding can represent every buddy glyph."""
+    sample = "⠋▰▱❯◉◎⚡⊘●─"
+    encoding = getattr(sys.stdout, "encoding", None) or "ascii"
+    try:
+        sample.encode(encoding)
+        return True
+    except (UnicodeEncodeError, LookupError):
+        return False
+
+
+_UNICODE_OK = force_utf8()
+
+
+# ---------------------------------------------------------------------------
+# State definitions
+# ---------------------------------------------------------------------------
+
+class AIState(str, Enum):
+    THINKING = "thinking"
+    DOING = "doing"
+    ANSWERING = "answering"
+    IDLE = "idle"
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class StateAnimation:
+    """One state's complete visual definition."""
+
+    frames: tuple[str, ...]        # compact frames (spinner / inline titles)
+    buddy: tuple[str, ...]         # wide "companion" frames (status lines)
+    ascii_frames: tuple[str, ...]
+    ascii_buddy: tuple[str, ...]
+    interval_ms: int
+    style: str                     # rich theme style name
+    glyph: str                     # static symbol for one-off lines
+    ascii_glyph: str
+    label: str                     # default status label
+    tagline: str                   # buddy's voice for this state
+
+
+def _scan(track: str, pupil: str, width: int) -> tuple[str, ...]:
+    """Build a KITT-style scanner: a pupil sweeping across a track and back."""
+    positions = list(range(width)) + list(range(width - 2, 0, -1))
+    return tuple(track * i + pupil + track * (width - 1 - i) for i in positions)
+
+
+_ANIMATIONS: dict[AIState, StateAnimation] = {
+    AIState.THINKING: StateAnimation(
+        frames=_scan("▰", "●", 5),
+        buddy=tuple(f"⟦{frame}⟧" for frame in _scan("▰", "●", 7)),
+        ascii_frames=_scan("=", "0", 5),
+        ascii_buddy=tuple(f"[{frame}]" for frame in _scan("=", "0", 7)),
+        interval_ms=70,
+        style="secondary",
+        glyph="◉",
+        ascii_glyph="0",
+        label="thinking",
+        tagline="scanning the problem",
+    ),
+    AIState.DOING: StateAnimation(
+        frames=("⚡▱▱▱▱", "▰⚡▱▱▱", "▰▰⚡▱▱", "▰▰▰⚡▱", "▰▰▰▰⚡", "▰▰▰▰▰", "▱▰▰▰▰", "▱▱▰▰▰", "▱▱▱▰▰", "▱▱▱▱▰"),
+        buddy=("⟦⚡▱▱▱▱▱⟧", "⟦▰⚡▱▱▱▱⟧", "⟦▰▰⚡▱▱▱⟧", "⟦▰▰▰⚡▱▱⟧", "⟦▰▰▰▰⚡▱⟧", "⟦▰▰▰▰▰⚡⟧", "⟦▰▰▰▰▰▰⟧", "⟦▱▱▱▱▱▱⟧"),
+        ascii_frames=("*----", "#*---", "##*--", "###*-", "####*", "#####", "-####", "--###"),
+        ascii_buddy=("[*-----]", "[#*----]", "[##*---]", "[###*--]", "[####*-]", "[#####*]", "[######]", "[------]"),
+        interval_ms=75,
+        style="accent",
+        glyph="⚡",
+        ascii_glyph="*",
+        label="working",
+        tagline="executing",
+    ),
+    AIState.ANSWERING: StateAnimation(
+        frames=("◉   ", "◉❯  ", "◉❯❯ ", "◉❯❯❯", "◉ ❯❯", "◉  ❯"),
+        buddy=("⟦ ◉ ⟧   ", "⟦ ◉ ⟧❯  ", "⟦ ◉ ⟧❯❯ ", "⟦ ◉ ⟧❯❯❯", "⟦ ◉ ⟧ ❯❯", "⟦ ◉ ⟧  ❯"),
+        ascii_frames=("0   ", "0>  ", "0>> ", "0>>>", "0 >>", "0  >"),
+        ascii_buddy=("[ 0 ]   ", "[ 0 ]>  ", "[ 0 ]>> ", "[ 0 ]>>>", "[ 0 ] >>", "[ 0 ]  >"),
+        interval_ms=100,
+        style="primary",
+        glyph="❯",
+        ascii_glyph=">",
+        label="answering",
+        tagline="streaming the answer",
+    ),
+    AIState.IDLE: StateAnimation(
+        # Slow breath with an occasional blink (the ─ frame).
+        frames=("◉", "◉", "◉", "◎", "○", "◎", "◉", "◉", "─", "◉"),
+        buddy=("⟦ ◉ ⟧", "⟦ ◉ ⟧", "⟦ ◉ ⟧", "⟦ ◎ ⟧", "⟦ ○ ⟧", "⟦ ◎ ⟧", "⟦ ◉ ⟧", "⟦ ◉ ⟧", "⟦ ─ ⟧", "⟦ ◉ ⟧"),
+        ascii_frames=("0", "0", "0", "o", ".", "o", "0", "0", "-", "0"),
+        ascii_buddy=("[ 0 ]", "[ 0 ]", "[ 0 ]", "[ o ]", "[ . ]", "[ o ]", "[ 0 ]", "[ 0 ]", "[ - ]", "[ 0 ]"),
+        interval_ms=350,
+        style="muted",
+        glyph="◉",
+        ascii_glyph="0",
+        label="ready",
+        tagline="ready for work",
+    ),
+    AIState.ERROR: StateAnimation(
+        # Deliberately static: errors should arrest, not flicker.
+        frames=("⊘", "⊘"),
+        buddy=("⟦ ⊘ ⟧", "⟦ ⊘ ⟧"),
+        ascii_frames=("X", "X"),
+        ascii_buddy=("[ X ]", "[ X ]"),
+        interval_ms=500,
+        style="error",
+        glyph="⊘",
+        ascii_glyph="X",
+        label="error",
+        tagline="something broke",
+    ),
+}
+
+
+# ---------------------------------------------------------------------------
+# Frame access
+# ---------------------------------------------------------------------------
+
+def animation_for(state: AIState | str) -> StateAnimation:
+    return _ANIMATIONS[AIState(state)]
+
+
+def frames_for(state: AIState | str, *, buddy: bool = False) -> tuple[str, ...]:
+    anim = animation_for(state)
+    if buddy:
+        return anim.buddy if _UNICODE_OK else anim.ascii_buddy
+    return anim.frames if _UNICODE_OK else anim.ascii_frames
+
+
+def glyph(state: AIState | str) -> Text:
+    """Static styled symbol for prefixing one-off lines (no animation)."""
+    anim = animation_for(state)
+    return Text(anim.glyph if _UNICODE_OK else anim.ascii_glyph, style=anim.style)
+
+
+def current_frame(state: AIState | str) -> str:
+    """Wall-clock frame for callers that re-render on their own cadence.
+
+    Any display that updates regularly (a Live panel refreshed per token
+    batch, a prompt redraw) shows smooth motion just by calling this on
+    every render — no timer ownership needed.
+    """
+    return _pick_frame(frames_for(state), animation_for(state).interval_ms)
+
+
+def buddy_frame(state: AIState | str) -> Text:
+    """The companion eye, styled, at this instant — for status/footer lines."""
+    anim = animation_for(state)
+    frame = _pick_frame(frames_for(state, buddy=True), anim.interval_ms)
+    return Text(frame, style=anim.style)
+
+
+def _pick_frame(frames: tuple[str, ...], interval_ms: int) -> str:
+    # perf_counter, not monotonic: display tests stub time.monotonic with a
+    # finite tick iterator, and frame picking must never consume those ticks.
+    return frames[int(time.perf_counter() * 1000 / interval_ms) % len(frames)]
+
+
+def state_line(state: AIState | str, message: str = "") -> Text:
+    """Single styled line: buddy + message — e.g. ``⟦ ◉ ⟧ ready for work``."""
+    anim = animation_for(state)
+    line = buddy_frame(state)
+    line.append(f" {message or anim.tagline}", style=anim.style)
+    return line
+
+
+# ---------------------------------------------------------------------------
+# Rich spinner channel
+# ---------------------------------------------------------------------------
+
+_SPINNERS_REGISTERED = False
+
+
+def register_spinners() -> None:
+    """Register buddy spinners (``algo-<state>``) with rich. Idempotent."""
+    global _SPINNERS_REGISTERED
+    if _SPINNERS_REGISTERED:
+        return
+    for state, anim in _ANIMATIONS.items():
+        SPINNERS[f"algo-{state.value}"] = {
+            "interval": anim.interval_ms,
+            "frames": list(anim.buddy if _UNICODE_OK else anim.ascii_buddy),
+        }
+    _SPINNERS_REGISTERED = True
+
+
+def spinner_name(state: AIState | str) -> str:
+    register_spinners()
+    return f"algo-{AIState(state).value}"
+
+
+@contextmanager
+def animate(console: Any, state: AIState | str, message: str = "") -> Iterator[None]:
+    """Animated buddy status for a state::
+
+        with animate(console, AIState.DOING, "search_files"):
+            run_tool()
+    """
+    anim = animation_for(state)
+    label = f"[{anim.style}]{message or anim.tagline}[/]"
+    with console.status(label, spinner=spinner_name(state), spinner_style=anim.style):
+        yield
+
+
+# ---------------------------------------------------------------------------
+# Set pieces
+# ---------------------------------------------------------------------------
+
+def intro_sweep(console: Any, *, duration: float = 0.9) -> None:
+    """Boot animation: one scanner sweep under the logo, then settle to idle.
+
+    Skipped automatically when stdout is not a live terminal (pipes, CI,
+    JSON bridges) so it never pollutes captured output.
+    """
+    if not getattr(console, "is_terminal", False):
+        return
+    anim = animation_for(AIState.THINKING)
+    deadline = time.perf_counter() + duration
+    try:
+        with console.status("", spinner=spinner_name(AIState.THINKING), spinner_style=anim.style):
+            while time.perf_counter() < deadline:
+                time.sleep(min(0.05, anim.interval_ms / 1000))
+    except Exception:
+        return
+
+
+def demo() -> None:  # pragma: no cover - manual visual check
+    """Walk the buddy through every state. Run: ``python -m algo_cli.animations``"""
+    from algo_cli.display import console, show_error
+
+    console.print()
+    console.print(state_line(AIState.IDLE))
+    intro_sweep(console, duration=1.2)
+    with animate(console, AIState.THINKING, "scanning the problem"):
+        time.sleep(2.4)
+    with animate(console, AIState.DOING, "executing search_files"):
+        time.sleep(2.4)
+    with animate(console, AIState.ANSWERING, "streaming the answer"):
+        time.sleep(1.8)
+    console.print(state_line(AIState.ANSWERING, "answer delivered"))
+    console.print()
+    show_error("simulated failure — eye locks wide open, no flicker")
+    console.print(state_line(AIState.IDLE, "recovered — ready for work"))
+    console.print()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    demo()