1use crate::development::{DevelopmentError, DevelopmentResult};
4use crate::pi_runtime::{GlassPiRuntime, PiRuntimeOptions, PiSessionRequest, PiToolExecutor};
5use serde::{Deserialize, Serialize};
6use serde_json::Value;
7use std::collections::{BTreeMap, BTreeSet, VecDeque};
8use std::path::{Path, PathBuf};
9use std::sync::Arc;
10use std::sync::atomic::{AtomicU64, Ordering};
11use std::sync::mpsc::{self, Receiver, SyncSender, TryRecvError, TrySendError};
12use std::thread;
13use std::time::{Duration, SystemTime, UNIX_EPOCH};
14
15const COMMAND_CAPACITY: usize = 32;
16const EVENT_CAPACITY: usize = 256;
17const HISTORY_CAPACITY: usize = 512;
18const AGENT_EVIDENCE_CAPACITY: usize = 64;
19const MAX_AGENTS: usize = 32;
20const MAX_PROMPT_BYTES: usize = 64 * 1024;
21
22#[derive(Debug, Clone)]
23pub struct ResidentAgentBroker {
24 pub socket: PathBuf,
25 pub token: String,
26 pub workspace_id: String,
27}
28
29#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
30pub struct AgentId(String);
31
32impl AgentId {
33 pub fn as_str(&self) -> &str {
34 &self.0
35 }
36
37 pub fn parse(value: impl Into<String>) -> DevelopmentResult<Self> {
38 let value = value.into();
39 if !value.starts_with("agent-")
40 || value.len() > 64
41 || value.chars().any(|character| character.is_control())
42 {
43 return Err(DevelopmentError::InvalidInput("invalid agent id".into()));
44 }
45 Ok(Self(value))
46 }
47}
48
49#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
50#[serde(rename_all = "camelCase")]
51pub enum AgentStatus {
52 Queued,
53 Starting,
54 Idle,
55 Working,
56 Waiting,
57 Completed,
58 Failed,
59 Cancelled,
60}
61
62impl AgentStatus {
63 fn terminal(self) -> bool {
64 matches!(self, Self::Completed | Self::Failed | Self::Cancelled)
65 }
66
67 pub fn label(self) -> &'static str {
69 match self {
70 Self::Queued => "queued",
71 Self::Starting => "starting",
72 Self::Idle => "idle",
73 Self::Working => "working",
74 Self::Waiting => "waiting",
75 Self::Completed => "completed",
76 Self::Failed => "failed",
77 Self::Cancelled => "cancelled",
78 }
79 }
80}
81
82#[derive(Debug, Clone, Serialize, Deserialize)]
83#[serde(rename_all = "camelCase")]
84pub struct AgentSpec {
85 pub role: String,
86 pub task: String,
87 #[serde(default)]
88 pub dependencies: Vec<AgentId>,
89 pub model: Option<String>,
90 pub thinking: Option<String>,
91 pub worktree: Option<PathBuf>,
92 #[serde(default)]
93 pub unrestricted: bool,
94 pub max_runtime_seconds: Option<u64>,
95 pub max_events: Option<u64>,
96}
97
98impl AgentSpec {
99 pub fn new(role: impl Into<String>, task: impl Into<String>) -> Self {
100 Self {
101 role: role.into(),
102 task: task.into(),
103 dependencies: Vec::new(),
104 model: None,
105 thinking: None,
106 worktree: None,
107 unrestricted: false,
108 max_runtime_seconds: Some(3_600),
109 max_events: Some(10_000),
110 }
111 }
112}
113
114#[derive(Debug, Clone, Serialize, Deserialize)]
115#[serde(rename_all = "camelCase")]
116pub struct AgentSnapshot {
117 pub id: AgentId,
118 pub role: String,
119 pub task: String,
120 pub status: AgentStatus,
121 pub dependencies: Vec<AgentId>,
122 pub model: Option<String>,
123 pub thinking: Option<String>,
124 pub worktree: PathBuf,
125 pub unrestricted: bool,
126 pub created_at_ms: u128,
127 pub started_at_ms: Option<u128>,
128 pub updated_at_ms: u128,
129 pub event_count: u64,
130 pub dropped_event_count: u64,
131 pub last_error: Option<String>,
132 pub last_response_id: Option<String>,
133 pub evidence: Vec<Value>,
134}
135
136#[derive(Debug, Clone, Serialize, Deserialize)]
137#[serde(rename_all = "camelCase")]
138pub struct AgentEvent {
139 pub sequence: u64,
140 pub agent_id: AgentId,
141 pub timestamp_ms: u128,
142 pub kind: String,
143 pub payload: Value,
144}
145
146#[derive(Debug)]
147enum WorkerCommand {
148 Request(PiSessionRequest),
149 ApproveTool { frame_id: String, approved: bool },
150 Shutdown,
151}
152
153#[derive(Debug)]
154enum WorkerEvent {
155 Ready(AgentId),
156 RequestStarted(AgentId, String, bool),
157 Pi(AgentId, Value),
158 Failed(AgentId, String),
159 Stopped(AgentId),
160}
161
162struct AgentRecord {
163 snapshot: AgentSnapshot,
164 spec: AgentSpec,
165 command: Option<SyncSender<WorkerCommand>>,
166 worker: Option<thread::JoinHandle<()>>,
167 awaiting_agent_settle: bool,
168 dropped_events: Arc<AtomicU64>,
169}
170
171struct WorkerRuntime {
172 worktree: PathBuf,
173 local_tool_executor: Option<PiToolExecutor>,
174 sessions_dir: PathBuf,
175 broker: Option<ResidentAgentBroker>,
176 additional_system_prompt: Option<String>,
177}
178
179pub struct AgentRegistry {
185 root: PathBuf,
186 sessions_dir: PathBuf,
187 records: BTreeMap<AgentId, AgentRecord>,
188 events_tx: SyncSender<WorkerEvent>,
189 events_rx: Receiver<WorkerEvent>,
190 history: VecDeque<AgentEvent>,
191 local_tool_executor: Option<PiToolExecutor>,
192 next_agent: u64,
193 next_event: u64,
194 broker: Option<ResidentAgentBroker>,
195 additional_system_prompt: Option<String>,
196 default_model: Option<String>,
197 default_thinking: Option<String>,
198}
199
200impl AgentRegistry {
201 pub fn new(root: impl AsRef<Path>) -> DevelopmentResult<Self> {
202 let root = std::fs::canonicalize(root)?;
203 let sessions_dir = root.join(".glass").join("pi-sessions");
204 let (events_tx, events_rx) = mpsc::sync_channel(EVENT_CAPACITY);
205 Ok(Self {
206 root,
207 sessions_dir,
208 records: BTreeMap::new(),
209 events_tx,
210 events_rx,
211 history: VecDeque::new(),
212 local_tool_executor: None,
213 next_agent: 1,
214 next_event: 1,
215 broker: None,
216 additional_system_prompt: None,
217 default_model: None,
218 default_thinking: None,
219 })
220 }
221
222 pub fn set_resident_broker(&mut self, broker: ResidentAgentBroker) -> DevelopmentResult<()> {
223 if !broker.socket.is_absolute()
224 || broker.socket == Path::new("/")
225 || broker.token.is_empty()
226 || broker.token.len() > 256
227 || broker.workspace_id.is_empty()
228 || broker.workspace_id.len() > 128
229 || broker
230 .workspace_id
231 .chars()
232 .any(|character| character.is_control())
233 {
234 return Err(DevelopmentError::InvalidInput(
235 "invalid resident agent broker context".into(),
236 ));
237 }
238 self.broker = Some(broker);
239 Ok(())
240 }
241 pub(crate) fn set_local_tool_executor(&mut self, executor: PiToolExecutor) {
242 self.local_tool_executor = Some(executor);
243 }
244
245 pub fn set_additional_system_prompt(
246 &mut self,
247 prompt: Option<String>,
248 ) -> DevelopmentResult<()> {
249 if prompt
250 .as_ref()
251 .is_some_and(|prompt| prompt.len() > 128 * 1024 || prompt.contains('\0'))
252 {
253 return Err(DevelopmentError::InvalidInput(
254 "agent project instructions exceed 128 KiB or contain NUL".into(),
255 ));
256 }
257 self.additional_system_prompt = prompt;
258 Ok(())
259 }
260
261 pub fn additional_system_prompt(&self) -> Option<&str> {
263 self.additional_system_prompt.as_deref()
264 }
265
266 pub fn set_defaults(
267 &mut self,
268 model: Option<String>,
269 thinking: Option<String>,
270 ) -> DevelopmentResult<()> {
271 for (label, value) in [("model", &model), ("thinking", &thinking)] {
272 if value
273 .as_ref()
274 .is_some_and(|value| value.is_empty() || value.len() > 256 || value.contains('\0'))
275 {
276 return Err(DevelopmentError::InvalidInput(format!(
277 "default agent {label} must contain 1..=256 bytes without NUL"
278 )));
279 }
280 }
281 self.default_model = model;
282 self.default_thinking = thinking;
283 Ok(())
284 }
285
286 pub fn create(&mut self, mut spec: AgentSpec) -> DevelopmentResult<AgentId> {
287 self.refresh()?;
288 if spec.model.is_none() {
289 spec.model.clone_from(&self.default_model);
290 }
291 if spec.thinking.is_none() {
292 spec.thinking.clone_from(&self.default_thinking);
293 }
294 validate_spec(&self.root, &self.records, &spec)?;
295 if self.records.len() >= MAX_AGENTS {
296 return Err(DevelopmentError::Conflict(format!(
297 "agent registry reached its {MAX_AGENTS} session limit"
298 )));
299 }
300 let id = AgentId(format!("agent-{:04}", self.next_agent));
301 self.next_agent = self
302 .next_agent
303 .checked_add(1)
304 .ok_or_else(|| DevelopmentError::Conflict("agent identifier space exhausted".into()))?;
305 let now = now_ms();
306 let worktree = spec.worktree.clone().unwrap_or_else(|| self.root.clone());
307 let status = if spec.dependencies.is_empty() {
308 AgentStatus::Starting
309 } else {
310 AgentStatus::Queued
311 };
312 self.records.insert(
313 id.clone(),
314 AgentRecord {
315 snapshot: AgentSnapshot {
316 id: id.clone(),
317 role: spec.role.clone(),
318 task: spec.task.clone(),
319 status,
320 dependencies: spec.dependencies.clone(),
321 model: spec.model.clone(),
322 thinking: spec.thinking.clone(),
323 worktree,
324 unrestricted: spec.unrestricted,
325 created_at_ms: now,
326 started_at_ms: None,
327 updated_at_ms: now,
328 event_count: 0,
329 dropped_event_count: 0,
330 last_error: None,
331 last_response_id: None,
332 evidence: Vec::new(),
333 },
334 spec,
335 command: None,
336 worker: None,
337 awaiting_agent_settle: false,
338 dropped_events: Arc::new(AtomicU64::new(0)),
339 },
340 );
341 if status == AgentStatus::Starting {
342 self.spawn(&id)?;
343 }
344 Ok(id)
345 }
346
347 pub fn refresh(&mut self) -> DevelopmentResult<()> {
348 loop {
349 match self.events_rx.try_recv() {
350 Ok(event) => self.apply_worker_event(event),
351 Err(TryRecvError::Empty) => break,
352 Err(TryRecvError::Disconnected) => {
353 return Err(DevelopmentError::Process(
354 "agent scheduler event channel closed".into(),
355 ));
356 }
357 }
358 }
359 for record in self.records.values_mut() {
360 record.snapshot.dropped_event_count = record.dropped_events.load(Ordering::Relaxed);
361 }
362 self.reap_finished_workers();
363 self.enforce_budgets();
364 self.fail_blocked_dependents();
365 self.start_ready_agents()?;
366 Ok(())
367 }
368
369 pub fn snapshot(&mut self, id: &AgentId) -> DevelopmentResult<AgentSnapshot> {
370 self.refresh()?;
371 self.records
372 .get(id)
373 .map(|record| record.snapshot.clone())
374 .ok_or_else(|| DevelopmentError::NotFound(format!("agent {}", id.as_str())))
375 }
376
377 pub fn list(&mut self) -> DevelopmentResult<Vec<AgentSnapshot>> {
378 self.refresh()?;
379 Ok(self
380 .records
381 .values()
382 .map(|record| record.snapshot.clone())
383 .collect())
384 }
385
386 pub fn history(&mut self, since: u64) -> DevelopmentResult<Vec<AgentEvent>> {
387 self.refresh()?;
388 Ok(self
389 .history
390 .iter()
391 .filter(|event| event.sequence > since)
392 .cloned()
393 .collect())
394 }
395
396 pub fn prompt(&mut self, id: &AgentId, text: impl Into<String>) -> DevelopmentResult<()> {
397 self.prompt_with_context(id, text, None)
398 }
399
400 pub fn prompt_with_context(
401 &mut self,
402 id: &AgentId,
403 text: impl Into<String>,
404 context: Option<Value>,
405 ) -> DevelopmentResult<()> {
406 let text = text.into();
407 validate_text("agent prompt", &text, MAX_PROMPT_BYTES)?;
408 validate_context_attachment(context.as_ref())?;
409 self.send(id, PiSessionRequest::Prompt { text, context })
410 }
411
412 pub fn steer(&mut self, id: &AgentId, text: impl Into<String>) -> DevelopmentResult<()> {
413 self.steer_with_context(id, text, None)
414 }
415
416 pub fn steer_with_context(
417 &mut self,
418 id: &AgentId,
419 text: impl Into<String>,
420 context: Option<Value>,
421 ) -> DevelopmentResult<()> {
422 let text = text.into();
423 validate_text("agent steering", &text, MAX_PROMPT_BYTES)?;
424 validate_context_attachment(context.as_ref())?;
425 self.send(id, PiSessionRequest::Steer { text, context })
426 }
427
428 pub fn follow_up(&mut self, id: &AgentId, text: impl Into<String>) -> DevelopmentResult<()> {
429 self.follow_up_with_context(id, text, None)
430 }
431
432 pub fn follow_up_with_context(
433 &mut self,
434 id: &AgentId,
435 text: impl Into<String>,
436 context: Option<Value>,
437 ) -> DevelopmentResult<()> {
438 let text = text.into();
439 validate_text("agent follow-up", &text, MAX_PROMPT_BYTES)?;
440 validate_context_attachment(context.as_ref())?;
441 self.send(id, PiSessionRequest::FollowUp { text, context })
442 }
443
444 pub fn approve_tool(
445 &mut self,
446 id: &AgentId,
447 frame_id: impl Into<String>,
448 approved: bool,
449 ) -> DevelopmentResult<()> {
450 self.refresh()?;
451 let frame_id = frame_id.into();
452 validate_text("Pi approval frame", &frame_id, 256)?;
453 let record = self.record_mut(id)?;
454 if record.snapshot.status.terminal() {
455 return Err(DevelopmentError::Conflict(format!(
456 "agent {} is already terminal",
457 id.as_str()
458 )));
459 }
460 let sender = record.command.as_ref().ok_or_else(|| {
461 DevelopmentError::Conflict(format!("agent {} is still starting", id.as_str()))
462 })?;
463 sender
464 .try_send(WorkerCommand::ApproveTool { frame_id, approved })
465 .map_err(|error| match error {
466 TrySendError::Full(_) => DevelopmentError::Conflict(format!(
467 "agent {} command queue is full",
468 id.as_str()
469 )),
470 TrySendError::Disconnected(_) => DevelopmentError::Process(format!(
471 "agent {} command channel closed",
472 id.as_str()
473 )),
474 })
475 }
476
477 pub fn request(&mut self, id: &AgentId, request: PiSessionRequest) -> DevelopmentResult<()> {
478 self.send(id, request)
479 }
480
481 pub fn complete(&mut self, id: &AgentId) -> DevelopmentResult<()> {
482 self.refresh()?;
483 if self.record_mut(id)?.snapshot.status.terminal() {
484 return Err(DevelopmentError::Conflict(format!(
485 "agent {} is already terminal",
486 id.as_str()
487 )));
488 }
489 if let Some(sender) = self.record_mut(id)?.command.take() {
490 let _ = sender.try_send(WorkerCommand::Shutdown);
491 }
492 self.join_worker(id, AgentStatus::Completed)?;
493 self.record_event(id, "completed", Value::Null);
494 self.start_ready_agents()?;
495 Ok(())
496 }
497
498 pub fn cancel(&mut self, id: &AgentId) -> DevelopmentResult<()> {
499 self.refresh()?;
500 if self.record_mut(id)?.snapshot.status.terminal() {
501 return Ok(());
502 }
503 if let Some(sender) = &self.record_mut(id)?.command {
504 let _ = sender.try_send(WorkerCommand::Request(PiSessionRequest::Abort));
505 let _ = sender.try_send(WorkerCommand::Shutdown);
506 }
507 self.record_mut(id)?.command = None;
508 self.join_worker(id, AgentStatus::Cancelled)?;
509 self.record_event(id, "cancelled", Value::Null);
510 self.fail_blocked_dependents();
511 Ok(())
512 }
513 pub fn restart(&mut self, id: &AgentId) -> DevelopmentResult<()> {
520 self.refresh()?;
521 let previous_status = {
522 let record = self.record_mut(id)?;
523 if !matches!(
524 record.snapshot.status,
525 AgentStatus::Failed | AgentStatus::Cancelled
526 ) {
527 return Err(DevelopmentError::Conflict(format!(
528 "agent {} can only restart from failed or cancelled, not {:?}",
529 id.as_str(),
530 record.snapshot.status
531 )));
532 }
533 record.snapshot.status
534 };
535 self.join_worker(id, previous_status)?;
538 {
539 let record = self.record_mut(id)?;
540 record.snapshot.last_error = None;
541 record.snapshot.last_response_id = None;
542 record.awaiting_agent_settle = false;
543 }
544 self.spawn(id)?;
545 self.record_event(
546 id,
547 "restarted",
548 serde_json::json!({"previousStatus": previous_status.label()}),
549 );
550 Ok(())
551 }
552
553 fn send(&mut self, id: &AgentId, request: PiSessionRequest) -> DevelopmentResult<()> {
554 self.refresh()?;
555 let user_event = match &request {
556 PiSessionRequest::Prompt { text, context } => Some(
557 serde_json::json!({"text": text, "mode": "prompt", "contextAttached": context.is_some()}),
558 ),
559 PiSessionRequest::Steer { text, context } => Some(
560 serde_json::json!({"text": text, "mode": "steer", "contextAttached": context.is_some()}),
561 ),
562 PiSessionRequest::FollowUp { text, context } => Some(
563 serde_json::json!({"text": text, "mode": "follow-up", "contextAttached": context.is_some()}),
564 ),
565 _ => None,
566 };
567 {
568 let record = self.record_mut(id)?;
569 if record.snapshot.status.terminal() || record.snapshot.status == AgentStatus::Queued {
570 return Err(DevelopmentError::Conflict(format!(
571 "agent {} cannot accept requests while {:?}",
572 id.as_str(),
573 record.snapshot.status
574 )));
575 }
576 let sender = record.command.as_ref().ok_or_else(|| {
577 DevelopmentError::Conflict(format!("agent {} is still starting", id.as_str()))
578 })?;
579 sender
580 .try_send(WorkerCommand::Request(request))
581 .map_err(|error| match error {
582 TrySendError::Full(_) => DevelopmentError::Conflict(format!(
583 "agent {} command queue is full",
584 id.as_str()
585 )),
586 TrySendError::Disconnected(_) => DevelopmentError::Process(format!(
587 "agent {} command channel closed",
588 id.as_str()
589 )),
590 })?;
591 }
592 if let Some(payload) = user_event {
593 self.record_event(id, "user", payload);
594 }
595 Ok(())
596 }
597
598 fn spawn(&mut self, id: &AgentId) -> DevelopmentResult<()> {
599 let sessions_dir = self.sessions_dir.clone();
600 let events = self.events_tx.clone();
601 let broker = self.broker.clone();
602 let additional_system_prompt = self.additional_system_prompt.clone();
603 let local_tool_executor = self.local_tool_executor.clone();
604 let record = self.record_mut(id)?;
605 let dropped_events = Arc::clone(&record.dropped_events);
606 let spec = record.spec.clone();
607 let worktree = record.snapshot.worktree.clone();
608 let worker_id = id.clone();
609 let (commands_tx, commands_rx) = mpsc::sync_channel(COMMAND_CAPACITY);
610 record.command = Some(commands_tx);
611 record.snapshot.status = AgentStatus::Starting;
612 record.snapshot.started_at_ms = Some(now_ms());
613 record.snapshot.updated_at_ms = now_ms();
614 let worker = thread::Builder::new()
615 .name(format!("glass-{}", id.as_str()))
616 .spawn(move || {
617 run_worker(
618 worker_id,
619 spec,
620 WorkerRuntime {
621 local_tool_executor,
622 worktree,
623 sessions_dir,
624 broker,
625 additional_system_prompt,
626 },
627 commands_rx,
628 events,
629 dropped_events,
630 )
631 })
632 .map_err(DevelopmentError::Io)?;
633 record.worker = Some(worker);
634 self.record_event(id, "starting", Value::Null);
635 Ok(())
636 }
637
638 fn start_ready_agents(&mut self) -> DevelopmentResult<()> {
639 let ready: Vec<_> = self
640 .records
641 .iter()
642 .filter(|(_, record)| record.snapshot.status == AgentStatus::Queued)
643 .filter(|(_, record)| {
644 record.spec.dependencies.iter().all(|dependency| {
645 self.records.get(dependency).is_some_and(|dependency| {
646 dependency.snapshot.status == AgentStatus::Completed
647 })
648 })
649 })
650 .map(|(id, _)| id.clone())
651 .collect();
652 for id in ready {
653 self.spawn(&id)?;
654 }
655 Ok(())
656 }
657
658 fn fail_blocked_dependents(&mut self) {
659 let terminal_failures: BTreeSet<_> = self
660 .records
661 .iter()
662 .filter(|(_, record)| {
663 matches!(
664 record.snapshot.status,
665 AgentStatus::Failed | AgentStatus::Cancelled
666 )
667 })
668 .map(|(id, _)| id.clone())
669 .collect();
670 let blocked: Vec<_> = self
671 .records
672 .iter()
673 .filter(|(_, record)| record.snapshot.status == AgentStatus::Queued)
674 .filter(|(_, record)| {
675 record
676 .spec
677 .dependencies
678 .iter()
679 .any(|dependency| terminal_failures.contains(dependency))
680 })
681 .map(|(id, _)| id.clone())
682 .collect();
683 for id in blocked {
684 if let Some(record) = self.records.get_mut(&id) {
685 record.snapshot.status = AgentStatus::Failed;
686 record.snapshot.last_error = Some("a required agent did not complete".into());
687 record.snapshot.updated_at_ms = now_ms();
688 }
689 self.record_event(
690 &id,
691 "dependencyFailed",
692 Value::String("a required agent did not complete".into()),
693 );
694 }
695 }
696
697 fn enforce_budgets(&mut self) {
698 let now = now_ms();
699 let exceeded: Vec<_> = self
700 .records
701 .iter()
702 .filter(|(_, record)| !record.snapshot.status.terminal())
703 .filter(|(_, record)| {
704 record
705 .spec
706 .max_runtime_seconds
707 .zip(record.snapshot.started_at_ms)
708 .is_some_and(|(seconds, started)| {
709 now.saturating_sub(started) > u128::from(seconds) * 1_000
710 })
711 || record
712 .spec
713 .max_events
714 .is_some_and(|limit| record.snapshot.event_count >= limit)
715 })
716 .map(|(id, _)| id.clone())
717 .collect();
718 for id in exceeded {
719 if let Some(record) = self.records.get_mut(&id) {
720 if let Some(sender) = record.command.take() {
721 let _ = sender.try_send(WorkerCommand::Request(PiSessionRequest::Abort));
722 let _ = sender.try_send(WorkerCommand::Shutdown);
723 }
724 record.snapshot.status = AgentStatus::Failed;
725 record.snapshot.last_error = Some("agent budget exceeded".into());
726 record.snapshot.updated_at_ms = now;
727 }
728 self.record_event(&id, "budgetExceeded", Value::Null);
729 }
730 }
731
732 fn apply_worker_event(&mut self, event: WorkerEvent) {
733 match event {
734 WorkerEvent::Ready(id) => {
735 if let Some(record) = self.records.get_mut(&id)
736 && !record.snapshot.status.terminal()
737 {
738 record.snapshot.status = AgentStatus::Idle;
739 record.snapshot.updated_at_ms = now_ms();
740 }
741 self.record_event(&id, "ready", Value::Null);
742 }
743 WorkerEvent::RequestStarted(id, request_id, waits_for_agent) => {
744 if let Some(record) = self.records.get_mut(&id)
745 && !record.snapshot.status.terminal()
746 {
747 record.snapshot.last_response_id = Some(request_id.clone());
748 record.snapshot.status = AgentStatus::Working;
749 record.awaiting_agent_settle |= waits_for_agent;
750 record.snapshot.updated_at_ms = now_ms();
751 }
752 self.record_event(&id, "requestStarted", Value::String(request_id));
753 }
754 WorkerEvent::Pi(id, value) => {
755 if let Some(record) = self.records.get_mut(&id) {
756 let event_type = value.get("type").and_then(Value::as_str);
757 if event_type == Some("agent_settled") && !record.snapshot.status.terminal() {
758 record.awaiting_agent_settle = false;
759 record.snapshot.status = AgentStatus::Idle;
760 }
761 if event_type == Some("response")
762 && !record.awaiting_agent_settle
763 && !record.snapshot.status.terminal()
764 {
765 record.snapshot.status = AgentStatus::Idle;
766 }
767 record.snapshot.event_count = record.snapshot.event_count.saturating_add(1);
768 record.snapshot.updated_at_ms = now_ms();
769 if record.snapshot.evidence.len() == AGENT_EVIDENCE_CAPACITY {
770 record.snapshot.evidence.remove(0);
771 }
772 record.snapshot.evidence.push(value.clone());
773 }
774 let kind = value
775 .get("type")
776 .and_then(Value::as_str)
777 .unwrap_or("piEvent")
778 .to_string();
779 self.record_event(&id, &kind, value);
780 }
781 WorkerEvent::Failed(id, error) => {
782 if let Some(record) = self.records.get_mut(&id)
783 && !record.snapshot.status.terminal()
784 {
785 record.snapshot.status = AgentStatus::Failed;
786 record.snapshot.last_error = Some(error.clone());
787 record.snapshot.updated_at_ms = now_ms();
788 record.command = None;
789 }
790 self.record_event(&id, "failed", Value::String(error));
791 }
792 WorkerEvent::Stopped(id) => {
793 if let Some(record) = self.records.get_mut(&id) {
794 record.command = None;
795 }
796 self.record_event(&id, "stopped", Value::Null);
797 }
798 }
799 }
800
801 fn join_worker(&mut self, id: &AgentId, terminal: AgentStatus) -> DevelopmentResult<()> {
802 let worker = self.record_mut(id)?.worker.take();
803 if let Some(worker) = worker
804 && worker.join().is_err()
805 {
806 let error = format!("agent {} worker panicked", id.as_str());
807 let record = self.record_mut(id)?;
808 record.command = None;
809 record.snapshot.status = AgentStatus::Failed;
810 record.snapshot.last_error = Some(error.clone());
811 record.snapshot.updated_at_ms = now_ms();
812 self.record_event(
813 id,
814 "workerPanicked",
815 serde_json::json!({"agentId":id.as_str(),"error":error}),
816 );
817 return Err(DevelopmentError::Process(error));
818 }
819 let record = self.record_mut(id)?;
820 record.command = None;
821 record.snapshot.status = terminal;
822 record.snapshot.updated_at_ms = now_ms();
823 Ok(())
824 }
825
826 fn reap_finished_workers(&mut self) {
827 let finished = self
828 .records
829 .iter()
830 .filter(|(_, record)| {
831 record
832 .worker
833 .as_ref()
834 .is_some_and(|worker| worker.is_finished())
835 })
836 .map(|(id, _)| id.clone())
837 .collect::<Vec<_>>();
838 for id in finished {
839 let worker = self
840 .records
841 .get_mut(&id)
842 .and_then(|record| record.worker.take());
843 let panicked = worker.is_some_and(|worker| worker.join().is_err());
844 let mut event = None;
845 if let Some(record) = self.records.get_mut(&id) {
846 record.command = None;
847 if panicked {
848 let error = format!("agent {} worker panicked", id.as_str());
849 record.snapshot.status = AgentStatus::Failed;
850 record.snapshot.last_error = Some(error.clone());
851 record.snapshot.updated_at_ms = now_ms();
852 event = Some((
853 "workerPanicked",
854 serde_json::json!({
855 "agentId":id.as_str(),
856 "role":record.snapshot.role.clone(),
857 "task":record.snapshot.task.clone(),
858 "error":error,
859 }),
860 ));
861 } else if !record.snapshot.status.terminal() {
862 let error = format!(
863 "agent {} worker exited before a terminal outcome",
864 id.as_str()
865 );
866 record.snapshot.status = AgentStatus::Failed;
867 record.snapshot.last_error = Some(error.clone());
868 record.snapshot.updated_at_ms = now_ms();
869 event = Some(("workerExited", Value::String(error)));
870 }
871 }
872 if let Some((kind, payload)) = event {
873 self.record_event(&id, kind, payload);
874 }
875 }
876 }
877
878 fn record_event(&mut self, id: &AgentId, kind: &str, payload: Value) {
879 if self.history.len() == HISTORY_CAPACITY {
880 self.history.pop_front();
881 }
882 self.history.push_back(AgentEvent {
883 sequence: self.next_event,
884 agent_id: id.clone(),
885 timestamp_ms: now_ms(),
886 kind: kind.into(),
887 payload,
888 });
889 self.next_event = self.next_event.saturating_add(1);
890 }
891
892 fn record_mut(&mut self, id: &AgentId) -> DevelopmentResult<&mut AgentRecord> {
893 self.records
894 .get_mut(id)
895 .ok_or_else(|| DevelopmentError::NotFound(format!("agent {}", id.as_str())))
896 }
897}
898
899impl Drop for AgentRegistry {
900 fn drop(&mut self) {
901 let mut workers = Vec::new();
902 for (id, record) in &mut self.records {
903 if let Some(sender) = record.command.take() {
904 let _ = sender.try_send(WorkerCommand::Shutdown);
905 }
906 if let Some(worker) = record.worker.take() {
907 workers.push((id.clone(), worker));
908 }
909 }
910 for (id, worker) in workers {
911 if worker.join().is_err() {
912 tracing::error!(agent_id = %id.as_str(), "agent worker panicked during registry drop");
913 }
914 }
915 }
916}
917
918fn run_worker(
919 id: AgentId,
920 spec: AgentSpec,
921 runtime: WorkerRuntime,
922 commands: Receiver<WorkerCommand>,
923 events: SyncSender<WorkerEvent>,
924 dropped_events: Arc<AtomicU64>,
925) {
926 let options = PiRuntimeOptions {
927 unrestricted: spec.unrestricted,
928 session_dir: runtime.sessions_dir,
929 name: Some(format!("{}: {}", spec.role, id.as_str())),
930 model: spec.model,
931 thinking: spec.thinking,
932 broker: runtime.broker,
933 local_tool_executor: runtime.local_tool_executor,
934 additional_system_prompt: runtime.additional_system_prompt,
935 resume: false,
936 };
937 let mut harness = match GlassPiRuntime::spawn(&runtime.worktree, options) {
938 Ok(harness) => harness,
939 Err(error) => {
940 send_critical_worker_event(&events, WorkerEvent::Failed(id, error.to_string()));
941 return;
942 }
943 };
944 send_critical_worker_event(&events, WorkerEvent::Ready(id.clone()));
945 loop {
946 loop {
947 match commands.try_recv() {
948 Ok(WorkerCommand::Request(request)) => {
949 let waits_for_agent = matches!(
950 request,
951 PiSessionRequest::Prompt { .. } | PiSessionRequest::FollowUp { .. }
952 );
953 match harness.start_request(request) {
954 Ok(request_id) => send_critical_worker_event(
955 &events,
956 WorkerEvent::RequestStarted(id.clone(), request_id, waits_for_agent),
957 ),
958 Err(error) => {
959 send_critical_worker_event(
960 &events,
961 WorkerEvent::Failed(id.clone(), error.to_string()),
962 );
963 return;
964 }
965 }
966 }
967 Ok(WorkerCommand::ApproveTool { frame_id, approved }) => {
968 if let Err(error) = harness.resolve_tool_approval(&frame_id, approved) {
969 send_critical_worker_event(
970 &events,
971 WorkerEvent::Pi(
972 id.clone(),
973 serde_json::json!({
974 "type":"glass_tool_approval_resolved",
975 "frameId":frame_id,
976 "approved":approved,
977 "ok":false,
978 "error":error.to_string(),
979 }),
980 ),
981 );
982 }
983 }
984 Ok(WorkerCommand::Shutdown) | Err(TryRecvError::Disconnected) => {
985 send_critical_worker_event(&events, WorkerEvent::Stopped(id));
986 return;
987 }
988 Err(TryRecvError::Empty) => break,
989 }
990 }
991 match harness.recv_event_timeout(Duration::from_millis(25)) {
992 Ok(Some(value)) => send_lossy_worker_event(
993 &events,
994 WorkerEvent::Pi(id.clone(), value),
995 &dropped_events,
996 ),
997 Ok(None) => {}
998 Err(error) => {
999 send_critical_worker_event(&events, WorkerEvent::Failed(id, error.to_string()));
1000 return;
1001 }
1002 }
1003 }
1004}
1005
1006fn send_lossy_worker_event(
1007 events: &SyncSender<WorkerEvent>,
1008 event: WorkerEvent,
1009 dropped_events: &AtomicU64,
1010) {
1011 if matches!(events.try_send(event), Err(TrySendError::Full(_))) {
1012 dropped_events.fetch_add(1, Ordering::Relaxed);
1013 }
1014}
1015
1016fn send_critical_worker_event(events: &SyncSender<WorkerEvent>, event: WorkerEvent) {
1017 let _ = events.send(event);
1018}
1019
1020fn validate_spec(
1021 root: &Path,
1022 records: &BTreeMap<AgentId, AgentRecord>,
1023 spec: &AgentSpec,
1024) -> DevelopmentResult<()> {
1025 validate_text("agent role", &spec.role, 128)?;
1026 validate_text("agent task", &spec.task, MAX_PROMPT_BYTES)?;
1027 if spec.dependencies.len() > MAX_AGENTS {
1028 return Err(DevelopmentError::InvalidInput(
1029 "agent dependency list is too large".into(),
1030 ));
1031 }
1032 let mut unique = BTreeSet::new();
1033 for dependency in &spec.dependencies {
1034 if !unique.insert(dependency) {
1035 return Err(DevelopmentError::InvalidInput(format!(
1036 "duplicate dependency {}",
1037 dependency.as_str()
1038 )));
1039 }
1040 if !records.contains_key(dependency) {
1041 return Err(DevelopmentError::NotFound(format!(
1042 "dependency agent {}",
1043 dependency.as_str()
1044 )));
1045 }
1046 }
1047 if let Some(worktree) = &spec.worktree {
1048 let worktree = std::fs::canonicalize(worktree)?;
1049 if worktree == Path::new("/")
1050 || (!worktree.starts_with(root) && !worktree.join(".git").exists())
1051 {
1052 return Err(DevelopmentError::PathOutsideWorkspace(worktree));
1053 }
1054 }
1055 if spec.max_runtime_seconds == Some(0) || spec.max_events == Some(0) {
1056 return Err(DevelopmentError::InvalidInput(
1057 "agent budgets must be greater than zero".into(),
1058 ));
1059 }
1060 Ok(())
1061}
1062
1063fn validate_text(description: &str, text: &str, limit: usize) -> DevelopmentResult<()> {
1064 if text.trim().is_empty() || text.len() > limit || text.contains('\0') {
1065 return Err(DevelopmentError::InvalidInput(format!(
1066 "{description} must contain 1..={limit} bytes without NUL"
1067 )));
1068 }
1069 Ok(())
1070}
1071
1072fn validate_context_attachment(context: Option<&Value>) -> DevelopmentResult<()> {
1073 let Some(context) = context else {
1074 return Ok(());
1075 };
1076 if !context.is_object() {
1077 return Err(DevelopmentError::InvalidInput(
1078 "agent context attachment must be a JSON object".into(),
1079 ));
1080 }
1081 let size = serde_json::to_vec(context)
1082 .map_err(|error| DevelopmentError::Serialization(error.to_string()))?
1083 .len();
1084 if size > 64 * 1024 {
1085 return Err(DevelopmentError::InvalidInput(
1086 "agent context attachment exceeds 64 KiB".into(),
1087 ));
1088 }
1089 Ok(())
1090}
1091
1092fn now_ms() -> u128 {
1093 SystemTime::now()
1094 .duration_since(UNIX_EPOCH)
1095 .unwrap_or_default()
1096 .as_millis()
1097}
1098
1099#[cfg(test)]
1100mod tests {
1101 use super::*;
1102 use std::sync::atomic::{AtomicU64, Ordering};
1103
1104 static NEXT_ROOT: AtomicU64 = AtomicU64::new(0);
1105
1106 fn test_root() -> PathBuf {
1107 let sequence = NEXT_ROOT.fetch_add(1, Ordering::Relaxed);
1108 let root = std::env::temp_dir().join(format!(
1109 "glass-agent-registry-{}-{sequence}",
1110 std::process::id()
1111 ));
1112 std::fs::create_dir_all(&root).unwrap();
1113 root
1114 }
1115
1116 #[test]
1117 fn lossy_worker_queue_reports_dropped_events() {
1118 let (sender, _receiver) = mpsc::sync_channel(1);
1119 let id = AgentId::parse("agent-overflow").unwrap();
1120 sender.send(WorkerEvent::Ready(id.clone())).unwrap();
1121 let dropped = AtomicU64::new(0);
1122 send_lossy_worker_event(
1123 &sender,
1124 WorkerEvent::Pi(id, serde_json::json!({"type":"delta"})),
1125 &dropped,
1126 );
1127 assert_eq!(dropped.load(Ordering::Relaxed), 1);
1128 }
1129
1130 fn insert_test_worker(
1131 registry: &mut AgentRegistry,
1132 id: AgentId,
1133 command: SyncSender<WorkerCommand>,
1134 worker: thread::JoinHandle<()>,
1135 ) {
1136 let spec = AgentSpec::new("lifecycle-test", "prove worker ownership");
1137 let now = now_ms();
1138 registry.records.insert(
1139 id.clone(),
1140 AgentRecord {
1141 snapshot: AgentSnapshot {
1142 id,
1143 role: spec.role.clone(),
1144 task: spec.task.clone(),
1145 status: AgentStatus::Working,
1146 dependencies: Vec::new(),
1147 model: None,
1148 thinking: None,
1149 worktree: registry.root.clone(),
1150 unrestricted: false,
1151 created_at_ms: now,
1152 started_at_ms: Some(now),
1153 updated_at_ms: now,
1154 event_count: 0,
1155 dropped_event_count: 0,
1156 last_error: None,
1157 last_response_id: None,
1158 evidence: Vec::new(),
1159 },
1160 spec,
1161 command: Some(command),
1162 worker: Some(worker),
1163 awaiting_agent_settle: false,
1164 dropped_events: Arc::new(AtomicU64::new(0)),
1165 },
1166 );
1167 }
1168
1169 #[test]
1170 fn repeated_cancel_joins_every_owned_worker() {
1171 let root = test_root();
1172 let mut registry = AgentRegistry::new(&root).unwrap();
1173 let exited = Arc::new(AtomicU64::new(0));
1174 for sequence in 0..128 {
1175 let id = AgentId::parse(format!("agent-test-{sequence}")).unwrap();
1176 let (command, commands) = mpsc::sync_channel(COMMAND_CAPACITY);
1177 let exits = Arc::clone(&exited);
1178 let worker = thread::spawn(move || {
1179 while let Ok(command) = commands.recv() {
1180 if matches!(command, WorkerCommand::Shutdown) {
1181 break;
1182 }
1183 }
1184 exits.fetch_add(1, Ordering::SeqCst);
1185 });
1186 insert_test_worker(&mut registry, id.clone(), command, worker);
1187 registry.cancel(&id).unwrap();
1188 let record = registry.records.get(&id).unwrap();
1189 assert_eq!(record.snapshot.status, AgentStatus::Cancelled);
1190 assert!(record.worker.is_none());
1191 }
1192 assert_eq!(exited.load(Ordering::SeqCst), 128);
1193 drop(registry);
1194 std::fs::remove_dir_all(root).unwrap();
1195 }
1196
1197 #[test]
1198 fn worker_panic_becomes_attributed_agent_failure() {
1199 let root = test_root();
1200 let mut registry = AgentRegistry::new(&root).unwrap();
1201 let id = AgentId::parse("agent-panic-test").unwrap();
1202 let (command, _commands) = mpsc::sync_channel(COMMAND_CAPACITY);
1203 let worker = thread::spawn(|| panic!("intentional worker panic"));
1204 worker.thread().unpark();
1205 insert_test_worker(&mut registry, id.clone(), command, worker);
1206 for _ in 0..100 {
1207 registry.refresh().unwrap();
1208 if registry.records[&id].snapshot.status == AgentStatus::Failed {
1209 break;
1210 }
1211 thread::sleep(Duration::from_millis(5));
1212 }
1213 let snapshot = registry.snapshot(&id).unwrap();
1214 assert_eq!(snapshot.status, AgentStatus::Failed);
1215 assert!(snapshot.last_error.unwrap().contains(id.as_str()));
1216 assert!(registry.history(0).unwrap().iter().any(|event| {
1217 event.agent_id == id
1218 && event.kind == "workerPanicked"
1219 && event.payload["role"] == "lifecycle-test"
1220 }));
1221 drop(registry);
1222 std::fs::remove_dir_all(root).unwrap();
1223 }
1224
1225 fn wait_for_status(
1226 registry: &mut AgentRegistry,
1227 id: &AgentId,
1228 expected: AgentStatus,
1229 ) -> AgentSnapshot {
1230 for _ in 0..800 {
1231 let snapshot = registry.snapshot(id).unwrap();
1232 if snapshot.status == expected {
1233 return snapshot;
1234 }
1235 if snapshot.status == AgentStatus::Failed {
1236 panic!("agent failed: {:?}", snapshot.last_error);
1237 }
1238 thread::sleep(Duration::from_millis(25));
1239 }
1240 panic!("agent did not reach {expected:?}");
1241 }
1242
1243 #[test]
1244 fn independent_pi_sessions_schedule_dependencies_and_stream_state() {
1245 if std::process::Command::new("pi")
1246 .arg("--version")
1247 .output()
1248 .is_err()
1249 {
1250 return;
1251 }
1252 let root = test_root();
1253 let mut registry = AgentRegistry::new(&root).unwrap();
1254 let first = registry
1255 .create(AgentSpec::new("implementer", "inspect state"))
1256 .unwrap();
1257 let peer = registry
1258 .create(AgentSpec::new("researcher", "inspect independent state"))
1259 .unwrap();
1260 wait_for_status(&mut registry, &first, AgentStatus::Idle);
1261 wait_for_status(&mut registry, &peer, AgentStatus::Idle);
1262 registry.request(&first, PiSessionRequest::State).unwrap();
1263 registry.request(&peer, PiSessionRequest::State).unwrap();
1264 for _ in 0..200 {
1265 let snapshot = registry.snapshot(&first).unwrap();
1266 if snapshot
1267 .evidence
1268 .iter()
1269 .any(|event| event.get("type").and_then(Value::as_str) == Some("response"))
1270 {
1271 break;
1272 }
1273 thread::sleep(Duration::from_millis(25));
1274 }
1275 assert!(registry.snapshot(&first).unwrap().event_count > 0);
1276 for _ in 0..200 {
1277 if registry.snapshot(&peer).unwrap().event_count > 0 {
1278 break;
1279 }
1280 thread::sleep(Duration::from_millis(25));
1281 }
1282 assert!(registry.snapshot(&peer).unwrap().event_count > 0);
1283
1284 let mut dependent = AgentSpec::new("reviewer", "review evidence");
1285 dependent.dependencies.push(first.clone());
1286 let second = registry.create(dependent).unwrap();
1287 assert_eq!(
1288 registry.snapshot(&second).unwrap().status,
1289 AgentStatus::Queued
1290 );
1291 registry.complete(&first).unwrap();
1292 wait_for_status(&mut registry, &second, AgentStatus::Idle);
1293 assert_ne!(first, second);
1294 registry.cancel(&second).unwrap();
1295 assert_eq!(
1296 registry.snapshot(&second).unwrap().status,
1297 AgentStatus::Cancelled
1298 );
1299 registry.restart(&second).unwrap();
1300 wait_for_status(&mut registry, &second, AgentStatus::Idle);
1301 registry.cancel(&second).unwrap();
1302 registry.cancel(&peer).unwrap();
1303 drop(registry);
1304 std::fs::remove_dir_all(root).unwrap();
1305 }
1306
1307 #[test]
1308 fn invalid_agent_specs_and_failed_dependencies_fail_closed() {
1309 let root = test_root();
1310 let mut registry = AgentRegistry::new(&root).unwrap();
1311 assert!(registry.create(AgentSpec::new("", "task")).is_err());
1312 let first = registry.create(AgentSpec::new("lead", "task")).unwrap();
1313 let mut dependent = AgentSpec::new("review", "task");
1314 dependent.dependencies.push(first.clone());
1315 let second = registry.create(dependent).unwrap();
1316 registry.cancel(&first).unwrap();
1317 assert_eq!(
1318 registry.snapshot(&second).unwrap().status,
1319 AgentStatus::Failed
1320 );
1321 drop(registry);
1322 std::fs::remove_dir_all(root).unwrap();
1323 }
1324
1325 #[test]
1326 fn context_attachments_are_bounded_json_objects() {
1327 assert!(validate_context_attachment(None).is_ok());
1328 assert!(validate_context_attachment(Some(&serde_json::json!("text"))).is_err());
1329 let oversized = serde_json::json!({"text": "x".repeat(64 * 1024)});
1330 assert!(validate_context_attachment(Some(&oversized)).is_err());
1331 let bounded = serde_json::json!({
1332 "schemaVersion": "glass.agent-context.v1",
1333 "browser": {"browserRevision": 12}
1334 });
1335 assert!(validate_context_attachment(Some(&bounded)).is_ok());
1336 }
1337}