@muzi3/herdr 0.1.3 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muzi3/herdr",
-  "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).",
+  "version": "0.2.0",
+  "description": "Herdr for pi: three independent extensions (agent + blocked state reporting, /pi-hot-restart, and the herdr_layout / herdr_pane / herdr_agent pane control tools forked from @ogulcancelik/pi-herdr) plus the herdr-guide skill.",
   "keywords": [
     "pi-package",
     "pi",
@@ -15,22 +15,29 @@
     "troubleshooting",
     "agent-state",
     "pane",
-    "integration"
+    "pane-control",
+    "layout",
+    "fork"
   ],
-  "license": "Apache-2.0",
+  "license": "Apache-2.0 AND MIT",
+  "type": "module",
   "pi": {
     "extensions": [
-      "./extensions/index.ts",
-      "./extensions/pi-hot-restart.ts",
-      "./extensions/session-notify.ts"
+      "./extensions/herdr-agent-state/index.ts",
+      "./extensions/pane-agent-tools/index.ts",
+      "./extensions/pi-hot-restart/index.ts"
     ],
     "skills": [
       "./skills"
     ]
   },
+  "scripts": {
+    "test": "node --test tests/"
+  },
   "files": [
     "extensions",
-    "skills"
+    "skills",
+    "LICENSE.MIT"
   ],
   "repository": {
     "type": "git",

package/extensions/index.ts

@@ -1,257 +0,0 @@
-// installed by herdr
-// managed by herdr; reinstalling or updating the integration overwrites this file.
-// add custom hooks/plugins beside this file instead of editing it.
-// HERDR_INTEGRATION_ID=pi
-// HERDR_INTEGRATION_VERSION=8
-// @ts-nocheck
-
-import net from "node:net";
-
-const HERDR_ENV = process.env.HERDR_ENV;
-const socketPath = process.env.HERDR_SOCKET_PATH;
-const socketEndpoint =
-  process.platform === "win32" && socketPath ? `\\\\.\\pipe\\${socketPath}` : socketPath;
-const paneId = process.env.HERDR_PANE_ID;
-const source = "herdr:pi";
-
-function enabled() {
-  return HERDR_ENV === "1" && !!socketPath && !!paneId;
-}
-
-function sendRequestAttempt(request: unknown, timeoutMs: number): Promise<boolean> {
-  if (!enabled()) {
-    return Promise.resolve(true);
-  }
-
-  return new Promise((resolve) => {
-    let done = false;
-    let timeout: ReturnType<typeof setTimeout> | undefined;
-    const finish = (delivered: boolean) => {
-      if (done) return;
-      done = true;
-      if (timeout) {
-        clearTimeout(timeout);
-      }
-      socket.destroy();
-      resolve(delivered);
-    };
-
-    const socket = net.createConnection(socketEndpoint!);
-    socket.on("error", () => finish(false));
-    socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
-    socket.on("data", () => finish(true));
-    socket.on("end", () => finish(false));
-    timeout = setTimeout(() => finish(false), timeoutMs);
-    timeout.unref?.();
-  });
-}
-
-async function sendRequest(request: unknown): Promise<void> {
-  if (await sendRequestAttempt(request, 500)) {
-    return;
-  }
-  await sendRequestAttempt(request, 1500);
-}
-
-type AgentState = "working" | "blocked" | "idle";
-
-type QueuedState = {
-  state: AgentState;
-  message?: string;
-  seq: number;
-};
-
-let reportSeq = Date.now() * 1000;
-let currentAgentSessionId: string | undefined;
-let currentAgentSessionPath: string | undefined;
-
-function nextReportSeq(): number {
-  reportSeq += 1;
-  return reportSeq;
-}
-
-function updateSessionRef(ctx: any): void {
-  try {
-    const file = ctx?.sessionManager?.getSessionFile?.();
-    currentAgentSessionPath =
-      typeof file === "string" && file.startsWith("/") ? file : undefined;
-  } catch {
-    currentAgentSessionPath = undefined;
-  }
-
-  try {
-    const id = ctx?.sessionManager?.getSessionId?.();
-    currentAgentSessionId = typeof id === "string" && id.length > 0 ? id : undefined;
-  } catch {
-    currentAgentSessionId = undefined;
-  }
-}
-
-function withSessionRef(params: Record<string, unknown>): Record<string, unknown> {
-  if (currentAgentSessionPath) {
-    return { ...params, agent_session_path: currentAgentSessionPath };
-  }
-  if (currentAgentSessionId) {
-    return { ...params, agent_session_id: currentAgentSessionId };
-  }
-  return params;
-}
-
-function currentSessionRef(): Record<string, unknown> | undefined {
-  if (currentAgentSessionPath) {
-    return { agent_session_path: currentAgentSessionPath };
-  }
-  if (currentAgentSessionId) {
-    return { agent_session_id: currentAgentSessionId };
-  }
-  return undefined;
-}
-
-function reportSession(sessionStartSource?: string): Promise<void> {
-  const sessionRef = currentSessionRef();
-  if (!sessionRef) {
-    return Promise.resolve();
-  }
-
-  return sendRequest({
-    id: `${source}:session:${Date.now()}:${Math.random().toString(36).slice(2)}`,
-    method: "pane.report_agent_session",
-    params: {
-      pane_id: paneId,
-      source,
-      agent: "pi",
-      seq: nextReportSeq(),
-      session_start_source: sessionStartSource,
-      ...sessionRef,
-    },
-  });
-}
-
-function sendState(state: AgentState, message?: string, seq = nextReportSeq()): Promise<void> {
-  return sendRequest({
-    id: `${source}:${Date.now()}:${Math.random().toString(36).slice(2)}`,
-    method: "pane.report_agent",
-    params: withSessionRef({
-      pane_id: paneId,
-      source,
-      agent: "pi",
-      state,
-      message,
-      seq,
-    }),
-  });
-}
-
-let sendInFlight = false;
-let queuedState: QueuedState | undefined;
-
-function queueState(state: AgentState, message?: string): void {
-  queuedState = { state, message, seq: nextReportSeq() };
-  if (!sendInFlight) {
-    void drainStateQueue();
-  }
-}
-
-async function drainStateQueue(): Promise<void> {
-  if (sendInFlight) {
-    return;
-  }
-
-  sendInFlight = true;
-  try {
-    while (queuedState) {
-      const next = queuedState;
-      queuedState = undefined;
-      await sendState(next.state, next.message, next.seq);
-    }
-  } finally {
-    sendInFlight = false;
-    if (queuedState) {
-      void drainStateQueue();
-    }
-  }
-}
-
-export default function (pi) {
-  if (!enabled()) {
-    return;
-  }
-
-  let agentActive = false;
-  let blockedCount = 0;
-  let blockedMessage: string | undefined;
-  let lastState: AgentState | undefined;
-  let lastMessage: string | undefined;
-  let rootSession = false;
-
-  function desiredState() {
-    if (blockedCount > 0) {
-      return { state: "blocked" as const, message: blockedMessage };
-    }
-    if (agentActive) {
-      return { state: "working" as const, message: undefined };
-    }
-    return { state: "idle" as const, message: undefined };
-  }
-
-  function publishState(force = false) {
-    const next = desiredState();
-    if (!force && next.state === lastState && next.message === lastMessage) {
-      return;
-    }
-    lastState = next.state;
-    lastMessage = next.message;
-    queueState(next.state, next.message);
-  }
-
-  pi.events.on("herdr:blocked", (data) => {
-    if (!rootSession) {
-      return;
-    }
-    if (!data?.active) {
-      blockedCount = Math.max(0, blockedCount - 1);
-      if (blockedCount === 0) {
-        blockedMessage = undefined;
-      }
-      publishState();
-      return;
-    }
-
-    blockedCount += 1;
-    blockedMessage = data.label;
-    publishState();
-  });
-
-  pi.on("session_start", async (event, ctx) => {
-    // TUI only: RPC/JSON/print modes are headless (no PTY herdr can display),
-    // and RPC still reports hasUI=true, so mode is the reliable gate.
-    if (ctx?.mode !== "tui") {
-      return;
-    }
-    rootSession = true;
-    updateSessionRef(ctx);
-    await reportSession(event?.reason);
-    // A reload can replace this extension mid-run without emitting another agent_start.
-    agentActive = ctx?.isIdle?.() === false;
-    publishState(true);
-  });
-
-  pi.on("agent_start", (_event, ctx) => {
-    if (!rootSession) {
-      return;
-    }
-    updateSessionRef(ctx);
-    void reportSession();
-    agentActive = true;
-    publishState();
-  });
-
-  pi.on("agent_settled", (_event, ctx) => {
-    if (!rootSession || ctx?.isIdle?.() !== true) {
-      return;
-    }
-
-    agentActive = false;
-    publishState();
-  });
-}

package/extensions/session-notify.ts

@@ -1,190 +0,0 @@
-/**
- * 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

@@ -1,91 +0,0 @@
-/**
- * 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 {
-			// 忽略
-		}
-	});
-}