> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos del ciclo de vida de sesión

> Explica cómo suscribirse a los eventos de creación, actualización, eliminación y cambio de estado (foreground/background) de las sesiones de Laravel Copilot SDK.

## 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 |

```php theme={null}
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()`.

```php theme={null}
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.

```php theme={null}
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).

```php theme={null}
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

```php theme={null}
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

```php theme={null}
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.

```php theme={null}
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.

```bash theme={null}
# Arranca Copilot CLI en modo TUI+servidor
copilot --ui-server --port 8080
```

```php theme={null}
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](/es/packages/laravel-copilot-sdk/hooks)

<Info>
  Consulta la información más reciente en el [repositorio de GitHub](https://github.com/invokable/laravel-copilot-sdk).
</Info>


## Related topics

- [Ciclo de vida de la solicitud](/es/lifecycle.md)
- [Introducción a Eloquent](/es/eloquent.md)
- [Observers de Eloquent y eventos del modelo](/es/advanced/eloquent-observers.md)
- [⚡Introducción a Livewire 4 — Crear UIs reactivas sin JavaScript](/es/blog/livewire-introduction.md)
- [Guía de desarrollo de apps con integración de la Engine API - VOICEVOX for Laravel](/es/packages/laravel-voicevox/app-guide.md)