Add app-server next-turn state API

This commit is contained in:
Eric Traut
2026-05-13 09:10:18 -07:00
parent 63a3a26013
commit 7c16071325
29 changed files with 4259 additions and 112 deletions
@@ -732,6 +732,12 @@ client_request_definitions! {
serialization: thread_id(params.thread_id),
response: v2::TurnStartResponse,
},
ThreadTurnContextUpdate => "thread/turnContext/update" {
params: v2::ThreadTurnContextUpdateParams,
inspect_params: true,
serialization: thread_id(params.thread_id),
response: v2::ThreadTurnContextUpdateResponse,
},
TurnSteer => "turn/steer" {
params: v2::TurnSteerParams,
inspect_params: true,
@@ -1432,6 +1438,7 @@ server_notification_definitions! {
Error => "error" (v2::ErrorNotification),
ThreadStarted => "thread/started" (v2::ThreadStartedNotification),
ThreadStatusChanged => "thread/status/changed" (v2::ThreadStatusChangedNotification),
ThreadTurnContextUpdated => "thread/turnContext/updated" (v2::ThreadTurnContextUpdatedNotification),
ThreadArchived => "thread/archived" (v2::ThreadArchivedNotification),
ThreadUnarchived => "thread/unarchived" (v2::ThreadUnarchivedNotification),
ThreadClosed => "thread/closed" (v2::ThreadClosedNotification),
@@ -1531,6 +1538,9 @@ mod tests {
use anyhow::Result;
use codex_protocol::ThreadId;
use codex_protocol::account::PlanType;
use codex_protocol::config_types::CollaborationMode;
use codex_protocol::config_types::ModeKind;
use codex_protocol::config_types::Settings;
use codex_protocol::parse_command::ParsedCommand;
use codex_protocol::protocol::RealtimeConversationVersion;
use codex_protocol::protocol::RealtimeOutputModality;
@@ -1552,6 +1562,31 @@ mod tests {
test_path_buf(&path).abs()
}
fn sample_thread_turn_context(cwd: AbsolutePathBuf) -> v2::ThreadTurnContext {
v2::ThreadTurnContext {
model: "gpt-5".to_string(),
model_provider: "openai".to_string(),
service_tier: None,
cwd,
approval_policy: v2::AskForApproval::OnFailure,
approvals_reviewer: v2::ApprovalsReviewer::User,
sandbox_policy: v2::SandboxPolicy::DangerFullAccess,
permission_profile: v2::PermissionProfile::Disabled,
active_permission_profile: None,
effort: None,
summary: None,
personality: None,
collaboration_mode: CollaborationMode {
mode: ModeKind::Default,
settings: Settings {
model: "gpt-5".to_string(),
reasoning_effort: None,
developer_instructions: None,
},
},
}
}
fn request_id() -> RequestId {
const REQUEST_ID: i64 = 1;
RequestId::Integer(REQUEST_ID)
@@ -1589,6 +1624,20 @@ mod tests {
})
);
let thread_turn_context_update = ClientRequest::ThreadTurnContextUpdate {
request_id: request_id(),
params: v2::ThreadTurnContextUpdateParams {
thread_id: thread_id.clone(),
..Default::default()
},
};
assert_eq!(
thread_turn_context_update.serialization_scope(),
Some(ClientRequestSerializationScope::Thread {
thread_id: thread_id.clone()
})
);
let thread_fork = ClientRequest::ThreadFork {
request_id: request_id(),
params: v2::ThreadForkParams {
@@ -2263,6 +2312,40 @@ mod tests {
Ok(())
}
#[test]
fn serialize_thread_turn_context_update_request() -> Result<()> {
let request = ClientRequest::ThreadTurnContextUpdate {
request_id: RequestId::Integer(5),
params: v2::ThreadTurnContextUpdateParams {
thread_id: "thread-1".to_string(),
model: Some("gpt-5.2".to_string()),
service_tier: Some(None),
..Default::default()
},
};
assert_eq!(
json!({
"method": "thread/turnContext/update",
"id": 5,
"params": {
"threadId": "thread-1",
"cwd": null,
"approvalPolicy": null,
"approvalsReviewer": null,
"sandboxPolicy": null,
"permissions": null,
"model": "gpt-5.2",
"serviceTier": null,
"summary": null,
"personality": null,
"collaborationMode": null
}
}),
serde_json::to_value(&request)?,
);
Ok(())
}
#[test]
fn serialize_client_response() -> Result<()> {
let cwd = absolute_path("/tmp");
@@ -2354,6 +2437,72 @@ mod tests {
Ok(())
}
#[test]
fn serialize_thread_turn_context_response_and_notification() -> Result<()> {
let cwd = absolute_path("/tmp");
let turn_context = sample_thread_turn_context(cwd);
let response = ClientResponse::ThreadTurnContextUpdate {
request_id: RequestId::Integer(11),
response: v2::ThreadTurnContextUpdateResponse {
turn_context: turn_context.clone(),
},
};
let notification = ServerNotification::ThreadTurnContextUpdated(
v2::ThreadTurnContextUpdatedNotification {
thread_id: "thread-1".to_string(),
turn_context,
},
);
let turn_context_json = json!({
"model": "gpt-5",
"modelProvider": "openai",
"serviceTier": null,
"cwd": absolute_path_string("tmp"),
"approvalPolicy": "on-failure",
"approvalsReviewer": "user",
"sandboxPolicy": {
"type": "dangerFullAccess"
},
"permissionProfile": {
"type": "disabled"
},
"activePermissionProfile": null,
"effort": null,
"summary": null,
"personality": null,
"collaborationMode": {
"mode": "default",
"settings": {
"model": "gpt-5",
"reasoning_effort": null,
"developer_instructions": null
}
}
});
assert_eq!(
json!({
"method": "thread/turnContext/update",
"id": 11,
"response": {
"turnContext": turn_context_json
}
}),
serde_json::to_value(&response)?,
);
assert_eq!(
json!({
"method": "thread/turnContext/updated",
"params": {
"threadId": "thread-1",
"turnContext": turn_context_json
}
}),
serde_json::to_value(&notification)?,
);
Ok(())
}
#[test]
fn serialize_config_requirements_read() -> Result<()> {
let request = ClientRequest::ConfigRequirementsRead {
@@ -3486,6 +3486,39 @@ fn turn_start_params_preserve_explicit_null_service_tier() {
assert_eq!(serialized_without_override.get("serviceTier"), None);
}
#[test]
fn thread_turn_context_update_params_support_partial_updates_and_explicit_nulls() {
let params: ThreadTurnContextUpdateParams = serde_json::from_value(json!({
"threadId": "thread_123",
"model": "gpt-5.2",
"serviceTier": null,
"effort": null
}))
.expect("params should deserialize");
assert_eq!(params.thread_id, "thread_123");
assert_eq!(params.model.as_deref(), Some("gpt-5.2"));
assert_eq!(params.service_tier, Some(None));
assert_eq!(params.effort, Some(None));
assert_eq!(params.cwd, None);
let serialized = serde_json::to_value(&params).expect("params should serialize");
assert_eq!(
serialized.get("serviceTier"),
Some(&serde_json::Value::Null)
);
assert_eq!(serialized.get("effort"), Some(&serde_json::Value::Null));
assert_eq!(serialized.get("cwd"), Some(&serde_json::Value::Null));
let without_overrides = ThreadTurnContextUpdateParams {
thread_id: "thread_123".to_string(),
..Default::default()
};
let serialized_without_overrides =
serde_json::to_value(&without_overrides).expect("params should serialize");
assert_eq!(serialized_without_overrides.get("serviceTier"), None);
assert_eq!(serialized_without_overrides.get("effort"), None);
}
#[test]
fn turn_start_params_round_trip_environments() {
let cwd = test_absolute_path();
@@ -13,7 +13,9 @@ use super::TurnEnvironmentParams;
use super::TurnItemsView;
use super::shared::v2_enum_from_core;
use codex_experimental_api_macros::ExperimentalApi;
use codex_protocol::config_types::CollaborationMode;
use codex_protocol::config_types::Personality;
use codex_protocol::config_types::ReasoningSummary;
use codex_protocol::models::ResponseItem;
use codex_protocol::openai_models::ReasoningEffort;
use codex_protocol::protocol::ThreadGoalStatus as CoreThreadGoalStatus;
@@ -169,6 +171,88 @@ pub struct ThreadStartParams {
pub persist_extended_history: bool,
}
#[derive(
Serialize, Deserialize, Debug, Default, Clone, PartialEq, JsonSchema, TS, ExperimentalApi,
)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ThreadTurnContextUpdateParams {
pub thread_id: String,
/// Override the working directory for subsequent turns.
#[ts(optional = nullable)]
pub cwd: Option<PathBuf>,
/// Override the approval policy for subsequent turns.
#[experimental(nested)]
#[ts(optional = nullable)]
pub approval_policy: Option<AskForApproval>,
/// Override where approval requests are routed for review on subsequent turns.
#[ts(optional = nullable)]
pub approvals_reviewer: Option<ApprovalsReviewer>,
/// Override the sandbox policy for subsequent turns.
#[ts(optional = nullable)]
pub sandbox_policy: Option<SandboxPolicy>,
/// Select a named permissions profile for subsequent turns. Cannot be
/// combined with `sandboxPolicy`.
#[ts(optional = nullable)]
pub permissions: Option<PermissionProfileSelectionParams>,
/// Override the model for subsequent turns.
#[ts(optional = nullable)]
pub model: Option<String>,
/// Override the service tier for subsequent turns.
#[serde(
default,
deserialize_with = "crate::protocol::serde_helpers::deserialize_double_option",
serialize_with = "crate::protocol::serde_helpers::serialize_double_option",
skip_serializing_if = "Option::is_none"
)]
#[ts(optional = nullable)]
pub service_tier: Option<Option<String>>,
/// Override the reasoning effort for subsequent turns.
#[serde(
default,
deserialize_with = "crate::protocol::serde_helpers::deserialize_double_option",
serialize_with = "crate::protocol::serde_helpers::serialize_double_option",
skip_serializing_if = "Option::is_none"
)]
#[ts(optional = nullable)]
pub effort: Option<Option<ReasoningEffort>>,
/// Override the reasoning summary for subsequent turns.
#[ts(optional = nullable)]
pub summary: Option<ReasoningSummary>,
/// Override the personality for subsequent turns.
#[ts(optional = nullable)]
pub personality: Option<Personality>,
/// Set a pre-set collaboration mode for subsequent turns.
#[ts(optional = nullable)]
pub collaboration_mode: Option<CollaborationMode>,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ThreadTurnContext {
pub model: String,
pub model_provider: String,
pub service_tier: Option<String>,
pub cwd: AbsolutePathBuf,
pub approval_policy: AskForApproval,
pub approvals_reviewer: ApprovalsReviewer,
pub sandbox_policy: SandboxPolicy,
pub permission_profile: PermissionProfile,
pub active_permission_profile: Option<ActivePermissionProfile>,
pub effort: Option<ReasoningEffort>,
pub summary: Option<ReasoningSummary>,
pub personality: Option<Personality>,
pub collaboration_mode: CollaborationMode,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ThreadTurnContextUpdateResponse {
pub turn_context: ThreadTurnContext,
}
#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
@@ -1131,6 +1215,14 @@ pub struct ThreadStatusChangedNotification {
pub status: ThreadStatus,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct ThreadTurnContextUpdatedNotification {
pub thread_id: String,
pub turn_context: ThreadTurnContext,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]