codex_tools/
tool_executor.rs

1use crate::FunctionCallError;
2use crate::ToolName;
3use crate::ToolOutput;
4use crate::ToolSearchInfo;
5use crate::ToolSpec;
6use std::future::Future;
7use std::pin::Pin;
8
9/// The boxed future returned by [`ToolExecutor::handle`].
10pub type ToolExecutorFuture<'a> =
11    Pin<Box<dyn Future<Output = Result<Box<dyn ToolOutput>, FunctionCallError>> + Send + 'a>>;
12
13/// Controls where a tool is exposed to the model.
14#[derive(Clone, Copy, Debug, Eq, PartialEq)]
15pub enum ToolExposure {
16    /// Include this tool in the initial model-visible tool list.
17    ///
18    /// When code mode is enabled, this tool is also available as a nested
19    /// code-mode tool.
20    Direct,
21
22    /// Register this tool for later discovery, but omit it from the initial
23    /// model-visible tool list. Deferred tools must provide search metadata via
24    /// [`ToolExecutor::search_info`]. The default implementation derives
25    /// metadata from function and namespace specs.
26    Deferred,
27
28    /// Include this tool in the initial model-visible tool list only.
29    ///
30    /// In code-mode-only sessions, this keeps the tool callable as a normal
31    /// model tool while excluding it from the nested code-mode tool surface.
32    DirectModelOnly,
33
34    /// Keep this tool registered for dispatch without exposing it to the model.
35    Hidden,
36}
37
38impl ToolExposure {
39    pub fn is_direct(self) -> bool {
40        matches!(self, Self::Direct | Self::DirectModelOnly)
41    }
42}
43
44/// Shared runtime contract for model-visible tools.
45///
46/// Implementations keep the model-visible spec tied to the executable runtime.
47/// Host crates can layer routing, hooks, telemetry, or other orchestration on
48/// top without reopening the spec/runtime split.
49pub trait ToolExecutor<Invocation>: Send + Sync {
50    /// The concrete tool name handled by this runtime instance.
51    fn tool_name(&self) -> ToolName;
52
53    fn spec(&self) -> ToolSpec;
54
55    fn exposure(&self) -> ToolExposure {
56        ToolExposure::Direct
57    }
58
59    fn search_info(&self) -> Option<ToolSearchInfo> {
60        let spec = self.spec();
61        ToolSearchInfo::from_tool_spec(spec, /*source_info*/ None)
62    }
63
64    fn supports_parallel_tool_calls(&self) -> bool {
65        false
66    }
67
68    fn handle(&self, invocation: Invocation) -> ToolExecutorFuture<'_>;
69}
codex_tools/tool_executor.rs

codex_tools/
tool_executor.rs
