tool/execution

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

ToolDefinition::raw(
    "tool:write_file",
    "write_file",
    "Replace a file's contents.",
    input_schema,
    output_schema,
)
.with_scheduling(ToolScheduling::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.

Deferred completion has one hard rule: before returning ToolResult::Pending, the tool must first obtain a completion key by calling call.context.completion_key().await. That key names the durable wait and is what the external resolver later uses to deliver the result. Returning Pending without having taken a key fails the call with the internal error pending_tool_missing_completion_key.

use lash::tools::PendingCompletion;

// Take the completion key BEFORE returning Pending, then hand it to whatever
// will deliver the result out-of-band — a webhook, a job queue, a human.
let key = match call.context.completion_key().await {
    Ok(key) => key,
    Err(err) => return ToolResult::err_fmt(format_args!("{err}")),
};
enqueue_external_work(key);

// Returning Pending without first taking the key fails the call with
// `pending_tool_missing_completion_key`.
ToolResult::pending(PendingCompletion::new())

PendingCompletion configures the wait: an optional deadline, an on_timeout behavior (ErrorAsResult feeds a timeout result back to the model; FailTurn fails the whole turn), and an on_cancel hint (CancelExternalWork by default, or Ignore to leave the out-of-band work running). Adjust it with PendingCompletion::new().with_deadline(..) and .fail_turn_on_timeout(). The remote protocol carries tool grants only; execute tools through a normal ToolProvider at the host boundary.

Journal a JSON Step

Use run_json around the side effect that must not double-run after replay. The closure receives the JSON input that was recorded in the envelope; return a JSON value that is safe to store in the effect log.

let durable = match call.context.durable_effects() {
    Ok(durable) => durable,
    Err(err) => return ToolResult::err_fmt(err),
};

let opened = match durable
    .run_json(
        "create-input-request",
        serde_json::json!({ "question": call.args["question"].clone() }),
        |input| async move {
            // Create the external record, enqueue work, or call a service.
            Ok(serde_json::json!({
                "request_id": "request-1",
                "question": input["question"].clone()
            }))
        },
    )
    .await
{
    Ok(value) => value,
    Err(err) => return ToolResult::err_fmt(err),
};

Wait On An External Resolver

Generate the key before publishing the request, persist or emit the full key, then await that same key. Hosts resolve it through their effect host; the tool stays local and does not receive workflow-engine context.

let key = match durable
    .external_event_key(format!("input-request:{}", opened["request_id"]))
    .await
{
    Ok(key) => key,
    Err(err) => return ToolResult::err_fmt(err),
};

// Store or emit the complete key. The resolver needs the signed key, not just
// the human-readable custom identity string used above.
if let Err(err) = publish_input_request(opened.clone(), key.clone()).await {
    return ToolResult::err_fmt(format_args!("{err}"));
}

let answer = match durable.await_event_json(key).await {
    Ok(value) => value,
    Err(err) => return ToolResult::err_fmt(err),
};

Emit A Domain Process Event

When the tool is running inside a Lashlang process, process event context is carried into the ToolContext. That lets ordinary tools append domain events from the same implementation path the model calls.

if let Err(err) = durable
    .emit_process_event(
        "work.input_request.opened",
        serde_json::json!({
            "request_id": opened["request_id"].clone(),
            "await_key_id": key.key_id,
        }),
    )
    .await
{
    return ToolResult::err_fmt(err);
}

Replay Rules

• Step ids are local to one tool invocation. Reusing the same id in the same call fails before the closure runs. Use stable names such as create and complete, not random ids.
• Inputs are part of the envelope hash. Changing the JSON input changes the recorded effect identity, which protects replay from silently accepting a different side effect.
• Inline is not crash-durable. The inline effect controller supports the API for local runs and tests, but workflow adapters such as the Restate host are what persist outcomes across process crashes.
• Remote tool execution is not special-cased. A durable tool can call a remote service from inside run_json, but the runtime still sees a local ToolProvider and a local effect log.

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

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

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

Defaults are 16 KiB and 400 lines per tool output (the size cap is bytes by default; ToolOutputBudgetMode::Tokens switches it to an approximate token count). Outputs under both caps pass through untouched; outputs over either cap keep a preview window wrapped in a "...N bytes truncated..." marker; the unit reads bytes (or tokens) when the size cap binds, lines when the line cap binds.

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.