Struct Session 

pub struct Session { /* private fields */ }

A conversation with an agent.

Holds the session id, the event log, and the message history — which is a projection of that log, never a separate source. Sessions are created from an Agent and can be resumed from a log alone.

Implementations

impl Session

pub fn id(&self) -> SessionId

The session’s correlation id — generated internally, readable on demand, never an input you must mint.

pub fn input(&self) -> InputQueue

A handle for steering a turn that is already running.

run borrows the session for the whole turn, so this is taken before starting one and used from wherever the input comes from — a UI task, a socket, a signal handler. Messages join the conversation at the turn’s next reasoning step; see agentyk_core::input::InputQueue::drain for why that boundary.

Anything pushed while no turn is running waits for the next one, so a UI never has to know whether the agent is busy.

use agentyk_core::{input::InputQueue, message::Message};

// What `session.input()` hands out: a queue whose clones share one
// backlog, so a UI task can push while the turn runs.
let steering = InputQueue::new();
let from_the_ui = steering.clone();
from_the_ui.push(Message::user("skip the tests, just build"));

assert_eq!(steering.drain().len(), 1);

pub fn is_closed(&self) -> bool

Whether Session::close has fired this session’s end hooks.

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

Close this in-memory session and fire advisory session_end hooks.

Dropping a Rust value cannot await async hooks, so session end is explicit. Closing is idempotent. A closed session retains its history for inspection but refuses new turns.

pub async fn point(&self) -> Result<SessionPoint>

Current immutable point at the session’s durable head.

pub async fn inspect(&self, point: SessionPoint) -> Result<SessionView>

Reconstruct a read-only view without executing or modifying history.

pub async fn fork(&self, point: SessionPoint) -> Result<Self>

Create an independent branch from a completed-turn boundary.

The original session remains unchanged. The returned session inherits history through point and records session.forked lineage before new turns are appended.

pub async fn resume_pending(&mut self) -> Result<Option<TurnResult>>

Continue the newest incomplete turn at this session’s current head.

Returns None when the session has no incomplete turn. Recovery is at-least-once for external actions; see InProcessExecutor::resume_turn. The agent’s default model is used.

pub async fn resume_pending_with_options( &mut self, options: RunOptions, ) -> Result<Option<TurnResult>>

Continue the newest incomplete turn with explicit cancellation and model controls.

pub async fn resume_pending_with_agent( &mut self, agent: &Agent, ) -> Result<Option<TurnResult>>

Continue an incomplete turn using the agent that originally answered it in a multi-agent session.

The event log records turn state, not sensitive agent configuration. A host therefore supplies the same by-value agent again when recovering an addressed guest turn.

pub async fn resume_pending_with_agent_and_options( &mut self, agent: &Agent, options: RunOptions, ) -> Result<Option<TurnResult>>

Continue an incomplete guest-agent turn with explicit run options.

pub fn messages(&self) -> &[Message]

The reconstructed-or-live message history — always equal to a replay of this session’s log.

pub async fn events(&self) -> Result<Vec<Event>>

All events recorded for this session, ordered by sequence.

pub fn commands(&self) -> Vec<CommandDescriptor>

Every slash command the agent’s capabilities expose — see agentyk_core::capability::Capability::commands.

pub async fn execute_command( &self, name: &str, args: &str, ) -> Result<ToolOutput>

Run a command directly — bypasses the turn loop entirely (no model call, no event log entry): the first capability whose agentyk_core::capability::Capability::commands lists name and whose execute_command returns Some(..) wins. Errors with an “unknown command” message if none claims it.

pub async fn run(&mut self, input: impl Into<Message>) -> Result<TurnResult>

Run one turn: user input in, final assistant text out. Uncancellable and on the agent’s default model — see Session::run_with_options for cancellation and per-turn model/reasoning overrides.

Takes anything that becomes a Message, so run("hello") stays a one-liner while a turn opened with an image is run(Message::user_multimodal(parts)) rather than a different method.

pub async fn run_cancellable( &mut self, input: impl Into<Message>, token: CancellationToken, ) -> Result<TurnResult>

Run one turn, stoppable from elsewhere: clone token before calling, keep the clone, and call CancellationToken::cancel on it (e.g. from a UI event or another task) to stop the turn at its next check point — between reason/tool steps, or between streaming chunks. Returns Err(Error::Cancelled) if the turn was stopped this way.

pub async fn run_controlled( &mut self, input: impl Into<Message>, controls: TurnControls, ) -> Result<TurnResult>

Run one turn with per-turn model/reasoning overrides, without rebuilding the agent — see TurnControls.

pub async fn run_with_options( &mut self, input: impl Into<Message>, options: RunOptions, ) -> Result<TurnResult>

Run one turn with full control over cancellation and per-turn overrides — the general form run/run_cancellable/run_controlled delegate to.

pub async fn run_with_agent( &mut self, agent: &Agent, input: impl Into<Message>, ) -> Result<TurnResult>

Run an addressed turn with another by-value agent definition while retaining this session’s shared history and host environment.

This is the engine seam behind multi-agent session routing. The embedding host owns membership, roles, and authorization, resolves the addressed participant to an Agent, then passes that value here. The guest contributes behavior and model defaults; the session host keeps supplying drivers, listeners, and extensions. Plain Self::run continues to route to the session’s host agent.

pub async fn run_with_agent_and_options( &mut self, agent: &Agent, input: impl Into<Message>, options: RunOptions, ) -> Result<TurnResult>

Run an addressed agent turn with cancellation and model overrides.