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

> Démarrez un hôte Agent Host Protocol (AHP) avec Laravel Copilot SDK et configurez l'authentification, la politique de création de sessions et les sessions gérées par l'application.

## AHP Host

L'Agent Host Protocol (AHP) permet de démarrer un listener géré par le runtime Copilot et d'accepter des clients distants via WebSocket ou Mission Control de GitHub. Un hôte AHP appartient à sa connexion `Client`. Arrêter le listener avec `Client::stop()` ou avec la méthode `dispose()` de l'hôte ne supprime pas les sessions utilisées par l'hôte.

## Démarrer un hôte

Passez au moins l'un des paramètres `localServer` ou `githubEnvironment`. Un mode d'authentification est également requis. Pour autoriser l'accès anonyme, vous devez passer explicitement `none`.

```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: []` utilise une adresse de loopback et un port libre. `githubEnvironment` nécessite l'authentification `github`. Traitez le `token` renvoyé par l'hôte comme un secret de connexion.

`workspace` est le répertoire de travail utilisé par l'hôte AHP. Le runtime Copilot résout ce chemin sur l'hôte où il s'exécute ; il peut donc différer du chemin au sein de votre application Laravel. Si vous l'omettez, le SDK n'inclut pas `workspace` dans l'appel RPC et le runtime conserve son comportement existant.

## Modes d'authentification

* `AhpHostAuthentication::github()` s'authentifie avec un compte GitHub. Vous pouvez le combiner avec `githubEnvironment`.
* `AhpHostAuthentication::none()` désactive explicitement l'authentification.
* `AhpHostAuthentication::custom()` valide les tokens d'admission avec la logique propre à votre application. Il nécessite une identité de propriétaire stable et un callback de validation.

Le callback d'authentification personnalisée reçoit une `HostValidateAuthenticationRequest` contenant le token d'admission déchiffré, ainsi qu'un `CancellationToken` signalant l'annulation. En cas de succès, renvoyez l'identité et une date `expiresAt` future au format RFC3339. Pour rejeter le token, renvoyez `null`. L'identité doit correspondre exactement à `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: [],
);
```

Le token d'admission est un identifiant distinct du token GitHub ou du token de fournisseur utilisé pour l'inférence. Ne le stockez ni dans les logs ni dans la configuration de session. Le signal du callback est annulé lorsque l'hôte reçoit `host.authenticationCancelled` ou s'arrête. Si le callback appelle des services externes, enregistrez la gestion de l'interruption avec `onCancellationRequested()`.

## Politique de création de sessions

`allowCreatingNewSessions` définit la politique initiale de création de nouvelles sessions par les clients distants. S'il est omis, la création de sessions à distance est refusée. Cette politique ne s'applique pas aux sessions créées par l'application propriétaire, aux sessions publiées ni aux connexions existantes.

Pour modifier la politique pendant que l'hôte s'exécute, appelez la méthode `setSessionCreationPolicy()` de l'hôte. La nouvelle politique s'applique aux requêtes reçues après la confirmation du changement. Les requêtes de création déjà acceptées peuvent se terminer. Les clients connectés ne sont pas déconnectés.

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

Si vous utilisez directement le RPC, appelez `$client->rpc()->host()->setSessionCreationPolicy()` en passant une `HostSetSessionCreationPolicyRequest` avec le `hostId` et le nouveau paramètre.

## Sessions gérées par l'application

Passez les callbacks `createSession` et `resumeSession` pour transmettre les requêtes de l'hôte AHP au `Client` de votre application. Chaque callback reçoit une `HostMaterializeSessionRequest` contenant la `HostSessionAuthentication` vérifiée par le runtime et la `config` fournie par l'hôte, ainsi qu'un `CancellationToken` pour l'annulation coopérative. Renvoyez une session créée ou reprise avec le même `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 {
        // Nettoyage côté application lorsque la participation AHP prend fin
    },
);
```

`onSessionReleased` reçoit la session dont la participation a pris fin. Le SDK ne déconnecte ni ne détruit la session. `HostMaterializeSessionRequest::$authentication` est une identité de confiance vérifiée par l'hôte, et non une entrée du client. Effectuez néanmoins dans le callback toute vérification d'autorisation de tenant ou d'utilisateur nécessaire.

## Catalogue de sessions et arrêt

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

Annuler la publication retire la session du catalogue AHP. Cela ne supprime pas l'historique local et n'arrête pas le travail en cours. `dispose()` arrête le listener mais ne supprime pas les sessions associées.

## Documentation associée

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


## Related topics

- [RPC (Remote Procedure Call)](https://kawax.biz/fr/packages/laravel-copilot-sdk/rpc.md)
- [Réinitialisation du mot de passe](https://kawax.biz/fr/passwords.md)
- [Laravel Reverb](https://kawax.biz/fr/reverb.md)
- [Laravel Sail](https://kawax.biz/fr/sail.md)
- [Cache](https://kawax.biz/fr/cache.md)


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