lash/advanced

use std::sync::Arc;

let factory = lash::rlm::RlmProtocolPluginFactory::new(
    lash::rlm::RlmProtocolPluginConfig::default(),
    Arc::new(lash::persistence::InMemoryLashlangArtifactStore::new()),
);
let core = lash::LashCore::rlm_builder(factory)
    .provider(provider)
    .model(model)
    .effect_host(Arc::new(lash::durability::InlineEffectHost::default()))
    .attachment_store(Arc::new(lash::persistence::InMemoryAttachmentStore::new()))
    .build()?;

use std::sync::Arc;

use lash::persistence::FileAttachmentStore;
use lash_sqlite_store::{SqliteSessionStoreFactory, Store};

let store_factory = Arc::new(SqliteSessionStoreFactory::new(data_dir.join("sessions")));
let artifact_store = Arc::new(Store::open(&data_dir.join("artifacts.db")).await?);

let factory = lash::rlm::RlmProtocolPluginFactory::new(
    lash::rlm::RlmProtocolPluginConfig::default(),
    artifact_store,
);
let core = lash::LashCore::rlm_builder(factory)
    .provider(provider)
    .model(model)
    .store_factory(store_factory)
    .effect_host(Arc::new(lash::durability::InlineEffectHost::default()))
    .attachment_store(Arc::new(FileAttachmentStore::new(
        data_dir.join("attachments"),
    )))
    .build()?;

Sessions park automatically when the handle drops. Long-running servers can hold thousands of session ids cheaply. Residency policy controls in-memory trimming while a session is active:

use std::sync::Arc;

use lash::durability::{InlineEffectHost, Residency};
use lash::persistence::FileAttachmentStore;
use lash_sqlite_store::Store;

let factory = lash::rlm::RlmProtocolPluginFactory::new(
    lash::rlm::RlmProtocolPluginConfig::default(),
    Arc::new(Store::open(&data_dir.join("artifacts.db")).await?),
);
let core = lash::LashCore::rlm_builder(factory)
    .provider(provider)
    .model(
        lash::ModelSpec::from_token_limits(model.clone(), None, 200_000, None)
            .expect("valid model metadata"),
    )
    .store_factory(store_factory)
    .effect_host(Arc::new(InlineEffectHost::default()))
    .attachment_store(Arc::new(FileAttachmentStore::new(
        data_dir.join("attachments"),
    )))
    .residency(Residency::ActivePathOnly)
    .build()?;

Plugin background work (tasks tracked via ToolContext::processes(), post-turn observation summaries, MCP warm-ups) continues past turn return. To drain it before returning (one-shot processes that need observations persisted before exit):

session.refresh_background_graph().await?;

Exposed by the CLI as --await-background-work on lash --print. Embedders rarely need it outside short-lived processes.

let factory = lash::rlm::RlmProtocolPluginFactory::new(
    lash::rlm::RlmProtocolPluginConfig::default(),
    artifact_store,
);
let core = lash::LashCore::rlm_builder(factory)
    .provider(provider)
    .model(model)
    .store_factory(store_factory)
    .process_registry(process_registry)
    .effect_host(Arc::new(lash::durability::InlineEffectHost::default()))
    .attachment_store(attachment_store)
    .build()?;

use std::collections::BTreeMap;

let mut resources = lashlang::LashlangHostCatalog::new();
resources.add_trigger_source_constructor(
    ["app", "button"],
    lashlang::TypeExpr::Object(Vec::new()),
    lashlang::NamedDataType::object(
        "app.ButtonPressed",
        vec![lashlang::TypeField {
            name: "color".into(),
            ty: lashlang::TypeExpr::Str,
            optional: false,
        }],
    )?,
)?;

let environment = lashlang::LashlangHostEnvironment {
    resources,
    abilities: lashlang::LashlangAbilities::default().with_processes(),
    ..lashlang::LashlangHostEnvironment::default()
};

let compiled = lashlang::compile_module(lashlang::ModuleCompileRequest {
    source: r#"
process on_button(event: app.ButtonPressed) {
  finish event.color
}
source = app.button({})
finish source
"#,
    environment: &environment,
    artifact_store: Some(artifact_store.as_ref()),
})
.await?;

let process = compiled
    .introspection
    .exported_processes
    .iter()
    .find(|process| process.definition.process_name == "on_button")
    .expect("compiled module exports on_button");

let inputs = lashlang::TriggerInputTemplate::new(BTreeMap::from([(
    "event".to_string(),
    lashlang::TriggerInputBinding::Event,
)]));
let compatibility =
    lashlang::check_trigger_compatibility(lashlang::TriggerCompatibilityRequest {
        artifact: &compiled.artifact,
        definition: &process.definition,
        source_type: "app.button",
        inputs: &inputs,
    })?;

println!(
    "compiled {} and trigger emits {}",
    compiled.module_ref,
    compatibility.event_type.name()
);

Shape: the runtime driver polls TurnMachine. For each reply-producing turn effect it builds a RuntimeEffectEnvelope with a typed RuntimeInvocation, invokes the active ScopedEffectController, and feeds the returned outcome back as the matching response. The InlineEffectHost runs locally and is not in-flight durable. A durable workflow EffectHost such as Restate records effects in workflow history, uses durable timers for sleeps, and reruns the handler with the same turn id before Lash retries the final idempotent commit.

