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 lifecycle events
Session lifecycle events notify you about session creation, deletion, updates, and foreground/background state changes (in TUI + server mode).
Event types
The SessionLifecycleEventType enum defines five event types:
| Event | Description |
|---|
session.created | A new session was created |
session.deleted | A session was deleted |
session.updated | A session was updated |
session.foreground | A session moved to foreground |
session.background | A session moved to background |
use Revolution\Copilot\Enums\SessionLifecycleEventType;
// Get enum value
echo SessionLifecycleEventType::SESSION_CREATED->value; // 'session.created'
Subscribe to events
Use onLifecycle() to subscribe to session lifecycle events:
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionLifecycleEvent;
// Get client and subscribe to lifecycle events
$client = Copilot::client();
// Subscribe to all lifecycle events
$unsubscribe = $client->onLifecycle(function (SessionLifecycleEvent $event) {
match ($event->type) {
SessionLifecycleEventType::SESSION_CREATED => info("Session created: {$event->sessionId}"),
SessionLifecycleEventType::SESSION_DELETED => info("Session deleted: {$event->sessionId}"),
SessionLifecycleEventType::SESSION_FOREGROUND => info("Foreground: {$event->sessionId}"),
SessionLifecycleEventType::SESSION_BACKGROUND => info("Background: {$event->sessionId}"),
default => null,
};
});
// Unsubscribe
$unsubscribe();
SessionLifecycleEvent
SessionLifecycleEvent is a readonly class with lifecycle event details:
use Revolution\Copilot\Types\SessionLifecycleEvent;
use Revolution\Copilot\Types\SessionLifecycleEventMetadata;
readonly class SessionLifecycleEvent implements Arrayable
{
public function __construct(
public SessionLifecycleEventType $type, // Event type
public string $sessionId, // Session ID
public ?SessionLifecycleEventMetadata $metadata = null, // Metadata (null on delete)
) {}
}
readonly class SessionLifecycleEventMetadata implements Arrayable
{
public function __construct(
public string $startTime, // Session start time
public string $modifiedTime, // Last modified time
public ?string $summary = null, // Session summary
) {}
}
Foreground session management
When connected to a server running in TUI + server mode (--ui-server), you can manage the foreground session.
Get current foreground session
use Revolution\Copilot\Facades\Copilot;
$client = Copilot::client();
// Get the current session ID shown in TUI
$sessionId = $client->getForegroundSessionId();
if ($sessionId !== null) {
echo "Current foreground session: {$sessionId}";
}
Set foreground session
use Revolution\Copilot\Facades\Copilot;
$client = Copilot::client();
// Show a specific session in TUI
$client->setForegroundSessionId('session-123');
ForegroundSessionInfo
ForegroundSessionInfo is a readonly class with foreground session details:
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 path
) {}
}
TCP mode usage
Run Copilot CLI in TUI + server mode, then connect from the SDK to use lifecycle events:
# Start Copilot CLI in TUI + server mode
copilot --ui-server --port 8080
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionLifecycleEvent;
// Connect in TCP mode
$client = Copilot::useTcp('tcp://127.0.0.1:8080')->client();
// Subscribe to lifecycle events
$client->onLifecycle(function (SessionLifecycleEvent $event) {
// Handle events
});
Notes
session.foreground and session.background events occur only in TUI + server mode.- On session delete (
session.deleted), metadata is null.
onLifecycle() returns a callback for unsubscribing.
