vmware-debug 1.10.0__tar.gz → 1.11.0__tar.gz

{vmware_debug-1.10.0 → vmware_debug-1.11.0}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-debug",
   "displayName": "VMware Debug",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Read-only VMware incident correlation: timeline, spikes, root-cause routing. 2 MCP tools.",
   "author": {
     "name": "Wei Zhou",

{vmware_debug-1.10.0 → vmware_debug-1.11.0}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-debug==1.10.0",
+        "vmware-debug==1.11.0",
         "vmware-debug-mcp"
       ]
     }

{vmware_debug-1.10.0 → vmware_debug-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-debug
-Version: 1.10.0
+Version: 1.11.0
 Summary: VMware diagnostic brain — read-only incident triage, log/event correlation, and root-cause routing across the VMware skill family
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-Debug
 Project-URL: Repository, https://github.com/vmware-skills/VMware-Debug

{vmware_debug-1.10.0 → vmware_debug-1.11.0}/RELEASE_NOTES.md

@@ -1,3 +1,45 @@
+## v1.11.0 — the correlation engine, on a real incident
+
+A tester fed the investigation layer a genuine failure: on 08-03 at 05:49, four
+ESXi hosts went `EnteringMaintenanceMode` → `EnteredMaintenanceMode` →
+`HostShutdown` → `HostConnectionLost` → `HostSyncFailed` ×24 within 32 seconds,
+and never came back. 3,818 real vCenter events over 40 days, pulled per this
+skill's own envelope documentation. The case-management layer held up. The
+correlation engine — the thing this skill is named for — did not.
+
+**80% of events were `uncategorized`, and the headline conclusion was "cannot
+classify, widen your search window".** The classification table's
+`power_lifecycle` keywords were all VM-centric (`power on`/`power off`, `vmx`,
+`ovf`, `clone`, `snapshot`); nothing covered host maintenance mode or host
+shutdown, and `"Shut down of esxi05"` does not match `"power off"`. There is now
+a `host_lifecycle` category — a separate category rather than more keywords,
+because it is a separate investigation, routed to monitor + logs + harden (a
+host that left service on cue was usually told to). `classification_coverage()`
+reports what went unread in every result, and above ~25% it reaches
+`next_checks`. The "widen the window" remedy is gone: the window was already 40
+days, and widening makes the incident *less* findable.
+
+**The only spike detected was the day the hosts came back up.**
+`_auto_bin_seconds` was `span/30`, so a 29-day window gave 23.2-hour buckets;
+the incident hour was the second-busiest in the dataset and absent from the
+spike list, while `--bin-seconds 3600` found it at z=8.25. Binning now chooses
+by event *density*, from a floor of 4 events per bin that is derived rather than
+tuned: spikes flag at mean+2σ, and a count only exceeds twice its mean once the
+mean reaches 4. The chosen width, how it was chosen, and the bin count are
+reported.
+
+**The same incident described five ways routed five different ways** — decided
+by an incidental noun, with the most accurate description routing nowhere.
+Categories are now ranked by matched-keyword length, so a long phrase beats a
+stray word, and the losing categories are named.
+
+Also fixed: `case_timeline`'s payload contract was undocumented and its MCP
+parameter type refused the array shape the docstring implied; pure-Chinese
+summaries collapsed to one `case_id` per second, with a collision message that
+was false; and skill names were compared as raw strings, so `monitor` and
+`vmware-monitor` counted as two independent evidence sources — buying *Probable*
+out of orthography, in the layer built to prevent exactly that.
+
 ## v1.10.0 — the knowledge layer is implemented, not just described
 
 v1.9.0 shipped the investigation layer with `applies_to` documented as the thing

{vmware_debug-1.10.0 → vmware_debug-1.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-debug"
-version = "1.10.0"
+version = "1.11.0"
 description = "VMware diagnostic brain — read-only incident triage, log/event correlation, and root-cause routing across the VMware skill family"
 readme = "README.md"
 license = "MIT"

{vmware_debug-1.10.0 → vmware_debug-1.11.0}/server.json

@@ -7,12 +7,21 @@
     "url": "https://github.com/vmware-skills/VMware-Debug",
     "source": "github"
   },
-  "version": "1.10.0",
+  "version": "1.11.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-debug",
-      "version": "1.10.0",
+      "version": "1.11.0",
+      "runtimeHint": "uvx",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "valueHint": "subcommand",
+          "value": "mcp",
+          "description": "Starts the stdio MCP server. Without it the console script runs the human CLI and exits."
+        }
+      ],
       "transport": {
         "type": "stdio"
       }

