Struct BackgroundTasks 

pub struct BackgroundTasks { /* private fields */ }

Session-level background task table. Clone is cheap (inner Arc) — DefaultSession holds one copy, cloned to tools via ToolContext.

Implementations

impl BackgroundTasks

pub fn new( session_cancel: CancellationToken, progress_config: BackgroundProgressConfig, ) -> Self

Constructs a new instance with a session-level cancellation token and a progress-view configuration. session_cancel is owned by the session and is cancelled when the session terminates.

pub async fn wait_for_completion(&self)

Wait for a “task completion enqueued” event. The session driver uses this to drive proactive continuation.

Uses Notify: the driver first calls notified() to obtain a future, then checks the queue, then awaits — avoiding missed notifications that arrive between checks (Notify’s permit semantics guarantee that already-fired notifies are not lost).

pub fn has_completed(&self) -> bool

Whether there are completed results waiting to be collected. The driver checks this after waking up to decide whether to start a turn.

pub fn spawn<F, Fut>(&self, label: String, make_fut: F) -> String

where F: FnOnce(CancellationToken, TaskHandle) -> Fut, Fut: Future<Output = BackgroundResult> + Send + 'static,

Spawns a background task and returns its ID immediately.

make_fut receives two handles: a CancellationToken specific to this task (a child of the session-level token, which the task body should use to observe cancellation) and a TaskHandle (the task body shares its history Arc into the table via TaskHandle::attach_history, allowing the control plane to peek at the message chunks submitted to the LLM). On completion, the result is placed in the completed queue and the corresponding entry in the tasks table is marked as terminal (the entry is retained for later inspection).

The closure form that “receives token/handle and then creates the future” is used because both must be minted inside spawn, and the future needs to capture them — accepting a future directly would not allow obtaining a token whose lifetime is independent of the turn.

pub fn drain_completed(&self) -> Vec<BackgroundOutcome>

Drain all completed results (clears the queue). Called by run_turn before starting a turn to passively collect results.

pub fn running_count(&self) -> usize

Number of currently running tasks. Used for diagnostics / control plane.

pub fn list(&self) -> Vec<TaskSnapshot>

Returns a snapshot of all tasks (running + recently finished), without reading history (recent is empty, block_count is 0). Sorted by task ID in ascending order. Used by inspect_background_task when called without arguments.

pub fn peek( &self, id: &str, recent_blocks: Option<usize>, ) -> Option<TaskSnapshot>

Take a snapshot of a single task, including the most recent recent_blocks message blocks submitted to the LLM (None uses the config default). Returns None if the task does not exist (never spawned or already evicted); blocks are empty if the task does not expose history.

Implementation: clone the task’s history Arc while holding the table lock, then release the table lock before snapshotting (snapshotting uses the history’s own lock). This avoids performing a potentially expensive deep copy of history while holding the table lock, which would block spawn/finish.

pub fn cancel_task(&self, id: &str) -> Option<bool>

Cancel a single task early: cancels only its dedicated child token, without affecting other tasks.

Returns Some(true) if a running task was found and cancellation was requested; Some(false) if the task exists but is already in a terminal state (no-op); None if no such id exists. Cancellation is cooperative — the task body must observe its cancel token and exit; the status transitions to Canceled only when the task actually finishes.

pub fn cancel_all(&self)

Cancels all background tasks (called when the session ends). Idempotent.

Trait Implementations

impl Clone for BackgroundTasks

fn clone(&self) -> BackgroundTasks

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.