@geekbeer/minion 3.13.0 → 3.14.0

package/docs/api-reference.md

@@ -54,9 +54,9 @@ Outcome values: `success`, `failure`, `partial`
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/terminal/sessions` | List tmux sessions |
+| GET | `/api/terminal/sessions` | List sessions (CMD + WSL merged) |
 | POST | `/api/terminal/send` | Send keys. Body: `{session, input?, enter?, special?}` |
-| POST | `/api/terminal/create` | Create session. Body: `{name?, command?}` |
+| POST | `/api/terminal/create` | Create session. Body: `{name?, command?, type?, get_or_create?}` |
 | POST | `/api/terminal/kill` | Kill session. Body: `{session}` |
 | GET | `/api/terminal/capture` | Capture pane content. Query: `?session=&lines=100` |
 | GET | `/api/terminal/ttyd/status` | ttyd process status |
@@ -64,6 +64,31 @@ Outcome values: `success`, `failure`, `partial`
 | POST | `/api/terminal/ttyd/stop` | Stop ttyd for session. Body: `{session}` |
 | POST | `/api/terminal/ttyd/stop-all` | Stop all ttyd processes |
 
+#### WSL セッション（Windows ミニオン限定）
+
+WSL 内でコマンドを実行するには `type: "wsl"` を指定する。セッション名は `wsl-` prefix が自動付与される。
+
+```bash
+# WSL セッション作成（既存があれば再利用）
+curl -X POST http://localhost:8080/api/terminal/create \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "wsl-dev", "type": "wsl", "get_or_create": true}'
+```
+
+| パラメータ | 型 | 説明 |
+|-----------|-----|------|
+| `type` | string | `"wsl"` で WSL セッションを作成 |
+| `get_or_create` | boolean | `true` の場合、同名の既存セッションがあれば再利用（レスポンスに `reused: true`） |
+
+WSL セッションの上限は **5つ**。上限に達すると `429` を返す。不要なセッションを `kill` してから再作成すること。
+
+```bash
+# WSL サーバー稼働状態の確認
+curl http://localhost:8080/api/terminal/wsl/status \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
 ### Files
 
 Files are stored in `~/files/`. Max upload size: 50MB.

package/docs/environment-setup.md

@@ -232,6 +232,14 @@ curl -X POST http://localhost:8080/api/chat \
 | 7682 | WSL session server (HTTP API) | localhost のみ |
 | 7683 | WSL session server (WebSocket) | localhost のみ、ttyd プロトコル |
 
+### セッション管理
+
+- **セッション再利用**: `get_or_create: true` を指定すると、同名の既存セッションがあれば再利用される。毎回新しいセッションを作らないこと。
+- **固定名**: `wsl-dev`, `wsl-build` など目的を示す名前を使う。名前を省略するとタイムスタンプ名が生成され再利用できない。
+- **上限**: WSL セッションは最大 5 つ。上限に達すると作成が拒否される。
+- **自動クリーンアップ**: 完了済みセッションは 5 分後に自動削除される。
+- **手動クリーンアップ**: 不要なセッションは `POST /api/terminal/kill` で終了する。
+
 ### トラブルシューティング
 
 | 問題 | 原因 | 対処 |
@@ -239,6 +247,7 @@ curl -X POST http://localhost:8080/api/chat \
 | WSL session server is not running | ユーザーが未ログイン | RDP/コンソールでログイン |
 | WSL not detected during setup | WSL 未インストール | `wsl --install` を実行後 `minion-cli setup` を再実行 |
 | Connection refused on port 7682 | サーバー異常終了 | `schtasks /Run /TN "MinionWSL"` で再起動 |
+| WSL session limit reached | 5 セッション上限 | `GET /api/terminal/sessions` で確認し不要なセッションを `kill` |
 
 ---
 

package/package.json

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

package/rules/core.md

@@ -40,6 +40,30 @@ Minion
 
 API の詳細仕様は `~/.minion/docs/api-reference.md` の「Email」セクションを参照。
 
