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

# AHP Host

> Explica cómo iniciar un host de Agent Host Protocol (AHP) con Laravel Copilot SDK y configurar la autenticación, la política de creación de sesiones y las sesiones gestionadas por la aplicación.

## AHP Host

Agent Host Protocol (AHP) te permite iniciar un listener gestionado por el runtime de Copilot y aceptar clientes remotos mediante WebSocket o Mission Control de GitHub. Un host AHP pertenece a su conexión `Client`. Detener el listener con `Client::stop()` o con el `dispose()` del host no elimina las sesiones que ha utilizado el host.

## Iniciar un host

Pasa al menos uno de `localServer` o `githubEnvironment`. También es obligatorio un modo de autenticación. Para permitir el acceso anónimo, debes pasar `none` de forma explícita.

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

$client = Copilot::client();

$host = $client->startAhpHost(
    authentication: AhpHostAuthentication::github(),
    localServer: [],
    allowCreatingNewSessions: true,
    workspace: '/workspace/project',
);

echo $host->url;
```

`localServer: []` usa una dirección de loopback y un puerto libre. `githubEnvironment` requiere autenticación `github`. Trata el `token` devuelto por el host como un secreto de conexión.

`workspace` es el directorio de trabajo que utiliza el host AHP. El runtime de Copilot resuelve esta ruta en el host donde se ejecuta el runtime, por lo que puede diferir de la ruta dentro de tu aplicación Laravel. Si lo omites, el SDK no incluye `workspace` en la llamada RPC y el runtime mantiene su comportamiento existente.

## Modos de autenticación

* `AhpHostAuthentication::github()` autentica con una cuenta de GitHub. Puedes combinarlo con `githubEnvironment`.
* `AhpHostAuthentication::none()` deshabilita la autenticación de forma explícita.
* `AhpHostAuthentication::custom()` valida los tokens de admisión con la lógica propia de tu aplicación. Requiere una identidad de propietario estable y un callback de validación.

El callback de autenticación personalizada recibe un `HostValidateAuthenticationRequest` que contiene el token de admisión descifrado y un `CancellationToken` que indica la cancelación. Si la validación es correcta, devuelve la identidad y un `expiresAt` futuro en formato RFC3339. Para rechazar el token, devuelve `null`. La identidad debe coincidir exactamente con `requireIdentity`.

```php theme={null}
use Revolution\Copilot\Types\AhpHostAuthentication;
use Revolution\Copilot\Types\Rpc\HostAuthenticationResult;
use Revolution\Copilot\Types\Rpc\HostValidateAuthenticationRequest;
use Revolution\Copilot\Support\CancellationToken;

$authentication = AhpHostAuthentication::custom(
    requireIdentity: 'team-123',
    authenticate: function (
        HostValidateAuthenticationRequest $request,
        CancellationToken $signal,
    ): ?HostAuthenticationResult {
        if ($signal->isCancellationRequested()) {
            return null;
        }

        $identity = validateAdmissionToken($request->token);

        if ($identity !== 'team-123') {
            return null;
        }

        return new HostAuthenticationResult(
            identity: $identity,
            expiresAt: '2099-01-01T00:00:00Z',
        );
    },
);

$host = $client->startAhpHost(
    authentication: $authentication,
    localServer: [],
);
```

El token de admisión es una credencial distinta del token de GitHub o del token del proveedor que se usa para la inferencia. No lo guardes en logs ni en la configuración de la sesión. La señal del callback se cancela cuando el host recibe `host.authenticationCancelled` o se apaga. Si el callback llama a servicios externos, registra el manejo de la cancelación con `onCancellationRequested()`.

## Política de creación de sesiones

`allowCreatingNewSessions` establece la política inicial para que los clientes remotos creen nuevas sesiones. Si se omite, se deniega la creación de sesiones remotas. La política no se aplica a las sesiones creadas por la aplicación propietaria, a las sesiones publicadas ni a las conexiones existentes.

Para cambiar la política mientras el host está en ejecución, llama a `setSessionCreationPolicy()` del host. La nueva política se aplica a las solicitudes que llegan después de que se confirme el cambio. Las solicitudes de creación ya aceptadas pueden completarse. Los clientes conectados no se desconectan.

```php theme={null}
$host->setSessionCreationPolicy(allowCreatingNewSessions: false);
```

Si usas RPC directamente, llama a `$client->rpc()->host()->setSessionCreationPolicy()` y pasa un `HostSetSessionCreationPolicyRequest` con el `hostId` y la nueva configuración.

## Sesiones gestionadas por la aplicación

Pasa los callbacks `createSession` y `resumeSession` para delegar las solicitudes del host AHP al `Client` de tu aplicación. Cada callback recibe un `HostMaterializeSessionRequest` que contiene el `HostSessionAuthentication` verificado por el runtime y la `config` proporcionada por el host, además de un `CancellationToken` para la cancelación cooperativa. Devuelve una sesión creada o reanudada con el mismo `Client`.

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Support\CancellationToken;
use Revolution\Copilot\Types\Rpc\HostMaterializeSessionRequest;
use Revolution\Copilot\Support\PermissionHandler;

$host = $client->startAhpHost(
    authentication: $authentication,
    localServer: [],
    createSession: function (
        HostMaterializeSessionRequest $request,
        CancellationToken $signal,
    ) use ($client): CopilotSession {
        return $client->createSession([
            ...($request->config ?? []),
            'onPermissionRequest' => PermissionHandler::approveAll(),
        ]);
    },
    resumeSession: function (
        HostMaterializeSessionRequest $request,
        CancellationToken $signal,
    ) use ($client): CopilotSession {
        $sessionId = $request->config['sessionId'];

        return $client->resumeSession($sessionId, [
            'onPermissionRequest' => PermissionHandler::approveAll(),
        ]);
    },
    onSessionReleased: function (CopilotSession $session): void {
        // Limpieza en la aplicación cuando termina la participación en AHP
    },
);
```

`onSessionReleased` recibe la sesión cuya participación ha terminado. El SDK no desconecta ni destruye la sesión. `HostMaterializeSessionRequest::$authentication` es una identidad de confianza verificada por el host, no una entrada del cliente. Aun así, realiza dentro del callback cualquier autorización de tenant o de usuario que necesites.

## Catálogo de sesiones y apagado

```php theme={null}
$host->publishSession('session-id');
$sessions = $host->listSessions();
$host->unpublishSession('session-id');
$host->dispose();
```

Despublicar una sesión la elimina del catálogo de AHP. No elimina el historial local ni detiene el trabajo en curso. `dispose()` detiene el listener, pero no elimina las sesiones relacionadas.

## Documentación relacionada

* [RPC](https://kawax.biz/es/packages/laravel-copilot-sdk/rpc.md)
* [Remote Sessions](https://kawax.biz/es/packages/laravel-copilot-sdk/remote-sessions.md)


## Related topics

- [RPC (Remote Procedure Call)](https://kawax.biz/es/packages/laravel-copilot-sdk/rpc.md)
- [Restablecimiento de contraseña](https://kawax.biz/es/passwords.md)
- [Laravel Sail](https://kawax.biz/es/sail.md)
- [Laravel Reverb](https://kawax.biz/es/reverb.md)
- [Caché](https://kawax.biz/es/cache.md)


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