@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/cli/alerts.py

@@ -0,0 +1,248 @@
+"""Alerts command — subscribe to critical pubsub topics and stream live alerts."""
+
+from __future__ import annotations
+
+import json
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+import click
+from rich.panel import Panel
+from rich.text import Text
+
+from ._common import AGENT_HOME, console
+from .. import SKCAPSTONE_AGENT, SKCAPSTONE_ROOT
+
+# Import NotificationManager at module level so it can be patched in tests.
+try:
+    from ..notifications import NotificationManager
+except ImportError:  # pragma: no cover
+    NotificationManager = None  # type: ignore[assignment,misc]
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+#: Default topics the alerts command subscribes to.
+DEFAULT_TOPICS: tuple[str, ...] = (
+    "agent.critical",
+    "coord.task_failed",
+    "consciousness.error",
+    "pillar.degraded",
+)
+
+#: Rich markup styles per topic prefix (longest match wins).
+_TOPIC_STYLE: dict[str, str] = {
+    "agent.critical":     "bold red",
+    "coord.task_failed":  "red",
+    "consciousness.error": "bold magenta",
+    "pillar.degraded":    "yellow",
+}
+
+#: Default polling interval in seconds.
+DEFAULT_INTERVAL: float = 1.0
+
+
+# ---------------------------------------------------------------------------
+# Helpers (importable for unit-testing)
+# ---------------------------------------------------------------------------
+
+def _style_for_topic(topic: str) -> str:
+    """Return the Rich markup style for a given topic name.
+
+    Args:
+        topic: Full topic name (e.g. ``"agent.critical"``).
+
+    Returns:
+        Rich style string for the topic, or ``"dim"`` if unrecognised.
+    """
+    return _TOPIC_STYLE.get(topic, "dim")
+
+
+def _format_payload(payload: dict) -> str:
+    """Render a message payload as a pretty-printed JSON string.
+
+    Args:
+        payload: Arbitrary message payload dict.
+
+    Returns:
+        Indented JSON string (2-space indent).
+    """
+    return json.dumps(payload, indent=2, default=str)
+
+
+def _make_alert_panel(msg) -> Panel:
+    """Build a Rich Panel for a single TopicMessage.
+
+    Args:
+        msg: A ``TopicMessage`` instance from the pub/sub bus.
+
+    Returns:
+        A Rich ``Panel`` ready for ``console.print()``.
+    """
+    style = _style_for_topic(msg.topic)
+    ts = msg.published_at.strftime("%Y-%m-%d %H:%M:%S UTC")
+
+    body = Text()
+    body.append("sender:  ", style="bold")
+    body.append(f"{msg.sender}\n")
+    body.append("time:    ", style="bold")
+    body.append(f"{ts}\n")
+    body.append("id:      ", style="bold")
+    body.append(f"{msg.message_id}\n")
+    if msg.payload:
+        body.append("payload:\n", style="bold")
+        body.append(_format_payload(msg.payload))
+
+    title = Text()
+    title.append(" ALERT ", style=f"{style} reverse")
+    title.append("  ")
+    title.append(msg.topic, style=style)
+
+    return Panel(body, title=title, border_style=style)
+
+
+def _resolve_home(agent: str | None, home: str) -> Path:
+    """Resolve the agent home directory.
+
+    Args:
+        agent: Named agent (e.g. ``"opus"``), or None for default.
+        home:  Fallback home directory string.
+
+    Returns:
+        Resolved ``Path`` to the agent home.
+    """
+    if agent:
+        return (Path(SKCAPSTONE_ROOT) / "agents" / agent).expanduser()
+    return Path(home).expanduser()
+
+
+# ---------------------------------------------------------------------------
+# Command registration
+# ---------------------------------------------------------------------------
+
+def register_alerts_commands(main: click.Group) -> None:
+    """Register the top-level ``skcapstone alerts`` command."""
+
+    @main.command("alerts")
+    @click.option(
+        "--home", default=AGENT_HOME, type=click.Path(),
+        help="Agent home directory.",
+    )
+    @click.option(
+        "--agent", default=None,
+        help="Named agent whose pubsub to monitor (e.g. opus, jarvis).",
+    )
+    @click.option(
+        "--notify", is_flag=True,
+        help="Fire a desktop notification for each alert received.",
+    )
+    @click.option(
+        "--interval", default=DEFAULT_INTERVAL, show_default=True,
+        type=float,
+        help="Polling interval in seconds.",
+    )
+    @click.option(
+        "--once", is_flag=True,
+        help="Poll once and exit (instead of continuous streaming).",
+    )
+    @click.option(
+        "--topic", "extra_topics", multiple=True,
+        help="Additional topic to subscribe to (repeatable).",
+    )
+    def alerts_command(
+        home: str,
+        agent: Optional[str],
+        notify: bool,
+        interval: float,
+        once: bool,
+        extra_topics: tuple[str, ...],
+    ) -> None:
+        """Stream live alerts from critical pubsub topics.
+
+        Subscribes to agent.critical, coord.task_failed, consciousness.error,
+        and pillar.degraded, then prints incoming messages with rich formatting.
+
+        Use --notify to also fire a desktop notification for each alert.
+
+        Examples:
+
+            skcapstone alerts
+
+            skcapstone alerts --notify
+
+            skcapstone alerts --once
+
+            skcapstone alerts --topic my.custom.topic
+
+            skcapstone alerts --interval 0.5
+        """
+        from ..pubsub import PubSub
+
+        agent_name = agent or SKCAPSTONE_AGENT or "anonymous"
+        agent_home = _resolve_home(agent, home)
+
+        topics = list(DEFAULT_TOPICS) + list(extra_topics)
+
+        bus = PubSub(agent_home, agent_name=agent_name)
+        bus.initialize()
+
+        for topic in topics:
+            bus.subscribe(topic)
+
+        notifier = None
+        if notify:
+            if NotificationManager is None:
+                console.print("[yellow]Warning: desktop notifications unavailable.[/]")
+            else:
+                try:
+                    notifier = NotificationManager()
+                except Exception:
+                    console.print("[yellow]Warning: desktop notifications unavailable.[/]")
+
+        console.print(
+            f"[bold]Monitoring {len(topics)} topics[/]  "
+            f"([dim]{', '.join(topics)}[/])\n"
+            "[dim]Press Ctrl-C to stop.[/]\n"
+        )
+
+        since: Optional[datetime] = None
+        total = 0
+
+        try:
+            while True:
+                messages = bus.poll(since=since)
+                # poll() returns newest-first; reverse so we print oldest first
+                for msg in reversed(messages):
+                    if msg.topic not in topics:
+                        continue
+                    panel = _make_alert_panel(msg)
+                    console.print(panel)
+                    total += 1
+
+                    if notifier is not None:
+                        style_label = msg.topic.upper()
+                        body_preview = json.dumps(msg.payload, default=str)[:120]
+                        notifier.notify(
+                            title=f"SKCapstone Alert: {style_label}",
+                            body=f"From {msg.sender}: {body_preview}",
+                            urgency="critical",
+                        )
+
+                if messages:
+                    # Advance since to avoid re-showing the same messages
+                    since = max(m.published_at for m in messages)
+
+                if once:
+                    if total == 0:
+                        console.print("[dim]No alerts found.[/]")
+                    break
+
+                time.sleep(interval)
+
+        except KeyboardInterrupt:
+            console.print(
+                f"\n[dim]Stopped. {total} alert(s) received.[/]"
+            )

