@geekbeer/minion 2.10.3 → 2.16.0

package/bin/hq

@@ -0,0 +1,108 @@
+#!/bin/bash
+# HQ API helper for minion chat context
+#
+# Fetches resource details from the HQ server API.
+# Used by Claude CLI during chat to retrieve information about
+# skills, workflows, and projects that the user is viewing on the dashboard.
+#
+# Environment variables (inherited from minion server):
+#   HQ_URL    - HQ server URL (e.g., https://minion-agent.com)
+#   API_TOKEN - Minion API token for authentication
+#
+# Usage:
+#   hq fetch skill <name>            - Get skill details (content, description, files)
+#   hq fetch workflow <name>         - Get workflow details (pipeline, cron, etc.)
+#   hq fetch project <id>            - Get project info (name, description, role)
+#   hq fetch project-context <id>    - Get project context (shared Markdown document)
+
+set -euo pipefail
+
+# Validate required environment variables
+if [ -z "${HQ_URL:-}" ]; then
+  echo "Error: HQ_URL is not set" >&2
+  exit 1
+fi
+
+if [ -z "${API_TOKEN:-}" ]; then
+  echo "Error: API_TOKEN is not set" >&2
+  exit 1
+fi
+
+BASE_URL="${HQ_URL}/api/minion"
+
+# Pretty-print JSON if jq is available, otherwise output raw
+format_json() {
+  if command -v jq &>/dev/null; then
+    jq .
+  else
+    cat
+  fi
+}
+
+fetch_resource() {
+  local url="$1"
+  local response
+  local http_code
+
+  # Fetch with HTTP status code
+  response=$(curl -s -w "\n%{http_code}" -H "Authorization: Bearer $API_TOKEN" "$url")
+  http_code=$(echo "$response" | tail -1)
+  body=$(echo "$response" | sed '$d')
+
+  if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
+    echo "$body" | format_json
+  else
+    echo "Error: HQ API returned HTTP $http_code" >&2
+    echo "$body" >&2
+    exit 1
+  fi
+}
+
+# Main command dispatch
+case "${1:-}" in
+  fetch)
+    resource="${2:-}"
+    identifier="${3:-}"
+
+    if [ -z "$resource" ] || [ -z "$identifier" ]; then
+      echo "Usage: hq fetch {skill|workflow|project|project-context} <identifier>" >&2
+      exit 1
+    fi
+
+    case "$resource" in
+      skill)
+        fetch_resource "$BASE_URL/skills/$identifier"
+        ;;
+      workflow)
+        fetch_resource "$BASE_URL/workflows/$identifier"
+        ;;
+      project)
+        # Fetch all projects and filter by ID
+        response=$(curl -s -H "Authorization: Bearer $API_TOKEN" "$BASE_URL/me/projects")
+        if command -v jq &>/dev/null; then
+          echo "$response" | jq --arg id "$identifier" '.projects[] | select(.id == $id)'
+        else
+          echo "$response" | format_json
+        fi
+        ;;
+      project-context)
+        fetch_resource "$BASE_URL/me/project/$identifier/context"
+        ;;
+      *)
+        echo "Unknown resource: $resource" >&2
+        echo "Usage: hq fetch {skill|workflow|project|project-context} <identifier>" >&2
+        exit 1
+        ;;
+    esac
+    ;;
+  *)
+    echo "HQ API helper for minion chat" >&2
+    echo "" >&2
+    echo "Usage:" >&2
+    echo "  hq fetch skill <name>            - Get skill details" >&2
+    echo "  hq fetch workflow <name>          - Get workflow details" >&2
+    echo "  hq fetch project <id>             - Get project info" >&2
+    echo "  hq fetch project-context <id>     - Get project context" >&2
+    exit 1
+    ;;
+esac

package/chat-store.js

