lash/api

Durable session graph

Conversation records, tool events, mode events, and plugin nodes live in one SessionGraph per session. SessionReadView and ChronologicalProjection read it; nothing else owns persistence.

Per-turn atomic commit

RuntimeCommit writes graph delta, checkpoint blobs, usage deltas, and head revision in one SQLite transaction with optimistic CAS on expected_head_revision. Partial turn = no commit.

Typed plugin capabilities

Tools see a named ToolContext surface — tasks(), sessions(), direct_completion, tool_catalog, snapshot reads — not a general host handle. There is no ToolContext::host() escape hatch.

Sandboxed code load, ready

RLM mode runs model-emitted Lashlang programs in a VM with no filesystem, process, or network surface. Every effect crosses ToolHost. Use it when the model should compose multiple tool calls per turn instead of one.

Subagent capability boundaries

Capability::resolve(parent_policy) returns a constrained SessionSpec for the child. Interactive-only tools are stripped from every subagent surface regardless of capability.

Semantic event stream

Identity-bearing TurnActivity items: assistant prose deltas, reasoning deltas, tool start/complete pairs with correlation ids, code-block start/complete, terminal SubmittedValue/ToolValue, per-call and rolling usage. Apps fold this directly into product state.

Tracing as a first-class sink

Every provider call across every session emits TraceRecords through TraceSink implementations. JSONL by default, OTel optional.

Snapshot and restore seams

Plugins, tool state, and the Lashlang VM each persist through versioned snapshot writers so a parked session resumes intact across process restarts.

What sits outside this crate, on purpose: tenancy boundaries, retention and lifecycle for long-lived artifacts, discovery of agent-authored procedures, a shared coherent image across many sessions. lash is the kernel and runtime; the platform-shaped pieces belong to whatever embeds it.

use std::sync::Arc;

use lash::{tools::*, LashCore, ModeId, ModePreset, PluginStack, TurnEvent, TurnInput};

let store_factory = Arc::new(lash_sqlite_store::SqliteSessionStoreFactory::new("lash-sessions"));

let core = LashCore::builder()
    .install_mode(ModePreset::standard())
    .install_mode(ModePreset::rlm())
    .default_mode(ModeId::rlm())
    .provider(provider)
    .model("anthropic/claude-sonnet-4.6", None)
    .max_context_tokens(200_000)
    .plugins(PluginStack::runtime())
    .tools(Arc::new(AppTools) as Arc<dyn ToolProvider>)
    .store_factory(store_factory)
    .build()?;

let session = core.session("chat-123").rlm().open().await?;
let result = session.turn(TurnInput::text("Use the app tools.")).run().await?;
let assistant_text: String = result.activities.iter().filter_map(|activity| match &activity.event {
    TurnEvent::AssistantProseDelta { text } => Some(text.as_str()),
    _ => None,
}).collect();
println!("{assistant_text}");

LashCore

Cloneable shared configuration: provider, model, installed modes, tool providers, plugin factories, store factory, attachment store, and tracing. Runtime internals such as residency and termination policy live behind .advanced().

ModePreset

Installs execution modes. Use ModePreset::standard() for native provider tool calls, ModePreset::rlm() for Lashlang-driven RLM turns, or install both and choose the default with default_mode.

SessionSpec

Reusable public configuration overlay for provider, model/variant, execution mode, max context tokens, max turns, and prompt layer. Root cores use SessionSpec::new(); child sessions and subagents usually use SessionSpec::inherit().

PluginStack

Ordered plugin factory list. LashCore::standard() and LashCore::rlm() include PluginStack::runtime(); a raw LashCore::builder() stays explicit and needs modes and plugins installed by the host.

LashSession

One app conversation or task. Sessions wrap a parked/resumable runtime, can use a per-session store, and expose turn(TurnInput), run(TurnInput), read_view(), and lower-level control groups through control().

TurnBuilder

Per-turn configuration: cancellation, mode options, typed plugin input, and RLM-projected bindings. Call .stream(&sink) for live events or .run() for a collected ordered activity log.

use lash::{plugins::PluginFactory, LashCore, PluginStack, SessionSpec};

