Module tool 

Rhai script tools - drop-in tool definitions for agent blueprints.

A .rhai file in an agent’s tools/ directory (or the global ~/.leviath/tools/) defines one custom tool. Its metadata comes from comment annotations at the top of the file (// @tool, // @description, // @param) or an optional sibling tool.toml (which, when present, overrides the annotations). Each script is compiled to a Rhai AST once at agent boot.

Scripts run sandboxed: the only way they reach the outside world is the small, controlled set of host functions registered on the tool engine. Five of them (http_get, http_post, shell, read_file, env_var) do I/O and go through a ScriptHost trait object so the host can enforce permissions and tests can inject a fake; the other three (parse_json, to_json, encode_uri) are pure and defined here.

Errors never bubble as a Result to the agent - execute always returns a String, using the [error] … prefix convention the rest of the tool layer uses, so a failing script surfaces to the model the same way a built-in tool’s error does.

Structs

ParamSpec

One declared parameter of a script tool.

ScriptTool

A discovered, compiled script tool: its metadata plus the Rhai AST (compiled once) and the path it came from.

ScriptToolMeta

Metadata describing a script tool: its name, description, and parameters.

ScriptToolSet

The set of script tools available to one agent, keyed by tool name.

SkippedTool

A .rhai file that could not be turned into a tool (bad annotations, tool.toml, or a compile error). Surfaced so the caller can log it - the library itself does no logging, keeping that policy decision in the host.

Constants

SCRIPT_TOOL_MAX_OPERATIONS

Maximum wall-clock a single script tool call may run. Enforced via the Rhai operation limit already set on the engine; this constant documents intent for the (blocking) host wrapper.

Traits

ScriptHost

The side-effecting host functions a script tool can call. Implemented by the daemon (with permission enforcement + real I/O) and by tests (with canned responses). Every method returns Result<String, String>; an Err(msg) is turned into a Rhai exception by the tool engine, which surfaces to the agent as an [error] … result.

Functions

execute

Execute a compiled script tool with the model-supplied args, returning the result as a string for the agent. args is exposed to the script as the params object-map. The returned Rhai value is serialized to JSON unless it is already a string (returned verbatim). Any script error becomes an [error] … string.

parse_annotations

Parse a script tool’s metadata from its .rhai source comment annotations.

parse_tool_toml

Parse a tool.toml manifest into ScriptToolMeta. When a tool.toml sits beside a script it takes precedence over the script’s comment annotations.