> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 とクラウドエージェントに文脈を渡すため指定することを推奨します。

```php theme={null}
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',
        ),
    ),
));
```

配列でも指定できます。

```php theme={null}
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` を確認してから送信してください。

```php theme={null}
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](/jp/packages/laravel-copilot-sdk/remote-sessions)
* [SessionConfig](/jp/packages/laravel-copilot-sdk/session-config)
* [ストリーミングイベント](/jp/packages/laravel-copilot-sdk/streaming-events)

<Info>
  最新情報は [GitHub リポジトリ](https://github.com/invokable/laravel-copilot-sdk) を参照してください。
</Info>