Skip to main content

muse_code_sdk/session/
wire_verbs.rs

1//! Session queries and commands the host serves directly: task, skill and
2//! hook lists, workflow pause and resume, recaps, feedback, and side chats.
3//!
4//! Each refuses before sending on a discarded session or a closed client, and
5//! a failure fails only its own call.
6
7use serde::Serialize;
8use serde::de::DeserializeOwned;
9
10use crate::client::FacadeResult;
11use crate::errors::ProtocolError;
12use crate::msp::{
13    FeedbackClassification, FeedbackSubmitParams, FeedbackSubmitResult, HookListParams,
14    HookListResult, RecapRequestParams, RecapRequestResult, SessionSideChatParams,
15    SessionSideChatResult, SkillListParams, SkillListResult, TaskListParams, TaskListResult,
16    WorkflowControlResult, WorkflowPauseParams, WorkflowResumeParams, WorkflowResumeResult,
17};
18
19use super::Session;
20use super::submit::require_accepted;
21
22/// What [`Session::submit_feedback`] sends; the session id is this session's.
23#[derive(Clone, Debug, PartialEq, Eq)]
24pub struct SubmitFeedbackOptions {
25    /// The kind of report.
26    pub classification: FeedbackClassification,
27    /// The report text; the host requires it non-empty for a bug.
28    pub note: String,
29    /// Whether the report may include files.
30    pub with_files: bool,
31    /// Whether to attach this session's record. The host accepts `true` only
32    /// for a bug or a bad result, with `with_files` set.
33    pub attach_session_record: bool,
34    /// An absolute path, on the host's machine, to a bundle of extra files the
35    /// client packed.
36    pub client_artifacts_path: Option<String>,
37}
38
39impl Session {
40    /// Lists this session's running tasks, background and foreground
41    /// (`task/list`).
42    pub async fn list_tasks(&self) -> FacadeResult<TaskListResult> {
43        let params = TaskListParams {
44            session_id: self.inner.session_id.clone(),
45        };
46        self.query("task/list", &params).await
47    }
48
49    /// Lists the skills a user can invoke in this session (`skill/list`).
50    pub async fn list_skills(&self) -> FacadeResult<SkillListResult> {
51        let params = SkillListParams {
52            session_id: self.inner.session_id.clone(),
53        };
54        self.query("skill/list", &params).await
55    }
56
57    /// Lists this session's installed hooks, one row per handler and event
58    /// (`hook/list`).
59    pub async fn list_hooks(&self) -> FacadeResult<HookListResult> {
60        let params = HookListParams {
61            session_id: self.inner.session_id.clone(),
62        };
63        self.query("hook/list", &params).await
64    }
65
66    /// Pauses a running workflow (`workflow/pause`). The result is admission
67    /// only: the pause shows on the workflow item's later events. Pass
68    /// `workflow_run_id` exactly as the workflow item names it.
69    pub async fn pause_workflow(
70        &self,
71        workflow_run_id: impl Into<String>,
72    ) -> FacadeResult<WorkflowControlResult> {
73        let command_id = self.mint_command_id()?;
74        let params = WorkflowPauseParams {
75            session_id: self.inner.session_id.clone(),
76            command_id: command_id.clone(),
77            workflow_run_id: workflow_run_id.into(),
78        };
79        let result: WorkflowControlResult = self.query("workflow/pause", &params).await?;
80        require_echo("workflow/pause", &result.command_id, &command_id)?;
81        require_accepted("workflow/pause", &result.status)?;
82        Ok(result)
83    }
84
85    /// Resumes a paused workflow (`workflow/resume`). The host drives a turn
86    /// for it, a fresh one on an idle session or the running one otherwise,
87    /// and the result names that turn. Pass `workflow_run_id` exactly as the
88    /// workflow item names it.
89    pub async fn resume_workflow(
90        &self,
91        workflow_run_id: impl Into<String>,
92    ) -> FacadeResult<WorkflowResumeResult> {
93        let command_id = self.mint_command_id()?;
94        let params = WorkflowResumeParams {
95            session_id: self.inner.session_id.clone(),
96            command_id: command_id.clone(),
97            workflow_run_id: workflow_run_id.into(),
98        };
99        let result: WorkflowResumeResult = self.query("workflow/resume", &params).await?;
100        require_echo("workflow/resume", &result.command_id, &command_id)?;
101        require_accepted("workflow/resume", &result.status)?;
102        Ok(result)
103    }
104
105    /// Asks the host for a recap of this session (`recap/request`). The
106    /// result is admission only, never the recap itself.
107    pub async fn request_recap(&self) -> FacadeResult<RecapRequestResult> {
108        let command_id = self.mint_command_id()?;
109        let params = RecapRequestParams {
110            session_id: self.inner.session_id.clone(),
111            command_id: command_id.clone(),
112        };
113        let result: RecapRequestResult = self.query("recap/request", &params).await?;
114        require_echo("recap/request", &result.command_id, &command_id)?;
115        require_accepted("recap/request", &result.status)?;
116        Ok(result)
117    }
118
119    /// Submits feedback about this session (`feedback/submit`). The host
120    /// serves it only on a connection granted the `feedback` capability.
121    /// [`MuseClient`](crate::client::MuseClient) requests no capabilities yet,
122    /// so a real host refuses this call with `capabilityRequired`
123    /// ([`MuseError::Msp`](crate::errors::MuseError::Msp)).
124    pub async fn submit_feedback(
125        &self,
126        options: SubmitFeedbackOptions,
127    ) -> FacadeResult<FeedbackSubmitResult> {
128        let params = FeedbackSubmitParams {
129            classification: options.classification,
130            note: options.note,
131            with_files: options.with_files,
132            attach_session_record: options.attach_session_record,
133            session_id: Some(self.inner.session_id.clone()),
134            client_artifacts_path: options.client_artifacts_path,
135        };
136        self.query("feedback/submit", &params).await
137    }
138
139    /// Opens a side chat from this session (`session/sideChat`) and returns
140    /// the opening the host served for the new side session: its session,
141    /// view cursor and history. It returns no [`Session`] for the side chat.
142    pub async fn open_side_chat(&self) -> FacadeResult<SessionSideChatResult> {
143        let params = SessionSideChatParams {
144            command_id: self.mint_command_id()?,
145            session_id: self.inner.session_id.clone(),
146        };
147        self.query("session/sideChat", &params).await
148    }
149
150    /// Mints a command id for this session's next command. The discard check
151    /// comes first, so a discarded session names its discard, not the
152    /// transport end behind it.
153    fn mint_command_id(&self) -> FacadeResult<String> {
154        self.inner.ensure_available()?;
155        self.inner.client.mint_command_id()
156    }
157
158    /// Sends one request for this session, refused before sending on a
159    /// discarded session (and, inside the client, on a closed one).
160    async fn query<P, R>(&self, method: &str, params: &P) -> FacadeResult<R>
161    where
162        P: Serialize,
163        R: DeserializeOwned,
164    {
165        self.inner.ensure_available()?;
166        self.inner.client.command(method, params).await
167    }
168}
169
170fn require_echo(method: &str, echoed: &str, sent: &str) -> Result<(), ProtocolError> {
171    if echoed == sent {
172        Ok(())
173    } else {
174        Err(ProtocolError::new(
175            format!("{method} echoed command id {echoed}, expected {sent}"),
176            None,
177        ))
178    }
179}