Do not wrap a durable handler turn in another persistent submitted/running work-item state machine. The workflow key and turn_id are the durable in-flight identity; Lash's session execution lease and idempotent commit are the runtime correctness boundary; host tables should store product rows, reconnect outbox rows, cancellation handles, or terminal output.

Full contract: Architecture → Durability. Embedders without workflow orchestration use the regular session-store path.

use std::sync::Arc;

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

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

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

let factory = lash::rlm::RlmProtocolPluginFactory::new(
    lash::rlm::RlmProtocolPluginConfig::default(),
    Arc::new(lash::persistence::InMemoryLashlangArtifactStore::new()),
);
let core = lash::LashCore::rlm_builder(factory)
    .provider(provider)
    .model(
        lash::ModelSpec::from_token_limits(model.clone(), None, 200_000, None)
            .expect("valid model metadata"),
    )
    .effect_host(Arc::new(lash::durability::InlineEffectHost::default()))
    .attachment_store(Arc::new(lash::persistence::InMemoryAttachmentStore::new()))
    .plugin(Arc::new(subagents) as Arc<dyn PluginFactory>)
    .build()?;

Capabilities return SessionSpec overlays. StaticCapability pins exact child authority; TierCapability backs the built-in explore and peer tiers. Do not construct SessionPolicy directly; it's the resolved runtime artifact.

Built-in tiers

Both tiers consult tier_models for an override, then fall back to the parent's model. Pass overrides through default_registry(&tier_models).

Capability resolution

Capability::build_session_request(ctx) sees the live parent SessionPolicy and returns a SessionCreateRequest. The runtime composes the capability's SessionSpec against parent policy to produce effective child config. The spec is what's persisted, so a resumed subagent re-derives the same authority.

Interactive-only tools such as ask and showcase would block a subagent indefinitely; nothing is listening on the other side. Hide them from every child surface with SubagentsPluginFactory::with_hidden_tools(...) or a custom SessionToolAccess; the CLI hides its five interactive tools this way. Recursion is bounded separately: at the maximum spawn depth (5) the runtime hides spawn_agent itself.

Usage attribution

Child sessions emit TurnEvent::ChildUsage on the parent's stream, tagged with source ("subagent", "compaction", "observer") and child session_id. TurnResult.children_usage rolls up per (source, model); total_usage() sums parent + children. Finer splits: fold ChildUsage from the stream directly.

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 factory = lash::rlm::RlmProtocolPluginFactory::new(
    lash::rlm::RlmProtocolPluginConfig::default(),
    std::sync::Arc::new(lash::persistence::InMemoryLashlangArtifactStore::new()),
);
let core = lash::LashCore::rlm_builder(factory)
    .provider(provider)
    .model(
        lash::ModelSpec::from_token_limits(model.clone(), None, 200_000, None)
            .expect("valid model metadata"),
    )
    .effect_host(std::sync::Arc::new(
        lash::durability::InlineEffectHost::default(),
    ))
    .attachment_store(std::sync::Arc::new(
        lash::persistence::InMemoryAttachmentStore::new(),
    ))
    .plugin(std::sync::Arc::new(mcp))
    .build()?;

Tools appear as mcp__<server>__<tool> with original schemas preserved. attach_server / detach_server mutate the live pool without rebuilding the core.

Lifecycle and failure isolation

Servers connect once at McpPluginFactory::new(...). Built session plugins clone the shared Arc<McpConnectionPool>, so startup cost is one-per-process, not one-per-chat.

After attach_server, new tools are visible to sessions on their next tool-catalog refresh (start of next turn). detach_server shuts the server down and removes its tools; in-flight calls fail rather than hang.

// Hot-swap a server at runtime.
mcp.attach_server(
    "new-tool".to_string(),
    McpServerConfig::stdio("uvx", vec!["mcp-server-new".into()]),
)
.await?;

mcp.detach_server("old-tool").await?;

Failures are isolated: an exited child, a 500ing endpoint, or a dropped SSE stream surfaces as ToolResult::err(...) on the affected tool; other servers keep working. If a server is unreachable at new time, the call fails; use McpPluginFactory::empty() plus runtime attach_server when initial connectivity is unreliable.

let factory = lash::rlm::RlmProtocolPluginFactory::new(
    lash::rlm::RlmProtocolPluginConfig::default(),
    std::sync::Arc::new(lash_sqlite_store::Store::open(&data_dir.join("artifacts.db")).await?),
);
let core = lash::LashCore::rlm_builder(factory)
    .provider(provider)
    .model(
        lash::ModelSpec::from_token_limits("anthropic/claude-sonnet-4.6", None, 200_000, None)
            .expect("valid model metadata"),
    )
    .store_factory(store_factory)
    .effect_host(std::sync::Arc::new(
        lash::durability::InlineEffectHost::default(),
    ))
    .attachment_store(std::sync::Arc::new(
        lash::persistence::FileAttachmentStore::new(data_dir.join("attachments")),
    ))
    .residency(lash::durability::Residency::ActivePathOnly)
    .build()?;

Streaming is semantic: TurnBuilder::stream emits TurnActivity and resolves to a TurnResult. Raw runtime telemetry belongs in tracing, not the app surface.

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

Source: examples/agent-service. Walkthrough: Agent Service.