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/full.rs (line 28)

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()
            })
        },
    ));

    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()
}

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()
}

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 32)

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()
            })
        },
    ));

    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 26)

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()
            })
        },
    ));

    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.