Skip to content

Commit 7ee14e1

Browse files
committed
feat(agents): mount an opt-in sub-agent token for orchestrating sessions
With pod_options.subagent_token, the provider adds a projected, 600-second ServiceAccount token (plus cluster CA and namespace) at /var/run/secrets/buzz-subagents, so an orchestrating agent can claim short-lived worker Sandboxes. The ambient ServiceAccount token stays off, the option is off by default, and enabling it changes the launch intent. The deployment scopes the token to SandboxClaims in the developer namespace. Signed-off-by: Tee8z <[email protected]>
1 parent 13fc30b commit 7ee14e1

4 files changed

Lines changed: 201 additions & 17 deletions

File tree

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

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,13 @@ pub struct PodOptions {
9292
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
9393
/// Expose the server-assigned Pod UID to a bounded owner setup gate.
9494
pub setup_pending: bool,
95+
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
96+
/// Mount a short-lived ServiceAccount token so an orchestrating agent can
97+
/// claim sub-agent Sandboxes (§Sub-agents). Off by default.
98+
pub enable_subagents: bool,
99+
#[serde(default, skip_serializing_if = "Option::is_none")]
100+
/// Optional priority class, also usable by namespace-scoped resource quotas.
101+
pub priority_class_name: Option<String>,
95102
}
96103

