Trait Extension 

pub trait Extension: Send + Sync {
    // Required method
    fn source(&self) -> SourceInfo;

    // Provided methods
    fn grants(&self) -> Grants { ... }
    fn warn(&self, _message: &str) { ... }
    fn load(&self, _tools: &Tools) { ... }
    fn commands(&self) -> Vec<Command> { ... }
    fn complete(&self, _command: &str, _prefix: &str) -> ArgumentCompletions { ... }
    fn shortcuts(&self) -> Vec<Shortcut> { ... }
    fn run_shortcut<'a>(
        &'a self,
        _key: &'a str,
        _ctx: &'a Context,
    ) -> BoxFuture<'a, Result<(), String>> { ... }
    fn run_command<'a>(
        &'a self,
        _command: &'a str,
        _args: &'a str,
        _ctx: &'a Context,
    ) -> BoxFuture<'a, ()> { ... }
    fn settle(&self) -> BoxFuture<'_, u64> { ... }
    fn session_start<'a>(&'a self, _ctx: &'a Context) -> BoxFuture<'a, ()> { ... }
    fn session_shutdown<'a>(&'a self, _ctx: &'a Context) -> BoxFuture<'a, ()> { ... }
    fn end_session<'a>(&'a self, _session_id: &'a str) -> BoxFuture<'a, ()> { ... }
    fn before_agent_start<'a>(
        &'a self,
        _ctx: &'a Context,
        _sections: &'a mut IndexMap<String, String>,
    ) -> BoxFuture<'a, ()> { ... }
    fn handles(&self, _kind: &str) -> bool { ... }
    fn handle<'a>(
        &'a self,
        _ctx: &'a Context,
        _event: &'a Value,
    ) -> BoxFuture<'a, Option<Value>> { ... }
    fn prepare_loadout(&self, _loadout: &Loadout) -> LoadoutChanges { ... }
    fn refresh_loadout<'a>(&'a self, _loadout: &'a Loadout) -> BoxFuture<'a, ()> { ... }
    fn renderers(&self) -> Renderers { ... }
    fn component<'a>(
        &'a self,
        _request: &'a Value,
    ) -> BoxFuture<'a, Option<RemoteComponent>> { ... }
    fn transform_markdown<'a>(
        &'a self,
        _request: &'a Value,
    ) -> BoxFuture<'a, Result<Option<String>, String>> { ... }
    fn render_code<'a>(
        &'a self,
        _request: &'a Value,
    ) -> BoxFuture<'a, Result<Option<Vec<String>>, String>> { ... }
    fn tool_call<'a>(
        &'a self,
        _ctx: &'a Context,
        _tool: &'a str,
        _input: &'a Value,
    ) -> BoxFuture<'a, Option<String>> { ... }
    fn run_bash<'a>(
        &'a self,
        _handle: &'a Value,
        _command: &'a str,
        _cwd: &'a Path,
        _output: UnboundedSender<Vec<u8>>,
        _cancel: CancellationToken,
    ) -> BoxFuture<'a, Result<Option<i32>, String>> { ... }
    fn refresh_models<'a>(
        &'a self,
        _registry: &'a ModelRegistry,
        _options: &'a RefreshOptions,
    ) -> BoxFuture<'a, Vec<(String, ModelList)>> { ... }
}

An extension. Every hook has a no-op default.

Required Methods

fn source(&self) -> SourceInfo

Where the extension comes from, as get_commands reports it.

Provided Methods

fn grants(&self) -> Grants

What the extension may reach. The session applies its event handlers’ results only within these.

fn warn(&self, _message: &str)

Reports message, a warning from the host about the extension, such as a handler result the session dropped for lack of a grant, with the extension’s own output. Built-in extensions, which have every grant, report nothing.

fn load(&self, _tools: &Tools)

Registers the tools it offers from the start, before the session’s active tools are chosen.

fn commands(&self) -> Vec<Command>

The commands it handles.

fn complete(&self, _command: &str, _prefix: &str) -> ArgumentCompletions

Completions for the argument of command. While they are ArgumentCompletions::Pending, the UI’s refresh_completions follows once they are ready.

fn shortcuts(&self) -> Vec<Shortcut>

The keys it binds.

fn run_shortcut<'a>( &'a self, _key: &'a str, _ctx: &'a Context, ) -> BoxFuture<'a, Result<(), String>>

Runs the handler of shortcut key and returns the handler’s error.

