@geekbeer/minion 4.4.0 → 4.7.0

package/core/stores/variable-store.js

@@ -177,6 +177,36 @@ function deleteEntry(table, workspaceId, key) {
   return { removed: info.changes > 0, wsId }
 }
 
+/**
+ * Move a single entry from one workspace scope to another, atomically.
+ *
+ * Used to fix entries that were registered under the wrong workspace scope.
+ * The destination is NEVER overwritten: if the key already exists at the
+ * destination, the move is refused (`status: 'conflict'`) so no value is lost.
+ *
+ * @returns {{status: 'moved'|'not_found'|'conflict'|'same_scope', value?: string, from?: string, to?: string}}
+ */
+function moveEntry(table, fromWorkspaceId, toWorkspaceId, key) {
+  const from = normalizeWorkspaceId(fromWorkspaceId)
+  const to = normalizeWorkspaceId(toWorkspaceId)
+  if (from === to) return { status: 'same_scope' }
+
+  const db = getDb()
+  const src = db.prepare(`SELECT value FROM ${table} WHERE workspace_id = ? AND key = ?`).get(from, key)
+  if (!src) return { status: 'not_found' }
+
+  const dst = db.prepare(`SELECT 1 FROM ${table} WHERE workspace_id = ? AND key = ?`).get(to, key)
+  if (dst) return { status: 'conflict' }
+
+  const tx = db.transaction(() => {
+    db.prepare(`INSERT INTO ${table} (workspace_id, key, value, updated_at) VALUES (?, ?, ?, ?)`)
+      .run(to, key, src.value, Date.now())
+    db.prepare(`DELETE FROM ${table} WHERE workspace_id = ? AND key = ?`).run(from, key)
+  })
+  tx()
+  return { status: 'moved', value: src.value, from, to }
+}
+
 function listScopes(table) {
   const db = getDb()
   const rows = db.prepare(`SELECT DISTINCT workspace_id FROM ${table}`).all()
@@ -219,6 +249,19 @@ function removeVariable(workspaceId, key) {
   return removed
 }
 
+/**
+ * Move a variable from one workspace scope to another. The destination is not
+ * overwritten on conflict — see `moveEntry`.
+ */
+function moveVariable(fromWorkspaceId, toWorkspaceId, key) {
+  migrateLegacyVariablesFile()
+  const r = moveEntry('variables', fromWorkspaceId, toWorkspaceId, key)
+  if (r.status === 'moved') {
+    console.log(`[VariableStore] Moved variable ${key}: ${r.from || 'minion-wide'} -> ${r.to || 'minion-wide'}`)
+  }
+  return r
+}
+
 function listVariableKeys(workspaceId) {
   migrateLegacyVariablesFile()
   const rows = getRowsForScope('variables', workspaceId)
@@ -280,6 +323,24 @@ function removeSecret(workspaceId, key) {
   return removed
 }
 
+/**
+ * Move a secret from one workspace scope to another. The destination is not
+ * overwritten on conflict — see `moveEntry`.
+ *
+ * Keeps `process.env` in sync: leaving the minion-wide bucket removes the env
+ * var; entering it sets the env var. WS-scoped secrets never touch process.env.
+ */
+function moveSecret(fromWorkspaceId, toWorkspaceId, key) {
+  migrateLegacySecretsFile()
+  const r = moveEntry('secrets', fromWorkspaceId, toWorkspaceId, key)
+  if (r.status === 'moved') {
+    if (r.from === '') delete process.env[key]
+    if (r.to === '') process.env[key] = String(r.value ?? '')
+    console.log(`[VariableStore] Moved secret ${key}: ${r.from || 'minion-wide'} -> ${r.to || 'minion-wide'}`)
+  }
+  return r
+}
+
 function listSecretScopes() {
   migrateLegacySecretsFile()
   return listScopes('secrets')
@@ -345,6 +406,7 @@ module.exports = {
   getVariable,
   setVariable,
   removeVariable,
+  moveVariable,
   listVariableKeys,
   listVariableScopes,
   migrateLegacyVariablesFile,
@@ -355,6 +417,7 @@ module.exports = {
   listSecretKeys,
   setSecret,
   removeSecret,
+  moveSecret,
   listSecretScopes,
   migrateLegacySecretsFile,
 }

package/docs/api-reference.md

@@ -251,6 +251,37 @@ Response:
 }
 ```
 
+### Chat (Detached Execution)
+
+チャットメッセージは **デタッチ実行** される (v4.6.0〜)。`POST /api/chat` で起動した LLM プロセスは
+HTTP リクエストではなく内部の **run manager** が所有するため、SSE 接続が切れても (タブを閉じる・
+リロード・プロキシのアイドルタイムアウト・回線断) 処理は中断されない。接続は単なる「覗き窓」であり、
+切断時はサブスクライブを解除するだけでプロセスは kill されない。LLM を実際に停止するのは
+`POST /api/chat/abort` のみ。
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/chat` | メッセージ送信 → 内部で run を起動し、その run のイベントを SSE で tail。SSE の最初のイベントは `{ "type": "run", "run_id": "..." }`（再接続用） |
+| GET  | `/api/chat/stream` | 進行中(または直近完了)の run に **再接続**し、`cursor` 以降のイベントから tail を再開。`run_id` または `workspace_id`(アクティブ run 自動解決) と任意の `cursor`(=最後に受け取った `seq`) を指定 |
+| POST | `/api/chat/abort` | アクティブ run を明示的に kill (SIGTERM → 2秒後 SIGKILL)。Body に `workspace_id` / `run_id`(任意) |
+| GET  | `/api/chat/session` | アクティブセッションに加え、進行中 run があれば `active_run: { run_id, status, last_seq }` を返す(クライアントはこれを見て `/api/chat/stream` にアタッチする) |
+
+各 SSE イベントには単調増加の `seq` が付与され、これが再接続時の `cursor` になる。終端は必ず
+`{ "type": "done", "session_id, turn_count }`(失敗時は直前に `{ "type": "error" }`)。run の
+イベントログは `$DATA_DIR/chat-runs/{run_id}.ndjson` に永続化され、完了から一定時間(既定10分)後に
+メモリから evict、24時間でログ/索引を prune する。
+
+> **再起動の挙動 (Phase 1):** run manager はミニオンプロセス内で動作するため、ミニオン自体の再起動は
+> 生存しない。起動時に `running` のまま残った run は `interrupted` に掃き出される (クライアントは待ち続けない)。
+> 接続断への耐性が主目的であり、再起動生存は将来の拡張 (tmux バックエンド) で対応予定。
+
+`GET /api/chat/stream` 例:
+```bash
+# 直近のアクティブ run に seq 12 以降から再接続
+curl -N -H "Authorization: Bearer $API_TOKEN" \
+  "http://localhost:8080/api/chat/stream?workspace_id=ws_abc123&cursor=12"
+```
+
 ### Self-Reflection Schedule (自己反省時間)
 
 The minion has a built-in daily scheduler that automatically runs end-of-day processing
@@ -714,10 +745,32 @@ Web ページの読み取り・要約・情報抽出をミニオン内のサブ
 ```json
 {
   "url": "https://example.com/article/123",
-  "hint": "本文と著者を抽出してほしい (任意, 抽出フィールドのヒント)"
+  "hint": "本文と著者を抽出してほしい (任意, 抽出フィールドのヒント)",
+  "scroll": {
+    "strategy": "count",
+    "targetItems": 50,
+    "itemSelector": ".feed-item",
+    "maxScrolls": 20,
+    "maxMs": 15000,
+    "settleMs": 600
+  }
 }
 ```
 
+**`scroll` (任意, v4.7.0〜):** 無限スクロール / 遅延ロードのページで「どこまでコンテンツを読み込むか」を**呼び出し側が宣言**するためのオプション。省略時はスクロールしない (従来動作)。
+
+| フィールド | 説明 |
+|-----------|------|
+| `strategy` | `"count"` (件数到達まで) / `"untilStable"` (件数=増加が止まるまで) / `"fixed"` (回数固定)。未指定/不正ならスクロールしない |
+| `targetItems` | `count` の目標件数。`itemSelector` が解決できる場合のみ有効 |
+| `itemSelector` | 件数を数える CSS セレクタ。省略時はレシピ内の最初の `multiple: true` セレクタを流用 |
+| `maxScrolls` | スクロール回数の上限 (default 10、サーバー上限 50) |
+| `maxMs` | スクロールに使う最大時間 (default 15000、サーバー上限 45000) |
+| `settleMs` | 1スクロールごとの描画待ち静止時間 (default 600) |
+| `times` | `fixed` のスクロール回数 (default 10) |
+
+> 値はサーバー側で上限にクランプされる。スクロール有効時はリクエスト全体のタイムアウトが 60s→120s に拡張される。
+
 **レスポンス (success):**
 ```json
 {
@@ -732,15 +785,24 @@ Web ページの読み取り・要約・情報抽出をミニオン内のサブ
   "title": "...",
   "content": "Markdown 本文...",
   "structured": { "title": "...", "author": "...", "publishedAt": "..." },
-  "selectors": { "title": { "selector": "h1" }, "author": { "selector": "a[rel=author]" } }
+  "selectors": { "title": { "selector": "h1" }, "author": { "selector": "a[rel=author]" } },
+  "scrollInfo": { "scrolls": 12, "items": 50, "reachedTarget": true, "stoppedReason": "reachedTarget" }
 }
 ```
 
+- `scrollInfo` は `scroll` 指定時のみ含まれる。目標未達で上限打ち切りの場合は `reachedTarget: false` と `warning` が返るので、`maxScrolls` / `maxMs` を上げて再試行できる (サイレントに打ち切らない)。
+
 **動作:**
-- 初回アクセス (cold): Playwright でレンダリング → Readability で本文抽出 → Anthropic Haiku でセレクタ生成 → SQLite (`page_recipes`) に保存 → セレクタで再抽出して返却
-- 2回目以降 (hot): URL 正規化・テンプレート化 → DOM フィンガープリントで保存済みレシピを照合 → セレクタで抽出のみ (LLM 呼び出しなし)
+- 初回アクセス (cold): Playwright でレンダリング (**DOM が静止するまで待機**) → Readability で本文抽出 → Anthropic Haiku でセレクタ + `ready_selector` (描画完了の合図となる要素) を生成 → SQLite (`page_recipes`) に保存 → セレクタで再抽出して返却
+- 2回目以降 (hot): URL 正規化・テンプレート化 → DOM フィンガープリントで保存済みレシピを照合 → **`ready_selector` の出現を待機**してからセレクタで抽出 (LLM 呼び出しなし)
 - セルフヒール: hot 実行で空結果が返ったら `fail_count++`、3回失敗で破棄して次回 cold 再生成
 
+**SPA (クライアントレンダリング) への対応 (v4.7.0〜):**
+- `page.goto` は `domcontentloaded` で解決するが、SPA はその時点では中身が空のシェルなので、ナビゲーション後に追加で描画完了を待つ:
+  1. レシピに `ready_selector` があればその要素の出現を待つ
+  2. 無ければ **DOM が `settleMs` の間ミューテーションしなくなるまで待つ** (MutationObserver、コンテンツ量に依存せず自己校正)
+- これにより「SPA の描画が始まる前に空 DOM を掴んでタイムアウト/空結果になる」問題を回避する
+
 **URL 正規化ルール:**
 - `utm_*` `fbclid` `gclid` `ref` 等のトラッキングクエリは除去
 - `page` `p` `offset` 等のページネーション値は `:n` プレースホルダ化
@@ -932,6 +994,20 @@ Response:
 
 同名キーがある場合はワークスペース別が優先される。`/api/secrets/*` エンドポイントは `?workspace_id=<uuid>` クエリパラメータでスコープを指定する。省略または空文字でミニオン全体を操作する。シークレット値はHQ DBには保存されず、HQ APIはpass-throughとして中継するのみ。
 
+#### スコープ間の移動
+
+誤ったワークスペーススコープに登録してしまったシークレット/変数は、削除・再登録せずに別スコープへ**移動**できる。移動はミニオン内部で1トランザクションとして実行され、シークレット値はミニオンの外に出ない。
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/variables/:key/move` | 変数を別スコープへ移動。Body: `{from_workspace_id, to_workspace_id}` |
+| POST | `/api/secrets/:key/move` | シークレットを別スコープへ移動。Body: `{from_workspace_id, to_workspace_id}` |
+
+- `from_workspace_id` / `to_workspace_id` は省略または空文字 `""` でミニオン全体スコープを指す。
+- 移動先に同名キーが既に存在する場合、**上書きせず `409` を返す**（値の消失を防ぐため）。先に移動先の既存キーを削除すること。
+- 移動元にキーが無い場合は `404`、移動元と移動先が同一スコープの場合は `400`。
+- シークレットを移動した場合、ミニオン全体スコープから外れると `process.env` から除去され、ミニオン全体スコープに入ると `process.env` に反映される。
+
 ### Project Tasks
 
 タスクは5段階Kanban (`backlog`/`todo`/`doing`/`review`/`done`)で管理される。親子関係は2階層まで(孫タスク禁止)。担当は **ミニオンか人間の二択**(両方は不可、後勝ち null)。
@@ -2160,6 +2236,8 @@ POST `/api/minion/workspaces/:id/notes` body:
 
 PATCH body は workspace 版と共通: `{title?, content?, change_summary?}` (status は workspace 経由のみ受理)。
 
+> **ロックされたノート (423 Locked):** ユーザーが「ロック」したノート(パスワード等の保護用)は、ミニオンからの更新がすべて拒否され、`HTTP 423` (`{"code":"note_locked"}`) が返る。**ロックの解除は人間のみが HQ ダッシュボードで行える。ミニオンは解除できない。** 423 を受け取ったら、上書きを試み続けず、必要なら threads でユーザーにロック解除を依頼すること。ノート詳細(GET)では `is_locked` / `is_masked` フィールドで状態を確認できる(`is_masked` は HQ UI 上の表示マスクで、API レスポンスの本文には影響しない)。
+
 #### hq CLI ラッパー
 
 ```bash

package/docs/task-guides.md

@@ -20,16 +20,34 @@ curl -X POST http://localhost:8080/api/web/extract \
 
 このAPIは内部で Playwright + Readability を回して **メインセッションには結果 JSON だけ返す** ため、Playwright MCP を使うときに起きていたチャットコンテキストのトークン肥大化が回避できる。
 
+### SPA / 無限スクロールのページ (v4.7.0〜)
+
+- **SPA (React/Vue 等でクライアント描画するページ)** もそのまま `/api/web/extract` でよい。内部で DOM が静止するまで待ってから抽出するため、空シェルを掴む問題は解消済み。
+- **無限スクロール / 「もっと見る」で件数が増えるページ**で十分な件数を確保したい場合は `scroll` オプションを付ける。**どれだけ集めるかは呼び出し側が決める**:
+
+```bash
+curl -X POST http://localhost:8080/api/web/extract \
+  -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
+  -d '{
+    "url": "対象URL",
+    "scroll": { "strategy": "count", "targetItems": 50, "maxScrolls": 20, "maxMs": 15000 }
+  }' | jq
+```
+
+- `count`: 目標件数 (`targetItems`) に達するまでスクロール。`untilStable`: 件数が増えなくなるまで。`fixed`: 回数固定。
+- レスポンスの `scrollInfo.reachedTarget` が `false` なら上限で打ち切られている → `maxScrolls` / `maxMs` を上げて再試行する。
+- スクロール上限はサーバー側でクランプされる (maxScrolls≤50 / maxMs≤45s)。それ以上の網羅が要るなら**ページネーションURLをループ呼び出し**する方が確実。
+
 ### Playwright MCP を使うべき場面
 
 `/api/web/extract` で対応できないのは以下のケース。このときだけ `mcp__playwright__*` を使う:
 
 - ログイン必須ページ (Cookie/2FA 等の認証必要)
 - フォーム入力・複数ページ遷移を伴う操作
-- ボタンクリック→動的に追加されるコンテンツの取得
+- 「もっと見る」**ボタンのクリック**で追加ロードするページ (スクロールでは増えないもの。`scroll` はスクロール式のみ対応)
 - Lancers コンペ応募など、明らかに対話的操作が必要なフロー
 
-**単純な閲覧・抽出用途では MCP を使わない。**
+**単純な閲覧・抽出 (SPA・無限スクロール含む) では MCP を使わない。**
 
 ### よくあるパターン