Skip to main content

codex_codes/
client_async.rs

1//! Asynchronous multi-turn client for the Codex app-server.
2//!
3//! Spawns `codex app-server --listen stdio://` and communicates over
4//! newline-delimited JSON-RPC. The connection stays open for multiple
5//! turns until explicitly shut down.
6//!
7//! # Lifecycle
8//!
9//! 1. Create a client with [`AsyncClient::start`] (spawns and initializes the app-server)
10//! 2. Call [`AsyncClient::thread_start`] to create a conversation session
11//! 3. Call [`AsyncClient::turn_start`] to send user input
12//! 4. Consume [`AsyncClient::next_message`] to stream notifications
13//! 5. Handle approval requests via [`AsyncClient::respond`]
14//! 6. Repeat steps 3-5 for follow-up turns
15//! 7. The client kills the app-server on [`Drop`]
16//!
17//! # Example
18//!
19//! ```ignore
20//! use codex_codes::{AsyncClient, ThreadStartParams, TurnStartParams, UserInput, ServerMessage};
21//!
22//! let mut client = AsyncClient::start().await?;
23//! let thread = client.thread_start(&ThreadStartParams::default()).await?;
24//!
25//! client.turn_start(&TurnStartParams {
26//!     thread_id: thread.thread_id().to_string(),
27//!     input: vec![UserInput::Text { text: "Hello!".into() }],
28//!     model: None,
29//!     reasoning_effort: None,
30//!     sandbox_policy: None,
31//! }).await?;
32//!
33//! while let Some(msg) = client.next_message().await? {
34//!     match msg {
35//!         ServerMessage::Notification(n) => {
36//!             if let codex_codes::Notification::TurnCompleted(_) = n { break; }
37//!         }
38//!         ServerMessage::Request { id, .. } => {
39//!             client.respond(id, &serde_json::json!({"decision": "accept"})).await?;
40//!         }
41//!     }
42//! }
43//! ```
44
45use crate::cli::AppServerBuilder;
46use crate::error::{Error, ParseError, Result};
47use crate::jsonrpc::{
48    JsonRpcError, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, RequestId,
49};
50use crate::messages::{Notification, ServerMessage, ServerRequest};
51use crate::protocol::{
52    ClientInfo, InitializeParams, InitializeResponse, ThreadArchiveParams, ThreadArchiveResponse,
53    ThreadDeleteParams, ThreadDeleteResponse, ThreadForkParams, ThreadForkResponse,
54    ThreadItemsListParams, ThreadItemsListResponse, ThreadResumeParams, ThreadResumeResponse,
55    ThreadRevertParams, ThreadRevertResponse, ThreadStartParams, ThreadStartResponse,
56    ThreadTurnsListParams, ThreadTurnsListResponse, TurnInterruptParams, TurnInterruptResponse,
57    TurnStartParams, TurnStartResponse, TurnSteerParams, TurnSteerResponse,
58};
59use crate::protocol_generated::types::{
60    CancelLoginAccountParams, CancelLoginAccountResponse, GetAccountParams,
61    GetAccountRateLimitsParams, GetAccountRateLimitsResponse, GetAccountResponse,
62    GetAccountTokenUsageParams, GetAccountTokenUsageResponse, LoginAccountParams,
63    LoginAccountResponse, LogoutAccountResponse,
64};
65use log::{debug, error, warn};
66use serde::de::DeserializeOwned;
67use serde::Serialize;
68use std::collections::VecDeque;
69use std::sync::atomic::{AtomicI64, Ordering};
70use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader, BufWriter};
71use tokio::process::Child;
72
73/// Buffer size for reading stdout (10MB).
74const STDOUT_BUFFER_SIZE: usize = 10 * 1024 * 1024;
75
76/// Asynchronous multi-turn client for the Codex app-server.
77///
78/// Communicates with a long-lived `codex app-server` process via
79/// newline-delimited JSON-RPC over stdio. Manages request/response
80/// correlation and buffers incoming notifications that arrive while
81/// waiting for RPC responses.
82///
83/// Reads performed by [`AsyncClient::request`] and [`AsyncClient::next_message`]
84/// are cancellation-safe. If either future is dropped while a JSON line is
85/// only partially available, the partial frame is retained and completed by
86/// the next read operation.
87///
88/// The client automatically kills the app-server process when dropped.
89pub struct AsyncClient {
90    child: Child,
91    writer: BufWriter<tokio::process::ChildStdin>,
92    reader: BufReader<tokio::process::ChildStdout>,
93    /// Bytes read from stdout for the current, not-yet-decoded frame.
94    inbound_frame: Vec<u8>,
95    /// Handle to the background task draining the child's stderr pipe.
96    /// Kept alive for the lifetime of the client; the task exits on EOF
97    /// when the child is killed.
98    _stderr_drain: tokio::task::JoinHandle<()>,
99    next_id: AtomicI64,
100    /// Buffered incoming messages (notifications/server requests) that arrived
101    /// while waiting for a response to a client request.
102    buffered: VecDeque<ServerMessage>,
103}
104
105impl AsyncClient {
106    /// Create a client from an existing Tokio child process.
107    ///
108    /// The child's stdin, stdout, and stderr must all be piped. This does not
109    /// perform the app-server `initialize` handshake or a Codex version check.
110    /// Use [`AppServerBuilder::build_command`] to retain the SDK's command-line
111    /// and stdio configuration while customizing how the process is spawned.
112    pub fn new(mut child: Child) -> Result<Self> {
113        let stdin = child
114            .stdin
115            .take()
116            .ok_or_else(|| Error::Protocol("Failed to get stdin".to_string()))?;
117        let stdout = child
118            .stdout
119            .take()
120            .ok_or_else(|| Error::Protocol("Failed to get stdout".to_string()))?;
121        let stderr = child
122            .stderr
123            .take()
124            .ok_or_else(|| Error::Protocol("Failed to get stderr".to_string()))?;
125
126        // The app-server emits ~200 KB/s of tracing to stderr. Without an
127        // active reader, the ~64 KB kernel pipe fills almost instantly and
128        // the child blocks. Drain in the background and route lines through
129        // the `log` crate (see [`crate::stderr_drain`]).
130        let stderr_drain = crate::stderr_drain::spawn_async(stderr);
131
132        Ok(Self {
133            child,
134            writer: BufWriter::new(stdin),
135            reader: BufReader::with_capacity(STDOUT_BUFFER_SIZE, stdout),
136            inbound_frame: Vec::new(),
137            _stderr_drain: stderr_drain,
138            next_id: AtomicI64::new(1),
139            buffered: VecDeque::new(),
140        })
141    }
142
143    /// Start an app-server with default settings.
144    ///
145    /// Spawns `codex app-server --listen stdio://`, performs the required
146    /// `initialize` handshake, and returns a connected client ready for
147    /// `thread_start()`.
148    ///
149    /// # Errors
150    ///
151    /// Returns an error if the `codex` CLI is not installed, the version is
152    /// incompatible, the process fails to start, or the initialization
153    /// handshake fails.
154    pub async fn start() -> Result<Self> {
155        Self::start_with(AppServerBuilder::new()).await
156    }
157
158    /// Start an app-server with a custom [`AppServerBuilder`].
159    ///
160    /// Performs the required `initialize` handshake before returning.
161    /// Use this to configure the binary path, working directory, environment,
162    /// or CLI arguments.
163    ///
164    /// # Errors
165    ///
166    /// Returns an error if the process fails to start, stdio pipes
167    /// cannot be established, or the initialization handshake fails.
168    pub async fn start_with(builder: AppServerBuilder) -> Result<Self> {
169        let mut client = Self::spawn(builder).await?;
170        client
171            .initialize(&InitializeParams {
172                client_info: ClientInfo {
173                    name: "codex-codes".to_string(),
174                    version: env!("CARGO_PKG_VERSION").to_string(),
175                    title: None,
176                },
177                capabilities: None,
178            })
179            .await?;
180        Ok(client)
181    }
182
183    /// Spawn an app-server without performing the `initialize` handshake.
184    ///
185    /// Use this if you need to send a custom [`InitializeParams`] (e.g., with
186    /// specific capabilities). You **must** call [`AsyncClient::initialize`]
187    /// before any other requests.
188    pub async fn spawn(builder: AppServerBuilder) -> Result<Self> {
189        crate::version::check_codex_version_async().await?;
190        Self::new(builder.spawn().await?)
191    }
192
193    /// Send a JSON-RPC request and wait for the matching response.
194    ///
195    /// Any notifications or server requests that arrive before the response
196    /// are buffered and can be retrieved via [`AsyncClient::next_message`].
197    /// Dropping this future during a partial inbound frame preserves that frame
198    /// for the next call to `request` or [`AsyncClient::next_message`].
199    ///
200    /// # Errors
201    ///
202    /// - [`Error::JsonRpc`] if the server returns a JSON-RPC error
203    /// - [`Error::ServerClosed`] if the connection drops before a response arrives
204    /// - [`Error::Json`] if response deserialization fails
205    pub async fn request<P: Serialize, R: DeserializeOwned>(
206        &mut self,
207        method: &str,
208        params: &P,
209    ) -> Result<R> {
210        let id = RequestId::Integer(self.next_id.fetch_add(1, Ordering::Relaxed));
211
212        let req = JsonRpcRequest {
213            id: id.clone(),
214            method: method.to_string(),
215            params: Some(serde_json::to_value(params).map_err(Error::Json)?),
216        };
217
218        self.send_raw(&req).await?;
219
220        // Read lines until we get a response matching our id
221        loop {
222            let msg = self.read_message().await?;
223            match msg {
224                JsonRpcMessage::Response(resp) if resp.id == id => {
225                    let result: R = serde_json::from_value(resp.result).map_err(Error::Json)?;
226                    return Ok(result);
227                }
228                JsonRpcMessage::Error(err) if err.id == id => {
229                    return Err(err.error.into());
230                }
231                // Buffer notifications and server requests
232                JsonRpcMessage::Notification(notif) => {
233                    let typed = Notification::from_envelope(&notif.method, notif.params)
234                        .map_err(Error::Json)?;
235                    self.buffered.push_back(ServerMessage::Notification(typed));
236                }
237                JsonRpcMessage::Request(req) => {
238                    let typed = ServerRequest::from_envelope(&req.method, req.params)
239                        .map_err(Error::Json)?;
240                    self.buffered.push_back(ServerMessage::Request {
241                        id: req.id,
242                        request: typed,
243                    });
244                }
245                // Response/error for a different id — unexpected
246                JsonRpcMessage::Response(resp) => {
247                    warn!(
248                        "[CLIENT] Unexpected response for id={}, expected id={}",
249                        resp.id, id
250                    );
251                }
252                JsonRpcMessage::Error(err) => {
253                    warn!(
254                        "[CLIENT] Unexpected error for id={}, expected id={}",
255                        err.id, id
256                    );
257                }
258            }
259        }
260    }
261
262    /// Start a new thread (conversation session).
263    ///
264    /// A thread must be created before any turns can be started. The returned
265    /// [`ThreadStartResponse`] contains the `thread_id` needed for subsequent calls.
266    pub async fn thread_start(
267        &mut self,
268        params: &ThreadStartParams,
269    ) -> Result<ThreadStartResponse> {
270        self.request(crate::protocol::methods::THREAD_START, params)
271            .await
272    }
273
274    /// Resume a previously persisted thread by id.
275    ///
276    /// Replays the thread's history so turns can continue where they left off.
277    pub async fn thread_resume(
278        &mut self,
279        params: &ThreadResumeParams,
280    ) -> Result<ThreadResumeResponse> {
281        self.request(crate::protocol::methods::THREAD_RESUME, params)
282            .await
283    }
284
285    /// Fork an existing thread into a new independent thread.
286    pub async fn thread_fork(&mut self, params: &ThreadForkParams) -> Result<ThreadForkResponse> {
287        self.request(crate::protocol::methods::THREAD_FORK, params)
288            .await
289    }
290
291    /// Start a new turn within a thread.
292    ///
293    /// Sends user input to the agent. After calling this, use [`AsyncClient::next_message`]
294    /// to stream notifications until `turn/completed` arrives.
295    pub async fn turn_start(&mut self, params: &TurnStartParams) -> Result<TurnStartResponse> {
296        self.request(crate::protocol::methods::TURN_START, params)
297            .await
298    }
299
300    /// Steer an active turn with additional user input (`turn/steer`) —
301    /// appends to the running turn instead of starting a new one.
302    pub async fn turn_steer(&mut self, params: &TurnSteerParams) -> Result<TurnSteerResponse> {
303        self.request(crate::protocol::methods::TURN_STEER, params)
304            .await
305    }
306
307    /// Page through a thread's items in canonical order (`thread/items/list`).
308    /// Follow `next_cursor` for subsequent pages (0.148 upstream).
309    pub async fn thread_items_list(
310        &mut self,
311        params: &ThreadItemsListParams,
312    ) -> Result<ThreadItemsListResponse> {
313        self.request(crate::protocol::methods::THREAD_ITEMS_LIST, params)
314            .await
315    }
316
317    /// Page through a thread's turns (`thread/turns/list`); defaults to
318    /// newest-first with summary item detail (0.148 upstream).
319    pub async fn thread_turns_list(
320        &mut self,
321        params: &ThreadTurnsListParams,
322    ) -> Result<ThreadTurnsListResponse> {
323        self.request(crate::protocol::methods::THREAD_TURNS_LIST, params)
324            .await
325    }
326
327    /// Replace a paginated thread's durable history with the prefix before
328    /// one turn (`thread/revert`). Does not revert local file changes
329    /// (0.148 upstream).
330    pub async fn thread_revert(
331        &mut self,
332        params: &ThreadRevertParams,
333    ) -> Result<ThreadRevertResponse> {
334        self.request(crate::protocol::methods::THREAD_REVERT, params)
335            .await
336    }
337
338    /// Interrupt an active turn.
339    pub async fn turn_interrupt(
340        &mut self,
341        params: &TurnInterruptParams,
342    ) -> Result<TurnInterruptResponse> {
343        self.request(crate::protocol::methods::TURN_INTERRUPT, params)
344            .await
345    }
346
347    /// Archive a thread.
348    pub async fn thread_archive(
349        &mut self,
350        params: &ThreadArchiveParams,
351    ) -> Result<ThreadArchiveResponse> {
352        self.request(crate::protocol::methods::THREAD_ARCHIVE, params)
353            .await
354    }
355
356    /// Delete a thread.
357    pub async fn thread_delete(
358        &mut self,
359        params: &ThreadDeleteParams,
360    ) -> Result<ThreadDeleteResponse> {
361        self.request(crate::protocol::methods::THREAD_DELETE, params)
362            .await
363    }
364
365    /// Perform the `initialize` handshake with the app-server.
366    ///
367    /// Sends `initialize` with the given params and then sends the
368    /// `initialized` notification. This must be the first request after
369    /// spawning the process.
370    pub async fn initialize(&mut self, params: &InitializeParams) -> Result<InitializeResponse> {
371        let resp: InitializeResponse = self
372            .request(crate::protocol::methods::INITIALIZE, params)
373            .await?;
374        self.send_notification(crate::protocol::methods::INITIALIZED)
375            .await?;
376        Ok(resp)
377    }
378
379    /// Respond to a server-to-client request (e.g., approval flow).
380    ///
381    /// When the server sends a [`ServerMessage::Request`], it expects a response.
382    /// Use this method with the request's `id` and a result payload. For command
383    /// approval, pass a [`CommandExecutionApprovalResponse`](crate::CommandExecutionApprovalResponse).
384    /// For file change approval, pass a [`FileChangeApprovalResponse`](crate::FileChangeApprovalResponse).
385    pub async fn respond<R: Serialize>(&mut self, id: RequestId, result: &R) -> Result<()> {
386        let resp = JsonRpcResponse {
387            id,
388            result: serde_json::to_value(result).map_err(Error::Json)?,
389        };
390        self.send_raw(&resp).await
391    }
392
393    /// Respond to a server-to-client request with an error.
394    pub async fn respond_error(&mut self, id: RequestId, code: i64, message: &str) -> Result<()> {
395        let err = JsonRpcError {
396            id,
397            error: crate::jsonrpc::JsonRpcErrorData {
398                code,
399                message: message.to_string(),
400                data: None,
401            },
402        };
403        self.send_raw(&err).await
404    }
405
406    /// Read the next incoming server message (notification or server request).
407    ///
408    /// Returns buffered messages first (from notifications that arrived during
409    /// an [`AsyncClient::request`] call), then reads from the wire.
410    ///
411    /// Returns `Ok(None)` when the app-server closes the connection (EOF).
412    /// Dropping this future during a partial inbound frame preserves that frame
413    /// for the next call to `next_message` or [`AsyncClient::request`].
414    ///
415    /// # Typical notification methods
416    ///
417    /// | Method | Meaning |
418    /// |--------|---------|
419    /// | `turn/started` | Agent began processing |
420    /// | `item/agentMessage/delta` | Streaming text chunk |
421    /// | `item/commandExecution/outputDelta` | Command output chunk |
422    /// | `item/started` / `item/completed` | Item lifecycle |
423    /// | `turn/completed` | Agent finished the turn |
424    /// | `error` | Server-side error |
425    pub async fn next_message(&mut self) -> Result<Option<ServerMessage>> {
426        // Drain buffered messages first
427        if let Some(msg) = self.buffered.pop_front() {
428            return Ok(Some(msg));
429        }
430
431        // Read from the wire
432        loop {
433            let msg = match self.read_message_opt().await? {
434                Some(m) => m,
435                None => return Ok(None),
436            };
437
438            match msg {
439                JsonRpcMessage::Notification(notif) => {
440                    let JsonRpcNotification { method, params } = notif;
441                    let typed =
442                        Notification::from_envelope(&method, params.clone()).map_err(|e| {
443                            Error::Deserialization(ParseError::from_envelope(method, params, e))
444                        })?;
445                    return Ok(Some(ServerMessage::Notification(typed)));
446                }
447                JsonRpcMessage::Request(req) => {
448                    let JsonRpcRequest { id, method, params } = req;
449                    let typed =
450                        ServerRequest::from_envelope(&method, params.clone()).map_err(|e| {
451                            Error::Deserialization(ParseError::from_envelope(method, params, e))
452                        })?;
453                    return Ok(Some(ServerMessage::Request { id, request: typed }));
454                }
455                // Unexpected responses without a pending request
456                JsonRpcMessage::Response(resp) => {
457                    warn!(
458                        "[CLIENT] Unexpected response (no pending request): id={}",
459                        resp.id
460                    );
461                }
462                JsonRpcMessage::Error(err) => {
463                    warn!(
464                        "[CLIENT] Unexpected error (no pending request): id={} code={}",
465                        err.id, err.error.code
466                    );
467                }
468            }
469        }
470    }
471
472    /// Return an async event stream over [`ServerMessage`]s.
473    ///
474    /// Wraps [`AsyncClient::next_message`] in a stream-like API. Call
475    /// [`EventStream::next`] in a loop, or [`EventStream::collect`] to
476    /// gather all messages until EOF.
477    pub fn events(&mut self) -> EventStream<'_> {
478        EventStream { client: self }
479    }
480
481    /// Get the process ID.
482    pub fn pid(&self) -> Option<u32> {
483        self.child.id()
484    }
485
486    // ── Account / auth methods ─────────────────────────────────────────
487
488    /// `account/read` — the active account (plan, email, auth mode), or
489    /// `account: null` when logged out.
490    pub async fn account_read(&mut self, params: &GetAccountParams) -> Result<GetAccountResponse> {
491        self.request(crate::protocol::methods::ACCOUNT_READ, params)
492            .await
493    }
494
495    /// `account/login/start` — begin a login. The params select the mode
496    /// (`apiKey` completes immediately; `chatgpt` returns an auth URL to
497    /// open; `chatgptDeviceCode` returns a user code + verification URL).
498    /// Browser/device modes complete asynchronously: watch for the
499    /// `account/login/completed` notification, or cancel with
500    /// [`account_login_cancel`](Self::account_login_cancel).
501    pub async fn account_login_start(
502        &mut self,
503        params: &LoginAccountParams,
504    ) -> Result<LoginAccountResponse> {
505        self.request(crate::protocol::methods::ACCOUNT_LOGIN_START, params)
506            .await
507    }
508
509    /// `account/login/cancel` — abort an in-flight browser/device login.
510    pub async fn account_login_cancel(
511        &mut self,
512        params: &CancelLoginAccountParams,
513    ) -> Result<CancelLoginAccountResponse> {
514        self.request(crate::protocol::methods::ACCOUNT_LOGIN_CANCEL, params)
515            .await
516    }
517
518    /// `account/logout` — remove the stored credential.
519    pub async fn account_logout(&mut self) -> Result<LogoutAccountResponse> {
520        self.request(
521            crate::protocol::methods::ACCOUNT_LOGOUT,
522            &serde_json::json!({}),
523        )
524        .await
525    }
526
527    /// `account/rateLimits/read` — current rate-limit windows.
528    ///
529    /// `params` declares the client's usage-read capabilities;
530    /// `GetAccountRateLimitsParams::default()` serializes as `{}` and matches
531    /// the pre-capability wire shape.
532    pub async fn account_rate_limits_read(
533        &mut self,
534        params: GetAccountRateLimitsParams,
535    ) -> Result<GetAccountRateLimitsResponse> {
536        self.request(crate::protocol::methods::ACCOUNT_RATELIMITS_READ, &params)
537            .await
538    }
539
540    /// `account/usage/read` — account-wide token-usage summary. Same as
541    /// [`account_usage_read_with`](Self::account_usage_read_with) with default
542    /// params.
543    pub async fn account_usage_read(&mut self) -> Result<GetAccountTokenUsageResponse> {
544        self.account_usage_read_with(&GetAccountTokenUsageParams::default())
545            .await
546    }
547
548    /// `account/usage/read` with explicit params. Set `thread_id` to read the
549    /// estimated usage of one thread (returned in `thread_usage`, including
550    /// `native_usage_usd_micros` when known) instead of account-wide token
551    /// activity. Default params serialize as `{}`.
552    pub async fn account_usage_read_with(
553        &mut self,
554        params: &GetAccountTokenUsageParams,
555    ) -> Result<GetAccountTokenUsageResponse> {
556        self.request(crate::protocol::methods::ACCOUNT_USAGE_READ, params)
557            .await
558    }
559
560    /// Check if the child process is still running.
561    pub fn is_alive(&mut self) -> bool {
562        self.child.try_wait().ok().flatten().is_none()
563    }
564
565    /// Shut down the app-server process.
566    ///
567    /// Consumes the client. If you don't call this explicitly, the
568    /// [`Drop`] implementation will kill the process automatically.
569    pub async fn shutdown(mut self) -> Result<()> {
570        debug!("[CLIENT] Shutting down");
571        self.child.kill().await.map_err(Error::Io)?;
572        Ok(())
573    }
574
575    // -- internal --
576
577    async fn send_notification(&mut self, method: &str) -> Result<()> {
578        let notif = JsonRpcNotification {
579            method: method.to_string(),
580            params: None,
581        };
582        self.send_raw(&notif).await
583    }
584
585    async fn send_raw<T: Serialize>(&mut self, msg: &T) -> Result<()> {
586        let json = serde_json::to_string(msg).map_err(Error::Json)?;
587        debug!("[CLIENT] Sending: {}", json);
588        self.writer
589            .write_all(json.as_bytes())
590            .await
591            .map_err(Error::Io)?;
592        self.writer.write_all(b"\n").await.map_err(Error::Io)?;
593        self.writer.flush().await.map_err(Error::Io)?;
594        Ok(())
595    }
596
597    async fn read_message(&mut self) -> Result<JsonRpcMessage> {
598        self.read_message_opt().await?.ok_or(Error::ServerClosed)
599    }
600
601    async fn read_message_opt(&mut self) -> Result<Option<JsonRpcMessage>> {
602        loop {
603            // `read_until` is cancellation-safe: bytes consumed from `reader`
604            // are appended to the persistent buffer before the await can be
605            // cancelled. Do not clear that buffer until a full frame exists.
606            let bytes_read = self
607                .reader
608                .read_until(b'\n', &mut self.inbound_frame)
609                .await
610                .map_err(Error::Io)?;
611
612            if bytes_read == 0 {
613                debug!("[CLIENT] Stream closed (EOF)");
614                if self.inbound_frame.is_empty() {
615                    return Ok(None);
616                }
617            }
618
619            if !self.inbound_frame.ends_with(b"\n") && bytes_read != 0 {
620                continue;
621            }
622
623            let line = match std::str::from_utf8(&self.inbound_frame) {
624                Ok(line) => line,
625                Err(error) => {
626                    let error = std::io::Error::new(std::io::ErrorKind::InvalidData, error);
627                    self.inbound_frame.clear();
628                    return Err(Error::Io(error));
629                }
630            };
631            let trimmed = line.trim();
632            if trimmed.is_empty() {
633                self.inbound_frame.clear();
634                continue;
635            }
636
637            debug!("[CLIENT] Received: {}", trimmed);
638
639            let decoded = serde_json::from_str::<JsonRpcMessage>(trimmed);
640            match decoded {
641                Ok(msg) => {
642                    self.inbound_frame.clear();
643                    return Ok(Some(msg));
644                }
645                Err(e) => {
646                    warn!(
647                        "[CLIENT] Failed to deserialize message. \
648                         Please report this at https://github.com/meawoppl/rust-code-agent-sdks/issues"
649                    );
650                    warn!("[CLIENT] Parse error: {}", e);
651                    warn!("[CLIENT] Raw: {}", trimmed);
652                    let parse_error = ParseError::from_line(trimmed, e);
653                    self.inbound_frame.clear();
654                    return Err(Error::Deserialization(parse_error));
655                }
656            }
657        }
658    }
659}
660
661impl Drop for AsyncClient {
662    fn drop(&mut self) {
663        if self.is_alive() {
664            if let Err(e) = self.child.start_kill() {
665                error!("Failed to kill app-server process on drop: {}", e);
666            }
667        }
668    }
669}
670
671/// Async stream of [`ServerMessage`]s from an [`AsyncClient`].
672pub struct EventStream<'a> {
673    client: &'a mut AsyncClient,
674}
675
676impl EventStream<'_> {
677    /// Get the next server message.
678    pub async fn next(&mut self) -> Option<Result<ServerMessage>> {
679        match self.client.next_message().await {
680            Ok(Some(msg)) => Some(Ok(msg)),
681            Ok(None) => None,
682            Err(e) => Some(Err(e)),
683        }
684    }
685
686    /// Collect all remaining messages.
687    pub async fn collect(mut self) -> Result<Vec<ServerMessage>> {
688        let mut msgs = Vec::new();
689        while let Some(result) = self.next().await {
690            msgs.push(result?);
691        }
692        Ok(msgs)
693    }
694}
695
696#[cfg(test)]
697mod tests {
698    use super::*;
699    use crate::protocol::ModelProviderError;
700    use std::process::Stdio;
701    use tokio::process::Command;
702
703    #[cfg(unix)]
704    fn scripted_client(script: &str) -> AsyncClient {
705        let mut command = Command::new("sh");
706        command
707            .arg("-c")
708            .arg(script)
709            .stdin(Stdio::piped())
710            .stdout(Stdio::piped())
711            .stderr(Stdio::piped());
712        AsyncClient::new(command.spawn().expect("spawn scripted app-server"))
713            .expect("construct async client")
714    }
715
716    fn unknown_method(message: ServerMessage) -> String {
717        match message {
718            ServerMessage::Notification(Notification::Unknown { method, .. }) => method,
719            other => panic!("expected unknown notification, got {other:?}"),
720        }
721    }
722
723    #[test]
724    fn test_buffer_size() {
725        assert_eq!(STDOUT_BUFFER_SIZE, 10 * 1024 * 1024);
726    }
727
728    #[cfg(unix)]
729    #[tokio::test]
730    async fn request_error_keeps_model_provider_data() {
731        let mut client = scripted_client(
732            r#"IFS= read -r req; printf '%s\n' '{"id":1,"error":{"code":-32600,"message":"provider mismatch","data":{"type":"modelProviderMismatch","modelProvider":"old","currentModelProvider":"new"}}}'"#,
733        );
734        let params = ThreadResumeParams {
735            thread_id: "thr_1".to_string(),
736            ..Default::default()
737        };
738        let err = client.thread_resume(&params).await.unwrap_err();
739
740        assert!(matches!(
741            &err,
742            Error::JsonRpc { code: -32600, message, data: Some(_) } if message == "provider mismatch"
743        ));
744        assert_eq!(
745            err.model_provider_error(),
746            Some(ModelProviderError::ModelProviderMismatch {
747                model_provider: "old".to_string(),
748                current_model_provider: "new".to_string(),
749            })
750        );
751    }
752
753    #[cfg(unix)]
754    #[tokio::test]
755    async fn account_usage_read_with_sends_thread_id() {
756        // Answers with thread usage only if the request carried the thread id.
757        let mut client = scripted_client(
758            r#"IFS= read -r req; case "$req" in *'"params":{"threadId":"thr_1"}'*) printf '%s\n' '{"id":1,"result":{"summary":{},"threadUsage":{"threadId":"thr_1","estimatedUsageCreditsMicros":5,"nativeUsageUsdMicros":1200,"groups":[]}}}' ;; *) printf '%s\n' '{"id":1,"error":{"code":-1,"message":"unexpected params"}}' ;; esac"#,
759        );
760        let usage = client
761            .account_usage_read_with(&GetAccountTokenUsageParams {
762                thread_id: Some("thr_1".to_string()),
763            })
764            .await
765            .expect("thread usage");
766        let thread = usage.thread_usage.expect("thread_usage");
767        assert_eq!(thread.thread_id, "thr_1");
768        assert_eq!(thread.native_usage_usd_micros, Some(1200));
769    }
770
771    #[cfg(unix)]
772    #[tokio::test]
773    async fn account_usage_read_sends_empty_params() {
774        let mut client = scripted_client(
775            r#"IFS= read -r req; case "$req" in *'"params":{}'*) printf '%s\n' '{"id":1,"result":{"summary":{}}}' ;; *) printf '%s\n' '{"id":1,"error":{"code":-1,"message":"unexpected params"}}' ;; esac"#,
776        );
777        let usage = client.account_usage_read().await.expect("account usage");
778        assert!(usage.thread_usage.is_none());
779    }
780
781    #[cfg(unix)]
782    #[tokio::test]
783    async fn cancelled_next_message_resumes_partial_frame_exactly_once() {
784        const PARTIAL: &[u8] = br#"{"method":"test/first","params":{"part":"#;
785        let mut client = scripted_client(
786            r#"printf '%s' '{"method":"test/first","params":{"part":'; IFS= read -r release; printf '%s\n' '1}}'; printf '%s\n' '{"method":"test/second","params":{}}'"#,
787        );
788
789        assert_eq!(
790            client
791                .reader
792                .fill_buf()
793                .await
794                .expect("buffer partial frame"),
795            PARTIAL
796        );
797        let mut pending_read = Box::pin(client.next_message());
798        tokio::select! {
799            biased;
800            result = &mut pending_read => panic!("partial frame completed unexpectedly: {result:?}"),
801            _ = async {} => {}
802        }
803        drop(pending_read);
804        // A pipe may split one write across reads, so require the bytes that
805        // reached the decoder to be a nonempty prefix, not the entire write.
806        assert!(!client.inbound_frame.is_empty());
807        assert!(PARTIAL.starts_with(&client.inbound_frame));
808        client
809            .writer
810            .write_all(b"release\n")
811            .await
812            .expect("release remaining frame");
813        client.writer.flush().await.expect("flush release");
814
815        let first = client
816            .next_message()
817            .await
818            .expect("resume first frame")
819            .expect("first message");
820        let second = client
821            .next_message()
822            .await
823            .expect("read second frame")
824            .expect("second message");
825
826        assert_eq!(unknown_method(first), "test/first");
827        assert_eq!(unknown_method(second), "test/second");
828        assert!(client.next_message().await.expect("read EOF").is_none());
829    }
830
831    #[cfg(unix)]
832    #[tokio::test]
833    async fn cancelled_request_preserves_shared_decoder_framing() {
834        const PARTIAL: &[u8] = br#"{"id":1,"result":{"abandoned":"#;
835        let mut client = scripted_client(
836            r#"printf '%s' '{"id":1,"result":{"abandoned":'; IFS= read -r first; IFS= read -r release; printf '%s\n' 'true}}' '{"method":"test/between","params":{}}'; IFS= read -r second; printf '%s\n' '{"id":2,"result":{"ok":true}}' '{"method":"test/after","params":{}}'"#,
837        );
838
839        assert_eq!(
840            client
841                .reader
842                .fill_buf()
843                .await
844                .expect("buffer partial response"),
845            PARTIAL
846        );
847        let params = serde_json::json!({});
848        let mut pending_request =
849            Box::pin(client.request::<_, serde_json::Value>("test/abandoned", &params));
850        tokio::select! {
851            biased;
852            result = &mut pending_request => panic!("partial response completed unexpectedly: {result:?}"),
853            _ = async {} => {}
854        }
855        drop(pending_request);
856        // A pipe may split one write across reads, so require the bytes that
857        // reached the decoder to be a nonempty prefix, not the entire write.
858        assert!(!client.inbound_frame.is_empty());
859        assert!(PARTIAL.starts_with(&client.inbound_frame));
860        client
861            .writer
862            .write_all(b"release\n")
863            .await
864            .expect("release remaining response");
865        client.writer.flush().await.expect("flush release");
866
867        let response: serde_json::Value = client
868            .request("test/resumed", &serde_json::json!({}))
869            .await
870            .expect("second request should resume the shared decoder");
871        assert_eq!(response, serde_json::json!({"ok": true}));
872
873        let between = client
874            .next_message()
875            .await
876            .expect("read buffered notification")
877            .expect("between message");
878        let after = client
879            .next_message()
880            .await
881            .expect("read trailing notification")
882            .expect("after message");
883        assert_eq!(unknown_method(between), "test/between");
884        assert_eq!(unknown_method(after), "test/after");
885        assert!(client.next_message().await.expect("read EOF").is_none());
886    }
887
888    #[cfg(unix)]
889    #[tokio::test]
890    async fn next_message_resumes_notification_partially_read_by_cancelled_request() {
891        const PARTIAL: &[u8] = br#"{"method":"test/during-request","params":{"part":"#;
892        let mut client = scripted_client(
893            r#"printf '%s' '{"method":"test/during-request","params":{"part":'; IFS= read -r request; IFS= read -r release; printf '%s\n' '1}}' '{"id":1,"result":{}}'"#,
894        );
895
896        assert_eq!(
897            client
898                .reader
899                .fill_buf()
900                .await
901                .expect("buffer partial notification"),
902            PARTIAL
903        );
904        let params = serde_json::json!({});
905        let mut pending_request =
906            Box::pin(client.request::<_, serde_json::Value>("test/abandoned", &params));
907        tokio::select! {
908            biased;
909            result = &mut pending_request => panic!("partial notification completed unexpectedly: {result:?}"),
910            _ = async {} => {}
911        }
912        drop(pending_request);
913        // A pipe may split one write across reads, so require the bytes that
914        // reached the decoder to be a nonempty prefix, not the entire write.
915        assert!(!client.inbound_frame.is_empty());
916        assert!(PARTIAL.starts_with(&client.inbound_frame));
917        client
918            .writer
919            .write_all(b"release\n")
920            .await
921            .expect("release remaining notification");
922        client.writer.flush().await.expect("flush release");
923
924        let notification = client
925            .next_message()
926            .await
927            .expect("resume partial notification")
928            .expect("notification");
929        assert_eq!(unknown_method(notification), "test/during-request");
930        assert!(client.next_message().await.expect("read EOF").is_none());
931    }
932
933    #[cfg(unix)]
934    #[tokio::test]
935    async fn request_resumes_notification_partially_read_by_cancelled_next_message() {
936        const PARTIAL: &[u8] = br#"{"method":"test/before-request","params":{"part":"#;
937        let mut client = scripted_client(
938            r#"printf '%s' '{"method":"test/before-request","params":{"part":'; IFS= read -r release; printf '%s\n' '1}}'; IFS= read -r request; printf '%s\n' '{"id":1,"result":{"ok":true}}'"#,
939        );
940
941        assert_eq!(
942            client
943                .reader
944                .fill_buf()
945                .await
946                .expect("buffer partial notification"),
947            PARTIAL
948        );
949        let mut pending_read = Box::pin(client.next_message());
950        tokio::select! {
951            biased;
952            result = &mut pending_read => panic!("partial notification completed unexpectedly: {result:?}"),
953            _ = async {} => {}
954        }
955        drop(pending_read);
956        // A pipe may split one write across reads, so require the bytes that
957        // reached the decoder to be a nonempty prefix, not the entire write.
958        assert!(!client.inbound_frame.is_empty());
959        assert!(PARTIAL.starts_with(&client.inbound_frame));
960        client
961            .writer
962            .write_all(b"release\n")
963            .await
964            .expect("release remaining notification");
965        client.writer.flush().await.expect("flush release");
966
967        let response: serde_json::Value = client
968            .request("test/resumed", &serde_json::json!({}))
969            .await
970            .expect("request should resume the shared decoder");
971        assert_eq!(response, serde_json::json!({"ok": true}));
972
973        let notification = client
974            .next_message()
975            .await
976            .expect("read buffered notification")
977            .expect("notification");
978        assert_eq!(unknown_method(notification), "test/before-request");
979        assert!(client.next_message().await.expect("read EOF").is_none());
980    }
981
982    #[cfg(unix)]
983    #[tokio::test]
984    async fn request_directly_resumes_response_partially_read_by_cancelled_next_message() {
985        const PARTIAL: &[u8] = br#"{"id":1,"result":{"ok":"#;
986        // The fixture knows the client's initial request id, but withholds the
987        // rest of the response until it has received that request.
988        let mut client = scripted_client(
989            r#"printf '%s' '{"id":1,"result":{"ok":'; IFS= read -r request; printf '%s\n' 'true}}'"#,
990        );
991
992        assert_eq!(
993            client
994                .reader
995                .fill_buf()
996                .await
997                .expect("buffer partial response"),
998            PARTIAL
999        );
1000        let mut pending_read = Box::pin(client.next_message());
1001        tokio::select! {
1002            biased;
1003            result = &mut pending_read => panic!("partial response completed unexpectedly: {result:?}"),
1004            _ = async {} => {}
1005        }
1006        drop(pending_read);
1007        // A pipe may split one write across reads, so require the bytes that
1008        // reached the decoder to be a nonempty prefix, not the entire write.
1009        assert!(!client.inbound_frame.is_empty());
1010        assert!(PARTIAL.starts_with(&client.inbound_frame));
1011        assert!(client.buffered.is_empty());
1012
1013        let response: serde_json::Value = client
1014            .request("test/resumed", &serde_json::json!({}))
1015            .await
1016            .expect("request should directly resume the partial response");
1017        assert_eq!(response, serde_json::json!({"ok": true}));
1018        assert!(client.buffered.is_empty());
1019        assert!(client.next_message().await.expect("read EOF").is_none());
1020    }
1021}