聊天通道

ahp-chat:/<uuid> 通道的參考資料 — 每個聊天的狀態、回合生命週期、工具呼叫狀態機、附件、待處理訊息與輸入請求。聊天隸屬於某個工作階段（請參閱工作階段通道）；一個工作階段可包含多個聊天。線路層級的概觀請參閱聊天通道規格。

JSON Schema: state.schema.json

狀態類型

ChatState

單一聊天的完整狀態，於用戶端訂閱該聊天的 URI 時載入。

聊天的輕量目錄表示為 {@link ChatSummary}，承載於 {@link SessionState.chats | SessionState.chats}。ChatState 將每個 {@link ChatSummary} 欄位直接 反正規化 到自身，讓訂閱者收到單一 扁平物件，而不需合併巢狀的 summary 子物件。產生者 MUST 保持兩個 表示一致：下方內嵌欄位的任何變更，也 SHOULD 透過相符的 {@link SessionChatUpdatedAction | session/chatUpdated} 操作在父工作階段上發布。

欄位	類型	必要	說明
resource	URI	是	聊天 URI
title	string	是	聊天標題
status	SessionStatus	是	目前的聊天狀態（沿用 SessionStatus 形狀）
activity	string	否	此聊天目前正在做什麼的人類可讀描述
modifiedAt	string	是	上次修改時間戳記（ISO 8601，例如 "2025-03-10T18:42:03.123Z"）
origin	ChatOrigin	否	此聊天如何產生
interactivity	ChatInteractivity	否	使用者可如何與此聊天互動。參見 {@link ChatInteractivity}。 支援代理程式團隊模式，其中工作者聊天為唯讀或隱藏。當此欄位缺省時， 為向後相容預設為 {@link ChatInteractivity.Full}。
workingDirectories	URI[]	否	此聊天的代理程式具有工具存取權的工作階段 {@link SessionState.workingDirectories | workingDirectories} 子集。每個 項目 MUST 存在於所屬工作階段的 workingDirectories 中；伺服器 MUST 拒絕 違反此限制的 chat/workingDirectorySet 操作。 當缺省時，聊天會繼承完整的工作階段集合。當存在但為空（不建議）時， 聊天完全沒有工作目錄工具存取權。 分派 chat/workingDirectorySet / chat/workingDirectoryRemoved 以 更新執行中聊天上的子集。
primaryWorkingDirectory	URI	否	聊天的主要工作目錄 — 此聊天所居中的特殊根目錄（例如此聊天的代理程式 行程根目錄、相對路徑的預設位置）。MUST 為此聊天的有效工作目錄之一 （{@link workingDirectories}，或當缺省時為工作階段的集合）。當代理程式 廣告 {@link MultipleWorkingDirectoriesCapability.requiresPrimary} 時存在。 建立時即為唯讀且固定。 其值取自 {@link CreateChatParams.primaryWorkingDirectory}（或對於工作階段的預設 聊天，取自 {@link CreateSessionParams.primaryWorkingDirectory}），且在 聊天生命週期內不會改變 — 沒有操作可變動它，且它不參與 session/chatUpdated。
turns	Turn[]	是	已完成的回合
turnsNextCursor	string	否	用於將較舊的已完成回合載入此聊天狀態的游標。 存在時表示 turns 為尾端視窗，且有更多歷史回合可用。將此不透明 游標傳遞給 fetchTurns；主機 MUST 在回應前將載入的回合插入狀態， 並更新或清除此游標。缺省時表示狀態包含所有保留的回合。
activeTurn	ActiveTurn	否	目前進行中的回合
steeringMessage	PendingMessage	否	在適當時機注入目前回合的訊息
queuedMessages	PendingMessage[]	否	在目前回合結束後自動作為新回合傳送的訊息
draft	Message	否	使用者對此聊天進行中的草稿輸入 — 他們正在撰寫但尚未傳送的訊息， 包含其 {@link Message.model | model} / {@link Message.agent | agent} 選擇與附件。 用戶端 MAY 定期將其本地輸入狀態同步到此欄位，讓草稿在重新載入後存活， 且對檢視相同聊天的其他用戶端可見。並 不 需要積極同步 — 用戶端 SHOULD 去抖動，且 MAY 僅在適當時機同步。在為既有聊天呈現輸入 UI 時， 用戶端 SHOULD 使用任何 draft 來初始化其輸入狀態。一旦訊息傳送即清除 （設為 undefined）。
_meta	Record<string, unknown>	否	此聊天的額外提供者特定中介資料。

ChatSummary

聊天的輕量目錄項目，承載於 {@link SessionState.chats | SessionState.chats}。 完整對話存在於 {@link ChatState}，其內嵌（反正規化）了下方所有欄位。

欄位	類型	必要	說明
resource	URI	是	聊天 URI
title	string	是	聊天標題
status	SessionStatus	是	目前的聊天狀態（沿用 SessionStatus 形狀）
activity	string	否	此聊天目前正在做什麼的人類可讀描述
modifiedAt	string	是	上次修改時間戳記（ISO 8601，例如 "2025-03-10T18:42:03.123Z"）
origin	ChatOrigin	否	此聊天如何產生
interactivity	ChatInteractivity	否	使用者可如何與此聊天互動。參見 {@link ChatInteractivity}。 支援代理程式團隊模式，其中工作者聊天為唯讀或隱藏。當此欄位缺省時， 為向後相容預設為 {@link ChatInteractivity.Full}。
workingDirectories	URI[]	否	此聊天使用的工作階段工作目錄子集。 完整語意請參見 {@link ChatState.workingDirectories}。
primaryWorkingDirectory	URI	否	聊天的主要工作目錄。 完整語意請參見 {@link ChatState.primaryWorkingDirectory}。

ChatOriginKind

{@link ChatOrigin} 的判別欄位 — 聊天如何產生。

成員	值	說明
User	'user'	使用者明確建立此聊天（例如透過主機 UI）。
Fork	'fork'	在特定回合從既有聊天分岔。
SideChat	'sideChat'	從特定回合建立為獨立的側邊對話。
Tool	'tool'	由執行於另一個聊天的工具呼叫產生（例如子代理程式委派）。

SideChatSelection

建立側邊聊天時擷取的不可變選取文字快照。

主機在接受 createChat 時記錄此確切文字；之後對來源聊天的變更不會 改變它。

欄位	類型	必要	說明
text	string	是	在接受 createChat 時擷取的確切選取文字快照。 MUST 非空。
responsePartId	string	否	主機拍攝快照時，包含 {@link text} 的回應部分的選用出處資訊。 僅供參考：這不是即時範圍或位移，且 MUST NOT 用於重新計算 text。

ChatOrigin

聊天如何產生。用戶端 MAY 使用它來呈現情境 UI（父項指標、分岔標記、 「由工具產生」徽章）。

分岔與側邊聊天起源兩者都帶有穩定的頂層 turnId，伴隨其判別 kind 值，而非快照建立時該回合為作用中或歷史的狀態。消費者視需要將 識別碼解析為來源聊天目前的 activeTurn 或保留的 turns。

當主機接受從來源聊天目前作用中回合建立側邊聊天時，它會快照保留的 歷史，加上該回合目前的使用者訊息與任何已可用的部分代理程式回應。 之後來源回合的差異不會回溯變更所建立側邊聊天的起始情境，且一旦 來源回合完成，它仍由相同的 turnId 參照。側邊聊天起源 MAY 也保留 在接受時擷取的不可變 {@link SideChatSelection | 選取文字快照}；其中 的任何 responsePartId 僅為出處，不是範圍。

