把託管式 Heddle Agent 準備至正式環境

身分與授權

• 建立 Heddle run address 或 repository scope 前先完成 authentication。
• 在受信任的 server 端取得 tenant、account 與 user identity。絕不信任 browser 傳入的 account ID。
• 分別授權 start、subscribe、cancel、approval resolution、session read、reset 與 artifact access。
• 使用穩定的 product conversation ID，並在 application service 與 storage adapter 兩層都強制 tenant isolation。
• 對未知或錯誤範圍的 runId 回傳 not found；持有 ID 不代表已授權。

憑證、能力與政策

• 在 server 端依據已驗證的產品 context 解析 model credential。
• 在 composition root 選擇 model、reasoning effort、system context、product tool、MCP extension 與 capability policy。
• 檢查 tool schema 與 output 的 tenant/data boundary。
• 定義誰可以核准每一種敏感操作，以及 approval UI 如何證明核准者身分。
• Denial 與 timeout 行為必須可預測。缺少 approval UI 時，絕不能默認為核准。

持久儲存

預設 JSON session repository 適合單機、本機優先產品。請把 stateRoot 指向具有一般 local locking 與 atomic rename semantics 的 durable application data。不要把它放在 eventually consistent object-store mount 上。

Hosted 或 multi-process product 應注入 async、revisioned ChatSessionRepository。Database update 與 delete 必須原子比較 expected revision，避免 concurrent writer 靜默覆蓋較新狀態。Adapter 必須區分 missing record、already-existing record 與 revision conflict，並使用 deterministic cursor 分頁。

若 generated content 應放在 object/blob storage，請注入 ArtifactRepository。明確定義 content addressing、tenant scope、retention、encryption、backup 與 deletion。

Trace 與 memory 目前仍持久化在 stateRoot 下，尚未提供相同的 injectable repository boundary。請據此規劃宿主 filesystem 與 retention policy，不要假設所有 Heddle record 都在產品 database 中。

對外 contract 與傳輸安全

• 使用嚴格 schema 驗證每個不受信任的 request 與 response。
• 只公開經授權的 activity 與 terminal field。除非產品明確需要且已授權，否則排除 tool input/output、filesystem path、trace、provider message、credential 與 internal session record。
• 設定 payload limit、CORS、rate limit、request timeout、secure header 與 audit log。
• 把 internal failure 投影成穩定 public code 與安全 message，同時在 server 端保留原始診斷。
• 當獨立 client 依賴 public API 與 event schema 時，請建立版本政策。

重播與客戶端復原

• 只有在應用程式處理完成後才保存最後 sequence。
• Cursor 要與它所代表的 visible projection 一起持久化，否則 reload 可能跳過內容。
• 測試 duplicate replay、sequence gap、串流未收到 terminal 就結束、malformed stored checkpoint、offline recovery 與 retry budget exhausted。
• Reconnect 必須有界且可見。不要把 authorization 或 validation failure 當成 transient server error 重試。
• Terminal settlement 後重新取得 durable conversation state。

行程拓樸與傳遞

ConversationRunService 的 replay 位於單一行程且有界。它不是 restart recovery，也不是 distributed broker。

• 決定哪個 process 擁有 run，以及每個 operation 如何到達它。
• 多 instance 部署必須定義 sticky routing，或加入 shared routing 與 delivery infrastructure。
• 定義 shutdown 與 draining 行為：停止接受新 run、避免 active result projection 與 shutdown 競爭，並完成或明確取消工作。
• 依 event volume、reconnect expectation 與 memory use 調整 replay limit 與 retention。
• 驗證 deploy、crash、provider stall、storage failure 與 client disconnect 時的行為。

產品 finalization

使用 projectResult 在 Heddle 發布成功前持久化或 reconcile 經授權的 product state。使用 projectError 防止 internal diagnostic 進入 retained public replay。請決定 product finalization 是否 idempotent、如何偵測 retry，以及 persistence 成功但後續 response delivery 失敗時如何處理。

可觀測性與營運

• 串連 product conversation ID、Heddle session ID、run ID、trace 與 public request ID，但不要公開敏感值。
• 記錄 run acceptance、terminal kind、latency、cancellation、approval wait、model failure category、storage conflict、reconnect exhaustion 與 projection failure。
• 對 stuck active run、repeated lease conflict、replay exhaustion、authentication failure，以及 provider quota/rate-limit category 建立 alert。
• 分開 trace 與 public activity：trace 是診斷證據，activity 是使用者可見進度。
• 提供 support tooling 檢查安全的 run/session status，但不授予廣泛 filesystem 或 tenant access。

發佈前檢查

部署前至少驗證：兩個 turn 重用一個 durable session；concurrent writer 不會遺失更新；disconnect 不會取消；cursor reconnect 不會重複或重啟工作；wrong-scope access 被拒絕；cancellation 到達 terminal；approval decision 鎖定確切 run；storage/projection failure 仍維持 failure；只有預期 public field 跨越 transport；active run 在 shutdown 時有可預測行為。