app-server: expose loaded thread status via read/list and notifications (#11786)

Motivation
- Today, a newly connected client has no direct way to determine the
current runtime status of threads from read/list responses alone.
- This forces clients to infer state from transient events, which can
lead to stale or inconsistent UI when reconnecting or attaching late.

Changes
- Add `status` to `thread/read` responses.
- Add `statuses` to `thread/list` responses.
- Emit `thread/status/changed` notifications with `threadId` and the new
status.
- Track runtime status for all loaded threads and default unknown
threads to `idle`.
- Update protocol/docs/tests/schema fixtures for the revised API.

Testing
- Validated protocol API changes with automated protocol tests and
regenerated schema/type fixtures.
- Validated app-server behavior with unit and integration test suites,
including status transitions and notifications.
This commit is contained in:
Ruslan Nigmatullin
2026-02-18 15:20:03 -08:00
committed by GitHub
parent 216fe7f2ef
commit 1f54496c48
34 changed files with 2563 additions and 119 deletions

View File

@@ -8108,6 +8108,26 @@
"title": "Thread/startedNotification",
"type": "object"
},
{
"properties": {
"method": {
"enum": [
"thread/status/changed"
],
"title": "Thread/status/changedNotificationMethod",
"type": "string"
},
"params": {
"$ref": "#/definitions/v2/ThreadStatusChangedNotification"
}
},
"required": [
"method",
"params"
],
"title": "Thread/status/changedNotification",
"type": "object"
},
{
"properties": {
"method": {
@@ -15168,6 +15188,14 @@
],
"description": "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.)."
},
"status": {
"allOf": [
{
"$ref": "#/definitions/v2/ThreadStatus"
}
],
"description": "Current runtime status for the thread."
},
"turns": {
"description": "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.",
"items": {
@@ -15189,11 +15217,19 @@
"modelProvider",
"preview",
"source",
"status",
"turns",
"updatedAt"
],
"type": "object"
},
"ThreadActiveFlag": {
"enum": [
"waitingOnApproval",
"waitingOnUserInput"
],
"type": "string"
},
"ThreadArchiveParams": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
@@ -16375,6 +16411,98 @@
"title": "ThreadStartedNotification",
"type": "object"
},
"ThreadStatus": {
"oneOf": [
{
"properties": {
"type": {
"enum": [
"notLoaded"
],
"title": "NotLoadedThreadStatusType",
"type": "string"
}
},
"required": [
"type"
],
"title": "NotLoadedThreadStatus",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"idle"
],
"title": "IdleThreadStatusType",
"type": "string"
}
},
"required": [
"type"
],
"title": "IdleThreadStatus",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"systemError"
],
"title": "SystemErrorThreadStatusType",
"type": "string"
}
},
"required": [
"type"
],
"title": "SystemErrorThreadStatus",
"type": "object"
},
{
"properties": {
"activeFlags": {
"items": {
"$ref": "#/definitions/v2/ThreadActiveFlag"
},
"type": "array"
},
"type": {
"enum": [
"active"
],
"title": "ActiveThreadStatusType",
"type": "string"
}
},
"required": [
"activeFlags",
"type"
],
"title": "ActiveThreadStatus",
"type": "object"
}
]
},
"ThreadStatusChangedNotification": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"status": {
"$ref": "#/definitions/v2/ThreadStatus"
},
"threadId": {
"type": "string"
}
},
"required": [
"status",
"threadId"
],
"title": "ThreadStatusChangedNotification",
"type": "object"
},
"ThreadTokenUsage": {
"properties": {
"last": {