pi-brainstorm 0.4.0 → 0.4.2

package/README.md

@@ -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.4.0
+pi install git:github.com/Jarcis-cy/pi-brainstorm@v0.4.2
 ```
 
 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

@@ -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.4.0
+pi install git:github.com/Jarcis-cy/pi-brainstorm@v0.4.2
 ```
 
 本地开发安装：
@@ -83,10 +89,26 @@ participants:
 
 ## 前置条件
 
-该扩展依赖 pi 中已有的 `subagent` 工具。命令处理器会先创建本地会议记录，然后让主 Agent 调用配置中定义的参与者（默认：`gpt-brainstormer`、`deepseek-brainstormer`、`minimax-brainstormer`、`glm-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/extensions/brainstorm.ts

@@ -301,7 +301,6 @@ function generateAgentFile(participant: ParticipantConfig): string {
     : `- 参与多模型讨论并提供${participant.displayName}视角的分析`;
 
   return [
-    MANAGED_MARKER,
     "---",
     `name: ${yamlScalar(participant.agentName)}`,
     `description: ${yamlScalar(description)}`,
@@ -309,6 +308,8 @@ function generateAgentFile(participant: ParticipantConfig): string {
     `model: ${yamlScalar(participant.model)}`,
     "---",
     "",
+    MANAGED_MARKER,
+    "",
     `# ${participant.displayName} Brainstormer${roleTitle}`,
     "",
     participant.rolePrompt,
@@ -573,7 +574,7 @@ function buildBrainstormPrompt(
     "",
     "### NEVER do this",
     "- Do NOT fabricate or simulate a consultant's response",
-    "- Do NOT wait more than 3 minutes total per consultant (including retries)",
+    "- 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",
@@ -691,7 +692,7 @@ function buildDebatePrompt(
     "",
     "### NEVER do this",
     "- Do NOT fabricate or simulate a debater's argument",
-    "- Do NOT wait more than 3 minutes total per debater (including retries)",
+    "- 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",
     "",

package/package.json

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