Struct LashRuntime 

pub struct LashRuntime { /* private fields */ }

Generic runtime for CLI or programmatic embedding.

Implementations

impl LashRuntime

pub fn builder() -> EmbeddedRuntimeBuilder

impl LashRuntime

pub fn set_model(&mut self, model: ModelSpec)

Update model spec on the runtime config.

pub fn set_provider(&mut self, provider: ProviderHandle)

Update provider on the runtime config.

pub fn set_session_id(&mut self, session_id: Option<String>)

Update session ID metadata on the runtime config.

pub async fn update_session_config( &mut self, provider: Option<ProviderHandle>, model: Option<ModelSpec>, prompt: Option<PromptLayer>, )

pub async fn set_prompt_template(&mut self, template: PromptTemplate)

pub async fn clear_prompt_template(&mut self)

pub async fn add_prompt_contribution( &mut self, contribution: PromptContribution, )

pub async fn replace_prompt_slot( &mut self, slot: PromptSlot, contributions: impl IntoIterator<Item = PromptContribution>, )

pub async fn clear_prompt_slot(&mut self, slot: PromptSlot)

pub async fn refresh_session_tool_surface(&mut self) -> Result<(), SessionError>

Re-register the current tool surface in the live RLM session.

pub async fn apply_tool_state( &mut self, snapshot: ToolState, ) -> Result<u64, SessionError>

pub async fn restore_tool_state( &mut self, snapshot: ToolState, ) -> Result<u64, SessionError>

Restore a persisted tool-state snapshot, adopting its generation.

Unlike apply_tool_state — a generation-checked delta that requires the snapshot to match the current generation and bumps it — this restores the exact persisted surface idempotently, so a cold resume of a session whose surface reached generation ≥ 2 succeeds (a delta-apply onto a fresh base-1 registry would be rejected).

impl LashRuntime

pub fn unregister_plugin_session(&self) -> Result<(), PluginError>

pub async fn from_embedded_state( policy: SessionPolicy, host: EmbeddedRuntimeHost, services: RuntimeServices, state: RuntimeSessionState, ) -> Result<Self, SessionError>

Build a runtime for an embedded host with no background worker support.

pub async fn from_background_state( policy: SessionPolicy, host: ProcessRuntimeHost, services: RuntimeServices, state: RuntimeSessionState, ) -> Result<Self, SessionError>

Build a runtime for a host that supports background plugin work.

pub async fn from_persistent_embedded_state( policy: SessionPolicy, host: EmbeddedRuntimeHost, services: PersistentRuntimeServices, state: RuntimeSessionState, ) -> Result<Self, SessionError>

Build a runtime for an embedded host with persistent store support.

pub async fn from_persistent_background_state( policy: SessionPolicy, host: ProcessRuntimeHost, services: PersistentRuntimeServices, state: RuntimeSessionState, ) -> Result<Self, SessionError>

Build a runtime for a background-capable host with persistent store support.

pub async fn from_environment( env: &RuntimeEnvironment, policy: SessionPolicy, state: RuntimeSessionState, store: Option<Arc<dyn RuntimePersistence>>, ) -> Result<Self, SessionError>

Embedder-preferred constructor: build a LashRuntime from a shared RuntimeEnvironment.

Everything expensive (plugin factories, HTTP client pool, prompt template, path resolver) lives on the environment and is reused across every runtime the embedder builds. This call is O(plugin-session-registration + state-hydration), not O(full-infrastructure-init).

• env — the shared environment. env.plugin_host must be set.
• policy — per-session policy (model, provider, autonomy, turn limits).
• state — persisted session state (empty for a fresh session).
• store — per-session store. None builds an embedded runtime with no persistence; Some builds a persistent background-capable runtime.

pub async fn park(self) -> Result<ParkedSession, SessionError>

Persist any dirty state and drop the runtime, returning a lightweight handle the embedder can cache and resume later via LashRuntime::resume. This is the webserver-embedder parking primitive: the handle holds only the session id, policy, and store reference — no graph nodes, no plugin session, no HTTP client.

pub async fn resume( parked: ParkedSession, env: &RuntimeEnvironment, ) -> Result<Self, SessionError>

