fix(agent_runtime): paginate workspace lookup & avoid input mutation

Address two issues raised in PR #102 review by Ohyee:

1. Workspace lookup was hardcoded to a single page (page_size=50). If
   the upstream `name=` filter is server-side prefix/fuzzy match, a busy
   account can easily exceed 50 same-prefix workspaces and the resolver
   would silently miss the target. `_lookup_sync` / `_lookup_async` now
   paginate, accumulating candidates across pages and short-circuiting
   when a page returns fewer than `_PAGE_SIZE` rows; a `_MAX_PAGES=20`
   safety cap (1000 candidates) prevents runaway loops on misbehaving
   upstreams.

2. The workspace_name resolution path mutated the caller's input object
   (`input.workspace_id = ...; input.workspace_name = None`), which is
   surprising for a side-effect-free convenience field. Replaced with
   `input = input.model_copy(update={...})` so the caller's instance is
   untouched. Applied to create / create_async / list / list_async in
   client.py and mirrored into the codegen template.

Tests:
- 4 new pagination cases (multi-page accumulation, short-page early
  stop, MAX_PAGES cap, async multi-page).
- 4 existing mutation assertions flipped to "caller's input stays
  unchanged; OpenAPI request carries the resolved id".

agent_runtime suite 266 passed / 2 skipped; `_workspace.py` 95.62%
line/branch. Full repo 3481 passed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Sodawyx <sodawyx@126.com>

Author: Sodawyx

agentrun/agent_runtime/__client_async_template.py

@@ -90,10 +90,12 @@ async def create_async(
             )
         if input.workspace_name is not None:
             cfg = Config.with_configs(self.config, config)
