@agents-ensemble/cli 0.5.3 → 0.6.1

package/docs/config.md

@@ -0,0 +1,170 @@
+# ensemble 共通設定（config.yaml）
+
+> **正本:** `.ensemble/config.yaml` の配置・書き方・スキーマと conductor MCP 設定。本書以外の設定層の一覧・解決パターンは [settings.md](settings.md) を参照します。
+
+`.ensemble/config.yaml` は harness 横断の設定の正本。team-profile（`profile.yaml`）や conductor SDK 認証とは別系統。
+
+conductor（Cursor SDK）に渡す MCP 設定もこの config.yaml とは別の JSON ファイルで管理する（下記の [Conductor MCP 設定](#conductor-mcp-設定mcpjson) を参照）。
+
+## 配置と解決順
+
+| 層 | パス | 優先度 |
+|----|------|--------|
+| プロジェクト | `<repoRoot>/.ensemble/config.yaml` | 高（上書き） |
+| ユーザ | `~/.ensemble/config.yaml` | 低（既定） |
+
+- 両方ある場合は **deep merge**（プロジェクトがユーザを上書き）
+- どちらも無い場合は **コード内デフォルト**
+- **環境変数・CLI フラグは config より優先**（明示上書き）
+
+### 設定項目ごとの解決順（Phase 1）
+
+すべての Phase 1 キーで次の順序を **実装・テストで固定**している:
+
+```
+CLI 明示指定 > 環境変数 > project .ensemble/config.yaml > user ~/.ensemble/config.yaml > コード内デフォルト
+```
+
+`loadEnsembleConfig(repoRoot)` は user → project の順で merge した `EnsembleConfig` を返す。各 `resolve*Setting` はその merged config を **config 層**として参照する。
+
+`ensemble issue` 起動時（GitHub monitor / Issue コンテキスト取得より前）に config を読み込む。
+
+## テンプレート
+
+リポジトリ直下の [`config.example.yaml`](../config.example.yaml) をコピーして使う。実運用の config は `.ensemble/` 配下のため **gitignore 対象**（方針 A）。チームで共有したい非秘密項目だけ example を更新する。
+
+```bash
+mkdir -p .ensemble
+cp config.example.yaml .ensemble/config.yaml
+# またはユーザ全体
+mkdir -p ~/.ensemble
+cp config.example.yaml ~/.ensemble/config.yaml
+```
+
+## スキーマ（Phase 1）
+
+```yaml
+profile:
+  default: implementer-and-reviewer   # ENSEMBLE_DEFAULT_PROFILE 相当
+
+conductor:
+  model: default                      # CONDUCTOR_MODEL_ID 相当
+
+acp:
+  defaultPreset: cursor               # ENSEMBLE_DEFAULT_ACP_CLI 相当
+
+session:
+  worktree: isolated                  # --worktree 既定（isolated | in-repo）
+  maxTurns:
+    tty: 0                            # 0 = 無制限
+    nonTty: 5
+  postLoop:
+    wait: true                        # TTY 時 post-loop 待機（--no-wait で上書き）
+
+github:
+  auth:
+    allowGhAuthTokenFallback: true
+  monitor:
+    enabled: true
+    debounceMs: 30000
+    pollIntervalMs: 60000
+    activePollIntervalMs: 15000
+    stopPollWaitMs: 5000
+
+tui:
+  layout: pane                        # ENSEMBLE_TUI_LAYOUT 相当
+  forceHyperlink: auto                # FORCE_HYPERLINK 相当（auto | on | off）
+```
+
+### キー一覧
+
+| キー | 意味 | CLI 上書き | env 上書き |
+|------|------|-----------|-----------|
+| `profile.default` | 既定 team profile（名前またはパス） | `--profile` | `ENSEMBLE_DEFAULT_PROFILE` |
+| `conductor.model` | conductor モデル id | `--model` | `CONDUCTOR_MODEL_ID` |
+| `acp.defaultPreset` | worker ACP built-in preset | `--default-acp-cli` 等 | `ENSEMBLE_DEFAULT_ACP_CLI` |
+| `session.worktree` | worker workspace モード | `--worktree` | — |
+| `session.maxTurns.tty` / `nonTty` | 自律ターン上限 | `--max-turns` / `--no-max-turns` | — |
+| `session.postLoop.wait` | post-loop 待機（TTY） | `--no-wait` | — |
+| `tui.layout` | TTY レイアウト（`pane` / `stream`） | — | `ENSEMBLE_TUI_LAYOUT` |
+| `tui.forceHyperlink` | Issue リンク OSC 8（`auto` / `on` / `off`） | — | `FORCE_HYPERLINK`（`1`/`0`） |
+| `github.auth.allowGhAuthTokenFallback` | `gh auth token` フォールバック | — | — |
+| `github.monitor.enabled` | Issue / PR 監視 | `--no-github-monitor` | — |
+| `github.monitor.debounceMs` | 更新 debounce | `--github-monitor-debounce-ms` | — |
+| `github.monitor.pollIntervalMs` 他 | poll 間隔（コード内既定のみ） | — | — |
+
+profile / worker に `acp` がある worker は `--default-acp-*` / config `acp.defaultPreset` より **profile 側が優先**（従来どおり）。
+
+### GitHub 認証トークンの解決順
+
+`resolveGitHubAuthToken({ config })`（`@agents-ensemble/core`）:
+
+1. 環境変数 `GITHUB_TOKEN`
+2. 環境変数 `GH_TOKEN`
+3. `config.github.auth.allowGhAuthTokenFallback: true` のときのみ `gh auth token`
+
+`allowGhAuthTokenFallback: false` のときは **`gh auth token` を呼ばない**。CI 等では `GH_TOKEN` / `GITHUB_TOKEN` を明示設定すること。
+
+## 移行表（env → config）
+
+| 従来（env / コード default） | config キー | 備考 |
+|------------------------------|-------------|------|
+| `ENSEMBLE_DEFAULT_PROFILE` | `profile.default` | env は CI 上書き用として維持 |
+| `CONDUCTOR_MODEL_ID` | `conductor.model` | 同上 |
+| `ENSEMBLE_DEFAULT_ACP_CLI` | `acp.defaultPreset` | 同上 |
+| CLI `--worktree` 既定 `isolated` | `session.worktree` | |
+| TTY 無制限 / 非 TTY 5 | `session.maxTurns.tty` / `nonTty` | |
+| TTY post-loop 待機 ON | `session.postLoop.wait` | |
+| monitor 各種定数 | `github.monitor.*` | |
+| `ENSEMBLE_TUI_LAYOUT` | `tui.layout` | env は invocation 上書き用として維持 |
+| `FORCE_HYPERLINK` | `tui.forceHyperlink` | `1`/`0` ↔ `on`/`off`。未設定 ↔ `auto` |
+
+**config 未作成時**は従来どおり env とコード default のみが効く（後方互換）。
+
+## Conductor MCP 設定（mcp.json）
+
+MCP 設定は次の 2 層から読み込み、`mcpServers` のサーバー名単位でマージする。
+
+| 層 | パス | 優先度 |
+|----|------|--------|
+| プロジェクト | `<repoRoot>/.agents/mcp.json` | 高（同名を上書き） |
+| ユーザ | `~/.ensemble/mcp.json` | 低（既定） |
+
+プロジェクト設定が同名サーバーを定義した場合は、ユーザ設定の定義全体を置き換える。片方だけ存在する場合はその設定を使い、両方とも無い場合は MCP なしで起動する。
+
+ファイル形式は Cursor SDK の `mcp.json` 形式（`mcpServers` オブジェクト）を使う。
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "some-mcp-server"],
+      "env": {
+        "API_KEY": "${env:API_KEY}"
+      }
+    }
+  }
+}
+```
+
+この MVP では解決済み設定を conductor の Cursor SDK `Agent.create` / `Agent.resume` に inline MCP として渡す。`Agent.resume` と認証エラーからの in-process reconnect の両方で同じ設定を再注入する。設定値の `${env:...}` や `${workspaceFolder}` などの展開は SDK に任せる。`.cursor/mcp.json` へのコピー・symlink は行わず、ACP worker にはこの設定を渡さない。
+
+JSON が不正、または `mcpServers` / サーバー定義の形式が不正な場合は、そのファイルを `[mcp]` 警告とともにスキップする。もう一方の層が有効ならそちらは引き続き読み込み、両方をスキップした場合は MCP なしで起動する。MCP のホットリロードは行わないため、変更後は新しいセッションを開始する。
+
+## 秘密情報を config に書かない
+
+**token 本体を config に平文で保存しない。** 認証は環境変数、`gh auth login`、将来の stored credential 経路（別 Issue）を使う。
+
+## スキーマ外キー
+
+YAML に未知のキーがあっても **無視する**（警告なし）。将来のスキーマ拡張用に残してよい。既知キーで型が合わない値も **該当キーのみ**無視し、下位層またはデフォルトにフォールバックする。
+
+## 関連
+
+- [settings.md](settings.md) — 全設定層の一覧・解決パターン（本書は config.yaml 詳細）
+- [ADR 0020](https://github.com/otolab/agents-ensemble/blob/main/docs/adr/0020-ensemble-config-setting-resolution.md) — 解決順の設計判断
+- [ADR 0018](https://github.com/otolab/agents-ensemble/blob/main/docs/adr/0018-team-profile-four-layer-resolution.md) — `.ensemble/` 配下の規約（team-profile）
+- [#223](https://github.com/otolab/agents-ensemble/issues/223) — config 基盤
+- [#228](https://github.com/otolab/agents-ensemble/issues/228) — Phase 1 拡張

package/docs/settings.md

@@ -0,0 +1,161 @@
+# 設定値リファレンス
+
+> **正本:** `ensemble` の CLI / 環境変数 / config / profile / TUI 設定の対応表と解決順。本書の `config.yaml` スキーマ詳細は [config.md](config.md) を参照します。
+
+## 設定の層
+
+| 層 | 正本 | 用途 |
+|----|------|------|
+| **CLI フラグ** | `ensemble issue` 等 | invocation 単位の明示上書き |
+| **環境変数** | シェル / CI | 一時上書き・秘密情報・自動化注入 |
+| **project config** | `<repoRoot>/.ensemble/config.yaml` | リポジトリ単位の既定 |
+| **user config** | `~/.ensemble/config.yaml` | マシン全体の既定 |
+| **team profile** | `profile.yaml`（[elements.md](https://github.com/otolab/agents-ensemble/blob/main/docs/elements.md)） | worker 構成・per-worker ACP / workspace |
+| **MCP** | `.agents/mcp.json` / `~/.ensemble/mcp.json` | conductor 向け MCP（[config.md § MCP](config.md#conductor-mcp-設定mcpjson)） |
+| **コード default** | `packages/core/src/config/defaults.ts` 等 | config 未作成時のフォールバック |
+
+project / user config は **deep merge**（project が user を上書き）。秘密情報（token 本体）は **config に平文で書かない**（[config.md](config.md)）。
+
+## 解決パターン
+
+すべての項目が同じ順序ではない。実装は `packages/core/src/config/resolve-settings.ts` の `resolve*Setting` か、各機能の専用解決関数に従う。
+
+### パターン A — Phase 1 横断（env あり）
+
+```
+CLI > 環境変数 > project config > user config > コード default
+```
+
+`profile.default` / `conductor.model` / `acp.defaultPreset` など。設計判断は [ADR 0020](https://github.com/otolab/agents-ensemble/blob/main/docs/adr/0020-ensemble-config-setting-resolution.md)。
+
+### パターン B — Phase 1 横断（env なし）
+
+```
+CLI > project config > user config > コード default
+```
+
+`session.worktree` / `session.maxTurns.*` / `session.postLoop.wait` / `github.monitor.*` など。
+
+### パターン C — profile / worker 優先
+
+worker spawn 時の ACP 解決（[ADR 0019](https://github.com/otolab/agents-ensemble/blob/main/docs/adr/0019-worker-acp-cli-presets.md)）:
+
+```
+profile.workers[].acp > profile.acp > CLI --default-acp-* > ENSEMBLE_DEFAULT_ACP_CLI > config acp.defaultPreset > cursor
+```
+
+### パターン D — 実行時入力（env / CLI）
+
+config キーなし。CI・スクリプト・端末検出、または 1 回限りのオペレータ入力向け。
+
+### パターン E — 認証（config は可否のみ）
+
+| 種別 | 解決順 |
+|------|--------|
+| GitHub API | `GITHUB_TOKEN` > `GH_TOKEN` > （`allowGhAuthTokenFallback: true` 時のみ）`gh auth token` |
+| conductor | `CURSOR_API_KEY` > `~/.cursor/sdk/auth.json`（`ensemble auth login`） |
+| worker ACP（preset 依存） | preset ごとに README / ADR 0019 参照 |
+
+## 一覧 — Phase 1（config.yaml）
+
+| 設定 | config キー | 環境変数 | CLI | コード default | 解決 |
+|------|-------------|----------|-----|----------------|------|
+| 既定 team profile | `profile.default` | `ENSEMBLE_DEFAULT_PROFILE` | `--profile` | 同梱 `implementer-and-reviewer` | A |
+| conductor モデル | `conductor.model` | `CONDUCTOR_MODEL_ID` | `--model` | `default` | A |
+| worker ACP preset（profile 未指定 worker） | `acp.defaultPreset` | `ENSEMBLE_DEFAULT_ACP_CLI` | `--default-acp-cli` 等 | `cursor` | C |
+| Issue worktree | `session.worktree` | — | `--worktree` | `isolated` | B |
+| 自律ターン上限（TTY） | `session.maxTurns.tty` | — | `--max-turns` / `--no-max-turns` | `0`（無制限） | B |
+| 自律ターン上限（非 TTY） | `session.maxTurns.nonTty` | — | `--max-turns` / `--no-max-turns` | `5` | B |
+| post-loop 待機（TTY） | `session.postLoop.wait` | — | `--no-wait` | `true` | B |
+| `gh auth token` フォールバック | `github.auth.allowGhAuthTokenFallback` | — | — | `true` | B |
+| GitHub 監視 | `github.monitor.enabled` | — | `--no-github-monitor` | `true` | B |
+| 監視 debounce | `github.monitor.debounceMs` | — | `--github-monitor-debounce-ms` | `30000` | B |
+| poll 間隔 | `github.monitor.pollIntervalMs` 他 | — | — | 各定数 | B |
+
+テンプレート: [`config.example.yaml`](../config.example.yaml)。`ensemble issue` 起動時（GitHub monitor より前）に `loadEnsembleConfig(repoRoot)` で読み込む。
+
+## 一覧 — TUI / オペレータ UI
+
+| 設定 | 環境変数 | config | CLI | コード default | 解決 |
+|------|----------|--------|-----|----------------|------|
+| TTY レイアウト | `ENSEMBLE_TUI_LAYOUT` | `tui.layout` | — | `pane` | A |
+| OSC 8 ハイパーリンク | `FORCE_HYPERLINK`（`1`/`0`） | `tui.forceHyperlink`（`auto`/`on`/`off`） | — | `auto` | A |
+| オペレータ 1 回注入 | `ENSEMBLE_OPERATOR_MESSAGE` | — | `ensemble issue <ref> [message...]` | — | D |
+
+TUI 設定は `loadEnsembleConfig` 結果を `createIssueSessionTuiHost` へ渡して解決する。Issue リンク表示の詳細は [operator-input.md](https://github.com/otolab/agents-ensemble/blob/main/docs/operator-input.md)。
+
+### 初回オペレータメッセージの CLI / env 関係
+
+`ensemble issue <ref> [message...]` の残り引数をスペース 1 つで結合し、前後を trim して初回メッセージにします。CLI メッセージと `ENSEMBLE_OPERATOR_MESSAGE` は同時に指定できません。両方が trim 後に空でない場合は、優先順位を設けず起動前にエラーにします。
+
+新規セッションでは、指定した値を binding 直後に 1 回だけ `operator.message` として送ります。TTY / 非 TTY の両方に対応します。`--continue` / `--resume` に CLI メッセージを付けた場合は注入せず、stderr に 1 行の警告を出します。
+
+## 一覧 — 自動化・非 TTY
+
+| 設定 | 環境変数 | config | 備考 |
+|------|----------|--------|------|
+| 人間エスカレーション回答 | `ENSEMBLE_ESCALATION_RESPONSE` | — | 非 TTY で `ask_human` への env フォールバック |
+
+## 一覧 — 認証（秘密情報）
+
+| 設定 | 環境変数 | config で制御できること |
+|------|----------|------------------------|
+| GitHub API token | `GITHUB_TOKEN` / `GH_TOKEN` | `github.auth.allowGhAuthTokenFallback` のみ |
+| conductor API key | `CURSOR_API_KEY` | —（`ensemble auth login` は別経路） |
+
+## 一覧 — 別ファイル
+
+| 設定 | ファイル | 解決順 |
+|------|----------|--------|
+| conductor MCP | `.agents/mcp.json` / `~/.ensemble/mcp.json` | project > user（サーバー名単位 merge） |
+| team profile | `.ensemble/profiles/…` / `--profile` パス | [ADR 0018](https://github.com/otolab/agents-ensemble/blob/main/docs/adr/0018-team-profile-four-layer-resolution.md) |
+
+## 一覧 — ランタイム（利用者が「設定」しない）
+
+| 変数 | 用途 |
+|------|------|
+| `TERM_PROGRAM` / `TERM` / `CI` / `WT_SESSION` 等 | OSC 8 対応端末判定（`supportsOsc8Hyperlinks`） |
+| `CURSOR_RIPGREP_PATH` | SDK 起動時に ripgrep パスを設定（内部） |
+| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | conductor の proxy。既存値を優先し、未設定時は Cursor settings から補完 |
+
+## どこに書くべきか
+
+| やりたいこと | 推奨 |
+|--------------|------|
+| チーム / 個人の恒久既定（モデル、worktree、monitor） | `~/.ensemble/config.yaml` または project `.ensemble/config.yaml` |
+| CI で 1 ジョブだけ上書き | 環境変数（`CONDUCTOR_MODEL_ID` 等） |
+| 1 回限りの実行 | CLI フラグ（初回メッセージは `ensemble issue <ref> [message...]`） |
+| token | 環境変数 or `gh auth login` / `ensemble auth login`（config に書かない） |
+| tmux 内で Issue リンクを短縮表示 | `~/.ensemble/config.yaml` に `tui.forceHyperlink: on`（または env `FORCE_HYPERLINK=1`） |
+| worker ごとの ACP / cwd | `profile.yaml` |
+| conductor の MCP | `mcp.json` |
+
+## env-only の棚卸し
+
+次の値は config 化済みの設定を重複して説明するものではなく、用途上 config キーを持たない、または秘密情報・実行環境に依存するため env-only としています。
+
+| env-only | 理由 |
+|----------|------|
+| `ENSEMBLE_OPERATOR_MESSAGE` | CLI 引数を使えない自動化などで、1 回だけオペレータ入力を注入する env-only の値。永続設定にはしない |
+| `ENSEMBLE_ESCALATION_RESPONSE` | 非 TTY で `ask_human` への回答を 1 回注入する自動化用値。永続設定にはしない |
+| `CURSOR_API_KEY` | conductor の秘密情報。config に平文保存しない |
+| `GITHUB_TOKEN` / `GH_TOKEN` | GitHub API の秘密情報。config では token 本体を管理しない |
+| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | SDK 起動時のプロセス環境・既存環境を優先する proxy 設定 |
+| `TERM` / `TERM_PROGRAM` / `CI` 等 | TTY / CI の実行環境を検出する値 |
+| `CURSOR_RIPGREP_PATH` | SDK 起動時に利用する内部ツールの明示指定 |
+
+`profile.default`、`conductor.model`、`acp.defaultPreset`、`session.*`、`github.monitor.*`、`tui.*` のように config キーがある設定は、上の env-only 表ではなく本書の設定一覧と [config.md](config.md) に記載しています。env は invocation 単位の上書きとして残る場合があります。
+
+## 既知のギャップ
+
+| 項目 | 状態 |
+|------|------|
+| `resolveDefaultAcpPresetSetting` と `resolveDefaultAcpSpawn` の二重実装 | 挙動は一致。将来 refactor 可 |
+| Phase 2（`acp.defaultCommand` 等） | [ADR 0020 フォローアップ](https://github.com/otolab/agents-ensemble/blob/main/docs/adr/0020-ensemble-config-setting-resolution.md) |
+
+## 関連
+
+- [config.md](config.md) — `config.yaml` スキーマ・MCP・移行表
+- [CLI README](https://github.com/otolab/agents-ensemble/blob/main/docs/cli/README.md) — CLI のインストール・最小クイックスタート
+- [operator-input.md](https://github.com/otolab/agents-ensemble/blob/main/docs/operator-input.md) — TUI レイアウト・Issue リンク
+- [ADR 0020](https://github.com/otolab/agents-ensemble/blob/main/docs/adr/0020-ensemble-config-setting-resolution.md) — Phase 1 解決順

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-ensemble/cli",
-  "version": "0.5.3",
+  "version": "0.6.1",
   "type": "module",
   "description": "ensemble CLI — Issue-based agent orchestration",
   "bin": {
@@ -14,9 +14,9 @@
     "commander": "14.0.1",
     "ink": "7.1.1",
     "react": "19.2.0",
-    "react-ink-textarea": "npm:@otolab/react-ink-textarea@0.4.1-otolab.0",
+    "react-ink-textarea": "npm:@otolab/react-ink-textarea@0.4.1-otolab.3",
     "string-width": "8.1.0",
-    "@agents-ensemble/core": "0.5.3"
+    "@agents-ensemble/core": "0.6.1"
   },
   "devDependencies": {
     "@types/js-yaml": "4.0.9",
@@ -34,7 +34,10 @@
     "directory": "packages/cli"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "docs/**",
+    "config.example.yaml"
   ],
   "publishConfig": {
     "access": "public",
@@ -44,7 +47,7 @@
     "node": ">=22.0.0"
   },
   "scripts": {
-    "build": "tsc --build",
+    "build": "tsc --build && node scripts/copy-docs.mjs",
     "test:e2e": "vitest run --config vitest.config.e2e.ts",
     "test": "vitest",
     "test:run": "vitest run",