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

# Sesiones, host y entorno

> Usa ServerRpc en Laravel Copilot SDK para gestionar sesiones, el host, el entorno de ejecución, las tareas en la nube y la clasificación de trayectorias.

## Sesiones, host y entorno

Ámbito: ServerRpc (operaciones de todo el servidor vinculadas al Client)

Para una visión general de RPC y la lista de todas las páginas de RPC, consulta [RPC](https://kawax.biz/es/packages/laravel-copilot-sdk/rpc.md).

```php theme={null}
use Revolution\Copilot\Enums\EventsReadDirection;
use Revolution\Copilot\Types\Rpc\HooksDiscoverRequest;
use Revolution\Copilot\Types\Rpc\SessionsListRequest;
use Revolution\Copilot\Types\Rpc\SessionsPruneOldRequest;
use Revolution\Copilot\Types\Rpc\SessionsReadPersistedEventsRequest;
use Revolution\Copilot\Types\Rpc\SessionsOpenCreateRequest;
use Revolution\Copilot\Enums\SessionsOpenStatus;
use Revolution\Copilot\Types\SessionConfig;
use Revolution\Copilot\Types\SessionListFilter;

// Lista de slash commands integrados disponibles en las sesiones nuevas (experimental)
Copilot::client()->rpc()->commands()->list();

// Exploración de hooks antes de iniciar la sesión (experimental)
Copilot::client()->rpc()->hooks()->discover(new HooksDiscoverRequest(
    projectPaths: ['/path/to/project'],
));

// Soporte de sandbox del host (experimental)
$hostSupport = Copilot::client()->rpc()->sandbox()->getHostSupport();
// $hostSupport->supported, $hostSupport->reason, $hostSupport->capabilities

// sessions (experimental: consulta y gestión de sesiones persistidas)

// sessions.open selecciona con `kind` entre create, resume, resumeLast, attach, conexión remote/cloud o handoff.
$opened = $sessions->open(new SessionsOpenCreateRequest(
    options: new SessionConfig(sessionId: 'new-session', model: 'gpt-5'),
));
if ($opened->status === SessionsOpenStatus::Created) {
    echo $opened->sessionId;
}
// También se puede pasar un array. Al reanudar, indica sessionId en el nivel superior de la variante.
$resumed = $sessions->open(['kind' => 'resume', 'sessionId' => 'existing-session']);
// Devuelve SessionsOpenResult. Si el estado es not_found, no hay sessionId.
// sessionApi, onTaskCreated, onProgress y onConfirm son solo del proceso y no se incluyen en el payload enviado.

$listed = $sessions->list(new SessionsListRequest(
    source: 'local',
    metadataLimit: 50,
    filter: new SessionListFilter(cwd: '/path/to/project'),
));
// Distingue sesiones local / remote con isRemote de cada SessionMetadata
foreach ($listed->sessions as $session) {
    echo $session->sessionId;
}

$sessions->findByTaskId(['taskId' => 'task-id']);
$sessions->findByPrefix(['prefix' => 'session-id-prefix']);
$sessions->getLastForContext(['context' => ['cwd' => '/path/to/project']]);
// Comprueba si existe un log de eventos local sin abrir la sesión (un log vacío también cuenta)
$hasEvents = Copilot::client()->rpc()->sessions()->hasEvents(['sessionId' => 'session-id']);
// $hasEvents->exists es false cuando la sesión tiene metadatos pero no log
$sizes = $sessions->getSizes(); // $sizes->sizes asocia el ID de sesión => número de bytes
$inUse = $sessions->checkInUse(['sessionIds' => ['session-id']]);
$deleted = $sessions->bulkDelete(['sessionIds' => ['session-id']]);

// Cerrar una sesión activa (no elimina el historial)
$sessions->close(['sessionId' => 'session-id']);

// Guardar en disco los eventos pendientes
$sessions->save(['sessionId' => 'session-id']);

// Liberar explícitamente el in-use lock de las sesiones que mantiene este proceso
$sessions->releaseLock(['sessionId' => 'session-id']);

// reloadPluginHooks recarga los user/plugin hooks.
// Antes de confirmar folder trust, los repo hooks se aplazan y se cargan después de confirmar la confianza.
$sessions->reloadPluginHooks([
    'sessionId' => 'session-id',
    'deferRepoHooks' => true,
]);
$loadedHooks = $sessions->loadDeferredRepoHooks(['sessionId' => 'session-id']);
// $loadedHooks->startupPrompts y $loadedHooks->hookCount

// Reemplazar la configuración de plugins adicionales a nivel de Manager (array vacío para borrarla)
$sessions->setAdditionalPlugins(['plugins' => []]);

// Completar summary / context de los local session metadata
$enriched = $sessions->enrichMetadata([
    'sessions' => [[
        'sessionId' => 'session-id',
        'startTime' => '2026-10-17T09:00:00Z',
        'modifiedTime' => '2026-10-17T09:00:00Z',
        'isRemote' => false,
    ]],
]);

// close() realiza el shutdown, guarda los eventos y libera el bloqueo, descartando la active session,
// pero no elimina el persisted history. $session->disconnect() libera con session.detach la conexión
// con este SDK y los in-memory resources del lado PHP. Para eliminar datos persistidos usa bulkDelete().

// Paginar eventos persistidos con cursor sin abrir la sesión
$cursor = null;
do {
    $page = $sessions->readPersistedEvents(new SessionsReadPersistedEventsRequest(
        sessionId: 'session-id',
        cursor: $cursor,
        max: 100,
        direction: EventsReadDirection::FORWARD,
    ));

    foreach ($page->events as $event) {
        // Procesar el evento
    }

    $cursor = $page->cursor;
} while ($page->hasMore);

// dryRun no elimina y devuelve candidatos y estimaciones. Para eliminar de verdad, indica dryRun: false
$preview = $sessions->pruneOld(new SessionsPruneOldRequest(
    olderThanDays: 30,
    dryRun: true,
));

// sessions.fork
$sessions->fork(new SessionsForkRequest(
    sessionId: 'source-session-id',
    toEventId: 'evt-boundary', // Opcional: incluir solo los eventos anteriores a este ID
));

// environments (experimental: buscar, obtener y eliminar entornos de GitHub Mission Control)
$result = Copilot::client()->rpc()->environments()->list(['kind' => 'user-local']);
// $result->environments es un array de GitHubEnvironment
$env = Copilot::client()->rpc()->environments()->get(['environmentId' => 'env-id']);
Copilot::client()->rpc()->environments()->delete(['environmentId' => 'env-id']);
```

## Ciclo de vida de Runtime y Host (experimental)

`host.unpublishSession()` retira la application publication de un host en ejecución del que se es propietario. Retirar la publicación no elimina ni detiene el historial de la sesión original, el worktree ni el trabajo en curso. Si ya no estaba publicada, `unpublished` es `false`, y las publication que no son application producen un error.

```php theme={null}
$result = Copilot::client()->rpc()->host()->unpublishSession([
    'hostId' => 'host-1',
    'sessionId' => 'session-1',
]);
// $result->unpublished
```

`host.dispose()` destruye el listener del host indicando `hostId`.

```php theme={null}
Copilot::client()->rpc()->host()->dispose(['hostId' => 'host-1']);
```

`host.setSessionCreationPolicy()` cambia si un host en ejecución acepta nuevas sesiones remotas. El cambio no desconecta a los clientes existentes y solo se aplica a las admisiones posteriores.

```php theme={null}
use Revolution\Copilot\Types\Rpc\HostSetSessionCreationPolicyRequest;

Copilot::client()->rpc()->host()->setSessionCreationPolicy(
    new HostSetSessionCreationPolicyRequest(
        hostId: 'host-1',
        allowCreatingNewSessions: false,
    ),
);
```

En los runtimes stdio arrancados por el SDK, `Client::stop()` llama a `runtime.shutdown` después de desconectar las sesiones y antes de cerrar la conexión JSON-RPC y el proceso. La desconexión de sesiones (`session.detach`) comparte un único plazo total de 10 segundos para todas las sesiones. Una desconexión que supera el plazo se incluye como error en el valor de retorno y el proceso de parada continúa. También espera hasta 10 segundos a que termine la limpieza del runtime y, si falla, incluye el error en el valor de retorno y continúa con el resto del proceso de parada. En conexiones a runtimes externos como `cli_url`, no llama a esta RPC para no terminar un runtime compartido.

Si la CLI no puede identificar la petición correspondiente y devuelve un error JSON-RPC con `id: null`, todas las peticiones en curso fallan con una `JsonRpcException`. La excepción incluye un mensaje de diagnóstico sin los valores entre comillas y con la longitud limitada. La conexión se mantiene abierta. Como es posible que la CLI ya haya procesado la petición, no reintentes automáticamente sin confirmar que es seguro hacerlo. El SDK rechaza antes de enviarlas las peticiones salientes con más de 127 niveles de anidamiento, que la CLI no puede leer, y sustituye por un error JSON-RPC las respuestas de handlers con un anidamiento demasiado profundo.

## cloudTasks (experimental: tareas del agente en la nube)

`cloudTasks()` crea, elimina y obtiene tareas del agente de codificación en la nube, recupera los logs y replays de sesión, cambia el estado de uso compartido y resuelve la sesión que se debe abrir a partir de un ID de tarea. Cada método acepta el tipo Params correspondiente o un array y devuelve un DTO tipado. Cuando `ok` del resultado de creación es `false`, consulta `reason` y `message` para ver por qué el servicio rechazó la solicitud, y `statusCode`, `errorMessage` y `errorPayloadJson` para la información de fallo de la solicitud HTTP realizada.

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\Rpc\CloudTasksCreateParams;

$result = Copilot::client()->rpc()->cloudTasks()->create(
    new CloudTasksCreateParams(
        authInfo: $authInfo,
        integrationId: 'my-app',
        repositoryOwner: 'octo',
        repositoryName: 'example',
    ),
);

if (! $result->ok) {
    // $result->reason y $result->message describen una petición rechazada.
    // $result->statusCode y $result->errorMessage describen una petición HTTP intentada.
}
```

## taskAnalytics (experimental: clasificar trayectorias grabadas)

`taskAnalytics()->classifyTrajectory()` clasifica eventos de Copilot grabados o datos ATIF sin crear una sesión. Las herramientas archivadas no se ejecutan y no se añade nada al historial de conversación ni a la telemetría de clasificación. Pasa `events` en su orden original. También puedes indicar `classifiers`, `maxConcurrentRequests`, `judge` y `previousResult`. Con `validateOnly: true`, el runtime omite la inferencia y devuelve solo el resultado de la validación local.

Una clasificación normal envía el contenido de los eventos al procesamiento del modelo, que usa tus credenciales de GitHub CAPI. No hay redacción automática ni protección frente a prompt injection. Aprueba la subida, verifica el origen del archivo y elimina antes los datos sensibles. Los resultados de clasificación no son hechos fiables, así que no los uses para decisiones de autorización o de seguridad.

```php theme={null}
$result = Copilot::client()->rpc()->taskAnalytics()->classifyTrajectory([
    'events' => $events,
    'validateOnly' => true,
]);
```

Para abrir una URL de autenticación en el navegador, usa `runtime()->openBrowser()`.

```php theme={null}
use Revolution\Copilot\Types\Rpc\RuntimeOpenBrowserRequest;

Copilot::client()->rpc()->runtime()->openBrowser(new RuntimeOpenBrowserRequest(
    url: 'https://example.com/authorize',
));
```

Para obtener el aviso de concesión de rutas del sandbox, usa `sandbox()->getPathGrantWarning()`.

```php theme={null}
use Revolution\Copilot\Types\Rpc\SandboxPathGrantWarningParams;

$warning = Copilot::client()->rpc()->sandbox()->getPathGrantWarning(new SandboxPathGrantWarningParams(
    resolvedPath: '/workspace/project',
    readOnly: false,
));
```

## sessions connect y Remote Control (modo TCP)

Para conectar el servidor del CLI a una sesión remota existente, usa `sessions()->connect()`. Pasa el `sessionId` remoto y el resultado contendrá el `sessionId` del lado del SDK y los metadatos de la sesión remota.

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\Rpc\ConnectRemoteSessionParams;

$client = Copilot::useTcp(url: 'tcp://127.0.0.1:12345')->client();

$connected = $client->rpc()->sessions()->connect(
    new ConnectRemoteSessionParams(sessionId: 'remote-session-id'),
);

echo $connected->sessionId;
// $connected->metadata - Objeto ConnectedRemoteSessionMetadata
```

En modo TCP, también puedes usar `sessions()` para gestionar un único Remote Control para todo el runtime. A diferencia de `remote()->enable()`, que actúa por sesión, estos métodos te permiten iniciar, detener y transferir Remote Control entre sesiones, y leer su estado actual.

```php theme={null}
use Revolution\Copilot\Types\Rpc\RemoteControlConfig;
use Revolution\Copilot\Types\Rpc\SessionsStartRemoteControlRequest;

$result = $client->rpc()->sessions()->startRemoteControl(
    new SessionsStartRemoteControlRequest(
        sessionId: $sessionId,
        config: new RemoteControlConfig(
            remote: true,
            steerable: true,
            explicit: true,
            silent: false,
        ),
    ),
);

if ($result->status->frontendUrl !== null) {
    echo 'Remote URL: '.$result->status->frontendUrl.PHP_EOL;
}

$status = $client->rpc()->sessions()->getRemoteControlStatus();
// El estado es off / connecting / active / error. Cuando es active, también están disponibles frontendUrl e isSteerable

$client->rpc()->sessions()->setRemoteControlSteering(['enabled' => true]);
$client->rpc()->sessions()->transferRemoteControl([
    'toSessionId' => $nextSessionId,
    'expectedFromSessionId' => $sessionId,
]);
$client->rpc()->sessions()->stopRemoteControl([
    'expectedSessionId' => $nextSessionId,
]);
```

Para más detalles, consulta [Sesiones remotas](https://kawax.biz/es/packages/laravel-copilot-sdk/remote-sessions.md).


## Related topics

- [Resumen de ServerRpc](https://kawax.biz/es/packages/laravel-copilot-sdk/rpc/server-overview.md)
- [RPC (Remote Procedure Call)](https://kawax.biz/es/packages/laravel-copilot-sdk/rpc.md)
- [AHP Host](https://kawax.biz/es/packages/laravel-copilot-sdk/ahp.md)
- [SessionConfig](https://kawax.biz/es/packages/laravel-copilot-sdk/session-config.md)
- [Información de la sesión y gestión de sesiones locales](https://kawax.biz/es/packages/laravel-copilot-sdk/rpc/session-info.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.