Quest ライフサイクル

01背景と課題

現在の kage は cron ベースのみ。1タスク=1プロンプトを決まった時刻に起動し、Memory で線形に状態を保つ。人間のリアルな仕事――"ぼんやりした方向"から 0 で現状を調べ、PoC を回し、ROI で撤退/拡大を繰り返す――とは質が違う。

02全体アーキテクチャ

cron と quest は同じ kage cron run 1分 tick に乗り、新しく常駐プロセスは立たない。quest のノード実行は既存の executor.execute_task を再利用するため、run 履歴 / log / metadata が cron と同一。

034つのロール = 総合力チーム (v2)

v2 では ロールは Quest 作成時に宣言。デフォルト (team モード) scout,poc,strategist,owner。各ロールは provider + プロンプト雛形を持ち、実行時に具体化。--solo でv1動作(scout/pocが直接spawn)に戻る。--provider claude 等でチーム単位の AI 指定も可。

04マインドマップ = タスクグラフ

直線的なチェックリストではなく、親から子へ枝分かれし、死んだ枝は aborted、有望な枝は grew_to で延伸。SQLite の 3 テーブルで永続化。

ノードのライフサイクル

# pending → run → {explored | growing | aborted}
pending  → running → explored   # 結論のみ・分岐なし
pending  → running → growing    # promising → 子 poc を展開
pending  → running → aborted   # dead → strategist を spawn

051 分 tick の中身

アクティブな quest ごとに 最大1ノード を dispatch。実行は同期待ちで execute_task に乗せ、完了後に verdict JSON を parse して子ノード/エッジを生成。agent_runs を +1。

AI との出力契約 (Output contract)

```json
{ "verdict": "promising (有望)" | "dead (撤退)",
  "evidence": "<要約>",
  "new_directions": ["<次に試す仮説>", ...] }
```

06暴走防止 — 終了条件

07データモデル

id, project_path, name, direction,
status (active|done|terminated|stopped),
max_agent_runs, agent_runs,
roles_json, provider, created_at, updated_at

id, quest_id, parent_id, role,
hypothesis,
status (pending|running|explored|
       aborted|growing),
verdict, evidence, run_id,
created_at, updated_at

quest_edges

id, quest_id, from_node, to_node,
relation (spawned|aborted_to|grew_to), created_at

08CLI

kage quest new <name> --direction "..." \
            [--roles scout,poc,strategist] [--max-agent-runs 50] \
            [--provider claude] [--project <path>]
kage quest list        # id / 名前 / 状態 / runs / ノード数
kage quest show <id>   # ノード + エッジ表で表示
kage quest stop <id>
kage quest resume <id>
kage quest abort-node <node_id>

quest 実行は既存の kage runs / kage logs にもそのまま載る。task 名は quest:<quest_id>:<node_id>。

09ざっくり使ってみる

kage quest new ocr-hunt \
  --direction "日本語請求書PDF向けの無料OCRで最大精度を探す" \
  --max-agent-runs 80 --provider claude
# あとは寝る。1分ごとに scout→poc→... が回り、
# 朝には死んだ枝が abort され、有望枝が grow した状態で記録される。
kage quest list
kage quest show <id>     # グラフ＋検証結果を一覧
kage runs                 # quest の各ノードもここに並ぶ

15v3.2 設計: Team と工程 (planner→executer→accepter)

ユーザー指摘: scout/poc は「ロール」よりTeamという上位概念で持て。Team 内で planner → executer → accepter (受け入れテスター) の工程を回し、accepter が ng なら工程へ差し戻し。accept されたら初めて owner へ返せ。

階層構造

Team は1ノード、各工程は子ノード。Teamは編成単位、工程は社内 pipeline。owner は Team に dispatch し、Team は accept されたとき初めて owner に verdict を返す。

工程ごとの役割

差し戻しループ

planner ─▶ executer ─▶ accepter
   ↑                         │
   └── # reject (revision_target=planner)
        ↑
        └── executer だけ差し戻し (revision_target=executer) も可

