Grok Build · Tool Configuration

Process-Level External Toolset Preset Registry

config.rs allows extension code outside the crate to register name-resolved toolset builder functions within the current process, using Public and Internal visibility to control inclusion in the public enumeration.

Learning Objective Understand what the registry stores, the difference between Public and Internal, and how late registration has different effects on “already-resolved configs” vs. “future resolution.”
Core Visual · Pedagogical Structure Diagram
Registration APIregister_toolset_presetregister_internal_toolset_preset TOOLSET_PRESETSOnceLock<Mutex<HashMap<...>>>name → (builder, visibility)builder: fn() → ToolServerConfig PublicEnumerable and name-resolvable InternalName-resolvable only, not publicly enumerated registered_toolset_preset(name)Retrieves the function and immediately builds a new config
Pedagogical diagram: nodes and edges illustrate source-code relationships; content has been adapted for instructional purposes.
Three Facts You Must Distinguish
Builder Is a Function Pointer

ToolsetPresetBuilder = fn() -> ToolServerConfig. The registry stores builder functions; calling the function at query time generates a config.

Visibility Only Controls Enumeration

Public entries appear in preset_names and the public preset set. Internal entries are not publicly enumerated, but can still be resolved by name via toolset_for_preset.

Registry Belongs to the Process

OnceLock and Mutex wrap a global HashMap, covering the lifetime of the current process with lock-protected reads and writes.

Precise Meaning of Registration Timing
Config A Already Resolved

A newly registered preset does not write back to config A. The existing ToolServerConfig remains unchanged.

Config B Resolved Later

Subsequent calls re-query the global registry and can therefore see late-registered presets. Source comments still advise completing registration before the first resolution to ensure consistent startup behavior.

Real Source Code Evidence
crates/codegen/xai-grok-agent/src/config.rsLines 38–81 (excerpt)
pub type ToolsetPresetBuilder = fn() -> ToolServerConfig;

enum PresetVisibility {
    Public,
    Internal,
}

pub fn register_toolset_preset(name: &str, builder: ToolsetPresetBuilder) {
    toolset_preset_registry().lock().expect("toolset preset registry poisoned")
        .insert(name.to_string(), (builder, PresetVisibility::Public));
}

pub fn register_internal_toolset_preset(name: &str, builder: ToolsetPresetBuilder) {
    toolset_preset_registry().lock().expect("toolset preset registry poisoned")
        .insert(name.to_string(), (builder, PresetVisibility::Internal));
}

fn registered_toolset_preset(name: &str) -> Option<ToolServerConfig> {
    toolset_preset_registry().lock().expect("toolset preset registry poisoned")
        .get(name).map(|(f, _)| f())
}
Source Snapshot Note: Based on local repository grok-build-main, cross-checked against crates/codegen/xai-grok-agent/src/config.rs, verification date 2026-07-17. Code blocks retain the original source text for all displayed fields, functions, and strings.
Lab Exercise
01

Design a preset for use exclusively by a test Harness

Write the registration function to call, the full type of the builder, and whether it can appear in preset_names(). Then clarify: if a session config has already been resolved, does that session automatically change after registration?

Takeaway: The external preset registry stores a mapping from name to builder function and visibility. The core difference between Public and Internal is the public enumeration scope. Late registration does not alter already-resolved configs; subsequent resolutions can still find newly registered entries.