Skip to main content

qualia_core_db/agent_runtime/
orchestration.rs

1//! Multi-agent orchestration — roster agents, blackboard wiring, governance gates.
2//!
3//! Connects the agent_runtime planner, DAG executor, blackboard bus, and
4//! deontic governance into a single orchestration layer that can be driven
5//! from VibeScript.
6//!
7//! The orchestration flow:
8//! 1. Register agents in a roster with their capabilities and DID.
9//! 2. Create an orchestration session with a task description.
10//! 3. The planner produces a DAG from the task + available capabilities.
11//! 4. The DAG executor runs nodes in topological order, wiring blackboard I/O.
12//! 5. Governance gates check capabilities before each node executes.
13//! 6. Results are collected and returned as a structured record.
14
15use crate::modalities::blackboard::BlackboardBus;
16use crate::NQuin;
17use std::collections::BTreeMap;
18use vibe::dag::{DagEdge, DagNode, DagPipeline, NodeEffect};
19use vibe::deontic_interrupt::{Phase, PhaseLeaser};
20
21/// An agent in the roster.
22#[derive(Debug, Clone)]
23pub struct RosterAgent {
24    pub id: String,
25    pub did: String,
26    pub name: String,
27    pub capabilities: Vec<String>,
28    pub role: AgentRole,
29    pub active: bool,
30}
31
32/// Functional role a roster agent plays in an orchestration.
33#[derive(Debug, Clone, Copy, PartialEq, Eq)]
34pub enum AgentRole {
35    /// Gathers source material and evidence.
36    Researcher,
37    /// Interprets and evaluates material.
38    Analyst,
39    /// Combines inputs into coherent outputs.
40    Synthesiser,
41    /// Checks outputs for correctness.
42    Verifier,
43    /// Produces the final delivered record.
44    Reporter,
45    /// Coordinates the other agents.
46    Orchestrator,
47    /// Role defined by the caller.
48    Custom,
49}
50
51impl RosterAgent {
52    /// Create an active agent with an empty capability set.
53    pub fn new(id: &str, did: &str, name: &str, role: AgentRole) -> Self {
54        Self {
55            id: id.to_string(),
56            did: did.to_string(),
57            name: name.to_string(),
58            capabilities: Vec::new(),
59            role,
60            active: true,
61        }
62    }
63
64    /// Append a capability string (e.g. a vibe `Family.name`) to the agent.
65    pub fn add_capability(&mut self, cap: &str) {
66        self.capabilities.push(cap.to_string());
67    }
68
69    /// True when the agent advertises `cap`.
70    pub fn has_capability(&self, cap: &str) -> bool {
71        self.capabilities.iter().any(|c| c == cap)
72    }
73}
74
75/// The agent roster — a collection of agents available for orchestration.
76#[derive(Debug, Clone, Default)]
77pub struct AgentRoster {
78    pub agents: BTreeMap<String, RosterAgent>,
79}
80
81impl AgentRoster {
82    /// Create an empty roster.
83    pub fn new() -> Self {
84        Self::default()
85    }
86
87    /// Insert or replace an agent keyed by its `id`.
88    pub fn register(&mut self, agent: RosterAgent) {
89        self.agents.insert(agent.id.clone(), agent);
90    }
91
92    /// Remove an agent by id; true when one was present.
93    pub fn unregister(&mut self, agent_id: &str) -> bool {
94        self.agents.remove(agent_id).is_some()
95    }
96
97    /// Look up an agent by id.
98    pub fn get(&self, agent_id: &str) -> Option<&RosterAgent> {
99        self.agents.get(agent_id)
100    }
101
102    /// Sorted, de-duplicated capabilities across all active agents.
103    pub fn all_capabilities(&self) -> Vec<String> {
104        let mut caps: Vec<String> = self
105            .agents
106            .values()
107            .filter(|a| a.active)
108            .flat_map(|a| a.capabilities.iter().cloned())
109            .collect();
110        caps.sort();
111        caps.dedup();
112        caps
113    }
114
115    /// All agents currently marked active.
116    pub fn active_agents(&self) -> Vec<&RosterAgent> {
117        self.agents.values().filter(|a| a.active).collect()
118    }
119
120    /// First active agent advertising `cap` (BTreeMap id order).
121    pub fn find_agent_for_capability(&self, cap: &str) -> Option<&RosterAgent> {
122        self.agents
123            .values()
124            .find(|a| a.active && a.has_capability(cap))
125    }
126
127    /// Number of registered agents (active and inactive).
128    pub fn count(&self) -> usize {
129        self.agents.len()
130    }
131}
132
133/// An orchestration session — a task to be executed by the roster.
134#[derive(Debug, Clone)]
135pub struct OrchestrationSession {
136    pub id: String,
137    pub task: String,
138    pub roster: AgentRoster,
139    pub plan: Option<crate::agent_runtime::planner::AgentPlan>,
140    pub status: OrchestrationStatus,
141    pub results: Vec<NodeExecutionResult>,
142}
143
144/// Lifecycle state of an orchestration session.
145#[derive(Debug, Clone, Copy, PartialEq, Eq)]
146pub enum OrchestrationStatus {
147    /// Session created; no plan yet.
148    Created,
149    /// Plan produced; not yet executing.
150    Planning,
151    /// DAG pipeline is running.
152    Executing,
153    /// All nodes completed successfully.
154    Completed,
155    /// Execution failed (pipeline error or node failure).
156    Failed,
157    /// Stopped by a deontic interrupt before completion.
158    Halted,
159}
160
161impl OrchestrationStatus {
162    /// Lowercase wire/summary label for the status.
163    pub fn as_str(&self) -> &'static str {
164        match self {
165            Self::Created => "created",
166            Self::Planning => "planning",
167            Self::Executing => "executing",
168            Self::Completed => "completed",
169            Self::Failed => "failed",
170            Self::Halted => "halted",
171        }
172    }
173}
174
175/// Result of executing a single node in the orchestration.
176#[derive(Debug, Clone)]
177pub struct NodeExecutionResult {
178    pub node_id: u32,
179    pub node_name: String,
180    pub agent_id: Option<String>,
181    pub success: bool,
182    pub outputs: Vec<(String, String)>, // (channel, summary)
183    pub diagnostics: Vec<String>,
184}
185
186/// Create a new orchestration session.
187pub fn create_session(id: &str, task: &str) -> OrchestrationSession {
188    OrchestrationSession {
189        id: id.to_string(),
190        task: task.to_string(),
191        roster: AgentRoster::new(),
192        plan: None,
193        status: OrchestrationStatus::Created,
194        results: Vec::new(),
195    }
196}
197
198/// Plan the orchestration — use the planner to produce a DAG from the task
199/// and the roster's combined capabilities.
200pub fn plan_session(session: &mut OrchestrationSession) -> Result<(), String> {
201    let caps = session.roster.all_capabilities();
202    if caps.is_empty() {
203        return Err("no capabilities available in roster".into());
204    }
205    let plan = crate::agent_runtime::planner::plan_task(&session.task, &caps);
206    session.plan = Some(plan);
207    session.status = OrchestrationStatus::Planning;
208    Ok(())
209}
210
211/// Assign agents to planned steps based on capability matching.
212pub fn assign_agents(session: &mut OrchestrationSession) -> Vec<(u32, String)> {
213    let plan = match &session.plan {
214        Some(p) => p,
215        None => return Vec::new(),
216    };
217    let mut assignments = Vec::new();
218    for step in &plan.steps {
219        if let Some(agent) = session.roster.find_agent_for_capability(&step.capability) {
220            assignments.push((step.id, agent.id.clone()));
221        }
222    }
223    assignments
224}
225
226/// A NodeExecutor that routes DAG node execution to roster agents.
227///
228/// Each node's capability is matched to an agent in the roster. The executor
229/// produces structured outputs for each node based on the plan's output
230/// channels. This is a deterministic executor — it does not call LLM
231/// inference, but it does run the full DAG pipeline through the real
232/// `dag_executor::execute_pipeline`, including blackboard I/O, phase lease
233/// gating, and deontic interrupt handling.
234struct RosterNodeExecutor {
235    assignments: Vec<(u32, String)>,
236}
237
238impl crate::poet_host::invoke::agent::dag_executor::NodeExecutor for RosterNodeExecutor {
239    fn execute(
240        &mut self,
241        node_id: u32,
242        node_name: &str,
243        inputs: &[(String, Vec<NQuin>)],
244        capabilities: &[String],
245    ) -> Result<Vec<(String, Vec<NQuin>)>, vibe::Diagnostic> {
246        // Find the assigned agent for this node.
247        let _agent_id = self
248            .assignments
249            .iter()
250            .find(|(id, _)| *id == node_id)
251            .map(|(_, aid)| aid.clone());
252
253        // Process and forward all input channel quins with node provenance metadata.
254        let mut outputs = Vec::new();
255        for (channel, quins) in inputs {
256            if !quins.is_empty() {
257                let mut processed = quins.clone();
258                for q in &mut processed {
259                    // Stamp node execution into Lamport clock / metadata tracking
260                    q.metadata = (q.metadata & !0xFFFF_u64) | (node_id as u64 & 0xFFFF);
261                    q.parity = q.subject ^ q.predicate ^ q.object ^ q.context;
262                }
263                outputs.push((channel.clone(), processed));
264            }
265        }
266        // If no channel inputs were provided, produce an initial step token for this node.
267        if outputs.is_empty() {
268            let subject = crate::q_hash(node_name);
269            let predicate = crate::q_hash("agent:step");
270            let object = node_id as u64;
271            let context = 0;
272            let metadata = node_id as u64;
273            let parity = subject ^ predicate ^ object ^ context;
274
275            outputs.push((
276                format!("{node_name}_out"),
277                vec![NQuin {
278                    subject,
279                    predicate,
280                    object,
281                    context,
282                    metadata,
283                    parity,
284                }],
285            ));
286        }
287        let _ = capabilities; // capabilities checked by phase leaser
288        Ok(outputs)
289    }
290}
291
292/// Execute the orchestration session — run the planned DAG through the real
293/// `dag_executor::execute_pipeline` with blackboard I/O, phase lease gating,
294/// and deontic interrupt handling.
295pub fn execute_session(session: &mut OrchestrationSession) -> Result<(), String> {
296    let pipeline = session_to_pipeline(session)
297        .ok_or_else(|| "no plan — call plan_session first".to_string())?;
298    session.status = OrchestrationStatus::Executing;
299    let assignments = assign_agents(session);
300
301    // Build blackboard and phase leaser.
302    let mut bus = BlackboardBus::new();
303    let mut leaser = create_phase_leaser(session);
304
305    // Create the roster-based node executor.
306    let mut executor = RosterNodeExecutor {
307        assignments: assignments.clone(),
308    };
309
310    // Run the real DAG executor.
311    let result = crate::poet_host::invoke::agent::dag_executor::execute_pipeline(
312        &pipeline,
313        &mut bus,
314        Some(&mut leaser),
315        &mut executor,
316    );
317
318    // Convert pipeline results to session results.
319    match result {
320        Ok(pipeline_result) => {
321            for nr in &pipeline_result.node_results {
322                let agent_id = assignments
323                    .iter()
324                    .find(|(id, _)| *id == nr.node_id)
325                    .map(|(_, aid)| aid.clone());
326                session.results.push(NodeExecutionResult {
327                    node_id: nr.node_id,
328                    node_name: nr.node_name.clone(),
329                    agent_id,
330                    success: nr.success,
331                    outputs: nr
332                        .outputs
333                        .iter()
334                        .map(|(ch, quins)| (ch.clone(), format!("{} quins", quins.len())))
335                        .collect(),
336                    diagnostics: nr.diagnostics.iter().map(|d| format!("{:?}", d)).collect(),
337                });
338            }
339            if pipeline_result.success {
340                session.status = OrchestrationStatus::Completed;
341            } else if pipeline_result.interrupt.is_some() {
342                session.status = OrchestrationStatus::Halted;
343            } else {
344                session.status = OrchestrationStatus::Failed;
345            }
346            Ok(())
347        }
348        Err(e) => {
349            session.status = OrchestrationStatus::Failed;
350            Err(format!("DAG execution failed: {e:?}"))
351        }
352    }
353}
354
355/// Build a DAG pipeline from an orchestration session's plan.
356pub fn session_to_pipeline(session: &OrchestrationSession) -> Option<DagPipeline> {
357    let plan = session.plan.as_ref()?;
358    let mut pipeline = DagPipeline::new();
359    // Add all nodes first.
360    for step in &plan.steps {
361        let effect = match step.effect {
362            "pure" => NodeEffect::Pure,
363            "hot" => NodeEffect::Hot,
364            "cold" => NodeEffect::Cold,
365            "async" => NodeEffect::Async,
366            "external" => NodeEffect::External,
367            _ => NodeEffect::Pure,
368        };
369        let mut node = DagNode::new(step.id, &step.name, effect).with_budget(step.budget);
370        if !step.capability.is_empty() {
371            node = node.with_capability(&step.capability);
372        }
373        for input in &step.inputs {
374            node = node.with_input(input);
375        }
376        for output in &step.outputs {
377            node = node.with_output(output);
378        }
379        let _ = pipeline.add_node(node);
380    }
381    // Add dependency edges.
382    for step in &plan.steps {
383        for &dep_id in &step.depends_on {
384            let _ = pipeline.add_edge(DagEdge::new(dep_id, step.id));
385        }
386    }
387    Some(pipeline)
388}
389
390/// Create a blackboard bus for an orchestration session.
391pub fn create_blackboard(_session: &OrchestrationSession) -> BlackboardBus {
392    BlackboardBus::new()
393}
394
395/// Create a phase leaser for governance gating, seeded from the roster's
396/// capabilities. The leaser is registered with a single "execution" phase
397/// that allows all roster capabilities.
398pub fn create_phase_leaser(session: &OrchestrationSession) -> PhaseLeaser {
399    let mut leaser = PhaseLeaser::new();
400    let caps = session.roster.all_capabilities();
401    let mut phase = Phase::new("execution");
402    for cap in caps {
403        phase = phase.allow(&cap);
404    }
405    let _ = leaser.register_phase(phase);
406    let _ = leaser.enter_phase("execution");
407    leaser
408}
409
410/// Summarise the orchestration session as a structured record.
411pub fn session_summary(session: &OrchestrationSession) -> BTreeMap<String, String> {
412    let mut summary = BTreeMap::new();
413    summary.insert("id".into(), session.id.clone());
414    summary.insert("task".into(), session.task.clone());
415    summary.insert("status".into(), session.status.as_str().into());
416    summary.insert("agent_count".into(), session.roster.count().to_string());
417    summary.insert("node_count".into(), session.results.len().to_string());
418    let completed = session.results.iter().filter(|r| r.success).count();
419    summary.insert("nodes_completed".into(), completed.to_string());
420    summary
421}
422
423#[cfg(test)]
424mod tests {
425    use super::*;
426
427    #[test]
428    fn roster_register_and_lookup() {
429        let mut roster = AgentRoster::new();
430        let mut agent = RosterAgent::new("a1", "did:q42:alice", "Alice", AgentRole::Researcher);
431        agent.add_capability("NLP.substrate_extract");
432        roster.register(agent);
433        assert_eq!(roster.count(), 1);
434        assert!(roster.get("a1").is_some());
435        assert!(roster
436            .find_agent_for_capability("NLP.substrate_extract")
437            .is_some());
438    }
439
440    #[test]
441    fn roster_unregister() {
442        let mut roster = AgentRoster::new();
443        roster.register(RosterAgent::new(
444            "a1",
445            "did:q42:a",
446            "A",
447            AgentRole::Researcher,
448        ));
449        assert!(roster.unregister("a1"));
450        assert_eq!(roster.count(), 0);
451    }
452
453    #[test]
454    fn roster_all_capabilities() {
455        let mut roster = AgentRoster::new();
456        let mut a1 = RosterAgent::new("a1", "d1", "A", AgentRole::Researcher);
457        a1.add_capability("cap_a");
458        let mut a2 = RosterAgent::new("a2", "d2", "B", AgentRole::Analyst);
459        a2.add_capability("cap_b");
460        a2.add_capability("cap_a");
461        roster.register(a1);
462        roster.register(a2);
463        let caps = roster.all_capabilities();
464        assert_eq!(caps.len(), 2);
465        assert!(caps.contains(&"cap_a".to_string()));
466        assert!(caps.contains(&"cap_b".to_string()));
467    }
468
469    #[test]
470    fn create_session_basic() {
471        let session = create_session("s1", "Research climate impacts");
472        assert_eq!(session.id, "s1");
473        assert_eq!(session.status, OrchestrationStatus::Created);
474        assert_eq!(session.roster.count(), 0);
475    }
476
477    #[test]
478    fn plan_session_no_caps() {
479        let mut session = create_session("s1", "Research");
480        let result = plan_session(&mut session);
481        assert!(result.is_err());
482    }
483
484    #[test]
485    fn plan_session_with_caps() {
486        let mut session = create_session("s1", "Research climate");
487        let mut agent = RosterAgent::new("a1", "did:q42:a", "A", AgentRole::Researcher);
488        agent.add_capability("NLP.substrate_extract");
489        session.roster.register(agent);
490        let result = plan_session(&mut session);
491        assert!(result.is_ok());
492        assert!(session.plan.is_some());
493        assert_eq!(session.status, OrchestrationStatus::Planning);
494    }
495
496    #[test]
497    fn execute_session_completes() {
498        let mut session = create_session("s1", "Research climate");
499        let mut agent = RosterAgent::new("a1", "did:q42:a", "A", AgentRole::Researcher);
500        agent.add_capability("NLP.substrate_extract");
501        session.roster.register(agent);
502        plan_session(&mut session).unwrap();
503        execute_session(&mut session).unwrap();
504        assert_eq!(session.status, OrchestrationStatus::Completed);
505        assert!(!session.results.is_empty());
506    }
507
508    #[test]
509    fn assign_agents_matches() {
510        let mut session = create_session("s1", "Research climate");
511        let mut agent = RosterAgent::new("a1", "did:q42:a", "A", AgentRole::Researcher);
512        agent.add_capability("NLP.substrate_extract");
513        session.roster.register(agent);
514        plan_session(&mut session).unwrap();
515        let assignments = assign_agents(&mut session);
516        assert!(!assignments.is_empty());
517    }
518
519    #[test]
520    fn session_summary_basic() {
521        let mut session = create_session("s1", "Research");
522        let mut agent = RosterAgent::new("a1", "did:q42:a", "A", AgentRole::Researcher);
523        agent.add_capability("NLP.substrate_extract");
524        session.roster.register(agent);
525        plan_session(&mut session).unwrap();
526        execute_session(&mut session).unwrap();
527        let summary = session_summary(&session);
528        assert_eq!(summary.get("status"), Some(&"completed".to_string()));
529        assert_eq!(summary.get("agent_count"), Some(&"1".to_string()));
530    }
531
532    #[test]
533    fn create_blackboard_basic() {
534        let session = create_session("s1", "Research");
535        let _bb = create_blackboard(&session);
536    }
537
538    #[test]
539    fn create_phase_leaser_basic() {
540        let mut session = create_session("s1", "Research");
541        let mut agent = RosterAgent::new("a1", "did:q42:a", "A", AgentRole::Researcher);
542        agent.add_capability("cap_x");
543        session.roster.register(agent);
544        let leaser = create_phase_leaser(&session);
545        assert!(leaser.is_leased("cap_x"));
546    }
547}