Sleep Tool Design

Goal

Add a model-callable sleep tool that pauses the current agent tool call for a requested number of whole seconds. This first version only waits in process and does not schedule durable or background work.

Interface

Tool name: sleep
Arguments: an object with one required seconds field
seconds must be an integer from 0 through 86400 inclusive
The maximum foreground wait is 24 hours
0 is valid and completes immediately
Unknown object fields are ignored consistently with existing native tools

Invalid, missing, negative, fractional, or values above 86400 return an ordinary unsuccessful ToolResult. A successful call returns Slept for N second(s)., with the requested duration substituted for N.

Implementation

Create a stateless SleepTool in src/tools/sleep.rs. Its Tool::execute implementation validates seconds, waits on one bounded Tokio timer, and returns success after the full duration. The asynchronous timer does not block the Gateway runtime.

Export the type from src/tools/mod.rs and register it in create_default_tools, making it available to the root agent and to constrained tool registries unless those registries explicitly filter it by name.

The tool does not persist state, create a background task, or send messages. It retains the Tool trait's default non-concurrency-safe classification, so a model response containing sleep and other calls executes that batch sequentially. /stop, supervisor shutdown, scheduler timeout, and sub-agent timeout cancel work by dropping the surrounding agent execution future; dropping that future also drops the current Tokio sleep timer. When a Turn is cancelled, every still-running tool block is normalized to ToolStatus::Cancelled before publishing the terminal snapshot.

The 24-hour cap bounds foreground resource retention. Longer or restart-durable waits must use Scheduler or background work rather than holding an interactive session worker.

Testing

Unit tests cover the tool metadata and schema, immediate success for zero seconds, elapsed-time behavior using Tokio's paused clock, rejection of missing, negative, fractional, string, and over-24-hour values, acceptance of the 24-hour boundary, cancellation of an active sleeping task, and Turn cancellation normalization.

Run the targeted tests, cargo test --lib, cargo clippy --all-targets --all-features -- -D warnings, and cargo build.

Out Of Scope

Slash commands or direct user invocation
Durable sleeps that survive process restart
Delayed or scheduled message delivery
A configurable duration limit

This change increments only the product patch version.

2.6 KiB Raw Blame History