能力、管理查詢與執行規劃

本頁對應後端 release v5.21.0，釘選後端 172a7f80bdf4dbdffdc018eb08bfa42c62bb485c。Private 路徑共用 /private/module/sandbox。

先讀 GET /me

GET /me 回報目前使用者能管理什麼，本身不授予權限；之後每個操作仍重新檢查自己的 dependency。UI 可使用：

欄位	介面用途
`can_manage_environments`、`can_create_tasks`	達部門／公司管理員門檻時顯示編輯控制
`can_read_settings`	只對公司管理員顯示公司設定
`can_quick_run_any_room`	只有公司管理員為 true；其他管理員仍可在自己能管理的房間 Quick Run
`manageable_chatroom_scope`	`company` 是所有現有／未來房間，`listed` 是列出的 id，`none` 是沒有可管理房間
`manageable_chatroom_ids`、`manageable_chatroom_ids_truncated`	`company` 搭配空陣列代表全部房間，不是零個；被截斷的陣列不是完整名冊
`manageable_department_ids`	呼叫者可管理的部門 scope
`creatable_task_owner_scopes`	`{scope, ids}` 項目，可對應 task 的合法 `owner_scope`／`owner_id` 選項

房間／部門 id 陣列上限 5000。受限 Sandbox key 在 auth scope 回 403，外部 social client 回 404；這些整合應使用 room-addressed API。

目錄可見與原始內容可見是兩個判斷

GET /tasks、任務 detail 與版本清單，只顯示使用者擁有／可管理，或透過 live audience grant 可見的任務。同公司不代表能看全部任務；已刪除的 owner 房間也不應讓整份目錄失敗。

SandboxTaskVersionResponse.source_visible 是必填布林值。True 表示 owner-source view；false 表示腳本、ordinary_env、work_command、slot declarations、output policy、task bundle 被隱藏，不能把 null 解讀成空任務。Room menu 永遠使用 borrower view，即使 owner 呼叫也回 source_visible=false。Owner 還要看 content_state：已 scrub 的版本也可能沒有可讀原始內容。

Borrower 可見的 input_schema、說明與範例仍可用來建立表單。input_schema／input_example 存在時是 JSON 編碼字串，使用前要解析；不要用角色數字或空腳本欄位猜 source 權限。

跨房間讀取執行歷史

GET /runs 回 {items, total, page_size, next_page_token}。公司管理員可看公司 run；其他使用者可看自己的 run，加上自己建立／管理房間的 run，部門管理員再加上自己部門的房間。篩選只能縮小此範圍：


GET /private/module/sandbox/runs?status=platform_failed&status=customer_failed&submitted_by_me=true&page_size=50

chatroom_id、task_id、status 可重複傳入。from／to 是包含邊界的 queued-time 篩選。排序為 queued_at、id 新到舊；從未 queued 的列排最後，有時間界線時則排除。total 在分頁前使用相同可見範圍與篩選。page_size 預設 50（1..100），下一頁原樣傳回不透明 cursor；格式錯誤會回第一頁。受限 key／social client 使用房間專屬歷史路徑。

查找 binding 與遮罩 secret metadata

GET 路徑	誰可讀／用途
`/tasks/{task_id}/bindings`	Owner-scope manager 可看採用紀錄；其他看得到任務的呼叫者，只看可管理房間的列
`/chatrooms/{chatroom_id}/bindings`	房間管理員查看 binding 歷史；`task_visible=false` 時不顯示不可存取的任務名稱／owner metadata
`/tasks/{task_id}/secrets`	同時要求任務可見與 consumer-scope 權限；擁有任務不代表能看其他 consumer 的 secret binding
`/tasks/{task_id}/secret-approvals`	只看可管理 consumer scope 的核准 metadata
`/secrets?consumer_scope=chatroom&consumer_id=...`	精確 consumer-scope 管理員；可加 task／slot 篩選，外層與每列都有 `consumer_name`

這些管理清單上限 2000 列，以 truncated 標示，不使用 page cursor。Binding 清單預設 lifecycle=active，傳 all／retired 可看撤銷的採用紀錄。它們與 menu（可執行的 Agent 目錄）、granted-jobs（live 可用性與啟用開關）不同。

請一起判讀 enabled、authority_applicable、update_available、state 與時間欄位。Secret 清單只提供遮罩狀態、generation 與 provider binding 是否存在，不回值、provider 路徑／id 或 fingerprint。讀取清單不會建立核准；請見分享與 Enable 同意及Secret 核准。

依 settings 規劃區域與費用

需登入且具公司管理權限的 settings 提供 selectable_regions 與可為 null 的 pricing。執行區域選項應使用目前 operator region codes，不要硬編碼公開確認 enum。allowed_regions 是已儲存的選擇，PUT 時會再次檢查可用性。Environment 的 region_readiness 保留 live codes，值為 ready／not_ready。

pricing.regions[].profiles 提供已含加價的客戶 usd_per_second。回應還包含費率／界線版本、min_billable_seconds、finalization_seconds、進出站費率，以及 outbound 預留 bytes／USD。預估上限使用符合條件區域中的最高 profile 費率：


max(min_billable_seconds, timeout_seconds + finalization_seconds)
  * highest_eligible_usd_per_second
  + outbound_reservation_usd

不要再乘一次加價。沒有可選區域時 pricing=null；提交仍會重新檢查目前政策、費率與預算。這是規劃預估，不是最後的用量帳單。

allowed_regions 只控制 runtime execution，不控制 build、registry、R2、log 或 control-plane 的位置；residency_guaranteed 仍為 false。runtime_egress_enabled 是 settings 中唯讀、由 operator 管理的欄位；區域選擇不是 egress 或資料落地保證。

雲端與地端部署（v5.10.11）

同一套租戶 API 可以跑在託管雲端（預設 provider），也可以跑在自架主機（SANDBOX_PROVIDER=onprem）。沒有欄位直接標示 provider；看區域目錄就能分辨，因為只有地端部署會公開 onprem。請依目錄、GET /settings 與 run 欄位建構介面，不要預設雲端行為。

面向	託管雲端	地端部署
公開區域目錄（`GET /public/info/sandbox/regions`）	雲端區域，`tier` 1 或 2	只有 `onprem`（「On-premises」），`tier` 3
`build_region`	預設 `asia-east1`；`onprem` → 422 `build_region_unavailable`	預設 `onprem`；其他代碼 → 422 `build_region_unavailable`
`GET /settings` 的 `pricing`	Cloud Run 費率，已含加價	tier 3 名目會計費率（預設每 vCPU-秒與每 GiB-秒 `0.000001` USD，operator 可覆寫，絕不為 0），同樣已含加價；`onprem` 是唯一可選區域時 `pricing_version` 為 `sandbox_onprem/v1.0.0`
等待中的 run	`queue_position` 為公司 `queued` run 中的位置；`eta_seconds` 一律 `null`	跨公司的 executor 佇列位置（`starting` 時也有）；有已完成 run 的歷史時才有 `eta_seconds`
佇列上限（429）	公司政策 `queued_run_limit` → `sandbox_queued_run_limit`	另有每公司（預設 20）與整個 fleet（預設 200 → `queue_full`，`Retry-After: 60`）上限；Quick Run 兩者都適用
`next_action` 用語	在適用處指名 Cloud Run	不指名 provider：submit／start 狀態用「the local runtime」、容量狀態用「the on-prem sandbox」；`wait_reason` 值相同
失敗詞彙	Go runner 的字面值	相同的 `error_code`／`failure_stage` 字面值，逾時 `exit_code=124`、取消 `130`；少數 executor 端失敗使用地端專屬代碼，例如 `executor_error`——遇到不認得的代碼當成平台失敗，並顯示 `failure_hint`
工作 shell 的環境變數	`PATH`、`ordinary_env`、secret slot 與三個 `TEAMSYNC_*` 路徑——沒有其他映像 `ENV`	相同（其他映像 `ENV` 在 session 開始前就被 unset）；另可能帶有下方的信任憑證變數
執行期對外網路	公司 `runtime_egress_enabled`	另需主機設 `SANDBOX_ONPREM_EGRESS=internet`（預設 `none`）
工作回呼這個 TeamSync（自訂表格 writeback、Command 輸出）	公開的 API origin	需要執行期對外網路，加上 operator 開放 API origin（`SANDBOX_ONPREM_TENANT_API_ORIGIN`）。設定 `SANDBOX_ONPREM_TENANT_CA_FILE` 後，主機的憑證經由 `/etc/teamsync/ca` 受信任，`SSL_CERT_FILE`、`REQUESTS_CA_BUNDLE`、`CURL_CA_BUNDLE`、`GIT_SSL_CAINFO`、`NODE_EXTRA_CA_CERTS` 會指向它，除非任務自己已經設定

selectable_regions 是租戶 settings 使用的 active operator 列集合，不是封閉的公開目錄。正確 bootstrap 的地端部署只會有 active onprem；若 operator 另外註冊 tier 1／2 列，它們可能出現在 selectable_regions，即使公開目錄與 build_region gate 仍只發布 onprem。

營運端機制（executor work lease、排程器、佇列逾時、GET /root/sandbox/queue）見營運與 Root。Run 欄位細節見執行與取回結果。

保留作者的 metadata

新的 secret_slot_declarations 使用物件，每筆必須有合法、非保留環境名稱的 name，並保留可選宣告 metadata。讀取側仍可能遇到歷史字串或不透明物件；請保留既有資料，新寫入則使用目前的具名物件格式。OpenAPI 會保留 name 與 region-readiness 值型別，供前端產生型別。

來源：Sandbox tenant router 的 principal_views.py、ownership_views.py、server.py、tasks.py、runs.py，以及 src/schemas/sandbox.py 與共用 access／binding helpers。Provider 差異：src/components/sandbox/providers/、src/components/sandbox/constants.py（visible_region_codes）、src/components/sandbox/pricing.py、src/components/sandbox/run_visibility.py、src/crud/sandbox/run_submission.py、src/crud/sandbox/onprem_scheduler.py 與地端 executor src/workers/sandbox_onprem/。