Sync with official SDK PR #346: SessionLifecycle events and headless flag

docs/jp/session-lifecycle.md

@@ -0,0 +1,154 @@
+# セッションライフサイクルイベント
+
+セッションライフサイクルイベントは、セッションの作成、削除、更新、およびフォアグラウンド/バックグラウンドの状態変更（TUI+サーバーモード時）を通知するイベントです。
+
+## イベントタイプ
+
+`SessionLifecycleEventType` enumで定義されている5つのイベントタイプがあります：
+
+| イベント | 説明 |
+|---------|------|
+| `session.created` | 新しいセッションが作成された |
+| `session.deleted` | セッションが削除された |
+| `session.updated` | セッションが更新された |
+| `session.foreground` | セッションがフォアグラウンドに移動した |
+| `session.background` | セッションがバックグラウンドに移動した |
+
+```php
+use Revolution\Copilot\Enums\SessionLifecycleEventType;
+
+// イベントタイプの値を取得
+echo SessionLifecycleEventType::SESSION_CREATED->value; // 'session.created'
+```
+
+## イベントの購読
+
+`onLifecycle()` メソッドを使用してセッションライフサイクルイベントを購読できます：
+
+```php
+use Revolution\Copilot\Facades\Copilot;
+use Revolution\Copilot\Types\SessionLifecycleEvent;
+
+// Clientを取得してライフサイクルイベントを購読
+$client = Copilot::client();
+
+// 全てのライフサイクルイベントを購読
+$unsubscribe = $client->onLifecycle(function (SessionLifecycleEvent $event) {
+    match ($event->type) {
+        SessionLifecycleEventType::SESSION_CREATED => info("セッション作成: {$event->sessionId}"),
+        SessionLifecycleEventType::SESSION_DELETED => info("セッション削除: {$event->sessionId}"),
+        SessionLifecycleEventType::SESSION_FOREGROUND => info("フォアグラウンド: {$event->sessionId}"),
+        SessionLifecycleEventType::SESSION_BACKGROUND => info("バックグラウンド: {$event->sessionId}"),
+        default => null,
+    };
+});
+
+// 購読を解除
+$unsubscribe();
+```
+
+## SessionLifecycleEvent
+
+`SessionLifecycleEvent` はライフサイクルイベントの詳細を含むreadonly classです：
+
+```php
+use Revolution\Copilot\Types\SessionLifecycleEvent;
+use Revolution\Copilot\Types\SessionLifecycleEventMetadata;
+
+readonly class SessionLifecycleEvent implements Arrayable
+{
+    public function __construct(
+        public SessionLifecycleEventType $type,  // イベントタイプ
+        public string $sessionId,                 // セッションID
+        public ?SessionLifecycleEventMetadata $metadata = null,  // メタデータ（削除時は含まれない）
+    ) {}
+}
+```
+
+### SessionLifecycleEventMetadata
+
+セッションのメタデータを含むクラスです（削除イベントには含まれません）：
+
+```php
+readonly class SessionLifecycleEventMetadata implements Arrayable
+{
+    public function __construct(
+        public string $startTime,      // セッション開始時刻
+        public string $modifiedTime,   // 最終更新時刻
+        public ?string $summary = null, // セッションの要約
+    ) {}
+}
+```
+
+## フォアグラウンドセッション管理
+
+TUI+サーバーモード（`--ui-server`）で動作しているサーバーに接続している場合、フォアグラウンドセッションを管理できます。
+
+### 現在のフォアグラウンドセッションを取得
+
+```php
+use Revolution\Copilot\Facades\Copilot;
+
+$client = Copilot::client();
+
+// TUIに表示されている現在のセッションIDを取得
+$sessionId = $client->getForegroundSessionId();
+
+if ($sessionId !== null) {
+    echo "現在のフォアグラウンドセッション: {$sessionId}";
+}
+```
+
+### フォアグラウンドセッションを設定
+
+```php
+use Revolution\Copilot\Facades\Copilot;
+
+$client = Copilot::client();
+
+// TUIに特定のセッションを表示
+$client->setForegroundSessionId('session-123');
+```
+
+## ForegroundSessionInfo
+
+フォアグラウンドセッションの情報を含むreadonly classです：
+
+```php
+use Revolution\Copilot\Types\ForegroundSessionInfo;
+
+readonly class ForegroundSessionInfo implements Arrayable
+{
+    public function __construct(
+        public ?string $sessionId = null,      // フォアグラウンドセッションID
+        public ?string $workspacePath = null,  // ワークスペースパス
+    ) {}
+}
+```
+
+## TCPモードでの使用
+
+TUI+サーバーモードでCopilot CLIを起動し、SDKから接続することでライフサイクルイベントを活用できます：
+
+```bash
+# TUI+サーバーモードでCopilot CLIを起動
+copilot --ui-server --port 8080
+```
+
+```php
+use Revolution\Copilot\Facades\Copilot;
+
+// TCPモードでサーバーに接続
+$client = Copilot::useTcp('tcp://127.0.0.1:8080')->client();
+
+// ライフサイクルイベントを購読
+$client->onLifecycle(function (SessionLifecycleEvent $event) {
+    // イベント処理
+});
+```
+
+## 注意事項
+
+- `session.foreground` と `session.background` イベントは、TUI+サーバーモードでのみ発生します
+- セッション削除時（`session.deleted`）には `metadata` プロパティは `null` になります
+- `onLifecycle()` は購読解除用のコールバック関数を返します

