Requests and events
AGENT_REQUEST_SCHEMAS maps every request name to { payload, result }, and AGENT_EVENT_SCHEMAS maps every event name to its payload schema. AgentRequestType and AgentEventType are the unions of their names. This page lists both tables with the schema of each side and the type inferred from it. Protocol covers the frames they travel in.
Not every host implements every request. A host that only runs chats refuses the fork requests with chat-unsupported (see Host). A request without a payload or a result uses EmptySchema, {}.
Open and read
| Request | Payload | Result |
|---|---|---|
chat.create | ChatCreatePayloadSchema (ChatCreatePayload) | ChatInfoSchema (ChatInfo) |
chat.list | EmptySchema | ChatListResultSchema (ChatListResult) |
chat.attach | ChatAttachPayloadSchema | ChatAttachResultSchema (ChatAttachResult) |
chat.detach | ChatTargetPayloadSchema (ChatTargetPayload) | EmptySchema |
chat.history | ChatHistoryPayloadSchema | ChatHistoryResultSchema (ChatHistoryResult) |
chat.toolOutput | ChatToolOutputPayloadSchema (ChatToolOutputPayload) | ChatToolOutputResultSchema (ChatToolOutputResult) |
chat.create takes a chatId the client picks, and optionally a provider, account, folder, model selection and runtime mode. ChatIdSchema (ChatId) is any nonempty string. ChatTargetPayload is { chatId }, the payload of every request that only names a chat.
chat.attach takes an optional historyLimit and the since of a reconnect. chat.history takes a cursor and an optional limit, and returns items with a history page (ChatHistoryPageSchema, { start, cursor }). See Attaching and replay.
Send and control
| Request | Payload | Result |
|---|---|---|
chat.send | ChatSendPayloadSchema (ChatSendPayload) | ChatSendResultSchema (ChatSendResult) |
chat.unqueue | ChatQueuePayloadSchema (ChatQueuePayload) | ChatUnqueueResultSchema (ChatUnqueueResult) |
chat.sendNow | ChatQueuePayloadSchema | EmptySchema |
chat.cancel | ChatCancelPayloadSchema (ChatCancelPayload) | EmptySchema |
chat.compact | ChatTargetPayloadSchema | EmptySchema |
chat.clear | ChatClearPayloadSchema (ChatClearPayload) | EmptySchema |
chat.restart | ChatTargetPayloadSchema | EmptySchema |
chat.kill | ChatTargetPayloadSchema | EmptySchema |
chat.send answers { queued, turnId? } once the host took the message. A queued message is a ChatQueuedMessage (ChatQueuedMessageSchema) in ChatInfo.queue. chat.unqueue and chat.sendNow name it by messageId, and chat.unqueue returns it so the client can put it back in the draft. chat.cancel with subagents: true also stops every agent the chat opened. chat.clear refuses a chat in the middle of a turn unless it carries force: true.
Answer
| Request | Payload | Result |
|---|---|---|
chat.approve | ChatApprovePayloadSchema (ChatApprovePayload) | EmptySchema |
chat.answer | ChatAnswerPayloadSchema (ChatAnswerPayload) | EmptySchema |
chat.dismiss | ChatDismissPayloadSchema (ChatDismissPayload) | EmptySchema |
Configure
| Request | Payload | Result |
|---|---|---|
chat.configure | ChatConfigurePayloadSchema (ChatConfigurePayload) | ChatInfoSchema |
chat.setPreferences | ChatPreferencesPayloadSchema (ChatPreferencesPayload) | EmptySchema |
skills.list | SkillsListPayloadSchema (SkillsListPayload) | SkillsListResultSchema (SkillsListResult) |
provider.list | EmptySchema | ProviderListResultSchema (ProviderListResult) |
chat.configure changes a chat's account, model selection, runtime mode or resumeAtReset. The account must be able to continue the conversation. chat.setPreferences stores what new chats start with: a runtime mode, a model selection and an account per provider. skills.list returns the skills a chat can use, each a ChatSkill (ChatSkillSchema) with a ChatSkillSource (ChatSkillSourceSchema).
Turns and forks
| Request | Payload | Result |
|---|---|---|
chat.turnDiff | ChatTurnDiffPayloadSchema (ChatTurnDiffPayload) | ChatTurnDiffResultSchema (ChatTurnDiffResult) |
chat.fork | ChatForkPayloadSchema (ChatForkPayload) | ChatForkResultSchema (ChatForkResult) |
chat.forkInfo | ChatForkInfoPayloadSchema (ChatForkInfoPayload) | ChatForkInfoResultSchema (ChatForkInfoResult) |
chat.summarize | ChatSummarizePayloadSchema (ChatSummarizePayload) | ChatSummarizeResultSchema (ChatSummarizeResult) |
chat.continueOn | ChatContinueOnPayloadSchema (ChatContinueOnPayload) | ChatContinueOnResultSchema (ChatContinueOnResult) |
chat.summarize returns the turn in which the chat writes its summary. chat.continueOn returns the chat that goes on, and the fork when it went on in one. See Checkpoints and forks.
Delegated work
| Request | Payload | Result |
|---|---|---|
chat.subagent | ChatSubagentPayloadSchema (ChatSubagentPayload) | ChatSubagentResultSchema (ChatSubagentResult) |
chat.stopSubagent | ChatStopSubagentPayloadSchema (ChatStopSubagentPayload) | EmptySchema |
chat.stopTask | ChatStopTaskPayloadSchema (ChatStopTaskPayload) | EmptySchema |
chat.goal | ChatGoalPayloadSchema (ChatGoalPayload) | EmptySchema |
chat.subagent reads one subagent's conversation by the toolUseId of the call that started it, a page at a time. With watch: true the host sends chat.subagentChanged while it grows. The result holds items, a page (ChatSubagentPageSchema), the pending requests, whether it is still live, and its source, a ChatSubagentSource (ChatSubagentSourceSchema) that says which CLI's record it was read from. chat.stopTask stops one background task by taskId.
Bookmarks and visuals
| Request | Payload | Result |
|---|---|---|
chat.addBookmark | ChatAddBookmarkPayloadSchema (ChatAddBookmarkPayload) | ChatBookmarksResultSchema (ChatBookmarksResult) |
chat.renameBookmark | ChatRenameBookmarkPayloadSchema (ChatRenameBookmarkPayload) | ChatBookmarksResultSchema |
chat.removeBookmark | ChatRemoveBookmarkPayloadSchema (ChatRemoveBookmarkPayload) | ChatBookmarksResultSchema |
chat.removeVisual | ChatRemoveVisualPayloadSchema (ChatRemoveVisualPayload) | ChatVisualsResultSchema (ChatVisualsResult) |
UI blocks
| Request | Payload | Result |
|---|---|---|
chat.uiChoice | ChatUiChoicePayloadSchema (ChatUiChoicePayload) | ChatSendResultSchema |
ui.query | ChatUiQueryPayloadSchema (ChatUiQueryPayload) | ChatUiQueryReadingSchema (ChatUiQueryReading) |
ui.link | ChatUiLinkPayloadSchema (ChatUiLinkPayload) | ChatUiLinkReadingSchema (ChatUiLinkReading) |
See UI blocks in replies.
Accounts
| Request | Payload | Result |
|---|---|---|
accounts.list | EmptySchema | ProviderAccountsSchema (ProviderAccounts) |
accounts.save | ProviderAccountsSavePayloadSchema (ProviderAccountsSavePayload) | ProviderAccountsSchema |
accounts.reorder | ProviderAccountsReorderPayloadSchema (ProviderAccountsReorderPayload) | ProviderAccountsSchema |
accounts.create | ProviderAccountCreatePayloadSchema (ProviderAccountCreatePayload) | ProviderAccountCreateResultSchema (ProviderAccountCreateResult) |
accounts.refresh | EmptySchema | ProviderAccountsSchema |
accounts.watchLogin | ProviderAccountWatchLoginPayloadSchema (ProviderAccountWatchLoginPayload) | EmptySchema |
accounts.watchLogin answers at once, and later results arrive as accounts.changed. See Accounts.
Usage
| Request | Payload | Result |
|---|---|---|
usage.summary | UsageSummaryPayloadSchema (UsageSummaryPayload) | UsageSummaryResultSchema (UsageSummaryResult) |
usage.subscribe | EmptySchema | EmptySchema |
usage.unsubscribe | EmptySchema | EmptySchema |
usage.limits | EmptySchema | UsageLimitsSnapshotSchema (UsageLimitsSnapshot) |
usage.refreshLimits | EmptySchema | UsageLimitsSnapshotSchema |
See Usage.
Events
| Event | Payload | What a client does with it |
|---|---|---|
chat.event | ChatEventEnvelopeSchema (ChatEventEnvelope) | { chatId, event, seq? }: apply the ChatEvent to a thread the client attached. |
chat.status | ChatStatusEventSchema (ChatStatusEvent) | { chatId, info }: the chat's whole ChatInfo, to every client, attached or not. |
chat.subagentChanged | ChatSubagentChangedEventSchema (ChatSubagentChangedEvent) | { chatId, toolUseId }: ask for the watched subagent page again. It carries no conversation. |
chat.bookmarks | ChatBookmarksEventSchema (ChatBookmarksEvent) | { chatId, bookmarks }: the attached chat's whole bookmark list. |
chat.visuals | ChatVisualsEventSchema (ChatVisualsEvent) | { chatId, visuals }: the attached chat's whole list of visuals. |
accounts.changed | ProviderAccountsSchema | The whole account snapshot. |
usage.changed | UsageChangedEventSchema (UsageChangedEvent) | { scannedAt }: ask for the period on screen again. |
usage.limitsChanged | UsageLimitsSnapshotSchema | The whole plan limit snapshot. |
chat.status goes to every client, so a chat waiting on a person shows it everywhere. info.requests carries a card-sized summary of the waiting approvals and questions. ChatEventSchema (ChatEvent) is the event inside a chat.event; Attaching and replay lists its kinds.