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 authored and copyberry committed 2026-08-25 19:06:42 +00:00
1 parent 5cb7a35de9
commit d132b69219
19 files changed
+261 -29

No files matched your search

@@ -20164,7 +20164,7 @@
"type": "boolean"
},
"excludeTurns": {
"description": "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.",
"description": "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. Full-history hydration is deprecated for paginated threads; use this with `thread/turns/list` and `thread/items/list` instead.",
"type": "boolean"
},
"lastTurnId": {
@@ -21739,7 +21739,7 @@
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"includeTurns": {
"description": "When true, include turns and their items from rollout history.",
"description": "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`.",
"type": "boolean"
},
"threadId": {
@@ -22366,7 +22366,7 @@
]
},
"excludeTurns": {
"description": "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.",
"description": "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. Full-history hydration is deprecated for paginated threads; use this with `thread/turns/list` and `thread/items/list` instead.",
"type": "boolean"
},
"model": {