let root_spec = SessionSpec::new()
    .provider(provider)
    .model("gpt-5.4", None)
    .max_context_tokens(200_000);

let core = LashCore::rlm()
    .session_spec(root_spec)
    .configure_plugins(|plugins| {
        plugins.push(Arc::new(AppPluginFactory) as Arc<dyn PluginFactory>);
    })
    .build()?;

let plugins = PluginStack::runtime().configure(|plugins| {
    plugins.replace(Arc::new(CustomBudgetPlugin) as Arc<dyn PluginFactory>);
    plugins.push(Arc::new(AppPluginFactory) as Arc<dyn PluginFactory>);
});

let core = LashCore::builder()
    .install_mode(ModePreset::rlm())
    .default_mode(ModeId::rlm())
    .session_spec(root_spec)
    .plugins(plugins)
    .build()?;

.plugin(...) appends one factory to the current stack, .plugins(...) replaces the full stack, and .configure_plugins(...) mutates the current stack in place. That gives hosts a default runtime set while still allowing precise removal, replacement, or insertion.

let collected = session
    .turn(TurnInput::text("Summarize this task."))
    .run()
    .await?;

let visible_answer: String = collected.activities.iter().filter_map(|activity| match &activity.event {
    TurnEvent::AssistantProseDelta { text } => Some(text.as_str()),
    _ => None,
}).collect();
let parent_usage = collected.result.usage;          // parent's own LLM tokens
let children = &collected.result.children_usage;    // per-(source, model) child entries
let total = collected.result.total_usage();         // parent + children
let outcome = collected.result.outcome;

let ui_sink = Arc::new(AppEvents::new(tx));

let turn = session
    .turn(TurnInput::text(user_text))
    .stream(ui_sink.as_ref())
    .await?;

persist(app_turn_state.assistant_text(), turn.total_usage())?;

Apps own their projection policy. Fold TurnActivity directly when persisting assistant prose, terminal values, tool summaries, or timelines. Treat TurnActivity.correlation_id as the stable identity for multi-phase UI rows: start events insert rows, completion events update those same rows.

TraceSink

Every provider call across every session in the runtime. Right for billing, audit, off-line analysis. Heavier than necessary for plain totals.

TurnEvent::Usage / TurnEvent::ChildUsage

Live during a turn, one event per LLM iteration. Usage is the parent's own model call; ChildUsage carries session_id and source so a UI can group child traffic (subagent, compaction, observer). Right for live counters.

TurnResult.usage / TurnResult.children_usage

Per-turn snapshot at completion. usage is parent-only; children_usage is a per-(source, model) breakdown for any child sessions that ran during the turn. TurnResult::total_usage() sums both.

session.usage_report() → SessionUsageReport

Aggregate across the whole session, broken down by source × model. Right for dashboards and "session so far."

The full re-export and well-known source label constants live in lash::usage.

#[derive(Clone, Debug)]
struct BoardPlugin;

#[derive(Clone, Debug)]
struct BoardConfig;

#[derive(Clone, Debug)]
struct BoardTurnInput {
    board: BoardState,
}

impl lash::PluginBinding for BoardPlugin {
    const ID: &'static str = "board";
    type SessionConfig = BoardConfig;
    type Input = BoardTurnInput;

    fn factory(_: &Self::SessionConfig) -> Arc<dyn lash::plugins::PluginFactory> {
        Arc::new(BoardPluginFactory)
    }

    fn requires_turn_input(_: &Self::SessionConfig) -> bool {
        true
    }
}

impl lash::plugins::SessionPlugin for BoardSessionPlugin {
    fn id(&self) -> &'static str { BoardPlugin::ID }

    fn register(&self, reg: &mut lash::plugins::PluginRegistrar) -> Result<(), lash::plugins::PluginError> {
        reg.prompt().contribute(Arc::new(|ctx| {
            Box::pin(async move {
                let Some(input) = ctx.turn_context.plugin_input::<BoardTurnInput>(BoardPlugin::ID) else {
                    return Ok(Vec::new());
                };
                Ok(vec![lash::PromptContribution::environment(
                    "Board",
                    format_board(&input.board),
                )])
            })
        }));
        reg.tools().provider(Arc::new(BoardTools))
    }
}

