Skip to main content

arabica_session/
lib.rs

1//! Session lifecycle and scheduling.
2//!
3//! This module owns session/run identity, lifecycle state, dispatch, and
4//! monotonically ordered event envelopes. Runtime execution remains behind
5//! [`RuntimeEngine`].
6
7mod 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/// Whether an Event reached the client-visible subset `dispatch` and `handle`
27/// return, or was internal evidence such as a `model.response.item`.
28///
29/// This is [`Event::is_client_visible`] reified as data, so an observer that
30/// wants only what a client sees does not have to duplicate that rule.
31/// `Serialize`/`Deserialize` (`"client"`/`"internal"`) so a persistent
32/// observer (`arabica-adapters`' file session store) can record it
33/// alongside the Event it was computed for.
34#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
35#[serde(rename_all = "snake_case")]
36pub enum EventVisibility {
37    Client,
38    Internal,
39}
40
41/// Receives every canonical Event as it is appended, in sequence order,
42/// including internal ones. This is how a host streams progress: `dispatch`
43/// itself returns only after the whole Command finishes, and internal Events
44/// such as `model.response.item` never appear in that return value at all.
45///
46/// `observe` is called synchronously, inline with the append that produced
47/// the Event, from inside the `.await`ed call that is doing the work. An
48/// implementation must not block: hand the envelope to a channel or a `Vec`
49/// behind a mutex rather than doing I/O here.
50pub trait SessionEventObserver: Send + Sync {
51    fn observe(&self, envelope: &EventEnvelope, visibility: EventVisibility);
52}
53
54/// Forwards every Event to each observer in turn, in the order given, so a
55/// host can attach more than one -- a persistent store (`arabica-adapters`'
56/// `FileSessionStore`) alongside a live-progress observer, say -- to one
57/// `dispatch` call. [`DispatchControl`] only carries one
58/// `Arc<dyn SessionEventObserver>`; this is how a host composes several into
59/// that one slot instead of `arabica-session` growing a second observer
60/// field for every combination a host might want.
61pub 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/// Everything a host may attach to one call to [`SessionManager::dispatch`].
78///
79/// The default attaches nothing: no cancellation or permission gate reaches
80/// Runtime, and no observer is notified. A Command dispatched with the
81/// default emits exactly the Events it emitted before this type existed;
82/// [`SessionManager::handle`] uses the default so its behavior is unchanged.
83#[derive(Clone, Default)]
84pub struct DispatchControl {
85    pub run: RunControl,
86    pub observer: Option<Arc<dyn SessionEventObserver>>,
87}
88
89/// Allocates Session and Run identifiers.
90///
91/// The default, [`SequentialIds`], reproduces the `session-N` / `run-N`
92/// format every existing caller and recorded benchmark campaign depends on.
93/// A host that runs one `SessionManager` per external session (for example
94/// one per ACP connection) needs identifiers unique across managers, not just
95/// within one, and supplies its own allocator (a UUIDv7 generator, typically)
96/// through [`SessionManager::with_ids`].
97pub trait IdAllocator: Send + std::fmt::Debug {
98    fn session_id(&mut self) -> SessionId;
99    fn run_id(&mut self) -> RunId;
100
101    /// Tells the allocator that `session_id` is already in use, by a session
102    /// [`SessionManager::restore_session`] just reconstructed, so a later
103    /// [`Self::session_id`] call must never produce it. The default is a
104    /// no-op, which suits an allocator (a UUIDv7 generator, say) whose
105    /// collision probability is already negligible regardless of prior
106    /// history; a counter-based allocator overrides it to advance past the
107    /// observed id.
108    fn observe_used_session_id(&mut self, session_id: &SessionId) {
109        let _ = session_id;
110    }
111
112    /// The [`Self::run_id`] counterpart of [`Self::observe_used_session_id`].
113    /// A restored session's history can contain many run ids (one per past
114    /// turn), so this is called once per id found, not once per restore.
115    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
126/// Parses the `N` out of a `SequentialIds`-shaped id (`"session-N"` or
127/// `"run-N"`); anything else (a UUID, say) parses to `None` and is silently
128/// ignored, since `observe_used_*`'s only job is to keep this specific
129/// counter-based scheme from reissuing an id already seen, not to make sense
130/// of ids some other allocator minted.
131fn 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    /// Immutable history inherited at the fork boundary. It is input to the
167    /// short-memory projection but does not consume this Session's sequence.
168    base_events: Vec<EventEnvelope>,
169    /// Local append-only event log. This is the source of truth for short
170    /// memory; Runtime never owns a second conversation store.
171    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    /// Append one canonical Event and, if a host attached one, notify the
187    /// observer. This is the single place envelopes are constructed, so both
188    /// runtime-driven Events (through `SessionRuntimeEventLog`) and
189    /// session-lifecycle Events (through `SessionManager::append_events`)
190    /// reach the same observer through the same path.
191    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    /// Construct with a caller-supplied [`IdAllocator`], for a host that runs
308    /// one `SessionManager` per external session and needs identifiers
309    /// unique across managers, not just within one.
310    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    /// Handle one Command with no host control attached: no cancellation or
395    /// permission gate reaches Runtime, and nothing observes Events as they
396    /// occur. Delegates to [`Self::dispatch`] with the default
397    /// [`DispatchControl`], so its behavior is exactly what it was before
398    /// `dispatch` existed.
399    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    /// Handle one Command with host-supplied control for the run it starts
407    /// and an observer notified of every Event as it is appended, including
408    /// internal ones. Still returns only the client-visible subset, exactly
409    /// like [`Self::handle`]; the observer is the channel for everything
410    /// else.
411    ///
412    /// A retried `command_id` (see the idempotency rule below) is replayed
413    /// from the cached result without re-invoking Runtime, so the observer is
414    /// not notified a second time for it: nothing new was appended.
415    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    /// Reconstructs a [`SessionRecord`] from a session's replayed Event
733    /// history and re-establishes the Runtime-side state
734    /// [`RuntimeEngine::restore_session`] owns.
735    ///
736    /// Rejects a snapshot whose Events do not form a session this can
737    /// reconstruct: empty, non-contiguous, or forked (Phase 2 does not
738    /// restore a session with a parent -- its `base_events` would need the
739    /// parent's own history too, which this snapshot alone does not carry).
740    /// Also rejects restoring over a session id that is already open,
741    /// matching `Command::SessionCreate`'s own collision behavior.
742    ///
743    /// A run left without a terminal Event (the process ended mid-run) is
744    /// repaired before this returns: every dangling tool call -- requested
745    /// but never completed -- gets a synthetic `tool.call.completed` with an
746    /// error first, then the run itself gets `run.failed`. Both are
747    /// appended under `restore_command_id` through the same
748    /// observer-notifying path as any live Event, so a reattached
749    /// persistent store sees exactly what happened: the run did not
750    /// finish, here is why.
751    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
894/// A session's replayed Event history, ready for
895/// [`SessionManager::restore_session`]. Typically read back from a
896/// `arabica-adapters` `FileSessionStore` file, but this type carries no
897/// file-format knowledge itself -- restoring only needs the Events in
898/// order, from wherever a caller got them.
899pub struct SessionSnapshot {
900    pub events: Vec<EventEnvelope>,
901}
902
903/// What `restore_session` actually did, for a caller that wants to log or
904/// display it (a CLI's `--resume` telling the user "recovered N Events,
905/// repaired an interrupted run", say) rather than re-deriving it from the
906/// session afterward.
907#[derive(Debug)]
908pub struct RestoreReport {
909    pub session_id: SessionId,
910    pub restored_event_count: usize,
911    /// The synthetic Events `restore_session` itself appended to repair an
912    /// interrupted run (dangling `tool.call.completed`s, then
913    /// `run.failed`), in the order they were appended. Empty when nothing
914    /// needed repair.
915    pub repaired_events: Vec<EventEnvelope>,
916    /// Which runs, if any, had no terminal Event in the snapshot and were
917    /// therefore repaired and marked `RunStatus::Failed`.
918    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        // Unreachable in practice: `restore_session` already rejects a
950        // snapshot whose first Event is not `session.created`, so at least
951        // one lifecycle Event always exists. Active is the safe fallback
952        // regardless, since anything else would refuse an operation the
953        // Runtime state might actually support.
954        .unwrap_or(SessionStatus::Active)
955}
956
957/// Every run named by a `run_id` in `events`, with the status its own
958/// terminal Event implies -- or, for a run with none (the process ended
959/// before it finished), `RunStatus::Failed`, since `restore_session`
960/// repairs every such run into that state before returning. Also returns
961/// which run ids those were, so the repair step knows which ones to act on.
962fn 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
985/// `(call_id, name)` for every `tool.call.requested` in `run_events` that
986/// has no matching `tool.call.completed`, in request order.
987fn 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    /// A model that emits a real `model.response.item` (an internal Event)
1537    /// in addition to `final_output`, so a run through it produces at least
1538    /// one internal Event alongside its client-visible ones.
1539    #[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    /// Records every envelope and its visibility, in the order `observe` is
1569    /// called. `observe` takes `&self`, so a std `Mutex` provides the
1570    /// interior mutability; no `.await` is ever held across the lock.
1571    #[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        // The default DispatchControl must be behaviorally invisible: this is
1595        // what lets `handle()` delegate to `dispatch()` without changing what
1596        // every existing caller and recorded benchmark campaign observes.
1597        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        // occurred_at_ms is wall-clock and explicitly informational (see
1652        // docs/protocol.md: consumers order by sequence, never by it), so two
1653        // separately timed runs may legitimately differ there by a
1654        // millisecond. The claim under test is that dispatch with the
1655        // default control changes none of the canonical content.
1656        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        // Sequence order is preserved end to end.
1709        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        // session.created is a lifecycle Event appended through append_events,
1718        // not through SessionRuntimeEventLog; the observer must see it too.
1719        assert!(seen.iter().any(|(envelope, visibility)| matches!(
1720            envelope.event,
1721            Event::SessionCreated { .. }
1722        ) && *visibility
1723            == EventVisibility::Client));
1724
1725        // model.response.item is internal: never in dispatch's own return
1726        // value, but the observer must see it, and label it Internal.
1727        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        // Every Event dispatch returned was also observed, labeled Client.
1740        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    /// Hangs until cancelled, so a run through it only ends if cancellation
1754    /// actually reaches Runtime through `dispatch`.
1755    #[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    /// Denies every call, so a permission gate threaded through `dispatch`
1826    /// must be what stops the tool from ever reaching this runner.
1827    #[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        // A restore observing an older, smaller id than the allocator has
2000        // already handed out live must not walk the counter backwards and
2001        // risk a future collision with an id already issued this run.
2002        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        /// A well-formed, fully-terminated one-run history: created, one
2040        /// completed run with a read tool call, nothing left dangling.
2041        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); // drop sequence 3, leaving a 2 -> 4 gap
2128            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            // The process ended mid-run: a tool call was requested but never
2207            // completed, and there is no run.completed/failed/cancelled at
2208            // all -- exactly what a crash mid-`shell` call would leave
2209            // behind in the file.
2210            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            // The repair Events must actually be part of the session's own
2263            // log, not just the report, with sequence numbers continuing
2264            // from where the snapshot left off (4), not restarting.
2265            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            // The run itself never got a terminal Event, but this specific
2274            // call did finish before the crash -- only the run needs a
2275            // run.failed, the call must not get a second, contradictory
2276            // "completed" synthesized on top of its real one.
2277            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            // The snapshot's own run was "run-1"; a fresh SequentialIds
2343            // would hand that id out again next, colliding with the
2344            // restored run's own history.
2345            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}