accept ─▶ Team 完了 verdict ─▶ owner へ
reject は max_revisions で暴走防止
cap 超過 ─▶ Team team_blocked ─▶ owner に fail verdict → 再判断

accepter は looper の judge と同じ。reviewer は notes のみ。reviewer-only は clean 宣言できない (looper gate rule 互換)。

Team ごとの accept 基準

verdict flow

Team (pending) ← owner.dispatch (stages_into)
planner (proposed→running→explored) ─makes_plan→ executer
executer (proposed→running→explored) ─executes→ accepter
accepter (running) ─ judge
  ├─ accept ─▶ Team (explored) ─▶ owner へ verdict 返却
  └─ reject ─▶ revision_target (revising) ─▶ planner/executer 差し戻し
                max_revisions 超過 → team_blocked → owner に fail

schema 予約

quest_nodes.team_kind: scout|poc|strategist|custom
quest_nodes.stage: plan|exec|accept|revising
quest_nodes.revision_count, max_revisions
quest_edges.relation: stages_into, makes_plan, executes,
                       rejects_to, accepts_to

4モード階層 (互換性)

• --mode solo: v1 (直接 spawn, 工程なし)
• --mode team --council "": v2 (owner 単独, 工程 skip の簡易)
• --mode team --council "reviewer:2,judge:1": v3.1 (council)
• --mode team --council "...": v3.2 (Team + 工程 + council accepter)

デメリット (追加分)

• さらに遅い: 1 work で planner+executer+accepter の最低3 tick。revision 含めると 3+3*rev。24h と loop_control で整合必須
• graph が深くなり可視化が煩雑: kage ui /quests で Team 折りたたみ表示が必須
• accepter 判定ミスで無駄 revision: revision_target を誤ると間違った工程に差し戻し。max_revisions キャップ必須
• CLI 設定項目増: --teams / --accept-mode / --council / --max-revisions。preset 化が必要

14v3.1 設計: looper から学んだ role 設計

参考: ksimback/looper · @0xCodez loop engineering · @shannholmberg looper

looper は「設計 → 実行」の2層 + council (reviewer/judge) + programmatic検証 で「same model grading its own homework」を排除する。kage v2 の owner 単独はまさにその blind spot で、v3 は区別を取り込む。

reviewer vs judge (council_member を置き換え)

--council "reviewer:2,judge:1" 形式で構成。reviewer-only gate は fixed_passes のみ。clean 宣言は禁止。

3つの検証 type (looper 互換)

programmatic: # 無料・deterministic
  check: ["pytest", "tests/test_quest.py"], expect: exit_zero
judge: # rubric + 構造化 verdict
  rubric: "少なくとも2つの独立 evidence が同方向"
human: # kage connector 経由で consent
  prompt: "Discord で 📌 で同意"

明示 gate (scout/poc/synthesis)

loop_control 拡張 (暴走防止)

max_iterations: 50          # = max_agent_runs 後方互換
budget:
  tokens: 2_000_000
  wall_clock_min: 1440       # 24h (既存 max_wall_minutes 列に統合)
no_progress:
  max_stalled_iterations: 3
  signals: ["同じ issue が繰り返し", "evidence 3ラウンド不変"]
  action: stop
human_checkpoints: [scout_gate]   # connector 経由

v2 の max_agent_runs だけでは「動いている間に実質進んでいない」堂々巡りを検知できない。no_progress が looper 由来でその穴を埋める。

cross-model council (privacy)

host(owner):  claude     # kage quest.provider
reviewer-A:   gemini     # 別 family 推奨 (blind spot)
judge-B:      codex      # gate 判定
# privacy.egress: 別 vendor CLI 送信を明示 + consent + redact glob

council_members は quest 単位の provider とは個別に provider を持てる。

状態機械 (v3.1)

work(scout/poc) 完了
  ↓ owner (pending) — _should_dispatch_owner() gate
  ↓ design: gate spawn (scout_gate / poc_gate / ...)
