Struct Session 

pub struct Session { /* private fields */ }

One session. A cheap handle: clones share the terminal latch. Build it with Sessions::create, Sessions::start, or Sessions::open.

Implementations

impl Session

pub async fn over_budget(&self) -> Result<bool, LaserError>

Whether this session’s usage has passed its budget: the summed input and output tokens of its records over the token ceiling, or their summed cost over the cost ceiling. A deployment that indexes sessions answers from its index. On open Apache Iggy, or for a session the index does not know yet, the retained session lane is folded: the budget of the first start record against the usage of every record. A session without a budget is never over it. The answer is eventually consistent, so a budget is a cooperative limit, not a hard spending cap.

impl Session

pub async fn parked(&self) -> Result<ParkedRecords, LaserError>

The work records this session’s agents held while it was paused and have not reported handled. A session canceled while paused keeps its held records here unprocessed. The read covers the newest CONTEXT_READ_WINDOW records of each agent.sessions partition.

impl Session

pub fn signed_by(self, key: SigningKey) -> Self

This handle signing its terminal record with key, so a verifying reader can prove which agent ended the session. Feature sign.

pub fn as_agent(self, agent: impl Into<AgentId>) -> Self

This handle writing as agent.

pub fn conversation(&self) -> ConversationId

This session’s id.

pub fn stream(&self) -> Result<&str, LaserError>

The stream this session lives in.

pub fn agent(&self) -> Option<&AgentId>

The agent this handle writes as.

pub fn parent(&self) -> Option<ConversationId>

The parent session, for a child session.

pub fn root(&self) -> Option<ConversationId>

The root of this session’s tree, for a child session.

pub fn config(&self) -> &SessionConfig

The layout this session follows.

pub fn scope(&self) -> &ContextScope

The underlying ContextScope, for a topic outside the session lane or an explicit ContextPolicy.

pub async fn append( &self, envelope: AgentEnvelope, ) -> Result<AgdxReceipt, LaserError>

Append one typed envelope to the session lane. The envelope must name this session as its conversation.

pub async fn end(&self) -> Result<(), LaserError>

End the session as completed. State changed since the last snapshot is snapshotted first, so a reader can start from the final document.

pub async fn fail(&self, error: AgentErrorBody) -> Result<(), LaserError>

End the session as failed with error.

pub async fn cancel(&self) -> Result<(), LaserError>

End the session as canceled.

pub async fn run<F, Fut, T>( self, lease: SessionLease, work: F, ) -> Result<T, LaserError>

where F: FnOnce(Session) -> Fut, Fut: Future<Output = Result<T, LaserError>>,

Run work inside the session and end it by the outcome: completed on success, failed on an error or a panic. A panic is re-raised after the failure is written. When the terminal write also fails, the error from work is returned. A dropped future, panic = "abort", an unawaited child task, or process death is not captured, and the session then shows idle once its heartbeat stops.

pub async fn context(&self) -> Result<Vec<SessionTurn>, LaserError>

The model-ready context: the configured last records on the session lane, trimmed to the configured estimated token bound.

pub async fn context_with( &self, policy: Box<dyn ContextPolicy>, ) -> Result<Vec<SessionTurn>, LaserError>

context under an explicit policy.

pub fn memory(&self) -> ScopedMemory

This session’s memory in the configured namespace, scoped to the session.

pub fn memory_in(&self, namespace: impl Into<String>) -> ScopedMemory

memory in an explicit namespace.

pub fn graph(&self, name: impl Into<String>) -> GraphHandle<'_>

The knowledge graph name, the same graph Laser::graph returns. Feature graph.

pub async fn checkpoint(&self) -> Result<Checkpoint, LaserError>

Where the session lane ends right now. Persist it (it serializes) and hand it to state_at or replay.

pub async fn turns_at( &self, checkpoint: Checkpoint, ) -> Result<Vec<SessionTurn>, LaserError>

The records up to checkpoint.

