Phase A: SessionConfig/ResumeSessionConfig renames

- on_exit_plan_mode -> on_exit_plan_mode_request (handler kwarg + TypedDict field)
- on_auto_mode_switch -> on_auto_mode_switch_request (handler kwarg + TypedDict field)
- CopilotSession.get_messages() -> get_events() (returns SessionEvent[], not messages)
- ProviderConfig.max_input_tokens -> max_prompt_tokens (matches wire key maxPromptTokens)

Mirrors PR #1357 Phase A (TypeScript SDK API review).

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

Author: SteveSandersonMS

python/README.md

@@ -103,7 +103,7 @@ asyncio.run(main())
 - ✅ Full JSON-RPC protocol support
 - ✅ stdio and TCP transports
 - ✅ Real-time streaming events
-- ✅ Session history with `get_messages()`
+- ✅ Session history with `get_events()`
 - ✅ Type hints throughout
 - ✅ Async/await native
 - ✅ Async context manager support for automatic resource cleanup

python/copilot/client.py

@@ -1377,8 +1377,8 @@ async def create_session(
         on_event: Callable[[SessionEvent], None] | None = None,
         commands: list[CommandDefinition] | None = None,
         on_elicitation_request: ElicitationHandler | None = None,
-        on_exit_plan_mode: ExitPlanModeHandler | None = None,
-        on_auto_mode_switch: AutoModeSwitchHandler | None = None,
+        on_exit_plan_mode_request: ExitPlanModeHandler | None = None,
+        on_auto_mode_switch_request: AutoModeSwitchHandler | None = None,
         create_session_fs_handler: CreateSessionFsHandler | None = None,
         github_token: str | None = None,
         remote_session: RemoteSessionMode | None = None,
@@ -1520,8 +1520,8 @@ async def create_session(
 
         # Enable elicitation request callback if handler provided
         payload["requestElicitation"] = bool(on_elicitation_request)
-        payload["requestExitPlanMode"] = bool(on_exit_plan_mode)
-        payload["requestAutoModeSwitch"] = bool(on_auto_mode_switch)
+        payload["requestExitPlanMode"] = bool(on_exit_plan_mode_request)
+        payload["requestAutoModeSwitch"] = bool(on_auto_mode_switch_request)
 
         # Serialize commands (name + description only) into payload
         if commands:
@@ -1664,10 +1664,10 @@ async def create_session(
             session._register_user_input_handler(on_user_input_request)
         if on_elicitation_request:
             session._register_elicitation_handler(on_elicitation_request)
-        if on_exit_plan_mode:
-            session._register_exit_plan_mode_handler(on_exit_plan_mode)
-        if on_auto_mode_switch:
-            session._register_auto_mode_switch_handler(on_auto_mode_switch)
+        if on_exit_plan_mode_request:
+            session._register_exit_plan_mode_handler(on_exit_plan_mode_request)
+        if on_auto_mode_switch_request:
+            session._register_auto_mode_switch_handler(on_auto_mode_switch_request)
         if hooks:
             session._register_hooks(hooks)
         if transform_callbacks:
@@ -1756,8 +1756,8 @@ async def resume_session(
         on_event: Callable[[SessionEvent], None] | None = None,
         commands: list[CommandDefinition] | None = None,
         on_elicitation_request: ElicitationHandler | None = None,
-        on_exit_plan_mode: ExitPlanModeHandler | None = None,
-        on_auto_mode_switch: AutoModeSwitchHandler | None = None,
+        on_exit_plan_mode_request: ExitPlanModeHandler | None = None,
+        on_auto_mode_switch_request: AutoModeSwitchHandler | None = None,
         create_session_fs_handler: CreateSessionFsHandler | None = None,
         github_token: str | None = None,
         remote_session: RemoteSessionMode | None = None,
@@ -1914,8 +1914,8 @@ async def resume_session(
 
         # Enable elicitation request callback if handler provided
         payload["requestElicitation"] = bool(on_elicitation_request)
-        payload["requestExitPlanMode"] = bool(on_exit_plan_mode)
-        payload["requestAutoModeSwitch"] = bool(on_auto_mode_switch)
+        payload["requestExitPlanMode"] = bool(on_exit_plan_mode_request)
+        payload["requestAutoModeSwitch"] = bool(on_auto_mode_switch_request)
 
         # Serialize commands (name + description only) into payload
         if commands:
@@ -2017,10 +2017,10 @@ async def resume_session(
             session._register_user_input_handler(on_user_input_request)
         if on_elicitation_request:
             session._register_elicitation_handler(on_elicitation_request)
-        if on_exit_plan_mode:
-            session._register_exit_plan_mode_handler(on_exit_plan_mode)
-        if on_auto_mode_switch:
-            session._register_auto_mode_switch_handler(on_auto_mode_switch)
+        if on_exit_plan_mode_request:
+            session._register_exit_plan_mode_handler(on_exit_plan_mode_request)
+        if on_auto_mode_switch_request:
+            session._register_auto_mode_switch_handler(on_auto_mode_switch_request)
         if hooks:
             session._register_hooks(hooks)
         if transform_callbacks:
@@ -2548,8 +2548,8 @@ def _convert_provider_to_wire_format(
             wire_provider["modelId"] = provider["model_id"]
         if "wire_model" in provider:
             wire_provider["wireModel"] = provider["wire_model"]
-        if "max_input_tokens" in provider:
-            wire_provider["maxPromptTokens"] = provider["max_input_tokens"]
+        if "max_prompt_tokens" in provider:
+            wire_provider["maxPromptTokens"] = provider["max_prompt_tokens"]
         if "max_output_tokens" in provider:
             wire_provider["maxOutputTokens"] = provider["max_output_tokens"]
         if "azure" in provider:

python/copilot/session.py

@@ -937,7 +937,7 @@ class ProviderConfig(TypedDict, total=False):
     # triggers conversation compaction before sending a request when the prompt
     # (system message, history, tool definitions, user message) would exceed
     # this limit.
-    max_input_tokens: int
+    max_prompt_tokens: int
     # Overrides the resolved model's default max output tokens. When hit, the
     # model stops generating and returns a truncated response.
     max_output_tokens: int
@@ -1027,9 +1027,9 @@ class SessionConfig(TypedDict, total=False):
     # When provided, the server calls back to this client for form-based UI dialogs.
     on_elicitation_request: ElicitationHandler
     # Handler for exit-plan-mode requests from the server.
-    on_exit_plan_mode: ExitPlanModeHandler
+    on_exit_plan_mode_request: ExitPlanModeHandler
     # Handler for auto-mode-switch requests from the server.
-    on_auto_mode_switch: AutoModeSwitchHandler
+    on_auto_mode_switch_request: AutoModeSwitchHandler
     # Handler factory for session-scoped sessionFs operations.
     create_session_fs_handler: CreateSessionFsHandler
 
@@ -1117,9 +1117,9 @@ class ResumeSessionConfig(TypedDict, total=False):
     # Handler for elicitation requests from the server.
     on_elicitation_request: ElicitationHandler
     # Handler for exit-plan-mode requests from the server.
-    on_exit_plan_mode: ExitPlanModeHandler
+    on_exit_plan_mode_request: ExitPlanModeHandler
     # Handler for auto-mode-switch requests from the server.
-    on_auto_mode_switch: AutoModeSwitchHandler
+    on_auto_mode_switch_request: AutoModeSwitchHandler
     # Handler factory for session-scoped sessionFs operations.
     create_session_fs_handler: CreateSessionFsHandler
 
@@ -2252,7 +2252,7 @@ async def _handle_hooks_invoke(self, hook_type: str, input_data: Any) -> Any:
             )
             return None
 
-    async def get_messages(self) -> list[SessionEvent]:
+    async def get_events(self) -> list[SessionEvent]:
         """
         Retrieve all events and messages from this session's history.
 
@@ -2267,7 +2267,7 @@ async def get_messages(self) -> list[SessionEvent]:
 
         Example:
             >>> from copilot.generated.session_events import AssistantMessageData
-            >>> events = await session.get_messages()
+            >>> events = await session.get_events()
             >>> for event in events:
             ...     match event.data:
             ...         case AssistantMessageData() as data:

python/e2e/test_error_resilience_e2e.py

@@ -30,7 +30,7 @@ async def test_should_throw_when_getting_messages_from_disconnected_session(
         await session.disconnect()
 
         with pytest.raises(Exception):
-            await session.get_messages()
+            await session.get_events()
 
     async def test_should_handle_double_abort_without_error(self, ctx: E2ETestContext):
         session = await ctx.client.create_session(

python/e2e/test_event_fidelity_e2e.py

@@ -207,7 +207,7 @@ async def test_should_preserve_message_order_in_getmessages_after_tool_use(
         try:
             await session.send_and_wait("Read the file 'order.txt' and tell me what the number is.")
 
-            messages = await session.get_messages()
+            messages = await session.get_events()
             types = [m.type.value for m in messages]
 
             # Verify complete event ordering contract:

python/e2e/test_mode_handlers_e2e.py

@@ -75,7 +75,7 @@ async def test_should_invoke_exit_plan_mode_handler_when_model_uses_tool(
     ):
         exit_plan_mode_requests = []
 
-        async def on_exit_plan_mode(request, invocation):
+        async def on_exit_plan_mode_request(request, invocation):
             exit_plan_mode_requests.append(request)
             assert invocation["session_id"] == session.session_id
             return {
@@ -87,7 +87,7 @@ async def on_exit_plan_mode(request, invocation):
         session = await mode_ctx.client.create_session(
             github_token=MODE_HANDLER_TOKEN,
             on_permission_request=PermissionHandler.approve_all,
-            on_exit_plan_mode=on_exit_plan_mode,
+            on_exit_plan_mode_request=on_exit_plan_mode_request,
         )
 
         try:
@@ -139,15 +139,15 @@ async def test_should_invoke_auto_mode_switch_handler_when_rate_limited(
     ):
         auto_mode_switch_requests = []
 
-        async def on_auto_mode_switch(request, invocation):
+        async def on_auto_mode_switch_request(request, invocation):
             auto_mode_switch_requests.append(request)
             assert invocation["session_id"] == session.session_id
             return "yes"
 
         session = await mode_ctx.client.create_session(
             github_token=MODE_HANDLER_TOKEN,
             on_permission_request=PermissionHandler.approve_all,
-            on_auto_mode_switch=on_auto_mode_switch,
+            on_auto_mode_switch_request=on_auto_mode_switch_request,
         )
 
         try:

python/e2e/test_pending_work_resume_e2e.py

@@ -481,7 +481,7 @@ async def blocking_external_tool(args):
                     )
 
                     # Verify resume event: continue_pending_work=False and session_was_active=True
-                    messages = await session2.get_messages()
+                    messages = await session2.get_events()
                     resume_events = [m for m in messages if isinstance(m.data, SessionResumeData)]
                     assert len(resume_events) == 1, "Expected exactly one session.resume event"
                     resume_event = resume_events[0]
@@ -549,7 +549,7 @@ async def test_should_report_continuependingwork_true_in_resume_event(
                     continue_pending_work=True,
                 )
 
-                messages = await resumed_session.get_messages()
+                messages = await resumed_session.get_events()
                 resume_events = [m for m in messages if isinstance(m.data, SessionResumeData)]
                 assert len(resume_events) == 1, "Expected exactly one session.resume event"
                 resume_event = resume_events[0]

python/e2e/test_rpc_event_side_effects_e2e.py

@@ -215,7 +215,7 @@ async def test_should_emit_snapshot_rewind_event_and_remove_events_on_truncate(
         try:
             await session.send_and_wait("Say SNAPSHOT_REWIND_TARGET exactly.", timeout=60.0)
 
-            events = await session.get_messages()
+            events = await session.get_events()
             user_msgs = [e for e in events if isinstance(e.data, UserMessageData)]
             assert len(user_msgs) >= 1
             first_user_event_id = str(user_msgs[0].id)
@@ -236,7 +236,7 @@ def on_event(event):
                 assert evt.data.events_removed >= 1
                 assert evt.data.up_to_event_id.lower() == first_user_event_id.lower()
 
-                messages_after = await session.get_messages()
+                messages_after = await session.get_events()
                 assert not any(e.id == user_msgs[0].id for e in messages_after)
             except Exception as exc:
                 if "unhandled method" in str(exc).lower():
@@ -257,7 +257,7 @@ async def test_should_allow_session_use_after_truncate(self, ctx: E2ETestContext
         try:
             await session.send_and_wait("Say SNAPSHOT_REWIND_TARGET exactly.", timeout=60.0)
 
-            events = await session.get_messages()
+            events = await session.get_events()
             user_msgs = [e for e in events if isinstance(e.data, UserMessageData)]
             assert len(user_msgs) >= 1
             first_user_event_id = str(user_msgs[0].id)

python/e2e/test_rpc_session_state_e2e.py

@@ -171,7 +171,7 @@ async def test_should_fork_session_with_persisted_messages(self, ctx: E2ETestCon
             assert initial_answer is not None
             assert "FORK_SOURCE_ALPHA" in (initial_answer.data.content or "")
 
-            source_messages = await session.get_messages()
+            source_messages = await session.get_events()
             source_conversation = _conversation_messages(source_messages)
             assert any(
                 role == "user" and content == source_prompt for role, content in source_conversation
@@ -192,18 +192,18 @@ async def test_should_fork_session_with_persisted_messages(self, ctx: E2ETestCon
                 on_permission_request=PermissionHandler.approve_all,
             )
             try:
-                forked_messages = await forked_session.get_messages()
+                forked_messages = await forked_session.get_events()
                 forked_conversation = _conversation_messages(forked_messages)
                 assert forked_conversation[: len(source_conversation)] == source_conversation
 
                 fork_answer = await forked_session.send_and_wait(fork_prompt, timeout=60.0)
                 assert fork_answer is not None
                 assert "FORK_CHILD_BETA" in (fork_answer.data.content or "")
 
-                source_after_fork = _conversation_messages(await session.get_messages())
+                source_after_fork = _conversation_messages(await session.get_events())
                 assert all(content != fork_prompt for _, content in source_after_fork)
 
-                fork_after_prompt = _conversation_messages(await forked_session.get_messages())
+                fork_after_prompt = _conversation_messages(await forked_session.get_events())
                 assert any(
                     role == "user" and content == fork_prompt for role, content in fork_after_prompt
                 )
@@ -241,7 +241,7 @@ async def test_should_handle_forking_session_without_persisted_events(
                 on_permission_request=PermissionHandler.approve_all,
             )
             try:
-                assert _conversation_messages(await forked_session.get_messages()) == []
+                assert _conversation_messages(await forked_session.get_events()) == []
             finally:
                 await forked_session.disconnect()
         finally:
@@ -506,7 +506,7 @@ async def test_should_fork_session_to_event_id_excluding_boundary_event(
             await session.send_and_wait(first_prompt, timeout=60.0)
             await session.send_and_wait(second_prompt, timeout=60.0)
 
-            source_events = await session.get_messages()
+            source_events = await session.get_events()
             second_user_event = next(
                 (
                     e
@@ -531,7 +531,7 @@ async def test_should_fork_session_to_event_id_excluding_boundary_event(
                 on_permission_request=PermissionHandler.approve_all,
             )
             try:
-                forked_events = await forked_session.get_messages()
+                forked_events = await forked_session.get_events()
                 forked_ids = {str(e.id) for e in forked_events}
                 assert boundary_event_id not in forked_ids, (
                     "toEventId is exclusive — boundary event must not be in forked session"

python/e2e/test_rpc_shell_and_fleet_e2e.py

@@ -128,7 +128,7 @@ def record_fleet_completion(invocation: ToolInvocation) -> ToolResult:
         async def _wait_for_messages(timeout: float = 120.0):
             deadline = asyncio.get_event_loop().time() + timeout
             while asyncio.get_event_loop().time() < deadline:
-                messages = await session.get_messages()
+                messages = await session.get_events()
                 if any(
                     isinstance(m.data, AssistantMessageData)
                     and "fleet task" in (m.data.content or "").lower()