42 lines
2.6 KiB
Markdown
42 lines
2.6 KiB
Markdown
# 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.
|