Skip to main content

tea_cli/rpc/
server.rs

1use std::future::Future;
2use std::pin::Pin;
3use std::str::FromStr as _;
4
5use futures_util::stream::{FuturesUnordered, StreamExt as _};
6use tea::RuntimeCommandOutcome;
7use tea_coding::{CodingAgentService, CommandAcceptance};
8use tea_protocol::{CommandId, SessionId};
9use tea_session::SessionName;
10use tokio::io::{AsyncRead, AsyncWrite};
11
12use super::reader::{RpcFrameReader, RpcReadError};
13use super::types::{RpcError, RpcErrorCode, RpcOutput, RpcRequest, RpcRequestKind, RpcResponse};
14use super::writer::{RpcLineWriter, RpcWriteError};
15use crate::args::{CliArgs, SessionSelection};
16use crate::session_views::{
17    SessionStateView, SessionStatsView, mcp_servers, session_list, session_tree, snapshot_page,
18};
19use crate::{CliBootstrap, CliFailure, ExitCategory};
20
21/// One connection parses and dispatches at most one request at a time.
22pub const MAX_RPC_IN_FLIGHT_REQUESTS: usize = 1;
23
24type OwnedRun<'a> = Pin<
25    Box<
26        dyn Future<
27                Output = (
28                    CommandId,
29                    SessionId,
30                    Result<RuntimeCommandOutcome, tea_coding::CodingError>,
31                ),
32            > + 'a,
33    >,
34>;
35
36struct HandledRequest {
37    response: RpcResponse,
38    selected_session: Option<SessionId>,
39    accepted: Option<CommandAcceptance>,
40}
41
42/// Builds and owns a service for strict JSONL/RPC mode.
43///
44/// # Errors
45///
46/// Returns stable CLI failures for bootstrap, framing, output, or cancellation.
47pub async fn run<R, W>(
48    args: &CliArgs,
49    bootstrap: &CliBootstrap,
50    input: R,
51    output: W,
52) -> Result<(), CliFailure>
53where
54    R: AsyncRead + Unpin,
55    W: AsyncWrite + Unpin + Send + 'static,
56{
57    if !args.rpc {
58        return Err(CliFailure::usage("RPC mode requires --rpc"));
59    }
60    if !args.prompt.is_empty() {
61        return Err(CliFailure::usage(
62            "RPC mode accepts prompts only through request frames",
63        ));
64    }
65    let (service, selection) = bootstrap.build_async(args).await?;
66    let result = run_service(&service, selection, input, output).await;
67    service.shutdown().await;
68    result
69}
70
71/// Runs one RPC connection over an existing mode-neutral service.
72///
73/// EOF and signals return only after the writer is drained; the caller remains
74/// responsible for shutting down the borrowed service and its owned runs.
75///
76/// # Errors
77///
78/// Returns a terminal framing, I/O, output-backpressure, or signal failure.
79#[allow(clippy::too_many_lines)] // Keep connection input/event/run/shutdown ordering auditable.
80pub async fn run_service<R, W>(
81    service: &CodingAgentService,
82    selection: SessionSelection,
83    input: R,
84    output: W,
85) -> Result<(), CliFailure>
86where
87    R: AsyncRead + Unpin,
88    W: AsyncWrite + Unpin + Send + 'static,
89{
90    let mut session_id = crate::modes::print::select_session(service, selection).await?;
91    let mut events = service.subscribe(session_id).map_err(CliFailure::from)?;
92    let mut reader = RpcFrameReader::new(input);
93    let writer = RpcLineWriter::spawn(output);
94    writer
95        .write(&RpcOutput::ready(
96            session_id,
97            service.workspace_id().clone(),
98        ))
99        .await
100        .map_err(write_failure)?;
101
102    let mut owned_runs = FuturesUnordered::<OwnedRun<'_>>::new();
103    let interrupt = tokio::signal::ctrl_c();
104    tokio::pin!(interrupt);
105    let mut terminal_error = None;
106
107    loop {
108        tokio::select! {
109            frame = reader.read_frame() => {
110                let frame = match frame {
111                    Ok(Some(frame)) => frame,
112                    Ok(None) => break,
113                    Err(error) => {
114                        terminal_error = Some(read_failure(error));
115                        break;
116                    }
117                };
118                let Ok(request) = serde_json::from_slice::<RpcRequest>(&frame) else {
119                    writer
120                        .write(&RpcOutput::error(
121                            None,
122                            RpcError::new(RpcErrorCode::ParseError, "request JSON is malformed"),
123                        ))
124                        .await
125                        .map_err(write_failure)?;
126                    continue;
127                };
128                let request_id = request.id().cloned();
129                let request = match request.into_parts() {
130                    Ok((_, request)) => request,
131                    Err(error) => {
132                        writer
133                            .write(&RpcOutput::error(request_id, error))
134                            .await
135                            .map_err(write_failure)?;
136                        continue;
137                    }
138                };
139                let handled = match handle_request(service, session_id, request).await {
140                    Ok(handled) => handled,
141                    Err(error) => {
142                        writer
143                            .write(&RpcOutput::error(request_id, error))
144                            .await
145                            .map_err(write_failure)?;
146                        continue;
147                    }
148                };
149                if let Some(selected) = handled.selected_session {
150                    match service.subscribe(selected) {
151                        Ok(subscription) => {
152                            session_id = selected;
153                            events = subscription;
154                        }
155                        Err(error) => {
156                            writer
157                                .write(&RpcOutput::error(request_id, RpcError::from(error)))
158                                .await
159                                .map_err(write_failure)?;
160                            continue;
161                        }
162                    }
163                }
164                writer
165                    .write(&RpcOutput::response(request_id, handled.response))
166                    .await
167                    .map_err(write_failure)?;
168                if let Some(acceptance) = handled.accepted {
169                    owned_runs.push(Box::pin(wait_owned(service, acceptance)));
170                }
171            }
172            event = events.recv() => {
173                if let Some(event) = event {
174                    writer
175                        .write(&RpcOutput::event(event))
176                        .await
177                        .map_err(write_failure)?;
178                } else {
179                    let snapshot = service
180                        .session_snapshot(session_id)
181                        .await
182                        .map_err(CliFailure::from)?;
183                    events = service.subscribe(session_id).map_err(CliFailure::from)?;
184                    writer
185                        .write(&RpcOutput::resnapshot_required(
186                            session_id,
187                            snapshot.state().tail_sequence(),
188                        ))
189                        .await
190                        .map_err(write_failure)?;
191                }
192            }
193            completed = owned_runs.next(), if !owned_runs.is_empty() => {
194                if let Some((command_id, completed_session, outcome)) = completed {
195                    let error = outcome.err().map(RpcError::from);
196                    writer
197                        .write(&RpcOutput::command_finished(
198                            command_id,
199                            completed_session,
200                            error,
201                        ))
202                        .await
203                        .map_err(write_failure)?;
204                }
205            }
206            signal = &mut interrupt => {
207                terminal_error = Some(match signal {
208                    Ok(()) => CliFailure::new(ExitCategory::Cancelled, "RPC operation cancelled"),
209                    Err(_) => CliFailure::new(
210                        ExitCategory::Internal,
211                        "RPC cancellation handler failed",
212                    ),
213                });
214                break;
215            }
216        }
217    }
218
219    drop(owned_runs);
220    writer.shutdown().await.map_err(write_failure)?;
221    match terminal_error {
222        Some(error) => Err(error),
223        None => Ok(()),
224    }
225}
226
227async fn wait_owned(
228    service: &CodingAgentService,
229    acceptance: CommandAcceptance,
230) -> (
231    CommandId,
232    SessionId,
233    Result<RuntimeCommandOutcome, tea_coding::CodingError>,
234) {
235    (
236        acceptance.command_id(),
237        acceptance.session_id(),
238        service.wait(acceptance.session_id()).await,
239    )
240}
241
242#[allow(clippy::too_many_lines)]
243async fn handle_request(
244    service: &CodingAgentService,
245    session_id: SessionId,
246    request: RpcRequestKind,
247) -> Result<HandledRequest, RpcError> {
248    let mut selected_session = None;
249    let mut accepted = None;
250    let response = match request {
251        RpcRequestKind::NewSession {} => {
252            let new_session = service.create_session().await.map_err(RpcError::from)?;
253            let state = service
254                .snapshot(new_session)
255                .await
256                .map_err(RpcError::from)?;
257            selected_session = Some(new_session);
258            RpcResponse::SessionSelected {
259                state: SessionStateView::from(&state),
260                resnapshot_required: true,
261            }
262        }
263        RpcRequestKind::OpenSession {
264            session_id: selected,
265        } => {
266            let state = service
267                .open_session(selected)
268                .await
269                .map_err(RpcError::from)?;
270            selected_session = Some(selected);
271            RpcResponse::SessionSelected {
272                state: SessionStateView::from(&state),
273                resnapshot_required: true,
274            }
275        }
276        RpcRequestKind::NameSession { name } => {
277            let name = name
278                .map(|name| SessionName::from_str(&name))
279                .transpose()
280                .map_err(|_| {
281                    RpcError::new(RpcErrorCode::InvalidRequest, "session name is invalid")
282                })?;
283            service
284                .name_session(session_id, name)
285                .await
286                .map_err(RpcError::from)?;
287            RpcResponse::CommandCompleted { session_id }
288        }
289        RpcRequestKind::Prompt { text } => {
290            let acceptance = service.prompt(session_id, text).map_err(RpcError::from)?;
291            accepted = Some(acceptance);
292            RpcResponse::CommandAccepted {
293                command_id: acceptance.command_id(),
294                session_id,
295            }
296        }
297        RpcRequestKind::Steer { text } => {
298            service
299                .steer(session_id, text)
300                .await
301                .map_err(RpcError::from)?;
302            RpcResponse::CommandCompleted { session_id }
303        }
304        RpcRequestKind::FollowUp { text } => {
305            service
306                .follow_up(session_id, text)
307                .await
308                .map_err(RpcError::from)?;
309            RpcResponse::CommandCompleted { session_id }
310        }
311        RpcRequestKind::Abort {} => {
312            service.abort(session_id).await.map_err(RpcError::from)?;
313            RpcResponse::CommandCompleted { session_id }
314        }
315        RpcRequestKind::ResolveApproval {
316            approval_id,
317            decision,
318        } => {
319            let acceptance = service
320                .approve(session_id, approval_id, decision)
321                .map_err(RpcError::from)?;
322            accepted = Some(acceptance);
323            RpcResponse::CommandAccepted {
324                command_id: acceptance.command_id(),
325                session_id,
326            }
327        }
328        RpcRequestKind::SetModel { model } => {
329            service
330                .set_model(session_id, model)
331                .await
332                .map_err(RpcError::from)?;
333            RpcResponse::CommandCompleted { session_id }
334        }
335        RpcRequestKind::Compact {} => {
336            service.compact(session_id).await.map_err(RpcError::from)?;
337            RpcResponse::CommandCompleted { session_id }
338        }
339        RpcRequestKind::Fork {
340            from_message_id,
341            branch_id,
342        } => {
343            service
344                .fork(session_id, from_message_id, branch_id)
345                .await
346                .map_err(RpcError::from)?;
347            RpcResponse::CommandCompleted { session_id }
348        }
349        RpcRequestKind::ListSessions {} => {
350            let sessions = service.list_sessions().await.map_err(RpcError::from)?;
351            RpcResponse::Sessions {
352                sessions: session_list(&sessions),
353            }
354        }
355        RpcRequestKind::QueryState {} => {
356            let state = service.snapshot(session_id).await.map_err(RpcError::from)?;
357            RpcResponse::State {
358                state: SessionStateView::from(&state),
359            }
360        }
361        RpcRequestKind::QuerySnapshot {
362            after_sequence,
363            limit,
364        } => {
365            if limit == 0 {
366                return Err(RpcError::new(
367                    RpcErrorCode::InvalidRequest,
368                    "snapshot limit must be non-zero",
369                ));
370            }
371            let snapshot = service
372                .session_snapshot(session_id)
373                .await
374                .map_err(RpcError::from)?;
375            RpcResponse::Snapshot {
376                snapshot: snapshot_page(&snapshot, after_sequence, limit),
377            }
378        }
379        RpcRequestKind::QueryStats {} => {
380            let stats = service.stats(session_id).await.map_err(RpcError::from)?;
381            RpcResponse::Stats {
382                stats: SessionStatsView::from(stats),
383            }
384        }
385        RpcRequestKind::QueryTree {} => {
386            let snapshot = service
387                .session_snapshot(session_id)
388                .await
389                .map_err(RpcError::from)?;
390            RpcResponse::Tree {
391                tree: session_tree(&snapshot),
392            }
393        }
394        RpcRequestKind::ListModels {} => RpcResponse::Models {
395            models: service.models(),
396        },
397        RpcRequestKind::ListMcpServers {} => {
398            let snapshot = service.mcp_snapshot().map_err(RpcError::from)?;
399            RpcResponse::McpServers {
400                servers: mcp_servers(&snapshot),
401            }
402        }
403        RpcRequestKind::ReconnectMcp { server_id } => {
404            service
405                .reconnect_mcp(&server_id)
406                .await
407                .map_err(RpcError::from)?;
408            let snapshot = service.mcp_snapshot().map_err(RpcError::from)?;
409            RpcResponse::McpServers {
410                servers: mcp_servers(&snapshot),
411            }
412        }
413    };
414    Ok(HandledRequest {
415        response,
416        selected_session,
417        accepted,
418    })
419}
420
421fn read_failure(error: RpcReadError) -> CliFailure {
422    let message = match error {
423        RpcReadError::Oversize => "RPC input frame exceeds the size limit",
424        RpcReadError::Unterminated => "RPC input ended inside a frame",
425        RpcReadError::Io => "RPC input is unavailable",
426    };
427    CliFailure::new(ExitCategory::Usage, message)
428}
429
430fn write_failure(error: RpcWriteError) -> CliFailure {
431    let category = match error {
432        RpcWriteError::InvalidValue => ExitCategory::Internal,
433        RpcWriteError::Closed | RpcWriteError::Deadline => ExitCategory::Cancelled,
434    };
435    CliFailure::new(category, error.to_string())
436}