src/Client.php

@@ -21,12 +21,14 @@
 use Revolution\Copilot\JsonRpc\JsonRpcClient;
 use Revolution\Copilot\Process\ProcessManager;
 use Revolution\Copilot\Transport\TcpTransport;
+use Revolution\Copilot\Types\ForegroundSessionInfo;
 use Revolution\Copilot\Types\GetAuthStatusResponse;
 use Revolution\Copilot\Types\GetStatusResponse;
 use Revolution\Copilot\Types\ModelInfo;
 use Revolution\Copilot\Types\ResumeSessionConfig;
 use Revolution\Copilot\Types\SessionConfig;
 use Revolution\Copilot\Types\SessionEvent;
+use Revolution\Copilot\Types\SessionLifecycleEvent;
 use Revolution\Copilot\Types\SessionMetadata;
 use Revolution\Copilot\Types\ToolResultObject;
 use Revolution\Copilot\Types\UserInputRequest;
@@ -63,6 +65,13 @@ class Client implements CopilotClient
      */
     protected array $sessions = [];
 
+    /**
+     * Session lifecycle event handlers.
+     *
+     * @var array<callable(SessionLifecycleEvent): void>
+     */
+    protected array $lifecycleHandlers = [];
+
     /**
      * Create a new CopilotClient.
      */
@@ -499,6 +508,65 @@ public function listSessions(): array
         );
     }
 
+    /**
+     * Gets the foreground session ID in TUI+server mode.
+     *
+     * This returns the ID of the session currently displayed in the TUI.
+     * Only available when connecting to a server running in TUI+server mode (--ui-server).
+     *
+     * @throws JsonRpcException
+     */
+    public function getForegroundSessionId(): ?string
+    {
+        $this->ensureConnected();
+
+        $response = $this->rpcClient->request('session.getForeground', []);
+
+        return ForegroundSessionInfo::fromArray($response)->sessionId;
+    }
+
+    /**
+     * Sets the foreground session in TUI+server mode.
+     *
+     * This requests the TUI to switch to displaying the specified session.
+     * Only available when connecting to a server running in TUI+server mode (--ui-server).
+     *
+     * @throws RuntimeException|JsonRpcException
+     */
+    public function setForegroundSessionId(string $sessionId): void
+    {
+        $this->ensureConnected();
+
+        $response = $this->rpcClient->request('session.setForeground', [
+            'sessionId' => $sessionId,
+        ]);
+
+        if (! ($response['success'] ?? false)) {
+            throw new RuntimeException($response['error'] ?? 'Failed to set foreground session');
+        }
+    }
+
+    /**
+     * Subscribes to session lifecycle events.
+     *
+     * Lifecycle events are emitted when sessions are created, deleted, updated,
+     * or change foreground/background state (in TUI+server mode).
+     *
+     * @param  callable(SessionLifecycleEvent): void  $handler
+     * @return callable(): void A function that, when called, unsubscribes the handler
+     */
+    public function onLifecycle(callable $handler): callable
+    {
+        $this->lifecycleHandlers[] = $handler;
+
+        return function () use ($handler) {
+            $this->lifecycleHandlers = array_filter(
+                $this->lifecycleHandlers,
+                fn ($h) => $h !== $handler,
+            );
+        };
+    }
+
     /**
      * Ensure the client is connected.
      *
@@ -551,6 +619,40 @@ protected function handleNotification(string $method, array $params): void
                 $this->sessions[$sessionId]->dispatchEvent($event);
             }
         }
+
+        if ($method === 'session.lifecycle') {
+            $this->handleLifecycleNotification($params);
+        }
+    }
+
+    /**
+     * Handle session lifecycle notifications.
+     */
+    protected function handleLifecycleNotification(array $params): void
+    {
+        // Validate required fields
+        if (! isset($params['type']) || ! is_string($params['type'])) {
+            return;
+        }
+
+        if (! isset($params['sessionId']) || ! is_string($params['sessionId'])) {
+            return;
+        }
+
+        try {
+            $event = SessionLifecycleEvent::fromArray($params);
+
+            // Dispatch to all registered handlers
+            foreach ($this->lifecycleHandlers as $handler) {
+                try {
+                    $handler($event);
+                } catch (Throwable) {
+                    // Ignore handler errors
+                }
+            }
+        } catch (Throwable) {
+            // Ignore parsing errors for invalid event types
+        }
     }
 
     /**

src/Contracts/CopilotClient.php

@@ -10,6 +10,7 @@
 use Revolution\Copilot\Types\ModelInfo;
 use Revolution\Copilot\Types\ResumeSessionConfig;
 use Revolution\Copilot\Types\SessionConfig;
+use Revolution\Copilot\Types\SessionLifecycleEvent;
 use Throwable;
 
 /**
@@ -68,6 +69,28 @@ public function getAuthStatus(): GetAuthStatusResponse;
      */
     public function listModels(): array;
 
