cct-cli 0.7.9.0__py3-none-any.whl

calc_terminal/errors.py

@@ -0,0 +1,120 @@
+"""
+CCT Error Recovery (spec section 19).
+
+Before this module, a failure inside try/except blocks scattered
+across app.py just did `print(theme.red(f"Error: {e}"))` and moved
+on — a technical exception string, no way to retry without re-typing
+the whole command, no way to see more detail, no way to know if it's
+worth trying again. That's real (see the audit in
+CHANGELOG_v0.6.3_architecture.md: 7 call sites doing exactly this).
+
+This module gives failures one consistent shape: a themed card with a
+plain-language title + message, and numbered recovery actions —
+Retry (re-runs the same operation), View Details (the actual
+exception message, only surfaced on request, not by default), and
+Dismiss. It does NOT catch anything itself — callers still do their
+own try/except, same as before; this just replaces the "print a red
+line and give up" ending with a real recovery loop, and importantly
+never lets the underlying exception propagate up and crash the REPL.
+
+CONTEXTS below covers the failure kinds already wired in (see
+WIRED_INTO at the bottom for the honest current list). Anything not
+in CONTEXTS still gets a real card — just with a generic title.
+"""
+
+from . import theme
+
+WIDTH = 78  # matches app.py's WIDTH; passed in by callers where it differs
+
+CONTEXTS = {
+    "export": ("Export failed", "CAT couldn't save your export."),
+    "render": ("Visualization failed", "CAT couldn't generate that image."),
+    "solve": ("Calculation failed", "CAT couldn't solve that with the numbers given."),
+    "balance": ("Reaction balancing failed", "CAT couldn't balance that chemical equation."),
+    "import": ("Import failed", "CAT couldn't read that file."),
+    "ai_provider": ("AI provider unavailable", "CAT couldn't reach the configured AI provider."),
+    "workspace": ("Workspace error", "CAT couldn't read or write to the project workspace."),
+}
+
+
+def error_card(context, exc, retry=None, extra_actions=None, width=None):
+    """Show a friendly recovery card for `exc` and act on the user's
+    choice.
+
+    `retry` (zero-arg callable, optional): if given and the user picks
+    Retry, calls it and loops — success closes the card, another
+    failure reopens it with the new exception.
+
+    `extra_actions` (list of (label, callback), optional): additional
+    numbered options between Retry and View Details, e.g. Reconnect /
+    Switch Provider for an AI-unavailable card. Each callback is
+    zero-arg. After running one, if `retry` was also given this
+    automatically attempts it (reconnecting and then not retrying the
+    request would be a dead end); otherwise the card just closes.
+
+    Returns True if the operation eventually succeeded via retry,
+    False if the user dismissed without a successful retry."""
+    w = width or WIDTH
+    extra_actions = extra_actions or []
+    current_exc = exc
+    while True:
+        title, friendly = CONTEXTS.get(context, ("Something went wrong", "CAT hit an unexpected error."))
+        actions = []
+        if retry is not None:
+            actions.append(("Retry", "retry", None))
+        for label, cb in extra_actions:
+            actions.append((label, "extra", cb))
+        actions.append(("View Details", "details", None))
+        actions.append(("Dismiss", "dismiss", None))
+
+        lines = [theme.red(f"\u26a0 {title}", bold=True), "", theme.text(friendly), ""]
+        for i, (label, _, _) in enumerate(actions, 1):
+            lines.append(f"{theme.cyan(str(i) + '.')} {label}")
+        print()
+        print(theme.panel(lines, title="error", color=theme.RED, width=w))
+        raw_choice = input(theme.dim("  \u25b8 ")).strip().lower()
+
+        chosen = None
+        for i, (label, act, cb) in enumerate(actions, 1):
+            if raw_choice == str(i) or raw_choice == label.lower() or raw_choice == act:
+                chosen = (act, cb)
+                break
+
+        if chosen is None:
+            return False  # unrecognized input or bare Enter dismisses
+        act, cb = chosen
+
+        if act == "details":
+            print(theme.faint(f"\n  {current_exc}\n"))
+            continue
+        if act == "extra":
+            cb()
+            if retry is None:
+                return False
+            try:
+                retry()
+                return True
+            except Exception as e2:
+                current_exc = e2
+                continue
+        if act == "retry":
+            try:
+                retry()
+                return True
+            except Exception as e2:
+                current_exc = e2
+                continue
+        return False  # "dismiss"
+
+
+# What's actually wired into error_card() right now vs. still using a
+# plain print(theme.red(...)) line — read this before assuming every
+# failure in the app shows a recovery card.
+WIRED_INTO = {
+    "app.py cmd_export": "reports/PDF export failures",
+    "app.py cmd_react/_react_balance": "equation-balancing failures",
+    "app.py _solve_library/_solve_custom": "not yet — still a plain red line",
+    "app.py cmd_orbitalgrid": "not yet — still a plain red line",
+    "app.py cmd_import (zip extraction)": "not yet — still a plain red line",
+    "agent.py AI tool calls": "not yet — still returns a plain error string",
+}