{vmware_debug-1.10.0 → vmware_debug-1.11.0}/skills/vmware-debug/SKILL.md

@@ -256,8 +256,10 @@ vmware-debug mcp                                # start stdio MCP server (proxy-
 ## Troubleshooting
 
 - **`incident_timeline` raises "event[N] could not be normalised"** — event N is missing a timestamp or has an unparseable one. Every event needs `ts` (ISO-8601, epoch seconds, or millis).
-- **All hypotheses come back "uncategorized"** — the symptom isn't in the catalogue yet; widen the window and pull from another source (aria anomalies, log-insight). Consider adding a signature (see `references/routing.md`).
-- **No spikes detected on an obvious burst** — you need ≥3 time bins for a baseline; shrink `bin_seconds`.
+- **Most events come back "uncategorized"** — read `classification` in the result: it says how many, what share, and quotes the texts that matched nothing. Do **not** widen the window; a wider window adds baseline, not signal. The spikes still tell you *when*, which is answerable without a category. If the samples name a subsystem the taxonomy does not know, add a signature (see `references/routing.md`).
+- **No spikes detected on an obvious burst** — check `binning` for the resolution you were given. The width is chosen from event density so that bins average ≥4 events; a burst shorter than one bin can still be flattened by it. Pass `bin_seconds` to narrow. Below three bins there is no baseline at all and nothing is reported.
+- **`case_timeline` says zero events after you submitted results** — check `payload_events` in each `case_submit_evidence` reply. Events are read from a bare list, or from `items`/`events`/`rows`; a *summary* of a tool's result carries none. `note` names which items carried nothing and what keys they held instead.
+- **`case_readiness` says a skill you have is not installed** — both spellings are accepted (`monitor` and `vmware-monitor`). A name it did not recognise comes back in `unrecognised_skills` rather than being read as missing.
 - **It won't execute the fix** — by design. Route to vmware-aiops or vmware-pilot.
 
 ## Audit & Safety

{vmware_debug-1.10.0 → vmware_debug-1.11.0}/skills/vmware-debug/references/capabilities.md

@@ -27,9 +27,16 @@ fixed in-process constant, so `total` is a real count and `limit` is `null`.
 
 ## Symptom categories
 
-`storage`, `network`, `compute`, `ha_drs`, `power_lifecycle`, `auth`, `platform`.
+`storage`, `network`, `compute`, `ha_drs`, `host_lifecycle`, `power_lifecycle`,
+`auth`, `platform`.
 See `references/routing.md` for keyword signatures and the skill each routes to.
 
+`host_lifecycle` is a host changing its own availability state — maintenance
+mode, shutdown, reboot, standby, connection loss, sync failure.
+`power_lifecycle` is the VM-level equivalent. They are separate because they are
+separate investigations: the second is a task question for vmware-aiops, the
+first is a cluster, DPM, vLCM or drift question.
+
 ## Design properties
 
 - **Zero cross-skill runtime deps** — correlation is pure functions over plain

{vmware_debug-1.10.0 → vmware_debug-1.11.0}/skills/vmware-debug/references/event-envelope.md

