devopsiq 0.1.0__py3-none-any.whl

tools/investigation.py

@@ -0,0 +1,357 @@
+"""Investigation meta-tools (Phase 4).
+
+The model uses these three tools to maintain a first-class investigation
+record (agent/investigation.py) while it works a reported problem: open the
+investigation, record hypotheses / evidence / verdicts, and conclude with
+root cause + remediation + verification.
+
+These are the only "stateful" tools — and they mutate NOTHING outside the
+agent's own memory: no cluster, no files, no infrastructure. The read-only
+guarantee of the project is unaffected.
+
+Phase 7 adds persistence: every mutation is auto-saved (best-effort) to the
+InvestigationStore (agent/store.py), so the record survives CLI exits. The
+save hook lives here because all record mutations funnel through the shared
+functions below — tool executors and CLI commands are literally the same
+code path.
+"""
+
+from agent.investigation import (
+    CONFIDENCE_LEVELS,
+    HYPOTHESIS_STATUSES,
+    Investigation,
+    InvestigationError,
+)
+from agent.store import InvestigationStore, default_store
+from tools.base import Tool, ToolError
+from tools.registry import register
+
+# The single active investigation for this agent process (single-threaded CLI).
+_active: Investigation | None = None
+
+# Persistence (Phase 7): resolved lazily (explicit > AGENT_STORE_DIR > the
+# default home directory), disableable for tests. set_store(None) turns
+# persistence off; _get_store() otherwise resolves and caches a default.
+_store: InvestigationStore | None = None
+_store_disabled: bool = False
+
+
+def set_store(store: InvestigationStore | None) -> None:
+    """Replace the persistence store (tests pass None to disable saving)."""
+    global _store, _store_disabled
+    _store = store
+    _store_disabled = store is None
+
+
+def _get_store() -> InvestigationStore | None:
+    """The process store, or None when persistence is off/unavailable."""
+    global _store
+    if _store_disabled:
+        return None
+    if _store is None:
+        try:
+            _store = default_store()
+        except Exception:  # noqa: BLE001 — persistence must never break the agent
+            return None
+    return _store
+
+
+def _persist() -> str:
+    """Auto-save the active record; returns a short note for the result text.
+
+    Best-effort: an unavailable store returns "" (no note, no error) and a
+    failing save adds a one-line note instead of raising.
+    """
+    store = _get_store()
+    if store is None:
+        return ""
+    path = store.save(_active)
+    if path is None:
+        return "\n(note: persistence unavailable — the record is not being saved)"
+    return f"\n(saved to {path})"
+
+
+# --- thin functions shared by the CLI and the tool executors ---
+
+def start_investigation(problem: str, hypotheses: list[str] | None = None) -> str:
+    """Open an investigation (tool executor and /investigate both route here)."""
+    global _active
+    if _active is not None:
+        return "an investigation is already active:\n" + _active.render_status()
+    try:
+        _active = Investigation(problem, hypotheses)
+    except InvestigationError as exc:
+        raise ToolError(str(exc)) from exc
+    return (
+        "Investigation started.\n"
+        + _active.render_status()
+        + _persist()
+        + "\n\nTrack hypotheses and evidence with investigation_record, and "
+          "finish with investigation_conclude."
+    )
+
+
+def record(
+    kind: str,
+    content: str,
+    hypothesis_id: str | None = None,
+    status: str | None = None,
+) -> str:
+    inv = _require_active()
+    try:
+        kind = (kind or "").strip()
+        if kind == "hypothesis":
+            result = inv.add_hypothesis(content)
+        elif kind == "evidence":
+            result = inv.record_evidence(content, hypothesis_id)
+        elif kind == "verdict":
+            if not hypothesis_id or not status:
+                raise InvestigationError(
+                    "a verdict requires both hypothesis_id and status"
+                )
+            result = inv.verify_hypothesis(hypothesis_id, status, content)
+        else:
+            raise InvestigationError(
+                f"unknown kind {kind!r}; expected hypothesis | evidence | verdict"
+            )
+    except InvestigationError as exc:
+        raise ToolError(str(exc)) from exc
+    return result + "\n" + inv.render_status() + _persist()
+
+
+def conclude_investigation(
+    *,
+    summary: str,
+    root_cause: str,
+    remediation: str | list[str],
+    verification: str | list[str],
+    confidence: str = "medium",
+) -> str:
+    inv = _require_active()
+    try:
+        result = inv.conclude(
+            summary=summary,
+            root_cause=root_cause,
+            remediation=remediation,
+            verification=verification,
+            confidence=confidence,
+        )
+    except InvestigationError as exc:
+        raise ToolError(str(exc)) from exc
+    return result + _persist()
+
+
+def status_text() -> str | None:
+    return _active.render_status() if _active is not None else None
+
+
+def report_text() -> str | None:
+    """Current tracker, or the canonical report once concluded."""
+    return _active.render_report() if _active is not None else None
+
+
+def report_json() -> dict | None:
+    """Structured JSON export of the active investigation (CI/automation)."""
+    return _active.render_report_json() if _active is not None else None
+
+
+def finish_investigation() -> str:
+    global _active
+    if _active is None:
+        return "no active investigation"
+    _active = None
+    store = _get_store()
+    if store is not None:
+        store.forget()  # clears memory only — the saved copy stays as history
+    return "investigation cleared"
+
+
+def resume_investigation() -> str | None:
+    """Load the newest in-progress record from the store into memory.
+
+    Returns a short notice, or None when nothing was resumed (persistence
+    off, no saved in-progress record, or an investigation is already
+    active).
+    """
+    global _active
+    if _active is not None:
+        return None
+    store = _get_store()
+    if store is None:
+        return None
+    inv = store.resume_latest()
+    if inv is None:
+        return None
+    _active = inv
+    return f"Resumed: {inv.problem} — /investigation to view, continue as before."
+
+
+def list_saved_text() -> str | None:
+    """Rendered list of saved records, or None when there is nothing to show."""
+    store = _get_store()
+    if store is None:
+        return None
+    rows = store.list_saved()
+    if not rows:
+        return None
+    current = store.current_file
+    lines = ["**Saved investigations** (newest first)"]
+    for row in rows:
+        marker = "  <- active" if row["file"] == current else ""
+        lines.append(f"- [{row['status']}] {row['file']}{marker} — {row['problem']}")
+    return "\n".join(lines)
+
+
+def store_directory_text() -> str | None:
+    """Where records are being saved, or None when persistence is off."""
+    store = _get_store()
+    return str(store.directory) if store is not None else None
+
+
+def _require_active() -> Investigation:
+    if _active is None:
+        raise ToolError(
+            "no active investigation. Call investigation_begin first (the "
+            "user must be reporting a concrete problem)."
+        )
+    return _active
+
+
+# --- tool executors (adapter from parsed args dict to the functions above) ---
+
+
+def _begin_executor(args: dict) -> str:
+    return start_investigation(
+        args.get("problem"),
+        args.get("initial_hypotheses"),
+    )
+
+
+def _record_executor(args: dict) -> str:
+    return record(
+        kind=args.get("kind"),
+        content=args.get("content"),
+        hypothesis_id=args.get("hypothesis_id"),
+        status=args.get("status"),
+    )
+
+
+def _conclude_executor(args: dict) -> str:
+    return conclude_investigation(
+        summary=args.get("summary"),
+        root_cause=args.get("root_cause"),
+        remediation=args.get("remediation"),
+        verification=args.get("verification"),
+        confidence=args.get("confidence", "medium"),
+    )
+
+
+INVESTIGATION_BEGIN = Tool(
+    name="investigation_begin",
+    description=(
+        "Start a formal incident investigation for a problem the user just "
+        "reported (a failing pod, broken rollout, alert, degradation — NOT a "
+        "general question). Call this BEFORE gathering evidence, listing your "
+        "initial hypotheses. Returns the live investigation tracker."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "problem": {
+                "type": "string",
+                "description": "One-line statement of the problem to investigate.",
+            },
+            "initial_hypotheses": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "2-4 plausible causes to test (will become H1, H2, ...).",
+            },
+        },
+        "required": ["problem"],
+        "additionalProperties": False,
+    },
+    executor=_begin_executor,
+)
+
+INVESTIGATION_RECORD = Tool(
+    name="investigation_record",
+    description=(
+        "Record something into the ACTIVE investigation: a new hypothesis "
+        "(kind=hypothesis), an evidence note linked to a hypothesis "
+        "(kind=evidence, optional hypothesis_id), or a verdict updating a "
+        "hypothesis (kind=verdict with hypothesis_id and status). Returns the "
+        "updated tracker. Requires an active investigation."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "kind": {
+                "type": "string",
+                "enum": ["hypothesis", "evidence", "verdict"],
+                "description": "What to record.",
+            },
+            "content": {
+                "type": "string",
+                "description": "The hypothesis statement, evidence note, or "
+                "verdict justification.",
+            },
+            "hypothesis_id": {
+                "type": "string",
+                "description": "Hypothesis id (H1, H2, ...) to link evidence to "
+                "or to give a verdict.",
+            },
+            "status": {
+                "type": "string",
+                "enum": list(HYPOTHESIS_STATUSES),
+                "description": "For kind=verdict: new status of the hypothesis.",
+            },
+        },
+        "required": ["kind", "content"],
+        "additionalProperties": False,
+    },
+    executor=_record_executor,
+)
+
+INVESTIGATION_CONCLUDE = Tool(
+    name="investigation_conclude",
+    description=(
+        "Finish the ACTIVE investigation once evidence is sufficient: name the "
+        "root cause, remediation RECOMMENDATIONS (you never execute anything), "
+        "verification steps, and your confidence. Requires an active "
+        "investigation run by investigation_begin."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "summary": {
+                "type": "string",
+                "description": "One-paragraph summary of the investigation.",
+            },
+            "root_cause": {
+                "type": "string",
+                "description": "The confirmed/likeliest root cause.",
+            },
+            "remediation": {
+                "oneOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}],
+                "description": "Recommended fixes (read-only agent: these are "
+                "proposals, never executed).",
+            },
+            "verification": {
+                "oneOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}],
+                "description": "Steps to confirm the fix worked.",
+            },
+            "confidence": {
+                "type": "string",
+                "enum": list(CONFIDENCE_LEVELS),
+                "description": "Confidence in the root cause.",
+            },
+        },
+        "required": ["summary", "root_cause", "remediation", "verification"],
+        "additionalProperties": False,
+    },
+    executor=_conclude_executor,
+)
+
+register(INVESTIGATION_BEGIN)
+register(INVESTIGATION_RECORD)
+register(INVESTIGATION_CONCLUDE)

