Struct ScriptedToolBuilder 

pub struct ScriptedToolBuilder { /* private fields */ }

Builder for ScriptedTool.

use bashkit_scripted_tool::{ScriptedTool, ToolArgs, ToolDef};

let tool = ScriptedTool::builder("net")
    .short_description("Network tools")
    .tool_fn(
        ToolDef::new("ping", "Ping a host")
            .with_schema(serde_json::json!({
                "type": "object",
                "properties": { "host": {"type": "string"} }
            })),
        |args: &ToolArgs| {
            Ok(format!("pong {}\n", args.param_str("host").unwrap_or("?")))
        },
    )
    .build();

Implementations

impl ScriptedToolBuilder

pub fn locale(self, locale: &str) -> Self

Set locale for descriptions, help, prompts, and user-facing errors.

pub fn short_description(self, desc: impl Into<String>) -> Self

One-line description for tool listings.

pub fn tool(self, tool: ToolImpl) -> Self

Register a ToolImpl (definition + exec functions).

This is the preferred registration method. The ToolImpl carries its own name, schema, and sync/async exec.

pub fn builtin(self, name: impl Into<String>, builtin: Box<dyn Builtin>) -> Self

Register a raw-argv builtin alongside the ToolDef tools.

ToolDef commands are parsed by the schema-driven flag parser, which only understands --key value and --key=value. A command that needs positionals, short flags, --, or parse-time checking of required arguments gets none of that. Registering it here hands the builtin the raw ctx.args instead, so it can parse them however it likes — including with ClapBuiltin, the house parser for Bash builtins.

The builtin runs in the same logic-only shell as the ToolDef commands and gets the same disabled filesystem, so registering one does not widen the scripted catalog’s filesystem posture. It is ordinary trusted host code otherwise: whatever the builtin itself reaches, the script reaches.

Custom builtins are registered before the ToolDef commands, so a name collision resolves in favour of the registered tool: a custom builtin can never shadow a tool command, help, or discover.

struct Ping;

#[async_trait]
impl Builtin for Ping {
    async fn execute(&self, ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
        Ok(ExecResult::ok(format!("pong {}\n", ctx.args.join(" "))))
    }
}

let tool = ScriptedTool::builder("api")
    .builtin("ping", Box::new(Ping))
    .build();

pub fn tool_fn( self, def: ToolDef, exec: impl Fn(&ToolArgs) -> Result<String, String> + Send + Sync + 'static, ) -> Self

Register a tool with its definition and synchronous exec function.

Convenience shorthand — constructs a ToolImpl internally. The exec receives ToolArgs with --key value flags parsed into a JSON object, type-coerced per the schema.

pub fn tool_with_dry_run( self, def: ToolDef, exec: impl Fn(&ToolArgs) -> Result<String, String> + Send + Sync + 'static, dry_run: impl Fn(&ToolArgs) -> Result<String, String> + Send + Sync + 'static, ) -> Self

Register a tool with its definition, exec function, and a custom --dry-run handler. When the tool is invoked with --dry-run, the custom handler runs instead of the regular callback.

pub fn async_tool_fn<F, Fut>(self, def: ToolDef, exec: F) -> Self

where F: Fn(ToolArgs) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<String, String>> + Send + 'static,

Register a tool with its definition and async exec function.

Convenience shorthand — constructs a ToolImpl internally. Same as tool_fn() but returns a Future, allowing non-blocking I/O. Takes owned ToolArgs because the future may outlive the borrow.

pub fn limits(self, limits: ExecutionLimits) -> Self

Set execution limits for the bash interpreter.

pub fn profile(self, profile: ExecutionProfile) -> Self

Apply execution, session, and memory policy from a profile.

Scripted tools always retain their disabled filesystem/network/runtime surface; those capability policies are intentionally not widened.

pub fn env(self, key: impl Into<String>, value: impl Into<String>) -> Self

Add an environment variable visible inside scripts.

pub fn sanitize_errors(self, sanitize: bool) -> Self

Control whether callback and custom-builtin fatal errors are sanitized before appearing in tool output. When true (the default), internal error details are replaced with a generic “callback failed” message to prevent leaking file paths, connection strings, or stack traces to LLM agents. Cancellation and resource-limit errors retain their actionable category.

pub fn compact_prompt(self, compact: bool) -> Self

Emit compact system_prompt() that omits full schemas and adds help tip.

When enabled, system_prompt() lists only tool names + one-liners and instructs the LLM to use help <tool> / help <tool> --json for details. Default: false (full schemas in prompt, backward compatible).

pub fn build(&self) -> ScriptedTool

Build the ScriptedTool.

pub fn build_service(&self) -> ToolService

Build a tower::Service<Value, Response = Value, Error = ToolError>.

pub fn build_tool_definition(&self) -> Value

Build an OpenAI-compatible tool definition.

pub fn build_input_schema(&self) -> Value

Build the input schema without constructing the full tool.

pub fn build_output_schema(&self) -> Value

Build the output schema for ToolOutput::result.