Streaming Events

在 SessionConfig 中啟用 streaming: true 後,Session 中的動作會以事件形式依序傳遞。本頁是將官方的 streaming-events.md 針對 Laravel 版做易讀化整理的版本。

SessionEvent 頁面是 Laravel 版擴充的 SessionEvent 類別本身的說明。本頁則是「何種事件類型會傳送何種資料」的參考文件。

概觀

Copilot Agent 的處理(推論、訊息生成、工具執行、權限確認等)全部都以 Session Event 形式傳遞。

Ephemeral event: 僅即時傳遞。不會持久化至 Session log(恢復時不會重播)
Persisted event: 儲存於 Session log(恢復時會重播)
Delta event: 分段傳來的差異事件(如 deltaContent),需串接以構成全文
parentId chain: 每個事件參照前一個事件 ID 形成的鏈結

Event envelope(共用欄位)

所有事件都具備以下共用結構。

Field	Type	說明
`id`	`string`	事件唯一 ID(UUID v4)
`timestamp`	`string`	建立時間(ISO 8601)
`parentId`	`string \| null`	前一事件 ID(首個事件為 `null`)
`ephemeral`	`boolean?`	若為暫時事件則為 `true`
`type`	`string`	事件類型
`data`	`object`	事件專屬 payload

Laravel 訂閱範例

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SessionEvent;

Copilot::start(function (CopilotSession $session): void {
    // 所有事件
    $session->on(function (SessionEvent $event): void {
        info($event->type(), $event->toArray());
    });

    // 特定事件
    $session->on(SessionEventType::ASSISTANT_MESSAGE_DELTA, function (SessionEvent $event): void {
        echo $event->deltaContent();
    });

    $session->sendAndWait(prompt: '請告訴我 Laravel 的特色');
}, config: new SessionConfig(streaming: true));

主要事件分類

Assistant events

`assistant.turn_start`

Turn 開始。

turnId(必填)
interactionId(選填)

`assistant.intent`(ephemeral)

目前的執行意圖(例如 Exploring codebase)。

intent(必填)

`assistant.reasoning`

推論區塊的完整版。

reasoningId(必填)
content(必填)

`assistant.reasoning_delta`(ephemeral)

推論文字的差異。

reasoningId(必填)
deltaContent(必填)

`assistant.message`

Assistant 的完整訊息。主要欄位:

messageId(必填)
content(必填)
toolRequests(選填)
reasoningOpaque / reasoningText / encryptedContent(選填)
phase / outputTokens / interactionId(選填)
parentToolCallId(選填,由 sub-agent 產生時)

`assistant.message_delta`(ephemeral)

訊息本文的差異。

messageId(必填)
deltaContent(必填)
parentToolCallId(選填)

`assistant.turn_end`

Turn 結束。

turnId(必填)

`assistant.usage`(ephemeral)

單一 API 呼叫的使用量資訊。主要欄位:

model(必填)
inputTokens / outputTokens / cost / duration(選填)
apiCallId / providerCallId(選填)
quotaSnapshots / copilotUsage(選填)

`assistant.streaming_delta`(ephemeral)

低層次的接收進度。

totalResponseSizeBytes(必填)

Tool execution events

`tool.execution_start`

工具執行開始。

toolCallId(必填)
toolName(必填)
arguments / mcpServerName / mcpToolName / parentToolCallId(選填)

`tool.execution_partial_result`(ephemeral)

工具執行中的部分輸出。

toolCallId(必填)
partialOutput(必填)

`tool.execution_progress`(ephemeral)

進度訊息。

toolCallId(必填)
progressMessage(必填)

`tool.execution_complete`

工具執行完成(成功/失敗)。

toolCallId(必填)
success(必填)
result(成功時)
error(失敗時)
toolTelemetry / parentToolCallId(選填)

`tool.user_requested`

使用者明確要求的工具呼叫。

toolCallId(必填)
toolName(必填)
arguments(選填)

Session lifecycle events

`session.start`

Session 開始。在 Cloud Sessions 中,建議確認 producer 為 copilot-agent 的 session.start 後再送出第一個 prompt,較為安全。

producer(選填)

`session.idle`(ephemeral)

目前處理完成,等待下一個輸入。

backgroundTasks(選填)

`session.error`

Session 處理中的錯誤。

errorType(必填)
message(必填)
stack / statusCode / providerCallId(選填)

`session.compaction_start`

Context 壓縮開始(data 為空物件)。

`session.compaction_complete`

Context 壓縮完成。主要欄位:

success(必填)
error(選填)
preCompactionTokens / postCompactionTokens(選填)
summaryContent / checkpointPath(選填)

`session.title_changed`(ephemeral)

自動標題更新。

title(必填)

`session.context_changed`

Working context 變更。

cwd(必填)
gitRoot / repository / branch(選填)

`session.info`

遠端 URL 等 Session 資訊。

