SessionEvent

Every message from Copilot is a Revolution\Copilot\Types\SessionEvent class. Because this is the class you use most often, Laravel-native conveniences are added on top.

`content()`

Get the most important response message from the AI.

$response = Copilot::run('1 + 1');
echo $response->content(); // '2'
// content() can be null

Implicit conversion via __toString() also returns the message content.

echo (string) $response; // '2'
// This one is never null

Checking the event type

isAssistantMessage(), isUserMessage(), isIdle(), and isAssistantMessageDelta() are available. Additional helpers may be added for commonly used event types. Use is() to check for any EventType.

use Revolution\Copilot\Enums\SessionEventType;

if ($response->is(SessionEventType::HOOK_START)) {
    // Handle the hook-start event
}

type() returns the string value of the SessionEventType enum.

echo $response->type(); // 'assistant.message'

`failed()` / `successful()`

When the event type is SESSION_ERROR, failed() returns true. successful() is the opposite. Renamed from isError() to match Laravel’s naming.

`throw()`

Just like Laravel’s HTTP or Process API, errors are retained and can be raised via throw(). If there’s no error it does nothing, so you can write:

$content = $response->throw()->content();

If the event type is SESSION_ERROR, Revolution\Copilot\Exceptions\SessionErrorException is thrown. On timeout, Revolution\Copilot\Exceptions\SessionTimeoutException is thrown. For JSON-RPC errors, Revolution\Copilot\Exceptions\JsonRpcException is thrown.

Conditionable

when() and unless() are available.

$response->when($response->isAssistantMessage(), function (SessionEvent $event) {
    // Handle assistant messages
});

Dumpable

dump() and dd() are available.

$response->dump();

Tappable

tap() is available.

return $response->tap(function (SessionEvent $event) {
    // Do something
    info($event->content());
});

InteractsWithData

This feature applies only to SessionEvent’s $data property. Familiar helpers such as all(), has(), only(), and collect() are available. See InteractsWithData for details. Because SessionEvent’s $data shape differs per EventType, this is handy for accessing event-specific values. content() also uses InteractsWithData under the hood.

return $this->data('content', $default);

// Pass a default to keep content() from being null
echo $response->content('');

`toArray()` / `toJson()`

You can convert the entire SessionEvent to an array or JSON.

$array = $response->toArray();
$json = $response->toJson();

There is no top-level collect() method for the event as a whole, since InteractsWithData already provides collect() for $data. To perform collection operations on the whole event, use Laravel’s collect() helper.

$collect = collect($response->toArray());

`broadcast()` / `broadcastNow()`

You can broadcast with the same interface as the Laravel AI SDK’s StreamEvent. The AI SDK uses it during streaming, but for SessionEvent you can use it with any EventType.

use Illuminate\Broadcasting\Channel;

$event->broadcast(new Channel('channel-name'));

broadcastNow() broadcasts immediately without going through a queue.

$event->broadcastNow(new Channel('channel-name'));

Streaming example:

use Illuminate\Broadcasting\Channel;
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SessionEvent;

Copilot::start(function (CopilotSession $session) {
    $session->on(function (SessionEvent $event): void {
        if ($event->isAssistantMessageDelta()) {
            $event->broadcastNow(new Channel('copilot'));
        }
    });

    $session->sendAndWait(prompt: 'Tell me something about Laravel.');
}, config: new SessionConfig(streaming: true));

Event metadata

Starting with Copilot CLI 1.0.99, some events include additional metadata. The SDK keeps these values as-is in $data, so you can access them through $event->data or the InteractsWithData helpers.

Compaction events

data.compactionAttemptId on session.compaction_start and session.compaction_complete is an ID that links the start event to the complete event. When the compaction involves a model switch, switchTargetModel is also included. When the target model has a different prompt token budget, targetPromptTokenLimit is also included. The complete event may include initialModel, model, outcome, outcomeReason, failureReason, tokenAccountingBasis, and more. outcome and the reason fields are strings that may gain new values in the future. Don’t treat them as a fixed enum, and preserve unknown values as-is. A missing field means the value wasn’t provided. Don’t infer a default value.

if ($event->is(SessionEventType::SESSION_COMPACTION_COMPLETE)) {
    $attemptId = $event->data('compactionAttemptId');
    $outcome = $event->data('outcome');
}

Tool execution usage

data.toolUsage on tool.execution_complete is the provider-reported usage for runtime-owned tool operations. It is separate from the conversation model’s assistant.usage. It may include reported usage even when the tool execution failed. toolUsage.model is the model requested by the tool operation, not the conversation model. Token counts and billing information may be only partially provided. A missing field means the value is unavailable, not zero tokens.

$usage = $event->data['toolUsage'] ?? null;
$inputTokens = $usage['inputTokens'] ?? null;
$imageTokens = $usage['inputTokensDetails']['imageTokens'] ?? null;

The per-modality token counts in inputTokensDetails and outputTokensDetails are breakdowns included in their respective totals. Don’t add them to the totals. toolUsage.requestId is an ID the runtime uses to deduplicate redelivery and replay. It is not an upstream billing identifier. data.toolUsageRequestIds on session.usage_checkpoint and session.shutdown is also runtime-internal deduplication metadata that identifies the tool operations included in the accounting snapshot. Don’t treat it as an upstream billing ID.

Fusion resolved events

data.selectedRuleId on session.fusion_resolved identifies the server rule when server-side routing selects a different workflow than the local rule. It is omitted when there is no override.

MCP server tools loaded events

SessionEventType::SESSION_MCP_SERVER_TOOLS_LOADED (session.mcp_server_tools_loaded) fires when an MCP server’s tool list becomes available. It is an ephemeral event that fires once per connection and is not persisted. It includes data.serverName and data.toolCount. An MCP server reaching connected does not mean its tools have finished loading. After the server leaves the connected state, treat it as loading until you receive this event again. When cached tools are used, this event may arrive before connected.

if ($event->is(SessionEventType::SESSION_MCP_SERVER_TOOLS_LOADED)) {
    info("{$event->data('serverName')}: {$event->data('toolCount')} tools loaded");
}

For the latest updates, see the GitHub repository.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds and RSS

Middleware

SessionEvent

SessionEvent

`content()`

Checking the event type

`failed()` / `successful()`

`throw()`

Conditionable

Dumpable

Tappable

InteractsWithData

`toArray()` / `toJson()`

`broadcast()` / `broadcastNow()`

Event metadata

Compaction events

Tool execution usage

Fusion resolved events

MCP server tools loaded events

​SessionEvent

​content()

​Checking the event type

​failed() / successful()

​throw()

​Conditionable

​Dumpable

​Tappable

​InteractsWithData

​toArray() / toJson()

​broadcast() / broadcastNow()

​Event metadata

​Compaction events

​Tool execution usage

​Fusion resolved events

​MCP server tools loaded events

SessionEvent

`content()`

Checking the event type

`failed()` / `successful()`

`throw()`

Conditionable

Dumpable

Tappable

InteractsWithData

`toArray()` / `toJson()`

`broadcast()` / `broadcastNow()`

Event metadata

Compaction events

Tool execution usage

Fusion resolved events

MCP server tools loaded events