app-server.md +108 −9
205- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filters. Returned `thread` objects include runtime `status`.205- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filters. Returned `thread` objects include runtime `status`.
206- `thread/loaded/list` - list the thread ids currently loaded in memory.206- `thread/loaded/list` - list the thread ids currently loaded in memory.
207- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.207- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.
208- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread and emits `thread/closed`.
208- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread` and emits `thread/unarchived`.209- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread` and emits `thread/unarchived`.
209- `thread/status/changed` - notification emitted when a loaded thread's runtime `status` changes.210- `thread/status/changed` - notification emitted when a loaded thread's runtime `status` changes.
210- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.211- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.
227- `windowsSandbox/setupStart` - start Windows sandbox setup for `elevated` or `unelevated` mode; returns quickly and later emits `windowsSandbox/setupCompleted`.228- `windowsSandbox/setupStart` - start Windows sandbox setup for `elevated` or `unelevated` mode; returns quickly and later emits `windowsSandbox/setupCompleted`.
228- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id, plus optional `extraLogFiles` attachments).229- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id, plus optional `extraLogFiles` attachments).
229- `config/read` - fetch the effective configuration on disk after resolving configuration layering.230- `config/read` - fetch the effective configuration on disk after resolving configuration layering.
231- `externalAgentConfig/detect` - detect migratable external-agent artifacts with `includeHome` and optional `cwds`; each detected item includes `cwd` (`null` for home).
232- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home).
230- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.233- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.
231- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.234- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.
232- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists and residency requirements (or `null` if you haven’t set any up).235- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists and residency requirements (or `null` if you haven’t set any up).
301- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filtering.304- `thread/list` supports cursor pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filtering.
302- `thread/loaded/list` returns the thread IDs currently in memory.305- `thread/loaded/list` returns the thread IDs currently in memory.
303- `thread/archive` moves the thread's persisted JSONL log into the archived directory.306- `thread/archive` moves the thread's persisted JSONL log into the archived directory.
307- `thread/unsubscribe` unsubscribes the current connection from a loaded thread and can trigger `thread/closed`.
304- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.308- `thread/unarchive` restores an archived thread rollout back into the active sessions directory.
305- `thread/compact/start` triggers compaction and returns `{}` immediately.309- `thread/compact/start` triggers compaction and returns `{}` immediately.
306- `thread/rollback` drops the last N turns from the in-memory context and records a rollback marker in the thread's persisted JSONL log.310- `thread/rollback` drops the last N turns from the in-memory context and records a rollback marker in the thread's persisted JSONL log.
315 "cwd": "/Users/me/project",319 "cwd": "/Users/me/project",
316 "approvalPolicy": "never",320 "approvalPolicy": "never",
317 "sandbox": "workspaceWrite",321 "sandbox": "workspaceWrite",
318322 "personality": "friendly" "personality": "friendly",
323 "serviceName": "my_app_server_client"
319} }324} }
320{ "id": 10, "result": {325{ "id": 10, "result": {
321 "thread": {326 "thread": {
322 "id": "thr_123",327 "id": "thr_123",
323 "preview": "",328 "preview": "",
329 "ephemeral": false,
324 "modelProvider": "openai",330 "modelProvider": "openai",
325 "createdAt": 1730910000331 "createdAt": 1730910000
326 }332 }
328{ "method": "thread/started", "params": { "thread": { "id": "thr_123" } } }334{ "method": "thread/started", "params": { "thread": { "id": "thr_123" } } }
329```335```
330 336
337`serviceName` is optional. Set it when you want app-server to tag thread-level metrics with your integration's service name.
338
331To continue a stored session, call `thread/resume` with the `thread.id` you recorded earlier. The response shape matches `thread/start`. You can also pass the same configuration overrides supported by `thread/start`, such as `personality`:339To continue a stored session, call `thread/resume` with the `thread.id` you recorded earlier. The response shape matches `thread/start`. You can also pass the same configuration overrides supported by `thread/start`, such as `personality`:
332 340
333```json341```json
335 "threadId": "thr_123",343 "threadId": "thr_123",
336 "personality": "friendly"344 "personality": "friendly"
337} }345} }
338346{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes" } } }{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false } } }
339```347```
340 348
341Resuming a thread doesn't update `thread.updatedAt` (or the rollout file's modified time) by itself. The timestamp updates when you start a turn.349Resuming a thread doesn't update `thread.updatedAt` (or the rollout file's modified time) by itself. The timestamp updates when you start a turn.
365 373
366```json374```json
367{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }375{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }
368376{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "status": { "type": "notLoaded" }, "turns": [] } } }{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false, "status": { "type": "notLoaded" }, "turns": [] } } }
369```377```
370 378
371Unlike `thread/resume`, `thread/read` doesn't load the thread into memory or emit `thread/started`.379Unlike `thread/resume`, `thread/read` doesn't load the thread into memory or emit `thread/started`.
405} }413} }
406{ "id": 20, "result": {414{ "id": 20, "result": {
407 "data": [415 "data": [
408416 { "id": "thr_a", "preview": "Create a TUI", "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } }, { "id": "thr_a", "preview": "Create a TUI", "ephemeral": false, "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } },
409417 { "id": "thr_b", "preview": "Fix tests", "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } } { "id": "thr_b", "preview": "Fix tests", "ephemeral": true, "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } }
410 ],418 ],
411 "nextCursor": "opaque-token-or-null"419 "nextCursor": "opaque-token-or-null"
412} }420} }
437{ "id": 21, "result": { "data": ["thr_123", "thr_456"] } }445{ "id": 21, "result": { "data": ["thr_123", "thr_456"] } }
438```446```
439 447
448### Unsubscribe from a loaded thread
449
450`thread/unsubscribe` removes the current connection's subscription to a thread. The response status is one of:
451
452- `unsubscribed` when the connection was subscribed and is now removed.
453- `notSubscribed` when the connection was not subscribed to that thread.
454- `notLoaded` when the thread is not loaded.
455
456If this was the last subscriber, the server unloads the thread and emits a `thread/status/changed` transition to `notLoaded` plus `thread/closed`.
457
458```json
459{ "method": "thread/unsubscribe", "id": 22, "params": { "threadId": "thr_123" } }
460{ "id": 22, "result": { "status": "unsubscribed" } }
461{ "method": "thread/status/changed", "params": {
462 "threadId": "thr_123",
463 "status": { "type": "notLoaded" }
464} }
465{ "method": "thread/closed", "params": { "threadId": "thr_123" } }
466```
467
440### Archive a thread468### Archive a thread
441 469
442Use `thread/archive` to move the persisted thread log (stored as a JSONL file on disk) into the archived sessions directory.470Use `thread/archive` to move the persisted thread log (stored as a JSONL file on disk) into the archived sessions directory.
470{ "id": 25, "result": {} }498{ "id": 25, "result": {} }
471```499```
472 500
501### Roll back recent turns
502
503Use `thread/rollback` to remove the last `numTurns` entries from the in-memory context and persist a rollback marker in the rollout log. The returned `thread` includes `turns` populated after the rollback.
504
505```json
506{ "method": "thread/rollback", "id": 26, "params": { "threadId": "thr_b", "numTurns": 1 } }
507{ "id": 26, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }
508```
509
473## Turns510## Turns
474 511
475The `input` field accepts a list of items:512The `input` field accepts a list of items:
724 761
725## Events762## Events
726 763
727764Event notifications are the server-initiated stream for thread lifecycles, turn lifecycles, and the items within them. After you start or resume a thread, keep reading the active transport stream for `thread/started`, `thread/archived`, `thread/unarchived`, `thread/status/changed`, `turn/*`, and `item/*` notifications.Event notifications are the server-initiated stream for thread lifecycles, turn lifecycles, and the items within them. After you start or resume a thread, keep reading the active transport stream for `thread/started`, `thread/archived`, `thread/unarchived`, `thread/closed`, `thread/status/changed`, `turn/*`, `item/*`, and `serverRequest/resolved` notifications.
728 765
729### Notification opt-out766### Notification opt-out
730 767
767- `commandExecution` - `{id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}`.804- `commandExecution` - `{id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}`.
768- `fileChange` - `{id, changes, status}` describing proposed edits; `changes` list `{path, kind, diff}`.805- `fileChange` - `{id, changes, status}` describing proposed edits; `changes` list `{path, kind, diff}`.
769- `mcpToolCall` - `{id, server, tool, status, arguments, result?, error?}`.806- `mcpToolCall` - `{id, server, tool, status, arguments, result?, error?}`.
807- `dynamicToolCall` - `{id, tool, arguments, status, contentItems?, success?, durationMs?}` for client-executed dynamic tool invocations.
770- `collabToolCall` - `{id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}`.808- `collabToolCall` - `{id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}`.
771- `webSearch` - `{id, query, action?}` for web search requests issued by the agent.809- `webSearch` - `{id, query, action?}` for web search requests issued by the agent.
772- `imageView` - `{id, path}` emitted when the agent invokes the image viewer tool.810- `imageView` - `{id, path}` emitted when the agent invokes the image viewer tool.
823Order of messages:861Order of messages:
824 862
8251. `item/started` shows the pending `commandExecution` item with `command`, `cwd`, and other fields.8631. `item/started` shows the pending `commandExecution` item with `command`, `cwd`, and other fields.
8268642. `item/commandExecution/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, optional `command`, optional `cwd`, optional `commandActions`, optional `proposedExecpolicyAmendment`, and optional `networkApprovalContext`.2. `item/commandExecution/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, optional `command`, optional `cwd`, optional `commandActions`, optional `proposedExecpolicyAmendment`, optional `networkApprovalContext`, and optional `availableDecisions`. When `initialize.params.capabilities.experimentalApi = true`, the payload can also include experimental `additionalPermissions` describing requested per-command sandbox access. Any filesystem paths inside `additionalPermissions` are absolute on the wire.
8273. Client responds with one of the command execution approval decisions above.8653. Client responds with one of the command execution approval decisions above.
8288664. `item/completed` returns the final `commandExecution` item with `status: completed | failed | declined`.4. `serverRequest/resolved` confirms that the pending request has been answered or cleared.
8675. `item/completed` returns the final `commandExecution` item with `status: completed | failed | declined`.
829 868
830When `networkApprovalContext` is present, the prompt is for managed network access (not a general shell-command approval). The current v2 schema exposes the target `host` and `protocol`; clients should render a network-specific prompt and not rely on `command` being a user-meaningful shell command preview.869When `networkApprovalContext` is present, the prompt is for managed network access (not a general shell-command approval). The current v2 schema exposes the target `host` and `protocol`; clients should render a network-specific prompt and not rely on `command` being a user-meaningful shell command preview.
831 870
8381. `item/started` emits a `fileChange` item with proposed `changes` and `status: "inProgress"`.8771. `item/started` emits a `fileChange` item with proposed `changes` and `status: "inProgress"`.
8392. `item/fileChange/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, and optional `grantRoot`.8782. `item/fileChange/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, and optional `grantRoot`.
8403. Client responds with one of the file change approval decisions above.8793. Client responds with one of the file change approval decisions above.
8418804. `item/completed` returns the final `fileChange` item with `status: completed | failed | declined`.4. `serverRequest/resolved` confirms that the pending request has been answered or cleared.
8815. `item/completed` returns the final `fileChange` item with `status: completed | failed | declined`.
882
883### `tool/requestUserInput`
884
885When the client responds to `item/tool/requestUserInput`, app-server emits `serverRequest/resolved` with `{ threadId, requestId }`. If the pending request is cleared by turn start, turn completion, or turn interruption before the client answers, the server emits the same notification for that cleanup.
886
887### Dynamic tool calls (experimental)
888
889`dynamicTools` on `thread/start` and the corresponding `item/tool/call` request or response flow are experimental APIs.
890
891When a dynamic tool is invoked during a turn, app-server emits:
892
8931. `item/started` with `item.type = "dynamicToolCall"`, `status = "inProgress"`, plus `tool` and `arguments`.
8942. `item/tool/call` as a server request to the client.
8953. The client response payload with returned content items.
8964. `item/completed` with `item.type = "dynamicToolCall"`, the final `status`, and any returned `contentItems` or `success` value.
842 897
843### MCP tool-call approvals (apps)898### MCP tool-call approvals (apps)
844 899
1088}1143}
1089```1144```
1090 1145
1146### Detect and import external agent config
1147
1148Use `externalAgentConfig/detect` to discover migratable external-agent artifacts, then pass the selected entries to `externalAgentConfig/import`.
1149
1150Detection example:
1151
1152```json
1153{ "method": "externalAgentConfig/detect", "id": 63, "params": {
1154 "includeHome": true,
1155 "cwds": ["/Users/me/project"]
1156} }
1157{ "id": 63, "result": {
1158 "items": [
1159 {
1160 "itemType": "AGENTS_MD",
1161 "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
1162 "cwd": "/Users/me/project"
1163 },
1164 {
1165 "itemType": "SKILLS",
1166 "description": "Copy skill folders from /Users/me/.claude/skills to /Users/me/.agents/skills.",
1167 "cwd": null
1168 }
1169 ]
1170} }
1171```
1172
1173Import example:
1174
1175```json
1176{ "method": "externalAgentConfig/import", "id": 64, "params": {
1177 "migrationItems": [
1178 {
1179 "itemType": "AGENTS_MD",
1180 "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
1181 "cwd": "/Users/me/project"
1182 }
1183 ]
1184} }
1185{ "id": 64, "result": {} }
1186```
1187
1188Supported `itemType` values are `AGENTS_MD`, `CONFIG`, `SKILLS`, and `MCP_SERVER_CONFIG`. Detection returns only items that still have work to do. For example, AGENTS migration is skipped when `AGENTS.md` already exists and is non-empty, and skill imports do not overwrite existing skill directories.
1189
1091## Auth endpoints1190## Auth endpoints
1092 1191
1093The JSON-RPC auth/account surface exposes request/response methods plus server-initiated notifications (no `id`). Use these to determine auth state, start or cancel logins, logout, and inspect ChatGPT rate limits.1192The JSON-RPC auth/account surface exposes request/response methods plus server-initiated notifications (no `id`). Use these to determine auth state, start or cancel logins, logout, and inspect ChatGPT rate limits.