lash/turns

pub enum TurnOutcome {
    Finished(TurnFinish),
    AgentFrameSwitch { frame_id: String, task: String },
    Stopped(TurnStop),
}

pub enum TurnFinish {
    AssistantMessage { text: String },
    FinalValue { value: serde_json::Value },
    ToolValue { tool_name: String, value: serde_json::Value },
}

Finished: clean terminal value. AssistantMessage is the prose default for both modes; the runtime commit materializes the transcript message exactly once; there is no second "final message" stream event after AssistantProseDelta. FinalValue / ToolValue come from RLM finish or a tool-authored terminal; both arrive on the stream too.

AgentFrameSwitch: a protocol plugin or tool switched to a fresh AgentFrame inside the same session. Runtime callers normally use the facade, which keeps driving the same session until a terminal outcome is reached.

Stopped: turn aborted before a terminal value. Ten TurnStop variants:

Host-driven stops are recoverable next request. Provider stops usually want a different model or shorter context. Runtime stops indicate a configuration or authoring problem. RuntimeError is the only category where identical-input retry is unlikely to help.

Session-lane conflicts and CAS backstop conflicts are not Stopped variants; they surface as Err from run()/stream(), no partial commit. See Persistence → Session Lane And CAS.

match result.outcome {
    TurnOutcome::Finished(finish) => persist_terminal(finish)?,
    TurnOutcome::AgentFrameSwitch { frame_id, .. } => record_frame_boundary(frame_id)?,
    TurnOutcome::Stopped(stop) => match stop {
        TurnStop::Cancelled | TurnStop::InvalidInput => report_user_visible(stop),
        TurnStop::ProviderError | TurnStop::Incomplete => offer_retry(stop),
        TurnStop::MaxTurns => suggest_higher_max_turns(),
        other => record_for_diagnosis(other),
    },
}

Conventional pattern: push onto an mpsc channel and return immediately; drain into UI state from a separate task. Sender::send only awaits when full; the channel bound is the backpressure dial:

use tokio::sync::mpsc;

struct ChannelSink {
    tx: mpsc::Sender<TurnActivity>,
}

#[async_trait::async_trait]
impl TurnActivitySink for ChannelSink {
    async fn emit(&self, activity: TurnActivity) {
        // send().await yields when the channel is full — the turn
        // will pause here if your UI consumer falls behind.
        let _ = self.tx.send(activity).await;
    }
}

Sink panics or Err-shaped activities do not abort the turn. Persistence and TurnOutput.activities are independent of the sink; a dropped sink loses no activity.

Two tiers. TurnBuilder::cancel(token) attaches a caller-owned CancellationToken (re-exported at the crate root, no tokio-util dependency needed) to one turn. LashSession::cancel_running_turns() cancels everything currently executing through that opened session and its clones: the affordance behind a UI stop button, with no token threading. It returns how many turns were signalled; a handle opened separately for the same session id is not reached.

use lash::CancellationToken;
use lash::{TurnOutcome, TurnStop};

// Per-turn token: hand it to whatever can decide to stop the turn
// (an HTTP handler, a keybinding, a timeout task).
let cancel = CancellationToken::new();
let stream = session
    .turn(TurnInput::text("Summarize the incident."))
    .cancel(cancel.clone())
    .stream()?;
// elsewhere: cancel.cancel();

// Or skip token plumbing entirely: any clone of the opened session can
// stop whatever it is currently running.
let stopper = session.clone();
let cancelled_turns = stopper.cancel_running_turns();

let result = stream.finish().await?;
if matches!(result.outcome, TurnOutcome::Stopped(TurnStop::Cancelled)) {
    // The turn committed as cancelled; the session is ready for the
    // next turn.
}

TraceSink

Every provider call across every session. Billing, audit, off-line analysis.

TurnEvent::Usage / TurnEvent::ChildUsage

Live during a turn, one event per LLM iteration. ChildUsage carries session_id and source for grouping child traffic.

TurnResult.usage / TurnResult.children_usage

Per-turn snapshot. Parent-only and per-(source, model) child breakdown. TurnResult::total_usage() sums both.

session.usage_report() → SessionUsageReport

Session aggregate by source × model. Dashboards and "session so far."

All usage surfaces use the same five canonical buckets: uncached input_tokens, total output_tokens, cache_read_input_tokens, cache_write_input_tokens, and reasoning_output_tokens. Reasoning is included in output. Source-label constants and re-exports: lash::usage.

use lash::rlm::RlmTurnBuilderExt as _;

let finished = session
    .turn(TurnInput::text("Move on the board."))
    .require_finish()?
    .stream_to(&sink)
    .await?;

let natural = session
    .turn(TurnInput::text("Answer directly if no code is needed."))
    .allow_prose_or_finish()?
    .run()
    .await?;

match result.outcome {
    TurnOutcome::Finished(TurnFinish::FinalValue { value }) => {
        // Same value already arrived as TurnEvent::FinalValue.
        persist_typed_value(value)?;
    }
    TurnOutcome::Finished(TurnFinish::AssistantMessage { text }) => persist_text(text)?,
    other => handle_other_outcome(other)?,
}

Use require_finish_schema(...) when the final value must match a JSON Schema. Use RlmSessionBuilderExt::final_answer_format(...) to set the session's normal final-value presentation: root RLM sessions default to Markdown guidance, managed child sessions default to raw finish values, and schema-required turns ignore the presentation preference.

use lash::rlm::{RlmFinalAnswerFormat, RlmSessionBuilderExt as _, RlmTurnBuilderExt as _};

let session = core
    .session("analysis")
    .final_answer_format(RlmFinalAnswerFormat::RawFinalValue)?
    .open()
    .await?;

let result = session
    .turn(TurnInput::text("Return a risk rating."))
    .require_finish_schema(serde_json::json!({
        "type": "object",
        "required": ["rating"],
        "properties": {
            "rating": { "type": "string" }
        },
        "additionalProperties": false
    }))?
    .run()
    .await?;