請求與回應欄位
以下每個 request body 都是 extra="forbid"：未知欄位 → 422。路徑省略 {BASE}/private/module/sandbox。模型定義在租戶 router（src/routers/private/modules/sandbox/*.py）與 src/schemas/sandbox.py。本頁與 origin/master 不一致時，以後端為準。
表格慣例
?= 可選／可空／某些視圖會省略。owner-only= 只有 owner-scope manager 看得到，borrower 視圖省略。- id 字串符合
^[A-Za-z0-9_.\-]+$（部分寫入欄位更嚴：^[A-Za-z0-9_.:@-]{1,64}$）。 - Digest 為
sha256:+ 64 位小寫 hex。
共用：分頁
| 欄位 | 型別 | 說明 |
|---|---|---|
page_size | int | ge=1、le=100（MAX_PAGE_SIZE），所有列表一致。預設 20 適用環境／環境版本／建置／任務／任務版本／分享列表（DEFAULT_PAGE_SIZE）；三條 chatroom 路由預設 50：GET .../menu、GET .../runs、GET .../runs/{rid}/artifacts。 |
page_token | string? | 不透明，max_length=512。把上一頁的 next_page_token 原封不動送回；格式錯誤的 token 會從第一頁重來（不會 422）。後端 #1149 起所有列表都收，包括 GET .../menu、GET .../runs（游標釘在 (queued_at, id)，最新在前）與 GET .../runs/{rid}/artifacts（依 relative_path 排序）。 |
next_page_token | string? | 缺／null = 最後一頁。還有資料時每條列表都會回真的游標（後端 ≥ #1149；之前三條 chatroom 路由永遠回 null，無法翻頁）。 |
lifecycle | active / retired / all | 多數列表預設 active。GET /tasks/{id}/shares 預設 all。 |
status | 可重複 query | 僅 run 列表。?status=queued&status=running。 |
Retired 詞彙（src/routers/private/modules/sandbox/_filters.py）：
| 列表 | 預設隱藏的 retired 值（除非 lifecycle=retired 或 all） |
|---|---|
| 環境 | archived |
| 環境版本 | archived（retryable_failed / rejected 仍可見） |
| 任務 | archived |
| 任務版本 | archived |
| 分享授權 | revoked（預設 all，讓撤銷可見） |
| Run 產出物 | delete_pending / deleted / tombstoned |
公司設定
SandboxCompanySettingsUpdate（PUT /settings）
| 欄位 | 型別 | 限制 |
|---|---|---|
run_content_retention_days | int | 1..365 |
unreferenced_image_retention_days | int | 1..90 |
allowed_regions | string[] | min_length=1。只管執行期 Job / Execution 放置。 |
policy_version | int | ge=1。樂觀鎖 CAS；不符 → 409。 |
SandboxCompanySettingsResponse（GET/PUT /settings）
上述可寫欄位，加上唯讀：
| 欄位 | 型別 | 說明 |
|---|---|---|
company_id | string | |
selectable_regions | string[] | 設定寫入接受的活躍 operator 區域，可超出公開確認集合。 |
pricing | SandboxRuntimePricing? | 已登入可讀的客戶費率與預留界線；無可選區域時為 null。 |
runtime_egress_enabled | bool | 唯讀 operator 政策；租戶 PUT /settings 不可修改。 |
| timeout_ceiling_seconds | int | 租戶上限。預設 86400。 |
| active_environment_limit | int | 預設 30。 |
| capacity_retained_version_limit | int | 預設 100。 |
| placement_scope | "runtime_execution_only" | 字面值。 |
| does_not_govern | string[] | build / validator / registry / r2 / log / control_plane。 |
| residency_guaranteed | false | 字面值。 |
| regional_job_capacity_grace_days_fixed | int | 30。 |
環境 / 版本 / 建置
SandboxEnvironmentCreateRequest / UpdateRequest
| 欄位 | 建立 | 更新 | 限制 |
|---|---|---|---|
name | 必填 | 可選 | 1..256 |
owner_scope | 可選，預設 company | 不可修改 | company 或 department，沒有 chatroom owner |
owner_id | 公司可省略；部門須提供部門 id | 不可修改 | 公司 id 預設呼叫者的公司；部門須符合 owner 管理權 |
description | 可選，預設 "" | 可選 | ≤2048 |
SandboxEnvironmentResponse
| 欄位 | 型別 | 說明 |
|---|---|---|
id | string | |
company_id | string? | system_curated 環境為 null。 |
owner_kind | system_curated / company | 租戶可 pin 策展版本，不能建立策展環境。 |
name | string | |
description | string | |
state | string | 活著：active。退休：archived。 |
security_state | string | 通常 clear。Root digest-block 可設 blocked。 |
current_version_id | string? |
Context 上傳
| 模型 | 欄位 |
|---|---|
SandboxContextUploadInitRequest | declared_bytes 1..1 GiB。archive_format zip/tar/tar.gz（預設 tar.gz）。 |
SandboxContextUploadInitResponse | upload_session_id、capability_token、capability_expires_at（15 分鐘）、upload_mode（single_part）、object_kind（context）、archive_format、declared_bytes、max_bytes、put_header_name（X-Sandbox-Upload-Capability）、put_content_type（application/octet-stream）。 |
SandboxContextUploadPutResponse | upload_session_id、bytes_received、digest。 |
SandboxContextUploadCompleteRequest | expected_size?、expected_digest?（sha256:）。 |
SandboxContextUploadCompleteResponse | owned_object_id、digest、byte_size、upload_session_id、environment_id。 |
SandboxContextUploadSessionResponse | upload_session_id、environment_id、state（uploading/completed/aborted/abort_pending）、object_kind、declared_bytes、owned_object_id?、digest?、byte_size?、session_expires_at?。 |
PUT body 是原始位元組，不是 JSON。
SandboxEnvironmentVersionCreateRequest
| 欄位 | 型別 | 限制 |
|---|---|---|
owned_object_id | string? | 來自 complete。1..36。首選。 |
source_digest | string? | ^sha256:[0-9a-f]{64}$。至少要有一個。單獨送不會被比對到任何已完成的 context 物件——後端只檢查格式，就會建出一個沒有綁定封存的版本；排建置本身會成功（還會先扣預算），錯誤要到建置階段才浮現（context_invalid）。實務上一律送 complete 回傳的 owned_object_id；兩個都送時 digest 必須與該物件相符（否則 422 source_digest_mismatch）。 |
source_ref | string | 可選，預設 ""，≤1024。擁有者標籤（檔名）。不是 key 或 URL。 |
resource_profile | enum | 確認集合 GET /public/info/sandbox/profiles。不是 xlarge。 必填。 |
SandboxEnvironmentVersionResponse
| 欄位 | 型別 | 說明 |
|---|---|---|
id, environment_id | string | |
company_id | string? | |
version_number | int | ge=1 |
state | SandboxEnvironmentVersionState | 輪詢到 ready。 |
security_state | string | |
resource_profile | string | |
capacity_retained | bool | 計入公司版本配額。 |
promoted_digest | string? | 推廣後的映像 digest。 |
composed_execution_digest | string? | 執行期合成。 |
runner_release, runner_abi_revision, policy_revision | string? | Runner 身份。 |
runner_release_approved | bool | 後端 ≥ #1162。 此版本的 runner release 已核准跑 task-bundle 工作時為 true。草稿、或由尚未核准的 runner 建出的版本為 false —— 此時 bundle 的發佈/執行回 409 task_bundle_runner_unsupported。 |
runner_release_next_action | string | runner_release_approved 為 false 時的白話指引（重新排一次建置，或請 operator 核准該 release）；否則為空。 |
region_readiness | any? | 各區佈建對照。 |
ready_at, verified_at | datetime? | |
compressed_bytes, unpacked_bytes | int? | |
last_build_attempt_id, last_build_status, last_build_terminal_class, last_build_stage_code, last_build_error_code, last_build_error_detail | string | 最新一次建置嘗試；error_detail 僅擁有者可見。 |
build_stage | string | 最新嘗試目前所在階段：build_queued、context_validator、customer_build、static_scan、smoke、sign、attest、promote、final_verify、runner_floor、regional_readback、terminal；尚未建置時為空。 |
build_stage_index, build_stage_count | int | 驗證鏈進度的分子／分母（排隊中或終態為 0）。 |
build_stage_since | datetime? | 最新嘗試進入 build_stage 的時間。 |
build_expected_seconds | int | 本平台一次完整建置的典型耗時；沒有進行中的建置時為 0。 |
build_next_action | string | ≤400。建置進行中或失敗後「正在發生什麼／該做什麼」；ready 之後為空。 |
source_digest, source_ref | string? | Owner-only。 borrower 視圖省略。 |
SandboxBuildAttemptCreateRequest
| 欄位 | 型別 | 預設 |
|---|---|---|
build_region | SandboxRegionCode? | 確認集合 GET /public/info/sandbox/regions。省略 → 部署預設值：託管雲端 asia-east1，地端部署 onprem。不在該部署公開目錄內的代碼（例如雲端的 onprem）→ 422 build_region_unavailable；地端在已有 active 區域列、但指定的不在其中時也回同一個 422。 |
build_profile | string? | ≤32。預設 standard。列舉：standard / fast / large。 |
SandboxBuildAttemptResponse
絕不包含憑證、金鑰或物件 URL。
| 欄位 | 型別 | 說明 |
|---|---|---|
id, company_id, environment_version_id | string | |
attempt_number | int | ge=1 |
status | SandboxBuildAttemptState | |
phase, stage_code, error_code | string | 細節；沒用時為空字串。 |
error_detail | string | ≤128 字元，; 分隔的 slug，點名 error_code 底下具體是哪條規則，例如 reserved_path_or_hostile_entry 或 dockerfile_too_large。絕不是自由文字或顧客內容。終態沒有更多細節時為空。 |
terminal_class | SandboxBuildTerminalClass 或 "" | 非空 = 終態。 |
build_region, build_profile | string | |
raw_upload_digest, canonical_digest | string | |
queued_at | datetime? | |
retryable_until | datetime? | 後端 ≥ #1149。失敗／取消的 attempt 在版本仍是 retryable_failed 時帶：POST .../versions/{vid}/retry-build 還會接受的期限（版本最後一次狀態變更起 7 天）。期限過了、版本離開該狀態、或 attempt 不是失敗結束時為 null。同一版本的每個失敗 attempt 值相同。 |
report_total_bytes | int | > 0 代表有報告。報告本體不在租戶 API。 |
stage_index, stage_count, stage_since, next_action | int, int, datetime?, string | 與版本的 build_stage_* 相同的階段進度資訊。 |
列表包裝：環境／版本／建置皆為 { items, page_size, next_page_token }。
任務 / 版本 / 分享
SandboxTaskCreateRequest
| 欄位 | 型別 | 限制 |
|---|---|---|
name | string | 1..256 |
description | string | 預設 ""，≤2048 |
owner_scope | enum | 只有 department / company（SandboxTaskCreateOwnerScope）。chatroom → 422。 |
owner_id | string | 1..36，id pattern。部門 id 或公司 id。 |
agent_enabled | bool | 預設 false。舊旗標。 Agent 目錄看房間啟用。 |
呼叫者不能擁有的 department／company scope → 403 owner_scope_forbidden。見 任務受眾。
SandboxTaskResponse
| 欄位 | 型別 | 說明 |
|---|---|---|
id, company_id, owner_scope, owner_id | string | |
name, description | string | |
agent_enabled | bool | |
state | string | active / archived（GET /tasks 會過濾隱藏的 quick-run 父任務）。POST /tasks/{id}/archive（後端 ≥ #1151）會將它改為 archived，並連帶歸檔版本、撤銷 binding。 |
security_state | string | |
current_published_version_id | string? | |
current_draft_version_id | string? |
SandboxTaskUpdateRequest（PATCH /tasks/{id}，後端 ≥ #1151）
只送要改的欄位；至少一個（否則 422 no_fields）。
| 欄位 | 型別 | 限制 |
|---|---|---|
name | string? | 1..256，不可空白 |
description | string? | ≤2048（可為空） |
agent_enabled | bool? | 任務層的 Agent 旗標；聊天室仍需 grant + enable |
SandboxContextObjectItemResponse／SandboxContextObjectListResponse（GET /environments/{id}/context-uploads，後端 ≥ #1151）
| 欄位 | 型別 | 說明 |
|---|---|---|
owned_object_id | string | POST .../versions 接受的 owned_object_id。 |
environment_id | string | |
byte_size | int | |
digest | string | 上傳封存的 sha256:<hex>；等於版本的 source_digest。 |
deletion_state | string | active 才能用；其他都是退場狀態，不能拿來建版本。 |
used_by_version_ids | string[] | 此環境中 source_digest 相同的版本。 |
created_at、expires_at | datetime? |
列表包裝 { items, page_size, next_page_token }；lifecycle 預設 active。絕不回儲存 key 或 URL。已經拿去建版本的上傳仍會列出（它會改綁到那個版本，used_by_version_ids 會寫出來——後端 ≥ #1156）；平台把物件退場後只在 lifecycle=retired／all 看得到。
SandboxTaskVersionCreateRequest / UpdateRequest
建立必填 environment_version_id。更新僅限 draft（PATCH）。
| 欄位 | 型別 | 限制 |
|---|---|---|
environment_version_id | string | 必須是 ready 版本。 |
startup_script | string | 預設 ""，≤1 MiB，禁 NUL |
work_script | string | 預設 ""，≤1 MiB，禁 NUL |
startup_script_id、work_script_id | string? | POST /tasks/{id}/script-uploads 回的 handle（24 小時，可重用）；內容會複製進 startup_script／work_script。與直接內嵌該腳本互斥。 |
ordinary_env | object? | 名字規則（與 secrets 合計 ≤100 個；每筆 ≤64 KiB；名字 ^[A-Za-z_][A-Za-z0-9_]{0,127}$；保留名 TEAMSYNC_… 拒絕）在這兩條草稿路由上不會被驗證——後端原樣存下，違規要到 run 認領時才被控制面擋下（而且僅限該版本宣告了 secret slot 的情況），結果是 run 失敗而不是 422。只有 Quick Run 的 ordinary_env 會在請求時就驗證。Writeback URL／token 走密封 secret 通道，不走這裡。 |
input_instructions | string? | ≤65536 |
input_example | string? | ≤65536。若設了 input_schema，必須符合它（草稿建立／更新時不符合會是 422 job_contract_invalid——發布不會重新驗證）。 |
input_schema | string? | ≤65536。JSON Schema（draft 2020-12）字串。設定後，每次提交的 input 都會照它驗證——不符合在派工前回 422 input_schema_violation。 |
work_command | string? | ≤4096 UTF-8 位元組（照位元組算，不是字元——非 ASCII 時位元組上限先擋下）。自由格式的 driver 指令列，例如 python3 /workspace/work.sh（work_script 永遠落地在 /workspace/work.sh，上傳檔名不保留——指向固定路徑，不是上傳時的檔名）。原封不動寫進 /workspace/driver.sh，在 startup.sh 之後 source（絕不是 argv）。空白／省略 → . /workspace/work.sh。含 NUL 或超長 → 422 job_contract_invalid。 |
timeout_seconds | int | 預設 1800；ge=1；le=604680（7 天 − 120 秒收尾包絡） |
secret_slot_declarations | list? | 見下。 |
requires_confirmation | bool | 預設 false。Agent 必須先提案、下一輪再 commit。Trigger 不能用。 |
output_policy | SandboxOutputPolicy? | 有型別，以 kind 區分的聯集：custom_table_writeback（table_id、allowed_ops create（預設）或 create,update）或 custom_table_command（command_id、chatroom_id、input_schema；v5.21.0）——見下。只有部門擁有。打進 canonical_digest。借用者永遠看不到。 |
secret_slot_declarations 形狀。 Owner 視圖存 list。每項是字串名字，或 { "name": "<slot>" }。name 必須符合 env-name pattern 且非保留字。Borrower／選單只露出 secret_slot_names: string[]。
SandboxOutputPolicy（以 kind 區分）
版本建立／更新請求，以及 owner 的版本回應上的 output_policy 是聯集型別；由 kind 選擇哪一支。兩支都是 extra="forbid"。
kind | 欄位 | 說明 |
|---|---|---|
custom_table_writeback | table_id（1..36 字元，id 格式）、allowed_ops（create 預設，或 create,update） | 限於單次 run 的表格 callback token。見任務受眾。 |
custom_table_command（v5.21.0） | command_id（≤36 字元，id 格式）、chatroom_id（≤36 字元，id 格式）、input_schema（自訂表格 CommandInput 的 list，≤200） | 限於單次 run 的 Command 憑證。見任務輸出交給自訂表格 Command。 |
舊版本這個欄位可能仍帶著歷史上未被解讀的物件（回應型別是聯集或一般物件）；新的寫入一律對聯集驗證。
SandboxRuntimeContract
每個 work script 執行時都套用的固定契約——除了 driver，其餘每個任務都一樣。出現在選單項目與 input-preview 回應的 runtime_contract 裡。
| 欄位 | 型別 | 說明 |
|---|---|---|
invocation | string | 固定：". /workspace/startup.sh && . /workspace/driver.sh"。 |
driver | string | 這個任務 /workspace/driver.sh 的內容——owner 看到真正的 work_command，否則是預設 fallback ". /workspace/work.sh"（borrower 永遠看不到真正那行）。 |
working_directory | string | 固定說明：runner 以 cwd=/workspace 啟動 /bin/sh session，但契約不保證工作目錄——腳本與 work_command 一律用絕對路徑 /workspace/...。 |
network | string | 固定說明：公司設定 runtime_egress_enabled 為 true 時（GET /settings；預設開啟），執行期可對外連線——startup_script／work_script 裡的 pip install／npm ci／go get 可以用，對外流量會計量（measured_egress_bytes）。仍建議把相依烤進環境映像（Dockerfile RUN 連得到公網；私有、loopback 與 metadata 網段仍被封鎖），執行才快且可重現。Operator 可關閉該公司的執行期 egress，關掉後工作階段的安裝會失敗。 |
inputs_file_env | string | 固定："TEAMSYNC_INPUTS_FILE"——存放這次 run 輸入 JSON 檔案路徑的環境變數名。 |
output_file_env | string | 固定："TEAMSYNC_OUTPUT_FILE"——存放腳本該把結果寫去哪裡的環境變數名。 |
artifacts_dir_env | string | 固定："TEAMSYNC_ARTIFACTS_DIR"（= /workspace/artifacts，startup.sh 之前建好、空的）——留在裡面的每個一般檔案都會變成可下載的產出物檔案（後端／runner ≥ #1152）。 |
artifacts | string | 人讀規則：子目錄保留為路徑前綴；遇到 symlink／hard link／特殊檔、..／控制字元、超過 1000 個檔案、路徑 >1024 B 或單一層 >255 B、總量超過 standard profile 上限（workspace 上限 − 16 MiB，最多 1 GiB）時整包拒收（run 照樣 completed，log 說明原因）。 |
input_delivery | string | 人類可讀說明：input JSON 會在腳本啟動前寫進 $TEAMSYNC_INPUTS_FILE。 |
secrets_delivery | string | 人類可讀說明：宣告的 secret slot 會在腳本執行前以環境變數匯出——絕不寫進磁碟。 |
SandboxInputPreviewRequest / Response（POST .../versions/{vid}/input-preview）
Request：{ input: <任意 JSON> }。不會派工。
| 回應欄位 | 型別 | 說明 |
|---|---|---|
input_file_content | string | 這個 input 會落在 $TEAMSYNC_INPUTS_FILE 的精確 UTF-8 位元組。 |
input_digest | string | sha256: + 64 hex——跟真的提交 run 會拿到的 digest 一樣。 |
runtime_contract | SandboxRuntimeContract | 只有呼叫者管理這個任務時，driver 才會反映真正的 work_command。 |
schema_valid | bool | input 符合版本的 input_schema（或根本沒設）時是 true。 |
schema_errors | string[] | ≤20 筆。schema_valid 時是空陣列。 |
SandboxScriptUploadResponse
| 欄位 | 型別 | 說明 |
|---|---|---|
id | string | 當 work_script_id／startup_script_id 用。 |
filename | string | 只作顯示；不會被解讀。 |
byte_size | int | ≤ 1 MiB。 |
sha256 | string | 驗證過位元組的 sha256:<hex>。 |
expires_at | datetime | handle 壽命（24 小時）。 |
SandboxTaskVersionResponse
| 欄位 | 型別 | 說明 |
|---|---|---|
id, task_id, company_id | string | |
version_number | int | |
state | draft / published / archived | |
content_state | active / scrubbed | 選單／執行需要 state=published 且 content_state=active。 |
environment_version_id | string | |
environment_id、environment_name | string | 後端 ≥ #1149。釘住的版本所屬的環境（GET /environments/{id} 用的 id）與顯示名稱——curated 或自家的都有。只有釘住的版本列已不存在時兩者才為空。 |
timeout_seconds | int | |
requires_confirmation | bool | |
secret_slot_names | string[] | 一定在（可為空）。 |
canonical_digest, content_hash | string | 精確版本身份。Approval 釘的是 canonical_digest。 |
published_at, archived_at | datetime? | |
update_available | bool | 有更新的已發布版本（binding 語境）。 |
input_instructions, input_example | string? | 出現在選單。 |
input_schema | string? | owner 與 borrower 都看得到——它描述的是呼叫者自己 input 的形狀，不是 owner 的實作。 |
runtime_contract | SandboxRuntimeContract? | 兩種視圖都有（不是 owner-only）：owner 視圖的 driver 回顯真正的 work_command，borrower 視圖是預設 fallback ". /workspace/work.sh"。 |
source_visible | bool，必填 | Owner source view 為 true；false 表示原始內容被隱藏，不是空值。Menu 永遠為 false。 |
startup_script, work_script, work_command, ordinary_env, secret_slot_declarations, output_policy | owner-only | borrower 為 null／隱藏（work_command 是 null，不只是缺席）。 |
SandboxShareCreateRequest / RevokeRequest / GrantResponse
建立：target_kind（chatroom、department、company）+ target_id + 可選 secret_slot_policies。有權的 owner 可直接分享到同公司任一存活聊天室，不必先建更廣的 grant。撤銷可帶最多 512 字的 reason；分享不會啟用 Agent。
| 請求欄位 | 型別 | 說明 |
|---|---|---|
secret_slot_policies | Dict[str, "borrower"|"owner"|"owner_overridable"]? | 逐 slot 的 secret 憑證來源政策。≤100 筆；key 必須是合法 slot 名。只能在建立時設定——要改就是撤銷再重新分享（開新 generation）。map 格式不對是 422 secret_slot_policies_invalid。見 Secret 與授權。 |
| 回應欄位 | 型別 | 說明 |
|---|---|---|
id, company_id, task_id, target_kind, target_id | string | |
generation | int | |
state | string | 活著 vs revoked。 |
active | bool | |
authority_applicable | bool | 聊天室改掛／刪除／authority bump 後為 false。 |
owner_authority_generation, target_authority_generation | int | |
revoked_at | datetime? | |
revoke_reason | string | |
secret_slot_policies | object? | 跟請求同一種形狀。回在 owner-manager 的分享路由上（三條都要求 _get_managed_task）——根本沒有 borrower 能打的分享端點會回 SandboxShareGrantResponse。Borrower 要看有效政策，得從選單／granted-jobs 的 secret_slots[].policy 讀。 |
Company-manager 歷史
GET /tasks/{task_id}/runs 回 SandboxTaskRunHistoryItem 的 JSON 陣列（不是 { items, page_token }）。搭配 GET /tasks/{task_id}/runs/numOfData → { num }。
Query：offset ≥0 預設 0、limit 1..100 預設 10、order asc/desc（依 queued_at 再 id）、可選 status、method（agent/manual）、executor_kind（internal_user/external_user）、source_kind（chatroom/department/external_platform）、department_id、chatroom_id。
歷史列欄位：id、task_id、task_version_id、status、queued_at?、started_at?、terminal_at?、duration_seconds?、cost_usd?（已結算 USD，未結算為 null）、executor_kind、executor_id、executor_display_name、source_kind、chatroom_id、chatroom_name、department_id、department_name、external_platform?（line/messenger/instagram/agent）、method、submission_source、resource_profile、error_code。
Granted jobs
| 模型 | 欄位 |
|---|---|
SandboxGrantedJobEnableRequest | task_version_id? — 省略則釘目前已發布版。 |
SandboxGrantedJobItemResponse | task_id、task_name、task_description、owner_scope、owner_id、secret_slots（SandboxSecretSlotStatus[]，啟用時對應釘住的版本，否則對應目前已發布版本）、enabled、binding_id?、pinned_task_version_id?、current_published_version_id?、update_available。 |
SandboxGrantedJobListResponse | chatroom_id、items。 |
Bindings
沒有 GET /bindings 列表。首選 granted-jobs 啟用。
請求
| 模型 | 欄位 |
|---|---|
SandboxBindingCreateRequest | chatroom_id, task_id, task_version_id（已發布且 active） |
SandboxBindingAcceptVersionRequest | task_version_id（同一任務的較新已發布版本） |
SandboxBindingRevokeRequest | reason ≤512 |
SandboxBindingResponse
| 欄位 | 型別 | 說明 |
|---|---|---|
id, company_id, chatroom_id, task_id, task_version_id | string | |
generation, share_generation, target_authority_generation | int | |
state | string | 選單要看到它，必須是 enabled。 |
update_available | bool | 有較新已發布版本；永不自動升級。 |
authority_applicable | bool | 分享／房間 authority 仍有效。 |
accepted_at, revoked_at | datetime? |
Secrets / approvals
值絕不回傳。建立／輪替／撤銷必須帶 Idempotency-Key（1..128 字元，禁 NUL）。
SandboxEncryptedValue（混合傳輸信封）
secret 值在線上唯一接受的形狀。明文 value 欄位一律拒絕。Client 端加密流程見 Secret 與授權。
| 欄位 | 型別 | 說明 |
|---|---|---|
encrypted_key | string | Base64，≤1024 字元。隨機 AES-256 金鑰，用 GET /public/info/model_key/public_key 以 RSA-OAEP-SHA256 包住。 |
iv | string | Base64，剛好 16 字元（不補 padding——大小正確的 12-byte IV 本來就不需要）。AES-GCM nonce。 |
ciphertext | string | Base64。AES-256-GCM ciphertext，GCM tag 附加在後。 |
SandboxSecretWriteRequest / RevokeRequest
| 欄位 | 型別 | 說明 |
|---|---|---|
consumer_scope | chatroom / department / company | 是 consumer，不是任務 owner。 |
consumer_id | string | |
task_id | string | |
slot_name | string | ^[A-Za-z_][A-Za-z0-9_]{0,127}$，且非保留。 |
encrypted_value | SandboxEncryptedValue（僅寫入，必填） | 解密後的值最少 4 UTF-8 bytes、最多 64 KiB，禁 NUL，永不回顯。撤銷沒有此欄。明文 value 一律拒絕，不管有沒有設金鑰對——四種可分辨的 422 slug 見 錯誤。 |
SandboxSecretBindingResponse / SandboxSecretOperationResponse
Binding：id, company_id, consumer_scope, consumer_id, task_id, slot_name, generation, state, has_provider_binding（bool）。沒有值、路徑、provider id。
Operation：operation_id, operation_type（create / rotate / revoke）, operation_state（SandboxSecretOperationState）, binding。
SandboxSecretApprovalCreateRequest
| 欄位 | 型別 | 說明 |
|---|---|---|
consumer_scope, consumer_id, task_id, task_version_id | string | Borrower 身份 + 精確版本。 |
task_version_digest | sha256:… | 必須等於已發布的 canonical_digest，否則 409 task_version_digest_mismatch。 |
slot_names | string[] | 1..100，不重複，合法 slot 名。 |
risk_accepted | true | 只能是字面 true。 |
撤銷：reason（預設 "revoked"，≤512）。別名路徑 /shared-task-secret-approvals 語意相同。
SandboxSecretApprovalResponse
id, company_id, consumer_scope, consumer_id, owner_scope, owner_id, task_id, task_version_id, task_version_digest, slot_set_hash（排序後名字的 sha256:）、generation, state, active, created_at, revoked_at。絕不帶 secret 值。
Runs
SandboxManualRunSubmitRequest
| 欄位 | 型別 | 說明 |
|---|---|---|
task_version_id | string | 已發布且 content_state=active。手動 REST：任何已授予版本。選單／Agent：已啟用的釘選。 |
input | 任意 JSON | Canonical JSON（見 內容）。 |
timeout_seconds | int? | ge=1，le=604680。省略 → 用版本預設。 |
Header：必須帶 Idempotency-Key（1..128 字元，禁 NUL）。
SandboxQuickRunRequest
僅 manager。name 1..256、environment_version_id、startup_script、work_script、ordinary_env（預設 {}）、input、timeout_seconds 必填。回傳 { task, version, run }。input 跟手動提交一樣會暫存（v5.10.11），因此會落在 $TEAMSYNC_INPUTS_FILE，run 的內容也回 has_input=true。
佇列背壓的 429 body
宣告為 POST .../runs、POST .../runs/{run_id}/retry 與 POST .../quick-run 的 429 回應。FastAPI 會把 body 包在 detail 裡，所以具名元件是外層信封。什麼都沒排入佇列。
| 模型 | 欄位 |
|---|---|
SandboxQueuedRunLimitErrorResponse | detail：SandboxQueuedRunLimitError——code 固定為 sandbox_queued_run_limit、message、limit（int ge=1，觸及的上限）。 |
SandboxQueueFullErrorResponse | detail：SandboxQueueFullError——code 固定為 queue_full、message、limit（int ge=1，整個 fleet 的佇列上限）、retry_after_seconds（int ge=0，也以 Retry-After 送出）。僅地端部署。 |
SandboxSecretSlotStatus
逐 slot 的 borrower／owner 履行狀態——只有 metadata，絕不含 secret 值、binding id 或 provider 路徑。出現在選單項目與 granted-job 項目的 secret_slots[]。
| 欄位 | 型別 | 說明 |
|---|---|---|
name | string | Slot 名稱。 |
policy | borrower / owner / owner_overridable | 這筆 grant 的逐 slot 政策（分享時沒設就預設 borrower）。 |
borrower_bound | bool | 借用方是否對這個 slot 有 live binding。 |
owner_bound | bool | Owner 是否對這個 slot 有 live binding。 |
effective_source | borrower / owner / missing | 現在提交 run 的話，實際會用哪一邊供值。 |
SandboxMenuItemResponse
| 欄位 | 型別 | 說明 |
|---|---|---|
task_id, task_name | string | |
task_description | string | |
owner_scope, owner_id | string | |
task_version_id | string | 提交時用這個。 |
task_version_digest | string | Approval 用的精確 digest。 |
version_number | int | |
version_state | string | 選單上是 published。 |
input_instructions, input_example | string? | |
input_schema | string? | input 必須符合的 JSON Schema（否則提交是 422 input_schema_violation）。 |
secret_slot_names | string[] | |
secret_slots | SandboxSecretSlotStatus[] | 逐 slot 履行狀態（版本沒宣告 secret slot 就是空陣列）。 |
timeout_seconds | int | |
requires_confirmation | bool | Agent 確認；人類仍走 POST /runs。 |
update_available | bool | Binding 有較新已發布版本。 |
secret_use_risk_warning | string? | 此版本會用到 borrower secrets 時出現。 |
runtime_contract | SandboxRuntimeContract? | 選單上的 driver 永遠是預設 fallback ". /workspace/work.sh"，就算是擁有 scope 的管理者也一樣——_menu_item_from_view 寫死 build_runtime_contract(None)，選單永遠不會帶真正的 work_command。要看真正的 driver，請走 GET /tasks/{id}/versions/{vid}（owner 視圖）或以管理者身分打 POST .../input-preview。 |
沒有腳本原文。 選單 page_size 預設 50；後端 ≥ #1149 起 next_page_token 是真的游標（依 task_id 排序），之前永遠 null。
SandboxSlotProvenance
Run 凍結的 secret 快照裡，逐 slot 的遮蔽解析溯源——絕不含 fingerprint、binding id 或 provider 路徑。
| 欄位 | 型別 | 說明 |
|---|---|---|
resolved_via | borrower / owner | 這次 run 這個 slot 實際是哪一邊供的值。 |
consumer_scope | chatroom / department / company | 這次 run 解析時用的 consumer scope。 |
SandboxRunDetailResponse
| 欄位 | 型別 | 說明 |
|---|---|---|
id, company_id, chatroom_id | string | |
status | SandboxRunState | 有 terminal_at 就是終態。 |
resource_profile | string | 繼承自環境版本。 |
principal_type | user / social_media_client | |
principal_id | string | 行為主體。Restricted key 只能看自己的。 |
auth_method | jwt / api_key | |
task_id, task_version_id | string | |
timeout_seconds | int | |
submission_source | string | rest / agent / quick_run / custom_table_trigger。未設時為空字串。 |
error_code、error_detail | string | 失敗來源；completed 時為空。error_detail ≤128，[A-Za-z0-9._@:/+=%;-]。 |
exit_code | int? | 工作指令真正的結束碼（未終態時 null；completed 為 0）。 |
failure_stage | enum | '' / task_bundle / secret_env / workspace / spawn / metering_arm / metering_start / metering_wait / metering_terminal / work / output / timeout / cancel / egress_cap / wait |
failure_source | enum | '' / runner / reconcile / dispatch / submit / policy / tenant |
wait_reason | enum | '' / awaiting_dispatch / company_saturated / no_active_region / missing_image_digest / capacity_snapshot_stale / provider_capacity_exhausted / provider_submit_pending / provider_submit_uncertain / container_starting / cancel_pending。非終態 run 還沒跑起來的原因；running 與終態為空。 |
next_action | string | ≤400。對應 wait_reason 的指引；wait_reason 為空時也為空。 |
wait_since | datetime? | 目前這段等待開始的時間。 |
queue_position | int? | ge=1。在 run 等待 run slot 的佇列中的位置；已被認領或派送、或沒在等待時為 null。雲端：在公司 queued run 中。地端：在 executor 佇列中，starting 時也有。 |
eta_seconds | int? | ge=0。等待中的 run 大約還要幾秒開始，依佇列位置、fleet 的 run slot 數與同一 profile 近期已完成 run 的平均耗時估算。沒在等待或沒有歷史時為 null——絕不是猜的數字。託管雲端一律 null。 |
failure_hint | string | ≤400。失敗終態的修法建議（由 error_code／exit_code 推出）；其餘為空。 |
measured_ingress_bytes、measured_egress_bytes | int | 工作階段計量的網路位元組。 |
input_digest | string | 提交 input 的 canonical hash。 |
retry_of_run_id | string | 不是 retry 則為空。 |
error_code | string | 成功時為空。 |
queued_at, terminal_at | datetime? | 輪詢 terminal_at。 |
secret_slot_provenance | Dict[str, SandboxSlotProvenance]? | 逐 slot 的遮蔽解析結果，在 run 的 secret pin 於認領時發布（publish）那一刻凍結。Run 沒有留存快照、或快照裡每一筆都格式不對被跳過時是 null。 |
cancel_requested_at 有持久化（PR #951 的 cancel provenance），但不在此回應。看 status=cancel_requested 再變 cancelled。Run 提交時凍結的 share_grant_id 同樣只是內部用——不在此回應上。
SandboxRunContentResponse
只有旗標。沒有本體、沒有 object key。
| 欄位 | 型別 | 說明 |
|---|---|---|
run_id, company_id | string | |
state | string | 還沒有 content 列時是 "missing"。 |
input_digest | string | |
has_input, has_output, has_log, has_artifact_bundle | bool | 沒有租戶端點回傳 log／output 位元組。 |
SandboxRunArtifactItemResponse
id, run_id, relative_path, path_hash, byte_size, digest, deletion_state（active / delete_pending / deleted / tombstoned）、declared_content_type。
SandboxArtifactDownloadCapabilityResponse
| 欄位 | 型別 | 說明 |
|---|---|---|
artifact_id, run_id, company_id | string | |
capability_token | string | 不透明 token_urlsafe(32)。不是 URL。 |
expires_at | datetime | now + 5 分鐘（_DOWNLOAD_CAPABILITY_TTL）。 |
content_type | string | application/octet-stream |
content_disposition | string | attachment; filename="…"（已消毒）。 |
x_content_type_options | "nosniff" |
前端實際能拿這個 token 做什麼，見 內容、Digest 與下載。
SandboxArtifactPublicLinkResponse（POST/DELETE .../artifacts/{artifact_id}/public-link，後端 ≥ #1149）
| 欄位 | 型別 | 說明 |
|---|---|---|
run_id、artifact_id | string | |
relative_path | string | 檔案在任務包裡的路徑（只作顯示）。 |
object_kind | "artifact" | |
url | string | {base}/public/sandbox/artifacts/{token}——永久有效，驗過記錄的 sha256 後只串流這個檔案的位元組區間，不是整個 bundle。免登入。 |
token | string | 16..64 字元，不可猜。 |
revoked | bool | |
created_at | datetime? |
SandboxPublicLinkResponse（POST/DELETE .../{kind}/public-link）
| 欄位 | 型別 | 說明 |
|---|---|---|
run_id | string | |
object_kind | log / output | 絕不是 artifact。 |
url | string | 完整永久公開 URL（{base}/public/sandbox/artifacts/{token}）。沒有 TTL。撤銷回應如果本來就沒有連結，會是空字串。 |
token | string | 16..64 字元。撤銷回應如果本來就沒有連結，會是 0000000000000000 佔位符（不是活著的 token）。 |
revoked | bool | 撤銷回應是 true。 |
created_at | datetime? |
鑄造是冪等的（回既有的 live 連結）；先撤銷再鑄一次會拿到新token。受限 Sandbox API 金鑰打這兩條路由都是 404。
SandboxCommandOutputRequest（POST /public/module/custom_tables/callback/command-output/{token_id}，v5.21.0）
公開路由，授權是 TEAMSYNC_CT_WRITEBACK_TOKEN 的 Bearer secret——不是租戶路由。Body 是 { "inputs": object }，沒有別的（extra="forbid"）。inputs 在解析 body 時先檢查自訂表格 Command 的 JSON 上限，處理呼叫時再對照 Command 宣告的輸入（422 output_schema_violation）。回應是 Command 的執行回應（CommandExecutionResponse，省略 null 欄位）。見任務輸出交給自訂表格 Command。
Agent 工具輸入（不是 REST）
這些是 LangGraph 工具參數。從不帶 company／chatroom／principal／turn 身份——伺服器在帶外附上。見 Agent toolkit。
| 模型 | 欄位 |
|---|---|
SandboxAgentMenuInput | page_size, page_token?, query?（≤256） |
SandboxAgentSubmitToolInput | mode=request：task_version_id + input + 可選 timeout_seconds。mode=commit：只能有 proposal_receipt（≤4096）。 |
SandboxSubmittedJobsInput | page_size, page_token? |
SandboxJobStatusToolInput | run_id, wait_seconds 0..60, artifact_page_token? |
SandboxCancelJobInput | run_id?（省略 = 取消此 principal 待確認提案） |
本頁刻意不列
/sandbox-control/*請求本體（託管雲端：OIDC + capability；地端 work lease：executor-token 驗證；不是前端）。/root/sandbox/*請求本體（營運面；見 營運與 Root）。src/schemas/sandbox.py裡的SandboxWorkQueueResponse／SandboxWorkQueueItem／SandboxExecutorCapacity屬於營運路由GET /root/sandbox/queue，不是租戶路由。- Provider 名稱、object key、presigned URL、secret 值。
目前的管理查詢與執行型別（v5.10.0）
SandboxPrincipalCapabilitiesResponse、SandboxCompanyRunListResponse、task／room binding 清單，以及遮罩 secret／approval 清單，請見能力與管理查詢。Binding／secret／approval 管理清單使用 truncated；/runs 與有分頁的目錄仍使用 cursor。
新的 secret-slot declarations 使用 SandboxSecretSlotDeclarations：每個物件必須有合法、非保留名稱的 name，同時保留可選 metadata。讀取側 SandboxStoredSecretSlotDeclarations 仍接受歷史字串／不透明宣告，不要在讀取時改寫。region_readiness 是 live region code 到 ready／not_ready 的 map。
SandboxRunRetryRequest 含可省略的 input：缺席／null 重放來源位元組，非 null 值提供新輸入，請見重試契約。SandboxRuntimePricing 包含幣別、費率／界線版本、各區 profile 費率、進出站費率、最低計費時間、finalization 時間與 outbound 預留界線，請見執行規劃。
Environment 回應除了 owner_kind，也有 owner_scope 與 owner_id。owner_kind=company 仍表示 tenant-custom，不代表 owner_scope=company。