pub async fn turns_since( &self, checkpoint: Checkpoint, ) -> Result<Vec<SessionTurn>, LaserError>

The records appended after checkpoint.

pub async fn state_at<S, F>( &self, checkpoint: Checkpoint, init: S, fold: F, ) -> Result<S, LaserError>

where F: FnMut(S, &SessionTurn) -> S,

Fold the records up to checkpoint into S: state as it stood then.

pub async fn replay<S, F>( &self, checkpoint: Checkpoint, init: S, fold: F, ) -> Result<S, LaserError>

where F: FnMut(S, &SessionTurn) -> S,

Fold the records appended after checkpoint into S: bring state saved at that checkpoint up to date.

impl Session

pub async fn status(&self) -> Result<SessionInfo, LaserError>

This session’s summary from the deployment’s session index: status, participants, counters, and the derived idle and over-budget flags.

impl Session

pub fn reference(&self) -> Result<SessionRef, LaserError>

This session as a stream-scoped reference, for writes that land outside the session’s own stream.

pub fn redact( self, redactor: impl Fn(&mut Value) + Send + Sync + 'static, ) -> Self

Replace the redaction applied to tool arguments and model request bodies before they are published. The default drops the values of common secret keys.

pub fn acting_on(self, source: SourceRef) -> Self

This handle with source as the record it acts on, stamped as the source of graph writes and the origin of remembered items.

pub async fn cancel_requested(&self) -> Result<bool, LaserError>

Whether an operator asked to cancel this session on agent.control, by a cancel request or a forced cancel. Reads the retained control records of this session, so it answers on open Apache Iggy too.

pub async fn pending_control(&self) -> Result<PendingControl, LaserError>

The pause and cancel requests operators sent this session on agent.control, addressed to this handle’s agent or to every agent. Inside a handler the runtime’s control subscription keeps them current, and the first read of a session folds its retained control records. Outside a runtime every call reads the retained records. The runtime only records requests: the handler decides when to stop.

pub fn state(&self) -> SessionState

The session’s state document.

pub async fn assemble( &self, policy: Box<dyn ContextPolicy>, ) -> Result<AssembledContext, LaserError>

Assemble the model context under policy from the session lane and describe it in a manifest. Nothing is written.

pub async fn model( &self, request: ModelRequest, assembled: Option<&AssembledContext>, ) -> Result<ModelCall, LaserError>

Record a model request addressed to this agent, and the context it received when assembled is given. Finish the returned call when the application’s provider answers.

pub async fn tool( &self, name: impl Into<String>, args: Value, ) -> Result<ToolCall, LaserError>

Record a tool call addressed to this agent, with args redacted.

pub async fn record_model_call( &self, request: ModelRequest, response: ModelResponse, assembled: Option<&AssembledContext>, ) -> Result<AgdxReceipt, LaserError>

Record a model call that already happened: the request, the context when given, and the response. duration is the measured call time. A response with no duration records duration_micros = 0.

pub fn kv(&self, namespace: impl Into<String>) -> Result<Kv, LaserError>

The key-value namespace namespace with every write linked to this session. Feature kv.

pub fn linked_graph( &self, name: impl Into<String>, ) -> Result<GraphHandle<'_>, LaserError>

The knowledge graph name with every upsert linked to this session, stamped with this agent as producer and the current record as source. Feature graph.

pub async fn record_retrieval( &self, query: Option<String>, items: &[MemoryItem], ) -> Result<AgdxReceipt, LaserError>

Record that items, recalled for query when there was one, entered the session’s context, with each item’s id and score.

pub async fn record_compaction( &self, compaction: ContextCompaction, ) -> Result<AgdxReceipt, LaserError>

Record that a summary replaced the covered records of the session’s context.

pub fn linked_memory(&self) -> ScopedMemory

This session’s memory with every remembered item stamped with this agent as producer and the current record as origin.

Trait Implementations

impl Clone for Session

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.