+    /**
+     * Gets the foreground session ID in TUI+server mode.
+     *
+     * @throws JsonRpcException
+     */
+    public function getForegroundSessionId(): ?string;
+
+    /**
+     * Sets the foreground session in TUI+server mode.
+     *
+     * @throws JsonRpcException
+     */
+    public function setForegroundSessionId(string $sessionId): void;
+
+    /**
+     * Subscribes to session lifecycle events.
+     *
+     * @param  callable(SessionLifecycleEvent): void  $handler
+     * @return callable(): void A function that, when called, unsubscribes the handler
+     */
+    public function onLifecycle(callable $handler): callable;
+
     /**
      * Stop the CLI server and close all sessions.
      *

src/Enums/SessionEventType.php

@@ -18,6 +18,8 @@ enum SessionEventType: string
     case SESSION_MODEL_CHANGE = 'session.model_change';
     case SESSION_HANDOFF = 'session.handoff';
     case SESSION_TRUNCATION = 'session.truncation';
+    case SESSION_SNAPSHOT_REWIND = 'session.snapshot_rewind';
+    case SESSION_SHUTDOWN = 'session.shutdown';
     case SESSION_USAGE_INFO = 'session.usage_info';
     case SESSION_COMPACTION_START = 'session.compaction_start';
     case SESSION_COMPACTION_COMPLETE = 'session.compaction_complete';
@@ -46,6 +48,9 @@ enum SessionEventType: string
     case TOOL_EXECUTION_PROGRESS = 'tool.execution_progress';
     case TOOL_EXECUTION_COMPLETE = 'tool.execution_complete';
 
+    // Skill events
+    case SKILL_INVOKED = 'skill.invoked';
+
     // Subagent events
     case SUBAGENT_STARTED = 'subagent.started';
     case SUBAGENT_COMPLETED = 'subagent.completed';

src/Enums/SessionLifecycleEventType.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Revolution\Copilot\Enums;
+
+/**
+ * Types of session lifecycle events.
+ *
+ * These events are emitted when sessions are created, deleted, updated,
+ * or change foreground/background state (in TUI+server mode).
+ */
+enum SessionLifecycleEventType: string
+{
+    case SESSION_CREATED = 'session.created';
+    case SESSION_DELETED = 'session.deleted';
+    case SESSION_UPDATED = 'session.updated';
+    case SESSION_FOREGROUND = 'session.foreground';
+    case SESSION_BACKGROUND = 'session.background';
+}

src/Process/ProcessManager.php

@@ -167,7 +167,7 @@ protected function startProcess(): void
             $env['COPILOT_SDK_AUTH_TOKEN'] = $this->githubToken;
         }
 
-        $args = ['--server', '--stdio', '--log-level', $this->logLevel];
+        $args = ['--headless', '--stdio', '--log-level', $this->logLevel];
 
         // Add auth-related flags
         if (filled($this->githubToken)) {