pi-brainstorm 0.3.1 → 0.4.1

package/README.md

@@ -10,7 +10,7 @@ The plugin stores each participant's full contribution in a local meeting blackb
 
 ## Features
 
-- Multi-model brainstorming with configurable participants (default: GPT, DeepSeek, MiniMax).
+- Multi-model brainstorming with configurable participants (default: GPT, DeepSeek, MiniMax, GLM).
 - Debate / battle mode where agents prosecute, stress-test, and challenge positions.
 - Configuration-driven: add, remove, or customize participants via YAML.
 - Round-by-round summaries focused on consensus, disagreement, and next questions.
@@ -21,7 +21,13 @@ The plugin stores each participant's full contribution in a local meeting blackb
 
 ## Install
 
-From npm:
+Recommended one-line install:
+
+```bash
+pi install npm:@narumitw/pi-subagents && pi install npm:pi-brainstorm
+```
+
+Install only this package from npm:
 
 ```bash
 pi install npm:pi-brainstorm
@@ -30,7 +36,7 @@ pi install npm:pi-brainstorm
 From GitHub:
 
 ```bash
-pi install git:github.com/Jarcis-cy/pi-brainstorm@v0.3.1
+pi install git:github.com/Jarcis-cy/pi-brainstorm@v0.4.1
 ```
 
 For local development:
@@ -39,6 +45,26 @@ For local development:
 pi install /Users/jarcis/Project/pi-brainstorm
 ```
 
+## Prerequisites
+
+`pi-brainstorm` orchestrates participants through Pi's `subagent` tool. Install the `subagent` tool separately before using `/brainstorm` or `/debate`:
+
+```bash
+pi install npm:@narumitw/pi-subagents
+```
+
+`@narumitw/pi-subagents` registers the `subagent` tool used by this package to run participant agents in isolated Pi subprocesses. It is a runtime prerequisite, not bundled inside `pi-brainstorm`.
+
+For reference, Pi's coding-agent distribution also includes an example implementation at:
+
+```text
+/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/
+```
+
+`pi-brainstorm` also needs participant agents such as `gpt-brainstormer`, `deepseek-brainstormer`, `minimax-brainstormer`, and `glm-brainstormer`. On first use, the extension can create or update managed user-level agent files from its YAML configuration. Existing unmanaged agent files are left untouched.
+
+`@narumitw/pi-subagents` applies a hard subprocess timeout. If `timeoutMs` is not set, it uses `PI_SUBAGENT_TIMEOUT_MS`, or `600000` milliseconds (10 minutes) when that environment variable is unset. Long participant output is not itself a timeout condition, but generating very long output can take longer and may hit that wall-clock timeout. Participant full text is written to `.pi-meetings/...`; the main chat should only receive short `WROTE_ENTRY` summaries and facilitator synthesis.
+
 ## Configuration
 
 Participants are defined in YAML. The extension loads config in this order (later overrides earlier):

package/README.zh-CN.md

@@ -10,7 +10,7 @@ English README: [README.md](./README.md).
 
 ## 功能
 
-- 多模型头脑风暴：参与者可配置（默认：GPT、DeepSeek、MiniMax）。
+- 多模型头脑风暴：参与者可配置（默认：GPT、DeepSeek、MiniMax、GLM）。
 - 辩论 / battle 模式：Agent 会攻击、审视、反驳彼此的观点。
 - 配置驱动：通过 YAML 添加、删除或自定义参与者。
 - 每轮输出聚焦共识、分歧、关键问题和下一步方向。
@@ -21,7 +21,13 @@ English README: [README.md](./README.md).
 
 ## 安装
 
-通过 npm 安装：
+推荐一行安装：
+
+```bash
+pi install npm:@narumitw/pi-subagents && pi install npm:pi-brainstorm
+```
+
+只安装本包：
 
 ```bash
 pi install npm:pi-brainstorm
@@ -30,7 +36,7 @@ pi install npm:pi-brainstorm
 通过 GitHub 安装：
 
 ```bash
