tools

Use ToolDefinition::typed when Rust argument and output structs can derive JsonSchema. Lash validates the incoming JSON against the contract before execution; the tool still decodes call.args into its local Rust type inside execute().

use std::sync::Arc;

use async_trait::async_trait;
use lash::tools::{
    StaticToolExecute, StaticToolProvider, ToolCall, ToolDefinition, ToolProvider, ToolResult,
};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, JsonSchema)]
struct WeatherArgs {
    city: String,
    units: Option<String>,
}

#[derive(Serialize, JsonSchema)]
struct WeatherReport {
    summary: String,
    temperature_c: f32,
}

struct WeatherTools;

#[async_trait]
impl StaticToolExecute for WeatherTools {
    async fn execute(&self, call: ToolCall<'_>) -> ToolResult {
        match call.name {
            "weather_lookup" => {
                let args: WeatherArgs = match serde_json::from_value(call.args.clone()) {
                    Ok(args) => args,
                    Err(err) => return ToolResult::err_fmt(format_args!("invalid args: {err}")),
                };

                let report = lookup_weather(args).await;
                match serde_json::to_value(report) {
                    Ok(value) => ToolResult::ok(value),
                    Err(err) => ToolResult::err_fmt(format_args!("serialize output: {err}")),
                }
            }
            other => ToolResult::err_fmt(format_args!("unknown tool: {other}")),
        }
    }
}

pub fn weather_provider() -> Arc<dyn ToolProvider> {
    let definition = ToolDefinition::typed::<WeatherArgs, WeatherReport>(
        "tool:weather_lookup",
        "weather_lookup",
        "Look up the current weather for a city.",
    );

    Arc::new(StaticToolProvider::new(vec![definition], WeatherTools)) as Arc<dyn ToolProvider>
}

async fn lookup_weather(args: WeatherArgs) -> WeatherReport {
    let units = args.units.unwrap_or_else(|| "metric".to_string());
    WeatherReport {
        summary: format!("{} weather in {}", units, args.city),
        temperature_c: 21.0,
    }
}

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<'a>,            // 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 normalized through each tool's ToolArgumentProjectionPolicy before schema validation and before execute(); ordinary tools use the default materializing policy and should not know about the internal projection marker. Projection-aware RLM control tools declare PreserveProjectedRefsInField { field: "seed" }, so only root seed entries keep projected wrappers and ref-backed entries keep {"__projection_ref__": ...} for child or AgentFrames.

Typed per-turn input passed via TurnBuilder::with_plugin_input is read off the turn context, not the execute-time ToolContext: a tool's prepare_tool_call sees it through ctx.plugin_input::<MyInput>("plugin_id") on the ToolPrepareContext, and hooks read the same value from their TurnContext. See the Lash API · prompts 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.sessions().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,
        generation: Default::default(),
        stream_events: None,
        session_id: None, // filled by ToolContext
        caused_by: None,  // filled by ToolContext
        replay: None,
    };

    match call
        .context
        .direct_completions()
        .complete(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 host wiring stays inside lash-core; plugin-facing code uses explicit context capabilities. Import direct-call request/result types from lash::direct; plugin authors should not depend on provider internals for one-shot model calls.