calc_terminal/event_stream.py

@@ -0,0 +1,146 @@
+import time
+import threading
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+MODEL_RESPONSE = "model_response"
+TOOL_REQUEST = "tool_request"
+TOOL_STARTED = "tool_started"
+TOOL_RESULT = "tool_result"
+FILE_CREATED = "file_created"
+FILE_EDITED = "file_edited"
+FILE_DELETED = "file_deleted"
+FILE_MOVED = "file_moved"
+COMMAND_STARTED = "command_started"
+COMMAND_RESULT = "command_result"
+MEMORY_READ = "memory_read"
+MEMORY_CREATED = "memory_created"
+MEMORY_UPDATED = "memory_updated"
+MEMORY_DELETED = "memory_deleted"
+AGENT_STARTED = "agent_started"
+AGENT_COMPLETED = "agent_completed"
+AGENT_FAILED = "agent_failed"
+SESSION_CLEARED = "session_cleared"
+CONTEXT_SWITCHED = "context_switched"
+
+# ---------------------------------------------------------------------------
+# v0.7.9.0 — unified real-time activity vocabulary (requirement #2/#29).
+# Every displayed operation must correspond to an actual backend event;
+# these are the topics the whole runtime (model router, agent loop, vision
+# pipeline, multi-AI orchestrator) publishes and the UI subscribes to.
+# ---------------------------------------------------------------------------
+USER_MESSAGE = "user_message"                  # request entered the pipeline
+ROUTE_DECIDED = "route_decided"                # smart router picked a path
+MODEL_SELECTED = "model_selected"              # which model/config will answer
+MODEL_REQUEST_STARTED = "model_request_started"
+MODEL_FIRST_TOKEN = "model_first_token"        # real first token arrived
+TEXT_DELTA = "text_delta"                      # streamed text fragment
+AGENT_THINKING = "agent_thinking"              # waiting on model reasoning
+TOOL_DETECTED = "tool_detected"
+TOOL_PROGRESS = "tool_progress"
+TOOL_FINISHED = "tool_finished"
+AGENT_CONTINUING = "agent_continuing"          # tool result fed back → looping
+AGENT_SWITCHED = "agent_switched"
+MULTI_AGENT_STARTED = "multi_agent_started"
+MULTI_AGENT_PROGRESS = "multi_agent_progress"
+MULTI_AGENT_FINISHED = "multi_agent_finished"
+IMAGE_ANALYSIS_STARTED = "image_analysis_started"
+IMAGE_ANALYSIS_FINISHED = "image_analysis_finished"
+FINAL_RESPONSE = "final_response"              # turn truly complete
+ERROR = "error"
+
+# Vision events (v0.8.a CAT Vision — spec 41)
+VISION_SESSION_STARTED = "VISION_SESSION_STARTED"
+VISION_SESSION_STOPPED = "VISION_SESSION_STOPPED"
+VISION_CAPTURE_STARTED = "VISION_CAPTURE_STARTED"
+VISION_CAPTURE_ENDED = "VISION_CAPTURE_ENDED"
+VISION_FRAME_SELECTED = "VISION_FRAME_SELECTED"
+VISION_FRAME_ANALYZED = "VISION_FRAME_ANALYZED"
+VISION_CURSOR_EVENT = "VISION_CURSOR_EVENT"
+VISION_ANNOTATION_CREATED = "VISION_ANNOTATION_CREATED"
+VISION_ANNOTATION_UPDATED = "VISION_ANNOTATION_UPDATED"
+VISION_ANNOTATION_DELETED = "VISION_ANNOTATION_DELETED"
+VISION_USER_MESSAGE = "VISION_USER_MESSAGE"
+VISION_AI_ANALYSIS = "VISION_AI_ANALYSIS"
+VISION_FIX_PROPOSED = "VISION_FIX_PROPOSED"
+VISION_FIX_APPLIED = "VISION_FIX_APPLIED"
+VISION_PREVIEW_REFRESHED = "VISION_PREVIEW_REFRESHED"
+VISION_VERIFICATION_COMPLETE = "VISION_VERIFICATION_COMPLETE"
+
+# Bounded buffer: a very long session must not grow this without limit.
+_MAX_BUFFER = 500
+
+
+@dataclass
+class Event:
+    event_type: str
+    timestamp: float
+    data: Dict[str, Any] = field(default_factory=dict)
+    source: str = ""
+
+
+class EventStream:
+    def __init__(self):
+        self._buffer: List[Event] = []
+        self._subscribers: Dict[str, List[Callable]] = {}
+        self._lock = threading.Lock()
+
+    def emit(self, event_type: str, source: str = "", **data: Any) -> Event:
+        event = Event(
+            event_type=event_type,
+            timestamp=time.time(),
+            data=data,
+            source=source,
+        )
+        with self._lock:
+            self._buffer.append(event)
+            if len(self._buffer) > _MAX_BUFFER:
+                del self._buffer[:len(self._buffer) - _MAX_BUFFER]
+            subscribers = list(self._subscribers.get(event_type, []))
+
+        for callback in subscribers:
+            try:
+                callback(event)
+            except Exception as e:
+                logger.debug("Subscriber error for %s: %s", event_type, e)
+
+        return event
+
+    def subscribe(self, event_type: str, callback: Callable) -> Callable:
+        with self._lock:
+            self._subscribers.setdefault(event_type, []).append(callback)
+        return callback
+
+    def unsubscribe(self, event_type: str, callback: Callable) -> None:
+        with self._lock:
+            subscribers = self._subscribers.get(event_type, [])
+            if callback in subscribers:
+                subscribers.remove(callback)
+
+    def get_recent(self, event_type: Optional[str] = None, limit: int = 50) -> List[Event]:
+        with self._lock:
+            if event_type is None:
+                return list(self._buffer[-limit:])
+            return [e for e in self._buffer if e.event_type == event_type][-limit:]
+
+    def get_all(self, event_type: Optional[str] = None) -> List[Event]:
+        with self._lock:
+            if event_type is None:
+                return list(self._buffer)
+            return [e for e in self._buffer if e.event_type == event_type]
+
+    def clear(self) -> None:
+        with self._lock:
+            self._buffer.clear()
+
+    def subscriber_count(self, event_type: Optional[str] = None) -> int:
+        with self._lock:
+            if event_type is None:
+                return sum(len(subs) for subs in self._subscribers.values())
+            return len(self._subscribers.get(event_type, []))
+
+
+stream = EventStream()

