openai/codex
1
0
Fork 0
mirror of https://github.com/openai/codex.git synced 2026-10-19 17:28:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Promote paginated thread history APIs (#40673)

Browse Source 
## What changed

- Make `thread/turns/list`, `thread/items/list`, and `thread/revert` available
  without the experimental API capability.
- Stabilize `thread/reverted`, `thread.historyMode`, and the pagination fields
  used by `thread/resume` and `thread/fork`.
- Publish the promoted requests, responses, and fields in the stable JSON and
  TypeScript schemas, and update the app-server documentation accordingly.

GitOrigin-RevId: 18b8c53c265211597bb1a62fd62f66f4a3df5f06
This commit is contained in:
Owen Lin
2026-08-25 19:03:27 +00:00
committed by copyberry
parent 7e1ee6df6c
commit 5cb7a35de9
38 changed files with 7453 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
codex-rs/app-server-protocol/schema/json/ClientRequest.json
Generated
+191
View File
@@ -4118,6 +4118,10 @@
"ephemeral": {
"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.",
"type": "boolean"
},
"lastTurnId": {
"description": "Optional last turn id to fork through, inclusive.\n\nWhen specified, turns after `last_turn_id` are omitted from the fork. The referenced turn cannot be in progress.",
"type": [
@@ -4265,6 +4269,51 @@
],
"type": "object"
},
"ThreadItemsListParams": {
"properties": {
"cursor": {
"description": "Opaque cursor to pass to the next call to continue after the last item.",
"type": [
"string",
"null"
]
},
"limit": {
"description": "Optional item page size.",
"format": "uint32",
"minimum": 0.0,
"type": [
"integer",
"null"
]
},
"sortDirection": {
"anyOf": [
{
"$ref": "#/definitions/SortDirection"
},
{
"type": "null"
}
],
"description": "Optional item pagination direction; defaults to ascending."
},
"threadId": {
"type": "string"
},
"turnId": {
"description": "Optional turn id to filter by. When omitted, returns items across the thread.",
"type": [
"string",
"null"
]
}
},
"required": [
"threadId"
],
"type": "object"
},
"ThreadListCwdFilter": {
"anyOf": [
{
@@ -4670,6 +4719,10 @@
"null"
]
},
"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.",
"type": "boolean"
},
"model": {
"description": "Configuration overrides for the resumed thread, if any.",
"type": [
@@ -4718,6 +4771,23 @@
],
"type": "object"
},
"ThreadRevertParams": {
"description": "Replace a paginated thread's durable history with the prefix before one turn.\n\nThis only changes persisted conversation history. It does not revert local file changes.",
"properties": {
"beforeTurnId": {
"description": "Turn excluded from the replacement history, together with every later turn.",
"type": "string"
},
"threadId": {
"type": "string"
}
},
"required": [
"beforeTurnId",
"threadId"
],
"type": "object"
},
"ThreadRollbackParams": {
"description": "DEPRECATED: `thread/rollback` will be removed soon.",
"properties": {
@@ -5066,6 +5136,55 @@
],
"type": "string"
},
"ThreadTurnsListParams": {
"properties": {
"cursor": {
"description": "Opaque cursor to pass to the next call to continue after the last turn.",
"type": [
"string",
"null"
]
},
"itemsView": {
"anyOf": [
{
"$ref": "#/definitions/TurnItemsView"
},
{
"type": "null"
}
],
"description": "How much item detail to include for each returned turn; defaults to summary."
},
"limit": {
"description": "Optional turn page size.",
"format": "uint32",
"minimum": 0.0,
"type": [
"integer",
"null"
]
},
"sortDirection": {
"anyOf": [
{
"$ref": "#/definitions/SortDirection"
},
{
"type": "null"
}
],
"description": "Optional turn pagination direction; defaults to descending."
},
"threadId": {
"type": "string"
}
},
"required": [
"threadId"
],
"type": "object"
},
"ThreadUnarchiveParams": {
"properties": {
"threadId": {
@@ -5956,6 +6075,30 @@
"title": "Thread/rollbackRequest",
"type": "object"
},
{
"properties": {
"id": {
"$ref": "#/definitions/RequestId"
},
"method": {
"enum": [
"thread/revert"
],
"title": "Thread/revertRequestMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/ThreadRevertParams"
}
},
"required": [
"id",
"method",
"params"
],
"title": "Thread/revertRequest",
"type": "object"
},
{
"properties": {
"id": {
@@ -6124,6 +6267,54 @@
"title": "Thread/readRequest",
"type": "object"
},
{
"properties": {
"id": {
"$ref": "#/definitions/RequestId"
},
"method": {
"enum": [
"thread/turns/list"
],
"title": "Thread/turns/listRequestMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/ThreadTurnsListParams"
}
},
"required": [
"id",
"method",
"params"
],
"title": "Thread/turns/listRequest",
"type": "object"
},
{
"properties": {
"id": {
"$ref": "#/definitions/RequestId"
},
"method": {
"enum": [
"thread/items/list"
],
"title": "Thread/items/listRequestMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/ThreadItemsListParams"
}
},
"required": [
"id",
"method",
"params"
],
"title": "Thread/items/listRequest",
"type": "object"
},
{
"description": "Append raw Responses API items to the thread history without starting a user turn.",
"properties": {
codex-rs/app-server-protocol/schema/json/ServerNotification.json
Generated
+9
View File
@@ -3940,6 +3940,15 @@
],
"description": "Optional Git metadata captured when the thread was created."
},
"historyMode": {
"allOf": [
{
"$ref": "#/definitions/ThreadHistoryMode"
}
],
"default": "legacy",
"description": "Persisted thread history contract selected when this thread was created."
},
"id": {
"description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
"type": "string"
codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json
Generated
+314
View File
@@ -636,6 +636,30 @@
"title": "Thread/rollbackRequest",
"type": "object"
},
{
"properties": {
"id": {
"$ref": "#/definitions/v2/RequestId"
},
"method": {
"enum": [
"thread/revert"
],
"title": "Thread/revertRequestMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/v2/ThreadRevertParams"
}
},
"required": [
"id",
"method",
"params"
],
"title": "Thread/revertRequest",
"type": "object"
},
{
"properties": {
"id": {
@@ -804,6 +828,54 @@
"title": "Thread/readRequest",
"type": "object"
},
{
"properties": {
"id": {
"$ref": "#/definitions/v2/RequestId"
},
"method": {
"enum": [
"thread/turns/list"
],
"title": "Thread/turns/listRequestMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/v2/ThreadTurnsListParams"
}
},
"required": [
"id",
"method",
"params"
],
"title": "Thread/turns/listRequest",
"type": "object"
},
{
"properties": {
"id": {
"$ref": "#/definitions/v2/RequestId"
},
"method": {
"enum": [
"thread/items/list"
],
"title": "Thread/items/listRequestMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/v2/ThreadItemsListParams"
}
},
"required": [
"id",
"method",
"params"
],
"title": "Thread/items/listRequest",
"type": "object"
},
{
"description": "Append raw Responses API items to the thread history without starting a user turn.",
"properties": {
@@ -19773,6 +19845,15 @@
],
"description": "Optional Git metadata captured when the thread was created."
},
"historyMode": {
"allOf": [
{
"$ref": "#/definitions/v2/ThreadHistoryMode"
}
],
"default": "legacy",
"description": "Persisted thread history contract selected when this thread was created."
},
"id": {
"description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
"type": "string"
@@ -20082,6 +20163,10 @@
"ephemeral": {
"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.",
"type": "boolean"
},
"lastTurnId": {
"description": "Optional last turn id to fork through, inclusive.\n\nWhen specified, turns after `last_turn_id` are omitted from the fork. The referenced turn cannot be in progress.",
"type": [
@@ -21260,6 +21345,83 @@
],
"type": "object"
},
"ThreadItemsListParams": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"cursor": {
"description": "Opaque cursor to pass to the next call to continue after the last item.",
"type": [
"string",
"null"
]
},
"limit": {
"description": "Optional item page size.",
"format": "uint32",
"minimum": 0.0,
"type": [
"integer",
"null"
]
},
"sortDirection": {
"anyOf": [
{
"$ref": "#/definitions/v2/SortDirection"
},
{
"type": "null"
}
],
"description": "Optional item pagination direction; defaults to ascending."
},
"threadId": {
"type": "string"
},
"turnId": {
"description": "Optional turn id to filter by. When omitted, returns items across the thread.",
"type": [
"string",
"null"
]
}
},
"required": [
"threadId"
],
"title": "ThreadItemsListParams",
"type": "object"
},
"ThreadItemsListResponse": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"backwardsCursor": {
"description": "Opaque cursor to pass as `cursor` when reversing `sortDirection`. This is only populated when the page contains at least one item.",
"type": [
"string",
"null"
]
},
"data": {
"items": {
"$ref": "#/definitions/v2/ThreadItemEntry"
},
"type": "array"
},
"nextCursor": {
"description": "Opaque cursor to pass to the next call to continue after the last item. if None, there are no more items to return.",
"type": [
"string",
"null"
]
}
},
"required": [
"data"
],
"title": "ThreadItemsListResponse",
"type": "object"
},
"ThreadListCwdFilter": {
"anyOf": [
{
@@ -22203,6 +22365,10 @@
"null"
]
},
"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.",
"type": "boolean"
},
"model": {
"description": "Configuration overrides for the resumed thread, if any.",
"type": [
@@ -22277,6 +22443,14 @@
},
"type": "array"
},
"itemsBackwardsCursor": {
"default": null,
"description": "Opaque cursor for hydrating paginated items backwards.\n\nPass this as `cursor` to `thread/items/list` with `sortDirection: \"desc\"`. The first page includes the item identified by the cursor.",
"type": [
"string",
"null"
]
},
"model": {
"type": "string"
},
@@ -22309,6 +22483,14 @@
},
"thread": {
"$ref": "#/definitions/v2/Thread"
},
"turnsBackwardsCursor": {
"default": null,
"description": "Opaque cursor for hydrating paginated turns backwards.\n\nPass this as `cursor` to `thread/turns/list` with `sortDirection: \"desc\"`. The first page includes the turn identified by the cursor.",
"type": [
"string",
"null"
]
}
},
"required": [
@@ -22323,6 +22505,57 @@
"title": "ThreadResumeResponse",
"type": "object"
},
"ThreadRevertParams": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Replace a paginated thread's durable history with the prefix before one turn.\n\nThis only changes persisted conversation history. It does not revert local file changes.",
"properties": {
"beforeTurnId": {
"description": "Turn excluded from the replacement history, together with every later turn.",
"type": "string"
},
"threadId": {
"type": "string"
}
},
"required": [
"beforeTurnId",
"threadId"
],
"title": "ThreadRevertParams",
"type": "object"
},
"ThreadRevertResponse": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"itemsBackwardsCursor": {
"description": "Opaque cursor for hydrating paginated items backwards.\n\nPass this as `cursor` to `thread/items/list` with `sortDirection: \"desc\"`. The first page includes the item identified by the cursor.",
"type": [
"string",
"null"
]
},
"thread": {
"allOf": [
{
"$ref": "#/definitions/v2/Thread"
}
],
"description": "Updated loaded thread metadata. `turns` is always empty; hydrate retained history through `thread/turns/list`."
},
"turnsBackwardsCursor": {
"description": "Opaque cursor for hydrating paginated turns backwards.\n\nPass this as `cursor` to `thread/turns/list` with `sortDirection: \"desc\"`. The first page includes the turn identified by the cursor.",
"type": [
"string",
"null"
]
}
},
"required": [
"thread"
],
"title": "ThreadRevertResponse",
"type": "object"
},
"ThreadRevertedNotification": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
@@ -23310,6 +23543,87 @@
"title": "ThreadTokenUsageUpdatedNotification",
"type": "object"
},
"ThreadTurnsListParams": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"cursor": {
"description": "Opaque cursor to pass to the next call to continue after the last turn.",
"type": [
"string",
"null"
]
},
"itemsView": {
"anyOf": [
{
"$ref": "#/definitions/v2/TurnItemsView"
},
{
"type": "null"
}
],
"description": "How much item detail to include for each returned turn; defaults to summary."
},
"limit": {
"description": "Optional turn page size.",
"format": "uint32",
"minimum": 0.0,
"type": [
"integer",
"null"
]
},
"sortDirection": {
"anyOf": [
{
"$ref": "#/definitions/v2/SortDirection"
},
{
"type": "null"
}
],
"description": "Optional turn pagination direction; defaults to descending."
},
"threadId": {
"type": "string"
}
},
"required": [
"threadId"
],
"title": "ThreadTurnsListParams",
"type": "object"
},
"ThreadTurnsListResponse": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"backwardsCursor": {
"description": "Opaque cursor to pass as `cursor` when reversing `sortDirection`. This is only populated when the page contains at least one turn. Use it with the opposite `sortDirection` to include the anchor turn again and catch updates to that turn.",
"type": [
"string",
"null"
]
},
"data": {
"items": {
"$ref": "#/definitions/v2/Turn"
},
"type": "array"
},
"nextCursor": {
"description": "Opaque cursor to pass to the next call to continue after the last turn. if None, there are no more turns to return.",
"type": [
"string",
"null"
]
}
},
"required": [
"data"
],
"title": "ThreadTurnsListResponse",
"type": "object"
},
"ThreadUnarchiveParams": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json
Generated
+314
View File
@@ -2039,6 +2039,30 @@
"title": "Thread/rollbackRequest",
"type": "object"
},
{
"properties": {
"id": {
"$ref": "#/definitions/RequestId"
},
"method": {
"enum": [
"thread/revert"
],
"title": "Thread/revertRequestMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/ThreadRevertParams"
}
},
"required": [
"id",
"method",
"params"
],
"title": "Thread/revertRequest",
"type": "object"
},
{
"properties": {
"id": {
@@ -2207,6 +2231,54 @@
"title": "Thread/readRequest",
"type": "object"
},
{
"properties": {
"id": {
"$ref": "#/definitions/RequestId"
},
"method": {
"enum": [
"thread/turns/list"
],
"title": "Thread/turns/listRequestMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/ThreadTurnsListParams"
}
},
"required": [
"id",
"method",
"params"
],
"title": "Thread/turns/listRequest",
"type": "object"
},
{
"properties": {
"id": {
"$ref": "#/definitions/RequestId"
},
"method": {
"enum": [
"thread/items/list"
],
"title": "Thread/items/listRequestMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/ThreadItemsListParams"
}
},
"required": [
"id",
"method",
"params"
],
"title": "Thread/items/listRequest",
"type": "object"
},
{
"description": "Append raw Responses API items to the thread history without starting a user turn.",
"properties": {
@@ -17508,6 +17580,15 @@
],
"description": "Optional Git metadata captured when the thread was created."
},
"historyMode": {
"allOf": [
{
"$ref": "#/definitions/ThreadHistoryMode"
}
],
"default": "legacy",
"description": "Persisted thread history contract selected when this thread was created."
},
"id": {
"description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
"type": "string"
@@ -17817,6 +17898,10 @@
"ephemeral": {
"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.",
"type": "boolean"
},
"lastTurnId": {
"description": "Optional last turn id to fork through, inclusive.\n\nWhen specified, turns after `last_turn_id` are omitted from the fork. The referenced turn cannot be in progress.",
"type": [
@@ -18995,6 +19080,83 @@
],
"type": "object"
},
"ThreadItemsListParams": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"cursor": {
"description": "Opaque cursor to pass to the next call to continue after the last item.",
"type": [
"string",
"null"
]
},
"limit": {
"description": "Optional item page size.",
"format": "uint32",
"minimum": 0.0,
"type": [
"integer",
"null"
]
},
"sortDirection": {
"anyOf": [
{
"$ref": "#/definitions/SortDirection"
},
{
"type": "null"
}
],
"description": "Optional item pagination direction; defaults to ascending."
},
"threadId": {
"type": "string"
},
"turnId": {
"description": "Optional turn id to filter by. When omitted, returns items across the thread.",
"type": [
"string",
"null"
]
}
},
"required": [
"threadId"
],
"title": "ThreadItemsListParams",
"type": "object"
},
"ThreadItemsListResponse": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"backwardsCursor": {
"description": "Opaque cursor to pass as `cursor` when reversing `sortDirection`. This is only populated when the page contains at least one item.",
"type": [
"string",
"null"
]
},
"data": {
"items": {
"$ref": "#/definitions/ThreadItemEntry"
},
"type": "array"
},
"nextCursor": {
"description": "Opaque cursor to pass to the next call to continue after the last item. if None, there are no more items to return.",
"type": [
"string",
"null"
]
}
},
"required": [
"data"
],
"title": "ThreadItemsListResponse",
"type": "object"
},
"ThreadListCwdFilter": {
"anyOf": [
{
@@ -19938,6 +20100,10 @@
"null"
]
},
"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.",
"type": "boolean"
},
"model": {
"description": "Configuration overrides for the resumed thread, if any.",
"type": [
@@ -20012,6 +20178,14 @@
},
"type": "array"
},
"itemsBackwardsCursor": {
"default": null,
"description": "Opaque cursor for hydrating paginated items backwards.\n\nPass this as `cursor` to `thread/items/list` with `sortDirection: \"desc\"`. The first page includes the item identified by the cursor.",
"type": [
"string",
"null"
]
},
"model": {
"type": "string"
},
@@ -20044,6 +20218,14 @@
},
"thread": {
"$ref": "#/definitions/Thread"
},
"turnsBackwardsCursor": {
"default": null,
"description": "Opaque cursor for hydrating paginated turns backwards.\n\nPass this as `cursor` to `thread/turns/list` with `sortDirection: \"desc\"`. The first page includes the turn identified by the cursor.",
"type": [
"string",
"null"
]
}
},
"required": [
@@ -20058,6 +20240,57 @@
"title": "ThreadResumeResponse",
"type": "object"
},
"ThreadRevertParams": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Replace a paginated thread's durable history with the prefix before one turn.\n\nThis only changes persisted conversation history. It does not revert local file changes.",
"properties": {
"beforeTurnId": {
"description": "Turn excluded from the replacement history, together with every later turn.",
"type": "string"
},
"threadId": {
"type": "string"
}
},
"required": [
"beforeTurnId",
"threadId"
],
"title": "ThreadRevertParams",
"type": "object"
},
"ThreadRevertResponse": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"itemsBackwardsCursor": {
"description": "Opaque cursor for hydrating paginated items backwards.\n\nPass this as `cursor` to `thread/items/list` with `sortDirection: \"desc\"`. The first page includes the item identified by the cursor.",
"type": [
"string",
"null"
]
},
"thread": {
"allOf": [
{
"$ref": "#/definitions/Thread"
}
],
"description": "Updated loaded thread metadata. `turns` is always empty; hydrate retained history through `thread/turns/list`."
},
"turnsBackwardsCursor": {
"description": "Opaque cursor for hydrating paginated turns backwards.\n\nPass this as `cursor` to `thread/turns/list` with `sortDirection: \"desc\"`. The first page includes the turn identified by the cursor.",
"type": [
"string",
"null"
]
}
},
"required": [
"thread"
],
"title": "ThreadRevertResponse",
"type": "object"
},
"ThreadRevertedNotification": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
@@ -21045,6 +21278,87 @@
"title": "ThreadTokenUsageUpdatedNotification",
"type": "object"
},
"ThreadTurnsListParams": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"cursor": {
"description": "Opaque cursor to pass to the next call to continue after the last turn.",
"type": [
"string",
"null"
]
},
"itemsView": {
"anyOf": [
{
"$ref": "#/definitions/TurnItemsView"
},
{
"type": "null"
}
],
"description": "How much item detail to include for each returned turn; defaults to summary."
},
"limit": {
"description": "Optional turn page size.",
"format": "uint32",
"minimum": 0.0,
"type": [
"integer",
"null"
]
},
"sortDirection": {
"anyOf": [
{
"$ref": "#/definitions/SortDirection"
},
{
"type": "null"
}
],
"description": "Optional turn pagination direction; defaults to descending."
},
"threadId": {
"type": "string"
}
},
"required": [
"threadId"
],
"title": "ThreadTurnsListParams",
"type": "object"
},
"ThreadTurnsListResponse": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"backwardsCursor": {
"description": "Opaque cursor to pass as `cursor` when reversing `sortDirection`. This is only populated when the page contains at least one turn. Use it with the opposite `sortDirection` to include the anchor turn again and catch updates to that turn.",
"type": [
"string",
"null"
]
},
"data": {
"items": {
"$ref": "#/definitions/Turn"
},
"type": "array"
},
"nextCursor": {
"description": "Opaque cursor to pass to the next call to continue after the last turn. if None, there are no more turns to return.",
"type": [
"string",
"null"
]
}
},
"required": [
"data"
],
"title": "ThreadTurnsListResponse",
"type": "object"
},
"ThreadUnarchiveParams": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
codex-rs/app-server-protocol/schema/json/v2/ThreadForkParams.json
Generated
+4
View File
@@ -126,6 +126,10 @@
"ephemeral": {
"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.",
"type": "boolean"
},
"lastTurnId": {
"description": "Optional last turn id to fork through, inclusive.\n\nWhen specified, turns after `last_turn_id` are omitted from the fork. The referenced turn cannot be in progress.",
"type": [
codex-rs/app-server-protocol/schema/json/v2/ThreadForkResponse.json
Generated
+9
View File
@@ -1150,6 +1150,15 @@
],
"description": "Optional Git metadata captured when the thread was created."
},
"historyMode": {
"allOf": [
{
"$ref": "#/definitions/ThreadHistoryMode"
}
],
"default": "legacy",
"description": "Persisted thread history contract selected when this thread was created."
},
"id": {
"description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
"type": "string"
codex-rs/app-server-protocol/schema/json/v2/ThreadItemsListParams.json
Generated
+56
View File
@@ -0,0 +1,56 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SortDirection": {
"enum": [
"asc",
"desc"
],
"type": "string"
}
},
"properties": {
"cursor": {
"description": "Opaque cursor to pass to the next call to continue after the last item.",
"type": [
"string",
"null"
]
},
"limit": {
"description": "Optional item page size.",
"format": "uint32",
"minimum": 0.0,
"type": [
"integer",
"null"
]
},
"sortDirection": {
"anyOf": [
{
"$ref": "#/definitions/SortDirection"
},
{
"type": "null"
}
],
"description": "Optional item pagination direction; defaults to ascending."
},
"threadId": {
"type": "string"
},
"turnId": {
"description": "Optional turn id to filter by. When omitted, returns items across the thread.",
"type": [
"string",
"null"
]
}
},
"required": [
"threadId"
],
"title": "ThreadItemsListParams",
"type": "object"
}
codex-rs/app-server-protocol/schema/json/v2/ThreadItemsListResponse.json
Generated
+1730
View File
File diff suppressed because it is too large Load Diff
codex-rs/app-server-protocol/schema/json/v2/ThreadListResponse.json
Generated
+9
View File
@@ -941,6 +941,15 @@
],
"description": "Optional Git metadata captured when the thread was created."
},
"historyMode": {
"allOf": [
{
"$ref": "#/definitions/ThreadHistoryMode"
}
],
"default": "legacy",
"description": "Persisted thread history contract selected when this thread was created."
},
"id": {
"description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
"type": "string"
codex-rs/app-server-protocol/schema/json/v2/ThreadMetadataUpdateResponse.json
Generated
+9
View File
@@ -941,6 +941,15 @@
],
"description": "Optional Git metadata captured when the thread was created."
},
"historyMode": {
"allOf": [
{
"$ref": "#/definitions/ThreadHistoryMode"
}
],
"default": "legacy",
"description": "Persisted thread history contract selected when this thread was created."
},
"id": {
"description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
"type": "string"
codex-rs/app-server-protocol/schema/json/v2/ThreadReadResponse.json
Generated
+9
View File
@@ -941,6 +941,15 @@
],
"description": "Optional Git metadata captured when the thread was created."
},
"historyMode": {
"allOf": [
{
"$ref": "#/definitions/ThreadHistoryMode"
}
],
"default": "legacy",
"description": "Persisted thread history contract selected when this thread was created."
},
"id": {
"description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
"type": "string"
codex-rs/app-server-protocol/schema/json/v2/ThreadResumeParams.json
Generated
+4
View File
@@ -1438,6 +1438,10 @@
"null"
]
},
"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.",
"type": "boolean"
},
"model": {
"description": "Configuration overrides for the resumed thread, if any.",
"type": [
codex-rs/app-server-protocol/schema/json/v2/ThreadResumeResponse.json
Generated
+25
View File
@@ -1150,6 +1150,15 @@
],
"description": "Optional Git metadata captured when the thread was created."
},
"historyMode": {
"allOf": [
{
"$ref": "#/definitions/ThreadHistoryMode"
}
],
"default": "legacy",
"description": "Persisted thread history contract selected when this thread was created."
},
"id": {
"description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
"type": "string"
@@ -2692,6 +2701,14 @@
},
"type": "array"
},
"itemsBackwardsCursor": {
"default": null,
"description": "Opaque cursor for hydrating paginated items backwards.\n\nPass this as `cursor` to `thread/items/list` with `sortDirection: \"desc\"`. The first page includes the item identified by the cursor.",
"type": [
"string",
"null"
]
},
"model": {
"type": "string"
},
@@ -2724,6 +2741,14 @@
},
"thread": {
"$ref": "#/definitions/Thread"
},
"turnsBackwardsCursor": {
"default": null,
"description": "Opaque cursor for hydrating paginated turns backwards.\n\nPass this as `cursor` to `thread/turns/list` with `sortDirection: \"desc\"`. The first page includes the turn identified by the cursor.",
"type": [
"string",
"null"
]
}
},
"required": [
codex-rs/app-server-protocol/schema/json/v2/ThreadRevertParams.json
Generated
+19
View File
@@ -0,0 +1,19 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Replace a paginated thread's durable history with the prefix before one turn.\n\nThis only changes persisted conversation history. It does not revert local file changes.",
"properties": {
"beforeTurnId": {
"description": "Turn excluded from the replacement history, together with every later turn.",
"type": "string"
},
"threadId": {
"type": "string"
}
},
"required": [
"beforeTurnId",
"threadId"
],
"title": "ThreadRevertParams",
"type": "object"
}
codex-rs/app-server-protocol/schema/json/v2/ThreadRevertResponse.json
Generated
+2475
View File
File diff suppressed because it is too large Load Diff
codex-rs/app-server-protocol/schema/json/v2/ThreadRollbackResponse.json
Generated
+9
View File
@@ -941,6 +941,15 @@
],
"description": "Optional Git metadata captured when the thread was created."
},
"historyMode": {
"allOf": [
{
"$ref": "#/definitions/ThreadHistoryMode"
}
],
"default": "legacy",
"description": "Persisted thread history contract selected when this thread was created."
},
"id": {
"description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
"type": "string"
codex-rs/app-server-protocol/schema/json/v2/ThreadStartResponse.json
Generated
+9
View File
@@ -1150,6 +1150,15 @@
],
"description": "Optional Git metadata captured when the thread was created."
},
"historyMode": {
"allOf": [
{
"$ref": "#/definitions/ThreadHistoryMode"
}
],
"default": "legacy",
"description": "Persisted thread history contract selected when this thread was created."
},
"id": {
"description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
"type": "string"
codex-rs/app-server-protocol/schema/json/v2/ThreadStartedNotification.json
Generated
+9
View File
@@ -941,6 +941,15 @@
],
"description": "Optional Git metadata captured when the thread was created."
},
"historyMode": {
"allOf": [
{
"$ref": "#/definitions/ThreadHistoryMode"
}
],
"default": "legacy",
"description": "Persisted thread history contract selected when this thread was created."
},
"id": {
"description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
"type": "string"
codex-rs/app-server-protocol/schema/json/v2/ThreadTurnsListParams.json
Generated
+85
View File
@@ -0,0 +1,85 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"SortDirection": {
"enum": [
"asc",
"desc"
],
"type": "string"
},
"TurnItemsView": {
"oneOf": [
{
"description": "`items` was not loaded for this turn. The field is intentionally empty.",
"enum": [
"notLoaded"
],
"type": "string"
},
{
"description": "`items` contains only a display summary for this turn.",
"enum": [
"summary"
],
"type": "string"
},
{
"description": "`items` contains every ThreadItem available from persisted app-server history for this turn.",
"enum": [
"full"
],
"type": "string"
}
]
}
},
"properties": {
"cursor": {
"description": "Opaque cursor to pass to the next call to continue after the last turn.",
"type": [
"string",
"null"
]
},
"itemsView": {
"anyOf": [
{
"$ref": "#/definitions/TurnItemsView"
},
{
"type": "null"
}
],
"description": "How much item detail to include for each returned turn; defaults to summary."
},
"limit": {
"description": "Optional turn page size.",
"format": "uint32",
"minimum": 0.0,
"type": [
"integer",
"null"
]
},
"sortDirection": {
"anyOf": [
{
"$ref": "#/definitions/SortDirection"
},
{
"type": "null"
}
],
"description": "Optional turn pagination direction; defaults to descending."
},
"threadId": {
"type": "string"
}
},
"required": [
"threadId"
],
"title": "ThreadTurnsListParams",
"type": "object"
}
codex-rs/app-server-protocol/schema/json/v2/ThreadTurnsListResponse.json
Generated
+1990
View File
File diff suppressed because it is too large Load Diff
codex-rs/app-server-protocol/schema/json/v2/ThreadUnarchiveResponse.json
Generated
+9
View File
@@ -941,6 +941,15 @@
],
"description": "Optional Git metadata captured when the thread was created."
},
"historyMode": {
"allOf": [
{
"$ref": "#/definitions/ThreadHistoryMode"
}
],
"default": "legacy",
"description": "Persisted thread history contract selected when this thread was created."
},
"id": {
"description": "Identifier for this thread. Codex-generated thread IDs are UUIDv7.",
"type": "string"
codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst
Generated
BIN
View File
Binary file not shown.
codex-rs/app-server-protocol/schema/typescript/ClientRequest.ts
Generated
+4 -1
View File
File diff suppressed because one or more lines are too long
codex-rs/app-server-protocol/schema/typescript/v2/Thread.ts
Generated
+4
View File
@@ -4,6 +4,7 @@
import type { AbsolutePathBuf } from "../AbsolutePathBuf";
import type { GitInfo } from "./GitInfo";
import type { SessionSource } from "./SessionSource";
import type { ThreadHistoryMode } from "./ThreadHistoryMode";
import type { ThreadSection } from "./ThreadSection";
import type { ThreadSource } from "./ThreadSource";
import type { ThreadStatus } from "./ThreadStatus";
@@ -37,6 +38,9 @@ sectionEnteredAt: number | null, /**
* Canonical project assignment owned by app-server, if any.
*/
projectId: string | null, /**
* Persisted thread history contract selected when this thread was created.
*/
historyMode: ThreadHistoryMode, /**
* Model provider used for this thread (for example, 'openai').
*/
modelProvider: string, /**
codex-rs/app-server-protocol/schema/typescript/v2/ThreadForkParams.ts
Generated
+6 -1
View File
@@ -33,4 +33,9 @@ model?: string | null, modelProvider?: string | null, serviceTier?: string | nul
approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, ephemeral?: boolean, /**
* Optional client-supplied analytics source classification for this forked thread.
*/
threadSource?: ThreadSource | null};
threadSource?: ThreadSource | null, /**
* 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.
*/
excludeTurns?: boolean};
codex-rs/app-server-protocol/schema/typescript/v2/ThreadItemsListParams.ts
Generated
+22
View File
@@ -0,0 +1,22 @@
// GENERATED CODE! DO NOT MODIFY BY HAND!
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
import type { SortDirection } from "./SortDirection";
export type ThreadItemsListParams = { threadId: string,
/**
* Optional turn id to filter by. When omitted, returns items across the thread.
*/
turnId?: string | null,
/**
* Opaque cursor to pass to the next call to continue after the last item.
*/
cursor?: string | null,
/**
* Optional item page size.
*/
limit?: number | null,
/**
* Optional item pagination direction; defaults to ascending.
*/
sortDirection?: SortDirection | null, };
codex-rs/app-server-protocol/schema/typescript/v2/ThreadItemsListResponse.ts
Generated
+16
View File
@@ -0,0 +1,16 @@
// GENERATED CODE! DO NOT MODIFY BY HAND!
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
import type { ThreadItemEntry } from "./ThreadItemEntry";
export type ThreadItemsListResponse = { data: Array<ThreadItemEntry>,
/**
* Opaque cursor to pass to the next call to continue after the last item.
* if None, there are no more items to return.
*/
nextCursor: string | null,
/**
* Opaque cursor to pass as `cursor` when reversing `sortDirection`.
* This is only populated when the page contains at least one item.
*/
backwardsCursor: string | null, };
codex-rs/app-server-protocol/schema/typescript/v2/ThreadResumeParams.ts
Generated
+6 -1
View File
@@ -30,4 +30,9 @@ model?: string | null, modelProvider?: string | null, serviceTier?: string | nul
* Override where approval requests are routed for review on this thread
* and subsequent turns.
*/
approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, personality?: Personality | null};
approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, personality?: Personality | null, /**
* 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.
*/
excludeTurns?: boolean};
codex-rs/app-server-protocol/schema/typescript/v2/ThreadResumeResponse.ts
Generated
+13 -1
View File
@@ -19,4 +19,16 @@ approvalsReviewer: ApprovalsReviewer, /**
* Legacy sandbox policy retained for compatibility. Experimental clients
* should prefer `activePermissionProfile` for profile provenance.
*/
sandbox: SandboxPolicy, reasoningEffort: ReasoningEffort | null};
sandbox: SandboxPolicy, reasoningEffort: ReasoningEffort | null, /**
* Opaque cursor for hydrating paginated turns backwards.
*
* Pass this as `cursor` to `thread/turns/list` with
* `sortDirection: "desc"`. The first page includes the turn identified by the cursor.
*/
turnsBackwardsCursor: string | null, /**
* Opaque cursor for hydrating paginated items backwards.
*
* Pass this as `cursor` to `thread/items/list` with
* `sortDirection: "desc"`. The first page includes the item identified by the cursor.
*/
itemsBackwardsCursor: string | null};
codex-rs/app-server-protocol/schema/typescript/v2/ThreadRevertParams.ts
Generated
+14
View File
@@ -0,0 +1,14 @@
// GENERATED CODE! DO NOT MODIFY BY HAND!
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
/**
* Replace a paginated thread's durable history with the prefix before one turn.
*
* This only changes persisted conversation history. It does not revert local file changes.
*/
export type ThreadRevertParams = { threadId: string,
/**
* Turn excluded from the replacement history, together with every later turn.
*/
beforeTurnId: string, };
codex-rs/app-server-protocol/schema/typescript/v2/ThreadRevertResponse.ts
Generated
+25
View File
@@ -0,0 +1,25 @@
// GENERATED CODE! DO NOT MODIFY BY HAND!
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
import type { Thread } from "./Thread";
export type ThreadRevertResponse = {
/**
* Updated loaded thread metadata. `turns` is always empty; hydrate retained history through
* `thread/turns/list`.
*/
thread: Thread,
/**
* Opaque cursor for hydrating paginated turns backwards.
*
* Pass this as `cursor` to `thread/turns/list` with
* `sortDirection: "desc"`. The first page includes the turn identified by the cursor.
*/
turnsBackwardsCursor: string | null,
/**
* Opaque cursor for hydrating paginated items backwards.
*
* Pass this as `cursor` to `thread/items/list` with
* `sortDirection: "desc"`. The first page includes the item identified by the cursor.
*/
itemsBackwardsCursor: string | null, };
codex-rs/app-server-protocol/schema/typescript/v2/ThreadTurnsListParams.ts
Generated
+23
View File
@@ -0,0 +1,23 @@
// GENERATED CODE! DO NOT MODIFY BY HAND!
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
import type { SortDirection } from "./SortDirection";
import type { TurnItemsView } from "./TurnItemsView";
export type ThreadTurnsListParams = { threadId: string,
/**
* Opaque cursor to pass to the next call to continue after the last turn.
*/
cursor?: string | null,
/**
* Optional turn page size.
*/
limit?: number | null,
/**
* Optional turn pagination direction; defaults to descending.
*/
sortDirection?: SortDirection | null,
/**
* How much item detail to include for each returned turn; defaults to summary.
*/
itemsView?: TurnItemsView | null, };
codex-rs/app-server-protocol/schema/typescript/v2/ThreadTurnsListResponse.ts
Generated
+18
View File
@@ -0,0 +1,18 @@
// GENERATED CODE! DO NOT MODIFY BY HAND!
// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
import type { Turn } from "./Turn";
export type ThreadTurnsListResponse = { data: Array<Turn>,
/**
* Opaque cursor to pass to the next call to continue after the last turn.
* if None, there are no more turns to return.
*/
nextCursor: string | null,
/**
* Opaque cursor to pass as `cursor` when reversing `sortDirection`.
* This is only populated when the page contains at least one turn.
* Use it with the opposite `sortDirection` to include the anchor turn again
* and catch updates to that turn.
*/
backwardsCursor: string | null, };
codex-rs/app-server-protocol/schema/typescript/v2/index.ts
Generated
+6
View File
@@ -479,6 +479,8 @@ export type { ThreadInjectItemsParams } from "./ThreadInjectItemsParams";
export type { ThreadInjectItemsResponse } from "./ThreadInjectItemsResponse";
export type { ThreadItem } from "./ThreadItem";
export type { ThreadItemEntry } from "./ThreadItemEntry";
export type { ThreadItemsListParams } from "./ThreadItemsListParams";
export type { ThreadItemsListResponse } from "./ThreadItemsListResponse";
export type { ThreadListParams } from "./ThreadListParams";
export type { ThreadListResponse } from "./ThreadListResponse";
export type { ThreadLoadedListParams } from "./ThreadLoadedListParams";
@@ -512,6 +514,8 @@ export type { ThreadRealtimeTranscriptRole } from "./ThreadRealtimeTranscriptRol
export type { ThreadResumeInitialTurnsPageParams } from "./ThreadResumeInitialTurnsPageParams";
export type { ThreadResumeParams } from "./ThreadResumeParams";
export type { ThreadResumeResponse } from "./ThreadResumeResponse";
export type { ThreadRevertParams } from "./ThreadRevertParams";
export type { ThreadRevertResponse } from "./ThreadRevertResponse";
export type { ThreadRevertedNotification } from "./ThreadRevertedNotification";
export type { ThreadRollbackParams } from "./ThreadRollbackParams";
export type { ThreadRollbackResponse } from "./ThreadRollbackResponse";
@@ -547,6 +551,8 @@ export type { ThreadStatusChangedNotification } from "./ThreadStatusChangedNotif
export type { ThreadTimelineEntry } from "./ThreadTimelineEntry";
export type { ThreadTokenUsage } from "./ThreadTokenUsage";
export type { ThreadTokenUsageUpdatedNotification } from "./ThreadTokenUsageUpdatedNotification";
export type { ThreadTurnsListParams } from "./ThreadTurnsListParams";
export type { ThreadTurnsListResponse } from "./ThreadTurnsListResponse";
export type { ThreadUnarchiveParams } from "./ThreadUnarchiveParams";
export type { ThreadUnarchiveResponse } from "./ThreadUnarchiveResponse";
export type { ThreadUnarchivedNotification } from "./ThreadUnarchivedNotification";
codex-rs/app-server-protocol/src/protocol/common.rs
-4
View File
@@ -692,7 +692,6 @@ client_request_definitions! {
serialization: thread_id(params.thread_id),
response: v2::ThreadRollbackResponse,
},
#[experimental("thread/revert")]
ThreadRevert => "thread/revert" {
params: v2::ThreadRevertParams,
serialization: thread_id(params.thread_id),
@@ -789,14 +788,12 @@ client_request_definitions! {
serialization: thread_id(params.thread_id),
response: v2::ThreadReadResponse,
},
#[experimental("thread/turns/list")]
ThreadTurnsList => "thread/turns/list" {
params: v2::ThreadTurnsListParams,
// Explicitly concurrent: this primarily reads append-only rollout storage.
serialization: None,
response: v2::ThreadTurnsListResponse,
},
#[experimental("thread/items/list")]
ThreadItemsList => "thread/items/list" {
params: v2::ThreadItemsListParams,
// Explicitly concurrent: this primarily reads append-only rollout storage.
@@ -1845,7 +1842,6 @@ server_notification_definitions! {
ThreadDeleted => "thread/deleted" (v2::ThreadDeletedNotification),
ThreadUnarchived => "thread/unarchived" (v2::ThreadUnarchivedNotification),
ThreadClosed => "thread/closed" (v2::ThreadClosedNotification),
#[experimental("thread/reverted")]
ThreadReverted => "thread/reverted" (v2::ThreadRevertedNotification),
SkillsChanged => "skills/changed" (v2::SkillsChangedNotification),
ThreadNameUpdated => "thread/name/updated" (v2::ThreadNameUpdatedNotification),
codex-rs/app-server-protocol/src/protocol/v2/thread.rs
-4
View File
@@ -398,7 +398,6 @@ pub struct ThreadResumeParams {
/// 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.
#[experimental("thread/resume.excludeTurns")]
#[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
@@ -450,14 +449,12 @@ pub struct ThreadResumeResponse {
///
/// Pass this as `cursor` to `thread/turns/list` with
/// `sortDirection: "desc"`. The first page includes the turn identified by the cursor.
#[experimental("thread/resume.turnsBackwardsCursor")]
#[serde(default)]
pub turns_backwards_cursor: Option<String>,
/// Opaque cursor for hydrating paginated items backwards.
///
/// Pass this as `cursor` to `thread/items/list` with
/// `sortDirection: "desc"`. The first page includes the item identified by the cursor.
#[experimental("thread/resume.itemsBackwardsCursor")]
#[serde(default)]
pub items_backwards_cursor: Option<String>,
}
@@ -589,7 +586,6 @@ pub struct ThreadForkParams {
/// 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.
#[experimental("thread/fork.excludeTurns")]
#[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
codex-rs/app-server-protocol/src/protocol/v2/thread_data.rs
-1
View File
@@ -226,7 +226,6 @@ pub struct Thread {
)]
pub project_id: Option<String>,
/// Persisted thread history contract selected when this thread was created.
#[experimental("thread.historyMode")]
#[serde(default)]
pub history_mode: ThreadHistoryMode,
/// Model provider used for this thread (for example, 'openai').
codex-rs/app-server/README.md
+8 -8
View File
@@ -163,7 +163,7 @@ Example with notification opt-out:
- `server/diagnostics` — experimental; read process-local memory measurements and registered diagnostic gauges.
- `thread/start` — create a new thread; emits `thread/started` (including the current `thread.status`) and auto-subscribes you to turn/item events for that thread. Experimental `projectId` assigns a durable thread to an existing project; ephemeral threads expose the same project identity in live responses without creating a stored/listable assignment. Experimental `historyMode: "paginated"` selects projection-backed durable history. When the request includes a `cwd` and the resolved sandbox is `workspace-write` or full access, app-server also marks that project as trusted in the user `config.toml`. Pass `sessionStartSource: "clear"` when starting a replacement thread after clearing the current session so `SessionStart` hooks receive `source: "clear"` instead of the default `"startup"`. Experimental `allowProviderModelFallback` lets providers backed by an authoritative static model catalog replace an unavailable requested `model` with the catalog default; dynamic or cached catalogs preserve the requested model. Experimental `runtimeWorkspaceRoots` supplies the runtime workspace roots used when app-server creates default environment selections; paths must be absolute. For permissions, prefer experimental `permissions` profile selection by id; the legacy `sandbox` shorthand is still accepted but cannot be combined with `permissions`. Deprecated experimental `multiAgentMode` is ignored; use Ultra reasoning effort for proactive multi-agent behavior. Experimental `environments` selects the sticky execution environments for turns on the thread; omit it to use the server default, pass `[]` to disable environments, or pass explicit environment ids with per-environment `cwd` and optional environment-native `runtimeWorkspaceRoots`. Explicit environments ignore the top-level roots; omitted per-environment roots default to that environment's `cwd`, while an empty list explicitly selects no roots. Experimental `selectedCapabilityRoots` selects environment-owned plugin or standalone-skill roots using environment-native absolute paths. Skills found below those roots are listed and read through the owning environment. Stdio MCP servers declared by selected plugins are started in that environment, and HTTP MCP connections use that environment's HTTP client.
- `thread/resume` — reopen an existing thread by id so subsequent `turn/start` calls append to it. Accepts the same permission override rules as `thread/start`.
- `thread/fork` — fork an existing thread into a new thread id by copying the stored history; pass an optional `lastTurnId` to copy history only through that turn, inclusive, and drop later turns from the fork. An in-progress `lastTurnId` boundary is rejected. Experimental `beforeTurnId` instead copies history strictly before the referenced turn, including when that turn is in progress, and cannot be combined with `lastTurnId`. If both boundaries are null while the source thread is mid-turn, the fork records the same interruption marker as `turn/interrupt` instead of inheriting an unmarked partial turn suffix. The returned `thread.forkedFromId` points at the source thread when known. Accepts `ephemeral: true` for an in-memory temporary fork, emits `thread/started` (including the current `thread.status`), and auto-subscribes you to turn/item events for the new thread. Experimental clients can pass `excludeTurns: true` when they plan to page fork history via `thread/turns/list` instead of receiving the full turn array immediately, or `deferGoalContinuation: true` to carry the source thread's current goal into the fork and run an explicit turn before automatic continuation resumes. Deferred goal continuation is persisted until that turn starts and cannot be combined with `ephemeral: true`. Accepts the same permission override rules as `thread/start`.
- `thread/fork` — fork an existing thread into a new thread id by copying the stored history; pass an optional `lastTurnId` to copy history only through that turn, inclusive, and drop later turns from the fork. An in-progress `lastTurnId` boundary is rejected. Experimental `beforeTurnId` instead copies history strictly before the referenced turn, including when that turn is in progress, and cannot be combined with `lastTurnId`. If both boundaries are null while the source thread is mid-turn, the fork records the same interruption marker as `turn/interrupt` instead of inheriting an unmarked partial turn suffix. The returned `thread.forkedFromId` points at the source thread when known. Accepts `ephemeral: true` for an in-memory temporary fork, emits `thread/started` (including the current `thread.status`), and auto-subscribes you to turn/item events for the new thread. Clients can pass `excludeTurns: true` when they plan to page fork history via `thread/turns/list` instead of receiving the full turn array immediately. Experimental `deferGoalContinuation: true` carries the source thread's current goal into the fork and runs an explicit turn before automatic continuation resumes. Deferred goal continuation is persisted until that turn starts and cannot be combined with `ephemeral: true`. Accepts the same permission override rules as `thread/start`.
- `thread/start`, `thread/resume`, and `thread/fork` responses include the legacy `sandbox` compatibility projection. `instructionSources` lists loaded instruction files using each source environment's native absolute path syntax, including files loaded from remote environments. Experimental clients can read `runtimeWorkspaceRoots` for the thread-scoped runtime roots and `activePermissionProfile` for the named or implicit built-in profile identity/provenance when known. Their deprecated experimental `multiAgentMode` field, and the corresponding thread setting, always report `explicitRequestOnly`; Ultra reasoning effort is the source of proactive multi-agent behavior.
- `thread/list` — page through stored threads; supports cursor-based pagination and optional `modelProviders`, `sourceKinds`, `archived`, `sectionId`, `cwd`, and `searchTerm` filters. Experimental `projectId` filters one project, while `null` selects unassigned threads. Set `sortKey` to `"section_position"` when listing a section in its persisted manual order. Experimental clients can use `parentThreadId` for direct spawned children or `ancestorThreadId` for spawned descendants at any depth; the two filters are mutually exclusive. Review and Guardian threads are not included because they do not participate in that spawn-edge lifecycle. Each returned `thread` includes `status` (`ThreadStatus`), defaulting to `notLoaded` when the thread is not currently loaded. Subagent threads also include `parentThreadId` when the immediate parent is known.
- `project/list`, `project/read`, `project/create`, `project/import`, `project/update`, `project/move`, and `project/delete` — experimental SQLite-backed project APIs. Projects have canonical server-generated IDs, persisted manual positions, ordered absolute roots, and an opaque string metadata bag. `project/move` places a project before another project or appends it when `beforeProjectId` is `null`. Create and import require an opaque `idempotencyKey`; clients should generate a UUID for ordinary creates and may use a stable namespaced legacy ID for migration. Reusing a key returns the original project without emitting notifications or repeating thread assignments, and keys remain reserved after deletion. Import can atomically assign existing thread IDs. Delete clears assignments but never deletes threads, directories, or files.
@@ -174,8 +174,8 @@ Example with notification opt-out:
- `threadSection/delete` — delete an existing custom section and atomically return its member threads to the unsectioned list; returns `{}`. The built-in pinned section cannot be deleted.
- `thread/loaded/list` — list the thread ids currently loaded in memory.
- `thread/read` — read a stored thread by id without resuming it; optionally include turns via `includeTurns`. The returned `thread` includes `status` (`ThreadStatus`), defaulting to `notLoaded` when the thread is not currently loaded. For loaded threads, experimental clients can use `canAcceptDirectInput` to determine whether `turn/start` and `turn/steer` are accepted (`false` for parent-owned Multi-Agent V2 subagents); unloaded stored threads report `null` when that capability is unavailable.
- `thread/turns/list` — experimental; page through a stored thread’s turn history without resuming it; supports cursor-based pagination with `sortDirection`, `itemsView`, `nextCursor`, and `backwardsCursor`.
- `thread/items/list` — experimental; page through persisted thread items without resuming the thread. Pass `turnId` to restrict results to one turn, or omit it to page items across the thread. The active thread store must support item pagination.
- `thread/turns/list` — page through a stored thread’s turn history without resuming it; supports cursor-based pagination with `sortDirection`, `itemsView`, `nextCursor`, and `backwardsCursor`.
- `thread/items/list` — page through persisted thread items without resuming the thread. Pass `turnId` to restrict results to one turn, or omit it to page items across the thread. The active thread store must support item pagination.
- `thread/searchOccurrences` — experimental; find literal, case-insensitive matches in visible user messages and summary-selected final assistant messages within one paginated thread.
- `thread/metadata/update` — patch stored thread metadata in sqlite; supports updating persisted `gitInfo` fields and experimental `projectId`, then returns the refreshed `thread`. Omit `projectId` to preserve assignment and pass an empty string to clear it.
- `thread/section/move` — atomically move a thread into the section identified by `sectionId`, before another thread or at the end when `beforeThreadId` is `null`. Reordering within the same section preserves `sectionEnteredAt`; entering a different section resets it. Set `sectionId` to `null` to remove the thread from its section. Returns `{}` on success.
@@ -208,7 +208,7 @@ Example with notification opt-out:
- `thread/backgroundTerminals/list` — list running background terminals for a loaded thread (experimental; requires `capabilities.experimentalApi`); returns `data` with the running terminal ids.
- `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.
- `thread/revert` — 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. 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.
@@ -367,7 +367,7 @@ To continue a stored session, call `thread/resume` with the `thread.id` you prev
Parent-owned Multi-Agent V2 children are an exception: `thread/resume` ignores configuration overrides and reattaches to the existing child. An unloaded child is reloaded through its actual, currently loaded parent using parent-derived configuration. If that owner-controlled reload cannot be performed, the request returns JSON-RPC error `-32600`; resume the parent first, or use `thread/read` or `thread/turns/list` to inspect the child's stored history without loading it. This policy follows the child's multi-agent runtime, including leaf workers whose models cannot delegate further.
By default, `thread/resume` includes the reconstructed turn history in `thread.turns`. Experimental clients can pass `excludeTurns: true` to return only thread metadata and live resume state, then call `thread/turns/list` separately if they want to page the turn history over the network. A cold paginated resume can still replay persisted `thread/tokenUsage/updated` when it can identify the corresponding stored turn; resuming an already-loaded thread waits for the next live update.
By default, `thread/resume` includes the reconstructed turn history in `thread.turns`. Clients can pass `excludeTurns: true` to return only thread metadata and live resume state, then call `thread/turns/list` separately if they want to page the turn history over the network. A cold paginated resume can still replay persisted `thread/tokenUsage/updated` when it can identify the corresponding stored turn; resuming an already-loaded thread waits for the next live update.
Paginated threads keep the same resume contract as legacy threads. A default resume materializes the full projected history into `thread.turns`; `excludeTurns: true` keeps that array empty and includes `turnsBackwardsCursor` and `itemsBackwardsCursor` for the durable history visible at the resume boundary. Pass each cursor directly to its matching list API with `sortDirection: "desc"`; the first page includes the row identified by the cursor, while newer records arrive through live notifications. Either cursor is `null` when there is no durable row yet.
@@ -423,7 +423,7 @@ To branch from a stored session, call `thread/fork` with the `thread.id`. This c
{ "method": "thread/started", "params": { "thread": { … } } }
```
Like `thread/resume`, experimental clients can pass `excludeTurns: true` to `thread/fork` to return only thread metadata in `thread.turns` and page history with `thread/turns/list`. Metadata-only forks do not replay restored `thread/tokenUsage/updated`. Ephemeral forks of paginated threads require `excludeTurns: true`.
Like `thread/resume`, clients can pass `excludeTurns: true` to `thread/fork` to return only thread metadata in `thread.turns` and page history with `thread/turns/list`. Metadata-only forks do not replay restored `thread/tokenUsage/updated`. Ephemeral forks of paginated threads require `excludeTurns: true`.
### Example: List threads (with pagination & filters)
@@ -591,9 +591,9 @@ Paginated threads can also use `includeTurns: true`, but clients should prefer
} }
```
### Example: List thread turns (experimental)
### Example: List thread turns
Use `thread/turns/list` with `capabilities.experimentalApi = true` to page a stored thread’s turn history without resuming it. By default, results are sorted descending so clients can start at the present and fetch older turns with `nextCursor`. The response also includes `backwardsCursor`; pass it as `cursor` on a later request with `sortDirection: "asc"` to fetch turns newer than the first item from the earlier page.
Use `thread/turns/list` to page a stored thread’s turn history without resuming it. By default, results are sorted descending so clients can start at the present and fetch older turns with `nextCursor`. The response also includes `backwardsCursor`; pass it as `cursor` on a later request with `sortDirection: "asc"` to fetch turns newer than the first item from the earlier page.
Every returned `Turn` includes `itemsView`, which tells clients whether the `items` array was omitted intentionally (`notLoaded`), contains only summary items (`summary`), or contains every item available from persisted app-server history (`full`). Pass `itemsView` to choose the returned detail level; omitted `itemsView` defaults to `"summary"`.