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