Struct LashSession 

pub struct LashSession { /* private fields */ }

Implementations

impl LashSession

pub async fn close(self) -> Result<()>

Durably close this session, then release its in-memory runtime.

close is the honest teardown verb: a persistent session flushes its dirty state (via a fresh-lease commit) so the store reflects the final transcript, its in-memory plugin session is unregistered, and the live runtime is dropped. A store-less (ephemeral) session has nothing to persist, so closing it is exactly the plugin-session unregister plus dropping the runtime.

This consumes the session and requires exclusive ownership: any cloned LashSession handle or in-flight turn keeps a live reference to the same runtime, so close returns EmbedError::SessionStillInUse until those are dropped or finished. Cancel running turns first with cancel_running_turns if needed.

To keep a handle for later resumption instead of discarding the session, use park.

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

Quiesce this session for later resumption, returning a lightweight ParkedSession handle.

Parking flushes dirty state to the store (a fresh-lease commit), drops the live runtime and its plugin session, and hands back a cheap handle the host can cache and later rebuild with LashCore::resume. This is the quiesce/handoff lever for webserver embedders that hold many idle sessions: it bounds resident memory per session without deleting durable state.

Contract:

• Persistent runtime required. Parking flushes to the store, so a store-less session cannot be parked and returns an error. Use close to tear down an ephemeral session.
• Exclusive ownership required. park consumes the session and drops the in-memory runtime, so it needs the sole live reference. A cloned LashSession or an in-flight turn holds another reference and makes park return EmbedError::SessionStillInUse. Because an executing turn holds such a reference, parking is effectively an idle-session operation: finish or cancel_running_turns first. The store commit itself does not observe an active turn; the exclusive-ownership guard is what makes mid-turn parking an explicit error rather than a silent partial flush.

pub fn session_id(&self) -> String

pub fn policy_snapshot(&self) -> SessionPolicy

pub fn observe(&self) -> ObservableSession

pub fn parent_session_id(&self) -> Option<&str>

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

pub fn turn(&self, input: TurnInput) -> TurnBuilder

pub fn queued_turn(&self) -> QueuedTurnBuilder

pub fn cancel_running_turns(&self) -> usize

Cancel every turn currently executing through this opened session (including its clones) and report how many were signalled.

This is the affordance behind a UI “stop” control: hold a clone of the session wherever the stop arrives and call this, instead of threading a CancellationToken into every turn call (TurnBuilder::cancel remains the per-turn hook when you need one). A cancelled turn finishes with TurnOutcome::Stopped(TurnStop::Cancelled) and commits like any other turn; the session stays usable.

Scope: turns started from this LashSession instance and its clones. A handle opened separately for the same session id has its own registry and is not reached.

pub fn admin(&self) -> SessionAdmin

pub async fn configure(&self, patch: SessionConfigPatch) -> Result<()>

pub fn tools(&self) -> ToolAdmin

pub fn commands(&self) -> SessionCommandAdmin

pub fn triggers(&self) -> SessionTriggerAdmin

pub fn processes(&self) -> SessionProcessAdmin

pub async fn refresh_background_graph(&self) -> Result<()>

Refresh the session graph from any background process that signalled it changed. This is the honest name for the former processes().await_all() misnomer (ADR 0019 grill): a session-graph resync, not a terminal wait on background work — wait on a process with SessionProcessAdmin::await_output. It lives on the session surface because it refreshes the session graph, not the global process registry.

pub fn plugin_operations(&self) -> PluginOperations

pub fn enqueue(&self, input: TurnInput) -> EnqueueTurnBuilder<'_>

pub async fn queued_work(&self) -> Result<Vec<QueuedWorkBatch>>

Return all pending durable queued-work batches for this session.

This is an admin/introspection view for non-user queued work such as process wakes and session commands. User-visible model input is stored separately as pending turn input and is exposed by pending_turn_inputs.

pub async fn pending_turn_inputs(&self) -> Result<Vec<PendingTurnInput>>

pub async fn cancel_pending_turn_input( &self, input_id: &str, ) -> Result<PendingTurnInputCancelOutcome>

pub async fn cancel_pending_turn_inputs( &self, targets: impl IntoIterator<Item = PendingTurnInputCancelTarget>, ) -> Result<Vec<PendingTurnInputCancelResult>>

Atomically cancel a set of pending user inputs by runtime input id or app source key.

This is the app reconciliation path for explicit selections such as “remove these pending drafts”. Returned outcomes distinguish newly cancelled input from input that was already claimed, completed, cancelled, or missing.

pub async fn cancel_pending_turn_input_suffix( &self, anchor: PendingTurnInputCancelTarget, ) -> Result<PendingTurnInputSuffixCancelOutcome>

Atomically cancel the same-session pending-input suffix from anchor.

Apps that let users edit previously submitted product messages should map the edited message to the stored pending-input input_id or source_key, call this method, and only restore/edit drafts that return PendingTurnInputCancelOutcome::Cancelled. Claimed or completed inputs have already crossed the runtime boundary and should be treated as reconciliation state, not local editable drafts.

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

pub async fn abandon_queued_work_claim( &self, claim: &QueuedWorkClaim, ) -> Result<()>

Release a held queued-work claim without completing it, returning its batches to the pending queue immediately.

A host stopping an external queued-work driver mid-claim calls this with the claims that driver still holds so the work becomes claimable again at once instead of waiting out the claim’s lease TTL.

pub async fn abandon_turn_input_claim( &self, claim: &TurnInputClaim, ) -> Result<()>

Release a held pending-turn-input claim without completing it, returning its inputs to the pending queue immediately. The turn-input counterpart of abandon_queued_work_claim.

pub async fn revoke_durable_waits(&self) -> Result<()>

Cancel every outstanding durable wait for this session without deleting the session.

Each waiter receives a terminal Resolution::Cancelled instead of hanging until an external completion arrives, and late resolves observe that terminal. The session itself stays usable: new durable waits registered afterwards behave normally, unlike the tombstoning revocation LashCore::delete_session performs.

pub async fn await_queued_work_batch(&self, batch_id: &str) -> Result<()>

Resolve once batch_id is no longer pending in the queue store — drained by whoever runs queued work (a queued-work runner, a durable worker, or another handle’s queued_turn) or cancelled. This is the enqueue-and-observe side of the queue: the caller never claims the work itself.

Completion is read from the persistent queue store, so it observes drains performed by other session handles and other processes alike. There is no built-in deadline — nothing resolves if nothing drains the queue, so bound it with tokio::time::timeout when the worker may be unavailable. A batch id the store has never seen resolves immediately.

pub fn read_view(&self) -> SessionReadView

pub fn usage_report(&self) -> SessionUsageReport

pub async fn set_turn_phase_probe(&self, probe: Arc<dyn RuntimeTurnPhaseProbe>)

Trait Implementations

impl Clone for LashSession

fn clone(&self) -> LashSession

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.