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

> Laravel Copilot SDK에서 Agent Host Protocol(AHP) 호스트를 시작하고, 인증, 세션 생성 정책, 애플리케이션 소유 세션을 구성하는 방법을 설명합니다.

## AHP Host

Agent Host Protocol(AHP)을 사용하면 Copilot 런타임이 관리하는 리스너를 시작하고, WebSocket 또는 GitHub의 Mission Control을 통해 원격 클라이언트를 받아들일 수 있습니다. AHP 호스트는 해당 `Client` 연결이 소유합니다. `Client::stop()`이나 호스트의 `dispose()`로 리스너를 중지해도 호스트가 사용한 세션은 삭제되지 않습니다.

## 호스트 시작

`localServer` 또는 `githubEnvironment` 중 적어도 하나를 전달합니다. 인증 모드도 필수입니다. 익명 접근을 허용하려면 `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: []`는 루프백 주소와 비어 있는 포트를 사용합니다. `githubEnvironment`에는 `github` 인증이 필요합니다. 호스트가 반환하는 `token`은 연결용 시크릿으로 취급하세요.

`workspace`는 AHP 호스트가 사용하는 작업 디렉터리입니다. Copilot 런타임은 이 경로를 런타임이 실행되는 호스트에서 해석하므로, Laravel 애플리케이션 내부의 경로와 다를 수 있습니다. 생략하면 SDK는 RPC 호출에 `workspace`를 포함하지 않으며, 런타임은 기존 동작을 유지합니다.

## 인증 모드

* `AhpHostAuthentication::github()`는 GitHub 계정으로 인증합니다. `githubEnvironment`와 함께 사용할 수 있습니다.
* `AhpHostAuthentication::none()`은 인증을 명시적으로 비활성화합니다.
* `AhpHostAuthentication::custom()`은 애플리케이션 자체 로직으로 입장 토큰(admission token)을 검증합니다. 고정된 소유자 ID와 검증 콜백이 필요합니다.

커스텀 인증 콜백은 복호화된 입장 토큰을 담은 `HostValidateAuthenticationRequest`와 취소를 알리는 `CancellationToken`을 받습니다. 성공 시에는 ID와 RFC3339 형식의 미래 시각 `expiresAt`을 반환합니다. 토큰을 거부하려면 `null`을 반환합니다. ID는 `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: [],
);
```

입장 토큰은 추론에 사용하는 GitHub 토큰이나 프로바이더 토큰과는 별개의 자격 증명입니다. 로그나 세션 설정에 저장하지 마세요. 호스트가 `host.authenticationCancelled`를 받거나 종료되면 콜백의 signal이 취소됩니다. 콜백에서 외부 서비스를 호출하는 경우 `onCancellationRequested()`로 중단 처리를 등록하세요.

## 세션 생성 정책

`allowCreatingNewSessions`는 원격 클라이언트가 새 세션을 생성하는 것에 대한 초기 정책을 설정합니다. 생략하면 원격 세션 생성이 거부됩니다. 이 정책은 소유 애플리케이션이 생성한 세션, 공개된 세션, 기존 연결에는 적용되지 않습니다.

호스트 실행 중에 정책을 변경하려면 호스트의 `setSessionCreationPolicy()`를 호출합니다. 새 정책은 변경이 확인된 이후에 도착한 요청에 적용됩니다. 이미 수락된 생성 요청은 완료될 수 있습니다. 연결된 클라이언트의 연결은 끊기지 않습니다.

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

RPC를 직접 사용하는 경우 `$client->rpc()->host()->setSessionCreationPolicy()`를 호출하고, `hostId`와 새 설정을 담은 `HostSetSessionCreationPolicyRequest`를 전달합니다.

## 애플리케이션 소유 세션

`createSession`과 `resumeSession` 콜백을 전달하면 AHP 호스트의 요청을 애플리케이션의 `Client`로 넘길 수 있습니다. 각 콜백은 런타임이 검증한 `HostSessionAuthentication`과 호스트가 제공한 `config`를 담은 `HostMaterializeSessionRequest`, 그리고 협조적 취소를 위한 `CancellationToken`을 받습니다. 같은 `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 {
        // AHP 참여가 끝났을 때 애플리케이션 측 정리 처리
    },
);
```

`onSessionReleased`는 참여가 끝난 세션을 받습니다. SDK는 세션의 연결을 끊거나 파기하지 않습니다. `HostMaterializeSessionRequest::$authentication`은 클라이언트 입력이 아니라 호스트가 검증한 신뢰할 수 있는 ID입니다. 그래도 필요한 테넌트 또는 사용자 인가는 콜백 내에서 수행하세요.

## 세션 카탈로그와 종료

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

공개를 해제하면 세션이 AHP 카탈로그에서 제거됩니다. 로컬 이력을 삭제하거나 실행 중인 작업을 중지하지는 않습니다. `dispose()`는 리스너를 중지하지만 관련 세션은 삭제하지 않습니다.

## 관련 문서

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


## Related topics

- [RPC(Remote Procedure Call)](https://kawax.biz/ko/packages/laravel-copilot-sdk/rpc.md)
- [비밀번호 재설정](https://kawax.biz/ko/passwords.md)
- [Laravel Sail](https://kawax.biz/ko/sail.md)
- [캐시](https://kawax.biz/ko/cache.md)
- [Laravel Reverb](https://kawax.biz/ko/reverb.md)


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