Arcrun/.agents/specs/resumable-workflow/design.md

SDD: Resumable Workflow（webhook callback 喚醒）

2026-05-07 建立。狗糧寫 wiki 合成 workflow 時，Mira daemon 對長草稿（>2KB）切非同步模式回 {pending, task_id, poll_url}，cypher-executor 沒處理就直接傳下游。 本 SDD 解這層：workflow 跑到一半遇到 pending 任務 → 暫停 + 持久化狀態 → 外部 callback 進來時喚醒繼續。 範圍：兩家自家服務之間（Mira daemon ↔ cypher-executor）走 webhook 推。對外服務無 webhook 的場景留 wishlist 用 poll 解。

---

1. 問題

1.1 撞牆現場

wiki 合成 workflow 第一節點 claude_api(recipe:wiki_synthesis)：

• 短草稿（< 2KB）→ daemon 同步回 {success, data: {text}}，recipe output parser 解 JSON 成功
• 長草稿（> 2KB）→ daemon 估 75s，切非同步模式回：

{
  "success": true,
  "pending": true,
  "task_id": "task_14_1778133152480",
  "poll_url": "https://mira.uncle6.me/mira/execute/task_14_1778133152480",
  "estimated_seconds": 75
}

cypher-executor 拿到這個物件就當 result，但裡面沒 data.text，下游 recipe output parser 找不到要 parse 的東西，整個 workflow 算「success」但實際上 wiki 還沒生出來。

1.2 現有 toolkit 不夠

• wait 零件：固定 sleep N ms，沒 retry / 條件判斷
• http_request 零件：通用 HTTP，不認 daemon 的 polling 協議
• cypher-executor visited Set：擋住節點重訪，沒辦法做迴圈式 poll
• Worker CPU 30s 限制：同步 poll 75s 任務不可能

1.3 Push vs Pull 抉擇（2026-05-07 拍板）

	Webhook 推	Poll 拉
適用	雙方都自家	對方無 callback 能力
Worker 時間消耗	趨近 0	全程占用
時長限制	無	Worker CPU 30s
工程位置	runtime 能力（cypher-executor）	零件（poll_task）

走 Webhook 推（自家服務優先，poll_task 進 wishlist）。

---

2. 設計

2.1 三層改動

A. Mira daemon 端（infra/cloud-cto）

• /mira/execute 接受新欄位 callback_url: string（optional）
• task 完成時 POST 到 callback_url，body：

  {
    "task_id": "task_14_xxx",
    "success": true,
    "data": { "text": "..." }
  }
  

• 失敗也要 callback，body 含 error 欄位
• 重試策略：3 次 backoff（1s / 5s / 30s），最後失敗就放棄（task 狀態存進 daemon 自己 KV）

B. cypher-executor 端（resumable runtime）

新概念：workflow run 可以暫停。

設計：

1. 新 KV namespace（或用既有 EXEC_CONTEXT）存暫停的 run state：
   • key: paused_run:{task_id} 或 paused_run:{run_id}
   • value: { run_id, graph, paused_node_id, paused_node_pending_result, context, trace_so_far, kv_store_ref, expires_at }
2. graph-executor 偵測節點 result 含 pending: true + task_id → 暫停 + 寫 KV + 回 {paused: true, task_id, run_id}
3. 新 endpoint POST /workflows/resume：
   • body: { task_id, result }（result 是 daemon callback 給的完整資料）
   • 從 KV 拿 paused state → merge result 進 paused_node 的 output → 從下個節點繼續執行
4. claude_api 容器呼叫 daemon 時自動帶 callback_url：
   • https://cypher.arcrun.dev/workflows/resume?task_id={預先派發的 task_id}
   • 但 task_id 是 daemon 自己派的，cypher-executor 不知道。需先 daemon 派完 task_id 才能組 URL
   • 解：daemon 改成「先回 task_id，再啟動實際工作 + 完成時 callback」— 兩階段 hand-shake

實際流程（兩階段）：

