soothe_client/
events.rs

1//! Client-facing event namespace constants for the Soothe daemon wire protocol.
2//!
3//! Internal catalog types (`soothe.internal.*`) are server-only and are never
4//! broadcast to WebSocket clients.
5
6use crate::verbosity::VerbosityTier;
7
8// ---------------------------------------------------------------------------
9// Plan / goal
10// ---------------------------------------------------------------------------
11
12/// Plan created.
13pub const EVENT_PLAN_CREATED: &str = "soothe.cognition.plan.created";
14/// Plan batch started.
15pub const EVENT_PLAN_BATCH_STARTED: &str = "soothe.cognition.plan.batch.started";
16/// Plan reflected.
17pub const EVENT_PLAN_REFLECTED: &str = "soothe.cognition.plan.reflected";
18
19/// Goal created.
20pub const EVENT_GOAL_CREATED: &str = "soothe.cognition.goal.created";
21/// Goal completed.
22pub const EVENT_GOAL_COMPLETED: &str = "soothe.cognition.goal.completed";
23/// Goal failed.
24pub const EVENT_GOAL_FAILED: &str = "soothe.cognition.goal.failed";
25/// Goal deferred.
26pub const EVENT_GOAL_DEFERRED: &str = "soothe.cognition.goal.deferred";
27/// Goal batch started.
28pub const EVENT_GOAL_BATCH_STARTED: &str = "soothe.cognition.goal.batch.started";
29/// Goal reported.
30pub const EVENT_GOAL_REPORTED: &str = "soothe.cognition.goal.reported";
31/// Goal directives applied.
32pub const EVENT_GOAL_DIRECTIVES_APPLIED: &str = "soothe.cognition.goal.directives.applied";
33
34// ---------------------------------------------------------------------------
35// Subagents
36// ---------------------------------------------------------------------------
37
38/// Deep research started.
39pub const EVENT_DEEP_RESEARCH_STARTED: &str = "soothe.subagent.deep_research.started";
40/// Deep research progress.
41pub const EVENT_DEEP_RESEARCH_PROGRESS: &str = "soothe.subagent.deep_research.progress";
42/// Deep research step completed.
43pub const EVENT_DEEP_RESEARCH_STEP_COMPLETED: &str = "soothe.subagent.deep_research.step.completed";
44/// Deep research gather summary.
45pub const EVENT_DEEP_RESEARCH_GATHER_SUMMARY: &str = "soothe.subagent.deep_research.gather.summary";
46/// Deep research crawl summary.
47pub const EVENT_DEEP_RESEARCH_CRAWL_SUMMARY: &str = "soothe.subagent.deep_research.crawl.summary";
48/// Deep research completed.
49pub const EVENT_DEEP_RESEARCH_COMPLETED: &str = "soothe.subagent.deep_research.completed";
50
51// ---------------------------------------------------------------------------
52// Control / cards / tools
53// ---------------------------------------------------------------------------
54
55/// Replay complete control-plane frame.
56pub const EVENT_REPLAY_COMPLETE: &str = "replay_complete";
57/// Loop reattached control-plane frame.
58pub const EVENT_LOOP_REATTACHED_WIRE: &str = "loop_reattached";
59
60/// Card created.
61pub const EVENT_CARD_CREATED: &str = "soothe.card.created";
62/// Card updated.
63pub const EVENT_CARD_UPDATED: &str = "soothe.card.updated";
64/// Card finalized.
65pub const EVENT_CARD_FINALIZED: &str = "soothe.card.finalized";
66/// Card replay begin.
67pub const EVENT_CARD_REPLAY_BEGIN: &str = "soothe.card.replay.begin";
68/// Card replay end.
69pub const EVENT_CARD_REPLAY_END: &str = "soothe.card.replay.end";
70
71/// Tool started.
72pub const EVENT_TOOL_STARTED: &str = "soothe.tool.execution.started";
73/// Tool completed.
74pub const EVENT_TOOL_COMPLETED: &str = "soothe.tool.execution.completed";
75/// Tool error.
76pub const EVENT_TOOL_ERROR: &str = "soothe.tool.execution.error";
77
78/// Stream tool call update.
79pub const EVENT_STREAM_TOOL_CALL_UPDATE: &str = "soothe.stream.tool_call.update";
80/// Tool call updates batch.
81pub const EVENT_TOOL_CALL_UPDATES_BATCH: &str = "tool_call_updates_batch";
82
83// ---------------------------------------------------------------------------
84// StrangeLoop / branch / protocol / output / autopilot / error
85// ---------------------------------------------------------------------------
86
87/// Strange loop started.
88pub const EVENT_STRANGE_LOOP_STARTED: &str = "soothe.cognition.strange_loop.started";
89/// Strange loop completed.
90pub const EVENT_STRANGE_LOOP_COMPLETED: &str = "soothe.cognition.strange_loop.completed";
91/// Strange loop plan decision.
92pub const EVENT_STRANGE_LOOP_PLAN_DECISION: &str = "soothe.cognition.strange_loop.plan.decision";
93/// Strange loop reasoned.
94pub const EVENT_STRANGE_LOOP_REASONED: &str = "soothe.cognition.strange_loop.reasoned";
95/// Strange loop step started.
96pub const EVENT_STRANGE_LOOP_STEP_STARTED: &str = "soothe.cognition.strange_loop.step.started";
97/// Strange loop step queued.
98pub const EVENT_STRANGE_LOOP_STEP_QUEUED: &str = "soothe.cognition.strange_loop.step.queued";
99/// Strange loop step completed.
100pub const EVENT_STRANGE_LOOP_STEP_COMPLETED: &str = "soothe.cognition.strange_loop.step.completed";
101/// Strange loop context compacted.
102pub const EVENT_STRANGE_LOOP_CONTEXT_COMPACTED: &str =
103    "soothe.cognition.strange_loop.context.compacted";
104
105/// Branch created.
106pub const EVENT_BRANCH_CREATED: &str = "soothe.cognition.branch.created";
107/// Branch retry started.
108pub const EVENT_BRANCH_RETRY_STARTED: &str = "soothe.cognition.branch.retry.started";
109
110/// Message received.
111pub const EVENT_MESSAGE_RECEIVED: &str = "soothe.protocol.message.received";
112/// Message sent.
113pub const EVENT_MESSAGE_SENT: &str = "soothe.protocol.message.sent";
114
115/// Final report.
116pub const EVENT_FINAL_REPORT: &str = "soothe.output.autonomous.final_report.reported";
117
118/// Autopilot status changed.
119pub const EVENT_AUTOPILOT_STATUS_CHANGED: &str = "soothe.system.autopilot.status.changed";
120/// Autopilot goal created.
121pub const EVENT_AUTOPILOT_GOAL_CREATED: &str = "soothe.system.autopilot.goal.created";
122/// Autopilot goal progress.
123pub const EVENT_AUTOPILOT_GOAL_PROGRESS: &str = "soothe.system.autopilot.goal.reported";
124/// Autopilot goal completed.
125pub const EVENT_AUTOPILOT_GOAL_COMPLETED: &str = "soothe.system.autopilot.goal.completed";
126/// Autopilot goal suspended.
127pub const EVENT_AUTOPILOT_GOAL_SUSPENDED: &str = "soothe.system.autopilot.goal.suspended";
128/// Autopilot goal blocked.
129pub const EVENT_AUTOPILOT_GOAL_BLOCKED: &str = "soothe.system.autopilot.goal.blocked";
130/// Autopilot dreaming entered.
131pub const EVENT_AUTOPILOT_DREAMING_ENTERED: &str = "soothe.system.autopilot.dreaming.started";
132/// Autopilot dreaming exited.
133pub const EVENT_AUTOPILOT_DREAMING_EXITED: &str = "soothe.system.autopilot.dreaming.completed";
134
135/// General failure.
136pub const EVENT_GENERAL_FAILED: &str = "soothe.error.general.failed";
137
138/// Parsed 4-segment namespace components.
139#[derive(Debug, Clone, PartialEq, Eq)]
140pub struct ParsedNamespace {
141    /// Domain (e.g. `cognition`).
142    pub domain: String,
143    /// Component (e.g. `plan`).
144    pub component: String,
145    /// Action (e.g. `created`).
146    pub action: String,
147}
148
149/// Split a 4-segment event namespace into domain / component / action.
150///
151/// Returns `None` for non-`soothe.*` paths, short paths, or `soothe.internal.*`.
152pub fn parse_namespace(ns: &str) -> Option<ParsedNamespace> {
153    let parts: Vec<&str> = ns.split('.').collect();
154    if parts.len() < 4 || parts[0] != "soothe" {
155        return None;
156    }
157    if parts[1] == "internal" {
158        return None;
159    }
160    Some(ParsedNamespace {
161        domain: parts[1].to_string(),
162        component: parts[2].to_string(),
163        action: parts[3].to_string(),
164    })
165}
166
167/// Classify an event type / namespace into a verbosity tier.
168pub fn classify_event_verbosity(event_type_or_namespace: &str) -> VerbosityTier {
169    if let Some(parsed) = parse_namespace(event_type_or_namespace) {
170        return classify_by_domain(&parsed.domain, event_type_or_namespace);
171    }
172    classify_by_event_type_string(event_type_or_namespace)
173}
174
175fn classify_by_domain(domain: &str, full: &str) -> VerbosityTier {
176    match domain {
177        "cognition" => VerbosityTier::Normal,
178        "protocol" => VerbosityTier::Detailed,
179        "tool" => VerbosityTier::Internal,
180        "subagent" => classify_subagent_event(full),
181        "autopilot" | "system" => VerbosityTier::Normal,
182        "output" | "error" => VerbosityTier::Quiet,
183        _ => VerbosityTier::Normal,
184    }
185}
186
187fn classify_subagent_event(full: &str) -> VerbosityTier {
188    let Some(parsed) = parse_namespace(full) else {
189        return VerbosityTier::Normal;
190    };
191    match parsed.action.as_str() {
192        "started" | "completed" => VerbosityTier::Normal,
193        _ => VerbosityTier::Detailed,
194    }
195}
196
197fn classify_by_event_type_string(event_type: &str) -> VerbosityTier {
198    if event_type == EVENT_FINAL_REPORT || event_type == EVENT_GENERAL_FAILED {
199        return VerbosityTier::Quiet;
200    }
201    if event_type == EVENT_TOOL_STARTED {
202        return VerbosityTier::Internal;
203    }
204    VerbosityTier::Normal
205}
206
207/// Whether the event type represents a completion milestone.
208pub fn is_completion_event(event_type: &str) -> bool {
209    event_type.ends_with(".completed")
210        || event_type.ends_with(".failed")
211        || event_type == EVENT_GENERAL_FAILED
212}
213
214/// Lifecycle subagent events (started/completed) for progress UI.
215pub fn is_subagent_progress_event(event_type: &str) -> bool {
216    let Some(parsed) = parse_namespace(event_type) else {
217        return false;
218    };
219    parsed.domain == "subagent" && matches!(parsed.action.as_str(), "started" | "completed")
220}
221
222#[cfg(test)]
223mod tests {
224    use super::*;
225
226    #[test]
227    fn parse_valid() {
228        let p = parse_namespace("soothe.cognition.plan.created").unwrap();
229        assert_eq!(p.domain, "cognition");
230        assert_eq!(p.component, "plan");
231        assert_eq!(p.action, "created");
232    }
233
234    #[test]
235    fn reject_internal() {
236        assert!(parse_namespace("soothe.internal.loop.completed").is_none());
237    }
238
239    #[test]
240    fn classify_quiet() {
241        assert_eq!(
242            classify_event_verbosity(EVENT_FINAL_REPORT),
243            VerbosityTier::Quiet
244        );
245    }
246}
soothe_client/events.rs

soothe_client/
events.rs
