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

# 세션 라이프사이클 이벤트

> Laravel Copilot SDK의 세션 생성, 업데이트, 삭제, 포그라운드 상태 변경 이벤트를 구독하는 방법을 설명합니다.

## 세션 라이프사이클 이벤트

세션 라이프사이클 이벤트는 세션의 생성, 삭제, 업데이트 그리고 포그라운드/백그라운드 상태 변경(TUI+서버 모드 시)을 통지하는 이벤트입니다.

## 이벤트 타입

`SessionLifecycleEventType` enum으로 정의된 5개의 이벤트 타입이 있습니다.

| 이벤트                  | 설명                |
| -------------------- | ----------------- |
| `session.created`    | 새 세션이 작성되었습니다     |
| `session.deleted`    | 세션이 삭제되었습니다       |
| `session.updated`    | 세션이 업데이트되었습니다     |
| `session.foreground` | 세션이 포그라운드로 이동했습니다 |
| `session.background` | 세션이 백그라운드로 이동했습니다 |

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

// 이벤트 타입 값 가져오기
echo SessionLifecycleEventType::SESSION_CREATED->value; // 'session.created'
```

## 이벤트 구독

`onLifecycle()` 메서드를 사용해 세션 라이프사이클 이벤트를 구독할 수 있습니다.

```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("세션 작성: {$event->sessionId}"),
        SessionLifecycleEventType::SESSION_DELETED => info("세션 삭제: {$event->sessionId}"),
        SessionLifecycleEventType::SESSION_FOREGROUND => info("포그라운드: {$event->sessionId}"),
        SessionLifecycleEventType::SESSION_BACKGROUND => info("백그라운드: {$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,                 // 세션 ID
        public ?SessionLifecycleEventMetadata $metadata = null,  // 메타데이터(삭제 시에는 포함되지 않음)
    ) {}
}
```

### SessionLifecycleEventMetadata

세션 메타데이터를 포함하는 클래스입니다(삭제 이벤트에는 포함되지 않습니다).

```php theme={null}
readonly class SessionLifecycleEventMetadata implements Arrayable
{
    public function __construct(
        public string $startTime,      // 세션 시작 시각
        public string $modifiedTime,   // 마지막 업데이트 시각
        public ?string $summary = null, // 세션 요약
    ) {}
}
```

## 포그라운드 세션 관리

TUI+서버 모드(`--ui-server`)에서 동작하는 서버에 접속하는 경우, 포그라운드 세션을 관리할 수 있습니다.

### 현재 포그라운드 세션 가져오기

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

$client = Copilot::client();

// TUI에 표시된 현재의 세션 ID 가져오기
$sessionId = $client->getForegroundSessionId();

if ($sessionId !== null) {
    echo "현재의 포그라운드 세션: {$sessionId}";
}
```

### 포그라운드 세션 설정

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

$client = Copilot::client();

// TUI에 특정 세션 표시
$client->setForegroundSessionId('session-123');
```

## ForegroundSessionInfo

포그라운드 세션의 정보를 포함하는 readonly class입니다.

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

readonly class ForegroundSessionInfo implements Arrayable
{
    public function __construct(
        public ?string $sessionId = null,      // 포그라운드 세션 ID
        public ?string $workspacePath = null,  // 워크스페이스 경로
    ) {}
}
```

## TCP 모드에서의 사용

TUI+서버 모드에서 Copilot CLI를 기동하고 SDK에서 접속함으로써 라이프사이클 이벤트를 활용할 수 있습니다.

```bash theme={null}
# TUI+서버 모드에서 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+서버 모드에서만 발생합니다
* 세션 삭제 시(`session.deleted`)에는 `metadata` 프로퍼티가 `null`이 됩니다
* `onLifecycle()`은 구독 해제용 콜백 함수를 반환합니다
* [Session Hooks](/ko/packages/laravel-copilot-sdk/hooks)의 `onSessionStart`나 `onSessionEnd`와는 별개의 기능입니다

<Info>
  최신 정보는 [GitHub 저장소](https://github.com/invokable/laravel-copilot-sdk)를 참고하세요.
</Info>


## Related topics

- [요청 라이프사이클](/ko/lifecycle.md)
- [Eloquent 입문](/ko/eloquent.md)
- [⚡Livewire 4 입문 — JavaScript 없이 리액티브한 UI 만들기](/ko/blog/livewire-introduction.md)
- [세션 훅](/ko/packages/laravel-copilot-sdk/hooks.md)
- [Eloquent의 커스텀 캐스트](/ko/advanced/eloquent-casts.md)