vmware-debug 1.6.1__py3-none-any.whl

mcp_server/__init__.py

@@ -0,0 +1 @@
+"""stdio MCP server package for vmware-debug."""

mcp_server/server.py

@@ -0,0 +1,78 @@
+"""vmware-debug MCP server entry point.
+
+Tools are defined in vmware_debug.mcp.tools (so audit logs see skill=debug).
+This module wires them into a FastMCP server and provides the stdio entry point.
+
+Note: signatures here use typing.Optional, never PEP 604 ``X | None`` — FastMCP
+reflects these at registration and ``X | None`` crashes on Python 3.10 + older
+mcp/pydantic (CLAUDE.md 踩坑 #33).
+"""
+
+import sys
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from vmware_debug.mcp import tools as t
+
+
+def build_server() -> FastMCP:
+    """Construct and configure the MCP server."""
+    server = FastMCP("vmware-debug")
+
+    @server.tool(name="incident_timeline")
+    def _incident_timeline_impl(
+        events: list[dict],
+        bin_seconds: Optional[float] = None,
+        z_threshold: float = 2.0,
+        top_n: int = 5,
+    ) -> dict:
+        """[READ] Correlate already-fetched VMware events into one incident view.
+
+        WHEN: after you've pulled events for an incident from the data-source
+        skills (vmware-monitor event_list/alarm_list, vmware-aria alerts/anomaly,
+        vmware-log-insight log_search/log_aggregate, vmware-nsx) — feed them all
+        here to find what correlates and where to look next. This tool does NOT
+        fetch anything itself; it has no vCenter/network access.
+
+        INPUT: events = list of event envelopes, each {ts, source, severity,
+        entity, text, fields} (ts may be ISO-8601, epoch seconds, or millis;
+        severity is normalised). Optional: bin_seconds (time-bin width; auto if
+        omitted), z_threshold (spike sensitivity, default 2.0), top_n (max
+        hypotheses, default 5).
+
+        RETURNS: {event_count, window, spikes (anomalous time bins), hypotheses
+        (ranked root-cause candidates, each with a suggested_check), next_checks
+        (concrete ideas for what to investigate next, including which skill/tool
+        to run)}.
+
+        GOTCHAS: read-only and stateless — nothing is executed. Remediation is
+        routed to vmware-aiops (single fix) or vmware-pilot (multi-step, gated).
+        A malformed event raises ValueError naming its index."""
+        return t.incident_timeline(events, bin_seconds, z_threshold, top_n)
+
+    @server.tool(name="list_symptom_categories")
+    def _list_symptom_categories_impl() -> list[dict]:
+        """[READ] List the symptom categories vmware-debug recognises and, for
+        each, example keywords and the suggested next check (which skill/tool to
+        run). Takes no parameters. Use this when you don't yet know what to look
+        at — it turns "something's wrong" into concrete investigation steps.
+        Read-only; no network access."""
+        return t.list_symptom_categories()
+
+    return server
+
+
+def main() -> None:
+    """Entry point for `vmware-debug-mcp` (stdio transport)."""
+    if sys.version_info < (3, 11):
+        sys.exit(
+            "vmware-debug-mcp requires Python >= 3.11 (FastMCP schema reflection "
+            "is unreliable on 3.10). Reinstall under 3.11+: "
+            "uv tool install --python 3.11 vmware-debug"
+        )
+    build_server().run()
+
+
+if __name__ == "__main__":
+    main()

vmware_debug/__init__.py

@@ -0,0 +1,8 @@
+"""vmware-debug — VMware diagnostic brain.
+
+Read-only incident triage: correlate events from monitor/aria/log-insight/nsx
+into a unified timeline, detect spikes, rank root-cause hypotheses, and route
+remediation to vmware-aiops / vmware-pilot. Never writes; never executes fixes.
+"""
+
+__version__ = "1.6.1"

vmware_debug/cli.py

