執行與取回結果

執行都以聊天室定址：/chatrooms/{chatroom_id}/...。受限 API key 可用 menu / 提交 / 查自己的 run / 下載自己的產出物 / 取消自己的 run；retry、quick-run 對受限 key 一律 404。

1. 探索可執行清單

GET /chatrooms/{chatroom_id}/menu   # query page_size (ge1 le100, 預設 50)

回 items[]（SandboxMenuItemResponse）：task_version_id、requires_confirmation、secret_slot_names、timeout_seconds、update_available、input_instructions / input_example。不含腳本原文。

2. 提交執行

POST /chatrooms/{chatroom_id}/runs
Idempotency-Key: <UUID>          # 必帶，否則 422 idempotency_key_required
{ "task_version_id": "...", "input": {...}, "timeout_seconds": 1800 }

• input：canonical JSON（≤1 MiB、深度 ≤64、節點 ≤100k、無 NUL、無重複 key）。
• body 過大先回 413 request_too_large（依 Content-Length）。
• 版本非「published + content active」→ 409（_refuse_not_runnable）。
• 回 SandboxRunDetailResponse，status: "queued"。

3. 輪詢狀態

GET /chatrooms/{chatroom_id}/runs/{run_id}

status 走 queued → starting → running → completed（或 customer_failed / platform_failed；取消 cancel_requested → cancelled）。終態看 terminal_at。失敗看 error_code。

列表 + 篩選：

GET /chatrooms/{chatroom_id}/runs?status=queued&status=running   # status 可重複

受限 key 只會看到自己的 run。

4. 看有哪些產出

GET /chatrooms/{chatroom_id}/runs/{run_id}/content
# → { state, has_input, has_output, has_log, has_artifact_bundle, input_digest }

只有布林旗標，沒有內容本體（這是「c2 log/output」的 metadata 視圖）。state 可能是 "missing"（尚無內容列）。

5. 列出並下載產出物

GET /chatrooms/{chatroom_id}/runs/{run_id}/artifacts        # 預設 lifecycle=active
# → items[] { id, relative_path, byte_size, digest, deletion_state, declared_content_type }
 
POST /chatrooms/{chatroom_id}/runs/{run_id}/artifacts/{artifact_id}/download
# → { capability_token, expires_at, content_type, content_disposition, x_content_type_options: "nosniff" }

• 回的是短效 capability token，不是原始 key / presigned URL。用它去取實際位元組。
• deletion_state != active 的產出物，download 一律 404。
• capability 過期就重新 POST .../download。

6. 取消 / 重試

POST /chatrooms/{chatroom_id}/runs/{run_id}/cancel     # 取消自己進行中的 run（kill switch 下仍可用）
POST /chatrooms/{chatroom_id}/runs/{run_id}/retry      # 以新身分重試終態 run；帶 Idempotency-Key；受限 key 404

• retry 來源 run 非可重試終態 → 409 retry_not_eligible。

Quick Run（manager-only）

一次原子建立隱藏任務+版本+執行：POST /chatrooms/{chatroom_id}/quick-run（SandboxQuickRunRequest，帶 Idempotency-Key）。回 { task, version, run }。受限 key 404。

常見錯誤速查