Add the ability to connect to a running instance of the Copilot CLI (#346)

* Add the ability to connect to a running instance of the Copilot CLI

* format, lint and document new flags

* Fix lint

Author: friggeri

.github/aw/github-agentic-workflows.md

@@ -214,18 +214,18 @@ The YAML frontmatter supports these fields:
     The `custom` engine allows you to define your own GitHub Actions steps instead of using an AI processor. Each step in the `steps` array follows standard GitHub Actions step syntax with `name`, `uses`/`run`, `with`, `env`, etc. This is useful for deterministic workflows that don't require AI processing.
 
     **Environment Variables Available to Custom Engines:**
-    
+
     Custom engine steps have access to the following environment variables:
-    
+
     - **`$GH_AW_PROMPT`**: Path to the generated prompt file (`/tmp/gh-aw/aw-prompts/prompt.txt`) containing the markdown content from the workflow. This file contains the natural language instructions that would normally be sent to an AI processor. Custom engines can read this file to access the workflow's markdown content programmatically.
     - **`$GH_AW_SAFE_OUTPUTS`**: Path to the safe outputs file (when safe-outputs are configured). Used for writing structured output that gets processed automatically.
     - **`$GH_AW_MAX_TURNS`**: Maximum number of turns/iterations (when max-turns is configured in engine config).
-    
+
     Example of accessing the prompt content:
     ```bash
     # Read the workflow prompt content
     cat $GH_AW_PROMPT
-    
+
     # Process the prompt content in a custom step
     - name: Process workflow instructions
       run: |
@@ -253,7 +253,7 @@ The YAML frontmatter supports these fields:
         log-level: debug                  # Optional: debug, info (default), warn, error
         args: ["--custom-arg", "value"]   # Optional: additional AWF arguments
     ```
-  
+
 - **`sandbox:`** - Sandbox configuration for AI engines (string or object)
   - String format: `"default"` (no sandbox), `"awf"` (Agent Workflow Firewall), `"srt"` or `"sandbox-runtime"` (Anthropic Sandbox Runtime)
   - Object format for full configuration:
@@ -703,7 +703,7 @@ cache:
     restore-keys: |
       node-modules-
   - key: build-cache-${{ github.sha }}
-    path: 
+    path:
       - dist
       - .cache
     restore-keys:
@@ -963,7 +963,7 @@ All other expressions are dissallowed.
 The `needs.activation.outputs.text` value provides automatically sanitized content based on the triggering event:
 
 - **Issues**: `title + "\n\n" + body`
-- **Pull Requests**: `title + "\n\n" + body`  
+- **Pull Requests**: `title + "\n\n" + body`
 - **Issue Comments**: `comment.body`
 - **PR Review Comments**: `comment.body`
 - **PR Reviews**: `review.body`
@@ -1163,7 +1163,7 @@ permissions:
 
 safe-outputs:
   create-issue:       # Automatic issue creation
-  add-comment:  # Automatic comment creation  
+  add-comment:  # Automatic comment creation
   create-pull-request: # Automatic PR creation
 ```
 
@@ -1437,7 +1437,7 @@ The `--start-date` and `--end-date` flags support delta time syntax for relative
 
 **Supported Time Units:**
 - **Days**: `-1d`, `-7d`
-- **Weeks**: `-1w`, `-4w` 
+- **Weeks**: `-1w`, `-4w`
 - **Months**: `-1mo`, `-6mo`
 - **Hours/Minutes**: `-12h`, `-30m` (for sub-day precision)
 - **Combinations**: `-1mo2w3d`, `-2w5d12h`
@@ -1447,7 +1447,7 @@ The `--start-date` and `--end-date` flags support delta time syntax for relative
 # Get runs from the last week
 gh aw logs --start-date -1w
 
-# Get runs up to yesterday  
+# Get runs up to yesterday
 gh aw logs --end-date -1d
 
 # Get runs from the last month
@@ -1502,7 +1502,7 @@ permissions:
 GitHub Agentic Workflows supports security scanning during compilation with `--actionlint`, `--zizmor`, and `--poutine` flags.
 
 **actionlint** - Lints GitHub Actions workflows and validates shell scripts with integrated shellcheck
-**zizmor** - Scans for security vulnerabilities, privilege escalation, and secret exposure  
+**zizmor** - Scans for security vulnerabilities, privilege escalation, and secret exposure
 **poutine** - Analyzes supply chain risks and third-party action usage
 
 ```bash
@@ -1559,7 +1559,7 @@ gh aw mcp list-tools github weekly-research
 
 This command is useful for:
 - **Discovering capabilities**: See what tools are available from each MCP server
-- **Workflow discovery**: Find which workflows use a specific MCP server  
+- **Workflow discovery**: Find which workflows use a specific MCP server
 - **Permission debugging**: Check which tools are allowed in your workflow configuration
 
 ## Compilation Process
@@ -1588,7 +1588,7 @@ Agentic workflows compile to GitHub Actions YAML:
 
 1. **Use descriptive workflow names** that clearly indicate purpose
 2. **Set appropriate timeouts** to prevent runaway costs
-3. **Include security notices** for workflows processing user content  
+3. **Include security notices** for workflows processing user content
 4. **Use the `imports:` field** in frontmatter for common patterns and security boilerplate
 5. **ALWAYS run `gh aw compile` after every change** to generate the GitHub Actions workflow (or `gh aw compile <workflow-id>` for specific workflows)
 6. **Review generated `.lock.yml`** files before deploying
@@ -1651,4 +1651,4 @@ gh aw logs <workflow-id>
 
 ### Documentation
 
-For complete CLI documentation, see: https://githubnext.github.io/gh-aw/setup/cli/
+For complete CLI documentation, see: https://githubnext.github.io/gh-aw/setup/cli/

docs/getting-started.md

@@ -954,10 +954,10 @@ By default, the SDK automatically manages the Copilot CLI process lifecycle, sta
 
 ### Running the CLI in Server Mode
 
-Start the CLI in server mode using the `--server` flag and optionally specify a port:
+Start the CLI in server mode using the `--headless` flag and optionally specify a port:
 
 ```bash
-copilot --server --port 4321
+copilot --headless --port 4321
 ```
 
 If you don't specify a port, the CLI will choose a random available port.

dotnet/README.md

@@ -124,6 +124,43 @@ List all available sessions.
 
 Delete a session and its data from disk.
 
+##### `GetForegroundSessionIdAsync(): Task<string?>`
+
+Get the ID of the session currently displayed in the TUI. Only available when connecting to a server running in TUI+server mode (`--ui-server`).
+
+##### `SetForegroundSessionIdAsync(string sessionId): Task`
+
+Request the TUI to switch to displaying the specified session. Only available in TUI+server mode.
+
+##### `On(Action<SessionLifecycleEvent> handler): IDisposable`
+
+Subscribe to all session lifecycle events. Returns an `IDisposable` that unsubscribes when disposed.
+
+```csharp
+using var subscription = client.On(evt =>
+{
+    Console.WriteLine($"Session {evt.SessionId}: {evt.Type}");
+});
+```
+
+##### `On(string eventType, Action<SessionLifecycleEvent> handler): IDisposable`
+
+Subscribe to a specific lifecycle event type. Use `SessionLifecycleEventTypes` constants.
+
+```csharp
+using var subscription = client.On(SessionLifecycleEventTypes.Foreground, evt =>
+{
+    Console.WriteLine($"Session {evt.SessionId} is now in foreground");
+});
+```
+
+**Lifecycle Event Types:**
+- `SessionLifecycleEventTypes.Created` - A new session was created
+- `SessionLifecycleEventTypes.Deleted` - A session was deleted
+- `SessionLifecycleEventTypes.Updated` - A session was updated
+- `SessionLifecycleEventTypes.Foreground` - A session became the foreground session in TUI
+- `SessionLifecycleEventTypes.Background` - A session is no longer the foreground session
+
 ---
 
 ### CopilotSession
@@ -462,13 +499,13 @@ var session = await client.CreateSessionAsync(new SessionConfig
         // request.Question - The question to ask
         // request.Choices - Optional list of choices for multiple choice
         // request.AllowFreeform - Whether freeform input is allowed (default: true)
-        
+
         Console.WriteLine($"Agent asks: {request.Question}");
         if (request.Choices?.Count > 0)
         {
             Console.WriteLine($"Choices: {string.Join(", ", request.Choices)}");
         }
-        
+
         // Return the user's response
         return new UserInputResponse
         {
@@ -501,7 +538,7 @@ var session = await client.CreateSessionAsync(new SessionConfig
                 AdditionalContext = "Extra context for the model"
             };
         },
-        
+
         // Called after each tool execution
         OnPostToolUse = async (input, invocation) =>
         {
@@ -511,7 +548,7 @@ var session = await client.CreateSessionAsync(new SessionConfig
                 AdditionalContext = "Post-execution notes"
             };
         },
-        
+
         // Called when user submits a prompt
         OnUserPromptSubmitted = async (input, invocation) =>
         {
@@ -521,7 +558,7 @@ var session = await client.CreateSessionAsync(new SessionConfig
                 ModifiedPrompt = input.Prompt // Optionally modify the prompt
             };
         },
-        
+
         // Called when session starts
         OnSessionStart = async (input, invocation) =>
         {
@@ -531,14 +568,14 @@ var session = await client.CreateSessionAsync(new SessionConfig
                 AdditionalContext = "Session initialization context"
             };
         },
-        
+
         // Called when session ends
         OnSessionEnd = async (input, invocation) =>
         {
             Console.WriteLine($"Session ended: {input.Reason}");
             return null;
         },
-        
+
         // Called when an error occurs
         OnErrorOccurred = async (input, invocation) =>
         {