Add turn-scoped settings updates to the app server (#40656)

## What changed

- Add the experimental `turn/settings/update` method for changing `model`,
  `effort`, `summary`, and `serviceTier` on a specific live turn without
  changing future turns.
- Report whether the update was applied or the target turn was unavailable,
  and reject unsupported fields, disabled feature use, unsafe model changes,
  and direct updates to parent-owned subagents.
- Document the method's feature requirements, null handling, and limits.

## Testing

- Cover current-turn and future-turn isolation, rejected and unavailable
  targets, feature and capability gates, saved threads, and subagent ownership.

GitOrigin-RevId: 18440f6d7ee5fcd06ae23bd41b22c492b62bb2b5
This commit is contained in:
joeflorencio-openai authored and copyberry committed 2026-08-25 17:55:50 +00:00
1 parent a10c8127f7
commit 9695e71519
13 files changed
+626 -10

No files matched your search

@@ -973,6 +973,12 @@ client_request_definitions! {
serialization: thread_id(params.thread_id),
response: v2::TurnStartResponse,
},
#[experimental("turn/settings/update")]
TurnSettingsUpdate => "turn/settings/update" {
params: v2::TurnSettingsUpdateParams,
serialization: thread_id(params.thread_id),
response: v2::TurnSettingsUpdateResponse,
},
TurnSteer => "turn/steer" {
params: v2::TurnSteerParams,
inspect_params: true,
@@ -35,6 +35,54 @@ pub enum TurnStatus {
}
// Turn APIs
/// Experimental settings changes for one running turn, not future turns.
/// Unsupported fields are rejected rather than silently ignored.
/// Any live task kind may accept publication. Child sessions and consumers of
/// frozen initial settings are unchanged.
#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq, JsonSchema, TS)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[ts(export_to = "v2/")]
pub struct TurnSettingsUpdateParams {
pub thread_id: String,
pub turn_id: String,
/// Omission or `null` leaves the model unchanged.
#[ts(optional = nullable)]
pub model: Option<String>,
/// Omission or `null` leaves the effort unchanged.
#[ts(optional = nullable)]
pub effort: Option<ReasoningEffort>,
/// Omission or `null` leaves the summary preference unchanged.
#[ts(optional = nullable)]
pub summary: Option<ReasoningSummary>,
/// `null` clears the requested tier; omission leaves it unchanged.
#[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>>,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct TurnSettingsUpdateResponse {
pub status: TurnSettingsUpdateStatus,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(rename_all = "camelCase", export_to = "v2/")]
pub enum TurnSettingsUpdateStatus {
/// Published for subsequent captures, even if the values were unchanged.
/// Already captured steps are unchanged; a later inference is not guaranteed.
Applied,
/// No matching live task remained available for publication.
TargetUnavailable,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS, ExperimentalApi)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]