> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Streaming Events

> 整理啟用 SessionConfig 的 streaming 時可接收的 Session Event 種類與 payload。

## Streaming Events

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

> [SessionEvent](/zh-TW/packages/laravel-copilot-sdk/session-event) 頁面是 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 訂閱範例

```php theme={null}
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`(必填)

## 典型事件順序

```text theme={null}
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     |

## 相關文件

* [官方 Streaming Events 參考](https://github.com/github/copilot-sdk/blob/main/docs/features/streaming-events.md)
* Laravel 版事件類別說明: [SessionEvent](/zh-TW/packages/laravel-copilot-sdk/session-event)
* Streaming 實作模式: [Streaming](/zh-TW/packages/laravel-copilot-sdk/streaming)


## Related topics

- [Streaming](/zh-TW/packages/laravel-copilot-sdk/streaming.md)
- [SessionEvent](/zh-TW/packages/laravel-copilot-sdk/session-event.md)
- [Laravel AI SDK](/zh-TW/ai-sdk.md)
- [Steering 與 Queueing](/zh-TW/packages/laravel-copilot-sdk/steering.md)
- [Cloud Sessions](/zh-TW/packages/laravel-copilot-sdk/cloud-sessions.md)