tool 變體從工作者側記錄工具產生的工作者：其 chat/toolCallId 識別父聊天中產生的工具呼叫。這是產生關係的標準記錄。相同的邊從父側 由 {@link ToolResultSubagentContent} 呈現，其 resource 為此聊天的 URI；主機 MUST 保持兩者一致。

{ kind: ChatOriginKind.User } | { kind: ChatOriginKind.Fork; chat: URI; turnId: string } | { kind: ChatOriginKind.SideChat; chat: URI; turnId: string; selection?: SideChatSelection } | { kind: ChatOriginKind.Tool; chat: URI; toolCallId: string }

ChatInteractivity

使用者可如何與聊天互動。

• Full — 使用者可傳送訊息並觀看（缺省時為預設）
• ReadOnly — 使用者可觀看但無法傳送訊息（例如代理程式團隊工作者）
• Hidden — 完全不顯示在 UI 中的內部工作者

支援代理程式團隊模式，其中主導聊天為完全互動，而工作者聊天為唯讀 （可見以供可觀測性）或隱藏（內部實作細節）。框架根據聊天的角色 設定此值；UI 使用它來顯示適當的控制項。

成員	值	說明
Full	'full'	使用者可傳送訊息並觀看（缺省時為預設）
ReadOnly	'read-only'	使用者可觀看但無法傳送訊息
Hidden	'hidden'	完全不顯示在 UI 中的內部工作者

PendingMessageKind

待處理訊息種類的判別欄位。

成員	值	說明
Steering	'steering'	在適當時機注入目前回合
Queued	'queued'	在目前回合結束後自動作為新回合傳送

PendingMessage

已排入佇列、待未來傳遞給代理程式的訊息。

引導訊息會在進行中注入目前回合。佇列訊息會在目前回合自然結束後 自動作為新回合啟動。

欄位	類型	說明
id	string	此待處理訊息的唯一識別碼
message	Message	將啟動下一回合的訊息

ChatInputResponseKind

用戶端如何完成輸入請求。

成員	值
Accept	'accept'
Decline	'decline'
Cancel	'cancel'

ChatInputQuestionKind

問題／輸入控制項種類。

成員	值
Text	'text'
Number	'number'
Integer	'integer'
Boolean	'boolean'
SingleSelect	'single-select'
MultiSelect	'multi-select'

ChatInputOption

選擇式問題中的一個選項。

欄位	類型	必要	說明
id	string	是	穩定的選項識別碼；對 MCP 列舉值而言此為列舉字串
label	string	是	顯示標籤
description	string	否	選用的次要文字
recommended	boolean	否	此選項是否為建議／預設選擇

ChatInputTextQuestion

聊天輸入請求中的文字問題。

欄位	類型	必要	說明
kind	ChatInputQuestionKind.Text	是
format	string	否	文字問題的格式提示，例如 email、uri、date 或 date-time
min	number	否	最小字串長度
max	number	否	最大字串長度
defaultValue	string	否	預設文字

ChatInputNumberQuestion

聊天輸入請求中的數值問題。

欄位	類型	必要	說明
kind	ChatInputQuestionKind.Number | ChatInputQuestionKind.Integer	是
min	number	否	最小值
max	number	否	最大值
defaultValue	number	否	預設數值

ChatInputBooleanQuestion

聊天輸入請求中的布林值問題。

欄位	類型	必要	說明
kind	ChatInputQuestionKind.Boolean	是
defaultValue	boolean	否	預設布林值

ChatInputSingleSelectQuestion

聊天輸入請求中的單選問題。

欄位	類型	必要	說明
kind	ChatInputQuestionKind.SingleSelect	是
options	ChatInputOption[]	是	使用者可從中選取的選項
allowFreeformInput	boolean	否	使用者是否可改為輸入文字而不選取選項

ChatInputMultiSelectQuestion

聊天輸入請求中的多選問題。

欄位	類型	必要	說明
kind	ChatInputQuestionKind.MultiSelect	是
options	ChatInputOption[]	是	使用者可從中選取的選項
allowFreeformInput	boolean	否	使用者是否可在選取選項之外另輸入文字
min	number	否	最小選取項目數
max	number	否	最大選取項目數

ChatInputQuestion

聊天輸入請求中的單一問題。

ChatInputTextQuestion | ChatInputNumberQuestion | ChatInputBooleanQuestion | ChatInputSingleSelectQuestion | ChatInputMultiSelectQuestion

ChatInputRequest

由 {@link InputRequestResponsePart} 承載的請求有效負載。

伺服器會以 chat/inputRequested 建立或取代包含的回應部分。用戶端以 chat/inputAnswerChanged 同步草稿，並以 chat/inputCompleted 提交回應。

欄位	類型	必要	說明
id	string	是	穩定的請求識別碼
message	string	否	整個請求的顯示訊息
url	URI	否	使用者應檢閱或開啟的 URL，用於 URL 式引出
questions	ChatInputQuestion[]	否	要詢問使用者的有序問題
answers	Record<string, ChatInputAnswer>	否	目前的草稿或已提交答案，以問題 ID 為索引鍵

ChatInputAnswerValueKind

答案值種類。

成員	值
Text	'text'
Number	'number'
Boolean	'boolean'
Selected	'selected'
SelectedMany	'selected-many'

ChatInputTextAnswerValue

為單一答案擷取的值。

欄位	類型	說明
kind	ChatInputAnswerValueKind.Text
value	string

ChatInputNumberAnswerValue

欄位	類型	說明
kind	ChatInputAnswerValueKind.Number
value	number

ChatInputBooleanAnswerValue

欄位	類型	說明
kind	ChatInputAnswerValueKind.Boolean
value	boolean

ChatInputSelectedAnswerValue

欄位	類型	必要	說明
kind	ChatInputAnswerValueKind.Selected	是
value	string	是
freeformValues	string[]	否	改為輸入而非選取選項的自由格式文字

ChatInputSelectedManyAnswerValue

欄位	類型	必要	說明
kind	ChatInputAnswerValueKind.SelectedMany	是
value	string[]	是
freeformValues	string[]	否	除了選取選項之外另輸入的自由格式文字

ChatInputAnswerValue

ChatInputTextAnswerValue | ChatInputNumberAnswerValue | ChatInputBooleanAnswerValue | ChatInputSelectedAnswerValue | ChatInputSelectedManyAnswerValue

ChatInputAnswered

欄位	類型	說明
state	ChatInputAnswerState.Draft | ChatInputAnswerState.Submitted	答案狀態
value	ChatInputAnswerValue	答案值

ChatInputSkipped

欄位	類型	必要	說明
state	ChatInputAnswerState.Skipped	是	答案狀態
freeformValues	string[]	否	跳過時擷取的自由格式原因或值（若有）

ChatInputAnswerState

答案生命週期狀態。

成員	值
Draft	'draft'
Submitted	'submitted'
Skipped	'skipped'

ChatInputAnswer

單一問題的草稿、已提交或已跳過答案。

ChatInputAnswered | ChatInputSkipped

TurnState

回合如何結束。

成員	值
Complete	'complete'
Cancelled	'cancelled'
Error	'error'

MessageAttachmentKind

{@link MessageAttachment} 變體的判別欄位。

成員	值	說明
Simple	'simple'	簡單、不透明的附件，其表示由產生者描述。
EmbeddedResource	'embeddedResource'	資料以 base64 字串內嵌的附件。
Resource	'resource'	依 URI 參照資源的附件。
Annotations	'annotations'	參照註解通道上之註解的附件。
Chat	'chat'	參照另一個聊天之有界轉錄的附件。

Turn

已完成的請求／回應循環。

