Skip to content

Commit df6a2b2

Browse files
committed
feat(backend-kubernetes): launch thread-bound Agent Sandbox sessions
Add an opt-in sandbox mode that creates one agents.x-k8s.io/v1beta1 Sandbox per agent, channel, and canonical thread root. A matching running Sandbox is reused; a changed, replaced, or completed one requires explicit recovery instead of a silent empty replacement. The provider requires the identity policy and an absolute Pod deadline, binds the launch Secret to the first Pod UID, configures the harness for owner-only bound thread sessions with activity logging, and supports Codex device account setup. Sandbox Pods use the bare-Pod termination grace, which covers the drain and the stop checkpoint. Because the workspace does not outlive the Pod, deploy refuses Sandbox mode unless BUZZ_CHECKPOINT_BUCKET and BUZZ_CHECKPOINT_PREFIX enable the stop checkpoint, or BUZZ_SANDBOX_CHECKPOINT=disabled opts out. The env guard now accepts the harness's strict owner respond-to mode. Signed-off-by: Tee8z <[email protected]>
1 parent cefb9aa commit df6a2b2

11 files changed

Lines changed: 1012 additions & 4 deletions

File tree

‎Cargo.lock‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎crates/buzz-acp/TESTING.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,20 @@ The image repository's `buzz-agent/test-checkpoint-storage.py` also stops the
3636
packaged harness during startup while an adapter writes files. It checks that
3737
recovery preserves the final edit and rejected uploads make shutdown fail.
3838

39+
Run the controller lifecycle test against the isolated local kind cluster:
40+
41+
```sh
42+
BUZZ_SANDBOX_TEST_KUBECONFIG=/absolute/kind.kubeconfig \
43+
BUZZ_SANDBOX_TEST_IMAGE=registry.example/uid-guard-fixture@sha256:<digest> \
44+
cargo test -p buzz-backend-kubernetes live_controller_reuses_scopes \
45+
-- --ignored --nocapture
46+
```
47+
48+
The test requires context `kind-remote-agent-check`, the Agent Sandbox controller,
49+
and a loaded fixture image that checks the Pod UID binding before sleeping.
50+
It verifies concurrent reuse, separate threads, owner and relay refusals, and
51+
refusal after the original Pod is replaced. It does not enroll real accounts.
52+
3953
Managed agent sessions may already export harness options. Clear them when
4054
running the package suite: three CLI parsing tests assert the unset defaults,
4155
and inherited values would change the inputs those tests exercise. Running the

‎crates/buzz-backend-kubernetes/Cargo.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ sha2 = { workspace = true }
2222
hex = { workspace = true }
2323
rand = { workspace = true }
2424
chrono = { workspace = true }
25+
uuid = { workspace = true }
2526
http = "1"
2627
http-body-util = "0.1"
2728

‎crates/buzz-backend-kubernetes/src/config.rs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -416,6 +416,28 @@ pub fn config_schema() -> serde_json::Value {
416416
"title": "Service account",
417417
"description": "Scheduling/RBAC identity only. No API token is mounted."
418418
},
419+
"sandbox": {
420+
"oneOf": [
421+
{"const": false},
422+
{
423+
"type": "object",
424+
"additionalProperties": false,
425+
"required": ["channel_id", "thread_root"],
426+
"properties": {
427+
"channel_id": {
428+
"type": "string",
429+
"format": "uuid",
430+
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
431+
},
432+
"thread_root": {"type": "string", "pattern": "^[0-9a-f]{64}$"}
433+
}
434+
}
435+
],
436+
"x-buzz-ui-type": "boolean",
437+
"default": false,
438+
"title": "Workspace per thread",
439+
"description": "Use Agent Sandbox. Mention the agent in a channel to create or reuse that thread's workspace. Requires an absolute Pod deadline and BUZZ_CHECKPOINT_BUCKET/BUZZ_CHECKPOINT_PREFIX (or BUZZ_SANDBOX_CHECKPOINT=disabled) in the agent environment. Desktop stores a boolean setting and binds the mentioned thread at launch; deploy accepts only {\"channel_id\": \"<UUID>\", \"thread_root\": \"<event ID>\"} and refuses true. false or absent disables Sandbox."
440+
},
419441
"identity_policy": {
420442
"type": "object",
421443
"description": "Optional approved agent and owner public keys, cryptographically checked before cluster access. Also enables local --check-identity preflight.",
@@ -806,6 +828,7 @@ mod tests {
806828
"memory_request",
807829
"namespace",
808830
"pod_options",
831+
"sandbox",
809832
"service_account"
810833
]
811834
);

