Module cancel 

Cooperative, runtime-agnostic run cancellation.

In the recursive runtime a single CancellationToken can be shared down a tree of nested runs (a parent agent, its sub-agents, and their sub-graphs), so an orchestrator cancels an entire recursion with one cancel() and every level unwinds at its next safe checkpoint with crate::error::TinyAgentsError::Cancelled.

This module provides CancellationToken, a lightweight, self-contained cancellation primitive (an Arc<AtomicBool> paired with a tokio::sync::Notify) used to request that an in-flight harness run stop at its next safe checkpoint. It deliberately avoids pulling in a heavier dependency such as tokio-util: the harness only needs new/cancel/is_cancelled plus an async cancelled().await future, all of which are a few lines over the tokio sync feature already in the dependency tree.

Cooperative, not preemptive

Cancelling a token never aborts a running future. Instead the agent loop polls CancellationToken::is_cancelled at the same safe checkpoints it uses for steering — before each model call and before each tool call — and the streaming pipeline races CancellationToken::cancelled against the provider stream. On observing cancellation the run unwinds cleanly with crate::error::TinyAgentsError::Cancelled. This guarantees a token is never observed in the middle of a side-effecting tool call or a partially consumed provider stream chunk.

Example

use tinyagents::harness::cancel::CancellationToken;

let token = CancellationToken::new();
let waiter = token.clone();

// In another task, request cancellation.
token.cancel();

// The `cancelled` future resolves once cancellation is requested.
waiter.cancelled().await;
assert!(waiter.is_cancelled());

Structs

CancellationToken

A cheap, clonable handle used to request cooperative cancellation of a run.