v1.0.5

# 🚀 Announcing Agent Sandbox v1.0.5!

We're excited to announce the release of Agent Sandbox v1.0.5! This release introduces a comprehensive runtime connectivity layer to the TypeScript SDK, native in-cluster `sandboxd` transport for Python and TypeScript clients, streaming file transfers, deterministic claim adoption, OpenAI Agents integration, new observability metrics, and high-scale controller tuning configurations in the Helm chart.

### ⚠️ Breaking Changes / Action Required
* **Deep Agents Adapter Requirements & Error Handling (#1511):** The Deep Agents adapter now requires `deepagents>=0.7.10,<0.8.0`; support for Deep Agents 0.6 has been dropped. Additionally, execution transport and response failures now propagate as native exceptions rather than synthetic `ExecuteResponse(exit_code=-1)` results. Users upgrading the adapter must update their Deep Agents dependencies and handle operational exceptions.

---

### Key Highlights

#### TypeScript SDK Runtime Layer & Enhancements
* **`sandboxd` Runtime Execution & Filesystem Layer (#1759, #1596):** Added full runtime connectivity to `Sandbox` handles, enabling command execution via gRPC (`sandbox.commands.run()`), filesystem operations (`read`, `write`, `exists`, `list`, `delete`), and health/metadata endpoints (`sandbox.health()`, `sandbox.metadata()`).
* **Streaming File Transfers (#1759):** Added `sandbox.files.readStream()` and `sandbox.files.writeStream()` to transfer large files without buffering entire payloads into client memory.
* **Direct In-Cluster Connectivity (#1759):** Added support for direct in-cluster transport modes (`in-cluster-service` and `in-cluster-pod-ip`) alongside the standard port-forward transport.
* **Label Selectors & Pod Metadata (#1606, #1778):** Added `labelSelector` support to `SandboxClient.listAllSandboxes` and added `podLabels` and `podAnnotations` options to `createSandbox`.
* **Standardized Error Handling (#1766, #1779):** Converted validation and timeout errors across the SDK to consistently throw `SandboxError`, and treated `InvalidConfiguration` as a terminal claim ready condition to fail fast instead of waiting out the timeout.

#### Python SDK & Framework Integrations
* **Direct In-Cluster `sandboxd` Transport (#1750):** Added `SandboxdInClusterConnectionConfig` to connect directly to sandboxd via Service DNS or Pod IP without requiring local port-forwards.
* **Streaming File Uploads (#1634):** `Filesystem.write` and `AsyncFilesystem.write` now accept binary file objects and stream uploads in chunks without memory buffering.
* **Deterministic Claim Creation & Adoption (#1573):** Added `claim_name` and `adopt_existing` parameters to `create_sandbox` across sync and async clients, enabling durable workflows to safely adopt existing claims on retry.
* **Safe Sandbox Lookup (#1770):** Fixed an issue where transient lookup failures during `get_sandbox()` could inadvertently delete active SandboxClaims and running sandboxes.
* **OpenAI Agents SDK Integration (#1388):** Added dedicated integration package (`clients/integrations/openai`) allowing OpenAI Agents to run seamlessly inside Agent Sandbox with workspace hydration and session resumption.
* **Fast Failure on Invalid Configuration (#1747):** Added `InvalidConfiguration` to `TERMINAL_CLAIM_READY_REASONS` to fail fast when unrecoverable child-resource validation errors occur.
* **Local Tunnel Concurrency & Diagnosis (#1683, #1132):** Protected tunnel connections with an re-entrant lock to prevent port-forward leaks under concurrent first requests, and included namespace context in router error messages.

#### Core Controller, Extensions & Observability
* **High-Scale Controller Tuning Flags (#1794):** Exposed high-scale controller flags (including `--api-connections`, `--cache-label-selectors`, `--sandbox-write-behind-window`, `--sandbox-warm-pool-replenish-delay`, and event suppression flags) as first-class parameters under `controller.*` in the Helm chart.
* **Warm Pool Size Gauge Metric (#1774):** Added the `agent_sandbox_warmpool_size` Prometheus gauge metric reporting warm pool capacity partitioned by namespace, pool name, sandbox template, and sandbox readiness state.
* **Warm Pool Template Printer Column (#1790):** Added a `Template` column to the `SandboxWarmPool` CRD for enhanced visibility when running `kubectl get sandboxwarmpools`.
* **Controller Cache-Lag Backoff (#1768):** Implemented geometric requeue backoff (capped at 5s) for the SandboxClaim controller during informer cache lag races.
* **Mirrored PodScheduled Scheduling Optimization (#1439):** Refactored warm pool unschedulable detection to read mirrored `PodScheduled` conditions from `Sandbox.status` rather than issuing Pod `GET` calls.
* **Router Cache Consistency (#1757):** Fixed cache eviction logic in `sandbox-router` to cleanly remove stale or un-identified Pod entries on deletion and not-ready events.
* **Go SDK Ready Waiter (#1760):** Added `K8sHelper.WaitForSandboxReady` to wait for a Sandbox's Ready condition with context deadlines and cancellation.
* **Go Fake Clientset Improvements (#795):** Generated Server-Side Apply configurations and `NewClientset` constructors for fake Kubernetes clientsets.
* **Toolchain & Dependency Upgrades (#1733, #1786):** Upgraded all Go builder images and toolchains to Go 1.27.1, and bumped Kubernetes dependencies to v0.37.1 and controller-runtime to v0.25.1.

#### Examples & Ecosystem
* **Reinforcement Learning Scoping Fixes (#1811):** Assigned run IDs to pods under non-reserved labels (`agent-sandbox-rl/run-id`) and prevented on-demand runs from relabeling templates owned by other runs.
* **Ray RLlib PPO Integration (#1684):** Added an end-to-end RLlib PPO training example demonstrating environment interaction with `SandboxEnv`.
* **WebMCP-to-MCP Bridge (#1754):** Added an example using Playwright to bridge browser-registered WebMCP tools to MCP inside a Sandbox.
* **NemoClaw & OpenShell Example (#1501):** Added an example showcasing NemoClaw running inside an Agent Sandbox using OpenShell.
* **urunc Unikernel Runtime Example (#1709):** Added an example demonstrating sandboxes running as microVMs using the urunc OCI runtime.
* **Tilt Development Workflow (#1720):** Added a development guide for running and testing Agent Sandbox applications with Tilt.
* **IRSA Simulation Hardening (#1579):** Added a cryptographic STS trust verifier proxy to the LocalStack IRSA simulation example.
* **Python Runtime Shell Execution (#1765):** Updated `/execute` in `examples/python-runtime-sandbox` to execute commands under a shell, enabling chaining and I/O redirection.

---

### 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.5/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.5/sandbox.yaml

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

#### Python SDK
```bash
pip install k8s-agent-sandbox==1.0.5.post1
```
(Note that ==1.0.5 won't match it; use ~=1.0.5, >=1.0.5, or ==1.0.5.post1.)

--------
### Contributors
We extend our sincere thanks to all contributors to this release:
@1fanwang, @ArthurKamalov, @HasonoCell, @Karthik-Chowdary, @LucasGois1, @Pepper-rice, @Sean-790761, @YoungJinJung, @abhayjoshi201, @aditya-shantanu, @adityajoshi12, @dependabot, @chansuke, @cmainas, @drogovozDP, @ericcurtin, @felixmr1, @igooch, @james-westbrook, @janetkuo, @karimad, @khirotaka, @lunarwhite, @noeljackson, @tomergee, @vincent0426, @yuzhiquan

### New Contributors
* @chansuke made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1746
* @adityajoshi12 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1132
* @LucasGois1 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1573
* @james-westbrook made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1720
* @abhayjoshi201 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1757
* @felixmr1 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1760
* @Karthik-Chowdary made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1764
* @cmainas made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1709
* @ericcurtin made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1765
* @YoungJinJung made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1781

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