gate (pending)
  ↓ spawn N× reviewer/judge (relation: council_of)
member (proposed→running→explored)
  ↓ verdict / notes
gate (running) — chair merge
  ↓ verdict_source "pass" → 次フェーズ work を pending 化
  ↓ verdict_source "revise" → 前フェーズ work を保持し revision spawn
gate (explored)
  ↓ run: owner が merged actions[] → tick 適用
owner (explored)

3モード階層 (互換性)

• --solo: v1 (scout/poc 直接 spawn)
• --council "": v2 (owner 単独)
• --council "reviewer:2,judge:1": v3.1 (council 付き team)

今回は intent + 本レポートに設計のみ。executor 並列化と connector consent 拡張後に着手。programmatic check / loop_control 拡張は非同期化なしでも実装可能。

13v3 設計: design + run 2-phase で owner SPOF 解消

v2 では owner 1出力が曲がればグラフ全体が曲がる SPOF だった。v3 は owner を design (協議) + run (実行) の2フェーズに分け、design phase で council を並列招集して再帰リスクを下げる。

council_member ロール (新)

Role: council_member   権限: execute + 提案のみ (graf 編集不可)
入力: 全 evidence + proposed 一覧 (owner と同一)
出力: { "member_id":"A", "confidence":0.8, "actions":[...], "dissent":"..." }
既定3体 (--council-size N で変更可)

2-phase 状態機械

owner (pending)  ← _should_dispatch_owner() 待機
   ↓
owner (running)   ─ design phase ─▶ spawn N × council_member (並列, proposed)
   ↓                        owner は全 member 完了待ち (status: council_pending)
owner (running)   ─ chair: merge
   ↓
owner (explored)  ─ run phase 出力 → tick 適用 (機械的)

→ 新 status: council_pending / 新 relation: council_of (owner→member), council_reply (member→owner) / 新列: quest_nodes.phase (design|run) / --council-size 0 で v2 単独 owner に戻る

なぜ今回は設計だけか

• 並列 council には executor の非同期化が前提。現状は1分・1ノード同期
• シリアル council だと design→run で N+2 tick かかり、遅さが v2 より悪化
• そのため intent + 本レポートに設計のみ追記。executor 並列化後に着手

11v2: Owner-gated team model

v1 では scout/poc が promising 判定のたびに 勝手に子ノードを spawn していた。LLM 1 個のミスが即グラフに漏れる構造で、「1エージェントはまだミスが多い」限界を捨てきれない。

proposed ノードのライフ

# scout/poc/strategist が実行 → proposed を残す
SCOUT POC  ──execute──▶ proposed (by scout)
                          │
                          │ owner が promote で pending 化
                          ▼
                       pending ──▶ running ──▶ explored/growing/aborted
                                               │
                                               └▶ owner が次ラウンドで triage

→ proposed_by 列 & proposed_from エッジで誰の提案か追跡可能。owner は全 evidence を食べて総合判断。「1人で進めるのはダメ、チームで戦う」を機構として保証。

12v2: Web UI — kage ui /quests

kage ui に quest 専用ページを追加。PC・スマホ両方で LAN から確認できる。

kage ui --host 0.0.0.0 --port 8771
# スマホ: http://<raspiのIP>:8771/quests

追加 route

• GET /quests — quest 一覧 + 個別グラフ描画 SPA ページ
• GET /api/quests — 全 quest JSON (status / runs / roles / mode / node_counts)
• GET /api/quests/{id} — ノード + エッジ + verdict / evidence 詳細

ページ機能:

• クエストカード一覧 (status badge / runs / node 数)
• クリックで SVG グラフ描画 (layered tree): 色=status, 点線=proposed, 王冠=owner, 矢印=relation 別色
• Nodes / Edges テーブル (verdict, evidence, proposed_by 表示)
• 5 秒間隔で自動リロード (進行状況がほぼリアルタイムで見える)

10実装スコープ & 残課題