Struct Tool 

pub struct Tool {
    pub name: String,
    pub description: String,
    pub schema: Schema,
    pub readable: bool,
    pub timeout_sec: u32,
    pub detail_from_args: Option<Box<dyn FnMut(&[u8]) -> String>>,
    pub execute: Box<dyn FnMut(&[u8]) -> Pin<Box<dyn Future<Output = Result<ToolResult, String>>>>>,
}

An LLM-callable tool. schema is a typed JSON Schema for parameters (same role as Go’s Parameters / Codex’s schemars-generated input schema). The execute handler returns a boxed future so sync (Tool::new) and async (Tool::new_async) handlers share one storage type; it is run to completion on a single-threaded tokio runtime, blocking the PXB loop the same way a sync handler does (the host waits for the result anyway).

Fields

name: String

description: String

schema: Schema

readable: bool

Side-effect-free: the host may run a batch of Readable calls concurrently. Set with Tool::readable.

timeout_sec: u32

Host RPC wait for execute, in seconds. 0 = host default (30s).

detail_from_args: Option<Box<dyn FnMut(&[u8]) -> String>>

Optional one-line TUI detail from raw JSON args (before execute).

execute: Box<dyn FnMut(&[u8]) -> Pin<Box<dyn Future<Output = Result<ToolResult, String>>>>>

Tool handler: takes raw JSON args, returns a future yielding the result. Not Send — the run loop is single-threaded, so handlers may capture non-Send state.

Implementations

impl Tool

