vmware-pilot 2.2.0__tar.gz → 2.4.0__tar.gz

{vmware_pilot-2.2.0 → vmware_pilot-2.4.0}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-pilot",
   "displayName": "VMware Pilot",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Multi-step workflow orchestration for VMware MCP skills with approval gates and rollback.",
   "author": {
     "name": "Wei Zhou",

{vmware_pilot-2.2.0 → vmware_pilot-2.4.0}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-pilot==2.2.0",
+        "vmware-pilot==2.4.0",
         "vmware-pilot-mcp"
       ]
     }

{vmware_pilot-2.2.0 → vmware_pilot-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-pilot
-Version: 2.2.0
+Version: 2.4.0
 Summary: VMware workflow orchestration — multi-step state machine with approval gates
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-Pilot
 Project-URL: Repository, https://github.com/vmware-skills/VMware-Pilot
@@ -9,7 +9,7 @@ Project-URL: Changelog, https://github.com/vmware-skills/VMware-Pilot/blob/main/
 Author-email: Wei Zhou <wei-wz.zhou@broadcom.com>
 License-Expression: MIT
 Requires-Python: >=3.10
-Requires-Dist: mcp[cli]<2.0,>=1.28
+Requires-Dist: mcp[cli]<2.0,>=1.30
 Requires-Dist: pyyaml<7.0,>=6.0
 Requires-Dist: typer<1.0,>=0.12
 Requires-Dist: vmware-policy<2.0,>=1.21.0
@@ -89,20 +89,21 @@ pip install --no-index --find-links dist vmware-pilot
 | `create_workflow` | Create custom workflow from step list (refused if a destructive step has no approval gate before it) |
 | `run_workflow` | Execute workflow, pauses at approval gates |
 | `get_workflow_status` | Query state + diff report + audit log |
-| `approve` | Human approval, continue execution |
+| `approve` | Human approval, continue execution. Refused while steps before the gate are `not_executed`, until `acknowledge_not_executed=True` says you ran them |
 | `rollback` | Explicit, best-effort undo of steps pilot recorded as succeeded — never automatic. Previews (`blast_radius`) unless `confirm=True` |
 | `cancel_workflow` | Cancel a workflow — move it to the terminal CANCELLED state. Previews (`blast_radius`) unless `confirm=True` |
 
 ## Built-in Templates (15)
 
 `n` is the number of VMs (or drift items); ranges depend on which optional parameters are set.
-`clone_and_test` has 7 steps when `change_spec` is a guest command (an extra gate before it runs
+`clone_and_test` needs `snapshot_name` (the snapshot to clone from), resizes staging while it is
+powered off, and has 8 steps when `change_spec` is a guest command (an extra gate before it runs
 in staging). `investigate_alert`'s approvals are synthesis checkpoints; its steps are all reads.
 See `skills/vmware-pilot/references/templates.md` for parameters and steps.
 
 | Template | Steps | Approval | Skills Used |
 |----------|:-----:|:--------:|-------------|
-| `clone_and_test` | 6-7 | Yes | aiops, monitor |
+| `clone_and_test` | 7-8 | Yes | aiops, monitor |
 | `incident_response` | 4 | Yes | monitor, aiops |
 | `investigate_alert` | 4 (8 with `deep_dive`) | Yes | monitor, aria |
 | `plan_and_approve` | 3 | Yes | aiops |
@@ -146,6 +147,89 @@ update it. Requires vmware-policy ≥ 1.19.0. Details: [RELEASE_NOTES.md](RELEAS
 > corporate proxy (`invalid peer certificate: UnknownIssuer`). The installed entry point above
 > touches the network zero times; set `UV_NATIVE_TLS=true` if you must use `uvx`.
 
+### Pilot runs the steps itself: `--dispatch`
+
+By default pilot executes nothing: `run_workflow` returns each step in `pending_dispatch` and your agent performs it.
+Add `--dispatch` (or set `VMWARE_PILOT_DISPATCH=stdio`) and pilot runs each step itself, in that skill's own MCP
+server (`vmware-<skill>-mcp`, which must be installed), so the skill's policy rules, confirmation gate and audit
+apply as usual. Nothing after an approval gate runs before `approve`, and workflows reach `completed`.
+
+```json
+{"mcpServers": {"vmware-pilot": {"command": "vmware-pilot", "args": ["mcp", "--dispatch"]}}}
+```
+
+stdio only: pilot refuses to start with `--dispatch` and `--transport https`/`http` (the skill servers it starts would
+have no caller identity, so roles could not apply). A step that takes longer than `VMWARE_PILOT_DISPATCH_TIMEOUT`
+seconds (default 1800) is recorded `interrupted` — its effect is unknown — and rollback waits for you to check it.
+`run_workflow` and `approve` take as long as the steps they run: set your MCP client's tool timeout above your
+longest step. If a call does time out, Pilot carries on and answers nothing else until the step ends; then
+`get_workflow_status` shows the outcome. Never perform those steps yourself.
+
+<!-- usage: remote-and-exposure -->
+## Remote access (HTTPS) and limiting tools
+
+By default `vmware-pilot mcp` speaks stdio to one local client and offers every tool. Two options change that
+(vmware-policy ≥ 1.21.0).
+
+**Serve over HTTPS** so clients on other machines can connect. Every caller needs a bearer token:
+
+```bash
+vmware-audit token create alice          # prints the token once; give it to alice
+vmware-audit token list                  # names only
+vmware-audit token revoke alice          # refused from its next request, no restart
+vmware-pilot mcp --transport https --host 0.0.0.0 --port 8443 \
+    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
+    --public-name mcp.example.com
+```
+
+Connect a client (Claude Code shown; any MCP client that supports streamable HTTP and custom headers works):
+
+```bash
+claude mcp add --transport http vmware-pilot https://mcp.example.com:8443/mcp \
+    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"
+```
+
+```json
+{
+  "mcpServers": {
+    "vmware-pilot": {
+      "type": "http",
+      "url": "https://mcp.example.com:8443/mcp",
+      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
+    }
+  }
+}
+```
+
+- The server will not start without a token, refuses Host/Origin values outside `--public-name`, and checks
+  before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
+- Behind a TLS-terminating reverse proxy on the same machine use `--transport http --host 127.0.0.1
+  --public-name mcp.example.com` and pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine), list in `--public-name` the host name the balancer sends as `Host`, and have it forward `Authorization`.
+  Its health probe can use `GET /healthz`, which needs no token and returns only `{"status": "ok"}`
+  (vmware-policy ≥ 1.23.0).
+- Send `traceparent` or `X-Request-ID` with each request to have it stored on the audit row;
+  `vmware-audit log --correlation-id ID` then finds the calls behind one platform request.
+- The audit log records each caller as `token:<name>`. Calls naming different targets run in parallel; calls that
+  name no target run one at a time, so name the target when several people share a server.
+- **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:**
+
+```bash
+vmware-pilot mcp --expose read --allow-write cancel_workflow
+# or: VMWARE_PILOT_MCP_EXPOSE=read VMWARE_PILOT_MCP_ALLOW_WRITE=cancel_workflow vmware-pilot mcp
+```
+
+Tools not offered do not appear in the client's tool list. A bad value or an unknown write tool stops the server
+(exit 2). This limits what clients are offered; it is not authorization, so the account itself should be
+least-privilege.
+
+Details: `skills/vmware-pilot/references/setup-guide.md` ("Serving MCP over HTTPS", "Limiting which tools are offered").
+
 ## License
 
 MIT

{vmware_pilot-2.2.0 → vmware_pilot-2.4.0}/README-CN.md

@@ -43,19 +43,19 @@ vmware-pilot mcp          # 启动 MCP server（stdio）
 | `create_workflow` | 从步骤列表直接创建自定义工作流（若破坏性步骤之前没有审批门控则拒绝） |
 | `run_workflow` | 执行工作流，在审批门控处暂停 |
 | `get_workflow_status` | 查询状态 + 差异报告 + 审计日志 |
-| `approve` | 人工审批，继续执行 |
+| `approve` | 人工审批，继续执行。审批点之前仍有 `not_executed` 步骤时拒绝，直到 `acknowledge_not_executed=True` 表明这些步骤已由你执行 |
 | `rollback` | 显式、尽力而为地逆序撤销 pilot 记录为成功的步骤——从不自动执行。不带 `confirm=True` 时只预览（`blast_radius`） |
 | `cancel_workflow` | 取消工作流，置为终态 CANCELLED。不带 `confirm=True` 时只预览（`blast_radius`） |
 
 ## 内置模板（15 个）
 
-`n` 为虚拟机（或漂移项）数量；区间取决于设置了哪些可选参数。`change_spec` 为 guest 命令时
-`clone_and_test` 有 7 步（在 staging 中执行命令前多一道审批）。`investigate_alert` 的审批是综合
-判断检查点，其步骤全部为只读。参数与步骤详见 `skills/vmware-pilot/references/templates.md`。
+`n` 为虚拟机（或漂移项）数量；区间取决于设置了哪些可选参数。`clone_and_test` 需要
+`snapshot_name`（克隆所用的快照），在 staging 关机状态下调整规格；`change_spec` 为 guest 命令时
+有 8 步（在 staging 中执行命令前多一道审批）。`investigate_alert` 的审批是综合判断检查点，其步骤全部为只读。参数与步骤详见 `skills/vmware-pilot/references/templates.md`。
 
 | 模板 | 步骤数 | 审批 | 使用的技能 |
 |------|:------:|:----:|-----------|
-| `clone_and_test` | 6-7 | 是 | aiops, monitor |
+| `clone_and_test` | 7-8 | 是 | aiops, monitor |
 | `incident_response` | 4 | 是 | monitor, aiops |
 | `investigate_alert` | 4（`deep_dive` 时 8） | 是 | monitor, aria |
 | `plan_and_approve` | 3 | 是 | aiops |
@@ -97,6 +97,23 @@ CLI 命令也不变。技能目录同时跟随 vmware-vks 的改名（`get_super
 > （`invalid peer certificate: UnknownIssuer`）。上面的入口点走 PATH，完全不联网；
 > 若必须用 `uvx`，请设置 `UV_NATIVE_TLS=true`。
 
+### 由 Pilot 自己执行步骤：`--dispatch`
+
+默认情况下 Pilot 不执行任何步骤：`run_workflow` 把每一步放在 `pending_dispatch` 里返回，由你的 agent 去执行。
+加上 `--dispatch`（或设置 `VMWARE_PILOT_DISPATCH=stdio`）后，Pilot 会在对应 skill 自己的 MCP server
+（`vmware-<skill>-mcp`，需已安装）里执行每一步，因此该 skill 的策略规则、确认门和审计照常生效。审批点之后的步骤
+在 `approve` 之前不会执行，工作流可以走到 `completed`。
+
+```json
+{"mcpServers": {"vmware-pilot": {"command": "vmware-pilot", "args": ["mcp", "--dispatch"]}}}
+```
+
+仅限 stdio：`--dispatch` 与 `--transport https`/`http` 同时使用时 Pilot 拒绝启动（它启动的 skill server 没有调用者
+身份，角色无法生效）。超过 `VMWARE_PILOT_DISPATCH_TIMEOUT` 秒（默认 1800）的步骤记为 `interrupted`——效果未知——
+回滚会等你确认后再进行。
+`run_workflow` 和 `approve` 的耗时等于它们执行的步骤：请把 MCP 客户端的工具超时设得比最长的步骤更长；万一调用超时，
+Pilot 会继续执行，并在该步骤结束前不响应其他调用；之后用 `get_workflow_status` 查看结果——不要自己去执行这些步骤。
+
 ## 审计与安全
 
 所有操作通过 vmware-policy（`@vmware_tool` 装饰器）自动审计：
@@ -105,6 +122,69 @@ CLI 命令也不变。技能目录同时跟随 vmware-vks 的改名（`get_super
 - 查看最近操作：`vmware-audit log --last 20`
 - 查看被拒绝的操作：`vmware-audit log --status denied`
 
+<!-- usage: remote-and-exposure -->
+## 远程访问（HTTPS）与限制工具
+
+默认情况下 `vmware-pilot mcp` 通过 stdio 服务一个本地客户端，并提供全部工具。以下两个选项可以改变这一点
+（需 vmware-policy ≥ 1.21.0）。
+
+**通过 HTTPS 提供服务**，让其他机器上的客户端连接。每个调用者都需要一个 bearer token：
+
+```bash
+vmware-audit token create alice          # 只显示一次，交给 alice
+vmware-audit token list                  # 只列名字
+vmware-audit token revoke alice          # 下一个请求起即拒绝，无需重启
+vmware-pilot mcp --transport https --host 0.0.0.0 --port 8443 \
+    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
+    --public-name mcp.example.com
+```
+
+连接客户端（以 Claude Code 为例；任何支持 streamable HTTP 和自定义请求头的 MCP 客户端都可以）：
+
+```bash
+claude mcp add --transport http vmware-pilot https://mcp.example.com:8443/mcp \
+    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"
+```
+
+```json
+{
+  "mcpServers": {
+    "vmware-pilot": {
+      "type": "http",
+      "url": "https://mcp.example.com:8443/mcp",
+      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
+    }
+  }
+}
+```
+
+- 没有 token 时服务不会启动；`--public-name` 之外的 Host/Origin 一律拒绝；绑定端口前会自检，确认未认证请求得到 401。
+  证书要用客户端信任、且覆盖这些名字的证书。
+- 在同一台机器上由反向代理终结 TLS 时，用 `--transport http --host 127.0.0.1 --public-name mcp.example.com`，
+  并让代理透传 `Authorization` 头。
+- 负载均衡或网关在另一台机器上时，保持 `--transport https`（自签证书也可以），在 `--public-name` 里写上负载均衡
+  转发时带的 `Host` 名，并让它透传 `Authorization`。健康检查可以用 `GET /healthz`：不需要 token，只返回
+  `{"status": "ok"}`（需 vmware-policy ≥ 1.23.0）。
+- 每个请求带上 `traceparent` 或 `X-Request-ID`，它会记进审计记录；用 `vmware-audit log --correlation-id ID`
+  就能查到平台上某一次请求对应的调用。
+- 审计日志把每个调用者记为 `token:<名字>`。指定不同 target 的调用并行执行；不指定 target 的调用逐个执行，
+  所以多人共用一个 server 时请写明 target。
+- **能连到这个端点的人，都以该 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 的「网络调用者的角色」一节。
+
+**只提供读工具，加上你选定的写工具：**
+
+```bash
+vmware-pilot mcp --expose read --allow-write cancel_workflow
+# 或：VMWARE_PILOT_MCP_EXPOSE=read VMWARE_PILOT_MCP_ALLOW_WRITE=cancel_workflow vmware-pilot mcp
+```
+
+未提供的工具不会出现在客户端的工具列表里。取值错误或写工具名不存在时服务直接退出（exit 2）。
+这只限制提供给客户端的工具，不是授权；账号本身仍应遵循最小权限。
+
+详见 `skills/vmware-pilot/references/setup-guide.md`（"Serving MCP over HTTPS"、"Limiting which tools are offered"）。
+
 ## 许可证
 
 MIT

{vmware_pilot-2.2.0 → vmware_pilot-2.4.0}/README.md

@@ -72,20 +72,21 @@ pip install --no-index --find-links dist vmware-pilot
 | `create_workflow` | Create custom workflow from step list (refused if a destructive step has no approval gate before it) |
 | `run_workflow` | Execute workflow, pauses at approval gates |
 | `get_workflow_status` | Query state + diff report + audit log |
-| `approve` | Human approval, continue execution |
+| `approve` | Human approval, continue execution. Refused while steps before the gate are `not_executed`, until `acknowledge_not_executed=True` says you ran them |
 | `rollback` | Explicit, best-effort undo of steps pilot recorded as succeeded — never automatic. Previews (`blast_radius`) unless `confirm=True` |
 | `cancel_workflow` | Cancel a workflow — move it to the terminal CANCELLED state. Previews (`blast_radius`) unless `confirm=True` |
 
 ## Built-in Templates (15)
 
 `n` is the number of VMs (or drift items); ranges depend on which optional parameters are set.
-`clone_and_test` has 7 steps when `change_spec` is a guest command (an extra gate before it runs
+`clone_and_test` needs `snapshot_name` (the snapshot to clone from), resizes staging while it is
+powered off, and has 8 steps when `change_spec` is a guest command (an extra gate before it runs
 in staging). `investigate_alert`'s approvals are synthesis checkpoints; its steps are all reads.
 See `skills/vmware-pilot/references/templates.md` for parameters and steps.
 
 | Template | Steps | Approval | Skills Used |
 |----------|:-----:|:--------:|-------------|
-| `clone_and_test` | 6-7 | Yes | aiops, monitor |
+| `clone_and_test` | 7-8 | Yes | aiops, monitor |
 | `incident_response` | 4 | Yes | monitor, aiops |
 | `investigate_alert` | 4 (8 with `deep_dive`) | Yes | monitor, aria |
 | `plan_and_approve` | 3 | Yes | aiops |
@@ -129,6 +130,89 @@ update it. Requires vmware-policy ≥ 1.19.0. Details: [RELEASE_NOTES.md](RELEAS
 > corporate proxy (`invalid peer certificate: UnknownIssuer`). The installed entry point above
 > touches the network zero times; set `UV_NATIVE_TLS=true` if you must use `uvx`.
 
+### Pilot runs the steps itself: `--dispatch`
+
+By default pilot executes nothing: `run_workflow` returns each step in `pending_dispatch` and your agent performs it.
+Add `--dispatch` (or set `VMWARE_PILOT_DISPATCH=stdio`) and pilot runs each step itself, in that skill's own MCP
+server (`vmware-<skill>-mcp`, which must be installed), so the skill's policy rules, confirmation gate and audit
+apply as usual. Nothing after an approval gate runs before `approve`, and workflows reach `completed`.
+
+```json
+{"mcpServers": {"vmware-pilot": {"command": "vmware-pilot", "args": ["mcp", "--dispatch"]}}}
+```
+
+stdio only: pilot refuses to start with `--dispatch` and `--transport https`/`http` (the skill servers it starts would
+have no caller identity, so roles could not apply). A step that takes longer than `VMWARE_PILOT_DISPATCH_TIMEOUT`
+seconds (default 1800) is recorded `interrupted` — its effect is unknown — and rollback waits for you to check it.
+`run_workflow` and `approve` take as long as the steps they run: set your MCP client's tool timeout above your
+longest step. If a call does time out, Pilot carries on and answers nothing else until the step ends; then
+`get_workflow_status` shows the outcome. Never perform those steps yourself.
+
+<!-- usage: remote-and-exposure -->
+## Remote access (HTTPS) and limiting tools
+
+By default `vmware-pilot mcp` speaks stdio to one local client and offers every tool. Two options change that
+(vmware-policy ≥ 1.21.0).
+
+**Serve over HTTPS** so clients on other machines can connect. Every caller needs a bearer token:
+
+```bash
+vmware-audit token create alice          # prints the token once; give it to alice
+vmware-audit token list                  # names only
+vmware-audit token revoke alice          # refused from its next request, no restart
+vmware-pilot mcp --transport https --host 0.0.0.0 --port 8443 \
+    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
+    --public-name mcp.example.com
+```
+
+Connect a client (Claude Code shown; any MCP client that supports streamable HTTP and custom headers works):
+
+```bash
+claude mcp add --transport http vmware-pilot https://mcp.example.com:8443/mcp \
+    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"
+```
+
+```json
+{
+  "mcpServers": {
+    "vmware-pilot": {
+      "type": "http",
+      "url": "https://mcp.example.com:8443/mcp",
+      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
+    }
+  }
+}
+```
+
+- The server will not start without a token, refuses Host/Origin values outside `--public-name`, and checks
+  before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
+- Behind a TLS-terminating reverse proxy on the same machine use `--transport http --host 127.0.0.1
+  --public-name mcp.example.com` and pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine), list in `--public-name` the host name the balancer sends as `Host`, and have it forward `Authorization`.
+  Its health probe can use `GET /healthz`, which needs no token and returns only `{"status": "ok"}`
+  (vmware-policy ≥ 1.23.0).
+- Send `traceparent` or `X-Request-ID` with each request to have it stored on the audit row;
+  `vmware-audit log --correlation-id ID` then finds the calls behind one platform request.
+- The audit log records each caller as `token:<name>`. Calls naming different targets run in parallel; calls that
+  name no target run one at a time, so name the target when several people share a server.
+- **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:**
+
+```bash
+vmware-pilot mcp --expose read --allow-write cancel_workflow
+# or: VMWARE_PILOT_MCP_EXPOSE=read VMWARE_PILOT_MCP_ALLOW_WRITE=cancel_workflow vmware-pilot mcp
+```
+
+Tools not offered do not appear in the client's tool list. A bad value or an unknown write tool stops the server
+(exit 2). This limits what clients are offered; it is not authorization, so the account itself should be
+least-privilege.
+
+Details: `skills/vmware-pilot/references/setup-guide.md` ("Serving MCP over HTTPS", "Limiting which tools are offered").
+
 ## License
 
 MIT

{vmware_pilot-2.2.0 → vmware_pilot-2.4.0}/RELEASE_NOTES.md

@@ -1,3 +1,97 @@
+## v2.4.0 — runs its own steps on request; honest gates and rollback (first real-vSphere run)
+
+### Behaviour changes for existing callers
+
+* `approve` refuses a gate whose earlier steps were handed out (`not_executed`) until
+  `acknowledge_not_executed=True` — this applies to the default MCP server and to workflows saved by 2.3.0 that are
+  already awaiting approval. An automated `approve` caller must pass the flag after performing the steps.
+* `clone_and_test` requires `snapshot_name` (it used to clone from a snapshot literally named `current`).
+* Rollback reports a step without an undo as `not_reversible` (was `skipped`); approval gates and catalog reads are no
+  longer listed. A rollback whose undo failed or whose effect is unknown returns `action: "rollback_incomplete"` with
+  `outcome: "failed"` and an `error` naming them (it said `rolled_back`).
+* `cancel_workflow` keeps handed-out steps `not_executed` (was rewritten to `skipped`).
+* With vmware-policy 1.24.2, Pilot's own refusals and failed outcomes (`run_workflow`/`approve` ending
+  `outcome: "failed"`, refusals carrying `error`, an incomplete rollback) are `isError` frames; previews,
+  `awaiting_approval` and `dispatch_required` are not.
+
+### Details
+
+* A step result's `kubeconfig` (a bearer token from VKS `issue_*_kubeconfig` under `--dispatch`) is masked in
+  `workflows.db` like a password. With `--dispatch`, a skill's failed call keeps its own error envelope (`hint`
+  included) instead of a flattened JSON string.
+
+Found running Pilot workflows on vCenter 8.0.3 for the first time, through the MCP server and through an embedder
+that dispatched steps to the 2.4.0 skill servers.
+
+* **`clone_and_test` works on real vSphere.** It cloned from a snapshot literally named `current` (almost no VM
+  has one) and resized the clone after powering it on, which vCenter refuses (`MemoryHotPlugNotSupported`) on any
+  VM without hot-add. Now `snapshot_name` is **required** (no default; the error names `list_vm_snapshots`), the
+  clone is made powered off, staging is resized while off and then powered on, and the check is vmware-monitor
+  `investigate_vm` on the staging VM instead of `get_alarms` for the whole vCenter. A guest command runs after
+  power-on. 7 steps (8 for a guest command). Pilot still does not wait `monitor_minutes`: the approval message
+  asks the approver to, says a running production VM is resized in place (needs hot-add), and that the production
+  change is not rolled back. The clone step no longer claims a rollback (powering a clone off does not remove it).
+* **`approve` refuses a gate whose earlier steps nobody ran.** Through the MCP server (no dispatcher) every step
+  before the gate is `not_executed`, and the gate used to pass under "Staging VM … tested". It now refuses and
+  lists them in `not_executed_before_gate`; `acknowledge_not_executed=True` records them as `reported_done`
+  (performed outside Pilot) and they are not handed out again. Pilot never saw their results: through MCP a later
+  step that references one is handed out with the reference unresolved (fill it from that step's result), and
+  an embedder that dispatches it refuses it. An embedder with a dispatcher is unaffected unless it resumes a workflow
+  that was first run without one — then the same refusal applies. The acknowledgement is the caller's
+  statement, not a check: Pilot records who sent it, not what the steps returned.
+  SKILL.md now says plainly who executes steps: through MCP the agent does, and a workflow never reaches
+  `completed` that way.
+* **Rollback says what it cannot undo.** A step with no rollback is reported `not_reversible` (it was `skipped`,
+  "no rollback defined"); a rollback that does not remove what the step created — a clone powered off — is
+  `partial` with `left_behind`, and the step is `partially_rolled_back`. The preview carries the same:
+  `leaves_behind` on such entries and `left_in_place_note`. Approval gates are no longer listed as skipped.
+* **Failure is read from the frame, not from prose.** Besides `isError` and a top-level `error` on a plain
+  dict, a top-level `error` in an MCP result's structured content and a one-row `[{"error": ...}]` list now fail
+  the step, the last step included. A string is never read as failure, even one starting `Error: ` — decided,
+  as in vmware-policy, because tools return console text that can start that way. A skill must set `isError`;
+  AIops's linked clone returned its failure as prose in 2.4.0 and is fixed there (it now raises).
+* **Pilot can run the steps itself: `vmware-pilot mcp --dispatch`** (or `VMWARE_PILOT_DISPATCH=stdio`), off by
+  default (HLD §19, D-26). Each step runs in that skill's own MCP server (`vmware-<skill>-mcp`), so its policy,
+  confirmation gate and audit apply; nothing after an approval gate runs before `approve`; workflows reach
+  `completed`. stdio only — refused with `--transport https`/`http`, and a call with a network caller is refused.
+  Only the family's skills (not `pilot`) are started, without a shell. A step that exceeds
+  `VMWARE_PILOT_DISPATCH_TIMEOUT` (default 1800 s) is recorded `interrupted` (effect unknown), as is a step whose
+  skill server died after the call was sent; a server that never starts fails the step with its reason. Every
+  step's skill is resolved before step 0 runs; settings are checked at start (`VMWARE_PILOT_DISPATCH` must be
+  `stdio` or unset). A step already handed out in `pending_dispatch` is never run again by a `--dispatch` Pilot.
+  Results are stored as the tool's own data, so `__from_step_N__:key` works; a reference to a key the step did
+  not return is refused (it used to send the whole result in its place). Failure is read from the frame:
+  skills' failed calls arrive as `isError` once they run vmware-policy with `vmware_policy.frame` (vmware-policy
+  1.24.2). With an older Policy, 13 of 14 skills sent failures with `isError: false`; Pilot catches the
+  `{"error": ...}` envelope itself, but a string-shaped failure (mostly AVI's) reads as success.
+  Pilot's tools are synchronous: set the MCP client's tool timeout above the longest step.
+* A guest command (`run_vm_guest_command`, `_with_output`) that exits non-zero now fails the step (it was recorded
+  as success); one that timed out or whose process vanished (`exit_code` -1) is `interrupted` — it may still be
+  running. A clone left `partially_rolled_back` is still listed by a second rollback; an undo whose effect is
+  unknown marks its step `interrupted`. The rollback preview lists a rollback attached to a read step.
+* `investigate_vm` added to the design catalog (101 tools).
+* Two new step statuses, `reported_done` and `partially_rolled_back`. Pilot 2.3.0 does not know them: reading a
+  workflow that has them, its `rollback` / `cancel_workflow` refuse ("unrecognised status") rather than guess.
+* The rollback preview gains `not_reversible_outside_pilot` (steps handed to the caller with no undo — a clone,
+  a production resize; tools the catalog marks read-only left out) with a note; through MCP those used to appear nowhere in the
+  preview. The cancel preview gains `handed_out_to_caller`: steps already in `pending_dispatch`, which cancel
+  can neither stop nor undo — they used to be listed as `would_skip`, and cancel now keeps them `not_executed`
+  on the record instead of rewriting them to `skipped`.
+
+## v2.3.0 — roles for network callers (HLD §18)
+
+* Workflows record their creator (`created_by`: the network caller `token:<name>`, or the OS user). Workflows saved
+  before this release have none.
+* With vmware-policy ≥ 1.24.0 and roles enabled, `approve` follows the caller's role: `approve: none` cannot
+  approve, `approve: others` cannot approve a workflow its own token created (nor one with no recorded creator),
+  `approve: any` can. The token also needs a role that allows the `approve` tool itself. Whoever edits a draft
+  (`update_draft`) or confirms it (`confirm_draft`) is recorded in `authors` and counts as its creator for
+  `others`; so is whoever saved a custom template, for workflows made from it (the YAML records `authors`).
+  A refusal is audited as `denied` with `rule=role:<name>`.
+* Approval is an audited attestation, not a gate on execution: this server does not run other skills' steps, it
+  returns them (`pending_dispatch`) and each skill's server checks the caller's own role there.
+* Declares role metadata (no tool takes a target). README and setup guide: one endpoint for several people or roles.
+
 ## v2.2.0 — serve MCP over HTTPS
 
 `vmware-pilot mcp` can now serve the network as well as stdio (HLD §16, via vmware-policy 1.21.0):
@@ -8,6 +102,15 @@ vmware-pilot mcp --transport https --host 0.0.0.0 --port 8443 \
     --cert server.pem --key server-key.pem --public-name mcp.example.com
 ```
 
+Connect a client and manage callers (Claude Code shown; any MCP client with streamable HTTP and custom headers works):
+
+```bash
+claude mcp add --transport http vmware-pilot https://mcp.example.com:8443/mcp \
+    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"
+vmware-audit token list                  # names only
+vmware-audit token revoke alice          # refused from its next request, no restart
+```
+
 * Every request needs `Authorization: Bearer <token>`; the server will not start without a token, refuses Host or
   Origin values outside `--public-name`, and checks itself (unauthenticated requests must get 401) before it
   binds. `--transport http` binds loopback only, for a TLS-terminating reverse proxy.

{vmware_pilot-2.2.0 → vmware_pilot-2.4.0}/SECURITY.md

@@ -32,14 +32,15 @@ A workflow pauses at each `require_approval` step until `approve()` is called wi
 1. **Review before every run** — `run_workflow` reviews the plan and refuses one whose destructive step (skill-catalog risk high/critical, or a destructive name) or unclassifiable step has no gate before it
 2. **Custom workflows are rejected, not warned** — for a custom YAML, `create_workflow`, or AI-designed workflow, that same finding makes `create_workflow_from_template`, `create_workflow` and `confirm_draft` refuse to save it and `run_workflow` refuse it even with `force=True`; only built-in templates keep the audited `force=True` override
 3. **Credentials and guest commands count as destructive** — `vks issue_tkc_kubeconfig` and `issue_supervisor_kubeconfig` return a live Supervisor credential, and the aiops guest tools (`run_vm_guest_command`, `run_vm_guest_command_with_output`, `upload_vm_guest_file`, `provision_vm_guest`) run arbitrary commands or write files inside a VM as the account the caller names; all are gated like a delete
-4. **The gate is in pilot's workflow, not in the target skill** — on the MCP server pilot executes nothing itself; the calling agent performs each step through the companion skill, which applies its own policy rules
+4. **The gate is in pilot's workflow, not in the target skill** — by default pilot executes nothing itself; the calling agent performs each step through the companion skill, which applies its own policy rules
+5. **`--dispatch` makes the gate hold for workflows run through pilot** — pilot then runs each step in that skill's own MCP server (same policy, confirmation gate and audit) and nothing after a gate runs before `approve`. It does not stop an agent from calling a skill directly. stdio only: refused with a network transport, because the skill servers it starts would have no caller identity and roles could not apply
 
 ### Rollback (explicit, best-effort — never automatic)
 
 - A failed step stops the workflow (`failed`); remaining steps are marked `skipped` and nothing is undone automatically
 - `rollback()` and `cancel_workflow()` preview by default: without `confirm=True` they return `blast_radius` (steps undone, left applied, or skipped) and change nothing; `confirm=True` refuses when the state does not allow the transition, a step status is unrecognised, the record cannot be read, or a step was left `running`/`interrupted` (unknown effect) — the last only lifts with an explicit `acknowledge_unknown_effects=True` after the step is checked in the target system
-- `rollback()` must be called deliberately. It reverses, last first, only the steps pilot recorded as `success`, dispatching each step's `rollback_tool` — which only happens when an embedder supplied a dispatcher. On the MCP server (no dispatcher) the steps the agent performed are recorded `not_executed`, so `rollback()` reverses nothing but approval gates; the agent must call each performed step's `rollback_tool` itself
-- Steps without a `rollback_tool` are reported `skipped`; a failed undo does not stop the rest and sets `blocked_reason: rollback_failed`
+- `rollback()` must be called deliberately. It reverses, last first, only the steps pilot recorded as `success`, dispatching each step's `rollback_tool` — which only happens when pilot runs with `--dispatch` (or an embedder supplied a dispatcher). On the MCP server without `--dispatch` the steps the agent performed are recorded `not_executed`, so `rollback()` reverses nothing but approval gates; the agent must call each performed step's `rollback_tool` itself
+- Steps without a `rollback_tool` are reported `not_reversible` (their change stays); an undo that does not remove what the step created is `partial`; a failed undo does not stop the rest and sets `blocked_reason: rollback_failed`
 - Rollback results are kept on the workflow record and each `rollback` call is audited to `~/.vmware/audit.db`
 - A dispatched step or undo that returns a top-level `action: preview` (a companion tool called without `confirm=True`) is recorded `failed`, never `success`; built-in templates pass `confirm=True` to those tools only in steps that come after an approval gate (a test fails any template that does so earlier)
 

{vmware_pilot-2.2.0 → vmware_pilot-2.4.0}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-pilot==2.2.0",
+        "vmware-pilot==2.4.0",
         "vmware-pilot-mcp"
       ]
     }

{vmware_pilot-2.2.0 → vmware_pilot-2.4.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/vmware-pilot",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Multi-step workflow orchestration for VMware MCP skills with approval gates and rollback.",
   "private": true,
   "license": "MIT",

{vmware_pilot-2.2.0 → vmware_pilot-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-pilot"
-version = "2.2.0"
+version = "2.4.0"
 description = "VMware workflow orchestration — multi-step state machine with approval gates"
 readme = "README.md"
 license = "MIT"
@@ -12,7 +12,7 @@ requires-python = ">=3.10"
 authors = [{ name = "Wei Zhou", email = "wei-wz.zhou@broadcom.com" }]
 dependencies = [
     "vmware-policy>=1.21.0,<2.0",
-    "mcp[cli]>=1.28,<2.0",
+    "mcp[cli]>=1.30,<2.0",
     "pyyaml>=6.0,<7.0",
     "typer>=0.12,<1.0",
 ]

{vmware_pilot-2.2.0 → vmware_pilot-2.4.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/vmware-skills/VMware-Pilot",
     "source": "github"
   },
-  "version": "2.2.0",
+  "version": "2.4.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-pilot",
-      "version": "2.2.0",
+      "version": "2.4.0",
       "runtimeHint": "uvx",
       "packageArguments": [
         {