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