Skip to main content

SessionEvent

Copilot에서 오는 메시지는 모두 Revolution\Copilot\Types\SessionEvent 클래스입니다. 이 클래스는 가장 많이 사용되므로 Laravel다운 편리 기능이 추가되어 있습니다.

content()

AI로부터의 가장 중요한 응답 메시지를 가져옵니다.
__toString()에 의한 암묵적 타입 변환으로도 메시지 내용을 반환합니다.

Event type 판정

isAssistantMessage(), isUserMessage(), isIdle(), isAssistantMessageDelta()를 사용할 수 있습니다. 자주 사용하는 Event type이 있다면 추가로 헬퍼가 추가되는 경우가 있습니다. is()로 임의의 EventType을 판정할 수 있습니다.
type()은 SessionEventType enum의 문자열 값을 반환합니다.

failed() / successful()

이벤트 타입이 SESSION_ERROR일 때는 failed()가 true가 됩니다. successful()은 그 반대입니다. Laravel의 명명에 맞추기 위해 isError()에서 개명되었습니다.

throw()

Laravel의 HTTP API나 Process API와 마찬가지로 에러는 보유되며, throw()로 예외를 송출할 수 있습니다. 에러가 없는 경우 아무것도 하지 않으므로 다음과 같이 쓸 수 있습니다.
이벤트 타입이 SESSION_ERROR인 경우 Revolution\Copilot\Exceptions\SessionErrorException을 송출합니다. 타임아웃 시에는 Revolution\Copilot\Exceptions\SessionTimeoutException을 송출합니다. JSON-RPC의 에러에서는 Revolution\Copilot\Exceptions\JsonRpcException을 송출합니다.

Conditionable

when()과 unless()를 사용할 수 있습니다.

Dumpable

dump()와 dd()를 사용할 수 있습니다.

Tappable

tap()을 사용할 수 있습니다.

InteractsWithData

이 기능은 SessionEvent의 $data 프로퍼티에만 적용됩니다. all(), has(), only(), collect() 등 익숙한 헬퍼를 사용할 수 있습니다. 자세한 내용은 InteractsWithData를 참고하세요. SessionEvent의 $data는 EventType마다 구조가 다르므로 이벤트별 값 접근에 편리합니다. content()도 내부적으로 InteractsWithData를 사용합니다.

toArray() / toJson()

SessionEvent 전체를 배열 또는 JSON으로 변환할 수 있습니다.
이벤트 전체용 collect() 메서드는 없습니다. $data에는 InteractsWithData의 collect()가 있기 때문입니다. 이벤트 전체를 컬렉션 조작하려면 Laravel의 collect() 헬퍼를 사용합니다.

broadcast() / broadcastNow()

Laravel AI SDK의 StreamEvent와 같은 인터페이스로 브로드캐스트할 수 있습니다. AI SDK에서는 스트리밍 시에 사용되지만, SessionEvent에서는 임의의 EventType에서 사용할 수 있습니다.
broadcastNow()는 큐를 거치지 않고 즉시 브로드캐스트합니다.
스트리밍 시의 이용 예:

이벤트 메타데이터

Copilot CLI 1.0.99 이후 일부 이벤트에는 추가 메타데이터가 포함됩니다. SDK는 이 값들을 $data에 그대로 보관하므로 $event->data나 InteractsWithData 헬퍼로 참조할 수 있습니다.

Compaction 이벤트

session.compaction_start와 session.compaction_complete의 data.compactionAttemptId는 시작 이벤트와 완료 이벤트를 연결하는 ID입니다. 모델 전환이 수반되는 경우 switchTargetModel도 포함됩니다. 전환 대상의 프롬프트 토큰 예산이 다른 경우 targetPromptTokenLimit도 포함됩니다. 완료 이벤트에는 initialModel, model, outcome, outcomeReason, failureReason, tokenAccountingBasis 등이 포함될 수 있습니다. outcome과 각 사유 필드는 앞으로 새로운 값이 추가될 수 있는 문자열입니다. 고정된 Enum으로 취급하지 말고 알 수 없는 값도 그대로 보관하세요. 필드가 없다면 값이 제공되지 않았다는 뜻입니다. 기본값을 추측하지 마세요.

도구 실행 사용량

tool.execution_complete의 data.toolUsage는 런타임이 소유한 도구 작업에 대해 프로바이더가 보고한 사용량입니다. 대화 모델의 assistant.usage와는 별개의 사용량입니다. 도구 실행이 실패한 경우에도 보고된 사용량이 포함될 수 있습니다. toolUsage.model은 도구 작업에서 요청한 모델이며 대화 모델이 아닙니다. 토큰 수나 과금 정보는 일부만 제공될 수 있습니다. 필드가 없다면 사용할 수 없다는 뜻이며 0 토큰을 의미하지 않습니다.
inputTokensDetails와 outputTokensDetails의 모달리티별 토큰 수는 각각의 합계에 포함된 내역입니다. 합계에 더하지 마세요. toolUsage.requestId는 런타임이 중복 전달이나 재생을 제거하기 위한 ID이며 업스트림 과금 식별자가 아닙니다. session.usage_checkpoint와 session.shutdown의 data.toolUsageRequestIds도 회계 스냅샷에 포함된 도구 작업을 식별하는 런타임 내부의 중복 제거 메타데이터입니다. 업스트림 과금 ID로 취급하지 마세요.

Fusion 해결 이벤트

session.fusion_resolved의 data.selectedRuleId는 서버 측 라우팅이 로컬 규칙과 다른 워크플로를 선택한 경우 해당 서버 규칙을 식별합니다. 대체가 없으면 생략됩니다.

MCP 서버 도구 로드 이벤트

SessionEventType::SESSION_MCP_SERVER_TOOLS_LOADED(session.mcp_server_tools_loaded)는 MCP 서버의 도구 목록을 사용할 수 있게 되었을 때 발생합니다. 연결마다 한 번만 발생하는 ephemeral 이벤트이며 영속화되지 않습니다. data.serverName과 data.toolCount를 포함합니다. MCP 서버가 connected가 되었다고 해서 도구 로드가 완료된 것은 아닙니다. 연결 상태를 벗어난 후에는 다음에 이 이벤트를 받을 때까지 로드 중으로 취급하세요. 캐시된 도구를 사용하는 경우 이 이벤트가 connected보다 먼저 도착할 수 있습니다.
최신 정보는 GitHub 저장소를 참고하세요.
마지막 수정일 2026년 10월 19일