vmware-debug 1.8.0__tar.gz → 1.8.2__tar.gz

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/.gitignore

@@ -15,7 +15,6 @@ venv/
 htmlcov/
 .coverage
 config.yaml
-.agents/
 .claude/
 .trae/
 skills-lock.json

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vmware-debug
-Version: 1.8.0
+Version: 1.8.2
 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

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/RELEASE_NOTES.md

@@ -1,3 +1,64 @@
+## v1.8.2 (2026-07-20) — the MCP server moves into the package namespace
+
+### Fixed — co-installing two skills broke all but the last one
+
+Every skill shipped its MCP server as a **top-level `mcp_server` package**. Python
+has one top-level namespace, so installing any two of them into one environment let
+the second overwrite the first — silently, with no error and no warning.
+
+    uv tool install vmware-aiops   ->  49 tools   (correct)
+    uv pip  install vmware-aiops   ->  27 tools   (Monitor's read-only server)
+
+vmware-aiops depends on vmware-monitor, so this was not an edge case: **every pip
+install hit it**, and the operator got 27 read-only tools where 49 were expected,
+with all 35 write tools missing. Docker images, shared MCP hosts and CI runners that
+install more than one skill were affected the same way.
+
+The server now lives at `vmware_<skill>/mcp_server/`, a name only this package can
+claim. Introduced 2026-02-26; it survived 70 releases because every test ran against
+a single package in its own repo, where the local directory shadows site-packages —
+the conflict was invisible by construction.
+
+**Migration.** Console scripts are unchanged: `vmware-<skill>` and
+`vmware-<skill>-mcp` work exactly as before, as does `"command": "vmware-<skill>",
+"args": ["mcp"]` in an MCP client config. Only a direct `python -m mcp_server`
+breaks; use `python -m vmware_<skill>.mcp_server`.
+
+### Added — `references/agent-guardrails.md` in every skill
+
+The operating rules for local and small models (Llama 3.3 70B, Qwen, Mistral via
+Goose / Ollama / OpenShift AI) existed in two skills. They now ship in all 13, each
+with its own tool counts and failure modes, and are linked from every SKILL.md.
+
+### Changed — Python floor is 3.10 across the family
+
+vmware-debug and vmware-log-insight demanded 3.11 on the grounds that FastMCP schema
+reflection was unreliable on 3.10. That was the symptom of PEP 604 `X | None` in the
+server's own signatures, fixed in 1.8.0. 3.10 was verified end to end on 2026-07-19 —
+every tool's schema built, zero failures — so the stricter floor was rejecting a
+version that works.
+
+## v1.8.1 (2026-07-19) — read-only mode reaches the surfaces that teach it
+
+v1.8.0 put read-only mode in the code and documented it in the README only.
+Every other layer was empty, and each serves a different reader: SKILL.md is what
+the agent loads, setup-guide is what an operator reads while configuring, `doctor`
+is where they verify it took. The gap had two concrete costs.
+
+An agent read SKILL.md, called a write tool the gate had withheld, and got nothing
+back — with no way to learn that the absence was a deliberate lockdown rather than
+a fault. It reads as a broken tool, so the model retries or hunts for a workaround.
+
+An operator who set the switch had no way to confirm it. The only signal was a line
+in the MCP server's start-up log.
+
+### Added — the feature is now documented where each reader looks
+
+SKILL.md, setup-guide and capabilities now cover read-only mode. Both tools here
+are reads, so nothing is withheld — the gate instead verifies that at start-up
+rather than taking this documentation's word for it. Env vars are the only switch;
+this package has no config file.
+
 ## v1.8.0 (2026-07-18) — read-only mode, working policy defaults, declared environments
 
 Family release driven by [VMware-AIops#31](https://github.com/zw008/VMware-AIops/issues/31),

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/SECURITY.md

@@ -38,7 +38,7 @@ anything based on event content.
 ## Static Analysis
 
 ```bash
-uvx bandit -r vmware_debug/ mcp_server/
+uvx bandit -r vmware_debug/
 ```
 
 Release bar: 0 Medium-or-higher severity findings.

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-debug"
-version = "1.8.0"
+version = "1.8.2"
 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"
@@ -26,10 +26,10 @@ dependencies = [
 
 [project.scripts]
 vmware-debug = "vmware_debug.cli:app"
-vmware-debug-mcp = "mcp_server.server:main"
+vmware-debug-mcp = "vmware_debug.mcp_server.server:main"
 
 [tool.hatch.build.targets.wheel]
-packages = ["vmware_debug", "mcp_server"]
+packages = ["vmware_debug"]
 
 [dependency-groups]
 dev = [

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/zw008/VMware-Debug",
     "source": "github"
   },
-  "version": "1.8.0",
+  "version": "1.8.2",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-debug",
-      "version": "1.8.0",
+      "version": "1.8.2",
       "transport": {
         "type": "stdio"
       }

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/skills/vmware-debug/SKILL.md

@@ -113,6 +113,18 @@ a recommended plan.
 See `references/event-envelope.md`. The agent normalises each source's events into this
 shape; debug stays source-agnostic and has no dependency on the other packages.
 
+## Read-Only Mode
+
+Both tools here are reads, so read-only mode withholds nothing — but
+`VMWARE_DEBUG_READ_ONLY=true` or the family-wide `VMWARE_READ_ONLY=true` still applies, and
+the gate verifies at start-up that zero write tools are exposed rather than taking this
+document's word for it. Debug has no config file, so the env vars are the only switch. The
+same family variable withholds write tools across every companion skill, so a whole-estate
+audit posture is one setting — and when you route a fix to vmware-aiops or vmware-pilot and
+the tool is missing from *their* `list_tools()`, that is the lockdown, not a fault. Do not
+retry or hunt for another route: name the blocked operation and say an operator must clear
+the switch and restart that server. Running with local or small models? See [`references/agent-guardrails.md`](references/agent-guardrails.md).
+
 ## CLI Quick Reference
 
 ```bash

vmware_debug-1.8.2/skills/vmware-debug/references/agent-guardrails.md

@@ -0,0 +1,171 @@
+# Operating vmware-debug with a local / small model
+
+Claude-class models drive this skill without special instruction. Smaller and
+locally-hosted models — Llama 3.3 70B, Qwen, Mistral, and similar, served
+through Goose, Ollama, or OpenShift AI — need explicit operating rules to call
+tools reliably.
+
+This page exists because an operator wrote those rules by hand first. The
+guardrails below are adapted, with thanks, from the working configuration
+[@juanpf-ha](https://github.com/juanpf-ha) developed while running
+vmware-monitor and vmware-aria against a production vSphere estate with Llama
+3.3 70B FP8 on an on-prem H100
+([VMware-AIops#31](https://github.com/zw008/VMware-AIops/issues/31)). The
+cross-skill rules are identical across this family; the parts below marked
+vmware-debug are specific to this skill.
+
+vmware-debug exposes 2 MCP tools and both are reads. It connects to nothing:
+the calling agent gathers events from the other skills, normalises them, and
+hands them over for correlation. That makes it the safest skill in the family
+to point a small model at — and the one most exposed to the model's reasoning,
+because its output *is* an interpretation.
+
+> **Disclaimer**: This is a community-maintained open-source project and is
+> **not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom
+> Inc.** "VMware" and "vSphere" are trademarks of Broadcom.
+
+---
+
+## First: the rules you no longer need to write
+
+Several guardrails from the original configuration are now enforced by the
+skill itself. Prompt instructions are advisory — a model can ignore them.
+These are structural, so it cannot.
+
+| Guardrail you would otherwise prompt for | Now enforced by |
+|---|---|
+| "Work exclusively in read-only mode and never modify anything" | **The tool surface, and the gate that proves it.** Both tools are reads, so read-only mode withholds nothing here — but setting it makes the guarantee checkable: the gate verifies at start-up that zero write tools are exposed rather than taking this document's word for it. |
+| "Diagnose only — never apply the fix you propose" | **Structural.** This skill has no tool that changes anything, and it holds no connection to vCenter, NSX or anything else. Remediation is routed to vmware-aiops or vmware-pilot by the calling agent. |
+| "Do not fabricate a timeline — build it from the events I gave you" | **`incident_timeline` correlates only its input.** It is source-agnostic and has no way to fetch anything, so the timeline cannot contain an event the agent did not supply. |
+| "Tell me when the symptom is outside what you can recognise" | **`list_symptom_categories`** states the catalogue, and unmatched symptoms come back as `uncategorized` rather than being forced into the nearest signature. |
+| "Use explicit limits for queries that may return large amounts of data" | **The list envelope.** `list_symptom_categories` returns `{items, returned, limit, total, truncated, hint}` with `truncated` always `false` — which is the point: it states that the catalogue is complete instead of leaving you to infer it. |
+| "Log everything you looked at" | **The `@vmware_tool` decorator.** Every call is recorded to `~/.vmware/audit.db`, reads included. |
+
+### Turning read-only mode on
+
+One variable covers every skill in the family:
+
+```json
+{
+  "mcpServers": {
+    "vmware-debug": {
+      "command": "vmware-debug",
+      "args": ["mcp"],
+      "env": { "VMWARE_READ_ONLY": "true" }
+    }
+  }
+}
+```
+
+Per-skill override:
+
+```bash
+VMWARE_READ_ONLY=true          # whole family read-only
+VMWARE_DEBUG_READ_ONLY=false   # …except this skill
+```
+
+**This skill has no `config.yaml`**, so the two environment variables are the
+only switch — there is no `read_only:` configuration setting to fall back on.
+Precedence is per-skill env → family env → off. An unparseable value
+(`VMWARE_READ_ONLY=ture`) enables read-only mode rather than silently ignoring
+the typo.
+
+Setting it here is worth doing even though nothing is withheld: the same
+variable withholds write tools across every companion skill, so a whole-estate
+diagnostic posture is one setting. That matters especially in this skill's
+workflow — you gather signals read-only, correlate, and then route a fix. When
+the fix tool is missing from vmware-aiops's or vmware-pilot's `list_tools()`,
+that is the lockdown working, not a fault: name the blocked operation and stop,
+rather than retrying or hunting for another route.
+
+---
+
+## The system prompt
+
+Everything below still benefits from being stated explicitly. Copy this into
+your agent's instruction block.
+
+```text
+## Tool use
+
+- Gather real events with the companion skills' read tools before calling
+  incident_timeline. Never answer from memory or assumption, and never
+  hand-write events to represent what you believe happened.
+- Never describe a tool call, and never output a JSON example, instead of
+  executing the tool. If you intend to call a tool, call it.
+- If a tool fails, report the actual error text. Do not complete the answer
+  with assumptions about what the result would have been.
+- Use explicit limits and time windows when gathering events. Do not request
+  unlimited results unless the user asks for them.
+
+## Skill routing
+
+- vmware-debug: correlate pre-fetched events into a timeline, detect spikes,
+  rank root-cause hypotheses, suggest next checks.
+- Gather the events from: vmware-monitor (alarms, events, host logs),
+  vmware-log-insight (centralised logs), vmware-aria (metrics, anomalies),
+  vmware-nsx / vmware-nsx-security (network and firewall), vmware-storage.
+- Route the fix to vmware-aiops, or to vmware-pilot when it needs approval
+  gating. This skill executes nothing.
+
+## Building the event set
+
+- Every event needs ts (ISO-8601, epoch seconds, or millis), and the envelope
+  shape {ts, source, severity, entity, text, fields}. An event that cannot be
+  normalised is rejected by index — fix that event, do not drop the batch.
+- Carry each event's original source and severity through unchanged. Do not
+  re-grade a severity to make a story cohere.
+- Pull from more than one source before concluding. A single source's view of
+  an incident is not a correlation.
+- Widen the window before concluding "no spike": spike detection needs at least
+  three time bins, so a short window or a large bin_seconds can hide a burst.
+
+## Data fidelity
+
+- Never invent events, timestamps, entities, or relationships between them. If
+  an event was not in the input, it does not exist for this answer.
+- Preserve the exact severity and source values. Do not translate, normalise,
+  or prettify them.
+- Report the timeline in the order the tool returned it.
+- If a requested field was not returned, show it as "not available".
+- When a response is long, report every item it contains.
+
+## Analysis discipline
+
+- Separate observed data from interpretation. State which is which. In this
+  skill that separation is the deliverable.
+- Report the ranked hypotheses the tool returned, with its ranking. Do not
+  promote your own preferred explanation above them, and do not present the
+  top hypothesis as a diagnosis.
+- Report next_checks as checks still to be run, not as findings.
+- Do not claim a root cause is confirmed. The tool ranks; it does not conclude.
+- Avoid generic recommendations that are not directly supported by the results.
+```
+
+---
+
+## Known failure modes on small models
+
+Observed with Llama 3.3 70B FP8 (Goose, on-prem H100), and useful as a
+checklist when evaluating any local model against these skills:
+
+| Symptom | Mitigation |
+|---|---|
+| Describes a tool call, or emits a JSON example, instead of executing it | The "never describe a tool call" rule above. This skill is unusually exposed to it: its input *is* JSON, so a model that has just been shown an event envelope will sometimes emit a fabricated one instead of gathering real events. Check that the events came from tool calls. |
+| Long tool responses: omits items, or reports "no data returned" when data was present | Ask for explicit limits and narrow windows when gathering. `list_symptom_categories` states `truncated: false`, so a "no categories" claim is checkable against `returned`. |
+| Adds generic recommendations unsupported by results | The "analysis discipline" rules. Root-cause output attracts invented advice more than any other shape of result in this family. |
+| Drops requested fields or reorders results | State the required fields and ordering in the request itself. A reordered timeline is a different incident. |
+| Multi-tool workflows take 30–50s end to end | Unavoidable in part — this skill's whole premise is a fan-out gather. Narrow each source's window before widening, and prefer the companion skills' aggregate tools when gathering. |
+| Presents the top-ranked hypothesis as the confirmed cause | The "the tool ranks, it does not conclude" rule. |
+| Re-grades an event's severity so the narrative fits | The "carry severity through unchanged" rule. |
+| Concludes from one source because the others were slow to query | The "pull from more than one source" rule. |
+| Reports "no spike" from a window too short to have a baseline | Three bins minimum. Widen the window or shrink `bin_seconds` before concluding. |
+| Offers to apply the fix it proposed | It cannot. Route to vmware-aiops or vmware-pilot. |
+
+## Reporting results
+
+Local-model compatibility is an explicit design constraint for this family, and
+the evidence base is small. If you evaluate a model against this skill —
+Qwen, Mistral, Granite, or anything else — a report of what worked and what did
+not is genuinely useful:
+[github.com/zw008/VMware-Debug/issues](https://github.com/zw008/VMware-Debug/issues).

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/skills/vmware-debug/references/capabilities.md

@@ -7,6 +7,11 @@ Read-only, offline incident correlation. No network, no credentials, no writes.
 | `incident_timeline` | `{event_count, window, spikes:[{start,end,count,zscore}], hypotheses:[{category, score, summary, evidence_count, first_seen, last_seen, sample_text, suggested_check}], next_checks:[...]}` | 300–2000 (scales with hypotheses) |
 | `list_symptom_categories` | `{items: [{category, example_keywords, suggested_check}], returned, limit, total, truncated, hint}` | ~400 |
 
+> Read-only mode (`VMWARE_DEBUG_READ_ONLY=true` or the family-wide `VMWARE_READ_ONLY=true`;
+> debug has no config file) removes nothing from this table — both tools are `[READ]`, and
+> the gate proves that at start-up rather than trusting the marker. Classification comes
+> from the `[READ]`/`[WRITE]` docstring marker — see README.
+
 `list_symptom_categories` returns the family list envelope — read the rows from
 `items`. It has no `limit` parameter, which is exactly why the envelope matters:
 `truncated: false` states that this is every category there is, rather than

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/skills/vmware-debug/references/setup-guide.md

@@ -26,6 +26,46 @@ For full cross-skill diagnosis, also install the data-source skills it correlate
 (vmware-monitor, vmware-log-insight, vmware-aria, vmware-nsx) and the executors it
 routes fixes to (vmware-aiops, vmware-pilot).
 
+## Read-Only Mode
+
+Off by default. Both of debug's tools are reads, so turning it on withholds nothing here —
+the value is that the gate *verifies* at start-up that no write tool is exposed, instead of
+trusting this document, and that the same family variable locks down every other installed
+skill in one setting.
+
+**Debug has no config file, so the environment is the only switch.** There is no
+`read_only:` setting to write. Precedence:
+
+| Priority | Signal | Scope |
+|---|---|---|
+| 1 | `VMWARE_DEBUG_READ_ONLY` | This skill only |
+| 2 | `VMWARE_READ_ONLY` | Every installed VMware skill |
+| 3 | (nothing set) | Off |
+
+```json
+{
+  "mcpServers": {
+    "vmware-debug": {
+      "command": "vmware-debug",
+      "args": ["mcp"],
+      "env": { "VMWARE_READ_ONLY": "true" }
+    }
+  }
+}
+```
+
+**Fail-closed.** If the mode is requested but cannot be *proven*, the server refuses to
+start with `ReadOnlyGateError`: the FastMCP tool registry cannot be enumerated (usually an
+incompatible `mcp` version), or a removal did not take effect. One case does *not* abort —
+an unparseable value (`VMWARE_DEBUG_READ_ONLY=ture`) resolves to **on** with a warning
+naming the accepted values, so a typo locks the deployment down rather than leaving it
+open.
+
+**Verifying.** Debug ships no `doctor` command; the start-up log is the record — the server
+logs every withheld tool when the mode engages, and logs nothing to withhold here. Skills
+that do ship one (e.g. `vmware-log-insight doctor`) report their resolved state and where it
+came from.
+
 ## Security
 
 > **Disclaimer**: Community-maintained open-source project, **not affiliated with,
@@ -46,5 +86,5 @@ routes fixes to (vmware-aiops, vmware-pilot).
    warning — the next major release will refuse them. debug has no config and
    no connection to declare one about, so it reports a constant `local`. Since
    it ships no operation above read risk, nothing here is gated either way.
-7. **Static analysis** — `uvx bandit -r vmware_debug/ mcp_server/` (release bar:
+7. **Static analysis** — `uvx bandit -r vmware_debug/` (release bar:
    0 Medium+).

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/tests/eval/regression/test_debug_regressions.py

@@ -9,7 +9,7 @@ import asyncio
 import json
 from pathlib import Path
 
-from mcp_server.server import build_server
+from vmware_debug.mcp_server.server import build_server
 from vmware_debug.envelope import Event
 from vmware_debug.ops.timeline import category_routing, incident_timeline, known_categories
 

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/tests/eval/regression/test_declared_environment.py

@@ -26,7 +26,7 @@ import importlib
 import pytest
 
 import vmware_policy.environment as env_mod
-from mcp_server import server
+from vmware_debug.mcp_server import server
 from vmware_policy.environment import resolve_environment, set_environment_resolver
 
 
@@ -90,7 +90,7 @@ class TestConstantResolverIsRegistered:
         importlib.reload(server)
 
         assert env_mod._resolver is not None, (
-            "mcp_server.server must call set_environment_resolver() at import."
+            "vmware_debug.mcp_server.server must call set_environment_resolver() at import."
         )
         assert env_mod._resolver is server._environment_for
 

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/tests/eval/regression/test_read_only_mode.py

@@ -24,7 +24,7 @@ import asyncio
 import pytest
 from vmware_policy import apply_read_only_gate
 
-from mcp_server import server as server_module
+from vmware_debug.mcp_server import server as server_module
 
 EXPECTED_TOOLS = {"incident_timeline", "list_symptom_categories"}
 
@@ -144,7 +144,7 @@ def test_build_server_actually_applies_the_gate(monkeypatch):
     trivially true of a gate that never runs — and a grep for the symbol found
     the unused import. Only observing the factory invoke it closes that gap.
     """
-    import mcp_server.server as server
+    import vmware_debug.mcp_server.server as server
 
     calls = []
     real = server.apply_read_only_gate

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/vmware_debug/__init__.py

@@ -5,4 +5,4 @@ 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.8.0"
+__version__ = "1.8.2"

{vmware_debug-1.8.0 → vmware_debug-1.8.2}/vmware_debug/cli.py

@@ -76,7 +76,7 @@ def triage(
 @app.command()
 def mcp() -> None:
     """Start the stdio MCP server (no network access; proxy-safe)."""
-    from mcp_server.server import main as _main
+    from vmware_debug.mcp_server.server import main as _main
 
     _main()
 

vmware_debug-1.8.2/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 vmware_debug/mcp_server/ wires these into FastMCP."""

{vmware_debug-1.8.0 → vmware_debug-1.8.2/vmware_debug}/mcp_server/server.py

@@ -137,11 +137,19 @@ def build_server() -> FastMCP:
 
 def main() -> None:
     """Entry point for `vmware-debug-mcp` (stdio transport)."""
-    if sys.version_info < (3, 11):
+    # Floor is 3.10, matching `requires-python` and the other eleven skills.
+    # This guard used to demand 3.11 on the grounds that FastMCP schema
+    # reflection was unreliable on 3.10 (踩坑 #33). That was the symptom; the
+    # cause was PEP 604 `X | None` in the server's own signatures, fixed by
+    # converting them to `Optional[X]`. 3.10 was then verified end to end on
+    # 2026-07-19 — every tool's schema built, zero failures, pydantic 2.13.4 —
+    # so the stricter floor was rejecting a version that works.
+    if sys.version_info < (3, 10):
         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"
+            "vmware-debug-mcp requires Python >= 3.10 "
+            f"(got {sys.version_info.major}.{sys.version_info.minor}). "
+            "Reinstall on a newer interpreter: "
+            "uv tool install --python 3.12 --force vmware-debug"
         )
     build_server().run()
 

vmware_debug-1.8.0/vmware_debug/mcp/__init__.py

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