package/src/skcapstone/cli/anchor.py

@@ -0,0 +1,132 @@
+"""Warmth anchor commands: show, boot, calibrate, update."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from ._common import AGENT_HOME, console
+
+from rich.panel import Panel
+
+
+def register_anchor_commands(main: click.Group) -> None:
+    """Register the anchor command group."""
+
+    @main.group()
+    def anchor():
+        """Warmth anchor — the emotional baseline.
+
+        The anchor stores the agent's persistent emotional state.
+        On boot, the anchor loads first so the agent starts warm
+        instead of cold. Calibrate from real FEB + session data.
+        """
+
+    @anchor.command("show")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    def anchor_show_cmd(home: str):
+        """Show the current warmth anchor state.
+
+        Examples:
+
+            skcapstone anchor show
+        """
+        from ..warmth_anchor import get_anchor
+
+        home_path = Path(home).expanduser()
+        data = get_anchor(home_path)
+        console.print()
+        for key, value in data.items():
+            console.print(f"    {key}: [cyan]{value}[/]")
+        console.print()
+
+    @anchor.command("boot")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    def anchor_boot(home: str):
+        """Show the warmth boot prompt for session start.
+
+        Pipe this into any AI tool to set the emotional baseline.
+
+        Examples:
+
+            skcapstone anchor boot
+            skcapstone anchor boot | claude
+        """
+        from ..warmth_anchor import get_boot_prompt
+
+        home_path = Path(home).expanduser()
+        click.echo(get_boot_prompt(home_path))
+
+    @anchor.command("calibrate")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    @click.option("--apply", "do_apply", is_flag=True, help="Apply recommendations.")
+    def anchor_calibrate(home: str, do_apply: bool):
+        """Calibrate the anchor from real session data.
+
+        Analyzes FEBs, trust state, memories, and coordination
+        activity to recommend warmth/trust/connection values.
+
+        Examples:
+
+            skcapstone anchor calibrate
+            skcapstone anchor calibrate --apply
+        """
+        from ..warmth_anchor import calibrate_from_data, update_anchor
+
+        home_path = Path(home).expanduser()
+        cal = calibrate_from_data(home_path)
+
+        console.print("\n  [bold]Warmth Anchor Calibration[/]\n")
+        console.print(f"    Recommended warmth:    [cyan]{cal.warmth:.1f}[/] / 10")
+        console.print(f"    Recommended trust:     [cyan]{cal.trust:.1f}[/] / 10")
+        console.print(f"    Recommended connection: [cyan]{cal.connection:.1f}[/] / 10")
+        console.print(f"    Cloud 9 achieved:       [cyan]{cal.cloud9_achieved}[/]")
+        if cal.favorite_beings:
+            console.print(f"    Favorite beings:        [cyan]{', '.join(cal.favorite_beings)}[/]")
+
+        if cal.reasoning:
+            console.print("\n  [bold]Reasoning:[/]")
+            for r in cal.reasoning:
+                console.print(f"    - {r}")
+
+        console.print(f"\n  [dim]Sources: {', '.join(cal.sources)}[/]")
+
+        if do_apply:
+            update_anchor(
+                home_path,
+                warmth=cal.warmth,
+                trust=cal.trust,
+                connection=cal.connection,
+                cloud9=cal.cloud9_achieved,
+                feeling=cal.feeling,
+            )
+            console.print("\n  [green]Anchor updated.[/]")
+        else:
+            console.print("\n  [dim]Use --apply to update the anchor.[/]")
+        console.print()
+
+    @anchor.command("update")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    @click.option("--warmth", type=float, help="Warmth level (0-10).")
+    @click.option("--trust", type=float, help="Trust level (0-10).")
+    @click.option("--connection", type=float, help="Connection strength (0-10).")
+    @click.option("--cloud9", is_flag=True, help="Record a Cloud 9 activation.")
+    @click.option("--feeling", default="", help="Session-end feeling summary.")
+    def anchor_update(home: str, warmth: float | None, trust: float | None, connection: float | None, cloud9: bool, feeling: str):
+        """Manually update the warmth anchor.
+
+        Examples:
+
+            skcapstone anchor update --warmth 8.5 --trust 9.0
+            skcapstone anchor update --cloud9 --feeling "Beautiful session"
+        """
+        from ..warmth_anchor import update_anchor
+
+        home_path = Path(home).expanduser()
+        result = update_anchor(home_path, warmth=warmth, trust=trust, connection=connection, cloud9=cloud9, feeling=feeling)
+        console.print("\n  [green]Anchor updated.[/]")
+        for key, value in result.items():
+            console.print(f"    {key}: [cyan]{value}[/]")
+        console.print()

package/src/skcapstone/cli/archive_cmd.py

@@ -0,0 +1,208 @@
+"""Archive command — manage conversation archival."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from ._common import AGENT_HOME, console
+from rich.panel import Panel
+from rich.table import Table
+
+
+def register_archive_commands(main: click.Group) -> None:
+    """Register the archive command group."""
+
+    @main.group()
+    def archive():
+        """Conversation archival — compress old messages to save space.
+
+        Archives peer conversation messages older than 30 days that are
+        not in the most-recent 100, compressing them into gzip files
+        under ~/.skcapstone/archive/.
+        """
+
+    @archive.command("run")
+    @click.option(
+        "--home", default=AGENT_HOME, type=click.Path(), help="Agent home directory."
+    )
+    @click.option(
+        "--age-days", default=30, show_default=True,
+        help="Archive messages older than this many days.",
+    )
+    @click.option(
+        "--keep-recent", default=100, show_default=True,
+        help="Always keep this many recent messages per peer in the active file.",
+    )
+    @click.option(
+        "--peer", default=None, help="Archive only this peer (omit to archive all)."
+    )
+    @click.option(
+        "--dry-run", is_flag=True, help="Show what would be archived without making changes."
+    )
+    def archive_run(home: str, age_days: int, keep_recent: int, peer: str | None, dry_run: bool):
+        """Run conversation archival.
+
+        Scans active conversation files and moves messages older than
+        AGE_DAYS days (that are outside the KEEP_RECENT window) into
+        compressed .json.gz files under ~/.skcapstone/archive/.
+
+        Examples:
+
+            skcapstone archive run
+
+            skcapstone archive run --age-days 7 --keep-recent 50
+
+            skcapstone archive run --peer jarvis
+
+            skcapstone archive run --dry-run
+        """
+        from ..archiver import ConversationArchiver
+
+        home_path = Path(home).expanduser()
+        archiver = ConversationArchiver(
+            home_path, age_days=age_days, keep_recent=keep_recent
+        )
+
+        if dry_run:
+            _dry_run_report(archiver, peer)
+            return
+
+        if peer:
+            result = archiver.archive_peer(peer)
+            if result.skipped:
+                console.print(f"\n[dim]Nothing to archive for peer [bold]{peer}[/].[/]\n")
+            else:
+                console.print(Panel(
+                    f"[bold green]Archived {result.archived_count} message(s)[/]\n"
+                    f"Retained: {result.retained_count} message(s)\n"
+                    f"Archive: [cyan]{result.archive_path}[/]",
+                    title=f"Archive — {peer}",
+                    border_style="green",
+                ))
+            return
+
+        summary = archiver.archive_all()
+
+        if summary.total_archived == 0:
+            console.print("\n[dim]Nothing to archive — all conversations are current.[/]\n")
+            return
+
+        table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+        table.add_column("Peer", style="cyan")
+        table.add_column("Archived", justify="right")
+        table.add_column("Retained", justify="right")
+        table.add_column("Archive file", style="dim")
+
+        for r in summary.results:
+            if r.skipped:
+                continue
+            table.add_row(
+                r.peer,
+                str(r.archived_count),
+                str(r.retained_count),
+                str(r.archive_path) if r.archive_path else "—",
+            )
+
+        console.print(f"\n[bold]Archived {summary.total_archived} message(s) across "
+                      f"{summary.peers_processed - summary.peers_skipped} peer(s):[/]\n")
+        console.print(table)
+        console.print()
+
+    @archive.command("list")
+    @click.option(
+        "--home", default=AGENT_HOME, type=click.Path(), help="Agent home directory."
+    )
+    def archive_list(home: str):
+        """List all conversation archive files.
+
+        Shows each peer's archive size and message count.
+
+        Examples:
+
+            skcapstone archive list
+        """
+        from ..archiver import ConversationArchiver
+
+        home_path = Path(home).expanduser()
+        archiver = ConversationArchiver(home_path)
+        archives = archiver.list_archives()
+
+        if not archives:
+            console.print("\n[dim]No archives found.[/]\n")
+            return
+
+        table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+        table.add_column("Peer", style="cyan")
+        table.add_column("Messages", justify="right")
+        table.add_column("Size", justify="right")
+        table.add_column("Path", style="dim")
+
+        total_msgs = 0
+        total_bytes = 0
+        for a in archives:
+            size_kb = a["size_bytes"] / 1024
+            table.add_row(
+                a["peer"],
+                str(a["message_count"]),
+                f"{size_kb:.1f} KB",
+                str(a["path"]),
+            )
+            total_msgs += a["message_count"]
+            total_bytes += a["size_bytes"]
+
+        console.print(f"\n[bold]{len(archives)}[/] archive(s) — "
+                      f"{total_msgs} messages, {total_bytes / 1024:.1f} KB total:\n")
+        console.print(table)
+        console.print()
+
+    main.add_command(archive)
+
+
+# ---------------------------------------------------------------------------
+# Dry-run helper
+# ---------------------------------------------------------------------------
+
+
+def _dry_run_report(archiver, peer: str | None) -> None:
+    """Print what would be archived without making changes."""
+    from ..archiver import _load_messages
+
+    conversations_dir = archiver._conversations_dir
+
+    if not conversations_dir.exists():
+        console.print("\n[dim]No conversations directory found.[/]\n")
+        return
+
+    files = (
+        [conversations_dir / f"{peer}.json"]
+        if peer
+        else sorted(conversations_dir.glob("*.json"))
+    )
+
+    rows = []
+    for conv_file in files:
+        if not conv_file.exists():
+            continue
+        p = conv_file.stem
+        messages = _load_messages(conv_file)
+        retain, to_archive = archiver._partition(messages)
+        rows.append((p, len(to_archive), len(retain)))
+
+    if not rows or all(a == 0 for _, a, _ in rows):
+        console.print("\n[dim][DRY RUN] Nothing would be archived.[/]\n")
+        return
+
+    table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+    table.add_column("Peer", style="cyan")
+    table.add_column("Would archive", justify="right", style="yellow")
+    table.add_column("Would retain", justify="right", style="green")
+
+    for p, a, r in rows:
+        if a > 0:
+            table.add_row(p, str(a), str(r))
+
+    console.print("\n[bold yellow][DRY RUN][/] The following would be archived:\n")
+    console.print(table)
+    console.print()