diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f452156..aa82e24 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,14 +20,14 @@ Component-specific tooling lives in its own directory (`runtimes/rizin/`, `tests Do not add Git submodules: Claude Code clones a marketplace with every submodule into each user's plugin cache. Record build-time sources in a lock file and fetch them into ignored `build/` at build time, as `runtimes/rizin/build_bundle.py` does. A checkout that initialized the old submodules keeps an untracked `sources/` directory; delete it rather than adding it back (the checker rejects gitlink entries). -Within Hyper-V Control, `HyperVTools*` exposes the MCP contract, `Services/` owns host/guest operations and resource lifetimes, and `Extracted/` contains the core Hyper-V service, console and guest UI implementation. Keep protocol handling out of the extracted layer. Changes to VM state, credentials, elevation, or debugger lifetime need behavior tests at their corresponding boundary. +Within Hyper-V Control, `HyperVTools*` exposes the MCP contract and contains no PowerShell text: a tool method parses and validates its arguments, calls one service, and returns an object. `Services/` owns host/guest operations and resource lifetimes. Every host-side Hyper-V script is built with `Services/HyperVScript.cs` (shared module bootstrap, in-script VM resolution by exact name or GUID, state assertions, typed parameter rendering, one failure envelope `{ ok:false, error, errorType, errorId, category }`) and executed through `PowerShellRunner.InvokeAsync`; `VmLifecycleService`, `ImageCatalogService` and `ImageBuildService` own lifecycle, catalog and image work, and `JobRunner` hosts operations that outlive one tool call. `Extracted/` contains the core Hyper-V inventory/power/checkpoint service, console and guest UI implementation; keep protocol handling out of it. Changes to VM state, credentials, elevation, or debugger lifetime need behavior tests at their corresponding boundary. Host scripts are tested without a Hyper-V host against the recording mock module under `tests/HyperVControl.Tests/MockHyperV/` (selected through `HYPERV_CONTROL_MODULE_PATH`; add cmdlets in `*.functions.ps1` files), which records every cmdlet call with its bound parameters; live phases of the harness (`lifecycle-live`, `images-live`, `image-build-live`) create and remove throwaway VMs named `HyperVControl-validation-*` and need explicit authorization. ## Sources of truth - Edit `plugins//plugin.json` for plugin identity, version, and interface metadata. Both clients cache an installed plugin by its version string, so bump the version whenever installed content changes. Run `python scripts/check-marketplace.py --sync` to generate `.codex-plugin/plugin.json`, `.claude-plugin/plugin.json`, and the root `.claude-plugin/marketplace.json`; do not maintain these compatibility copies independently. Claude marketplace entries come from the canonical catalog and plugin descriptions; marketplace owner/description metadata lives in the checker's `claude_marketplace` function. - Edit a plugin's portable `mcp.json` for MCP commands, using `${PLUGIN_ROOT}` for paths inside the package. The same sync command generates `.codex-plugin/mcp.json` with `${PLUGIN_ROOT}` and `.mcp.json` with `${CLAUDE_PLUGIN_ROOT}`. Point the canonical `com.openai.mcpServers` field at `./.codex-plugin/mcp.json`. Claude automatically reads the root `.mcp.json`; keeping the client files separate prevents unresolved path variables. Both clients share the same `skills/` and runtime helpers. - Native downloads use the plugin's `runtime.json` for the exact release tag, asset, and SHA-256; both installers verify the download against it and never resolve a latest release. Rizin's build inputs are in `runtimes/rizin/bundle.lock.json`; after publishing a new Rizin runtime, update the plugin's `runtime.json` pin. Keep dependency versions in metadata and lockfiles. -- Hyper-V's project, CLI, and protocol versions must match its runtime pin. The plugin version can advance independently for launcher or skill updates. The repository checker rejects inconsistent runtime updates. CI rebuilds the executable and compares it with the published pinned asset (`scripts/compare-hyperv-runtime.py`): the host, the bundled runtime, and the app assembly's IL and metadata must match byte for byte, while compiler-recorded build identifiers (PE timestamp, module version id, PDB id and checksum) may differ, because they change with comment-only edits and with the runtime patch the compiler happens to run on. +- Hyper-V's project, CLI, and protocol versions must match its runtime pin. The plugin version can advance independently for launcher or skill updates. The repository checker rejects inconsistent runtime updates. CI rebuilds the executable and compares it with the published pinned asset (`scripts/compare-hyperv-runtime.py`): the host, the bundled runtime, and the app assembly's IL and metadata must match byte for byte, while compiler-recorded build identifiers (PE timestamp, module version id, PDB id and checksum) may differ, because they change with comment-only edits and with the runtime patch the compiler happens to run on. The bundle deflates its files (`EnableCompressionInSingleFile`), so the comparison inflates each entry first and ignores the bundle header offset the host stores, which moves with the compressed sizes. - README files explain purpose, setup, and usage. Keep current version numbers, release dates, and changelogs out of them. The [download catalog](docs/guides/releases.md#release-index) is the maintained entrypoint for current releases. - Skills explain how an agent should choose tools and interpret results. Put detailed task procedures in their `references/` directory and scripts needed at runtime inside the plugin. - Record experiments in validation reports and keep their harnesses under `tests//`. Imported material lives under `docs/archive//` with an `import-manifest.json`; the checker verifies those files byte-for-byte, so never edit them. Plugins ship only maintained content. diff --git a/docs/README.md b/docs/README.md index 08054e1..6de2b40 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,7 +22,7 @@ These are dated or versioned records of what was tested, including environment d | Rizin | [Runtime validation](validation/rizin/runtime-v0.3.1/report.md) | | Capstone Binary Patching | [Native patching experiments](validation/capstone-binary-patching/plugin-v0.1.0/report.md) | | Frida Use | [Windows instrumentation experiments and evidence](validation/frida-use/2026-10-01/report.md) | -| Hyper-V Control | [VM, console, and debugger validation](validation/hyper-v-control/runtime-v0.1.0/report.md) | +| Hyper-V Control | [Lifecycle v2, images, image builds and jobs](validation/hyper-v-control/runtime-v0.2.0/report.md) ยท [VM, console, and debugger validation](validation/hyper-v-control/runtime-v0.1.0/report.md) | ## Archive diff --git a/docs/guides/releases.md b/docs/guides/releases.md index d541459..b573d77 100644 --- a/docs/guides/releases.md +++ b/docs/guides/releases.md @@ -8,7 +8,7 @@ This repository supports the [Codex marketplace workflow](https://developers.ope | Runtime | Release | Download | | --- | --- | --- | -| Hyper-V Control | [Windows x64](https://github.com/JerryLinLinLin/jerry-plugin-marketplace/releases/tag/hyper-v-control-v0.1.0) | Self-contained MCP executable | +| Hyper-V Control | [Windows x64](https://github.com/JerryLinLinLin/jerry-plugin-marketplace/releases/tag/hyper-v-control-v0.2.0) | Self-contained MCP executable | | Rizin | [Windows x64](https://github.com/JerryLinLinLin/jerry-plugin-marketplace/releases/tag/rizin-v0.3.1) | Portable runtime; RetDec build SDK is a separate maintainer asset | Frida and Capstone dependencies are installed by their plugin setup workflows. They do not need a binary release in this repository. diff --git a/docs/validation/hyper-v-control/runtime-v0.2.0/report.md b/docs/validation/hyper-v-control/runtime-v0.2.0/report.md new file mode 100644 index 0000000..1ecf27c --- /dev/null +++ b/docs/validation/hyper-v-control/runtime-v0.2.0/report.md @@ -0,0 +1,53 @@ +# Validation + +Validation date: October 14, 2026 (America/Chicago). Local Windows 11 Pro 26200 x64 host with client Hyper-V (VM configuration version 12.0), .NET SDK 10.0.401, self-contained .NET runtime 10.0.12, official MCP C# SDK 2.2.0. Runtime 0.2.0 adds VM lifecycle v2 (state-gated configuration, create sources, guarded removal, clones, standalone disks, adapters, NAT switches), an image catalog and library with background jobs, golden image builds, and a shared PowerShell script pipeline with a mock-module test seam. + +Live phases ran on throwaway VMs named `HyperVControl-validation-*` with files under `D:\HyperVControl-validation\`, all removed afterwards. The user's existing VMs (`Windows 11 AV Test`, `sibyl-test01`, `New Virtual Machine`) and switches were never changed. The user authorized the throwaway VMs, one download of the Ubuntu 22.04 gallery image, and a user-local .NET SDK 10 installation. + +## Measured behavior + +| Area | Evidence | +| --- | --- | +| Build | C# compilation and single-file publish with zero warnings/errors; `--version` reports 0.2.0 | +| Unit phase | 192 checks pass against the recording mock module (no Hyper-V host): script quoting, guest wrapper, lifecycle v1/v2 state rules and parameter rendering, image catalog parsing of the real feed, fetch/resume/hash/cancel over a local HTTP server, deploy rendering, image build scripts and unattend, elevation bridge header | +| MCP protocol | Official client initialized the EXE over stdio and discovered 41 unique tools; invalid paths and unknown actions return the uniform `{ok:false, error, errorType}` envelope | +| Elevation | Same-user worker; `HYPERV_CONTROL_IMAGE_ROOT` set only in the client process reached the elevated worker (the worker reported the library root under that path) | +| Lifecycle v2 (`lifecycle-live`) | 28 of 28 steps: create (new disk), configure Off, start, configure while Running (static memory resize attempted; vCPU change refused with the setting named), adapter add/remove while Running, firmware/TPM, standalone VHD create/inspect, linked clone, remove with dry run then `deleteDisks`, files verified gone | +| Images (`images-live`) | Catalog list flagged the expired Windows 11 image and recommended Ubuntu 22.04; fetch job downloaded 2,484,769,532 bytes, verified SHA-256, extracted a 6,417,285,120-byte Zip64 VHDX in 172 s and deleted the archive; linked-clone deploy on the Default Switch (resolved by ID) with Secure Boot off per the feed, HvSocket, static memory, Standard checkpoints; the VM booted (heartbeat OK, basic console showed Ubuntu's first-boot wizard); remove refused while the clone existed; VM, disk, entry and file removed | +| Image build (`image-build-live`) | Synthetic WIM inside an ISO through the full Windows pipeline in 26 s: GPT layout (300 MB FAT32 EFI, 16 MB MSR, NTFS), applied files, Panther unattend with the exact password, byte-identical `C:\Tools`, boot store with debug and network-debug settings; a WIM without boot files failed with bcdboot's reason and its outputs were removed; Linux build refused without `qemu-img` naming `HYPERV_CONTROL_QEMU_IMG`; a `.vhdx` source was resized and a `CIDATA` seed ISO with `user-data` and `meta-data` mounted on the host | +| Integration (final build) | 19 of 19 steps: `hyperv_vhd` create, `hyperv_image` register, `hyperv_vm_create source=image` (linked clone of the registered template, parent read-only), info, start, Running-state refusal, full clone as a job, export as a job, jobs list, remove dry run, remove with `deleteDisks` for both VMs, image remove with file deletion, inventory unchanged | +| Removal reporting | A linked VM's removal lists its parent under `kept` with the reason and the `hyperv_vhd delete` follow-up; the parent was then deleted once unused | +| Packaging | Marketplace checker (49 documents), runtime packaging, launcher test from a path with spaces, release isolation and corrupt-download rejection all pass | + +## Findings fixed during validation + +- `Export-VM` fails with `Access is denied (0x80070005)` when any disk in the VM's chain carries the read-only attribute, which the plugin sets on linked parents. Reproduced with a plain VM (export succeeded), a linked VM (failed), and the same VM after clearing the attribute (succeeded). Exports and full clones now clear the attribute for the duration of the export and restore it. +- A UAC launch starts the worker with the profile environment, so every `HYPERV_CONTROL_*` override set only in the MCP client's process environment was lost. The bridge now forwards `HYPERV_CONTROL_*`, `HYPERV_GUEST_*` and `_NT_SYMBOL_PATH` over its pipe. +- `New-VM` on this host enables dynamic memory and boots from the network adapter before the disk; create and linked clone set the memory mode and first boot device explicitly. +- A full clone's copied parent and a linked clone's template were neither deleted nor reported by removal; they are now listed under `kept`. + +## Follow-up on October 14, 2026, before the release + +Three changes landed after the runs above, on the same host. The executable was rebuilt and `runtime.json` re-pinned; the 0.2.0 asset is still unpublished. The Images row above records the date heuristic that flagged the Windows 11 image as expired; that heuristic was wrong (the user verified that Quick Create still downloads and runs the image) and is gone. + +| Area | Evidence | +| --- | --- | +| Elevation on demand | `--elevate` no longer prompts at start. Through the real launcher, unelevated: initialize, 41 tools and ping were answered with no worker process. With the test seam `HYPERV_CONTROL_WORKER=always` on the published EXE: the first tool call starts exactly one worker, ten concurrent first calls start one worker, the second call reuses it, `HYPERV_CONTROL_IMAGE_ROOT` set only for the server reaches the worker, closing stdin ends both processes within about 40 ms, and a worker killed between calls is reported once as `ElevatedWorkerExited` and replaced on the next call. Unit checks with injected launchers cover the `runas` start info, `ElevationDeclined` with a new prompt on the next call, cancellation while a prompt is open, and the refusal of a non-elevated worker without the seam. | +| Default image | `hyperv_vm_create` defaults to `source=image` with Microsoft's Windows 11 dev environment, or `HYPERV_CONTROL_DEFAULT_IMAGE`. Unit checks: the saved gallery feed marks the image fetchable and recommended with an evaluation warning; default resolution with and without the variable; a library image deploys within the call against the mock module; an absent image runs one quick-create job (local HTTP fixture, then the mock module) whose result is the VM; a running fetch of the same image is joined; parameters of other sources are refused. The smoke phase confirms both refusals on the published EXE before any download. No image was downloaded. | +| Bundle size | `EnableCompressionInSingleFile`: 53,380,027 bytes instead of 120,887,421. Measured here: `--version` 79 ms (42 ms uncompressed) and initialize plus tools/list 258 ms (210 ms). ReadyToRun gave 146 MB and 109 ms but no gain once compressed; Native AOT is refused (`PublishTrimmed` cannot be false for Windows Forms, and 89 IL2026/IL3050 warnings come from WMI, the RDP ActiveX control and reflection-based JSON). Per tool call the host still pays about 1 s for powershell.exe plus the Hyper-V module import. | +| Differencing disks | CI's small runner volume exposed that a linked clone or a differencing `hyperv_vhd` demanded the parent's full virtual size free on the target volume (the mock parent reports 64 GB; the runner had about 14 GB), which would also refuse a linked clone of the 44.8 GB Windows 11 image on most lab volumes. A differencing child now needs 1 GB free and the result warns when the volume could not hold the parent's size. | +| Checks | Unit 215 (192 before), stdio smoke including the proxy checks, launcher, release isolation, runtime packaging, marketplace checker (50 documents), and the CI comparison on two compressed builds that differ only in build identifiers. | + +## Practical limits + +- The real UAC prompt was not clicked in this session: approving, declining, and the elevated worker's process and user checks under a high-integrity token were exercised only through the seam. The first tool call of the next session is the test. +- The Windows 11 dev environment was not fetched or booted through the plugin (23.3 GB download, about 69 GB free needed); Quick Create's own download and VM were verified by hand. The plugin's deploy of that image, with Secure Boot and a vTPM, is covered by the mock module only. +- A static memory resize on a Running VM is refused by Hyper-V until a guest OS has booted; the live VMs had no OS, so a successful live resize was not observed. +- No VM has booted from a built golden image. On this host `bcdboot` could not create the boot store with any source, so the pipeline falls back to `bcdedit` with the image's `BCD-Template` and says so in the warnings; unattend behavior on 26H2 is unverified. The evaluation ISO download, `qemu-img` conversion and cloud-init in a real Ubuntu VM were tested only against mocks and local servers. +- NAT switch creation, removing a Saved VM, Generation 1 paths, attaching an ISO while Running, full clones of VMs with checkpoints, file and UNC catalogs, `keepArchive`, resume over the internet and the Windows deploy path (vTPM, Microsoft Windows template) were exercised only against the mock module. +- Generation 2 guests detect a COM port mapped while Running only after a full stop and start. +- During an early experiment of the image-build work, `bcdboot` was run once against the host's own `C:\Windows`; BitLocker logged a key reseal on the system volume. The boot manager was found byte-identical afterwards and protection stayed on. The shipped pipeline never uses the host's Windows as a source. + +## Reproduction + +Build with `scripts/build-hyperv-control.ps1 -DotNet `; run the C# harness in `unit` and `smoke` modes, then `scripts/test-hyperv-launcher.ps1` and `scripts/test-release-isolation.ps1`. Live phases are explicit: `lifecycle-live`, `images-live` (downloads 2.5 GB; set `HYPERV_CONTROL_IMAGE_ROOT` to a volume with 10 GB free), `image-build-live`, plus the earlier `prepare`/`guest`/`ui`/`debug`/`kernel-*`/`cleanup` phases for the unchanged channels. Each live phase creates and removes its own `HyperVControl-validation-*` VMs and needs explicit authorization. Raw results are written under ignored `build/hyperv-control/validation`. diff --git a/plugins/hyper-v-control/.claude-plugin/plugin.json b/plugins/hyper-v-control/.claude-plugin/plugin.json index 71f6a9b..181e941 100644 --- a/plugins/hyper-v-control/.claude-plugin/plugin.json +++ b/plugins/hyper-v-control/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "hyper-v-control", - "version": "0.1.3", + "version": "0.2.0", "description": "Control Hyper-V VMs, graphical consoles, guest automation and user/kernel debugging through a native C# stdio MCP server.", "author": { "name": "JerryLinLinLin", diff --git a/plugins/hyper-v-control/.codex-plugin/plugin.json b/plugins/hyper-v-control/.codex-plugin/plugin.json index c3598ec..ff3d592 100644 --- a/plugins/hyper-v-control/.codex-plugin/plugin.json +++ b/plugins/hyper-v-control/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "hyper-v-control", - "version": "0.1.3", + "version": "0.2.0", "description": "Control Hyper-V VMs, graphical consoles, guest automation and user/kernel debugging through a native C# stdio MCP server.", "author": { "name": "JerryLinLinLin", diff --git a/plugins/hyper-v-control/README.md b/plugins/hyper-v-control/README.md index c0280c1..f9c4e28 100644 --- a/plugins/hyper-v-control/README.md +++ b/plugins/hyper-v-control/README.md @@ -4,7 +4,9 @@ Manage a Hyper-V lab from your AI agent. Create and restore experiments, interac ## What it helps with -- **VM management:** create, configure, start, stop, clone, import, and export virtual machines; manage disks and networking. +- **VM management:** create a Windows lab VM in one call from Microsoft's Windows 11 dev environment image (an evaluation edition; downloaded once, then linked clones in seconds), or from another library image, a new disk, an ISO, or an existing or linked disk; configure CPU, memory, firmware, vTPM, checkpoints, adapters and automatic actions, with changes gated by what Hyper-V allows while a VM runs; clone (linked in seconds, or full as a job); remove with a dry run and optional, guarded disk deletion; manage disks, switches and NAT networks. +- **Images and templates:** list Microsoft's Quick Create gallery or your own catalog, download and verify images into a local library as background jobs, choose the default image, register your own disks, and deploy linked-clone lab VMs from them in seconds with lab-friendly defaults. +- **Golden images:** build a Windows template from an ISO or Microsoft evaluation media applied offline with an unattend file (local admin, RDP, no device encryption, optional kernel-debug settings), or an Ubuntu template from a cloud image with a NoCloud seed, without ever running Setup interactively. - **Repeatable experiments:** inspect checkpoint trees, save a known state, and restore it after testing. - **Desktop interaction:** use Basic or Enhanced Session, capture screenshots, send mouse and keyboard input, and work with guest UI Automation. - **Guest automation:** run commands and processes, transfer files and folders, and manage reusable credentials. @@ -33,7 +35,7 @@ For an offline machine, use the plugin's `scripts/install.ps1` in your preparati ## Permissions and guest setup -With `--elevate`, Windows requests administrator approval once when needed. Subsequent operations use the same elevated worker until the MCP session ends. The MCP client can stay unelevated. UAC cancellation exits without operating on VMs; alternate-user elevation is unsupported. See the [permission model](skills/hyper-v-control/references/runtime.md). +With `--elevate`, starting the MCP server never prompts. Windows asks for administrator approval on the first tool call, once per MCP session: that call and every later one use the same elevated worker until the session ends. The MCP client can stay unelevated. Declining fails only that call, without operating on VMs, and the next call asks again; alternate-user elevation is unsupported. See the [permission model](skills/hyper-v-control/references/runtime.md). Run `hyperv_capabilities` to inspect the host and available integrations. Windows guest automation needs credentials for PowerShell Direct. UI Automation needs an unlocked interactive guest desktop; Enhanced Session needs guest support and host policy. Basic Session can interact with boot screens and guests without PowerShell Direct. diff --git a/plugins/hyper-v-control/plugin.json b/plugins/hyper-v-control/plugin.json index 439af3a..b7927ac 100644 --- a/plugins/hyper-v-control/plugin.json +++ b/plugins/hyper-v-control/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "hyper-v-control", - "version": "0.1.3", + "version": "0.2.0", "description": "Control Hyper-V VMs, graphical consoles, guest automation and user/kernel debugging through a native C# stdio MCP server.", "author": {"name": "JerryLinLinLin", "url": "https://github.com/JerryLinLinLin"}, "repository": "https://github.com/JerryLinLinLin/jerry-plugin-marketplace", diff --git a/plugins/hyper-v-control/runtime.json b/plugins/hyper-v-control/runtime.json index 98951e6..fddb1bb 100644 --- a/plugins/hyper-v-control/runtime.json +++ b/plugins/hyper-v-control/runtime.json @@ -1,11 +1,11 @@ { "plugin": "hyper-v-control", - "version": "0.1.0", - "tag": "hyper-v-control-v0.1.0", - "asset": "hyper-v-control-win-x64-v0.1.0.exe", + "version": "0.2.0", + "tag": "hyper-v-control-v0.2.0", + "asset": "hyper-v-control-win-x64-v0.2.0.exe", "rid": "win-x64", "framework": "net10.0-windows", "selfContained": true, - "sha256": "c58492c6711e0448b47019092ca47624f0b71f5b3fd762053f13606409cefbc6", - "url": "https://github.com/JerryLinLinLin/jerry-plugin-marketplace/releases/download/hyper-v-control-v0.1.0/hyper-v-control-win-x64-v0.1.0.exe" + "sha256": "24ce6b1318271098197a473dc04e813a5c722060d22a127654fb7813784378ca", + "url": "https://github.com/JerryLinLinLin/jerry-plugin-marketplace/releases/download/hyper-v-control-v0.2.0/hyper-v-control-win-x64-v0.2.0.exe" } diff --git a/plugins/hyper-v-control/skills/hyper-v-control/SKILL.md b/plugins/hyper-v-control/skills/hyper-v-control/SKILL.md index 15c430a..208610b 100644 --- a/plugins/hyper-v-control/skills/hyper-v-control/SKILL.md +++ b/plugins/hyper-v-control/skills/hyper-v-control/SKILL.md @@ -5,7 +5,7 @@ description: Manage Hyper-V VM lifecycle and checkpoints, operate Basic or Enhan # Hyper-V Control -Use this plugin's `hyperv_*` MCP tools. The runtime is a compiled Windows x64 C# EXE speaking stdio. It requires no Python or user-side SDK. If unavailable, read [runtime and permissions](references/runtime.md). +Use this plugin's `hyperv_*` MCP tools. The runtime is a compiled Windows x64 C# EXE speaking stdio. It requires no Python or user-side SDK. If unavailable, read [runtime and permissions](references/runtime.md). The first tool call of a session can show a Windows UAC prompt; after `ElevationDeclined`, ask the user before calling again, because each new call prompts again. Start with `hyperv_capabilities` and `hyperv_list` when host or target state is unknown. Resolve the exact VM name/ID and re-read state before dependent operations. An existing authorization to operate a test VM carries through the requested workflow; ask only for missing credentials or materially new/destructive scope. @@ -13,7 +13,12 @@ Choose the channel that fits the task: | Task | Channel | | --- | --- | -| Inventory, creation, hardware, start/stop, export/import | VM tools; no console needed | +| Inventory, creation, hardware, start/stop, export/import | VM tools; no console needed. `vm_create` defaults to `source=image` (the default image, next rows); other sources: new_disk, iso, existing_vhd, linked, none. Changes are gated by VM state and refused with the list of settings that need Off | +| Delete a VM safely, inspect or create disks, clone | `vm_remove` with `dryRun` then `deleteDisks` (never powers off; keeps shared disks and linked parents); `vhd` create/inspect/delete; `vm_clone` linked (seconds) or full (a job) | +| Obtain a bootable image: Microsoft's gallery or a custom catalog, the local library, verified download and extraction | `image` (`list` with `defaultImage`, `fetch` as a job, `register`, `remove`, `catalogs`); poll with `jobs` | +| Create a Windows lab VM in one call: the default image is Microsoft's Windows 11 dev environment (a Windows 11 Enterprise evaluation), or `HYPERV_CONTROL_DEFAULT_IMAGE` | `vm_create` without `source`: a linked clone with lab defaults in seconds once the image is in the library; otherwise one job downloads it first (23.3 GB, about 69 GB free needed) and its result is the VM. Before that first download, check `image` `list` (`defaultImage.inLibrary` is null) and confirm with the user. `image` `deploy` or `vm_create imageName=` for other images | +| Build a golden template without running Setup: Windows ISO or evaluation media applied offline with an unattend, or an Ubuntu cloud image with a NoCloud seed | `image_build` (a job); register the sidecar with `image` `register` | +| Anything that outlives one call: downloads, extraction, export/import, full clones, image builds | `jobs` (`list`, `status`, `wait`, `cancel`) | | Reproduce and roll back a test | Checkpoint tools; retain the checkpoint ID and initial power state | | Boot, firmware, sign-in, locked desktop, visual clicks | Basic console + inline screenshot + input | | Resizable remote desktop and clipboard | Enhanced console; check the actual mode returned | @@ -23,6 +28,6 @@ Choose the channel that fits the task: | Debug the VM's kernel | KDNET or two-phase KDCOM, then host KD session | | Analyze an existing dump | `debug_open` with `mode=dump`; copy guest dumps to host first | -For lifecycle/rollback details read [VM operations](references/operations.md). For console, keyboard/mouse, clipboard and winapp read [guest interaction](references/interaction.md). For live debugging read [debugging](references/debugging.md). +For lifecycle/rollback details read [VM operations](references/operations.md). For catalogs, the image library, fetch jobs and deployment read [images](references/images.md). For golden image builds read [image builds](references/image-build.md). For console, keyboard/mouse, clipboard and winapp read [guest interaction](references/interaction.md). For live debugging read [debugging](references/debugging.md). Read the actual MCP schema for parameter names. Tool failures arrive as `isError` with an explanation; do not interpret process startup, BCD configuration or a timeout as successful attachment/execution. After a mutation, verify through the channel that observes its result. Report unsupported states rather than substituting host input or changing guest security settings silently. diff --git a/plugins/hyper-v-control/skills/hyper-v-control/references/image-build.md b/plugins/hyper-v-control/skills/hyper-v-control/references/image-build.md new file mode 100644 index 0000000..00bcb29 --- /dev/null +++ b/plugins/hyper-v-control/skills/hyper-v-control/references/image-build.md @@ -0,0 +1,41 @@ +# Golden image builds + +`hyperv_image_build` turns OS media into a template VHDX that new VMs start from. It never creates a VM. Build once per OS release, keep the VHDX unchanged, and give each VM a differencing child (`New-VHD -Differencing -ParentPath