1mod approval_route;
4mod fold_view;
5mod gap_route;
6mod notification_params;
7mod reconnect;
8mod state;
9mod submit;
10mod turn_route;
11mod user_input;
12
13use std::collections::HashMap;
14use std::future::Future;
15use std::sync::{Arc, Mutex, Weak};
16
17use serde_json::Value;
18
19use crate::approval::ApprovalDecisionInput;
20use crate::client::{ClientShared, lock};
21use crate::fold::SessionFold;
22use crate::msp::{
23 ApprovalRequestParams, ApprovalResolvedParams, ApprovalUpdatedParams, Item,
24 ItemCompletedParams, ItemDeltaParams, ItemStartedParams, ItemUpdatedParams, Notification,
25 PendingRequestKind, SessionHistory, SessionResumeResult, SessionStartResult,
26 TurnCompletedParams, TurnStartedParams, TurnUnqueuedParams,
27};
28use crate::turn::TurnWaitError;
29
30use approval_route::ApprovalRoute;
31pub use fold_view::SessionFoldView;
32pub(crate) use fold_view::{drop_unreadable_snapshot, resume_history_items};
33use gap_route::GapRoute;
34use notification_params::{approval_id, decode, turn_id};
35use state::{PendingCommandGuard, SessionState};
36
37pub use reconnect::{PendingTurn, ReconnectResolution, Reconnected};
38pub use submit::SendUserTurnOptions;
39
40const MAX_SETTLED_TURN_ALIASES: usize = 128;
41pub(crate) const MAX_RETIRED_TURNS: usize = 256;
42pub(crate) const MAX_ACTIVE_TURNS: usize = 128;
43
44#[derive(Clone, Debug, PartialEq)]
46#[non_exhaustive]
47pub enum SessionOpening {
48 Start(Box<SessionStartResult>),
50 Resume(Box<SessionResumeResult>),
53}
54
55#[derive(Clone)]
58pub struct Session {
59 inner: Arc<SessionInner>,
60}
61
62fn served_history_items(history: &SessionHistory) -> Option<&[Item]> {
65 history.items.as_deref().or_else(|| {
66 history
67 .snapshot
68 .as_ref()
69 .map(|snapshot| snapshot.state.items.as_slice())
70 })
71}
72
73impl Session {
74 pub(crate) fn from_opening(
75 client: Arc<ClientShared>,
76 opening: SessionOpening,
77 history: &[Value],
78 dropped_snapshot_schema_version: Option<u64>,
79 ) -> Self {
80 let session_id = match &opening {
81 SessionOpening::Start(result) => result.session.session_id.clone(),
82 SessionOpening::Resume(result) => result.session.session_id.clone(),
83 };
84 let (approval, pending_approvals) = ApprovalRoute::new();
85 let gaps = GapRoute::new(&session_id);
86 let fold = fold_view::seeded_fold(&session_id, history);
87 let inner = Arc::new(SessionInner {
88 client,
89 session_id,
90 opening,
91 fold: Mutex::new(fold),
92 state: Arc::new(Mutex::new(SessionState::default())),
93 approval,
94 gaps,
95 dropped_snapshot_schema_version,
96 });
97 if let SessionOpening::Resume(result) = &inner.opening {
98 let mut state = lock(&inner.state);
99 state.hold_settled_aliases = true;
103 state.last_turn_id = result.last_turn.as_ref().map(|last| last.turn_id.clone());
104 }
105 inner
106 .approval
107 .spawn(inner.runtime(), Arc::downgrade(&inner), pending_approvals);
108 if let SessionOpening::Resume(result) = &inner.opening
109 && let Some(items) = served_history_items(&result.history)
110 {
111 let mut history_turn_items: HashMap<String, Vec<usize>> = HashMap::new();
117 for (index, item) in items.iter().enumerate() {
118 if let Some(turn_id) = &item.turn_id {
119 history_turn_items
120 .entry(turn_id.clone())
121 .or_default()
122 .push(index);
123 }
124 }
125 lock(&inner.state).history_turn_items = history_turn_items;
126 if let Some(active_turn_id) = result.session.active_turn_id.as_deref() {
127 inner.turn_handle(active_turn_id);
128 }
129 }
130 Self { inner }
131 }
132
133 pub fn session_id(&self) -> &str {
136 self.inner.session_id()
137 }
138
139 pub fn opening(&self) -> &SessionOpening {
144 &self.inner.opening
145 }
146
147 pub fn dropped_snapshot_schema_version(&self) -> Option<u64> {
158 self.inner.dropped_snapshot_schema_version
159 }
160
161 pub fn is_discarded(&self) -> bool {
166 lock(&self.inner.state).discarded
167 }
168
169 pub(crate) fn fix_resume_approval_routing(&self) {
171 if let SessionOpening::Resume(result) = &self.inner.opening {
172 self.inner.approval.fix_handoff_routing(
173 result
174 .pending_requests
175 .iter()
176 .filter(|pointer| pointer.kind == PendingRequestKind::Approval)
177 .filter_map(|pointer| pointer.approval_id.clone()),
178 );
179 }
180 }
181
182 pub fn on_approval<Handler, HandlerFuture>(&self, handler: Handler)
193 where
194 Handler: Fn(ApprovalRequestParams) -> HandlerFuture + Send + Sync + 'static,
195 HandlerFuture: Future<Output = ApprovalDecisionInput> + Send + 'static,
196 {
197 self.inner.approval.on_approval(handler);
198 }
199
200 pub(crate) fn downgrade(&self) -> Weak<SessionInner> {
201 Arc::downgrade(&self.inner)
202 }
203}
204
205pub(crate) struct SessionInner {
206 client: Arc<ClientShared>,
207 session_id: String,
208 opening: SessionOpening,
209 fold: Mutex<SessionFold>,
210 state: Arc<Mutex<SessionState>>,
211 approval: ApprovalRoute,
212 gaps: GapRoute,
213 dropped_snapshot_schema_version: Option<u64>,
214}
215
216impl SessionInner {
217 pub(crate) fn session_id(&self) -> &str {
218 &self.session_id
219 }
220
221 pub(super) fn runtime(&self) -> &tokio::runtime::Handle {
224 &self.client.runtime
225 }
226
227 pub(crate) fn apply(self: &Arc<Self>, notification: Notification) {
231 self.gaps.route(self, notification);
232 }
233
234 fn apply_now(self: &Arc<Self>, notification: Notification) {
235 self.fold_event(¬ification);
236 self.route_now(notification);
237 }
238
239 fn route_now(self: &Arc<Self>, notification: Notification) {
241 let Notification { method, params, .. } = notification;
242 match method.as_str() {
243 "item/started" => {
244 let _ = decode::<ItemStartedParams>(&method, params)
245 .map(|params| self.push_item(params.item));
246 }
247 "item/updated" => {
248 let _ = decode::<ItemUpdatedParams>(&method, params)
249 .map(|params| self.push_item(params.item));
250 }
251 "item/completed" => {
252 let _ = decode::<ItemCompletedParams>(&method, params)
253 .map(|params| self.push_item(params.item));
254 }
255 "item/delta" => {
256 let _ = decode::<ItemDeltaParams>(&method, params)
257 .map(|params| self.push_delta(params));
258 }
259 "approval/requested" | "approval/request" => {
261 let turn_id = turn_id(¶ms);
262 let approval_id = approval_id(¶ms);
263 match decode::<ApprovalRequestParams>(&method, params) {
264 Ok(params) => self.approval.enqueue_requested(self, params),
265 Err(error) => {
266 self.fail_named_turn(turn_id.clone(), error);
270 if let (Some(turn_id), Some(approval_id)) =
271 (turn_id.as_deref(), approval_id.as_deref())
272 {
273 self.approval.retire_owing(approval_id, turn_id, 0);
274 }
275 }
276 }
277 }
278 "approval/updated" => {
279 let approval_id = approval_id(¶ms);
280 match decode::<ApprovalUpdatedParams>(&method, params) {
281 Ok(params) => self.approval.enqueue_updated(self, params),
282 Err(error) => {
283 let tracked = approval_id.as_deref().and_then(|approval_id| {
284 Some((approval_id, self.approval.tracked_turn(approval_id)?))
285 });
286 let turn_id = tracked.as_ref().map(|(_, turn_id)| turn_id.clone());
287 self.fail_named_turn(turn_id, error);
288 if let Some((approval_id, _)) = tracked {
289 self.approval.retire_tracked(approval_id);
290 }
291 }
292 }
293 }
294 "approval/resolved" => {
295 let approval_id = approval_id(¶ms);
296 match decode::<ApprovalResolvedParams>(&method, params) {
297 Ok(params) => {
298 self.approval.retire(¶ms.approval_id);
299 }
300 Err(_) => {
301 if let Some(approval_id) = approval_id.as_deref() {
302 self.approval.retire(approval_id);
303 }
304 }
305 }
306 }
307 "turn/started" => {
308 let turn_id = turn_id(¶ms);
309 match decode::<TurnStartedParams>(&method, params) {
310 Ok(params) => self.mark_started(¶ms.turn_id),
311 Err(error) => self.fail_named_turn(turn_id, error),
312 }
313 }
314 "turn/completed" => {
315 let turn_id = turn_id(¶ms);
316 match decode::<TurnCompletedParams>(&method, params) {
317 Ok(params) => self.settle_turn(params),
318 Err(error) => self.fail_named_turn(turn_id, error),
319 }
320 }
321 "turn/unqueued" => {
322 let turn_id = turn_id(¶ms);
323 match decode::<TurnUnqueuedParams>(&method, params) {
324 Ok(params) => self.settle_unqueued(params),
325 Err(error) => self.fail_named_turn(turn_id, error),
326 }
327 }
328 _ => {}
329 }
330 }
331
332 pub(crate) fn transport_ended(&self, discard: bool) {
333 self.approval.abort();
334 self.gaps.abort();
335 self.stop_fold_on_cut_fill();
338 let mut state = lock(&self.state);
339 state.settle_source_failure(TurnWaitError::SourceClosed);
340 if !discard {
341 return;
342 }
343 state.discarded = true;
344 state.last_turn_settled = None;
345 state.pending_commands.clear();
346 state.forget_submissions();
347 state.settled_turns.clear();
348 state.settled_turn_order.clear();
349 state.retired_turns.clear();
350 state.retired_turn_order.clear();
351 }
352
353 pub(crate) fn is_command_discarded(&self, command_id: &str) -> bool {
354 lock(&self.state).is_command_discarded(command_id)
355 }
356
357 pub(crate) fn fail_event_source(&self, failure: TurnWaitError) {
358 if matches!(failure, TurnWaitError::EventSourceFailed { .. }) {
359 self.mark_fold_lost();
360 }
361 self.approval.abort();
362 self.gaps.abort();
363 self.stop_fold_on_cut_fill();
365 lock(&self.state).settle_source_failure(failure);
366 }
367
368 #[cfg(test)]
371 pub(crate) fn event_source_failure(&self) -> Option<TurnWaitError> {
372 lock(&self.state).event_source_failure.clone()
373 }
374
375 fn client_closed(&self) -> bool {
378 self.client.is_closed()
379 }
380
381 pub(crate) fn begin_close(&self) -> Option<tokio::task::JoinHandle<()>> {
382 let worker = self.approval.detach();
383 self.fail_event_source(TurnWaitError::ClientClosed);
385 worker
386 }
387}
388
389#[cfg(test)]
390mod tests {
391 use std::collections::HashSet;
392 use std::future::Future;
393 use std::io;
394 use std::pin::Pin;
395 use std::task::{Context, Poll, Waker};
396
397 use tokio::sync::mpsc;
398
399 use super::state::TurnRoute;
400 use super::*;
401 use crate::DuplexTransport;
402 use crate::client::{MuseClient, ResumeSessionOptions, StartSessionOptions};
403 use crate::msp::SessionDurability;
404 use crate::turn::{TurnHandle, TurnOutcome};
405
406 struct ChannelTransport {
407 inbound: mpsc::UnboundedReceiver<String>,
408 }
409
410 impl DuplexTransport for ChannelTransport {
411 fn read_chunk(
412 &mut self,
413 ) -> Pin<Box<dyn Future<Output = io::Result<Option<String>>> + Send + '_>> {
414 Box::pin(async { Ok(self.inbound.recv().await) })
415 }
416
417 fn write(
418 &mut self,
419 _frame: &str,
420 ) -> Pin<Box<dyn Future<Output = io::Result<()>> + Send + '_>> {
421 Box::pin(async { Ok(()) })
422 }
423 }
424
425 struct RepliesOnWrite {
430 inbound: mpsc::UnboundedReceiver<String>,
431 outbound: mpsc::UnboundedSender<String>,
432 replies: std::collections::VecDeque<(&'static str, serde_json::Value)>,
433 }
434
435 impl DuplexTransport for RepliesOnWrite {
436 fn read_chunk(
437 &mut self,
438 ) -> Pin<Box<dyn Future<Output = io::Result<Option<String>>> + Send + '_>> {
439 Box::pin(async { Ok(self.inbound.recv().await) })
440 }
441
442 fn write(
443 &mut self,
444 frame: &str,
445 ) -> Pin<Box<dyn Future<Output = io::Result<()>> + Send + '_>> {
446 if let Ok(request) = serde_json::from_str::<serde_json::Value>(frame.trim())
447 && self
448 .replies
449 .front()
450 .is_some_and(|(method, _)| request["method"] == *method)
451 && let Some((_, mut reply)) = self.replies.pop_front()
452 {
453 reply["id"] = request["id"].clone();
454 let _ = self.outbound.send(format!("{reply}\n"));
455 }
456 Box::pin(async { Ok(()) })
457 }
458 }
459
460 fn poll_once<F: Future + ?Sized>(future: Pin<&mut F>) -> Poll<F::Output> {
461 future.poll(&mut Context::from_waker(Waker::noop()))
462 }
463
464 #[tokio::test(flavor = "current_thread")]
469 async fn transport_end_does_not_abort_a_handler_waiting_in_close() {
470 let (outbound, inbound) = mpsc::unbounded_channel();
471 let replies = std::collections::VecDeque::from([(
472 "session/start",
473 serde_json::json!({
474 "jsonrpc": "2.0",
475 "id": 0,
476 "result": {
477 "session": {
478 "sessionId": "session-1",
479 "path": "/tmp/session-1.jsonl",
480 "status": "idle",
481 "activeTurnId": null,
482 "createdAt": "2026-09-29T00:00:00Z",
483 "updatedAt": "2026-09-29T00:00:00Z",
484 "workspaceRoot": null,
485 "providerId": null,
486 "modelId": null,
487 "turnCount": 0,
488 "forkedFrom": null
489 },
490 "viewCursor": "cursor-1"
491 }
492 }),
493 )]);
494 let client = Arc::new(MuseClient::with_command_id_minter(
495 RepliesOnWrite {
496 inbound,
497 outbound,
498 replies,
499 },
500 SessionDurability::Durable,
501 || "command-1".to_owned(),
502 ));
503 let session = client.start_session(StartSessionOptions::default()).await;
504 assert!(session.is_ok(), "session opens");
505 let Ok(session) = session else {
506 return;
507 };
508
509 let (entered_tx, entered_rx) = tokio::sync::oneshot::channel::<()>();
510 let (release_tx, release_rx) = tokio::sync::oneshot::channel::<()>();
511 let (done_tx, done_rx) = tokio::sync::oneshot::channel::<()>();
512 let signals = Arc::new(Mutex::new(Some((entered_tx, release_rx, done_tx))));
513 let handler_client = Arc::clone(&client);
514 session.on_approval(move |_| {
515 let client = Arc::clone(&handler_client);
516 let signals = lock(&signals).take();
517 async move {
518 if let Some((entered_tx, release_rx, done_tx)) = signals {
519 let mut close = Box::pin(client.close());
520 let _ = poll_once(close.as_mut());
521 let _ = entered_tx.send(());
522 let _ = release_rx.await;
523 let _ = done_tx.send(());
524 }
525 ApprovalDecisionInput {
526 choice_id: "allow_once".to_owned(),
527 feedback: None,
528 }
529 }
530 });
531 session.inner.apply(approval_requested("approval-1"));
532
533 assert!(entered_rx.await.is_ok(), "handler entered close()");
535 session.inner.transport_ended(false);
536 let _ = release_tx.send(());
537 assert!(
538 done_rx.await.is_ok(),
539 "transport end aborted the closing handler"
540 );
541 }
542
543 fn approval_requested(approval_id: &str) -> Notification {
545 Notification {
546 jsonrpc: crate::msp::JsonRpcVersion::V2,
547 method: "approval/requested".to_owned(),
548 params: serde_json::json!({
549 "sessionId": "session-1",
550 "approvalId": approval_id,
551 "turnId": "turn-1",
552 "taskId": "task-1",
553 "itemId": "item-1",
554 "toolCallId": "call-1",
555 "toolName": "shell",
556 "rawArgs": "{}",
557 "viewCursor": "cursor-2",
558 "sourceRange": {
559 "stream": {"kind": "run", "id": "turn-1"},
560 "first": {"id": "event-1", "sequence": 1},
561 "last": {"id": "event-1", "sequence": 1}
562 },
563 "subject": {"kind": "shell", "command": "pwd"},
564 "currentRequirementId": {"approvalId": approval_id, "sourceIndex": 0},
565 "availableChoices": [
566 {
567 "choiceId": "allow_once",
568 "label": "Allow once",
569 "decision": "approved",
570 "scope": "once"
571 },
572 {
573 "choiceId": "abort",
574 "label": "Abort",
575 "decision": "abort",
576 "scope": "once"
577 }
578 ],
579 "protectedWrite": false,
580 "judgeEscalated": false
581 })
582 .as_object()
583 .cloned(),
584 emitted_at_ms: None,
585 }
586 }
587
588 type ApprovalFixture = fn(&str) -> Notification;
590
591 fn allow_only_approval_requested(approval_id: &str) -> Notification {
594 let mut notification = approval_requested(approval_id);
595 if let Some(params) = notification.params.as_mut() {
596 params.insert(
597 "availableChoices".to_owned(),
598 serde_json::json!([{
599 "choiceId": "allow_once",
600 "label": "Allow once",
601 "decision": "approved",
602 "scope": "once"
603 }]),
604 );
605 }
606 notification
607 }
608
609 #[tokio::test(flavor = "current_thread")]
616 async fn an_approval_routed_while_a_handler_closes_the_client_reaches_no_handler() {
617 let cases: [(&str, ApprovalFixture, &str); 4] = [
618 ("an allow and an abort", approval_requested, "not_offered"),
619 ("an allow and an abort", approval_requested, "allow_once"),
620 ("an allow and an abort", approval_requested, "abort"),
621 (
622 "only an allow",
623 allow_only_approval_requested,
624 "not_offered",
625 ),
626 ];
627 for (offered, approval, answer) in cases {
628 let (inbound, reads) = mpsc::unbounded_channel();
629 let client = Arc::new(MuseClient::with_command_id_minter(
630 ChannelTransport { inbound: reads },
631 SessionDurability::Durable,
632 || "command-1".to_owned(),
633 ));
634 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
635 let session = client.start_session(StartSessionOptions::default()).await;
636 assert!(session.is_ok(), "the session opens");
637 let Ok(session) = session else {
638 return;
639 };
640
641 let (routed_tx, mut routed) = mpsc::unbounded_channel::<String>();
642 let (closed_tx, closed_rx) = tokio::sync::oneshot::channel::<()>();
643 let (release_tx, release_rx) = tokio::sync::oneshot::channel::<()>();
644 let (answered_tx, answered_rx) = tokio::sync::oneshot::channel::<()>();
645 let signals = Arc::new(Mutex::new(Some((closed_tx, release_rx, answered_tx))));
646 let handler_client = Arc::clone(&client);
647 session.on_approval(move |request| {
648 let _ = routed_tx.send(request.approval_id);
649 let client = Arc::clone(&handler_client);
650 let signals = lock(&signals).take();
651 async move {
652 if let Some((closed_tx, release_rx, answered_tx)) = signals {
653 client.close().await;
654 let _ = closed_tx.send(());
655 let _ = release_rx.await;
656 let _ = answered_tx.send(());
657 }
658 ApprovalDecisionInput {
659 choice_id: answer.to_owned(),
660 feedback: None,
661 }
662 }
663 });
664 session.inner.apply(approval("approval-1"));
665 assert!(closed_rx.await.is_ok(), "the handler closed the client");
666 assert_eq!(routed.recv().await.as_deref(), Some("approval-1"));
667 session.inner.apply(approval("approval-2"));
670 let _ = release_tx.send(());
671 assert!(answered_rx.await.is_ok(), "the closing handler answered");
672
673 let rerouted = tokio::select! {
677 biased;
678 approval_id = routed.recv() => approval_id,
679 () = session.inner.approval.worker_stopped() => None,
680 };
681 assert_eq!(
682 rerouted, None,
683 "after answering {answer:?} to an approval offering {offered}, the closing handler's worker routed another approval"
684 );
685 }
686 }
687
688 #[tokio::test(flavor = "current_thread")]
695 async fn an_approval_answered_after_the_transport_ended_leaves_its_turn_to_the_sweep() {
696 let (inbound, reads) = mpsc::unbounded_channel();
697 let client = MuseClient::with_command_id_minter(
698 ChannelTransport { inbound: reads },
699 SessionDurability::Durable,
700 || "command-1".to_owned(),
701 );
702 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
703 let session = client.start_session(StartSessionOptions::default()).await;
704 assert!(session.is_ok(), "the session opens");
705 let Ok(session) = session else {
706 return;
707 };
708 drop(inbound);
711 let ended = client
712 .start_session(StartSessionOptions::default())
713 .await
714 .err();
715 assert!(
716 matches!(ended, Some(crate::client::FacadeError::TransportEnded)),
717 "control: a request after the end sees TransportEnded, got {ended:?}"
718 );
719
720 let unsettled = Session::from_opening(
722 Arc::clone(&session.inner.client),
723 session.opening().clone(),
724 &[],
725 None,
726 );
727 let turn = unsettled.inner.claim_turn_for_ordering_tests("turn-1");
728 unsettled.inner.apply(approval_requested("approval-1"));
729 let completion = turn.completed();
730 let stopped = unsettled.inner.approval.worker_stopped();
731 let settled = tokio::time::timeout(std::time::Duration::from_secs(5), async {
733 tokio::select! {
734 biased;
735 outcome = completion => Some(outcome),
738 () = stopped => None,
739 }
740 })
741 .await;
742 assert!(
743 matches!(settled, Ok(None)),
744 "a worker refused with TransportEnded must stop and leave the turn to the sweep, got {settled:?}"
745 );
746 }
747
748 #[tokio::test(flavor = "current_thread")]
753 async fn an_approval_decide_cut_short_by_the_transport_end_leaves_its_turn_to_the_sweep() {
754 let (inbound, reads) = mpsc::unbounded_channel();
755 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
756 let host = Arc::new(Mutex::new(Some(inbound)));
758 let minted = Arc::new(std::sync::atomic::AtomicUsize::new(0));
759 let minter_host = Arc::clone(&host);
760 let client = MuseClient::with_command_id_minter(
761 ChannelTransport { inbound: reads },
762 SessionDurability::Durable,
763 move || {
764 if minted.fetch_add(1, std::sync::atomic::Ordering::Relaxed) == 1 {
765 lock(&minter_host).take();
766 }
767 "command-1".to_owned()
768 },
769 );
770 let session = client.start_session(StartSessionOptions::default()).await;
771 assert!(session.is_ok(), "the session opens");
772 let Ok(session) = session else {
773 return;
774 };
775
776 let unsettled = Session::from_opening(
778 Arc::clone(&session.inner.client),
779 session.opening().clone(),
780 &[],
781 None,
782 );
783 let turn = unsettled.inner.claim_turn_for_ordering_tests("turn-1");
784 unsettled.inner.apply(approval_requested("approval-1"));
785 let completion = turn.completed();
786 let stopped = unsettled.inner.approval.worker_stopped();
787 let settled = tokio::time::timeout(std::time::Duration::from_secs(5), async {
789 tokio::select! {
790 biased;
791 outcome = completion => Some(outcome),
794 () = stopped => None,
795 }
796 })
797 .await;
798 assert!(
799 lock(&host).is_none(),
800 "control: the worker minted the approval's command id"
801 );
802 assert!(
803 matches!(settled, Ok(None)),
804 "a decide cut short by the transport end must stop the worker and leave the turn to the sweep, got {settled:?}"
805 );
806 }
807
808 #[test]
809 fn settled_turns_leave_session_routing_state() {
810 let handle = TurnHandle::new("turn-1");
811 let mut state = SessionState::default();
812 state.turns.insert(
813 "turn-1".to_owned(),
814 TurnRoute {
815 handle,
816 item_ids: HashSet::from(["item-1".to_owned(), "item-2".to_owned()]),
817 },
818 );
819 state
820 .item_turns
821 .insert("item-1".to_owned(), "turn-1".to_owned());
822 state
823 .item_turns
824 .insert("item-2".to_owned(), "turn-1".to_owned());
825
826 assert!(state.settle_and_retire_turn("turn-1", |handle| {
827 handle.fail(TurnWaitError::EventSourceFailed {
828 message: "settled".to_owned(),
829 });
830 }));
831 assert!(state.turns.is_empty());
832 assert!(state.item_turns.is_empty());
833 }
834
835 #[test]
841 fn frames_held_past_the_gap_hold_bound_fail_the_event_source() {
842 let runtime = tokio::runtime::Builder::new_current_thread()
843 .enable_all()
844 .build();
845 assert!(runtime.is_ok(), "caller runtime builds");
846 let Ok(runtime) = runtime else {
847 return;
848 };
849 runtime.block_on(async {
850 let (outbound, inbound) = mpsc::unbounded_channel();
851 let replies = std::collections::VecDeque::from([
852 ("session/start", serde_json::json!({
853 "jsonrpc": "2.0",
854 "id": 0,
855 "result": {
856 "session": {
857 "sessionId": "session-1",
858 "path": "/tmp/session.jsonl",
859 "status": "idle",
860 "activeTurnId": null,
861 "createdAt": "2026-09-29T00:00:00Z",
862 "updatedAt": "2026-09-29T00:00:00Z",
863 "workspaceRoot": null,
864 "providerId": null,
865 "modelId": null,
866 "turnCount": 0,
867 "forkedFrom": null
868 },
869 "viewCursor": "cursor-1"
870 }
871 })),
872 ("session/start", serde_json::json!({
873 "jsonrpc": "2.0",
874 "id": 0,
875 "result": {
876 "session": {
877 "sessionId": "session-2",
878 "path": "/tmp/session-2.jsonl",
879 "status": "idle",
880 "activeTurnId": null,
881 "createdAt": "2026-09-29T00:00:00Z",
882 "updatedAt": "2026-09-29T00:00:00Z",
883 "workspaceRoot": null,
884 "providerId": null,
885 "modelId": null,
886 "turnCount": 0,
887 "forkedFrom": null
888 },
889 "viewCursor": "cursor-1"
890 }
891 })),
892 ]);
893 let client = MuseClient::with_command_id_minter(
894 RepliesOnWrite {
895 inbound,
896 outbound,
897 replies,
898 },
899 SessionDurability::Durable,
900 || "command-1".to_owned(),
901 );
902 let session = client.start_session(StartSessionOptions::default()).await;
903 assert!(session.is_ok(), "session opens");
904 let Ok(session) = session else {
905 return;
906 };
907 let notification = |method: &str, params: serde_json::Value| Notification {
908 jsonrpc: crate::msp::JsonRpcVersion::V2,
909 method: method.to_owned(),
910 params: params.as_object().cloned(),
911 emitted_at_ms: None,
912 };
913 session.inner.apply(notification(
914 "view/gap",
915 serde_json::json!({"sessionId": "session-1", "after": "cursor-2", "next": "cursor-5"}),
916 ));
917 for index in 0..=gap_route::MAX_HELD_GAP_FRAMES {
918 assert!(
919 lock(&session.inner.state).event_source_failure.is_none(),
920 "frame {index} is within the hold's bound"
921 );
922 session.inner.apply(notification(
923 "item/completed",
924 serde_json::json!({
925 "sessionId": "session-1",
926 "viewCursor": format!("cursor-{}", index + 6),
927 }),
928 ));
929 }
930 assert_eq!(
931 lock(&session.inner.state).event_source_failure,
932 Some(TurnWaitError::EventSourceFailed {
933 message: "notification backlog exceeded for this session behind a pending \
934 delivery gap"
935 .to_owned(),
936 })
937 );
938 let survivor = client.start_session(StartSessionOptions::default()).await;
942 assert!(
943 survivor.is_ok_and(|survivor| survivor.session_id() == "session-2"),
944 "another session on the same client survives the hold bound"
945 );
946 client.close().await;
947 });
948 }
949
950 fn opened_session(id: i64, session_id: &str) -> String {
951 format!(
952 "{}\n",
953 serde_json::json!({
954 "jsonrpc": "2.0",
955 "id": id,
956 "result": {
957 "session": {
958 "sessionId": session_id,
959 "path": "/tmp/session.jsonl",
960 "status": "idle",
961 "activeTurnId": null,
962 "createdAt": "2026-09-29T00:00:00Z",
963 "updatedAt": "2026-09-29T00:00:00Z",
964 "workspaceRoot": null,
965 "providerId": null,
966 "modelId": null,
967 "turnCount": 0,
968 "forkedFrom": null
969 },
970 "viewCursor": "cursor-1"
971 }
972 })
973 )
974 }
975
976 fn item_completed(session_id: &str, item_id: &str) -> Notification {
977 Notification {
978 jsonrpc: crate::msp::JsonRpcVersion::V2,
979 method: "item/completed".to_owned(),
980 params: serde_json::json!({
981 "sessionId": session_id,
982 "viewCursor": format!("cursor-{item_id}"),
983 "sourceRange": {
984 "stream": {"kind": "run", "id": "turn-1"},
985 "first": {"id": "event-1", "sequence": 1},
986 "last": {"id": "event-1", "sequence": 1}
987 },
988 "item": {
989 "itemId": item_id,
990 "kind": "agentMessage",
991 "turnId": "turn-1",
992 "revision": 1,
993 "status": "completed",
994 "text": "reply"
995 }
996 })
997 .as_object()
998 .cloned(),
999 emitted_at_ms: None,
1000 }
1001 }
1002
1003 #[test]
1009 fn a_lost_event_stops_only_its_own_session_fold() {
1010 let runtime = tokio::runtime::Builder::new_current_thread()
1011 .enable_all()
1012 .build();
1013 assert!(runtime.is_ok(), "caller runtime builds");
1014 let Ok(runtime) = runtime else {
1015 return;
1016 };
1017 runtime.block_on(async {
1018 let (inbound, reads) = mpsc::unbounded_channel();
1019 let client = MuseClient::with_command_id_minter(
1020 ChannelTransport { inbound: reads },
1021 SessionDurability::Durable,
1022 || "command-1".to_owned(),
1023 );
1024 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1025 let affected = client.start_session(StartSessionOptions::default()).await;
1026 assert!(affected.is_ok(), "the affected session opens");
1027 assert!(inbound.send(opened_session(2, "session-2")).is_ok());
1028 let unaffected = client.start_session(StartSessionOptions::default()).await;
1029 assert!(unaffected.is_ok(), "the unaffected session opens");
1030 let (Ok(affected), Ok(unaffected)) = (affected, unaffected) else {
1031 return;
1032 };
1033
1034 affected
1035 .inner
1036 .apply(item_completed("session-1", "item-before"));
1037 affected
1038 .inner
1039 .fail_event_source(TurnWaitError::EventSourceFailed {
1040 message: "notification backlog exceeded for this session; close this client, then resume the session on a new client to continue".to_owned(),
1041 });
1042 assert!(
1043 affected.fold().is_stopped(),
1044 "the loss alone stops the fold"
1045 );
1046 assert!(
1047 !affected.fold().is_current(),
1048 "the loss alone ends currency"
1049 );
1050 affected
1051 .inner
1052 .apply(item_completed("session-1", "item-after"));
1053 affected.inner.apply(Notification {
1054 jsonrpc: crate::msp::JsonRpcVersion::V2,
1055 method: "userInput/requested".to_owned(),
1056 params: serde_json::json!({"sessionId": "session-1", "userInputId": "input-after"})
1057 .as_object()
1058 .cloned(),
1059 emitted_at_ms: None,
1060 });
1061 unaffected
1062 .inner
1063 .apply(item_completed("session-2", "item-other"));
1064
1065 {
1066 let fold = affected.fold();
1067 assert!(fold.item("item-before").is_some());
1068 assert!(
1069 fold.item("item-after").is_none(),
1070 "nothing folds across the lost event"
1071 );
1072 assert!(
1073 fold.pending_user_inputs().is_empty(),
1074 "a lost event stops questions too"
1075 );
1076 assert!(!fold.is_current(), "the fold says it is incomplete");
1077 assert!(fold.is_stopped(), "the fold says it stopped for good");
1078 assert!(fold.pending_gap().is_none(), "no gap names the loss");
1079 }
1080 {
1081 let fold = unaffected.fold();
1082 assert!(fold.item("item-other").is_some());
1083 assert!(fold.is_current());
1084 assert!(!fold.is_stopped());
1085 }
1086
1087 client.close().await;
1088 assert!(
1089 unaffected.fold().is_current(),
1090 "closing the client loses no event"
1091 );
1092 assert!(!unaffected.fold().is_stopped());
1093 });
1094 }
1095
1096 #[test]
1100 fn a_failed_turn_wakes_to_a_stopped_fold_when_its_fill_was_cut() {
1101 struct ReadFoldOnWake {
1102 session: Session,
1103 seen: std::sync::Mutex<Option<bool>>,
1104 }
1105 impl std::task::Wake for ReadFoldOnWake {
1106 fn wake(self: Arc<Self>) {
1107 self.wake_by_ref();
1108 }
1109 fn wake_by_ref(self: &Arc<Self>) {
1110 let mut seen = self
1111 .seen
1112 .lock()
1113 .unwrap_or_else(std::sync::PoisonError::into_inner);
1114 if seen.is_none() {
1115 *seen = Some(self.session.fold().is_stopped());
1116 }
1117 }
1118 }
1119 let cuts: [fn(&SessionInner); 2] = [
1120 |inner| inner.fail_event_source(TurnWaitError::ClientClosed),
1121 |inner| inner.transport_ended(false),
1122 ];
1123 for cut in cuts {
1124 let runtime = tokio::runtime::Builder::new_current_thread()
1125 .enable_all()
1126 .build();
1127 assert!(runtime.is_ok(), "caller runtime builds");
1128 let Ok(runtime) = runtime else {
1129 return;
1130 };
1131 runtime.block_on(async {
1132 let (inbound, reads) = mpsc::unbounded_channel();
1133 let client = MuseClient::with_command_id_minter(
1134 ChannelTransport { inbound: reads },
1135 SessionDurability::Durable,
1136 || "command-1".to_owned(),
1137 );
1138 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1139 let session = client.start_session(StartSessionOptions::default()).await;
1140 assert!(session.is_ok(), "the session opens");
1141 let Ok(session) = session else {
1142 return;
1143 };
1144 let handle = TurnHandle::new("turn-1");
1145 let turn = handle.turn();
1146 lock(&session.inner.state).turns.insert(
1147 "turn-1".to_owned(),
1148 TurnRoute {
1149 handle,
1150 item_ids: HashSet::new(),
1151 },
1152 );
1153 let reader = Arc::new(ReadFoldOnWake {
1154 session: session.clone(),
1155 seen: std::sync::Mutex::new(None),
1156 });
1157 let waker = Waker::from(Arc::clone(&reader));
1158 let mut completed = Box::pin(turn.completed());
1159 assert!(
1160 completed
1161 .as_mut()
1162 .poll(&mut Context::from_waker(&waker))
1163 .is_pending()
1164 );
1165 session.inner.mirror_gap(Some(&crate::msp::ViewGapParams {
1166 session_id: "session-1".to_owned(),
1167 after: "cursor-2".to_owned(),
1168 next: "cursor-3".to_owned(),
1169 }));
1170
1171 cut(&session.inner);
1172 let seen = *reader
1173 .seen
1174 .lock()
1175 .unwrap_or_else(std::sync::PoisonError::into_inner);
1176 assert_eq!(seen, Some(true), "the woken turn reads a stopped fold");
1177 drop(completed);
1178 client.close().await;
1179 });
1180 }
1181 }
1182
1183 #[test]
1187 fn a_client_closed_failure_stops_a_fold_whose_fill_it_cuts() {
1188 let runtime = tokio::runtime::Builder::new_current_thread()
1189 .enable_all()
1190 .build();
1191 assert!(runtime.is_ok(), "caller runtime builds");
1192 let Ok(runtime) = runtime else {
1193 return;
1194 };
1195 runtime.block_on(async {
1196 let (inbound, reads) = mpsc::unbounded_channel();
1197 let client = MuseClient::with_command_id_minter(
1198 ChannelTransport { inbound: reads },
1199 SessionDurability::Durable,
1200 || "command-1".to_owned(),
1201 );
1202 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1203 let session = client.start_session(StartSessionOptions::default()).await;
1204 assert!(session.is_ok(), "the session opens");
1205 let Ok(session) = session else {
1206 return;
1207 };
1208 session.inner.mirror_gap(Some(&crate::msp::ViewGapParams {
1209 session_id: "session-1".to_owned(),
1210 after: "cursor-2".to_owned(),
1211 next: "cursor-3".to_owned(),
1212 }));
1213 assert!(!session.fold().is_stopped(), "the fill is still running");
1214 session.inner.fail_event_source(TurnWaitError::ClientClosed);
1215 let fold = session.fold();
1216 assert!(fold.pending_gap().is_some());
1217 assert!(fold.is_stopped(), "the close failure cut the fill");
1218 client.close().await;
1219 });
1220 }
1221
1222 #[test]
1225 fn transport_end_stops_a_fold_whose_fill_it_cuts() {
1226 let runtime = tokio::runtime::Builder::new_current_thread()
1227 .enable_all()
1228 .build();
1229 assert!(runtime.is_ok(), "caller runtime builds");
1230 let Ok(runtime) = runtime else {
1231 return;
1232 };
1233 runtime.block_on(async {
1234 let (inbound, reads) = mpsc::unbounded_channel();
1235 let client = MuseClient::with_command_id_minter(
1236 ChannelTransport { inbound: reads },
1237 SessionDurability::Durable,
1238 || "command-1".to_owned(),
1239 );
1240 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1241 let session = client.start_session(StartSessionOptions::default()).await;
1242 assert!(session.is_ok(), "the session opens");
1243 let Ok(session) = session else {
1244 return;
1245 };
1246 session.inner.mirror_gap(Some(&crate::msp::ViewGapParams {
1247 session_id: "session-1".to_owned(),
1248 after: "cursor-2".to_owned(),
1249 next: "cursor-3".to_owned(),
1250 }));
1251 assert!(!session.fold().is_stopped(), "the fill is still running");
1252
1253 session.inner.transport_ended(false);
1254 let fold = session.fold();
1255 assert!(fold.pending_gap().is_some());
1256 assert!(fold.is_stopped(), "nothing can fill the hole after the end");
1257 client.close().await;
1258 });
1259 }
1260
1261 #[test]
1264 fn close_stops_a_fold_whose_fill_it_cuts() {
1265 let runtime = tokio::runtime::Builder::new_current_thread()
1266 .enable_all()
1267 .build();
1268 assert!(runtime.is_ok(), "caller runtime builds");
1269 let Ok(runtime) = runtime else {
1270 return;
1271 };
1272 runtime.block_on(async {
1273 let (inbound, reads) = mpsc::unbounded_channel();
1274 let client = MuseClient::with_command_id_minter(
1275 ChannelTransport { inbound: reads },
1276 SessionDurability::Durable,
1277 || "command-1".to_owned(),
1278 );
1279 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1280 let session = client.start_session(StartSessionOptions::default()).await;
1281 assert!(session.is_ok(), "the session opens");
1282 let Ok(session) = session else {
1283 return;
1284 };
1285 session.inner.mirror_gap(Some(&crate::msp::ViewGapParams {
1286 session_id: "session-1".to_owned(),
1287 after: "cursor-2".to_owned(),
1288 next: "cursor-3".to_owned(),
1289 }));
1290 assert!(!session.fold().is_stopped(), "the fill is still running");
1291
1292 drop(session.inner.begin_close());
1294 let fold = session.fold();
1295 assert!(fold.pending_gap().is_some());
1296 assert!(fold.is_stopped(), "nothing can fill the hole after close");
1297 client.close().await;
1298 });
1299 }
1300
1301 #[test]
1306 fn a_frame_after_close_does_not_fold() {
1307 let runtime = tokio::runtime::Builder::new_current_thread()
1308 .enable_all()
1309 .build();
1310 assert!(runtime.is_ok(), "caller runtime builds");
1311 let Ok(runtime) = runtime else {
1312 return;
1313 };
1314 runtime.block_on(async {
1315 let (inbound, reads) = mpsc::unbounded_channel();
1316 let client = MuseClient::with_command_id_minter(
1317 ChannelTransport { inbound: reads },
1318 SessionDurability::Durable,
1319 || "command-1".to_owned(),
1320 );
1321 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1322 let session = client.start_session(StartSessionOptions::default()).await;
1323 assert!(session.is_ok(), "the session opens");
1324 let Ok(session) = session else {
1325 return;
1326 };
1327 session
1328 .inner
1329 .apply(item_completed("session-1", "item-before"));
1330 drop(session.inner.begin_close());
1331 session
1332 .inner
1333 .apply(item_completed("session-1", "item-after"));
1334
1335 {
1336 let fold = session.fold();
1337 assert!(fold.item("item-before").is_some());
1338 assert!(
1339 fold.item("item-after").is_none(),
1340 "the tail after close never folds"
1341 );
1342 assert!(fold.is_stopped(), "the dropped frame stops the fold");
1343 assert!(!fold.is_current());
1344 }
1345 client.close().await;
1346 });
1347 }
1348
1349 #[test]
1352 fn a_loss_after_a_reopen_stops_question_events() {
1353 let runtime = tokio::runtime::Builder::new_current_thread()
1354 .enable_all()
1355 .build();
1356 assert!(runtime.is_ok(), "caller runtime builds");
1357 let Ok(runtime) = runtime else {
1358 return;
1359 };
1360 runtime.block_on(async {
1361 let (inbound, reads) = mpsc::unbounded_channel();
1362 let client = MuseClient::with_command_id_minter(
1363 ChannelTransport { inbound: reads },
1364 SessionDurability::Durable,
1365 || "command-1".to_owned(),
1366 );
1367 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1368 let session = client.start_session(StartSessionOptions::default()).await;
1369 assert!(session.is_ok(), "the session opens");
1370 let Ok(session) = session else {
1371 return;
1372 };
1373 let question = |id: &str| Notification {
1374 jsonrpc: crate::msp::JsonRpcVersion::V2,
1375 method: "userInput/requested".to_owned(),
1376 params: serde_json::json!({"sessionId": "session-1", "userInputId": id})
1377 .as_object()
1378 .cloned(),
1379 emitted_at_ms: None,
1380 };
1381 session.mark_fold_reopened();
1382 session.inner.apply(question("input-before"));
1383 session
1384 .inner
1385 .fail_event_source(TurnWaitError::EventSourceFailed {
1386 message: "notification backlog exceeded for this session; close this client, then resume the session on a new client to continue".to_owned(),
1387 });
1388 session.inner.apply(question("input-after"));
1389
1390 let pending: Vec<String> = session
1391 .fold()
1392 .pending_user_inputs()
1393 .iter()
1394 .filter_map(|input| input["userInputId"].as_str().map(str::to_owned))
1395 .collect();
1396 assert_eq!(
1397 pending,
1398 ["input-before"],
1399 "the re-opened fold took the first question; the loss stopped the second"
1400 );
1401 client.close().await;
1402 });
1403 }
1404
1405 #[test]
1409 fn a_close_after_a_reopen_stops_question_events() {
1410 let runtime = tokio::runtime::Builder::new_current_thread()
1411 .enable_all()
1412 .build();
1413 assert!(runtime.is_ok(), "caller runtime builds");
1414 let Ok(runtime) = runtime else {
1415 return;
1416 };
1417 runtime.block_on(async {
1418 let (inbound, reads) = mpsc::unbounded_channel();
1419 let client = MuseClient::with_command_id_minter(
1420 ChannelTransport { inbound: reads },
1421 SessionDurability::Durable,
1422 || "command-1".to_owned(),
1423 );
1424 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1425 let session = client.start_session(StartSessionOptions::default()).await;
1426 assert!(session.is_ok(), "the session opens");
1427 let Ok(session) = session else {
1428 return;
1429 };
1430 let question = |id: &str| Notification {
1431 jsonrpc: crate::msp::JsonRpcVersion::V2,
1432 method: "userInput/requested".to_owned(),
1433 params: serde_json::json!({"sessionId": "session-1", "userInputId": id})
1434 .as_object()
1435 .cloned(),
1436 emitted_at_ms: None,
1437 };
1438 session.mark_fold_reopened();
1439 session.inner.apply(question("input-before"));
1440 drop(session.inner.begin_close());
1441 session.inner.apply(question("input-after"));
1442
1443 let pending: Vec<String> = session
1444 .fold()
1445 .pending_user_inputs()
1446 .iter()
1447 .filter_map(|input| input["userInputId"].as_str().map(str::to_owned))
1448 .collect();
1449 assert_eq!(
1450 pending,
1451 ["input-before"],
1452 "the re-opened fold took the first question; the close stopped the second"
1453 );
1454 client.close().await;
1455 });
1456 }
1457
1458 #[test]
1462 fn a_fold_view_holds_no_lock_between_reads() {
1463 let runtime = tokio::runtime::Builder::new_current_thread()
1464 .enable_all()
1465 .build();
1466 assert!(runtime.is_ok(), "caller runtime builds");
1467 let Ok(runtime) = runtime else {
1468 return;
1469 };
1470 runtime.block_on(async {
1471 let (inbound, reads) = mpsc::unbounded_channel();
1472 let client = MuseClient::with_command_id_minter(
1473 ChannelTransport { inbound: reads },
1474 SessionDurability::Durable,
1475 || "command-1".to_owned(),
1476 );
1477 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1478 let session = client.start_session(StartSessionOptions::default()).await;
1479 assert!(session.is_ok(), "the session opens");
1480 let Ok(session) = session else {
1481 return;
1482 };
1483
1484 let view = session.fold();
1485 assert!(view.item("item-later").is_none());
1486 assert!(
1487 session.inner.fold.try_lock().is_ok(),
1488 "a kept view must not hold the fold lock"
1489 );
1490 session
1491 .inner
1492 .apply(item_completed("session-1", "item-later"));
1493 assert!(
1494 view.item("item-later").is_some(),
1495 "the next read sees the event applied after the last one"
1496 );
1497 client.close().await;
1498 });
1499 }
1500
1501 #[test]
1504 fn an_extended_delivery_gap_moves_the_fold_to_the_new_target() {
1505 let runtime = tokio::runtime::Builder::new_current_thread()
1506 .enable_all()
1507 .build();
1508 assert!(runtime.is_ok(), "caller runtime builds");
1509 let Ok(runtime) = runtime else {
1510 return;
1511 };
1512 runtime.block_on(async {
1513 let (inbound, reads) = mpsc::unbounded_channel();
1514 let client = MuseClient::with_command_id_minter(
1515 ChannelTransport { inbound: reads },
1516 SessionDurability::Durable,
1517 || "command-1".to_owned(),
1518 );
1519 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1520 let session = client.start_session(StartSessionOptions::default()).await;
1521 assert!(session.is_ok(), "the session opens");
1522 let Ok(session) = session else {
1523 return;
1524 };
1525 let gap = |after: &str, next: &str| Notification {
1526 jsonrpc: crate::msp::JsonRpcVersion::V2,
1527 method: "view/gap".to_owned(),
1528 params: serde_json::json!({"sessionId": "session-1", "after": after, "next": next})
1529 .as_object()
1530 .cloned(),
1531 emitted_at_ms: None,
1532 };
1533
1534 session.inner.apply(gap("cursor-2", "cursor-3"));
1535 session.inner.apply(gap("cursor-3", "cursor-5"));
1536
1537 let fold = session.fold();
1538 assert!(!fold.is_current());
1539 let pending = fold
1540 .pending_gap()
1541 .map(|gap| (gap.after().to_owned(), gap.next().to_owned()));
1542 assert_eq!(
1543 pending,
1544 Some(("cursor-2".to_owned(), "cursor-5".to_owned()))
1545 );
1546 client.close().await;
1547 });
1548 }
1549
1550 #[test]
1554 fn a_fold_view_reads_approvals_user_inputs_deltas_and_the_active_turn() {
1555 let runtime = tokio::runtime::Builder::new_current_thread()
1556 .enable_all()
1557 .build();
1558 assert!(runtime.is_ok(), "caller runtime builds");
1559 let Ok(runtime) = runtime else {
1560 return;
1561 };
1562 runtime.block_on(async {
1563 let (inbound, reads) = mpsc::unbounded_channel();
1564 let client = MuseClient::with_command_id_minter(
1565 ChannelTransport { inbound: reads },
1566 SessionDurability::Durable,
1567 || "command-1".to_owned(),
1568 );
1569 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1570 let session = client.start_session(StartSessionOptions::default()).await;
1571 assert!(session.is_ok(), "the session opens");
1572 let Ok(session) = session else {
1573 return;
1574 };
1575 let note = |method: &str, params: serde_json::Value| Notification {
1576 jsonrpc: crate::msp::JsonRpcVersion::V2,
1577 method: method.to_owned(),
1578 params: params.as_object().cloned(),
1579 emitted_at_ms: None,
1580 };
1581 let range = serde_json::json!({
1582 "stream": {"kind": "run", "id": "turn-9"},
1583 "first": {"id": "event-1", "sequence": 1},
1584 "last": {"id": "event-1", "sequence": 1}
1585 });
1586 for (approval_id, resolve) in [("approval-1", true), ("approval-2", false)] {
1587 session.inner.apply(note(
1588 "approval/requested",
1589 serde_json::json!({
1590 "sessionId": "session-1",
1591 "approvalId": approval_id,
1592 "turnId": "turn-9",
1593 "taskId": format!("task-{approval_id}"),
1594 "itemId": format!("item-{approval_id}"),
1595 "toolCallId": format!("call-{approval_id}"),
1596 "toolName": "shell",
1597 "rawArgs": "{}",
1598 "viewCursor": format!("cursor-{approval_id}"),
1599 "sourceRange": range,
1600 "subject": {"kind": "shell", "command": "pwd"},
1601 "currentRequirementId": {"approvalId": approval_id, "sourceIndex": 0},
1602 "availableChoices": [],
1603 "protectedWrite": false,
1604 "judgeEscalated": false
1605 }),
1606 ));
1607 if resolve {
1608 session.inner.apply(note(
1609 "approval/resolved",
1610 serde_json::json!({"sessionId": "session-1", "approvalId": approval_id}),
1611 ));
1612 }
1613 }
1614 for input in ["input-1", "input-2"] {
1615 session.inner.apply(note(
1616 "userInput/requested",
1617 serde_json::json!({"sessionId": "session-1", "userInputId": input}),
1618 ));
1619 }
1620 session.inner.apply(note(
1621 "userInput/settled",
1622 serde_json::json!({"sessionId": "session-1", "userInputId": "input-1"}),
1623 ));
1624 session.inner.apply(note(
1625 "turn/started",
1626 serde_json::json!({
1627 "sessionId": "session-1",
1628 "viewCursor": "cursor-t",
1629 "sourceRange": range,
1630 "turnId": "turn-9",
1631 "commandId": "command-9"
1632 }),
1633 ));
1634 session.inner.apply(note(
1635 "item/started",
1636 serde_json::json!({
1637 "sessionId": "session-1",
1638 "viewCursor": "cursor-i",
1639 "sourceRange": range,
1640 "item": {
1641 "itemId": "item-a",
1642 "kind": "agentMessage",
1643 "turnId": "turn-9",
1644 "revision": 1,
1645 "status": "inProgress",
1646 "text": ""
1647 }
1648 }),
1649 ));
1650 session.inner.apply(note(
1651 "item/delta",
1652 serde_json::json!({
1653 "sessionId": "session-1",
1654 "viewCursor": "cursor-d",
1655 "itemId": "item-a",
1656 "delta": "hi"
1657 }),
1658 ));
1659
1660 let fold = session.fold();
1661 assert!(fold.pending_approval("approval-1").is_none());
1662 assert!(fold.resolved_approval("approval-1").is_some());
1663 assert!(fold.pending_approval("approval-2").is_some());
1664 assert!(fold.resolved_approval("approval-2").is_none());
1665 let ids = |inputs: Vec<serde_json::Value>| -> Vec<String> {
1666 inputs
1667 .iter()
1668 .filter_map(|input| input["userInputId"].as_str().map(str::to_owned))
1669 .collect()
1670 };
1671 assert_eq!(ids(fold.pending_user_inputs()), ["input-2"]);
1672 assert_eq!(ids(fold.settled_user_inputs()), ["input-1"]);
1673 assert!(fold.pending_user_input("input-2").is_some());
1674 assert!(fold.settled_user_input("input-1").is_some());
1675 assert_eq!(fold.accumulated("item-a", "text"), Some("hi".to_owned()));
1676 assert_eq!(fold.active_turn_id(), Some("turn-9".to_owned()));
1677 client.close().await;
1678 });
1679 }
1680
1681 #[test]
1685 fn a_fold_view_lists_item_and_turn_ids_in_first_seen_order() {
1686 let runtime = tokio::runtime::Builder::new_current_thread()
1687 .enable_all()
1688 .build();
1689 assert!(runtime.is_ok(), "caller runtime builds");
1690 let Ok(runtime) = runtime else {
1691 return;
1692 };
1693 runtime.block_on(async {
1694 let (inbound, reads) = mpsc::unbounded_channel();
1695 let client = MuseClient::with_command_id_minter(
1696 ChannelTransport { inbound: reads },
1697 SessionDurability::Durable,
1698 || "command-1".to_owned(),
1699 );
1700 assert!(inbound.send(opened_session(1, "session-1")).is_ok());
1701 let session = client.start_session(StartSessionOptions::default()).await;
1702 assert!(session.is_ok(), "the session opens");
1703 let Ok(session) = session else {
1704 return;
1705 };
1706 let note = |method: &str, params: serde_json::Value| Notification {
1707 jsonrpc: crate::msp::JsonRpcVersion::V2,
1708 method: method.to_owned(),
1709 params: params.as_object().cloned(),
1710 emitted_at_ms: None,
1711 };
1712 let order = ["e", "b", "g", "a", "h", "c", "f", "d"];
1715 for (revision, id) in [(1, "e"), (1, "b"), (1, "g"), (1, "a"), (2, "b")]
1716 .into_iter()
1717 .chain([(1, "h"), (1, "c"), (1, "f"), (1, "d"), (2, "e")])
1718 {
1719 session.inner.apply(note(
1720 "item/updated",
1721 serde_json::json!({
1722 "sessionId": "session-1",
1723 "viewCursor": format!("cursor-{id}-{revision}"),
1724 "item": {"itemId": format!("item-{id}"), "revision": revision}
1725 }),
1726 ));
1727 }
1728 for id in order.iter().rev().chain(["d", "a"].iter()) {
1729 session.inner.apply(note(
1730 "turn/started",
1731 serde_json::json!({
1732 "sessionId": "session-1",
1733 "viewCursor": format!("cursor-turn-{id}"),
1734 "turnId": format!("turn-{id}"),
1735 "commandId": format!("command-{id}")
1736 }),
1737 ));
1738 }
1739
1740 let fold = session.fold();
1741 assert_eq!(
1742 fold.item_ids(),
1743 order.map(|id| format!("item-{id}")),
1744 "items list in first-seen order; updates do not move them"
1745 );
1746 assert_eq!(
1747 fold.turn_ids(),
1748 order
1749 .map(|id| format!("turn-{id}"))
1750 .into_iter()
1751 .rev()
1752 .collect::<Vec<_>>(),
1753 "turns list in first-seen order; repeats do not move them"
1754 );
1755 client.close().await;
1756 });
1757 }
1758
1759 #[test]
1760 fn source_failure_settlement_records_first_cause_and_clears_routes() {
1761 let handle = TurnHandle::new("turn-1");
1762 let turn = handle.turn();
1763 let mut state = SessionState::default();
1764 state.turns.insert(
1765 "turn-1".to_owned(),
1766 TurnRoute {
1767 handle,
1768 item_ids: HashSet::from(["item-1".to_owned()]),
1769 },
1770 );
1771 state
1772 .item_turns
1773 .insert("item-1".to_owned(), "turn-1".to_owned());
1774
1775 state.settle_source_failure(TurnWaitError::ClientClosed);
1776 state.settle_source_failure(TurnWaitError::SourceClosed);
1777
1778 assert_eq!(
1779 state.event_source_failure,
1780 Some(TurnWaitError::ClientClosed)
1781 );
1782 assert!(state.turns.is_empty());
1783 assert!(state.item_turns.is_empty());
1784 let mut completed = turn.completed();
1785 assert!(matches!(
1786 poll_once(completed.as_mut()),
1787 Poll::Ready(Err(crate::errors::MuseError::ClientClosed))
1788 ));
1789 }
1790
1791 #[test]
1792 fn dropping_send_user_turn_retires_its_pending_command() {
1793 let runtime = tokio::runtime::Builder::new_current_thread()
1794 .enable_all()
1795 .build();
1796 assert!(runtime.is_ok(), "caller runtime builds");
1797 let Ok(runtime) = runtime else {
1798 return;
1799 };
1800 runtime.block_on(async {
1801 let (inbound, reads) = mpsc::unbounded_channel();
1802 let queued = inbound.send(format!(
1803 "{}\n",
1804 serde_json::json!({
1805 "jsonrpc": "2.0",
1806 "id": 1,
1807 "result": {
1808 "session": {
1809 "sessionId": "session-1",
1810 "path": "/tmp/session.jsonl",
1811 "status": "idle",
1812 "activeTurnId": null,
1813 "createdAt": "2026-09-29T00:00:00Z",
1814 "updatedAt": "2026-09-29T00:00:00Z",
1815 "workspaceRoot": null,
1816 "providerId": null,
1817 "modelId": null,
1818 "turnCount": 0,
1819 "forkedFrom": null
1820 },
1821 "viewCursor": "cursor-1"
1822 }
1823 })
1824 ));
1825 assert!(queued.is_ok(), "session response queued");
1826 let client = MuseClient::with_command_id_minter(
1827 ChannelTransport { inbound: reads },
1828 SessionDurability::Durable,
1829 || "command-1".to_owned(),
1830 );
1831 let session = client.start_session(StartSessionOptions::default()).await;
1832 assert!(session.is_ok(), "session opens");
1833 let Ok(session) = session else {
1834 return;
1835 };
1836 let mut turn = Box::pin(session.send_user_turn(SendUserTurnOptions::default()));
1837 assert!(poll_once(turn.as_mut()).is_pending());
1838 assert_eq!(lock(&session.inner.state).pending_commands.len(), 1);
1839
1840 drop(turn);
1841
1842 assert!(lock(&session.inner.state).pending_commands.is_empty());
1843 client.close().await;
1844 });
1845 }
1846
1847 #[test]
1848 fn turn_claimed_after_client_close_keeps_closed_error() {
1849 let runtime = tokio::runtime::Builder::new_current_thread()
1850 .enable_all()
1851 .build();
1852 assert!(runtime.is_ok(), "caller runtime builds");
1853 let Ok(runtime) = runtime else {
1854 return;
1855 };
1856 runtime.block_on(async {
1857 let (inbound, reads) = mpsc::unbounded_channel();
1858 let queued = inbound.send(format!(
1859 "{}\n",
1860 serde_json::json!({
1861 "jsonrpc": "2.0",
1862 "id": 1,
1863 "result": {
1864 "session": {
1865 "sessionId": "session-1",
1866 "path": "/tmp/session.jsonl",
1867 "status": "idle",
1868 "activeTurnId": null,
1869 "createdAt": "2026-09-29T00:00:00Z",
1870 "updatedAt": "2026-09-29T00:00:00Z",
1871 "workspaceRoot": null,
1872 "providerId": null,
1873 "modelId": null,
1874 "turnCount": 0,
1875 "forkedFrom": null
1876 },
1877 "viewCursor": "cursor-1"
1878 }
1879 })
1880 ));
1881 assert!(queued.is_ok(), "session response queued");
1882 let client = MuseClient::with_command_id_minter(
1883 ChannelTransport { inbound: reads },
1884 SessionDurability::Durable,
1885 || "command-1".to_owned(),
1886 );
1887 let session = client.start_session(StartSessionOptions::default()).await;
1888 assert!(session.is_ok(), "session opens");
1889 let Ok(session) = session else {
1890 return;
1891 };
1892
1893 client.close().await;
1894 session.inner.transport_ended(false);
1895 let turn = session.inner.claim_turn("turn-after-close");
1896
1897 assert!(matches!(
1898 turn.completed().await,
1899 Err(crate::errors::MuseError::ClientClosed)
1900 ));
1901 });
1902 }
1903
1904 #[test]
1905 fn settled_alias_capacity_evicts_instead_of_poisoning_the_session() {
1906 let mut state = SessionState::default();
1907 state.pending_commands.insert("command-1".to_owned());
1908 for sequence in 0..=MAX_SETTLED_TURN_ALIASES {
1909 let turn_id = format!("turn-{sequence}");
1910 let handle = TurnHandle::new(&turn_id);
1911 state.turns.insert(
1912 turn_id.clone(),
1913 TurnRoute {
1914 handle,
1915 item_ids: HashSet::new(),
1916 },
1917 );
1918 assert!(state.settle_and_retire_turn(&turn_id, |handle| {
1919 handle.fail(TurnWaitError::EventSourceFailed {
1920 message: "settled".to_owned(),
1921 });
1922 }));
1923 }
1924
1925 assert!(state.event_source_failure.is_none());
1926 assert_eq!(state.settled_turns.len(), MAX_SETTLED_TURN_ALIASES);
1927 assert!(
1928 state
1929 .settled_turns
1930 .contains_key(&format!("turn-{MAX_SETTLED_TURN_ALIASES}"))
1931 );
1932 }
1933
1934 #[test]
1935 fn a_resumed_session_holds_settled_aliases_until_released() {
1936 let mut state = SessionState::default();
1937 state.hold_settled_aliases = true;
1938 let handle = TurnHandle::new("turn-1");
1939 state.turns.insert(
1940 "turn-1".to_owned(),
1941 TurnRoute {
1942 handle,
1943 item_ids: HashSet::new(),
1944 },
1945 );
1946
1947 assert!(state.settle_and_retire_turn("turn-1", |handle| {
1949 handle.fail(TurnWaitError::EventSourceFailed {
1950 message: "settled".to_owned(),
1951 });
1952 }));
1953 assert!(state.settled_turns.contains_key("turn-1"));
1954 state.pending_commands.insert("command-other".to_owned());
1955 state.finish_pending_command("command-other");
1956 assert!(state.settled_turns.contains_key("turn-1"));
1957
1958 state.release_settled_alias_hold();
1959 assert!(state.settled_turns.is_empty());
1960 }
1961
1962 fn carried(session_id: &str, command_id: &str, turn_id: Option<&str>) -> PendingTurn {
1963 PendingTurn {
1964 session_id: session_id.to_owned(),
1965 command_id: command_id.to_owned(),
1966 options: SendUserTurnOptions::default(),
1967 turn_id: turn_id.map(str::to_owned),
1968 }
1969 }
1970
1971 async fn resumed_session(
1974 later: Vec<(&'static str, serde_json::Value)>,
1975 ) -> Option<(MuseClient, Session)> {
1976 let (outbound, inbound) = mpsc::unbounded_channel();
1977 let mut replies = std::collections::VecDeque::from([(
1978 "session/resume",
1979 serde_json::json!({
1980 "jsonrpc": "2.0",
1981 "id": 0,
1982 "result": {
1983 "session": {
1984 "sessionId": "session-1",
1985 "path": "/tmp/session.jsonl",
1986 "status": "idle",
1987 "activeTurnId": null,
1988 "createdAt": "2026-09-29T00:00:00Z",
1989 "updatedAt": "2026-09-29T00:00:00Z",
1990 "workspaceRoot": null,
1991 "providerId": null,
1992 "modelId": null,
1993 "turnCount": 1,
1994 "forkedFrom": null
1995 },
1996 "viewCursor": "cursor-1",
1997 "history": {"mode": "inline", "items": [], "snapshot": null},
1998 "pendingRequests": []
1999 }
2000 }),
2001 )]);
2002 replies.extend(later);
2003 let client = MuseClient::with_command_id_minter(
2004 RepliesOnWrite {
2005 inbound,
2006 outbound,
2007 replies,
2008 },
2009 SessionDurability::Durable,
2010 || "command-resume".to_owned(),
2011 );
2012 let session = client
2013 .resume_session(ResumeSessionOptions {
2014 session_id: "session-1".to_owned(),
2015 ..ResumeSessionOptions::default()
2016 })
2017 .await;
2018 assert!(session.is_ok(), "session resumes");
2019 Some((client, session.ok()?))
2020 }
2021
2022 fn apply_turn_completed(session: &Session, turn_id: &str) {
2024 session.inner.apply(Notification {
2025 jsonrpc: crate::msp::JsonRpcVersion::V2,
2026 method: "turn/completed".to_owned(),
2027 params: serde_json::json!({
2028 "sessionId": "session-1",
2029 "viewCursor": "cursor-2",
2030 "sourceRange": {
2031 "stream": {"kind": "run", "id": turn_id},
2032 "first": {"id": "event-1", "sequence": 1},
2033 "last": {"id": "event-1", "sequence": 1}
2034 },
2035 "turnId": turn_id,
2036 "terminal": "completed",
2037 "durationMs": 5
2038 })
2039 .as_object()
2040 .cloned(),
2041 emitted_at_ms: None,
2042 });
2043 }
2044
2045 #[test]
2046 fn a_refused_resolve_reconnect_keeps_the_hold_for_the_corrected_call() {
2047 let runtime = tokio::runtime::Builder::new_current_thread()
2048 .enable_all()
2049 .build();
2050 assert!(runtime.is_ok(), "caller runtime builds");
2051 let Ok(runtime) = runtime else {
2052 return;
2053 };
2054 runtime.block_on(async {
2055 let answer = serde_json::json!({
2057 "jsonrpc": "2.0",
2058 "id": 0,
2059 "result": {
2060 "commandId": "command-own",
2061 "status": "accepted",
2062 "turnId": "turn-1",
2063 "startedNewTurn": true,
2064 "disposition": "started"
2065 }
2066 });
2067 let Some((client, session)) = resumed_session(vec![("turn/start", answer)]).await
2068 else {
2069 return;
2070 };
2071 apply_turn_completed(&session, "turn-1");
2073 assert!(
2074 lock(&session.inner.state)
2075 .settled_turns
2076 .contains_key("turn-1")
2077 );
2078 let own = carried("session-1", "command-own", Some("turn-1"));
2079
2080 let refused = session
2081 .resolve_reconnect(vec![
2082 own.clone(),
2083 carried("session-2", "command-foreign", None),
2084 ])
2085 .await;
2086
2087 assert!(matches!(
2088 refused,
2089 Err(crate::errors::MuseError::Protocol(_))
2090 ));
2091 assert!(
2092 lock(&session.inner.state)
2093 .settled_turns
2094 .contains_key("turn-1"),
2095 "a refused call keeps the hold for the corrected call"
2096 );
2097 let corrected = session.resolve_reconnect(vec![own]).await;
2098 let live = corrected
2099 .ok()
2100 .and_then(|mut resolved| resolved.pop())
2101 .and_then(|resolution| resolution.result.ok());
2102 assert!(
2103 matches!(live, Some(Reconnected::Live(_))),
2104 "the corrected call follows turn-1"
2105 );
2106 if let Some(Reconnected::Live(turn)) = live {
2107 assert!(matches!(
2108 turn.completed().await,
2109 Ok(TurnOutcome::Completed { .. })
2110 ));
2111 }
2112 client.close().await;
2113 });
2114 }
2115
2116 #[test]
2117 fn an_empty_resolve_reconnect_releases_the_hold() {
2118 let runtime = tokio::runtime::Builder::new_current_thread()
2119 .enable_all()
2120 .build();
2121 assert!(runtime.is_ok(), "caller runtime builds");
2122 let Ok(runtime) = runtime else {
2123 return;
2124 };
2125 runtime.block_on(async {
2126 let Some((client, session)) = resumed_session(Vec::new()).await else {
2127 return;
2128 };
2129 apply_turn_completed(&session, "turn-1");
2130 assert!(
2131 lock(&session.inner.state)
2132 .settled_turns
2133 .contains_key("turn-1")
2134 );
2135
2136 let resolved = session.resolve_reconnect(Vec::new()).await;
2137
2138 assert!(matches!(resolved.as_deref(), Ok([])));
2139 assert!(!lock(&session.inner.state).hold_settled_aliases);
2140 assert!(lock(&session.inner.state).settled_turns.is_empty());
2141 client.close().await;
2142 });
2143 }
2144
2145 #[test]
2146 fn a_cancelled_resolve_reconnect_releases_the_hold() {
2147 let runtime = tokio::runtime::Builder::new_current_thread()
2148 .enable_all()
2149 .build();
2150 assert!(runtime.is_ok(), "caller runtime builds");
2151 let Ok(runtime) = runtime else {
2152 return;
2153 };
2154 runtime.block_on(async {
2155 let Some((client, session)) = resumed_session(Vec::new()).await else {
2157 return;
2158 };
2159 assert!(lock(&session.inner.state).hold_settled_aliases);
2160 let mut resolving = Box::pin(session.resolve_reconnect(vec![carried(
2161 "session-1",
2162 "command-own",
2163 None,
2164 )]));
2165 assert!(poll_once(resolving.as_mut()).is_pending());
2166 assert!(lock(&session.inner.state).hold_settled_aliases);
2167
2168 drop(resolving);
2169
2170 assert!(!lock(&session.inner.state).hold_settled_aliases);
2171 client.close().await;
2172 });
2173 }
2174
2175 #[test]
2176 fn an_answered_turn_refused_a_route_at_the_cap_stays_pending() {
2177 let runtime = tokio::runtime::Builder::new_current_thread()
2178 .enable_all()
2179 .build();
2180 assert!(runtime.is_ok(), "caller runtime builds");
2181 let Ok(runtime) = runtime else {
2182 return;
2183 };
2184 runtime.block_on(async {
2185 let answer = serde_json::json!({
2186 "jsonrpc": "2.0",
2187 "id": 0,
2188 "result": {
2189 "commandId": "command-resume",
2190 "status": "accepted",
2191 "turnId": "turn-over-cap",
2192 "startedNewTurn": true,
2193 "disposition": "started"
2194 }
2195 });
2196 let Some((client, session)) = resumed_session(vec![("turn/start", answer)]).await
2197 else {
2198 return;
2199 };
2200 {
2201 let mut state = lock(&session.inner.state);
2202 for sequence in 0..MAX_ACTIVE_TURNS {
2203 let turn_id = format!("live-{sequence}");
2204 state
2205 .turns
2206 .insert(turn_id.clone(), TurnRoute::new(&turn_id));
2207 }
2208 }
2209
2210 let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
2213 assert!(turn.is_ok(), "the answer is accepted");
2214 assert!(
2215 !lock(&session.inner.state)
2216 .turns
2217 .contains_key("turn-over-cap"),
2218 "the cap refused the turn a route"
2219 );
2220
2221 let pending = session.pending();
2222 assert_eq!(pending.len(), 1);
2223 assert_eq!(pending[0].command_id(), "command-resume");
2224 assert_eq!(pending[0].turn_id(), Some("turn-over-cap"));
2225 apply_turn_completed(&session, "turn-over-cap");
2227 assert_eq!(
2228 session.pending().len(),
2229 1,
2230 "a terminal under a full cap is not applied"
2231 );
2232 client.close().await;
2233 });
2234 }
2235
2236 #[test]
2237 fn a_cap_refused_turn_leaves_pending_once_its_terminal_arrives() {
2238 let runtime = tokio::runtime::Builder::new_current_thread()
2239 .enable_all()
2240 .build();
2241 assert!(runtime.is_ok(), "caller runtime builds");
2242 let Ok(runtime) = runtime else {
2243 return;
2244 };
2245 runtime.block_on(async {
2246 let answer = serde_json::json!({
2247 "jsonrpc": "2.0",
2248 "id": 0,
2249 "result": {
2250 "commandId": "command-resume",
2251 "status": "accepted",
2252 "turnId": "turn-over-cap",
2253 "startedNewTurn": true,
2254 "disposition": "started"
2255 }
2256 });
2257 let Some((client, session)) = resumed_session(vec![("turn/start", answer)]).await
2258 else {
2259 return;
2260 };
2261 {
2262 let mut state = lock(&session.inner.state);
2263 for sequence in 0..MAX_ACTIVE_TURNS {
2264 let turn_id = format!("live-{sequence}");
2265 state
2266 .turns
2267 .insert(turn_id.clone(), TurnRoute::new(&turn_id));
2268 }
2269 }
2270 let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
2271 assert!(turn.is_ok(), "the answer is accepted");
2272 assert!(
2273 !lock(&session.inner.state)
2274 .turns
2275 .contains_key("turn-over-cap"),
2276 "the cap refused the turn a route"
2277 );
2278 assert_eq!(session.pending().len(), 1);
2279
2280 apply_turn_completed(&session, "live-0");
2283 assert_eq!(
2284 session.pending().len(),
2285 1,
2286 "another turn's terminal answers nothing"
2287 );
2288 apply_turn_completed(&session, "turn-over-cap");
2289
2290 assert!(session.pending().is_empty());
2291 client.close().await;
2292 });
2293 }
2294
2295 #[derive(Debug)]
2297 enum SeenOnWake {
2298 Locked,
2303 Unlocked {
2304 still_routed: bool,
2305 new_route_fits: bool,
2306 },
2307 }
2308
2309 struct LookOnWake {
2312 inner: Arc<SessionInner>,
2313 turn_id: &'static str,
2314 seen: Mutex<Option<SeenOnWake>>,
2315 }
2316
2317 impl std::task::Wake for LookOnWake {
2318 fn wake(self: Arc<Self>) {
2319 self.wake_by_ref();
2320 }
2321
2322 fn wake_by_ref(self: &Arc<Self>) {
2323 let seen = match self.inner.state.try_lock() {
2324 Ok(state) => SeenOnWake::Unlocked {
2325 still_routed: state.turns.contains_key(self.turn_id),
2326 new_route_fits: state.accepts_turn_notification("turn-after"),
2327 },
2328 Err(std::sync::TryLockError::WouldBlock) => SeenOnWake::Locked,
2329 Err(std::sync::TryLockError::Poisoned(state)) => {
2330 let state = state.into_inner();
2331 SeenOnWake::Unlocked {
2332 still_routed: state.turns.contains_key(self.turn_id),
2333 new_route_fits: state.accepts_turn_notification("turn-after"),
2334 }
2335 }
2336 };
2337 *lock(&self.seen) = Some(seen);
2338 }
2339 }
2340
2341 fn settled_turn_is_retired_before_its_waiter_wakes(
2345 turn_id: &'static str,
2346 settle: fn(&Session, &str),
2347 ) {
2348 let runtime = tokio::runtime::Builder::new_current_thread()
2349 .enable_all()
2350 .build();
2351 assert!(runtime.is_ok(), "caller runtime builds");
2352 let Ok(runtime) = runtime else {
2353 return;
2354 };
2355 runtime.block_on(async {
2356 let answer = serde_json::json!({
2357 "jsonrpc": "2.0",
2358 "id": 0,
2359 "result": {
2360 "commandId": "command-resume",
2361 "status": "accepted",
2362 "turnId": "turn-after",
2363 "startedNewTurn": true,
2364 "disposition": "started"
2365 }
2366 });
2367 let Some((client, session)) = resumed_session(vec![("turn/start", answer)]).await
2368 else {
2369 return;
2370 };
2371 let turn = session.inner.claim_turn(turn_id);
2372 {
2373 let mut state = lock(&session.inner.state);
2374 for sequence in 1..MAX_ACTIVE_TURNS {
2375 let live = format!("live-{sequence}");
2376 state.turns.insert(live.clone(), TurnRoute::new(&live));
2377 }
2378 assert!(
2379 !state.accepts_turn_notification("turn-after"),
2380 "the active-turn cap is full"
2381 );
2382 }
2383 let look = Arc::new(LookOnWake {
2384 inner: Arc::clone(&session.inner),
2385 turn_id,
2386 seen: Mutex::new(None),
2387 });
2388 let waker = Waker::from(Arc::clone(&look));
2389 let mut context = Context::from_waker(&waker);
2390 let mut completed = turn.completed();
2391 assert!(completed.as_mut().poll(&mut context).is_pending());
2392
2393 settle(&session, turn_id);
2394
2395 let seen = lock(&look.seen).take();
2396 assert!(
2397 matches!(
2398 seen,
2399 Some(
2400 SeenOnWake::Locked
2401 | SeenOnWake::Unlocked {
2402 still_routed: false,
2403 new_route_fits: true
2404 }
2405 )
2406 ),
2407 "the woken waiter saw the settled turn still holding its route: {seen:?}"
2408 );
2409 assert!(matches!(
2410 completed.as_mut().poll(&mut context),
2411 Poll::Ready(Ok(_))
2412 ));
2413 let after = session.send_user_turn(SendUserTurnOptions::default()).await;
2414 assert!(after.is_ok(), "the next turn/start is accepted");
2415 assert!(
2416 lock(&session.inner.state).turns.contains_key("turn-after"),
2417 "a turn started right after completed() resolves gets a route"
2418 );
2419 client.close().await;
2420 });
2421 }
2422
2423 #[test]
2424 fn a_completed_turn_is_retired_before_its_waiter_wakes() {
2425 settled_turn_is_retired_before_its_waiter_wakes("turn-1", apply_turn_completed);
2426 }
2427
2428 #[test]
2429 fn an_unqueued_turn_is_retired_before_its_waiter_wakes() {
2430 settled_turn_is_retired_before_its_waiter_wakes("turn-queued", |session, turn_id| {
2431 session.inner.apply(Notification {
2432 jsonrpc: crate::msp::JsonRpcVersion::V2,
2433 method: "turn/unqueued".to_owned(),
2434 params: serde_json::json!({
2435 "sessionId": "session-1",
2436 "viewCursor": "cursor-2",
2437 "sourceRange": {
2438 "stream": {"kind": "session", "id": "session-1"},
2439 "first": {"id": "event-1", "sequence": 1},
2440 "last": {"id": "event-1", "sequence": 1}
2441 },
2442 "turnId": turn_id,
2443 "commandId": "command-1"
2444 })
2445 .as_object()
2446 .cloned(),
2447 emitted_at_ms: None,
2448 });
2449 });
2450 }
2451
2452 #[test]
2453 fn settle_and_retire_turn_settles_the_routed_handle_then_retires_it() {
2454 let mut state = SessionState::default();
2455 let handle = TurnHandle::new("turn-1");
2456 state.turns.insert(
2457 "turn-1".to_owned(),
2458 TurnRoute {
2459 handle: handle.clone(),
2460 item_ids: HashSet::new(),
2461 },
2462 );
2463
2464 assert!(state.settle_and_retire_turn("turn-1", |turn| {
2465 turn.fail(TurnWaitError::EventSourceFailed {
2466 message: "settled".to_owned(),
2467 });
2468 }));
2469 assert!(handle.is_settled());
2470 assert!(state.turns.is_empty());
2471
2472 let mut settled_unrouted = false;
2473 assert!(!state.settle_and_retire_turn("turn-unrouted", |_| settled_unrouted = true));
2474 assert!(
2475 !settled_unrouted,
2476 "an unrouted turn has no handle to settle"
2477 );
2478 }
2479
2480 #[test]
2481 fn retired_turns_reject_late_notification_recreation() {
2482 let mut state = SessionState::default();
2483 for sequence in 0..=(MAX_RETIRED_TURNS + MAX_ACTIVE_TURNS) {
2484 let turn_id = format!("turn-{sequence}");
2485 let handle = TurnHandle::new(&turn_id);
2486 state.turns.insert(
2487 turn_id.clone(),
2488 TurnRoute {
2489 handle,
2490 item_ids: HashSet::new(),
2491 },
2492 );
2493 assert!(state.settle_and_retire_turn(&turn_id, |handle| {
2494 handle.fail(TurnWaitError::EventSourceFailed {
2495 message: "settled".to_owned(),
2496 });
2497 }));
2498 }
2499
2500 assert!(!state.accepts_turn_notification(&format!("turn-{MAX_RETIRED_TURNS}")));
2501 for sequence in 0..=(MAX_RETIRED_TURNS + MAX_ACTIVE_TURNS) {
2502 let turn_id = format!("turn-{sequence}");
2503 if state.accepts_turn_notification(&turn_id) {
2504 state
2505 .turns
2506 .insert(turn_id.clone(), TurnRoute::new(&turn_id));
2507 }
2508 }
2509 assert_eq!(state.turns.len(), MAX_ACTIVE_TURNS);
2510 assert!(!state.accepts_turn_notification("another-late-turn"));
2511 }
2512
2513 #[test]
2514 fn retired_discard_history_is_bounded_per_session() {
2515 let mut state = SessionState::default();
2516 for sequence in 0..=MAX_RETIRED_TURNS {
2517 let turn_id = format!("turn-{sequence}");
2518 let command_id = format!("command-{sequence}");
2519 let handle = TurnHandle::new(&turn_id);
2520 let turn = handle.turn().with_discard(command_id);
2521 drop(turn);
2522 state.turns.insert(
2523 turn_id.clone(),
2524 TurnRoute {
2525 handle,
2526 item_ids: HashSet::new(),
2527 },
2528 );
2529 assert!(state.settle_and_retire_turn(&turn_id, |handle| {
2530 handle.fail(TurnWaitError::EventSourceFailed {
2531 message: "settled".to_owned(),
2532 });
2533 }));
2534 }
2535
2536 assert_eq!(state.retired_turns.len(), MAX_RETIRED_TURNS);
2537 assert!(!state.is_command_discarded("command-0"));
2538 assert!(state.is_command_discarded(&format!("command-{MAX_RETIRED_TURNS}")));
2539 }
2540
2541 #[test]
2542 fn inline_history_resume_keeps_new_turns_runnable_past_the_active_turn_cap() {
2543 let runtime = tokio::runtime::Builder::new_current_thread()
2547 .enable_all()
2548 .build();
2549 assert!(runtime.is_ok(), "caller runtime builds");
2550 let Ok(runtime) = runtime else {
2551 return;
2552 };
2553 runtime.block_on(async {
2554 let (inbound, reads) = mpsc::unbounded_channel();
2555 let history: Vec<serde_json::Value> = (0..=MAX_ACTIVE_TURNS)
2556 .map(|sequence| {
2557 serde_json::json!({
2558 "itemId": format!("item-{sequence}"),
2559 "kind": "agentMessage",
2560 "turnId": format!("turn-{sequence}"),
2561 "revision": 1,
2562 "status": "completed",
2563 "text": "earlier reply"
2564 })
2565 })
2566 .collect();
2567 let queued = inbound.send(format!(
2568 "{}\n",
2569 serde_json::json!({
2570 "jsonrpc": "2.0",
2571 "id": 1,
2572 "result": {
2573 "session": {
2574 "sessionId": "session-1",
2575 "path": "/tmp/session.jsonl",
2576 "status": "idle",
2577 "activeTurnId": null,
2578 "createdAt": "2026-09-29T00:00:00Z",
2579 "updatedAt": "2026-09-29T00:00:00Z",
2580 "workspaceRoot": null,
2581 "providerId": null,
2582 "modelId": null,
2583 "turnCount": MAX_ACTIVE_TURNS + 1,
2584 "forkedFrom": null
2585 },
2586 "viewCursor": "cursor-1",
2587 "history": {"mode": "inline", "items": history, "snapshot": null},
2588 "pendingRequests": []
2589 }
2590 })
2591 ));
2592 assert!(queued.is_ok(), "resume response queued");
2593 let client = MuseClient::with_command_id_minter(
2594 ChannelTransport { inbound: reads },
2595 SessionDurability::Durable,
2596 || "command-1".to_owned(),
2597 );
2598 let session = client
2599 .resume_session(ResumeSessionOptions {
2600 session_id: "session-1".to_owned(),
2601 ..ResumeSessionOptions::default()
2602 })
2603 .await;
2604 assert!(session.is_ok(), "session resumes");
2605 let Ok(session) = session else {
2606 return;
2607 };
2608
2609 let queued = inbound.send(format!(
2610 "{}\n",
2611 serde_json::json!({
2612 "jsonrpc": "2.0",
2613 "id": 2,
2614 "result": {
2615 "commandId": "command-1",
2616 "status": "accepted",
2617 "turnId": "turn-new",
2618 "startedNewTurn": true,
2619 "disposition": "started"
2620 }
2621 })
2622 ));
2623 assert!(queued.is_ok(), "turn/start response queued");
2624 let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
2625 assert!(turn.is_ok(), "turn/start is accepted");
2626 let Ok(turn) = turn else {
2627 return;
2628 };
2629 let mut completed = turn.completed();
2630 let first_poll = poll_once(completed.as_mut());
2631 assert!(
2632 first_poll.is_pending(),
2633 "a new turn after an inline-history resume must wait for its own terminal, got {first_poll:?}"
2634 );
2635 assert!(
2636 lock(&session.inner.state).turns.len() <= 1,
2637 "finished history turns must hold no live route; routes: {}",
2638 lock(&session.inner.state).turns.len()
2639 );
2640
2641 let queued = inbound.send(format!(
2642 "{}\n",
2643 serde_json::json!({
2644 "jsonrpc": "2.0",
2645 "method": "turn/completed",
2646 "params": {
2647 "sessionId": "session-1",
2648 "viewCursor": "cursor-2",
2649 "sourceRange": {
2650 "stream": {"kind": "run", "id": "turn-new"},
2651 "first": {"id": "event-1", "sequence": 1},
2652 "last": {"id": "event-1", "sequence": 1}
2653 },
2654 "turnId": "turn-new",
2655 "terminal": "completed",
2656 "reason": null,
2657 "durationMs": 5,
2658 "timeToFirstTokenMs": 1,
2659 "usage": null
2660 }
2661 })
2662 ));
2663 assert!(queued.is_ok(), "turn/completed queued");
2664 let outcome = completed.await;
2665 assert!(
2666 matches!(outcome, Ok(TurnOutcome::Completed { .. })),
2667 "the new turn settles on its own terminal, got {outcome:?}"
2668 );
2669 client.close().await;
2670 });
2671 }
2672
2673 #[test]
2674 fn inline_history_resume_routes_the_running_turn_with_no_held_items() {
2675 let runtime = tokio::runtime::Builder::new_current_thread()
2678 .enable_all()
2679 .build();
2680 assert!(runtime.is_ok(), "caller runtime builds");
2681 let Ok(runtime) = runtime else {
2682 return;
2683 };
2684 runtime.block_on(async {
2685 let (inbound, reads) = mpsc::unbounded_channel();
2686 let queued = inbound.send(format!(
2687 "{}\n",
2688 serde_json::json!({
2689 "jsonrpc": "2.0",
2690 "id": 1,
2691 "result": {
2692 "session": {
2693 "sessionId": "session-1",
2694 "path": "/tmp/session.jsonl",
2695 "status": "running",
2696 "activeTurnId": "turn-live",
2697 "createdAt": "2026-09-29T00:00:00Z",
2698 "updatedAt": "2026-09-29T00:00:00Z",
2699 "workspaceRoot": null,
2700 "providerId": null,
2701 "modelId": null,
2702 "turnCount": 2,
2703 "forkedFrom": null
2704 },
2705 "viewCursor": "cursor-1",
2706 "history": {
2707 "mode": "inline",
2708 "items": [
2709 {
2710 "itemId": "item-old",
2711 "kind": "agentMessage",
2712 "turnId": "turn-old",
2713 "revision": 1,
2714 "status": "completed",
2715 "text": "earlier reply"
2716 }
2717 ],
2718 "snapshot": null
2719 },
2720 "pendingRequests": []
2721 }
2722 })
2723 ));
2724 assert!(queued.is_ok(), "resume response queued");
2725 let client = MuseClient::with_command_id_minter(
2726 ChannelTransport { inbound: reads },
2727 SessionDurability::Durable,
2728 || "command-1".to_owned(),
2729 );
2730 let session = client
2731 .resume_session(ResumeSessionOptions {
2732 session_id: "session-1".to_owned(),
2733 ..ResumeSessionOptions::default()
2734 })
2735 .await;
2736 assert!(session.is_ok(), "session resumes");
2737 let Ok(session) = session else {
2738 return;
2739 };
2740 {
2741 let state = lock(&session.inner.state);
2742 let routed: Vec<&str> = state.turns.keys().map(String::as_str).collect();
2743 assert_eq!(routed, ["turn-live"], "resume routes only the running turn");
2744 }
2745
2746 session.inner.apply(Notification {
2747 jsonrpc: crate::msp::JsonRpcVersion::V2,
2748 method: "turn/completed".to_owned(),
2749 params: serde_json::json!({
2750 "sessionId": "session-1",
2751 "viewCursor": "cursor-2",
2752 "sourceRange": {
2753 "stream": {"kind": "run", "id": "turn-live"},
2754 "first": {"id": "event-1", "sequence": 1},
2755 "last": {"id": "event-1", "sequence": 1}
2756 },
2757 "turnId": "turn-live",
2758 "terminal": "completed",
2759 "reason": null,
2760 "durationMs": 5,
2761 "timeToFirstTokenMs": 1,
2762 "usage": null
2763 })
2764 .as_object()
2765 .cloned(),
2766 emitted_at_ms: None,
2767 });
2768 assert!(
2769 lock(&session.inner.state).turns.is_empty(),
2770 "the running turn's terminal retires its route"
2771 );
2772 client.close().await;
2773 });
2774 }
2775
2776 #[derive(Clone, Copy)]
2780 enum HistoryForm {
2781 Inline,
2782 Snapshot,
2783 AnchoredSnapshot,
2784 }
2785
2786 fn served_history(form: HistoryForm, items: serde_json::Value) -> serde_json::Value {
2787 match form {
2788 HistoryForm::Inline => {
2789 serde_json::json!({"mode": "inline", "items": items, "snapshot": null})
2790 }
2791 HistoryForm::Snapshot | HistoryForm::AnchoredSnapshot => serde_json::json!({
2792 "mode": match form {
2793 HistoryForm::AnchoredSnapshot => "anchoredSnapshot",
2794 _ => "snapshot",
2795 },
2796 "items": null,
2797 "snapshot": {
2798 "schemaVersion": 1,
2799 "viewCursor": "cursor-1",
2800 "anchor": match form {
2801 HistoryForm::AnchoredSnapshot => serde_json::json!({
2802 "boundaryCursor": "cursor-0",
2803 "summarizedThrough": "anchor-0"
2804 }),
2805 _ => serde_json::Value::Null,
2806 },
2807 "state": {
2808 "items": items,
2809 "activeTurn": null,
2810 "queuedTurns": [],
2811 "pendingApprovals": [],
2812 "pendingUserInputs": [],
2813 "approvalMode": {"mode": "promptUnmatched", "source": "replay", "lastCommandId": null},
2814 "effectiveModel": null,
2815 "goal": null,
2816 "todoList": null,
2817 "branch": null,
2818 "tokenUsage": {"promptTokens": 0, "outputTokens": 0, "totalTokens": 0},
2819 "turnCount": 1
2820 }
2821 }
2822 }),
2823 }
2824 }
2825
2826 #[test]
2827 fn inline_history_resume_keeps_the_running_turn_routed_and_settles_it() {
2828 resume_keeps_the_running_turn_routed_and_settles_it(HistoryForm::Inline);
2829 }
2830
2831 #[test]
2832 fn snapshot_history_resume_keeps_the_running_turn_routed_and_settles_it() {
2833 resume_keeps_the_running_turn_routed_and_settles_it(HistoryForm::Snapshot);
2834 }
2835
2836 #[test]
2837 fn anchored_snapshot_history_resume_keeps_the_running_turn_routed_and_settles_it() {
2838 resume_keeps_the_running_turn_routed_and_settles_it(HistoryForm::AnchoredSnapshot);
2839 }
2840
2841 fn resume_keeps_the_running_turn_routed_and_settles_it(form: HistoryForm) {
2842 let runtime = tokio::runtime::Builder::new_current_thread()
2846 .enable_all()
2847 .build();
2848 assert!(runtime.is_ok(), "caller runtime builds");
2849 let Ok(runtime) = runtime else {
2850 return;
2851 };
2852 runtime.block_on(async {
2853 let (inbound, reads) = mpsc::unbounded_channel();
2854 let queued = inbound.send(format!(
2855 "{}\n",
2856 serde_json::json!({
2857 "jsonrpc": "2.0",
2858 "id": 1,
2859 "result": {
2860 "session": {
2861 "sessionId": "session-1",
2862 "path": "/tmp/session.jsonl",
2863 "status": "running",
2864 "activeTurnId": "turn-live",
2865 "createdAt": "2026-09-29T00:00:00Z",
2866 "updatedAt": "2026-09-29T00:00:00Z",
2867 "workspaceRoot": null,
2868 "providerId": null,
2869 "modelId": null,
2870 "turnCount": 2,
2871 "forkedFrom": null
2872 },
2873 "viewCursor": "cursor-1",
2874 "history": served_history(form, serde_json::json!([
2875 {
2876 "itemId": "item-old",
2877 "kind": "agentMessage",
2878 "turnId": "turn-old",
2879 "revision": 1,
2880 "status": "completed",
2881 "text": "finished reply"
2882 },
2883 {
2884 "itemId": "item-live",
2885 "kind": "agentMessage",
2886 "turnId": "turn-live",
2887 "revision": 1,
2888 "status": "inProgress",
2889 "text": "partial reply"
2890 }
2891 ])),
2892 "pendingRequests": []
2893 }
2894 })
2895 ));
2896 assert!(queued.is_ok(), "resume response queued");
2897 let client = MuseClient::with_command_id_minter(
2898 ChannelTransport { inbound: reads },
2899 SessionDurability::Durable,
2900 || "command-1".to_owned(),
2901 );
2902 let session = client
2903 .resume_session(ResumeSessionOptions {
2904 session_id: "session-1".to_owned(),
2905 ..ResumeSessionOptions::default()
2906 })
2907 .await;
2908 assert!(session.is_ok(), "session resumes");
2909 let Ok(session) = session else {
2910 return;
2911 };
2912 {
2913 let state = lock(&session.inner.state);
2914 let mut routed: Vec<&String> = state.turns.keys().collect();
2915 routed.sort();
2916 assert_eq!(
2917 routed,
2918 vec!["turn-live"],
2919 "only the running turn holds a route after resume"
2920 );
2921 }
2922
2923 let queued = inbound.send(format!(
2924 "{}\n",
2925 serde_json::json!({
2926 "jsonrpc": "2.0",
2927 "id": 2,
2928 "result": {
2929 "commandId": "command-1",
2930 "status": "accepted",
2931 "turnId": "turn-live",
2932 "startedNewTurn": false,
2933 "disposition": "steered"
2934 }
2935 })
2936 ));
2937 assert!(queued.is_ok(), "turn/start response queued");
2938 let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
2939 assert!(turn.is_ok(), "steered turn/start is accepted");
2940 let Ok(turn) = turn else {
2941 return;
2942 };
2943 let mut items = turn.items();
2944 let mut deltas = turn.deltas();
2945 let held = poll_once(std::pin::pin!(items.recv()));
2946 assert!(
2947 matches!(&held, Poll::Ready(Ok(Some(item))) if item.item_id == "item-live"),
2948 "the running turn's held item replays first, got {held:?}"
2949 );
2950
2951 let queued = inbound.send(format!(
2952 "{}\n{}\n",
2953 serde_json::json!({
2954 "jsonrpc": "2.0",
2955 "method": "item/delta",
2956 "params": {
2957 "sessionId": "session-1",
2958 "viewCursor": "cursor-2",
2959 "itemId": "item-live",
2960 "field": "text",
2961 "delta": " continued"
2962 }
2963 }),
2964 serde_json::json!({
2965 "jsonrpc": "2.0",
2966 "method": "turn/completed",
2967 "params": {
2968 "sessionId": "session-1",
2969 "viewCursor": "cursor-3",
2970 "sourceRange": {
2971 "stream": {"kind": "run", "id": "turn-live"},
2972 "first": {"id": "event-1", "sequence": 1},
2973 "last": {"id": "event-1", "sequence": 1}
2974 },
2975 "turnId": "turn-live",
2976 "terminal": "completed",
2977 "reason": null,
2978 "durationMs": 5,
2979 "timeToFirstTokenMs": 1,
2980 "usage": null
2981 }
2982 })
2983 ));
2984 assert!(queued.is_ok(), "item/delta and turn/completed queued");
2985 let delta = deltas.recv().await;
2986 assert!(
2987 matches!(&delta, Ok(Some(delta)) if delta.item_id == "item-live"),
2988 "a live delta for the replayed history item still routes, got {delta:?}"
2989 );
2990 let outcome = turn.completed().await;
2991 assert!(
2992 matches!(outcome, Ok(TurnOutcome::Completed { .. })),
2993 "the running turn settles on its own terminal, got {outcome:?}"
2994 );
2995 let end = items.recv().await;
2999 assert!(
3000 matches!(end, Ok(None)),
3001 "the held item replays once, got {end:?}"
3002 );
3003 client.close().await;
3004 });
3005 }
3006
3007 #[test]
3008 fn inline_history_resume_replays_history_when_a_claim_opens_the_turn_first() {
3009 let runtime = tokio::runtime::Builder::new_current_thread()
3013 .enable_all()
3014 .build();
3015 assert!(runtime.is_ok(), "caller runtime builds");
3016 let Ok(runtime) = runtime else {
3017 return;
3018 };
3019 runtime.block_on(async {
3020 let (inbound, reads) = mpsc::unbounded_channel();
3021 let queued = inbound.send(format!(
3022 "{}\n",
3023 serde_json::json!({
3024 "jsonrpc": "2.0",
3025 "id": 1,
3026 "result": {
3027 "session": {
3028 "sessionId": "session-1",
3029 "path": "/tmp/session.jsonl",
3030 "status": "idle",
3031 "activeTurnId": null,
3032 "createdAt": "2026-09-29T00:00:00Z",
3033 "updatedAt": "2026-09-29T00:00:00Z",
3034 "workspaceRoot": null,
3035 "providerId": null,
3036 "modelId": null,
3037 "turnCount": 1,
3038 "forkedFrom": null
3039 },
3040 "viewCursor": "cursor-1",
3041 "history": {
3042 "mode": "inline",
3043 "items": [
3044 {
3045 "itemId": "item-first",
3046 "kind": "userMessage",
3047 "turnId": "turn-killed",
3048 "commandId": "command-1",
3049 "revision": 1,
3050 "status": "completed",
3051 "text": "retry me"
3052 },
3053 {
3054 "itemId": "item-second",
3055 "kind": "agentMessage",
3056 "turnId": "turn-killed",
3057 "revision": 1,
3058 "status": "completed",
3059 "text": "partial reply"
3060 }
3061 ],
3062 "snapshot": null
3063 },
3064 "pendingRequests": []
3065 }
3066 })
3067 ));
3068 assert!(queued.is_ok(), "resume response queued");
3069 let client = MuseClient::with_command_id_minter(
3070 ChannelTransport { inbound: reads },
3071 SessionDurability::Durable,
3072 || "command-1".to_owned(),
3073 );
3074 let session = client
3075 .resume_session(ResumeSessionOptions {
3076 session_id: "session-1".to_owned(),
3077 ..ResumeSessionOptions::default()
3078 })
3079 .await;
3080 assert!(session.is_ok(), "session resumes");
3081 let Ok(session) = session else {
3082 return;
3083 };
3084 assert!(
3085 lock(&session.inner.state).turns.is_empty(),
3086 "resume opens no route for the finished turn"
3087 );
3088
3089 let queued = inbound.send(format!(
3092 "{}\n",
3093 serde_json::json!({
3094 "jsonrpc": "2.0",
3095 "id": 2,
3096 "result": {
3097 "commandId": "command-1",
3098 "status": "accepted",
3099 "turnId": "turn-killed",
3100 "startedNewTurn": true,
3101 "disposition": "started"
3102 }
3103 })
3104 ));
3105 assert!(queued.is_ok(), "retry answer queued");
3106 let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
3107 assert!(turn.is_ok(), "same-command retry is accepted");
3108 let Ok(turn) = turn else {
3109 return;
3110 };
3111 let mut items = turn.items();
3112 let first = poll_once(std::pin::pin!(items.recv()));
3115 assert!(
3116 matches!(first, Poll::Ready(Ok(Some(_)))),
3117 "the claim replays the turn's history at once, got {first:?}"
3118 );
3119 let mut replayed = Vec::new();
3120 if let Poll::Ready(Ok(Some(item))) = first {
3121 replayed.push(item.item_id);
3122 }
3123
3124 session.inner.apply(Notification {
3128 jsonrpc: crate::msp::JsonRpcVersion::V2,
3129 method: "turn/completed".to_owned(),
3130 params: serde_json::json!({
3131 "sessionId": "session-1",
3132 "viewCursor": "cursor-2",
3133 "sourceRange": {
3134 "stream": {"kind": "session", "id": "session-1"},
3135 "first": {"id": "event-1", "sequence": 1},
3136 "last": {"id": "event-1", "sequence": 1}
3137 },
3138 "turnId": "turn-killed",
3139 "terminal": "cancelled",
3140 "reason": "resume_reconcile:orphaned_by_process_loss"
3141 })
3142 .as_object()
3143 .cloned(),
3144 emitted_at_ms: None,
3145 });
3146 let outcome = turn.completed().await;
3147 assert!(
3148 matches!(outcome, Ok(TurnOutcome::Completed { .. })),
3149 "the claimed turn settles on its terminal, got {outcome:?}"
3150 );
3151 assert!(
3152 lock(&session.inner.state).item_turns.is_empty(),
3153 "the retired turn drops its replayed items' delta routes"
3154 );
3155 loop {
3156 match items.recv().await {
3157 Ok(Some(item)) => replayed.push(item.item_id),
3158 end => {
3159 assert!(matches!(end, Ok(None)), "item stream failed: {end:?}");
3160 break;
3161 }
3162 }
3163 }
3164 assert_eq!(
3165 replayed,
3166 ["item-first", "item-second"],
3167 "the claimed turn replays its history once, in history order"
3168 );
3169 client.close().await;
3170 });
3171 }
3172
3173 #[test]
3174 fn inline_history_resume_replays_a_reconciled_turn_into_its_same_command_retry() {
3175 resume_replays_a_reconciled_turn_into_its_same_command_retry(HistoryForm::Inline);
3176 }
3177
3178 #[test]
3179 fn snapshot_history_resume_replays_a_reconciled_turn_into_its_same_command_retry() {
3180 resume_replays_a_reconciled_turn_into_its_same_command_retry(HistoryForm::Snapshot);
3181 }
3182
3183 #[test]
3184 fn a_newer_snapshot_schema_version_replays_no_turn_history() {
3185 let runtime = tokio::runtime::Builder::new_current_thread()
3190 .enable_all()
3191 .build();
3192 assert!(runtime.is_ok(), "caller runtime builds");
3193 let Ok(runtime) = runtime else {
3194 return;
3195 };
3196 runtime.block_on(async {
3197 let mut history = served_history(
3198 HistoryForm::Snapshot,
3199 serde_json::json!([{
3200 "itemId": "item-live",
3201 "kind": "agentMessage",
3202 "turnId": "turn-live",
3203 "revision": 1,
3204 "status": "inProgress",
3205 "text": "partial reply"
3206 }]),
3207 );
3208 history["snapshot"]["schemaVersion"] = serde_json::json!(2);
3209 history["snapshot"]["state"] = serde_json::json!({"entries": []});
3210 let (inbound, reads) = mpsc::unbounded_channel();
3211 let queued = inbound.send(format!(
3212 "{}\n",
3213 serde_json::json!({
3214 "jsonrpc": "2.0",
3215 "id": 1,
3216 "result": {
3217 "session": {
3218 "sessionId": "session-1",
3219 "path": "/tmp/session.jsonl",
3220 "status": "running",
3221 "activeTurnId": "turn-live",
3222 "createdAt": "2026-09-29T00:00:00Z",
3223 "updatedAt": "2026-09-29T00:00:00Z",
3224 "workspaceRoot": null,
3225 "providerId": null,
3226 "modelId": null,
3227 "turnCount": 1,
3228 "forkedFrom": null
3229 },
3230 "viewCursor": "cursor-1",
3231 "history": history,
3232 "pendingRequests": []
3233 }
3234 })
3235 ));
3236 assert!(queued.is_ok(), "resume response queued");
3237 let client = MuseClient::with_command_id_minter(
3238 ChannelTransport { inbound: reads },
3239 SessionDurability::Durable,
3240 || "command-1".to_owned(),
3241 );
3242 let session = client
3243 .resume_session(ResumeSessionOptions {
3244 session_id: "session-1".to_owned(),
3245 ..ResumeSessionOptions::default()
3246 })
3247 .await;
3248 assert!(session.is_ok(), "session resumes");
3249 let Ok(session) = session else {
3250 return;
3251 };
3252 {
3253 let state = lock(&session.inner.state);
3254 assert!(
3255 state.history_turn_items.is_empty(),
3256 "a newer snapshot indexes no turn items"
3257 );
3258 assert!(
3259 state.turns.is_empty(),
3260 "a newer snapshot opens no route at resume"
3261 );
3262 }
3263 assert!(
3264 matches!(&session.inner.opening, SessionOpening::Resume(_)),
3265 "a resume opens with its resume result"
3266 );
3267 let SessionOpening::Resume(result) = &session.inner.opening else {
3268 return;
3269 };
3270 assert!(
3271 result.history.snapshot.is_none(),
3272 "the opening carries no snapshot the SDK cannot read"
3273 );
3274 assert_eq!(result.history.mode, crate::msp::HistoryMode::Snapshot);
3275 assert_eq!(
3276 session.dropped_snapshot_schema_version(),
3277 Some(2),
3278 "the session names the snapshot version it dropped"
3279 );
3280 client.close().await;
3281 });
3282 }
3283
3284 #[test]
3285 fn anchored_snapshot_history_resume_replays_a_reconciled_turn_into_its_same_command_retry() {
3286 resume_replays_a_reconciled_turn_into_its_same_command_retry(HistoryForm::AnchoredSnapshot);
3287 }
3288
3289 fn resume_replays_a_reconciled_turn_into_its_same_command_retry(form: HistoryForm) {
3290 let runtime = tokio::runtime::Builder::new_current_thread()
3296 .enable_all()
3297 .build();
3298 assert!(runtime.is_ok(), "caller runtime builds");
3299 let Ok(runtime) = runtime else {
3300 return;
3301 };
3302 runtime.block_on(async {
3303 let (inbound, reads) = mpsc::unbounded_channel();
3304 let queued = inbound.send(format!(
3305 "{}\n",
3306 serde_json::json!({
3307 "jsonrpc": "2.0",
3308 "id": 1,
3309 "result": {
3310 "session": {
3311 "sessionId": "session-1",
3312 "path": "/tmp/session.jsonl",
3313 "status": "idle",
3314 "activeTurnId": null,
3315 "createdAt": "2026-09-29T00:00:00Z",
3316 "updatedAt": "2026-09-29T00:00:00Z",
3317 "workspaceRoot": null,
3318 "providerId": null,
3319 "modelId": null,
3320 "turnCount": 1,
3321 "forkedFrom": null
3322 },
3323 "viewCursor": "cursor-1",
3324 "history": served_history(form, serde_json::json!([
3325 {
3326 "itemId": "item-killed",
3327 "kind": "userMessage",
3328 "turnId": "turn-killed",
3329 "commandId": "command-1",
3330 "revision": 1,
3331 "status": "completed",
3332 "text": "retry me"
3333 }
3334 ])),
3335 "lastTurn": {
3336 "turnId": "turn-killed",
3337 "terminal": "cancelled",
3338 "reason": "resume_reconcile:orphaned_by_process_loss"
3339 },
3340 "pendingRequests": []
3341 }
3342 })
3343 ));
3344 assert!(queued.is_ok(), "resume response queued");
3345 let client = MuseClient::with_command_id_minter(
3346 ChannelTransport { inbound: reads },
3347 SessionDurability::Durable,
3348 || "command-1".to_owned(),
3349 );
3350 let session = client
3351 .resume_session(ResumeSessionOptions {
3352 session_id: "session-1".to_owned(),
3353 ..ResumeSessionOptions::default()
3354 })
3355 .await;
3356 assert!(session.is_ok(), "session resumes");
3357 let Ok(session) = session else {
3358 return;
3359 };
3360 assert!(
3361 lock(&session.inner.state).turns.is_empty(),
3362 "resume opens no route for the finished turn"
3363 );
3364
3365 session.inner.apply(Notification {
3369 jsonrpc: crate::msp::JsonRpcVersion::V2,
3370 method: "turn/completed".to_owned(),
3371 params: serde_json::json!({
3372 "sessionId": "session-1",
3373 "viewCursor": "cursor-2",
3374 "sourceRange": {
3375 "stream": {"kind": "session", "id": "session-1"},
3376 "first": {"id": "event-1", "sequence": 1},
3377 "last": {"id": "event-1", "sequence": 1}
3378 },
3379 "turnId": "turn-killed",
3380 "terminal": "cancelled",
3381 "reason": "resume_reconcile:orphaned_by_process_loss"
3382 })
3383 .as_object()
3384 .cloned(),
3385 emitted_at_ms: None,
3386 });
3387 {
3388 let state = lock(&session.inner.state);
3389 assert!(
3390 state.settled_turns.contains_key("turn-killed"),
3391 "the reconciled turn is held as a settled turn for its retry"
3392 );
3393 assert!(
3394 !state.history_turn_items.contains_key("turn-killed"),
3395 "opening the route takes the turn's history entry"
3396 );
3397 assert!(
3398 state.item_turns.is_empty(),
3399 "the retired turn drops its replayed items' delta routes"
3400 );
3401 }
3402
3403 let queued = inbound.send(format!(
3404 "{}\n",
3405 serde_json::json!({
3406 "jsonrpc": "2.0",
3407 "id": 2,
3408 "result": {
3409 "commandId": "command-1",
3410 "status": "accepted",
3411 "turnId": "turn-killed",
3412 "startedNewTurn": true,
3413 "disposition": "started"
3414 }
3415 })
3416 ));
3417 assert!(queued.is_ok(), "retry answer queued");
3418 let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
3419 assert!(turn.is_ok(), "same-command retry is accepted");
3420 let Ok(turn) = turn else {
3421 return;
3422 };
3423 let outcome = turn.completed().await;
3424 assert!(
3425 matches!(outcome, Ok(TurnOutcome::Completed { .. })),
3426 "the retried turn settles on the reconciliation terminal, got {outcome:?}"
3427 );
3428 let mut items = turn.items();
3429 let replayed = items.recv().await;
3430 assert!(
3431 matches!(&replayed, Ok(Some(item)) if item.item_id == "item-killed"),
3432 "the retried turn replays its history userMessage, got {replayed:?}"
3433 );
3434 let end = items.recv().await;
3435 assert!(
3436 matches!(end, Ok(None)),
3437 "the history item replays once, got {end:?}"
3438 );
3439 client.close().await;
3440 });
3441 }
3442
3443 #[test]
3444 fn a_same_command_retry_of_a_turn_that_ended_before_the_resume_settles() {
3445 let runtime = tokio::runtime::Builder::new_current_thread()
3450 .enable_all()
3451 .build();
3452 assert!(runtime.is_ok(), "caller runtime builds");
3453 let Ok(runtime) = runtime else {
3454 return;
3455 };
3456 runtime.block_on(async {
3457 let (inbound, reads) = mpsc::unbounded_channel();
3458 let queued = inbound.send(format!(
3459 "{}\n",
3460 serde_json::json!({
3461 "jsonrpc": "2.0",
3462 "id": 1,
3463 "result": {
3464 "session": {
3465 "sessionId": "session-1",
3466 "path": "/tmp/session.jsonl",
3467 "status": "idle",
3468 "activeTurnId": null,
3469 "createdAt": "2026-09-29T00:00:00Z",
3470 "updatedAt": "2026-09-29T00:00:00Z",
3471 "workspaceRoot": null,
3472 "providerId": null,
3473 "modelId": null,
3474 "turnCount": 1,
3475 "forkedFrom": null
3476 },
3477 "viewCursor": "cursor-1",
3478 "history": served_history(HistoryForm::Inline, serde_json::json!([
3479 {
3480 "itemId": "item-done",
3481 "kind": "userMessage",
3482 "turnId": "turn-done",
3483 "commandId": "command-1",
3484 "revision": 1,
3485 "status": "completed",
3486 "text": "retry me"
3487 }
3488 ])),
3489 "lastTurn": {"turnId": "turn-done", "terminal": "completed"},
3490 "pendingRequests": []
3491 }
3492 })
3493 ));
3494 assert!(queued.is_ok(), "resume response queued");
3495 let client = MuseClient::with_command_id_minter(
3496 ChannelTransport { inbound: reads },
3497 SessionDurability::Durable,
3498 || "command-1".to_owned(),
3499 );
3500 let session = client
3501 .resume_session(ResumeSessionOptions {
3502 session_id: "session-1".to_owned(),
3503 ..ResumeSessionOptions::default()
3504 })
3505 .await;
3506 assert!(session.is_ok(), "session resumes");
3507 let Ok(session) = session else {
3508 return;
3509 };
3510 let queued = inbound.send(format!(
3511 "{}\n",
3512 serde_json::json!({
3513 "jsonrpc": "2.0",
3514 "id": 2,
3515 "result": {
3516 "commandId": "command-1",
3517 "status": "accepted",
3518 "turnId": "turn-done",
3519 "startedNewTurn": true,
3520 "disposition": "started"
3521 }
3522 })
3523 ));
3524 assert!(queued.is_ok(), "retry answer queued");
3525 let turn = session.send_user_turn(SendUserTurnOptions::default()).await;
3526 assert!(turn.is_ok(), "same-command retry is accepted");
3527 let Ok(turn) = turn else {
3528 return;
3529 };
3530 let completion = turn.completed();
3531 let outcome = tokio::time::timeout(std::time::Duration::from_secs(5), completion).await;
3533 assert!(
3534 matches!(
3535 &outcome,
3536 Ok(Ok(TurnOutcome::Ended(last_turn)))
3537 if last_turn.turn_id == "turn-done"
3538 && last_turn.terminal == crate::msp::TurnTerminal::Completed
3539 ),
3540 "a retry of a turn that ended before the resume must settle Ended from its \
3541 lastTurn, not wait for close, got {outcome:?}"
3542 );
3543 assert!(
3544 session.pending().is_empty(),
3545 "a retry settled from lastTurn leaves pending()"
3546 );
3547 client.close().await;
3548 });
3549 }
3550}