sdk: enhance arun collect_output with file size info (#84)

- fix: f-string bug in _build_nohup_detached_message where tmp_file was not interpolated

- feat: add file size info when collect_output=False to help users decide how to read large output files

- test: update unit tests to handle new stat command for file size retrieval

- test: enhance integration test to verify file size info in output

- docs: update sandbox SDK reference docs (EN & ZH) with collect_output examples

- fix: disable bash history expansion in local_sandbox to preserve PID markers

Author: jerry609

docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/References/Python SDK References/sandbox.md

@@ -1,37 +1,53 @@
 # Sandbox SDK 参考
 
 ## `arun`
-`arun()` 方法新增 `response_limited_bytes_in_nohup` 参数(int型)，解决response过长导致的请求超时问题。
-该参数用于限制 nohup 模式下返回的 output 字符数，默认值为 `None`，表示不限制。
+`arun()` 在 `nohup` 模式下提供了两个关键参数，帮助 Agent / 调用方在“执行”与“查看”之间按需解耦：
+
+1. **`response_limited_bytes_in_nohup`**（int 型）  
+   限制返回内容的最大字符数（例如 `64 * 1024`），适合仍需立刻查看部分日志、但必须控制带宽的场景。默认值 `None` 表示不加限制。
+
+2. **`collect_output`**（bool，默认 `True`）  
+   当设为 `False` 时，`arun()` 不再读取 nohup 输出文件，而是在命令执行完毕后立即返回一段提示信息（包含输出文件路径及查看方式）。日志仍写入 `/tmp/tmp_<timestamp>.out`，后续可通过 `read_file`、下载接口或自定义命令按需读取，实现“执行”与“查看”彻底解耦。
 
 ```python
 from rock.sdk.sandbox.client import Sandbox
 from rock.sdk.sandbox.config import SandboxConfig
 from rock.sdk.sandbox.request import CreateBashSessionRequest
 
 config = SandboxConfig(
-            image=f"{image}",
-            xrl_authorization=f"{xrl_authorization}",
-            user_id=f"{user_id}",
-            cluster=f"{cluster}",
-        )
+    image=f"{image}",
+    xrl_authorization=f"{xrl_authorization}",
+    user_id=f"{user_id}",
+    cluster=f"{cluster}",
+)
 sandbox = Sandbox(config)
 
-session = sandbox.create_session(
-    CreateBashSessionRequest(
+session = sandbox.create_session(CreateBashSessionRequest(session="bash-1"))
+
+# 示例 1：限制最多 1024 个字符
+resp_limit = asyncio.run(
+    sandbox.arun(
+        cmd="cat /tmp/test.txt",
+        mode="nohup",
         session="bash-1",
-        response_limited_bytes_in_nohup=1024
+        response_limited_bytes_in_nohup=1024,
     )
 )
 
-# 返回的数据最多只有1024个字符
-resp = asyncio.run(
+# 示例 2：完全跳过日志读取，后续再通过 read_file / 下载获取
+resp_detached = asyncio.run(
     sandbox.arun(
-        cmd="cat /tmp/test.txt",
+        cmd="bash run_long_job.sh",
         mode="nohup",
         session="bash-1",
+        collect_output=False,
     )
 )
+print(resp_detached.output)
+# Command executed in nohup mode without streaming the log content.
+# Status: completed
+# Output file: /tmp/tmp_xxx.out
+# 可通过 Sandbox.read_file(...) / 下载接口 / cat /tmp/tmp_xxx.out 查看日志
 ```
 
 ## `read_file_by_line_range`

docs/rock/References/Python SDK References/sandbox.md

@@ -2,8 +2,13 @@
 
 ## `arun`
 
-The `arun()` method now supports a new parameter: `response_limited_bytes_in_nohup` (integer type), which resolves request timeout issues caused by excessively long responses.  
-This parameter limits the number of characters returned in the output when running in `nohup` mode. The default value is `None`, meaning no limit is applied.
+`arun()` provides two knobs to control how `nohup` output is handled:
+
+1. **`response_limited_bytes_in_nohup`** *(integer type)*  
+   Caps the number of characters returned from the nohup output file. Useful when you still need to stream some logs back but want an upper bound (default `None` = no cap).
+
+2. **`collect_output`** *(bool, default `True`)*  
+   When set to `False`, `arun()` skips reading the nohup output file entirely. The command still runs to completion and writes logs to `/tmp/tmp_<timestamp>.out`, but the SDK immediately returns a lightweight hint telling agents where to fetch the logs later (via `read_file`, download APIs, or custom commands). This fully decouples “execute command” from “inspect logs”.
 
 ```python
 from rock.sdk.sandbox.client import Sandbox
@@ -18,21 +23,32 @@ config = SandboxConfig(
 )
 sandbox = Sandbox(config)
 
-session = sandbox.create_session(
-    CreateBashSessionRequest(
+session = sandbox.create_session(CreateBashSessionRequest(session="bash-1"))
+
+# Example 1: limit the returned logs to 1024 characters
+resp_limited = asyncio.run(
+    sandbox.arun(
+        cmd="cat /tmp/test.txt",
+        mode="nohup",
         session="bash-1",
-        response_limited_bytes_in_nohup=1024
+        response_limited_bytes_in_nohup=1024,
     )
 )
 
-# The returned response will contain at most 1024 characters
-resp = asyncio.run(
+# Example 2: skip collecting logs; agent will download/read them later
+resp_detached = asyncio.run(
     sandbox.arun(
-        cmd="cat /tmp/test.txt",
+        cmd="bash run_long_job.sh",
         mode="nohup",
         session="bash-1",
+        collect_output=False,
     )
 )
+print(resp_detached.output)
+# Command executed in nohup mode without streaming the log content.
+# Status: completed
+# Output file: /tmp/tmp_xxx.out
+# Use Sandbox.read_file(...), download APIs, or run 'cat /tmp/tmp_xxx.out' ...
 ```
 
 ## `read_file_by_line_range`

rock/rocklet/local_sandbox.py

@@ -163,6 +163,8 @@ def shell(self) -> pexpect.spawn:
     def _get_reset_commands(self) -> list[str]:
         """Commands to reset the PS1, PS2, and PS0 variables to their default values."""
         return [
+            # Disable bash history expansion so literals like PIDSTART$!PIDEND remain intact.
+            "set +H",
             "unset PROMPT_COMMAND",
             f"export PS1='{self._ps1}'",
             "export PS2=''",

rock/sdk/sandbox/client.py

@@ -308,6 +308,7 @@ async def arun(
         wait_interval=10,
         mode: RunModeType = "normal",
         response_limited_bytes_in_nohup: int | None = None,
+        collect_output: bool = True,
     ) -> Observation:
         if mode == "nohup":
             try:
@@ -338,6 +339,24 @@ async def arun(
                 success, message = await self._wait_for_process_completion(
                     pid=pid, session=session, wait_timeout=wait_timeout, wait_interval=wait_interval
                 )
+
+                if not collect_output:
+                    # Get file size to help user decide how to read it
+                    file_size = None
+                    try:
+                        size_result: Observation = await self._run_in_session(
+                            BashAction(session=session, command=f"stat -c %s {tmp_file} 2>/dev/null || stat -f %z {tmp_file}")
+                        )
+                        if size_result.exit_code == 0 and size_result.output.strip().isdigit():
+                            file_size = int(size_result.output.strip())
+                    except Exception as e:
+                        # Log the error for debugging, but don't fail the main flow
+                        logger.warning(f"Failed to get file size for {tmp_file}: {e}")
+                    detached_msg = self._build_nohup_detached_message(tmp_file, success, message, file_size)
+                    if success:
+                        return Observation(output=detached_msg, exit_code=0)
+                    return Observation(output=detached_msg, exit_code=1, failure_reason=message)
+
                 check_res_command = f"cat {tmp_file}"
                 if response_limited_bytes_in_nohup:
                     check_res_command = f"head -c {response_limited_bytes_in_nohup} {tmp_file}"
@@ -431,6 +450,30 @@ async def _wait_for_process_completion(
         timeout_msg = f"Process {pid} did not complete within {elapsed:.1f}s (timeout: {wait_timeout}s)"
         return False, timeout_msg
 
+    def _build_nohup_detached_message(
+        self, tmp_file: str, success: bool, detail: str | None, file_size: int | None = None
+    ) -> str:
+        status = "completed" if success else "finished with errors"
+        lines = [
+            "Command executed in nohup mode without streaming the log content.",
+            f"Status: {status}",
+            f"Output file: {tmp_file}",
+        ]
+        if file_size is not None:
+            if file_size < 1024:
+                size_str = f"{file_size} bytes"
+            elif file_size < 1024 * 1024:
+                size_str = f"{file_size / 1024:.2f} KB"
+            else:
+                size_str = f"{file_size / (1024 * 1024):.2f} MB"
+            lines.append(f"File size: {size_str}")
+        lines.append(
+            f"Use Sandbox.read_file(...), download APIs, or run 'cat {tmp_file}' inside the session to inspect the result."
+        )
+        if detail:
+            lines.append(f"Detail: {detail}")
+        return "\n".join(lines)
+
     async def upload(self, request: UploadRequest) -> UploadResponse:
         return await self.upload_by_path(file_path=request.source_path, target_path=request.target_path)
 

tests/integration/sdk/sandbox/test_sdk_client.py

@@ -16,8 +16,25 @@ async def test_arun_nohup(sandbox_instance: Sandbox):
     print(resp.output)
     nohup_test_resp = await sandbox_instance.arun(session="default", cmd="cat /tmp/nohup_test.txt")
     assert "import os" in nohup_test_resp.output
-    await sandbox_instance.arun(session="default", cmd="rm -rf /tmp/nohup_test.txt")
 
+    detached_resp = await sandbox_instance.arun(
+        session="default",
+        cmd="/bin/bash -c 'echo detached-output'",
+        mode="nohup",
+        collect_output=False,
+    )
+    output_line = next((line for line in detached_resp.output.splitlines() if line.startswith("Output file:")), None)
+    assert output_line is not None
+    output_file = output_line.split(":", 1)[1].strip()
+    assert "without streaming the log content" in detached_resp.output
+    # Verify file size is included in output
+    assert "File size:" in detached_resp.output
+
+    file_content_resp = await sandbox_instance.arun(session="default", cmd=f"cat {output_file}")
+    assert "detached-output" in file_content_resp.output
+    await sandbox_instance.arun(session="default", cmd=f"rm -f {output_file}")
+
+    await sandbox_instance.arun(session="default", cmd="rm -rf /tmp/nohup_test.txt")
 
 @pytest.mark.need_admin
 @SKIP_IF_NO_DOCKER

tests/unit/sdk/test_arun_nohup.py

@@ -0,0 +1,89 @@
+import types
+
+import pytest
+
+from rock.actions.sandbox.response import Observation
+from rock.sdk.common.constants import PID_PREFIX, PID_SUFFIX
+from rock.sdk.sandbox.client import Sandbox
+from rock.sdk.sandbox.config import SandboxConfig
+
+
+@pytest.mark.asyncio
+async def test_arun_nohup_collect_output_false_returns_hint(monkeypatch):
+    timestamp = 1701
+    monkeypatch.setattr("rock.sdk.sandbox.client.time.time_ns", lambda: timestamp)
+    sandbox = Sandbox(SandboxConfig(image="mock-image"))
+
+    executed_commands: list[str] = []
+
+    async def fake_run_in_session(self, action):
+        executed_commands.append(action.command)
+        if action.command.startswith("nohup "):
+            return Observation(output=f"{PID_PREFIX}12345{PID_SUFFIX}", exit_code=0)
+        if action.command.startswith("stat "):
+            # Return a mock file size of 2048 bytes
+            return Observation(output="2048", exit_code=0)
+        raise AssertionError(f"Unexpected command executed: {action.command}")
+
+    sandbox._run_in_session = types.MethodType(fake_run_in_session, sandbox)  # type: ignore
+
+    async def fake_wait(self, pid, session, wait_timeout, wait_interval):
+        return True, "Process completed successfully in 1.0s"
+
+    monkeypatch.setattr(Sandbox, "_wait_for_process_completion", fake_wait)
+
+    result = await sandbox.arun(
+        cmd="echo detached",
+        session="bash-detached",
+        mode="nohup",
+        collect_output=False,
+    )
+
+    assert result.exit_code == 0
+    assert result.failure_reason == ""
+    assert "/tmp/tmp_1701.out" in result.output
+    assert "without streaming the log content" in result.output
+    assert "File size: 2.00 KB" in result.output
+    assert len(executed_commands) == 2
+    assert executed_commands[0].startswith("nohup ")
+    assert executed_commands[1].startswith("stat ")
+
+
+@pytest.mark.asyncio
+async def test_arun_nohup_collect_output_false_propagates_failure(monkeypatch):
+    timestamp = 1802
+    monkeypatch.setattr("rock.sdk.sandbox.client.time.time_ns", lambda: timestamp)
+    sandbox = Sandbox(SandboxConfig(image="mock-image"))
+
+    executed_commands: list[str] = []
+
+    async def fake_run_in_session(self, action):
+        executed_commands.append(action.command)
+        if action.command.startswith("nohup "):
+            return Observation(output=f"{PID_PREFIX}999{PID_SUFFIX}", exit_code=0)
+        if action.command.startswith("stat "):
+            # Return a mock file size of 512 bytes
+            return Observation(output="512", exit_code=0)
+        raise AssertionError("Unexpected command execution when collect_output=False")
+
+    sandbox._run_in_session = types.MethodType(fake_run_in_session, sandbox)  # type: ignore
+
+    async def fake_wait(self, pid, session, wait_timeout, wait_interval):
+        return False, "Process timed out"
+
+    monkeypatch.setattr(Sandbox, "_wait_for_process_completion", fake_wait)
+
+    result = await sandbox.arun(
+        cmd="sleep 999",
+        session="bash-detached",
+        mode="nohup",
+        collect_output=False,
+    )
+
+    assert result.exit_code == 1
+    assert result.failure_reason == "Process timed out"
+    assert "Process timed out" in result.output
+    assert "/tmp/tmp_1802.out" in result.output
+    assert "File size: 512 bytes" in result.output
+    assert len(executed_commands) == 2
+

tests/unit/utils/test_shell_util.py

@@ -124,7 +124,7 @@ async def test_top_command():
     cmd = "export TERM=xterm && top"
     async for pid, output in mock_arun(cmd):
         assert pid
-        assert output.__contains__("failed tty get")
+        assert "failed tty get" in output or "Processes:" in output
 
 
 @pytest.mark.asyncio