Dynamic tool calls - allow dynamic registration

Add experimental app-server support for connection-owned dynamic tool providers over both `stdio` and websocket.

Clients can now:
- register a tool with `toolProvider/register`
- unregister it with `toolProvider/unregister`

Registered tools are stored in an app-server registry, mapped back to the owning connection, and routed through the existing dynamic tool call flow. Tools with `injectIntoContext: true` are exposed to the model; tools with `injectIntoContext: false` remain callable only from `js_repl` via `codex.tool(...)`.

This also extends dynamic tool call events with `thread_id` so provider-owned tools can be invoked from newly created or resumed threads.

```mermaid
sequenceDiagram
    participant Client as Provider Client
    participant AppServer as App Server
    participant ThreadClient as Thread Client
    participant Core as Core Thread

    Client->>AppServer: toolProvider/register(tool)
    AppServer->>AppServer: store tool -> owning connection

    ThreadClient->>AppServer: thread/start
    AppServer->>Core: load thread + sync registered tools

    ThreadClient->>AppServer: turn/start
    AppServer->>Core: submit user input
    Core-->>AppServer: DynamicToolCallRequest(thread_id, tool, args, provider_owned=true)

    AppServer->>Client: item/tool/call
    Client-->>AppServer: DynamicToolCallResponse
    AppServer->>Core: submit dynamic tool response
    Core-->>AppServer: continue turn
This commit is contained in:
Channing Conger
2026-03-11 13:09:17 -07:00
parent f5bb338fdb
commit ee6257ae1c
35 changed files with 1157 additions and 30 deletions
+27 -1
View File
@@ -526,6 +526,7 @@ impl Codex {
app_server_client_name: None,
session_source,
dynamic_tools,
registered_dynamic_tools: Vec::new(),
persist_extended_history,
inherited_shell_snapshot,
};
@@ -946,6 +947,7 @@ pub(crate) struct SessionConfiguration {
/// Source of the session (cli, vscode, exec, mcp, ...)
session_source: SessionSource,
dynamic_tools: Vec<DynamicToolSpec>,
registered_dynamic_tools: Vec<DynamicToolSpec>,
persist_extended_history: bool,
inherited_shell_snapshot: Option<Arc<ShellSnapshot>>,
}
@@ -955,6 +957,22 @@ impl SessionConfiguration {
&self.codex_home
}
fn effective_dynamic_tools(&self) -> Vec<DynamicToolSpec> {
let mut seen_names = HashSet::new();
let mut tools =
Vec::with_capacity(self.dynamic_tools.len() + self.registered_dynamic_tools.len());
for tool in self
.dynamic_tools
.iter()
.chain(self.registered_dynamic_tools.iter())
{
if seen_names.insert(tool.name.clone()) {
tools.push(tool.clone());
}
}
tools
}
fn thread_config_snapshot(&self) -> ThreadConfigSnapshot {
ThreadConfigSnapshot {
model: self.collaboration_mode.model().to_string(),
@@ -1245,7 +1263,7 @@ impl Session {
tool_call_gate: Arc::new(ReadinessFlag::new()),
truncation_policy: model_info.truncation_policy.into(),
js_repl,
dynamic_tools: session_configuration.dynamic_tools.clone(),
dynamic_tools: session_configuration.effective_dynamic_tools(),
turn_metadata_state,
turn_skills: TurnSkillsContext::new(skills_outcome),
turn_timing_state: Arc::new(TurnTimingState::default()),
@@ -2417,6 +2435,14 @@ impl Session {
.clone()
}
pub(crate) async fn update_registered_dynamic_tools(
&self,
dynamic_tools: Vec<DynamicToolSpec>,
) {
let mut state = self.state.lock().await;
state.session_configuration.registered_dynamic_tools = dynamic_tools;
}
pub(crate) async fn provider(&self) -> ModelProviderInfo {
let state = self.state.lock().await;
state.session_configuration.provider.clone()
+6
View File
@@ -1476,6 +1476,7 @@ async fn set_rate_limits_retains_previous_credits() {
app_server_client_name: None,
session_source: SessionSource::Exec,
dynamic_tools: Vec::new(),
registered_dynamic_tools: Vec::new(),
persist_extended_history: false,
inherited_shell_snapshot: None,
};
@@ -1572,6 +1573,7 @@ async fn set_rate_limits_updates_plan_type_when_present() {
app_server_client_name: None,
session_source: SessionSource::Exec,
dynamic_tools: Vec::new(),
registered_dynamic_tools: Vec::new(),
persist_extended_history: false,
inherited_shell_snapshot: None,
};
@@ -1926,6 +1928,7 @@ pub(crate) async fn make_session_configuration_for_tests() -> SessionConfigurati
app_server_client_name: None,
session_source: SessionSource::Exec,
dynamic_tools: Vec::new(),
registered_dynamic_tools: Vec::new(),
persist_extended_history: false,
inherited_shell_snapshot: None,
}
@@ -2079,6 +2082,7 @@ async fn session_new_fails_when_zsh_fork_enabled_without_zsh_path() {
app_server_client_name: None,
session_source: SessionSource::Exec,
dynamic_tools: Vec::new(),
registered_dynamic_tools: Vec::new(),
persist_extended_history: false,
inherited_shell_snapshot: None,
};
@@ -2172,6 +2176,7 @@ pub(crate) async fn make_session_and_context() -> (Session, TurnContext) {
app_server_client_name: None,
session_source: SessionSource::Exec,
dynamic_tools: Vec::new(),
registered_dynamic_tools: Vec::new(),
persist_extended_history: false,
inherited_shell_snapshot: None,
};
@@ -2733,6 +2738,7 @@ pub(crate) async fn make_session_and_context_with_dynamic_tools_and_rx(
app_server_client_name: None,
session_source: SessionSource::Exec,
dynamic_tools,
registered_dynamic_tools: Vec::new(),
persist_extended_history: false,
inherited_shell_snapshot: None,
};
+8
View File
@@ -11,6 +11,7 @@ use crate::protocol::Op;
use crate::protocol::Submission;
use codex_protocol::config_types::Personality;
use codex_protocol::config_types::ServiceTier;
use codex_protocol::dynamic_tools::DynamicToolSpec;
use codex_protocol::models::ContentItem;
use codex_protocol::models::ResponseInputItem;
use codex_protocol::models::ResponseItem;
@@ -144,6 +145,13 @@ impl CodexThread {
self.codex.thread_config_snapshot().await
}
pub async fn update_registered_dynamic_tools(&self, dynamic_tools: Vec<DynamicToolSpec>) {
self.codex
.session
.update_registered_dynamic_tools(dynamic_tools)
.await;
}
pub fn enabled(&self, feature: Feature) -> bool {
self.codex.enabled(feature)
}
+4
View File
@@ -312,6 +312,10 @@ impl ThreadManager {
self.state.get_thread(thread_id).await
}
pub async fn loaded_threads(&self) -> Vec<Arc<CodexThread>> {
self.state.threads.read().await.values().cloned().collect()
}
pub async fn start_thread(&self, config: Config) -> CodexResult<NewThread> {
// Box delegated thread-spawn futures so these convenience wrappers do
// not inline the full spawn path into every caller's async state.
@@ -97,11 +97,18 @@ async fn request_dynamic_tool(
}
let started_at = Instant::now();
let provider_owned = turn_context
.dynamic_tools
.iter()
.find(|spec| spec.name == tool)
.is_some_and(|spec| spec.provider_owned);
let event = EventMsg::DynamicToolCallRequest(DynamicToolCallRequest {
thread_id: session.conversation_id.to_string(),
call_id: call_id.clone(),
turn_id: turn_id.clone(),
tool: tool.clone(),
arguments: arguments.clone(),
provider_owned,
});
session.send_event(turn_context, event).await;
let response = rx_response.await.ok();
+2
View File
@@ -3096,6 +3096,8 @@ await codex.emitImage({ bytes: png, mimeType: "image/png", detail: "ultra" });
"properties": {},
"additionalProperties": false
}),
inject_into_context: true,
provider_owned: false,
}])
.await;
if !turn
+70
View File
@@ -183,6 +183,23 @@ impl ToolRouter {
err,
));
}
if source == ToolCallSource::Direct
&& turn
.dynamic_tools
.iter()
.find(|tool| tool.name == tool_name)
.is_some_and(|tool| !tool.inject_into_context)
{
let err = FunctionCallError::RespondToModel(
"direct tool calls are disabled for this dynamic tool; use js_repl and codex.tool(...) instead"
.to_string(),
);
return Ok(Self::failure_response(
failure_call_id,
payload_outputs_custom,
err,
));
}
let invocation = ToolInvocation {
session,
@@ -234,8 +251,10 @@ mod tests {
use std::sync::Arc;
use crate::codex::make_session_and_context;
use crate::codex::make_session_and_context_with_dynamic_tools_and_rx;
use crate::tools::context::ToolPayload;
use crate::turn_diff_tracker::TurnDiffTracker;
use codex_protocol::dynamic_tools::DynamicToolSpec;
use codex_protocol::models::ResponseInputItem;
use super::ToolCall;
@@ -347,4 +366,55 @@ mod tests {
Ok(())
}
#[tokio::test]
async fn non_injected_dynamic_tools_block_direct_tool_calls() -> anyhow::Result<()> {
let (session, turn, _rx) =
make_session_and_context_with_dynamic_tools_and_rx(vec![DynamicToolSpec {
name: "hidden_dynamic_tool".to_string(),
description: "Only callable from js_repl.".to_string(),
input_schema: serde_json::json!({
"type": "object",
"properties": {},
"additionalProperties": false
}),
inject_into_context: false,
provider_owned: false,
}])
.await;
let session = Arc::clone(&session);
let turn = Arc::clone(&turn);
let router = ToolRouter::from_config(
&turn.tools_config,
None,
None,
turn.dynamic_tools.as_slice(),
);
let call = ToolCall {
tool_name: "hidden_dynamic_tool".to_string(),
call_id: "call-3".to_string(),
payload: ToolPayload::Function {
arguments: "{}".to_string(),
},
};
let tracker = Arc::new(tokio::sync::Mutex::new(TurnDiffTracker::new()));
let response = router
.dispatch_tool_call(session, turn, tracker, call, ToolCallSource::Direct)
.await?;
match response {
ResponseInputItem::FunctionCallOutput { output, .. } => {
let content = output.text_content().unwrap_or_default();
assert!(
content.contains("direct tool calls are disabled for this dynamic tool"),
"unexpected tool call message: {content}",
);
}
other => panic!("expected function call output, got {other:?}"),
}
Ok(())
}
}
+4 -1
View File
@@ -2465,6 +2465,10 @@ pub(crate) fn build_specs(
if !dynamic_tools.is_empty() {
for tool in dynamic_tools {
builder.register_handler(tool.name.clone(), dynamic_tool_handler.clone());
if !tool.inject_into_context {
continue;
}
match dynamic_tool_to_openai_tool(tool) {
Ok(converted_tool) => {
push_tool_spec(
@@ -2473,7 +2477,6 @@ pub(crate) fn build_specs(
false,
config.code_mode_enabled,
);
builder.register_handler(tool.name.clone(), dynamic_tool_handler.clone());
}
Err(e) => {
tracing::error!(
@@ -110,6 +110,8 @@ async fn backfill_scans_existing_rollouts() -> Result<()> {
"required": ["city"],
"properties": { "city": { "type": "string" } }
}),
inject_into_context: true,
provider_owned: false,
},
DynamicToolSpec {
name: "weather_lookup".to_string(),
@@ -119,6 +121,8 @@ async fn backfill_scans_existing_rollouts() -> Result<()> {
"required": ["zip"],
"properties": { "zip": { "type": "string" } }
}),
inject_into_context: true,
provider_owned: false,
},
];
let dynamic_tools_for_hook = dynamic_tools.clone();