Resume a previously parked session against a shared environment. Loads only the active-path graph when env.residency == ActivePathOnly; under KeepAll loads the full graph (current behavior).

pub async fn get_historic_node( &self, node_id: &str, ) -> Result<Option<SessionNodeRecord>, SessionError>

Opt-in async read for historic (non-active-path) nodes under Residency::ActivePathOnly. Plugins that walk the full graph call this instead of session_graph().find_node() so missing nodes surface as Ok(None) rather than silently missing.

pub async fn orphaned_node_ids(&self) -> Result<Vec<String>, SessionError>

Store-resident node IDs that are NOT reachable from the current leaf — i.e. orphans eligible for tombstoning. lash owns RAM; the host owns disk lifecycle, so this is a primitive the host calls on its own schedule (e.g. every N turns, or off-peak).

Typical autonomous-agent loop:

let orphans = runtime.orphaned_node_ids().await?;
if !orphans.is_empty() {
    store.tombstone_nodes(&orphans).await;
}
// And less often:
store.vacuum().await;

impl LashRuntime

pub fn session_id(&self) -> &str

pub fn tool_state(&self) -> Result<ToolState, SessionError>

pub fn set_protocol_turn_options(&mut self, options: ProtocolTurnOptions)

Override protocol-owned turn options for this session.

pub fn export_state(&self) -> SessionSnapshot

Export current session state for inspection/UI purposes. This keeps persistence-heavy snapshots untouched; callers that need a fully persisted view should use export_persisted_state.

pub fn read_view(&self) -> SessionReadView

pub fn export_persistence_state(&self) -> RuntimeSessionState

Export the narrow persistence snapshot used by stores and resume logic.

pub fn apply_persistence_state( &mut self, state: RuntimeSessionState, ) -> Result<(), SessionError>

pub fn export_persisted_state(&self) -> RuntimeSessionState

Export a persistence-ready state envelope with dynamic/plugin snapshots refreshed from the live session.

pub fn usage_report(&self) -> SessionUsageReport

pub async fn await_background_work(&mut self) -> Result<(), SessionError>

pub fn session_state_service( &self, ) -> Result<Arc<dyn SessionStateService>, PluginActionInvokeError>

pub fn session_lifecycle_service( &self, ) -> Result<Arc<dyn SessionLifecycleService>, PluginActionInvokeError>

pub fn session_graph_service( &self, ) -> Result<Arc<dyn SessionGraphService>, PluginActionInvokeError>

pub fn process_service( &self, ) -> Result<Arc<dyn ProcessService>, PluginActionInvokeError>

pub fn process_cancel_ability(&self) -> Arc<dyn ProcessCancelAbility>

pub fn effect_host(&self) -> Arc<dyn EffectHost>

pub async fn enqueue_turn_input( &self, input: TurnInput, delivery_policy: DeliveryPolicy, slot_policy: SlotPolicy, source_key: Option<String>, ) -> Result<QueuedWorkBatch, RuntimeError>

pub async fn cancel_queued_work_batch( &self, session_id: &str, batch_id: &str, ) -> Result<Option<QueuedWorkBatch>, RuntimeError>

pub fn plugin_session(&self) -> Option<Arc<PluginSession>>

The plugin session bound to the currently active runtime session, if any.

pub async fn rewrite_history( &mut self, trigger: RewriteTrigger, ) -> Result<bool, PluginActionInvokeError>

Run the registered history rewrite pipeline against the current state, applying the resulting messages back onto the runtime. Returns true when at least one rewriter produced a summary or otherwise mutated the message list.

impl LashRuntime

pub async fn submit_session_command( &mut self, command: SessionCommand, idempotency_key: impl Into<String>, ) -> Result<SessionCommandReceipt, RuntimeError>

pub async fn drain_next_session_command( &mut self, ) -> Result<Option<SessionCommandReceipt>, RuntimeError>

impl LashRuntime

pub fn set_persisted_state( &mut self, state: RuntimeSessionState, ) -> Result<(), SessionError>

Replace the host-owned state envelope.

pub async fn append_session_nodes( &mut self, request: AppendSessionNodesRequest, ) -> Result<AppendSessionNodesResult, SessionError>

