refactor: simplify microvm spawner

[justinmoon]

Summary

• simplify vm-spawner down to private create/recover/delete/health behavior
• move the microvm request/response contract to the minimal production shape and remove stale host config surface
• keep compatibility for pre-rollout VMs during recover/delete and add deterministic layout tests

Testing

• cargo test -p vm-spawner -p pika-agent-microvm -p pika-agent-control-plane
• just pre-commit

---

Summary by CodeRabbit

Release Notes

• Documentation

  • Added comprehensive documentation for MicroVM Spawner scope and lifecycle management.

• Refactor

  • Simplified VM provisioning API by removing optional configuration parameters, reducing complexity for standard deployments.
  • Streamlined VM response payloads to essential information.
  • Removed redundant HTTP endpoints (list VMs, get VM details, execute commands, capacity queries).
  • Reduced configuration surface, eliminating unnecessary environment variables and settings.
  • Simplified infrastructure configuration requirements.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR simplifies the MicroVM provisioning ecosystem by removing optional configuration fields (spawn_variant, flake_ref, dev_shell, cpu, memory_mb, ttl_seconds) from multiple data structures across control plane, microvm, and spawner crates. The provisioning return type changes from rich VmResponse to a simple vm_id String, default constants are deleted, and VM spawner endpoints/configuration are streamlined. Additionally, a major internal refactor in the manager introduces layout-based VM allocation and error types, and HTTP routes are reduced.

Changes

Cohort / File(s)	Summary
Control Plane & Microvm Struct Simplification crates/pika-agent-control-plane/src/lib.rs, crates/pika-agent-microvm/src/lib.rs	Removed optional/mandatory fields (spawn_variant, flake_ref, dev_shell, cpu, memory_mb, ttl_seconds) from MicrovmProvisionParams and ResolvedMicrovmParams; deleted public constants (DEFAULT_FLAKE_REF, etc.); changed VmResponse from rich struct to optional status field; simplified CreateVmRequest to only guest_autostart; removed get_vm method from client.
VM Spawner Manager Refactoring crates/vm-spawner/src/manager.rs	Major internal restructure introducing layout-based VM allocation with VmHostLayout and VmRuntimeMetadata abstractions; added public error types InvalidVmIdError and VmNotFoundError; replaced in-memory state model with layout-driven lifecycle; updated cleanup, IP/ID reservation, and metadata handling; added deterministic derivation tests.
VM Spawner Models Streamlining crates/vm-spawner/src/models.rs	Drastically simplified CreateVmRequest (only guest_autostart remains) and VmResponse (only id field); removed CapacityResponse, SessionRegistry, SessionRecord, PersistedVm structs and their implementations; removed default_spawn_variant helper.
VM Spawner Configuration & Routing crates/vm-spawner/src/config.rs, crates/vm-spawner/src/main.rs	Removed 13 configuration fields (definition_dir, sessions_file, dhcp_hosts_dir, workspace_template_path, etc.) and max_vms() method; removed GET /vms, GET /vms/:id, /vms/:id/exec, /capacity endpoints; simplified health endpoint and removed background tasks (TTL reaper, health ticker); added error type imports for status mapping.
Server Provisioning Flow Integration crates/pika-server/src/agent_api.rs	Changed provision_vm_for_owner return type from VmResponse to String (vm_id); removed phase_from_vm_status helper; updated provisioning, recovery, and agent status flows to set phase directly to READY using vm_id instead of deriving from remote status; simplified spawner params to only populate spawner_url.
Infrastructure & Documentation infra/nix/modules/microvm-host.nix, docs/microvm-spawner-scope.md	Removed 9 environment variables and related dnsmasq/tmpfiles configuration (definition_dir, sessions_file, dhcp setup); updated service startup to use reduced directory/env set; added new MicroVM Spawner scope documentation clarifying responsibilities and lifecycle interactions.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• MicroVM MVP rollout: server auth/allowlist, CLI flow, and host integration #452: Overlapping changes to MicrovmProvisionParams, ResolvedMicrovmParams, and CreateVmRequest fields during MicroVM MVP rollout.
• fix(agents): address review follow-ups #454: Reversed additions of status/get_vm endpoint and phase_from_vm_status logic in spawner client integration.

Poem

🐰✨ Burrows simplified, clutter shed,
Configuration fields now wisely spread—
Fewer options, cleaner paths,
Layout-driven, no more wrath!
Simpler spawning, lighter load,
A streamlined rabbit's lean abode. 🏡

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 21.74% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'refactor: simplify microvm spawner' directly and clearly summarizes the main change—a refactor to simplify the microvm spawner's API surface and configuration.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 7 additional findings.