세션 라이프사이클 이벤트

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

​

세션 라이프사이클 이벤트

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

​

이벤트 타입

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

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

use Revolution\Copilot\Enums\SessionLifecycleEventType;

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

​

이벤트 구독

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

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입니다.

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

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

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

​

포그라운드 세션 관리

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

​

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

use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

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

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

​

포그라운드 세션 설정

use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

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

​

ForegroundSessionInfo

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

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에서 접속함으로써 라이프사이클 이벤트를 활용할 수 있습니다.

# TUI+서버 모드에서 Copilot CLI 기동
copilot --ui-server --port 8080

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의 onSessionStart나 onSessionEnd와는 별개의 기능입니다

최신 정보는 GitHub 저장소를 참고하세요.