Cloud Sessions

ローカルの Copilot CLI ではなく GitHub ホスト環境でセッションを実行する Cloud Sessions の使い方を説明します。

​

Cloud Sessions

Cloud Sessions は、ローカルの Copilot CLI プロセスではなく GitHub 側のホスト環境でセッションを実行する機能です。Mission Control 上でタスクが予約され、クラウド側の copilot-agent が接続して処理を進めます。

通常の Remote Sessions は「ローカルで動くセッションを GitHub Web/モバイルから見えるようにする」機能です。実行場所自体を GitHub ホスト環境にしたい場合は Cloud Sessions を使います。

​

前提条件

• ユーザーが Cloud Agent を利用できる Copilot 権限を持っている
• GitHub トークン、またはログイン済み Copilot CLI ユーザーで認証できる
• 可能なら GitHub リポジトリ情報を関連付ける
• 組織ポリシーでクラウド実行とリモート閲覧が許可されている

​

基本的な使い方

SessionConfig の cloud に CloudSessionOptions を指定します。リポジトリ情報は SDK 型としては任意ですが、Mission Control とクラウドエージェントに文脈を渡すため指定することを推奨します。

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\CloudSessionOptions;
use Revolution\Copilot\Types\CloudSessionRepository;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session): void {
    $session->sendAndWait(prompt: 'READMEを要約して');
}, config: new SessionConfig(
    onPermissionRequest: PermissionHandler::approveSafety(),
    cloud: new CloudSessionOptions(
        repository: new CloudSessionRepository(
            owner: 'myorg',
            name: 'myrepo',
            branch: 'main',
        ),
    ),
));

配列でも指定できます。

Copilot::run(
    prompt: 'このリポジトリのテスト方針を確認して',
    config: [
        'cloud' => [
            'repository' => [
                'owner' => 'myorg',
                'name' => 'myrepo',
                'branch' => 'main',
            ],
        ],
    ],
);

​

最初のプロンプトを送るタイミング

Cloud Session は 2 段階で初期化されます。session.create は Mission Control でタスクが予約された時点で戻りますが、クラウド側の copilot-agent が接続して session.start を発行するまで少し時間があります。

最初のプロンプトを確実に届けるには、先にイベントを購読し、producer が copilot-agent の session.start を確認してから送信してください。

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Support\PermissionHandler;
use Revolution\Copilot\Types\CloudSessionOptions;
use Revolution\Copilot\Types\CloudSessionRepository;
use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    streaming: true,
    onPermissionRequest: PermissionHandler::approveSafety(),
    cloud: new CloudSessionOptions(
        repository: new CloudSessionRepository(owner: 'myorg', name: 'myrepo'),
    ),
);

Copilot::start(function (CopilotSession $session): void {
    $cloudAgentStarted = false;

    foreach ($session->stream(timeout: 30.0) as $event) {
        if (
            $event->is(SessionEventType::SESSION_START)
            && $event->data('producer') === 'copilot-agent'
        ) {
            $cloudAgentStarted = true;
            break;
        }
    }

    if (! $cloudAgentStarted) {
        throw new RuntimeException('Cloud session did not become ready.');
    }

    $session->sendAndWait(prompt: 'READMEを要約して');
}, config: $config);

実アプリでは、キューや非同期処理側で session.start 確認後にプロンプトを送る構成にすると扱いやすいです。

​

Remote Sessions との違い

機能	実行場所	主な用途
Remote Sessions	ローカルまたは自前サーバー	Web/モバイルから既存セッションを閲覧・操作する
Cloud Sessions	GitHub ホスト環境	ユーザー端末や自前サーバーで Copilot CLI を動かさずに処理する

​

注意点

• Cloud Sessions は権限と組織ポリシーの影響を受けます
• streaming: true にすると assistant.message_delta などのリアルタイムイベントを受け取れます
• 権限リクエストの扱いは通常セッションと同じです。Laravel 版の Facade 経由ではデフォルトで deny-all なので、必要に応じて PermissionHandler::approveSafety() などを指定してください

​

参考

• Remote Sessions
• SessionConfig
• ストリーミングイベント

最新情報は GitHub リポジトリ を参照してください。