cap-rs-orchestrator 0.1.0

Fleet orchestration engine for CAP (CLI Agent Protocol) — declarative YAML-driven multi-agent coordination.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

//! Types crossing the engine↔consumer boundary. This boundary is an in-process
//! `mpsc` channel today and the seam for the future remote (WebSocket) layer.

use cap_rs::core::{AgentEvent, AskKind, AskOption, ReverseRpc, RiskLevel, StopReason};

use crate::config::SessionId;

/// Everything the engine emits outward, tagged by session where applicable.
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub enum OrchestratorEvent {
    SessionStarted {
        session: SessionId,
    },
    /// A raw agent event, tagged with its originating session.
    Agent {
        session: SessionId,
        event: AgentEvent,
    },
    /// A permission request awaiting a human decision (only under `ask` policy).
    Ask {
        session: SessionId,
        req_id: String,
        tool: String,
        risk_level: RiskLevel,
    },
    /// An `ask_user` event from the agent awaiting a human answer (spec §7.5).
    AskUser {
        session: SessionId,
        ask_id: String,
        prompt: String,
        ask_kind: AskKind,
        options: Vec<AskOption>,
    },
    /// A Reverse RPC call from the agent to the orchestrator (§8).
    ReverseRpc {
        session: SessionId,
        rpc_id: String,
        rpc: ReverseRpc,
    },
    /// The engine routed one session's output into another's inbox.
    Routed {
        from: SessionId,
        to: SessionId,
    },
    SessionDone {
        session: SessionId,
        stop_reason: StopReason,
    },
    SessionFailed {
        session: SessionId,
        error: String,
    },
    /// A `collect: human` join completed; these candidate sessions await a pick.
    AwaitSelection {
        candidates: Vec<SessionId>,
    },
    FleetComplete,
}

/// Everything the consumer sends back in (decisions, selections, cancel).
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub enum OrchestratorControl {
    /// Answer to an [`OrchestratorEvent::Ask`].
    Decision {
        session: SessionId,
        req_id: String,
        allow: bool,
    },
    /// Answer to an [`OrchestratorEvent::AskUser`].
    AskUserResponse {
        session: SessionId,
        ask_id: String,
        value: serde_json::Value,
    },
    /// Answer to an [`OrchestratorEvent::ReverseRpc`].
    ReverseRpcResult {
        session: SessionId,
        rpc_id: String,
        result: cap_rs::core::ReverseRpcResult,
    },
    /// Answer to an [`OrchestratorEvent::AwaitSelection`].
    Select { session: SessionId },
    /// Inject a user message into a running session's inbox.
    UserMessage { session: SessionId, text: String },
    /// Hard-cancel the whole fleet.
    Cancel,
}