@@ -0,0 +1,106 @@
+/**
+ * Chat Session Store
+ * Persists the active chat session (session_id + messages) to local JSON file.
+ * One active session per minion. Claude CLI manages conversation context via --resume.
+ */
+
+const fs = require('fs').promises
+const path = require('path')
+
+const { config } = require('./config')
+
+const MAX_MESSAGES = 100
+
+/**
+ * Get chat session file path
+ * Uses /opt/minion-agent/ if available, otherwise home dir
+ */
+function getFilePath() {
+  const optPath = '/opt/minion-agent/chat-session.json'
+  try {
+    require('fs').accessSync(path.dirname(optPath))
+    return optPath
+  } catch {
+    return path.join(config.HOME_DIR, 'chat-session.json')
+  }
+}
+
+const SESSION_FILE = getFilePath()
+
+/**
+ * Load the active chat session
+ * @returns {Promise<object|null>} Session object or null if none exists
+ */
+async function load() {
+  try {
+    const data = await fs.readFile(SESSION_FILE, 'utf-8')
+    return JSON.parse(data)
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return null
+    }
+    console.error(`[ChatStore] Failed to load session: ${err.message}`)
+    return null
+  }
+}
+
+/**
+ * Save the active chat session
+ * @param {object} session - Session object
+ */
+async function save(session) {
+  try {
+    await fs.writeFile(SESSION_FILE, JSON.stringify(session, null, 2), 'utf-8')
+  } catch (err) {
+    console.error(`[ChatStore] Failed to save session: ${err.message}`)
+  }
+}
+
+/**
+ * Add a message to the active session
+ * Creates a new session if none exists
+ * @param {string} sessionId - Claude CLI session ID
+ * @param {{ role: string, content: string }} msg - Message to add
+ */
+async function addMessage(sessionId, msg) {
+  let session = await load()
+
+  // If session_id changed, start a new session
+  if (!session || session.session_id !== sessionId) {
+    session = {
+      session_id: sessionId,
+      messages: [],
+      created_at: Date.now(),
+      updated_at: Date.now(),
+    }
+  }
+
+  session.messages.push({
+    role: msg.role,
+    content: msg.content,
+    timestamp: Date.now(),
+  })
+  session.updated_at = Date.now()
+
+  // Prune old messages
+  if (session.messages.length > MAX_MESSAGES) {
+    session.messages = session.messages.slice(-MAX_MESSAGES)
+  }
+
+  await save(session)
+}
+
+/**
+ * Clear the active session
+ */
+async function clear() {
+  try {
+    await fs.unlink(SESSION_FILE)
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      console.error(`[ChatStore] Failed to clear session: ${err.message}`)
+    }
+  }
+}
+
+module.exports = { load, save, addMessage, clear }

package/{rules/minion.md → docs/api-reference.md}

@@ -1,67 +1,9 @@
-# Minion Agent Environment
+# Minion API Reference
 
-You are running on a Minion VPS managed by the @geekbeer/minion package.
-A local Agent API server runs at `http://localhost:3001` and a CLI tool `minion-cli` is available.
+このドキュメントはミニオンが利用可能なAPIの全仕様です。
+HQのソースコードを読む必要はありません — 必要な情報はすべてここに記載されています。
 
