fix(python): add timeout parameter to generated RPC methods (#681)

* fix(python): add timeout parameter to generated RPC methods

Every generated async RPC method now accepts an optional `timeout`
keyword argument that is forwarded to `JsonRpcClient.request()`.
This lets callers override the default 30s timeout for long-running
RPCs like `session.fleet.start` without bypassing the typed API.

Fixes #539

* test: cover no-params and server-scoped RPC timeout branches

Add tests for PlanApi.read (session, no params) and ModelsApi.list
(server, no params) to exercise all four codegen branches.

* fix: move _timeout_kwargs after quicktype imports, add server+params test

- Move _timeout_kwargs helper after the quicktype-generated import block
  to avoid duplicate Optional import and keep preamble conventional
- Add ToolsApi.list tests covering the server-scoped + params branch
- All four codegen branches now have test coverage

* style: fix ruff format in test_rpc_timeout.py

* fix: use float | None instead of Optional[float] in generated RPC

Optional is not imported in the generated rpc.py file. On Python 3.11
(used in CI), annotations are eagerly evaluated, so Optional[float]
would cause NameError at import time. Use the modern float | None
union syntax which requires no import and matches the rest of the
generated code.

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

* fix: wrap long docstring line in client.py to pass ruff E501

Pre-existing ruff line-length violation in get_last_session_id docstring
example that was failing CI on main.

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

* fix: resolve pre-existing CI failures in docs and ruff lint

- docs/guides/custom-agents.md: use typed enum constants instead of
  string literals for PermissionRequestResultKind (C# and Go examples)
- python/copilot/client.py: wrap long docstring line to satisfy E501

Both issues pre-exist on main and block all PR CI runs.

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

---------

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

Author: 3 people

docs/guides/custom-agents.md

@@ -121,7 +121,7 @@ session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
         },
     },
     OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (copilot.PermissionRequestResult, error) {
-        return copilot.PermissionRequestResult{Kind: "approved"}, nil
+        return copilot.PermissionRequestResult{Kind: copilot.PermissionRequestResultKindApproved}, nil
     },
 })
 ```
@@ -158,7 +158,7 @@ await using var session = await client.CreateSessionAsync(new SessionConfig
         },
     },
     OnPermissionRequest = (req, inv) =>
-        Task.FromResult(new PermissionRequestResult { Kind = "approved" }),
+        Task.FromResult(new PermissionRequestResult { Kind = PermissionRequestResultKind.Approved }),
 });
 ```
 

python/copilot/client.py

@@ -977,7 +977,8 @@ async def get_last_session_id(self) -> str | None:
         Example:
             >>> last_id = await client.get_last_session_id()
             >>> if last_id:
