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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vmware-debug
-Version: 1.6.1
+Version: 1.8.0
 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
@@ -13,7 +13,7 @@ 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
+Requires-Dist: vmware-policy<2.0,>=1.8.0
 Description-Content-Type: text/markdown
 
 <!-- mcp-name: io.github.zw008/vmware-debug -->
@@ -40,6 +40,8 @@ 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.
 
+- **Read-only by design — and provable** (v1.8.0): both MCP tools are read, none write; set `VMWARE_READ_ONLY=true` (or the per-skill `VMWARE_DEBUG_READ_ONLY`) and the family read-only gate verifies that at startup instead of taking the docs' word for it — env vars are the only switch here, this skill has no config file. See [Read-Only Mode](#read-only-mode).
+
 ## MCP tools
 
 | Tool | What |
@@ -47,6 +49,45 @@ methodology, the event-envelope contract, and symptom routing.
 | `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 |
 
+## Read-Only Mode
+
+vmware-debug is read-only by design — both MCP tools carry the `[READ]` marker, take no
+credentials, and make no network calls at all; they only correlate event dicts the
+calling agent has already fetched with the other skills' read tools. Since v1.8.0 that
+is **provable rather than merely documented**: set `VMWARE_READ_ONLY=true` and the
+family read-only gate enumerates the registry at startup and verifies that zero write
+tools are exposed — structural, not a prompt instruction a model can ignore. **Off by
+default.** Fail-closed: if the mode is requested but cannot be guaranteed, the server
+refuses to start rather than running open.
+
+The same variable is family-wide: one env var also strips every write tool from the
+write-capable siblings (aiops, storage, vks, nsx, ...), so a whole-estate read-only
+posture is a single setting.
+
+```json
+{
+  "mcpServers": {
+    "vmware-debug": {
+      "command": "vmware-debug",
+      "args": ["mcp"],
+      "env": {
+        "VMWARE_READ_ONLY": "true"
+      }
+    }
+  }
+}
+```
+
+- **Per-skill override**: `VMWARE_DEBUG_READ_ONLY` beats the family-wide
+  `VMWARE_READ_ONLY`. vmware-debug has no `config.yaml`, so the env vars are the only
+  switch. Precedence: per-skill env → family env → off.
+- **Classification**: this skill registers its tools through a `build_server()` factory,
+  so the gate classifies from the `[READ]`/`[WRITE]` docstring marker rather than from
+  MCP annotations. Anything not provably read-only is treated as a write.
+- **Startup log**: nothing is logged as withheld because nothing is — the gate's empty
+  result *is* the assertion (write-capable siblings log
+  `Read-only mode active ... withheld N write tool(s)` instead).
+
 ## License
 
 MIT.

vmware_debug-1.8.0/README-CN.md

@@ -0,0 +1,79 @@
+<!-- mcp-name: io.github.zw008/vmware-debug -->
+
+# VMware Debug（中文）
+
+> **声明**：本项目为社区维护的开源项目，**与 VMware, Inc. 或 Broadcom Inc. 无任何隶属、
+> 背书或赞助关系。** "VMware"、"vSphere" 为 Broadcom 商标。源码以 MIT 许可证公开可审计。
+
+VMware skill 家族的**诊断大脑**。你给出症状（报错、日志、变慢的 VM），它来跑系统化排查：
+把其它 skill 取到的事件关联成一条时间线、检测突刺、给根因假设排序，并告诉你下一步该查什么。
+**只读**——从不修改任何东西，也从不执行修复。修复一律路由给 vmware-aiops（单步）或
+vmware-pilot（多步、带审批门控），完全复刻 vmware-harden → vmware-pilot 的「顾问/执行」分工。
+
+- **设计上只读，且可证明**（v1.8.0）—— 2 个 MCP 工具全为只读、零写工具；设置 `VMWARE_READ_ONLY=true`（或按 skill 的 `VMWARE_DEBUG_READ_ONLY`），家族只读闸门会在启动时验证这一点，而不是让你相信文档——本 skill 没有配置文件，环境变量是唯一开关，详见[只读模式](#只读模式)
+
+## 配套 Skill
+
+| 需求 | Skill |
+|---|---|
+| 故障关联 / 根因 | **vmware-debug**（本项目） |
+| 集中日志检索 | vmware-log-insight（把 `log_search` 结果喂给它） |
+| vCenter 事件与告警 | vmware-monitor |
+| 指标 / 异常 | vmware-aria |
+| 执行修复 | vmware-aiops（单步）/ vmware-pilot（多步门控） |
+
+## 安装
+
+```bash
+uv tool install vmware-debug
+vmware-debug categories          # 看它能诊断哪些症状类别
+```
+
+## MCP 工具（2 个，全只读）
+
+- `incident_timeline`：把已取到的事件关联成 时间线 + 突刺 + 排序后的根因假设 + 下一步检查建议
+- `list_symptom_categories`：症状类别及对应的排查路由（不知道查什么时用它）
+
+**事件信封**：`{ts, source, severity, entity, text, fields}`。agent 把各源事件归一成此形状再交给
+debug；debug 因此与其它包零运行时依赖。
+
+## 只读模式
+
+vmware-debug 结构上就是只读的——两个 MCP 工具都带 `[READ]` 标记，不接收任何凭据，也完全不发起
+网络调用；它们只是对 agent 用其它 skill 的读工具**已经取到**的事件字典做关联分析。自 v1.8.0 起，
+这一点从「文档承诺」变成了**可证明的事实**：设置 `VMWARE_READ_ONLY=true`，家族只读门控会在启动时
+枚举注册表并验证暴露的写工具数为零——这是结构性保证，而非模型可以无视的提示词约束。**默认关闭**；
+且为 fail-closed 设计：请求了只读模式但无法保证时，服务器直接拒绝启动，而不是敞开运行。
+
+同一个变量是家族级的：一个环境变量同时会把有写能力的兄弟 skill（aiops、storage、vks、nsx 等）的
+全部写工具剥离，因此「整个环境切只读」只需一处设置。
+
+```json
+{
+  "mcpServers": {
+    "vmware-debug": {
+      "command": "vmware-debug",
+      "args": ["mcp"],
+      "env": {
+        "VMWARE_READ_ONLY": "true"
+      }
+    }
+  }
+}
+```
+
+- **按 skill 覆盖**：`VMWARE_DEBUG_READ_ONLY` 优先于家族级 `VMWARE_READ_ONLY`。vmware-debug
+  没有 `config.yaml`，因此环境变量是唯一的开关。优先级：按 skill 环境变量 → 家族环境变量 → 默认关闭。
+- **分类依据**：本 skill 通过 `build_server()` 工厂注册工具，不传 annotations，因此门控依据
+  `[READ]`/`[WRITE]` docstring 标记分类。凡是无法证明为只读的，一律按写工具处理。
+- **启动日志**：不会打印任何「被移除」的工具，因为确实一个都没有——门控返回空结果本身就是这个断言
+  （有写能力的兄弟 skill 则会打印 `Read-only mode active ... withheld N write tool(s)`）。
+
+## 安全
+
+结构上只读、离线、无凭据：不连任何 vCenter/NSX/Aria，没有可破坏面，也没有秘密可泄露。
+详见 [SECURITY.md](SECURITY.md)。
+
+## 许可证
+
+MIT。

vmware_debug-1.8.0/README.md

@@ -0,0 +1,75 @@
+<!-- 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.
+
+- **Read-only by design — and provable** (v1.8.0): both MCP tools are read, none write; set `VMWARE_READ_ONLY=true` (or the per-skill `VMWARE_DEBUG_READ_ONLY`) and the family read-only gate verifies that at startup instead of taking the docs' word for it — env vars are the only switch here, this skill has no config file. See [Read-Only Mode](#read-only-mode).
+
+## 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 |
+
+## Read-Only Mode
+
+vmware-debug is read-only by design — both MCP tools carry the `[READ]` marker, take no
+credentials, and make no network calls at all; they only correlate event dicts the
+calling agent has already fetched with the other skills' read tools. Since v1.8.0 that
+is **provable rather than merely documented**: set `VMWARE_READ_ONLY=true` and the
+family read-only gate enumerates the registry at startup and verifies that zero write
+tools are exposed — structural, not a prompt instruction a model can ignore. **Off by
+default.** Fail-closed: if the mode is requested but cannot be guaranteed, the server
+refuses to start rather than running open.
+
+The same variable is family-wide: one env var also strips every write tool from the
+write-capable siblings (aiops, storage, vks, nsx, ...), so a whole-estate read-only
+posture is a single setting.
+
+```json
+{
+  "mcpServers": {
+    "vmware-debug": {
+      "command": "vmware-debug",
+      "args": ["mcp"],
+      "env": {
+        "VMWARE_READ_ONLY": "true"
+      }
+    }
+  }
+}
+```
+
+- **Per-skill override**: `VMWARE_DEBUG_READ_ONLY` beats the family-wide
+  `VMWARE_READ_ONLY`. vmware-debug has no `config.yaml`, so the env vars are the only
+  switch. Precedence: per-skill env → family env → off.
+- **Classification**: this skill registers its tools through a `build_server()` factory,
+  so the gate classifies from the `[READ]`/`[WRITE]` docstring marker rather than from
+  MCP annotations. Anything not provably read-only is treated as a write.
+- **Startup log**: nothing is logged as withheld because nothing is — the gate's empty
+  result *is* the assertion (write-capable siblings log
+  `Read-only mode active ... withheld N write tool(s)` instead).
+
+## License
+
+MIT.

vmware_debug-1.8.0/RELEASE_NOTES.md

@@ -0,0 +1,90 @@
+## 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),
+where an operator running Llama 3.3 70B (Goose / OpenShift AI, on-prem H100) had to
+hand-write 17 prompt guardrails to make tool calling reliable. A prompt is advisory — a
+model can ignore it. Every guardrail that could move into the harness has.
+
+### Added
+- **Read-only mode.** Set `VMWARE_READ_ONLY=true` (or the per-skill
+  `VMWARE_DEBUG_READ_ONLY`) and every write tool is removed from the MCP registry at
+  start-up. `list_tools()` never offers them, so the model cannot call what it cannot
+  see. **Off by default** — nothing changes unless you turn it on. Fail-closed: if the
+  mode is requested but cannot be guaranteed, the server refuses to start rather than
+  running open. **vmware-debug has no `config.yaml`, so the environment variables are the
+  only switch** — precedence is per-skill env → family env → off. Both tools are `[READ]`,
+  so the gate withholds nothing here; its empty result *is* the assertion.
+- **`environment:` scoping for policy rules.** Policy rules now scope by the environment
+  a target declares (production / staging / lab). Skills that connect to a VMware estate
+  declare it per target in their own `config.yaml`; vmware-debug connects to nothing and
+  has no config, so it reports a constant `local`.
+
+### Added — list results now state whether they are complete
+
+Every `[READ]` list tool returns the family envelope instead of a bare array:
+
+    {"items": [...], "returned": 50, "limit": 50, "total": 213,
+     "truncated": true, "hint": "Showing 50 of 213. Raise limit or narrow the query..."}
+
+This closes the reported failure where long responses were summarised as "no data
+returned": a bare list gives a model no way to tell a complete answer from page one, so
+it guessed. `truncated: false` now positively states completeness — including when
+`items` is empty, which means "checked, found none", not "the call failed".
+
+- **1 tool(s) converted** across ops, MCP and CLI. The routing table is a fixed constant, so `total` is exact and `truncated` is always
+  false — there is no page two to go looking for.
+
+### Changed — migration, read this
+- **Approval tiers now actually run.** They shipped in v1.6.0 but the engine only ever
+  read `~/.vmware/rules.yaml`, and a fresh install has no such file — so every deny rule,
+  maintenance window and approval tier had been inert on every install that never
+  hand-authored one. A packaged baseline now loads when you have written no rules of your
+  own. Writes at medium risk and above are stamped with their tier in the audit log;
+  irreversible work and guest execution against a target declared `production` require a
+  named approver via `VMWARE_AUDIT_APPROVED_BY`.
+- **`environment:` will become required for writes — but not here.** Across the family, a
+  state-changing operation against a target that declares no `environment:` still runs and
+  logs a warning, and **the next major release refuses it**. vmware-debug ships no tool
+  above read risk, holds no credentials and makes no network calls, so there is nothing to
+  migrate — it reports a constant `local` and the upgrade is a no-op for this package.
+  Read-only operations are never affected, in this release or the next. Check what applies
+  to your write-capable siblings before upgrading:
+  `vmware-audit policy --operation vm_delete --env <env>`.
+
+### Fixed
+- **Policy glob patterns with a leading wildcard silently matched nothing.** A rule written
+  `operations: ["*_delete"]` parsed fine, read correctly, and never fired — only a trailing
+  `*` was honoured. Now full glob matching, for operations and environments alike.
+
+### Notes
+- Requires `vmware-policy>=1.8.0`; publish that package first.
+- `vmware-audit policy` reports which rules are in force and where they came from —
+  including the case where your rules file exists but failed to parse, which previously
+  looked identical to "policy is working".
+
+## v1.6.1 (2026-06-24) — initial release
+
+First release of **vmware-debug**: the read-only diagnostic brain of the VMware
+skill family. You bring the symptom; it runs the investigation, correlates
+events from the other skills into one timeline, ranks root-cause hypotheses, and
+routes remediation to vmware-aiops / vmware-pilot. It never writes and never
+executes fixes (advisor/executor split, mirroring vmware-harden → vmware-pilot).
+
+### Added
+- **2 read-only MCP tools**: `incident_timeline` (correlate pre-fetched events
+  into a timeline + z-score spikes + ranked hypotheses + next-check ideas) and
+  `list_symptom_categories` (the symptom→skill routing catalogue).
+- **Unified event envelope** + tolerant normalizer so debug stays source-agnostic
+  with zero runtime dependency on the other skill packages — the agent fans out
+  to each skill's read tools and feeds events here (avoids cross-skill coupling,
+  踩坑 #21/#32).
+- **Pure correlation engine** (timeline merge, time-binning, spike detection,
+  hypothesis ranking, symptom routing) — fully unit-tested offline.
+- **Typer CLI**: `triage`, `categories`, `version`, `mcp`. The `mcp` entry point
+  needs no network at startup (proxy-safe, 踩坑 #25).
+- SKILL.md + references (event-envelope contract, symptom routing, playbooks).
+
+### Notes
+- Read-only by construction; remediation is routed, never executed.
+- `parse_timestamp` rejects implausible/garbage timestamps loudly rather than
+  silently landing at the epoch.

vmware_debug-1.8.0/mcp_server/server.py

@@ -0,0 +1,150 @@
+"""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_policy import apply_read_only_gate, set_environment_resolver
+
+from vmware_debug.mcp import tools as t
+
+#: Names withheld by the most recent :func:`build_server` call. The gate runs
+#: inside the factory (this server has no module-level instance), so the result
+#: is recorded here for startup logging and tests.
+WITHHELD_WRITE_TOOLS: list[str] = []
+
+
+# ---------------------------------------------------------------------------
+# Environment declaration
+# ---------------------------------------------------------------------------
+
+#: What this skill reports as the environment of everything it touches.
+#:
+#: Policy rules scope by environment, and the baseline treats a target that
+#: declares none as unknown — today that warns on state-changing operations,
+#: and the next major release refuses them. Every other skill answers this from
+#: its own config, where an operator labels each target ``production`` /
+#: ``staging`` / ``lab``.
+#:
+#: vmware-debug has no such config and no connection to declare one about: its
+#: tools are pure correlation over event dicts the calling agent has already
+#: fetched with other skills' read tools. There is no network access, no
+#: writes, and in fact no @vmware_tool-decorated operation above read risk — so
+#: nothing here is gated under either setting today. Requiring a declaration it
+#: has no place to make would leave it permanently blocked for no gain.
+#:
+#: The constant is registered anyway so that the answer is explicit and stays
+#: true if this skill ever grows a tool that writes to a local store.
+LOCAL_ENVIRONMENT = "local"
+
+#: Client-facing behaviour hints, matching the rest of the family. Both tools
+#: are [READ]: pure correlation over dicts the caller already fetched, with the
+#: same answer every time. These drive MCP client UI (e.g. whether a call needs
+#: a confirmation prompt); the read-only gate classifies independently, from
+#: the [READ]/[WRITE] docstring marker.
+#:
+#: ``openWorldHint`` is False rather than the family's usual True: this skill
+#: has no network access at all, which is exactly the closed world the hint
+#: describes. Copying True would contradict both docstrings below.
+_READ = {
+    "readOnlyHint": True,
+    "destructiveHint": False,
+    "idempotentHint": True,
+    "openWorldHint": False,
+}
+
+
+def _environment_for(target: Optional[str]) -> str:
+    """Report the environment for policy scoping. Always ``local`` — see above."""
+    return LOCAL_ENVIRONMENT
+
+
+# Registered at import time rather than inside build_server(): the resolver is
+# process-global state in vmware_policy, not per-server-instance, and every
+# build_server() call would otherwise re-register the same constant.
+set_environment_resolver(_environment_for)
+
+
+def build_server() -> FastMCP:
+    """Construct and configure the MCP server."""
+    server = FastMCP("vmware-debug")
+
+    @server.tool(name="incident_timeline", annotations=_READ)
+    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", annotations=_READ)
+    def _list_symptom_categories_impl() -> 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.
+        Returns the family list envelope {items, returned, limit, total,
+        truncated, hint}; each item is {category, example_keywords,
+        suggested_check}. The routing table is a fixed constant, so truncated is
+        always false and total is exact — this is every category there is, not a
+        page of them. Read-only; no network access."""
+        return t.list_symptom_categories()
+
+    # Applied after every tool above has registered and before the server is
+    # handed out. The [READ]/[WRITE] docstring marker is what the gate reads
+    # first, so the readOnlyHint annotations above inform client UI without
+    # changing this classification; both tools are [READ] and nothing is
+    # withheld. Wired anyway so that stays provable, and so the gate is already
+    # in place the day this skill grows a write tool.
+    global WITHHELD_WRITE_TOOLS  # noqa: PLW0603 — factory has no module instance
+    WITHHELD_WRITE_TOOLS = apply_read_only_gate(
+        server, "vmware-debug", config_flag=None
+    )
+
+    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-1.6.1 → vmware_debug-1.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-debug"
-version = "1.6.1"
+version = "1.8.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"
@@ -21,7 +21,7 @@ dependencies = [
     "typer>=0.12,<1.0",
     "rich>=13.0,<15.0",
     "mcp[cli]>=1.10,<2.0",
-    "vmware-policy>=1.0.0,<2.0",
+    "vmware-policy>=1.8.0,<2.0",
 ]
 
 [project.scripts]

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

@@ -2,17 +2,17 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.zw008/vmware-debug",
   "title": "VMware Debug",
-  "description": "VMware diagnostic brain: read-only incident correlation (timeline, spikes, ranked root-cause hypotheses) and next-check routing across the VMware skill family — 2 MCP tools.",
+  "description": "Read-only VMware incident correlation: timeline, spikes, root-cause routing. 2 MCP tools.",
   "repository": {
     "url": "https://github.com/zw008/VMware-Debug",
     "source": "github"
   },
-  "version": "1.6.1",
+  "version": "1.8.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-debug",
-      "version": "1.6.1",
+      "version": "1.8.0",
       "transport": {
         "type": "stdio"
       }

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

@@ -19,7 +19,7 @@ installer:
   package: vmware-debug
 allowed-tools:
   - Bash
-metadata: {"openclaw":{"requires":{"bins":["vmware-debug"]},"primaryEnv":"NONE"}}
+metadata: {"openclaw":{"requires":{"bins":["vmware-debug"]},"optional":{"env":["VMWARE_READ_ONLY","VMWARE_DEBUG_READ_ONLY","VMWARE_AUDIT_APPROVED_BY","VMWARE_AUDIT_RATIONALE"],"bins":["vmware-policy"]},"primaryEnv":"NONE","homepage":"https://github.com/zw008/VMware-Debug","os":["macos","linux"]}}
 ---
 
 # VMware Debug
@@ -107,6 +107,8 @@ a recommended plan.
 | `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 |
 
