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

> Descrive come avviare un host Agent Host Protocol (AHP) con Laravel Copilot SDK e configurare l'autenticazione, la policy di creazione delle sessioni e le sessioni gestite dall'applicazione.

## AHP Host

L'Agent Host Protocol (AHP) ti permette di avviare un listener gestito dal runtime di Copilot e di accettare client remoti tramite WebSocket o Mission Control di GitHub. Un host AHP appartiene alla sua connessione `Client`. Fermare il listener con `Client::stop()` o con il `dispose()` dell'host non elimina le sessioni utilizzate dall'host.

## Avvio di un host

Passa almeno uno tra `localServer` e `githubEnvironment`. È inoltre richiesta una modalità di autenticazione. Per consentire l'accesso anonimo, devi passare esplicitamente `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: []` utilizza un indirizzo di loopback e una porta libera. `githubEnvironment` richiede l'autenticazione `github`. Tratta il `token` restituito dall'host come un segreto di connessione.

`workspace` è la directory di lavoro utilizzata dall'host AHP. Il runtime di Copilot risolve questo percorso sull'host in cui è in esecuzione il runtime, quindi può differire dal percorso all'interno della tua applicazione Laravel. Se lo ometti, l'SDK non include `workspace` nella chiamata RPC e il runtime mantiene il suo comportamento esistente.

## Modalità di autenticazione

* `AhpHostAuthentication::github()` esegue l'autenticazione con un account GitHub. Puoi combinarla con `githubEnvironment`.
* `AhpHostAuthentication::none()` disabilita esplicitamente l'autenticazione.
* `AhpHostAuthentication::custom()` convalida i token di ammissione con la logica della tua applicazione. Richiede un'identità del proprietario stabile e una callback di convalida.

La callback di autenticazione personalizzata riceve una `HostValidateAuthenticationRequest` contenente il token di ammissione decifrato e un `CancellationToken` che segnala l'annullamento. In caso di successo, restituisci l'identità e un `expiresAt` futuro in formato RFC3339. Per rifiutare il token, restituisci `null`. L'identità deve corrispondere esattamente a `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: [],
);
```

Il token di ammissione è una credenziale distinta dal token GitHub o dal token del provider utilizzato per l'inferenza. Non salvarlo nei log o nella configurazione della sessione. Il signal della callback viene annullato quando l'host riceve `host.authenticationCancelled` o viene arrestato. Se la callback chiama servizi esterni, registra la gestione dell'interruzione con `onCancellationRequested()`.

## Policy di creazione delle sessioni

`allowCreatingNewSessions` imposta la policy iniziale per la creazione di nuove sessioni da parte dei client remoti. Se omesso, la creazione di sessioni remote viene negata. La policy non si applica alle sessioni create dall'applicazione proprietaria, alle sessioni pubblicate o alle connessioni esistenti.

Per modificare la policy mentre l'host è in esecuzione, chiama `setSessionCreationPolicy()` dell'host. La nuova policy si applica alle richieste che arrivano dopo la conferma della modifica. Le richieste di creazione già accettate possono essere completate. I client connessi non vengono disconnessi.

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

Se usi direttamente l'RPC, chiama `$client->rpc()->host()->setSessionCreationPolicy()` e passa una `HostSetSessionCreationPolicyRequest` con l'`hostId` e la nuova impostazione.

## Sessioni gestite dall'applicazione

Passa le callback `createSession` e `resumeSession` per inoltrare le richieste dall'host AHP al `Client` della tua applicazione. Ogni callback riceve una `HostMaterializeSessionRequest` contenente la `HostSessionAuthentication` verificata dal runtime e la `config` fornita dall'host, oltre a un `CancellationToken` per l'annullamento cooperativo. Restituisci una sessione creata o ripresa con lo stesso `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 {
        // Pulizia lato applicazione al termine della partecipazione AHP
    },
);
```

`onSessionReleased` riceve la sessione la cui partecipazione è terminata. L'SDK non disconnette né distrugge la sessione. `HostMaterializeSessionRequest::$authentication` è un'identità attendibile verificata dall'host, non un input del client. Esegui comunque all'interno della callback qualsiasi autorizzazione per tenant o utente di cui hai bisogno.

## Catalogo delle sessioni e arresto

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

Annullare la pubblicazione rimuove la sessione dal catalogo AHP. Non elimina la cronologia locale né interrompe il lavoro in corso. `dispose()` ferma il listener ma non elimina le sessioni correlate.

## Riferimenti

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


## Related topics

- [RPC (Remote Procedure Call)](https://kawax.biz/it/packages/laravel-copilot-sdk/rpc.md)
- [Reset della password](https://kawax.biz/it/passwords.md)
- [Laravel Reverb](https://kawax.biz/it/reverb.md)
- [Laravel Sail](https://kawax.biz/it/sail.md)
- [Cache](https://kawax.biz/it/cache.md)


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