marvisx-cli 0.1.0__py3-none-any.whl

core/api/agents/session_health.py

@@ -0,0 +1,59 @@
+# v1.0.0 - 2026-03-02 - DevX session health checker (v1: dimension C only)
+"""Session health check — DevX Layer Sprint 3.
+
+v1 implementa solo Dimensione C (Continuita): sessione idle senza input richiesto.
+Le dimensioni A (task hygiene), B (context%), D (output quality) sono deferred Sprint 4.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from core.api.models import SessionInfo
+
+logger = logging.getLogger(__name__)
+
+IDLE_THRESHOLD_MINUTES = 15
+SESSION_MANAGER_COOLDOWN_MINUTES = 30  # Rate limit: max 1 msg per sessione per 30 min
+
+
+@dataclass
+class HealthCheckResult:
+    session_name: str
+    action: str              # "send_message" | "escalate" | "ok"
+    message: str | None
+    escalation_reason: str | None
+
+
+async def check_session_health(
+    session: SessionInfo,
+    last_action_at: datetime | None,
+) -> HealthCheckResult:
+    """v1: Solo dimensione C — sessione idle senza input richiesto.
+
+    Le dimensioni A, B, D sono deferred alla prossima sprint
+    dopo validazione di C in produzione.
+    """
+    # Rate limit: non mandare piu di 1 messaggio per cooldown period
+    if last_action_at is not None:
+        elapsed = (datetime.now(timezone.utc) - last_action_at).total_seconds() / 60
+        if elapsed < SESSION_MANAGER_COOLDOWN_MINUTES:
+            return HealthCheckResult(session.name, "ok", None, None)
+
+    # C — Continuita: sessione idle senza input richiesto
+    if session.activity_state == "idle" and not _session_waiting_for_input(session):
+        return HealthCheckResult(
+            session.name,
+            "send_message",
+            "La sessione sembra ferma. Continua con il task corrente. "
+            "Ricorda di aggiornare i task e fare handoff a fine sessione.",
+            None,
+        )
+
+    return HealthCheckResult(session.name, "ok", None, None)
+
+
+def _session_waiting_for_input(session: SessionInfo) -> bool:
+    """True se la sessione CC sta aspettando input (needs_input activity state)."""
+    return session.activity_state == "needs_input"

core/api/agents/session_manager.py

@@ -0,0 +1,206 @@
+# v1.0.0 - 2026-03-02 - DevX Session Manager Agent
+"""Session Manager Agent — DevX Layer Sprint 3.
+
+Runs every 10 minutes via host cron or manual trigger.
+Monitors sessions with agent_managed=True, runs health checks, acts on results.
+
+Usage:
+    cd /data/pir && python -m api.agents.session_manager
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+import aiosqlite
+
+from core.api.config import settings
+from core.api.agents.session_health import check_session_health
+from core.api.models import SessionInfo
+from core.api.services import tmux
+
+logger = logging.getLogger(__name__)
+
+ERRORS_DIR = Path("/data/pir/logs/errors")
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+async def list_agent_managed_sessions() -> list[SessionInfo]:
+    """Return all sessions with agent_managed=True via the sessions API.
+
+    Uses the internal API endpoint to get live activity_state (computed from tmux,
+    not stored in DB). Falls back to empty list on error.
+    """
+    import urllib.request
+    from core.api.config import settings as cfg
+    token = cfg.tasks_api_token if hasattr(cfg, "tasks_api_token") else os.environ.get("TASKS_API_TOKEN", "")
+    api_base = os.environ.get("PIR_INTERNAL_BASE", "http://localhost:8100")
+    try:
+        req = urllib.request.Request(
+            f"{api_base}/api/v1/sessions?agent_managed=true",
+            headers={
+                "Authorization": f"Bearer {token}",
+                "X-Agent-Name": "marvisx",
+            },
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read())
+        return [SessionInfo(**s) for s in data]
+    except Exception as exc:
+        logger.error("Failed to list agent_managed sessions: %s", exc)
+        return []
+
+
+async def get_last_agent_action(db: aiosqlite.Connection, session_name: str) -> datetime | None:
+    """Return the last time an automated action was taken on this session."""
+    try:
+        cursor = await db.execute(
+            "SELECT MAX(created_at) FROM agent_actions WHERE session_name = ?",
+            (session_name,),
+        )
+        row = await cursor.fetchone()
+        if row and row[0]:
+            # Parse ISO string from SQLite — may be naive (no tz offset)
+            ts_str: str = row[0]
+            ts_str = ts_str.replace("Z", "+00:00")
+            dt = datetime.fromisoformat(ts_str)
+            # SQLite stores UTC without offset — assume UTC if naive
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=timezone.utc)
+            return dt
+    except Exception as exc:
+        logger.warning("Failed to get last agent action for %s: %s", session_name, exc)
+    return None
+
+
+async def log_agent_action(
+    db: aiosqlite.Connection,
+    session_name: str,
+    action: str,
+    detail: str | None,
+) -> None:
+    """Log an automated action taken on a session."""
+    try:
+        await db.execute(
+            """
+            INSERT INTO agent_actions (agent_name, session_name, action, detail, created_at)
+            VALUES (?, ?, ?, ?, ?)
+            """,
+            ("session-manager", session_name, action, detail, datetime.now(timezone.utc).isoformat()),
+        )
+        await db.commit()
+    except Exception as exc:
+        logger.error("Failed to log agent action: %s", exc)
+
+
+async def send_session_message(session_name: str, text: str) -> bool:
+    """Send a message to a tmux session."""
+    try:
+        return await tmux.send_keys(session_name, text)
+    except Exception as exc:
+        logger.error("Failed to send message to session %s: %s", session_name, exc)
+        return False
+
+
+async def send_telegram_alert(text: str) -> None:
+    """Send a Telegram alert (best-effort)."""
+    import urllib.request
+    if not settings.telegram_bot_token or not settings.telegram_owner_chat_id:
+        logger.info("Telegram not configured, skipping alert")
+        return
+    try:
+        url = f"https://api.telegram.org/bot{settings.telegram_bot_token}/sendMessage"
+        data = json.dumps({
+            "chat_id": settings.telegram_owner_chat_id,
+            "text": text,
+            "parse_mode": "HTML",
+        }).encode("utf-8")
+        req = urllib.request.Request(
+            url, data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            resp.read()
+    except Exception as exc:
+        logger.warning("Telegram alert failed: %s", exc)
+
+
+async def log_error_to_knowledge(session_name: str, error_text: str) -> None:
+    """Log an error to the knowledge errors store for downstream analysis."""
+    ERRORS_DIR.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    error_file = ERRORS_DIR / f"{ts}-session-manager-{session_name}.txt"
+    try:
+        error_file.write_text(
+            f"session: {session_name}\nerror: {error_text}\nts: {ts}\n"
+        )
+    except Exception as exc:
+        logger.error("Failed to write error file: %s", exc)
+
+
+# ── core loop ────────────────────────────────────────────────────────────────
+
+async def _process_session(
+    db: aiosqlite.Connection,
+    session: SessionInfo,
+) -> None:
+    """Process a single session — isolated to not block others."""
+    last_action_at = await get_last_agent_action(db, session.name)
+    result = await check_session_health(session, last_action_at)
+
+    if result.action == "send_message" and result.message:
+        success = await send_session_message(session.name, result.message)
+        if success:
+            await log_agent_action(db, session.name, "health_check:C", result.message)
+            logger.info("Sent health check message to session %s", session.name)
+        else:
+            logger.warning("Failed to send message to session %s", session.name)
+
+    elif result.action == "escalate" and result.escalation_reason:
+        await send_telegram_alert(
+            f"<b>DevX Escalation</b> — <code>{session.name}</code>\n\n{result.escalation_reason}"
+        )
+        await log_agent_action(db, session.name, "escalate", result.escalation_reason)
+        logger.warning("Escalated session %s: %s", session.name, result.escalation_reason)
+
+
+async def run_session_manager() -> None:
+    """Main loop: monitor agent_managed sessions, run health checks."""
+    logger.info("Session Manager starting...")
+    from core.api.db import write_db
+    async with write_db() as db:
+        sessions = await list_agent_managed_sessions()
+        if not sessions:
+            logger.info("No agent_managed sessions to monitor")
+            return
+
+        logger.info("Checking %d agent_managed session(s)...", len(sessions))
+
+        results = await asyncio.gather(
+            *[_process_session(db, s) for s in sessions],
+            return_exceptions=True,
+        )
+
+        for session, result in zip(sessions, results):
+            if isinstance(result, Exception):
+                logger.error(
+                    "Health check failed for session %s: %s", session.name, result
+                )
+                await log_error_to_knowledge(session.name, str(result))
+
+    logger.info("Session Manager complete")
+
+
+# ── CLI entrypoint ────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s — %(message)s",
+    )
+    asyncio.run(run_session_manager())