欄位	類型	必要	說明
id	string	是	回合識別碼
startedAt	string	否	此回合開始時的 ISO 8601 時間戳記。
duration	number	否	回合持續時間，以毫秒為單位。
message	Message	是	啟動此回合的訊息
responseParts	ResponsePart[]	是	所有回應內容依串流順序排列：文字、工具呼叫、推理與內容參照。 消費者應透過串接 markdown 部分來衍生顯示文字，並透過篩選 ToolCall 部分來尋找工具呼叫。
usage	UsageInfo | undefined	是	權杖使用資訊
state	TurnState	是	回合如何結束
error	ErrorInfo	否	當狀態為 'error' 時的錯誤細節

ActiveTurn

進行中的回合 — 助理正在主動串流。

欄位	類型	說明
id	string	回合識別碼
startedAt	string	此回合開始時的 ISO 8601 時間戳記。
message	Message	啟動此回合的訊息
responseParts	ResponsePart[]	所有回應內容依串流順序排列：文字、工具呼叫、推理與內容參照。 當權限等待使用者核准時，工具呼叫部分會包含 pendingPermissions。
usage	UsageInfo | undefined	權杖使用資訊

MessageKind

{@link MessageOrigin} 的判別欄位 — 識別訊息的產生者。

成員	值	說明
User	'user'	由使用者直接傳送。
Agent	'agent'	由代理程式本身而非使用者產生 — 例如，代理程式為其產生的聊天 植入第一則訊息。
Tool	'tool'	由工具而非使用者產生 — 例如，工具產生一個工作者聊天，其第一則 訊息帶有種子提示。
SystemNotification	'systemNotification'	系統產生的通知，而非直接的使用者訊息。

MessageOrigin

識別 {@link Message} 的起源 — 由誰產生。對於啟動回合的訊息 （{@link Turn.message}），這也是回合的起源；對於引導或佇列訊息， 則僅為該訊息的起源。

欄位	類型	說明
kind	MessageKind	產生此訊息的行為者種類。

Message

啟動或引導回合的訊息。訊息可來自使用者、代理程式、工具，或由系統 產生（參見 {@link MessageOrigin}）。

附件 MAY 透過其 {@link MessageAttachmentBase.range} 欄位在 {@link Message.text} 中被參照。沒有範圍的附件仍與訊息關聯，但不 對應文字中的特定跨度。

欄位	類型	必要	說明
text	string	是	訊息文字
origin	MessageOrigin	是	訊息的起源
attachments	MessageAttachment[]	否	檔案／選取範圍附件
model	ModelSelection	否	此訊息已（或將）用來傳送的模型。 對於歷史使用者／代理程式訊息，此記錄實際使用的模型，讓編輯或重送 訊息的用戶端可保留該選擇。對於 {@link ChatState.draft | draft}， 它承載使用者為其正在撰寫的訊息所挑選的模型。缺省表示套用代理主機 的預設模型。
agent	AgentSelection	否	此訊息已（或將）用來傳送的自訂代理程式。 對於歷史訊息，此記錄實際使用的代理程式；對於 {@link ChatState.draft | draft}，它承載使用者挑選的代理程式。缺省 表示無自訂代理程式 — 套用提供者的預設行為。
_meta	Record<string, unknown>	否	此訊息的額外提供者特定中介資料。 用戶端 MAY 在此尋找已知的索引鍵以提供增強 UI，代理主機 MAY 用它 承載不符合任何其他欄位的情境。鏡像 MCP 的 _meta 慣例。

MessageAttachmentBase

所有 {@link MessageAttachment} 變體共用的欄位。

欄位	類型	必要	說明
label	string	是	附件的人類可讀標籤（例如檔案附件的檔名）。用於 UI 中的顯示。
range	TextRange	否	若已定義，為 {@link Message.text} 中參照此附件的範圍。這是文字 範圍，不是位元組範圍。
displayKind	string	否	轉譯此附件的用戶端的建議顯示提示。可辨識的值包含： - 'image'：附件為影像 - 'document'：附件為文字文件 - 'symbol'：附件為程式碼符號（例如函式或類別） - 'directory'：附件為資料夾 - 'selection'：附件為文件內的選取範圍 實作 MAY 提供額外的值；用戶端 SHOULD 在遇到未知值時退回合理的 預設值。
_meta	Record<string, unknown>	否	附件的額外實作定義中介資料。 若附件由 completions 指令產生，用戶端在傳送包含已接受補全的 使用者訊息時，MUST 保留代理主機原先傳回的 _meta 的每個屬性。

SimpleMessageAttachment

簡單、不透明的附件，其模型表示由產生者描述。

欄位	類型	必要	說明
type	MessageAttachmentKind.Simple	是	判別欄位
modelRepresentation	string	否	附件應顯示給模型的表示。 若附件由用戶端產生，此屬性 MUST 已定義，讓代理主機可正確解讀附件。 當附件源自 completions 回應時，MAY 省略此屬性。

MessageEmbeddedResourceAttachment

資料以 base64 字串內嵌的附件。

將此用於應隨使用者訊息本身傳遞而非另行擷取的小型二進位有效負載 （例如貼上的影像）。

欄位	類型	必要	說明
type	MessageAttachmentKind.EmbeddedResource	是	判別欄位
data	string	是	Base64 編碼的二進位資料
contentType	string	是	內容 MIME 類型（例如 "image/png"、"application/pdf"）
selection	TextSelection	否	附加文字資源內的選用選取範圍。 僅對文字資源有意義。

MessageResourceAttachment

依 URI 參照資源的附件。內容不會內嵌傳遞；消費者可在需要時透過 resourceRead 擷取它。

欄位	類型	必要	說明
type	MessageAttachmentKind.Resource	是	判別欄位
selection	TextSelection	否	被參照文字資源內的選用選取範圍。 僅對文字資源有意義。

MessageAnnotationsAttachment

參照工作階段之註解通道上之註解的附件（參見 {@link AnnotationsState}）。

當 {@link annotationIds} 缺省時，附件參照通道上的每個註解；當存在時， 僅參照列出的 {@link Annotation.id | 註解識別碼}。

欄位	類型	必要	說明
type	MessageAttachmentKind.Annotations	是	判別欄位
resource	URI	是	註解通道的 URI（通常為 ahp-session:/<uuid>/annotations）。 符合 {@link AnnotationsSummary.resource}。
annotationIds	string[]	否	要參照的特定 {@link Annotation.id | 註解識別碼}。當缺省時，附件 參照通道上的所有註解。

MessageChatAttachment

透過固定已完成回合參照聊天轉錄的附件。

被參照的聊天 MUST 與訊息的聊天屬於同一工作階段。主機在接受訊息時， 從其第一個保留回合到 endTurn（含）解析轉錄。之後的回合不會變更 已傳送附件所代表的情境。

主機 MUST NOT 遞迴展開在參照轉錄內找到的聊天附件。用戶端 SHOULD 在 被參照聊天之後被修剪時持續轉譯 label，並將開啟 resource 視為 盡力而為。

欄位	類型	說明
type	MessageAttachmentKind.Chat	判別欄位
resource	URI	被參照聊天的 URI。
endTurn	string	被參照轉錄中包含的最後一個已完成回合。

MessageAttachment

與 {@link Message} 關聯的附件。

SimpleMessageAttachment | MessageEmbeddedResourceAttachment | MessageResourceAttachment | MessageAnnotationsAttachment | MessageChatAttachment

ResponsePartKind

回應部分類型的判別欄位。

成員	值
Markdown	'markdown'
ContentRef	'contentRef'
ToolCall	'toolCall'
Reasoning	'reasoning'
SystemNotification	'systemNotification'
InputRequest	'inputRequest'

MarkdownResponsePart

欄位	類型	說明
kind	ResponsePartKind.Markdown	判別欄位
id	string	部分識別碼，由 chat/delta 用來指定此部分進行內容附加
content	string	Markdown 內容