-            input.workspace_id = await resolve_workspace_id_by_name_async(
+            resolved_id = await resolve_workspace_id_by_name_async(
                 input.workspace_name, cfg
             )
-            input.workspace_name = None
+            input = input.model_copy(
+                update={"workspace_id": resolved_id, "workspace_name": None}
+            )
 
         if input.network_configuration is None:
             input.network_configuration = NetworkConfig()
@@ -244,20 +246,22 @@ async def list_async(
                 )
             if input.workspace_name is not None or input.workspace_names:
                 cfg = Config.with_configs(self.config, config)
+                update: dict = {}
                 if input.workspace_name is not None:
-                    input.workspace_id = (
+                    update["workspace_id"] = (
                         await resolve_workspace_id_by_name_async(
                             input.workspace_name, cfg
                         )
                     )
-                    input.workspace_name = None
+                    update["workspace_name"] = None
                 if input.workspace_names:
-                    input.workspace_ids = (
+                    update["workspace_ids"] = (
                         await resolve_workspace_ids_by_names_async(
                             input.workspace_names, cfg
                         )
                     )
-                    input.workspace_names = None
+                    update["workspace_names"] = None
+                input = input.model_copy(update=update)
 
             results = await self.__control_api.list_agent_runtimes_async(
                 ListAgentRuntimesRequest().from_map(input.model_dump()),

agentrun/agent_runtime/_workspace.py

@@ -30,6 +30,13 @@
 # Value 为解析得到的 workspace_id。
 _RESOLVE_CACHE: Dict[Tuple[str, str, str], str] = {}
 
+# 翻页参数：ListWorkspaces 的 name= 参数在服务端可能是 prefix/fuzzy 匹配，
+# 单页 50 条不足以覆盖海量同前缀场景，因此累积所有页再做 exact match。
+_PAGE_SIZE = 50
+# 安全上限：避免上游异常导致死循环；20 页 × 50 条 = 1000 个候选，
+# 同名 / 同前缀 workspace 远超该值的概率极低。
+_MAX_PAGES = 20
+
 
 def _cache_key(cfg: Config, name: str) -> Tuple[str, str, str]:
     return (
@@ -113,35 +120,69 @@ def _lookup_sync(
         self, name: str, config: Optional[Config] = None
     ) -> Optional[Workspace]:
         client = self._get_client(config)
+        accumulated: List[Workspace] = []
+        page_number = 1
         try:
-            response = client.list_workspaces(
-                ListWorkspacesRequest(name=name, page_size="50")
-            )
+            while page_number <= _MAX_PAGES:
+                response = client.list_workspaces(
+                    ListWorkspacesRequest(
+                        name=name,
+                        page_size=str(_PAGE_SIZE),
+                        page_number=str(page_number),
+                    )
+                )
+                workspaces = (
+                    getattr(
+                        getattr(response.body, "data", None),
+                        "workspaces",
+                        None,
+                    )
+                    or []
+                )
+                if not workspaces:
+                    break
+                accumulated.extend(workspaces)
+                if len(workspaces) < _PAGE_SIZE:
+                    break
+                page_number += 1
         except (ClientException, ServerException) as e:
             _raise_for_tea_exception(e)
             raise
-        workspaces = (
-            getattr(getattr(response.body, "data", None), "workspaces", None)
-            or []
-        )
-        return _pick_exact_match(workspaces, name)
+        return _pick_exact_match(accumulated, name)
 
     async def _lookup_async(
         self, name: str, config: Optional[Config] = None
     ) -> Optional[Workspace]:
         client = self._get_client(config)
+        accumulated: List[Workspace] = []
+        page_number = 1
         try:
-            response = await client.list_workspaces_async(
-                ListWorkspacesRequest(name=name, page_size="50")
-            )
+            while page_number <= _MAX_PAGES:
+                response = await client.list_workspaces_async(
+                    ListWorkspacesRequest(
+                        name=name,
+                        page_size=str(_PAGE_SIZE),
+                        page_number=str(page_number),
+                    )
+                )
+                workspaces = (
+                    getattr(
+                        getattr(response.body, "data", None),
+                        "workspaces",
+                        None,
+                    )
+                    or []
+                )
+                if not workspaces:
+                    break
+                accumulated.extend(workspaces)
+                if len(workspaces) < _PAGE_SIZE:
+                    break
+                page_number += 1
         except (ClientException, ServerException) as e:
             _raise_for_tea_exception(e)
             raise
-        workspaces = (
-            getattr(getattr(response.body, "data", None), "workspaces", None)
-            or []
-        )
-        return _pick_exact_match(workspaces, name)
+        return _pick_exact_match(accumulated, name)
 
 
 def resolve_workspace_id_by_name(

agentrun/agent_runtime/client.py

@@ -100,10 +100,12 @@ async def create_async(
             )
         if input.workspace_name is not None:
             cfg = Config.with_configs(self.config, config)
-            input.workspace_id = await resolve_workspace_id_by_name_async(
+            resolved_id = await resolve_workspace_id_by_name_async(
                 input.workspace_name, cfg
             )
-            input.workspace_name = None
+            input = input.model_copy(
+                update={"workspace_id": resolved_id, "workspace_name": None}
+            )
 
         if input.network_configuration is None:
             input.network_configuration = NetworkConfig()
@@ -159,10 +161,12 @@ def create(
             )
         if input.workspace_name is not None:
             cfg = Config.with_configs(self.config, config)
-            input.workspace_id = resolve_workspace_id_by_name(
+            resolved_id = resolve_workspace_id_by_name(
                 input.workspace_name, cfg
             )
-            input.workspace_name = None
+            input = input.model_copy(
+                update={"workspace_id": resolved_id, "workspace_name": None}
+            )
 
         if input.network_configuration is None:
             input.network_configuration = NetworkConfig()
@@ -394,20 +398,22 @@ async def list_async(
                 )
             if input.workspace_name is not None or input.workspace_names:
                 cfg = Config.with_configs(self.config, config)
+                update: dict = {}
                 if input.workspace_name is not None:
-                    input.workspace_id = (
+                    update["workspace_id"] = (
                         await resolve_workspace_id_by_name_async(
                             input.workspace_name, cfg
                         )
                     )
-                    input.workspace_name = None
+                    update["workspace_name"] = None
                 if input.workspace_names:
-                    input.workspace_ids = (
+                    update["workspace_ids"] = (
                         await resolve_workspace_ids_by_names_async(
                             input.workspace_names, cfg
                         )
                     )
-                    input.workspace_names = None
+                    update["workspace_names"] = None
+                input = input.model_copy(update=update)
 
             results = await self.__control_api.list_agent_runtimes_async(
                 ListAgentRuntimesRequest().from_map(input.model_dump()),
@@ -458,16 +464,18 @@ def list(
                 )
             if input.workspace_name is not None or input.workspace_names:
                 cfg = Config.with_configs(self.config, config)
+                update: dict = {}
                 if input.workspace_name is not None:
-                    input.workspace_id = resolve_workspace_id_by_name(
+                    update["workspace_id"] = resolve_workspace_id_by_name(
                         input.workspace_name, cfg
                     )
-                    input.workspace_name = None
+                    update["workspace_name"] = None
                 if input.workspace_names:
-                    input.workspace_ids = resolve_workspace_ids_by_names(
+                    update["workspace_ids"] = resolve_workspace_ids_by_names(
                         input.workspace_names, cfg
                     )
-                    input.workspace_names = None
+                    update["workspace_names"] = None
+                input = input.model_copy(update=update)
 
             results = self.__control_api.list_agent_runtimes(
                 ListAgentRuntimesRequest().from_map(input.model_dump()),

tests/unittests/agent_runtime/test_workspace.py

@@ -242,6 +242,81 @@ def test_resolve_many_async(self, monkeypatch):
         assert result == "ws-a,ws-b"
 
 
+class TestResolveWorkspacePagination:
+    """翻页累积：避免 server-side name 模糊匹配下 50 条单页漏匹配。"""
+
+    def test_paginates_until_exact_match_across_pages(self, monkeypatch):
+        # 第 1 页 50 条都是前缀匹配但非 exact；第 2 页才含 exact，必须翻页
+        page1 = [_make_ws(f"my-ws-{i}", f"ws-p1-{i}") for i in range(50)]
+        page2 = [_make_ws("my-ws", "ws-target"), _make_ws("my-ws-x", "ws-x")]
+        client = MagicMock()
+        client.list_workspaces.side_effect = [
+            _make_response(page1),
+            _make_response(page2),
+        ]
+        monkeypatch.setattr(
+            ws_mod._WorkspaceResolver,
+            "_get_client",
+            lambda self, config=None: client,
+        )
+        assert resolve_workspace_id_by_name("my-ws") == "ws-target"
+        # 必须翻到第二页才能找到，因此至少 2 次调用
+        assert client.list_workspaces.call_count == 2
+        # page_number 应该递增
+        calls = client.list_workspaces.call_args_list
+        assert calls[0].args[0].page_number == "1"
+        assert calls[1].args[0].page_number == "2"
+
+    def test_short_page_breaks_pagination_early(self, monkeypatch):
+        # 单页返回 < page_size 即视为末页，不再翻页
+        client = MagicMock()
+        client.list_workspaces.return_value = _make_response(
+            [_make_ws("my-ws", "ws-1")]
+        )
+        monkeypatch.setattr(
+            ws_mod._WorkspaceResolver,
+            "_get_client",
+            lambda self, config=None: client,
+        )
+        assert resolve_workspace_id_by_name("my-ws") == "ws-1"
+        # 仅查 1 页就停（mock 返回 1 条 < 50）
+        assert client.list_workspaces.call_count == 1
+
+    def test_pagination_respects_max_pages_cap(self, monkeypatch):
+        # 异常情况：上游一直返回满页（不存在 exact match），
+        # 必须在 _MAX_PAGES 处停止，避免死循环。
+        full_page = [_make_ws(f"prefix-{i}", f"id-{i}") for i in range(50)]
+        client = MagicMock()
+        client.list_workspaces.return_value = _make_response(full_page)
+        monkeypatch.setattr(
+            ws_mod._WorkspaceResolver,
+            "_get_client",
+            lambda self, config=None: client,
+        )
+        with pytest.raises(ResourceNotExistError):
+            resolve_workspace_id_by_name("absent-target")
+        # 不应超过安全上限
+        assert client.list_workspaces.call_count == ws_mod._MAX_PAGES
+
+    def test_async_paginates_across_pages(self, monkeypatch):
+        page1 = [_make_ws(f"my-ws-{i}", f"ws-p1-{i}") for i in range(50)]
+        page2 = [_make_ws("my-ws", "ws-target-async")]
+        client = MagicMock()
+        client.list_workspaces_async = AsyncMock(
+            side_effect=[_make_response(page1), _make_response(page2)]
+        )
+        monkeypatch.setattr(
+            ws_mod._WorkspaceResolver,
+            "_get_client",
+            lambda self, config=None: client,
+        )
+        assert (
+            asyncio.run(resolve_workspace_id_by_name_async("my-ws"))
+            == "ws-target-async"
+        )
+        assert client.list_workspaces_async.await_count == 2
+
+
 class TestClientCreateWorkspaceResolution:
     """create 集成测试：workspace_name 自动转换为 workspace_id"""
 
@@ -282,9 +357,13 @@ def test_create_with_workspace_name_resolves(
         args, _ = mock_resolve.call_args
         assert args[0] == "my-ws"
         assert isinstance(args[1], Config)
-        # 调用 API 前，应把 workspace_name 清空且 workspace_id 写好
-        assert inp.workspace_id == "ws-resolved"
-        assert inp.workspace_name is None
+        # 调用方传入的 input 对象不应被 mutate
+        assert inp.workspace_id is None
+        assert inp.workspace_name == "my-ws"
+        # OpenAPI 收到的对象应带解析后的 workspace_id（workspace_name
+        # 是 SDK 侧便利字段，OpenAPI 模型本就没有）
+        api_input = mock_control_api.create_agent_runtime.call_args.args[0]
+        assert api_input.workspace_id == "ws-resolved"
 
     @patch(CONTROL_API_PATH)
     def test_create_rejects_both_workspace_fields(self, mock_control_api_class):
@@ -341,8 +420,13 @@ def test_create_async_resolves_workspace_name(
         args, _ = mock_resolve_async.call_args
         assert args[0] == "my-ws"
         assert isinstance(args[1], Config)
-        assert inp.workspace_id == "ws-resolved-async"
-        assert inp.workspace_name is None
+        # 调用方传入的 input 对象不应被 mutate
+        assert inp.workspace_id is None
+        assert inp.workspace_name == "my-ws"
+        api_input = mock_control_api.create_agent_runtime_async.call_args.args[
+            0
+        ]
+        assert api_input.workspace_id == "ws-resolved-async"
 
 
 class TestClientListWorkspaceResolution:
@@ -386,10 +470,15 @@ def test_list_resolves_workspace_name_and_names(
         many_args, _ = mock_resolve_many.call_args
         assert many_args[0] == "ws-a,ws-b"
         assert isinstance(many_args[1], Config)
-        assert inp.workspace_id == "ws-1"
-        assert inp.workspace_ids == "ws-1,ws-2"
-        assert inp.workspace_name is None
-        assert inp.workspace_names is None
+        # 调用方传入的 input 对象不应被 mutate
+        assert inp.workspace_id is None
+        assert inp.workspace_ids is None
+        assert inp.workspace_name == "my-ws"
+        assert inp.workspace_names == "ws-a,ws-b"
+        # OpenAPI 收到的对象应带解析后的 ID
+        api_input = mock_control_api.list_agent_runtimes.call_args.args[0]
+        assert api_input.workspace_id == "ws-1"
+        assert api_input.workspace_ids == "ws-1,ws-2"
 
     @patch(CONTROL_API_PATH)
     def test_list_rejects_both_singular(self, mock_control_api_class):
@@ -461,8 +550,14 @@ def test_list_async_resolves(
         many_args, _ = mock_resolve_many_async.call_args
         assert many_args[0] == "ws-a,ws-b"
         assert isinstance(many_args[1], Config)
-        assert inp.workspace_id == "ws-1"
-        assert inp.workspace_ids == "ws-1,ws-2"
+        # 调用方传入的 input 对象不应被 mutate
+        assert inp.workspace_id is None
+        assert inp.workspace_ids is None
+        assert inp.workspace_name == "my-ws"
+        assert inp.workspace_names == "ws-a,ws-b"
+        api_input = mock_control_api.list_agent_runtimes_async.call_args.args[0]
+        assert api_input.workspace_id == "ws-1"
+        assert api_input.workspace_ids == "ws-1,ws-2"
 
 
 class TestClientEffectiveConfig: