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/// v9 runtime extensions for SessionService.
22///
23/// This branch is runtime-backed only: every implementation is a v9
24/// runtime surface, so the methods below are unconditionally available.
25#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
26#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
27pub trait SessionServiceRuntimeExt: Send + Sync {
28    /// Accept an input for a session.
29    async fn accept_input(
30        &self,
31        session_id: &SessionId,
32        input: Input,
33    ) -> Result<AcceptOutcome, RuntimeDriverError>;
34
35    /// Accept an input and optionally return a completion handle that resolves
36    /// when the admitted work reaches a terminal runtime outcome.
37    async fn accept_input_with_completion(
38        &self,
39        session_id: &SessionId,
40        input: Input,
41    ) -> Result<(AcceptOutcome, Option<CompletionHandle>), RuntimeDriverError>;
42
43    /// Get the runtime state for a session.
44    async fn runtime_state(
45        &self,
46        session_id: &SessionId,
47    ) -> Result<RuntimeState, RuntimeDriverError>;
48
49    /// Get the runtime-owned resolved LLM capability surface for a session.
50    async fn resolved_session_llm_capabilities(
51        &self,
52        _session_id: &SessionId,
53    ) -> Result<Option<crate::meerkat_machine_types::SessionLlmCapabilitySurface>, RuntimeDriverError>
54    {
55        Err(RuntimeDriverError::Internal(
56            "resolved session llm capabilities are not implemented by this runtime adapter".into(),
57        ))
58    }
59
60    /// Retire a session's runtime.
61    async fn retire_runtime(
62        &self,
63        session_id: &SessionId,
64    ) -> Result<RetireReport, RuntimeDriverError>;
65
66    /// Reset a session's runtime.
67    async fn reset_runtime(
68        &self,
69        session_id: &SessionId,
70    ) -> Result<ResetReport, RuntimeDriverError>;
71
72    /// Get the state of a specific input, bundled with its DSL-owned seed
73    /// (phase / run association / boundary sequence).
74    async fn input_state(
75        &self,
76        session_id: &SessionId,
77        input_id: &InputId,
78    ) -> Result<Option<StoredInputState>, RuntimeDriverError>;
79
80    /// List all active (non-terminal) inputs for a session.
81    async fn list_active_inputs(
82        &self,
83        session_id: &SessionId,
84    ) -> Result<Vec<InputId>, RuntimeDriverError>;
85
86    /// Canonically reconfigure the LLM identity for a registered live session.
87    async fn reconfigure_session_llm_identity(
88        &self,
89        session_id: &SessionId,
90        request: SessionLlmReconfigureRequest,
91    ) -> Result<SessionLlmReconfigureReport, RuntimeDriverError>;
92
93    async fn configure_model_routing_baseline(
94        &self,
95        _session_id: &SessionId,
96        _baseline_model: meerkat_core::lifecycle::run_primitive::ModelId,
97        _realtime_capable: bool,
98    ) -> Result<(), RuntimeDriverError> {
99        Err(RuntimeDriverError::Internal(
100            "model routing baseline is not supported by this runtime adapter".into(),
101        ))
102    }
103
104    async fn session_model_routing_status(
105        &self,
106        _session_id: &SessionId,
107    ) -> Result<meerkat_core::image_generation::SessionModelRoutingStatus, RuntimeDriverError> {
108        Err(RuntimeDriverError::Internal(
109            "model routing status is not supported by this runtime adapter".into(),
110        ))
111    }
112
113    async fn request_switch_turn(
114        &self,
115        _session_id: &SessionId,
116        _request: SwitchTurnRequest,
117    ) -> Result<meerkat_core::image_generation::SwitchTurnControlResult, RuntimeDriverError> {
118        Err(RuntimeDriverError::Internal(
119            "switch_turn is not supported by this runtime adapter".into(),
120        ))
121    }
122
123    async fn admit_model_routing_assistant_turn(
124        &self,
125        _session_id: &SessionId,
126    ) -> Result<(), RuntimeDriverError> {
127        Err(RuntimeDriverError::Internal(
128            "model routing turn admission is not supported by this runtime adapter".into(),
129        ))
130    }
131
132    async fn begin_image_operation(
133        &self,
134        _session_id: &SessionId,
135        _request: ImageOperationRoutingRequest,
136    ) -> Result<ImageOperationRoutingResult, RuntimeDriverError> {
137        Err(RuntimeDriverError::Internal(
138            "image operation routing is not supported by this runtime adapter".into(),
139        ))
140    }
141
142    async fn deny_image_operation_plan(
143        &self,
144        _session_id: &SessionId,
145        _operation_id: meerkat_core::image_generation::ImageOperationId,
146        _reason: meerkat_core::image_generation::ImageOperationDenialReason,
147    ) -> Result<meerkat_core::image_generation::ImageOperationPhase, RuntimeDriverError> {
148        Err(RuntimeDriverError::Internal(
149            "image operation plan denial is not supported by this runtime adapter".into(),
150        ))
151    }
152
153    async fn activate_image_operation_override(
154        &self,
155        _session_id: &SessionId,
156        _operation_id: meerkat_core::image_generation::ImageOperationId,
157    ) -> Result<meerkat_core::image_generation::ImageOperationPhase, RuntimeDriverError> {
158        Err(RuntimeDriverError::Internal(
159            "image operation activation is not supported by this runtime adapter".into(),
160        ))
161    }
162
163    async fn classify_image_operation_terminal(
164        &self,
165        _session_id: &SessionId,
166        _operation_id: meerkat_core::image_generation::ImageOperationId,
167        _observation: meerkat_core::image_generation::ImageProviderTerminalObservation,
168        _provider_text: meerkat_core::image_generation::ProviderTextDisposition,
169    ) -> Result<meerkat_core::image_generation::ImageOperationTerminalClass, RuntimeDriverError>
170    {
171        Err(RuntimeDriverError::Internal(
172            "image operation terminal classification is not supported by this runtime adapter"
173                .into(),
174        ))
175    }
176
177    async fn complete_image_operation(
178        &self,
179        _session_id: &SessionId,
180        _operation_id: meerkat_core::image_generation::ImageOperationId,
181        _terminal: meerkat_core::image_generation::ImageOperationTerminalClass,
182    ) -> Result<meerkat_core::image_generation::ImageOperationPhase, RuntimeDriverError> {
183        Err(RuntimeDriverError::Internal(
184            "image operation completion is not supported by this runtime adapter".into(),
185        ))
186    }
187
188    async fn restore_image_operation_override(
189        &self,
190        _session_id: &SessionId,
191        _operation_id: meerkat_core::image_generation::ImageOperationId,
192    ) -> Result<meerkat_core::image_generation::ImageOperationPhase, RuntimeDriverError> {
193        Err(RuntimeDriverError::Internal(
194            "image operation restore is not supported by this runtime adapter".into(),
195        ))
196    }
197}
198
199#[cfg(test)]
200mod tests {
201    use super::*;
202
203    // Verify trait is object-safe
204    fn _assert_object_safe(_: &dyn SessionServiceRuntimeExt) {}
205}
meerkat_runtime/service_ext.rs

meerkat_runtime/
service_ext.rs
