> ## 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()` 使用你自己的应用逻辑验证准入 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 不同的凭据。请不要将其保存在日志或会话配置中。当主机收到 `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` 是经主机验证的可信身份，而不是客户端输入。尽管如此，仍请在回调中执行所需的租户或用户授权。

## 会话目录与关闭

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

取消发布会将会话从 AHP 目录中移除，但不会删除本地历史记录，也不会停止正在运行的工作。`dispose()` 会停止监听器，但不会删除相关会话。

## 相关文档

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


## Related topics

- [RPC（Remote Procedure Call）](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/rpc.md)
- [密码重置](https://kawax.biz/zh-CN/passwords.md)
- [Laravel Sail](https://kawax.biz/zh-CN/sail.md)
- [缓存](https://kawax.biz/zh-CN/cache.md)
- [Laravel Reverb](https://kawax.biz/zh-CN/reverb.md)


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