core/api/bin/marvisx-state-hook.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+# v1.0.0 - 2026-04-26 - Claude Code session state hook (PR2 plan 2026-04-26)
+"""Push Claude Code session lifecycle events to MarvisX backend.
+
+Wired to ~/.claude/settings.json hooks (PreToolUse, Stop, StopFailure,
+PermissionRequest, SessionStart, SessionEnd). Reads the Claude hook JSON
+payload from stdin, resolves the tmux session name, POSTs to
+`/api/v1/sessions/{name}/state`.
+
+Design choices (plan §M2/M3/M5/M6):
+
+- **Python over bash** (M5): single-process startup ~25ms vs bash+jq
+  fork chain at 80-150ms. Anthropic's <50ms PreToolUse target is reachable.
+
+- **fork + setsid + urllib** (M3): the parent process exits immediately so
+  Claude's hook completes fast. The child detaches from the parent's process
+  group via `os.setsid()` and uses urllib in-process (no curl exec, no token
+  leaking into argv visible in `ps -ef`). Survives parent SIGHUP — critical
+  for `Stop`/`SessionEnd` events fired during Claude shutdown.
+
+- **Token from file, not env** (M6): `~/.marvisx/agent-token` (mode 0600).
+  Env vars leak via `/proc/<pid>/environ` to other users on shared machines.
+
+- **Client-emitted ts** (M2): the backend uses this as the LWW key so that
+  out-of-order arrival between uvicorn workers doesn't leave the session
+  stuck in a stale state.
+
+- **Fail silent**: any error → exit 0. Hooks are fire-and-forget; surfacing
+  errors to Claude would be more noise than signal.
+"""
+from __future__ import annotations
+
+import json
+import os
+import socket
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib import error, request
+
+API_URL = os.environ.get("MARVISX_API_URL", "http://127.0.0.1:8100")
+TOKEN_FILE = Path.home() / ".marvisx" / "agent-token"
+TIMEOUT_SECS = 5
+
+
+def _read_token() -> str | None:
+    try:
+        if not TOKEN_FILE.exists():
+            return None
+        st = TOKEN_FILE.stat()
+        # Defense-in-depth: warn on loose perms but don't fail.
+        if st.st_mode & 0o077:
+            print(
+                f"[marvisx-state-hook] WARN: {TOKEN_FILE} permissive (chmod 600)",
+                file=sys.stderr,
+            )
+        return TOKEN_FILE.read_text(encoding="utf-8").strip() or None
+    except OSError:
+        return None
+
+
+def _resolve_session_name() -> str | None:
+    """Find the tmux session this hook is running inside.
+
+    Priority:
+    1. `TMUX_SESSION_NAME` env (exported by the launcher, plan §M9)
+    2. `MARVISX_SESSION_NAME` env (alternative explicit override)
+    3. `tmux display -p '#{session_name}'` if `$TMUX` is set
+    """
+    name = os.environ.get("TMUX_SESSION_NAME") or os.environ.get(
+        "MARVISX_SESSION_NAME"
+    )
+    if name:
+        return name
+    if not os.environ.get("TMUX"):
+        return None
+    import subprocess
+
+    try:
+        result = subprocess.run(
+            ["tmux", "display", "-p", "#{session_name}"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+            check=False,
+        )
+        if result.returncode == 0:
+            stripped = result.stdout.strip()
+            return stripped or None
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return None
+
+
+def _post(payload: dict, token: str, session_name: str) -> None:
+    """Send POST to backend. Called from the detached child only."""
+    url = f"{API_URL}/api/v1/sessions/{session_name}/state"
+    body = json.dumps(payload).encode("utf-8")
+    req = request.Request(
+        url,
+        data=body,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {token}",
+            "X-Agent-Name": "marvisx",
+        },
+    )
+    try:
+        with request.urlopen(req, timeout=TIMEOUT_SECS) as resp:  # noqa: S310
+            resp.read()
+    except (error.URLError, error.HTTPError, OSError, socket.timeout):
+        pass  # silent — hook is fire-and-forget
+
+
+def main() -> int:
+    try:
+        raw = sys.stdin.read()
+    except OSError:
+        return 0
+    if not raw:
+        return 0
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return 0
+
+    event = data.get("hook_event_name")
+    if not event:
+        return 0
+
+    session_name = _resolve_session_name()
+    if not session_name:
+        return 0
+
+    token = _read_token()
+    if not token:
+        return 0
+
+    payload = {
+        "provider": "claude",
+        "event": event,
+        "conv_id": data.get("session_id"),
+        "ts": datetime.now(timezone.utc).isoformat(),
+    }
+
+    # Fork-and-detach so the parent (hook) returns to Claude immediately and
+    # the child completes the POST even if Claude exits (Stop/SessionEnd
+    # races, julik R3). Posix-only — Marvis is Linux.
+    try:
+        pid = os.fork()
+    except OSError:
+        # Couldn't fork — last-resort inline POST.
+        _post(payload, token, session_name)
+        return 0
+
+    if pid > 0:
+        # Parent: hook returns success immediately.
+        return 0
+
+    # Child: detach from parent's session/process group + close inherited
+    # std streams to avoid keeping pipes alive after the parent exits.
+    try:
+        os.setsid()
+    except OSError:
+        pass
+    try:
+        for fd in (0, 1, 2):
+            os.close(fd)
+        devnull = os.open(os.devnull, os.O_RDWR)
+        os.dup2(devnull, 0)
+        os.dup2(devnull, 1)
+        os.dup2(devnull, 2)
+    except OSError:
+        pass
+
+    _post(payload, token, session_name)
+    os._exit(0)
+
+
+if __name__ == "__main__":
+    sys.exit(main())