Phase F: internals cleanup + expand public API surface

Mirrors PR #1357 Phase K + 4.1 (TypeScript SDK API review).

Cleanup:

* Remove the deprecated `CopilotSession.destroy()` method. Only `disconnect()`
  remains (matches TS PR #1357 4.1).
* Rename `NO_RESULT_PERMISSION_V2_ERROR` → `_NO_RESULT_PERMISSION_V2_ERROR`
  and `MIN_PROTOCOL_VERSION` → `_MIN_PROTOCOL_VERSION` (module-private
  constants; Python equivalent of TS `@internal` + `stripInternal`).

Public API audit vs C# / TypeScript:

* `copilot/__init__.py` now re-exports the full set of types that match the
  TS public surface from `nodejs/src/index.ts`. Notable additions:

  - Lifecycle event hierarchy: `SessionCreatedEvent`, `SessionDeletedEvent`,
    `SessionUpdatedEvent`, `SessionForegroundEvent`, `SessionBackgroundEvent`,
    `SessionLifecycleEvent`, `SessionLifecycleEventBase`,
    `SessionLifecycleEventMetadata`, `SessionLifecycleEventType`,
    `SessionLifecycleHandler`
  - Session metadata / context: `SessionContext`, `SessionListFilter`,
    `SessionMetadata`
  - Generated `PermissionRequest`, `SessionEvent`, `SessionEventType` (
    consumers shouldn't have to reach into `copilot.generated.*`)
  - `PermissionHandler`, `PermissionRequestResult`, `PermissionNoResult`,
    `UserInputHandler`, `UserInputRequest`, `UserInputResponse`
  - MCP server configs: `MCPHTTPServerConfig`, `MCPServerConfig`,
    `MCPStdioServerConfig`
  - Session config: `SessionConfig`, `ResumeSessionConfig`, `SessionHooks`,
    `SystemMessageConfig`, `InfiniteSessionConfig`
  - All hook handler / input / output TypedDicts: `PreToolUseHandler` &
    friends across the six hook lifecycle points
  - Model* completion (added `ModelLimits`, `ModelSupports`,
    `ModelVisionLimits`, `ModelBilling`, `ModelPolicy`, `ModelCapabilities`)
  - `ConnectionState`, `LogLevel`, `PingResponse`, `GetStatusResponse`,
    `GetAuthStatusResponse`, `StopError`
  - `ToolResultType`, `SessionEventHandler`

`__all__` is now alphabetically sorted.

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

Author: SteveSandersonMS

python/copilot/__init__.py

@@ -8,19 +8,50 @@
     ChildProcessRuntimeConnection,
     CloudSessionOptions,
     CloudSessionRepository,
+    ConnectionState,
     CopilotClient,
     CopilotClientOptions,
+    GetAuthStatusResponse,
+    GetStatusResponse,
+    LogLevel,
+    ModelBilling,
+    ModelCapabilities,
     ModelCapabilitiesOverride,
+    ModelInfo,
+    ModelLimits,
     ModelLimitsOverride,
+    ModelPolicy,
+    ModelSupports,
     ModelSupportsOverride,
+    ModelVisionLimits,
     ModelVisionLimitsOverride,
+    PingResponse,
     RemoteSessionMode,
     RuntimeConnection,
+    SessionBackgroundEvent,
+    SessionContext,
+    SessionCreatedEvent,
+    SessionDeletedEvent,
+    SessionForegroundEvent,
+    SessionLifecycleEvent,
+    SessionLifecycleEventBase,
+    SessionLifecycleEventMetadata,
+    SessionLifecycleEventType,
+    SessionLifecycleHandler,
+    SessionListFilter,
+    SessionMetadata,
+    SessionUpdatedEvent,
     StdioRuntimeConnection,
+    StopError,
     TcpRuntimeConnection,
     TelemetryConfig,
     UriRuntimeConnection,
 )
+from .generated.session_events import (
+    PermissionRequest,
+    SessionEvent,
+    SessionEventType,
+)
 from .session import (
     AutoModeSwitchHandler,
     AutoModeSwitchRequest,
@@ -33,16 +64,52 @@
     ElicitationHandler,
     ElicitationParams,
     ElicitationResult,
+    ErrorOccurredHandler,
+    ErrorOccurredHookInput,
+    ErrorOccurredHookOutput,
     ExitPlanModeHandler,
     ExitPlanModeRequest,
     ExitPlanModeResult,
+    InfiniteSessionConfig,
     InputOptions,
+    MCPHTTPServerConfig,
+    MCPServerConfig,
+    MCPStdioServerConfig,
+    PermissionHandler,
+    PermissionNoResult,
+    PermissionRequestResult,
+    PostToolUseHandler,
+    PostToolUseHookInput,
+    PostToolUseHookOutput,
+    PreMcpToolCallHandler,
+    PreMcpToolCallHookInput,
+    PreMcpToolCallHookOutput,
+    PreToolUseHandler,
+    PreToolUseHookInput,
+    PreToolUseHookOutput,
     ProviderConfig,
+    ResumeSessionConfig,
     SessionCapabilities,
+    SessionConfig,
+    SessionEndHandler,
+    SessionEndHookInput,
+    SessionEndHookOutput,
+    SessionEventHandler,
     SessionFsCapabilities,
     SessionFsConfig,
+    SessionHooks,
+    SessionStartHandler,
+    SessionStartHookInput,
+    SessionStartHookOutput,
     SessionUiApi,
     SessionUiCapabilities,
+    SystemMessageConfig,
+    UserInputHandler,
+    UserInputRequest,
+    UserInputResponse,
+    UserPromptSubmittedHandler,
+    UserPromptSubmittedHookInput,
+    UserPromptSubmittedHookOutput,
 )
 from .session_fs_provider import (
     SessionFsFileInfo,
@@ -56,58 +123,125 @@
     ToolBinaryResult,
     ToolInvocation,
     ToolResult,
+    ToolResultType,
     convert_mcp_call_tool_result,
     define_tool,
 )
 
 __version__ = "0.1.0"
 
 __all__ = [
-    "CommandContext",
     "AutoModeSwitchHandler",
     "AutoModeSwitchRequest",
     "AutoModeSwitchResponse",
     "ChildProcessRuntimeConnection",
-    "CommandDefinition",
     "CloudSessionOptions",
     "CloudSessionRepository",
+    "CommandContext",
+    "CommandDefinition",
+    "ConnectionState",
     "CopilotClient",
     "CopilotClientOptions",
     "CopilotSession",
     "CreateSessionFsHandler",
+    "ElicitationContext",
     "ElicitationHandler",
     "ElicitationParams",
-    "ElicitationContext",
     "ElicitationResult",
+    "ErrorOccurredHandler",
+    "ErrorOccurredHookInput",
+    "ErrorOccurredHookOutput",
     "ExitPlanModeHandler",
     "ExitPlanModeRequest",
     "ExitPlanModeResult",
+    "GetAuthStatusResponse",
+    "GetStatusResponse",
+    "InfiniteSessionConfig",
     "InputOptions",
+    "LogLevel",
+    "MCPHTTPServerConfig",
+    "MCPServerConfig",
+    "MCPStdioServerConfig",
+    "ModelBilling",
+    "ModelCapabilities",
     "ModelCapabilitiesOverride",
+    "ModelInfo",
+    "ModelLimits",
     "ModelLimitsOverride",
+    "ModelPolicy",
+    "ModelSupports",
     "ModelSupportsOverride",
+    "ModelVisionLimits",
     "ModelVisionLimitsOverride",
+    "PermissionHandler",
+    "PermissionNoResult",
+    "PermissionRequest",
+    "PermissionRequestResult",
+    "PingResponse",
+    "PostToolUseHandler",
+    "PostToolUseHookInput",
+    "PostToolUseHookOutput",
+    "PreMcpToolCallHandler",
+    "PreMcpToolCallHookInput",
+    "PreMcpToolCallHookOutput",
+    "PreToolUseHandler",
+    "PreToolUseHookInput",
+    "PreToolUseHookOutput",
     "ProviderConfig",
     "RemoteSessionMode",
+    "ResumeSessionConfig",
     "RuntimeConnection",
+    "SessionBackgroundEvent",
     "SessionCapabilities",
+    "SessionConfig",
+    "SessionContext",
+    "SessionCreatedEvent",
+    "SessionDeletedEvent",
+    "SessionEndHandler",
+    "SessionEndHookInput",
+    "SessionEndHookOutput",
+    "SessionEvent",
+    "SessionEventHandler",
+    "SessionEventType",
+    "SessionForegroundEvent",
     "SessionFsCapabilities",
     "SessionFsConfig",
     "SessionFsFileInfo",
     "SessionFsProvider",
     "SessionFsSqliteProvider",
     "SessionFsSqliteQueryResult",
-    "create_session_fs_adapter",
+    "SessionHooks",
+    "SessionLifecycleEvent",
+    "SessionLifecycleEventBase",
+    "SessionLifecycleEventMetadata",
+    "SessionLifecycleEventType",
+    "SessionLifecycleHandler",
+    "SessionListFilter",
+    "SessionMetadata",
+    "SessionStartHandler",
+    "SessionStartHookInput",
+    "SessionStartHookOutput",
     "SessionUiApi",
     "SessionUiCapabilities",
+    "SessionUpdatedEvent",
     "StdioRuntimeConnection",
+    "StopError",
+    "SystemMessageConfig",
     "TcpRuntimeConnection",
     "TelemetryConfig",
     "Tool",
     "ToolBinaryResult",
     "ToolInvocation",
     "ToolResult",
+    "ToolResultType",
     "UriRuntimeConnection",
+    "UserInputHandler",
+    "UserInputRequest",
+    "UserInputResponse",
+    "UserPromptSubmittedHandler",
+    "UserPromptSubmittedHookInput",
+    "UserPromptSubmittedHookOutput",
     "convert_mcp_call_tool_result",
+    "create_session_fs_adapter",
     "define_tool",
 ]

python/copilot/client.py

@@ -979,13 +979,13 @@ def _session_lifecycle_event_from_dict(data: dict) -> SessionLifecycleEvent:
 
 HandlerUnsubcribe = Callable[[], None]
 
-NO_RESULT_PERMISSION_V2_ERROR = (
+_NO_RESULT_PERMISSION_V2_ERROR = (
     "Permission handlers cannot return 'no-result' when connected to a protocol v2 server."
 )
 
 # Minimum protocol version this SDK can communicate with.
 # Servers reporting a version below this are rejected.
-MIN_PROTOCOL_VERSION = 2
+_MIN_PROTOCOL_VERSION = 2
 
 
 def _get_bundled_cli_path() -> str | None:
@@ -2664,15 +2664,15 @@ async def _verify_protocol_version(self) -> None:
         if server_version is None:
             raise RuntimeError(
                 "SDK protocol version mismatch: "
-                f"SDK supports versions {MIN_PROTOCOL_VERSION}-{max_version}"
+                f"SDK supports versions {_MIN_PROTOCOL_VERSION}-{max_version}"
                 ", but server does not report a protocol version. "
                 "Please update your server to ensure compatibility."
             )
 
-        if server_version < MIN_PROTOCOL_VERSION or server_version > max_version:
+        if server_version < _MIN_PROTOCOL_VERSION or server_version > max_version:
             raise RuntimeError(
                 "SDK protocol version mismatch: "
-                f"SDK supports versions {MIN_PROTOCOL_VERSION}-{max_version}"
+                f"SDK supports versions {_MIN_PROTOCOL_VERSION}-{max_version}"
                 f", but server reports version {server_version}. "
                 "Please update your SDK or server to ensure compatibility."
             )
@@ -3364,10 +3364,10 @@ async def _handle_permission_request_v2(self, params: dict) -> dict:
             perm_request = _load_PermissionRequest(permission_request)
             result = await session._handle_permission_request(perm_request)
             if isinstance(result, PermissionNoResult):
-                raise ValueError(NO_RESULT_PERMISSION_V2_ERROR)
+                raise ValueError(_NO_RESULT_PERMISSION_V2_ERROR)
             return {"result": result.to_dict()}
         except ValueError as exc:
-            if str(exc) == NO_RESULT_PERMISSION_V2_ERROR:
+            if str(exc) == _NO_RESULT_PERMISSION_V2_ERROR:
                 raise
             return {"result": PermissionDecisionUserNotAvailable().to_dict()}
         except Exception:  # pylint: disable=broad-except

python/copilot/session.py

@@ -2338,26 +2338,6 @@ async def disconnect(self) -> None:
             with self._auto_mode_switch_handler_lock:
                 self._auto_mode_switch_handler = None
 
-    async def destroy(self) -> None:
-        """
-        .. deprecated::
-            Use :meth:`disconnect` instead. This method will be removed in a future release.
-
-        Disconnect this session and release all in-memory resources.
-        Session data on disk is preserved for later resumption.
-
-        Raises:
-            Exception: If the connection fails.
-        """
-        import warnings
-
-        warnings.warn(
-            "destroy() is deprecated, use disconnect() instead",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        await self.disconnect()
-
     async def __aenter__(self) -> CopilotSession:
         """Enable use as an async context manager."""
         return self