pub fn new( name: impl Into<String>, description: impl Into<String>, schema: impl Into<Schema>, execute: impl FnMut(&[u8]) -> Result<ToolResult, String> + 'static, ) -> Self

Examples found in repository

examples/full.rs (lines 9-22)

fn main() -> Result<(), phi::Error> {
    let mut m = phi::Extension::new("full", "0.1.0");

    m.register_tool(
        phi::Tool::new(
            "echo",
            "Echo the input back",
            phi::Schema::object()
                .property("text", phi::Schema::string())
                .required(["text"]),
            |args| {
                let text = String::from_utf8_lossy(args);
                Ok(phi::ToolResult {
                    content: format!("echo: {text}"),
                    ..Default::default()
                })
            },
        )
        .detail_from_args(|args| String::from_utf8_lossy(args).into_owned()),
    );

    m.register_tool(
        phi::Tool::new_async(
            "async-echo",
            "Echo the input back (async handler)",
            phi::Schema::object()
                .property("text", phi::Schema::string())
                .required(["text"]),
            |args| async move {
                // Yield once: proves the SDK's runtime drives the future
                // rather than just polling a ready block.
                tokio::task::yield_now().await;
                let text = String::from_utf8_lossy(&args);
                Ok(phi::ToolResult {
                    content: format!("async echo: {text}"),
                    ..Default::default()
                })
            },
        )
        .timeout_sec(10),
    );

    m.register_command(
        "ask",
        phi::Command::new("Ask a yes/no question", |_args, ctx| {
            let reply = ctx.confirm("Confirm?", "Proceed with /tmp/x?");
            if reply.ok {
                ctx.notify("info", "Confirmed!");
            } else {
                ctx.notify("warning", "Declined.");
            }
            ctx.submit("follow-up from ask");
            Ok(())
        }),
    );

    m.run()
}

pub fn new_async<F, Fut>( name: impl Into<String>, description: impl Into<String>, schema: impl Into<Schema>, execute: F, ) -> Self

where F: FnMut(Vec<u8>) -> Fut + 'static, Fut: Future<Output = Result<ToolResult, String>> + 'static,

Builds a tool with an async handler (network / IO friendly). The closure returns a future that the SDK drives to completion on its single-threaded runtime when the host invokes the tool. Args are owned (Vec<u8>) so |args| async move { … } can capture them directly in a 'static future.

Examples found in repository

examples/full.rs (lines 27-43)

fn main() -> Result<(), phi::Error> {
    let mut m = phi::Extension::new("full", "0.1.0");

    m.register_tool(
        phi::Tool::new(
            "echo",
            "Echo the input back",
            phi::Schema::object()
                .property("text", phi::Schema::string())
                .required(["text"]),
            |args| {
                let text = String::from_utf8_lossy(args);
                Ok(phi::ToolResult {
                    content: format!("echo: {text}"),
                    ..Default::default()
                })
            },
        )
        .detail_from_args(|args| String::from_utf8_lossy(args).into_owned()),
    );

    m.register_tool(
        phi::Tool::new_async(
            "async-echo",
            "Echo the input back (async handler)",
            phi::Schema::object()
                .property("text", phi::Schema::string())
                .required(["text"]),
            |args| async move {
                // Yield once: proves the SDK's runtime drives the future
                // rather than just polling a ready block.
                tokio::task::yield_now().await;
                let text = String::from_utf8_lossy(&args);
                Ok(phi::ToolResult {
                    content: format!("async echo: {text}"),
                    ..Default::default()
                })
            },
        )
        .timeout_sec(10),
    );

    m.register_command(
        "ask",
        phi::Command::new("Ask a yes/no question", |_args, ctx| {
            let reply = ctx.confirm("Confirm?", "Proceed with /tmp/x?");
            if reply.ok {
                ctx.notify("info", "Confirmed!");
            } else {
                ctx.notify("warning", "Declined.");
            }
            ctx.submit("follow-up from ask");
            Ok(())
        }),
    );

    m.run()
}

pub fn timeout_sec(self, secs: u32) -> Self

Sets how long the host waits for this tool’s result (1–3600; host clamps).

Examples found in repository

examples/full.rs (line 44)

fn main() -> Result<(), phi::Error> {
    let mut m = phi::Extension::new("full", "0.1.0");

    m.register_tool(
        phi::Tool::new(
            "echo",
            "Echo the input back",
            phi::Schema::object()
                .property("text", phi::Schema::string())
                .required(["text"]),
            |args| {
                let text = String::from_utf8_lossy(args);
                Ok(phi::ToolResult {
                    content: format!("echo: {text}"),
                    ..Default::default()
                })
            },
        )
        .detail_from_args(|args| String::from_utf8_lossy(args).into_owned()),
    );

    m.register_tool(
        phi::Tool::new_async(
            "async-echo",
            "Echo the input back (async handler)",
            phi::Schema::object()
                .property("text", phi::Schema::string())
                .required(["text"]),
            |args| async move {
                // Yield once: proves the SDK's runtime drives the future
                // rather than just polling a ready block.
                tokio::task::yield_now().await;
                let text = String::from_utf8_lossy(&args);
                Ok(phi::ToolResult {
                    content: format!("async echo: {text}"),
                    ..Default::default()
                })
            },
        )
        .timeout_sec(10),
    );

    m.register_command(
        "ask",
        phi::Command::new("Ask a yes/no question", |_args, ctx| {
            let reply = ctx.confirm("Confirm?", "Proceed with /tmp/x?");
            if reply.ok {
                ctx.notify("info", "Confirmed!");
            } else {
                ctx.notify("warning", "Declined.");
            }
            ctx.submit("follow-up from ask");
            Ok(())
        }),
    );

    m.run()
}

pub fn detail_from_args(self, f: impl FnMut(&[u8]) -> String + 'static) -> Self

Sets a one-line TUI detail formatter for raw JSON arguments.

Examples found in repository

examples/full.rs (line 23)

fn main() -> Result<(), phi::Error> {
    let mut m = phi::Extension::new("full", "0.1.0");

    m.register_tool(
        phi::Tool::new(
            "echo",
            "Echo the input back",
            phi::Schema::object()
                .property("text", phi::Schema::string())
                .required(["text"]),
            |args| {
                let text = String::from_utf8_lossy(args);
                Ok(phi::ToolResult {
                    content: format!("echo: {text}"),
                    ..Default::default()
                })
            },
        )
        .detail_from_args(|args| String::from_utf8_lossy(args).into_owned()),
    );

    m.register_tool(
        phi::Tool::new_async(
            "async-echo",
            "Echo the input back (async handler)",
            phi::Schema::object()
                .property("text", phi::Schema::string())
                .required(["text"]),
            |args| async move {
                // Yield once: proves the SDK's runtime drives the future
                // rather than just polling a ready block.
                tokio::task::yield_now().await;
                let text = String::from_utf8_lossy(&args);
                Ok(phi::ToolResult {
                    content: format!("async echo: {text}"),
                    ..Default::default()
                })
            },
        )
        .timeout_sec(10),
    );

    m.register_command(
        "ask",
        phi::Command::new("Ask a yes/no question", |_args, ctx| {
            let reply = ctx.confirm("Confirm?", "Proceed with /tmp/x?");
            if reply.ok {
                ctx.notify("info", "Confirmed!");
            } else {
                ctx.notify("warning", "Declined.");
            }
            ctx.submit("follow-up from ask");
            Ok(())
        }),
    );

    m.run()
}

pub fn readable(self) -> Self

Marks this tool side-effect-free so the host may run a batch of Readable calls concurrently.