ResourceReponsePart

作為對儲存於狀態樹外之大型內容參照的內容部分。

欄位	類型	說明
kind	ResponsePartKind.ContentRef	判別欄位

ToolCallResponsePart

表示為回應部分的工具呼叫。

工具呼叫為回應串流的一部分，與文字與推理交錯。toolCall.toolCallId 作為指定此部分之操作的識別碼。

欄位	類型	說明
kind	ResponsePartKind.ToolCall	判別欄位
toolCall	ToolCallState	完整工具呼叫生命週期狀態

ReasoningResponsePart

來自模型的推理／思考內容。

欄位	類型	說明
kind	ResponsePartKind.Reasoning	判別欄位
id	string	部分識別碼，由 chat/reasoning 用來指定此部分進行內容附加
content	string	累積的推理文字

ResponsePart

MarkdownResponsePart | ResourceReponsePart | ToolCallResponsePart | ReasoningResponsePart | SystemNotificationResponsePart | InputRequestResponsePart

InputRequestResponsePart

回合回應串流中的作用中或已解決輸入請求（引出）。

伺服器以 chat/inputRequested 插入此部分。當 {@link response} 缺省時， 用戶端可以 chat/inputAnswerChanged 更新答案草稿，並以 chat/inputCompleted 提交回應。完成時會就地更新此部分，使其串流 位置穩定，且完整互動保持持久並可透過 fetchTurns 回填。

若回合在未提交回應的情況下結束，未解決的部分會留在已完成的回合 轉錄中，且 {@link response} 缺省。

欄位	類型	必要	說明
kind	ResponsePartKind.InputRequest	是	判別欄位
request	ChatInputRequest	是	請求，承載其 id、message、url、questions 與目前的草稿或 已提交 answers。
response	ChatInputResponseKind	否	請求如何被解決。在用戶端以 chat/inputCompleted 提交 accept、 decline 或 cancel 之前為缺省。

SystemNotificationResponsePart

作為回應串流一部分呈現的系統通知。

系統通知是由代理程式框架撰寫的訊息，需要對代理程式（供情境感知） 與使用者（供轉錄連續性）皆可見。例如「背景子代理程式 X 已完成」 或「任務 Y 已取消」。

欄位	類型	必要	說明
kind	ResponsePartKind.SystemNotification	是	判別欄位
content	StringOrMarkdown	是	系統通知的文字
_meta	Record<string, unknown>	否	此通知的額外提供者特定中介資料。 主機 MAY 附加觸發通知之項目的機器可讀描述子，讓用戶端可在不解析 content 的情況下對其分類、加圖示、分組、篩選或在地化。用戶端 MAY 在此尋找已知的索引鍵以提供增強 UI，且當 _meta 缺省或無法 辨識時，MUST 單獨從 content 一致地轉譯。

ToolCallStatus

工具呼叫在生命週期狀態機中的狀態。

成員	值	說明
Streaming	'streaming'
PendingConfirmation	'pending-confirmation'
Running	'running'
AuthRequired	'auth-required'	執行暫停，因為支援此呼叫的 MCP 伺服器需要驗證（通常是範圍不足的 步進式驗證，於執行中浮現）。參見 {@link ToolCallAuthRequiredState}。
PendingResultConfirmation	'pending-result-confirmation'
Completed	'completed'
Cancelled	'cancelled'

ToolCallConfirmationReason

工具呼叫如何被確認執行。

• NotNeeded — 無需確認（自動核准）
• UserAction — 使用者明確核准
• Setting — 由持續性使用者設定核准

成員	值
NotNeeded	'not-needed'
UserAction	'user-action'
Setting	'setting'

ToolCallRiskAssessmentKind

將模型評審器識別為確認需求的來源。

成員	值
Judge	'judge'

ToolCallRiskAssessmentStatus

非同步模型評審器確認決定的生命週期狀態。

成員	值
Loading	'loading'
Complete	'complete'

ToolCallRiskAssessmentLoadingState

模型評審器仍在評估工具呼叫。

欄位	類型	說明
status	ToolCallRiskAssessmentStatus.Loading

ToolCallRiskAssessmentCompleteState

模型評審器已完成其評估。

欄位	類型	說明
status	ToolCallRiskAssessmentStatus.Complete
reason	StringOrMarkdown
safety	number	評審器的正規化安全分數，其中 0 為不安全，1 為安全。

ToolCallRiskAssessment

ToolCallRiskAssessmentLoadingState | ToolCallRiskAssessmentCompleteState

ToolCallCancellationReason

工具呼叫為何被取消。

成員	值
Denied	'denied'
Skipped	'skipped'
ResultDenied	'result-denied'

ConfirmationOptionKind

確認選項是否代表核准或拒絕動作。

成員	值
Approve	'approve'
Deny	'deny'

ConfirmationOption

伺服器為等待核准的工具呼叫所提供的確認選項。允許超出簡單 核准／拒絕的更豐富選擇 — 例如「在此工作階段中核准」或 「附帶原因拒絕」。

欄位	類型	必要	說明
id	string	是	選項的唯一識別碼，於確認操作中傳回
label	string	是	顯示給使用者的人類可讀標籤
kind	ConfirmationOptionKind	是	此選項是否代表核准或拒絕
group	number	否	用於視覺分類的邏輯群組編號。 用戶端 SHOULD 依選項定義的順序顯示選項，且 MAY 使用不同的群組 編號在選項的邏輯叢集之間插入分隔線。

ToolCallContributorKind

成員	值
Client	'client'
MCP	'mcp'

ToolCallClientContributor

欄位	類型	說明
kind	ToolCallContributorKind.Client
clientId	string	若此工具由用戶端提供，為所屬用戶端的 clientId。伺服器端工具 為缺省。 設定時，所識別的用戶端負責執行工具並以結果分派 chat/toolCallComplete。

ToolCallMcpContributor

欄位	類型	說明
kind	ToolCallContributorKind.MCP
customizationId	string	在 {@link SessionState.customizations} 中對應 MCP 伺服器的自訂 ID。

ToolCallContributor

ToolCallClientContributor | ToolCallMcpContributor

ToolCallResult

工具執行結果細節，於執行完成後可用。

欄位	類型	必要	說明
success	boolean	是	工具是否成功
pastTenseMessage	StringOrMarkdown	是	工具已執行之事的過去式描述
content	ToolResultContent[]	否	非結構化結果內容區塊。 這鏡像 MCP CallToolResult 的 content 欄位。
structuredContent	Record<string, unknown>	否	選用的結構化結果物件。 這鏡像 MCP CallToolResult 的 structuredContent 欄位。
error	{ message: string; code?: string }	否	當工具失敗時的錯誤細節

ToolCallStreamingState

LM 正在串流工具呼叫參數。

欄位	類型	必要	說明
status	ToolCallStatus.Streaming	是
partialInput	string	否	目前為止累積的部分參數
invocationMessage	StringOrMarkdown	否	參數串流時顯示的進度訊息

ToolCallPendingConfirmationState

參數已完整，或執行中的工具需要重新確認（例如執行中的權限檢查）。

欄位	類型	必要	說明
status	ToolCallStatus.PendingConfirmation	是
confirmationTitle	StringOrMarkdown	否	確認提示的簡短標題（例如 "Run in terminal"、"Write file"）
riskAssessment	ToolCallRiskAssessment	否	促成此確認需求的風險評估。
edits	{ items: FileEdit[] }	否	此工具呼叫將執行的檔案編輯，供確認前預覽
editable	boolean	否	代理主機是否允許用戶端在確認前編輯工具的輸入參數
options	ConfirmationOption[]	否	伺服器為此確認提供的選項。當存在時，用戶端 SHOULD 改為轉譯這些 選項，而非單純的核准／拒絕 UI。每個選項屬於一個 {@link ConfirmationOptionGroup}，讓用戶端仍可分類這些選擇。