@@ -0,0 +1,85 @@
+"""vmware-debug CLI — read-only incident triage from the terminal.
+
+Correlation is local and offline: feed it events you've already collected (a
+JSON file or stdin) and it returns a ranked timeline + next-check ideas. The
+`mcp` subcommand starts the stdio MCP server (entry point that does not touch
+the network, so it works behind corporate TLS proxies — CLAUDE.md 踩坑 #25).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from vmware_debug import __version__
+from vmware_debug.mcp.tools import incident_timeline, list_symptom_categories
+
+app = typer.Typer(
+    add_completion=False,
+    help="VMware diagnostic brain — read-only incident triage and root-cause routing.",
+)
+console = Console()
+
+
+@app.command()
+def version() -> None:
+    """Print the installed version."""
+    console.print(f"vmware-debug {__version__}")
+
+
+@app.command()
+def categories() -> None:
+    """List the symptom categories debug recognises and what to check for each."""
+    table = Table(title="vmware-debug symptom categories")
+    table.add_column("category", style="cyan")
+    table.add_column("example keywords")
+    table.add_column("suggested check", style="green")
+    for c in list_symptom_categories():
+        table.add_row(c["category"], ", ".join(c["example_keywords"]), c["suggested_check"])
+    console.print(table)
+
+
+@app.command()
+def triage(
+    events_file: Optional[Path] = typer.Option(
+        None, "--events", "-e", help="JSON file of event envelopes; reads stdin if omitted."
+    ),
+    bin_seconds: Optional[float] = typer.Option(None, help="Time-bin width; auto if omitted."),
+    top_n: int = typer.Option(5, help="Max hypotheses to return."),
+) -> None:
+    """Correlate a set of pre-collected events into a ranked incident timeline."""
+    raw = events_file.read_text() if events_file else sys.stdin.read()
+    try:
+        events = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        console.print(f"[red]Invalid JSON:[/red] {exc}. Provide a JSON array of event envelopes.")
+        raise typer.Exit(code=2) from exc
+    if not isinstance(events, list):
+        console.print("[red]Expected a JSON array of event envelopes.[/red]")
+        raise typer.Exit(code=2)
+
+    try:
+        result = incident_timeline(events, bin_seconds=bin_seconds, top_n=top_n)
+    except ValueError as exc:
+        console.print(f"[red]Could not correlate events:[/red] {exc}")
+        raise typer.Exit(code=2) from exc
+
+    console.print_json(data=result)
+
+
+@app.command()
+def mcp() -> None:
+    """Start the stdio MCP server (no network access; proxy-safe)."""
+    from mcp_server.server import main as _main
+
+    _main()
+
+
+if __name__ == "__main__":
+    app()

vmware_debug/envelope.py

@@ -0,0 +1,173 @@
+"""The unified event envelope — the contract between vmware-debug and every
+data-source skill (monitor, aria, log-insight, nsx, ...).
+
+vmware-debug deliberately has NO runtime dependency on the other skill packages
+(CLAUDE.md 踩坑 #21/#32: no hidden cross-skill coupling, no version lockstep).
+Instead the orchestrating agent fetches events with each skill's own read tools
+and hands them to debug's correlator as plain dicts. This module normalises
+those heterogeneous dicts into one immutable ``Event`` shape so the timeline /
+spike / hypothesis logic can stay source-agnostic and unit-testable.
+
+Envelope shape (also documented in references/event-envelope.md):
+
+    {
+      "ts":       <ISO8601 string | epoch seconds | epoch millis>,
+      "source":   "monitor" | "aria" | "loginsight" | "nsx" | ...,
+      "severity": "critical" | "error" | "warning" | "info" | "unknown",
+      "entity":   "vm-web01" | "host-12" | "" ,
+      "text":     "<human-readable message>",
+      "fields":   { ... source-specific extras ... }
+    }
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+# Canonical severities, ordered by weight (higher = more severe). Used both for
+# normalisation and for hypothesis scoring.
+SEVERITY_WEIGHT: dict[str, int] = {
+    "critical": 5,
+    "error": 4,
+    "warning": 3,
+    "info": 1,
+    "unknown": 0,
+}
+
+# Common vendor spellings mapped onto the canonical set. Lower-cased on lookup.
+_SEVERITY_ALIASES: dict[str, str] = {
+    "crit": "critical",
+    "critical": "critical",
+    "fatal": "critical",
+    "alert": "critical",
+    "emergency": "critical",
+    "err": "error",
+    "error": "error",
+    "red": "error",
+    "warn": "warning",
+    "warning": "warning",
+    "yellow": "warning",
+    "notice": "info",
+    "info": "info",
+    "information": "info",
+    "informational": "info",
+    "green": "info",
+    "debug": "info",
+}
+
+
+@dataclass(frozen=True)
+class Event:
+    """One normalised observation on the incident timeline."""
+
+    ts: float  # epoch seconds (UTC)
+    source: str
+    severity: str
+    entity: str
+    text: str
+    fields: dict = field(default_factory=dict)
+
+
+def normalize_severity(raw: object) -> str:
+    """Map an arbitrary severity token onto the canonical set."""
+    if raw is None:
+        return "unknown"
+    return _SEVERITY_ALIASES.get(str(raw).strip().lower(), "unknown")
+
+
+# Numeric timestamps below this (epoch seconds for ~1973-03) are implausible for
+# VMware incident data and almost certainly a parse error (e.g. a bare year like
+# "2020" -> 1970). Rejected loudly rather than landing silently at the epoch.
+_MIN_PLAUSIBLE_EPOCH = 10**8
+
+
+def parse_timestamp(raw: object) -> float:
+    """Parse a timestamp into epoch seconds (UTC).
+
+    Accepts ISO-8601 strings (with or without 'Z'), epoch seconds, or epoch
+    milliseconds (auto-detected by magnitude). ISO is tried before the numeric
+    fallback, and implausibly small epochs are rejected, so a malformed value
+    (a bare year, garbage) surfaces loudly rather than landing at 1970.
+    bool is excluded explicitly (it is an int subclass).
+    """
+    if isinstance(raw, bool):
+        raise ValueError(f"unparseable timestamp: {raw!r}")
+    if isinstance(raw, (int, float)):
+        value = float(raw)
+        # Values past ~year 2286 in seconds are really milliseconds.
+        if value > 1e11:
+            value /= 1000.0
+        if value < _MIN_PLAUSIBLE_EPOCH:
+            raise ValueError(f"implausible epoch timestamp: {raw!r}")
+        return value
+    if isinstance(raw, str):
+        text = raw.strip()
+        if not text:
+            raise ValueError("empty timestamp")
+        # ISO-8601 first (so "2020-..." is a date, not epoch 2020).
+        try:
+            dt = datetime.fromisoformat(text.replace("Z", "+00:00"))
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=timezone.utc)
+            return dt.timestamp()
+        except ValueError:
+            pass
+        # Then a numeric epoch string, subject to the same plausibility floor.
+        return parse_timestamp(float(text))
+    raise ValueError(f"unparseable timestamp: {raw!r}")
+
+
+def _first(d: dict, *keys: str) -> object:
+    """Return the first present, non-None value among ``keys``."""
+    for k in keys:
+        if k in d and d[k] is not None:
+            return d[k]
+    return None
+
+
+def normalize_event(raw: dict, source: str | None = None) -> Event:
+    """Normalise one source-specific event dict into an :class:`Event`.
+
+    Tolerant of the common field-name variations across vCenter events, Aria
+    alerts/anomalies, Log Insight events, and NSX. Unknown extras are preserved
+    under ``fields`` so nothing is silently dropped.
+    """
+    ts_raw = _first(raw, "ts", "timestamp", "time", "createTime", "startTimeUTC")
+    if ts_raw is None:
+        raise ValueError(f"event has no timestamp field: {raw!r}")
+
+    src = source or _first(raw, "source", "skill") or "unknown"
+    sev = normalize_severity(_first(raw, "severity", "criticality", "level", "status"))
+    entity = _first(
+        raw, "entity", "entity_name", "resourceName", "vm", "vm_name", "object", "host"
+    )
+    text = _first(raw, "text", "message", "msg", "description", "fullFormattedMessage")
+
+    known = {
+        "ts", "timestamp", "time", "createTime", "startTimeUTC",
+        "source", "skill", "severity", "criticality", "level", "status",
+        "entity", "entity_name", "resourceName", "vm", "vm_name", "object", "host",
+        "text", "message", "msg", "description", "fullFormattedMessage",
+    }
+    extras = {k: v for k, v in raw.items() if k not in known}
+
+    return Event(
+        ts=parse_timestamp(ts_raw),
+        source=str(src),
+        severity=sev,
+        entity=str(entity) if entity is not None else "",
+        text=str(text) if text is not None else "",
+        fields=extras,
+    )
+
+
+def normalize_events(raw_events: list[dict], source: str | None = None) -> list[Event]:
+    """Normalise a batch, skipping nothing — a bad event raises with its index."""
+    out: list[Event] = []
+    for i, raw in enumerate(raw_events):
+        try:
+            out.append(normalize_event(raw, source))
+        except (ValueError, AttributeError, TypeError) as exc:
+            raise ValueError(f"event[{i}] could not be normalised: {exc}") from exc
+    return out

