Eventos del ciclo de vida de sesión

Los eventos del ciclo de vida de sesión notifican la creación, eliminación y actualización de sesiones, así como los cambios de estado foreground/background (en modo TUI+servidor).

Tipos de evento

Hay 5 tipos de evento definidos en el enum SessionLifecycleEventType.

Evento	Descripción
`session.created`	Se creó una nueva sesión
`session.deleted`	Se eliminó una sesión
`session.updated`	Se actualizó una sesión
`session.foreground`	La sesión pasó a primer plano
`session.background`	La sesión pasó a segundo plano

use Revolution\Copilot\Enums\SessionLifecycleEventType;

// Obtén el valor del tipo de evento
echo SessionLifecycleEventType::SESSION_CREATED->value; // 'session.created'

Suscribirse a eventos

Puedes suscribirte a los eventos del ciclo de vida con el método onLifecycle().

use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionLifecycleEvent;

// Obtén el Client y suscríbete a los eventos del ciclo de vida
$client = Copilot::client();

// Suscríbete a todos los eventos del ciclo de vida
$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,
    };
});

// Cancela la suscripción
$unsubscribe();

SessionLifecycleEvent

SessionLifecycleEvent es una readonly class con el detalle del evento del ciclo de vida.

use Revolution\Copilot\Types\SessionLifecycleEvent;
use Revolution\Copilot\Types\SessionLifecycleEventMetadata;

readonly class SessionLifecycleEvent implements Arrayable
{
    public function __construct(
        public SessionLifecycleEventType $type,  // tipo de evento
        public string $sessionId,                 // ID de sesión
        public ?SessionLifecycleEventMetadata $metadata = null,  // metadata (no está en el evento de eliminación)
    ) {}
}

SessionLifecycleEventMetadata

Clase con los metadatos de la sesión (no se incluye en el evento de eliminación).

readonly class SessionLifecycleEventMetadata implements Arrayable
{
    public function __construct(
        public string $startTime,      // hora de inicio de la sesión
        public string $modifiedTime,   // hora de última modificación
        public ?string $summary = null, // resumen de la sesión
    ) {}
}

Gestión de la sesión foreground

Cuando estás conectado a un servidor en modo TUI+servidor (--ui-server), puedes gestionar la sesión foreground.

Obtener la sesión foreground actual

use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

// Obtén el ID de sesión que se muestra actualmente en la TUI
$sessionId = $client->getForegroundSessionId();

if ($sessionId !== null) {
    echo "Sesión foreground actual: {$sessionId}";
}

Establecer la sesión foreground

use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

// Muestra una sesión concreta en la TUI
$client->setForegroundSessionId('session-123');

ForegroundSessionInfo

Readonly class con la información de la sesión foreground.

use Revolution\Copilot\Types\ForegroundSessionInfo;

readonly class ForegroundSessionInfo implements Arrayable
{
    public function __construct(
        public ?string $sessionId = null,      // ID de la sesión foreground
        public ?string $workspacePath = null,  // ruta del workspace
    ) {}
}

Uso en modo TCP

Puedes aprovechar los eventos del ciclo de vida arrancando Copilot CLI en modo TUI+servidor y conectando desde el SDK.

# Arranca Copilot CLI en modo TUI+servidor
copilot --ui-server --port 8080

use Revolution\Copilot\Facades\Copilot;

// Conecta al servidor en modo TCP
$client = Copilot::useTcp('tcp://127.0.0.1:8080')->client();

// Suscríbete a los eventos del ciclo de vida
$client->onLifecycle(function (SessionLifecycleEvent $event) {
    // Procesa el evento
});

Consideraciones

Los eventos session.foreground y session.background solo se producen en modo TUI+servidor
En la eliminación de sesión (session.deleted), la propiedad metadata es null
onLifecycle() devuelve un callback para cancelar la suscripción
Es una funcionalidad distinta a onSessionStart y onSessionEnd de los Hooks de sesión

Consulta la información más reciente en el repositorio de GitHub.