@geekbeer/minion 3.29.1 → 3.29.4

package/docs/api-reference.md

@@ -1066,8 +1066,12 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
 | PATCH | `/api/minion/dag-workflows/:id/nodes/:nodeId` | ノードのプロパティを更新 |
 | DELETE | `/api/minion/dag-workflows/:id/nodes/:nodeId` | ノードを削除（自動再接続対応） |
 | POST | `/api/minion/dag-workflows/:id/edges` | エッジを追加 |
-| PATCH | `/api/minion/dag-workflows/:id/edges/:edgeId` | エッジの kind / condition_label を更新 |
+| PATCH | `/api/minion/dag-workflows/:id/edges/:edgeId` | エッジの kind / condition_label / contract を更新 |
 | DELETE | `/api/minion/dag-workflows/:id/edges/:edgeId` | エッジを削除 |
+| GET | `/api/minion/dag-workflows/:id/contracts` | 全contractsを取得 |
+| PUT | `/api/minion/dag-workflows/:id/contracts` | 全contractsを上書き |
+| POST | `/api/minion/dag-workflows/:id/contracts` | 個別contractを追加/更新 |
+| DELETE | `/api/minion/dag-workflows/:id/contracts` | 個別contractを削除 |
 | POST | `/api/minion/dag-workflows/:id/validate` | ドラフトをフル検証（公開せず） |
 
 #### POST `/api/minion/dag-workflows/:id/nodes` — ノード追加
@@ -1166,6 +1170,7 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
 - `source`, `target` (必須): 既存ノードのID
 - `kind` (任意): `normal` (default) | `approved` | `revision`
 - `condition_label` (任意): conditional ノードの分岐ラベル
+- `contract` (任意): `graph.contracts` 内の型名への参照
 - `id` (任意): 省略時は `edge_1`, `edge_2`, ... で自動採番
 
 #### PATCH `/api/minion/dag-workflows/:id/edges/:edgeId` — エッジ更新
@@ -1173,18 +1178,85 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
 ```json
 {
   "kind": "approved",
-  "condition_label": "success"
+  "condition_label": "success",
+  "contract": "prototype"
 }
 ```
 
 - `kind` (任意): `normal` | `approved` | `revision`
 - `condition_label` (任意): 分岐ラベル。`null` を渡すとクリア
+- `contract` (任意): contracts 内の型名。`null` を渡すとクリア
 - 指定したフィールドのみ上書き（未指定フィールドは変更しない）
 
 #### DELETE `/api/minion/dag-workflows/:id/edges/:edgeId` — エッジ削除
 
 - エッジIDを指定して削除
 
+#### Contracts API
+
+エッジを流れるデータの型を定義するための API。contracts は `graph.contracts` に保存される。
+
+**Contract のスキーマ:**
+
+```typescript
+{
+  description: string          // contract の説明
+  fields: [{
+    key: string                // フィールド名
+    type: "string" | "number" | "boolean" | "url" | "array" | "object"  // フィールド型
+    description: string        // フィールドの説明
+    required?: boolean         // 必須フラグ (省略時 false)
+  }]
+}
+```
+
+**注意:**
+- エッジに設定する `contract` は `graph.contracts` に存在する名前でなければならない（存在しない名前を指定すると 400 エラー）
+- contract を削除すると、参照しているエッジの `contract` フィールドが自動でクリアされる（DELETE / PUT 共通）
+- `validate` エンドポイントはダングリング参照（存在しない contract への参照）をエラーとして報告する
+
+##### GET `/api/minion/dag-workflows/:id/contracts` — 全contracts取得
+
+レスポンス: `{ "contracts": { "name": { "description": "...", "fields": [...] }, ... } }`
+
+##### PUT `/api/minion/dag-workflows/:id/contracts` — 全contracts上書き
+
+```json
+{
+  "contracts": {
+    "prototype": {
+      "description": "プロトタイプ成果物",
+      "fields": [
+        { "key": "git_url", "type": "url", "description": "リポジトリURL", "required": true },
+        { "key": "preview_url", "type": "url", "description": "プレビューURL" }
+      ]
+    }
+  }
+}
+```
+
+##### POST `/api/minion/dag-workflows/:id/contracts` — 個別contract追加/更新
+
+```json
+{
+  "name": "prototype",
+  "contract": {
+    "description": "プロトタイプ成果物",
+    "fields": [
+      { "key": "git_url", "type": "url", "description": "リポジトリURL", "required": true }
+    ]
+  }
+}
+```
+
+##### DELETE `/api/minion/dag-workflows/:id/contracts` — 個別contract削除
+
+```json
+{ "name": "prototype" }
+```
+
+参照しているエッジの `contract` フィールドも自動でクリアされる。レスポンスの `cleared_edges` にクリアされたエッジIDの一覧が含まれる。
+
 #### POST `/api/minion/dag-workflows/:id/validate` — ドラフト検証
 
 body なし。現在のドラフトを `validateDagGraph` でフル検証し結果を返す。**公開はしない**。
@@ -1245,6 +1317,9 @@ hq dag update-node <wf-id> fan_out_1 /tmp/u.json
 
 テンプレート内部のノード/エッジを個別操作するAPIは現在ない。テンプレートは `template` フィールドの全体上書きで更新すること。テンプレートは start/end ノードを持たない sub-graph であり、バリデーション時に再帰的に検証される。
 
+> **⚠️ 重要: テンプレート内に `start` / `end` ノードを配置してはいけない。**
+> テンプレートのエントリポイントとエグジットポイントは、エッジ構造から自動検出される（incoming edge がないノード = エントリ、outgoing edge がないノード = エグジット）。`start` / `end` はトップレベル DAG 専用のノードタイプであり、テンプレート内に含めるとバリデーションエラーになる。テンプレート内では `skill`, `conditional`, `transform`, `review` 等の実行ノードのみ使用すること。
+
 ### ミニオン CLI ラッパー
 
 以下の `hq` サブコマンドが上記エンドポイントを呼び出す。いずれもリクエスト送信前にローカルで JSON 構文検証を行う。

package/docs/task-guides.md

@@ -345,8 +345,11 @@ hq dag remove-edge <wf-id> edge_3
 
 **fan_out テンプレート編集:**
 
+> **⚠️ テンプレート内に `start` / `end` ノードを入れないこと。** テンプレートのエントリ/エグジットはエッジ構造から自動検出される。`start` / `end` はトップレベル DAG 専用であり、テンプレート内に含めるとバリデーションエラーになる。`skill`, `conditional`, `transform`, `review` 等の実行ノードのみ使用すること。
+
 ```bash
 # fan_out ノードの template を PATCH で上書き
+# ※ start/end ノードは不要。実行ノードのみ配置する
 cat > /tmp/t.json <<'EOF'
 {
   "template": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "3.29.1",
+  "version": "3.29.4",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "linux/server.js",
   "bin": {