Trait BackgroundExecutable 

pub trait BackgroundExecutable: Tool {
    type PreparedBackground: Send + 'static;

    // Required methods
    fn task_type(&self) -> &str;
    fn prepare_background(
        &self,
        _args: &mut Value,
        _ctx: &ToolCallContext<'_>,
        _is_resume: bool,
    ) -> Result<Self::PreparedBackground, ToolResult>;
    fn execute_background<'life0, 'life1, 'async_trait>(
        &'life0 self,
        task_id: &'life1 str,
        args: Value,
        prepared: Self::PreparedBackground,
        execution: BackgroundExecutionContext,
        cancel_token: RunCancellationToken,
    ) -> Pin<Box<dyn Future<Output = TaskResult> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;

    // Provided methods
    fn supports_resume(&self) -> bool { ... }
    fn task_metadata(&self, _args: &Value) -> Value { ... }
    fn task_id_from_args(&self, _args: &Value) -> Option<String> { ... }
    fn set_task_id_in_args(&self, args: &mut Value, task_id: &str) { ... }
    fn task_description(&self, args: &Value) -> String { ... }
    fn execute_foreground<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        args: Value,
        ctx: &'life1 ToolCallContext<'life2>,
        _is_resume: bool,
    ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>
       where Self: Sync + 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn foreground_task_status(
        &self,
        result: &ToolResult,
    ) -> (TaskStatus, Option<String>) { ... }
}

Context-free background execution trait.

Tools implement this to opt into background execution support via BackgroundCapable. The wrapper handles persistence, resume, and background spawning — tools only implement execution logic.

Required Associated Types

type PreparedBackground: Send + 'static

Background-only prepared input computed before crossing the spawn boundary.

Required Methods

fn task_type(&self) -> &str

Task type label for persistence (e.g. "agent_run", "shell").

fn prepare_background( &self, _args: &mut Value, _ctx: &ToolCallContext<'_>, _is_resume: bool, ) -> Result<Self::PreparedBackground, ToolResult>

Validate and normalize arguments for background execution before any task state is persisted or spawned.

Tools can use this to perform the same semantic checks they enforce in foreground mode and to inject hidden, precomputed execution inputs that can safely cross the spawn boundary.

fn execute_background<'life0, 'life1, 'async_trait>( &'life0 self, task_id: &'life1 str, args: Value, prepared: Self::PreparedBackground, execution: BackgroundExecutionContext, cancel_token: RunCancellationToken, ) -> Pin<Box<dyn Future<Output = TaskResult> + Send + 'async_trait>>

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

Execute the tool logic in background mode.

Receives a task_id (new or resumed) and a cancellation token but NO ToolCallContext. Tools that need state access should capture what they need from args before the spawn boundary.

Provided Methods

fn supports_resume(&self) -> bool

Whether stopped tasks can be resumed with the same task_id.

fn task_metadata(&self, _args: &Value) -> Value

Metadata to persist alongside the task (e.g. agent_id, thread_id).

fn task_id_from_args(&self, _args: &Value) -> Option<String>

Extract an existing task_id from args (for resume/status queries). Return None for new tasks.

fn set_task_id_in_args(&self, args: &mut Value, task_id: &str)

Inject a generated task_id into the args before passing to execute. Default implementation sets args["task_id"].

fn task_description(&self, args: &Value) -> String

Human-readable task description for the background task listing.

fn execute_foreground<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, args: Value, ctx: &'life1 ToolCallContext<'life2>, _is_resume: bool, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

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

Execute the tool logic in foreground mode.

Tools can override this when foreground execution needs typed control data (for example, resume state) that should not be smuggled through hidden JSON fields.

fn foreground_task_status( &self, result: &ToolResult, ) -> (TaskStatus, Option<String>)

Derive the durable terminal task status for a foreground execution.

The default implementation treats tool-level errors as failed tasks and every other result as completed.

Implementors