mirror of https://github.com/openai/codex.git synced 2026-04-26 15:45:02 +00:00

Files

Michael Bolin 4e27a87ec6 codex-tools: extract configured tool specs (#16129 )

## Why

This continues the `codex-tools` migration by moving another passive
tool-spec layer out of `codex-core`.

After `ToolSpec` moved into `codex-tools`, `codex-core` still owned
`ConfiguredToolSpec` and `create_tools_json_for_responses_api()`. Both
are data-model and serialization helpers rather than runtime
orchestration, so keeping them in `core/src/tools/registry.rs` and
`core/src/tools/spec.rs` left passive tool-definition code coupled to
`codex-core` longer than necessary.

## What changed

- moved `ConfiguredToolSpec` into `codex-rs/tools/src/tool_spec.rs`
- moved `create_tools_json_for_responses_api()` into
`codex-rs/tools/src/tool_spec.rs`
- re-exported the new surface from `codex-rs/tools/src/lib.rs`, which
remains exports-only
- updated `core/src/client.rs`, `core/src/tools/registry.rs`, and
`core/src/tools/router.rs` to consume the extracted types and serializer
from `codex-tools`
- moved the tool-list serialization test into
`codex-rs/tools/src/tool_spec_tests.rs`
- added focused unit coverage for `ConfiguredToolSpec::name()`
- simplified `core/src/tools/spec_tests.rs` to use the extracted
`ConfiguredToolSpec::name()` directly and removed the now-redundant
local `tool_name()` helper
- updated `codex-rs/tools/README.md` so the crate boundary reflects the
newly extracted tool-spec wrapper and serialization helper

## Test plan

- `cargo test -p codex-tools`
- `CARGO_TARGET_DIR=/tmp/codex-core-configured-spec cargo test -p
codex-core --lib tools::spec::`
- `CARGO_TARGET_DIR=/tmp/codex-core-configured-spec cargo test -p
codex-core --lib client::`
- `just fix -p codex-tools -p codex-core`
- `just argument-comment-lint`

## References

- #15923
- #15928
- #15944
- #15953
- #16031
- #16047

2026-03-28 14:24:14 -07:00

3.0 KiB

Raw Blame History

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
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()

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:

Move low-coupling tool primitives here.
Switch non-core consumers to depend on codex-tools directly.
Leave compatibility-sensitive adapters in codex-core while downstream call sites are updated.
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:

#[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.

3.0 KiB Raw Blame History

codex-tools

Vision

Migration approach

Crate conventions

3.0 KiB

Raw Blame History