-## Architecture: Project / Workflow / Routine
-
-```
-Project (組織・課金単位)
-├── Context (markdown, PMが更新)
-├── Members (minion + role: pm | engineer)
-└── Workflows (何をするか + オプションのcronスケジュール)
-    ├── Versions (pipeline の不変スナップショット)
-    └── Executions (実行履歴, ステップごとの進捗)
-
-Minion
-└── Routines (いつ・何を, cron付き, ミニオンローカルのタスク)
-```
-
-- **Workflow** はプロジェクトスコープ。バージョン管理されたパイプライン（スキル列）を持つ。オプションで `cron_expression` によるスケジュール実行が可能。HQ UIからワンショット実行もできる。
-- **Routine** はミニオンスコープ。ミニオンローカルの定期タスク。cron_expression を持ち自律トリガーする。
-- ミニオンは複数プロジェクトに `pm` または `engineer` として参加できる。
-- ワークフローの各ステップには `assigned_role`（pm/engineer）と `requires_review` フラグがある。
-
-## Workflow Execution Model (DB ステートマシン)
-
-ワークフロー実行はHQのDBがステートマシンとして管理する。ミニオン間通信は不要。
-
-```
-1. Execution 作成 (HQ UIのRunボタン or cronスケジュール)
-   → workflow_execution (status='pending')
-   → workflow_step_executions (全ステップ status='pending')
-
-2. ミニオンエージェントが GET /api/minion/pending-steps をポーリング
-   → 自分のロールに該当 & 前ステップ完了済みのステップを取得
-
-3. ミニオンがステップを実行し完了を報告
-   → POST /api/minion/execution で status/outcome を更新
-
-4. 次ステップが eligible に → 別のミニオンが検知して実行
-   → requires_review=true の場合はHQでレビュー承認後に次へ
-
-5. 全ステップ完了 → execution 全体を completed に
-```
-
-**ポイント:**
-- HQの責務は「executionレコードを作る（指示書発行）」だけ
-- 各ミニオンは自分の担当ステップだけをポーリングして実行
-- ミニオンエージェント（Port 3001）が軽量HTTPポーリングを行い、pending検知時のみClaude Codeを起動（トークン節約）
-
-## CLI Commands
-
-```bash
-minion-cli status                         # Get current status (online/offline/busy)
-minion-cli health                         # Health check
-minion-cli set-status <status> [task]     # Set status and optional task description
-minion-cli skill push <name>              # Push local skill to HQ
-minion-cli skill fetch <name>             # Fetch skill from HQ to local
-minion-cli skill list                     # List skills on HQ
-minion-cli skill list --local             # List local deployed skills
-minion-cli --version                      # Show package version
-# Service management (requires sudo):
-# sudo minion-cli start | stop | restart
-```
+---
 
 ## Agent API Endpoints (http://localhost:3001)
 
@@ -142,6 +84,8 @@ Files are stored in `~/files/`. Max upload size: 50MB.
 
 Available commands: `restart-agent`, `update-agent`, `restart-display`, `status-services`
 
+---
+
 ## HQ API Endpoints (https://<HQ_URL>)
 
 Authentication: `Authorization: Bearer $API_TOKEN` header.
@@ -230,6 +174,60 @@ POST body (push):
 
 push するとパイプライン内のスキル名が `skill_version_id` に解決され、新バージョンが自動作成される。
 
+### Workflow Structure
+
+```json
+{
+  "name": "my-workflow",
+  "pipeline_skill_names": ["skill-1", "skill-2", "execution-report"],
+  "pipeline": [
+    {
+      "skill_version_id": "uuid",
+      "skill_name": "skill-1",
+      "skill_display_name": "Skill One",
+      "skill_version": 2,
+      "assigned_role": "engineer",
+      "requires_review": false,
+      "is_my_step": true
+    }
+  ],
+  "content": "Markdown description of the workflow",
+  "version": 2,
+  "cron_expression": "0 9 * * *",
+  "project_id": "uuid"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Slug identifier (`/^[a-z0-9-]+$/`) |
+| `pipeline_skill_names` | string[] | Ordered skill names (for display/push) |
+| `pipeline` | PipelineStep[] | Resolved pipeline with version IDs and roles |
+| `content` | string | Markdown body describing the workflow |
+| `version` | number | Current version number (auto-incremented on push) |
+| `cron_expression` | string\|null | Cron schedule (null = manual/one-shot only) |
+| `project_id` | string | UUID of the parent project |
+
+### Pipeline Step Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `skill_version_id` | string | UUID of the specific skill version |
+| `skill_name` | string | Skill slug name |
+| `skill_display_name` | string | Human-readable skill name |
+| `skill_version` | number | Skill version number |
+| `assigned_role` | string | `"pm"` or `"engineer"` — who executes this step |
+| `requires_review` | boolean | If true, human review required after completion |
+| `is_my_step` | boolean | Whether this minion's role matches assigned_role |
+
+### Syncing Workflows with HQ
+
+- `POST /api/workflows/push/:name` — Push local workflow to HQ. Pipeline skills are auto-pushed first.
+- `POST /api/workflows/fetch/:name` — Fetch workflow from HQ. Missing pipeline skills are auto-fetched.
+- `GET /api/workflows/remote` — List workflows available on HQ.
+
+Pipeline skills must be deployed locally (in `~/.claude/skills/`) before pushing a workflow.
+
 ### Pending Steps (軽量ポーリング)
 
 | Method | Endpoint | Description |
@@ -237,7 +235,6 @@ push するとパイプライン内のスキル名が `skill_version_id` に解
 | GET | `/api/minion/pending-steps` | 自分が実行すべき pending ステップ一覧 |
 
 **このエンドポイントはミニオンエージェント（非AI）による高頻度ポーリング用。**
-Claude Code（AIスキル実行）はステップ検知時のみ起動する。
 
 Response:
 ```json