97104
impl PodOptions {
@@ -316,7 +323,9 @@ pub fn config_schema() -> serde_json::Value {
316323
"ephemeral_storage_request": {"type": "string", "minLength": 1},
317324
"ephemeral_storage_limit": {"type": "string", "minLength": 1},
318325
"active_deadline_seconds": {"type": "integer", "minimum": 1},
319-
"setup_pending": {"type": "boolean", "default": false}
326+
"setup_pending": {"type": "boolean", "default": false},
327+
"enable_subagents": {"type": "boolean", "default": false},
328+
"priority_class_name": {"type": "string"}
320329
}
321330
},
322331
"service_account": {

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

Lines changed: 145 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,67 @@ use crate::naming::{
1212
AgentIdentity, ANNOTATION_CREATE_INTENT, ANNOTATION_IMAGE, ANNOTATION_PUBKEY_FULL,
1313
};
1414
use k8s_openapi::api::core::v1::{
15-
Capabilities, Container, EmptyDirVolumeSource, EnvFromSource, EnvVar, EnvVarSource,
16-
ObjectFieldSelector, Pod, PodSecurityContext, PodSpec, ResourceRequirements, SeccompProfile,
17-
Secret, SecretEnvSource, SecurityContext, Volume, VolumeMount,
15+
Capabilities, ConfigMapProjection, Container, DownwardAPIProjection, DownwardAPIVolumeFile,
16+
EmptyDirVolumeSource, EnvFromSource, EnvVar, EnvVarSource, KeyToPath, ObjectFieldSelector, Pod,
17+
PodSecurityContext, PodSpec, ProjectedVolumeSource, ResourceRequirements, SeccompProfile,
18+
Secret, SecretEnvSource, SecurityContext, ServiceAccountTokenProjection, Volume, VolumeMount,
19+
VolumeProjection,
1820
};
21+
22+
/// Where an orchestrating agent finds its sub-agent credentials (§Sub-agents):
23+
/// `token`, `ca.crt`, and `namespace`. Deliberately not the default
24+
/// ServiceAccount path, so tools do not pick the token up implicitly.
25+
pub const SUBAGENT_TOKEN_PATH: &str = "/var/run/secrets/buzz-subagents";
26+
/// Lifetime of the projected token; the kubelet rotates it before expiry.
27+
pub const SUBAGENT_TOKEN_SECONDS: i64 = 600;
28+
const SUBAGENT_TOKEN_VOLUME: &str = "subagent-token";
29+
30+
/// Short-lived API credentials for claiming sub-agent Sandboxes. RBAC in the
31+
/// developer namespace limits the token to SandboxClaims there.
32+
fn subagent_token_volume() -> Volume {
33+
Volume {
34+
name: SUBAGENT_TOKEN_VOLUME.to_string(),
35+
projected: Some(ProjectedVolumeSource {
36+
sources: Some(vec![
37+
VolumeProjection {
38+
service_account_token: Some(ServiceAccountTokenProjection {
39+
path: "token".to_string(),
40+
expiration_seconds: Some(SUBAGENT_TOKEN_SECONDS),
41+
..Default::default()
42+
}),
43+
..Default::default()
44+
},
45+
VolumeProjection {
46+
config_map: Some(ConfigMapProjection {
47+
name: "kube-root-ca.crt".to_string(),
48+
items: Some(vec![KeyToPath {
49+
key: "ca.crt".to_string(),
50+
path: "ca.crt".to_string(),
51+
..Default::default()
52+
}]),
53+
..Default::default()
54+
}),
55+
..Default::default()
56+
},
57+
VolumeProjection {
58+
downward_api: Some(DownwardAPIProjection {
59+
items: Some(vec![DownwardAPIVolumeFile {
60+
path: "namespace".to_string(),
61+
field_ref: Some(ObjectFieldSelector {
62+
field_path: "metadata.namespace".to_string(),
63+
..Default::default()
64+
}),
65+
..Default::default()
66+
}]),
67+
}),
68+
..Default::default()
69+
},
70+
]),
71+
..Default::default()
72+
}),
73+
..Default::default()
74+
}
75+
}
1976
use k8s_openapi::apimachinery::pkg::api::resource::Quantity;
2077
use k8s_openapi::apimachinery::pkg::apis::meta::v1::ObjectMeta;
2178
use std::collections::BTreeMap;
@@ -144,11 +201,22 @@ pub fn build_pod(
144201
limits: Some(limits),
145202
..Default::default()
146203
}),
147-
volume_mounts: Some(vec![VolumeMount {
148-
name: WORKSPACE_VOLUME.to_string(),
149-
mount_path: WORKSPACE_PATH.to_string(),
150-
..Default::default()
151-
}]),
204+
volume_mounts: Some({
205+
let mut mounts = vec![VolumeMount {
206+
name: WORKSPACE_VOLUME.to_string(),
207+
mount_path: WORKSPACE_PATH.to_string(),
208+
..Default::default()
209+
}];
210+
if cfg.pod_options.enable_subagents {
211+
mounts.push(VolumeMount {
212+
name: SUBAGENT_TOKEN_VOLUME.to_string(),
213+
mount_path: SUBAGENT_TOKEN_PATH.to_string(),
214+
read_only: Some(true),
215+
..Default::default()
216+
});
217+
}
218+
mounts
219+
}),
152220
security_context: Some(SecurityContext {
153221
allow_privilege_escalation: Some(false),
154222
capabilities: Some(Capabilities {
@@ -177,6 +245,7 @@ pub fn build_pod(
177245
tolerations: (!cfg.pod_options.tolerations.is_empty())
178246
.then(|| cfg.pod_options.tolerations.clone()),
179247
active_deadline_seconds: cfg.pod_options.active_deadline_seconds,
248+
priority_class_name: cfg.pod_options.priority_class_name.clone(),
180249
restart_policy: Some(RESTART_POLICY.to_string()),
181250
termination_grace_period_seconds: Some(TERMINATION_GRACE_SECONDS),
182251
// The agent runs prompted, untrusted code while holding an nsec;
@@ -197,14 +266,20 @@ pub fn build_pod(
197266
}),
198267
..Default::default()
199268
}),
200-
volumes: Some(vec![Volume {
201-
name: WORKSPACE_VOLUME.to_string(),
202-
empty_dir: Some(EmptyDirVolumeSource {
203-
size_limit: cfg.pod_options.workspace_size_limit.clone().map(Quantity),
269+
volumes: Some({
270+
let mut volumes = vec![Volume {
271+
name: WORKSPACE_VOLUME.to_string(),
272+
empty_dir: Some(EmptyDirVolumeSource {
273+
size_limit: cfg.pod_options.workspace_size_limit.clone().map(Quantity),
274+
..Default::default()
275+
}),
204276
..Default::default()
205-
}),
206-
..Default::default()
207-
}]),
277+
}];
278+
if cfg.pod_options.enable_subagents {
279+
volumes.push(subagent_token_volume());
280+
}
281+
volumes
282+
}),
208283
..Default::default()
209284
}),
210285
..Default::default()
@@ -376,6 +451,42 @@ mod tests {
376451
);
377452
}
378453