ToolCallRunningState

工具正在主動執行。

欄位	類型	必要	說明
status	ToolCallStatus.Running	是
content	ToolResultContent[]	否	工具仍在執行時產生的部分內容。 例如，終端機內容區塊讓用戶端可在工具完成前訂閱即時輸出。

ToolCallAuthRequiredState

執行中的工具呼叫暫停，因為支援它的 MCP 伺服器需要驗證 — 最常見為 由 tools/call 請求本身觸發的 {@link McpAuthRequirement.reason | insufficientScope} 步進式驗證。只能從 {@link ToolCallRunningState} 到達，且通常在驗證後返回該處：running → auth-required → running → …。用戶端也可改為不分派驗證，透過分派帶有 失敗 結果的 chat/toolCallComplete 來取消呼叫，且一律直接移至 {@link ToolCallCompletedState} — 此路徑上 requiresResultConfirmation 會被忽略，因此永遠不會進入 {@link ToolCallPendingResultConfirmationState}。 從此狀態分派的 成功 結果為無效，且 MUST 被化簡器作為 no-op 拒絕／忽略，因為挑戰後執行從未恢復。

這是 {@link McpServerAuthRequiredState} 的工具呼叫層級對應 — 該狀態 表示 MCP 伺服器 無法服務任何請求；此狀態表示 此特定呼叫 正在 等待相同種類的挑戰。兩者獨立分派，且 MAY 同時為真或不同時：例如， 由單一工具呼叫觸發的 insufficientScope 挑戰不必封鎖整個伺服器。

由於挑戰一律透過現有的 authenticate 指令推送權杖來解決，此狀態 只能源自 {@link ToolCallContributorKind.MCP | 由 MCP 伺服器貢獻} 的 工具呼叫 — contributor 因此被窄化（與其他工具呼叫狀態上選用、 多種類的 contributor 不同）。

欄位	類型	必要	說明
status	ToolCallStatus.AuthRequired	是
contributor	ToolCallMcpContributor	是	貢獻此工具呼叫的 MCP 伺服器 — 一律為 MCP，絕非用戶端工具。
auth	McpAuthRequirement	是	封鎖此呼叫的驗證挑戰。
content	ToolResultContent[]	否	呼叫為驗證暫停前產生的部分內容。

ToolCallPendingResultConfirmationState

工具已完成執行，等待用戶端核准結果。

欄位	類型	說明
status	ToolCallStatus.PendingResultConfirmation

ToolCallCompletedState

工具已成功完成或發生錯誤。

欄位	類型	說明
status	ToolCallStatus.Completed

ToolCallCancelledState

工具呼叫在執行前被取消。

欄位	類型	必要	說明
status	ToolCallStatus.Cancelled	是
reason	ToolCallCancellationReason	是	工具為何被取消
reasonMessage	StringOrMarkdown	否	解釋取消的選用訊息
userSuggestion	Message	否	使用者建議改為執行的動作
selectedOption	ConfirmationOption	否	使用者所選的確認選項（若有提供確認選項）

ToolCallState

所有工具呼叫生命週期狀態的判別聯集。

完整狀態機圖請參見 狀態模型指南。

ToolCallStreamingState | ToolCallPendingConfirmationState | ToolCallRunningState | ToolCallAuthRequiredState | ToolCallPendingResultConfirmationState | ToolCallCompletedState | ToolCallCancelledState

ToolCallConfirmationState

會因用戶端確認而封鎖的兩個工具呼叫狀態：執行前的參數確認 （{@link ToolCallPendingConfirmationState}）與執行後的結果確認 （{@link ToolCallPendingResultConfirmationState}）。

{@link ToolCallAuthRequiredState} 刻意 不 屬於此聯集：它不因 chat/toolCallConfirmed 式的用戶端決定而封鎖，而是因用戶端完成 OAuth 流程並呼叫 authenticate 而封鎖。其工作階段層級呈現請參見 {@link SessionToolAuthenticationRequest}。

在工作階段層級由 {@link SessionToolConfirmationRequest} 呈現。

ToolCallPendingConfirmationState | ToolCallPendingResultConfirmationState

ToolResultContentType

工具結果內容類型的判別欄位。

成員	值
Text	'text'
EmbeddedResource	'embeddedResource'
Resource	'resource'
FileEdit	'fileEdit'
Terminal	'terminal'
Subagent	'subagent'

ToolResultTextContent

工具結果中的文字內容。

鏡像 MCP TextContent。

欄位	類型	說明
type	ToolResultContentType.Text
text	string	文字內容

ToolResultEmbeddedResourceContent

內嵌於工具結果的 Base64 編碼二進位內容。

鏡像 MCP EmbeddedResource（用於內嵌二進位資料）。

欄位	類型	說明
type	ToolResultContentType.EmbeddedResource
data	string	Base64 編碼的資料
contentType	string	內容類型（例如 "image/png"、"application/pdf"）

ToolResultResourceContent

對儲存於工具結果外之資源的參照。

包裝 {@link ContentRef} 以延遲載入大型結果。

欄位	類型	說明
type	ToolResultContentType.Resource

ToolResultFileEditContent

描述工具執行的檔案修改。

欄位	類型	說明
type	ToolResultContentType.FileEdit

ToolResultTerminalContent

對輸出與此工具結果相關之終端機的參照。

用戶端可訂閱終端機的 URI 以即時串流其輸出，在工具執行時提供即時 回饋。

當指令結束時，{@link result} 會填入完成的結果中，為未訂閱的用戶端 保留結果。這記錄的是指令的結束，而非終端機的結束 — 終端機之後 可能會繼續執行。

欄位	類型	必要	說明
type	ToolResultContentType.Terminal	是
resource	URI	是	終端機 URI（可訂閱以取得完整終端機狀態）
title	string	是	終端機內容的顯示標題
isPty	boolean	否	此終端機式資源是否由偽終端機支援。當 false 時，輸出為純文字， 且用戶端不需解析 VT 序列。
result	TerminalCommandResult	否	指令的結果，於其結束後存在。

TerminalCommandResult

在終端機式工具中執行之指令的結果，於指令結束時填入 {@link ToolResultTerminalContent.result}。

欄位	類型	必要	說明
exitCode	number	否	已完成指令的結束代碼（若執行階段有回報）
preview	string	否	指令輸出的預覽，供未訂閱終端機或在其處置後才抵達的用戶端使用。 當 isPty 為 true 時，預覽可能包含 VT 序列；當 false 時為 純文字。
truncated	boolean	否	preview 是否已知為不完整或已截斷

ToolResultSubagentContent

內嵌於工具結果中的參照，指向由工具呼叫產生的工作者聊天（子代理程式 委派），由聊天 URI（ahp-chat:/...）參照。

這是產生工具呼叫對工作者的正向檢視。工作者聊天透過其 {@link ChatOrigin}（kind: 'tool'）反向記錄相同的邊，其 toolCallId 識別發出此內容的工具呼叫。

欄位	類型	必要	說明
type	ToolResultContentType.Subagent	是
resource	URI	是	工作者聊天 URI（可訂閱以取得完整聊天狀態）
title	string	是	子代理程式的顯示標題
agentName	string	否	內部代理程式名稱
description	string	否	子代理程式任務的人類可讀描述

ToolResultContent

工具結果中的內容區塊。

鏡像 MCP CallToolResult.content 中的內容區塊，加上用於延遲載入大型 結果的 ToolResultResourceContent、用於檔案編輯差異的 ToolResultFileEditContent、用於即時終端機輸出與指令完成中介資料的 ToolResultTerminalContent，以及用於工具產生工作者聊天的 ToolResultSubagentContent（AHP 擴充）。