@@ -21,7 +21,7 @@ runtime dependency** on the other packages (no version lockstep, no heavy instal
 | Field | Type | Notes |
 |---|---|---|
 | `ts` | string \| number | ISO-8601, epoch **seconds**, or epoch **millis** (auto-detected). Required. |
-| `source` | string | `monitor` \| `aria` \| `loginsight` \| `nsx` \| `nsx-security` \| `storage` \| ... |
+| `source` | string | `monitor` \| `aria` \| `loginsight` \| `nsx` \| `nsx-security` \| `storage` \| ... The catalogue in `rules/evidence_sources.yaml` spells the same skills `vmware-monitor`, `vmware-aria`, `vmware-log-insight`. Both spellings are understood wherever a skill is named — `case_readiness(available_skills=...)`, and the grader's count of independent sources, which treats two spellings of one skill as one source. |
 | `severity` | string | Free text; normalised to `critical`/`error`/`warning`/`info`/`unknown`. |
 | `entity` | string | The object the event is about (VM/host/datastore). May be empty. |
 | `text` | string | Human-readable message — this is what the symptom classifier matches on. |

{vmware_debug-1.10.0 → vmware_debug-1.11.0}/skills/vmware-debug/references/routing.md

@@ -10,6 +10,7 @@ Keep this in sync with `_CATEGORY_SIGNATURES` in `vmware_debug/ops/timeline.py`
 | **network** | vmotion, uplink, link down, mtu, firewall, dfw, segment, tier-0, bgp | vmware-nsx, vmware-nsx-security (traceflow, DFW hits) | pilot |
 | **compute** | cpu ready, memory, balloon, swap, contention, numa | vmware-aria (metrics + anomalies) | pilot (rightsizing) |
 | **ha_drs** | ha, high availability, drs, failover, admission control, isolation | vmware-monitor, vmware-aiops (cluster) | pilot |
+| **host_lifecycle** | maintenance mode, shut down of, host reboot, standby mode, lost connection to, cannot synchronize, not responding | vmware-monitor (host/cluster state), vmware-harden (drift — a host that left service on cue was told to), vmware-log-insight (vpxd/hostd) | pilot |
 | **power_lifecycle** | power on/off, failed to start, boot, vmx, ovf, clone, snapshot | vmware-aiops (task status, snapshot tree), vmware-monitor | aiops |
 | **auth** | login, authentication, denied, 401, 403, token, certificate, tls | config/.env, target cert + time sync | config fix |
 | **platform** | vpxd, hostd, service restart, crash, 503, not responding, disconnected | vmware-monitor (connection/service), vmware-log-insight (vpxd/hostd) | pilot |

{vmware_debug-1.10.0 → vmware_debug-1.11.0}/tests/eval/capability/_scores.json

@@ -94,7 +94,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "grading.py:56"
+            "where": "grading.py:57"
           },
           {
             "message": "grading_rules.yaml at {} is not valid YAML: {}. Fix it rather than deleting it \u2014 falling back to the",
@@ -102,7 +102,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "grading.py:58"
+            "where": "grading.py:59"
           },
           {
             "message": "A hypothesis needs a statement \u2014 what you think happened, in one line. An unnamed hypothesis cannot ",
@@ -135,7 +135,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "plan.py:72"
+            "where": "plan.py:84"
           },
           {
             "message": "evidence_sources.yaml at {} is missing 'classes' or 'routing'. An empty catalogue would make every r",
@@ -167,7 +167,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "timeline.py:140"
+            "where": "timeline.py:137"
           },
           {
             "message": "Cannot read case.json for {}: {}",
@@ -175,7 +175,7 @@
               "names_artifact",
               "states_remedy"
             ],
-            "where": "timeline.py:154"
+            "where": "timeline.py:151"
           }
         ],
         "per_dimension_pct": {
@@ -194,20 +194,20 @@
       "detail": {
         "heaviest_tools": {
           "case_open": 354,
-          "case_plan": 360,
+          "case_plan": 395,
           "case_record_gap": 337,
-          "case_submit_evidence": 621,
-          "incident_timeline": 329
+          "case_submit_evidence": 693,
+          "incident_timeline": 357
         },
-        "manifest_tokens": 3777,
-        "mean_tokens_per_tool": 269.8,
+        "manifest_tokens": 3988,
+        "mean_tokens_per_tool": 284.9,
         "reference_context": 16384,
         "tool_count": 14
       },
       "maximum": 16384,
-      "pct": 76.9,
+      "pct": 75.7,
       "unit": "tokens",
-      "value": 12607
+      "value": 12396
     },
     "parameter_documentation_coverage": {
       "detail": {
@@ -216,8 +216,7 @@
             "case_id"
           ],
           "case_submit_evidence": [
-            "fetched_at",
-            "summary"
+            "fetched_at"
           ],
           "case_timeline": [
             "bin_seconds",
@@ -228,23 +227,24 @@
         }
       },
       "maximum": 45,
-      "pct": 84.4,
+      "pct": 86.7,
       "unit": "parameters",
