mirror of https://github.com/pchuan98/codex.git synced 2026-07-01 00:31:56 +08:00

Files

T

mchen-oai af99f6a72f core: cache the tool search handler per session (#27258 )

## Why

Tool router construction rebuilds the deferred-tool BM25 index during
session initialization and before each sampling continuation, even when
the searchable tool metadata is unchanged. Local profiling measured
`append_tool_search_executor` at roughly 113 ms per continuation, making
repeated index construction the largest measured router-building cost.

## What changed

- Add a session-scoped `ToolSearchHandlerCache` so continuations and
user turns can reuse the existing handler.
- Key reuse on the complete ordered `Vec<ToolSearchInfo>`, rebuilding
when searchable text, loadable tool specs, source metadata, or ordering
changes.
- Build handlers outside the cache lock and recheck before publishing
them, avoiding holding the mutex during index construction.

## Verification

- `cache_reuses_identical_search_infos_and_rebuilds_changed_inputs`
covers exact cache reuse and invalidation when the ordered search
metadata changes.
- Local rollout profiling showed the initial router build populating the
cache and unchanged later continuations reusing it:
  - uncached: 118 ms median across 14 spans from 3 rollouts
  - cached: 4 ms median across 12 spans from 3 rollouts

af99f6a72f · 2026-06-15 14:48:30 -07:00

History

src

core: cache the tool search handler per session (#27258 )

2026-06-15 14:48:30 -07:00

tests

feat: support oneOf and allOf in tool input schemas (#24118 )

2026-06-08 21:41:05 +00:00

BUILD.bazel

[codex] Move tool specs into core handlers (#21416 )

2026-05-06 15:40:50 -07:00

Cargo.toml

Route image extension reads through turn environments v2 (#27498 )

2026-06-11 16:32:52 -07:00

README.md

Remove ToolsConfig from tool planning (#22835 )

2026-05-19 11:24:09 +02:00

README.md

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:

Keep extension-owned executable-tool authoring in codex-extension-api.
Move host-side planning/adaptation helpers here when they no longer need to stay coupled to codex-core.
Leave compatibility-sensitive adapters in codex-core while downstream call sites are updated.
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:

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