lash/turns

pub enum TurnOutcome {
    Finished(TurnFinish),
    AgentFrameSwitch { frame_key: FrameKey, 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_key, .. } => record_frame_boundary(frame_key)?,
    TurnOutcome::Stopped(stop) => match stop {
        TurnStop::Cancelled { .. } | TurnStop::InvalidInput => report_user_visible(stop),
        TurnStop::ProviderError | TurnStop::Incomplete => offer_retry(stop),
        // Either bound: the turn budget, or the no-progress budget when
        // consecutive attempts committed no successful execution.
        TurnStop::MaxTurns => review_turn_bounds(),
        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.

Host-facing controls retain the stable turn id and call LashSession::request_turn_cancel, or LashSession::request_turn_cancel_with_disposition when undelivered active-turn input should be dropped instead of deferred to the next turn. Drop leaves that input cancelled for the host to handle rather than replaying it as next-turn ingress. Deployments can use TurnWorkDriver::request_cancel directly. The keyed-promise gate is exact-scope and replay-safe, and await_terminal attaches idempotently to the authoritative result. Restate deployments use RestateTurnDeployment and LashDurableWaitWorkflow, not the Admin API. Cancellation is cooperative: detached effects are not guaranteed to stop. Session and turn ids are routing identity, not authorization.

use lash::{
    TurnAddress, TurnCancelDisposition, TurnCancellationEvidence, TurnOutcome, TurnStop,
};

let turn_id = "incident-summary-42";
let stream = session
    .turn(TurnInput::text("Summarize the incident."))
    .turn_id(turn_id)
    .stream()?;

// An HTTP handler can retain only these routing ids. Authenticate and
// authorize the caller before forwarding them to Lash. The default inline
// driver is same-process; cross-process cancellation requires a durable
// engine deployment. "user" is this host's vocabulary; Lash carries it
// opaquely without assigning semantics. Choose Drop when undelivered input
// should return to the host instead of being deferred to the next turn.
let receipt = session
    .request_turn_cancel_with_disposition(
        turn_id,
        "stop-button-7",
        Some("user".to_string()),
        Some("operator pressed Stop".to_string()),
        TurnCancelDisposition::Drop,
    )
    .await?;
let _receipt = receipt;

let result = stream.finish().await?;
// The evidence that settled the cancellation rides the outcome, so a
// cancelled turn always names the request that stopped it. Match on the
// variant, or read it with `TurnOutcome::cancellation`.
if let TurnOutcome::Stopped(TurnStop::Cancelled { evidence }) = &result.outcome {
    assert_eq!(evidence.request_id, "stop-button-7");
    assert_eq!(TurnOutcome::cancellation(&result.outcome), Some(evidence));
}
// Lash mints its own evidence when no host request explains the stop, so
// the request id is namespaced rather than absent.
assert_eq!(
    TurnCancellationEvidence::internal(turn_id).request_id,
    format!("internal:{turn_id}")
);

// Attachment is idempotent and returns immediately after publication.
let terminal = core
    .turn_work_driver()
    .await_terminal_with_timeout(
        &session.turn_address(turn_id),
        std::time::Duration::from_secs(30),
    )
    .await?;

Restate deployment wiring

let deployment = lash_restate::RestateTurnDeployment::new(ingress_url);

// Configure the core with this host. Bind LashDurableWaitWorkflowImpl and
// LashDurableWaitIndexImpl on the Restate endpoint alongside turn handlers.
let effect_host = deployment.effect_host();

// This durable driver can live in a different web process from the turn
// owner. It uses LashDurableWaitWorkflow—not the Restate Admin API—and
// survives web-process restarts. Inline TurnWorkDriver is same-process.
let driver = deployment.turn_work_driver();
let terminal_attach = deployment.turn_attach();

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.

TurnReport.usage / TurnReport.children_usage

Per-turn snapshot. Parent-only and per-(source, model) child breakdown. TurnReport::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. State TypeScript durably when the session opens, through SessionBuilder::plugin_option(RLM_PROTOCOL_PLUGIN_ID, RlmCreateExtras { dialect: Some(RlmDialect::Typescript), .. }); omission selects Lashlang. The same RlmCreateExtras::final_answer_format field sets 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. Both are durable facts, applied as a guarded set-if-unset write (ADR 0066).

use lash::rlm::{
    RLM_PROTOCOL_PLUGIN_ID, RlmCreateExtras, RlmDialect, RlmFinalAnswerFormat,
    RlmTurnBuilderExt as _,
};

// Durable session facts are stated once through the plugin options seam and
// applied as a guarded set-if-unset write (ADR 0066).
let session = core
    .session("analysis")
    .plugin_option(
        RLM_PROTOCOL_PLUGIN_ID,
        RlmCreateExtras {
            dialect: Some(RlmDialect::Typescript),
            final_answer_format: Some(RlmFinalAnswerFormat::RawFinalValue),
            ..RlmCreateExtras::default()
        },
    )?
    .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?;