vmware_debug/mcp/__init__.py

@@ -0,0 +1,2 @@
+"""MCP tool implementations for vmware-debug (kept here so audit logs see
+skill=debug). The stdio server in mcp_server/ wires these into FastMCP."""

vmware_debug/mcp/tools.py

@@ -0,0 +1,33 @@
+"""vmware-debug MCP tool logic — pure, read-only correlation. No network, no
+writes, no cross-skill imports. The agent fetches events with the other skills'
+read tools and passes them here as plain dicts (the unified event envelope)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from vmware_debug.envelope import normalize_events
+from vmware_debug.ops.timeline import category_routing
+from vmware_debug.ops.timeline import incident_timeline as _incident_timeline
+
+
+def incident_timeline(
+    events: list[dict],
+    bin_seconds: Optional[float] = None,
+    z_threshold: float = 2.0,
+    top_n: int = 5,
+) -> dict:
+    """Correlate pre-fetched events into a timeline + spikes + ranked hypotheses.
+
+    ``events`` is a list of event envelopes (see references/event-envelope.md).
+    Raises ValueError (with the offending index) if an event can't be normalised.
+    """
+    normalized = normalize_events(events)
+    return _incident_timeline(
+        normalized, bin_seconds=bin_seconds, z_threshold=z_threshold, top_n=top_n
+    )
+
+
+def list_symptom_categories() -> list[dict]:
+    """List the symptom categories debug recognises and what to check for each."""
+    return category_routing()

vmware_debug/ops/__init__.py

@@ -0,0 +1 @@
+"""Diagnostic operations for vmware-debug."""

vmware_debug/ops/timeline.py

@@ -0,0 +1,312 @@
+"""Incident correlation engine — the heart of vmware-debug.
+
+Pure functions over a list of normalised :class:`~vmware_debug.envelope.Event`.
+No I/O, no network, no cross-skill imports: the orchestrating agent fetches
+events via each data-source skill's read tools and feeds them here. That keeps
+the valuable logic (timeline merge, spike detection, hypothesis ranking, and
+next-check suggestions) self-contained and unit-testable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from vmware_debug.envelope import SEVERITY_WEIGHT, Event
+
+# A symptom taxonomy: keyword signatures -> (category, which skill/tool to look
+# at next). This is what lets debug "give a valuable idea even when the user
+# doesn't know what to check". Keywords are matched case-insensitively against
+# event text + entity. Order matters only for the human-readable label; scoring
+# counts every category that matches.
+_CATEGORY_SIGNATURES: tuple[tuple[str, tuple[str, ...], str], ...] = (
+    (
+        "storage",
+        ("datastore", "scsi", "latency", "vsan", "lun", "naa.", "apd", "pdl",
+         "disk full", "no space", "vmfs", "iscsi"),
+        "vmware-storage (datastore/vsan health) + vmware-log-insight (search "
+        "the host's vmkernel for scsi/apd events around the spike)",
+    ),
+    (
+        "network",
+        ("vmotion", "vnic", "dvswitch", "dvs ", "uplink", "link down", "mtu",
+         "firewall", "dfw", "segment", "tier-0", "tier-1", "bgp", "packet drop"),
+        "vmware-nsx / vmware-nsx-security (run a traceflow between the affected "
+        "endpoints; check DFW rule hits) + vmware-log-insight (network logs)",
+    ),
+    (
+        "compute",
+        ("cpu ready", "memory", "balloon", "swap", "contention", "overcommit",
+         "numa"),
+        "vmware-aria (CPU-ready / memory-contention metrics + anomalies for the "
+        "VM and its host) ",
+    ),
+    (
+        "ha_drs",
+        ("ha ", "high availability", "drs", "failover", "admission control",
+         "host isolation", "heartbeat"),
+        "vmware-monitor (cluster + host health, recent HA/DRS events) + "
+        "vmware-aiops (cluster state)",
+    ),
+    (
+        "power_lifecycle",
+        ("power on", "power off", "failed to start", "boot", "vmx", "ovf",
+         "deploy", "clone", "snapshot", "consolidate"),
+        "vmware-aiops (VM task status, snapshot tree) + vmware-monitor (the VM's "
+        "recent events)",
+    ),
+    (
+        "auth",
+        ("login", "authentication", "permission", "denied", "unauthorized",
+         "401", "403", "token", "certificate", "tls"),
+        "check the service account + credentials in config/.env; verify the "
+        "target's certificate/time sync",
+    ),
+    (
+        "platform",
+        ("vpxd", "hostd", "service", "restart", "crash", "core dump", "503",
+         "not responding", "disconnected"),
+        "vmware-monitor (host connection state + service health) + "
+        "vmware-log-insight (vpxd/hostd logs around the first error)",
+    ),
+)
+
+
+@dataclass(frozen=True)
+class Bucket:
+    """A time bin with event counts."""
+
+    start: float
+    end: float
+    count: int
+    by_severity: dict[str, int] = field(default_factory=dict)
+    by_source: dict[str, int] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Spike:
+    """A bin whose count is anomalously high vs the series mean."""
+
+    start: float
+    end: float
+    count: int
+    zscore: float
+
+
+@dataclass(frozen=True)
+class Hypothesis:
+    """A ranked root-cause candidate with evidence and a next step."""
+
+    category: str
+    score: float
+    summary: str
+    evidence_count: int
+    first_seen: float
+    last_seen: float
+    sample_text: str
+    suggested_check: str
+
+
+def build_timeline(events: list[Event]) -> list[Event]:
+    """Return events sorted chronologically (stable)."""
+    return sorted(events, key=lambda e: e.ts)
+
+
+def bin_events(events: list[Event], bin_seconds: float) -> list[Bucket]:
+    """Bucket events into fixed-width time bins covering [min_ts, max_ts]."""
+    if not events:
+        return []
+    if bin_seconds <= 0:
+        raise ValueError("bin_seconds must be positive")
+    ordered = build_timeline(events)
+    start = ordered[0].ts
+    end = ordered[-1].ts
+    n_bins = int((end - start) // bin_seconds) + 1
+    counts: list[dict] = [
+        {"count": 0, "by_severity": {}, "by_source": {}} for _ in range(n_bins)
+    ]
+    for e in ordered:
+        idx = min(int((e.ts - start) // bin_seconds), n_bins - 1)
+        b = counts[idx]
+        b["count"] += 1
+        b["by_severity"][e.severity] = b["by_severity"].get(e.severity, 0) + 1
+        b["by_source"][e.source] = b["by_source"].get(e.source, 0) + 1
+    return [
+        Bucket(
+            start=start + i * bin_seconds,
+            end=start + (i + 1) * bin_seconds,
+            count=b["count"],
+            by_severity=b["by_severity"],
+            by_source=b["by_source"],
+        )
+        for i, b in enumerate(counts)
+    ]
+
+
+def detect_spikes(buckets: list[Bucket], z_threshold: float = 2.0) -> list[Spike]:
+    """Flag bins whose count exceeds mean + ``z_threshold`` * stddev.
+
+    Needs at least 3 non-trivial bins to have a meaningful baseline; below that
+    it returns nothing rather than calling every event a spike.
+    """
+    counts = [b.count for b in buckets]
+    if len(counts) < 3:
+        return []
+    mean = sum(counts) / len(counts)
+    variance = sum((c - mean) ** 2 for c in counts) / len(counts)
+    stddev = variance**0.5
+    if stddev == 0:
+        return []
+    spikes = []
+    for b in buckets:
+        z = (b.count - mean) / stddev
+        if z >= z_threshold:
+            spikes.append(Spike(start=b.start, end=b.end, count=b.count, zscore=z))
+    return spikes
+
+
+def _categorize(text: str, entity: str) -> list[tuple[str, str]]:
+    """Return (category, suggested_check) for every signature the text matches."""
+    haystack = f"{text} {entity}".lower()
+    hits = []
+    for category, keywords, suggestion in _CATEGORY_SIGNATURES:
+        if any(kw in haystack for kw in keywords):
+            hits.append((category, suggestion))
+    return hits
+
+
+def rank_hypotheses(events: list[Event], top_n: int = 5) -> list[Hypothesis]:
+    """Cluster events by symptom category and rank them as root-cause candidates.
+
+    Score = sum of severity weights of the events in the category. Ties broken
+    by recency (a category whose evidence is more recent ranks higher). Events
+    matching no category are grouped under "uncategorized" so they remain
+    visible rather than dropped.
+    """
+    groups: dict[str, dict] = {}
+    for e in events:
+        cats = _categorize(e.text, e.entity) or [("uncategorized", "")]
+        for category, suggestion in cats:
+            g = groups.setdefault(
+                category,
+                {"score": 0.0, "events": [], "suggestion": suggestion},
+            )
+            g["score"] += SEVERITY_WEIGHT.get(e.severity, 0)
+            g["events"].append(e)
+            if suggestion:
+                g["suggestion"] = suggestion
+
+    hypotheses = []
+    for category, g in groups.items():
+        evs = build_timeline(g["events"])
+        worst = max(evs, key=lambda e: SEVERITY_WEIGHT.get(e.severity, 0))
+        hypotheses.append(
+            Hypothesis(
+                category=category,
+                score=g["score"],
+                summary=(
+                    f"{len(evs)} {category} event(s); most severe is "
+                    f"'{worst.severity}' from {worst.source}"
+                ),
+                evidence_count=len(evs),
+                first_seen=evs[0].ts,
+                last_seen=evs[-1].ts,
+                sample_text=worst.text[:200],
+                suggested_check=g["suggestion"]
+                or "no category matched — widen the search window or pull events "
+                "from another source (monitor events, aria alerts, log-insight)",
+            )
+        )
+    hypotheses.sort(key=lambda h: (h.score, h.last_seen), reverse=True)
+    return hypotheses[:top_n]
+
+
+def _auto_bin_seconds(events: list[Event]) -> float:
+    """Pick a sensible bin width from the event span (~30 bins, min 1s)."""
+    ordered = build_timeline(events)
+    span = ordered[-1].ts - ordered[0].ts
+    if span <= 0:
+        return 1.0
+    return max(1.0, span / 30.0)
+
+
+def incident_timeline(
+    events: list[Event],
+    *,
+    bin_seconds: float | None = None,
+    z_threshold: float = 2.0,
+    top_n: int = 5,
+) -> dict:
+    """Top-level correlation: timeline summary + spikes + ranked hypotheses.
+
+    Returns a JSON-serialisable dict suitable for an MCP tool response. Empty
+    input yields an explicit "no events" result with a suggestion rather than
+    an empty/ambiguous payload.
+    """
+    if not events:
+        return {
+            "event_count": 0,
+            "window": None,
+            "spikes": [],
+            "hypotheses": [],
+            "next_checks": [
+                "No events supplied. Pull a starting set: vmware-monitor "
+                "event_list / alarm_list for the affected entity, then "
+                "vmware-log-insight log_search around the reported time."
+            ],
+        }
+
+    ordered = build_timeline(events)
+    width = bin_seconds or _auto_bin_seconds(ordered)
+    buckets = bin_events(ordered, width)
+    spikes = detect_spikes(buckets, z_threshold=z_threshold)
+    hyps = rank_hypotheses(ordered, top_n=top_n)
+
+    next_checks = [h.suggested_check for h in hyps if h.category != "uncategorized"]
+    if not next_checks:
+        next_checks = [
+            "No known symptom pattern matched. Widen the time window, or pull "
+            "metrics from vmware-aria (anomalies) and logs from "
+            "vmware-log-insight to enrich the timeline."
+        ]
+
+    return {
+        "event_count": len(ordered),
+        "window": {"start": ordered[0].ts, "end": ordered[-1].ts, "bin_seconds": width},
+        "spikes": [
+            {"start": s.start, "end": s.end, "count": s.count, "zscore": round(s.zscore, 2)}
+            for s in spikes
+        ],
+        "hypotheses": [
+            {
+                "category": h.category,
+                "score": h.score,
+                "summary": h.summary,
+                "evidence_count": h.evidence_count,
+                "first_seen": h.first_seen,
+                "last_seen": h.last_seen,
+                "sample_text": h.sample_text,
+                "suggested_check": h.suggested_check,
+            }
+            for h in hyps
+        ],
+        "next_checks": next_checks,
+    }
+
+
+# Kept module-private but exported for tests that assert the catalogue stays
+# in sync with the routing playbooks.
+def known_categories() -> list[str]:
+    """Return the symptom categories debug knows how to route."""
+    return [name for name, _kw, _s in _CATEGORY_SIGNATURES]
+
+
+def category_routing() -> list[dict]:
+    """Return each symptom category with sample keywords and its next-check idea.
+
+    Powers the discovery tool that answers "what can you help me check?" — and
+    lets a regression test keep this catalogue in sync with the playbooks.
+    """
+    return [
+        {"category": name, "example_keywords": list(keywords[:6]), "suggested_check": suggestion}
+        for name, keywords, suggestion in _CATEGORY_SIGNATURES
+    ]

vmware_debug-1.6.1.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: vmware-debug
+Version: 1.6.1
+Summary: VMware diagnostic brain — read-only incident triage, log/event correlation, and root-cause routing across the VMware skill family
+Author-email: Wei Zhou <wei-wz.zhou@broadcom.com>
+License-Expression: MIT
+Keywords: ai-ops,debug,diagnostics,mcp,rca,troubleshooting,vmware,vsphere
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]<2.0,>=1.10
+Requires-Dist: rich<15.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: vmware-policy<2.0,>=1.0.0
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.zw008/vmware-debug -->
+
+# VMware Debug
+
+> ⚠️ **Work in progress** — the core (event correlation engine, MCP tools, CLI)
+> is built and tested; README, `server.json`, full reference docs, and packaging
+> polish are still landing. Not yet published to PyPI.
+
+> **Disclaimer**: Community-maintained open-source project, **not affiliated with,
+> endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" and
+> "vSphere" are trademarks of Broadcom. Source is publicly auditable under the MIT
+> license.
+
+The diagnostic brain of the VMware skill family. You bring the symptom (an error,
+a log dump, a slow VM); this skill runs a systematic investigation, correlates
+events from the other skills into one timeline, ranks root-cause hypotheses, and
+tells you what to check next. It is **read-only** — it never changes anything and
+never executes fixes. Remediation is routed to `vmware-aiops` (single op) or
+`vmware-pilot` (multi-step, gated), mirroring the `vmware-harden → vmware-pilot`
+advisor/executor split.
+
+See [`skills/vmware-debug/SKILL.md`](skills/vmware-debug/SKILL.md) for the full
+methodology, the event-envelope contract, and symptom routing.
+
+## MCP tools
+
+| Tool | What |
+|---|---|
+| `incident_timeline` | [READ] Correlate pre-fetched events → timeline + spikes + ranked hypotheses + next-check ideas |
+| `list_symptom_categories` | [READ] List recognised symptom categories + what to check for each |
+
+## License
+
+MIT.

vmware_debug-1.6.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+mcp_server/__init__.py,sha256=QZpQxriDdqDCYaS-HP7McsaPbTPbHwcamIwu-7UxY-E,49
+mcp_server/server.py,sha256=dsQhAD4AR42IYPGtPuadzUTVvEu7Yl-l4OeBGuLSPJw,3188
+vmware_debug/__init__.py,sha256=NG481KQ7ilwOHB36cwloCjUBkfMd0-zAXKKVNGmxMP0,309
+vmware_debug/cli.py,sha256=bObdZFEQ3SVHwxMqKDxcac_9cOcvofOsmyGtItr5Hjg,2818
+vmware_debug/envelope.py,sha256=rPW5xRb8n_vio6q5i3JXy0tvmIZjmNZ84kc_8ToXctg,6368
+vmware_debug/mcp/__init__.py,sha256=6EYkBo6LUZj2gtTLcjCInqUT441nNqai-XU1bO6uWyc,149
+vmware_debug/mcp/tools.py,sha256=RIumf88g3suRGQW_XqCRvufiyiNL04j5OHmeRKPjtS8,1214
+vmware_debug/ops/__init__.py,sha256=Co9u0zZexST7-IOUBOAS5eq5RHkaEeI2FqfYijzhI1g,46
+vmware_debug/ops/timeline.py,sha256=mZNQNTiQxdKGakh2cZAv3jjIzLCCb3OPifjQAGTvnLc,11273
+vmware_debug-1.6.1.dist-info/METADATA,sha256=-nOEynNcGJJhQ7_nMMt-d1MPFvYjP4cf_Bpw5nYtcQg,2211
+vmware_debug-1.6.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+vmware_debug-1.6.1.dist-info/entry_points.txt,sha256=Ye2yiV3UraSCbeb6bfadvGx2ZK2KEbUK4PC9KpaN0ak,96
+vmware_debug-1.6.1.dist-info/RECORD,,

vmware_debug-1.6.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

vmware_debug-1.6.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+vmware-debug = vmware_debug.cli:app
+vmware-debug-mcp = mcp_server.server:main