fix: raise ResourceNotExistError in delete_sandbox when data plane returns "sandbox not found"

[Copilot]

Control plane (list_sandboxes) and data plane (delete_sandbox) can diverge: a TERMINATED sandbox remains visible in list results, but the data plane has already removed it, causing delete_sandbox to raise ClientError('Failed to stop sandbox: sandbox not found') instead of a recognisable "not found" signal.

Changes

• agentrun/sandbox/client.py — In both delete_sandbox and delete_sandbox_async, when the data plane returns a non-SUCCESS response with a message containing "sandbox not found", raise ResourceNotExistError("Sandbox", sandbox_id) instead of ClientError. This is consistent with the existing HTTP 404 path and avoids returning an incomplete Sandbox object. Updated docstrings document that ResourceNotExistError covers both HTTP 404 and data-plane business-level not-found. A code comment tracks the long-term goal of switching to a stable server-side error_code (e.g. SandboxNotFound).

• tests/unittests/sandbox/test_client.py — Updated tests to assert ResourceNotExistError is raised for the data-plane not-found case; added boundary and negative tests: case-insensitive message variants, unrelated failure messages still raise ClientError, and empty message raises ClientError.

Before / After

# Before — raises generic ClientError on already-gone TERMINATED sandbox
client.delete_sandbox("91d970881b8d4dcaa5636df64577545b--18ee62652b")
# ClientError: Failed to stop sandbox: sandbox not found

# After — raises ResourceNotExistError (consistent with HTTP 404 path)
# Callers can implement idempotent deletion with a simple except clause:
try:
    client.delete_sandbox("91d970881b8d4dcaa5636df64577545b--18ee62652b")
except ResourceNotExistError:
    pass  # already gone — idempotent

[OhYee]

@copilot 修复方向正确（解决 issue #83 的 TERMINATED 残留场景），但建议对实现做一个关键调整。

问题：当前实现把 not-found 静默吞为成功

if "sandbox not found" in message.lower():
    return Sandbox.model_validate(
        {"sandboxId": sandbox_id}, by_alias=True
    )

这有三个隐患：

1. 吞掉真错误：用户传错 sandbox_id（笔误、跨账号、复制错）时也会"删除成功"，bug 隐藏
2. 返回的 Sandbox 残缺：只有 sandbox_id，其他字段（status/template_name 等）拿默认值，与正常成功响应 shape 不一致
3. 行为分裂：HTTP 404 路径已经抛 ResourceNotExistError("Sandbox", id)（见 client.py 中 except ClientError as e: if e.status_code == 404），业务码 not-found 静默成功，同语义两种返回

建议：改抛 ResourceNotExistError，与 HTTP 404 路径统一

代码改动（sync + async 两处）

                 message = result.get("message", "")
                 if "sandbox not found" in message.lower():
-                    return Sandbox.model_validate(
-                        {"sandboxId": sandbox_id}, by_alias=True
-                    )
+                    raise ResourceNotExistError("Sandbox", sandbox_id)
                 raise ClientError(
                     status_code=0,
                     message=(
                         "Failed to stop sandbox:"
                         f" {message or 'Unknown error'}"
                     ),
                 )

调用方写法（依然能实现幂等）

try:
    client.delete_sandbox(sid)
except ResourceNotExistError:
    pass  # 已经不在了，幂等达成

优点

• ✅ 修复 issue 【bug】AgentRun Python SDK 中 list_sandboxes 仍能查到 TERMINATED 实例，但 delete_sandbox 删除同一 sandbox_id 时返回 sandbox not found #83 的清理任务场景（多 1 行 except 即可幂等）
• ✅ 与 HTTP 404 路径完全一致——任何"对象不存在"都抛 ResourceNotExistError
• ✅ 不返回残缺 Sandbox 对象，避免 shape 不一致带来的下游问题
• ✅ 笔误/鉴权问题不再被吞，调用方能感知到真错误
• ✅ 字符串匹配万一失效（服务端文案改），降级到 ClientError 而不是错误的"删除成功"

还需要做的事

1. 更新 docstring（sync + async）

在 Raises: 段补充说明：

Raises:
    ResourceNotExistError: Sandbox 不存在（包括 HTTP 404 与数据面业务层 not-found
        两种情形）。调用方可 catch 此异常实现幂等删除。
    ClientError: 客户端错误
    ServerError: 服务器错误

2. 改造现有测试

把 test_delete_sandbox_not_found_in_response_is_idempotent 改为断言抛 ResourceNotExistError：

def test_delete_sandbox_not_found_in_response_raises_resource_not_exist(...):
    mock_data_api.delete_sandbox.return_value = {
        "code": "FAILED",
        "message": "sandbox not found",
    }
    client = SandboxClient()
    with pytest.raises(ResourceNotExistError):
        client.delete_sandbox("sandbox-123")

async 版同理。

3. 补负样本与边界测试

• 负样本：message 含 "sandbox not running"、"sandbox is busy" 等其他文本，应仍抛 ClientError（不该被误吞）
• 大小写：message 为 "Sandbox NOT FOUND"、"SANDBOX Not Found" 等变体，验证 .lower() 工作正常
• 边界：message 为空字符串或字段缺失时，应抛 ClientError（不该匹配）

4. 转 Ready for review

base 已能 cleanly merge 到当前 main（含 #95），无需 rebase；merge 后 71 个 sandbox client 测试本地全过。

---

关于服务端

字符串匹配 "sandbox not found" in message.lower() 是技术债——服务端文案变更即失效。建议在 PR 描述或 issue #83 中显式跟踪："长期方案是服务端返回稳定 error_code（如 SandboxNotFound），SDK 切换到按 code 判断"。目前 SDK 字符串补丁是合理的短期容错。

修复以上 4 项后即可合入。

[Copilot]

@copilot 修复方向正确（解决 issue #83 的 TERMINATED 残留场景），但建议对实现做一个关键调整。

问题：当前实现把 not-found 静默吞为成功...

Done in eec1443. Changes made:

1. client.py (sync + async) — replaced the stub-return with raise ResourceNotExistError("Sandbox", sandbox_id), aligning the data-plane not-found path with the existing HTTP 404 path. Updated docstrings to document both cases under Raises:, and added a comment noting the long-term plan of switching to a stable server-side error_code.

2. Tests — renamed/rewrote the idempotent tests to assert ResourceNotExistError; added:

   • case-insensitive variant ("Sandbox NOT FOUND" → ResourceNotExistError)
   • negative sample ("sandbox is busy" → ClientError)
   • empty message edge case ("" → ClientError)
   • async equivalents for failure/not-found paths

All 11 TestSandboxClientDeleteSandbox tests pass; type check clean (326 files, 0 errors).

[Copilot]

Pull request overview

This PR makes SandboxClient.delete_sandbox() / delete_sandbox_async() raise ResourceNotExistError("Sandbox", sandbox_id) when the data plane returns a business-level failure containing “sandbox not found”, aligning it with the existing HTTP 404 behavior so callers can implement idempotent deletion reliably.

Changes:

• Detect data-plane “sandbox not found” failures (case-insensitive) and raise ResourceNotExistError instead of a generic ClientError (sync + async).
• Update method docstrings to clarify ResourceNotExistError covers both HTTP 404 and data-plane not-found.
• Extend unit tests to cover not-found message variants and ensure unrelated failures still raise ClientError.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 8 comments.

File	Description
agentrun/sandbox/client.py	Adds message-based not-found detection in delete APIs and updates docstrings/error handling.
tests/unittests/sandbox/test_client.py	Adds/updates unit tests for data-plane not-found vs other failure messages (sync + async).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.