meerkat_runtime/
service_ext.rs

1//! SessionServiceRuntimeExt — v9 runtime extension for SessionService.
2//!
3//! This trait extends the existing SessionService with runtime-specific
4//! operations. It lives in meerkat-runtime (NOT in core) to maintain
5//! the separation: core owns SessionService, runtime owns runtime extensions.
6
7use meerkat_core::lifecycle::InputId;
8use meerkat_core::types::SessionId;
9
10use crate::accept::AcceptOutcome;
11use crate::completion::CompletionHandle;
12use crate::input::Input;
13use crate::input_state::StoredInputState;
14use crate::meerkat_machine_types::{
15    ImageOperationRoutingRequest, ImageOperationRoutingResult, SessionLlmReconfigureReport,
16    SessionLlmReconfigureRequest, SwitchTurnRequest,
17};
18use crate::runtime_state::RuntimeState;
19use crate::traits::{ResetReport, RetireReport, RuntimeDriverError};
20
21/// Runtime mode for a session service instance.
22///
23/// This branch is runtime-backed only. All sessions use v9 runtime.
24#[derive(Debug, Clone, Copy, PartialEq, Eq)]
25pub enum RuntimeMode {
26    /// Full v9 runtime-backed mode.
27    V9Compliant,
28}
29
30/// v9 runtime extensions for SessionService.
31///
32/// Surfaces query this to decide whether to expose v9 runtime methods.
33/// Legacy-mode surfaces MUST NOT advertise v9 capabilities.
34#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
35#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
36pub trait SessionServiceRuntimeExt: Send + Sync {
37    /// Get the runtime mode.
38    fn runtime_mode(&self) -> RuntimeMode;
39
40    /// Accept an input for a session.
41    async fn accept_input(
42        &self,
43        session_id: &SessionId,
44        input: Input,
45    ) -> Result<AcceptOutcome, RuntimeDriverError>;
46
47    /// Accept an input and optionally return a completion handle that resolves
48    /// when the admitted work reaches a terminal runtime outcome.
49    async fn accept_input_with_completion(
50        &self,
51        session_id: &SessionId,
52        input: Input,
53    ) -> Result<(AcceptOutcome, Option<CompletionHandle>), RuntimeDriverError>;
54
55    /// Get the runtime state for a session.
56    async fn runtime_state(
57        &self,
58        session_id: &SessionId,
59    ) -> Result<RuntimeState, RuntimeDriverError>;
60
61    /// Get the runtime-owned resolved LLM capability surface for a session.
62    async fn resolved_session_llm_capabilities(
63        &self,
64        _session_id: &SessionId,
65    ) -> Result<Option<crate::meerkat_machine_types::SessionLlmCapabilitySurface>, RuntimeDriverError>
66    {
67        Err(RuntimeDriverError::Internal(
68            "resolved session llm capabilities are not implemented by this runtime adapter".into(),
69        ))
70    }
71
72    /// Retire a session's runtime.
73    async fn retire_runtime(
74        &self,
75        session_id: &SessionId,
76    ) -> Result<RetireReport, RuntimeDriverError>;
77
78    /// Reset a session's runtime.
79    async fn reset_runtime(
80        &self,
81        session_id: &SessionId,
82    ) -> Result<ResetReport, RuntimeDriverError>;
83
84    /// Get the state of a specific input, bundled with its DSL-owned seed
85    /// (phase / run association / boundary sequence).
86    async fn input_state(
87        &self,
88        session_id: &SessionId,
89        input_id: &InputId,
90    ) -> Result<Option<StoredInputState>, RuntimeDriverError>;
91
92    /// List all active (non-terminal) inputs for a session.
93    async fn list_active_inputs(
94        &self,
95        session_id: &SessionId,
96    ) -> Result<Vec<InputId>, RuntimeDriverError>;
97
98    /// Canonically reconfigure the LLM identity for a registered live session.
99    async fn reconfigure_session_llm_identity(
100        &self,
101        session_id: &SessionId,
102        request: SessionLlmReconfigureRequest,
103    ) -> Result<SessionLlmReconfigureReport, RuntimeDriverError>;
104
105    async fn configure_model_routing_baseline(
106        &self,
107        _session_id: &SessionId,
108        _baseline_model: meerkat_core::lifecycle::run_primitive::ModelId,
109        _realtime_capable: bool,
110    ) -> Result<(), RuntimeDriverError> {
111        Err(RuntimeDriverError::Internal(
112            "model routing baseline is not supported by this runtime adapter".into(),
113        ))
114    }
115
116    async fn session_model_routing_status(
117        &self,
118        _session_id: &SessionId,
119    ) -> Result<meerkat_core::image_generation::SessionModelRoutingStatus, RuntimeDriverError> {
120        Err(RuntimeDriverError::Internal(
121            "model routing status is not supported by this runtime adapter".into(),
122        ))
123    }
124
125    async fn request_switch_turn(
126        &self,
127        _session_id: &SessionId,
128        _request: SwitchTurnRequest,
129    ) -> Result<meerkat_core::image_generation::SwitchTurnControlResult, RuntimeDriverError> {
130        Err(RuntimeDriverError::Internal(
131            "switch_turn is not supported by this runtime adapter".into(),
132        ))
133    }
134
135    async fn admit_model_routing_assistant_turn(
136        &self,
137        _session_id: &SessionId,
138    ) -> Result<(), RuntimeDriverError> {
139        Err(RuntimeDriverError::Internal(
140            "model routing turn admission is not supported by this runtime adapter".into(),
141        ))
142    }
143
144    async fn begin_image_operation(
145        &self,
146        _session_id: &SessionId,
147        _request: ImageOperationRoutingRequest,
148    ) -> Result<ImageOperationRoutingResult, RuntimeDriverError> {
149        Err(RuntimeDriverError::Internal(
150            "image operation routing is not supported by this runtime adapter".into(),
151        ))
152    }
153
154    async fn activate_image_operation_override(
155        &self,
156        _session_id: &SessionId,
157        _operation_id: meerkat_core::image_generation::ImageOperationId,
158    ) -> Result<meerkat_core::image_generation::ImageOperationPhase, RuntimeDriverError> {
159        Err(RuntimeDriverError::Internal(
160            "image operation activation is not supported by this runtime adapter".into(),
161        ))
162    }
163
164    async fn complete_image_operation(
165        &self,
166        _session_id: &SessionId,
167        _operation_id: meerkat_core::image_generation::ImageOperationId,
168        _terminal: meerkat_core::image_generation::ImageOperationTerminalClass,
169    ) -> Result<meerkat_core::image_generation::ImageOperationPhase, RuntimeDriverError> {
170        Err(RuntimeDriverError::Internal(
171            "image operation completion is not supported by this runtime adapter".into(),
172        ))
173    }
174
175    async fn restore_image_operation_override(
176        &self,
177        _session_id: &SessionId,
178        _operation_id: meerkat_core::image_generation::ImageOperationId,
179    ) -> Result<meerkat_core::image_generation::ImageOperationPhase, RuntimeDriverError> {
180        Err(RuntimeDriverError::Internal(
181            "image operation restore is not supported by this runtime adapter".into(),
182        ))
183    }
184}
185
186#[cfg(test)]
187mod tests {
188    use super::*;
189
190    // Verify trait is object-safe
191    fn _assert_object_safe(_: &dyn SessionServiceRuntimeExt) {}
192
193    #[test]
194    fn runtime_mode_equality() {
195        assert_eq!(RuntimeMode::V9Compliant, RuntimeMode::V9Compliant);
196    }
197}
meerkat_runtime/service_ext.rs

meerkat_runtime/
service_ext.rs