+## Terminal Session Management
+
+ターミナルセッション（`/api/terminal/*`）を使用する際は以下のルールに従うこと。
+
+### セッション再利用の原則
+
+- **新しいセッションを作る前に、既存セッションを確認する。**
+  ```bash
+  curl -H "Authorization: Bearer $API_TOKEN" http://localhost:8080/api/terminal/sessions
+  ```
+- 目的に合う既存セッション（未完了で再利用可能なもの）があれば、そのセッションに `send` でコマンドを送る。
+- 新規作成が必要な場合は、**目的を示す固定名**を付ける（例: `dev`, `build`, `test`）。タイムスタンプ名（`session-1234567890`）は避ける。
+
+### クリーンアップ
+
+- 作業が完了したセッションは `POST /api/terminal/kill` で終了する。
+- 一時的なコマンド実行（`command` 引数付きで作成したセッション）は、完了確認後に必ず kill する。
+- セッションを放置しない。使い終わったら片付ける。
+
+### セッション数の制限
+
+- 同時に保持するセッションは **最大3つ** を目安にする。
+- それ以上必要な場合は、不要なセッションを先に kill してから作成する。
+
 ## Available Tools
 
 ### CLI

package/rules/windows.md

@@ -0,0 +1,72 @@
+# Windows Minion
+
+Windows ミニオン固有のルール。
+
+## WSL セッション管理
+
+Windows ミニオンでは WSL（Windows Subsystem for Linux）内の Docker やリポジトリ操作のために WSL セッションを使用できる。
+
+### WSL セッションの使い方
+
+#### ターミナルセッション
+
+WSL 内でコマンドを実行するには `type: "wsl"` を指定してセッションを作成する:
+
+```bash
+# WSL セッション作成（固定名を付けること）
+curl -X POST http://localhost:8080/api/terminal/create \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "wsl-dev", "type": "wsl"}'
+
+# コマンド送信
+curl -X POST http://localhost:8080/api/terminal/send \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"session": "wsl-dev", "input": "docker compose up -d", "enter": true}'
+
+# 出力確認
+curl "http://localhost:8080/api/terminal/capture?session=wsl-dev&lines=50" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+#### チャット（WSL モード）
+
+チャット API に `wsl_mode: true` を追加すると、Claude Code CLI がユーザーセッションで実行され WSL コマンドを直接使用できる:
+
+```bash
+curl -X POST http://localhost:8080/api/chat \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"message": "WSL内でリポジトリをクローンしてDockerを起動して", "wsl_mode": true}'
+```
+
+### セッション管理ルール
+
+#### 再利用を徹底する
+
+- **WSL セッションの新規作成前に、必ず既存セッションを確認する。**
+  ```bash
+  curl -H "Authorization: Bearer $API_TOKEN" http://localhost:8080/api/terminal/sessions
+  ```
+  レスポンスの `type: "wsl"` かつ `completed: false` のセッションがあれば再利用する。
+- **固定名を使う。** `wsl-dev`, `wsl-build`, `wsl-docker` など目的を示す名前を付ける。
+  名前を省略すると `wsl-session-{timestamp}` が自動生成され、再利用できなくなる。
+- **1つの WSL セッションで複数コマンドを順次実行する。** コマンドごとに新しいセッションを作らない。
+
+#### クリーンアップ
+
+- WSL 作業が完了したら `POST /api/terminal/kill` でセッションを終了する。
+- WSL セッションは最大 **5つ** まで。上限に達すると新規作成が拒否される。
+- 完了済み（`completed: true`）のセッションは自動的にクリーンアップされる。
+
+#### WSL セッションサーバーの確認
+
+WSL セッションが使えない場合は、まずサーバーの稼働状態を確認する:
+
+```bash
+curl http://localhost:8080/api/terminal/wsl/status \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+`running: false` の場合、ターゲットユーザーがログインしていない可能性がある。

package/win/routes/terminal.js

