Add built-in namespace guidance and budget tool description prefixes (#62534)

## Why

Namespace-wide guidance can repeat on every entry in flat Code Mode listings. The existing prefix limit covers only reachable `functions` tools, leaving indirect namespace guidance outside the budget.

## What changed

- Add `builtin_tool_namespaces` to put guidance on namespace headers in Code Mode prompts and tool search responses, including headers shared with client tools. The selector applies to namespaces with a registered built-in tool and is omitted from flat listings. Overlapping selectors must agree after trimming.
- Validate all four prefix maps together against the selected model's `description_prefix_budget_bytes`, which defaults to 512. Count each trimmed value once in UTF-8 bytes, including unused selectors. Exclude keys, paragraph separators, and rendered copies.

## Testing

Cover shared headers, flat listings, and conflicting selectors. Exercise the default budget boundary with multibyte text and verify that a model can raise the limit.

GitOrigin-RevId: 1570c23ea1dbad6041cc8e48d0dc2b77f92596c7
This commit is contained in:
tongzhou wang
2026-11-19 15:31:33 +00:00
committed by copyberry
parent dabe0643a4
commit 27e16c08c3
13 changed files with 403 additions and 179 deletions
@@ -5,7 +5,6 @@ use crate::tools::context::boxed_tool_output;
use crate::tools::registry::CoreToolRuntime;
use crate::tools::registry::ToolExecutor;
use codex_prompts::ResolvedModelMessages;
use codex_tools::IndirectNamespacePrefixes;
use codex_tools::ToolName;
use codex_tools::ToolSpec;
use std::borrow::Cow;
@@ -70,12 +69,11 @@ impl CodeModeExecuteHandler {
enabled_tools.sort_by(|left, right| left.name.cmp(&right.name));
enabled_tools.dedup_by(|left, right| left.name == right.name);
let model_messages = ResolvedModelMessages::from_model(&step_context.settings.model_info);
IndirectNamespacePrefixes::new(
model_messages.indirect_description_prefixes(),
step_context.tool_router.mcp_namespaces(),
)
.map_err(|error| FunctionCallError::Fatal(error.to_string()))?
.apply_code_mode(&mut enabled_tools);
step_context
.tool_router
.indirect_namespace_prefixes(model_messages.indirect_description_prefixes())
.map_err(|error| FunctionCallError::Fatal(error.to_string()))?
.apply_code_mode(&mut enabled_tools);
let started_at = std::time::Instant::now();
let started_cell = exec
.session
+11 -17
View File
@@ -243,11 +243,10 @@ impl ToolSearchHandler {
}
let model_messages = ResolvedModelMessages::from_model(&step_context.settings.model_info);
let indirect_prefixes = IndirectNamespacePrefixes::new(
model_messages.indirect_description_prefixes(),
step_context.tool_router.mcp_namespaces(),
)
.map_err(|error| FunctionCallError::Fatal(error.to_string()))?;
let indirect_prefixes = step_context
.tool_router
.indirect_namespace_prefixes(model_messages.indirect_description_prefixes())
.map_err(|error| FunctionCallError::Fatal(error.to_string()))?;
if nested {
let tools = self.search_code_mode(
@@ -388,15 +387,12 @@ mod tests {
let replacement = cache.get_or_build(&replacement_registry, ToolSearchSourceListing::Omit);
assert!(!Arc::ptr_eq(&without_sources, &replacement));
registry
.apply_functions_namespace_function_prefixes(
Some(&std::collections::BTreeMap::from([(
"create_event".to_string(),
"Guidance.".to_string(),
)])),
[ToolName::plain("create_event")],
)
.expect("valid function prefixes");
registry.apply_functions_namespace_function_prefixes(Some(
&std::collections::BTreeMap::from([(
"create_event".to_string(),
"Guidance.".to_string(),
)]),
));
let prefixed = cache.get_or_build(&registry, ToolSearchSourceListing::Include);
let reused = cache.get_or_build(&registry, ToolSearchSourceListing::Include);
assert!(Arc::ptr_eq(&prefixed, &reused));
@@ -413,9 +409,7 @@ mod tests {
};
tool.description = format!("Guidance.\n\n{}", tool.description);
assert_eq!(prefixed.search("Create events", /*limit*/ 1), expected);
registry
.apply_functions_namespace_function_prefixes(/*prefixes*/ None, [])
.expect("clear prefixes");
registry.apply_functions_namespace_function_prefixes(/*prefixes*/ None);
let cleared = cache.get_or_build(&registry, ToolSearchSourceListing::Include);
assert_eq!(
cleared.search("Create events", /*limit*/ 1),
+31 -6
View File
@@ -487,21 +487,31 @@ impl ToolRegistry {
}
}
/// Apply catalog prefixes to this step's specs, budgeting only reachable tools.
/// The planner supplies the names; this does not change execution or exposure.
/// Prepare registered functions and the exec/wait wrappers added later in the plan.
pub(crate) fn apply_functions_namespace_function_prefixes(
&mut self,
prefixes: Option<&BTreeMap<String, String>>,
available_tools: impl IntoIterator<Item = ToolName>,
) -> Result<(), &'static str> {
let prefixes = FunctionsNamespaceFunctionPrefixes::new(prefixes, available_tools)?;
) {
let registered = self
.tools
.iter()
.filter(|(_, tool)| tool.exposure != ToolExposure::Hidden)
.map(|(name, _)| name.clone());
let wrappers = [
codex_code_mode::PUBLIC_TOOL_NAME,
codex_code_mode::WAIT_TOOL_NAME,
]
.into_iter()
.map(ToolName::plain)
.filter(|name| self.tool_policy.allows(name));
let prefixes =
FunctionsNamespaceFunctionPrefixes::new(prefixes, registered.chain(wrappers));
for tool in self.tools.values_mut() {
tool.model_spec = prefixes
.prepare(&tool.runtime.tool_name(), || tool.runtime.spec())
.map(Arc::new);
}
self.functions_namespace_function_prefixes = prefixes;
Ok(())
}
fn prepare_tool(
@@ -671,6 +681,21 @@ impl ToolRegistry {
self.tools.values_mut()
}
pub(crate) fn indirect_namespace_prefixes<'a>(
&self,
prefixes: Option<&'a codex_protocol::openai_models::IndirectDescriptionPrefixes>,
) -> Result<
codex_tools::IndirectNamespacePrefixes<'a>,
codex_tools::IndirectNamespacePrefixConflict,
> {
let builtin_tools = self
.tools
.iter()
.filter(|(_, tool)| !tool.runtime.is_third_party_tool())
.map(|(name, _)| name);
codex_tools::IndirectNamespacePrefixes::new(prefixes, self.mcp_namespaces(), builtin_tools)
}
/// Returns configured MCP server names and their registered callable namespaces.
pub(crate) fn mcp_namespaces(&self) -> impl Iterator<Item = (&str, &str)> {
self.tools.iter().filter_map(|(name, tool)| {
+8 -2
View File
@@ -240,8 +240,14 @@ impl ToolRouter {
self.registry.deferred_tool_namespaces()
}
pub(crate) fn mcp_namespaces(&self) -> impl Iterator<Item = (&str, &str)> {
self.registry.mcp_namespaces()
pub(crate) fn indirect_namespace_prefixes<'a>(
&self,
prefixes: Option<&'a codex_protocol::openai_models::IndirectDescriptionPrefixes>,
) -> Result<
codex_tools::IndirectNamespacePrefixes<'a>,
codex_tools::IndirectNamespacePrefixConflict,
> {
self.registry.indirect_namespace_prefixes(prefixes)
}
#[cfg(test)]
+10 -74
View File
@@ -406,6 +406,10 @@ pub(crate) fn finalize_tool_router(
tool_search_handler_cache: &ToolSearchHandlerCache,
) -> CodexResult<ToolRouter> {
let model_messages = ResolvedModelMessages::from_model(model_info);
model_messages
.validate_description_prefix_budget()
.map_err(CodexErrorDetails::InvalidRequest)?;
hosted_specs.retain(|spec| registry.tool_policy.allows(&ToolName::plain(spec.name())));
apply_direct_model_only_namespace_overrides(turn_context, &mut registry);
enforce_strict_3p_tools(turn_context, model_info, &mut registry);
@@ -476,12 +480,9 @@ pub(crate) fn finalize_tool_router(
}
}
prepare_function_description_prefixes(
turn_context,
model_info,
&mut registry,
search_exposure,
)?;
registry.apply_functions_namespace_function_prefixes(
model_messages.functions_namespace_functions_description_prefixes(),
);
if let Some(exposure) = search_exposure {
append_tool_search_executor(
@@ -492,11 +493,9 @@ pub(crate) fn finalize_tool_router(
);
}
let indirect_prefixes = IndirectNamespacePrefixes::new(
model_messages.indirect_description_prefixes(),
registry.mcp_namespaces(),
)
.map_err(|error| CodexErrorDetails::InvalidRequest(error.to_string()))?;
let indirect_prefixes = registry
.indirect_namespace_prefixes(model_messages.indirect_description_prefixes())
.map_err(|error| CodexErrorDetails::InvalidRequest(error.to_string()))?;
let (code_mode_tool_names, exec_definitions) =
register_code_mode_executors(turn_context, model_info, &mut registry, &indirect_prefixes);
let include_tool_namespaces_info = turn_context
@@ -923,69 +922,6 @@ fn is_excluded_from_code_mode(turn_context: &TurnContext, tool_name: &ToolName)
})
}
fn prepare_function_description_prefixes(
turn_context: &TurnContext,
model_info: &ModelInfo,
registry: &mut ToolRegistry,
search_exposure: Option<ToolExposure>,
) -> CodexResult<()> {
let model_messages = ResolvedModelMessages::from_model(model_info);
let prefixes = model_messages.functions_namespace_functions_description_prefixes();
let mut available_tools = Vec::new();
if prefixes.is_some_and(|prefixes| !prefixes.is_empty()) {
let code_mode_enabled = matches!(
effective_tool_mode(turn_context, model_info),
ToolMode::CodeMode | ToolMode::CodeModeOnly
);
let search_name = ToolName::plain(TOOL_SEARCH_TOOL_NAME);
let search_visible = search_exposure.is_some_and(|exposure| {
!is_hidden_by_code_mode_only(turn_context, model_info, &search_name, exposure)
|| (code_mode_enabled
&& registry
.tool_policy
.allows(&ToolName::plain(codex_code_mode::PUBLIC_TOOL_NAME))
&& turn_context
.config
.features
.enabled(Feature::CodeModeToolSearch)
&& exposure.is_available_in_code_mode()
&& !is_excluded_from_code_mode(turn_context, &search_name))
});
available_tools.extend(
registry
.entries()
.filter(|tool| {
is_directly_visible(turn_context, model_info, tool)
|| (search_visible
&& tool.exposure.is_deferred()
&& tool.runtime.search_info().is_some())
})
.map(|tool| tool.runtime.tool_name()),
);
available_tools.extend(
code_mode_tools(turn_context, model_info, registry)
.map(|(_, _, tool)| tool.runtime.tool_name()),
);
// These wrappers are generated after their inner descriptions are ready.
if code_mode_enabled {
available_tools.extend(
[
codex_code_mode::PUBLIC_TOOL_NAME,
codex_code_mode::WAIT_TOOL_NAME,
]
.into_iter()
.map(ToolName::plain)
.filter(|name| registry.tool_policy.allows(name)),
);
}
}
registry
.apply_functions_namespace_function_prefixes(prefixes, available_tools)
.map_err(|error| CodexErrorDetails::InvalidRequest(error.to_owned()).into())
}
/// Select the same nested tools for prefix budgeting and Code Mode construction.
/// A registered tool alone is not reachable when policy disallows the exec wrapper.
fn code_mode_tools<'a>(
turn_context: &'a TurnContext,
model_info: &'a ModelInfo,
+23 -3
View File
@@ -8870,12 +8870,18 @@ async fn code_mode_search_normalizes_and_calls_deferred_dynamic_tools(
.with_model_info_override("gpt-5.5", |model_info| {
model_info.supports_search_tool = true;
model_info.tool_mode = Some(ToolMode::CodeMode);
model_info
let tools = model_info
.model_messages
.get_or_insert_default()
.tools
.get_or_insert_default()
.functions_namespace_functions_description_prefixes =
.get_or_insert_default();
tools.indirect_description_prefixes = Some(
serde_json::from_value(serde_json::json!({
"builtin_tool_namespaces": {"functions": "Builtin."}
}))
.unwrap(),
);
tools.functions_namespace_functions_description_prefixes =
Some(std::collections::BTreeMap::from([(
"hidden-dynamic-tool".to_string(),
"Function guidance.".to_string(),
@@ -8943,6 +8949,9 @@ const out = await tools[tool.name]({ city: "Paris" });
text(
JSON.stringify({
name: tool?.name ?? null,
builtinLabel: ALL_TOOLS.find(t => t.name === "view_image").description.startsWith("Builtin.\n\n"),
dynamicLabel: ALL_TOOLS.find(t => t.name === tool.name).description.includes("Builtin."),
searchLabel: tool.description.includes("Builtin."),
description: tool?.description ?? null,
out,
recoveredFromInvalidArguments: errors.length === 2,
@@ -9062,6 +9071,9 @@ text(
Some(&Value::String("hidden-ok".to_string()))
);
assert_eq!(parsed["recoveredFromInvalidArguments"], true);
assert_eq!(parsed["builtinLabel"], false);
assert_eq!(parsed["dynamicLabel"], false);
assert_eq!(parsed["searchLabel"], false);
let loaded = search_response.single_request().tool_search_output("find");
let loaded = loaded["tools"]
.as_array()
@@ -9069,6 +9081,14 @@ text(
.iter()
.find(|tool| tool["name"] == namespace)
.expect("loaded namespace");
assert_eq!(
loaded["description"],
if namespace == "functions" {
"Builtin.\n\nCodex app tools."
} else {
"Codex app tools."
}
);
assert_eq!(
loaded["tools"][0]["description"],
if namespace == "functions" {
@@ -63,6 +63,34 @@ async fn catalog_namespace_prefixes_follow_the_selected_model(
)]))
.expect("MCP fixture allowed");
});
if include_search {
// Four maps contribute 508 + 1 + 1 + 1 + 1 bytes. Count both matching
// MCP selectors and the unused built-in selector, regardless of rendered copies.
for (slug, extra, limit) in [
("prefixes-at-budget", "", None),
("prefixes-over-budget", "x", None),
("prefixes-raised-budget", "x", Some(513)),
] {
builder = builder.with_model_info_override(slug, move |model| {
model.tool_mode = Some(tool_mode);
model.supports_search_tool = true;
model.model_messages.as_mut().expect("model messages").tools = Some(
serde_json::from_value(json!({
"description_prefix_budget_bytes": limit,
"functions_namespace_functions_description_prefixes": {
"exec": format!(" {}{extra} ", "é".repeat(254)), "view_image": "v"
},
"indirect_description_prefixes": {
"namespaces": {"mcp__reports_one": "m"},
"builtin_tool_namespaces": {"unavailable": "b"},
"mcp_servers": {"reports.one": "m"}
}
}))
.expect("prefix budget catalog"),
);
});
}
}
for (slug, prefixes, mcp_prefix) in [
(
"prefixes-conflicting",
@@ -74,14 +102,7 @@ async fn catalog_namespace_prefixes_follow_the_selected_model(
json!({"functions": "", "collaboration": ""}),
"",
),
(
"gpt-5.5",
json!({
"functions": " Functions context. ",
"collaboration": "Agents context.",
}),
"Reports context.",
),
("gpt-5.5", json!({}), "Reports context."),
] {
builder = builder.with_model_info_override(slug, move |model| {
model.tool_mode = Some(tool_mode);
@@ -95,6 +116,10 @@ async fn catalog_namespace_prefixes_follow_the_selected_model(
} else { json!({}) },
"indirect_description_prefixes": {
"namespaces": prefixes,
"builtin_tool_namespaces": if slug == "gpt-5.5" {
json!({"functions": "Functions context.", "collaboration": "Agents context.",
"mcp__reports_one": "Built-ins only."})
} else { json!({}) },
"mcp_servers": {"reports.one": mcp_prefix},
},
}))
@@ -231,20 +256,18 @@ text({descriptions, echo: report.structuredContent.echo, agent: agents.agents[0]
.as_str()
.expect("tool description")
));
for (index, prefix) in prefixes.iter().enumerate() {
expected["descriptions"][index] = json!(format!(
"{prefix}\n\n{}",
expected["descriptions"][index]
.as_str()
.expect("tool description")
));
}
expected["descriptions"][2] = json!(format!(
"Reports context.\n\n{}",
expected["descriptions"][2]
.as_str()
.expect("MCP tool description")
));
assert_eq!(outputs[0], expected);
if tool_mode == ToolMode::CodeModeOnly {
insta::assert_snapshot!(
"catalog_indirect_namespace_prefixes",
context_snapshot::format_request_history_snapshot(
"Function prefixes annotate direct and indirect tools; namespace prefixes annotate embedded namespace docs, loaded namespaces, and flat indirect entries. A model switch clears both without changing dispatch.",
"Function prefixes annotate individual tools. Built-in namespace prefixes annotate headers. MCP guidance also appears in flat entries. A model switch clears both without changing dispatch.",
&requests,
&ContextSnapshotOptions::default()
.rewrite_known_segments()
@@ -291,6 +314,51 @@ text({descriptions, echo: report.structuredContent.echo, agent: agents.agents[0]
"conflicting prefixes must fail before another model request",
);
}
if include_search {
for (slug, accepted) in [
("prefixes-at-budget", true),
("prefixes-raised-budget", true),
("prefixes-over-budget", false),
] {
let mock = responses::mount_sse_once(
&server,
responses::sse(vec![
responses::ev_assistant_message("budget", "Done."),
responses::ev_completed("budget"),
]),
)
.await;
test.codex
.start_or_steer_turn(
TurnInputRequest::user_input(vec![UserInput::Text {
text: "Check the prefix budget.".into(),
text_elements: vec![],
}])
.with_thread_settings(ThreadSettingsOverrides {
model: Some(slug.into()),
..Default::default()
}),
)
.await?;
let EventMsg::TurnComplete(completed) = wait_for_event(&test.codex, |event| {
matches!(event, EventMsg::TurnComplete(_))
})
.await
else {
unreachable!()
};
if accepted {
assert_eq!(completed.error, None);
assert_eq!(mock.requests().len(), 1);
} else {
assert_eq!(
completed.error.expect("over budget").message,
"Model catalog tool description prefixes total 513 UTF-8 bytes, exceeding description_prefix_budget_bytes (512)"
);
assert!(mock.requests().is_empty());
}
}
}
test.codex.shutdown_and_wait().await?;
Ok(())
}
@@ -1,8 +1,8 @@
---
source: core/tests/suite/scenarios_indirect_namespace_prefixes.rs
expression: "context_snapshot::format_request_history_snapshot(\"Function prefixes annotate direct and indirect tools; namespace prefixes annotate embedded namespace docs, loaded namespaces, and flat indirect entries. A model switch clears both without changing dispatch.\",\n&requests,\n&ContextSnapshotOptions::default().rewrite_known_segments().include_request_settings(),)"
expression: "context_snapshot::format_request_history_snapshot(\"Function prefixes annotate individual tools. Built-in namespace prefixes annotate headers. MCP guidance also appears in flat entries. A model switch clears both without changing dispatch.\",\n&requests,\n&ContextSnapshotOptions::default().rewrite_known_segments().include_request_settings(),)"
---
Scenario: Function prefixes annotate direct and indirect tools; namespace prefixes annotate embedded namespace docs, loaded namespaces, and flat indirect entries. A model switch clears both without changing dispatch.
Scenario: Function prefixes annotate individual tools. Built-in namespace prefixes annotate headers. MCP guidance also appears in flat entries. A model switch clears both without changing dispatch.
## Window 1
Settings:
@@ -44,7 +44,7 @@ Settings:
07:custom_tool_call_output:Script completed
Wall time <DURATION> seconds
Output:
| {"descriptions":["Functions context.\\n\\nImage guidance.\\n\\nView a local image file from the filesystem w...>>; };\\n```"],"echo":"ECHOING: ping","agent":"/root"} [hash=e3b76c8d361418c6]
| {"descriptions":["Image guidance.\\n\\nView a local image file from the filesystem when visual inspection ...>>; };\\n```"],"echo":"ECHOING: ping","agent":"/root"} [hash=a760dd5c2484ff73]
## Window 2 (after request 2)
Settings: relative to window 1
@@ -74,7 +74,7 @@ Settings: relative to window 1
07:custom_tool_call_output:Script completed
Wall time <DURATION> seconds
Output:
| {"descriptions":["Functions context.\\n\\nImage guidance.\\n\\nView a local image file from the filesystem w...>>; };\\n```"],"echo":"ECHOING: ping","agent":"/root"} [hash=e3b76c8d361418c6]
| {"descriptions":["Image guidance.\\n\\nView a local image file from the filesystem when visual inspection ...>>; };\\n```"],"echo":"ECHOING: ping","agent":"/root"} [hash=a760dd5c2484ff73]
08:message/assistant:
Done.
09:message/developer:
+34
View File
@@ -64,6 +64,7 @@ const REMINDER_MESSAGE_TEMPLATE: &str = concat!(
const PERSISTENT_INSTRUCTIONS: &str = include_str!("../templates/persistent_mode.md");
const CONTENT_FILTER_GUIDANCE: &str = "Your previous response was blocked by a content filter. Do not treat this as a transient failure or try to reproduce or work around the blocked content through repeated attempts, altered formatting, splitting, encoding, tools, subagents, or later wakes. Briefly explain the limitation and offer a permitted alternative. Continue unrelated authorized work.";
const MAX_CONTENT_FILTER_GUIDANCE_BYTES: usize = 512;
const DEFAULT_DESCRIPTION_PREFIX_BUDGET_BYTES: usize = 512;
/// Resolves model-owned text from catalog overrides or bundled defaults, one family at a time.
///
@@ -233,6 +234,39 @@ impl<'a> ResolvedModelMessages<'a> {
.as_ref()
}
/// Bound the selected model's configured prefix text before resolving tool availability.
pub fn validate_description_prefix_budget(&self) -> Result<(), String> {
let Some(tools) = self
.catalog_messages
.and_then(|messages| messages.tools.as_ref())
else {
return Ok(());
};
let indirect = tools.indirect_description_prefixes.as_ref();
let bytes: usize = [
tools
.functions_namespace_functions_description_prefixes
.as_ref(),
indirect.and_then(|prefixes| prefixes.namespaces.as_ref()),
indirect.and_then(|prefixes| prefixes.builtin_tool_namespaces.as_ref()),
indirect.and_then(|prefixes| prefixes.mcp_servers.as_ref()),
]
.into_iter()
.flatten()
.flat_map(|map| map.values())
.map(|prefix| prefix.trim().len())
.sum();
let limit = tools
.description_prefix_budget_bytes
.unwrap_or(DEFAULT_DESCRIPTION_PREFIX_BUDGET_BYTES);
if bytes > limit {
return Err(format!(
"Model catalog tool description prefixes total {bytes} UTF-8 bytes, exceeding description_prefix_budget_bytes ({limit})"
));
}
Ok(())
}
/// Selects indirect tool guidance; tool rendering owns namespace mapping and normalization.
pub fn indirect_description_prefixes(&self) -> Option<&'a IndirectDescriptionPrefixes> {
self.catalog_messages?
+13 -4
View File
@@ -669,13 +669,17 @@ pub struct ToolMessages {
pub incremental_tools: Option<IncrementalToolMessages>,
/// Prefixes for individual functions in the `functions` namespace, keyed by unqualified name.
/// Applies to direct declarations, Code Mode, and tool search, including custom tools.
/// Values are trimmed; empty values and unavailable functions add nothing. The trimmed
/// values for available functions plus separating blank lines must fit in 256 UTF-8 bytes
/// in total. This bounds the added text, not the complete definition or its token count.
/// Only available functions are annotated. All configured prefixes share the
/// `description_prefix_budget_bytes` limit with indirect namespace guidance.
/// Other namespaces are never affected.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub functions_namespace_functions_description_prefixes:
Option<std::collections::BTreeMap<String, String>>,
/// Maximum total UTF-8 bytes of trimmed prefix values in this model's catalog entry.
/// Defaults to 512. Each configured dictionary entry counts once, including unused
/// selectors. Keys, paragraph separators, and rendered copies are excluded.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description_prefix_budget_bytes: Option<usize>,
/// Optional guidance for indirectly presented tools; missing or empty adds no prefix.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub indirect_description_prefixes: Option<IndirectDescriptionPrefixes>,
@@ -696,9 +700,14 @@ pub struct ToolMessages {
#[derive(Debug, Default, Serialize, Deserialize, Clone, PartialEq, Eq, TS, JsonSchema)]
pub struct IndirectDescriptionPrefixes {
/// Exact rendered namespaces, including `functions` for plain tools.
/// Overlap with an MCP server prefix is allowed only when the trimmed values match.
/// Overlapping selectors must have the same trimmed value.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub namespaces: Option<std::collections::BTreeMap<String, String>>,
/// Exact rendered namespaces of registered built-in tools, including `functions` for plain tools.
/// Adds guidance once to the namespace header, including a header shared with client tools.
/// Flat listings have no header and omit this selector. External-only namespaces are ignored.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub builtin_tool_namespaces: Option<std::collections::BTreeMap<String, String>>,
/// Configured MCP server names, before callable namespace normalization.
/// Each prefix applies to all namespaces exposed by that server.
#[serde(default, skip_serializing_if = "Option::is_none")]
@@ -4,9 +4,10 @@
use crate::ResponsesApiNamespaceTool;
use crate::ToolName;
use crate::ToolSpec;
use crate::indirect_namespace_prefixes::prepend;
use std::collections::BTreeMap;
/// Trimmed, size-bounded description prefixes for the available `functions.*` tools.
/// Trimmed description prefixes for the available `functions.*` tools.
#[derive(Default)]
pub struct FunctionsNamespaceFunctionPrefixes(BTreeMap<String, String>);
@@ -14,11 +15,10 @@ impl FunctionsNamespaceFunctionPrefixes {
pub fn new(
prefixes: Option<&BTreeMap<String, String>>,
available_tools: impl IntoIterator<Item = ToolName>,
) -> Result<Self, &'static str> {
) -> Self {
let Some(prefixes) = prefixes.filter(|prefixes| !prefixes.is_empty()) else {
return Ok(Self::default());
return Self::default();
};
let mut remaining = 256usize;
let mut normalized = BTreeMap::new();
for tool in available_tools {
if !tool.is_default_namespace() || normalized.contains_key(&tool.name) {
@@ -31,15 +31,9 @@ impl FunctionsNamespaceFunctionPrefixes {
if prefix.is_empty() {
continue;
}
remaining = remaining
.checked_sub(prefix.len())
.and_then(|remaining| remaining.checked_sub(2))
.ok_or(
"Available functions' description prefixes exceed the 256-byte combined limit",
)?;
normalized.insert(tool.name, prefix.to_owned());
}
Ok(Self(normalized))
Self(normalized)
}
/// Returns an owned replacement only for a configured function. Unaffected tools
@@ -73,11 +67,7 @@ impl FunctionsNamespaceFunctionPrefixes {
fn prepend(&self, name: &str, description: &mut String) {
if let Some(prefix) = self.0.get(name) {
*description = if description.is_empty() {
prefix.clone()
} else {
format!("{prefix}\n\n{description}")
};
prepend(prefix, description);
}
}
}
@@ -1,6 +1,5 @@
//! Adds namespace guidance to indirect tool descriptions after selection.
//! Conflicting prefixes for the same final namespace are rejected before rendering.
//! Direct specifications, search indexes, and cached definitions remain unchanged.
use crate::LoadableToolSpec;
use crate::ToolName;
@@ -26,6 +25,8 @@ pub struct IndirectNamespacePrefixConflict {
/// Borrowed model text applied only to fresh indirect presentation data.
pub struct IndirectNamespacePrefixes<'a> {
prefixes: BTreeMap<String, &'a str>,
// This selector annotates namespace headers only, including shared headers.
builtin_headers: BTreeMap<&'a str, &'a str>,
}
impl<'a> IndirectNamespacePrefixes<'a> {
@@ -34,6 +35,7 @@ impl<'a> IndirectNamespacePrefixes<'a> {
pub fn new<'s>(
prefixes: Option<&'a IndirectDescriptionPrefixes>,
namespaces: impl IntoIterator<Item = (&'s str, &'s str)>,
builtin_tools: impl IntoIterator<Item = &'s ToolName>,
) -> Result<Self, IndirectNamespacePrefixConflict> {
let mut resolved = BTreeMap::new();
if let Some(namespaces) = prefixes.and_then(|prefixes| prefixes.namespaces.as_ref()) {
@@ -50,24 +52,41 @@ impl<'a> IndirectNamespacePrefixes<'a> {
{
for (server, namespace) in namespaces {
if let Some(prefix) = servers.get(server) {
let prefix = prefix.trim();
match resolved.entry(namespace.to_owned()) {
Entry::Vacant(entry) => {
entry.insert((prefix, format!("mcp_servers.{server}")));
}
Entry::Occupied(entry) if entry.get().0 != prefix => {
return Err(IndirectNamespacePrefixConflict {
namespace: namespace.to_owned(),
first_source: entry.get().1.clone(),
second_source: format!("mcp_servers.{server}"),
});
}
Entry::Occupied(_) => {}
}
insert_prefix(
&mut resolved,
namespace,
prefix,
format!("mcp_servers.{server}"),
)?;
}
}
}
let mut builtin_headers = BTreeMap::new();
if let Some(configured) = prefixes.and_then(|p| p.builtin_tool_namespaces.as_ref())
&& !configured.is_empty()
{
let registered = builtin_tools
.into_iter()
.map(namespace_name)
.collect::<BTreeSet<_>>();
for (namespace, prefix) in configured {
if !registered.contains(namespace.as_str()) {
continue;
}
if resolved.contains_key(namespace) {
insert_prefix(
&mut resolved,
namespace,
prefix,
format!("builtin_tool_namespaces.{namespace}"),
)?;
} else if !prefix.trim().is_empty() {
builtin_headers.insert(namespace.as_str(), prefix.trim());
}
}
}
Ok(Self {
builtin_headers,
prefixes: resolved
.into_iter()
.filter(|(_, (prefix, _))| !prefix.is_empty())
@@ -76,6 +95,10 @@ impl<'a> IndirectNamespacePrefixes<'a> {
})
}
pub fn is_empty(&self) -> bool {
self.prefixes.is_empty() && self.builtin_headers.is_empty()
}
/// ALL_TOOLS is flat, so each entry carries its namespace's guidance.
/// Its eventual model-visible output is subject to normal tool-output truncation.
pub fn apply_code_mode(&self, tools: &mut [ToolDefinition]) {
@@ -89,18 +112,18 @@ impl<'a> IndirectNamespacePrefixes<'a> {
/// Adds guidance to one owned description without copying the tool's schemas.
pub fn apply_code_mode_description(&self, tool_name: &ToolName, description: &mut String) {
if let Some(prefix) = self.prefix(namespace_name(tool_name)) {
if let Some(prefix) = self.flat_prefix(tool_name) {
prepend(prefix, description);
}
}
/// Adds one prefix per namespace actually embedded in the exec description.
/// Apply guidance once to each namespace embedded in the Code Mode prompt.
pub fn apply_exec_prompt(
&self,
tools: &mut [ToolDefinition],
namespaces: &mut BTreeMap<String, ToolNamespaceDescription>,
) {
if self.prefixes.is_empty() {
if self.is_empty() {
return;
}
let mut has_default_prefix = false;
@@ -137,24 +160,56 @@ impl<'a> IndirectNamespacePrefixes<'a> {
/// Applies prefixes after search ranking and namespace coalescing.
pub fn apply_search(&self, tools: &mut [LoadableToolSpec]) {
if self.prefixes.is_empty() {
if self.is_empty() {
return;
}
for spec in tools {
if let LoadableToolSpec::Namespace(namespace) = spec
&& let Some(prefix) = self.prefix(&namespace.name)
{
let LoadableToolSpec::Namespace(namespace) = spec else {
continue;
};
if let Some(prefix) = self.prefix(&namespace.name) {
prepend(prefix, &mut namespace.description);
}
}
}
/// Guidance attached to an individual entry in a flat Code Mode listing.
fn flat_prefix(&self, tool_name: &ToolName) -> Option<&'a str> {
self.prefixes.get(namespace_name(tool_name)).copied()
}
fn prefix(&self, namespace: &str) -> Option<&'a str> {
self.prefixes.get(namespace).copied()
self.prefixes
.get(namespace)
.or_else(|| self.builtin_headers.get(namespace))
.copied()
}
}
fn prepend(prefix: &str, description: &mut String) {
fn insert_prefix<'a>(
resolved: &mut BTreeMap<String, (&'a str, String)>,
namespace: &str,
prefix: &'a str,
source: String,
) -> Result<(), IndirectNamespacePrefixConflict> {
let prefix = prefix.trim();
match resolved.entry(namespace.to_owned()) {
Entry::Vacant(entry) => {
entry.insert((prefix, source));
}
Entry::Occupied(entry) if entry.get().0 != prefix => {
return Err(IndirectNamespacePrefixConflict {
namespace: namespace.to_owned(),
first_source: entry.get().1.clone(),
second_source: source,
});
}
Entry::Occupied(_) => {}
}
Ok(())
}
pub(super) fn prepend(prefix: &str, description: &mut String) {
*description = if description.is_empty() {
prefix.to_string()
} else {
@@ -1,6 +1,7 @@
//! Checks prefix normalization and rendering without exercising tool execution.
use super::*;
use crate::ResponsesApiNamespaceTool;
use codex_code_mode::CodeModeToolKind;
use codex_protocol::openai_models::IndirectDescriptionPrefixes;
use codex_protocol::openai_models::ToolMessages;
@@ -59,7 +60,7 @@ fn plain_tools_join_an_existing_functions_group_only_with_a_prefix() {
let configured: ToolMessages = serde_json::from_value(messages).unwrap();
let mut tools = original_tools.clone();
let mut namespaces = original_namespaces.clone();
IndirectNamespacePrefixes::new(configured.indirect_description_prefixes.as_ref(), [])
IndirectNamespacePrefixes::new(configured.indirect_description_prefixes.as_ref(), [], [])
.unwrap()
.apply_exec_prompt(&mut tools, &mut namespaces);
assert_eq!(render(&tools, &namespaces), original);
@@ -71,15 +72,99 @@ fn plain_tools_join_an_existing_functions_group_only_with_a_prefix() {
)])),
..Default::default()
};
let mut tools = original_tools;
let mut tools = original_tools.clone();
let mut namespaces = original_namespaces;
IndirectNamespacePrefixes::new(Some(&configured), [])
IndirectNamespacePrefixes::new(Some(&configured), [], [])
.unwrap()
.apply_exec_prompt(&mut tools, &mut namespaces);
let rendered = render(&tools, &namespaces);
assert_eq!(rendered.matches("## functions").count(), 1);
assert!(rendered.contains("## functions\nCatalog guidance.\n\nOriginal namespace guidance."));
assert!(rendered.find("## functions").unwrap() < rendered.find("### `plain`").unwrap());
// A client function and a built-in can share the default namespace.
let builtin_only = IndirectDescriptionPrefixes {
builtin_tool_namespaces: configured.namespaces.clone(),
..Default::default()
};
let inventory = [&original_tools[0].tool_name];
let prefixes = IndirectNamespacePrefixes::new(Some(&builtin_only), [], inventory).unwrap();
let mut tools = original_tools.clone();
let mut namespaces = BTreeMap::new();
prefixes.apply_exec_prompt(&mut tools, &mut namespaces);
assert_eq!(namespaces["functions"].description, "Catalog guidance.");
for (tool, original) in tools.iter().zip(&original_tools) {
assert_eq!(tool.description, original.description);
}
let mut flat = original_tools.clone();
prefixes.apply_code_mode(&mut flat);
assert_eq!(flat, original_tools);
// Search coalesces both owners under one header. Both member descriptions are preserved.
let mut search = [LoadableToolSpec::Namespace(crate::ResponsesApiNamespace {
name: "functions".into(),
description: "Shared namespace.".into(),
tools: original_tools
.iter()
.map(|tool| {
ResponsesApiNamespaceTool::Function(crate::ResponsesApiTool {
name: tool.tool_name.name.clone(),
description: tool.description.clone(),
strict: false,
defer_loading: Some(true),
parameters: crate::JsonSchema::object(
BTreeMap::new(),
/*required*/ None,
Some(false.into()),
),
output_schema: None,
})
})
.collect(),
})];
let mut expected = search.clone();
let LoadableToolSpec::Namespace(namespace) = &mut expected[0] else {
unreachable!()
};
namespace.description = "Catalog guidance.\n\nShared namespace.".into();
prefixes.apply_search(&mut search);
assert_eq!(search, expected);
let mut shared = builtin_only.clone();
let server_namespaces = [("calendar", "functions")];
shared.mcp_servers = Some(BTreeMap::from([(
"calendar".into(),
" Catalog guidance. ".into(),
)]));
let prefixes =
IndirectNamespacePrefixes::new(Some(&shared), server_namespaces, inventory).unwrap();
let mut namespaces = BTreeMap::new();
let mut tools = original_tools.clone();
prefixes.apply_exec_prompt(&mut tools, &mut namespaces);
assert_eq!(namespaces["functions"].description, "Catalog guidance.");
shared.mcp_servers = Some(BTreeMap::from([(
"calendar".into(),
"Different guidance.".into(),
)]));
assert_eq!(
IndirectNamespacePrefixes::new(Some(&shared), server_namespaces, inventory)
.err()
.expect("conflicting contributors")
.to_string(),
"Conflicting indirect description prefixes for namespace `functions`: `mcp_servers.calendar` and `builtin_tool_namespaces.functions`",
);
let overlapping = IndirectDescriptionPrefixes {
namespaces: Some(BTreeMap::from([("functions".into(), " ".into())])),
..builtin_only
};
assert_eq!(
IndirectNamespacePrefixes::new(Some(&overlapping), [], inventory)
.err()
.expect("explicit empty prefix conflicts")
.to_string(),
"Conflicting indirect description prefixes for namespace `functions`: `namespaces.functions` and `builtin_tool_namespaces.functions`"
);
}
#[test]
@@ -101,7 +186,7 @@ fn flat_tool_descriptions_use_trimmed_namespace_prefixes() {
output_schema: None,
};
let mut tools = [original.clone()];
IndirectNamespacePrefixes::new(Some(&configured), [])
IndirectNamespacePrefixes::new(Some(&configured), [], [])
.unwrap()
.apply_code_mode(&mut tools);
assert_eq!(
@@ -126,6 +211,7 @@ fn matching_prefixes_cover_each_namespace_once() {
let configured = IndirectDescriptionPrefixes {
namespaces: Some(exact),
mcp_servers: Some(servers),
..Default::default()
};
let original = ["gmail", "calendar", "drive", "slack"].map(|app| ToolDefinition {
name: format!("mcp__codex_apps__{app}__search"),
@@ -144,7 +230,7 @@ fn matching_prefixes_cover_each_namespace_once() {
("codex_apps", "mcp__codex_apps__gmail"),
("apps_alias", "mcp__codex_apps__gmail"),
]);
IndirectNamespacePrefixes::new(Some(&configured), namespaces)
IndirectNamespacePrefixes::new(Some(&configured), namespaces, [])
.unwrap()
.apply_code_mode(&mut tools);
let expected = original
@@ -173,10 +259,12 @@ fn conflicting_namespace_and_server_prefixes_report_keys_without_values() {
"reports.one".to_string(),
server_prefix.to_string(),
)])),
..Default::default()
};
let error = IndirectNamespacePrefixes::new(
Some(&configured),
[("reports.one", "mcp__reports_one")],
[],
)
.err()
.expect("conflicting prefixes")
@@ -200,6 +288,7 @@ fn conflicting_mcp_servers_report_the_shared_namespace() {
let error = IndirectNamespacePrefixes::new(
Some(&configured),
[("reports.one", "shared"), ("reports.two", "shared")],
[],
)
.err()
.expect("conflicting prefixes")