-pi install git:github.com/Jarcis-cy/pi-brainstorm@v0.3.1
+pi install git:github.com/Jarcis-cy/pi-brainstorm@v0.4.1
 ```
 
 本地开发安装：
@@ -83,10 +89,26 @@ participants:
 
 ## 前置条件
 
-该扩展依赖 pi 中已有的 `subagent` 工具。命令处理器会先创建本地会议记录，然后让主 Agent 调用配置中定义的参与者（默认：`gpt-brainstormer`、`deepseek-brainstormer`、`minimax-brainstormer`）。
+`pi-brainstorm` 通过 Pi 的 `subagent` 工具来调用各个参与者。使用 `/brainstorm` 或 `/debate` 前，请先单独安装提供 `subagent` 工具的包：
+
+```bash
+pi install npm:@narumitw/pi-subagents
+```
+
+`@narumitw/pi-subagents` 会注册 `subagent` 工具，让 `pi-brainstorm` 能把参与者作为隔离的 Pi 子进程运行。它是运行时前置条件，不随 `pi-brainstorm` 打包。
+
+作为参考，Pi coding-agent 发行包中也包含一个 example implementation，通常位于：
+
+```text
+/opt/homebrew/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/subagent/
+```
+
+命令处理器会先创建本地会议记录，然后让主 Agent 通过 `subagent` 调用配置中定义的参与者（默认：`gpt-brainstormer`、`deepseek-brainstormer`、`minimax-brainstormer`、`glm-brainstormer`）。
 
 第一次使用时，如果这些用户级 agent 不存在，扩展会询问是否写入内置默认定义。已有同名且不含托管标记的文件不会被覆盖。
 
+`@narumitw/pi-subagents` 对每个子进程有 hard timeout。未设置 `timeoutMs` 时，会使用环境变量 `PI_SUBAGENT_TIMEOUT_MS`；如果环境变量也没设置，默认是 `600000` 毫秒（10 分钟）。子 agent 输出很长本身不会被判定为 timeout，但生成超长输出会增加运行时间，如果超过这个 wall-clock timeout，就会被 `subagent` 工具标记为超时。参与者全文应写入 `.pi-meetings/...`，主会话只应看到短的 `WROTE_ENTRY` 摘要和主持人综合。
+
 ## 命令
 
 ```text

package/config/default.yaml

@@ -26,7 +26,7 @@ participants:
   - displayName: DeepSeek
     agentName: deepseek-brainstormer
     description: DeepSeek brainstorming consultant. Meticulous systems thinker for multi-model discussion sessions.
-    model: deepseek/deepseek-v4-pro:xhigh
+    model: opencode-go/deepseek-v4-pro:xhigh
     roleTitle: Meticulous Systems Thinker
     rolePrompt: |
       你是多模型头脑风暴中的系统思考者。分析结构、依赖、扩展上限和失败模式。用中文回答。
@@ -56,3 +56,21 @@ participants:
       prompt: |
         DEBATE MODE. You are THE CONTRARIAN. Take the opposite position from the dominant view. Expose groupthink. Propose radical alternatives. Challenge the fundamental premise if needed. Use Chinese.
     brainstormRole: Creative lateral thinker
+
+  - displayName: GLM
+    agentName: glm-brainstormer
+    description: GLM-5.2 brainstorming consultant. Pragmatic implementer who grounds ideas in feasibility, cost, and real-world constraints.
+    model: opencode-go/glm-5.2:xhigh
+    roleTitle: Pragmatic Implementer
+    rolePrompt: |
+      你是多模型头脑风暴中的务实执行者。当别人谈愿景、讲架构、玩创意时，你负责问：「这到底能不能做出来？」「需要多少资源？」「有什么更简单的方案？」你的价值在于把讨论拉回现实。用中文回答。
+    whatYouDo:
+      - 从可行性、成本、时间和资源角度审视每个提案
+      - 指出不切实际的想法——诚实、直接
+      - 提出更简单的替代方案，避免过度设计
+      - 关注执行路径和最小可行版本
+    debatePersona:
+      label: THE PRAGMATIST
+      prompt: |
+        DEBATE MODE. You are THE PRAGMATIST. Challenge every proposal on feasibility, cost, and real-world constraints. Expose impractical ideas. Push for simpler, cheaper, faster solutions. Use Chinese.
+    brainstormRole: Pragmatic implementer

package/extensions/brainstorm.ts

