@maplezzk/pi-interactive-subagents 3.10.0 → 3.11.0

package/README.md

@@ -8,7 +8,7 @@ https://github.com/user-attachments/assets/30adb156-cfb4-4c47-84ca-dd4aa80cba9f
 
 ## How It Works
 
-Call `subagent()` and it **returns immediately**. The sub-agent runs in its own terminal pane. A live widget above the input shows all running agents with their current state — `starting`, `active`, `waiting`, `stalled`, or `running`. When a sub-agent finishes, its result is **steered back** into the main session as an async notification — triggering a new turn so the agent can process it.
+Call `subagent()` and it **returns immediately**. The sub-agent runs in its own terminal pane. A live widget above the input shows all running agents with their current state — `starting`, `active`, `waiting`, `stalled`, or `running`. When a sub-agent finishes, its result is **steered back** into the main session as an async notification — triggering a new turn so the agent can process it. Completion reminders are injected only after the model stops normally; user aborts and provider errors stay quiet.
 
 ```
 ╭─ Subagents ──────────────────────────── 2 running ─╮

package/README.zh-CN.md

@@ -6,7 +6,7 @@
 
 ## 工作原理
 
-调用 `subagent()` 后**立即返回**，子 agent 在自己的终端分屏中运行。输入框上方的实时 widget 展示所有运行中的 agent 及其状态（`starting`、`active`、`waiting`、`stalled`、`running`）。子 agent 完成后，结果以异步通知形式**回流**到主会话，触发新一轮处理。
+调用 `subagent()` 后**立即返回**，子 agent 在自己的终端分屏中运行。输入框上方的实时 widget 展示所有运行中的 agent 及其状态（`starting`、`active`、`waiting`、`stalled`、`running`）。子 agent 完成后，结果以异步通知形式**回流**到主会话，触发新一轮处理。完成提醒仅在模型正常停止后注入；用户手动终止或提供方异常不会触发。
 
 ```typescript
 subagent({ name: "Scout: Auth", agent: "scout", task: "分析 auth 模块" });

package/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: configure-pi-interactive-subagents
+description: "配置与排查 interactive subagents 的终端复用器、Herdr split/tab 和状态面板。Use when configuring subagent mux behavior."
+---
+
+# 配置 pi-interactive-subagents
+
+## 诊断
+
+读取实际 Pi agent 目录下的 `extensions/pi-interactive-subagents/config.json`：`mux` 保存后端偏好，`herdrMode` 保存 `split|tab`。状态面板的 `status.enabled` 由安装包根目录的 `config.json` 读取；不存在时读取同目录 `config.json.example`。状态行数当前固定为 4，不是配置项。
+
+环境变量优先级：`PI_TERMINAL_MUX` > `PI_SUBAGENT_MUX` > 持久化 `mux` > `auto`；`PI_SUBAGENT_HERDR_MODE` > 持久化 `herdrMode` > `split`。
+
+## 修改
+
+优先运行：
+
+```text
+/config:subagent auto|muxy|cmux|tmux|zellij|wezterm|herdr [split|tab]|otty|orca
+```
+
+不带参数时使用交互选择。`/subagent-config`、`/pi-subagent-config` 是兼容别名。选择会立即写入用户配置并应用；环境变量仍可覆盖。
+
+不要把未支持的后端写入配置。修改状态配置时只使用 `status.enabled`；`status.lineLimit` 等未知字段会显式失败，无效 JSON 也不会静默回退。
+
+## 验证
+
+先用 `subagents_list` 确认扩展工具已加载，再启动一个最小 `subagent`，观察对应 pane/tab 与状态 widget。终端后端不可用时必须报告失败；不要静默声称已回退到目标后端。真实启动会创建子进程和终端 surface，执行前遵守当前任务的 E2E 授权边界。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maplezzk/pi-interactive-subagents",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "description": "Interactive async subagents for pi — spawn, orchestrate, and manage sub-agent sessions in multiplexer panes. Fork of HazAT/pi-interactive-subagents.",
   "type": "module",
   "main": "./index.ts",
@@ -14,10 +14,11 @@
     "locales",
     "config.json.example",
     "README.md",
