Trait Builtin 

pub trait Builtin: Send + Sync {
    // Required method
    fn execute<'life0, 'life1, 'async_trait>(
        &'life0 self,
        ctx: Context<'life1>,
    ) -> Pin<Box<dyn Future<Output = Result<ExecResult>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;

    // Provided methods
    fn execution_plan<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _ctx: &'life1 Context<'life2>,
    ) -> Pin<Box<dyn Future<Output = Result<Option<ExecutionPlan>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn llm_hint(&self) -> Option<&'static str> { ... }
}

Trait for implementing builtin commands.

All custom builtins must implement this trait. The trait requires Send + Sync for thread safety in async contexts.

Example

use bashkit::{Bash, Builtin, BuiltinContext, ExecResult, async_trait};

struct Greet {
    default_name: String,
}

#[async_trait]
impl Builtin for Greet {
    async fn execute(&self, ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
        let name = ctx.args.first()
            .map(|s| s.as_str())
            .unwrap_or(&self.default_name);
        Ok(ExecResult::ok(format!("Hello, {}!\n", name)))
    }
}

// Register the builtin
let bash = Bash::builder()
    .builtin("greet", Box::new(Greet { default_name: "World".into() }))
    .build();

LLM Hints

Builtins can provide short hints for LLM system prompts via llm_hint. These appear in the tool’s help() and system_prompt() output so LLMs know about capabilities and limitations.

Return Values

Return ExecResult::ok for success with output, or ExecResult::err for errors with exit code.

Required Methods

fn execute<'life0, 'life1, 'async_trait>( &'life0 self, ctx: Context<'life1>, ) -> Pin<Box<dyn Future<Output = Result<ExecResult>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Execute the builtin command.

Arguments

• ctx - The execution context containing arguments, environment, and filesystem

Returns

• Ok(ExecResult) - Execution result with stdout, stderr, and exit code
• Err(Error) - Fatal error that should abort execution

Provided Methods

fn execution_plan<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _ctx: &'life1 Context<'life2>, ) -> Pin<Box<dyn Future<Output = Result<Option<ExecutionPlan>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Return an execution plan for sub-command execution.

Builtins that need to execute other commands (e.g. timeout, xargs, find -exec) override this to return an ExecutionPlan. The interpreter fulfills the plan by executing the sub-commands and returning results.

When this returns Some(plan), the interpreter ignores the execute() result and instead runs the plan. When None, normal execute() is used.

The default implementation returns Ok(None).

fn llm_hint(&self) -> Option<&'static str>

Optional short hint for LLM system prompts.

Return a concise one-line description of capabilities and limitations. These hints are included in help() and system_prompt() output when the builtin is registered.

Example

fn llm_hint(&self) -> Option<&'static str> {
    Some("mycommand: Processes data files. Max 10MB input. No network access.")
}

Implementations on Foreign Types

impl Builtin for Arc<dyn Builtin>

fn execute<'life0, 'life1, 'async_trait>( &'life0 self, ctx: Context<'life1>, ) -> Pin<Box<dyn Future<Output = Result<ExecResult>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn execution_plan<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, ctx: &'life1 Context<'life2>, ) -> Pin<Box<dyn Future<Output = Result<Option<ExecutionPlan>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

fn llm_hint(&self) -> Option<&'static str>

Implementors