Deprecate full-history hydration for paginated threads (#40676)

## Why

Paginated thread history should be loaded incrementally through
`thread/turns/list` and `thread/items/list` instead of being fully reconstructed
in `thread.turns`.

## What changed

- Emit `deprecationNotice` when `thread/read`, `thread/resume`, or `thread/fork`
  requests full history for a paginated thread.
- Direct clients to omit `includeTurns` for reads or use `excludeTurns: true` for
  resumes and forks, then page history through the list APIs.
- Document the deprecation in the protocol schemas and app-server README.

## Testing

- Cover notices for paginated reads, cold and loaded resumes, and forks.
- Verify metadata-only requests, legacy threads, and rejected forks do not emit
  the notice.

GitOrigin-RevId: 0d387b46d73608f90b7960120a54af4ef332e510
This commit is contained in:
Owen Lin
2026-08-25 19:06:42 +00:00
committed by copyberry
parent 5cb7a35de9
commit d132b69219
19 changed files with 261 additions and 29 deletions
@@ -397,7 +397,9 @@ pub struct ThreadResumeParams {
pub personality: Option<Personality>,
/// When true, return only thread metadata and live-resume state without
/// populating `thread.turns`. This is useful when the client plans to call
/// `thread/turns/list` immediately after resuming.
/// `thread/turns/list` immediately after resuming. Full-history hydration
/// is deprecated for paginated threads; use this with `thread/turns/list`
/// and `thread/items/list` instead.
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub exclude_turns: bool,
/// When present, include a `thread/turns/list` page in the resume response
@@ -585,7 +587,9 @@ pub struct ThreadForkParams {
pub thread_source: Option<ThreadSource>,
/// When true, return only thread metadata and live fork state without
/// populating `thread.turns`. This is useful when the client plans to call
/// `thread/turns/list` immediately after forking.
/// `thread/turns/list` immediately after forking. Full-history hydration
/// is deprecated for paginated threads; use this with `thread/turns/list`
/// and `thread/items/list` instead.
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub exclude_turns: bool,
/// When true, carry the source thread's current goal into the fork without
@@ -1646,6 +1650,9 @@ pub enum ThreadActiveFlag {
pub struct ThreadReadParams {
pub thread_id: String,
/// When true, include turns and their items from rollout history.
/// Full-history hydration is deprecated for paginated threads; prefer a
/// metadata-only read and page with `thread/turns/list` and
/// `thread/items/list`.
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
pub include_turns: bool,
}