@@ -329,7 +326,7 @@ Response:
 
 使用可能なラベル: `bug`, `enhancement`, `critical`, `minor`
 
-**使い方:** サービスのバグや改善点を発見したら、このエンドポイントで GitHub Issue を起票する。報告者のミニオン名と ID が自動で本文に付記される。
+報告者のミニオン名と ID が自動で本文に付記される。
 
 ### Routines (minion-scoped)
 
@@ -355,127 +352,7 @@ Response:
 ]
 ```
 
-### Skills
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/minion/skills` | HQ に登録されたスキル一覧 |
-| GET | `/api/minion/skills/[name]` | スキル詳細取得（content, files 含む） |
-| POST | `/api/minion/skills` | スキル登録/更新（新バージョン自動作成） |
-
-スキルはバージョン管理される。push ごとに新バージョンが作成され、ファイルは Supabase Storage に保存される。
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `HQ_URL` | HQ server URL (empty = standalone mode) |
-| `API_TOKEN` | Bearer token for HQ and local API auth |
-| `MINION_ID` | UUID assigned by HQ |
-| `AGENT_PORT` | Agent HTTP port (default: 3001) |
-| `MINION_USER` | System user running the agent |
-
-## Skills Directory Structure
-
-Skills are stored in `~/.claude/skills/<name>/`:
-
-```
-~/.claude/skills/<name>/
-  SKILL.md          # Skill definition (YAML frontmatter + markdown body)
-  references/       # Optional supporting files
-```
-
-SKILL.md format:
-```markdown
----
-name: my-skill
-description: What this skill does
----
-
-Skill instructions here...
-```
-
-## HQ Connection
-
-When `HQ_URL` and `API_TOKEN` are set, the agent sends heartbeats and syncs with HQ.
-Use `minion-cli skill push/fetch` to sync skills between local and HQ.
-Use the workflow API endpoints (`/api/workflows/push/:name`, `/api/workflows/fetch/:name`) to sync workflows.
-When not configured, the agent runs in standalone mode and HQ-dependent features return errors.
-
-## Workflow Structure
-
-Workflows are project-scoped and versioned. Each version is an immutable snapshot of the pipeline.
-Fetched from HQ via `GET /api/minion/workflows`. Also stored locally in `workflows.json`.
-
-```json
-{
-  "name": "my-workflow",
-  "pipeline_skill_names": ["skill-1", "skill-2", "execution-report"],
-  "pipeline": [
-    {
-      "skill_version_id": "uuid",
-      "skill_name": "skill-1",
-      "skill_display_name": "Skill One",
-      "skill_version": 2,
-      "assigned_role": "engineer",
-      "requires_review": false,
-      "is_my_step": true
-    }
-  ],
-  "content": "Markdown description of the workflow",
-  "version": 2,
-  "cron_expression": "0 9 * * *",
-  "project_id": "uuid"
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | string | Slug identifier (`/^[a-z0-9-]+$/`) |
-| `pipeline_skill_names` | string[] | Ordered skill names (for display/push) |
-| `pipeline` | PipelineStep[] | Resolved pipeline with version IDs and roles |
-| `content` | string | Markdown body describing the workflow |
-| `version` | number | Current version number (auto-incremented on push) |
-| `cron_expression` | string\|null | Cron schedule (null = manual/one-shot only) |
-| `project_id` | string | UUID of the parent project |
-
-### Pipeline Step Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `skill_version_id` | string | UUID of the specific skill version |
-| `skill_name` | string | Skill slug name |
-| `skill_display_name` | string | Human-readable skill name |
-| `skill_version` | number | Skill version number |
-| `assigned_role` | string | `"pm"` or `"engineer"` — who executes this step |
-| `requires_review` | boolean | If true, human review required after completion |
-| `is_my_step` | boolean | Whether this minion's role matches assigned_role |
-
-### Syncing workflows with HQ
-
-- `POST /api/workflows/push/:name` — Push local workflow to HQ. Pipeline skills are auto-pushed first.
-- `POST /api/workflows/fetch/:name` — Fetch workflow from HQ. Missing pipeline skills are auto-fetched.
-- `GET /api/workflows/remote` — List workflows available on HQ.
-
-Pipeline skills must be deployed locally (in `~/.claude/skills/`) before pushing a workflow.
-
-## Routine Structure
-
-Routines are minion-scoped and fetched from HQ via `GET /api/minion/routines`.
-They are also stored locally in `routines.json`. Each routine object:
-
-```json
-{
-  "id": "uuid",
-  "name": "morning-work",
-  "pipeline_skill_names": ["project-workflow-check", "execution-report"],
-  "content": "Markdown description of the routine",
-  "cron_expression": "0 9 * * 1-5",
-  "is_active": true,
-  "last_run": "2026-02-10T09:00:00.000Z",
-  "next_run": "2026-02-11T09:00:00.000Z"
-}
-```
+### Routine Structure
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -488,44 +365,12 @@ They are also stored locally in `routines.json`. Each routine object:
 | `last_run` | string\|null | ISO timestamp of last execution |
 | `next_run` | string\|null | ISO timestamp of next scheduled run |
 
-## Routine Execution
-
-Routines run on cron schedules. Each execution:
-1. Creates a tmux session
-2. Runs skills in pipeline order via `claude --dangerously-skip-permissions`
-3. Appends `execution-report` skill to report outcome
-4. Environment variables `MINION_EXECUTION_ID`, `MINION_ROUTINE_ID`, `MINION_ROUTINE_NAME` are available during execution
-
-## Workflow Step Execution via Pending Steps
-
-ミニオンエージェントは `GET /api/minion/pending-steps` を定期ポーリングし、
-自分の担当ステップを検知したら Claude Code を起動してスキルを実行する。
-
-```
-ミニオンエージェント (Port 3001, 常駐, トークン不要)
-  │
-  ├── 軽量ポーリング: N秒ごとに GET /api/minion/pending-steps
-  │   → HTTPのみ、AIなし、コストゼロ
-  │   → pendingステップがなければ何もしない
-  │
-  └── ステップ検知時のみ:
-      1. Claude Code 起動 → 該当スキルを実行
-      2. POST /api/minion/execution → ステップ完了を報告
-      3. Claude Code 終了 → トークン消費はここだけ
-```
-
-### Workflow Execution via Routine (従来方式)
+### Skills
 
-ワークフローは `project-workflow-check` システムスキルを通じてルーティンからも実行可能:
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/minion/skills` | HQ に登録されたスキル一覧 |
+| GET | `/api/minion/skills/[name]` | スキル詳細取得（content, files 含む） |
+| POST | `/api/minion/skills` | スキル登録/更新（新バージョン自動作成） |
 
-```
-ルーティン: "morning-work" (cron: 0 9 * * 1-5)
-  pipeline: [project-workflow-check, execution-report]
-    ↓
-  project-workflow-check:
-    1. GET /api/minion/me/projects → 参加プロジェクト一覧
-    2. GET /api/minion/workflows → active なワークフロー一覧
-    3. 各ワークフローの pipeline を順に実行
-    ↓
-  execution-report → HQ に結果報告
-```
+スキルはバージョン管理される。push ごとに新バージョンが作成され、ファイルは Supabase Storage に保存される。