writing/plugins

use std::sync::Arc;
use lash::{plugins::PluginFactory, LashCore};

let core = LashCore::rlm()
    .provider(provider)
    .model("gpt-5.4", None)
    .max_context_tokens(200_000)
    .configure_plugins(|plugins| {
        plugins.push(Arc::new(AppPluginFactory) as Arc<dyn PluginFactory>);
    })
    .build()?;

use std::sync::Arc;
use lash::{
    plugins::ToolOutputBudgetPluginFactory, LashCore, ModeId, ModePreset, PluginStack,
};

let plugins = PluginStack::runtime().configure(|plugins| {
    plugins.replace(Arc::new(ToolOutputBudgetPluginFactory::new(config)));
    plugins.remove("some_optional_plugin");
});

let core = LashCore::builder()
    .install_mode(ModePreset::rlm())
    .default_mode(ModeId::rlm())
    .provider(provider)
    .model("gpt-5.4", None)
    .max_context_tokens(200_000)
    .plugins(plugins)
    .build()?;

Use .plugin(...) to append one factory, .plugins(...) to replace the full stack, and .configure_plugins(...) to mutate the current stack. PluginStack::runtime() currently installs the built-in ToolOutputBudgetPluginFactory, which budgets oversized tool outputs for state, model context, and history projection.

use std::sync::{Arc, Mutex};
use lash::plugins::{
    PluginError, PluginFactory, PluginRegistrar, PluginSessionContext, SessionPlugin,
};
use lash::tools::{ToolCall, ToolDefinition, ToolProvider, ToolResult};

const PLUGIN_ID: &str = "update_plan";

// 1. Factory — per-core, cheap to build.
pub struct UpdatePlanPluginFactory;

impl PluginFactory for UpdatePlanPluginFactory {
    fn id(&self) -> &'static str { PLUGIN_ID }

    fn build(
        &self,
        ctx: &PluginSessionContext,
    ) -> Result<Arc<dyn SessionPlugin>, PluginError> {
        Ok(Arc::new(UpdatePlanPlugin {
            // Gate by context: only enable in root sessions.
            active: ctx.is_root_session(),
            state: Arc::new(Mutex::new(PlanState::default())),
        }))
    }
}

// 2. SessionPlugin — per-session, wires hooks during register().
struct UpdatePlanPlugin {
    active: bool,
    state: Arc<Mutex<PlanState>>,
}

impl SessionPlugin for UpdatePlanPlugin {
    fn id(&self) -> &'static str { PLUGIN_ID }

    fn register(&self, reg: &mut PluginRegistrar) -> Result<(), PluginError> {
        if !self.active { return Ok(()); }
        reg.tools().provider(Arc::new(UpdatePlanTool {
            state: Arc::clone(&self.state),
        }))?;
        Ok(())
    }
}

// 3. ToolProvider — definitions() advertises, execute() runs.
struct UpdatePlanTool { state: Arc<Mutex<PlanState>> }

#[async_trait::async_trait]
impl ToolProvider for UpdatePlanTool {
    fn definitions(&self) -> Vec<ToolDefinition> {
        vec![ToolDefinition::raw(
            "update_plan",
            "Publish or replace the current plan.",
            serde_json::json!({ "type": "object", "properties": { /* … */ } }),
            serde_json::json!({}),
        )]
    }

    async fn execute(&self, call: ToolCall<'_>) -> ToolResult {
        // Read call.args, validate, mutate self.state, emit ToolResult::ok(...).
        ToolResult::ok(serde_json::json!({ "generation": 1 }))
    }
}

Real plugins typically register multiple hooks in the same register() call (e.g. a tool plus an after-tool hook that emits a UI event, plus a prompt contribution describing the tool). See crates/lash-plugin-plan-mode/src/update_plan.rs:280-330 for the full version.

• Perform I/O — disk reads, HTTP requests, DB queries.
• Compile regexes, JSON schemas, templates, or anything else that can be done once on the factory.
• Open network or process pools.
• Load large models or parse large config files.
• Block on long mutexes or run anything resembling work.

Put expensive state on the factory struct (wrap it in Arc), clone the Arc into the SessionPlugin at build time, and clone again into hook closures. The factory lives once per core; sessions are cheap shells.

fn snapshot(&self) -> Result<Option<Vec<u8>>, PluginError> { Ok(None) }
fn restore(&self, _bytes: &[u8]) -> Result<(), PluginError> { Ok(()) }

snapshot() serialises whatever session-local state the plugin holds — counters, accumulated context, pending state machines — and the bytes go into the same SQLite checkpoint blob the runtime uses for its own state. restore() is called on a fresh session plugin after register() when the runtime opens an existing session id. Treat the byte format as private to your plugin; version it inline if you anticipate schema drift.