@@ -546,6 +546,36 @@ function buildBrainstormPrompt(
     "",
     "After Round 3, present the complete structural overview and ask whether to write the final conclusion. Only write conclusion.md after the user confirms.",
     "",
+    "## FAILURE HANDLING",
+    "Subagent calls can fail (timeout, API error, model unavailable, crash). You MUST detect and handle failures:",
+    "",
+    "### Detecting failure",
+    "A subagent call has FAILED if:",
+    "- The tool result contains error text (\"error\", \"failed\", \"timeout\", \"unavailable\", \"connection\", etc.)",
+    "- The subagent returns no output or empty output",
+    "- The subagent output does NOT contain \"WROTE_ENTRY:\" (the expected success marker)",
+    "- The subagent produced no meeting_append_entry call (check with meeting_read_index after the parallel batch)",
+    "",
+    "### Retry strategy",
+    "When you detect a failure:",
+    "1. Wait 5-10 seconds before retrying (API rate limits may have triggered the failure)",
+    "2. Retry the SAME consultant with the SAME task up to 2 more times (3 attempts total)",
+    "3. On retry, add to the task: \"PREVIOUS ATTEMPT FAILED. This is retry N of 2. Focus only on completing your contribution and writing WROTE_ENTRY.\"",
+    "4. If the consultant succeeds on retry, proceed normally",
+    "5. If ALL retries are exhausted, treat this consultant as UNAVAILABLE for this round",
+    "",
+    "### When a consultant is UNAVAILABLE",
+    "- Do NOT wait indefinitely or freeze the session",
+    "- Proceed with the remaining consultants who succeeded",
+    "- In your structural overview, clearly mark the failed participant as: \"[displayName] ([agentName]): 本轮未响应 / did not respond\"",
+    "- Continue to the next round normally — do NOT skip the consultant in future rounds (they may recover)",
+    "- If the same consultant fails in 2 consecutive rounds, warn the user with the real display name, e.g.: \"DeepSeek 连续两轮失败，建议检查该模型是否可用\"",
+    "",
+    "### NEVER do this",
+    "- Do NOT fabricate or simulate a consultant's response",
+    "- Do NOT impose an extra manual timeout beyond the subagent tool's timeout; if the tool reports timeout, treat that attempt as failed",
+    "- Do NOT abort the entire session because one consultant failed",
+    "",
     "## IMPORTANT",
     "- All responses in Chinese (中文).",
     "- Save transcript.md and (after user confirms) conclusion.md per the MEETING OUTPUT PROTOCOL.",
@@ -634,6 +664,37 @@ function buildDebatePrompt(
     "- If NOT converged: run another cycle. Keep going.",
     "- If converged: present synthesis to me.",
     "",
+    "## FAILURE HANDLING",
+    "Subagent calls can fail (timeout, API error, model unavailable, crash). You MUST detect and handle failures:",
+    "",
+    "### Detecting failure",
+    "A subagent call has FAILED if:",
+    "- The tool result contains error text (\"error\", \"failed\", \"timeout\", \"unavailable\", \"connection\", etc.)",
+    "- The subagent returns no output or empty output",
+    "- The subagent output does NOT contain \"WROTE_ENTRY:\" (the expected success marker)",
+    "- The subagent produced no meeting_append_entry call (check with meeting_read_index after the chain step)",
+    "",
+    "### Retry strategy",
+    "When you detect a failure in a chain step:",
+    "1. Wait 5-10 seconds before retrying (API rate limits may have triggered the failure)",
+    "2. Retry the SAME debater with the SAME task up to 2 more times (3 attempts total)",
+    "3. On retry, add to the task: \"PREVIOUS ATTEMPT FAILED. This is retry N of 2. Focus only on completing your argument and writing WROTE_ENTRY.\"",
+    "4. If the debater succeeds on retry, proceed to the next debater in the chain",
+    "5. If ALL retries are exhausted, SKIP this debater for this cycle and move to the next debater",
+    "",
+    "### When a debater is UNAVAILABLE",
+    "- Do NOT wait indefinitely or freeze the session",
+    "- Skip to the next debater in the cycle",
+    "- In your structural overview, clearly mark the failed participant as: \"[displayName] ([agentName]): 本轮未响应 / did not respond\"",
+    "- Continue the debate with remaining debaters — do NOT abort the whole debate",
+    "- If the same debater fails in 2 consecutive cycles, warn the user with the real display name, e.g.: \"DeepSeek 连续两轮失败，建议检查该模型是否可用\"",
+    "",
+    "### NEVER do this",
+    "- Do NOT fabricate or simulate a debater's argument",
+    "- Do NOT impose an extra manual timeout beyond the subagent tool's timeout; if the tool reports timeout, treat that attempt as failed",
+    "- Do NOT abort the entire debate because one debater failed",
+    "- Do NOT get stuck in an infinite retry loop — 3 attempts max per debater per cycle",
+    "",
     "## Rules",
     "- NEVER stop at a predetermined count. Only convergence or user intervention ends this debate.",
     "- All responses in Chinese (中文).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-brainstorm",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Multi-model brainstorming and debate sessions for pi subagents.",
   "type": "module",
   "keywords": [