fn run_command<'a>( &'a self, _command: &'a str, _args: &'a str, _ctx: &'a Context, ) -> BoxFuture<'a, ()>

Runs command with its argument text.

fn settle(&self) -> BoxFuture<'_, u64>

Resolves once the extension code that is running has finished and delivered its results. pi runs extension code to completion before it reads the next input. Returns a count that grows with every call into the extension’s code.

fn session_start<'a>(&'a self, _ctx: &'a Context) -> BoxFuture<'a, ()>

The session started or was bound to a mode.

fn session_shutdown<'a>(&'a self, _ctx: &'a Context) -> BoxFuture<'a, ()>

The session ends or is being replaced.

fn end_session<'a>(&'a self, _session_id: &'a str) -> BoxFuture<'a, ()>

Session session_id ended or another replaced it, after its session_shutdown, but not on reload. pi disposes the session’s resources then, with pi-ai’s cleanupSessionResources.

fn before_agent_start<'a>( &'a self, _ctx: &'a Context, _sections: &'a mut IndexMap<String, String>, ) -> BoxFuture<'a, ()>

A prompt is about to run. sections are extra system prompt sections by tag name, which the extension may change.

fn handles(&self, _kind: &str) -> bool

Whether it handles pi events of type kind through Extension::handle.

fn handle<'a>( &'a self, _ctx: &'a Context, _event: &'a Value, ) -> BoxFuture<'a, Option<Value>>

Runs its handlers for pi event event, a JSON object with a type, and returns their combined result as pi’s runner combines one extension’s handlers. The session combines results across extensions.

fn prepare_loadout(&self, _loadout: &Loadout) -> LoadoutChanges

pi’s prepareLoadout hook of a tool it registered: how the next request presents the declared tools. Runs before every request.

fn refresh_loadout<'a>(&'a self, _loadout: &'a Loadout) -> BoxFuture<'a, ()>

Runs before a request’s Extension::prepare_loadout for loadout, for hooks that run elsewhere and answer later, so that prepare_loadout can give what they made of it.

fn renderers(&self) -> Renderers

What it draws in the transcript.

fn component<'a>( &'a self, _request: &'a Value, ) -> BoxFuture<'a, Option<RemoteComponent>>

Builds the component for a transcript item it draws. request is {"kind": "toolCall" | "toolResult", "name", "toolCallId", "args", "result", "options", "context"}, {"kind": "message", "key", "message", "options"} or {"kind": "entry", "key", "entry", "options"}. None keeps the built-in rendering, which shows nothing for an entry.

fn transform_markdown<'a>( &'a self, _request: &'a Value, ) -> BoxFuture<'a, Result<Option<String>, String>>

The Markdown its transformer makes of request, {"markdown", "context"} with pi’s MarkdownTransformContext. Ok(None) keeps the Markdown, as when the transformer fails or returns no string.

fn render_code<'a>( &'a self, _request: &'a Value, ) -> BoxFuture<'a, Result<Option<Vec<String>>, String>>

The lines its code renderer draws for request, {"code", "lang", "width"} with lang possibly null, as text with escape sequences. Ok(None) leaves the code to yapi, and an error is the renderer’s.

fn tool_call<'a>( &'a self, _ctx: &'a Context, _tool: &'a str, _input: &'a Value, ) -> BoxFuture<'a, Option<String>>

A tool is about to run. Some(reason) blocks it.

fn run_bash<'a>( &'a self, _handle: &'a Value, _command: &'a str, _cwd: &'a Path, _output: UnboundedSender<Vec<u8>>, _cancel: CancellationToken, ) -> BoxFuture<'a, Result<Option<i32>, String>>

Runs command in cwd through the operations its user_bash handler returned as handle, sending output to output, until the command ends or cancel fires, and returns the exit code.

fn refresh_models<'a>( &'a self, _registry: &'a ModelRegistry, _options: &'a RefreshOptions, ) -> BoxFuture<'a, Vec<(String, ModelList)>>

Refreshes the model lists of the providers it registered with refreshModels that options selects, as pi does: first offline with the registry’s runtime key or stored credential (ModelRegistry::read_credential), then, when options allow the network and a credential resolves, online with it. Then those with the legacy oauth.modifyModels project their models for the stored credential, and pi-ai Providers check their API key and filter their models for it. Returns each step’s update, or why it failed, by provider in order.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Extension for LlamaExtension

impl Extension for McpExtension

impl Extension for ToolSearchExtension