calc_terminal/eventbus.py

@@ -0,0 +1,133 @@
+"""
+CCT — eventbus.py: the Workspace Event Bus the v0.7.2 roadmap doc asks
+every backend module to communicate through ("Avoid placing all logic
+inside one file... every module should communicate through the
+Workspace Manager and Event Bus").
+
+Deliberately separate from ui/events.py's Textual `Message` classes,
+which stay exactly as they are — those are UI-thread widget-to-widget
+messages, already working, and this pass isn't rewriting that
+architecture. This bus is for the plain-Python backend modules
+(todos.py, timeline.py, and anything future — TodoManager/
+TimelineManager/DashboardManager in the roadmap's own suggested
+naming) that have no reason to depend on Textual at all. CCTApp is the
+one place that bridges the two: it subscribes bus topics to its own UI
+updates in ui/app.py's on_mount, the same way it already turns worker-
+thread results into posted ui/events.py Messages via call_from_thread.
+
+Plain pub/sub, synchronous, in-process. No persistence, no cross-
+process delivery, no priority/ordering guarantees beyond "subscribers
+fire in the order they subscribed" — this is a lightweight backbone
+for wiring already-in-process modules together, not a message queue.
+A single module-level `bus` instance is the one every module below
+imports and uses (`from .. import eventbus` / `from . import
+eventbus`, then `eventbus.bus.publish(...)`), mirroring the
+existing single-module-level-store convention projects.py/config.py
+already use instead of a class the caller has to instantiate.
+"""
+
+if __name__ == "__main__":
+    print("This is a library file and is not meant to be run directly.")
+    import sys
+    sys.exit(1)
+
+import time
+import traceback
+
+# Topic names — the roadmap's own "Track events such as" list for the
+# Session Timeline doubles as a reasonable topic vocabulary for the
+# whole bus, since nearly everything else (Todo, Dashboard) wants to
+# react to the same underlying happenings.
+FILE_CREATED = "file_created"
+FILE_DELETED = "file_deleted"
+FILE_RENAMED = "file_renamed"
+FILE_SAVED = "file_saved"
+AI_RESPONSE_GENERATED = "ai_response_generated"
+AI_FILE_EDIT = "ai_file_edit"
+TERMINAL_COMMAND = "terminal_command"
+WORKSPACE_OPENED = "workspace_opened"
+WORKSPACE_CLOSED = "workspace_closed"
+TODO_CREATED = "todo_created"
+TODO_COMPLETED = "todo_completed"
+TODO_UPDATED = "todo_updated"
+TODO_DELETED = "todo_deleted"
+
+# v0.7.7 autonomous-preview topics.
+PACKAGE_INSTALLED = "package_installed"
+PACKAGE_FAILED = "package_failed"
+PIPELINE_STAGE = "pipeline_stage"
+PIPELINE_COMPLETED = "pipeline_completed"
+MODE_SWITCHED = "mode_switched"
+DEVICE_ACTION = "device_action"
+
+# v0.7.9.0 explicit agent-tool filesystem topics (requirement: CAT's own
+# file tools must announce their changes immediately, so the Explorer can
+# react while the OS watcher confirms the real on-disk state):
+TOOL_FILE_CREATED = "tool_file_created"
+TOOL_FILE_DELETED = "tool_file_deleted"
+TOOL_FILE_MOVED = "tool_file_moved"
+TOOL_DIRECTORY_CHANGED = "tool_directory_changed"
+
+# Vision topics (v0.8.a — spec 41, mirrored with event_stream names)
+VISION_SESSION_STARTED = "VISION_SESSION_STARTED"
+VISION_SESSION_STOPPED = "VISION_SESSION_STOPPED"
+VISION_CAPTURE_STARTED = "VISION_CAPTURE_STARTED"
+VISION_CAPTURE_ENDED = "VISION_CAPTURE_ENDED"
+VISION_FRAME_SELECTED = "VISION_FRAME_SELECTED"
+VISION_FRAME_ANALYZED = "VISION_FRAME_ANALYZED"
+VISION_CURSOR_EVENT = "VISION_CURSOR_EVENT"
+VISION_ANNOTATION_CREATED = "VISION_ANNOTATION_CREATED"
+VISION_ANNOTATION_UPDATED = "VISION_ANNOTATION_UPDATED"
+VISION_ANNOTATION_DELETED = "VISION_ANNOTATION_DELETED"
+VISION_USER_MESSAGE = "VISION_USER_MESSAGE"
+VISION_AI_ANALYSIS = "VISION_AI_ANALYSIS"
+VISION_FIX_PROPOSED = "VISION_FIX_PROPOSED"
+VISION_FIX_APPLIED = "VISION_FIX_APPLIED"
+VISION_PREVIEW_REFRESHED = "VISION_PREVIEW_REFRESHED"
+VISION_VERIFICATION_COMPLETE = "VISION_VERIFICATION_COMPLETE"
+
+
+class EventBus:
+    def __init__(self):
+        self._subs = {}  # topic -> list[callable]
+
+    def subscribe(self, topic, callback):
+        """Registers `callback(**data)` for `topic`. Returns `callback`
+        unchanged so a caller can do
+        `self._sub = bus.subscribe(TOPIC, self._on_topic)` and later
+        pass that same reference to unsubscribe()."""
+        self._subs.setdefault(topic, []).append(callback)
+        return callback
+
+    def unsubscribe(self, topic, callback):
+        subs = self._subs.get(topic)
+        if not subs:
+            return
+        try:
+            subs.remove(callback)
+        except ValueError:
+            pass
+
+    def publish(self, topic, **data):
+        """Fires every subscriber for `topic` synchronously, in
+        subscribe order. `data.setdefault("ts", ...)` stamps every
+        event with a publish time so a subscriber (Timeline, mainly)
+        never has to remember to do it itself. A subscriber that
+        raises is logged (via Python's stdlib logging, not print() —
+        printing anything to stdout inside a running Textual app
+        corrupts the alt-screen, same reason ui/composer.py's own
+        error path uses self.log.error() instead) and does not stop
+        the remaining subscribers from still running — one broken
+        listener (e.g. a Timeline panel mid-teardown) must not be able
+        to silently break Todo/Dashboard updates too."""
+        data.setdefault("ts", time.time())
+        for callback in list(self._subs.get(topic, [])):
+            try:
+                callback(**data)
+            except Exception:
+                import logging
+                logging.getLogger("cct.eventbus").error(
+                    "subscriber for %r raised:\n%s", topic, traceback.format_exc())
+
+
+bus = EventBus()