Phase B: RuntimeConnection discriminated config + CopilotClientOptions

Mirrors PR #1343 Phase 9 (.NET) and PR #1357 Phase I (TypeScript). Removes
the flat `SubprocessConfig` / `ExternalServerConfig` split in favour of a
`RuntimeConnection` discriminated hierarchy, with process-management
options moved to a new `CopilotClientOptions` dataclass.

Public API:

* `RuntimeConnection` abstract base with static factories `stdio()`,
  `tcp()`, `uri()`.
* `ChildProcessRuntimeConnection` intermediate base carrying `path` and
  `args` shared by Stdio + Tcp.
* `StdioRuntimeConnection`, `TcpRuntimeConnection`, `UriRuntimeConnection`
  concrete subclasses; pattern-match / `isinstance` on the class to
  branch on the transport.
* `CopilotClientOptions(connection=..., working_directory=..., log_level=...,
  env=..., github_token=..., base_directory=..., use_logged_in_user=...,
  telemetry=..., session_fs=..., session_idle_timeout_seconds=...,
  enable_remote_sessions=...)`.
* `CopilotClient(options=CopilotClientOptions(...) | None, *, auto_start=...,
  on_list_models=...)`.

Renames:

* `copilot_home` → `base_directory`
* `remote` → `enable_remote_sessions`
* `CopilotClient.actual_port` → `CopilotClient.runtime_port`
* `CopilotClient.on(...)` → `CopilotClient.on_lifecycle(...)`
* `tcp_connection_token` moves off `CopilotClientOptions` and onto
  the variant: `TcpRuntimeConnection.connection_token` /
  `UriRuntimeConnection.connection_token`
* `use_stdio` bool is gone — the variant class IS the discriminator.

Migration:

* All hand-written code that previously branched on `isinstance(config,
  ExternalServerConfig)` now branches on the runtime-connection variant
  via `isinstance(connection, UriRuntimeConnection)` /
  `StdioRuntimeConnection` etc., giving proper type narrowing in
  pyright/mypy without relying on Literal-based tagged-union narrowing.
* Samples, scenarios, README, and tests updated in lock-step.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: SteveSandersonMS

python/README.md

@@ -113,7 +113,7 @@ asyncio.run(main())
 ### CopilotClient
 
 ```python
-from copilot import CopilotClient, SubprocessConfig
+from copilot import CopilotClient
 from copilot.session import PermissionHandler
 
 async with CopilotClient() as client:
@@ -133,40 +133,44 @@ async with CopilotClient() as client:
 > **Note:** For manual lifecycle management, see [Manual Resource Management](#manual-resource-management) above.
 
 ```python
-from copilot import CopilotClient, ExternalServerConfig
+from copilot import CopilotClient, CopilotClientOptions, RuntimeConnection
 
 # Connect to an existing CLI server
