狀態機與輪詢

沒有 streaming。 前端用輪詢（GET 狀態）追蹤進度。以下是各資源的狀態值（取自 src/schemas/enums.py）與轉換。

環境版本 SandboxEnvironmentVersionState

draft → build_queued → building → verifying → verified
      → regional_provisioning → ready        ← 可被 Task Version 引用

分支/失敗狀態：quarantined、retryable_failed、rejected、abandoned、blocked、superseded、archived、provisioning_blocked。

• retryable_failed → POST /.../retry-build。
• provisioning_blocked / provisioning 失敗 → POST /.../retry-provisioning。

建置嘗試 SandboxBuildAttemptState

validation_queued → validating → build_queued → building → verifying → completed
取消：cancel_requested → cancelling → cancelled
失敗：customer_failed / platform_failed

• terminal_class ∈ completed / customer_failed / platform_failed / cancelled。
• error_code / stage_code / phase 提供細節；report_total_bytes > 0 表示有建置報告。

執行 SandboxRunState

queued → starting → running → completed
取消：cancel_requested → cancelled
失敗：customer_failed / platform_failed

• 終態以 terminal_at 標記。
• error_code 提供失敗原因。

任務版本 SandboxTaskVersionState

draft → published → archived

另有 content_state；menu / 可執行判斷要求 content_state == "active"。

Agent 提案 SandboxProposalState（Agent 確認流程）

prepared → committing → committed
其他：superseded（被更新提案取代）/ cancelled / expired / failed

詳見 Agent 確認流程。

輪詢建議

• 建置：輪詢 GET /environments/{id}/versions/{vid}/builds/{attempt_id}，直到 terminal_class 有值。
• 執行：輪詢 GET /chatrooms/{id}/runs/{run_id}，直到 terminal_at 有值。
• 後端狀態等待上限 MAX_STATUS_WAIT_SECONDS = 60；前端輪詢間隔建議數秒起、對終態退避。
• 通知：後端另有 SandboxNotificationEvent（如 build_ready、build_failed、run_terminal、各種 security_finding_*），可搭配通知中心減少輪詢；事件本身不改變上面的輪詢模型。