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

# Session 生命週期事件

> 說明如何訂閱 Laravel Copilot SDK 的 Session 建立、更新、刪除,以及 Foreground 狀態變更事件。

## Session 生命週期事件

Session 生命週期事件是通知 Session 的建立、刪除、更新,以及 foreground/background 狀態變更(TUI+Server 模式)的事件。

## 事件類型

`SessionLifecycleEventType` enum 定義了 5 種事件類型。

| 事件                   | 說明                    |
| -------------------- | --------------------- |
| `session.created`    | 建立了新 Session          |
| `session.deleted`    | Session 已被刪除          |
| `session.updated`    | Session 已更新           |
| `session.foreground` | Session 移至 foreground |
| `session.background` | Session 移至 background |

```php theme={null}
use Revolution\Copilot\Enums\SessionLifecycleEventType;

// 取得事件類型的值
echo SessionLifecycleEventType::SESSION_CREATED->value; // 'session.created'
```

## 訂閱事件

使用 `onLifecycle()` 方法可訂閱 Session 生命週期事件。

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionLifecycleEvent;

// 取得 Client 並訂閱生命週期事件
$client = Copilot::client();

// 訂閱所有生命週期事件
$unsubscribe = $client->onLifecycle(function (SessionLifecycleEvent $event) {
    match ($event->type) {
        SessionLifecycleEventType::SESSION_CREATED => info("Session 建立: {$event->sessionId}"),
        SessionLifecycleEventType::SESSION_DELETED => info("Session 刪除: {$event->sessionId}"),
        SessionLifecycleEventType::SESSION_FOREGROUND => info("Foreground: {$event->sessionId}"),
        SessionLifecycleEventType::SESSION_BACKGROUND => info("Background: {$event->sessionId}"),
        default => null,
    };
});

// 取消訂閱
$unsubscribe();
```

## SessionLifecycleEvent

`SessionLifecycleEvent` 是包含生命週期事件細節的 readonly class。

```php theme={null}
use Revolution\Copilot\Types\SessionLifecycleEvent;
use Revolution\Copilot\Types\SessionLifecycleEventMetadata;

readonly class SessionLifecycleEvent implements Arrayable
{
    public function __construct(
        public SessionLifecycleEventType $type,  // 事件類型
        public string $sessionId,                 // Session ID
        public ?SessionLifecycleEventMetadata $metadata = null,  // Metadata(刪除時不包含)
    ) {}
}
```

### SessionLifecycleEventMetadata

包含 Session metadata 的類別(刪除事件不包含)。

```php theme={null}
readonly class SessionLifecycleEventMetadata implements Arrayable
{
    public function __construct(
        public string $startTime,      // Session 開始時間
        public string $modifiedTime,   // 最終更新時間
        public ?string $summary = null, // Session 摘要
    ) {}
}
```

## Foreground Session 管理

若連接到以 TUI+Server 模式(`--ui-server`)執行的伺服器,可管理 foreground Session。

### 取得目前的 Foreground Session

```php theme={null}
use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

// 取得目前顯示於 TUI 的 Session ID
$sessionId = $client->getForegroundSessionId();

if ($sessionId !== null) {
    echo "目前的 Foreground Session: {$sessionId}";
}
```

### 設定 Foreground Session

```php theme={null}
use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

// 在 TUI 顯示特定的 Session
$client->setForegroundSessionId('session-123');
```

## ForegroundSessionInfo

包含 foreground Session 資訊的 readonly class。

```php theme={null}
use Revolution\Copilot\Types\ForegroundSessionInfo;

readonly class ForegroundSessionInfo implements Arrayable
{
    public function __construct(
        public ?string $sessionId = null,      // Foreground Session ID
        public ?string $workspacePath = null,  // Workspace 路徑
    ) {}
}
```

## 於 TCP 模式使用

以 TUI+Server 模式啟動 Copilot CLI,並從 SDK 連線即可使用生命週期事件。

```bash theme={null}
# 以 TUI+Server 模式啟動 Copilot CLI
copilot --ui-server --port 8080
```

```php theme={null}
use Revolution\Copilot\Facades\Copilot;

// 以 TCP 模式連線至伺服器
$client = Copilot::useTcp('tcp://127.0.0.1:8080')->client();

// 訂閱生命週期事件
$client->onLifecycle(function (SessionLifecycleEvent $event) {
    // 事件處理
});
```

## 注意事項

* `session.foreground` 與 `session.background` 事件僅在 TUI+Server 模式下發生
* Session 刪除時(`session.deleted`),`metadata` 屬性為 `null`
* `onLifecycle()` 會回傳用於取消訂閱的回呼函式
* 與 [Session Hooks](/zh-TW/packages/laravel-copilot-sdk/hooks) 的 `onSessionStart` 或 `onSessionEnd` 是不同的功能

<Info>
  最新資訊請參閱 [GitHub 儲存庫](https://github.com/invokable/laravel-copilot-sdk)。
</Info>


## Related topics

- [Eloquent 入門](/zh-TW/eloquent.md)
- [SessionConfig](/zh-TW/packages/laravel-copilot-sdk/session-config.md)
- [請求生命週期](/zh-TW/lifecycle.md)
- [Eloquent 的自訂 Cast](/zh-TW/advanced/eloquent-casts.md)
- [Session Hook](/zh-TW/packages/laravel-copilot-sdk/hooks.md)