feat: add hypeman cp for file copy to/from running VMs (#45)

* refactor: rename exec-agent to guest-agent and add cp support

This commit renames the exec-agent to guest-agent to better reflect its
expanding role as a general-purpose guest interaction service. Along with
the rename, this adds gRPC support for file copy operations:

- Rename lib/exec to lib/guest
- Rename lib/system/exec_agent to lib/system/guest_agent
- Add CopyToGuest and CopyFromGuest RPCs
- Add StatPath RPC for querying guest filesystem metadata
- Implement cp handlers with uid/gid preservation support
- Update all imports and references

The guest-agent continues to listen on vsock port 2222 and handle
command execution, with new file copy capabilities.

* feat: add WebSocket endpoint for cp operations

Add /instances/{id}/cp WebSocket endpoint to enable file copy operations
between the local filesystem and running VM instances. Also adds
/instances/{id}/stat HTTP endpoint for querying guest path metadata.

Features:
- Copy files and directories to/from running instances
- Streaming file transfer with chunked data
- Support for symlinks and directory hierarchies
- UID/GID preservation for archive mode
- Follow symlinks option

* api: add dedicated /instances/{id}/stat endpoint

Add a separate HTTP endpoint for querying filesystem path info in guests.
This replaces the overloaded 'direction: stat' option in the cp WebSocket
endpoint with a cleaner REST API.

- Add PathInfo schema with exists, is_dir, is_file, is_symlink, etc.
- Add GET /instances/{id}/stat endpoint with path and follow_links params
- Add stat method to stainless.yaml for SDK generation

The new endpoint:
- Uses simple HTTP GET instead of WebSocket overhead
- Enables autogenerated SDK methods (client.Instances.Stat())
- Mirrors the guest agent's separate StatPath RPC
- Is self-documenting via OpenAPI spec

* test: add integration tests for cp operations

Add comprehensive integration tests for file copy functionality:
- Test copying single files to instance
- Test copying directories recursively to instance
- Test copying files from instance
- Test copying directories from instance
- Verify file content, permissions, and metadata preservation

Also adds Reset() method to outputBuffer helper used in tests.

* fix(cp): preserve directory modification times during copy

The mtime was only being applied when currentFile != nil, which is only
true for regular files. For directories, currentFile is never set since
they are created with os.MkdirAll without opening a file handle.

This fix moves the mtime logic outside of the currentFile != nil block
so it applies to both files and directories.

* chore: remove accidentally committed guest_agent binary

Updated .gitignore to cover both guest-agent and guest_agent naming
patterns and removed the tracked binary from the repository.

* feat(metrics): add cp metrics and OTEL tracing

Added metrics for copy operations following the exec metrics pattern:
- hypeman_cp_sessions_total (labels: direction, status)
- hypeman_cp_duration_seconds
- hypeman_cp_bytes_total

Also added OTEL span in CpHandler since WebSocket connections bypass
the otelchi middleware for HTTP request tracing.

* refactor(guest-agent): split main.go into logical files

Reorganized the 732-line main.go into a cleaner structure:
- main.go: Server setup, listener, gRPC registration (minimal)
- exec.go: Exec-related methods (Exec, executeTTY, executeNoTTY, buildEnv)
- cp.go: Copy methods (CopyToGuest, CopyFromGuest, helpers)
- stat.go: StatPath method

This matches the lib/*/README.md pattern used in the server codebase
and makes the guest-agent more maintainable as it grows.

Author: rgarcia

.gitignore

@@ -20,6 +20,8 @@ lib/vmm/binaries/cloud-hypervisor/*/*/cloud-hypervisor
 cloud-hypervisor
 cloud-hypervisor/**
 lib/system/exec_agent/exec-agent
+lib/system/guest_agent/guest-agent
+lib/system/guest_agent/guest_agent
 
 # Envoy binaries
 lib/ingress/binaries/**

Makefile

@@ -127,15 +127,23 @@ generate-grpc:
 	@echo "Generating gRPC code from proto..."
 	protoc --go_out=. --go_opt=paths=source_relative \
 		--go-grpc_out=. --go-grpc_opt=paths=source_relative \
-		lib/exec/exec.proto
+		lib/guest/guest.proto
 
 # Generate all code
 generate-all: oapi-generate generate-vmm-client generate-wire generate-grpc
 
 # Check if CH binaries exist, download if missing
 .PHONY: ensure-ch-binaries
 ensure-ch-binaries:
-	@if [ ! -f lib/vmm/binaries/cloud-hypervisor/v48.0/x86_64/cloud-hypervisor ]; then \
+	@ARCH=$$(uname -m); \
+	if [ "$$ARCH" = "x86_64" ]; then \
+		CH_ARCH=x86_64; \
+	elif [ "$$ARCH" = "aarch64" ] || [ "$$ARCH" = "arm64" ]; then \
+		CH_ARCH=aarch64; \
+	else \
+		echo "Unsupported architecture: $$ARCH"; exit 1; \
+	fi; \
+	if [ ! -f lib/vmm/binaries/cloud-hypervisor/v48.0/$$CH_ARCH/cloud-hypervisor ]; then \
 		echo "Cloud Hypervisor binaries not found, downloading..."; \
 		$(MAKE) download-ch-binaries; \
 	fi
@@ -156,27 +164,27 @@ ensure-caddy-binaries:
 		$(MAKE) build-caddy; \
 	fi
 
-# Build exec-agent (guest binary) into its own directory for embedding
-lib/system/exec_agent/exec-agent: lib/system/exec_agent/main.go
-	@echo "Building exec-agent..."
-	cd lib/system/exec_agent && CGO_ENABLED=0 go build -ldflags="-s -w" -o exec-agent .
+# Build guest-agent (guest binary) into its own directory for embedding
+lib/system/guest_agent/guest-agent: lib/system/guest_agent/main.go
+	@echo "Building guest-agent..."
+	cd lib/system/guest_agent && CGO_ENABLED=0 go build -ldflags="-s -w" -o guest-agent .
 
 # Build the binary
-build: ensure-ch-binaries ensure-caddy-binaries lib/system/exec_agent/exec-agent | $(BIN_DIR)
+build: ensure-ch-binaries ensure-caddy-binaries lib/system/guest_agent/guest-agent | $(BIN_DIR)
 	go build -tags containers_image_openpgp -o $(BIN_DIR)/hypeman ./cmd/api
 
 # Build all binaries
 build-all: build
 
 # Run in development mode with hot reload
-dev: ensure-ch-binaries ensure-caddy-binaries lib/system/exec_agent/exec-agent $(AIR)
+dev: ensure-ch-binaries ensure-caddy-binaries lib/system/guest_agent/guest-agent $(AIR)
 	@rm -f ./tmp/main
 	$(AIR) -c .air.toml
 
 # Run tests (as root for network capabilities, enables caching and parallelism)
 # Usage: make test                              - runs all tests
 #        make test TEST=TestCreateInstanceWithNetwork  - runs specific test
-test: ensure-ch-binaries ensure-caddy-binaries lib/system/exec_agent/exec-agent
+test: ensure-ch-binaries ensure-caddy-binaries lib/system/guest_agent/guest-agent
 	@if [ -n "$(TEST)" ]; then \
 		echo "Running specific test: $(TEST)"; \
 		sudo env "PATH=$$PATH" "DOCKER_CONFIG=$${DOCKER_CONFIG:-$$HOME/.docker}" go test -tags containers_image_openpgp -run=$(TEST) -v -timeout=180s ./...; \
@@ -194,9 +202,9 @@ clean:
 	rm -rf $(BIN_DIR)
 	rm -rf lib/vmm/binaries/cloud-hypervisor/
 	rm -rf lib/ingress/binaries/
-	rm -f lib/system/exec_agent/exec-agent
+	rm -f lib/system/guest_agent/guest-agent
 
 # Prepare for release build (called by GoReleaser)
 # Downloads all embedded binaries and builds embedded components
-release-prep: download-ch-binaries build-caddy-binaries lib/system/exec_agent/exec-agent
+release-prep: download-ch-binaries build-caddy-binaries lib/system/guest_agent/guest-agent
 	go mod tidy