fix(app-server): clarify command control APIs

Author: gersmann

codex/app_server/_async_services.py

@@ -377,16 +377,26 @@ async def write_stdin(
         )
         return await self._rpc.request_typed("command/exec/write", params, EmptyResult)
 
-    async def resize(
+    async def resize_terminal(
         self,
         *,
         process_id: str,
         size: protocol.CommandExecTerminalSize,
     ) -> EmptyResult:
+        """Resize the terminal attached to a running `command/exec` process.
+
+        This wraps the app-server `command/exec/resize` request and sends the
+        new terminal dimensions as `cols` and `rows`.
+        """
         params = protocol.CommandExecResizeParams(processId=process_id, size=size)
         return await self._rpc.request_typed("command/exec/resize", params, EmptyResult)
 
-    async def terminate(self, *, process_id: str) -> EmptyResult:
+    async def terminate_process(self, *, process_id: str) -> EmptyResult:
+        """Terminate a running `command/exec` process.
+
+        This wraps the app-server `command/exec/terminate` request for the
+        client-supplied process id.
+        """
         params = protocol.CommandExecTerminateParams(processId=process_id)
         return await self._rpc.request_typed("command/exec/terminate", params, EmptyResult)
 

codex/app_server/_sync_services.py

@@ -206,14 +206,14 @@ async def write_stdin(
         delta_base64: str | None = None,
     ) -> EmptyResult: ...
 
-    async def resize(
+    async def resize_terminal(
         self,
         *,
         process_id: str,
         size: protocol.CommandExecTerminalSize,
     ) -> EmptyResult: ...
 
-    async def terminate(self, *, process_id: str) -> EmptyResult: ...
+    async def terminate_process(self, *, process_id: str) -> EmptyResult: ...
 
 
 class _AsyncExternalAgentConfigClientLike(Protocol):
@@ -609,16 +609,26 @@ def write_stdin(
             )
         )
 
-    def resize(
+    def resize_terminal(
         self,
         *,
         process_id: str,
         size: protocol.CommandExecTerminalSize,
     ) -> EmptyResult:
-        return self._run(self._async_client.resize(process_id=process_id, size=size))
+        """Resize the terminal attached to a running `command/exec` process.
 
-    def terminate(self, *, process_id: str) -> EmptyResult:
-        return self._run(self._async_client.terminate(process_id=process_id))
+        This wraps the app-server `command/exec/resize` request and sends the
+        new terminal dimensions as `cols` and `rows`.
+        """
+        return self._run(self._async_client.resize_terminal(process_id=process_id, size=size))
+
+    def terminate_process(self, *, process_id: str) -> EmptyResult:
+        """Terminate a running `command/exec` process.
+
+        This wraps the app-server `command/exec/terminate` request for the
+        client-supplied process id.
+        """
+        return self._run(self._async_client.terminate_process(process_id=process_id))
 
 
 class _ExternalAgentConfigClient(_SyncRunner):

tests/test_app_server_client.py

@@ -1943,11 +1943,11 @@ def command_terminate(message: JsonObject) -> JsonObject:
             delta_base64="aGVsbG8K",
             close_stdin=True,
         )
-        resized = await client.command.resize(
+        resized = await client.command.resize_terminal(
             process_id="proc-1",
             size=protocol.CommandExecTerminalSize(cols=100, rows=30),
         )
-        terminated = await client.command.terminate(process_id="proc-1")
+        terminated = await client.command.terminate_process(process_id="proc-1")
 
         assert result.exit_code == 0
         assert wrote == EmptyResult()
@@ -2595,11 +2595,19 @@ def login_account(message: JsonObject) -> JsonObject:
         assert client.command.write_stdin.__doc__ is not None
         assert "command/exec/write" in client.command.write_stdin.__doc__
         assert "stdin" in client.command.write_stdin.__doc__
-        assert tuple(inspect.signature(client.command.resize).parameters) == (
+        assert tuple(inspect.signature(client.command.resize_terminal).parameters) == (
             "process_id",
             "size",
         )
-        assert tuple(inspect.signature(client.command.terminate).parameters) == ("process_id",)
+        assert client.command.resize_terminal.__doc__ is not None
+        assert "command/exec/resize" in client.command.resize_terminal.__doc__
+        assert "terminal" in client.command.resize_terminal.__doc__
+        assert tuple(inspect.signature(client.command.terminate_process).parameters) == (
+            "process_id",
+        )
+        assert client.command.terminate_process.__doc__ is not None
+        assert "command/exec/terminate" in client.command.terminate_process.__doc__
+        assert "process" in client.command.terminate_process.__doc__
         assert tuple(inspect.signature(client.account.login_chatgpt_tokens).parameters) == (
             "access_token",
             "chatgpt_account_id",