vmware-aiops 2.3.2__tar.gz → 2.4.1__tar.gz

{vmware_aiops-2.3.2 → vmware_aiops-2.4.1}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-aiops",
   "displayName": "VMware AIops",
-  "version": "2.3.2",
+  "version": "2.4.1",
   "description": "AI-powered VMware vCenter/ESXi VM lifecycle and deployment with 61 MCP tools.",
   "author": {
     "name": "Wei Zhou",

{vmware_aiops-2.3.2 → vmware_aiops-2.4.1}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-aiops==2.3.2",
+        "vmware-aiops==2.4.1",
         "vmware-aiops-mcp"
       ]
     }

{vmware_aiops-2.3.2 → vmware_aiops-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-aiops
-Version: 2.3.2
+Version: 2.4.1
 Summary: VMware vCenter/ESXi AI-powered VM lifecycle and deployment tool
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-AIops
 Project-URL: Repository, https://github.com/vmware-skills/VMware-AIops
@@ -1204,6 +1204,7 @@ claude mcp add --transport http vmware-aiops https://mcp.example.com:8443/mcp \
   (default 2) sessions per target; each session is a login on the target, and a call waits at most 300 s for one.
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant
   nothing on the platform. Run one endpoint per privilege level.
+- **Several people or roles on one endpoint:** run `vmware-audit roles enable` once, then give each token a role (`vmware-audit token create NAME --role reader`, or a role in `roles.yaml` naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".
 
 **Offer only read tools, plus the writes you choose:**
 

{vmware_aiops-2.3.2 → vmware_aiops-2.4.1}/README-CN.md

@@ -843,6 +843,7 @@ claude mcp add --transport http vmware-aiops https://mcp.example.com:8443/mcp \
   个会话；每个会话都是在该 target 上的一次登录，一个调用最多等待 300 秒拿到会话。
 - **能连到这个端点的人，都以该 server 配置的账号操作。** token 只用来识别调用者，不在平台上授予任何权限。
   每个权限级别单独起一个端点。
+- **一个端点给多人或多种角色用：** 先运行一次 `vmware-audit roles enable`，再给每个 token 指定角色（`vmware-audit token create 名字 --role reader`，或在 `roles.yaml` 里定义可用的工具和 target；需 vmware-policy ≥ 1.24.0）。角色只能限定这个 token 在本端点上能调用什么，不能超出账号本身的权限。详见 vmware-policy README 的「网络调用者的角色」一节。
 
 **只提供读工具，加上你选定的写工具：**
 

{vmware_aiops-2.3.2 → vmware_aiops-2.4.1}/README.md

@@ -1180,6 +1180,7 @@ claude mcp add --transport http vmware-aiops https://mcp.example.com:8443/mcp \
   (default 2) sessions per target; each session is a login on the target, and a call waits at most 300 s for one.
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant
   nothing on the platform. Run one endpoint per privilege level.
+- **Several people or roles on one endpoint:** run `vmware-audit roles enable` once, then give each token a role (`vmware-audit token create NAME --role reader`, or a role in `roles.yaml` naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".
 
 **Offer only read tools, plus the writes you choose:**
 

{vmware_aiops-2.3.2 → vmware_aiops-2.4.1}/RELEASE_NOTES.md

@@ -1,3 +1,44 @@
+## v2.4.1 — fixes from the 2026-10-17 real-hardware read and write rounds
+
+* **Tools that run other tools' operations obey `rules.yaml` for those tools**, on the MCP and CLI surfaces.
+  `restore_vm_clean_slate`, the batch tools, `provision_vm_guest`, and the deploy tools' `power_on` / snapshot /
+  CPU-memory follow-ups are refused, with a `denied` audit row, when the policy denies the tool that does that part
+  (a deny on `revert_vm_snapshot` used to leave clean slate working; a deny on `power_on_vm` did not stop
+  `batch_clone_vms(power_on=True)`). A follow-up is checked only when the call asks for it. `run_vm_guest_command_with_output` is
+  checked as `run_vm_guest_command` (and `download_vm_guest_file`) too.
+* **Behaviour change for custom network roles:** a role check reads no arguments, so a role that allows
+  `deploy_vm_from_template`, `deploy_vm_from_ova` or `deploy_linked_clone` must now also allow `power_on_vm`,
+  `create_vm_snapshot` and `reconfigure_vm` (and one allowing `run_vm_guest_command_with_output` must allow
+  `run_vm_guest_command` and `download_vm_guest_file`), or every call is refused. The built-in `reader` and `admin`
+  roles are unaffected.
+* **Plan steps obey `rules.yaml`.** Each step of `apply_vm_plan` / `rollback_vm_plan` is authorized by vmware-policy
+  under the tool that does the same thing (a `delete_vm` step as `delete_vm`, `power_off` as `power_off_vm`, the
+  rollback that deletes a VM the plan created as `delete_vm`), at that tool's risk level — in the preview and again
+  just before the step runs, with a `denied` audit row. A deny on `delete_vm` used to stop the tool but not a plan step.
+* **Failures are failures.** Deploy, clone, linked clone, template conversion, ISO attach, `create_vm`, `migrate_vm`,
+  `reconfigure_vm` and `configure_cluster` with nothing to change returned their refusals as status strings, which
+  the MCP frame and the audit recorded as success; they now raise. A plan that stops part-way, a rollback that leaves
+  a step not undone, and a plan that fails validation now carry the family `error` key.
+* **`deploy_vm_from_template` works on a vCenter with standalone hosts**: the clone gets the template's resource
+  pool (it failed with `spec.location.pool`), and the tool now takes `target_host`.
+* **`scan_all_datastore_images` keeps each target's images**: the cache was one list replaced by every scan, so
+  scanning `datastore1` on an ESXi host erased what a vCenter scan had found. Entries now carry `target`; a corrupt
+  cache file is rebuilt by the next scan and explained by the error instead of a bare JSON error.
+* **`browse_datastore` sees every file** (`.ova`, `.ovf`, `.vmx`, `.log` were filtered out), `ds_path` is well formed
+  for ESXi and vCenter folder paths, and a leading `/` is refused with the corrected path, as vmware-storage does.
+* Error text names MCP tools and parameters (CLI form in brackets); doctor is suggested only for connectivity errors;
+  a CPU-feature vMotion refusal leads with the remedy; `get_vm_task_status` no longer says an unknown id means the
+  task finished; powering off a VM that is already off is a plain `noop`.
+
+## v2.4.0 — roles for network callers (HLD §18)
+
+* Declares the role metadata vmware-policy ≥ 1.24.0 needs to apply **roles** to this server over HTTPS
+  (HLD §18): how a missing target resolves, the guest and host-file tools that escape a role, and what each composite tool can run — `apply_vm_plan` and `rollback_vm_plan` reach every tool a plan step maps to plus `delete_vm` (rollback), `set_vm_ttl` reaches `delete_vm`, the batch tools reach the deploy and clone tools and the follow-up steps their arguments ask for (`reconfigure_vm`, `create_vm_snapshot`, `power_on_vm`, and `attach_iso_to_vm` for a deployment spec); a test derives these from what the batch code calls. A role may allow a composite only if it allows all of them. A test fails when a new plan action is not mapped to a tool. With an older vmware-policy nothing changes. Once an operator runs
+  `vmware-audit roles enable`, a token's role decides which tools and targets it may use here; a refused call is
+  audited as `denied`. See vmware-policy's README, "Roles for network callers".
+* A target-limited role is checked against the same config the connection uses: the copy the server's connection manager loaded on its first connection. Edit `config.yaml` and restart for both to see the change.
+* README and setup guide: one endpoint for several people or roles (run `vmware-audit roles enable` first).
+
 ## v2.3.2 — tools may not touch this server's own control files
 
 * **Security fix (HLD §18 step 0).** guest file download/upload, OVA and deployment-spec paths could name this server's own files, so over HTTPS a token holder could

{vmware_aiops-2.3.2 → vmware_aiops-2.4.1}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-aiops==2.3.2",
+        "vmware-aiops==2.4.1",
         "vmware-aiops-mcp"
       ]
     }

{vmware_aiops-2.3.2 → vmware_aiops-2.4.1}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/vmware-aiops",
-  "version": "2.3.2",
+  "version": "2.4.1",
   "description": "AI-powered VMware vCenter/ESXi VM lifecycle and deployment with 61 MCP tools.",
   "private": true,
   "license": "MIT",

{vmware_aiops-2.3.2 → vmware_aiops-2.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-aiops"
-version = "2.3.2"
+version = "2.4.1"
 description = "VMware vCenter/ESXi AI-powered VM lifecycle and deployment tool"
 readme = "README.md"
 license = "MIT"

{vmware_aiops-2.3.2 → vmware_aiops-2.4.1}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/vmware-skills/VMware-AIops",
     "source": "github"
   },
-  "version": "2.3.2",
+  "version": "2.4.1",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-aiops",
-      "version": "2.3.2",
+      "version": "2.4.1",
       "runtimeHint": "uvx",
       "packageArguments": [
         {

{vmware_aiops-2.3.2 → vmware_aiops-2.4.1}/skills/vmware-aiops/SKILL.md

@@ -63,7 +63,7 @@ Read before connecting an agent. Per-tool inventory: `references/capabilities.md
 ## Quick Install
 
 ```bash
-uv tool install vmware-aiops==2.3.2
+uv tool install vmware-aiops==2.4.1
 vmware-aiops doctor
 vmware-aiops hub status   # see which family members are installed
 ```
@@ -303,7 +303,7 @@ The account has no vSphere role. Assign one (Read-Only or higher) on the vCenter
 ## Setup
 
 ```bash
-uv tool install vmware-aiops==2.3.2
+uv tool install vmware-aiops==2.4.1
 mkdir -p ~/.vmware-aiops
 vmware-aiops init  # generates config.yaml and .env templates
 chmod 600 ~/.vmware-aiops/.env

{vmware_aiops-2.3.2 → vmware_aiops-2.4.1}/skills/vmware-aiops/references/setup-guide.md

@@ -6,13 +6,13 @@ All install methods fetch from the same source: [github.com/vmware-skills/VMware
 
 ```bash
 # Via PyPI (recommended for version pinning)
-uv tool install vmware-aiops==2.3.2
+uv tool install vmware-aiops==2.4.1
 
 # Via Skills.sh (fetches from GitHub)
-npx skills add vmware-skills/VMware-AIops#v2.3.2
+npx skills add vmware-skills/VMware-AIops#v2.4.1
 
 # Via ClawHub (fetches from ClawHub registry snapshot of GitHub)
-clawhub install @zw008/vmware-aiops --version 2.3.2
+clawhub install @zw008/vmware-aiops --version 2.4.1
 ```
 
 ### Claude Code
@@ -35,7 +35,7 @@ claude mcp add vmware-aiops -- vmware-aiops mcp
 
 ```bash
 # 1. Install from PyPI (source: github.com/vmware-skills/VMware-AIops)
-uv tool install vmware-aiops==2.3.2
+uv tool install vmware-aiops==2.4.1
 
 # 2. Verify installation source
 vmware-aiops --version  # confirms installed version
@@ -73,7 +73,7 @@ The `vmware-aiops` package installs a Python CLI binary and its dependencies (py
 ## Development Install
 
 ```bash
-git clone --branch v2.3.2 https://github.com/vmware-skills/VMware-AIops.git
+git clone --branch v2.4.1 https://github.com/vmware-skills/VMware-AIops.git
 cd VMware-AIops
 uv venv && source .venv/bin/activate
 # --no-sources: pyproject's [tool.uv.sources] points vmware-monitor at a sibling
@@ -245,4 +245,5 @@ vmware-aiops mcp --transport https --host 0.0.0.0 --port 8443 \
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant
   nothing on the platform. Run one endpoint per privilege level (for example a read-only account behind
   `--expose read`, and a separate endpoint for operators).
+- **Several people or roles on one endpoint:** run `vmware-audit roles enable` once, then give each token a role (`vmware-audit token create NAME --role reader`, or a role in `roles.yaml` naming tools and targets; vmware-policy ≥ 1.24.0). A role limits what the token may call on this endpoint; it cannot grant more than the account has. See vmware-policy's README, "Roles for network callers".
 

vmware_aiops-2.4.1/tests/eval/regression/test_browse_ds_path_join.py

@@ -0,0 +1,79 @@
+"""browse_datastore must return a ds_path that deploy/attach tools can use.
+
+Regression source: real ESXi 8 host (home-esxi, 2026-10-17). The browse task
+reports each folder's ``folderPath`` with no trailing separator —
+``"[datastore1]"`` for the root, ``"[datastore1] backup"`` for a folder —
+and the old code glued the file name straight on, producing
+``"[datastore1] backupVMware-VCSA.iso"`` and ``"[datastore1]Hermers - TT"``.
+Agents pass that string into deploy_vm_from_ova / attach_iso_to_vm, so a
+malformed path breaks the very flow the browse exists for. The earlier tests
+mocked ``"[ds1] images/"`` (trailing slash), the one shape that hid the bug.
+"""
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+from pyVmomi import vim
+
+from vmware_aiops.ops import datastore_browser as dsb
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize(
+    ("folder", "name", "expected"),
+    [
+        # Root, as ESXi reports it: no space after the bracket.
+        ("[datastore1]", "Hermers - TT", "[datastore1] Hermers - TT"),
+        ("[datastore1]", "x.iso", "[datastore1] x.iso"),
+        # Root, as vCenter reports it: trailing space.
+        ("[datastore1] ", "x.iso", "[datastore1] x.iso"),
+        # Folder without a trailing slash (ESXi).
+        ("[datastore1] backup", "x.iso", "[datastore1] backup/x.iso"),
+        (
+            "[datastore1] Hermers - TT",
+            "Hermers - TT.vmdk",
+            "[datastore1] Hermers - TT/Hermers - TT.vmdk",
+        ),
+        ("[datastore1] a/b", "x.iso", "[datastore1] a/b/x.iso"),
+        # Folder with a trailing slash (vCenter) — must not double it.
+        ("[datastore1] backup/", "x.iso", "[datastore1] backup/x.iso"),
+    ],
+)
+def test_join_ds_path(folder, name, expected):
+    assert dsb._join_ds_path(folder, name) == expected
+
+
+@pytest.mark.unit
+def test_browse_root_returns_well_formed_paths_for_every_folder(monkeypatch):
+    """Root browse is recursive: subfolder rows come back too, each well formed."""
+    def _file(path):
+        return SimpleNamespace(path=path, fileSize=1024 * 1024, modification="2026-10-17")
+
+    results = [
+        SimpleNamespace(folderPath="[datastore1]", file=[_file("backup")]),
+        SimpleNamespace(folderPath="[datastore1] backup", file=[_file("x.iso")]),
+    ]
+    seen = {}
+
+    def fake_search(datastorePath, searchSpec):  # noqa: N803 — pyVmomi API names
+        seen["path"] = datastorePath
+        return SimpleNamespace(
+            info=SimpleNamespace(state=vim.TaskInfo.State.success, result=results, error=None)
+        )
+
+    monkeypatch.setattr(
+        dsb,
+        "find_datastore_by_name",
+        lambda si, name: SimpleNamespace(
+            browser=SimpleNamespace(SearchDatastoreSubFolders_Task=fake_search)
+        ),
+    )
+
+    rows = dsb.browse_datastore(object(), "datastore1")["items"]
+
+    assert seen["path"] == "[datastore1]"
+    assert {r["name"]: r["ds_path"] for r in rows} == {
+        "backup": "[datastore1] backup",
+        "x.iso": "[datastore1] backup/x.iso",
+    }

vmware_aiops-2.4.1/tests/eval/regression/test_browse_sees_every_file.py

@@ -0,0 +1,70 @@
+"""browse_datastore must see every file, and treat a leading '/' one way.
+
+Real hardware, 2026-10-17: vmware-aiops' search spec listed only IsoImageQuery,
+VmDiskQuery and FolderQuery under a comment saying "include all file types".
+A DatastoreBrowser query is a filter, not a hint -- with those three, .ova /
+.ovf / .vmx / .log files are never returned. On the lab vCenter it found 0 of
+the 2 OVAs on 'datastore1 (1)' that vmware-storage (which also passes the
+generic Query) found, so scan_all_datastore_images could not do the one job its
+description gives it: finding an OVA for deploy_vm_from_ova.
+
+The twin also drifted on a leading slash: vmware-aiops passed '/vcsa8' through,
+vmware-storage refused it as "absolute" (its 1.5.35 hardening). Both now refuse
+it, and the error names the corrected path.
+"""
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+from pyVmomi import vim
+
+from vmware_aiops.ops import datastore_browser as dsb
+
+
+def _browse(monkeypatch, path=""):
+    seen: dict = {}
+
+    def fake_search(datastorePath, searchSpec):  # noqa: N803 -- pyVmomi API names
+        seen["path"] = datastorePath
+        seen["spec"] = searchSpec
+        return SimpleNamespace(
+            info=SimpleNamespace(state=vim.TaskInfo.State.success, result=[], error=None)
+        )
+
+    monkeypatch.setattr(
+        dsb,
+        "find_datastore_by_name",
+        lambda si, name: SimpleNamespace(
+            browser=SimpleNamespace(SearchDatastoreSubFolders_Task=fake_search)
+        ),
+    )
+    dsb.browse_datastore(object(), "datastore1", path=path, pattern="*.ova")
+    return seen
+
+
+@pytest.mark.unit
+def test_search_spec_includes_the_generic_file_query(monkeypatch) -> None:
+    spec = _browse(monkeypatch)["spec"]
+    # Exact type: every specific query subclasses Query, so isinstance would pass
+    # for the three that hid the OVAs.
+    assert any(type(q) is vim.host.DatastoreBrowser.Query for q in spec.query)
+
+
+@pytest.mark.unit
+def test_relative_path_is_joined_under_the_datastore(monkeypatch) -> None:
+    assert _browse(monkeypatch, "vcsa8")["path"] == "[datastore1] vcsa8"
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("path", ["/vcsa8", "//vcsa8"])
+def test_leading_slash_is_refused_with_the_fix(monkeypatch, path) -> None:
+    with pytest.raises(ValueError, match="path='vcsa8'"):
+        _browse(monkeypatch, path)
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("path", ["../other", "a/../../b", "x\x00y", "\\\\server\\share", "/"])
+def test_traversal_and_odd_paths_are_refused(monkeypatch, path) -> None:
+    with pytest.raises(ValueError, match="datastore-relative"):
+        _browse(monkeypatch, path)

{vmware_aiops-2.3.2 → vmware_aiops-2.4.1}/tests/eval/regression/test_cli_writes_guarded.py

@@ -51,7 +51,9 @@ def _ops_refs(tree: ast.AST) -> tuple[dict[str, str], set[str]]:
     for n in ast.walk(tree):
         if isinstance(n, ast.ImportFrom) and n.module:
             parts = n.module.split(".")
-            if "ops" in parts:
+            # step_policy authorizes the operation; it is not the operation, and
+            # every composite command calls it (2026-10-17).
+            if "ops" in parts and parts[-1] != "step_policy":
                 if parts[-1] == "ops":
                     mods.update(a.asname or a.name for a in n.names)
                 else:

vmware_aiops-2.4.1/tests/eval/regression/test_deploy_failures_are_failures.py

@@ -0,0 +1,205 @@
+"""A deploy that did not happen must not be reported, or audited, as success.
+
+Real hardware, 2026-10-17: ``deploy_vm_from_ova`` with a datastore name that
+does not exist returned the string ``"Datastore 'x' not found."``. The ops layer
+*returned* it instead of raising, so ``@tool_errors`` never saw an exception:
+the MCP frame said success, the audit row said ``status=ok``, and the plan
+executor and batch deploy counted the step as done. The same shape ran through
+every early exit in ``vm_deploy`` / ``ova_deploy``.
+
+These tests assert the audit status and the raised type -- the returned text
+was never the problem.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+from pyVmomi import vim
+from vmware_policy.budget import reset_budget
+from vmware_policy.policy import reset_policy_engine
+from vmware_policy.undo import reset_undo_store
+
+import vmware_aiops.mcp_server.tools.deploy as deploy_tools
+from vmware_aiops.ops import ova_deploy, vm_deploy
+
+
+@pytest.fixture(autouse=True)
+def harness(tmp_path, monkeypatch):
+    monkeypatch.setenv("OPS_HOME", str(tmp_path))
+    reset_policy_engine()
+    reset_budget()
+    reset_undo_store()
+    yield
+    reset_policy_engine()
+    reset_budget()
+    reset_undo_store()
+
+
+@pytest.fixture
+def audit_rows(monkeypatch):
+    rows: list[dict] = []
+
+    class _Recorder:
+        def log(self, **kw):
+            rows.append(kw)
+
+    monkeypatch.setattr("vmware_policy.guard.get_engine", lambda: _Recorder())
+    return rows
+
+
+@pytest.mark.unit
+def test_ova_deploy_to_a_missing_datastore_raises(monkeypatch) -> None:
+    monkeypatch.setattr(ova_deploy, "find_datastore_by_name", lambda si, n: None)
+    with pytest.raises(vm_deploy.DeployError, match="list_all_datastores"):
+        vm_deploy.deploy_ova(MagicMock(), "/x.ova", "vm1", datastore_name="nope")
+
+
+@pytest.mark.unit
+def test_template_deploy_of_a_missing_template_raises(monkeypatch) -> None:
+    monkeypatch.setattr(vm_deploy, "find_vm_by_name", lambda si, n: None)
+    with pytest.raises(vm_deploy.DeployError, match="not found"):
+        vm_deploy.deploy_from_template(MagicMock(), "tmpl", "vm1")
+
+
+@pytest.mark.unit
+def test_template_deploy_to_a_missing_datastore_raises(monkeypatch) -> None:
+    tmpl = MagicMock()
+    tmpl.config.template = True
+    tmpl.runtime.host.parent.resourcePool = vim.ResourcePool("resgroup-1", None)
+    monkeypatch.setattr(vm_deploy, "find_vm_by_name", lambda si, n: tmpl)
+    monkeypatch.setattr(vm_deploy, "find_datastore_by_name", lambda si, n: None)
+    with pytest.raises(vm_deploy.DeployError, match="list_all_datastores"):
+        vm_deploy.deploy_from_template(MagicMock(), "tmpl", "vm1", datastore_name="nope")
+
+
+@pytest.mark.unit
+def test_linked_clone_of_a_missing_source_raises(monkeypatch) -> None:
+    monkeypatch.setattr(vm_deploy, "find_vm_by_name", lambda si, n: None)
+    with pytest.raises(vm_deploy.DeployError):
+        vm_deploy.linked_clone(MagicMock(), "src", "vm1", snapshot_name="s")
+
+
+@pytest.mark.unit
+def test_ova_tool_failure_is_audited_as_error(audit_rows, monkeypatch) -> None:
+    monkeypatch.setattr(deploy_tools, "_get_connection", lambda target=None: MagicMock())
+    monkeypatch.setattr(ova_deploy, "find_datastore_by_name", lambda si, n: None)
+
+    returned = deploy_tools.deploy_vm_from_ova("/x.ova", "vm1", "nope", target="t")
+
+    assert returned.startswith("Error:")
+    assert "nope" in returned
+    assert audit_rows and audit_rows[0]["status"] == "error"
+
+
+@pytest.mark.unit
+def test_template_tool_failure_is_audited_as_error(audit_rows, monkeypatch) -> None:
+    monkeypatch.setattr(deploy_tools, "_get_connection", lambda target=None: MagicMock())
+    monkeypatch.setattr(vm_deploy, "find_vm_by_name", lambda si, n: None)
+
+    returned = deploy_tools.deploy_vm_from_template("tmpl", "vm1", target="t")
+
+    assert returned.startswith("Error:")
+    assert audit_rows and audit_rows[0]["status"] == "error"
+
+
+@pytest.mark.unit
+def test_batch_deploy_marks_a_failed_vm_as_error(monkeypatch) -> None:
+    """A failed template deploy used to land in 'messages' with status ok."""
+    monkeypatch.setattr(vm_deploy, "find_vm_by_name", lambda si, n: None)
+    spec = {"template": "tmpl", "vms": [{"name": "vm1"}]}
+    monkeypatch.setattr(vm_deploy, "load_deploy_spec", lambda p: spec)
+
+    results = vm_deploy.batch_deploy(MagicMock(), "spec.yaml")
+
+    assert results[0]["status"] == "error"
+
+
+@pytest.mark.unit
+def test_create_vm_on_a_missing_datastore_raises(monkeypatch) -> None:
+    """The same shape one module over: create_vm returned this string too."""
+    from vmware_aiops.ops import inventory, vm_lifecycle
+
+    monkeypatch.setattr(vm_lifecycle, "resolve_datacenter", lambda si, *a, **k: MagicMock())
+    monkeypatch.setattr(vm_lifecycle, "find_compute_resource", lambda *a, **k: MagicMock())
+    monkeypatch.setattr(vm_lifecycle, "find_datastore_by_name", lambda si, n: None)
+    with pytest.raises(inventory.InventoryError, match="list_all_datastores"):
+        vm_lifecycle.create_vm(MagicMock(), "vm1", datastore_name="nope")
+
+
+# ── 2026-10-17 write tests on home-vcenter (second batch) ────────────────────
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize(
+    "kwargs, says",
+    [
+        ({"target_host": "esx-gone"}, "list_esxi_hosts"),
+        ({"target_datastore": "ds-gone"}, "list_all_datastores"),
+    ],
+)
+def test_clone_to_a_missing_host_or_datastore_raises(monkeypatch, kwargs, says) -> None:
+    """Its hints also named CLI commands that do not exist
+    ('vmware-aiops cluster list-hosts', 'vmware-aiops datastore list')."""
+    from vmware_aiops.ops import inventory, vm_lifecycle
+
+    monkeypatch.setattr(vm_lifecycle, "_require_vm", lambda si, n: MagicMock())
+    monkeypatch.setattr(vm_lifecycle, "find_host_by_name", lambda si, n: None)
+    monkeypatch.setattr(vm_lifecycle, "find_datastore_by_name", lambda si, n: None)
+    with pytest.raises(inventory.InventoryError, match=says) as info:
+        vm_lifecycle.clone_vm(MagicMock(), "src", "new", **kwargs)
+    assert "list-hosts" not in str(info.value) and "datastore list" not in str(info.value)
+
+
+@pytest.mark.unit
+def test_reconfigure_with_nothing_to_change_raises(monkeypatch) -> None:
+    from vmware_aiops.ops import vm_lifecycle
+
+    monkeypatch.setattr(vm_lifecycle, "_require_vm", lambda si, n: MagicMock())
+    with pytest.raises(ValueError, match="memory_mb"):
+        vm_lifecycle.reconfigure_vm(MagicMock(), "vm1")
+
+
+def _template_on_standalone_host(monkeypatch):
+    pool = vim.ResourcePool("resgroup-standalone", None)
+    tmpl = MagicMock(name="template")
+    tmpl.config.template = True
+    tmpl.runtime.host.parent.resourcePool = pool
+    seen = {}
+
+    def clone(folder, name, spec):
+        seen["spec"] = spec
+        return MagicMock()
+
+    tmpl.Clone = clone
+    monkeypatch.setattr(vm_deploy, "find_vm_by_name", lambda si, n: tmpl)
+    monkeypatch.setattr(vm_deploy, "_wait_for_task", lambda *a, **k: None)
+    return pool, seen
+
+
+@pytest.mark.unit
+def test_template_deploy_without_a_host_names_the_templates_pool(monkeypatch) -> None:
+    """vCenter with standalone hosts: 'A specified parameter was not correct:
+    spec.location.pool' on every call, because the pool was only set when
+    target_host was passed and the MCP tool did not expose target_host."""
+    pool, seen = _template_on_standalone_host(monkeypatch)
+
+    vm_deploy.deploy_from_template(MagicMock(), "tmpl", "vm1")
+
+    assert seen["spec"].location.pool is pool
+
+
+@pytest.mark.unit
+def test_template_tool_exposes_target_host(monkeypatch) -> None:
+    import inspect
+
+    assert "target_host" in inspect.signature(deploy_tools.deploy_vm_from_template).parameters
+
+
+@pytest.mark.unit
+def test_configure_cluster_with_nothing_to_change_raises() -> None:
+    from vmware_aiops.ops import cluster_mgmt
+
+    with pytest.raises(ValueError, match="drs_behavior"):
+        cluster_mgmt.configure_cluster(MagicMock(), "c1")

vmware_aiops-2.4.1/tests/eval/regression/test_error_hints_fit_the_surface.py

@@ -0,0 +1,85 @@
+"""Error hints must fit the error, and the surface that shows them.
+
+Real hardware, 2026-10-17: every MCP error carried "Run 'vmware-aiops doctor'
+to verify connectivity and credentials." -- also for a name that does not
+resolve, where connectivity is fine and the message already says what to change.
+And messages an agent reads said "Pass --target" / "Poll with: vm task-status
+... --target", a CLI flag and a CLI command; the MCP names are the ``target``
+parameter and ``get_vm_task_status``.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from vmware_aiops.config import AppConfig
+from vmware_aiops.mcp_server import _shared
+from vmware_aiops.ops.ova_deploy import DeployError
+from vmware_aiops.ops.vm_lifecycle import TaskStillRunning, VMNotFoundError
+
+
+def _unknown_target():
+    from vmware_aiops.config import UnknownTargetError
+
+    return UnknownTargetError("Target 'x' not found.")
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize(
+    "exc", [ValueError("bad"), _unknown_target(), VMNotFoundError("x"), DeployError("x")]
+)
+def test_an_authored_request_error_does_not_send_the_agent_to_doctor(exc) -> None:
+    assert "doctor" not in _shared._hint_for(exc)
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("exc", [ConnectionError("x"), TimeoutError("x"), RuntimeError("x")])
+def test_connectivity_and_unplanned_errors_keep_the_doctor_hint(exc) -> None:
+    assert _shared._hint_for(exc) == _shared._DOCTOR_HINT
+
+
+@pytest.mark.unit
+def test_unknown_target_names_the_mcp_parameter() -> None:
+    with pytest.raises(KeyError) as info:
+        AppConfig(targets=()).get_target("nope")
+    assert "target=" in str(info.value)
+
+
+@pytest.mark.unit
+def test_still_running_names_the_mcp_poll_tool() -> None:
+    assert "get_vm_task_status" in str(TaskStillRunning("task-1", 60))
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("make", [
+    lambda: __import__("vmware_aiops.ops.vm_lifecycle", fromlist=["x"]).TaskFailedError(
+        "Task failed: ... | fault=vim.fault.MemoryHotPlugNotSupported"),
+    lambda: __import__("vmware_aiops.ops.guest_ops", fromlist=["x"]).GuestOpsError(
+        "VMware Tools is not running in the guest"),
+    lambda: __import__("vmware_aiops.ops.gate", fromlist=["x"]).GateRefusedError(
+        "refused: VMware Tools is not running"),
+])
+def test_task_guest_and_gate_refusals_do_not_send_the_agent_to_doctor(make) -> None:
+    """Write round 2026-10-17: MemoryHotPlugNotSupported and Tools-not-running
+    errors said 'Run doctor to verify connectivity and credentials'."""
+    assert "doctor" not in _shared._hint_for(make())
+
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("exc", [
+    __import__("json").JSONDecodeError("Expecting value", "<html>", 0),
+    KeyError("summary.capacity"),
+    UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid start byte"),
+])
+def test_parse_errors_and_bare_key_errors_keep_the_doctor_hint(exc) -> None:
+    """Independent review 2026-10-17: a reverse proxy answering HTML raises
+    JSONDecodeError (a ValueError), and a programming slip raises a bare KeyError;
+    neither message says what to change, so they must not be told it does."""
+    assert _shared._hint_for(exc) == _shared._DOCTOR_HINT
+
+
+@pytest.mark.unit
+def test_an_unknown_target_is_still_a_key_error() -> None:
+    """Callers catch KeyError from get_target; the subclass must not break them."""
+    assert issubclass(type(_unknown_target()), KeyError)