feat: Add guest execution agent and vsock support

- Introduced a standalone guest execution agent to facilitate command execution within the guest VM over Firecracker's vsock.
- Enhanced FirecrackerClient to support vsock configuration, validating guest CID and UDS path.
- Updated configuration to include vsock settings by default.
- Refactored FirecrackerProcessManager to manage runtime sockets more effectively.
- Implemented guest agent installation and provisioning in the image store.
- Added API endpoints for executing commands in the VM and installing the guest agent.
- Improved error handling for guest execution failures and agent availability.

uvm/routers/vms.py

@@ -9,8 +9,11 @@ from ..api_models import (
     PortSyncResponse,
     PortUpdateRequest,
     VmActionResultResponse,
+    VmAgentInstallResponse,
     VmBulkActionRequest,
     VmCreateRequest,
+    VmExecRequest,
+    VmExecResponse,
     VmLogResponse,
     VmResponse,
     VmResizeRequest,
@@ -202,6 +205,32 @@ def sync_ports(
     )
 
 
+@router.post("/{vm_id}/exec", response_model=VmExecResponse)
+def execute_in_vm(
+    vm_id: str,
+    request: VmExecRequest,
+    application: Application = Depends(get_authorized_application),
+) -> VmExecResponse:
+    """Execute a bounded, non-interactive guest command over vsock (exact VM ID)."""
+    result = application.lifecycle.execute(
+        vm_id, request.command, sudo=request.sudo, timeout_seconds=request.timeout_seconds,
+    )
+    return VmExecResponse(
+        exit_code=result.exit_code, stdout=result.stdout, stderr=result.stderr,
+        timed_out=result.timed_out, truncated=result.truncated,
+    )
+
+
+@router.post("/{vm_id}/agent/install", response_model=VmAgentInstallResponse)
+def install_guest_agent(
+    vm_id: str,
+    application: Application = Depends(get_authorized_application),
+) -> VmAgentInstallResponse:
+    """Install/upgrade the execution agent on a stopped VM's retained private disk."""
+    vm = application.lifecycle.install_guest_agent(vm_id)
+    return VmAgentInstallResponse(id=vm.id)
+
+
 @router.get("/{identifier}/logs", response_model=VmLogResponse)
 def get_vm_logs(
     identifier: str,