-client = CopilotClient(ExternalServerConfig(url="localhost:3000"))
+client = CopilotClient(
+    CopilotClientOptions(connection=RuntimeConnection.uri("localhost:3000"))
+)
 ```
 
 **CopilotClient Constructor:**
 
 ```python
 CopilotClient(
-    config=None,        # SubprocessConfig | ExternalServerConfig | None
+    options=None,        # CopilotClientOptions | None
     *,
-    auto_start=True,    # auto-start server on first use
+    auto_start=True,     # auto-start server on first use
     on_list_models=None, # custom handler for list_models()
 )
 ```
 
-**SubprocessConfig** — spawn a local CLI process:
+**CopilotClientOptions** — configure the client:
 
-- `cli_path` (str | None): Path to CLI executable (default: `COPILOT_CLI_PATH` env var, or bundled binary)
-- `cli_args` (list[str]): Extra arguments for the CLI executable
-- `cwd` (str | None): Working directory for CLI process (default: current dir)
-- `use_stdio` (bool): Use stdio transport instead of TCP (default: True)
-- `port` (int): Server port for TCP mode (default: 0 for random)
-- `log_level` (str): Log level (default: "info")
-- `env` (dict | None): Environment variables for the CLI process
+- `connection` (RuntimeConnection | None): How to reach the runtime. Use
+  `RuntimeConnection.stdio(...)`, `RuntimeConnection.tcp(...)`, or
+  `RuntimeConnection.uri(...)`. Defaults to a stdio connection with the bundled binary.
+- `working_directory` (str | None): Working directory for the CLI process (default: current dir).
+- `log_level` (str): Log level (default: "info").
+- `env` (dict | None): Environment variables for the CLI process.
 - `github_token` (str | None): GitHub token for authentication. When provided, takes priority over other auth methods.
-- `copilot_home` (str | None): Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned CLI process. When `None`, the CLI defaults to `~/.copilot`. Useful in restricted environments where only specific directories are writable. Ignored when using `ExternalServerConfig`.
+- `base_directory` (str | None): Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned CLI process. When `None`, the CLI defaults to `~/.copilot`. Useful in restricted environments where only specific directories are writable. Ignored when using a `UriRuntimeConnection`.
 - `use_logged_in_user` (bool | None): Whether to use logged-in user for authentication (default: True, but False when `github_token` is provided).
 - `telemetry` (dict | None): OpenTelemetry configuration for the CLI process. Providing this enables telemetry — no separate flag needed. See [Telemetry](#telemetry) below.
+- `enable_remote_sessions` (bool): Enable remote/cloud session support (default: False).
 
-**ExternalServerConfig** — connect to an existing CLI server:
+**RuntimeConnection variants:**
 
-- `url` (str): Server URL (e.g., `"localhost:8080"`, `"http://127.0.0.1:9000"`, or just `"8080"`).
+- `RuntimeConnection.stdio(path=None, args=None)` — spawn a local CLI process and talk over stdio.
+- `RuntimeConnection.tcp(port=0, connection_token=None, path=None, args=None)` — spawn a local CLI in TCP mode.
+- `RuntimeConnection.uri(url, connection_token=None)` — connect to an existing CLI server (e.g. `"localhost:8080"`).
 
 **`CopilotClient.create_session()`:**
 
@@ -197,10 +201,10 @@ await client.set_foreground_session_id("session-123")
 def on_lifecycle(event):
     print(f"{event.type}: {event.sessionId}")
 
-unsubscribe = client.on(on_lifecycle)
+unsubscribe = client.on_lifecycle(on_lifecycle)
 
 # Subscribe to specific event type
-unsubscribe = client.on("session.foreground", lambda e: print(f"Foreground: {e.sessionId}"))
+unsubscribe = client.on_lifecycle("session.foreground", lambda e: print(f"Foreground: {e.sessionId}"))
 
 # Later, to stop receiving events:
 unsubscribe()
@@ -531,9 +535,9 @@ async with await client.create_session(
 The SDK supports OpenTelemetry for distributed tracing. Provide a `telemetry` config to enable trace export and automatic W3C Trace Context propagation.
 
 ```python
-from copilot import CopilotClient, SubprocessConfig
+from copilot import CopilotClient, CopilotClientOptions
 
-client = CopilotClient(SubprocessConfig(
+client = CopilotClient(CopilotClientOptions(
     telemetry={
         "otlp_endpoint": "http://localhost:4318",
     },

python/copilot/__init__.py

@@ -5,16 +5,20 @@
 """
 
 from .client import (
+    ChildProcessRuntimeConnection,
     CloudSessionOptions,
     CloudSessionRepository,
     CopilotClient,
-    ExternalServerConfig,
+    CopilotClientOptions,
     ModelCapabilitiesOverride,
     ModelLimitsOverride,
     ModelSupportsOverride,
     ModelVisionLimitsOverride,
     RemoteSessionMode,
-    SubprocessConfig,
+    RuntimeConnection,
+    StdioRuntimeConnection,
+    TcpRuntimeConnection,
+    UriRuntimeConnection,
 )
 from .session import (
     AutoModeSwitchHandler,
@@ -62,10 +66,12 @@
     "AutoModeSwitchHandler",
     "AutoModeSwitchRequest",
     "AutoModeSwitchResponse",
+    "ChildProcessRuntimeConnection",
     "CommandDefinition",
     "CloudSessionOptions",
     "CloudSessionRepository",
     "CopilotClient",
+    "CopilotClientOptions",
     "CopilotSession",
     "CreateSessionFsHandler",
     "ElicitationHandler",
@@ -75,14 +81,14 @@
     "ExitPlanModeHandler",
     "ExitPlanModeRequest",
     "ExitPlanModeResult",
-    "ExternalServerConfig",
     "InputOptions",
     "ModelCapabilitiesOverride",
     "ModelLimitsOverride",
     "ModelSupportsOverride",
     "ModelVisionLimitsOverride",
     "ProviderConfig",
     "RemoteSessionMode",
+    "RuntimeConnection",
     "SessionCapabilities",
     "SessionFsCapabilities",
     "SessionFsConfig",
@@ -93,11 +99,13 @@
     "create_session_fs_adapter",
     "SessionUiApi",
     "SessionUiCapabilities",
-    "SubprocessConfig",
+    "StdioRuntimeConnection",
+    "TcpRuntimeConnection",
     "Tool",
     "ToolBinaryResult",
     "ToolInvocation",
     "ToolResult",
+    "UriRuntimeConnection",
     "convert_mcp_call_tool_result",
     "define_tool",
 ]