> ## 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）主機，並設定驗證、Session 建立政策，以及由應用程式擁有的 Session。

## AHP Host

Agent Host Protocol（AHP）可讓您啟動由 Copilot 執行環境管理的監聽器，並透過 WebSocket 或 GitHub 的 Mission Control 接受遠端用戶端連線。AHP 主機由其 `Client` 連線所擁有。透過 `Client::stop()` 或主機的 `dispose()` 停止監聽器時，並不會刪除主機所使用的 Session。

## 啟動主機

請至少傳入 `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()` 使用您應用程式自己的邏輯驗證准入 Token。需要穩定的擁有者身分與驗證回呼。

自訂驗證回呼會收到包含已解密准入 Token 的 `HostValidateAuthenticationRequest`，以及用來通知取消的 `CancellationToken`。驗證成功時，請回傳身分與 RFC3339 格式的未來 `expiresAt`。若要拒絕 Token，請回傳 `null`。身分必須與 `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: [],
);
```

准入 Token 是與用於推論的 GitHub Token 或供應商 Token 不同的憑證。請勿將其儲存在日誌或 Session 設定中。當主機收到 `host.authenticationCancelled` 或關閉時，回呼的 signal 會被取消。若回呼會呼叫外部服務，請透過 `onCancellationRequested()` 註冊中止處理。

## Session 建立政策

`allowCreatingNewSessions` 用來設定遠端用戶端建立新 Session 的初始政策。省略時，會拒絕遠端建立 Session。此政策不適用於擁有者應用程式建立的 Session、已發佈的 Session 或既有的連線。

若要在主機執行期間變更政策，請呼叫主機的 `setSessionCreationPolicy()`。新政策會套用至變更被確認後才抵達的請求。已被接受的建立請求仍可完成。已連線的用戶端不會被中斷連線。

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

直接使用 RPC 時，請呼叫 `$client->rpc()->host()->setSessionCreationPolicy()`，並傳入包含 `hostId` 與新設定的 `HostSetSessionCreationPolicyRequest`。

## 由應用程式擁有的 Session

傳入 `createSession` 與 `resumeSession` 回呼，即可將來自 AHP 主機的請求交給您應用程式的 `Client` 處理。每個回呼都會收到包含經執行環境驗證的 `HostSessionAuthentication` 與主機提供的 `config` 的 `HostMaterializeSessionRequest`，以及用於協作式取消的 `CancellationToken`。請回傳使用同一個 `Client` 建立或恢復的 Session。

```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` 會收到參與已結束的 Session。SDK 不會中斷連線或銷毀該 Session。`HostMaterializeSessionRequest::$authentication` 是經主機驗證的可信任身分，而非用戶端輸入。儘管如此，仍請在回呼內執行所需的租戶或使用者授權檢查。

## Session 目錄與關閉

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

取消發佈會將 Session 從 AHP 目錄中移除。不會刪除本機歷程記錄，也不會停止執行中的工作。`dispose()` 會停止監聽器，但不會刪除相關的 Session。

## 相關文件

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


## Related topics

- [RPC(Remote Procedure Call)](https://kawax.biz/zh-TW/packages/laravel-copilot-sdk/rpc.md)
- [密碼重設](https://kawax.biz/zh-TW/passwords.md)
- [Laravel Sail](https://kawax.biz/zh-TW/sail.md)
- [快取](https://kawax.biz/zh-TW/cache.md)
- [Laravel Reverb](https://kawax.biz/zh-TW/reverb.md)


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