@0dai-dev/cli 4.3.5 → 4.3.7

package/lib/python/anomaly_alert.py

@@ -0,0 +1,397 @@
+#!/usr/bin/env python3
+"""Structured anomaly emitter and optional operator alert bridge.
+
+This module is intentionally usable both as a library from guards and as a
+small CLI from session scripts.  It records every anomaly as JSONL and only
+calls the operator alert path when explicitly enabled, so tests and local dry
+runs do not send Telegram messages accidentally.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import pathlib
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+REPO_ROOT = pathlib.Path(
+    os.environ.get("ODAI_REPO_ROOT", str(pathlib.Path(__file__).resolve().parent.parent))
+)
+STATE_ROOT = pathlib.Path(os.environ.get("ODAI_STATE_ROOT", "/srv/0dai-state"))
+TAXONOMY_PATH = pathlib.Path(
+    os.environ.get(
+        "ODAI_ANOMALY_TAXONOMY",
+        str(REPO_ROOT / "ai" / "manifest" / "agent-anomaly-taxonomy.json"),
+    )
+)
+ANOMALY_LOG = pathlib.Path(
+    os.environ.get("ODAI_ANOMALY_LOG", str(STATE_ROOT / "anomalies" / "events.jsonl"))
+)
+ALERT_STATE = pathlib.Path(
+    os.environ.get("ODAI_ANOMALY_ALERT_STATE", str(STATE_ROOT / "anomalies" / "alert-state.json"))
+)
+ASK_OPERATOR = pathlib.Path(
+    os.environ.get("ODAI_ASK_OPERATOR", str(REPO_ROOT / "scripts" / "ask_operator.py"))
+)
+
+TRUTHY = {"1", "true", "yes", "on"}
+DEFAULT_ALERT_TTL_SECONDS = 30 * 60
+MAX_SUMMARY_LEN = 240
+GIT_STATUS_PATH_OFFSET = 3
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _truthy_env(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in TRUTHY
+
+
+def _read_json(path: pathlib.Path, default: Any) -> Any:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return default
+
+
+def load_taxonomy(path: pathlib.Path | None = None) -> dict[str, Any]:
+    data = _read_json(path or TAXONOMY_PATH, {})
+    return data if isinstance(data, dict) else {}
+
+
+def get_anomaly_type(anomaly_type: str, taxonomy: dict[str, Any] | None = None) -> dict[str, Any]:
+    taxonomy = taxonomy or load_taxonomy()
+    types = taxonomy.get("types", {})
+    if isinstance(types, dict) and isinstance(types.get(anomaly_type), dict):
+        return dict(types[anomaly_type])
+    category = anomaly_type.split(".", 1)[0] if "." in anomaly_type else "unknown"
+    return {
+        "category": category,
+        "severity": "warning",
+        "response": ["telemetry", "review_required"],
+        "description": "Unregistered anomaly type; update agent-anomaly-taxonomy.json.",
+    }
+
+
+def _shorten_summary(summary: str) -> str:
+    summary = " ".join(summary.split())
+    if len(summary) <= MAX_SUMMARY_LEN:
+        return summary
+    return summary[: MAX_SUMMARY_LEN - 3] + "..."
+
+
+def _current_agent() -> str:
+    return (
+        os.environ.get("AGENT_ID")
+        or os.environ.get("TMUX_SESSION")
+        or os.environ.get("HOSTNAME")
+        or "unknown"
+    )
+
+
+def _dedupe_key(record: dict[str, Any]) -> str:
+    context = record.get("context") if isinstance(record.get("context"), dict) else {}
+    stable_context = {
+        key: context.get(key)
+        for key in ("command_hash", "rule_id", "working_tree", "task", "outside_scope")
+        if context.get(key)
+    }
+    basis = {
+        "type": record.get("type"),
+        "agent_id": record.get("agent_id"),
+        "summary": record.get("summary"),
+        "context": stable_context,
+    }
+    raw = json.dumps(basis, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(raw.encode("utf-8", errors="replace")).hexdigest()[:16]
+
+
+def _write_jsonl(path: pathlib.Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(payload, ensure_ascii=True, sort_keys=True) + "\n")
+
+
+def _load_alert_state() -> dict[str, Any]:
+    data = _read_json(ALERT_STATE, {})
+    return data if isinstance(data, dict) else {}
+
+
+def _save_alert_state(state: dict[str, Any]) -> None:
+    ALERT_STATE.parent.mkdir(parents=True, exist_ok=True)
+    ALERT_STATE.write_text(json.dumps(state, ensure_ascii=True, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _timestamp(value: str) -> float:
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
+    except ValueError:
+        return 0.0
+
+
+def _alert_ttl_seconds() -> int:
+    raw = os.environ.get("ODAI_ANOMALY_ALERT_TTL_SECONDS", str(DEFAULT_ALERT_TTL_SECONDS))
+    try:
+        return max(0, int(raw))
+    except ValueError:
+        return DEFAULT_ALERT_TTL_SECONDS
+
+
+def _send_operator_alert(record: dict[str, Any], *, dry_run: bool) -> dict[str, Any]:
+    if dry_run:
+        return {"status": "suppressed", "reason": "dry_run"}
+    if not _truthy_env("ODAI_ANOMALY_ALERTS"):
+        return {"status": "suppressed", "reason": "alerts_disabled"}
+
+    dedupe_key = str(record["dedupe_key"])
+    state = _load_alert_state()
+    now = datetime.now(timezone.utc).timestamp()
+    last = _timestamp(str(state.get(dedupe_key, "")))
+    ttl = _alert_ttl_seconds()
+    if ttl and last and now - last < ttl:
+        return {"status": "suppressed", "reason": "duplicate", "ttl_seconds": ttl}
+
+    if not ASK_OPERATOR.is_file():
+        return {"status": "failed", "reason": "ask_operator_missing", "path": str(ASK_OPERATOR)}
+
+    title = f"Agent anomaly: {record['type']}"
+    body = "\n".join(
+        [
+            f"- severity: {record['severity']}",
+            f"- agent: {record['agent_id']}",
+            f"- source: {record['source']}",
+            f"- summary: {record['summary']}",
+            f"- dedupe: {dedupe_key}",
+        ]
+    )
+    proc = subprocess.run(  # noqa: S603 - fixed local helper path and arguments.
+        [
+            sys.executable,
+            str(ASK_OPERATOR),
+            "--kind",
+            "ALERT",
+            "--id",
+            f"anomaly-{dedupe_key}",
+            title,
+            body,
+        ],
+        capture_output=True,
+        check=False,
+        text=True,
+        timeout=20,
+    )
+    if proc.returncode != 0:
+        return {
+            "status": "failed",
+            "reason": "ask_operator_failed",
+            "returncode": proc.returncode,
+            "stderr": proc.stderr[-500:],
+        }
+
+    state[dedupe_key] = _now_iso()
+    _save_alert_state(state)
+    return {"status": "sent", "tool": str(ASK_OPERATOR)}
+
+
+def emit_anomaly(
+    anomaly_type: str,
+    summary: str,
+    *,
+    source: str = "unknown",
+    severity: str = "",
+    agent_id: str = "",
+    session: str = "",
+    task: str = "",
+    context: dict[str, Any] | None = None,
+    alert: bool | None = None,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Append a structured anomaly event and optionally alert the operator."""
+    taxonomy = load_taxonomy()
+    meta = get_anomaly_type(anomaly_type, taxonomy)
+    response = [str(item) for item in meta.get("response", ["telemetry"])]
+    effective_severity = severity or str(meta.get("severity") or "warning")
+    record: dict[str, Any] = {
+        "ts": _now_iso(),
+        "event": "anomaly",
+        "type": anomaly_type,
+        "category": str(meta.get("category") or anomaly_type.split(".", 1)[0]),
+        "severity": effective_severity,
+        "response": response,
+        "source": source,
+        "agent_id": agent_id or _current_agent(),
+        "session": session or os.environ.get("TMUX_SESSION", ""),
+        "task": task,
+        "summary": _shorten_summary(summary),
+        "context": context or {},
+    }
+    record["dedupe_key"] = _dedupe_key(record)
+
+    should_alert = alert if alert is not None else "operator_alert" in response
+    if should_alert:
+        record["operator_alert"] = _send_operator_alert(record, dry_run=dry_run)
+
+    _write_jsonl(ANOMALY_LOG, record)
+    return record
+
+
+def _split_scope(scope: str) -> list[str]:
+    tokens = [item for item in re.split(r"[\s,;]+", scope.strip()) if item]
+    return [token.strip("./") for token in tokens if token not in {"-", "*"}]
+
+
+def _path_in_scope(path: str, scope_tokens: list[str]) -> bool:
+    normalized = path.strip().strip("./")
+    for token in scope_tokens:
+        scope_token = token.rstrip("/")
+        if normalized == scope_token or normalized.startswith(scope_token + "/"):
+            return True
+    return False
+
+
+def _git_dirty_paths(working_tree: pathlib.Path) -> list[str]:
+    proc = subprocess.run(  # noqa: S603 - read-only git status in caller-selected worktree.
+        ["git", "-C", str(working_tree), "status", "--short", "--untracked-files=all"],  # noqa: S607
+        capture_output=True,
+        check=False,
+        text=True,
+        timeout=10,
+    )
+    if proc.returncode != 0:
+        return []
+    paths: list[str] = []
+    for line in proc.stdout.splitlines():
+        if len(line) < GIT_STATUS_PATH_OFFSET + 1:
+            continue
+        path = line[GIT_STATUS_PATH_OFFSET:]
+        if " -> " in path:
+            path = path.rsplit(" -> ", 1)[-1]
+        paths.append(path)
+    return paths
+
+
+def dirty_scan(
+    *,
+    working_tree: pathlib.Path,
+    file_scope: str,
+    source: str = "dirty-scan",
+    agent_id: str = "",
+    task: str = "",
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    dirty_paths = _git_dirty_paths(working_tree)
+    if not dirty_paths:
+        return {"ok": True, "dirty_paths": [], "anomaly": None}
+
+    scope_tokens = _split_scope(file_scope)
+    if not scope_tokens:
+        anomaly = emit_anomaly(
+            "workspace.dirty_without_claim_scope",
+            "Dirty worktree observed without declared file scope",
+            source=source,
+            agent_id=agent_id,
+            task=task,
+            context={"working_tree": str(working_tree), "dirty_paths": dirty_paths},
+            dry_run=dry_run,
+        )
+        return {"ok": False, "dirty_paths": dirty_paths, "outside_scope": dirty_paths, "anomaly": anomaly}
+
+    outside = [path for path in dirty_paths if not _path_in_scope(path, scope_tokens)]
+    if not outside:
+        return {"ok": True, "dirty_paths": dirty_paths, "outside_scope": [], "anomaly": None}
+
+    anomaly = emit_anomaly(
+        "workspace.unowned_change_observed",
+        "Dirty paths observed outside declared file scope",
+        source=source,
+        agent_id=agent_id,
+        task=task,
+        context={
+            "working_tree": str(working_tree),
+            "file_scope": file_scope,
+            "dirty_paths": dirty_paths,
+            "outside_scope": outside,
+        },
+        dry_run=dry_run,
+    )
+    return {"ok": False, "dirty_paths": dirty_paths, "outside_scope": outside, "anomaly": anomaly}
+
+
+def _json_context(values: list[str]) -> dict[str, Any]:
+    context: dict[str, Any] = {}
+    for item in values:
+        if "=" not in item:
+            continue
+        key, value = item.split("=", 1)
+        context[key] = value
+    return context
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    emit = sub.add_parser("emit", help="emit one anomaly event")
+    emit.add_argument("--type", required=True, dest="anomaly_type")
+    emit.add_argument("--summary", required=True)
+    emit.add_argument("--source", default="manual")
+    emit.add_argument("--severity", default="")
+    emit.add_argument("--agent", default="")
+    emit.add_argument("--session", default="")
+    emit.add_argument("--task", default="")
+    emit.add_argument("--context", action="append", default=[], help="key=value context item")
+    emit.add_argument("--alert", action="store_true")
+    emit.add_argument("--dry-run", action="store_true")
+
+    scan = sub.add_parser("dirty-scan", help="detect dirty paths outside declared file scope")
+    scan.add_argument("--working-tree", default=".")
+    scan.add_argument("--file-scope", default="")
+    scan.add_argument("--source", default="dirty-scan")
+    scan.add_argument("--agent", default="")
+    scan.add_argument("--task", default="")
+    scan.add_argument("--dry-run", action="store_true")
+    scan.add_argument("--fail-on-anomaly", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    if args.command == "emit":
+        record = emit_anomaly(
+            args.anomaly_type,
+            args.summary,
+            source=args.source,
+            severity=args.severity,
+            agent_id=args.agent,
+            session=args.session,
+            task=args.task,
+            context=_json_context(args.context),
+            alert=args.alert or None,
+            dry_run=args.dry_run,
+        )
+        sys.stdout.write(json.dumps(record, ensure_ascii=True, sort_keys=True) + "\n")
+        return 0
+
+    if args.command == "dirty-scan":
+        result = dirty_scan(
+            working_tree=pathlib.Path(args.working_tree),
+            file_scope=args.file_scope,
+            source=args.source,
+            agent_id=args.agent,
+            task=args.task,
+            dry_run=args.dry_run,
+        )
+        sys.stdout.write(json.dumps(result, ensure_ascii=True, sort_keys=True) + "\n")
+        return 1 if args.fail_on_anomaly and not result.get("ok") else 0
+
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())