#[async_trait::async_trait]
impl lash::tools::ToolProvider for BoardTools {
    fn definitions(&self) -> Vec<lash::tools::ToolDefinition> {
        vec![/* read_board, play_move, app tools */]
    }

    async fn execute(&self, call: lash::tools::ToolCall<'_>) -> lash::tools::ToolResult {
        let Some(input) = call.context.plugin_input::<BoardTurnInput>(BoardPlugin::ID) else {
            return lash::tools::ToolResult::err_fmt("missing board input");
        };
        run_board_tool(call.name, call.args, &input.board)
    }
}

Human input follows the same rule: expose it as a host-owned tool that waits inside its tool implementation and returns a normal tool result. App streams then see ordinary tool start/completion events; there is no separate runtime prompt event to handle.

Plugin crates should export a domain extension trait that wraps the generic input primitive:

trait BoardTurnExt {
    fn with_board(self, board: BoardState) -> Self;
}

impl BoardTurnExt for lash::TurnBuilder {
    fn with_board(self, board: BoardState) -> Self {
        self.with_plugin_input::<BoardPlugin>(BoardTurnInput { board })
    }
}

Install typed plugins on the session and use the extension method before each run:

let core = LashCore::rlm()
    .provider(provider)
    .model(model, None)
    .max_context_tokens(200_000)
    .build()?;

let session = core
    .session(chat_id)
    .rlm()
    .plugin::<BoardPlugin>(BoardConfig)
    .open()
    .await?;

let result = session
    .turn(TurnInput::text("Play one move."))
    .with_board(board)
    .require_submit()?
    .collect_with(&sink)
    .await?;

use std::sync::Arc;
use lash::{plugins::PluginFactory, SessionSpec};
use lash_subagents::{default_registry, SubagentsPluginFactory};

let registry = Arc::new(default_registry(&tier_models));
let host = Arc::new(AppSubagentHost::new(child_store_factory));

let subagents = SubagentsPluginFactory::new(registry, host)
    .with_session_spec(SessionSpec::inherit().max_turns(8));

let core = LashCore::rlm()
    .provider(provider)
    .model(model, None)
    .max_context_tokens(200_000)
    .plugin(Arc::new(subagents) as Arc<dyn PluginFactory>)
    .build()?;

Capability implementations return SessionSpec overlays. StaticCapability is for exact child authority, while TierCapability implements the built-in explore and peer model/mode selection. Tool authors should not construct SessionPolicy for child configuration; it remains the resolved runtime artifact.

use std::collections::BTreeMap;
use lash_plugin_mcp::{McpPluginFactory, McpServerConfig};

let mut servers = BTreeMap::new();
servers.insert(
    "docs".to_string(),
    McpServerConfig::stdio("uvx", vec!["mcp-server-docs".into()]),
);
servers.insert(
    "web".to_string(),
    McpServerConfig::streamable_http("https://mcp.example.com/rpc"),
);

let mcp = McpPluginFactory::new(servers).await?;

let core = LashCore::rlm()
    .provider(provider)
    .model(model, None)
    .max_context_tokens(200_000)
    .plugin(std::sync::Arc::new(mcp))
    .build()?;

Tools are surfaced under mcp__<server>__<tool> names with their original input and output schemas preserved. The factory's attach_server / detach_server methods let hosts add or remove servers at runtime without rebuilding the core.

let core = LashCore::rlm()
    .provider(provider)
    .model("anthropic/claude-sonnet-4.6", None)
    .max_context_tokens(200_000)
    .store_factory(store_factory)
    .advanced()
    .residency(Residency::ActivePathOnly)
    .build()?;

Turn streaming is semantic by default: TurnBuilder::stream emits TurnActivity items and resolves with a rich TurnResult. Raw runtime telemetry belongs in tracing and lower-level runtime debugging, not the normal lash API surface.

OPENROUTER_API_KEY=... cargo run -p agent-service
# then open http://127.0.0.1:3000

Source: examples/agent-service. The dedicated walkthrough is Agent Service.