ToolResultTextContent | ToolResultEmbeddedResourceContent | ToolResultResourceContent | ToolResultFileEditContent | ToolResultTerminalContent | ToolResultSubagentContent

操作

變動 ChatState。透過外層的 ActionEnvelope.channel 限定於某個聊天 URI。

JSON Schema: actions.schema.json

chat/turnStarted

新訊息已傳送給代理程式，且新回合開始。

用戶端僅被允許傳送 {@link MessageKind.User} 訊息。

欄位	類型	必要	說明
type	ActionType.ChatTurnStarted	是
turnId	string	是	回合識別碼
startedAt	string	是	此回合開始時的 ISO 8601 時間戳記。
message	Message	是	新訊息
queuedMessageId	string	否	若此回合是從佇列訊息自動啟動，該訊息的 ID
_meta	Record<string, unknown>	否	此操作的額外提供者特定中繼資料。 用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP _meta 慣例。

chat/delta

來自助理的串流文字區塊，附加到特定回應部分。

伺服器 MUST 先發出 chat/responsePart 以建立目標部分（markdown 或推理），再使用此操作將文字附加到它。

欄位	類型	必要	說明
type	ActionType.ChatDelta	是
turnId	string	是	回合識別碼
partId	string	是	要附加到的回應部分識別碼
content	string	是	文字區塊
_meta	Record<string, unknown>	否	此操作的額外提供者特定中繼資料。 用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP _meta 慣例。

chat/responsePart

附加到回應的結構化內容。

欄位	類型	必要	說明
type	ActionType.ChatResponsePart	是
turnId	string	是	回合識別碼
part	ResponsePart	是	回應部分（markdown 或內容參照）
_meta	Record<string, unknown>	否	此操作的額外提供者特定中繼資料。 用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP _meta 慣例。

chat/toolCallStart

工具呼叫開始 — 參數正從 LM 串流傳入。

伺服器設定 {@link ToolCallContributor | contributor} 以識別工具的起源。對於用戶端提供的工具，具名用戶端負責在工具到達 running 狀態時執行它，並分派 chat/toolCallComplete。對於 MCP 伺服器提供的工具，伺服器會針對具名的 McpServerCustomization 執行呼叫。

欄位	類型	必要	說明
type	ActionType.ChatToolCallStart	是
toolName	string	是	內部工具名稱（用於除錯/日誌）
displayName	string	是	人類可讀的工具名稱
intention	string	否	工具呼叫意圖執行之動作的人類可讀描述
contributor	ToolCallContributor	否	所呼叫工具之貢獻者的參照。對於非由用戶端或 MCP 伺服器貢獻的伺服器端工具則不存在。

chat/toolCallDelta

工具呼叫的串流部分參數。

欄位	類型	必要	說明
type	ActionType.ChatToolCallDelta	是
content	string	是	要附加的部分參數內容
invocationMessage	StringOrMarkdown	否	更新的進度訊息

chat/toolCallReady

工具呼叫參數已完成，或執行中的工具需要重新確認。

當針對 streaming 工具呼叫分派時，會轉換到 pending-confirmation，或若設定了 confirmed 則直接轉換到 running。

當針對 running 工具呼叫分派時（例如執行中途需要權限），會轉換回 pending-confirmation。invocationMessage 與 _meta SHOULD 被更新以描述所需的特定確認。用戶端使用標準 chat/toolCallConfirmed 流程來核准或拒絕。

對於用戶端提供的工具，伺服器通常會將 confirmed 設為 'not-needed'，讓工具直接轉換到 running，讓擁有用戶端能立即開始執行。

欄位	類型	必要	說明
type	ActionType.ChatToolCallReady	是
invocationMessage	StringOrMarkdown	是	描述工具將執行之動作或所需確認的訊息
toolInput	string	否	原始工具輸入
confirmationTitle	StringOrMarkdown	否	確認提示的簡短標題（例如 "Run in terminal"、"Write file"）
riskAssessment	ToolCallRiskAssessment	否	促成確認需求的風險評估。
edits	{ items: FileEdit[] }	否	此工具呼叫將執行的檔案編輯，用於確認前的預覽
editable	boolean	否	代理主機是否允許用戶端在確認前編輯工具的輸入參數
confirmed	ToolCallConfirmationReason	否	若設定，工具已自動確認並直接轉換到 running
options	ConfirmationOption[]	否	伺服器為此確認提供的選項。若存在，用戶端 SHOULD 改為渲染這些選項，而非單純的核准/拒絕 UI。每個選項屬於一個 {@link ConfirmationOptionGroup}，讓用戶端仍能將選擇分類。

chat/toolCallConfirmed（已核准）

用戶端核准待處理的工具呼叫。工具轉換到 running。

欄位	類型	必要	說明
type	ActionType.ChatToolCallConfirmed	是
approved	true	是	工具呼叫已核准
confirmed	ToolCallConfirmationReason	是	工具確認的方式
editedToolInput	string	否	已編輯的工具輸入參數，若用戶端在確認前修改了它們
selectedOptionId	string	否	所選確認選項的 ID，若伺服器提供了選項

chat/toolCallConfirmed（已拒絕）

用戶端拒絕待處理的工具呼叫。工具轉換到 cancelled。

對於用戶端提供的工具，若擁有用戶端無法識別該工具或無法執行它，MUST 分派此操作。

欄位	類型	必要	說明
type	ActionType.ChatToolCallConfirmed	是
approved	false	是	工具呼叫已被拒絕
reason	ToolCallCancellationReason.Denied | ToolCallCancellationReason.Skipped	是	工具取消的原因
userSuggestion	Message	否	使用者建議改為執行的動作
reasonMessage	StringOrMarkdown	否	拒絕的選用說明
selectedOptionId	string	否	所選確認選項的 ID，若伺服器提供了選項

ChatToolCallConfirmedAction

用戶端確認或拒絕待處理的工具呼叫。

ChatToolCallApprovedAction | ChatToolCallDeniedAction

chat/toolCallComplete

工具執行完成。若 requiresResultConfirmation 為 true，轉換到 completed 或 pending-result-confirmation。

對於用戶端提供的工具（其工具呼叫狀態帶有含 clientId 的用戶端 ToolCallContributor），擁有用戶端會帶著執行結果分派此操作。若分派的用戶端與貢獻者的 clientId 不符，伺服器 SHOULD 拒絕此操作。

等待用戶端工具呼叫的伺服器 MAY 在實作用戶端中斷連線或變得無回應後，於合理持續時間後逾時，並帶著 result.success = false 與適當錯誤分派此操作。

用戶端 MAY 也針對目前處於 auth-required 狀態的工具呼叫，以 失敗 的結果（result.success: false）分派此操作，以在不完成待處理 MCP 驗證挑戰的情況下取消該呼叫。這永遠會將工具呼叫直接轉換到 completed，保留它在暫停以進行驗證前的欄位； requiresResultConfirmation 在此轉換會被忽略；取消永遠無法進入 pending-result-confirmation，因為沒有可檢閱的實際結果。

成功 的結果（result.success: true）對處於 auth-required 狀態的工具呼叫是無效的 — 執行在挑戰後從未恢復，因此沒有任何事物能產生它。reducer MUST 將其作為 no-op 拒絕/忽略，讓工具呼叫留在 auth-required。用戶端必須在成功完成前先解決驗證挑戰（chat/toolCallAuthResolved）。

欄位	類型	必要	說明
type	ActionType.ChatToolCallComplete	是
result	ToolCallResult	是	執行結果
requiresResultConfirmation	boolean	否	若為 true，結果在完成前需要用戶端核准