infoType(必填)
url(選填,例如 infoType 為 remote 時)

`session.remote_steerable_changed`

表示來自 Mission Control 的遠端操作可否發生變化。

remoteSteerable(選填)

`session.usage_info`(ephemeral)

Context window 使用狀況。

tokenLimit(必填)
currentTokens(必填)
messagesLength(必填)

`session.task_complete`

任務完成通知。

summary(選填)

`session.shutdown`

Session 結束。主要欄位:

shutdownType(必填)
errorReason(選填)
totalPremiumRequests / totalApiDurationMs(必填)
codeChanges / modelMetrics(必填)

Permission / user input events

`permission.requested`(ephemeral)

權限確認要求。

requestId(必填)
permissionRequest(必填)

permissionRequest.kind:

shell
write
read
mcp
url
memory
custom-tool

`permission.completed`(ephemeral)

權限確認的解決結果。

requestId(必填)
result.kind(必填)

`user_input.requested`(ephemeral)

向使用者提問。

requestId(必填)
question(必填)
choices / allowFreeform(選填)

`user_input.completed`(ephemeral)

使用者輸入完成。

requestId(必填)

`elicitation.requested`(ephemeral)

結構化輸入(表單)要求。

requestId(必填)
message(必填)
requestedSchema(必填)

`elicitation.completed`(ephemeral)

結構化輸入完成。

requestId(必填)

Sub-agent / skill events

`subagent.started`

toolCallId(必填)
agentName / agentDisplayName / agentDescription(必填)

`subagent.completed`

toolCallId(必填)
agentName / agentDisplayName(必填)

`subagent.failed`

toolCallId(必填)
agentName / agentDisplayName(必填)
error(必填)

`subagent.selected`

agentName(必填)
agentDisplayName(必填)
tools(必填,允許 null)

`subagent.deselected`

回到預設 Agent(data 為空物件)。

`skill.invoked`

name / path / content(必填)
allowedTools / pluginName / pluginVersion(選填)

Other events

`abort`

reason(必填)

`user.message`

content(必填)
transformedContent / attachments / source / agentMode / interactionId(選填)

`system.message`

content(必填)
role(必填)
name / metadata(選填)

`external_tool.requested`(ephemeral)

requestId / sessionId / toolCallId / toolName(必填)
arguments(選填)

`external_tool.completed`(ephemeral)

requestId(必填)

`exit_plan_mode.requested`(ephemeral)

requestId / summary / planContent / actions / recommendedAction(必填)

`exit_plan_mode.completed`(ephemeral)

requestId(必填)

`command.queued`(ephemeral)

requestId(必填)
command(必填)

`command.completed`(ephemeral)

requestId(必填)

典型事件順序

assistant.turn_start
├── assistant.intent (ephemeral)
├── assistant.reasoning_delta (ephemeral, 多次)
├── assistant.reasoning
├── assistant.message_delta (ephemeral, 多次)
├── assistant.message
├── assistant.usage (ephemeral)
├── [必要時 permission / tool.* 會循環]
assistant.turn_end
session.idle (ephemeral)

全事件一覽(快速參考)

Event Type	Ephemeral	Category
`session.start`		Session
`assistant.turn_start`		Assistant
`assistant.intent`	✅	Assistant
`assistant.reasoning`		Assistant
`assistant.reasoning_delta`	✅	Assistant
`assistant.streaming_delta`	✅	Assistant
`assistant.message`		Assistant
`assistant.message_delta`	✅	Assistant
`assistant.turn_end`		Assistant
`assistant.usage`	✅	Assistant
`tool.user_requested`		Tool
`tool.execution_start`		Tool
`tool.execution_partial_result`	✅	Tool
`tool.execution_progress`	✅	Tool
`tool.execution_complete`		Tool
`session.idle`	✅	Session
`session.error`		Session
`session.compaction_start`		Session
`session.compaction_complete`		Session
`session.title_changed`	✅	Session
`session.context_changed`		Session
`session.info`		Session
`session.remote_steerable_changed`		Session
`session.usage_info`	✅	Session
`session.task_complete`		Session
`session.shutdown`		Session
`permission.requested`	✅	Permission
`permission.completed`	✅	Permission
`user_input.requested`	✅	User Input
`user_input.completed`	✅	User Input
`elicitation.requested`	✅	User Input
`elicitation.completed`	✅	User Input
`subagent.started`		Sub-Agent
`subagent.completed`		Sub-Agent
`subagent.failed`		Sub-Agent
`subagent.selected`		Sub-Agent
`subagent.deselected`		Sub-Agent
`skill.invoked`		Skill
`abort`		Control
`user.message`		User
`system.message`		System
`external_tool.requested`	✅	External Tool
`external_tool.completed`	✅	External Tool
`command.queued`	✅	Command
`command.completed`	✅	Command
`exit_plan_mode.requested`	✅	Plan Mode
`exit_plan_mode.completed`	✅	Plan Mode