v1.0.4

# 🚀 Announcing Agent Sandbox v1.0.4!

We're excited to announce the release of **Agent Sandbox v1.0.4**! This release brings significant improvements across the board, including Kubernetes lifecycle event reporting for Sandboxes, streaming file download capabilities across SDKs, async `sandboxd` runtime support in Python, automatic sandbox expiration in TypeScript, enhanced concurrency isolation in the RL SDK, and numerous stability, security, and documentation enhancements.

### Key Highlights

#### Core Controller & Lifecycle Management
* **Kubernetes Lifecycle Events (#1532):** The Sandbox reconciler now emits Kubernetes Events across key lifecycle transitions, including `SandboxPodCreated`, `SandboxPodCreateFailed`, `SandboxReady`, `SandboxSuspended`, `SandboxExpired` (for `Retain` shutdown policies), `PodSucceeded`, and `PodFailed`. Events can be toggled via the new `--disable-sandbox-events` controller flag.
* **Terminal Validation for Long Service Names (#1630):** Fixed an issue where Sandboxes with derived headless Service names exceeding the 63-character DNS-1035 limit caused controller hot-looping. Permanent apiserver invalidity errors are now classified as terminal, marking the resource as `Ready=False` with reason `InvalidConfiguration` without requeuing.
* **Router Cache Invalidation Fencing (#1398):** Enhanced the sandbox-router Pod cache to track backing Pod UIDs alongside Sandbox UIDs, preventing delayed delete/NotReady events from old pods from evicting newly created replacement pods.

#### SDKs & Client Libraries
* **Streaming File Downloads (#1643):** Added streaming file download support to the Go (`ReadTo`) and Python (`read_to` / `AsyncFilesystem.read_to`) SDKs. Callers can now stream files directly into custom writers/sinks without buffering large responses in memory.
* **Python Async `sandboxd` Runtime Support (#1438, #1697):** Added full async support for `sandboxd` to `AsyncSandboxClient`, including gRPC-based process execution and REST filesystem operations over direct Pod tunnels, with hardened cleanup routines across connection failures and cancellations.
* **TypeScript SDK Expiration & Type Fixes (#1605, #1535):** Added support for `shutdownAfterSeconds` in `CreateSandboxOptions` to automatically set controller-enforced expiration deadlines. Widened the return type of `getSandboxClaimWarmpoolName()` to `Promise<string | undefined>`.
* **Resilient Python Watch Streams (#1612):** Improved watch stream reliability in `K8sHelper` and `AsyncK8sHelper` by catching transient HTTP disconnects (e.g. `ProtocolError`, `ReadTimeoutError`, `ClientConnectionError`) and reconnecting transparently while preserving tracked resource versions.
* **File Path & Sanitization Fixes (#1719, #1721, #1594):** Preserved leading, trailing, and embedded spaces in Python SDK file paths, prevented double-decoding of literal percent escapes in the Python runtime, and fixed path sanitization when sandbox roots are accessed through symlinked directory aliases.

#### Reinforcement Learning SDK (`agent-sandbox-rl`)
* **Run Isolation & Safe Concurrency (#1737):** Introduced run-scoped teardown selectors and `FleetConfig.run_isolation` modes (`"names"` and `"namespace"`), preventing concurrent training runs in shared namespaces from accidentally resizing, deleting, or stalling on each other's warm pools and templates. Added fail-fast handling on pool deletion and conditional resource writes.

#### Security & Governance
* **Hardened Command Governance Example (#1690):** Upgraded `governed_run.py` to protect against command injection, shell chaining (`;`, `&&`, `||`, `|`, `&`), command substitution (`$(...)` and backticks), GNU-style option abbreviations, and execution wrappers (`sudo`, `env`, `xargs`, `timeout`, `exec`).

#### Documentation & Tooling
* **Comprehensive Configuration & TLS Docs (#1653, #1689):** Documented all 34 controller flags in the configuration reference, published end-to-end instructions for enabling secure TLS metrics serving on port 8443, and added HTTP/2 and HTTP/1.1 ALPN negotiation support.
* **Runtime API Specification (#1645):** Published official runtime API reference documentation for `sandboxd` contracts, endpoints, and transport policies.
* **Developer Tooling & CI Enhancements (#1616, #1696, #1699, #1738, #1741):** Enforced LF line endings repository-wide via `.gitattributes`, made E2E port-forward helpers race-free, prevented duplicate flake reports for closed issues, integrated cluster-free framework tests into the unit test suite, and improved GCP kOps benchmark validation timeouts.

### 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/v1.0.4/sandbox-with-extensions.yaml
```

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

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

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

--------
### Contributors
We extend our sincere thanks to all contributors to this release:
@1fanwang, @Flandern1211, @HasonoCell, @Pepper-rice, @Sean-790761, @XixianWasTaken, @aditya-shantanu, @alanhuangch, @aojea, @dependabot, @briankhoi, @dongjiang1989, @esposem, @janetkuo, @karimad, @khirotaka, @lunarwhite, @niting, @pauldotyu, @tomergee, @vincent0426, @vvoronko, @yujunz, @yuzhiquan

### New Contributors
* @niting made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1612
* @Flandern1211 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1438
* @Sean-790761 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1630
* @pauldotyu made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1682
* @1fanwang made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1721
* @yujunz made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1594
* @XixianWasTaken made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1699

**Full Changelog**: https://github.com/kubernetes-sigs/agent-sandbox/compare/v1.0.3...v1.0.4