chat/toolCallResultConfirmed

用戶端核准或拒絕工具的結果。

若 approved 為 false，工具會以原因 result-denied 轉換到 cancelled。

欄位	類型	說明
type	ActionType.ChatToolCallResultConfirmed
approved	boolean	結果是否已核准

chat/toolCallContentChanged

工具仍在執行時產生的部分內容。

取代執行中工具呼叫狀態上的 content 陣列。用戶端可使用它在工具完成前顯示即時回饋（例如終端機參照）。

對於用戶端提供的工具（其工具呼叫狀態帶有含 clientId 的用戶端 ToolCallContributor），擁有用戶端會在執行時分派此操作以串流傳入中繼內容。若分派的用戶端與貢獻者的 clientId 不符，伺服器 SHOULD 拒絕此操作。

欄位	類型	說明
type	ActionType.ChatToolCallContentChanged
content	ToolResultContent[]	執行中工具呼叫的目前部分內容

chat/toolCallAuthRequired

執行中的工具呼叫已暫停，等待 MCP 驗證。將工具呼叫從 running 轉換到 auth-required。

伺服器在支援呼叫的 MCP 伺服器於執行中途以 401/403 挑戰回應時分派此操作（見 {@link McpAuthRequirement.reason | insufficientScope}）。主機 SHOULD 將此與 session/inputNeededSet（kind toolAuthentication）配對，讓區塊在工作階段摘要層級可見，鏡像 {@link McpServerAuthRequiredState} 自身的 InputNeeded 指引。

僅對由 MCP 伺服器貢獻的工具呼叫有效 — 若工具呼叫的 contributor 不是 {@link ToolCallContributorKind.MCP | MCP-kind}，reducer 為 no-op。

欄位	類型	說明
type	ActionType.ChatToolCallAuthRequired
auth	McpAuthRequirement	阻擋此呼叫的驗證挑戰。

chat/toolCallAuthResolved

阻擋工具呼叫的驗證挑戰已解決（用戶端透過 authenticate 推送權杖且主機已驗證它）。將工具呼叫從 auth-required 轉換回 running，保留它在暫停前的欄位。

主機 SHOULD 在此分派後移除對應的 session/inputNeededSet 項目（kind toolAuthentication）。

欄位	類型	說明
type	ActionType.ChatToolCallAuthResolved

chat/turnComplete

回合完成 — 助理已閒置。

欄位	類型	必要	說明
type	ActionType.ChatTurnComplete	是
turnId	string	是	回合識別碼
duration	number	是	以毫秒為單位的回合經過持續時間，由產生者自身的時鐘測量。用戶端 MUST NOT 透過相減時間戳記來推導此值 — 跨用戶端時鐘可能不同 — 且 MUST 將它視為不透明的、產生者提供的資料。
_meta	Record<string, unknown>	否	此操作的額外提供者特定中繼資料。 用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP _meta 慣例。

chat/turnCancelled

回合已中止；伺服器停止處理。

欄位	類型	必要	說明
type	ActionType.ChatTurnCancelled	是
turnId	string	是	回合識別碼
duration	number	是	以毫秒為單位的回合經過持續時間，由產生者自身的時鐘測量。用戶端 MUST NOT 透過相減時間戳記來推導此值 — 跨用戶端時鐘可能不同 — 且 MUST 將它視為不透明的、產生者提供的資料。
_meta	Record<string, unknown>	否	此操作的額外提供者特定中繼資料。 用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP _meta 慣例。

chat/error

回合處理期間發生錯誤。

欄位	類型	必要	說明
type	ActionType.ChatError	是
turnId	string	是	回合識別碼
duration	number	是	以毫秒為單位的回合經過持續時間，由產生者自身的時鐘測量。用戶端 MUST NOT 透過相減時間戳記來推導此值 — 跨用戶端時鐘可能不同 — 且 MUST 將它視為不透明的、產生者提供的資料。
error	ErrorInfo	是	錯誤詳細資料
_meta	Record<string, unknown>	否	此操作的額外提供者特定中繼資料。 用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP _meta 慣例。

chat/activityChanged

此聊天的活動描述已變更。

由伺服器分派以指出聊天目前正在做什麼（例如執行工具、思考）。透過省略它或將它設為 undefined 來清除活動。產生者 SHOULD 也以 session/chatUpdated 更新父工作階段的聊天目錄，讓 ChatSummary.activity 保持同步。

欄位	類型	必要	說明
type	ActionType.ChatActivityChanged	是
activity	string	否	目前活動的人類可讀描述；省略或設為 undefined 以清除

chat/workingDirectorySet

工作目錄已新增到此聊天的 {@link ChatState.workingDirectories} 子集。

以目錄 URI 為鍵的成員資格語意：當聊天的子集尚未包含 directory 時，reducer 會附加它（若不存在則建立子集），且當它已存在時為 no-op。directory MUST 是所屬工作階段 {@link SessionState.workingDirectories} 之一；主機 MUST 拒絕非如此的目錄。僅在代理程式公告 {@link AgentCapabilities.multipleWorkingDirectories} 時有效。

欄位	類型	說明
type	ActionType.ChatWorkingDirectorySet
directory	URI	要新增到此聊天子集的工作目錄。

chat/workingDirectoryRemoved

工作目錄已從此聊天的 {@link ChatState.workingDirectories} 子集中移除。

從聊天的子集中移除 directory；當它不存在時為 no-op。具冪等性，鏡像 session/workingDirectoryRemoved。僅影響聊天的子集 — 目錄仍保留在工作階段的集合中。

欄位	類型	說明
type	ActionType.ChatWorkingDirectoryRemoved
directory	URI	要從此聊天子集中移除的工作目錄。

chat/usage

回合的權杖使用量報告。

欄位	類型	必要	說明
type	ActionType.ChatUsage	是
turnId	string	是	回合識別碼
usage	UsageInfo	是	權杖使用量資料
_meta	Record<string, unknown>	否	此操作的額外提供者特定中繼資料。 用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP _meta 慣例。

chat/reasoning

來自模型的推理/思考文字，附加到特定推理回應部分。

伺服器 MUST 先發出 chat/responsePart 以建立目標推理部分，再使用此操作將文字附加到它。

欄位	類型	必要	說明
type	ActionType.ChatReasoning	是
turnId	string	是	回合識別碼
partId	string	是	要附加到的推理回應部分識別碼
content	string	是	推理文字區塊
_meta	Record<string, unknown>	否	此操作的額外提供者特定中繼資料。 用戶端 MAY 在此尋找已知鍵以提供增強的 UI，且代理主機 MAY 用它來承載不適合任何其他欄位的個別事件上下文 — 例如，將事件歸因於特定代理程式（例如在回合內運作的子代理程式）。沿用 MCP _meta 慣例。

chat/truncated

截斷工作階段的歷史。若提供 turnId，該回合之後的所有回合都會被移除，且保留指定的回合。若省略 turnId，所有回合都會被移除。

若有活動回合，它會被靜默捨棄，且聊天狀態回到 idle。

常見使用案例：截斷舊資料，然後以編輯過的訊息分派新的 chat/turnStarted。

欄位	類型	必要	說明
type	ActionType.ChatTruncated	是
turnId	string	否	保留到並包含此回合為止的回合。省略以清除所有回合。

chat/turnsLoaded

將較舊的已完成回合載入此聊天的狀態。

主機在回應 fetchTurns 之前，以及在套用任何參照比目前載入視窗更舊之回合的操作之前，分派此操作。turns 依最舊優先排序，並前置到目前的 turns 視窗。turnsNextCursor 取代狀態的游標；當所有保留回合現在都已載入時，省略它。