-      "value": 38
+      "value": 39
     },
     "per_tool_token_discipline": {
       "detail": {
         "ceiling": 350,
         "over_ceiling": {
           "case_open": 354,
-          "case_plan": 360,
-          "case_submit_evidence": 621
+          "case_plan": 395,
+          "case_submit_evidence": 693,
+          "incident_timeline": 357
         }
       },
       "maximum": 14,
-      "pct": 78.6,
+      "pct": 71.4,
       "unit": "tools",
-      "value": 11
+      "value": 10
     },
     "read_only_manifest_saving": {
       "detail": {
@@ -281,7 +281,7 @@
           "evidence.py:179",
           "evidence.py:211",
           "evidence.py:248",
-          "grading.py:66",
+          "grading.py:67",
           "hypotheses.py:47",
           "hypotheses.py:70"
         ]

vmware_debug-1.11.0/tests/eval/regression/test_case_id_non_ascii.py

@@ -0,0 +1,86 @@
+"""A case opened in Chinese got no identity of its own.
+
+``slugify`` reduces on ``[^a-z0-9]+``, so a summary written entirely in Chinese
+leaves nothing behind and the id falls back to the literal word ``case``:
+``20260830-061014-case``. Two completely different investigations opened in the
+same second then collide — and the collision message said they were "the same
+summary", which was false, and sent the reporter looking for a duplicate that
+did not exist.
+
+The id has to stay inside its character set: it is a directory name, and
+``validate_case_id`` is the only thing between a model-chosen string and
+``open(root / case_id)``. So the fix is not to widen the alphabet. It is that an
+id must distinguish summaries that differ, and that the collision message must
+describe what actually collided.
+
+The control is readability: an ASCII summary must still produce the readable
+slug the listing was designed around, not a digest for everybody.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from vmware_debug.ops.cases.ids import new_case_id, validate_case_id
+from vmware_debug.ops.cases.model import Scope
+from vmware_debug.ops.cases.store import CaseExists, create_case
+
+AT = "2026-08-30T06:10:14Z"
+
+#: Both must be free of Latin characters. An earlier draft wrote the first one
+#: as "四台 ESXi 主机…", and "esxi" survived slugify — so the two ids differed
+#: whatever the fallback did, and the test passed against the defect it was
+#: written to catch.
+ZH_A = "四台主机同时进入维护模式后关机"
+ZH_B = "存储集群延迟升高导致虚拟机无响应"
+
+
+@pytest.fixture(autouse=True)
+def isolated_home(tmp_path, monkeypatch):
+    monkeypatch.setenv("OPS_HOME", str(tmp_path / "vmware"))
+
+
+class TestANonAsciiSummaryStillGetsAnIdentity:
+    def test_two_different_chinese_summaries_do_not_collide(self):
+        assert new_case_id(ZH_A, AT) != new_case_id(ZH_B, AT)
+
+    def test_the_id_is_still_a_safe_directory_name(self):
+        validate_case_id(new_case_id(ZH_A, AT))
+
+    def test_the_same_summary_still_yields_the_same_id(self):
+        """Ids are replayable: a case folder re-opened from its scope has to
+        reconstruct the id it already has."""
+        assert new_case_id(ZH_A, AT) == new_case_id(ZH_A, AT)
+
+    def test_both_cases_can_actually_be_opened_in_the_same_second(self):
+        create_case(Scope(summary=ZH_A, determined_by="user report"), at=AT)
+        create_case(Scope(summary=ZH_B, determined_by="user report"), at=AT)
+
+
+class TestTheCollisionMessageIsTrue:
+    def test_it_does_not_claim_the_summaries_were_identical(self):
+        """Two summaries that differ only outside the id character set still
+        collide, and telling the reporter they submitted the same summary sends
+        them looking for something that is not there."""
+        create_case(Scope(summary="vsan latency!", determined_by="a"), at=AT)
+        with pytest.raises(CaseExists) as exc:
+            create_case(Scope(summary="vsan latency?", determined_by="a"), at=AT)
+        assert "same summary" not in str(exc.value)
+
+    def test_it_says_what_to_do_about_it(self):
+        create_case(Scope(summary="vsan latency", determined_by="a"), at=AT)
+        with pytest.raises(CaseExists) as exc:
+            create_case(Scope(summary="vsan latency", determined_by="a"), at=AT)
+        assert "case_get" in str(exc.value)
+
+
+class TestControlReadabilityIsNotSacrificed:
+    def test_an_ascii_summary_still_gets_its_readable_slug(self):
+        """A digest for every case would pass every test above and destroy the
+        one property the slug exists for — a directory listing you can read."""
+        assert new_case_id("vSAN datastore latency on cluster-01", AT).endswith(
+            "-vsan-datastore-latency-on-cluster-01"
+        )
+
+    def test_a_mixed_summary_keeps_the_part_that_survives(self):
+        assert "esxi05" in new_case_id("主机 esxi05 关机", AT)

vmware_debug-1.11.0/tests/eval/regression/test_evidence_payload_contract.py

@@ -0,0 +1,124 @@
+"""What `payload` has to be for case_timeline to see it, said at the time.
+
+The tester submitted the summary dict from a get_events call — ``{"total": 3818,
+"by_type": {...}}`` — as the payload. It was accepted, recorded, and reported
+back a grade, and nothing anywhere said the timeline would never see it.
+case_timeline then answered zero events with the hint "submit the get_events
+result with `payload`", which is what they had just done.
+
+Two things were missing and both are pinned here. The contract was undocumented
+— ``payload: Any`` with a docstring that said "the raw result" — and, worse, the
+one moment where the mismatch is knowable is the submission itself, where
+nothing looked.
+
+The controls stop the degenerate fix, which is to complain about every payload:
+a real event envelope has to come back clean, evidence that is not an event
+stream at all has to be accepted without being scolded, and the timeline still
+has to build.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from vmware_debug.mcp import tools as t
+from vmware_debug.mcp_server.server import build_server
+
+AT = "2026-08-30T09:00:00Z"
+
+
+@pytest.fixture(autouse=True)
+def isolated_home(tmp_path, monkeypatch):
+    monkeypatch.setenv("OPS_HOME", str(tmp_path / "vmware"))
+
+
+@pytest.fixture
+def case():
+    return t.case_open(summary="four hosts down", determined_by="alarm 42", at=AT)["case_id"]
+
+
+def submit(case, payload, skill="vmware-monitor"):
+    return t.case_submit_evidence(
+        case_id=case,
+        source_skill=skill,
+        source_tool="get_events",
+        query={"hours": 960},
+        summary="3818 events over 40 days",
+        fetched_at=AT,
+        payload=payload,
+    )
+
+
+EVENT = {"ts": "2026-08-03T05:49:00Z", "severity": "critical", "text": "Shut down of esxi05"}
+
+
+class TestTheMismatchIsReportedWhereItHappens:
+    def test_a_summary_dict_is_not_silently_accepted_as_events(self, case):
+        r = submit(case, {"total": 3818, "by_type": {"HostShutdown": 4}})
+        assert r["payload_events"] == 0
+        assert r["payload_note"]
+
+    def test_the_note_names_the_keys_that_were_actually_there(self, case):
+        """"Submit the get_events result" is unusable advice for someone who
+        did. Naming what arrived is what makes the mismatch visible."""
+        note = submit(case, {"total": 3818, "by_type": {}})["payload_note"]
+        assert "total" in note and "by_type" in note
+
+    def test_the_note_names_the_keys_it_reads(self, case):
+        note = submit(case, {"total": 3818})["payload_note"]
+        assert "items" in note and "events" in note and "rows" in note
+
+
+class TestTheAcceptedShapes:
+    def test_a_bare_list_of_events_is_counted(self, case):
+        assert submit(case, [EVENT, EVENT])["payload_events"] == 2
+
+    def test_the_family_list_envelope_is_counted(self, case):
+        assert submit(case, {"items": [EVENT], "total": 1})["payload_events"] == 1
+
+    def test_a_bare_list_survives_the_mcp_boundary(self):
+        """The documented shape has to be reachable through the tool schema.
+        Typed ``Optional[dict]``, an array of events was refused by validation
+        before any of this code ran."""
+        server = build_server()
+        schema = {tool.name: tool.inputSchema for tool in asyncio.run(server.list_tools())}
+        payload = schema["case_submit_evidence"]["properties"]["payload"]
+        allowed = {
+            entry.get("type") for entry in payload.get("anyOf", [payload]) if isinstance(entry, dict)
+        }
+        assert "array" in allowed, f"payload schema does not accept a list: {payload}"
+
+
+class TestControls:
+    def test_a_real_envelope_is_not_complained_about(self, case):
+        """The fix must not be 'warn on everything'. Banning one phrase is not
+        enough — the note has to positively report what it read, or a
+        complain-about-everything version passes by rewording."""
+        note = submit(case, {"items": [EVENT]})["payload_note"]
+        assert "no event rows" not in note
+        assert "1 event row" in note and "items" in note
+
+    def test_evidence_that_is_not_an_event_stream_is_still_accepted(self, case):
+        """A knowledge citation or a config dump carries no events by nature and
+        is not a mistake. It is recorded, and it still counts as a source."""
+        r = submit(case, None, skill="knowledge-kb")
+        assert r["evidence_id"]
+        assert r["payload_events"] == 0
+
+    def test_the_timeline_still_builds_from_a_real_payload(self, case):
+        submit(case, {"items": [EVENT]})
+        assert t.case_timeline(case_id=case)["event_count"] == 1
+
+
+class TestTheTimelineSaysWhichItemsCarriedNothing:
+    def test_it_names_the_items_and_what_they_held(self, case):
+        submit(case, {"total": 3818, "by_type": {}})
+        note = t.case_timeline(case_id=case)["note"]
+        assert "E001" in note
+        assert "total" in note
+
+    def test_control_a_populated_timeline_does_not_carry_the_complaint(self, case):
+        submit(case, {"items": [EVENT]})
+        assert "E001" not in t.case_timeline(case_id=case)["note"]