@muzi3/herdr 0.1.2 → 0.1.3

package/README.md

@@ -7,6 +7,8 @@
 | `herdr-guide` | user-invoked 向导 | 引导用户理解、安装、配置与排查 Herdr（`herdr.dev/agent-guide.md`） |
 | `herdr-agent-state` | 扩展 | 通过 Herdr 的 pane socket 上报 agent 状态（working / blocked / idle）及会话引用，供 Herdr 面板展示 |
 | `pi-hot-restart` | 扩展 | 提供 `/pi-hot-restart` 命令：批量重启当前 herdr 里的所有 pi 窗口（跳过 working），并恢复到原 session |
+| `session-notify` | 扩展 | 把 pi 的阻塞式交互弹窗（`ui_prompt_start` / `ui_prompt_end`，含 `ask_user_question`）转发为 herdr 的 `herdr:blocked` 事件（pane 显示 `blocked`），并发 macOS 桌面横幅：标题带 pane + 本轮任务，正文带问题原文 / 完成用时 |
+| `tab-task-label` | 扩展（默认不启用） | 每轮提问时把所在 tab 改名为该轮任务摘要，让 herdr 界面里也能看出「在做什么」；需要时加回 `pi.extensions` |
 
 ## 来源与许可
 
@@ -19,7 +21,7 @@ Herdr 以 [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) 许可发布
 
 > 扩展源文件由 Herdr 集成管理，重装或更新集成时会覆盖；请在旁边添加自定义 hooks 而非编辑它。
 
-`pi-hot-restart.ts` 是本包自带的补充扩展，与官方 `herdr-agent-state` 互不干扰，在 `package.json` 的 `pi.extensions` 中显式声明（因 `extensions/index.ts` 存在时 pi 不会扫描同目录兄弟文件）。
+`pi-hot-restart.ts`、`session-notify.ts` 与 `tab-task-label.ts`（默认未启用）是本包自带的补充扩展，与官方 `herdr-agent-state` 互不干扰，在 `package.json` 的 `pi.extensions` 中显式声明（因 `extensions/index.ts` 存在时 pi 不会扫描同目录兄弟文件）。
 
 ## 安装
 
@@ -41,6 +43,32 @@ pi install npm:@muzi3/herdr
 3. 弹出确认框，展示将重启的窗口清单与数量；
 4. 对每个目标窗口：向 pi 前台进程组发 SIGTERM 优雅退出（session 落盘），等待退出后用 `pi --session <path|id>` 在原 pane 恢复。
 
+### 等用户输入时上报 blocked + 桌面横幅
+
+herdr 的 pi 集成只认 `herdr:blocked` 事件，且 herdr 0.9.0 对 pi 仍没有终端 blocked 识别规则（内置规则只有一条 `working_literal`，匹配 `Working...`），所以 `ask_user_question` / confirm 弹窗期间 pane 会一直停在 `working`。`session-notify` 订阅 pi core 的 `ui_prompt_start` / `ui_prompt_end`（`select`/`confirm`/`input`/`editor`/`custom` 统一包装，只在外层触发）：
+
+- 等待期发 `herdr:blocked { active: true, label }`，结束后发 `{ active: false }`；label 形如 `等待回答：<问题 header>`（`custom` 无 title，取 `rpiv:ask-user:prompt` 的问题内容）、`等待确认：<title>`。
+- 契约同 pi-subagents 的 herdr-status bridge：herdr 的 `blockedCount` 是计数式的，切 label 前先发 `active:false` 再发 `active:true`；本扩展严格配对，只占一个计数。
+- 同一份信号同时发 macOS 桌面横幅：标题 `herdr · <pane id> · <本轮任务>`，正文 `等待回答：<问题原文>`；每轮结束时（`agent_settled` 且 `isIdle`）再发一条 `完成 · 用时 <n>s`。
+
+为什么桌面横幅自己发（herdr 0.9.0 实测）：
+
+- 内置弹窗正文是固定的 `<工作区名> · <工作区编号> · <tab 名>`，pane metadata（`--title` / `--display-agent` / `--state-label`）不会进弹窗，0.9.0 也没有内容定制选项；
+- herdr 会抑制「当前 tab」的通知，而一个 tab 里放多个 agent pane 是常见用法，等于一起静音；
+- 所以 `ui.toast.delivery` 保持 `off`（只留 herdr 内应用 toast + 音效），桌面横幅由本扩展负责，同一状态不弹两份。
+
+通道：优先用 `terminal-notifier`（`/opt/homebrew/bin`、`/usr/local/bin`，或 node-notifier 自带的那份；支持 `-group`，同一 pane 的旧横幅会被新横幅替换），否则回落到系统自带 `osascript`。只在 macOS + herdr 集成环境（`HERDR_ENV=1`、`HERDR_PANE_ID`）+ TUI 会话下工作；CLI 失败或超时静默忽略，不影响 pi 本体。
+
+> 与 `@raidou/pi-notify` 功能重叠：pi-notify 的通知内容只有 `pi — <cwd 目录名>` / `Waiting: Prompt`，区分不了同一目录下的多个 pane。两个都开会弹两份，建议在 `~/.pi/agent/settings.json` 设 `"piNotify": { "enabled": false }`。
+
+### （可选）tab 改名带上「在做什么」
+
+`tab-task-label.ts` 在每轮 `before_agent_start` 时把所在 tab 改名为该轮任务摘要（`event.prompt` 首行、折叠空白、截断到 40 字符），让 herdr 界面里的 tab 名就是当前任务。桌面横幅已经带上任务名，所以它默认**不在** `pi.extensions` 中启用；需要时加回去即可。
+
+- 只用 `HERDR_ENV` / `HERDR_TAB_ID` 门槛；CLI 调用失败或超时静默忽略，不阻塞 agent 启动。
+- 会话正常退出（`session_shutdown` 且 `reason === "quit"`）时，若 tab 名仍是我们写的那一份就还原为原名；用户中途手动改过则不覆盖。
+- 已知取舍：会覆盖用户自己起的 tab 名；同一 tab 内多个 pi 会话会互相覆盖，以最后提问者为准。
+
 ### 扩展环境变量
 
 扩展需在 Herdr 集成环境中运行，依赖以下环境变量：
