Struct Context 

pub struct Context<'a> {
    pub cwd: String,
    pub session_id: String,
    pub has_ui: bool,
    /* private fields */
}

Interaction surface handed to command handlers. All host traffic goes over the same PXB pipe the run loop owns — a handler may block the loop (e.g. confirm reads nested frames).

Fields

cwd: String

session_id: String

has_ui: bool

Implementations

impl Context<'_>

pub fn notify(&mut self, level: &str, message: &str)

Pushes a toast to the host (level: info | warning | error).

Examples found in repository

examples/hello.rs (line 11)

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

    m.register_command(
        "hello",
        phi::Command::new("Say hi", |_args, ctx| {
            ctx.notify("info", "Hello!");
            // ctx.submit("follow-up"); // after /hello returns
            // ctx.send_user_message("…"); // enqueue a turn anytime
            Ok(())
        }),
    );

    m.on_user_input(|_ev| {
        // return Some(phi::UserInputResult { handled: true, ..Default::default() }) to swallow
        // return Some(phi::UserInputResult { text: Some("rewritten".into()), ..Default::default() }) to transform
        None
    });

    m.on_tool_call(|_ev| {
        // return Some(phi::ToolCallResult { block: true, reason: "...".into(), ..Default::default() }) to deny
        None
    });

    m.on_tool_result(|_ev| {
        // return Some(phi::ToolResultResult { stop: true, ..Default::default() }) to end the agent loop
        None
    });

    m.on_turn_stopping(|_ev| {
        // return Some(phi::TurnStoppingResult { continue_: true, message: "check X".into(), ..Default::default() }) to steer
        None
    });

    m.subscribe(pxb::Event::SessionStart, |ev| {
        let _ = ev; // Reason, PreviousSessionID, …
    });

    m.run()
}

examples/full.rs (line 52)

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 set_status(&mut self, text: &str)

Updates the host footer extension status (empty text clears).

pub fn submit(&mut self, text: &str)

Queues a prompt for the host to send after the current slash command returns.

Examples found in repository

examples/full.rs (line 56)

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 send_user_message(&mut self, text: &str)

Asks the host to enqueue a user turn (fire-and-forget). Safe to call from command handlers on the PXB read loop.

pub fn confirm(&mut self, title: &str, message: &str) -> ConfirmReply

Shows a yes/no dialog on the host and waits for the answer.

Examples found in repository

examples/full.rs (line 50)

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 confirm_opts(&mut self, req: ConfirmRequest) -> ConfirmReply

confirm with labels / danger styling.