@@ -316,13 +316,26 @@ async function terminalRoutes(fastify) {
     if (type === 'wsl') {
       const sessionName = name || `wsl-session-${Date.now()}`
       const wslName = sessionName.startsWith('wsl-') ? sessionName : `wsl-${sessionName}`
+
+      // get_or_create: return existing session if it's still alive
+      if (request.body.get_or_create) {
+        const sessions = await proxyToWsl('GET', '/api/wsl/sessions')
+        if (sessions && sessions.success && sessions.sessions) {
+          const existing = sessions.sessions.find(s => s.name === wslName && !s.completed)
+          if (existing) {
+            console.log(`[Terminal] Reusing existing WSL session '${wslName}'`)
+            return { success: true, session: wslName, message: `Reusing existing WSL session '${wslName}'`, reused: true }
+          }
+        }
+      }
+
       console.log(`[Terminal] Creating WSL session '${wslName}' — proxying to WSL server`)
       const result = await proxyToWsl('POST', '/api/wsl/create', { name: wslName, command })
       if (!result) {
         reply.code(503)
         return { success: false, error: 'WSL session server is not running. The target user must be logged in for WSL sessions.' }
       }
-      reply.code(result.success ? 200 : 500)
+      reply.code(result.success ? 200 : (result.error?.includes('limit') ? 429 : 500))
       return result
     }
 

package/win/server.js

@@ -144,10 +144,12 @@ function syncBundledRules() {
   try {
     if (!fs.existsSync(bundledRulesDir)) return
     fs.mkdirSync(targetRulesDir, { recursive: true })
-    const coreSrc = path.join(bundledRulesDir, 'core.md')
-    if (fs.existsSync(coreSrc)) {
-      fs.copyFileSync(coreSrc, path.join(targetRulesDir, 'core.md'))
-      console.log('[Rules] Synced: core.md')
+    for (const ruleFile of ['core.md', 'windows.md']) {
+      const src = path.join(bundledRulesDir, ruleFile)
+      if (fs.existsSync(src)) {
+        fs.copyFileSync(src, path.join(targetRulesDir, ruleFile))
+        console.log(`[Rules] Synced: ${ruleFile}`)
+      }
     }
     for (const legacy of ['minion.md', 'role-pm.md', 'role-engineer.md']) {
       const legacyPath = path.join(targetRulesDir, legacy)

package/win/wsl-session-server.js

@@ -29,6 +29,9 @@ const DATA_DIR = path.join(HOME_DIR, '.minion')
 const TOKEN_FILE = path.join(DATA_DIR, '.wsl-session-token')
 const PID_FILE = path.join(DATA_DIR, '.wsl-session.pid')
 
+const MAX_WSL_SESSIONS = 5
+const COMPLETED_SESSION_TTL_MS = 5 * 60 * 1000 // 5 minutes
+
 let AUTH_TOKEN = ''
 try {
   AUTH_TOKEN = fs.readFileSync(TOKEN_FILE, 'utf-8').trim()
@@ -109,6 +112,7 @@ function createWslSession(sessionName, command) {
   ptyProcess.onExit(({ exitCode }) => {
     session.completed = true
     session.exitCode = exitCode
+    session.completedAt = Date.now()
     for (const ws of session.wsClients) {
       try { ws.close() } catch {}
     }
@@ -119,6 +123,30 @@ function createWslSession(sessionName, command) {
   return session
 }
 
+/**
+ * Remove completed sessions that have been idle for COMPLETED_SESSION_TTL_MS.
+ */
+function reapCompletedSessions() {
+  const now = Date.now()
+  for (const [name, session] of activeSessions) {
+    if (session.completed && session.completedAt && now - session.completedAt > COMPLETED_SESSION_TTL_MS) {
+      activeSessions.delete(name)
+      console.log(`[WSL] Reaped completed session '${name}'`)
+    }
+  }
+}
+
+/**
+ * Count active (non-completed) sessions.
+ */
+function activeSessionCount() {
+  let count = 0
+  for (const [, session] of activeSessions) {
+    if (!session.completed) count++
+  }
+  return count
+}
+
 const specialKeyMap = {
   'Enter': '\r', 'Escape': '\x1b', 'Tab': '\t',
   'C-c': '\x03', 'C-d': '\x04', 'C-z': '\x1a',
@@ -249,10 +277,24 @@ async function startServer() {
     if (!/^[\w-]+$/.test(sessionName)) {
       reply.code(400); return { success: false, error: 'Invalid session name' }
     }
+
+    // Reap completed sessions before checking limits
+    reapCompletedSessions()
+
     if (activeSessions.has(sessionName)) {
       reply.code(409); return { success: false, error: `Session '${sessionName}' already exists` }
     }
 
+    if (activeSessionCount() >= MAX_WSL_SESSIONS) {
+      reply.code(429)
+      return {
+        success: false,
+        error: `WSL session limit reached (max ${MAX_WSL_SESSIONS}). Kill unused sessions before creating new ones.`,
+        active_sessions: activeSessionCount(),
+        max_sessions: MAX_WSL_SESSIONS,
+      }
+    }
+
     try {
       createWslSession(sessionName, command)
       return { success: true, session: sessionName, message: `WSL session '${sessionName}' created` }
@@ -373,6 +415,9 @@ async function startServer() {
     fs.writeFileSync(PID_FILE, String(process.pid))
   } catch {}
 
+  // Periodically reap completed sessions
+  setInterval(reapCompletedSessions, 60 * 1000)
+
   return fastify
 }