‎crates/buzz-backend-kubernetes/src/env.rs‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,13 @@ const RESPOND_TO_ALLOWLIST: &str = "allowlist";
9393
/// rejects `nobody` on purpose (`managed_agents/types.rs:871-880`), but the
9494
/// harness starts fine with it. This guard exists to cover non-desktop callers,
9595
/// so inheriting a desktop-only narrowing would refuse a launch that works.
96-
const RESPOND_TO_MODES: [&str; 4] = ["owner-only", RESPOND_TO_ALLOWLIST, "anyone", "nobody"];
96+
const RESPOND_TO_MODES: [&str; 5] = [
97+
"owner-only",
98+
"owner",
99+
RESPOND_TO_ALLOWLIST,
100+
"anyone",
101+
"nobody",
102+
];
97103

98104
/// Refuse a respond-to gate the harness will reject at config parse.
99105
///
@@ -804,7 +810,7 @@ mod tests {
804810
/// for. Without this test, refusing `nobody` would pass everything above.
805811
#[test]
806812
fn every_mode_the_harness_accepts_is_deployable() {
807-
for mode in ["owner-only", "allowlist", "anyone", "nobody"] {
813+
for mode in ["owner-only", "owner", "allowlist", "anyone", "nobody"] {
808814
let agent = payload_json(serde_json::json!({
809815
"respond_to": mode,
810816
"respond_to_allowlist": [pubkey('a')],

‎crates/buzz-backend-kubernetes/src/main.rs‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ mod naming;
2121
mod observe;
2222
mod pod;
2323
mod reconcile;
24+
mod sandbox;
2425
mod wire;
2526

2627
use std::io::Read;
@@ -135,9 +136,10 @@ fn refuse_relay_mesh(raw: &serde_json::Value) -> Option<String> {
135136
/// Run one deploy to a terminal outcome.
136137
async fn deploy_agent(request: &wire::DeployRequest) -> Result<String, String> {
137138
let cfg = config::parse(&request.provider_config)?;
139+
let sandbox = sandbox::Options::parse(&request.provider_config)?;
138140
// Identity before any cluster contact: a malformed nsec is a refusal, not
139141
// a failed connection (§Deploy State Machine step 0).
140-
let identity = identity::check(request, false)?;
142+
let identity = identity::check(request, sandbox.is_some())?;
141143

142144
// One generation for this operation's first attempt; the reconciler mints
143145
// its own per attempt and restamps the correlator to match.
@@ -150,6 +152,15 @@ async fn deploy_agent(request: &wire::DeployRequest) -> Result<String, String> {
150152
)?;
151153

152154
let client = client::connect(cfg.context.as_deref()).await?;
155+
if let Some(scope) = sandbox {
156+
let owner = request
157+
.agent
158+
.launch
159+
.as_ref()
160+
.and_then(|launch| launch.owner_pubkey.as_deref())
161+
.ok_or("Sandbox requires a verified launch owner")?;
162+
return sandbox::deploy(client, &identity, &cfg, &scope, owner, env).await;
163+
}
153164
let substrate = cluster::Cluster::new(client, &cfg.namespace);
154165
reconcile::deploy(&substrate, &identity, &cfg, env).await
155166
}

0 commit comments

Comments
 (0)