1mod store;
8pub use store::{
9 NewSession, SessionHeader, SessionListing, SessionStore, SessionWriter, StoreError,
10 StoreErrorKind, StoredSession,
11};
12
13use std::collections::{BTreeMap, BTreeSet};
14use std::error::Error;
15use std::fmt::{Display, Formatter};
16use std::sync::Arc;
17use std::time::{SystemTime, UNIX_EPOCH};
18
19use arabica_protocol::{
20 Command, CommandEnvelope, CommandId, ErrorCode, Event, EventEnvelope, EventId, EventMetadata,
21 PROTOCOL_VERSION, RunId, RunStatus, SessionId, SessionStatus, WorkspaceId,
22};
23use arabica_runtime::{RunControl, RuntimeEngine, RuntimeEventLog};
24use serde::{Deserialize, Serialize};
25
26#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
35#[serde(rename_all = "snake_case")]
36pub enum EventVisibility {
37 Client,
38 Internal,
39}
40
41pub trait SessionEventObserver: Send + Sync {
51 fn observe(&self, envelope: &EventEnvelope, visibility: EventVisibility);
52}
53
54pub struct FanOutObserver(Vec<Arc<dyn SessionEventObserver>>);
62
63impl FanOutObserver {
64 pub fn new(observers: Vec<Arc<dyn SessionEventObserver>>) -> Self {
65 Self(observers)
66 }
67}
68
69impl SessionEventObserver for FanOutObserver {
70 fn observe(&self, envelope: &EventEnvelope, visibility: EventVisibility) {
71 for observer in &self.0 {
72 observer.observe(envelope, visibility);
73 }
74 }
75}
76
77#[derive(Clone, Default)]
84pub struct DispatchControl {
85 pub run: RunControl,
86 pub observer: Option<Arc<dyn SessionEventObserver>>,
87}
88
89pub trait IdAllocator: Send + std::fmt::Debug {
98 fn session_id(&mut self) -> SessionId;
99 fn run_id(&mut self) -> RunId;
100
101 fn observe_used_session_id(&mut self, session_id: &SessionId) {
109 let _ = session_id;
110 }
111
112 fn observe_used_run_id(&mut self, run_id: &RunId) {
116 let _ = run_id;
117 }
118}
119
120#[derive(Debug, Default)]
121pub struct SequentialIds {
122 next_session_id: u64,
123 next_run_id: u64,
124}
125
126fn sequential_suffix(id: &str, prefix: &str) -> Option<u64> {
132 id.strip_prefix(prefix)?.parse().ok()
133}
134
135impl IdAllocator for SequentialIds {
136 fn session_id(&mut self) -> SessionId {
137 self.next_session_id += 1;
138 SessionId::new(format!("session-{}", self.next_session_id))
139 }
140
141 fn run_id(&mut self) -> RunId {
142 self.next_run_id += 1;
143 RunId::new(format!("run-{}", self.next_run_id))
144 }
145
146 fn observe_used_session_id(&mut self, session_id: &SessionId) {
147 if let Some(n) = sequential_suffix(&session_id.0, "session-") {
148 self.next_session_id = self.next_session_id.max(n);
149 }
150 }
151
152 fn observe_used_run_id(&mut self, run_id: &RunId) {
153 if let Some(n) = sequential_suffix(&run_id.0, "run-") {
154 self.next_run_id = self.next_run_id.max(n);
155 }
156 }
157}
158
159#[derive(Clone, Debug)]
160pub struct SessionRecord {
161 pub id: SessionId,
162 pub workspace_id: WorkspaceId,
163 pub parent_session_id: Option<SessionId>,
164 pub status: SessionStatus,
165 pub runs: BTreeMap<RunId, RunStatus>,
166 base_events: Vec<EventEnvelope>,
169 events: Vec<EventEnvelope>,
172 next_sequence: u64,
173}
174
175impl SessionRecord {
176 fn runtime_history(&self) -> Vec<EventEnvelope> {
177 if self.base_events.is_empty() {
178 return self.events.clone();
179 }
180 let mut history = Vec::with_capacity(self.base_events.len() + self.events.len());
181 history.extend_from_slice(&self.base_events);
182 history.extend_from_slice(&self.events);
183 history
184 }
185
186 fn append_event(
192 &mut self,
193 command_id: &CommandId,
194 run_id: Option<&RunId>,
195 event: Event,
196 observer: Option<&dyn SessionEventObserver>,
197 ) -> EventEnvelope {
198 self.next_sequence += 1;
199 let sequence = self.next_sequence;
200 let visibility = if event.is_client_visible() {
201 EventVisibility::Client
202 } else {
203 EventVisibility::Internal
204 };
205 let envelope = EventEnvelope::new(
206 EventMetadata {
207 event_id: EventId::new(format!("event-{}-{sequence}", self.id)),
208 command_id: command_id.clone(),
209 workspace_id: self.workspace_id.clone(),
210 session_id: self.id.clone(),
211 run_id: run_id.cloned(),
212 sequence,
213 occurred_at_ms: unix_time_ms(),
214 },
215 event,
216 );
217 self.events.push(envelope.clone());
218 if let Some(observer) = observer {
219 observer.observe(&envelope, visibility);
220 }
221 envelope
222 }
223}
224
225struct SessionRuntimeEventLog<'a> {
226 session: &'a mut SessionRecord,
227 command_id: CommandId,
228 run_id: Option<RunId>,
229 observer: Option<&'a dyn SessionEventObserver>,
230 emitted: Vec<EventEnvelope>,
231}
232
233impl<'a> SessionRuntimeEventLog<'a> {
234 fn new(
235 session: &'a mut SessionRecord,
236 command_id: CommandId,
237 run_id: Option<RunId>,
238 observer: Option<&'a dyn SessionEventObserver>,
239 ) -> Self {
240 Self {
241 session,
242 command_id,
243 run_id,
244 observer,
245 emitted: Vec::new(),
246 }
247 }
248
249 fn into_emitted(self) -> Vec<EventEnvelope> {
250 self.emitted
251 }
252}
253
254impl RuntimeEventLog for SessionRuntimeEventLog<'_> {
255 fn snapshot(&self) -> Vec<EventEnvelope> {
256 self.session.runtime_history()
257 }
258
259 fn append(&mut self, event: Event) -> EventEnvelope {
260 let client_visible = event.is_client_visible();
261 let envelope =
262 self.session
263 .append_event(&self.command_id, self.run_id.as_ref(), event, self.observer);
264 if client_visible {
265 self.emitted.push(envelope.clone());
266 }
267 envelope
268 }
269}
270
271#[derive(Clone, Debug, Eq, PartialEq)]
272pub struct SessionError {
273 pub code: ErrorCode,
274 pub message: String,
275}
276
277impl SessionError {
278 fn new(code: ErrorCode, message: impl Into<String>) -> Self {
279 Self {
280 code,
281 message: message.into(),
282 }
283 }
284}
285
286impl Display for SessionError {
287 fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
288 self.message.fmt(formatter)
289 }
290}
291
292impl Error for SessionError {}
293
294#[derive(Debug)]
295pub struct SessionManager<R> {
296 runtime: R,
297 sessions: BTreeMap<SessionId, SessionRecord>,
298 processed_commands: BTreeMap<CommandId, (CommandEnvelope, Vec<EventEnvelope>)>,
299 ids: Box<dyn IdAllocator>,
300}
301
302impl<R> SessionManager<R> {
303 pub fn new(runtime: R) -> Self {
304 Self::with_ids(runtime, Box::new(SequentialIds::default()))
305 }
306
307 pub fn with_ids(runtime: R, ids: Box<dyn IdAllocator>) -> Self {
311 Self {
312 runtime,
313 sessions: BTreeMap::new(),
314 processed_commands: BTreeMap::new(),
315 ids,
316 }
317 }
318
319 pub fn session(&self, session_id: &SessionId) -> Option<&SessionRecord> {
320 self.sessions.get(session_id)
321 }
322
323 pub fn runtime(&self) -> &R {
324 &self.runtime
325 }
326
327 pub fn runtime_mut(&mut self) -> &mut R {
328 &mut self.runtime
329 }
330
331 fn allocate_session_id(&mut self) -> SessionId {
332 self.ids.session_id()
333 }
334
335 fn allocate_run_id(&mut self) -> RunId {
336 self.ids.run_id()
337 }
338
339 fn require_session_id(
340 &self,
341 session_id: Option<&SessionId>,
342 ) -> Result<SessionId, SessionError> {
343 let session_id = session_id.cloned().ok_or_else(|| {
344 SessionError::new(
345 ErrorCode::InvalidCommand,
346 "this command requires envelope.session_id",
347 )
348 })?;
349 if !self.sessions.contains_key(&session_id) {
350 return Err(SessionError::new(
351 ErrorCode::SessionNotFound,
352 format!("session not found: {session_id}"),
353 ));
354 }
355 Ok(session_id)
356 }
357
358 fn require_active(&self, session_id: &SessionId) -> Result<(), SessionError> {
359 let session = self.sessions.get(session_id).ok_or_else(|| {
360 SessionError::new(
361 ErrorCode::SessionNotFound,
362 format!("session not found: {session_id}"),
363 )
364 })?;
365 if session.status != SessionStatus::Active {
366 return Err(SessionError::new(
367 ErrorCode::InvalidSessionState,
368 format!("session {session_id} is not active"),
369 ));
370 }
371 Ok(())
372 }
373
374 fn append_events(
375 &mut self,
376 command_id: &CommandId,
377 session_id: &SessionId,
378 run_id: Option<&RunId>,
379 events: impl IntoIterator<Item = Event>,
380 observer: Option<&dyn SessionEventObserver>,
381 ) -> Vec<EventEnvelope> {
382 let session = self
383 .sessions
384 .get_mut(session_id)
385 .expect("session must exist before events are appended");
386 events
387 .into_iter()
388 .map(|event| session.append_event(command_id, run_id, event, observer))
389 .collect()
390 }
391}
392
393impl<R: RuntimeEngine> SessionManager<R> {
394 pub async fn handle(
400 &mut self,
401 envelope: CommandEnvelope,
402 ) -> Result<Vec<EventEnvelope>, SessionError> {
403 self.dispatch(envelope, DispatchControl::default()).await
404 }
405
406 pub async fn dispatch(
416 &mut self,
417 envelope: CommandEnvelope,
418 control: DispatchControl,
419 ) -> Result<Vec<EventEnvelope>, SessionError> {
420 if envelope.protocol_version != PROTOCOL_VERSION {
421 return Err(SessionError::new(
422 ErrorCode::ProtocolVersionMismatch,
423 format!(
424 "unsupported protocol version {}; expected {PROTOCOL_VERSION}",
425 envelope.protocol_version
426 ),
427 ));
428 }
429
430 if let Some((original, events)) = self.processed_commands.get(&envelope.command_id) {
431 if original != &envelope {
432 return Err(SessionError::new(
433 ErrorCode::InvalidCommand,
434 format!(
435 "command_id {} was already used with a different command",
436 envelope.command_id
437 ),
438 ));
439 }
440 return Ok(events.clone());
441 }
442
443 let original = envelope.clone();
444 let command_id = envelope.command_id.clone();
445 let events = self.handle_once(envelope, &control).await?;
446 self.processed_commands
447 .insert(command_id, (original, events.clone()));
448 Ok(events)
449 }
450
451 async fn handle_once(
452 &mut self,
453 envelope: CommandEnvelope,
454 control: &DispatchControl,
455 ) -> Result<Vec<EventEnvelope>, SessionError> {
456 let observer = control.observer.as_deref();
457 let command_id = envelope.command_id;
458 match envelope.command {
459 Command::SessionCreate { workspace_id } => {
460 let session_id = self.allocate_session_id();
461 self.runtime
462 .open_session(&session_id, &workspace_id)
463 .map_err(|error| {
464 SessionError::new(ErrorCode::RuntimeFailure, error.to_string())
465 })?;
466 self.sessions.insert(
467 session_id.clone(),
468 SessionRecord {
469 id: session_id.clone(),
470 workspace_id: workspace_id.clone(),
471 parent_session_id: None,
472 status: SessionStatus::Active,
473 runs: BTreeMap::new(),
474 base_events: Vec::new(),
475 events: Vec::new(),
476 next_sequence: 0,
477 },
478 );
479 Ok(self.append_events(
480 &command_id,
481 &session_id,
482 None,
483 [Event::SessionCreated { workspace_id }],
484 observer,
485 ))
486 }
487 Command::SessionFork { source_session_id } => {
488 let source = self
489 .sessions
490 .get(&source_session_id)
491 .cloned()
492 .ok_or_else(|| {
493 SessionError::new(
494 ErrorCode::SessionNotFound,
495 format!("session not found: {source_session_id}"),
496 )
497 })?;
498 let inherited_events = source.runtime_history();
499 let session_id = self.allocate_session_id();
500 self.runtime
501 .fork_session(&source_session_id, &session_id)
502 .map_err(|error| {
503 SessionError::new(ErrorCode::RuntimeFailure, error.to_string())
504 })?;
505 self.sessions.insert(
506 session_id.clone(),
507 SessionRecord {
508 id: session_id.clone(),
509 workspace_id: source.workspace_id,
510 parent_session_id: Some(source_session_id.clone()),
511 status: SessionStatus::Active,
512 runs: BTreeMap::new(),
513 base_events: inherited_events,
514 events: Vec::new(),
515 next_sequence: 0,
516 },
517 );
518 Ok(self.append_events(
519 &command_id,
520 &session_id,
521 None,
522 [Event::SessionForked { source_session_id }],
523 observer,
524 ))
525 }
526 Command::SessionResume => {
527 let session_id = self.require_session_id(envelope.session_id.as_ref())?;
528 let status = self
529 .sessions
530 .get(&session_id)
531 .expect("validated session exists")
532 .status;
533 if status != SessionStatus::Suspended {
534 return Err(SessionError::new(
535 ErrorCode::InvalidSessionState,
536 format!("session {session_id} cannot resume from {status:?}"),
537 ));
538 }
539 self.sessions
540 .get_mut(&session_id)
541 .expect("validated session exists")
542 .status = SessionStatus::Active;
543 Ok(self.append_events(
544 &command_id,
545 &session_id,
546 None,
547 [Event::SessionResumed],
548 observer,
549 ))
550 }
551 Command::SessionSuspend => {
552 let session_id = self.require_session_id(envelope.session_id.as_ref())?;
553 self.require_active(&session_id)?;
554 self.sessions
555 .get_mut(&session_id)
556 .expect("validated session exists")
557 .status = SessionStatus::Suspended;
558 Ok(self.append_events(
559 &command_id,
560 &session_id,
561 None,
562 [Event::SessionSuspended],
563 observer,
564 ))
565 }
566 Command::SessionClose => {
567 let session_id = self.require_session_id(envelope.session_id.as_ref())?;
568 let status = self
569 .sessions
570 .get(&session_id)
571 .expect("validated session exists")
572 .status;
573 if status == SessionStatus::Closed {
574 return Err(SessionError::new(
575 ErrorCode::InvalidSessionState,
576 format!("session {session_id} is already closed"),
577 ));
578 }
579 self.runtime.close_session(&session_id).map_err(|error| {
580 SessionError::new(ErrorCode::RuntimeFailure, error.to_string())
581 })?;
582 self.sessions
583 .get_mut(&session_id)
584 .expect("validated session exists")
585 .status = SessionStatus::Closed;
586 Ok(self.append_events(
587 &command_id,
588 &session_id,
589 None,
590 [Event::SessionClosed],
591 observer,
592 ))
593 }
594 Command::MessageSend { content, images } => {
595 let session_id = self.require_session_id(envelope.session_id.as_ref())?;
596 self.require_active(&session_id)?;
597 let run_id = self.allocate_run_id();
598 self.sessions
599 .get_mut(&session_id)
600 .expect("validated session exists")
601 .runs
602 .insert(run_id.clone(), RunStatus::Pending);
603
604 let mut envelopes = self.append_events(
605 &command_id,
606 &session_id,
607 Some(&run_id),
608 [Event::RunScheduled],
609 observer,
610 );
611 self.sessions
612 .get_mut(&session_id)
613 .expect("validated session exists")
614 .runs
615 .insert(run_id.clone(), RunStatus::Running);
616
617 let runtime_command = Command::MessageSend { content, images };
618 let runtime = &mut self.runtime;
619 let session = self
620 .sessions
621 .get_mut(&session_id)
622 .expect("validated session exists");
623 let mut event_log = SessionRuntimeEventLog::new(
624 session,
625 command_id.clone(),
626 Some(run_id.clone()),
627 observer,
628 );
629 if let Err(error) = runtime
630 .handle_with_control(
631 &session_id,
632 Some(&run_id),
633 &mut event_log,
634 &runtime_command,
635 &control.run,
636 )
637 .await
638 {
639 event_log.append(Event::RunFailed {
640 message: error.to_string(),
641 });
642 }
643 let status = terminal_run_status(&event_log.emitted).unwrap_or(RunStatus::Running);
644 event_log.session.runs.insert(run_id.clone(), status);
645 envelopes.extend(event_log.into_emitted());
646 Ok(envelopes)
647 }
648 Command::RunCancel { run_id } => {
649 let session_id = self.require_session_id(envelope.session_id.as_ref())?;
650 let run_status = self
651 .sessions
652 .get(&session_id)
653 .expect("validated session exists")
654 .runs
655 .get(&run_id)
656 .copied()
657 .ok_or_else(|| {
658 SessionError::new(
659 ErrorCode::RunNotFound,
660 format!("run not found: {run_id}"),
661 )
662 })?;
663 if !matches!(
664 run_status,
665 RunStatus::Pending | RunStatus::Running | RunStatus::WaitingForTool
666 ) {
667 return Err(SessionError::new(
668 ErrorCode::InvalidSessionState,
669 format!("run {run_id} cannot be cancelled from {run_status:?}"),
670 ));
671 }
672 let command = Command::RunCancel {
673 run_id: run_id.clone(),
674 };
675 let runtime = &mut self.runtime;
676 let session = self
677 .sessions
678 .get_mut(&session_id)
679 .expect("validated session exists");
680 let mut event_log = SessionRuntimeEventLog::new(
681 session,
682 command_id,
683 Some(run_id.clone()),
684 observer,
685 );
686 runtime
687 .handle_with_control(
688 &session_id,
689 Some(&run_id),
690 &mut event_log,
691 &command,
692 &control.run,
693 )
694 .await
695 .map_err(|error| {
696 SessionError::new(ErrorCode::RuntimeFailure, error.to_string())
697 })?;
698 event_log
699 .session
700 .runs
701 .insert(run_id.clone(), RunStatus::Cancelled);
702 Ok(event_log.into_emitted())
703 }
704 command @ (Command::ContextRead { .. }
705 | Command::ContextSearch { .. }
706 | Command::ContextUpdate { .. }
707 | Command::ContextDelete { .. }
708 | Command::ContextSetDisclosure { .. }) => {
709 let session_id = self.require_session_id(envelope.session_id.as_ref())?;
710 self.require_active(&session_id)?;
711 let runtime = &mut self.runtime;
712 let session = self
713 .sessions
714 .get_mut(&session_id)
715 .expect("validated session exists");
716 let mut event_log =
717 SessionRuntimeEventLog::new(session, command_id, None, observer);
718 if let Err(error) = runtime
719 .handle_with_control(&session_id, None, &mut event_log, &command, &control.run)
720 .await
721 {
722 event_log.append(Event::Error {
723 code: ErrorCode::RuntimeFailure,
724 message: error.to_string(),
725 });
726 }
727 Ok(event_log.into_emitted())
728 }
729 }
730 }
731
732 pub fn restore_session(
752 &mut self,
753 snapshot: SessionSnapshot,
754 restore_command_id: CommandId,
755 observer: Option<&dyn SessionEventObserver>,
756 ) -> Result<RestoreReport, SessionError> {
757 let events = snapshot.events;
758 let Some(first) = events.first() else {
759 return Err(SessionError::new(
760 ErrorCode::InvalidSnapshot,
761 "a session snapshot must contain at least one Event",
762 ));
763 };
764 if !matches!(first.event, Event::SessionCreated { .. }) {
765 return Err(SessionError::new(
766 ErrorCode::InvalidSnapshot,
767 "restore only accepts a session with no parent; its first Event must be session.created",
768 ));
769 }
770 validate_contiguous_sequence(&events)?;
771
772 let session_id = first.session_id.clone();
773 let workspace_id = first.workspace_id.clone();
774 if self.sessions.contains_key(&session_id) {
775 return Err(SessionError::new(
776 ErrorCode::InvalidSessionState,
777 format!("session {session_id} is already open; cannot restore over it"),
778 ));
779 }
780
781 let status = derive_status(&events);
782 let (runs, interrupted_runs) = derive_runs(&events);
783 let next_sequence = events.last().expect("checked non-empty above").sequence;
784 let dangling_by_run: Vec<(RunId, Vec<(String, String)>)> = interrupted_runs
785 .iter()
786 .map(|run_id| {
787 let run_events: Vec<EventEnvelope> = events
788 .iter()
789 .filter(|envelope| envelope.run_id.as_ref() == Some(run_id))
790 .cloned()
791 .collect();
792 (run_id.clone(), dangling_tool_calls(&run_events))
793 })
794 .collect();
795
796 self.runtime
797 .restore_session(&session_id, &workspace_id, &events)
798 .map_err(|error| SessionError::new(ErrorCode::RuntimeFailure, error.to_string()))?;
799
800 let restored_event_count = events.len();
801 self.sessions.insert(
802 session_id.clone(),
803 SessionRecord {
804 id: session_id.clone(),
805 workspace_id,
806 parent_session_id: None,
807 status,
808 runs,
809 base_events: Vec::new(),
810 events,
811 next_sequence,
812 },
813 );
814
815 let mut repaired_events = Vec::new();
816 for (run_id, dangling) in dangling_by_run {
817 for (call_id, name) in dangling {
818 repaired_events.extend(
819 self.append_events(
820 &restore_command_id,
821 &session_id,
822 Some(&run_id),
823 [Event::ToolCallCompleted {
824 call_id,
825 name,
826 result: "run_interrupted: the process ended before this call completed"
827 .to_owned(),
828 is_error: true,
829 }],
830 observer,
831 ),
832 );
833 }
834 repaired_events.extend(self.append_events(
835 &restore_command_id,
836 &session_id,
837 Some(&run_id),
838 [Event::RunFailed {
839 message: format!(
840 "run_interrupted: the process ended before run {run_id} finished"
841 ),
842 }],
843 observer,
844 ));
845 }
846
847 self.ids.observe_used_session_id(&session_id);
848 for run_id in self
849 .sessions
850 .get(&session_id)
851 .expect("just inserted")
852 .runs
853 .keys()
854 {
855 self.ids.observe_used_run_id(run_id);
856 }
857
858 Ok(RestoreReport {
859 session_id,
860 restored_event_count,
861 repaired_events,
862 interrupted_runs,
863 })
864 }
865}
866
867fn unix_time_ms() -> u64 {
868 SystemTime::now()
869 .duration_since(UNIX_EPOCH)
870 .unwrap_or_default()
871 .as_millis()
872 .try_into()
873 .unwrap_or(u64::MAX)
874}
875
876fn terminal_run_status(events: &[EventEnvelope]) -> Option<RunStatus> {
877 events.iter().rev().find_map(|event| match event {
878 EventEnvelope {
879 event: Event::RunCompleted { .. },
880 ..
881 } => Some(RunStatus::Finished),
882 EventEnvelope {
883 event: Event::RunFailed { .. },
884 ..
885 } => Some(RunStatus::Failed),
886 EventEnvelope {
887 event: Event::RunCancelled,
888 ..
889 } => Some(RunStatus::Cancelled),
890 _ => None,
891 })
892}
893
894pub struct SessionSnapshot {
900 pub events: Vec<EventEnvelope>,
901}
902
903#[derive(Debug)]
908pub struct RestoreReport {
909 pub session_id: SessionId,
910 pub restored_event_count: usize,
911 pub repaired_events: Vec<EventEnvelope>,
916 pub interrupted_runs: Vec<RunId>,
919}
920
921fn validate_contiguous_sequence(events: &[EventEnvelope]) -> Result<(), SessionError> {
922 for (index, envelope) in events.iter().enumerate() {
923 let expected = (index as u64) + 1;
924 if envelope.sequence != expected {
925 return Err(SessionError::new(
926 ErrorCode::InvalidSnapshot,
927 format!(
928 "non-contiguous snapshot: expected sequence {expected} at position {index}, found {}",
929 envelope.sequence
930 ),
931 ));
932 }
933 }
934 Ok(())
935}
936
937fn derive_status(events: &[EventEnvelope]) -> SessionStatus {
938 events
939 .iter()
940 .rev()
941 .find_map(|envelope| match &envelope.event {
942 Event::SessionCreated { .. } | Event::SessionForked { .. } | Event::SessionResumed => {
943 Some(SessionStatus::Active)
944 }
945 Event::SessionSuspended => Some(SessionStatus::Suspended),
946 Event::SessionClosed => Some(SessionStatus::Closed),
947 _ => None,
948 })
949 .unwrap_or(SessionStatus::Active)
955}
956
957fn derive_runs(events: &[EventEnvelope]) -> (BTreeMap<RunId, RunStatus>, Vec<RunId>) {
963 let mut runs = BTreeMap::new();
964 let mut interrupted = Vec::new();
965 let run_ids: BTreeSet<RunId> = events.iter().filter_map(|e| e.run_id.clone()).collect();
966 for run_id in run_ids {
967 let run_events: Vec<EventEnvelope> = events
968 .iter()
969 .filter(|envelope| envelope.run_id.as_ref() == Some(&run_id))
970 .cloned()
971 .collect();
972 match terminal_run_status(&run_events) {
973 Some(status) => {
974 runs.insert(run_id, status);
975 }
976 None => {
977 runs.insert(run_id.clone(), RunStatus::Failed);
978 interrupted.push(run_id);
979 }
980 }
981 }
982 (runs, interrupted)
983}
984
985fn dangling_tool_calls(run_events: &[EventEnvelope]) -> Vec<(String, String)> {
988 let mut requested = Vec::new();
989 let mut completed = BTreeSet::new();
990 for envelope in run_events {
991 match &envelope.event {
992 Event::ToolCallRequested { call_id, name, .. } => {
993 requested.push((call_id.clone(), name.clone()));
994 }
995 Event::ToolCallCompleted { call_id, .. } => {
996 completed.insert(call_id.clone());
997 }
998 _ => {}
999 }
1000 }
1001 requested
1002 .into_iter()
1003 .filter(|(call_id, _)| !completed.contains(call_id))
1004 .collect()
1005}
1006
1007#[cfg(test)]
1008mod tests {
1009 use super::*;
1010 use arabica_model::{
1011 ContentBlock, MessageItem, RuntimeItem, RuntimeRole, ToolCallItem, ToolResultItem,
1012 };
1013 use arabica_model::{FinishReason, RuntimeResponse, RuntimeUsage, ShortMemoryItem};
1014 use arabica_protocol::ContextEntry;
1015 use arabica_provider::{
1016 EchoModel, ModelProvider, ModelRunRequest, ModelRunResult, ProviderError,
1017 };
1018 use arabica_runner::NoopRunner;
1019 use arabica_runner::{
1020 RunnerEnvironment, RunnerError, RunnerOutput, ToolExecutionRequest, ToolExecutionResult,
1021 };
1022 use arabica_runtime::{
1023 CoreRuntime, RunCancellation, ToolPermissionGate, ToolPermissionPolicy, ToolPermissionRule,
1024 };
1025 use std::sync::Mutex;
1026
1027 #[test]
1028 fn event_visibility_serializes_as_the_documented_lowercase_strings() {
1029 assert_eq!(
1030 serde_json::to_string(&EventVisibility::Client).unwrap(),
1031 "\"client\""
1032 );
1033 assert_eq!(
1034 serde_json::to_string(&EventVisibility::Internal).unwrap(),
1035 "\"internal\""
1036 );
1037 assert_eq!(
1038 serde_json::from_str::<EventVisibility>("\"client\"").unwrap(),
1039 EventVisibility::Client
1040 );
1041 }
1042
1043 #[test]
1044 fn fan_out_observer_forwards_to_every_observer_in_order() {
1045 struct Named(&'static str, Arc<Mutex<Vec<&'static str>>>);
1046 impl SessionEventObserver for Named {
1047 fn observe(&self, _envelope: &EventEnvelope, _visibility: EventVisibility) {
1048 self.1.lock().unwrap().push(self.0);
1049 }
1050 }
1051
1052 let log: Arc<Mutex<Vec<&'static str>>> = Arc::new(Mutex::new(Vec::new()));
1053 let fan_out = FanOutObserver::new(vec![
1054 Arc::new(Named("first", log.clone())),
1055 Arc::new(Named("second", log.clone())),
1056 ]);
1057
1058 let envelope = EventEnvelope::new(
1059 EventMetadata {
1060 event_id: EventId::new("event-1"),
1061 command_id: CommandId::new("command-1"),
1062 workspace_id: WorkspaceId::new("ws-1"),
1063 session_id: SessionId::new("session-1"),
1064 run_id: None,
1065 sequence: 1,
1066 occurred_at_ms: 0,
1067 },
1068 Event::RunScheduled,
1069 );
1070 fan_out.observe(&envelope, EventVisibility::Client);
1071
1072 assert_eq!(*log.lock().unwrap(), vec!["first", "second"]);
1073 }
1074
1075 #[derive(Debug, Default)]
1076 struct CapturingModel {
1077 requests: Vec<ModelRunRequest>,
1078 }
1079
1080 impl ModelProvider for CapturingModel {
1081 async fn complete(
1082 &mut self,
1083 request: ModelRunRequest,
1084 ) -> Result<ModelRunResult, ProviderError> {
1085 let output = request.input.clone();
1086 self.requests.push(request);
1087 Ok(ModelRunResult {
1088 final_output: Some(output),
1089 prepared_request: None,
1090 response: None,
1091 })
1092 }
1093
1094 async fn cancel(&mut self, _run_id: &RunId) -> Result<bool, ProviderError> {
1095 Ok(false)
1096 }
1097 }
1098
1099 #[derive(Debug, Default)]
1100 struct TruncatedModel;
1101
1102 impl ModelProvider for TruncatedModel {
1103 async fn complete(
1104 &mut self,
1105 _request: ModelRunRequest,
1106 ) -> Result<ModelRunResult, ProviderError> {
1107 Ok(ModelRunResult {
1108 final_output: None,
1109 prepared_request: None,
1110 response: Some(RuntimeResponse {
1111 items: Vec::new(),
1112 finish_reason: Some(FinishReason::Length),
1113 usage: RuntimeUsage {
1114 input_tokens: 100,
1115 output_tokens: 8_192,
1116 cached_input_tokens: 80,
1117 cache_creation_input_tokens: 0,
1118 reasoning_output_tokens: 0,
1119 },
1120 provider_state: None,
1121 }),
1122 })
1123 }
1124
1125 async fn cancel(&mut self, _run_id: &RunId) -> Result<bool, ProviderError> {
1126 Ok(false)
1127 }
1128 }
1129
1130 fn command(id: &str, session_id: Option<SessionId>, command: Command) -> CommandEnvelope {
1131 CommandEnvelope::new(CommandId::new(id), session_id, command)
1132 }
1133
1134 #[tokio::test]
1135 async fn session_manager_schedules_runs_and_sequences_runtime_events() {
1136 let runtime = CoreRuntime::new(EchoModel::default(), NoopRunner);
1137 let mut manager = SessionManager::new(runtime);
1138 let created = manager
1139 .handle(command(
1140 "command-1",
1141 None,
1142 Command::SessionCreate {
1143 workspace_id: WorkspaceId::new("workspace-1"),
1144 },
1145 ))
1146 .await
1147 .expect("session is created");
1148 let session_id = created[0].session_id.clone();
1149
1150 let events = manager
1151 .handle(command(
1152 "command-2",
1153 Some(session_id.clone()),
1154 Command::MessageSend {
1155 images: Vec::new(),
1156 content: "hello".to_owned(),
1157 },
1158 ))
1159 .await
1160 .expect("message is dispatched");
1161
1162 assert_eq!(events[0].sequence, 2);
1163 assert!(matches!(events[0].event, Event::RunScheduled));
1164 assert!(matches!(events[1].event, Event::RunStarted));
1165 assert!(matches!(
1166 events.last().expect("terminal event").event,
1167 Event::RunCompleted { .. }
1168 ));
1169 let run_id = events[0].run_id.as_ref().expect("run id");
1170 assert_eq!(
1171 manager
1172 .session(&session_id)
1173 .expect("session exists")
1174 .runs
1175 .get(run_id),
1176 Some(&RunStatus::Finished)
1177 );
1178 }
1179
1180 #[tokio::test]
1181 async fn session_manager_marks_length_truncation_as_failed() {
1182 let runtime = CoreRuntime::new(TruncatedModel, NoopRunner);
1183 let mut manager = SessionManager::new(runtime);
1184 let created = manager
1185 .handle(command(
1186 "command-1",
1187 None,
1188 Command::SessionCreate {
1189 workspace_id: WorkspaceId::new("workspace-1"),
1190 },
1191 ))
1192 .await
1193 .expect("session is created");
1194 let session_id = created[0].session_id.clone();
1195
1196 let events = manager
1197 .handle(command(
1198 "command-2",
1199 Some(session_id.clone()),
1200 Command::MessageSend {
1201 images: Vec::new(),
1202 content: "hello".to_owned(),
1203 },
1204 ))
1205 .await
1206 .expect("truncation is represented as a terminal event");
1207
1208 assert!(matches!(
1209 &events.last().expect("terminal event").event,
1210 Event::RunFailed { message } if message.starts_with("model_output_truncated:")
1211 ));
1212 let run_id = events[0].run_id.as_ref().expect("run id");
1213 assert_eq!(
1214 manager
1215 .session(&session_id)
1216 .expect("session exists")
1217 .runs
1218 .get(run_id),
1219 Some(&RunStatus::Failed)
1220 );
1221 }
1222
1223 #[tokio::test]
1224 async fn forked_session_shares_workspace_long_memory() {
1225 let runtime = CoreRuntime::new(EchoModel::default(), NoopRunner);
1226 let mut manager = SessionManager::new(runtime);
1227 let created = manager
1228 .handle(command(
1229 "create",
1230 None,
1231 Command::SessionCreate {
1232 workspace_id: WorkspaceId::new("workspace-1"),
1233 },
1234 ))
1235 .await
1236 .expect("session is created");
1237 let source_id = created[0].session_id.clone();
1238 manager
1239 .handle(command(
1240 "update",
1241 Some(source_id.clone()),
1242 Command::ContextUpdate {
1243 path: "memory/name".to_owned(),
1244 content: "Structure".to_owned(),
1245 },
1246 ))
1247 .await
1248 .expect("context is updated");
1249
1250 let forked = manager
1251 .handle(command(
1252 "fork",
1253 None,
1254 Command::SessionFork {
1255 source_session_id: source_id.clone(),
1256 },
1257 ))
1258 .await
1259 .expect("session is forked");
1260 let target_id = forked[0].session_id.clone();
1261 manager
1262 .handle(command(
1263 "update-after-fork",
1264 Some(source_id),
1265 Command::ContextUpdate {
1266 path: "memory/name".to_owned(),
1267 content: "Shared Structure".to_owned(),
1268 },
1269 ))
1270 .await
1271 .expect("workspace long memory is updated after fork");
1272 let read = manager
1273 .handle(command(
1274 "read",
1275 Some(target_id),
1276 Command::ContextRead {
1277 path: "memory/name".to_owned(),
1278 },
1279 ))
1280 .await
1281 .expect("forked context can be read");
1282
1283 assert_eq!(
1284 read[0].event,
1285 Event::ContextRead {
1286 entry: ContextEntry {
1287 path: "memory/name".to_owned(),
1288 content: "Shared Structure".to_owned(),
1289 }
1290 }
1291 );
1292 }
1293
1294 #[tokio::test]
1295 async fn forked_session_inherits_short_memory_at_the_fork_boundary() {
1296 let runtime = CoreRuntime::new(CapturingModel::default(), NoopRunner);
1297 let mut manager = SessionManager::new(runtime);
1298 let created = manager
1299 .handle(command(
1300 "create",
1301 None,
1302 Command::SessionCreate {
1303 workspace_id: WorkspaceId::new("workspace-1"),
1304 },
1305 ))
1306 .await
1307 .expect("session is created");
1308 let source_id = created[0].session_id.clone();
1309 manager
1310 .handle(command(
1311 "first-message",
1312 Some(source_id.clone()),
1313 Command::MessageSend {
1314 images: Vec::new(),
1315 content: "first".to_owned(),
1316 },
1317 ))
1318 .await
1319 .expect("source run completes");
1320
1321 let forked = manager
1322 .handle(command(
1323 "fork",
1324 None,
1325 Command::SessionFork {
1326 source_session_id: source_id,
1327 },
1328 ))
1329 .await
1330 .expect("session is forked");
1331 let target_id = forked[0].session_id.clone();
1332 manager
1333 .handle(command(
1334 "second-message",
1335 Some(target_id),
1336 Command::MessageSend {
1337 images: Vec::new(),
1338 content: "second".to_owned(),
1339 },
1340 ))
1341 .await
1342 .expect("forked run completes");
1343
1344 let request = manager
1345 .runtime()
1346 .model()
1347 .requests
1348 .last()
1349 .expect("runner request exists");
1350 assert!(request.short_memory.iter().any(|entry| matches!(
1351 &entry.item,
1352 ShortMemoryItem::UserMessage { content, .. } if content == "first"
1353 )));
1354 assert!(!request.short_memory.iter().any(|entry| matches!(
1355 &entry.item,
1356 ShortMemoryItem::UserMessage { content, .. } if content == "second"
1357 )));
1358 }
1359
1360 #[tokio::test]
1361 async fn incompatible_protocol_versions_are_rejected_at_the_boundary() {
1362 let runtime = CoreRuntime::new(EchoModel::default(), NoopRunner);
1363 let mut manager = SessionManager::new(runtime);
1364 let mut envelope = command(
1365 "create",
1366 None,
1367 Command::SessionCreate {
1368 workspace_id: WorkspaceId::new("workspace-1"),
1369 },
1370 );
1371 envelope.protocol_version = "2.0".to_owned();
1372
1373 let error = manager
1374 .handle(envelope)
1375 .await
1376 .expect_err("version is rejected");
1377 assert_eq!(error.code, ErrorCode::ProtocolVersionMismatch);
1378 }
1379
1380 #[tokio::test]
1381 async fn a_terminal_run_cannot_be_cancelled() {
1382 let runtime = CoreRuntime::new(EchoModel::default(), NoopRunner);
1383 let mut manager = SessionManager::new(runtime);
1384 let created = manager
1385 .handle(command(
1386 "create",
1387 None,
1388 Command::SessionCreate {
1389 workspace_id: WorkspaceId::new("workspace-1"),
1390 },
1391 ))
1392 .await
1393 .expect("session is created");
1394 let session_id = created[0].session_id.clone();
1395 let completed = manager
1396 .handle(command(
1397 "message",
1398 Some(session_id.clone()),
1399 Command::MessageSend {
1400 images: Vec::new(),
1401 content: "done".to_owned(),
1402 },
1403 ))
1404 .await
1405 .expect("run completes");
1406 let run_id = completed[0].run_id.clone().expect("run id exists");
1407
1408 let error = manager
1409 .handle(command(
1410 "cancel",
1411 Some(session_id),
1412 Command::RunCancel { run_id },
1413 ))
1414 .await
1415 .expect_err("terminal run cannot be cancelled");
1416 assert_eq!(error.code, ErrorCode::InvalidSessionState);
1417 }
1418
1419 #[tokio::test]
1420 async fn retrying_a_command_id_replays_events_without_reexecuting_it() {
1421 let runtime = CoreRuntime::new(EchoModel::default(), NoopRunner);
1422 let mut manager = SessionManager::new(runtime);
1423 let create = command(
1424 "create-once",
1425 None,
1426 Command::SessionCreate {
1427 workspace_id: WorkspaceId::new("workspace-1"),
1428 },
1429 );
1430
1431 let first = manager
1432 .handle(create.clone())
1433 .await
1434 .expect("first command succeeds");
1435 let replay = manager
1436 .handle(create)
1437 .await
1438 .expect("retry returns cached events");
1439
1440 assert_eq!(replay, first);
1441 assert_eq!(manager.sessions.len(), 1);
1442 }
1443
1444 #[tokio::test]
1445 async fn reusing_a_command_id_with_a_different_body_is_rejected() {
1446 let runtime = CoreRuntime::new(EchoModel::default(), NoopRunner);
1447 let mut manager = SessionManager::new(runtime);
1448 manager
1449 .handle(command(
1450 "same-id",
1451 None,
1452 Command::SessionCreate {
1453 workspace_id: WorkspaceId::new("workspace-1"),
1454 },
1455 ))
1456 .await
1457 .expect("first command succeeds");
1458
1459 let error = manager
1460 .handle(command(
1461 "same-id",
1462 None,
1463 Command::SessionCreate {
1464 workspace_id: WorkspaceId::new("workspace-2"),
1465 },
1466 ))
1467 .await
1468 .expect_err("conflicting idempotency key is rejected");
1469 assert_eq!(error.code, ErrorCode::InvalidCommand);
1470 }
1471
1472 #[tokio::test]
1473 async fn session_lifecycle_enforces_suspend_resume_and_close() {
1474 let runtime = CoreRuntime::new(EchoModel::default(), NoopRunner);
1475 let mut manager = SessionManager::new(runtime);
1476 let created = manager
1477 .handle(command(
1478 "create",
1479 None,
1480 Command::SessionCreate {
1481 workspace_id: WorkspaceId::new("workspace-1"),
1482 },
1483 ))
1484 .await
1485 .expect("session is created");
1486 let session_id = created[0].session_id.clone();
1487
1488 manager
1489 .handle(command(
1490 "suspend",
1491 Some(session_id.clone()),
1492 Command::SessionSuspend,
1493 ))
1494 .await
1495 .expect("active session suspends");
1496 assert_eq!(
1497 manager.session(&session_id).expect("session exists").status,
1498 SessionStatus::Suspended
1499 );
1500
1501 manager
1502 .handle(command(
1503 "resume",
1504 Some(session_id.clone()),
1505 Command::SessionResume,
1506 ))
1507 .await
1508 .expect("suspended session resumes");
1509 manager
1510 .handle(command(
1511 "close",
1512 Some(session_id.clone()),
1513 Command::SessionClose,
1514 ))
1515 .await
1516 .expect("session closes");
1517 assert!(
1518 !manager.runtime().is_session_open(&session_id),
1519 "closing a session releases its runtime context"
1520 );
1521
1522 let error = manager
1523 .handle(command(
1524 "message-after-close",
1525 Some(session_id),
1526 Command::MessageSend {
1527 images: Vec::new(),
1528 content: "blocked".to_owned(),
1529 },
1530 ))
1531 .await
1532 .expect_err("closed session rejects work");
1533 assert_eq!(error.code, ErrorCode::InvalidSessionState);
1534 }
1535
1536 #[derive(Debug, Default)]
1540 struct TextItemModel;
1541
1542 impl ModelProvider for TextItemModel {
1543 async fn complete(
1544 &mut self,
1545 request: ModelRunRequest,
1546 ) -> Result<ModelRunResult, ProviderError> {
1547 let output = format!("echo: {}", request.input);
1548 Ok(ModelRunResult {
1549 final_output: Some(output.clone()),
1550 prepared_request: None,
1551 response: Some(RuntimeResponse {
1552 items: vec![RuntimeItem::Message(MessageItem::text(
1553 RuntimeRole::Assistant,
1554 output,
1555 ))],
1556 finish_reason: Some(FinishReason::Stop),
1557 usage: RuntimeUsage::default(),
1558 provider_state: None,
1559 }),
1560 })
1561 }
1562
1563 async fn cancel(&mut self, _run_id: &RunId) -> Result<bool, ProviderError> {
1564 Ok(false)
1565 }
1566 }
1567
1568 #[derive(Debug, Default)]
1572 struct RecordingObserver(Mutex<Vec<(EventEnvelope, EventVisibility)>>);
1573
1574 impl RecordingObserver {
1575 fn seen(&self) -> Vec<(EventEnvelope, EventVisibility)> {
1576 self.0
1577 .lock()
1578 .expect("observer mutex is not poisoned")
1579 .clone()
1580 }
1581 }
1582
1583 impl SessionEventObserver for RecordingObserver {
1584 fn observe(&self, envelope: &EventEnvelope, visibility: EventVisibility) {
1585 self.0
1586 .lock()
1587 .expect("observer mutex is not poisoned")
1588 .push((envelope.clone(), visibility));
1589 }
1590 }
1591
1592 #[tokio::test]
1593 async fn dispatch_with_the_default_control_matches_handle_exactly() {
1594 let mut plain = SessionManager::new(CoreRuntime::new(EchoModel::default(), NoopRunner));
1598 let created = plain
1599 .handle(command(
1600 "create",
1601 None,
1602 Command::SessionCreate {
1603 workspace_id: WorkspaceId::new("workspace-1"),
1604 },
1605 ))
1606 .await
1607 .expect("session is created");
1608 let session_id = created[0].session_id.clone();
1609 let expected = plain
1610 .handle(command(
1611 "message",
1612 Some(session_id.clone()),
1613 Command::MessageSend {
1614 images: Vec::new(),
1615 content: "hello".to_owned(),
1616 },
1617 ))
1618 .await
1619 .expect("message is handled");
1620
1621 let mut controlled =
1622 SessionManager::new(CoreRuntime::new(EchoModel::default(), NoopRunner));
1623 controlled
1624 .dispatch(
1625 command(
1626 "create",
1627 None,
1628 Command::SessionCreate {
1629 workspace_id: WorkspaceId::new("workspace-1"),
1630 },
1631 ),
1632 DispatchControl::default(),
1633 )
1634 .await
1635 .expect("session is created");
1636 let events = controlled
1637 .dispatch(
1638 command(
1639 "message",
1640 Some(session_id),
1641 Command::MessageSend {
1642 images: Vec::new(),
1643 content: "hello".to_owned(),
1644 },
1645 ),
1646 DispatchControl::default(),
1647 )
1648 .await
1649 .expect("message is handled");
1650
1651 let content = |envelopes: &[EventEnvelope]| {
1657 envelopes
1658 .iter()
1659 .map(|envelope| envelope.event.clone())
1660 .collect::<Vec<_>>()
1661 };
1662 assert_eq!(content(&events), content(&expected));
1663 }
1664
1665 #[tokio::test]
1666 async fn the_observer_sees_every_event_including_internal_ones_in_order() {
1667 let observer: Arc<RecordingObserver> = Arc::default();
1668 let mut manager = SessionManager::new(CoreRuntime::new(TextItemModel, NoopRunner));
1669
1670 let created = manager
1671 .dispatch(
1672 command(
1673 "create",
1674 None,
1675 Command::SessionCreate {
1676 workspace_id: WorkspaceId::new("workspace-1"),
1677 },
1678 ),
1679 DispatchControl {
1680 run: RunControl::default(),
1681 observer: Some(observer.clone()),
1682 },
1683 )
1684 .await
1685 .expect("session is created");
1686 let session_id = created[0].session_id.clone();
1687
1688 let returned = manager
1689 .dispatch(
1690 command(
1691 "message",
1692 Some(session_id),
1693 Command::MessageSend {
1694 images: Vec::new(),
1695 content: "hi".to_owned(),
1696 },
1697 ),
1698 DispatchControl {
1699 run: RunControl::default(),
1700 observer: Some(observer.clone()),
1701 },
1702 )
1703 .await
1704 .expect("message is handled");
1705
1706 let seen = observer.seen();
1707
1708 let sequences: Vec<u64> = seen.iter().map(|(envelope, _)| envelope.sequence).collect();
1710 let mut sorted = sequences.clone();
1711 sorted.sort_unstable();
1712 assert_eq!(
1713 sequences, sorted,
1714 "observed order must match sequence order"
1715 );
1716
1717 assert!(seen.iter().any(|(envelope, visibility)| matches!(
1720 envelope.event,
1721 Event::SessionCreated { .. }
1722 ) && *visibility
1723 == EventVisibility::Client));
1724
1725 assert!(
1728 !returned
1729 .iter()
1730 .any(|envelope| matches!(envelope.event, Event::ModelResponseItem { .. })),
1731 "model.response.item must not be client-visible"
1732 );
1733 assert!(seen.iter().any(|(envelope, visibility)| matches!(
1734 envelope.event,
1735 Event::ModelResponseItem { .. }
1736 ) && *visibility
1737 == EventVisibility::Internal));
1738
1739 for envelope in &returned {
1741 assert!(
1742 seen.iter()
1743 .any(
1744 |(seen_envelope, visibility)| seen_envelope.event_id == envelope.event_id
1745 && *visibility == EventVisibility::Client
1746 ),
1747 "returned event {:?} was not observed as Client-visible",
1748 envelope.event_id
1749 );
1750 }
1751 }
1752
1753 #[derive(Debug, Default)]
1756 struct HangingModel;
1757
1758 impl ModelProvider for HangingModel {
1759 async fn complete(
1760 &mut self,
1761 _request: ModelRunRequest,
1762 ) -> Result<ModelRunResult, ProviderError> {
1763 std::future::pending().await
1764 }
1765
1766 async fn cancel(&mut self, _run_id: &RunId) -> Result<bool, ProviderError> {
1767 Ok(true)
1768 }
1769 }
1770
1771 #[tokio::test]
1772 async fn dispatch_propagates_cancellation_to_a_hanging_run() {
1773 let mut manager = SessionManager::new(CoreRuntime::new(HangingModel, NoopRunner));
1774 let created = manager
1775 .handle(command(
1776 "create",
1777 None,
1778 Command::SessionCreate {
1779 workspace_id: WorkspaceId::new("workspace-1"),
1780 },
1781 ))
1782 .await
1783 .expect("session is created");
1784 let session_id = created[0].session_id.clone();
1785
1786 let cancellation = RunCancellation::new();
1787 let control = DispatchControl {
1788 run: RunControl {
1789 cancellation: Some(cancellation.clone()),
1790 permissions: None,
1791 },
1792 observer: None,
1793 };
1794 let run = manager.dispatch(
1795 command(
1796 "message",
1797 Some(session_id),
1798 Command::MessageSend {
1799 images: Vec::new(),
1800 content: "hang".to_owned(),
1801 },
1802 ),
1803 control,
1804 );
1805 let cancel_after_a_moment = async {
1806 tokio::time::sleep(std::time::Duration::from_millis(20)).await;
1807 cancellation.cancel();
1808 };
1809 let (result, ()) = tokio::time::timeout(std::time::Duration::from_secs(5), async {
1810 tokio::join!(run, cancel_after_a_moment)
1811 })
1812 .await
1813 .expect("dispatch must end once cancelled, not hang");
1814
1815 let events = result.expect("a cancelled run is still a handled Command");
1816 assert!(matches!(
1817 events.last(),
1818 Some(EventEnvelope {
1819 event: Event::RunCancelled,
1820 ..
1821 })
1822 ));
1823 }
1824
1825 #[derive(Debug, Default)]
1828 struct CountingRunner {
1829 executed: Vec<String>,
1830 }
1831
1832 impl RunnerEnvironment for CountingRunner {
1833 async fn execute(
1834 &mut self,
1835 request: ToolExecutionRequest,
1836 ) -> Result<ToolExecutionResult, RunnerError> {
1837 self.executed.push(request.call.call_id.clone());
1838 Ok(ToolExecutionResult {
1839 result: ToolResultItem {
1840 id: None,
1841 call_id: request.call.call_id,
1842 name: Some(request.call.name),
1843 content: vec![ContentBlock::text("done")],
1844 is_error: false,
1845 },
1846 output: vec![RunnerOutput::Stdout("done".to_owned())],
1847 })
1848 }
1849
1850 async fn cancel(&mut self, _run_id: &RunId) -> Result<bool, RunnerError> {
1851 Ok(false)
1852 }
1853 }
1854
1855 #[derive(Debug, Default)]
1856 struct OneToolCallModel {
1857 called: bool,
1858 }
1859
1860 impl ModelProvider for OneToolCallModel {
1861 async fn complete(
1862 &mut self,
1863 _request: ModelRunRequest,
1864 ) -> Result<ModelRunResult, ProviderError> {
1865 if self.called {
1866 return Ok(ModelRunResult {
1867 final_output: Some("done".to_owned()),
1868 prepared_request: None,
1869 response: None,
1870 });
1871 }
1872 self.called = true;
1873 Ok(ModelRunResult {
1874 final_output: None,
1875 prepared_request: None,
1876 response: Some(RuntimeResponse {
1877 items: vec![RuntimeItem::ToolCall(ToolCallItem {
1878 id: None,
1879 call_id: "call-1".to_owned(),
1880 name: "shell".to_owned(),
1881 arguments: serde_json::json!({}),
1882 provider_state: None,
1883 })],
1884 finish_reason: Some(FinishReason::ToolCalls),
1885 usage: RuntimeUsage::default(),
1886 provider_state: None,
1887 }),
1888 })
1889 }
1890
1891 async fn cancel(&mut self, _run_id: &RunId) -> Result<bool, ProviderError> {
1892 Ok(false)
1893 }
1894 }
1895
1896 #[tokio::test]
1897 async fn dispatch_propagates_the_permission_gate_and_denies_the_call() {
1898 let mut manager = SessionManager::new(CoreRuntime::new(
1899 OneToolCallModel::default(),
1900 CountingRunner::default(),
1901 ));
1902 let created = manager
1903 .handle(command(
1904 "create",
1905 None,
1906 Command::SessionCreate {
1907 workspace_id: WorkspaceId::new("workspace-1"),
1908 },
1909 ))
1910 .await
1911 .expect("session is created");
1912 let session_id = created[0].session_id.clone();
1913
1914 let mut by_tool = std::collections::BTreeMap::new();
1915 by_tool.insert("shell".to_owned(), ToolPermissionRule::Deny);
1916 let control = DispatchControl {
1917 run: RunControl {
1918 cancellation: None,
1919 permissions: Some(ToolPermissionGate {
1920 policy: ToolPermissionPolicy {
1921 default: ToolPermissionRule::Allow,
1922 by_tool,
1923 argument_rules: Vec::new(),
1924 },
1925 approver: None,
1926 }),
1927 },
1928 observer: None,
1929 };
1930 let events = manager
1931 .dispatch(
1932 command(
1933 "message",
1934 Some(session_id),
1935 Command::MessageSend {
1936 images: Vec::new(),
1937 content: "run shell".to_owned(),
1938 },
1939 ),
1940 control,
1941 )
1942 .await
1943 .expect("the run is handled");
1944
1945 assert!(
1946 events.iter().any(|envelope| matches!(
1947 &envelope.event,
1948 Event::ToolCallPermissionResolved {
1949 outcome: arabica_protocol::ToolPermissionOutcome::Denied,
1950 ..
1951 }
1952 )),
1953 "the gate's denial must reach dispatch's own return value: {events:?}"
1954 );
1955 assert!(
1956 manager.runtime().runner().executed.is_empty(),
1957 "a denied call must never reach the runner"
1958 );
1959 }
1960
1961 #[test]
1962 fn a_custom_id_allocator_actually_changes_the_produced_identifiers() {
1963 #[derive(Debug, Default)]
1964 struct FixedIds(u64);
1965 impl IdAllocator for FixedIds {
1966 fn session_id(&mut self) -> SessionId {
1967 self.0 += 1;
1968 SessionId::new(format!("s-{}", self.0))
1969 }
1970 fn run_id(&mut self) -> RunId {
1971 self.0 += 1;
1972 RunId::new(format!("r-{}", self.0))
1973 }
1974 }
1975 let mut manager = SessionManager::with_ids(
1976 CoreRuntime::new(EchoModel::default(), NoopRunner),
1977 Box::new(FixedIds::default()),
1978 );
1979 let session_id = manager.allocate_session_id();
1980 let run_id = manager.allocate_run_id();
1981 assert_eq!(session_id, SessionId::new("s-1"));
1982 assert_eq!(run_id, RunId::new("r-2"));
1983 }
1984
1985 #[test]
1986 fn sequential_ids_observing_a_used_id_advances_past_it() {
1987 let mut ids = SequentialIds::default();
1988 ids.observe_used_session_id(&SessionId::new("session-7"));
1989 ids.observe_used_run_id(&RunId::new("run-3"));
1990 assert_eq!(ids.session_id(), SessionId::new("session-8"));
1991 assert_eq!(ids.run_id(), RunId::new("run-4"));
1992 }
1993
1994 #[test]
1995 fn sequential_ids_observing_a_lower_id_than_already_issued_does_not_rewind() {
1996 let mut ids = SequentialIds::default();
1997 assert_eq!(ids.session_id(), SessionId::new("session-1"));
1998 assert_eq!(ids.session_id(), SessionId::new("session-2"));
1999 ids.observe_used_session_id(&SessionId::new("session-1"));
2003 assert_eq!(ids.session_id(), SessionId::new("session-3"));
2004 }
2005
2006 #[test]
2007 fn sequential_ids_ignores_an_id_it_would_never_have_produced_itself() {
2008 let mut ids = SequentialIds::default();
2009 ids.observe_used_run_id(&RunId::new("01a0c7ea-4f84-73fb-a00d-26087771166a"));
2010 ids.observe_used_run_id(&RunId::new("not-even-close"));
2011 assert_eq!(
2012 ids.run_id(),
2013 RunId::new("run-1"),
2014 "a foreign id shape must not perturb this allocator's own counter"
2015 );
2016 }
2017
2018 mod restore_session_tests {
2019 use super::*;
2020
2021 fn snap_event(sequence: u64, run_id: Option<&str>, event: Event) -> EventEnvelope {
2022 EventEnvelope {
2023 protocol_version: PROTOCOL_VERSION.to_owned(),
2024 event_id: EventId::new(format!("event-{sequence}")),
2025 command_id: CommandId::new("original-command"),
2026 workspace_id: WorkspaceId::new("ws-1"),
2027 session_id: SessionId::new("restored-session"),
2028 run_id: run_id.map(RunId::new),
2029 sequence,
2030 occurred_at_ms: 0,
2031 event,
2032 }
2033 }
2034
2035 fn manager() -> SessionManager<CoreRuntime<EchoModel, NoopRunner>> {
2036 SessionManager::new(CoreRuntime::new(EchoModel::default(), NoopRunner))
2037 }
2038
2039 fn healthy_history() -> Vec<EventEnvelope> {
2042 vec![
2043 snap_event(
2044 1,
2045 None,
2046 Event::SessionCreated {
2047 workspace_id: WorkspaceId::new("ws-1"),
2048 },
2049 ),
2050 snap_event(2, Some("run-1"), Event::RunScheduled),
2051 snap_event(3, Some("run-1"), Event::RunStarted),
2052 snap_event(
2053 4,
2054 Some("run-1"),
2055 Event::ToolCallRequested {
2056 call_id: "call-1".to_owned(),
2057 name: "read_file".to_owned(),
2058 arguments: serde_json::json!({"path": "a.txt"}),
2059 provider_state: None,
2060 },
2061 ),
2062 snap_event(
2063 5,
2064 Some("run-1"),
2065 Event::ToolCallCompleted {
2066 call_id: "call-1".to_owned(),
2067 name: "read_file".to_owned(),
2068 result: "contents".to_owned(),
2069 is_error: false,
2070 },
2071 ),
2072 snap_event(
2073 6,
2074 Some("run-1"),
2075 Event::RunCompleted {
2076 output: Some("done".to_owned()),
2077 },
2078 ),
2079 ]
2080 }
2081
2082 #[test]
2083 fn restores_a_healthy_session_exactly() {
2084 let mut sessions = manager();
2085 let report = sessions
2086 .restore_session(
2087 SessionSnapshot {
2088 events: healthy_history(),
2089 },
2090 CommandId::new("restore-1"),
2091 None,
2092 )
2093 .expect("a well-formed snapshot restores");
2094
2095 assert_eq!(report.session_id, SessionId::new("restored-session"));
2096 assert_eq!(report.restored_event_count, 6);
2097 assert!(report.repaired_events.is_empty());
2098 assert!(report.interrupted_runs.is_empty());
2099
2100 let session = sessions
2101 .session(&SessionId::new("restored-session"))
2102 .expect("session is restored");
2103 assert_eq!(session.status, SessionStatus::Active);
2104 assert_eq!(session.next_sequence, 6);
2105 assert_eq!(
2106 session.runs.get(&RunId::new("run-1")),
2107 Some(&RunStatus::Finished)
2108 );
2109 }
2110
2111 #[test]
2112 fn rejects_an_empty_snapshot() {
2113 let mut sessions = manager();
2114 let error = sessions
2115 .restore_session(
2116 SessionSnapshot { events: vec![] },
2117 CommandId::new("restore-1"),
2118 None,
2119 )
2120 .expect_err("an empty snapshot cannot be restored");
2121 assert_eq!(error.code, ErrorCode::InvalidSnapshot);
2122 }
2123
2124 #[test]
2125 fn rejects_a_non_contiguous_sequence() {
2126 let mut events = healthy_history();
2127 events.remove(2); let mut sessions = manager();
2129 let error = sessions
2130 .restore_session(
2131 SessionSnapshot { events },
2132 CommandId::new("restore-1"),
2133 None,
2134 )
2135 .expect_err("a gap in the sequence cannot be restored");
2136 assert_eq!(error.code, ErrorCode::InvalidSnapshot);
2137 }
2138
2139 #[test]
2140 fn rejects_a_forked_session() {
2141 let events = vec![snap_event(
2142 1,
2143 None,
2144 Event::SessionForked {
2145 source_session_id: SessionId::new("parent"),
2146 },
2147 )];
2148 let mut sessions = manager();
2149 let error = sessions
2150 .restore_session(
2151 SessionSnapshot { events },
2152 CommandId::new("restore-1"),
2153 None,
2154 )
2155 .expect_err("phase 2 does not restore a forked session");
2156 assert_eq!(error.code, ErrorCode::InvalidSnapshot);
2157 }
2158
2159 #[test]
2160 fn rejects_restoring_over_an_already_open_session_id() {
2161 let mut sessions = manager();
2162 sessions
2163 .restore_session(
2164 SessionSnapshot {
2165 events: healthy_history(),
2166 },
2167 CommandId::new("restore-1"),
2168 None,
2169 )
2170 .expect("first restore succeeds");
2171 let error = sessions
2172 .restore_session(
2173 SessionSnapshot {
2174 events: healthy_history(),
2175 },
2176 CommandId::new("restore-2"),
2177 None,
2178 )
2179 .expect_err("a second restore of the same session id must not clobber the first");
2180 assert_eq!(error.code, ErrorCode::InvalidSessionState);
2181 }
2182
2183 #[test]
2184 fn derives_status_from_the_last_lifecycle_event() {
2185 let mut events = healthy_history();
2186 events.push(snap_event(7, None, Event::SessionSuspended));
2187 let mut sessions = manager();
2188 sessions
2189 .restore_session(
2190 SessionSnapshot { events },
2191 CommandId::new("restore-1"),
2192 None,
2193 )
2194 .expect("restores");
2195 assert_eq!(
2196 sessions
2197 .session(&SessionId::new("restored-session"))
2198 .unwrap()
2199 .status,
2200 SessionStatus::Suspended
2201 );
2202 }
2203
2204 #[test]
2205 fn repairs_an_interrupted_run_before_marking_it_failed() {
2206 let events = vec![
2211 snap_event(
2212 1,
2213 None,
2214 Event::SessionCreated {
2215 workspace_id: WorkspaceId::new("ws-1"),
2216 },
2217 ),
2218 snap_event(2, Some("run-1"), Event::RunScheduled),
2219 snap_event(3, Some("run-1"), Event::RunStarted),
2220 snap_event(
2221 4,
2222 Some("run-1"),
2223 Event::ToolCallRequested {
2224 call_id: "call-1".to_owned(),
2225 name: "shell".to_owned(),
2226 arguments: serde_json::json!({"command": "sleep 100"}),
2227 provider_state: None,
2228 },
2229 ),
2230 ];
2231 let mut sessions = manager();
2232 let report = sessions
2233 .restore_session(
2234 SessionSnapshot { events },
2235 CommandId::new("restore-1"),
2236 None,
2237 )
2238 .expect("an interrupted run still restores, repaired");
2239
2240 assert_eq!(report.interrupted_runs, vec![RunId::new("run-1")]);
2241 assert_eq!(
2242 report.repaired_events.len(),
2243 2,
2244 "one synthetic completed, one run.failed"
2245 );
2246 assert!(matches!(
2247 report.repaired_events[0].event,
2248 Event::ToolCallCompleted { is_error: true, .. }
2249 ));
2250 assert!(matches!(
2251 report.repaired_events[1].event,
2252 Event::RunFailed { .. }
2253 ));
2254
2255 let session = sessions
2256 .session(&SessionId::new("restored-session"))
2257 .unwrap();
2258 assert_eq!(
2259 session.runs.get(&RunId::new("run-1")),
2260 Some(&RunStatus::Failed)
2261 );
2262 assert_eq!(session.events.len(), 6);
2266 assert_eq!(session.events[4].sequence, 5);
2267 assert_eq!(session.events[5].sequence, 6);
2268 assert_eq!(session.next_sequence, 6);
2269 }
2270
2271 #[test]
2272 fn a_completed_tool_call_in_an_interrupted_run_is_not_repaired_again() {
2273 let events = vec![
2278 snap_event(
2279 1,
2280 None,
2281 Event::SessionCreated {
2282 workspace_id: WorkspaceId::new("ws-1"),
2283 },
2284 ),
2285 snap_event(2, Some("run-1"), Event::RunScheduled),
2286 snap_event(3, Some("run-1"), Event::RunStarted),
2287 snap_event(
2288 4,
2289 Some("run-1"),
2290 Event::ToolCallRequested {
2291 call_id: "call-1".to_owned(),
2292 name: "read_file".to_owned(),
2293 arguments: serde_json::json!({"path": "a.txt"}),
2294 provider_state: None,
2295 },
2296 ),
2297 snap_event(
2298 5,
2299 Some("run-1"),
2300 Event::ToolCallCompleted {
2301 call_id: "call-1".to_owned(),
2302 name: "read_file".to_owned(),
2303 result: "contents".to_owned(),
2304 is_error: false,
2305 },
2306 ),
2307 ];
2308 let mut sessions = manager();
2309 let report = sessions
2310 .restore_session(
2311 SessionSnapshot { events },
2312 CommandId::new("restore-1"),
2313 None,
2314 )
2315 .expect("restores");
2316 assert_eq!(
2317 report.repaired_events.len(),
2318 1,
2319 "only run.failed, no synthetic completed for the call that already has a real one"
2320 );
2321 assert!(matches!(
2322 report.repaired_events[0].event,
2323 Event::RunFailed { .. }
2324 ));
2325 }
2326
2327 #[test]
2328 fn restoring_advances_a_sequential_allocator_past_the_restored_run() {
2329 let mut sessions = SessionManager::with_ids(
2330 CoreRuntime::new(EchoModel::default(), NoopRunner),
2331 Box::new(SequentialIds::default()),
2332 );
2333 sessions
2334 .restore_session(
2335 SessionSnapshot {
2336 events: healthy_history(),
2337 },
2338 CommandId::new("restore-1"),
2339 None,
2340 )
2341 .expect("restores");
2342 assert_eq!(sessions.allocate_run_id(), RunId::new("run-2"));
2346 }
2347
2348 #[test]
2349 fn an_attached_observer_sees_the_repair_events() {
2350 #[derive(Default)]
2351 struct Recording(Mutex<Vec<Event>>);
2352 impl SessionEventObserver for Recording {
2353 fn observe(&self, envelope: &EventEnvelope, _visibility: EventVisibility) {
2354 self.0.lock().unwrap().push(envelope.event.clone());
2355 }
2356 }
2357 let events = vec![
2358 snap_event(
2359 1,
2360 None,
2361 Event::SessionCreated {
2362 workspace_id: WorkspaceId::new("ws-1"),
2363 },
2364 ),
2365 snap_event(2, Some("run-1"), Event::RunScheduled),
2366 ];
2367 let recorder = Recording::default();
2368 let mut sessions = manager();
2369 sessions
2370 .restore_session(
2371 SessionSnapshot { events },
2372 CommandId::new("restore-1"),
2373 Some(&recorder),
2374 )
2375 .expect("restores");
2376 let recorded = recorder.0.lock().unwrap();
2377 assert!(
2378 recorded
2379 .iter()
2380 .any(|event| matches!(event, Event::RunFailed { .. })),
2381 "the observer must see the repair run.failed Event, not just the report"
2382 );
2383 }
2384 }
2385}