-    "README.zh-CN.md"
+    "README.zh-CN.md",
+    "SKILL.md"
   ],
   "scripts": {
-    "test": "tsx --test test/test.ts",
+    "test": "tsx --test test/subagent-done-nudge.test.ts test/test.ts",
     "test:integration": "tsx --test --test-concurrency=1 test/integration/*.test.ts",
     "typecheck": "tsc --noEmit --pretty false",
     "build": "npm run typecheck",
@@ -27,6 +28,9 @@
     "extensions": [
       "./index.ts",
       "../pi-extensions-i18n/index.ts"
+    ],
+    "skills": [
+      "./SKILL.md"
     ]
   },
   "engines": {
@@ -58,8 +62,8 @@
   ],
   "dependencies": {
     "ajv": "^8.20.0",
-    "pi-extensions-i18n": "^0.3.1",
-    "pi-terminal-mux": "^0.4.0"
+    "pi-extensions-i18n": "^0.4.0",
+    "pi-terminal-mux": "^0.4.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.80.0 <0.81.0",

package/pi-extension/subagents/subagent-done.ts

@@ -13,7 +13,7 @@
  *   现在不论 autoExit env 如何，agent 都必须主动调用 subagent_done 或 caller_ping
  *   才能结束。如果 agent 不调，会被 nudge 提醒。
  */
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { writeFileSync } from "node:fs";
@@ -22,23 +22,41 @@ import { createTranslator, loadCatalog } from "pi-extensions-i18n";
 import { createSubagentActivityRecorder } from "./activity.ts";
 
 const i18n = createTranslator(loadCatalog(new URL("../../locales/index.json", import.meta.url)));
+const ASSISTANT_ROLE = "assistant";
+const NORMAL_STOP_REASON = "stop";
+const ABORTED_STOP_REASON = "aborted";
 
+/** Treat input as manual takeover only after the first agent run has started. */
 export function shouldMarkUserTookOver(agentStarted: boolean): boolean {
   return agentStarted;
 }
 
+/** Return true only when the latest assistant message ended by the model stopping normally. */
+export function shouldScheduleAgentEndNudge(
+  messages: readonly { role?: string; stopReason?: string }[] | undefined,
+): boolean {
+  if (!messages) return false;
+
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message?.role === ASSISTANT_ROLE) {
+      return message.stopReason === NORMAL_STOP_REASON;
+    }
+  }
+
+  return false;
+}
+
+/** Preserve the former auto-exit decision for callers that still use this helper. */
 export function shouldAutoExitOnAgentEnd(
   _userTookOver: boolean,
-  messages: any[] | undefined,
+  messages: readonly { role?: string; stopReason?: string }[] | undefined,
 ): boolean {
-  // Manual input should not strand an auto-exit subagent. If the latest agent
-  // turn completed normally, close the session. Escape/abort still leaves it
-  // open for inspection or another prompt.
   if (messages) {
     for (let i = messages.length - 1; i >= 0; i--) {
-      const msg = messages[i];
-      if (msg?.role === "assistant") {
-        return msg.stopReason !== "aborted";
+      const message = messages[i];
+      if (message?.role === ASSISTANT_ROLE) {
+        return message.stopReason !== ABORTED_STOP_REASON;
       }
     }
   }
@@ -46,6 +64,7 @@ export function shouldAutoExitOnAgentEnd(
   return true;
 }
 
+/** Parse the comma-separated denied-tool setting and discard blank entries. */
 export function parseDeniedTools(rawValue: string | undefined): string[] {
   return (rawValue ?? "")
     .split(",")
@@ -81,6 +100,7 @@ export default function (pi: ExtensionAPI) {
   let userInputAfterAgentEnd = false;
   let nudgeTimer: ReturnType<typeof setTimeout> | null = null;
 
+  /** Cancel and forget the pending completion reminder, if any. */
   function clearNudgeTimer(): void {
     if (nudgeTimer !== null) {
       clearTimeout(nudgeTimer);
@@ -89,18 +109,17 @@ export default function (pi: ExtensionAPI) {
   }
 
   /**
-   * After a non-auto-exit subagent finishes generating, schedule a nudge
-   * reminding it to call subagent_done if it hasn't already.
+   * After a subagent stops normally, schedule a nudge reminding it to call
+   * subagent_done if it hasn't already. Error and aborted runs are excluded.
    *
    * Each call replaces any pending nudge, so repeated agent_end events
-   * (e.g. during multi-turn tool use) automatically reset the timer.
-   * The nudge only fires if no new agent activity or user input arrives
-   * within NUDGE_DELAY_MS.
+   * automatically reset the timer. The nudge only fires if no new agent
+   * activity or user input arrives within NUDGE_DELAY_MS.
    */
   function scheduleAgentEndNudge(): void {
     clearNudgeTimer();
     // 不论 autoExit 是否启用，都必须 nudge — autoExit 已被移除，
-    // agent 结束 turn 后只能靠主动调用 subagent_done 才能真正退出。
+    // agent 正常结束 turn 后只能靠主动调用 subagent_done 才能真正退出。
     if (NUDGE_DISABLED || doneCalled) return;
 
     nudgeTimer = setTimeout(() => {
@@ -114,10 +133,11 @@ export default function (pi: ExtensionAPI) {
     }, NUDGE_DELAY_MS);
   }
 
-  function renderWidget(ctx: { ui: { setWidget: Function } }, _theme: any) {
+  /** Render the subagent identity and tool availability widget. */
+  function renderWidget(ctx: Pick<ExtensionContext, "ui">): void {
     ctx.ui.setWidget(
       "subagent-tools",
-      (_tui: any, theme: any) => {
+      (_tui, theme) => {
         const box = new Box(1, 0, (text: string) => theme.bg("toolSuccessBg", text));
 
         const label = subagentAgent || subagentName;
@@ -178,7 +198,7 @@ export default function (pi: ExtensionAPI) {
     toolNames = tools.map((t) => t.name).sort();
     denied = parseDeniedTools(deniedToolsValue);
 
-    renderWidget(ctx, null);
+    renderWidget(ctx);
   });
 
   pi.on("input", () => {
@@ -216,10 +236,13 @@ export default function (pi: ExtensionAPI) {
     // subagent_done（或 caller_ping）。如果 agent 不调，下面会有 nudge 提醒。
     recorder.agentEndWaiting();
 
-    // For non-auto-exit agents: schedule a nudge in case the AI forgot to call
-    // subagent_done. This is automatically cleared/reset on any subsequent
-    // agent activity or user input.
-    scheduleAgentEndNudge();
+    // Only a normal model stop means the agent itself chose to finish.
+    // Provider errors and user aborts must stay quiet.
+    if (shouldScheduleAgentEndNudge(event.messages)) {
+      scheduleAgentEndNudge();
+    } else {
+      clearNudgeTimer();
+    }
   });
 
   pi.on("turn_start", (event) => {
@@ -272,7 +295,7 @@ export default function (pi: ExtensionAPI) {
     description: "Toggle subagent tools widget",
     handler: (ctx) => {
       expanded = !expanded;
-      renderWidget(ctx, null);
+      renderWidget(ctx);
     },
   });