mirror of
https://github.com/openai/codex.git
synced 2026-04-26 15:45:02 +00:00
258ba436f1
## Why `#16193` moved the pure `tool_search` and `tool_suggest` spec builders into `codex-tools`, but `codex-core` still owned the shared discoverable-tool model that those builders and the `tool_suggest` runtime both depend on. This change continues the migration by moving that reusable model boundary out of `codex-core` as well, so the discovery/suggestion stack uses one shared set of types and `core/src/tools` no longer needs its own `discoverable.rs` module. ## What changed - Moved `DiscoverableTool`, `DiscoverablePluginInfo`, and `filter_tool_suggest_discoverable_tools_for_client()` into `codex-rs/tools/src/tool_discovery.rs` alongside the extracted discovery/suggestion spec builders. - Added `codex-app-server-protocol` as a `codex-tools` dependency so the shared discoverable-tool model can own the connector-side `AppInfo` variant directly. - Updated `core/src/tools/handlers/tool_suggest.rs`, `core/src/tools/spec.rs`, `core/src/tools/router.rs`, `core/src/connectors.rs`, and `core/src/codex.rs` to consume the shared `codex-tools` model instead of the old core-local declarations. - Changed `core/src/plugins/discoverable.rs` to return `DiscoverablePluginInfo` directly, moved the pure client-filter coverage into `tool_discovery_tests.rs`, and deleted the old `core/src/tools/discoverable.rs` module. - Updated `codex-rs/tools/README.md` so the crate boundary documents that `codex-tools` now owns the discoverable-tool models in addition to the discovery/suggestion spec builders. ## Test plan - `cargo test -p codex-tools` - `CARGO_TARGET_DIR=/tmp/codex-core-discoverable-model cargo test -p codex-core --lib tools::handlers::tool_suggest::` - `CARGO_TARGET_DIR=/tmp/codex-core-discoverable-model cargo test -p codex-core --lib tools::spec::` - `CARGO_TARGET_DIR=/tmp/codex-core-discoverable-model cargo test -p codex-core --lib plugins::discoverable::` - `just bazel-lock-check` - `just argument-comment-lint` ## References - #16193 - #16154 - #15923 - #15928 - #15944 - #15953 - #16031 - #16047 - #16129 - #16132 - #16138 - #16141
101 lines
3.6 KiB
Markdown
101 lines
3.6 KiB
Markdown
# codex-tools
|
|
|
|
`codex-tools` is intended to become the home for tool-related code that is
|
|
shared across multiple crates and does not need to stay coupled to
|
|
`codex-core`.
|
|
|
|
Today this crate is intentionally small. It currently owns the shared tool
|
|
schema and Responses API tool primitives that no longer need to live in
|
|
`core/src/tools/spec.rs` or `core/src/client_common.rs`:
|
|
|
|
- `JsonSchema`
|
|
- `AdditionalProperties`
|
|
- `ToolDefinition`
|
|
- `ToolSpec`
|
|
- `ConfiguredToolSpec`
|
|
- `ResponsesApiTool`
|
|
- `FreeformTool`
|
|
- `FreeformToolFormat`
|
|
- `ToolSearchOutputTool`
|
|
- `ResponsesApiWebSearchFilters`
|
|
- `ResponsesApiWebSearchUserLocation`
|
|
- `ResponsesApiNamespace`
|
|
- `ResponsesApiNamespaceTool`
|
|
- code-mode `ToolSpec` adapters and `exec` / `wait` spec builders
|
|
- JS REPL spec builders
|
|
- MCP resource, `list_dir`, and `test_sync_tool` spec builders
|
|
- local host tool spec builders for shell/exec/request-permissions/view-image
|
|
- collaboration and agent-job `ToolSpec` builders for spawn/send/wait/close,
|
|
`request_user_input`, and CSV fanout/reporting
|
|
- discoverable-tool models, client filtering, and `ToolSpec` builders for
|
|
`tool_search` and `tool_suggest`
|
|
- `parse_tool_input_schema()`
|
|
- `parse_dynamic_tool()`
|
|
- `parse_mcp_tool()`
|
|
- `create_tools_json_for_responses_api()`
|
|
- `mcp_call_tool_result_output_schema()`
|
|
- `tool_definition_to_responses_api_tool()`
|
|
- `dynamic_tool_to_responses_api_tool()`
|
|
- `mcp_tool_to_responses_api_tool()`
|
|
- `mcp_tool_to_deferred_responses_api_tool()`
|
|
- `augment_tool_spec_for_code_mode()`
|
|
- `tool_spec_to_code_mode_tool_definition()`
|
|
|
|
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 tool-facing primitives that are shared by
|
|
multiple consumers, for example:
|
|
|
|
- schema and spec data models
|
|
- tool input/output parsing helpers
|
|
- tool metadata and compatibility shims that do not depend on `codex-core`
|
|
- other narrowly scoped utility code 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. Move low-coupling tool primitives here.
|
|
2. Switch non-core consumers to depend on `codex-tools` directly.
|
|
3. Leave compatibility-sensitive adapters in `codex-core` while downstream
|
|
call sites are updated.
|
|
4. Only extract higher-level tool infrastructure after the crate boundaries are
|
|
clear and independently testable.
|
|
|
|
That means it is normal for `codex-core` to temporarily re-export types or
|
|
helpers from `codex-tools` during the transition.
|
|
|
|
## 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.
|