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 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.

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}")),
    }
}

There is no public ToolContext::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.

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.