-            ...     session = await client.resume_session(last_id, {"on_permission_request": PermissionHandler.approve_all})
+            ...     config = {"on_permission_request": PermissionHandler.approve_all}
+            ...     session = await client.resume_session(last_id, config)
         """
         if not self._client:
             raise RuntimeError("Client not connected")

python/copilot/generated/rpc.py

@@ -1149,29 +1149,36 @@ def session_compaction_compact_result_to_dict(x: SessionCompactionCompactResult)
     return to_class(SessionCompactionCompactResult, x)
 
 
+def _timeout_kwargs(timeout: float | None) -> dict:
+    """Build keyword arguments for optional timeout forwarding."""
+    if timeout is not None:
+        return {"timeout": timeout}
+    return {}
+
+
 class ModelsApi:
     def __init__(self, client: "JsonRpcClient"):
         self._client = client
 
-    async def list(self) -> ModelsListResult:
-        return ModelsListResult.from_dict(await self._client.request("models.list", {}))
+    async def list(self, *, timeout: float | None = None) -> ModelsListResult:
+        return ModelsListResult.from_dict(await self._client.request("models.list", {}, **_timeout_kwargs(timeout)))
 
 
 class ToolsApi:
     def __init__(self, client: "JsonRpcClient"):
         self._client = client
 
-    async def list(self, params: ToolsListParams) -> ToolsListResult:
+    async def list(self, params: ToolsListParams, *, timeout: float | None = None) -> ToolsListResult:
         params_dict = {k: v for k, v in params.to_dict().items() if v is not None}
-        return ToolsListResult.from_dict(await self._client.request("tools.list", params_dict))
+        return ToolsListResult.from_dict(await self._client.request("tools.list", params_dict, **_timeout_kwargs(timeout)))
 
 
 class AccountApi:
     def __init__(self, client: "JsonRpcClient"):
         self._client = client
 
-    async def get_quota(self) -> AccountGetQuotaResult:
-        return AccountGetQuotaResult.from_dict(await self._client.request("account.getQuota", {}))
+    async def get_quota(self, *, timeout: float | None = None) -> AccountGetQuotaResult:
+        return AccountGetQuotaResult.from_dict(await self._client.request("account.getQuota", {}, **_timeout_kwargs(timeout)))
 
 
 class ServerRpc:
@@ -1182,113 +1189,113 @@ def __init__(self, client: "JsonRpcClient"):
         self.tools = ToolsApi(client)
         self.account = AccountApi(client)
 
-    async def ping(self, params: PingParams) -> PingResult:
+    async def ping(self, params: PingParams, *, timeout: float | None = None) -> PingResult:
         params_dict = {k: v for k, v in params.to_dict().items() if v is not None}
-        return PingResult.from_dict(await self._client.request("ping", params_dict))
+        return PingResult.from_dict(await self._client.request("ping", params_dict, **_timeout_kwargs(timeout)))
 
 
 class ModelApi:
     def __init__(self, client: "JsonRpcClient", session_id: str):
         self._client = client
         self._session_id = session_id
 
-    async def get_current(self) -> SessionModelGetCurrentResult:
-        return SessionModelGetCurrentResult.from_dict(await self._client.request("session.model.getCurrent", {"sessionId": self._session_id}))
+    async def get_current(self, *, timeout: float | None = None) -> SessionModelGetCurrentResult:
+        return SessionModelGetCurrentResult.from_dict(await self._client.request("session.model.getCurrent", {"sessionId": self._session_id}, **_timeout_kwargs(timeout)))
 
-    async def switch_to(self, params: SessionModelSwitchToParams) -> SessionModelSwitchToResult:
+    async def switch_to(self, params: SessionModelSwitchToParams, *, timeout: float | None = None) -> SessionModelSwitchToResult:
         params_dict = {k: v for k, v in params.to_dict().items() if v is not None}
         params_dict["sessionId"] = self._session_id
-        return SessionModelSwitchToResult.from_dict(await self._client.request("session.model.switchTo", params_dict))
+        return SessionModelSwitchToResult.from_dict(await self._client.request("session.model.switchTo", params_dict, **_timeout_kwargs(timeout)))
 
 
 class ModeApi:
     def __init__(self, client: "JsonRpcClient", session_id: str):
         self._client = client
         self._session_id = session_id
 
-    async def get(self) -> SessionModeGetResult:
-        return SessionModeGetResult.from_dict(await self._client.request("session.mode.get", {"sessionId": self._session_id}))
+    async def get(self, *, timeout: float | None = None) -> SessionModeGetResult:
+        return SessionModeGetResult.from_dict(await self._client.request("session.mode.get", {"sessionId": self._session_id}, **_timeout_kwargs(timeout)))
 
-    async def set(self, params: SessionModeSetParams) -> SessionModeSetResult:
+    async def set(self, params: SessionModeSetParams, *, timeout: float | None = None) -> SessionModeSetResult:
         params_dict = {k: v for k, v in params.to_dict().items() if v is not None}
         params_dict["sessionId"] = self._session_id
-        return SessionModeSetResult.from_dict(await self._client.request("session.mode.set", params_dict))
+        return SessionModeSetResult.from_dict(await self._client.request("session.mode.set", params_dict, **_timeout_kwargs(timeout)))
 
 
 class PlanApi:
     def __init__(self, client: "JsonRpcClient", session_id: str):
         self._client = client
         self._session_id = session_id
 
-    async def read(self) -> SessionPlanReadResult:
-        return SessionPlanReadResult.from_dict(await self._client.request("session.plan.read", {"sessionId": self._session_id}))
+    async def read(self, *, timeout: float | None = None) -> SessionPlanReadResult:
+        return SessionPlanReadResult.from_dict(await self._client.request("session.plan.read", {"sessionId": self._session_id}, **_timeout_kwargs(timeout)))
 
-    async def update(self, params: SessionPlanUpdateParams) -> SessionPlanUpdateResult:
+    async def update(self, params: SessionPlanUpdateParams, *, timeout: float | None = None) -> SessionPlanUpdateResult:
         params_dict = {k: v for k, v in params.to_dict().items() if v is not None}
         params_dict["sessionId"] = self._session_id
-        return SessionPlanUpdateResult.from_dict(await self._client.request("session.plan.update", params_dict))
+        return SessionPlanUpdateResult.from_dict(await self._client.request("session.plan.update", params_dict, **_timeout_kwargs(timeout)))
 
-    async def delete(self) -> SessionPlanDeleteResult:
-        return SessionPlanDeleteResult.from_dict(await self._client.request("session.plan.delete", {"sessionId": self._session_id}))
+    async def delete(self, *, timeout: float | None = None) -> SessionPlanDeleteResult:
+        return SessionPlanDeleteResult.from_dict(await self._client.request("session.plan.delete", {"sessionId": self._session_id}, **_timeout_kwargs(timeout)))
 
 
 class WorkspaceApi:
     def __init__(self, client: "JsonRpcClient", session_id: str):
         self._client = client
         self._session_id = session_id
 
-    async def list_files(self) -> SessionWorkspaceListFilesResult:
-        return SessionWorkspaceListFilesResult.from_dict(await self._client.request("session.workspace.listFiles", {"sessionId": self._session_id}))
+    async def list_files(self, *, timeout: float | None = None) -> SessionWorkspaceListFilesResult:
+        return SessionWorkspaceListFilesResult.from_dict(await self._client.request("session.workspace.listFiles", {"sessionId": self._session_id}, **_timeout_kwargs(timeout)))
 
-    async def read_file(self, params: SessionWorkspaceReadFileParams) -> SessionWorkspaceReadFileResult:
+    async def read_file(self, params: SessionWorkspaceReadFileParams, *, timeout: float | None = None) -> SessionWorkspaceReadFileResult:
         params_dict = {k: v for k, v in params.to_dict().items() if v is not None}
         params_dict["sessionId"] = self._session_id
-        return SessionWorkspaceReadFileResult.from_dict(await self._client.request("session.workspace.readFile", params_dict))
+        return SessionWorkspaceReadFileResult.from_dict(await self._client.request("session.workspace.readFile", params_dict, **_timeout_kwargs(timeout)))
 
-    async def create_file(self, params: SessionWorkspaceCreateFileParams) -> SessionWorkspaceCreateFileResult:
+    async def create_file(self, params: SessionWorkspaceCreateFileParams, *, timeout: float | None = None) -> SessionWorkspaceCreateFileResult:
         params_dict = {k: v for k, v in params.to_dict().items() if v is not None}
         params_dict["sessionId"] = self._session_id
-        return SessionWorkspaceCreateFileResult.from_dict(await self._client.request("session.workspace.createFile", params_dict))
+        return SessionWorkspaceCreateFileResult.from_dict(await self._client.request("session.workspace.createFile", params_dict, **_timeout_kwargs(timeout)))
 
 
 class FleetApi:
     def __init__(self, client: "JsonRpcClient", session_id: str):
         self._client = client
         self._session_id = session_id
 
-    async def start(self, params: SessionFleetStartParams) -> SessionFleetStartResult:
+    async def start(self, params: SessionFleetStartParams, *, timeout: float | None = None) -> SessionFleetStartResult:
         params_dict = {k: v for k, v in params.to_dict().items() if v is not None}
         params_dict["sessionId"] = self._session_id
-        return SessionFleetStartResult.from_dict(await self._client.request("session.fleet.start", params_dict))
+        return SessionFleetStartResult.from_dict(await self._client.request("session.fleet.start", params_dict, **_timeout_kwargs(timeout)))
 
 
 class AgentApi:
     def __init__(self, client: "JsonRpcClient", session_id: str):
         self._client = client
         self._session_id = session_id
 
-    async def list(self) -> SessionAgentListResult:
-        return SessionAgentListResult.from_dict(await self._client.request("session.agent.list", {"sessionId": self._session_id}))
+    async def list(self, *, timeout: float | None = None) -> SessionAgentListResult:
+        return SessionAgentListResult.from_dict(await self._client.request("session.agent.list", {"sessionId": self._session_id}, **_timeout_kwargs(timeout)))
 
-    async def get_current(self) -> SessionAgentGetCurrentResult:
-        return SessionAgentGetCurrentResult.from_dict(await self._client.request("session.agent.getCurrent", {"sessionId": self._session_id}))
+    async def get_current(self, *, timeout: float | None = None) -> SessionAgentGetCurrentResult:
+        return SessionAgentGetCurrentResult.from_dict(await self._client.request("session.agent.getCurrent", {"sessionId": self._session_id}, **_timeout_kwargs(timeout)))
 
-    async def select(self, params: SessionAgentSelectParams) -> SessionAgentSelectResult:
+    async def select(self, params: SessionAgentSelectParams, *, timeout: float | None = None) -> SessionAgentSelectResult:
         params_dict = {k: v for k, v in params.to_dict().items() if v is not None}
         params_dict["sessionId"] = self._session_id
-        return SessionAgentSelectResult.from_dict(await self._client.request("session.agent.select", params_dict))
+        return SessionAgentSelectResult.from_dict(await self._client.request("session.agent.select", params_dict, **_timeout_kwargs(timeout)))
 
-    async def deselect(self) -> SessionAgentDeselectResult:
-        return SessionAgentDeselectResult.from_dict(await self._client.request("session.agent.deselect", {"sessionId": self._session_id}))
+    async def deselect(self, *, timeout: float | None = None) -> SessionAgentDeselectResult:
+        return SessionAgentDeselectResult.from_dict(await self._client.request("session.agent.deselect", {"sessionId": self._session_id}, **_timeout_kwargs(timeout)))
 
 
 class CompactionApi:
     def __init__(self, client: "JsonRpcClient", session_id: str):
         self._client = client
         self._session_id = session_id
 
-    async def compact(self) -> SessionCompactionCompactResult:
-        return SessionCompactionCompactResult.from_dict(await self._client.request("session.compaction.compact", {"sessionId": self._session_id}))
+    async def compact(self, *, timeout: float | None = None) -> SessionCompactionCompactResult:
+        return SessionCompactionCompactResult.from_dict(await self._client.request("session.compaction.compact", {"sessionId": self._session_id}, **_timeout_kwargs(timeout)))
 
 
 class SessionRpc:

python/test_rpc_timeout.py

@@ -0,0 +1,134 @@
+"""Tests for timeout parameter on generated RPC methods."""
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from copilot.generated.rpc import (
+    FleetApi,
+    Mode,
+    ModeApi,
+    ModelsApi,
+    PlanApi,
+    SessionFleetStartParams,
+    SessionModeSetParams,
+    ToolsApi,
+    ToolsListParams,
+)
+
+
+class TestRpcTimeout:
+    """Tests for timeout forwarding across all four codegen branches:
+    - session-scoped with params
+    - session-scoped without params
+    - server-scoped with params
+    - server-scoped without params
+    """
+
+    # ── session-scoped, with params ──────────────────────────────────
+
+    @pytest.mark.asyncio
+    async def test_default_timeout_not_forwarded(self):
+        client = AsyncMock()
+        client.request = AsyncMock(return_value={"started": True})
+        api = FleetApi(client, "sess-1")
+
+        await api.start(SessionFleetStartParams(prompt="go"))
+
+        client.request.assert_called_once()
+        _, kwargs = client.request.call_args
+        assert "timeout" not in kwargs
+
+    @pytest.mark.asyncio
+    async def test_custom_timeout_forwarded(self):
+        client = AsyncMock()
+        client.request = AsyncMock(return_value={"started": True})
+        api = FleetApi(client, "sess-1")
+
+        await api.start(SessionFleetStartParams(prompt="go"), timeout=600.0)
+
+        _, kwargs = client.request.call_args
+        assert kwargs["timeout"] == 600.0
+
+    @pytest.mark.asyncio
+    async def test_timeout_on_session_params_method(self):
+        client = AsyncMock()
+        client.request = AsyncMock(return_value={"mode": "plan"})
+        api = ModeApi(client, "sess-1")
+
+        await api.set(SessionModeSetParams(mode=Mode.PLAN), timeout=120.0)
+
+        _, kwargs = client.request.call_args
+        assert kwargs["timeout"] == 120.0
+
+    # ── session-scoped, no params ────────────────────────────────────
+
+    @pytest.mark.asyncio
+    async def test_timeout_on_session_no_params_method(self):
+        client = AsyncMock()
+        client.request = AsyncMock(return_value={"exists": True})
+        api = PlanApi(client, "sess-1")
+
+        await api.read(timeout=90.0)
+
+        _, kwargs = client.request.call_args
+        assert kwargs["timeout"] == 90.0
+
+    @pytest.mark.asyncio
+    async def test_default_timeout_on_session_no_params_method(self):
+        client = AsyncMock()
+        client.request = AsyncMock(return_value={"exists": True})
+        api = PlanApi(client, "sess-1")
+
+        await api.read()
+
+        _, kwargs = client.request.call_args
+        assert "timeout" not in kwargs
+
+    # ── server-scoped, with params ─────────────────────────────────────
+
+    @pytest.mark.asyncio
+    async def test_timeout_on_server_params_method(self):
+        client = AsyncMock()
+        client.request = AsyncMock(return_value={"tools": []})
+        api = ToolsApi(client)
+
+        await api.list(ToolsListParams(), timeout=60.0)
+
+        _, kwargs = client.request.call_args
+        assert kwargs["timeout"] == 60.0
+
+    @pytest.mark.asyncio
+    async def test_default_timeout_on_server_params_method(self):
+        client = AsyncMock()
+        client.request = AsyncMock(return_value={"tools": []})
+        api = ToolsApi(client)
+
+        await api.list(ToolsListParams())
+
+        _, kwargs = client.request.call_args
+        assert "timeout" not in kwargs
+
+    # ── server-scoped, no params ─────────────────────────────────────
+
+    @pytest.mark.asyncio
+    async def test_timeout_on_server_no_params_method(self):
+        client = AsyncMock()
+        client.request = AsyncMock(return_value={"models": []})
+        api = ModelsApi(client)
+
+        await api.list(timeout=45.0)
+
+        _, kwargs = client.request.call_args
+        assert kwargs["timeout"] == 45.0
+
+    @pytest.mark.asyncio
+    async def test_default_timeout_on_server_no_params_method(self):
+        client = AsyncMock()
+        client.request = AsyncMock(return_value={"models": []})
+        api = ModelsApi(client)
+
+        await api.list()
+
+        _, kwargs = client.request.call_args
+        assert "timeout" not in kwargs