@@ -50,6 +78,7 @@ pi install npm:@muzi3/herdr
 | `HERDR_ENV` | 为 `1` 时启用 |
 | `HERDR_SOCKET_PATH` | Herdr pane socket 路径 |
 | `HERDR_PANE_ID` | 当前 pane id |
+| `HERDR_TAB_ID` | 当前 tab id（可选启用 `tab-task-label` 时用） |
 
 未设置这些变量时 `herdr-agent-state` 扩展静默跳过。`pi-hot-restart` 通过 PATH 调用 `herdr` CLI（`agent list` / `pane process-info` / `pane run`），不依赖上述变量。
 

package/extensions/session-notify.ts

@@ -0,0 +1,190 @@
+/**
+ * session-notify
+ *
+ * 两件相关的事，共用同一份「pi 现在在等什么 / 刚做完什么」的判断：
+ *
+ * 1) blocked 状态桥：把 pi 的阻塞式交互提示转发成 herdr 的 blocked 状态。
+ *    herdr 的 pi 集成只监听 `herdr:blocked` 事件再上报 `state: "blocked"`；而内置的
+ *    pi 终端识别规则只有一条 working_literal（匹配 "Working..."），没有任何 blocked
+ *    规则 —— 没有这个桥，ask_user_question 期间 pane 一直显示 working。
+ *    信号来源是 pi core 的 `ui_prompt_start` / `ui_prompt_end`（runner 统一包装
+ *    select/confirm/input/editor/custom，只在外层提示触发），所以覆盖所有阻塞弹窗；
+ *    `custom` 不带 title，额外借 `rpiv:ask-user:prompt` 的问题内容补 label。
+ *    herdr 的 blockedCount 是计数式的：切 label 前必须先发 `{active:false}` 降自己那
+ *    一份再发 `{active:true}`。本扩展严格配对 raise/lower，只占一个计数。
+ *
+ * 2) macOS 桌面横幅：herdr 自己的弹窗正文固定为「工作区 · 编号 · tab 名」，不含 pane
+ *    与问题原文，且按 tab 粒度抑制通知（同 tab 多 pane 会一起静音）。所以横幅自己发：
+ *    标题 = `herdr · <pane> · <本轮任务>`，正文 = 问题原文 / 完成用时。herdr 侧
+ *    ui.toast.delivery 保持 off，避免同一状态弹两份。
+ */
+
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** herdr 集成的入站事件通道。 */
+const HERDR_BLOCKED_EVENT = "herdr:blocked";
+/** @juicesharp/rpiv-ask-user-question 的公开事件通道。 */
+const ASK_USER_PROMPT_EVENT = "rpiv:ask-user:prompt";
+
+const PANE_ID = process.env.HERDR_PANE_ID ?? "";
+const MAX_LABEL_CHARS = 60;
+const MAX_TASK_CHARS = 24;
+const MAX_BODY_CHARS = 120;
+const TIMEOUT_MS = 5000;
+
+/** 各类交互提示的中文动词；未知类型回落到「等待用户输入」。 */
+const KIND_VERBS: Record<string, string> = {
+	select: "等待选择",
+	confirm: "等待确认",
+	input: "等待输入",
+	editor: "等待编辑",
+	custom: "等待回答",
+};
+
+/** terminal-notifier 支持 -group，同一 pane 的旧横幅会被新横幅替换；osascript 没有。 */
+const TERMINAL_NOTIFIER = [
+	"/opt/homebrew/bin/terminal-notifier",
+	"/usr/local/bin/terminal-notifier",
+	join(
+		homedir(),
+		".pi/agent/npm/node_modules/node-notifier/vendor/mac.noindex/terminal-notifier.app/Contents/MacOS/terminal-notifier",
+	),
+].find((path) => existsSync(path));
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function truncate(text: string, max: number): string {
+	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/** 折叠空白：AppleScript 字符串是一行，换行会把正文截断。 */
+function flatten(text: string): string {
+	return text.replace(/\s+/g, " ").trim();
+}
+
+function applescript(value: string): string {
+	return `"${flatten(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function notify(title: string, body: string): void {
+	if (process.platform !== "darwin") {
+		return;
+	}
+	const [command, args] = TERMINAL_NOTIFIER
+		? [
+				TERMINAL_NOTIFIER,
+				["-title", title, "-message", body, "-group", `herdr-${PANE_ID}`],
+			]
+		: ["osascript", ["-e", `display notification ${applescript(body)} with title ${applescript(title)}`]];
+	// 纯提示层，尽力而为：失败/超时都不该影响 pi 本体。
+	execFile(command, args, { timeout: TIMEOUT_MS }, () => {});
+}
+
+/** 取第一条问题的 header（短）与原文（长）。 */
+function readQuestion(data: unknown): { header?: string; question?: string } | undefined {
+	if (!isRecord(data) || !Array.isArray(data.questions)) {
+		return undefined;
+	}
+	const first = data.questions.find(isRecord);
+	if (!first) {
+		return undefined;
+	}
+	const header = typeof first.header === "string" ? flatten(first.header) : "";
+	const question = typeof first.question === "string" ? flatten(first.question) : "";
+	if (!header && !question) {
+		return undefined;
+	}
+	return { header: header || undefined, question: question || undefined };
+}
+
+export default function (pi: ExtensionAPI) {
+	// 与 herdr 集成保持一致：不在 herdr 集成环境里就完全静默。
+	if (process.env.HERDR_ENV !== "1" || !PANE_ID) {
+		return;
+	}
+
+	let rootSession = false;
+	let raised = false;
+	let raisedLabel: string | undefined;
+	let askUser: { header?: string; question?: string } | undefined;
+	let task: string | undefined;
+	let startedAt = 0;
+
+	function bannerTitle(): string {
+		return task ? `herdr · ${PANE_ID} · ${task}` : `herdr · ${PANE_ID}`;
+	}
+
+	function lower(): void {
+		if (!raised) return;
+		raised = false;
+		raisedLabel = undefined;
+		pi.events.emit(HERDR_BLOCKED_EVENT, { active: false });
+	}
+
+	function raise(kind: string, detail: string | undefined, bannerText?: string): void {
+		const verb = KIND_VERBS[kind] ?? "等待用户输入";
+		const label = detail ? `${verb}：${detail}` : "等待用户输入";
+		if (raised && raisedLabel === label) return;
+		lower(); // 先降自己那一份再抬高，保证 label 切换时计数不残留
+		raised = true;
+		raisedLabel = label;
+		pi.events.emit(HERDR_BLOCKED_EVENT, { active: true, label });
+		const body = bannerText ?? detail;
+		notify(bannerTitle(), body ? `${verb}：${truncate(body, MAX_BODY_CHARS)}` : verb);
+	}
+
+	pi.events.on(ASK_USER_PROMPT_EVENT, (data) => {
+		askUser = readQuestion(data);
+	});
+
+	pi.on("before_agent_start", (event) => {
+		const line = flatten(event.prompt ?? "");
+		task = line ? truncate(line, MAX_TASK_CHARS) : undefined;
+		startedAt = Date.now();
+	});
+
+	pi.on("ui_prompt_start", (event) => {
+		if (!rootSession) return;
+		if (event.kind === "custom") {
+			const detail = askUser?.header ?? askUser?.question;
+			raise("custom", detail ? truncate(detail, MAX_LABEL_CHARS) : undefined, askUser?.question);
+			return;
+		}
+		raise(event.kind, event.title);
+	});
+
+	pi.on("ui_prompt_end", () => {
+		askUser = undefined;
+		if (!rootSession) return;
+		lower();
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		if (!rootSession || ctx?.isIdle?.() !== true) return;
+		const seconds = startedAt ? Math.round((Date.now() - startedAt) / 1000) : undefined;
+		notify(bannerTitle(), seconds === undefined ? "完成" : `完成 · 用时 ${seconds}s`);
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		// 与 herdr 集成同一门槛：RPC/print 没有可展示的 PTY；
+		// reload 会同时重载集成与本扩展，两侧计数一起归零。
+		if (ctx?.mode !== "tui") return;
+		rootSession = true;
+		raised = false;
+		raisedLabel = undefined;
+		askUser = undefined;
+		startedAt = 0;
+	});
+
+	pi.on("session_shutdown", () => {
+		lower();
+		rootSession = false;
+		askUser = undefined;
+	});
+}

package/extensions/tab-task-label.ts

@@ -0,0 +1,91 @@
+/**
+ * tab-task-label
+ *
+ * 让 herdr 的完成/阻塞弹窗带上「这一轮在做什么」。
+ *
+ * 背景：herdr 0.8.2 的 agent 通知内容固定为
+ *   title = "<agent> finished" / "<agent> needs attention"
+ *   body  = "<工作区名> · <工作区编号> · <tab 名>"
+ * 实测结论（见 packages/herdr/README.md）：pane metadata（--title / --display-agent /
+ * --state-label）不会进入弹窗，弹窗里唯一可定制的一段就是 tab 名。所以这里在每轮
+ * 用户提问时把 tab 重命名为该轮任务摘要（提问首行、折叠空白、截断），这样无论是完成
+ * 还是阻塞待回答，弹窗正文都会带上任务信息。
+ *
+ * 取舍：会覆盖用户自己起的 tab 名（herdr 没有「临时显示名」这类旁路字段）。会话正常
+ * 退出（reason=quit）时，若 tab 名仍是我们写的那一份就还原成原名字；用户中途手动改过
+ * 则不动。同一 tab 多个 pi 会话会互相覆盖，以最后提问者为准。
+ */
+
+import { execFile } from "node:child_process";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const HERDR_BIN = process.env.HERDR_BIN_PATH || "herdr";
+const TAB_ID = process.env.HERDR_TAB_ID ?? "";
+const MAX_LABEL_CHARS = 40;
+const CLI_TIMEOUT_MS = 5000;
+
+function run(args: string[]): Promise<string> {
+	return new Promise((resolve, reject) => {
+		execFile(HERDR_BIN, args, { timeout: CLI_TIMEOUT_MS }, (err, stdout) => {
+			if (err) reject(err);
+			else resolve(stdout);
+		});
+	});
+}
+
+/** 读本 pane 所在 tab 当前的显示名。 */
+async function currentLabel(): Promise<string | undefined> {
+	const out = await run(["tab", "list"]);
+	const parsed = JSON.parse(out) as {
+		result?: { tabs?: Array<{ tab_id?: string; label?: string }> };
+	};
+	const tab = parsed.result?.tabs?.find((t) => t.tab_id === TAB_ID);
+	return tab?.label;
+}
+
+/** 提问首行 + 折叠空白 + 截断，作为 tab 名。 */
+function summarize(prompt: string): string {
+	const line = prompt.replace(/\s+/g, " ").trim();
+	return line.length > MAX_LABEL_CHARS ? `${line.slice(0, MAX_LABEL_CHARS - 1)}…` : line;
+}
+
+export default function (pi: ExtensionAPI) {
+	// 与 herdr 集成保持一致：不在 herdr 集成环境里就完全静默。
+	if (process.env.HERDR_ENV !== "1" || !TAB_ID) {
+		return;
+	}
+
+	let originalLabel: string | undefined;
+	let originalCaptured = false;
+	let written: string | undefined;
+
+	pi.on("before_agent_start", (event) => {
+		const label = summarize(event.prompt ?? "");
+		if (!label || label === written) return;
+		// 纯展示层，尽力而为且不阻塞 agent 启动：CLI 失败/超时都不该影响 pi 本体。
+		void (async () => {
+			try {
+				if (!originalCaptured) {
+					originalLabel = await currentLabel();
+					originalCaptured = true;
+				}
+				await run(["tab", "rename", TAB_ID, label]);
+				written = label;
+			} catch {
+				// 忽略：herdr CLI 不可用、socket 断开、tab 已关闭等
+			}
+		})();
+	});
+
+	pi.on("session_shutdown", async (event) => {
+		if (event.reason !== "quit" || !written || !originalLabel) return;
+		try {
+			// 用户在会话期间手动改过 tab 名，就不覆盖他的。
+			if ((await currentLabel()) !== written) return;
+			await run(["tab", "rename", TAB_ID, originalLabel]);
+			written = undefined;
+		} catch {
+			// 忽略
+		}
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muzi3/herdr",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Herdr for pi: the herdr operate skill (control Herdr from inside a pane), the herdr-guide skill (teach a human to set up and troubleshoot Herdr), and the herdr-agent-state extension (report agent state to Herdr).",
   "keywords": [
     "pi-package",
@@ -21,7 +21,8 @@
   "pi": {
     "extensions": [
       "./extensions/index.ts",
-      "./extensions/pi-hot-restart.ts"
+      "./extensions/pi-hot-restart.ts",
+      "./extensions/session-notify.ts"
     ],
     "skills": [
       "./skills"