mirror of
https://github.com/openai/codex.git
synced 2026-05-21 03:33:41 +00:00
05e171094d
## Why `codex-tools` is meant to hold reusable tool primitives, but `ToolsConfig` had become a second copy of core runtime decisions instead of a small shared contract. It carried provider capabilities, auth/model gates, permission and environment state, web/search/image feature gates, multi-agent settings, and goal availability from core into `codex-tools` ([definition](22dd9ad392/codex-rs/tools/src/tool_config.rs (L97)), [stored on each `TurnContext`](22dd9ad392/codex-rs/core/src/session/turn_context.rs (L87))). Every session/context variant then had to build and mutate that snapshot before assembling tools. This PR removes that master object instead of renaming it. Tool planning now reads the live `TurnContext`, where `codex-core` already owns those decisions, while `codex-tools` keeps only reusable primitives and a generic `ToolSetBuilder`/`ToolSet` accumulator. ## What Changed - Removed `ToolsConfig` / `ToolsConfigParams` from `codex-tools`; the crate keeps the shared helpers that still belong there, including request-user-input mode selection, shell backend/type resolution, `UnifiedExecShellMode`, and `ToolEnvironmentMode`. - Replaced config-snapshot planning with `ToolRouter::from_turn_context` and a `spec_plan` pipeline over `CoreToolPlanContext`, deriving provider capabilities, auth gates, model support, feature gates, environment count, goal support, multi-agent options, web search, and image generation from the authoritative turn state. - Added generic `codex_tools::ToolSetBuilder` / `ToolSet`, plus the small core adapter needed to accumulate `CoreToolRuntime` values and hosted model specs. - Added the `tool_family::shell` registration module and moved shell/unified-exec/memory accounting call sites to read the narrow per-turn fields directly. - Narrowed `TurnContext` to the remaining explicit per-turn fields needed by planning: `available_models`, `unified_exec_shell_mode`, and `goal_tools_supported`. - Reworked MCP exposure and tool-search setup so deferred/direct MCP behavior is driven by the current turn rather than a precomputed config snapshot. - Replaced the large expected-spec fixture tests with focused behavior-level coverage for shell tools, environments, goal and agent-job gates, MCP direct/deferred exposure, tool search, request-plugin-install, code mode, multi-agent mode, hosted tools, and extension executor dispatch. ## Verification - `cargo check -p codex-tools` - `cargo check -p codex-core --lib` - `cargo test -p codex-tools` - `cargo test -p codex-core spec_plan --lib` - `cargo test -p codex-core router --lib`
75 lines
2.8 KiB
Markdown
75 lines
2.8 KiB
Markdown
# codex-tools
|
|
|
|
`codex-tools` is the shared support crate for building, adapting, and executing
|
|
model-visible tools outside `codex-core`.
|
|
|
|
Today this crate owns the host-facing tool models and helpers that no longer
|
|
need to live in `core/src/tools/spec.rs` or `core/src/client_common.rs`:
|
|
|
|
- aggregate host models such as `ToolSpec`, `ConfiguredToolSpec`,
|
|
`LoadableToolSpec`, `ResponsesApiNamespace`, and
|
|
`ResponsesApiNamespaceTool`
|
|
- host discovery models used while assembling tool sets, including
|
|
discoverable-tool models and request-plugin-install helpers
|
|
- host adapters such as schema sanitization, MCP/dynamic conversion, code-mode
|
|
augmentation, and image-detail normalization
|
|
- shared executable-tool contracts such as `ToolExecutor`, `ToolCall`, and
|
|
`ToolOutput`
|
|
|
|
That extraction is the first step in a longer migration. The goal is not to
|
|
move all of `core/src/tools` into this crate in one shot. Instead, the plan is
|
|
to peel off reusable pieces in reviewable increments while keeping
|
|
compatibility-sensitive orchestration in `codex-core` until the surrounding
|
|
boundaries are ready.
|
|
|
|
## Vision
|
|
|
|
Over time, this crate should hold host-side tool machinery that is shared by
|
|
multiple consumers, for example:
|
|
|
|
- host-visible aggregate tool models
|
|
- tool-set planning and discovery helpers
|
|
- MCP and dynamic-tool adaptation into Responses API shapes
|
|
- code-mode compatibility shims that do not depend on `codex-core`
|
|
- other narrowly scoped host utilities that multiple crates need
|
|
|
|
The corresponding non-goals are just as important:
|
|
|
|
- do not move `codex-core` orchestration here prematurely
|
|
- do not pull `Session` / `TurnContext` / approval flow / runtime execution
|
|
logic into this crate unless those dependencies have first been split into
|
|
stable shared interfaces
|
|
- do not turn this crate into a grab-bag for unrelated helper code
|
|
|
|
## Migration approach
|
|
|
|
The expected migration shape is:
|
|
|
|
1. Keep extension-owned executable-tool authoring in `codex-extension-api`.
|
|
2. Move host-side planning/adaptation helpers here when they no longer need to
|
|
stay coupled to `codex-core`.
|
|
3. Leave compatibility-sensitive adapters in `codex-core` while downstream
|
|
call sites are updated.
|
|
4. Only extract higher-level host infrastructure after the crate boundaries are
|
|
clear and independently testable.
|
|
|
|
## Crate conventions
|
|
|
|
This crate should start with stricter structure than `core/src/tools` so it
|
|
stays easy to grow:
|
|
|
|
- `src/lib.rs` should remain exports-only.
|
|
- Business logic should live in named module files such as `foo.rs`.
|
|
- Unit tests for `foo.rs` should live in a sibling `foo_tests.rs`.
|
|
- The implementation file should wire tests with:
|
|
|
|
```rust
|
|
#[cfg(test)]
|
|
#[path = "foo_tests.rs"]
|
|
mod tests;
|
|
```
|
|
|
|
If this crate starts accumulating code that needs runtime state from
|
|
`codex-core`, that is a sign to revisit the extraction boundary before adding
|
|
more here.
|