Skip to main content

glass_dev/
agents.rs

1//! Glass-owned scheduling for independent resident Pi agent sessions.
2
3use crate::development::{DevelopmentError, DevelopmentResult};
4use crate::pi_runtime::{GlassPiRuntime, PiRuntimeOptions, PiSessionRequest};
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    /// Human-readable label for terminal and TUI surfaces.
68    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    Shutdown,
150}
151
152#[derive(Debug)]
153enum WorkerEvent {
154    Ready(AgentId),
155    RequestStarted(AgentId, String, bool),
156    Pi(AgentId, Value),
157    Failed(AgentId, String),
158    Stopped(AgentId),
159}
160
161struct AgentRecord {
162    snapshot: AgentSnapshot,
163    spec: AgentSpec,
164    command: Option<SyncSender<WorkerCommand>>,
165    worker: Option<thread::JoinHandle<()>>,
166    awaiting_agent_settle: bool,
167    dropped_events: Arc<AtomicU64>,
168}
169
170struct WorkerRuntime {
171    worktree: PathBuf,
172    sessions_dir: PathBuf,
173    broker: Option<ResidentAgentBroker>,
174    additional_system_prompt: Option<String>,
175}
176
177/// Registry and scheduler for independent Pi subprocesses.
178///
179/// Each running agent owns a distinct Pi process and persistent session. The
180/// registry only starts dependency-ready work, bounds all queues and retained
181/// evidence, and never silently promotes a failed dependency to success.
182pub struct AgentRegistry {
183    root: PathBuf,
184    sessions_dir: PathBuf,
185    records: BTreeMap<AgentId, AgentRecord>,
186    events_tx: SyncSender<WorkerEvent>,
187    events_rx: Receiver<WorkerEvent>,
188    history: VecDeque<AgentEvent>,
189    next_agent: u64,
190    next_event: u64,
191    broker: Option<ResidentAgentBroker>,
192    additional_system_prompt: Option<String>,
193    default_model: Option<String>,
194    default_thinking: Option<String>,
195}
196
197impl AgentRegistry {
198    pub fn new(root: impl AsRef<Path>) -> DevelopmentResult<Self> {
199        let root = std::fs::canonicalize(root)?;
200        let sessions_dir = root.join(".glass").join("pi-sessions");
201        let (events_tx, events_rx) = mpsc::sync_channel(EVENT_CAPACITY);
202        Ok(Self {
203            root,
204            sessions_dir,
205            records: BTreeMap::new(),
206            events_tx,
207            events_rx,
208            history: VecDeque::new(),
209            next_agent: 1,
210            next_event: 1,
211            broker: None,
212            additional_system_prompt: None,
213            default_model: None,
214            default_thinking: None,
215        })
216    }
217
218    pub fn set_resident_broker(&mut self, broker: ResidentAgentBroker) -> DevelopmentResult<()> {
219        if !broker.socket.is_absolute()
220            || broker.socket == Path::new("/")
221            || broker.token.is_empty()
222            || broker.token.len() > 256
223            || broker.workspace_id.is_empty()
224            || broker.workspace_id.len() > 128
225            || broker
226                .workspace_id
227                .chars()
228                .any(|character| character.is_control())
229        {
230            return Err(DevelopmentError::InvalidInput(
231                "invalid resident agent broker context".into(),
232            ));
233        }
234        self.broker = Some(broker);
235        Ok(())
236    }
237
238    pub fn set_additional_system_prompt(
239        &mut self,
240        prompt: Option<String>,
241    ) -> DevelopmentResult<()> {
242        if prompt
243            .as_ref()
244            .is_some_and(|prompt| prompt.len() > 128 * 1024 || prompt.contains('\0'))
245        {
246            return Err(DevelopmentError::InvalidInput(
247                "agent project instructions exceed 128 KiB or contain NUL".into(),
248            ));
249        }
250        self.additional_system_prompt = prompt;
251        Ok(())
252    }
253
254    /// Active user-global and trusted-project instructions supplied to Pi.
255    pub fn additional_system_prompt(&self) -> Option<&str> {
256        self.additional_system_prompt.as_deref()
257    }
258
259    pub fn set_defaults(
260        &mut self,
261        model: Option<String>,
262        thinking: Option<String>,
263    ) -> DevelopmentResult<()> {
264        for (label, value) in [("model", &model), ("thinking", &thinking)] {
265            if value
266                .as_ref()
267                .is_some_and(|value| value.is_empty() || value.len() > 256 || value.contains('\0'))
268            {
269                return Err(DevelopmentError::InvalidInput(format!(
270                    "default agent {label} must contain 1..=256 bytes without NUL"
271                )));
272            }
273        }
274        self.default_model = model;
275        self.default_thinking = thinking;
276        Ok(())
277    }
278
279    pub fn create(&mut self, mut spec: AgentSpec) -> DevelopmentResult<AgentId> {
280        self.refresh()?;
281        if spec.model.is_none() {
282            spec.model.clone_from(&self.default_model);
283        }
284        if spec.thinking.is_none() {
285            spec.thinking.clone_from(&self.default_thinking);
286        }
287        validate_spec(&self.root, &self.records, &spec)?;
288        if self.records.len() >= MAX_AGENTS {
289            return Err(DevelopmentError::Conflict(format!(
290                "agent registry reached its {MAX_AGENTS} session limit"
291            )));
292        }
293        let id = AgentId(format!("agent-{:04}", self.next_agent));
294        self.next_agent = self
295            .next_agent
296            .checked_add(1)
297            .ok_or_else(|| DevelopmentError::Conflict("agent identifier space exhausted".into()))?;
298        let now = now_ms();
299        let worktree = spec.worktree.clone().unwrap_or_else(|| self.root.clone());
300        let status = if spec.dependencies.is_empty() {
301            AgentStatus::Starting
302        } else {
303            AgentStatus::Queued
304        };
305        self.records.insert(
306            id.clone(),
307            AgentRecord {
308                snapshot: AgentSnapshot {
309                    id: id.clone(),
310                    role: spec.role.clone(),
311                    task: spec.task.clone(),
312                    status,
313                    dependencies: spec.dependencies.clone(),
314                    model: spec.model.clone(),
315                    thinking: spec.thinking.clone(),
316                    worktree,
317                    unrestricted: spec.unrestricted,
318                    created_at_ms: now,
319                    started_at_ms: None,
320                    updated_at_ms: now,
321                    event_count: 0,
322                    dropped_event_count: 0,
323                    last_error: None,
324                    last_response_id: None,
325                    evidence: Vec::new(),
326                },
327                spec,
328                command: None,
329                worker: None,
330                awaiting_agent_settle: false,
331                dropped_events: Arc::new(AtomicU64::new(0)),
332            },
333        );
334        if status == AgentStatus::Starting {
335            self.spawn(&id)?;
336        }
337        Ok(id)
338    }
339
340    pub fn refresh(&mut self) -> DevelopmentResult<()> {
341        loop {
342            match self.events_rx.try_recv() {
343                Ok(event) => self.apply_worker_event(event),
344                Err(TryRecvError::Empty) => break,
345                Err(TryRecvError::Disconnected) => {
346                    return Err(DevelopmentError::Process(
347                        "agent scheduler event channel closed".into(),
348                    ));
349                }
350            }
351        }
352        for record in self.records.values_mut() {
353            record.snapshot.dropped_event_count = record.dropped_events.load(Ordering::Relaxed);
354        }
355        self.reap_finished_workers();
356        self.enforce_budgets();
357        self.fail_blocked_dependents();
358        self.start_ready_agents()?;
359        Ok(())
360    }
361
362    pub fn snapshot(&mut self, id: &AgentId) -> DevelopmentResult<AgentSnapshot> {
363        self.refresh()?;
364        self.records
365            .get(id)
366            .map(|record| record.snapshot.clone())
367            .ok_or_else(|| DevelopmentError::NotFound(format!("agent {}", id.as_str())))
368    }
369
370    pub fn list(&mut self) -> DevelopmentResult<Vec<AgentSnapshot>> {
371        self.refresh()?;
372        Ok(self
373            .records
374            .values()
375            .map(|record| record.snapshot.clone())
376            .collect())
377    }
378
379    pub fn history(&mut self, since: u64) -> DevelopmentResult<Vec<AgentEvent>> {
380        self.refresh()?;
381        Ok(self
382            .history
383            .iter()
384            .filter(|event| event.sequence > since)
385            .cloned()
386            .collect())
387    }
388
389    pub fn prompt(&mut self, id: &AgentId, text: impl Into<String>) -> DevelopmentResult<()> {
390        let text = text.into();
391        validate_text("agent prompt", &text, MAX_PROMPT_BYTES)?;
392        self.send(id, PiSessionRequest::Prompt { text })
393    }
394
395    pub fn steer(&mut self, id: &AgentId, text: impl Into<String>) -> DevelopmentResult<()> {
396        let text = text.into();
397        validate_text("agent steering", &text, MAX_PROMPT_BYTES)?;
398        self.send(id, PiSessionRequest::Steer { text })
399    }
400
401    pub fn follow_up(&mut self, id: &AgentId, text: impl Into<String>) -> DevelopmentResult<()> {
402        let text = text.into();
403        validate_text("agent follow-up", &text, MAX_PROMPT_BYTES)?;
404        self.send(id, PiSessionRequest::FollowUp { text })
405    }
406
407    pub fn request(&mut self, id: &AgentId, request: PiSessionRequest) -> DevelopmentResult<()> {
408        self.send(id, request)
409    }
410
411    pub fn complete(&mut self, id: &AgentId) -> DevelopmentResult<()> {
412        self.refresh()?;
413        if self.record_mut(id)?.snapshot.status.terminal() {
414            return Err(DevelopmentError::Conflict(format!(
415                "agent {} is already terminal",
416                id.as_str()
417            )));
418        }
419        if let Some(sender) = self.record_mut(id)?.command.take() {
420            let _ = sender.try_send(WorkerCommand::Shutdown);
421        }
422        self.join_worker(id, AgentStatus::Completed)?;
423        self.record_event(id, "completed", Value::Null);
424        self.start_ready_agents()?;
425        Ok(())
426    }
427
428    pub fn cancel(&mut self, id: &AgentId) -> DevelopmentResult<()> {
429        self.refresh()?;
430        if self.record_mut(id)?.snapshot.status.terminal() {
431            return Ok(());
432        }
433        if let Some(sender) = &self.record_mut(id)?.command {
434            let _ = sender.try_send(WorkerCommand::Request(PiSessionRequest::Abort));
435            let _ = sender.try_send(WorkerCommand::Shutdown);
436        }
437        self.record_mut(id)?.command = None;
438        self.join_worker(id, AgentStatus::Cancelled)?;
439        self.record_event(id, "cancelled", Value::Null);
440        self.fail_blocked_dependents();
441        Ok(())
442    }
443
444    fn send(&mut self, id: &AgentId, request: PiSessionRequest) -> DevelopmentResult<()> {
445        self.refresh()?;
446        let record = self.record_mut(id)?;
447        if record.snapshot.status.terminal() || record.snapshot.status == AgentStatus::Queued {
448            return Err(DevelopmentError::Conflict(format!(
449                "agent {} cannot accept requests while {:?}",
450                id.as_str(),
451                record.snapshot.status
452            )));
453        }
454        let sender = record.command.as_ref().ok_or_else(|| {
455            DevelopmentError::Conflict(format!("agent {} is still starting", id.as_str()))
456        })?;
457        sender
458            .try_send(WorkerCommand::Request(request))
459            .map_err(|error| match error {
460                TrySendError::Full(_) => DevelopmentError::Conflict(format!(
461                    "agent {} command queue is full",
462                    id.as_str()
463                )),
464                TrySendError::Disconnected(_) => DevelopmentError::Process(format!(
465                    "agent {} command channel closed",
466                    id.as_str()
467                )),
468            })?;
469        Ok(())
470    }
471
472    fn spawn(&mut self, id: &AgentId) -> DevelopmentResult<()> {
473        let sessions_dir = self.sessions_dir.clone();
474        let events = self.events_tx.clone();
475        let broker = self.broker.clone();
476        let additional_system_prompt = self.additional_system_prompt.clone();
477        let record = self.record_mut(id)?;
478        let dropped_events = Arc::clone(&record.dropped_events);
479        let spec = record.spec.clone();
480        let worktree = record.snapshot.worktree.clone();
481        let worker_id = id.clone();
482        let (commands_tx, commands_rx) = mpsc::sync_channel(COMMAND_CAPACITY);
483        record.command = Some(commands_tx);
484        record.snapshot.status = AgentStatus::Starting;
485        record.snapshot.started_at_ms = Some(now_ms());
486        record.snapshot.updated_at_ms = now_ms();
487        let worker = thread::Builder::new()
488            .name(format!("glass-{}", id.as_str()))
489            .spawn(move || {
490                run_worker(
491                    worker_id,
492                    spec,
493                    WorkerRuntime {
494                        worktree,
495                        sessions_dir,
496                        broker,
497                        additional_system_prompt,
498                    },
499                    commands_rx,
500                    events,
501                    dropped_events,
502                )
503            })
504            .map_err(DevelopmentError::Io)?;
505        record.worker = Some(worker);
506        self.record_event(id, "starting", Value::Null);
507        Ok(())
508    }
509
510    fn start_ready_agents(&mut self) -> DevelopmentResult<()> {
511        let ready: Vec<_> = self
512            .records
513            .iter()
514            .filter(|(_, record)| record.snapshot.status == AgentStatus::Queued)
515            .filter(|(_, record)| {
516                record.spec.dependencies.iter().all(|dependency| {
517                    self.records.get(dependency).is_some_and(|dependency| {
518                        dependency.snapshot.status == AgentStatus::Completed
519                    })
520                })
521            })
522            .map(|(id, _)| id.clone())
523            .collect();
524        for id in ready {
525            self.spawn(&id)?;
526        }
527        Ok(())
528    }
529
530    fn fail_blocked_dependents(&mut self) {
531        let terminal_failures: BTreeSet<_> = self
532            .records
533            .iter()
534            .filter(|(_, record)| {
535                matches!(
536                    record.snapshot.status,
537                    AgentStatus::Failed | AgentStatus::Cancelled
538                )
539            })
540            .map(|(id, _)| id.clone())
541            .collect();
542        let blocked: Vec<_> = self
543            .records
544            .iter()
545            .filter(|(_, record)| record.snapshot.status == AgentStatus::Queued)
546            .filter(|(_, record)| {
547                record
548                    .spec
549                    .dependencies
550                    .iter()
551                    .any(|dependency| terminal_failures.contains(dependency))
552            })
553            .map(|(id, _)| id.clone())
554            .collect();
555        for id in blocked {
556            if let Some(record) = self.records.get_mut(&id) {
557                record.snapshot.status = AgentStatus::Failed;
558                record.snapshot.last_error = Some("a required agent did not complete".into());
559                record.snapshot.updated_at_ms = now_ms();
560            }
561            self.record_event(
562                &id,
563                "dependencyFailed",
564                Value::String("a required agent did not complete".into()),
565            );
566        }
567    }
568
569    fn enforce_budgets(&mut self) {
570        let now = now_ms();
571        let exceeded: Vec<_> = self
572            .records
573            .iter()
574            .filter(|(_, record)| !record.snapshot.status.terminal())
575            .filter(|(_, record)| {
576                record
577                    .spec
578                    .max_runtime_seconds
579                    .zip(record.snapshot.started_at_ms)
580                    .is_some_and(|(seconds, started)| {
581                        now.saturating_sub(started) > u128::from(seconds) * 1_000
582                    })
583                    || record
584                        .spec
585                        .max_events
586                        .is_some_and(|limit| record.snapshot.event_count >= limit)
587            })
588            .map(|(id, _)| id.clone())
589            .collect();
590        for id in exceeded {
591            if let Some(record) = self.records.get_mut(&id) {
592                if let Some(sender) = record.command.take() {
593                    let _ = sender.try_send(WorkerCommand::Request(PiSessionRequest::Abort));
594                    let _ = sender.try_send(WorkerCommand::Shutdown);
595                }
596                record.snapshot.status = AgentStatus::Failed;
597                record.snapshot.last_error = Some("agent budget exceeded".into());
598                record.snapshot.updated_at_ms = now;
599            }
600            self.record_event(&id, "budgetExceeded", Value::Null);
601        }
602    }
603
604    fn apply_worker_event(&mut self, event: WorkerEvent) {
605        match event {
606            WorkerEvent::Ready(id) => {
607                if let Some(record) = self.records.get_mut(&id)
608                    && !record.snapshot.status.terminal()
609                {
610                    record.snapshot.status = AgentStatus::Idle;
611                    record.snapshot.updated_at_ms = now_ms();
612                }
613                self.record_event(&id, "ready", Value::Null);
614            }
615            WorkerEvent::RequestStarted(id, request_id, waits_for_agent) => {
616                if let Some(record) = self.records.get_mut(&id)
617                    && !record.snapshot.status.terminal()
618                {
619                    record.snapshot.last_response_id = Some(request_id.clone());
620                    record.snapshot.status = AgentStatus::Working;
621                    record.awaiting_agent_settle |= waits_for_agent;
622                    record.snapshot.updated_at_ms = now_ms();
623                }
624                self.record_event(&id, "requestStarted", Value::String(request_id));
625            }
626            WorkerEvent::Pi(id, value) => {
627                if let Some(record) = self.records.get_mut(&id) {
628                    let event_type = value.get("type").and_then(Value::as_str);
629                    if event_type == Some("agent_settled") && !record.snapshot.status.terminal() {
630                        record.awaiting_agent_settle = false;
631                        record.snapshot.status = AgentStatus::Idle;
632                    }
633                    if event_type == Some("response")
634                        && !record.awaiting_agent_settle
635                        && !record.snapshot.status.terminal()
636                    {
637                        record.snapshot.status = AgentStatus::Idle;
638                    }
639                    record.snapshot.event_count = record.snapshot.event_count.saturating_add(1);
640                    record.snapshot.updated_at_ms = now_ms();
641                    if record.snapshot.evidence.len() == AGENT_EVIDENCE_CAPACITY {
642                        record.snapshot.evidence.remove(0);
643                    }
644                    record.snapshot.evidence.push(value.clone());
645                }
646                let kind = value
647                    .get("type")
648                    .and_then(Value::as_str)
649                    .unwrap_or("piEvent")
650                    .to_string();
651                self.record_event(&id, &kind, value);
652            }
653            WorkerEvent::Failed(id, error) => {
654                if let Some(record) = self.records.get_mut(&id)
655                    && !record.snapshot.status.terminal()
656                {
657                    record.snapshot.status = AgentStatus::Failed;
658                    record.snapshot.last_error = Some(error.clone());
659                    record.snapshot.updated_at_ms = now_ms();
660                    record.command = None;
661                }
662                self.record_event(&id, "failed", Value::String(error));
663            }
664            WorkerEvent::Stopped(id) => {
665                if let Some(record) = self.records.get_mut(&id) {
666                    record.command = None;
667                }
668                self.record_event(&id, "stopped", Value::Null);
669            }
670        }
671    }
672
673    fn join_worker(&mut self, id: &AgentId, terminal: AgentStatus) -> DevelopmentResult<()> {
674        let worker = self.record_mut(id)?.worker.take();
675        if let Some(worker) = worker
676            && worker.join().is_err()
677        {
678            let error = format!("agent {} worker panicked", id.as_str());
679            let record = self.record_mut(id)?;
680            record.command = None;
681            record.snapshot.status = AgentStatus::Failed;
682            record.snapshot.last_error = Some(error.clone());
683            record.snapshot.updated_at_ms = now_ms();
684            self.record_event(
685                id,
686                "workerPanicked",
687                serde_json::json!({"agentId":id.as_str(),"error":error}),
688            );
689            return Err(DevelopmentError::Process(error));
690        }
691        let record = self.record_mut(id)?;
692        record.command = None;
693        record.snapshot.status = terminal;
694        record.snapshot.updated_at_ms = now_ms();
695        Ok(())
696    }
697
698    fn reap_finished_workers(&mut self) {
699        let finished = self
700            .records
701            .iter()
702            .filter(|(_, record)| {
703                record
704                    .worker
705                    .as_ref()
706                    .is_some_and(|worker| worker.is_finished())
707            })
708            .map(|(id, _)| id.clone())
709            .collect::<Vec<_>>();
710        for id in finished {
711            let worker = self
712                .records
713                .get_mut(&id)
714                .and_then(|record| record.worker.take());
715            let panicked = worker.is_some_and(|worker| worker.join().is_err());
716            let mut event = None;
717            if let Some(record) = self.records.get_mut(&id) {
718                record.command = None;
719                if panicked {
720                    let error = format!("agent {} worker panicked", id.as_str());
721                    record.snapshot.status = AgentStatus::Failed;
722                    record.snapshot.last_error = Some(error.clone());
723                    record.snapshot.updated_at_ms = now_ms();
724                    event = Some((
725                        "workerPanicked",
726                        serde_json::json!({
727                            "agentId":id.as_str(),
728                            "role":record.snapshot.role.clone(),
729                            "task":record.snapshot.task.clone(),
730                            "error":error,
731                        }),
732                    ));
733                } else if !record.snapshot.status.terminal() {
734                    let error = format!(
735                        "agent {} worker exited before a terminal outcome",
736                        id.as_str()
737                    );
738                    record.snapshot.status = AgentStatus::Failed;
739                    record.snapshot.last_error = Some(error.clone());
740                    record.snapshot.updated_at_ms = now_ms();
741                    event = Some(("workerExited", Value::String(error)));
742                }
743            }
744            if let Some((kind, payload)) = event {
745                self.record_event(&id, kind, payload);
746            }
747        }
748    }
749
750    fn record_event(&mut self, id: &AgentId, kind: &str, payload: Value) {
751        if self.history.len() == HISTORY_CAPACITY {
752            self.history.pop_front();
753        }
754        self.history.push_back(AgentEvent {
755            sequence: self.next_event,
756            agent_id: id.clone(),
757            timestamp_ms: now_ms(),
758            kind: kind.into(),
759            payload,
760        });
761        self.next_event = self.next_event.saturating_add(1);
762    }
763
764    fn record_mut(&mut self, id: &AgentId) -> DevelopmentResult<&mut AgentRecord> {
765        self.records
766            .get_mut(id)
767            .ok_or_else(|| DevelopmentError::NotFound(format!("agent {}", id.as_str())))
768    }
769}
770
771impl Drop for AgentRegistry {
772    fn drop(&mut self) {
773        let mut workers = Vec::new();
774        for (id, record) in &mut self.records {
775            if let Some(sender) = record.command.take() {
776                let _ = sender.try_send(WorkerCommand::Shutdown);
777            }
778            if let Some(worker) = record.worker.take() {
779                workers.push((id.clone(), worker));
780            }
781        }
782        for (id, worker) in workers {
783            if worker.join().is_err() {
784                tracing::error!(agent_id = %id.as_str(), "agent worker panicked during registry drop");
785            }
786        }
787    }
788}
789
790fn run_worker(
791    id: AgentId,
792    spec: AgentSpec,
793    runtime: WorkerRuntime,
794    commands: Receiver<WorkerCommand>,
795    events: SyncSender<WorkerEvent>,
796    dropped_events: Arc<AtomicU64>,
797) {
798    let options = PiRuntimeOptions {
799        unrestricted: spec.unrestricted,
800        session_dir: runtime.sessions_dir,
801        name: Some(format!("{}: {}", spec.role, id.as_str())),
802        model: spec.model,
803        thinking: spec.thinking,
804        broker: runtime.broker,
805        additional_system_prompt: runtime.additional_system_prompt,
806        resume: false,
807    };
808    let mut harness = match GlassPiRuntime::spawn(&runtime.worktree, options) {
809        Ok(harness) => harness,
810        Err(error) => {
811            send_critical_worker_event(&events, WorkerEvent::Failed(id, error.to_string()));
812            return;
813        }
814    };
815    send_critical_worker_event(&events, WorkerEvent::Ready(id.clone()));
816    loop {
817        loop {
818            match commands.try_recv() {
819                Ok(WorkerCommand::Request(request)) => {
820                    let waits_for_agent = matches!(
821                        request,
822                        PiSessionRequest::Prompt { .. } | PiSessionRequest::FollowUp { .. }
823                    );
824                    match harness.start_request(request) {
825                        Ok(request_id) => send_critical_worker_event(
826                            &events,
827                            WorkerEvent::RequestStarted(id.clone(), request_id, waits_for_agent),
828                        ),
829                        Err(error) => {
830                            send_critical_worker_event(
831                                &events,
832                                WorkerEvent::Failed(id.clone(), error.to_string()),
833                            );
834                            return;
835                        }
836                    }
837                }
838                Ok(WorkerCommand::Shutdown) | Err(TryRecvError::Disconnected) => {
839                    send_critical_worker_event(&events, WorkerEvent::Stopped(id));
840                    return;
841                }
842                Err(TryRecvError::Empty) => break,
843            }
844        }
845        match harness.recv_event_timeout(Duration::from_millis(25)) {
846            Ok(Some(value)) => send_lossy_worker_event(
847                &events,
848                WorkerEvent::Pi(id.clone(), value),
849                &dropped_events,
850            ),
851            Ok(None) => {}
852            Err(error) => {
853                send_critical_worker_event(&events, WorkerEvent::Failed(id, error.to_string()));
854                return;
855            }
856        }
857    }
858}
859
860fn send_lossy_worker_event(
861    events: &SyncSender<WorkerEvent>,
862    event: WorkerEvent,
863    dropped_events: &AtomicU64,
864) {
865    if matches!(events.try_send(event), Err(TrySendError::Full(_))) {
866        dropped_events.fetch_add(1, Ordering::Relaxed);
867    }
868}
869
870fn send_critical_worker_event(events: &SyncSender<WorkerEvent>, event: WorkerEvent) {
871    let _ = events.send(event);
872}
873
874fn validate_spec(
875    root: &Path,
876    records: &BTreeMap<AgentId, AgentRecord>,
877    spec: &AgentSpec,
878) -> DevelopmentResult<()> {
879    validate_text("agent role", &spec.role, 128)?;
880    validate_text("agent task", &spec.task, MAX_PROMPT_BYTES)?;
881    if spec.dependencies.len() > MAX_AGENTS {
882        return Err(DevelopmentError::InvalidInput(
883            "agent dependency list is too large".into(),
884        ));
885    }
886    let mut unique = BTreeSet::new();
887    for dependency in &spec.dependencies {
888        if !unique.insert(dependency) {
889            return Err(DevelopmentError::InvalidInput(format!(
890                "duplicate dependency {}",
891                dependency.as_str()
892            )));
893        }
894        if !records.contains_key(dependency) {
895            return Err(DevelopmentError::NotFound(format!(
896                "dependency agent {}",
897                dependency.as_str()
898            )));
899        }
900    }
901    if let Some(worktree) = &spec.worktree {
902        let worktree = std::fs::canonicalize(worktree)?;
903        if worktree == Path::new("/")
904            || (!worktree.starts_with(root) && !worktree.join(".git").exists())
905        {
906            return Err(DevelopmentError::PathOutsideWorkspace(worktree));
907        }
908    }
909    if spec.max_runtime_seconds == Some(0) || spec.max_events == Some(0) {
910        return Err(DevelopmentError::InvalidInput(
911            "agent budgets must be greater than zero".into(),
912        ));
913    }
914    Ok(())
915}
916
917fn validate_text(description: &str, text: &str, limit: usize) -> DevelopmentResult<()> {
918    if text.trim().is_empty() || text.len() > limit || text.contains('\0') {
919        return Err(DevelopmentError::InvalidInput(format!(
920            "{description} must contain 1..={limit} bytes without NUL"
921        )));
922    }
923    Ok(())
924}
925
926fn now_ms() -> u128 {
927    SystemTime::now()
928        .duration_since(UNIX_EPOCH)
929        .unwrap_or_default()
930        .as_millis()
931}
932
933#[cfg(test)]
934mod tests {
935    use super::*;
936    use std::sync::atomic::{AtomicU64, Ordering};
937
938    static NEXT_ROOT: AtomicU64 = AtomicU64::new(0);
939
940    fn test_root() -> PathBuf {
941        let sequence = NEXT_ROOT.fetch_add(1, Ordering::Relaxed);
942        let root = std::env::temp_dir().join(format!(
943            "glass-agent-registry-{}-{sequence}",
944            std::process::id()
945        ));
946        std::fs::create_dir_all(&root).unwrap();
947        root
948    }
949
950    #[test]
951    fn lossy_worker_queue_reports_dropped_events() {
952        let (sender, _receiver) = mpsc::sync_channel(1);
953        let id = AgentId::parse("agent-overflow").unwrap();
954        sender.send(WorkerEvent::Ready(id.clone())).unwrap();
955        let dropped = AtomicU64::new(0);
956        send_lossy_worker_event(
957            &sender,
958            WorkerEvent::Pi(id, serde_json::json!({"type":"delta"})),
959            &dropped,
960        );
961        assert_eq!(dropped.load(Ordering::Relaxed), 1);
962    }
963
964    fn insert_test_worker(
965        registry: &mut AgentRegistry,
966        id: AgentId,
967        command: SyncSender<WorkerCommand>,
968        worker: thread::JoinHandle<()>,
969    ) {
970        let spec = AgentSpec::new("lifecycle-test", "prove worker ownership");
971        let now = now_ms();
972        registry.records.insert(
973            id.clone(),
974            AgentRecord {
975                snapshot: AgentSnapshot {
976                    id,
977                    role: spec.role.clone(),
978                    task: spec.task.clone(),
979                    status: AgentStatus::Working,
980                    dependencies: Vec::new(),
981                    model: None,
982                    thinking: None,
983                    worktree: registry.root.clone(),
984                    unrestricted: false,
985                    created_at_ms: now,
986                    started_at_ms: Some(now),
987                    updated_at_ms: now,
988                    event_count: 0,
989                    dropped_event_count: 0,
990                    last_error: None,
991                    last_response_id: None,
992                    evidence: Vec::new(),
993                },
994                spec,
995                command: Some(command),
996                worker: Some(worker),
997                awaiting_agent_settle: false,
998                dropped_events: Arc::new(AtomicU64::new(0)),
999            },
1000        );
1001    }
1002
1003    #[test]
1004    fn repeated_cancel_joins_every_owned_worker() {
1005        let root = test_root();
1006        let mut registry = AgentRegistry::new(&root).unwrap();
1007        let exited = Arc::new(AtomicU64::new(0));
1008        for sequence in 0..128 {
1009            let id = AgentId::parse(format!("agent-test-{sequence}")).unwrap();
1010            let (command, commands) = mpsc::sync_channel(COMMAND_CAPACITY);
1011            let exits = Arc::clone(&exited);
1012            let worker = thread::spawn(move || {
1013                while let Ok(command) = commands.recv() {
1014                    if matches!(command, WorkerCommand::Shutdown) {
1015                        break;
1016                    }
1017                }
1018                exits.fetch_add(1, Ordering::SeqCst);
1019            });
1020            insert_test_worker(&mut registry, id.clone(), command, worker);
1021            registry.cancel(&id).unwrap();
1022            let record = registry.records.get(&id).unwrap();
1023            assert_eq!(record.snapshot.status, AgentStatus::Cancelled);
1024            assert!(record.worker.is_none());
1025        }
1026        assert_eq!(exited.load(Ordering::SeqCst), 128);
1027        drop(registry);
1028        std::fs::remove_dir_all(root).unwrap();
1029    }
1030
1031    #[test]
1032    fn worker_panic_becomes_attributed_agent_failure() {
1033        let root = test_root();
1034        let mut registry = AgentRegistry::new(&root).unwrap();
1035        let id = AgentId::parse("agent-panic-test").unwrap();
1036        let (command, _commands) = mpsc::sync_channel(COMMAND_CAPACITY);
1037        let worker = thread::spawn(|| panic!("intentional worker panic"));
1038        worker.thread().unpark();
1039        insert_test_worker(&mut registry, id.clone(), command, worker);
1040        for _ in 0..100 {
1041            registry.refresh().unwrap();
1042            if registry.records[&id].snapshot.status == AgentStatus::Failed {
1043                break;
1044            }
1045            thread::sleep(Duration::from_millis(5));
1046        }
1047        let snapshot = registry.snapshot(&id).unwrap();
1048        assert_eq!(snapshot.status, AgentStatus::Failed);
1049        assert!(snapshot.last_error.unwrap().contains(id.as_str()));
1050        assert!(registry.history(0).unwrap().iter().any(|event| {
1051            event.agent_id == id
1052                && event.kind == "workerPanicked"
1053                && event.payload["role"] == "lifecycle-test"
1054        }));
1055        drop(registry);
1056        std::fs::remove_dir_all(root).unwrap();
1057    }
1058
1059    fn wait_for_status(
1060        registry: &mut AgentRegistry,
1061        id: &AgentId,
1062        expected: AgentStatus,
1063    ) -> AgentSnapshot {
1064        for _ in 0..200 {
1065            let snapshot = registry.snapshot(id).unwrap();
1066            if snapshot.status == expected {
1067                return snapshot;
1068            }
1069            if snapshot.status == AgentStatus::Failed {
1070                panic!("agent failed: {:?}", snapshot.last_error);
1071            }
1072            thread::sleep(Duration::from_millis(25));
1073        }
1074        panic!("agent did not reach {expected:?}");
1075    }
1076
1077    #[test]
1078    fn independent_pi_sessions_schedule_dependencies_and_stream_state() {
1079        if std::process::Command::new("pi")
1080            .arg("--version")
1081            .output()
1082            .is_err()
1083        {
1084            return;
1085        }
1086        let root = test_root();
1087        let mut registry = AgentRegistry::new(&root).unwrap();
1088        let first = registry
1089            .create(AgentSpec::new("implementer", "inspect state"))
1090            .unwrap();
1091        let peer = registry
1092            .create(AgentSpec::new("researcher", "inspect independent state"))
1093            .unwrap();
1094        wait_for_status(&mut registry, &first, AgentStatus::Idle);
1095        wait_for_status(&mut registry, &peer, AgentStatus::Idle);
1096        registry.request(&first, PiSessionRequest::State).unwrap();
1097        registry.request(&peer, PiSessionRequest::State).unwrap();
1098        for _ in 0..200 {
1099            let snapshot = registry.snapshot(&first).unwrap();
1100            if snapshot
1101                .evidence
1102                .iter()
1103                .any(|event| event.get("type").and_then(Value::as_str) == Some("response"))
1104            {
1105                break;
1106            }
1107            thread::sleep(Duration::from_millis(25));
1108        }
1109        assert!(registry.snapshot(&first).unwrap().event_count > 0);
1110        for _ in 0..200 {
1111            if registry.snapshot(&peer).unwrap().event_count > 0 {
1112                break;
1113            }
1114            thread::sleep(Duration::from_millis(25));
1115        }
1116        assert!(registry.snapshot(&peer).unwrap().event_count > 0);
1117
1118        let mut dependent = AgentSpec::new("reviewer", "review evidence");
1119        dependent.dependencies.push(first.clone());
1120        let second = registry.create(dependent).unwrap();
1121        assert_eq!(
1122            registry.snapshot(&second).unwrap().status,
1123            AgentStatus::Queued
1124        );
1125        registry.complete(&first).unwrap();
1126        wait_for_status(&mut registry, &second, AgentStatus::Idle);
1127        assert_ne!(first, second);
1128        registry.cancel(&second).unwrap();
1129        registry.cancel(&peer).unwrap();
1130        assert_eq!(
1131            registry.snapshot(&second).unwrap().status,
1132            AgentStatus::Cancelled
1133        );
1134        drop(registry);
1135        std::fs::remove_dir_all(root).unwrap();
1136    }
1137
1138    #[test]
1139    fn invalid_agent_specs_and_failed_dependencies_fail_closed() {
1140        let root = test_root();
1141        let mut registry = AgentRegistry::new(&root).unwrap();
1142        assert!(registry.create(AgentSpec::new("", "task")).is_err());
1143        let first = registry.create(AgentSpec::new("lead", "task")).unwrap();
1144        let mut dependent = AgentSpec::new("review", "task");
1145        dependent.dependencies.push(first.clone());
1146        let second = registry.create(dependent).unwrap();
1147        registry.cancel(&first).unwrap();
1148        assert_eq!(
1149            registry.snapshot(&second).unwrap().status,
1150            AgentStatus::Failed
1151        );
1152        drop(registry);
1153        std::fs::remove_dir_all(root).unwrap();
1154    }
1155}