@geekbeer/minion 3.29.1 → 3.30.0

package/core/lib/dag-step-poller.js

@@ -126,6 +126,8 @@ async function executeSkillNode(node) {
     input_data,
     revision_feedback,
     review_history,
+    input_contracts,
+    output_contracts,
   } = node
 
   console.log(
@@ -174,16 +176,18 @@ async function executeSkillNode(node) {
       }
     }
 
-    // 4. Run the skill with input_data context
+    // 4. Run the skill with input_data and contract context
     const runPayload = {
       skill_name: skillName,
       execution_id,
       workflow_name: dag_workflow_name,
       role: assigned_role,
-      // DAG-specific: inject input_data as context
+      // DAG-specific: inject input_data and contracts as context
       dag_node_id: node_id,
       dag_input_data: input_data,
       dag_node_execution_id: node_execution_id,
+      dag_input_contracts: input_contracts || null,
+      dag_output_contracts: output_contracts || null,
     }
     if (revision_feedback) {
       runPayload.revision_feedback = revision_feedback
@@ -251,6 +255,7 @@ async function executeTransformNode(node) {
     assigned_role,
     input_data,
     transform_instruction,
+    output_contracts,
   } = node
 
   console.log(
@@ -285,7 +290,7 @@ async function executeTransformNode(node) {
 
     // 2. Create ephemeral skill from transform_instruction.
     // Write to every active plugin's skill dir so any Primary can find it.
-    const skillContent = buildTransformSkillContent(transform_instruction, input_data)
+    const skillContent = buildTransformSkillContent(transform_instruction, input_data, output_contracts)
     for (const dir of ephemeralSkillDirs) {
       await fs.mkdir(dir, { recursive: true })
       await fs.writeFile(path.join(dir, 'SKILL.md'), skillContent, 'utf-8')
@@ -353,8 +358,8 @@ async function executeTransformNode(node) {
 /**
  * Build SKILL.md content for a transform node's ephemeral skill.
  */
-function buildTransformSkillContent(instruction, inputData) {
-  return [
+function buildTransformSkillContent(instruction, inputData, outputContracts) {
+  const lines = [
     '---',
     'name: dag-transform',
     'description: DAG Transform Node',
@@ -369,12 +374,31 @@ function buildTransformSkillContent(instruction, inputData) {
     '',
     '## Transform Instruction',
     instruction,
+  ]
+
+  if (outputContracts && outputContracts.length > 0) {
+    lines.push('', '## Output Contract')
+    lines.push('Your output MUST conform to the following contract(s):')
+    for (const oc of outputContracts) {
+      lines.push(`### ${oc.contract_name}`)
+      lines.push(oc.contract.description || '')
+      lines.push('| Field | Type | Required | Description |')
+      lines.push('|-------|------|----------|-------------|')
+      for (const f of oc.contract.fields || []) {
+        lines.push(`| ${f.key} | ${f.type} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |`)
+      }
+    }
+  }
+
+  lines.push(
     '',
     '## Task',
     'Apply the transform instruction to the input data above.',
     'Output the result as a JSON object in an "## Output Data" section with a json code block.',
     'Do NOT output anything other than the Output Data section.',
-  ].join('\n')
+  )
+
+  return lines.join('\n')
 }
 
 /**

package/core/routes/skills.js

@@ -344,6 +344,9 @@ async function skillRoutes(fastify, opts) {
       revision_feedback,
       review_history,
       dag_node_execution_id,
+      dag_input_data,
+      dag_input_contracts,
+      dag_output_contracts,
     } = request.body || {}
 
     if (!skill_name) {
@@ -393,6 +396,9 @@ async function skillRoutes(fastify, opts) {
     if (role) runOptions.role = role
     if (revision_feedback) runOptions.revisionFeedback = revision_feedback
     if (review_history && review_history.length > 0) runOptions.reviewHistory = review_history
+    if (dag_input_data) runOptions.dagInputData = dag_input_data
+    if (dag_input_contracts) runOptions.dagInputContracts = dag_input_contracts
+    if (dag_output_contracts) runOptions.dagOutputContracts = dag_output_contracts
 
     // Run asynchronously — respond immediately
     const executionPromise = (async () => {

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/linux/workflow-runner.js

@@ -92,7 +92,38 @@ async function executeWorkflowSession(workflow, executionId, skillNames, options
     revisionContext = `## Revision Feedback\nThe reviewer requested changes to your previous output. Address the following feedback:\n${options.revisionFeedback}\n\n`
   }
 
-  const prompt = `${rolePrefix}${revisionContext}Run the following skills in order: ${skillCommands}.`
+  // Inject DAG input data context (data from upstream nodes)
+  let dagDataContext = ''
+  if (options.dagInputData && Object.keys(options.dagInputData).length > 0) {
+    dagDataContext = `## Input Data (from upstream nodes)\nThe following data was produced by upstream steps in this workflow. Use it as context for your task.\n\`\`\`json\n${JSON.stringify(options.dagInputData, null, 2)}\n\`\`\`\n\n`
+  }
+
+  // Inject DAG contract context (input/output contracts from edges)
+  let contractContext = ''
+  if (options.dagInputContracts && options.dagInputContracts.length > 0) {
+    contractContext += '## Input Contracts\nThe input data above conforms to the following contract(s):\n'
+    for (const ic of options.dagInputContracts) {
+      contractContext += `### ${ic.contract_name}\n${ic.contract.description || ''}\n`
+      contractContext += '| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n'
+      for (const f of ic.contract.fields || []) {
+        contractContext += `| ${f.key} | ${f.type} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
+      }
+    }
+    contractContext += '\n'
+  }
+  if (options.dagOutputContracts && options.dagOutputContracts.length > 0) {
+    contractContext += '## Output Contract\nYour output MUST conform to the following contract(s). Include all required fields in your execution report.\n'
+    for (const oc of options.dagOutputContracts) {
+      contractContext += `### ${oc.contract_name}\n${oc.contract.description || ''}\n`
+      contractContext += '| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n'
+      for (const f of oc.contract.fields || []) {
+        contractContext += `| ${f.key} | ${f.type} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
+      }
+    }
+    contractContext += '\n'
+  }
+
+  const prompt = `${rolePrefix}${revisionContext}${dagDataContext}${contractContext}Run the following skills in order: ${skillCommands}.`
 
   // Exit code file to capture CLI result
   const exitCodeFile = `/tmp/tmux-exit-${sessionName}`

package/package.json

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

package/win/workflow-runner.js

@@ -99,7 +99,38 @@ async function executeWorkflowSession(workflow, executionId, skillNames, options
     revisionContext = `## Revision Feedback\nThe reviewer requested changes to your previous output. Address the following feedback:\n${options.revisionFeedback}\n\n`
   }
 
-  const prompt = `${rolePrefix}${revisionContext}Run the following skills in order: ${skillCommands}.`
+  // Inject DAG input data context (data from upstream nodes)
+  let dagDataContext = ''
+  if (options.dagInputData && Object.keys(options.dagInputData).length > 0) {
+    dagDataContext = `## Input Data (from upstream nodes)\nThe following data was produced by upstream steps in this workflow. Use it as context for your task.\n\`\`\`json\n${JSON.stringify(options.dagInputData, null, 2)}\n\`\`\`\n\n`
+  }
+
+  // Inject DAG contract context (input/output contracts from edges)
+  let contractContext = ''
+  if (options.dagInputContracts && options.dagInputContracts.length > 0) {
+    contractContext += '## Input Contracts\nThe input data above conforms to the following contract(s):\n'
+    for (const ic of options.dagInputContracts) {
+      contractContext += `### ${ic.contract_name}\n${ic.contract.description || ''}\n`
+      contractContext += '| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n'
+      for (const f of ic.contract.fields || []) {
+        contractContext += `| ${f.key} | ${f.type} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
+      }
+    }
+    contractContext += '\n'
+  }
+  if (options.dagOutputContracts && options.dagOutputContracts.length > 0) {
+    contractContext += '## Output Contract\nYour output MUST conform to the following contract(s). Include all required fields in your execution report.\n'
+    for (const oc of options.dagOutputContracts) {
+      contractContext += `### ${oc.contract_name}\n${oc.contract.description || ''}\n`
+      contractContext += '| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n'
+      for (const f of oc.contract.fields || []) {
+        contractContext += `| ${f.key} | ${f.type} | ${f.required ? 'Yes' : 'No'} | ${f.description || ''} |\n`
+      }
+    }
+    contractContext += '\n'
+  }
+
+  const prompt = `${rolePrefix}${revisionContext}${dagDataContext}${contractContext}Run the following skills in order: ${skillCommands}.`
 
   const logFile = logManager.getLogPath(executionId)