Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Add turn trigger metadata (#40665)

pakrym-oai538900ee769f
diff --git a/codex-rs/app-server-protocol/schema/json/ClientRequest.json b/codex-rs/app-server-protocol/schema/json/ClientRequest.json
index ec5e3b67bd..9911cd1c52 100644
--- a/codex-rs/app-server-protocol/schema/json/ClientRequest.json
+++ b/codex-rs/app-server-protocol/schema/json/ClientRequest.json
@@ -5266,6 +5266,13 @@
},
"threadId": {
"type": "string"
+ },
+ "turnTrigger": {
+ "description": "Optional source classification for the caller that starts this turn. Ignored when this request steers an already-active turn.",
+ "type": [
+ "string",
+ "null"
+ ]
}
},
"required": [
diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json
index 780cdf059b..d32a69565c 100644
--- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json
+++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json
@@ -23959,6 +23959,13 @@
},
"threadId": {
"type": "string"
+ },
+ "turnTrigger": {
+ "description": "Optional source classification for the caller that starts this turn. Ignored when this request steers an already-active turn.",
+ "type": [
+ "string",
+ "null"
+ ]
}
},
"required": [
diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json
index 79fed91877..e70fa88d12 100644
--- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json
+++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json
@@ -21694,6 +21694,13 @@
},
"threadId": {
"type": "string"
+ },
+ "turnTrigger": {
+ "description": "Optional source classification for the caller that starts this turn. Ignored when this request steers an already-active turn.",
+ "type": [
+ "string",
+ "null"
+ ]
}
},
"required": [
diff --git a/codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.json b/codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.json
index 197bdeff8c..96327a5cf6 100644
--- a/codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.json
+++ b/codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.json
@@ -675,6 +675,13 @@
},
"threadId": {
"type": "string"
+ },
+ "turnTrigger": {
+ "description": "Optional source classification for the caller that starts this turn. Ignored when this request steers an already-active turn.",
+ "type": [
+ "string",
+ "null"
+ ]
}
},
"required": [
diff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst
index b40f3eca94..570c8718d2 100644
Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst differ
diff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst
index a134b06aec..f764283be1 100644
Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst differ
diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts b/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts
index 7bccf79043..785ca22750 100644
--- a/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts
+++ b/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts
@@ -11,6 +11,10 @@ import type { SandboxPolicy } from "./SandboxPolicy";
import type { UserInput } from "./UserInput";
export type TurnStartParams = {threadId: string, clientUserMessageId?: string | null, input: Array<UserInput>, /**
+ * Optional source classification for the caller that starts this turn.
+ * Ignored when this request steers an already-active turn.
+ */
+turnTrigger?: string | null, /**
* Override the working directory for this turn and subsequent turns.
*/
cwd?: string | null, /**
diff --git a/codex-rs/app-server-protocol/src/protocol/v2/tests.rs b/codex-rs/app-server-protocol/src/protocol/v2/tests.rs
index 309196dd1c..491b882941 100644
--- a/codex-rs/app-server-protocol/src/protocol/v2/tests.rs
+++ b/codex-rs/app-server-protocol/src/protocol/v2/tests.rs
@@ -4714,6 +4714,7 @@ fn turn_start_params_preserve_explicit_null_service_tier() {
thread_id: "thread_123".to_string(),
client_user_message_id: None,
input: vec![],
+ turn_trigger: None,
responsesapi_client_metadata: None,
additional_context: None,
environments: None,
diff --git a/codex-rs/app-server-protocol/src/protocol/v2/turn.rs b/codex-rs/app-server-protocol/src/protocol/v2/turn.rs
index b1763095e7..6778748814 100644
--- a/codex-rs/app-server-protocol/src/protocol/v2/turn.rs
+++ b/codex-rs/app-server-protocol/src/protocol/v2/turn.rs
@@ -121,6 +121,10 @@ pub struct TurnStartParams {
#[ts(optional = nullable)]
pub client_user_message_id: Option<String>,
pub input: Vec<UserInput>,
+ /// Optional source classification for the caller that starts this turn.
+ /// Ignored when this request steers an already-active turn.
+ #[ts(optional = nullable)]
+ pub turn_trigger: Option<String>,
/// Optional metadata to enrich Codex's ResponsesAPI turn metadata.
///
/// Entries are flattened into the JSON string sent as
diff --git a/codex-rs/app-server/README.md b/codex-rs/app-server/README.md
index 5734d53446..993f0fa910 100644
--- a/codex-rs/app-server/README.md
+++ b/codex-rs/app-server/README.md
@@ -209,7 +209,7 @@ Example with notification opt-out:
- `thread/backgroundTerminals/terminate` — terminate one running background terminal by app-server `processId` (experimental; requires `capabilities.experimentalApi`); returns whether a process was terminated.
- `thread/rollback` — deprecated and will be removed soon. Drop the last N turns from the agent’s in-memory context and persist a rollback marker in the rollout so future resumes see the pruned history; returns the updated `thread` (with `turns` populated) on success. Paginated threads do not support rollback. Parent-owned Multi-Agent V2 subagents reject direct rollback requests.
- `thread/revert` — experimental. Replace a loaded paginated thread's durable history with the prefix strictly before `beforeTurnId` while preserving its thread id. The operation interrupts an active turn if needed, leaves older rollout files immutable, reloads the thread, returns updated thread metadata with empty `turns` plus pagination cursors, and emits `thread/reverted`. It does not revert local file changes. Parent-owned Multi-Agent V2 subagents reject direct revert requests.
-- `turn/start` — add user input to a thread and begin Codex generation; responds with the initial `turn` object and streams `turn/started`, `item/*`, and `turn/completed` notifications. `clientUserMessageId` is optional; when supplied, the corresponding `userMessage` item echoes it as `clientId`. Experimental `runtimeWorkspaceRoots` supplies the default roots for newly resolved environment selections. Explicit `environments[].runtimeWorkspaceRoots` override that fallback with environment-native absolute paths. Prefer experimental `permissions` profile selection by id for permission overrides; the legacy `sandboxPolicy` field is still accepted but cannot be combined with `permissions`. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode". Deprecated experimental `multiAgentMode` is ignored; Ultra reasoning effort selects proactive behavior. Parent-owned Multi-Agent V2 subagents reject direct turns.
+- `turn/start` — add user input to a thread and begin Codex generation; responds with the initial `turn` object and streams `turn/started`, `item/*`, and `turn/completed` notifications. Optional `turnTrigger` classifies who or what started a new turn and is sent as `turn_trigger` in Responses request metadata; it is ignored if the request steers an active turn. `clientUserMessageId` is optional; when supplied, the corresponding `userMessage` item echoes it as `clientId`. Experimental `runtimeWorkspaceRoots` supplies the default roots for newly resolved environment selections. Explicit `environments[].runtimeWorkspaceRoots` override that fallback with environment-native absolute paths. Prefer experimental `permissions` profile selection by id for permission overrides; the legacy `sandboxPolicy` field is still accepted but cannot be combined with `permissions`. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode". Deprecated experimental `multiAgentMode` is ignored; Ultra reasoning effort selects proactive behavior. Parent-owned Multi-Agent V2 subagents reject direct turns.
- `thread/inject_items` — append raw Responses API items to a loaded thread’s model-visible history without starting a user turn; returns `{}` on success. Parent-owned Multi-Agent V2 subagents reject direct item injection.
- `turn/settings/update` — experimental; publish a narrow model-settings patch to the exact live task identified by `threadId` and `turnId`, regardless of task kind. Requires `step_model_switching`; returns `status: "applied"` or `status: "targetUnavailable"`, or a request error if rejected. Future-thread settings and already captured steps are unchanged. Parent-owned Multi-Agent V2 subagents reject direct settings updates.
- `turn/steer` — add user input to an already in-flight regular turn without starting a new turn; returns the active `turnId` that accepted the input. `clientUserMessageId` is optional; when supplied, the corresponding `userMessage` item echoes it as `clientId`. Review and manual compaction turns reject `turn/steer`. Parent-owned Multi-Agent V2 subagents reject direct steering.
diff --git a/codex-rs/app-server/src/message_processor_tracing_tests.rs b/codex-rs/app-server/src/message_processor_tracing_tests.rs
index f3246bb453..a452929e0a 100644
--- a/codex-rs/app-server/src/message_processor_tracing_tests.rs
+++ b/codex-rs/app-server/src/message_processor_tracing_tests.rs
@@ -663,6 +663,7 @@ async fn turn_start_jsonrpc_span_parents_core_turn_spans() -> Result<()> {
text: "hello".to_string(),
text_elements: Vec::new(),
}],
+ turn_trigger: None,
responsesapi_client_metadata: None,
additional_context: None,
cwd: None,
diff --git a/codex-rs/app-server/src/request_processors/turn_processor.rs b/codex-rs/app-server/src/request_processors/turn_processor.rs
index d199d79b26..6ece29cc0b 100644
--- a/codex-rs/app-server/src/request_processors/turn_processor.rs
+++ b/codex-rs/app-server/src/request_processors/turn_processor.rs
@@ -580,6 +580,7 @@ impl TurnRequestProcessor {
})
.with_thread_settings(thread_settings)
.on_start(TurnStartOptions {
+ turn_trigger: params.turn_trigger,
final_output_json_schema: params.output_schema,
service_tier: params.service_tier_for_turn,
..Default::default()
diff --git a/codex-rs/app-server/tests/suite/v2/client_metadata.rs b/codex-rs/app-server/tests/suite/v2/client_metadata.rs
index 3904bee770..67b1412039 100644
--- a/codex-rs/app-server/tests/suite/v2/client_metadata.rs
+++ b/codex-rs/app-server/tests/suite/v2/client_metadata.rs
@@ -75,6 +75,7 @@ async fn turn_start_forwards_client_metadata_to_responses_request_v2() -> Result
"context_window_id".to_string(),
"client-supplied".to_string(),
),
+ ("turn_trigger".to_string(), "client-supplied".to_string()),
]);
let turn_req = mcp
.send_turn_start_request(TurnStartParams {
@@ -84,6 +85,7 @@ async fn turn_start_forwards_client_metadata_to_responses_request_v2() -> Result
text: "Hello".to_string(),
text_elements: Vec::new(),
}],
+ turn_trigger: Some("user".to_string()),
responsesapi_client_metadata: Some(client_metadata.clone()),
..Default::default()
})
@@ -106,6 +108,7 @@ async fn turn_start_forwards_client_metadata_to_responses_request_v2() -> Result
assert_eq!(metadata["fiber_run_id"].as_str(), Some("fiber-start-123"));
assert_eq!(metadata["origin"].as_str(), Some("gaas"));
assert_eq!(metadata["thread_source"].as_str(), Some("automation"));
+ assert_eq!(metadata["turn_trigger"].as_str(), Some("user"));
assert_eq!(metadata["turn_id"].as_str(), Some(turn.id.as_str()));
assert!(metadata.get("installation_id").is_some());
assert!(metadata.get("session_id").is_some());
@@ -437,6 +440,7 @@ async fn turn_steer_updates_client_metadata_on_follow_up_responses_request_v2()
text: "Run sleep".to_string(),
text_elements: Vec::new(),
}],
+ turn_trigger: Some("user".to_string()),
responsesapi_client_metadata: Some(start_metadata.clone()),
..Default::default()
})
@@ -490,6 +494,7 @@ async fn turn_steer_updates_client_metadata_on_follow_up_responses_request_v2()
Some("fiber-start-123")
);
assert_eq!(first_metadata["turn_id"].as_str(), Some(turn_id.as_str()));
+ assert_eq!(first_metadata["turn_trigger"].as_str(), Some("user"));
let second_metadata = requests[1]
.header("x-codex-turn-metadata")
@@ -502,6 +507,7 @@ async fn turn_steer_updates_client_metadata_on_follow_up_responses_request_v2()
);
assert_eq!(second_metadata["origin"].as_str(), Some("gaas"));
assert_eq!(second_metadata["turn_id"].as_str(), Some(turn_id.as_str()));
+ assert_eq!(second_metadata["turn_trigger"].as_str(), Some("user"));
Ok(())
}
@@ -555,6 +561,7 @@ async fn turn_start_forwards_client_metadata_to_responses_websocket_request_body
text: "Hello".to_string(),
text_elements: Vec::new(),
}],
+ turn_trigger: Some("user".to_string()),
responsesapi_client_metadata: Some(client_metadata),
..Default::default()
})
@@ -589,6 +596,7 @@ async fn turn_start_forwards_client_metadata_to_responses_websocket_request_body
assert_eq!(metadata["fiber_run_id"].as_str(), Some("fiber-start-123"));
assert_eq!(metadata["origin"].as_str(), Some("gaas"));
assert_eq!(metadata["thread_source"].as_str(), Some("automation"));
+ assert_eq!(metadata["turn_trigger"].as_str(), Some("user"));
assert_eq!(metadata["turn_id"].as_str(), Some(turn.id.as_str()));
assert!(metadata.get("session_id").is_some());
assert_eq!(
diff --git a/codex-rs/app-server/tests/suite/v2/thread_queue.rs b/codex-rs/app-server/tests/suite/v2/thread_queue.rs
index d094af9223..1b7099dc45 100644
--- a/codex-rs/app-server/tests/suite/v2/thread_queue.rs
+++ b/codex-rs/app-server/tests/suite/v2/thread_queue.rs
@@ -412,6 +412,7 @@ async fn idle_queue_dispatch_preserves_client_id() -> Result<()> {
metadata["turn_id"].as_str(),
Some(completed.turn.id.as_str())
);
+ assert_eq!(metadata["turn_trigger"].as_str(), Some("queue"));
Ok(())
}
@@ -715,7 +716,7 @@ async fn queue_start_without_id_starts_the_head_when_idle() -> Result<()> {
create_final_assistant_message_sse_response("first queued message done")?,
create_final_assistant_message_sse_response("second queued message done")?,
];
- let (mut app, _codex_home, _server) = queue_app(responses).await?;
+ let (mut app, _codex_home, server) = queue_app(responses).await?;
let thread_id = app
.start_thread(ThreadStartParams::default())
.await?
@@ -765,6 +766,26 @@ async fn queue_start_without_id_starts_the_head_when_idle() -> Result<()> {
assert_eq!(completed.turn.status, TurnStatus::Completed);
}
assert!(list_queue(&mut app, &thread_id).await?.data.is_empty());
+
+ let requests = server
+ .received_requests()
+ .await
+ .context("mock request capture unavailable")?;
+ let response_requests = requests
+ .iter()
+ .filter(|request| request.url.path().ends_with("/responses"))
+ .collect::<Vec<_>>();
+ assert_eq!(response_requests.len(), 3);
+ for request in &response_requests[1..] {
+ let metadata_header = request
+ .headers
+ .get("x-codex-turn-metadata")
+ .context("queued model request is missing its x-codex-turn-metadata header")?
+ .to_str()
+ .context("queued turn metadata header is not valid ASCII")?;
+ let metadata: Value = serde_json::from_str(metadata_header)?;
+ assert_eq!(metadata["turn_trigger"].as_str(), Some("queue"));
+ }
Ok(())
}
diff --git a/codex-rs/app-server/tests/suite/v2/thread_resume.rs b/codex-rs/app-server/tests/suite/v2/thread_resume.rs
index dd7a2a0ac4..7250a3d752 100644
--- a/codex-rs/app-server/tests/suite/v2/thread_resume.rs
+++ b/codex-rs/app-server/tests/suite/v2/thread_resume.rs
@@ -3021,6 +3021,23 @@ async fn thread_goal_lifecycle_emits_analytics_and_clear_deletes_goal() -> Resul
.is_some()
);
+ let requests = server
+ .received_requests()
+ .await
+ .expect("wiremock should record response requests");
+ let response_requests = requests
+ .iter()
+ .filter(|request| request.url.path().ends_with("/responses"))
+ .collect::<Vec<_>>();
+ assert_eq!(response_requests.len(), 2);
+ let metadata_header = response_requests[1]
+ .headers
+ .get("x-codex-turn-metadata")
+ .expect("goal continuation should include turn metadata")
+ .to_str()?;
+ let metadata: serde_json::Value = serde_json::from_str(metadata_header)?;
+ assert_eq!(metadata["turn_trigger"].as_str(), Some("goal"));
+
let status = wait_for_goal_event(
&server,
DEFAULT_READ_TIMEOUT,
diff --git a/codex-rs/app-server/tests/suite/v2/turn_start.rs b/codex-rs/app-server/tests/suite/v2/turn_start.rs
index 433be28752..33f22aa063 100644
--- a/codex-rs/app-server/tests/suite/v2/turn_start.rs
+++ b/codex-rs/app-server/tests/suite/v2/turn_start.rs
@@ -357,6 +357,7 @@ async fn turn_start_steers_active_turn_and_returns_active_turn_id() -> Result<()
text: "start".to_string(),
text_elements: Vec::new(),
}],
+ turn_trigger: Some("user".to_string()),
..Default::default()
},
})
@@ -377,6 +378,7 @@ async fn turn_start_steers_active_turn_and_returns_active_turn_id() -> Result<()
text: "steer".to_string(),
text_elements: Vec::new(),
}],
+ turn_trigger: Some("goal".to_string()),
..Default::default()
},
})
@@ -391,6 +393,18 @@ async fn turn_start_steers_active_turn_and_returns_active_turn_id() -> Result<()
mcp.read_stream_until_notification_message("turn/completed"),
)
.await??;
+
+ let requests = server.requests().await;
+ assert_eq!(requests.len(), 2);
+ for request in requests {
+ let body: Value = serde_json::from_slice(&request)?;
+ let turn_metadata: Value = serde_json::from_str(
+ body["client_metadata"]["x-codex-turn-metadata"]
+ .as_str()
+ .context("expected x-codex-turn-metadata")?,
+ )?;
+ assert_eq!(turn_metadata["turn_trigger"].as_str(), Some("user"));
+ }
Ok(())
}
@@ -2767,6 +2781,7 @@ async fn turn_start_explicit_local_environment_updates_legacy_cwd_between_turns(
text: "first turn".to_string(),
text_elements: Vec::new(),
}],
+ turn_trigger: None,
responsesapi_client_metadata: None,
additional_context: None,
cwd: Some(first_cwd.clone()),
@@ -2816,6 +2831,7 @@ async fn turn_start_explicit_local_environment_updates_legacy_cwd_between_turns(
text: "second turn".to_string(),
text_elements: Vec::new(),
}],
+ turn_trigger: None,
responsesapi_client_metadata: None,
additional_context: None,
cwd: None,
diff --git a/codex-rs/core/src/codex_delegate.rs b/codex-rs/core/src/codex_delegate.rs
index b23d82b507..3bd74e0afa 100644
--- a/codex-rs/core/src/codex_delegate.rs
+++ b/codex-rs/core/src/codex_delegate.rs
@@ -217,6 +217,7 @@ pub(crate) async fn run_codex_thread_one_shot(
service_tier: None,
parent_turn_id: Some(parent_turn_id),
root_turn_id,
+ ..Default::default()
}),
TurnInputMode::StartIfIdle,
)
diff --git a/codex-rs/core/src/guardian/review_session.rs b/codex-rs/core/src/guardian/review_session.rs
index 3f29a2595e..8e9bd6bb12 100644
--- a/codex-rs/core/src/guardian/review_session.rs
+++ b/codex-rs/core/src/guardian/review_session.rs
@@ -1182,6 +1182,7 @@ async fn run_review_on_session(
service_tier: None,
parent_turn_id: Some(parent_turn.sub_id.clone()),
root_turn_id: parent_turn.turn_metadata_state.root_turn_id(),
+ ..Default::default()
}),
TurnInputMode::StartIfIdle,
);
diff --git a/codex-rs/core/src/responses_metadata.rs b/codex-rs/core/src/responses_metadata.rs
index a06086280d..a520072975 100644
--- a/codex-rs/core/src/responses_metadata.rs
+++ b/codex-rs/core/src/responses_metadata.rs
@@ -43,6 +43,7 @@ pub(crate) const PARENT_TURN_ID_KEY: &str = "parent_turn_id";
pub(crate) const ROOT_TURN_ID_KEY: &str = "root_turn_id";
pub(crate) const SUBAGENT_KIND_KEY: &str = "subagent_kind";
pub(crate) const THREAD_SOURCE_KEY: &str = "thread_source";
+pub(crate) const TURN_TRIGGER_KEY: &str = "turn_trigger";
pub(crate) const SANDBOX_KEY: &str = "sandbox";
pub(crate) const SANDBOX_MODE_KEY: &str = "sandbox_mode";
pub(crate) const AUTO_REVIEW_ENABLED_KEY: &str = "auto_review_enabled";
@@ -76,6 +77,7 @@ const RESERVED_METADATA_KEYS: &[&str] = &[
ROOT_TURN_ID_KEY,
SUBAGENT_KIND_KEY,
THREAD_SOURCE_KEY,
+ TURN_TRIGGER_KEY,
SANDBOX_KEY,
SANDBOX_MODE_KEY,
AUTO_REVIEW_ENABLED_KEY,
@@ -220,6 +222,7 @@ pub struct CodexResponsesMetadata {
pub(crate) subagent_header: Option<String>,
pub(crate) subagent_kind: Option<String>,
pub(crate) thread_source: Option<ThreadSource>,
+ pub(crate) turn_trigger: Option<String>,
pub(crate) sandbox: Option<String>,
pub(crate) sandbox_mode: Option<String>,
pub(crate) auto_review_enabled: Option<bool>,
@@ -255,6 +258,7 @@ impl CodexResponsesMetadata {
subagent_header: None,
subagent_kind: None,
thread_source: None,
+ turn_trigger: None,
sandbox: None,
sandbox_mode: None,
auto_review_enabled: None,
@@ -379,6 +383,7 @@ impl CodexResponsesMetadata {
root_turn_id: self.root_turn_id.as_deref(),
subagent_kind: self.subagent_kind.as_deref(),
thread_source: self.thread_source.as_ref(),
+ turn_trigger: self.turn_trigger.as_deref(),
sandbox: self.sandbox.as_deref(),
sandbox_mode: self.sandbox_mode.as_deref(),
auto_review_enabled: self.auto_review_enabled,
@@ -508,6 +513,8 @@ struct CodexTurnMetadataPayload<'a> {
#[serde(default, skip_serializing_if = "Option::is_none")]
thread_source: Option<&'a ThreadSource>,
#[serde(default, skip_serializing_if = "Option::is_none")]
+ turn_trigger: Option<&'a str>,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
sandbox: Option<&'a str>,
#[serde(default, skip_serializing_if = "Option::is_none")]
sandbox_mode: Option<&'a str>,
diff --git a/codex-rs/core/src/session/turn_input.rs b/codex-rs/core/src/session/turn_input.rs
index f0a34e2a27..7eb922ba42 100644
--- a/codex-rs/core/src/session/turn_input.rs
+++ b/codex-rs/core/src/session/turn_input.rs
@@ -120,6 +120,7 @@ impl PreparedTurnInputSettings {
kind: TurnStartKind,
) -> CodexResult<Option<Arc<TurnContext>>> {
let TurnStartOptions {
+ turn_trigger,
final_output_json_schema,
service_tier,
parent_turn_id,
@@ -147,6 +148,11 @@ impl PreparedTurnInputSettings {
let Some((turn_context, settings_snapshot)) = turn_context else {
return Ok(None);
};
+ if let Some(turn_trigger) = turn_trigger {
+ turn_context
+ .turn_metadata_state
+ .set_turn_trigger(turn_trigger);
+ }
if emit_thread_settings_applied {
thread_settings::emit_applied(session, submission_id, settings_snapshot).await;
}
@@ -205,7 +211,12 @@ pub(super) async fn handle_recovery(
thread_settings: ThreadSettingsOverrides,
submission_id: String,
) -> CodexResult<TurnInputSubmission> {
- let request = TurnInputRequest::user_input(Vec::new()).with_thread_settings(thread_settings);
+ let request = TurnInputRequest::user_input(Vec::new())
+ .with_thread_settings(thread_settings)
+ .on_start(TurnStartOptions {
+ turn_trigger: Some("retry".to_string()),
+ ..Default::default()
+ });
start_if_idle(session, request, submission_id, TurnStartKind::Recovery).await
}
@@ -482,7 +493,11 @@ impl Session {
TurnInputRequest::user_input(vec![UserInput::Text {
text,
text_elements: Vec::new(),
- }]),
+ }])
+ .on_start(TurnStartOptions {
+ turn_trigger: Some("realtime".to_string()),
+ ..Default::default()
+ }),
TurnInputMode::StartOrSteer,
submission_id.clone(),
)
diff --git a/codex-rs/core/src/turn_metadata.rs b/codex-rs/core/src/turn_metadata.rs
index 51face5f2c..05b50f1894 100644
--- a/codex-rs/core/src/turn_metadata.rs
+++ b/codex-rs/core/src/turn_metadata.rs
@@ -113,6 +113,7 @@ pub(crate) struct TurnMetadataState {
subagent_header: Option<String>,
subagent_kind: Option<String>,
thread_source: Option<ThreadSource>,
+ turn_trigger: OnceLock<String>,
turn_id: String,
// TODO(anp): Derive this cached tag from TurnEnvironment::sandbox_context
// so metadata reflects the selected environment's backend.
@@ -184,6 +185,7 @@ impl TurnMetadataState {
subagent_header: subagent_header_value(session_source),
subagent_kind: subagent_metadata_kind(session_source),
thread_source,
+ turn_trigger: OnceLock::new(),
turn_id,
sandbox,
sandbox_mode,
@@ -297,6 +299,13 @@ impl TurnMetadataState {
let _ = self.root_turn_id.set(root_turn_id);
}
+ pub(crate) fn set_turn_trigger(&self, turn_trigger: String) {
+ if turn_trigger.trim().is_empty() {
+ return;
+ }
+ let _ = self.turn_trigger.set(turn_trigger);
+ }
+
pub(crate) fn root_turn_id(&self) -> Option<String> {
self.root_turn_id
.get()
@@ -390,6 +399,7 @@ impl TurnMetadataState {
subagent_header: self.subagent_header.clone(),
subagent_kind: self.subagent_kind.clone(),
thread_source: self.thread_source.clone(),
+ turn_trigger: self.turn_trigger.get().cloned(),
sandbox: self.sandbox.clone(),
sandbox_mode: self.sandbox_mode.clone(),
auto_review_enabled: Some(self.auto_review_enabled),
diff --git a/codex-rs/core/src/turn_metadata_tests.rs b/codex-rs/core/src/turn_metadata_tests.rs
index 36ad699bbd..1c296dd3d4 100644
--- a/codex-rs/core/src/turn_metadata_tests.rs
+++ b/codex-rs/core/src/turn_metadata_tests.rs
@@ -12,6 +12,7 @@ use crate::responses_metadata::PARENT_TURN_ID_KEY;
use crate::responses_metadata::ROOT_TURN_ID_KEY;
use crate::responses_metadata::SANDBOX_MODE_KEY;
use crate::responses_metadata::TOOL_NAMESPACES_INFO_KEY;
+use crate::responses_metadata::TURN_TRIGGER_KEY;
use crate::responses_metadata::TurnToolFunctionInfo;
use crate::responses_metadata::TurnToolNamespaceInfo;
use crate::responses_metadata::TurnToolSource;
@@ -682,6 +683,7 @@ fn turn_metadata_state_merges_client_metadata_without_replacing_reserved_fields(
)]));
state.set_parent_turn_id("parent-turn-a".to_string());
state.set_root_turn_id("root-turn-a".to_string());
+ state.set_turn_trigger("goal".to_string());
state.set_responsesapi_client_metadata(HashMap::from([
(
"codex_security_surface".to_string(),
@@ -737,6 +739,7 @@ fn turn_metadata_state_merges_client_metadata_without_replacing_reserved_fields(
"client-supplied".to_string(),
),
("thread_source".to_string(), "client-supplied".to_string()),
+ (TURN_TRIGGER_KEY.to_string(), "client-supplied".to_string()),
("request_kind".to_string(), "client-supplied".to_string()),
(
"turn_started_at_unix_ms".to_string(),
@@ -814,6 +817,7 @@ fn turn_metadata_state_merges_client_metadata_without_replacing_reserved_fields(
assert_eq!(json[ROOT_TURN_ID_KEY].as_str(), Some("root-turn-a"));
assert_eq!(json["subagent_kind"].as_str(), Some("thread_spawn"));
assert_eq!(json["thread_source"].as_str(), Some("automation"));
+ assert_eq!(json[TURN_TRIGGER_KEY].as_str(), Some("goal"));
assert_eq!(json["turn_id"].as_str(), Some("turn-a"));
assert!(json.get("request_kind").is_none());
assert!(json.get(WINDOW_ID_KEY).is_none());
@@ -953,7 +957,12 @@ fn turn_metadata_state_overlays_compaction_only_on_compaction_requests() {
#[test]
fn responses_api_metadata_rejects_reserved_keys() {
- for reserved_key in ["thread_source", WINDOW_ID_KEY, CONTEXT_WINDOW_ID_KEY] {
+ for reserved_key in [
+ "thread_source",
+ TURN_TRIGGER_KEY,
+ WINDOW_ID_KEY,
+ CONTEXT_WINDOW_ID_KEY,
+ ] {
assert_eq!(
validate_extra_metadata(
BTreeMap::from([(reserved_key.to_string(), "sdk".to_string())]).iter()
diff --git a/codex-rs/core/tests/suite/realtime_conversation.rs b/codex-rs/core/tests/suite/realtime_conversation.rs
index 7df6a447bf..490a546ea8 100644
--- a/codex-rs/core/tests/suite/realtime_conversation.rs
+++ b/codex-rs/core/tests/suite/realtime_conversation.rs
@@ -4184,6 +4184,13 @@ async fn inbound_handoff_request_starts_turn() -> Result<()> {
.await;
let request = response_mock.single_request();
+ let turn_metadata: Value = serde_json::from_str(
+ request
+ .header("x-codex-turn-metadata")
+ .as_deref()
+ .context("realtime-routed turn should include turn metadata")?,
+ )?;
+ assert_eq!(turn_metadata["turn_trigger"].as_str(), Some("realtime"));
let user_texts = request.message_input_texts("user");
assert!(user_texts.iter().any(|text| text
== "<realtime_delegation>\n <input>text from realtime</input>\n <transcript_delta>user: text from realtime</transcript_delta>\n</realtime_delegation>"));
diff --git a/codex-rs/core/tests/suite/turn_input_submission.rs b/codex-rs/core/tests/suite/turn_input_submission.rs
index f333ba84f3..475b6a0584 100644
--- a/codex-rs/core/tests/suite/turn_input_submission.rs
+++ b/codex-rs/core/tests/suite/turn_input_submission.rs
@@ -178,9 +178,16 @@ async fn recover_turn_if_idle_preserves_id_and_resumes_plan_mode() {
})
.await;
- let user_input_groups = response_mock
- .single_request()
- .message_input_text_groups("user");
+ let request = response_mock.single_request();
+ let turn_metadata: Value = serde_json::from_str(
+ request
+ .header("x-codex-turn-metadata")
+ .as_deref()
+ .expect("recovered turn should include turn metadata"),
+ )
+ .expect("recovered turn metadata should be valid JSON");
+ assert_eq!(turn_metadata["turn_trigger"].as_str(), Some("retry"));
+ let user_input_groups = request.message_input_text_groups("user");
assert_eq!(user_input_groups.len(), 1);
assert_eq!(user_input_groups[0].len(), 1);
assert!(user_input_groups[0][0].starts_with("<environment_context>"));
diff --git a/codex-rs/exec/src/lib.rs b/codex-rs/exec/src/lib.rs
index efb59b4424..3d049ab907 100644
--- a/codex-rs/exec/src/lib.rs
+++ b/codex-rs/exec/src/lib.rs
@@ -973,6 +973,7 @@ async fn run_exec_session(args: ExecRunArgs) -> anyhow::Result<()> {
request_id: request_ids.next(),
params: TurnStartParams {
thread_id: primary_thread_id_for_span.clone(),
+ turn_trigger: None,
client_user_message_id: None,
input: items.into_iter().map(Into::into).collect(),
responsesapi_client_metadata: None,
diff --git a/codex-rs/ext/goal/src/runtime.rs b/codex-rs/ext/goal/src/runtime.rs
index 28cc327127..d0579090fd 100644
--- a/codex-rs/ext/goal/src/runtime.rs
+++ b/codex-rs/ext/goal/src/runtime.rs
@@ -7,6 +7,7 @@ use codex_core::StartIfIdleSubmission;
use codex_core::ThreadManager;
use codex_core::TurnInput;
use codex_core::TurnInputRequest;
+use codex_core::TurnStartOptions;
use codex_protocol::ThreadId;
use codex_protocol::models::ResponseItem;
use codex_protocol::protocol::ThreadGoal;
@@ -406,7 +407,12 @@ impl GoalRuntimeHandle {
let item = continuation_steering_item(&protocol_goal_from_state(goal));
match thread
- .start_turn_if_idle(TurnInputRequest::new(TurnInput::ResponseItem(item)))
+ .start_turn_if_idle(
+ TurnInputRequest::new(TurnInput::ResponseItem(item)).on_start(TurnStartOptions {
+ turn_trigger: Some("goal".to_string()),
+ ..Default::default()
+ }),
+ )
.await
{
Ok(StartIfIdleSubmission::Started { .. }) => {}
diff --git a/codex-rs/ext/queue/src/service.rs b/codex-rs/ext/queue/src/service.rs
index a8686efb83..e72f0c7cb7 100644
--- a/codex-rs/ext/queue/src/service.rs
+++ b/codex-rs/ext/queue/src/service.rs
@@ -10,6 +10,7 @@ use codex_core::StartIfIdleSubmission;
use codex_core::ThreadManager;
use codex_core::TurnInput;
use codex_core::TurnInputRequest;
+use codex_core::TurnStartOptions;
use codex_extension_api::ExtensionEventSink;
use codex_extension_api::ExtensionFuture;
use codex_extension_api::ThreadIdleCause;
@@ -388,7 +389,12 @@ impl QueuedItemService {
return Err(QueueServiceError::InvalidInput);
};
let submission = thread
- .start_turn_if_idle(TurnInputRequest::new(input).with_trace(trace))
+ .start_turn_if_idle(TurnInputRequest::new(input).with_trace(trace).on_start(
+ TurnStartOptions {
+ turn_trigger: Some("queue".to_string()),
+ ..Default::default()
+ },
+ ))
.await?;
if matches!(submission, StartIfIdleSubmission::Started { .. }) {
self.delete_locked(thread_id, queued_item_id).await?;
@@ -431,7 +437,10 @@ impl QueuedItemService {
}
match thread
- .start_turn_if_idle(TurnInputRequest::new(input))
+ .start_turn_if_idle(TurnInputRequest::new(input).on_start(TurnStartOptions {
+ turn_trigger: Some("queue".to_string()),
+ ..Default::default()
+ }))
.await
{
Ok(StartIfIdleSubmission::Started { .. }) => {
diff --git a/codex-rs/protocol/src/turn_input.rs b/codex-rs/protocol/src/turn_input.rs
index 2fe52a1a43..209de883ca 100644
--- a/codex-rs/protocol/src/turn_input.rs
+++ b/codex-rs/protocol/src/turn_input.rs
@@ -143,6 +143,9 @@ pub enum TurnInputMode {
/// child input, Core also compares root lineage to detect ambiguity.
#[derive(Clone, Debug, Default)]
pub struct TurnStartOptions {
+ /// Source classification for the caller that starts a new turn.
+ /// Ignored when the submitted input steers an active turn.
+ pub turn_trigger: Option<String>,
/// Structured-output schema for a new turn. When steering, Core rejects
/// the input if the active turn uses a different schema.
pub final_output_json_schema: Option<Value>,
diff --git a/codex-rs/tui/src/app_server_session.rs b/codex-rs/tui/src/app_server_session.rs
index 5a60b3af58..186b5393af 100644
--- a/codex-rs/tui/src/app_server_session.rs
+++ b/codex-rs/tui/src/app_server_session.rs
@@ -1201,6 +1201,7 @@ impl AppServerSession {
request_id,
params: TurnStartParams {
thread_id: thread_id.to_string(),
+ turn_trigger: None,
client_user_message_id: None,
input: items,
responsesapi_client_metadata: None,