pub async fn apply_protocol_session_extension( &mut self, extension: ProtocolSessionExtensionHandle, ) -> Result<(), SessionError>

pub async fn validate_protocol_turn_extension( &mut self, extension: &ProtocolTurnExtensionHandle, ) -> Result<(), SessionError>

pub async fn branch_to_node( &mut self, node_id: Option<String>, ) -> Result<SessionSnapshot, SessionError>

pub async fn activate_managed_session( &mut self, session_id: &str, ) -> Result<(), SessionError>

Promote a managed child session into the foreground runtime.

Child sessions created through SessionLifecycleService::create_session are real runtimes, not serialized placeholders. Foreground activation must therefore claim that runtime instead of reconstructing a new empty state in the UI.

pub async fn snapshot_execution_state( &mut self, ) -> Result<Option<Vec<u8>>, SessionError>

Explicitly snapshot protocol-local execution state, if any.

pub async fn restore_execution_state( &mut self, snapshot: &[u8], ) -> Result<(), SessionError>

Explicitly restore protocol-local execution state from an opaque snapshot blob.

pub async fn activate_lashlang_trigger( &mut self, handle: &str, payload: Value, ) -> Result<HostEventEmitReport, SessionError>

pub async fn activate_lashlang_trigger_with_effect_scope( &mut self, handle: &str, payload: Value, scoped_effect_controller: ScopedEffectController<'_>, ) -> Result<HostEventEmitReport, SessionError>

pub async fn activate_lashlang_trigger_source_type( &mut self, source_type: impl AsRef<str>, payload: Value, ) -> Result<HostEventEmitReport, SessionError>

pub async fn activate_lashlang_trigger_source_type_with_effect_scope( &mut self, source_type: impl AsRef<str>, payload: Value, scoped_effect_controller: ScopedEffectController<'_>, ) -> Result<HostEventEmitReport, SessionError>

pub fn list_lashlang_trigger_registrations( &self, ) -> Result<Vec<TriggerRegistration>, SessionError>

pub fn lashlang_trigger_registrations_by_source_type( &self, source_type: impl Into<TriggerSourceType>, ) -> Result<Vec<TriggerRegistration>, SessionError>

pub async fn invoke_plugin_action( &self, name: &str, args: Value, session_id: Option<String>, ) -> Result<ToolResult, PluginActionInvokeError>

impl LashRuntime

pub async fn stream_turn( &mut self, input: TurnInput, opts: TurnOptions<'_>, ) -> Result<AssembledTurn, RuntimeError>

Run a single turn and stream events to the host sink.

pub async fn stream_next_queued_work( &mut self, opts: TurnOptions<'_>, ) -> Result<Option<AssembledTurn>, RuntimeError>

pub async fn stream_selected_queued_work( &mut self, opts: TurnOptions<'_>, batch_ids: &[String], ) -> Result<Option<AssembledTurn>, RuntimeError>

pub async fn stream_turn_with_agent_frames( &mut self, input: TurnInput, opts: TurnOptions<'_>, ) -> Result<AgentFrameRun, RuntimeError>

Stream one logical host turn, following foreground AgentFrame switches until a terminal outcome is reached.

RLM continue_as creates a new frame in the same session. Hosts that only care about the benchmark/app answer should not need to special-case that intermediate outcome; this helper keeps driving the same session through each frame’s task with the normal runtime turn guards.

pub async fn run_turn_assembled( &mut self, input: TurnInput, cancel: CancellationToken, ) -> Result<AssembledTurn, RuntimeError>

Run a single turn and return only the assembled terminal result.

pub async fn stream_prepared_turn( &mut self, messages: MessageSequence, _previous_prompt_usage: Option<PromptUsage>, protocol_turn_options: Option<ProtocolTurnOptions>, protocol_extension: Option<ProtocolTurnExtensionHandle>, turn_context: TurnContext, initial_turn_causes: Vec<TurnCause>, trace_turn_id: String, turn_index: usize, events: &dyn EventSink, turn_events: &dyn TurnActivitySink, scoped_effect_controller: ScopedEffectController<'_>, cancel: CancellationToken, initial_queue_claim: Option<QueuedWorkClaim>, ) -> Result<AssembledTurn, RuntimeError>

Run a turn using host-prepared message history.