cypher-executor                 Mira daemon
       │                              │
       │ POST /mira/execute           │
       │ { prompt,                    │
       │   callback_url: "?run_id=R1" }
       ├─────────────────────────────>│
       │                              │ 立即回 task_id（決定走非同步）
       │<─────────────────────────────┤ { pending, task_id: T9 }
       │                              │
       ├─ 看到 pending → 寫 KV         │ 啟動實際 LLM 任務
       │  paused_run:T9 = {run R1,    │
       │  paused_node, ctx, ...}      │
       │                              │
       │ 立即回 client (MCP)：         │
       │ { paused, task_id: T9 }       │
       │                              │
       ⋯⋯⋯⋯⋯ 75s 後 ⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯
       │                              │ task done
       │ POST /workflows/resume       │
       │ { task_id: T9, result: {...} }
       │<─────────────────────────────┤
       │                              │
       │ 從 KV 取 paused_run:T9       │
       │ → merge result 進 paused 節點 │
       │ → 從下個節點繼續              │
       │                              │
       │ run 跑完 → 寫 trace          │
       │ → 通知 client (?)            │
       │                              │

2.2 範圍邊界

第一版（v1）做：

• ✅ 單節點 pending → resume（最常見：claude_api 拿到 daemon pending）
• ✅ daemon 加 callback_url 支援
• ✅ cypher-executor /workflows/resume endpoint
• ✅ run state 寫 EXEC_CONTEXT KV，含 24h TTL（避免 KV 累積）
• ✅ 整合測：用 wiki 合成跑長草稿，驗 callback 進來能繼續

第一版不做：

• ❌ 多節點都 pending 的 nested 場景（例如 claude_api → 又一個 claude_api）— v2
• ❌ foreach 內 pending（item-level resume）— v2
• ❌ pending 期間用戶看到「進度」的前端 UI — 走 trace 有 paused 標記，前端 polling 自己做即可
• ❌ pending callback 失敗時的 retry / DLQ — v2，先記 log

前置依賴：

• ✅ recipe-system 已部署（cypher-executor 已會解 recipe）
• ✅ Mira daemon 在 Hetzner，可改 code

2.3 為什麼不用 Cloudflare Queues / Durable Objects

• CF Queues：適合大量 fan-out，這裡是點對點 callback，KV 已夠
• Durable Objects：long-lived state 比 KV 強，但成本高 + 複雜
• EXEC_CONTEXT KV：既有 binding，工程量最小

未來真撞到 KV 限制（每 partner 寫入頻率上限）再升級。

---

3. 詳細設計

3.1 daemon 端 callback 機制

infra/cloud-cto/index.js（Mira daemon）：

// /mira/execute handler
{
  // 既有 input + 新加：
  callback_url: string  // optional
}

// 處理邏輯：
// 1. 啟動 task（既有邏輯）
// 2. 預估時間 > 30s → 切非同步：
//    - 立即回 { success: true, pending: true, task_id, poll_url, estimated_seconds }
//    - 背景 task 完成時：
//      if (callback_url) POST callback_url with { task_id, success, data, error? }
//      （不論用戶有沒有 poll，callback 一定會送）

callback 失敗策略：

• 3 次重試（1s / 5s / 30s）
• 全失敗：task 狀態維持完成，等 client 主動 poll（poll_url 仍有效）
• 超過 24h 沒被消化的 task：daemon GC

3.2 cypher-executor 端 resumable runtime

3.2.1 偵測 pending（graph-executor）

在 Component case，runner 回傳後：

result = await runner(mergedContext);

// 偵測 pending pattern（daemon 約定的回應結構）
if (isResumablePending(result)) {
  await persistPausedRun(this.env.EXEC_CONTEXT, taskIdFromResult(result), {
    run_id, graph, paused_node_id: node.id, paused_context: context,
    paused_result: result, trace_so_far: trace, expires_at: Date.now() + 24*60*60*1000
  });
  // 提早結束此 run，回 paused 狀態
  return { paused: true, task_id, run_id };
}

