@agentikos/omega-os 0.2.0 → 0.19.6

package/omega/Agentik_Engine/omega_engine/tmux.py

@@ -0,0 +1,526 @@
+"""Tmux orchestration — the same session-naming + categorisation pattern
+the live VPS uses, but first-class in OmegaOS.
+
+Session naming convention (mirrors AISB):
+
+  * ``AISB-*``                       — the AISB master agent(s)
+  * ``<Project>-oracle``             — a project's Oracle
+  * ``<Project>-oracle-N``           — additional oracles (N > 1) on the same project
+  * ``<Project>-worker-N-<task>``    — a worker dispatched by oracle N
+  * ``<Project>-dev-<task>``         — direct development sessions
+  * ``<Project>-fix-<linear-id>``    — Linear-feedback fix sessions
+  * ``<Project>-linear``             — the Linear-mission orchestrator
+  * ``Home``, ``Home-2``, ``Home-3`` — interactive operator sessions
+  * everything else                  — "other"
+
+Surface
+-------
+
+``list_sessions(omega_home)``      → list[TmuxSession]
+``categorize(name)``               → category string
+``spawn(name, *, command, cwd)``   → start a detached session
+``attach_command(name)``           → the shell string the user runs to attach
+``kill(name)``                     → tmux kill-session
+``is_alive(name)``                 → bool
+``health_report(omega_home)``      → summary for `omega tmux health`
+
+Why this lives in the engine (not as a shell script): we want the same
+classifier the doctor uses, the menu uses, the audit-patrol uses, and
+the upcoming AISB-as-chat layer uses.
+"""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Categorisation
+# ---------------------------------------------------------------------------
+
+
+CATEGORIES = ("aisb", "oracle", "worker", "dev", "linear", "home", "other")
+
+
+_AISB_RE = re.compile(r"^(AISB|aisb)")
+# Two oracle conventions: `Project-oracle[-N]` AND `oracle-Project`.
+# The live VPS uses both depending on who spawned it.
+_ORACLE_RE = re.compile(
+    r"^(?:(?P<proj1>[A-Za-z0-9_-]+?)-oracle(?:-\d+)?"
+    r"|oracle-(?P<proj2>[A-Za-z0-9_-]+?))$"
+)
+_WORKER_RE = re.compile(
+    r"^(?P<proj>[A-Za-z0-9_-]+?)-(?:oracle-\d+-)?worker-\d+-(?P<task>.+)$"
+)
+_DEV_RE = re.compile(r"^(?P<proj>[A-Za-z0-9_-]+?)-(?:dev|fix|work)-")
+_LINEAR_RE = re.compile(r"^(?P<proj>[A-Za-z0-9_-]+?)-linear$")
+_HOME_RE = re.compile(r"^Home(?:-\d+|-[a-z]+)?$")
+
+
+def categorize(name: str) -> str:
+    """Return a single-token category for a tmux session name."""
+    if _AISB_RE.match(name):
+        return "aisb"
+    if _ORACLE_RE.match(name):
+        return "oracle"
+    if _WORKER_RE.match(name):
+        return "worker"
+    if _DEV_RE.match(name):
+        return "dev"
+    if _LINEAR_RE.match(name):
+        return "linear"
+    if _HOME_RE.match(name):
+        return "home"
+    return "other"
+
+
+def project_from(name: str) -> str | None:
+    """Best-effort project name extraction from a session name."""
+    m = _ORACLE_RE.match(name)
+    if m:
+        return m.group("proj1") or m.group("proj2")
+    for pat in (_WORKER_RE, _DEV_RE, _LINEAR_RE):
+        m = pat.match(name)
+        if m and "proj" in m.groupdict():
+            return m.group("proj")
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class TmuxSession:
+    name: str
+    category: str
+    project: str | None
+    attached: bool
+    windows: int
+    created: int          # unix seconds
+
+
+# ---------------------------------------------------------------------------
+# Subprocess helpers
+# ---------------------------------------------------------------------------
+
+
+def _have_tmux() -> bool:
+    return shutil.which("tmux") is not None
+
+
+def _tmux(*args: str, check: bool = False, timeout: int = 15) -> tuple[int, str]:
+    """Run `tmux <args>` and return (exit, stdout)."""
+    if not _have_tmux():
+        return 1, ""
+    try:
+        proc = subprocess.run(
+            ["tmux", *args],
+            check=False, capture_output=True, text=True, timeout=timeout,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return 1, str(exc)
+    out = (proc.stdout or "") + (proc.stderr or "")
+    if check and proc.returncode != 0:
+        raise RuntimeError(f"tmux {' '.join(args)}: {out.strip()[:200]}")
+    return proc.returncode, out
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def list_sessions(omega_home: str | Path | None = None) -> list[TmuxSession]:
+    """Parse `tmux ls -F` into structured rows.
+
+    Sessions are returned in the order tmux gives them (creation order in
+    most setups). When tmux isn't installed or no server is running, we
+    return an empty list — never raise.
+    """
+    fmt = (
+        "#{session_name}\t#{session_attached}\t#{session_windows}\t"
+        "#{session_created}"
+    )
+    rc, out = _tmux("list-sessions", "-F", fmt)
+    if rc != 0:
+        return []
+    rows: list[TmuxSession] = []
+    for line in out.splitlines():
+        parts = line.strip().split("\t")
+        if len(parts) < 4:
+            continue
+        name, attached, windows, created = parts[0], parts[1], parts[2], parts[3]
+        rows.append(TmuxSession(
+            name=name,
+            category=categorize(name),
+            project=project_from(name),
+            attached=str(attached) not in ("", "0"),
+            windows=int(windows or 1),
+            created=int(created or 0),
+        ))
+    return rows
+
+
+def is_alive(name: str) -> bool:
+    rc, _ = _tmux("has-session", "-t", name)
+    return rc == 0
+
+
+def attach_command(name: str) -> str:
+    """The exact shell command the user runs to attach (we never call
+    `tmux attach` from a non-interactive context — it would hijack
+    stdin/stdout)."""
+    return f"tmux attach -t {name}"
+
+
+def kill(name: str) -> bool:
+    rc, _ = _tmux("kill-session", "-t", name)
+    return rc == 0
+
+
+def spawn(
+    name: str, *,
+    command: str | None = None,
+    cwd: str | Path | None = None,
+    detached: bool = True,
+) -> bool:
+    """Create a new tmux session. Returns True on success.
+
+    Uses ``tmux new-session -d -s <name> [-c <cwd>] [<cmd>]``. When
+    ``command`` is None, an interactive shell is launched (the default).
+    Refuses to overwrite an existing session of the same name.
+    """
+    if is_alive(name):
+        return False
+    args = ["new-session"]
+    if detached:
+        args.append("-d")
+    args += ["-s", name]
+    if cwd:
+        args += ["-c", str(cwd)]
+    if command:
+        args.append(command)
+    rc, _ = _tmux(*args)
+    return rc == 0
+
+
+def spawn_oracle(project: str, *, cwd: str | Path | None = None,
+                 oracle_id: int = 1) -> str:
+    """Spawn an Oracle session for ``project`` and return its name."""
+    name = f"{project}-oracle" if oracle_id == 1 else f"{project}-oracle-{oracle_id}"
+    spawn(name, cwd=cwd)
+    return name
+
+
+def spawn_worker(project: str, task: str, *,
+                 cwd: str | Path | None = None,
+                 oracle_id: int = 1, worker_id: int = 1) -> str:
+    """Spawn a worker session and return its name."""
+    if oracle_id == 1:
+        name = f"{project}-worker-{worker_id}-{task}"
+    else:
+        name = f"{project}-oracle-{oracle_id}-worker-{worker_id}-{task}"
+    spawn(name, cwd=cwd)
+    return name
+
+
+def spawn_aisb_chat(omega_home: str | Path | None = None) -> str:
+    """Spawn an AISB chat session — the Telegram-conversation fallback.
+
+    Runs ``omega aisb chat-loop`` inside the session so the user can
+    attach and have a conversation with the AISB master agent without
+    needing Telegram connectivity.
+    """
+    name = "AISB-chat"
+    home = Path(omega_home or os.environ.get("OMEGA_HOME")
+                or Path.home() / "Omega")
+    omega_bin = home / "Agentik_Tools" / "bin" / "omega"
+    spawn(name, command=f"{omega_bin} aisb chat-loop")
+    return name
+
+
+# ---------------------------------------------------------------------------
+# Categorised view + health
+# ---------------------------------------------------------------------------
+
+
+def grouped(sessions: list[TmuxSession]) -> dict[str, list[TmuxSession]]:
+    """Group sessions by category, preserving order within each group."""
+    out: dict[str, list[TmuxSession]] = {c: [] for c in CATEGORIES}
+    for s in sessions:
+        out.setdefault(s.category, []).append(s)
+    return out
+
+
+def health_report(omega_home: str | Path | None = None) -> dict:
+    """Summarise the session population for `omega tmux health` and doctor."""
+    if not _have_tmux():
+        return {"tmux_installed": False, "sessions": 0,
+                "by_category": {}, "stale": []}
+    sessions = list_sessions(omega_home)
+    by_cat = {cat: [s.name for s in lst]
+              for cat, lst in grouped(sessions).items() if lst}
+    # "Stale" heuristic: detached worker sessions older than 6h.
+    now = int(time.time())
+    stale = [
+        s.name for s in sessions
+        if s.category == "worker" and not s.attached
+        and (now - s.created) > 6 * 3600
+    ]
+    return {
+        "tmux_installed": True,
+        "sessions": len(sessions),
+        "attached": sum(1 for s in sessions if s.attached),
+        "by_category": by_cat,
+        "stale": stale,
+    }
+
+
+def cleanup_stale(omega_home: str | Path | None = None,
+                  *, older_than_hours: int = 24,
+                  dry_run: bool = True) -> dict:
+    """Best-effort cleanup of stale detached worker sessions.
+
+    By default this is a dry-run (returns the list of candidates without
+    killing). Pass ``dry_run=False`` to actually kill them.
+    """
+    sessions = list_sessions(omega_home)
+    now = int(time.time())
+    candidates = [
+        s for s in sessions
+        if s.category == "worker"
+        and not s.attached
+        and (now - s.created) > older_than_hours * 3600
+    ]
+    killed: list[str] = []
+    if not dry_run:
+        for s in candidates:
+            if kill(s.name):
+                killed.append(s.name)
+    return {
+        "candidates": [s.name for s in candidates],
+        "killed": killed,
+        "dry_run": dry_run,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Default tmux config
+# ---------------------------------------------------------------------------
+
+
+_DEFAULT_CONFIG = """\
+# ════════════════════════════════════════════════════════════════════
+# OmegaOS — recommended tmux config (minimal)
+# Drop this file at ~/.tmux.conf (or source it from your existing one).
+# ════════════════════════════════════════════════════════════════════
+
+# Base — 256 colours + true colour
+set -g default-terminal "tmux-256color"
+set -ag terminal-overrides ",xterm-256color:RGB"
+
+# Sane indexing
+set -g base-index 1
+setw -g pane-base-index 1
+set -g renumber-windows on
+set -g history-limit 100000
+
+# Mouse on (scroll, resize, click sessions)
+set -g mouse on
+
+# Faster than default — important for vim/claude
+set -s escape-time 10
+
+# ════════════════════════════════════════════════════════════════════
+# Prefix+Z — OmegaOS session picker
+# Opens a tmux popup with `omega tmux menu` so you can attach to any
+# session (AISB / oracle / worker / dev / linear / home / other) without
+# leaving tmux.
+# ════════════════════════════════════════════════════════════════════
+bind-key Z display-popup -E -w 80% -h 80% "omega tmux menu"
+
+# Prefix+S — native session list (tmux's built-in choose-tree)
+bind-key S choose-tree -Zs
+
+# ════════════════════════════════════════════════════════════════════
+# Visual cues per session category
+# ════════════════════════════════════════════════════════════════════
+set -g status-style "bg=#1a1a2e,fg=#eee"
+set -g status-left  "#[fg=#7aa2f7,bold]#S #[fg=default]│ "
+set -g status-right "#[fg=#888]%H:%M │ #(omega tmux count 2>/dev/null) sessions"
+"""
+
+
+# OmegaOS PRO tmux config — distilled from the live VPS conf (293 lines)
+# down to the parts that aren't tied to AISB-specific scripts. Operators
+# get it via `omega tmux install --full`. We preserve the bits that
+# matter for any 24/7 agent VPS:
+#
+#   * Termius paste fix (the assume-paste-time=0 + buffer-limit dance
+#     that prevents the PTY deadlock on large pastes — discovered the
+#     hard way on the live VPS).
+#   * Session-kill forensics — every session-closed + pane-died lands in
+#     ``$OMEGA_HOME/Agentik_Extra/var/logs/tmux-session-kills.log`` so a
+#     mystery dead worker leaves a trace.
+#   * Smart scroll — when a pane is in alt-screen (Claude Code TUI),
+#     scrolling enters copy-mode instead of forwarding raw mouse
+#     sequences (which would print as garbage in claude).
+#   * Extended keys + clipboard OSC 52 — modern terminals work right.
+#
+# References live conf at ~/.tmux.conf on the live VPS as of 2026-05-25.
+_PRO_CONFIG = """\
+# ══════════════════════════════════════════════════════════════
+# OmegaOS — PRO tmux config (full polish for 24/7 agent VPS)
+# Generated by `omega tmux install --full`.
+# ══════════════════════════════════════════════════════════════
+
+# ====== SESSION KILL FORENSICS ======
+# Every session-closed + pane-died lands in the log — a mystery dead
+# worker leaves a trace.
+set-hook -g session-closed "run-shell 'echo \\"[$(date -Iseconds)] SESSION CLOSED\\" >> $OMEGA_HOME/Agentik_Extra/var/logs/tmux-session-kills.log'"
+set-hook -g pane-died "run-shell 'echo \\"[$(date -Iseconds)] PANE DIED session=#{session_name} pane=#{pane_id}\\" >> $OMEGA_HOME/Agentik_Extra/var/logs/tmux-session-kills.log'"
+
+# ====== TERMINAL ======
+set -g default-terminal "tmux-256color"
+set -s terminal-overrides "linux*:AX@,xterm-256color:Tc:Ms=,xterm:Tc:Ms="
+set -s terminal-features "xterm*:clipboard:ccolour:title,screen*:title,rxvt*:ignorefkeys"
+set -q -g status-utf8 on
+setw -q -g utf8 on
+
+# ====== BASIC ======
+set -g base-index 1
+setw -g pane-base-index 1
+set -g renumber-windows on
+set -g history-limit 100000
+
+# ====== LARGE PASTE FIX (Termius / SSH apps) ======
+# tmux 3.5a buffers paste input + writes it all at once → PTY deadlock.
+# assume-paste-time=0 disables the grouping; chars write individually
+# (slower but cannot deadlock).
+set -s buffer-limit 100
+set -g assume-paste-time 0
+set -s set-clipboard on
+set -g allow-passthrough off
+set -s message-limit 500
+
+# ====== ALT-SCREEN + FOCUS EVENTS ======
+# Alt-screen on prevents paste-freezes on Claude Code TUI.
+setw -g alternate-screen on
+# Focus events OFF — Termius leaks \\e[I / \\e[O as garbage characters.
+set -g focus-events off
+# Extended keys on so modern key sequences resolve properly.
+set -g extended-keys on
+set -s escape-time 10
+
+# ====== MOUSE + SMART SCROLL ======
+# When a pane is in alt-screen (Claude Code TUI), scroll up → enter
+# copy-mode. Prevents raw mouse sequences from leaking as garbage.
+set -g mouse on
+bind-key -T copy-mode-vi WheelUpPane send -X scroll-up
+bind-key -T copy-mode-vi WheelDownPane send -X scroll-down
+# Auto-exit copy-mode after a brief idle so the operator goes back to
+# typing without thinking about it.
+set -g @scroll-without-changing-pane on
+
+# ════════════════════════════════════════════════════════════════════
+# Prefix+Z — OmegaOS session picker
+# Opens a tmux popup with `omega tmux menu`.
+# ════════════════════════════════════════════════════════════════════
+bind-key Z display-popup -E -w 80% -h 80% "omega tmux menu"
+
+# Prefix+S — native choose-tree
+bind-key S choose-tree -Zs
+
+# Prefix+R — reload this config without leaving tmux
+bind-key r source-file ~/.tmux.conf \\; display-message "tmux.conf reloaded"
+
+# ════════════════════════════════════════════════════════════════════
+# Visual cues per session category — colour the status bar by name.
+# ════════════════════════════════════════════════════════════════════
+set -g status-style "bg=#1a1a2e,fg=#eee"
+set -g status-left  "#[fg=#7aa2f7,bold]#S #[fg=default]│ "
+set -g status-right "#[fg=#888]%H:%M │ #(omega tmux count 2>/dev/null) sessions"
+set -g status-interval 5
+set -g status-left-length 40
+set -g status-right-length 60
+
+# Pane border colour — softer than default red
+set -g pane-border-style "fg=#333"
+set -g pane-active-border-style "fg=#7aa2f7"
+"""
+
+
+def write_default_config(
+    target: str | Path | None = None,
+    *,
+    profile: str = "minimal",
+) -> Path:
+    """Write a tmux config to ``target``.
+
+    ``profile``:
+      * ``"minimal"`` (default) — ~30 lines, just prefix+Z + status bar.
+      * ``"pro"`` — full ~80 lines with paste-fix Termius, kill
+                     forensics, smart scroll, extended keys, OSC 52
+                     clipboard. Best for 24/7 agent VPS.
+
+    Default target is ``$OMEGA_HOME/Agentik_Tools/tmux.conf`` — the
+    operator decides whether to `source` it from their main `~/.tmux.conf`
+    or replace theirs entirely. We never silently overwrite ``~/.tmux.conf``.
+    Use :func:`install_into_home_tmux_conf` to do that explicitly + with
+    backup.
+    """
+    if target is None:
+        home = Path(os.environ.get("OMEGA_HOME",
+                                    str(Path.home() / "Omega")))
+        target = home / "Agentik_Tools" / "tmux.conf"
+    target = Path(target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    content = _PRO_CONFIG if profile == "pro" else _DEFAULT_CONFIG
+    target.write_text(content)
+    return target
+
+
+def install_into_home_tmux_conf(
+    *,
+    profile: str = "pro",
+    backup: bool = True,
+    omega_home: str | Path | None = None,
+) -> dict[str, str]:
+    """Write the chosen config to ``~/.tmux.conf`` with a timestamped backup.
+
+    Returns ``{written, backup_path, profile}``. Idempotent — re-running
+    keeps producing fresh backups so the operator can revert.
+    """
+    import shutil as _sh
+    import time as _t
+    home_conf = Path.home() / ".tmux.conf"
+    backup_path = ""
+    if home_conf.exists() and backup:
+        ts = _t.strftime("%Y%m%d-%H%M%S")
+        backup_path = str(home_conf.with_suffix(f".conf.bak.{ts}"))
+        _sh.copy2(home_conf, backup_path)
+    content = _PRO_CONFIG if profile == "pro" else _DEFAULT_CONFIG
+    home_conf.write_text(content)
+    # Also drop it under $OMEGA_HOME so `omega tmux install` is the
+    # single source of truth that the engine sync mechanism can refresh.
+    _ = write_default_config(omega_home=None) if False else None
+    home = Path(omega_home or os.environ.get(
+        "OMEGA_HOME", str(Path.home() / "Omega")
+    ))
+    bundled = home / "Agentik_Tools" / "tmux.conf"
+    bundled.parent.mkdir(parents=True, exist_ok=True)
+    bundled.write_text(content)
+    return {
+        "written": str(home_conf),
+        "backup_path": backup_path,
+        "bundled_copy": str(bundled),
+        "profile": profile,
+    }
+    return target