Plugins that hold no per-session state at all (most prompt contributors, observers, pure tool providers) can skip both methods — the defaults are correct. Plugins that hold mutable per-session state (counters, plan documents, ongoing observations) must implement snapshot/restore to remain consistent across restart; without them, the session resumes with the runtime graph intact but the plugin's view reset to factory defaults.

Snapshot bytes live in the session store, so they share its durability story: every commit is one SQLite transaction with optimistic CAS. There is no separate flush of plugin state — your snapshot lands in the same atomic write as the turn that produced it.

pub struct ToolCall<'a> {
    pub name: &'a str,                           // Advertised tool name the model called
    pub args: &'a serde_json::Value,             // Deserialized JSON args
    pub context: &'a ToolContext,                // Explicit session/tool capabilities
    pub progress: Option<&'a ProgressSender>,    // For streaming progress updates
}

Tools receive plain JSON arguments. In RLM mode, host-projected Lashlang values are materialized by the mode's before-tool hook before schema validation and before execute(); ordinary tool code should not know about the internal projection marker. Projection-aware RLM control tools preserve only root seed entries when they intentionally carry a projected source into a child or successor session.

context.plugin_input::<MyPlugin>("plugin_id") reads typed per-turn input passed via TurnBuilder::with_plugin_input (see the Lash API guide's "Typed Plugin Input" section for the matching PluginBinding pattern).

use lash::direct::{DirectOutputSpec, DirectRequest};

async fn rank(call: ToolCall<'_>) -> ToolResult {
    let model = match call.context.session_model().await {
        Ok(model) => model,
        Err(err) => return ToolResult::err_fmt(format_args!("{err}")),
    };

    let request = DirectRequest {
        model: model.model,
        model_variant: model.model_variant,
        messages: vec![/* ... */],
        attachments: Vec::new(),
        output: DirectOutputSpec::Text,
        stream_events: None,
        session_id: None,                 // filled by ToolContext
        originating_tool_call_id: None,   // filled by ToolContext
    };

    match call.context.direct_completion(request, "my_tool").await {
        Ok(completion) => ToolResult::ok(serde_json::json!({ "text": completion.text })),
        Err(err) => ToolResult::err_fmt(format_args!("{err}")),
    }
}

ToolContext exposes no public host() escape hatch. Runtime bridge traits such as ToolHookHost remain internal lash-core wiring, not plugin-facing API. Import direct-call request/result types from lash::direct; plugin authors should not depend on provider internals for one-shot model calls.

use lash::tools::{ToolDefinition, ToolExecutionMode};

ToolDefinition::raw("write_file", "Replace a file's contents.", schema, examples)
    .execution_mode(ToolExecutionMode::Serial)

Mixing parallel and serial tools in one batch is supported and common: a read-heavy plan emitting five read_file calls plus one write_file gets the reads concurrently and the write afterward. There is no model-visible distinction — the model sees the same JSON tool list regardless of dispatch mode.

use lash::plugins::{
    ToolOutputBudgetConfig, ToolOutputBudgetPluginFactory,
};

let config = ToolOutputBudgetConfig {
    max_bytes: 32 * 1024, // default: 16 * 1024
    max_lines: 800,        // default: 400
    ..ToolOutputBudgetConfig::default()
};

let plugins = PluginStack::runtime().configure(|plugins| {
    plugins.replace(Arc::new(ToolOutputBudgetPluginFactory::new(config)));
});

Defaults are 16 KiB and 400 lines per tool output. Outputs under both caps pass through untouched; outputs over either cap are truncated with a "… N more bytes / lines elided …" trailer.

The plugin registers a tool-result projector that applies at three points:

• Dispatch projection — what the runtime returns to the calling code as the tool's immediate result.
• Model projection — what gets serialised into the next provider request's tool-result message.
• History projection — what's written to the session graph for replay and audit.

RLM mode print observations go through the same projector — a Lashlang program that prints a 200 KiB blob sees the same trimmed view its next observation would carry. Replace the factory rather than appending; reg.tool_results() is exclusive (one projector per session). Plugins that need different projection logic should build on ToolOutputBudgetConfig rather than fight it.

let core = LashCore::builder()
    .provider(provider)
    .model("anthropic/claude-sonnet-4.6", None)
    .max_context_tokens(200_000)
    .plugin(Arc::new(UpdatePlanPluginFactory) as Arc<dyn PluginFactory>)
    .build()?;

For tools that aren't part of a plugin (no state, no lifecycle hooks), you can skip the factory and pass a ToolProvider directly to .tools(Arc::new(MyTools)). Both forms compose: provider-style tools live alongside plugin-registered tools on the same surface.