// ... 既有的 recipe output parsing / kvSetNodeOutput / 等

isResumablePending(result) = result?.pending === true && typeof result?.task_id === 'string'

3.2.2 callback URL 注入（claude_api 之前的 layer）

問題：claude_api 容器發 daemon 請求時，要帶 callback_url。但 task_id 是 daemon 派的，URL 裡只能放 run_id，daemon 收到 callback 時填 task_id：

callback_url = https://cypher.arcrun.dev/workflows/resume?run_id={current_run_id}

但 cypher-executor 端用 task_id 找 paused state（一個 run 可能多個 pending），所以 callback URL 應該是：

callback_url = https://cypher.arcrun.dev/workflows/resume（不帶 query，task_id 在 body）

實作位置：在 graph-executor 呼叫 claude_api 前，自動注入 callback_url 到 mergedContext：

if (node.componentId === 'claude_api' && this.env?.PUBLIC_BASE_URL) {
  mergedContext.callback_url = `${this.env.PUBLIC_BASE_URL}/workflows/resume`;
}

暫先用「componentId 寫死匹配」是 hacky，未來 component contract 加 supports_async_callback: true 標記就 generic 了。

3.2.3 resume endpoint

POST /workflows/resume：

{
  task_id: string,  // daemon 給的
  success: boolean,
  data?: { text: string },  // 跟同步呼叫一樣的結構
  error?: string
}

處理：

1. 從 EXEC_CONTEXT KV paused_run:{task_id} 拿 state
2. 沒拿到（過期 / 重複 callback）→ 回 200 + log
3. 把 callback 給的 result 當作 paused_node 的 output
4. 重建 GraphExecutor，從下個節點繼續執行
5. 跑完寫完整 trace

問題：resume 後沒辦法再回給原 client。 用戶最初打 /cypher/execute（同步），拿到 {paused, task_id} 之後就斷了；resume 跑完 result 沒地方送。

v1 解法：resume 完寫進 analytics_kv 或 D1，用戶要主動 query。簡單但 UX 差。 v2 想法：resume 完發另一個 webhook 給原 client（client 在 trigger 時帶 final_callback_url）。

---

4. 範圍

在本 SDD 範圍內：

• 4.1 daemon /mira/execute 加 callback_url 支援
• 4.2 cypher-executor 偵測 pending + 持久化 paused state
• 4.3 cypher-executor /workflows/resume endpoint
• 4.4 callback_url 自動注入（claude_api 場景）
• 4.5 wiki 合成 workflow 用長草稿端對端測試

不在本 SDD 範圍：

• nested pending（v2）
• foreach 內 pending（v2）
• final_callback 給原 client（v2）
• poll_task 零件（wishlist）

---

5. 驗收標準

1. wiki 合成 workflow 餵 5KB+ 草稿，跑完後 wiki page 有寫進 KBDB（不再 trace pending 假成功）
2. trace 有 paused 紀錄，能看到 task_id
3. 從 daemon 觸發 callback 後 < 5s 內 cypher-executor 把 paused state 撿起來繼續
4. 24h 沒 callback 的 paused state KV 自動 expire（看 KV TTL 列表）

---

6. 風險

風險	緩解
daemon callback 進來時 cypher-executor 重啟 → state 還在 KV，OK	KV 持久化
同 task_id 重複 callback（網路重試）→ 重複執行下游	resume endpoint idempotent：拿到 state 後立刻刪 KV，重複 callback 找不到 state
daemon callback 失敗（網路）	daemon 端 3 retry + 24h GC，超過就需手動干預（v1 接受）
paused state 含敏感資料（partner key）	KV 有 24h TTL；不寫 plaintext secrets（既有 credential injection 在執行前才解，paused state 存的是執行前的 context，secret 還沒解）

---

7. 變更紀錄

版本	日期	內容
v1.0	2026-05-07	初版。狗糧 wiki 合成撞 daemon 非同步 → 補 resumable workflow runtime。第一版只做單節點 pending + claude_api callback 注入。