@geekbeer/minion 3.60.4 → 4.0.1

package/LICENSE.md

@@ -0,0 +1,53 @@
+Copyright (c) 2026 GeekBeer Co., Ltd.
+
+Source code in this repository is covered by the Elastic License 2.0.
+The full license text is available at:
+https://www.elastic.co/licensing/elastic-license
+
+----
+
+Elastic License
+
+Acceptance
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations and conditions below.
+
+Limitations
+You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+Patents
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case subject to the limitations and conditions in this license. This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+Notices
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the software prominent notices stating that you have modified the software.
+
+No Other Rights
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+Termination
+If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
+
+No Liability
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+Definitions
+The licensor is the entity offering these terms, and the software is the software the licensor makes available under these terms, including any portion of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. control means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under these terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.
+

package/README.md

@@ -1,64 +1,59 @@
-# @geekbeer/minion
+> [!IMPORTANT]
+> This package is the agent runtime for [Minion](https://minion-agent.com), GeekBeer's AI agent platform. It is intended to run on a Minion-managed host (provisioned via the HQ dashboard) and is not designed for standalone use.
 
-AI Agent runtime for Minion - manages heartbeat, status, and skill deployment on VPS.
+# @geekbeer/minion
 
-## Install
+AI agent runtime that runs on a Minion host (Lightsail VPS, Docker container, or self-hosted machine). It exposes a local HTTP API on port `8080`, syncs heartbeats and skills with the HQ server, and runs Claude Code–based workflows and routines via tmux (Linux/macOS) or node-pty (Windows).
 
-```bash
-npm install -g @geekbeer/minion
-```
+Supported platforms: Linux (systemd / supervisord), Windows (NSSM service + WSL), macOS (launchd).
 
-## Usage
+## Documentation
 
-### Setup (VPS)
+Full documentation lives at **https://docs.minion-agent.com**. Start here:
 
-```bash
-minion-cli setup \
-  --hq-url https://minion-agent.com \
-  --minion-id <MINION_ID> \
-  --api-token <API_TOKEN> \
-  --setup-tunnel \
-  --non-interactive
-```
+- [Quickstart](https://docs.minion-agent.com/getting-started/quickstart/) — provision a minion from the HQ dashboard
+- [Concepts](https://docs.minion-agent.com/getting-started/concepts/) — workspaces, projects, skills, workflows, routines
+- [Self-hosting / Provisioning](https://docs.minion-agent.com/getting-started/provisioning/) — bring your own host
+- [Skill authoring](https://docs.minion-agent.com/skills-workflows/skill-authoring/) and [workflow design](https://docs.minion-agent.com/skills-workflows/workflow-design/)
+- [DAG workflow nodes](https://docs.minion-agent.com/skills-workflows/dag-nodes/)
 
-### Service Management
+Japanese documentation is available at https://docs.minion-agent.com/ja/.
 
-```bash
-minion-cli start      # Start the minion agent
-minion-cli stop       # Stop the minion agent
-minion-cli restart    # Restart the minion agent
-minion-cli status     # Show service status
-minion-cli health     # Run health check
-```
+## Install
 
-### Logging
+Most users do **not** install this package manually — the HQ dashboard provisions hosts automatically. For self-hosted setups:
 
 ```bash
-minion-cli log -m "Task completed" -l info -s skill-name
+npm install -g @geekbeer/minion
 ```
 
-### Issue Reporting
+Then follow the [self-hosting guide](https://docs.minion-agent.com/getting-started/provisioning/) to register the host with your HQ workspace.
 
-```javascript
-const { reportIssue } = require('@geekbeer/minion/api')
+## CLI
 
-await reportIssue({
-  title: 'HQ APIで502エラーが発生する',
-  body: '## 状況\n...\n\n## 再現手順\n...',
-  labels: ['bug', 'critical']
-})
-// → { success: true, issue_url: '...', issue_number: 42 }
+```bash
+minion-cli setup --user <USERNAME>     # Install dependencies and register services (Linux/macOS, run as root)
+minion-cli configure --hq-url ... --minion-id ... --api-token ...
+minion-cli start | stop | restart | status
+minion-cli health | diagnose | daemons
+minion-cli set-status <status> [task]
+hq <subcommand>                        # HQ API helper (notes, threads, tasks, memories, etc.)
 ```
 
+On Windows the equivalents are exposed as `minion-cli-win` and `hq-win`; on macOS as `minion-cli-mac` and `hq-mac`. See the [provisioning guide](https://docs.minion-agent.com/getting-started/provisioning/) for end-to-end setup.
+
 ## Environment Variables
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `HQ_URL` | Minion HQ server URL | - |
-| `API_TOKEN` | Authentication token | - |
-| `MINION_ID` | Minion UUID | - |
-| `AGENT_PORT` | Agent API listen port | `8080` |
+| Variable | Description |
+|----------|-------------|
+| `HQ_URL` | HQ server URL (leave empty for standalone mode) |
+| `API_TOKEN` | Bearer token for HQ and local API authentication |
+| `MINION_ID` | UUID assigned by HQ on provisioning |
+| `AGENT_PORT` | Local agent API port (default `8080`) |
+| `MINION_USER` | System user that owns the agent process |
 
 ## License
 
-MIT
+This software is licensed under the [Elastic License 2.0](./LICENSE.md) (SPDX: `Elastic-2.0`).
+
+Copyright (c) 2026 GeekBeer Co., Ltd.

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

@@ -161,12 +161,19 @@ async function executeSkillNode(node) {
   )
 
   try {
-    // 1. Claim the node
+    // 1. Claim the node. Response includes `template_vars` containing the
+    //    workspace/project-scope variables resolved on HQ — we merge these
+    //    with minion-local variables for the skill fetch below so HQ-side
+    //    variable updates (e.g. project_variables) take effect on the next
+    //    node execution. Minion-local values win over HQ-scope values,
+    //    matching the cross-scope rule (workspace < project < minion).
+    let hqVars = {}
     try {
-      await dagRequest('/claim-node', {
+      const claimResp = await dagRequest('/claim-node', {
         method: 'POST',
         body: JSON.stringify({ node_execution_id }),
       })
+      hqVars = (claimResp && claimResp.template_vars) || {}
     } catch (claimErr) {
       if (claimErr.statusCode === 409) {
         console.log(`[DagPoller] Node ${node_id} already claimed, skipping`)
@@ -187,7 +194,7 @@ async function executeSkillNode(node) {
     if (skillName) {
       try {
         const minionVars = variableStore.getAll('variables')
-        const mergedVars = { ...minionVars }
+        const mergedVars = { ...hqVars, ...minionVars }
         const varsParam = Object.keys(mergedVars).length > 0
           ? `?vars=${Buffer.from(JSON.stringify(mergedVars)).toString('base64')}`
           : ''

package/docs/api-reference.md

@@ -1236,6 +1236,9 @@ POST `/api/minion/dag-workflows/:id/publish` (body なし):
 | POST | `/api/minion/dag-workflows/:id/contracts` | 個別contractを追加/更新 |
 | DELETE | `/api/minion/dag-workflows/:id/contracts` | 個別contractを削除 |
 | POST | `/api/minion/dag-workflows/:id/validate` | ドラフトをフル検証（公開せず） |
+| GET | `/api/minion/dag-workflows/:id/variables` | DAGワークフロー変数の一覧取得 |
+| PUT | `/api/minion/dag-workflows/:id/variables` | DAGワークフロー変数を一括 upsert（既存を全削除→再投入） |
+| POST | `/api/minion/dag-workflows/:id/trigger` | 公開済みワークフローを手動実行（pull-model） |
 
 #### POST `/api/minion/dag-workflows/:id/nodes` — ノード追加
 
@@ -1482,6 +1485,80 @@ body なし。現在のドラフトを `validateDagGraph` でフル検証し結
 }
 ```
 
+#### GET / PUT `/api/minion/dag-workflows/:id/variables` — DAGワークフロー変数
+
+DAGワークフロー単位のキー/値ペア。スキル本文の `{{VAR_NAME}}` プレースホルダーに展開される。展開タイミングは `claim-node` のレスポンス `template_vars` に乗って降ってくる経路で、変更は **次のノード claim から即時反映** される。
+
+**スコープ優先順位** (narrower wins): `workspace_variables` < `project_variables` < `dag_workflow_variables` < minion-local。
+
+**バリデーション**:
+- `key`: `^[A-Za-z_][A-Za-z0-9_]{0,99}$`（先頭英字またはアンダースコア、最大100文字）
+- `value`: 文字列、最大2000文字
+- 同一 `key` の重複は不可
+
+`GET /api/minion/dag-workflows/:id/variables` レスポンス:
+```json
+{
+  "variables": [
+    { "id": "<uuid>", "key": "TARGET_CATEGORY", "value": "electronics", "created_at": "...", "updated_at": "..." }
+  ]
+}
+```
+
+`PUT /api/minion/dag-workflows/:id/variables` body:
+```json
+{
+  "variables": [
+    { "key": "TARGET_CATEGORY", "value": "electronics" },
+    { "key": "API_BASE_URL", "value": "https://api.example.com" }
+  ]
+}
+```
+
+- バッチ upsert 形式: **既存を全削除 → 渡された配列を全 insert** する（部分更新不可）。
+- 単一変数だけを変更したい場合も、先に GET で現在の集合を取得 → 編集 → PUT で全件送信する。
+- `variables: []` を送ると全削除になる。
+
+レスポンス:
+```json
+{ "success": true, "count": 2 }
+```
+
+エラー時 (400): `{ "error": "Invalid key: 1FOO" }` / `{ "error": "Duplicate key: FOO" }` 等。
+
+#### POST `/api/minion/dag-workflows/:id/trigger` — ワークフロー手動実行
+
+公開済み (`is_active=true` かつ `current_version_id` 設定済み) の DAG ワークフローを手動でトリガーする。HQダッシュボード経由の `POST /api/dag/projects/:projectId/workflows/:dagWfId/trigger` と同じ pull-model で動き、`trigger_source` は `'manual'` として記録される（cron / webhook と区別される）。
+
+Body (任意):
+```json
+{
+  "payload": { "...": "..." }
+}
+```
+
+- `payload` は start ノードの `output_data` に注入され、cascade 経由で下流に伝播する。
+- start ノードに `input_contract` が定義されている場合、`payload` が contract に準拠していないと 400 (`violations` フィールドに違反詳細) が返る。
+- payload を省略すると start ノードは空の出力で完了する。
+
+レスポンス (201):
+```json
+{
+  "execution_id": "<uuid>",
+  "dag_workflow_name": "Order Pipeline",
+  "root_nodes": 3,
+  "total_nodes": 12,
+  "mode": "pull"
+}
+```
+
+エラー応答:
+- 400: ワークフロー非アクティブ / 未公開 / graph 空 / payload 形式不正 / contract 違反
+- 403: ミニオンがプロジェクトの PM でない
+- 404: ワークフロー / プロジェクト未発見
+
+トリガー後はミニオンの `dag-step-poller` が pending ノードを順次拾って実行する。手動実行も含め、すべての DAG 実行は `dag_executions` テーブル + ダッシュボードの実行履歴で追跡できる。
+
 #### 全操作共通のレスポンス形式
 
 ノード/エッジ操作のレスポンスにはワークフロー全体 + `validation` フィールドが含まれる:
@@ -1682,9 +1759,15 @@ Body:
 
 Response (成功 / 201):
 ```json
-{ "success": true, "node_execution_id": "uuid" }
+{
+  "success": true,
+  "node_execution_id": "uuid",
+  "template_vars": { "PROJECT_VAR_NAME": "value", "WORKSPACE_VAR": "value" }
+}
 ```
 
+`template_vars` には claim したノードのコンテキストで解決された **workspace_variables / project_variables / dag_workflow_variables** が narrower-scope-wins (workspace < project < dag_workflow) でマージされて入る。スキルノードの場合は後続の `POST /api/skills/fetch/:name?vars=...` でこの値を base64 JSON として渡し、HQ 側で SKILL.md の `{{VAR}}` を置換する。ミニオンローカル変数はミニオン側で更にレイヤされ、`template_vars` の値を上書きする（cross-scope rule: workspace < project < dag_workflow < minion）。
+
 Response (競合 / 409): 他ミニオンが既に claim 済み、または状態が pending でない場合。
 ```json
 { "error": "Node already claimed or not pending" }
@@ -1949,6 +2032,55 @@ Response:
 
 スキルはバージョン管理される。push ごとに新バージョンが作成され、ファイルは Supabase Storage に保存される。
 
+**`GET /api/minion/skills/:name` レスポンス**:
+```json
+{
+  "id": "<skill-uuid>",
+  "current_version_id": "<skill-version-uuid>",
+  "name": "variable-injection-test",
+  "display_name": "Variable Injection Test",
+  "type": "workflow",
+  "description": "...",
+  "content": "...",
+  "files": [{ "path": "files/extra.md", "content": "..." }]
+}
+```
+
+**`POST /api/minion/skills` レスポンス**:
+```json
+{
+  "success": true,
+  "skill": {
+    "id": "<skill-uuid>",
+    "name": "variable-injection-test",
+    "workspace_id": "<workspace-uuid>",
+    "current_version_id": "<skill-version-uuid>",
+    "version": 3
+  }
+}
+```
+
+スキルを push してそのまま DAG ノードに組み込む典型フロー:
+
+```bash
+# 1. push してスキルIDを得る
+SKILL_ID=$(curl -s -X POST -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
+  $HQ_URL/api/minion/skills -d '{"name":"my-skill","content":"..."}' | jq -r '.skill.id')
+
+# 2. DAG ノードを追加 (skill_version_id は省略 = 常に最新を追従)
+curl -X POST -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
+  $HQ_URL/api/minion/dag-workflows/$DAG_ID/nodes \
+  -d "{\"type\":\"skill\",\"skill_id\":\"$SKILL_ID\",\"assigned_role\":\"engineer\",\"after\":\"start\",\"before\":\"end\"}"
+```
+
+**スキルバージョンの pin / latest 追従** (DAGスキルノード):
+
+DAGスキルノードの `skill_version_id` は **オプション** です。
+- `skill_version_id` を **省略 / null** にすると、実行時に常に skill の `current_version_id` (最新版) を fetch する（**latest auto-track**）。スキルを push して新バージョンを公開すると、次のノード実行から自動で反映される。
+- `skill_version_id` を **明示的に指定** すると、その特定バージョンに pin される（将来の pinned 実行向け。現状ランタイムは latest 解決を使うが、カラムは保持される）。
+
+旧来の挙動（publish 時に skill_version_id 必須）は廃止済み。`skill_id` のみ指定すれば DAG publish できる。
+
 ### Threads (HQ)
 
 | Method | Endpoint | Description |
@@ -2206,3 +2338,22 @@ POST レスポンス例:
 | 409 | `version_conflict` (他者の編集と衝突)、`name_conflict`、`order_key_collision` (同時挿入の競合、再送可) |
 | 410 | `deck_in_trash` (デッキがゴミ箱にある) |
 
+### Accounting Receipts 🧪 (HQ, experimental)
+
+`workspaces.feature_flags.experimental_accounting = true` のワークスペース向け。
+レシート (画像/PDF) の一覧取得・ダウンロード・取引紐付けをBearer認証で行える。
+**典型用途**: 人間が `/accounting/receipts` から大量アップロードした未仕訳レシートを
+ミニオン側で OCR → 仕訳作成 → 紐付け、という記帳ワークフロー。
+
+| Method | Endpoint | 説明 |
+|--------|----------|-------------|
+| GET | `/api/minion/workspaces/:id/accounting/receipts` | レシート一覧。Query: `?attached=true\|false\|all` (default `false`), `?limit=100` (max 500) |
+| GET | `/api/minion/workspaces/:id/accounting/receipts/:receiptId` | メタデータ |
+| GET | `/api/minion/workspaces/:id/accounting/receipts/:receiptId/download` | 60秒有効な signed URL を返す (`{ url, mime_type, file_name, expires_in_seconds }`) |
+| PATCH | `/api/minion/workspaces/:id/accounting/receipts/:receiptId` | 取引と紐付け / 解除。Body: `{ entry_id: string \| null }`。entry_id 指定時は同じ book に属する取引でないと 400 |
+
+レシートのMIME種別は `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `image/heic`, `image/heif`, `application/pdf` のいずれか。
+
+**未実装**: ミニオン向け仕訳作成 API (`POST /api/minion/workspaces/:id/accounting/entries`) は現状未実装。
+OCR後の仕訳作成は、当面ユーザー操作で `/accounting/new` から行うか、HQ管理者向けの Supabase session 経由のみ。
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "3.60.4",
+  "version": "4.0.1",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "linux/server.js",
   "bin": {
@@ -57,5 +57,5 @@
     "claude",
     "automation"
   ],
-  "license": "MIT"
+  "license": "Elastic-2.0"
 }

package/rules/core.md

@@ -32,6 +32,7 @@ Minion
     - **transform ノードの I/O 型は edge の contract から自動導出**。incoming edge と outgoing edge にそれぞれ contract を必ず貼ること。`transform_instruction` は contract だけで意図が伝わらない場合の補足ヒント（任意）
     - **script ノード (v3.54.0〜)** は LLM を使わない決定的処理用。`script_runtime` (`'python'` or `'node'`) と `script_source` を指定。input_data を stdin で JSON 受け取り → output_data を stdout に JSON 出力する規約。outgoing edge に contract を貼れば transform と同じ runtime validation が走る。LLMトークンを節約したい・出力ブレを許容できない定型処理に使う。詳細は `~/.minion/docs/task-guides.md` の「Script ノード」を参照
     - **fan_out の incoming edge に contract を貼る場合**、`fan_out_source` が指すフィールドが contract 内に `type='array'` として宣言されている必要がある（静的検証で弾かれる）
+    - **スキルノードの skill_version_id は省略可** (v3.60.8〜)。省略するとランタイムが常に skill の最新バージョンを fetch する（latest auto-track）。特定バージョンに pin したい場合のみ明示指定する。`POST /api/minion/skills` のレスポンスで `skill.id` (skill_id) と `skill.current_version_id` の両方が返るので、auto-track 運用なら前者だけ使えばよい
 - **Routine**: ミニオンスコープ。ミニオンローカルの定期タスク。
 - **Project Tasks / Milestones / Sprints**: プロジェクトスコープ。**人間+ミニオンが共有するタスクボード**(5段階Kanban: `backlog`→`todo`→`doing`→`review`→`done`)、ロードマップ(マイルストーン)、アジャイル運用単位(スプリント)。ミニオンは `/api/minion/projects/:projectId/{tasks,milestones,sprints,health}` で操作可能。
   - PMロールは朝のチェックで `/health` を叩いて遅延・停滞タスクを把握、ユーザー要望をエピック+子タスクに分解、スプリントに割り当てて active 化
@@ -225,6 +226,8 @@ Routine 実行中は以下もtmuxセッション環境で利用可能:
 
 **変数**（ワークスペース変数・プロジェクト変数・ワークフロー変数・ミニオン変数）はスキル本文の `{{VAR_NAME}}` テンプレートとして実行時に展開される。スキル作成時にパラメータ化したい値は `{{変数名}}` で記述すること。展開優先順位: ワークスペース < プロジェクト < ワークフロー < ミニオン（後者が優先）。ミニオンが最終オーバーライドとなる設計で、ミニオン運用者がHQ側のデフォルトを差し替えられる経路を保証する。ミニオン変数はさらにミニオン全体スコープとワークスペース別スコープに分かれ、当該ワークスペースのコンテキストで動く実行時はWS別がミニオン全体を上書きする。`/api/variables/*` は `?workspace_id=<uuid>` でスコープ指定（省略時はミニオン全体）。
 
+DAGワークフローでは、HQ側スコープ（workspace/project/dag_workflow）の変数は **`POST /api/dag/minion/claim-node` のレスポンス `template_vars`** に乗って降ってきて、ミニオン側で minion-local 変数とマージしたうえで `POST /api/skills/fetch/:name?vars=...` の base64 JSON に詰めて HQ に渡し、HQ 側で SKILL.md の `{{VAR}}` を置換して返す。つまり HQ-scope 変数の更新は **次のノード claim から反映される**（既存のミニオン上 SKILL.md は次回 fetch で上書きされる）。DAGワークフロー単位の変数は `dag_workflow_variables` テーブルに格納され、DAGエディタの "Variables" ボタンから編集可能。
+
 **シークレット**はワークスペース別にスコープされ、ミニオンローカルのSQLite (`secrets(workspace_id, key, value)`) に保存される。ワークスペース未指定（`workspace_id=''`）はミニオン全体のスコープで、サーバー起動時に `process.env` にロードされ全子プロセスで `$SECRET_NAME` として利用可能。ワークスペース別シークレット（`workspace_id=<uuid>`）は `process.env` にはロードされず、当該ワークスペースのコンテキストで動くランナー（ワークフロー/WSバインドされたルーティン/チャットセッション）にのみ実行時注入される。同名キーが両スコープに存在する場合はワークスペース別が優先。スキル側は常に `$KEY` で参照すればよく、どちらのスコープから来た値かを意識する必要はない。シークレット値はHQ DBに保存されることはなく、HQはpass-throughとして中継するのみ。
 
 デイリーログやメモリーから変数・シークレットの値を推測して使用してはならない。変数は `{{VAR_NAME}}` テンプレートとして定義し、シークレットは環境変数として参照すること。