@agents-ensemble/cli 0.9.0 → 0.9.2

package/README.md

@@ -36,7 +36,7 @@ Pi backend は Pi の設定ファイルを読みます。モデル設定は次
 
 Pi の resource root は `~/.ensemble/pi/` と `<repoRoot>/.ensemble/pi/` です。`conductor.pi.agentDir` / `conductor.pi.projectDir` で root のみ上書きできます。`settings.json` / `auth.json` / `models.json` / `extensions/` / `skills/` / `prompts/` / `themes/` を解決し、skills は compiled system prompt に追加され、prompts は `/name args` として展開されます。themes は headless conductor で読み込み・project 同名解決まで行いますが、TUI renderer がないため色・表示設定は適用しません。`.ensemble/pi/SYSTEM.md` / `APPEND_SYSTEM.md` は conductor の system prompt には使わず、modular-prompt のコンパイル結果を優先します。
 
-`settings.json` の headless 対応は、モデル選択（`defaultProvider` / `defaultModel`）、認証 fallback（`apiKey` / `apiKeys`）、resource path（`extensions` / `skills` / `prompts` / `themes`）に限定されます。`defaultThinkingLevel`、`thinkingBudgets`、`packages`、`enableSkillCommands` など Pi coding-agent の挙動・TUI・package 設定は警告なしで無視します。詳細な対応キーと失敗モードは [config.md の headless 対応範囲](../config.md#settingsjson-の-headless-対応範囲) を参照してください。
+`settings.json` の headless 対応は、モデル選択（`defaultProvider` / `defaultModel`）、認証 fallback（`apiKey` / `apiKeys`）、resource path（`extensions` / `skills` / `prompts` / `themes`）、および Pi `AgentSession` の compaction（`compaction.*`）と branch summary（`branchSummary.*`）です。コード正本は `pi-headless-settings.ts` で、未知のキーを含む未対応設定は Pi SDK の SettingsManager に渡さず警告なしで無視します。headless conductor は `.ensemble/pi` の設定だけを使い、Pi 標準の `<cwd>/.pi/settings.json` は読みません。`sessionDir` は設定しても conductor の transcript 保存先を変更せず、harness の `<repoRoot>/.ensemble/pi/sessions/` を使います。create / resume は `.ensemble/pi` を読み、reload は起動時スナップショットを再適用します。reload または snapshot 復元に失敗した session は close / dispose 済みの unusable 状態になります。cleanup が成功した単一の元エラーはそのまま reject され、元エラーと cleanup error が併発した場合は `AggregateError` の `.errors` に両方を含めて reject されるため、失敗した session は再利用せず resume/create してください。詳細な対応キーと失敗モードは [config.md の headless 対応範囲](../config.md#settingsjson-の-headless-対応範囲) を参照してください。
 
 MCP は harness が解決した `mcp.json` の map を Pi 1.x の公式 `createMcpExtension({ loadConfig })` へ注入します。Pi の `createAgentSession` は stdio / Streamable HTTP を扱い、SSE はサポートしません。MCP tool 名は `mcp__<server>__<tool>`、resource tools は `list_mcp_resources` / `list_mcp_resource_templates` / `read_mcp_resource` です。HTTP OAuth は公式 extension の対話フロー・credential store が担当します。解決済み設定が無い場合も harness tools と local extension tools は有効です。sidecar には MCP map の digest を保存し、resume 時に変更を検出した場合は fail fast します。Pi `.pi/mcp.json` への同期や core 独自の MCP client はありません。設計上の前提と制限は [ADR 0025](../adr/0025-conductor-agent-backend-sdk-and-pi.md) を参照してください。
 

package/config.example.yaml

@@ -24,9 +24,17 @@ conductor:
     projectDir: .ensemble/pi
     # 上記の各 root に settings.json / auth.json / models.json、
     # extensions/ / skills/ / prompts/ / themes/ を配置します。
-    # settings.json は headless conductor の対応キー（モデル選択・
-    # 認証 fallback・resource path）のみ有効です。thinking / packages /
+    # settings.json は headless conductor の対応キー（モデル選択・認証
+    # fallback・resource path・compaction.*・branchSummary.*）だけが有効です。
+    # compaction / branchSummary は user → project の deep merge で適用します。
+    # sessionDir は無視され、transcript は harness の
+    # <repoRoot>/.ensemble/pi/sessions/ が正本です。thinking / packages /
     # TUI 等の Pi coding-agent 設定は警告なしで無視します。
+    # Pi 標準の <repoRoot>/.pi/settings.json は headless conductor では読みません。
+    # reload は起動時スナップショットを再適用し、設定変更の反映は resume/create で行います。
+    # reload または snapshot 復元に失敗した session は close/dispose され unusable になります。
+    # cleanup も失敗した場合は元エラーと cleanup error を含む AggregateError になります。
+    # その session は再利用せず、resume/create で再作成してください。
 
 acp:
   # profile / worker に acp 未指定時の built-in preset

package/docs/config.md

@@ -123,30 +123,46 @@ profile / worker に `acp` がある worker は `--default-acp-*` / config `acp.
 - `prompts/`: Markdown template を読み込み、`/name args` の user prompt を Pi 標準の引数置換で展開します。
 - `themes/`: Pi 標準 JSON として読み込み、project 同名を優先します。conductor は headless `AgentSession` のため TUI renderer がなく、theme の色・表示設定はモデル入出力には適用しません。
 
-Pi の認証 CLI は provider 単位です。`ensemble auth login --provider <id>` は API-key provider なら secret prompt の値を user root の `auth.json`（既定 `~/.ensemble/pi/auth.json`）へ保存し、OAuth provider なら Pi 1.x の `ModelRuntime.login` を TTY / stderr 経由で実行します。`--provider` を省略した場合は `settings.json` の `defaultProvider` または選択モデルから解決します。`logout` / `status` も同じ provider 解決を使います。project `auth.json` は既存の project-over-user 読取優先を維持しますが、login の書込み先にはなりません。project 層の明示的な OAuth credential は runtime が安全に refresh できないため実行時には使わず、user 層でのログインを案内します。Pi の MCP HTTP OAuth は conductor provider OAuth とは別に、公式 MCP extension が `mcp-auth.json` と対話フローを管理します。`ensemble models list` は `ModelRegistry` と project resource の解決結果から認証済み model だけを表示します。
+Pi の認証 CLI は provider 単位です。`ensemble auth login --provider <id>` は API-key provider なら secret prompt の値を user root の `auth.json`（既定 `~/.ensemble/pi/auth.json`）へ保存し、OAuth provider なら Pi 1.x の `ModelRuntime.login` を TTY / stderr 経由で実行します。`--provider` を省略した場合は `settings.json` の `defaultProvider` または選択モデルから解決します。`logout` / `status` も同じ provider 解決を使います。project `auth.json` は既存の project-over-user 読取優先を維持しますが、login の書込み先にはなりません。project 層の明示的な OAuth credential は runtime が安全に refresh できないため実行時には使わず、user 層でのログインを案内します。Pi 標準どおり `models.json` / `settings.json` の API キーと header には `!command`（シェルコマンドの stdout）も指定できます。このコマンドは conductor プロセスの shell で実行され、同プロセスの OS 権限・環境を使うため、信頼できる設定でのみ使用してください。これは Pi と同じ accepted risk です。Pi の MCP HTTP OAuth は conductor provider OAuth とは別に、公式 MCP extension が `mcp-auth.json` と対話フローを管理します。`ensemble models list` は `ModelRegistry` と project resource の解決結果から認証済み model だけを表示します。
 
 #### `settings.json` の headless 対応範囲
 
 conductor は Pi 1.x の `createAgentSession` / `DefaultResourceLoader` を headless で使います。TUI と package manager は起動しないため、`settings.json` は Pi 標準のファイル名と resource path の意味を保ちますが、headless conductor が実際に参照するキーだけを契約とします。
 
+この契約のコード正本は [`pi-headless-settings.ts`](../packages/core/src/conductor/pi-headless-settings.ts) の `PI_HEADLESS_SETTING_DEFINITIONS` です。各キーには、conductor 内の `model-selection` / `auth-fallback` / `resource-path`、Pi SDK の `settings-manager-override` のいずれかの適用チャネル、または `ignored` が定義されています。表はコード正本を利用者向けに説明したものです。表にないキーも `ignored` と同じ扱いです。
+
 実際に効くキーは次のとおりです。
 
-| キー | headless conductor での意味 |
-|------|----------------------------|
-| `defaultProvider` / `defaultModel` | 明示的な `provider/model` がない場合のモデル選択。`model` / `modelId` は conductor の互換 alias として同じ選択に使います。 |
-| `apiKey` / `apiKeys` | `auth.json` に provider credential がない場合の認証 fallback。 |
-| `extensions` / `skills` / `prompts` / `themes` | 各 resource root を基準に追加で読む path。通常の `extensions/` 等の discovery と併用します。 |
+| キー | 適用チャネル | headless conductor での意味 |
+|------|--------------|----------------------------|
+| `defaultProvider` / `defaultModel` | `model-selection` | 明示的な `provider/model` がない場合のモデル選択。`model` / `modelId` は conductor の互換 alias として同じ選択に使います。 |
+| `apiKey` / `apiKeys` | `auth-fallback` | `auth.json` に provider credential がない場合の認証 fallback。 |
+| `extensions` / `skills` / `prompts` / `themes` | `resource-path` | 各 resource root を基準に追加で読む path。通常の `extensions/` 等の discovery と併用します。 |
+| `compaction.*` | `settings-manager-override` | Pi の `AgentSession` が行う manual / automatic compaction。`enabled`、`reserveTokens`、`keepRecentTokens`、`modelOverrides` だけを user → project の deep merge 結果から `SettingsManager` へ渡します。 |
+| `branchSummary.*` | `settings-manager-override` | Pi の branch summary。`reserveTokens` / `skipPrompt` だけを `compaction.*` と同じ merge 結果から `SettingsManager` へ渡します。 |
+
+#### Pi 標準の `<cwd>/.pi/settings.json` との関係
+
+Pi SDK の file-backed `SettingsManager` は通常、`agentDir/settings.json` と `<cwd>/.pi/settings.json` を自動的に読み込みます。しかし headless conductor はこの経路を使わず、**`SettingsManager.inMemory()` にコード正本で allowlist した settings-manager チャネルだけを渡します**。したがって、`<cwd>/.pi/settings.json`（および Pi 標準の `agentDir/settings.json`）に書いた値が headless conductor へ漏れることはありません。
+
+headless conductor の設定正本は常に `~/.ensemble/pi/settings.json` と `<repoRoot>/.ensemble/pi/settings.json` です。Pi CLI 用の `<cwd>/.pi/settings.json` とのコピー・symlink・自動マイグレーション・書き換えは行いません。`.pi` の設定を使う別の Pi CLI と、`ensemble issue` の Pi backend は独立しています。
+
+#### create / reload / resume の適用ポリシー
+
+- **create**: `loadPiResources` が `.ensemble/pi` の user → project を deep merge し、モデル選択・認証・resource path は各チャネルで使い、`compaction.*` / `branchSummary.*` は allowlist 後に in-memory `SettingsManager` へ適用します。
+- **reload**: Pi `AgentSession.reload()` の後に、create 時に解決した同じ settings-manager スナップショットを再適用します。実行中の `.ensemble/pi/settings.json` の変更を hot reload する契約ではないため、設定変更を反映するには `resume` または新しい create が必要です。`AgentSession.reload()` または snapshot の再適用が失敗した場合は、snapshot の復元を試みた後、session を close / dispose して unusable とします。失敗が 1 つだけで close / dispose が成功した場合はその元のエラーを reject し、reload と snapshot 復元の両方、または close / dispose の cleanup error も発生した場合は `AggregateError` を reject します。`AggregateError.errors` には発生した元の reload / snapshot エラーと cleanup error が含まれます。失敗した session は send で再利用せず、同じ transcript を続ける場合も `resume`、新しい作業なら create で再作成してください。
+- **resume**: 新しい Pi session を作るため `.ensemble/pi` を再読込し、create と同じチャネル適用を行ってから既存 transcript を開きます。resume でも `<cwd>/.pi/settings.json` は読みません。
 
-Pi の `settings.md` にあるが headless conductor が適用しないキーは、拒否せず警告なしで無視します。
+Pi の `settings.md` にあるが headless conductor が適用しないキーは、Pi SDK の SettingsManager へ渡さず、拒否せず警告なしで無視します。
 
 | 無視するキー（または prefix） | 適用されない挙動 |
 |------------------------------|------------------|
 | `defaultThinkingLevel` / `modelThinkingLevels` / `thinkingBudgets` / `enabledModels` | thinking level、budget、model cycling の設定 |
 | `hideThinkingBlock` / `showCacheMissNotices` / `cacheWarming` / `steeringMode` / `followUpMode` | transcript 表示、cache、対話キューの設定 |
-| `defaultTools` / `codemode.*` | Pi built-in coding tools の選択。conductor は built-in coding tools を無効にし、harness / MCP / local extension と公式 codemode/tool-search extension の loadout を使います。 |
+| `defaultTools` / `codemode.*` | `defaultTools` は headless conductor では無視します。built-in coding tools は profile の `conductor.builtinTools`（省略・未指定は有効、`false` のみ無効）で制御し、`config.yaml` には同キーを設けません。 |
 | `packages` | Pi package の install・解決。package が提供する resource は自動導入しません。 |
 | `enableSkillCommands` | skill command の登録 toggle。読み込んだ skill の `/skill:<name>` 展開可否はこのキーで変更できません。 |
-| `sessionDir` / `compaction.*` / `branchSummary.*` | Pi の session・compact・branch summary。session は harness の `.ensemble/pi/sessions/` が管理します。 |
+| `sessionDir` | Pi の settings にある session 保存先は conductor では変更できません。transcript は常に harness が `<repoRoot>/.ensemble/pi/sessions/` で管理します。 |
 | `theme` / `quietStartup` / `tuiMode` / `fullscreen*` / `terminal.*` / `images.*` / `markdown.*` | headless conductor の TUI・terminal 表示 |
 | `transport` / `httpProxy` / `httpIdleTimeoutMs` / `websocketConnectTimeoutMs` / `retry.*` / `shellPath` / `shellCommandPrefix` / `npmCommand` | Pi coding-agent の network、shell、package runtime |
 | `collapseChangelog` / `enableInstallTelemetry` / `enableAnalytics` / `warnings.*` | coding-agent の update、telemetry、UI warning |

package/docs/settings.md

@@ -28,7 +28,7 @@ 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)。
 
-`conductor.backend` は、選択した profile の `conductor.backend` を project/user の deep merge 済み config より優先し、どちらも未指定なら `cursor` を使います。`cursor` は Cursor SDK 経路、`pi` は Pi 1.x `createAgentSession` 経路を選びます。Pi は compiled conductor instructions を native system prompt に載せ、`~/.ensemble/pi` と `<repoRoot>/.ensemble/pi` の `settings.json` / `auth.json` / `models.json` / `extensions/` / `skills/` / `prompts/` / `themes/` を解決します。skills は system prompt へ追加し、prompts は `/name args` で展開します。themes は headless conductor のため読み込み・project 同名解決のみ行い、TUI 表示には使いません。root は `conductor.pi.agentDir` / `conductor.pi.projectDir` で上書きできます。`.ensemble/pi/SYSTEM.md` / `APPEND_SYSTEM.md` は無視します。`ensemble auth login|logout|status` は backend に分岐し、Pi では provider 単位に `ModelRuntime` を使います。API key は TTY の secret prompt から user 層へ保存し、OAuth は Pi の OAuth flow を stderr 対話で実行します（SSH でも URL / device code を利用できます）。MCP HTTP OAuth は Pi 公式 MCP extension が別の credential store で扱います。resume では sidecar に保存した backend と起動時の解決結果が一致しない場合、次のエラーで conductor を起動せず失敗します。
+`conductor.backend` は、選択した profile の `conductor.backend` を project/user の deep merge 済み config より優先し、どちらも未指定なら `cursor` を使います。`profile.conductor.builtinTools` は profile だけで制御し、省略・未指定は有効、`false` のみ built-in coding tools を無効にします。`config.yaml` や `settings.json.defaultTools` ではこの制御を行いません。`cursor` は Cursor SDK 経路、`pi` は Pi 1.x `createAgentSession` 経路を選びます。Pi は compiled conductor instructions を native system prompt に載せ、`~/.ensemble/pi` と `<repoRoot>/.ensemble/pi` の `settings.json` / `auth.json` / `models.json` / `extensions/` / `skills/` / `prompts/` / `themes/` を解決します。skills は system prompt へ追加し、prompts は `/name args` で展開します。themes は headless conductor のため読み込み・project 同名解決のみ行い、TUI 表示には使いません。root は `conductor.pi.agentDir` / `conductor.pi.projectDir` で上書きできます。`.ensemble/pi/SYSTEM.md` / `APPEND_SYSTEM.md` は無視します。`ensemble auth login|logout|status` は backend に分岐し、Pi では provider 単位に `ModelRuntime` を使います。API key は TTY の secret prompt から user 層へ保存し、OAuth は Pi の OAuth flow を stderr 対話で実行します（SSH でも URL / device code を利用できます）。MCP HTTP OAuth は Pi 公式 MCP extension が別の credential store で扱います。resume では sidecar に保存した backend と起動時の解決結果が一致しない場合、次のエラーで conductor を起動せず失敗します。
 
 ```text
 Session sidecar conductorBackend mismatch: pi !== cursor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-ensemble/cli",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "type": "module",
   "description": "ensemble CLI — Issue-based agent orchestration",
   "bin": {
@@ -17,7 +17,7 @@
     "react": "19.2.0",
     "react-ink-textarea": "npm:@otolab/react-ink-textarea@0.4.1-otolab.3",
     "string-width": "8.1.0",
-    "@agents-ensemble/core": "0.9.0"
+    "@agents-ensemble/core": "0.9.2"
   },
   "devDependencies": {
     "@types/js-yaml": "4.0.9",