v0.5.6

# 🚀 Announcing Agent Sandbox v0.5.6!

We're excited to announce the release of Agent Sandbox v0.5.6! This release brings significant improvements to controller reliability, warm pool lifecycle management, and race condition handling. It also introduces backing pod scheduling condition mirroring, Prometheus Operator monitoring resources in the Helm chart, filesystem tools in the MCP server, suspend/resume latency metrics in the Python SDK, and new examples for Pi coding agent, E2B envd daemon, and n8n orchestration.

### Key Highlights

#### Core Controller & Warm Pool Lifecycle
* **Strict Sandbox-to-Pod Mapping (#1337):** Enforced controller owner reference UIDs as the authoritative Sandbox-to-Pod mapping, preventing duplicate pod creation when pod-name annotations are missing or stale. If multiple owned pods exist, reconciliation safely fails closed with `Ready=False` (reason `MultiplePods`) and emits a warning event.
* **Warm Pool Stale Sandbox Adoption Prevention (#1078):** Fixed a race condition where `SandboxClaim` could adopt stale template pods under the `Recreate` update strategy by enforcing semantic blueprint and content hash checks on candidate adoption.
* **Transient Pod Networking Adoption Gate (#683):** Added bounded wait and requeue logic to `SandboxClaim` to ensure rotating warm-pool candidates report pod networking before adopting them or falling back to cold creation.
* **Informers Cache Lag Resilience (#1072):** Added bounded 200ms requeuing and the `SandboxCreatePending` condition when `createSandbox` encounters transient `AlreadyExists` errors due to informer cache lag, preventing workqueue churn and status wipes.
* **Warm Pool `observedGeneration` (#1328):** Added `status.observedGeneration` to `SandboxWarmPool` to allow clients and GitOps tooling to reliably detect when the controller has finished processing spec updates.
* **Configurable Readiness Grace Period and Recheck Cadence (#1290):** Added `--sandbox-warm-pool-readiness-grace-period` (default `5m`) and `--sandbox-warm-pool-unschedulable-recheck-interval` (default `1m`) controller flags to accommodate slower image startup times and node auto-provisioning latency.

#### API & Observability Enhancements
* **Pod Scheduling Status Mirroring (#1291):** Mirrored the backing pod's `PodScheduled` condition into `Sandbox.status.conditions` (surfacing reasons like `Unschedulable` and `SchedulingGated`), enabling diagnosis of scheduling issues without requiring pod-level RBAC.
* **Centralized API Enum Validations (#1288):** Refactored `+kubebuilder:validation:Enum` markers to type definitions across `SandboxOperatingMode`, `NetworkPolicyManagement`, `EnvVarsInjectionPolicy`, and `VolumeClaimTemplatesPolicy` for strict CRD validation.
* **API Documentation & Defaults Clarification (#1106):** Clarified doc comments regarding desired operating mode vs. observed readiness conditions, environment variable injection cold-start behaviors, and status field clearance during suspension.

#### SDKs & MCP Tooling
* **MCP Filesystem Parity Tools (#1329):** Added `list_files` and `file_exists` tools to the Agent Sandbox MCP server with token-budget bounding and isolation checks, aligning capabilities with the Go and Python SDKs.
* **Python SDK Suspend/Resume Telemetry (#1143):** Added Prometheus histogram metrics (`sandbox_client_suspend_latency_ms`, `sandbox_client_resume_latency_ms`, `sandbox_client_restore_latency_ms`) to benchmark snapshot and restore lifecycle operations.
* **Optional Warm Pool Option in Go SDK (#1179):** Relaxed `sandbox.NewClient` validation so `Options.WarmPoolName` is only required when actively provisioning a claim via `CreateSandbox` or `Open()`.
* **Reinforcement Learning Harness Robustness (#1314):** Added deep container spec merging to preserve custom images/specs when injecting volumes and environment variables, defensive exec stream handling, and concurrent batch fleet cleanup.

#### Helm & Deployment Operations
* **Opt-in Prometheus Operator Resources (#1355, #1017):** Added Helm support for deploying an opt-in `ServiceMonitor` to scrape the `/metrics` endpoint and a starter `PrometheusRule` alert (`AgentSandboxControllerMetricsTargetsDown`).
* **Helm Image Pull Secrets (#1370):** Added support for configuring `imagePullSecrets` on the controller deployment via Helm values.
* **Podman Deployment Support (#1152):** Added support for deploying local kind clusters using Podman (`CONTAINER_ENGINE=podman make deploy-kind`).

#### Ecosystem Examples & Workloads
* **Pi Coding Agent Example (#1373):** Added a sandbox example running the terminal-based Pi coding agent with interactive TUI attach and persistent workspace storage.
* **E2B envd Sandbox Example (#1302):** Added an example demonstrating E2B's `envd` daemon running inside a sandbox container, complete with REST/gRPC API support and verification clients across Python, Go, TypeScript, and Bash.
* **n8n Workflow Integration Example (#1345):** Added an integration example for managing sandbox lifecycles and tool executions directly from n8n workflows.
* **Python Runtime Non-Blocking Execution (#1380, #1025):** Offloaded `/execute` handler subprocess execution from the FastAPI event loop and added `SANDBOX_EXEC_TIMEOUT_SECONDS` (default 300s) to prevent commands from wedging sandbox health checks.
* **Example Documentation Coverage (#1372):** Published documentation website entries for 18 previously undocumented example architectures and integration patterns.

### Installation

#### Standard Install (Core + Extensions)
Recommended for most users and GitOps engines (Argo CD, Config Sync, kustomize):
```bash
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.6/sandbox-with-extensions.yaml
```

#### Selective Install
Install components separately:
```bash
# Core only:
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.6/sandbox.yaml

# Extensions (opt-in):
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.6/extensions.yaml
```

#### Python SDK
```bash
pip install k8s-agent-sandbox==0.5.6
```

--------
### Contributors
We extend our sincere thanks to all contributors to this release:
@Ryotess, @aditya-shantanu, @aegeiger, @akvnn, @alanhuangch, @dependabot, @chw120, @dongjiang1989, @drogovozDP, @esposem, @hchenxa, @janetkuo, @jensvandenreyt, @lunarwhite, @ngopalak-redhat, @noeljackson, @prash2512, @pujitha24, @shrutiyam-glitch, @tom1299, @yingjun8, @yuzhiquan

### New Contributors
* @yuzhiquan made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1290
* @pujitha24 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1380
* @Ryotess made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1025
* @alanhuangch made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1337
* @yingjun8 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1106
* @jensvandenreyt made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1370

**Full Changelog**: https://github.com/kubernetes-sigs/agent-sandbox/compare/v0.5.5...v0.5.6