+**List envelope** (output of `list_symptom_categories`): `{items, returned, limit, total, truncated, hint}` — read the rows from `items`. `truncated` is always `false` here, which is the point: it states that the catalogue is complete instead of leaving you to infer it.
+
 **Event envelope** (input to `incident_timeline`): `{ts, source, severity, entity, text, fields}`.
 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.
@@ -131,7 +133,9 @@ vmware-debug mcp                                # start stdio MCP server (proxy-
 
 Read-only by construction: no write tools, no network, nothing executed. Remediation
 is always routed to aiops/pilot, where the double-confirm / approval / audit gates live
-(audit DB `~/.vmware/audit.db`). See `references/setup-guide.md`.
+(audit DB `~/.vmware/audit.db`). Policy rules scope by environment; debug has no config
+and no connection to declare one about, so it reports a constant `local` — nothing here
+touches a remote VMware estate. See `references/setup-guide.md`.
 
 ## License
 

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

@@ -5,7 +5,13 @@ Read-only, offline incident correlation. No network, no credentials, no writes.
 | Tool | What it returns | Typical response tokens |
 |---|---|---|
 | `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` | `[{category, example_keywords, suggested_check}]` | ~400 |
+| `list_symptom_categories` | `{items: [{category, example_keywords, suggested_check}], returned, limit, total, truncated, hint}` | ~400 |
+
+`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
+leaving a model to guess whether it is holding page one. The catalogue is a
+fixed in-process constant, so `total` is a real count and `limit` is `null`.
 
 ## Correlation engine
 

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

@@ -39,5 +39,12 @@ routes fixes to (vmware-aiops, vmware-pilot).
    to vmware-aiops / vmware-pilot, where confirmation/approval/audit live.
 5. **No cross-skill coupling** — events arrive as plain dicts (the event
    envelope); debug imports no other skill package at runtime.
-6. **Static analysis** — `uvx bandit -r vmware_debug/ mcp_server/` (release bar:
+6. **Environment scoping** — policy rules scope by environment, and skills that
+   connect to a VMware estate declare `environment:` (`production` / `staging` /
+   `lab`) per target in their own `config.yaml`; a target that declares none is
+   treated as unknown, and state-changing operations against it currently log a
+   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:
    0 Medium+).