454+
#[test]
455+
fn subagent_token_is_opt_in_short_lived_and_off_the_default_path() {
456+
let mut cfg = provider_config();
457+
let fp = intent_template(&cfg, ["A".into()]).fingerprint();
458+
let plain = build_pod(&identity(), &cfg, "g", &fp);
459+
assert_eq!(spec(&plain).volumes.as_ref().unwrap().len(), 1);
460+
assert_eq!(
461+
spec(&plain).containers[0]
462+
.volume_mounts
463+
.as_ref()
464+
.unwrap()
465+
.len(),
466+
1
467+
);
468+
469+
cfg.pod_options.enable_subagents = true;
470+
let changed = intent_template(&cfg, ["A".into()]).fingerprint();
471+
let pod = build_pod(&identity(), &cfg, "g", &changed);
472+
let spec = spec(&pod);
473+
// Still no ambient token at the default ServiceAccount path.
474+
assert_eq!(spec.automount_service_account_token, Some(false));
475+
let volume = &spec.volumes.as_ref().unwrap()[1];
476+
let sources = volume.projected.as_ref().unwrap().sources.as_ref().unwrap();
477+
let token = sources[0].service_account_token.as_ref().unwrap();
478+
assert_eq!(token.expiration_seconds, Some(SUBAGENT_TOKEN_SECONDS));
479+
assert!(token.audience.is_none());
480+
let mount = &spec.containers[0].volume_mounts.as_ref().unwrap()[1];
481+
assert_eq!(mount.name, volume.name);
482+
assert_eq!(mount.mount_path, SUBAGENT_TOKEN_PATH);
483+
assert_eq!(mount.read_only, Some(true));
484+
assert_ne!(
485+
SUBAGENT_TOKEN_PATH,
486+
"/var/run/secrets/kubernetes.io/serviceaccount"
487+
);
488+
}
489+
379490
#[test]
380491
fn each_optional_pod_control_changes_intent() {
381492
let cfg = provider_config();
@@ -388,6 +499,8 @@ mod tests {
388499
serde_json::json!({"ephemeral_storage_limit": "4Gi"}),
389500
serde_json::json!({"active_deadline_seconds": 28800}),
390501
serde_json::json!({"setup_pending": true}),
502+
serde_json::json!({"enable_subagents": true}),
503+
serde_json::json!({"priority_class_name": "agent-session"}),
391504
] {
392505
let mut changed = cfg.clone();
393506
changed.pod_options = serde_json::from_value(value).unwrap();
@@ -400,6 +513,23 @@ mod tests {
400513
assert!(original.get("pod_options").is_none());
401514
}
402515

516+
#[test]
517+
fn priority_class_reaches_the_pod_without_changing_default_intent() {
518+
let mut cfg = provider_config();
519+
assert!(serde_json::to_value(&cfg.pod_options)
520+
.unwrap()
521+
.get("priority_class_name")
522+
.is_none());
523+
cfg.pod_options.priority_class_name = Some("agent-session".into());
524+
let identity = identity();
525+
let fingerprint = intent_template(&cfg, ["A".into()]).fingerprint();
526+
let pod = build_pod(&identity, &cfg, "generation", &fingerprint);
527+
assert_eq!(
528+
pod.spec.unwrap().priority_class_name.as_deref(),
529+
Some("agent-session")
530+
);
531+
}
532+
403533
#[test]
404534
fn optional_placement_storage_and_lifetime_reach_pod_and_intent() {
405535
let mut cfg = provider_config();

‎desktop/src-tauri/src/managed_agents/backend_tests.rs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -516,6 +516,24 @@ esac"#,
516516
assert!(error.contains("[REDACTED]"), "{error}");
517517
}
518518

519+
#[test]
520+
fn subagent_capability_is_public_but_credentials_still_fail() {
521+
for enabled in [true, false] {
522+
assert!(
523+
validate_provider_config(&serde_json::json!({"pod_options": {
524+
"enable_subagents": enabled, "priority_class_name": "agent-session"
525+
}}))
526+
.is_ok()
527+
);
528+
}
529+
for credential in [
530+
serde_json::json!({"access_token":"secret"}),
531+
serde_json::json!({"api_key":"secret"}),
532+
] {
533+
assert!(validate_provider_config(&serde_json::json!({"pod_options":credential})).is_err());
534+
}
535+
}
536+
519537
#[test]
520538
fn validate_provider_config_rejects_secret_key() {
521539
let cfg = serde_json::json!({"api_key": "val"});

‎docs/remote-agents.md‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1429,7 +1429,8 @@ removable with `kubectl delete`.
14291429
`cpu_limit`, `memory_limit`, `inactivity_seconds`, `service_account`.
14301430
The optional `pod_options` object adds `node_selector`, `tolerations`,
14311431
`workspace_size_limit`, `ephemeral_storage_request`, `ephemeral_storage_limit`,
1432-
`active_deadline_seconds`, and `setup_pending`.
1432+
`active_deadline_seconds`, `setup_pending`, `enable_subagents`, and `priority_class_name`.
1433+
Staging uses separate priority classes to enforce five primary sessions independently of worker slots; configure the class from the Terraform output.
14331434
Configured options participate in the create-intent fingerprint; omitted options preserve existing behavior.
14341435
Unknown options, nonpositive deadlines, and blank storage quantities are rejected.
14351436
Kubernetes validates scheduling fields and quantity syntax.
@@ -1633,6 +1634,32 @@ restart restarts the 60s lost grace and the 24h hold, which only delays a
16331634
tombstone. A receipt from a Pod that was deleted while the reaper was not
16341635
running is lost, and that session is recorded with `checkpoint=missing`.
16351636

1637+
### Sub-agents
1638+
1639+
An orchestrating agent can delegate focused work to short-lived worker
1640+
Sandboxes, so one long task does not block the others. Workers are headless:
1641+
each receives a focus, a repository, and a base branch, runs a model runtime
1642+
non-interactively, pushes its own branch, records a result, and exits. They have
1643+
no Buzz identity; the orchestrator reports their results in its thread.
1644+
1645+
With `provider_config.pod_options.enable_subagents: true`, the Pod gets a
1646+
projected ServiceAccount token at `/var/run/secrets/buzz-subagents` (`token`,
1647+
`ca.crt`, `namespace`). The token lasts 600 seconds and the kubelet rotates it.
1648+
It is not at the default ServiceAccount path, and `automountServiceAccountToken`
1649+
stays `false`, so tools do not pick it up implicitly.
1650+
1651+
The deployment must scope that token. The reference deployment grants the
1652+
ServiceAccount only SandboxClaim create/get/list/watch/delete in the developer
1653+
namespace, admits only claims against its worker template with bounded
1654+
lifetimes, and caps the claim count with a quota. A stolen token can therefore
1655+
start a bounded number of workers with the same developer's credentials that
1656+
the agent already holds.
1657+
1658+
Worker Sandboxes are created by the Agent Sandbox claim controller and do not
1659+
carry the `app.kubernetes.io/managed-by` or binding-version labels, so the
1660+
sandbox reaper never touches them; their claims expire through
1661+
`ttlSecondsAfterFinished` and `shutdownTime`.
1662+
16361663
### Distribution
16371664

16381665
Its own release workflow (macOS arm64/x64 + Linux musl; the sprig workflow's

0 commit comments

Comments
 (0)