tools/istio.py

@@ -0,0 +1,43 @@
+"""Read-only Istio tools (Phase 9).
+
+One tool: `istioctl proxy-status` — the service mesh's control-plane view of
+every connected Envoy proxy: which proxies exist, their cluster, their sync
+version with istiod, and which are STALE (not receiving config — the mesh
+version of a node NotReady).
+
+Safety model:
+- A single fixed argv template, no arguments at all — the model cannot
+  inject anything. istioctl's mutating verbs (proxy-config with write
+  paths, install, upgrade, webhook apply, x) are unreachable.
+- istioctl must be installed and pointed at a mesh; missing/unreachable
+  surfaces as the exact CLI error.
+"""
+
+from tools.base import Tool, read_command_output
+from tools.registry import register
+
+_TIMEOUT_S = 15
+
+
+def _istioctl_proxy_status(args: dict) -> str:
+    return read_command_output(
+        ("istioctl", "proxy-status"),
+        timeout=_TIMEOUT_S,
+    )
+
+
+ISTIOCTL_PROXY_STATUS = Tool(
+    name="istioctl_proxy_status",
+    description=(
+        "Istio mesh proxy status (istioctl proxy-status): every Envoy "
+        "proxy (CLUSTER/CDS/LDS/RDS/ECDS out-of-sync columns) and which "
+        "ones are STALE — out of sync with istiod. Use for mesh problems: "
+        "'traffic isn't following the new config', 'a sidecar stopped "
+        "receiving updates'. Requires istioctl + a reachable mesh. "
+        "Read-only."
+    ),
+    parameters={"type": "object", "properties": {}, "additionalProperties": False},
+    executor=_istioctl_proxy_status,
+)
+
+register(ISTIOCTL_PROXY_STATUS)