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, 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    /// 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    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
179/// Registry and scheduler for independent Pi subprocesses.
180///
181/// Each running agent owns a distinct Pi process and persistent session. The
182/// registry only starts dependency-ready work, bounds all queues and retained
183/// evidence, and never silently promotes a failed dependency to success.
184pub 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    /// Active user-global and trusted-project instructions supplied to Pi.
262    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    /// Restart a failed or cancelled session under the same agent identity.
514    ///
515    /// Interactive callers keep the selected agent id, so retrying after an
516    /// aborted or crashed turn should not strand the composer on a terminal
517    /// worker. Completed sessions remain terminal by design; callers should
518    /// create a new session when they explicitly finished one.
519    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        // A failure event can be observed just before the worker thread
536        // exits. Join it here instead of making the user retry a second time.
537        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}