fluers_core/
request.rs

1//! Request-scoped tool construction.
2//!
3//! The dev server (and any host that serves many agent runs) must build some
4//! tools **per request** because they carry per-run state — most notably the
5//! built-in `task` tool ([`crate::subagent::TaskTool`]), which owns the run's
6//! cancellation token, event sink, and delegation budget. Reusing one across
7//! requests would cross-wire cancellation and events between concurrent runs.
8//!
9//! [`ToolRequestContext`] bundles exactly the per-run inputs a tool factory
10//! needs, and [`ToolFactory`] is the type-erased closure a host stores to turn
11//! that context into a concrete tool list. See `docs/DEV_CONFIG_UX_DESIGN.md`.
12
13use std::sync::Arc;
14
15use tokio_util::sync::CancellationToken;
16
17use crate::event::EventSink;
18use crate::model::{Model, ModelProvider};
19use crate::runner::RunConfig;
20use crate::tool::Tool;
21
22/// Inputs needed to build a single request's tool list. Passed **by value**
23/// into a [`ToolFactory`] so the factory can construct request-local tools
24/// (e.g. a fresh top-level `TaskTool` bound to this run's cancel token + sink).
25///
26/// The `provider` / `parent_model` / `parent_config` are the agent's values
27/// (the same for every request of that agent); only `cancel` + `event_sink`
28/// vary per request. They are bundled together so the factory signature stays
29/// a single argument.
30#[derive(Clone)]
31pub struct ToolRequestContext {
32    /// The model provider (shared, stateless — safe to reuse across requests).
33    pub provider: Arc<dyn ModelProvider>,
34    /// The parent agent's model id. Inherited by subagents that omit their own.
35    pub parent_model: Model,
36    /// The parent agent's run config. Inherited by subagents that omit their own.
37    pub parent_config: RunConfig,
38    /// This run's cancellation token. Children inherit it via the `TaskTool`.
39    pub cancel: CancellationToken,
40    /// This run's event sink (OTel / tracing). Children emit to the same sink.
41    pub event_sink: Option<Arc<dyn EventSink>>,
42}
43
44/// Builds the full tool list for a single request.
45///
46/// Stored on a server's agent handle; when set, it takes precedence over any
47/// static tool list. The closure must be `Send + Sync` (called concurrently
48/// from many request tasks) and `Clone`-cheap (it is an `Arc`).
49pub type ToolFactory = Arc<dyn Fn(ToolRequestContext) -> Vec<Arc<dyn Tool>> + Send + Sync>;
fluers_core/request.rs

fluers_core/
request.rs
