feat(daemon): add daemon mode with C&C and display abstraction

- Add display abstraction with swappable backends (TerminalDisplay, NullDisplay) - Separate C&C into RX/TX topics for serial-like communication - Add StreamController with automatic ntfy topic warmup - Add performance monitoring for render + display stages - Update AGENTS.md and README.md with daemon/cmd operating procedures - Add clean/clobber tasks to mise.toml - Add tests for display, effects controller, and controller warmup - Fix bug where /effects reorder command was unreachable
2026-03-15 18:37:36 -07:00
parent 40ad935dda
commit bc2e086f2f
14 changed files with 633 additions and 82 deletions
--- a/engine/app.py
+++ b/engine/app.py
@@ -11,10 +11,8 @@ import time
 import tty

 from engine import config, render
+from engine.controller import StreamController
 from engine.fetch import fetch_all, fetch_poetry, load_cache, save_cache
-from engine.mic import MicMonitor
-from engine.ntfy import NtfyPoller
-from engine.scroll import stream
 from engine.terminal import (
    CLR,
    CURSOR_OFF,
@@ -363,6 +361,8 @@ def main():

    signal.signal(signal.SIGINT, handle_sigint)

+    StreamController.warmup_topics()
+
    w = tw()
    print(CLR, end="")
    print(CURSOR_OFF, end="")
@@ -419,9 +419,10 @@ def main():
        sys.exit(1)

    print()
-    mic = MicMonitor(threshold_db=config.MIC_THRESHOLD_DB)
-    mic_ok = mic.start()
-    if mic.available:
+    controller = StreamController()
+    mic_ok, ntfy_ok = controller.initialize_sources()
+
+    if controller.mic and controller.mic.available:
        boot_ln(
            "Microphone",
            "ACTIVE"
@@ -430,12 +431,6 @@ def main():
            bool(mic_ok),
        )

-    ntfy = NtfyPoller(
-        config.NTFY_TOPIC,
-        reconnect_delay=config.NTFY_RECONNECT_DELAY,
-        display_secs=config.MESSAGE_DISPLAY_SECS,
-    )
-    ntfy_ok = ntfy.start()
    boot_ln("ntfy", "LISTENING" if ntfy_ok else "OFFLINE", ntfy_ok)

    if config.FIREHOSE:
@@ -448,7 +443,7 @@ def main():
    print()
    time.sleep(0.4)

-    stream(items, ntfy, mic)
+    controller.run(items)

    print()
    print(f"  {W_GHOST}{'─' * (tw() - 4)}{RST}")
--- a/engine/config.py
+++ b/engine/config.py
@@ -105,7 +105,8 @@ class Config:
    firehose: bool = False

    ntfy_topic: str = "https://ntfy.sh/klubhaus_terminal_mainline/json"
-    ntfy_cc_topic: str = "https://ntfy.sh/klubhaus_terminal_mainline_cc/json"
+    ntfy_cc_cmd_topic: str = "https://ntfy.sh/klubhaus_terminal_mainline_cc_cmd/json"
+    ntfy_cc_resp_topic: str = "https://ntfy.sh/klubhaus_terminal_mainline_cc_resp/json"
    ntfy_reconnect_delay: int = 5
    message_display_secs: int = 30

@@ -149,7 +150,8 @@ class Config:
            mode="poetry" if "--poetry" in argv or "-p" in argv else "news",
            firehose="--firehose" in argv,
            ntfy_topic="https://ntfy.sh/klubhaus_terminal_mainline/json",
-            ntfy_cc_topic="https://ntfy.sh/klubhaus_terminal_mainline_cc/json",
+            ntfy_cc_cmd_topic="https://ntfy.sh/klubhaus_terminal_mainline_cc_cmd/json",
+            ntfy_cc_resp_topic="https://ntfy.sh/klubhaus_terminal_mainline_cc_resp/json",
            ntfy_reconnect_delay=5,
            message_display_secs=30,
            font_dir=font_dir,
@@ -195,7 +197,8 @@ FIREHOSE = "--firehose" in sys.argv

 # ─── NTFY MESSAGE QUEUE ──────────────────────────────────
 NTFY_TOPIC = "https://ntfy.sh/klubhaus_terminal_mainline/json"
-NTFY_CC_TOPIC = "https://ntfy.sh/klubhaus_terminal_mainline_cc/json"
+NTFY_CC_CMD_TOPIC = "https://ntfy.sh/klubhaus_terminal_mainline_cc_cmd/json"
+NTFY_CC_RESP_TOPIC = "https://ntfy.sh/klubhaus_terminal_mainline_cc_resp/json"
 NTFY_RECONNECT_DELAY = 5  # seconds before reconnecting after a dropped stream
 MESSAGE_DISPLAY_SECS = 30  # how long a message holds the screen

--- a/engine/controller.py
+++ b/engine/controller.py
@@ -14,6 +14,8 @@ from engine.scroll import stream
 class StreamController:
    """Controls the stream lifecycle - initializes sources and runs the stream."""

+    _topics_warmed = False
+
    def __init__(self, config: Config | None = None, event_bus: EventBus | None = None):
        self.config = config or get_config()
        self.event_bus = event_bus
@@ -21,6 +23,37 @@ class StreamController:
        self.ntfy: NtfyPoller | None = None
        self.ntfy_cc: NtfyPoller | None = None

+    @classmethod
+    def warmup_topics(cls) -> None:
+        """Warm up ntfy topics lazily (creates them if they don't exist)."""
+        if cls._topics_warmed:
+            return
+
+        import urllib.request
+
+        topics = [
+            "https://ntfy.sh/klubhaus_terminal_mainline_cc_cmd",
+            "https://ntfy.sh/klubhaus_terminal_mainline_cc_resp",
+            "https://ntfy.sh/klubhaus_terminal_mainline",
+        ]
+
+        for topic in topics:
+            try:
+                req = urllib.request.Request(
+                    topic,
+                    data=b"init",
+                    headers={
+                        "User-Agent": "mainline/0.1",
+                        "Content-Type": "text/plain",
+                    },
+                    method="POST",
+                )
+                urllib.request.urlopen(req, timeout=5)
+            except Exception:
+                pass
+
+        cls._topics_warmed = True
+
    def initialize_sources(self) -> tuple[bool, bool]:
        """Initialize microphone and ntfy sources.

@@ -38,7 +71,7 @@ class StreamController:
        ntfy_ok = self.ntfy.start()

        self.ntfy_cc = NtfyPoller(
-            self.config.ntfy_cc_topic,
+            self.config.ntfy_cc_cmd_topic,
            reconnect_delay=self.config.ntfy_reconnect_delay,
            display_secs=5,
        )
@@ -57,7 +90,7 @@ class StreamController:

        response = handle_effects_command(cmd)

-        topic_url = self.config.ntfy_cc_topic.replace("/json", "")
+        topic_url = self.config.ntfy_cc_resp_topic.replace("/json", "")
        data = response.encode("utf-8")
        req = urllib.request.Request(
            topic_url,
--- a/engine/display.py
+++ b/engine/display.py
@@ -0,0 +1,102 @@
+"""
+Display output abstraction - allows swapping output backends.
+
+Protocol:
+    - init(width, height): Initialize display with terminal dimensions
+    - show(buffer): Render buffer (list of strings) to display
+    - clear(): Clear the display
+    - cleanup(): Shutdown display
+"""
+
+import time
+from typing import Protocol
+
+
+class Display(Protocol):
+    """Protocol for display backends."""
+
+    def init(self, width: int, height: int) -> None:
+        """Initialize display with dimensions."""
+        ...
+
+    def show(self, buffer: list[str]) -> None:
+        """Show buffer on display."""
+        ...
+
+    def clear(self) -> None:
+        """Clear display."""
+        ...
+
+    def cleanup(self) -> None:
+        """Shutdown display."""
+        ...
+
+
+def get_monitor():
+    """Get the performance monitor."""
+    try:
+        from engine.effects.performance import get_monitor as _get_monitor
+
+        return _get_monitor()
+    except Exception:
+        return None
+
+
+class TerminalDisplay:
+    """ANSI terminal display backend."""
+
+    def __init__(self):
+        self.width = 80
+        self.height = 24
+
+    def init(self, width: int, height: int) -> None:
+        from engine.terminal import CURSOR_OFF
+
+        self.width = width
+        self.height = height
+        print(CURSOR_OFF, end="", flush=True)
+
+    def show(self, buffer: list[str]) -> None:
+        import sys
+
+        t0 = time.perf_counter()
+        sys.stdout.buffer.write("".join(buffer).encode())
+        sys.stdout.flush()
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+
+        monitor = get_monitor()
+        if monitor:
+            chars_in = sum(len(line) for line in buffer)
+            monitor.record_effect("terminal_display", elapsed_ms, chars_in, chars_in)
+
+    def clear(self) -> None:
+        from engine.terminal import CLR
+
+        print(CLR, end="", flush=True)
+
+    def cleanup(self) -> None:
+        from engine.terminal import CURSOR_ON
+
+        print(CURSOR_ON, end="", flush=True)
+
+
+class NullDisplay:
+    """Headless/null display - discards all output."""
+
+    def init(self, width: int, height: int) -> None:
+        self.width = width
+        self.height = height
+
+    def show(self, buffer: list[str]) -> None:
+        monitor = get_monitor()
+        if monitor:
+            t0 = time.perf_counter()
+            chars_in = sum(len(line) for line in buffer)
+            elapsed_ms = (time.perf_counter() - t0) * 1000
+            monitor.record_effect("null_display", elapsed_ms, chars_in, chars_in)
+
+    def clear(self) -> None:
+        pass
+
+    def cleanup(self) -> None:
+        pass
--- a/engine/effects/controller.py
+++ b/engine/effects/controller.py
@@ -52,6 +52,12 @@ def handle_effects_command(cmd: str) -> str:
    if parts[1] == "stats":
        return _format_stats()

+    if parts[1] == "reorder" and len(parts) >= 3:
+        new_order = parts[2].split(",")
+        if chain and chain.reorder(new_order):
+            return f"Reordered pipeline: {new_order}"
+        return "Failed to reorder pipeline"
+
    if len(parts) < 3:
        return "Usage: /effects <name> on|off|intensity <value>"

@@ -81,12 +87,6 @@ def handle_effects_command(cmd: str) -> str:
        except ValueError:
            return "Invalid intensity value"

-    if action == "reorder" and len(parts) >= 3:
-        new_order = parts[2].split(",")
-        if chain and chain.reorder(new_order):
-            return f"Reordered pipeline: {new_order}"
-        return "Failed to reorder pipeline"
-
    return f"Unknown action: {action}"


--- a/engine/scroll.py
+++ b/engine/scroll.py
@@ -4,10 +4,16 @@ Orchestrates viewport, frame timing, and layers.
 """

 import random
-import sys
 import time

 from engine import config
+from engine.display import (
+    Display,
+    TerminalDisplay,
+)
+from engine.display import (
+    get_monitor as _get_display_monitor,
+)
 from engine.frame import calculate_scroll_step
 from engine.layers import (
    apply_glitch,
@@ -16,24 +22,24 @@ from engine.layers import (
    render_message_overlay,
    render_ticker_zone,
 )
-from engine.terminal import CLR
 from engine.viewport import th, tw

 USE_EFFECT_CHAIN = True


-def stream(items, ntfy_poller, mic_monitor):
+def stream(items, ntfy_poller, mic_monitor, display: Display | None = None):
    """Main render loop with four layers: message, ticker, scroll motion, firehose."""
+    if display is None:
+        display = TerminalDisplay()
    random.shuffle(items)
    pool = list(items)
    seen = set()
    queued = 0

    time.sleep(0.5)
-    sys.stdout.write(CLR)
-    sys.stdout.flush()
-
    w, h = tw(), th()
+    display.init(w, h)
+    display.clear()
    fh = config.FIREHOSE_H if config.FIREHOSE else 0
    ticker_view_h = h - fh
    GAP = 3
@@ -97,6 +103,7 @@ def stream(items, ntfy_poller, mic_monitor):
        buf.extend(ticker_buf)

        mic_excess = mic_monitor.excess
+        render_start = time.perf_counter()

        if USE_EFFECT_CHAIN:
            buf = process_effects(
@@ -119,12 +126,16 @@ def stream(items, ntfy_poller, mic_monitor):
        if msg_overlay:
            buf.extend(msg_overlay)

-        sys.stdout.buffer.write("".join(buf).encode())
-        sys.stdout.flush()
+        render_elapsed = (time.perf_counter() - render_start) * 1000
+        monitor = _get_display_monitor()
+        if monitor:
+            chars = sum(len(line) for line in buf)
+            monitor.record_effect("render", render_elapsed, chars, chars)
+
+        display.show(buf)

        elapsed = time.monotonic() - t0
        time.sleep(max(0, config.FRAME_DT - elapsed))
        frame_number += 1

-    sys.stdout.write(CLR)
-    sys.stdout.flush()
+    display.cleanup()