欄位	類型	必要	說明
type	ActionType.ChatTurnsLoaded	是
turns	Turn[]	是	載入狀態的較舊已完成回合，依最舊優先排序。
turnsNextCursor	string	否	用於載入下一個較舊頁面的不透明游標，若還有剩餘。

chat/pendingMessageSet

待處理訊息已設定（upsert 語意：建立或取代）。

對於引導訊息，這永遠會取代單一引導訊息。對於佇列訊息，若具有給定 id 的訊息已存在，它會就地更新；否則會附加到佇列。若設定佇列訊息時聊天處於閒置狀態，伺服器 SHOULD 立即取用它並開始新回合。

用戶端僅被允許傳送 {@link MessageKind.User} 訊息。

欄位	類型	說明
type	ActionType.ChatPendingMessageSet
kind	PendingMessageKind	這是引導訊息還是佇列訊息
id	string	此待處理訊息的唯一識別碼
message	Message	訊息內容

chat/pendingMessageRemoved

待處理訊息已移除（引導或佇列）。

由用戶端分派以取消待處理訊息，或由伺服器在它取用訊息時分派（例如從佇列訊息開始回合，或將引導訊息注入目前回合）。

欄位	類型	說明
type	ActionType.ChatPendingMessageRemoved
kind	PendingMessageKind	這是引導訊息還是佇列訊息
id	string	要移除的待處理訊息識別碼

chat/queuedMessagesReordered

重新排序佇列訊息。

order 陣列包含佇列訊息的 ID，依其新的所需順序排列。不存在於目前佇列中的 ID 會被忽略。ID 不在 order 中的佇列訊息會以原始相對順序附加到結尾（讓具有過時佇列檢視的用戶端永遠不會靜默捨棄訊息）。

欄位	類型	說明
type	ActionType.ChatQueuedMessagesReordered
order	string[]	依所需順序排列的佇列訊息 ID

chat/draftChanged

聊天的草稿輸入已變更。

用戶端 MAY 定期將其本地輸入狀態 — 使用者正在撰寫的訊息，包括其 {@link Message.model | 模型} / {@link Message.agent | 代理程式} 選擇與附件 — 同步到聊天的 {@link ChatState.draft | draft}，讓它在重新載入後仍留存，且對檢視相同聊天的其他用戶端可見。積極同步 not 必要； 用戶端 SHOULD 去抖動，且 MAY 僅在方便的時刻同步。將 draft 設為 undefined 以清除它（例如訊息傳送後）。

用戶端僅被允許草擬 {@link MessageKind.User} 訊息。

欄位	類型	必要	說明
type	ActionType.ChatDraftChanged	是
draft	Message	否	新的草稿訊息，或 undefined 以清除它

chat/inputRequested

工作階段向使用者請求輸入。

在活動回合中建立未解決的 {@link InputRequestResponsePart}，或以具有相同請求 id 的未解決部分取代它。除非提供 request.answers，否則答案草稿會被保留。

欄位	類型	說明
type	ActionType.ChatInputRequested
request	ChatInputRequest	要建立或取代的輸入請求

chat/inputAnswerChanged

用戶端已更新、提交、跳過或移除單一進行中的答案。

以 answer: undefined 分派會移除該問題的答案草稿。

欄位	類型	必要	說明
type	ActionType.ChatInputAnswerChanged	是
requestId	string	是	輸入請求識別碼
questionId	string	是	輸入請求中的問題識別碼
answer	ChatInputAnswer	否	已更新的答案，或 undefined 以清除答案草稿

chat/inputCompleted

用戶端已提交對輸入請求的接受、拒絕或取消回應。

若接受，伺服器會使用 answers（若提供）加上請求的同步答案狀態來恢復受阻的操作。reducer 會在現有的 {@link InputRequestResponsePart} 上記錄回應與最終答案。

欄位	類型	必要	說明
type	ActionType.ChatInputCompleted	是
requestId	string	是	輸入請求識別碼
response	ChatInputResponseKind	是	完成結果
answers	Record<string, ChatInputAnswer>	否	選用的最終答案取代，以問題 ID 為鍵

ChatAction

ChatTurnStartedAction | ChatDeltaAction | ChatResponsePartAction | ChatToolCallStartAction | ChatToolCallDeltaAction | ChatToolCallReadyAction | ChatToolCallConfirmedAction | ChatToolCallCompleteAction | ChatToolCallResultConfirmedAction | ChatToolCallContentChangedAction | ChatToolCallAuthRequiredAction | ChatToolCallAuthResolvedAction | ChatTurnCompleteAction | ChatTurnCancelledAction | ChatErrorAction | ChatActivityChangedAction | ChatWorkingDirectorySetAction | ChatWorkingDirectoryRemovedAction | ChatUsageAction | ChatReasoningAction | ChatTruncatedAction | ChatTurnsLoadedAction | ChatPendingMessageSetAction | ChatPendingMessageRemovedAction | ChatQueuedMessagesReorderedAction | ChatDraftChangedAction | ChatInputRequestedAction | ChatInputAnswerChangedAction | ChatInputCompletedAction

指令

JSON Schema: commands.schema.json

createChat

在工作階段中建立新聊天。

屬性	值
方向	用戶端 → 伺服器
類型	請求

參數：

欄位	類型	必要	說明
channel	URI	是	包含新聊天的工作階段 URI。
chat	URI	是	聊天 URI（由用戶端選擇，例如 ahp-chat:/<uuid>）。
initialMessage	Message	否	新聊天的選用初始訊息。
source	ChatSource	否	選用的來源聊天與來源回合。 來源聊天 MUST 屬於此工作階段。用戶端 MUST 僅在所選代理程式公告 capabilities.multipleChats.fork 時請求 kind: "fork"，並僅在所選代理程式公告 capabilities.multipleChats.sideChat 時請求 kind: "sideChat"。兩種來源形式都帶有穩定的頂層 turnId。分叉的目標為已完成回合。側邊聊天也帶有穩定的 turnId，由主機對照來源聊天目前的活動回合或保留的歷史來解析。若它解析為活動回合，主機在接受 createChat 時會對目前可用的部分回應進行快照。當 source.kind === "sideChat" 且 source.selection 存在時，主機也會在所建立聊天的起源中對該確切選取文字進行快照並保留；其中的任何 responsePartId 僅作為出處，並非即時範圍。
workingDirectories	URI[]	否	此聊天的初始工作目錄子集。每個項目 MUST 存在於所屬工作階段的 workingDirectories 中；伺服器 MUST 拒絕任何不存在的項目。若省略，聊天會繼承完整的工作階段集合。分叉聊天（source.kind 為 "fork" 的聊天）會繼承來源聊天的 workingDirectories；此欄位對分叉會被忽略。 除非代理程式公告 {@link AgentCapabilities.multipleWorkingDirectories}，否則用戶端 MUST NOT 提供此欄位。
primaryWorkingDirectory	URI	否	聊天的主工作目錄 — 此聊天所置中的顯著根目錄。設定時，它 MUST 是聊天的有效工作目錄之一（{@link workingDirectories}，或省略時的工作階段集合）。當代理程式公告 {@link MultipleWorkingDirectoriesCapability.requiresPrimary} 時，用戶端 SHOULD 提供此項；主機 MAY 拒絕省略它的建立，或退回聊天的第一個目錄。建立時固定，並在 {@link ChatState.primaryWorkingDirectory} 上回報（唯讀）。對分叉會被忽略（source.kind 為 "fork" 的聊天會繼承來源聊天的主工作目錄）。

結果： 成功時為 null。

---

disposeChat

處置聊天並清理伺服器端資源。

屬性	值
方向	用戶端 → 伺服器
類型	請求

參數：

無參數。

結果： 成功時為 null。

---