@muzi3/herdr 0.3.0 → 0.3.2

package/README.md

@@ -30,7 +30,7 @@ extensions/
 
 每个扩展目录的入口都叫 `index.ts`，与 pi 自己的目录式扩展约定一致：扩展目录内可以再放内部模块，`pi.extensions` 只指向入口，不会误加载旁支文件。
 
-`herdr-agent-state/index.ts` 的目录名与 herdr 集成注入的文件同名，对齐上游时可以直接对比。内容分两段：官方集成正文（一直到文件末尾之前）与之后的「本包新增」段落。本包对官方正文只有**一处**改动：官方 `export default` 开头插入一行 `registerBlockedReporting(pi);` —— 该 default export 就是本扩展的唯一入口，blocked 上报只能挂在那里。重新同步上游时（`HERDR_INTEGRATION_VERSION` 从 8 往上升）重取注入文件替换官方正文并补回那一行；`diff` 应只有三处新增、零删除，漏帖那一行会被 `tests/herdr-agent-state.test.ts` 拦下。
+`herdr-agent-state/index.ts` 的目录名与 herdr 集成注入的文件同名，对齐上游时可以直接对比。内容分两段：官方集成正文（一直到文件末尾之前）与之后的「本包新增」段落。本包对官方正文只有**一处**改动：官方 `export default` 开头插入一行 `registerBlockedReporting(pi);` —— 该 default export 就是本扩展的唯一入口，blocked 上报只能挂在那里。重新同步上游时（`HERDR_INTEGRATION_VERSION` 从 9 往上升）重取注入文件替换官方正文并补回那一行；`diff` 应只有三处新增、零删除，漏帖那一行会被 `tests/herdr-agent-state.test.ts` 拦下。
 
 ## 来源与许可
 

package/extensions/herdr-agent-state/index.ts

@@ -2,14 +2,14 @@
 // 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
+// HERDR_INTEGRATION_VERSION=9
 // @ts-nocheck
 //
 // ---------------------------------------------------------------------------
 // 以下为本包（@muzi3/herdr）的说明，不属于 herdr 官方正文：
 //
 // 1. 本文件上方内容是 herdr 官方 pi 集成正文的副本，保留是为了将来能直接与上游重新同步：
-//    上游 `HERDR_INTEGRATION_VERSION` 从当前的 8 往上升时，重取 `herdr integration install pi`
+//    上游 `HERDR_INTEGRATION_VERSION` 从当前的 9 往上升时，重取 `herdr integration install pi`
 //    注入的文件并替换本文件的官方段落即可（文件末尾的「本包新增」段落不受影响）。
 //    本包对官方段落只有**一处**改动：`export default` 开头插入一行
 //    `registerBlockedReporting(pi);`（带「本包新增」标记）。因为官方的 default export 就是本
@@ -27,6 +27,7 @@
 // ---------------------------------------------------------------------------
 
 import net from "node:net";
+import path from "node:path";
 
 const HERDR_ENV = process.env.HERDR_ENV;
 const socketPath = process.env.HERDR_SOCKET_PATH;
@@ -67,11 +68,11 @@ function sendRequestAttempt(request: unknown, timeoutMs: number): Promise<boolea
   });
 }
 
-async function sendRequest(request: unknown): Promise<void> {
+async function sendRequest(request: unknown): Promise<boolean> {
   if (await sendRequestAttempt(request, 500)) {
-    return;
+    return true;
   }
-  await sendRequestAttempt(request, 1500);
+  return sendRequestAttempt(request, 1500);
 }
 
 type AgentState = "working" | "blocked" | "idle";
@@ -95,7 +96,10 @@ function updateSessionRef(ctx: any): void {
   try {
     const file = ctx?.sessionManager?.getSessionFile?.();
     currentAgentSessionPath =
-      typeof file === "string" && file.startsWith("/") ? file : undefined;
+      typeof file === "string" &&
+      (path.posix.isAbsolute(file) || path.win32.isAbsolute(file))
+        ? file
+        : undefined;
   } catch {
     currentAgentSessionPath = undefined;
   }
@@ -165,6 +169,7 @@ function sendState(state: AgentState, message?: string, seq = nextReportSeq()):
 
 let sendInFlight = false;
 let queuedState: QueuedState | undefined;
+let retryTimer: ReturnType<typeof setTimeout> | undefined;
 
 function queueState(state: AgentState, message?: string): void {
   queuedState = { state, message, seq: nextReportSeq() };
@@ -173,6 +178,17 @@ function queueState(state: AgentState, message?: string): void {
   }
 }
 
+function scheduleStateRetry(): void {
+  if (retryTimer) {
+    return;
+  }
+  retryTimer = setTimeout(() => {
+    retryTimer = undefined;
+    void drainStateQueue();
+  }, 1000);
+  retryTimer.unref?.();
+}
+
 async function drainStateQueue(): Promise<void> {
   if (sendInFlight) {
     return;
@@ -183,11 +199,18 @@ async function drainStateQueue(): Promise<void> {
     while (queuedState) {
       const next = queuedState;
       queuedState = undefined;
-      await sendState(next.state, next.message, next.seq);
+      if (await sendState(next.state, next.message, next.seq)) {
+        continue;
+      }
+      if (!queuedState || queuedState.seq < next.seq) {
+        queuedState = next;
+      }
+      scheduleStateRetry();
+      break;
     }
   } finally {
     sendInFlight = false;
-    if (queuedState) {
+    if (queuedState && !retryTimer) {
       void drainStateQueue();
     }
   }

package/extensions/pane-agent-tools/index.ts

@@ -128,6 +128,19 @@ const ReadModeEnum = StringEnum(["digest", "raw"] as const, {
 	description: "默认 digest：压成「前段信号行 + 尾部」；要整段原文传 raw",
 });
 
+/**
+ * 八个工具共用的结构化结果：codemode 脚本拿它做过滤，模型仍看 content 里的渲染文本。
+ * 与 Envelope 同形，免得多出一套真值。
+ */
+const envelopeOutputSchema = Type.Object({
+	ok: Type.Boolean({ description: "这条 herdr 命令是否成功" }),
+	exitCode: Type.Number({ description: "退出码；-1 表示本地截止时间到期" }),
+	timedOut: Type.Optional(Type.Boolean({ description: "本地截止时间是否到期" })),
+	output: Type.String({ description: "正文：digest 压缩后的信号行 + 尾部，或 raw 全文" }),
+	note: Type.Optional(Type.String({ description: "判据提示，或失败时的说明" })),
+	via: Type.Optional(Type.String({ description: "实际走了 agent 还是 pane 视图" })),
+});
+
 const CreateKindEnum = StringEnum(["workspace", "tab", "pane"] as const, {
 	description: "建 workspace、建 tab，还是切一个兄弟 pane",
 });
@@ -367,7 +380,12 @@ function renderEnvelope(value: Envelope): string {
 }
 
 function envelopeResult(value: Envelope) {
-	return { content: [{ type: "text" as const, text: renderEnvelope(value) }], details: value };
+	return {
+		content: [{ type: "text" as const, text: renderEnvelope(value) }],
+		details: value,
+		// 声明了 outputSchema 的工具：脚本收结构化值，模型仍收上面的渲染文本。
+		structuredContent: value,
+	};
 }
 
 /** 自己拒绝的决定，发生在任何 herdr 调用之前。 */
@@ -546,6 +564,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "herdr_overview",
 		label: "Herdr Overview",
+		outputSchema: envelopeOutputSchema,
 		description:
 			"盘点：一次拿到自己的位置 + 全机 workspace 拓扑 + 全机 agent 状态（名称/状态/cwd/pane id）。管理其他 agent 的第一步几乎总是它 —— 先看有哪些 agent、谁在忙、谁空着。只读。",
 		promptSnippet: "一次看清 herdr 里有哪些 agent、谁在忙、各自在哪个 pane",
@@ -624,6 +643,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "herdr_read",
 		label: "Herdr Read",
+		outputSchema: envelopeOutputSchema,
 		description:
 			"读屏：看某个 pane（或它里面的 agent）当前输出。盯梢一个 agent 在干什么、卡在哪，用它。target 用完整限定 pane id（如 wC:p77）；scope=agent 走 agent 语义视图，pane 走裸终端视图。只读。默认 digest 模式：只回「前段命中的审批/报错行 + 尾部 30 行」，省上下文；要看整段传 mode=\"raw\"。",
 		promptSnippet: "读取某个 pane 或 agent 的当前输出（默认压缩成信号行 + 尾部）",
@@ -683,6 +703,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "herdr_wait",
 		label: "Herdr Wait",
+		outputSchema: envelopeOutputSchema,
 		description:
 			"等某个 agent 进入指定状态（默认 idle/done/blocked）。盯梢的关键原语：下发任务后等它落定。注意超时只表示「没观测到」，不是失败 —— 不要据此重发任务，先 herdr_read 看实际情况。",
 		promptSnippet: "等待某个 agent 进入 idle/done/blocked",
@@ -735,6 +756,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "herdr_prompt",
 		label: "Herdr Prompt",
+		outputSchema: envelopeOutputSchema,
 		description:
 			"给另一个 agent 下发一段 prompt（调度）。先试 agent prompt（语义路径）；若对方是自报状态的 dsh-tui，herdr 会回 agent_not_ready，此时自动回退成 pane run 直接键入。返回的 via 会说明走了哪条路。「已送出」不等于「已开始干活」—— 要确认请配 herdr_wait 或 herdr_read。",
 		promptSnippet: "给另一个 agent 下发任务（自动回退到直接键入）",
@@ -858,6 +880,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "herdr_run",
 		label: "Herdr Run",
+		outputSchema: envelopeOutputSchema,
 		description:
 			"在指定 pane 里跑一条命令（裸终端，原子下发：文本 + Enter）。用来在别的 pane 起服务、跑脚本。成功 = 退出 0 且 stdout 为空，别期待回显信封；要确认结果用 herdr_read 或 herdr_wait。",
 		promptSnippet: "在另一个 pane 里原子下发一条命令",
@@ -889,6 +912,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "herdr_create",
 		label: "Herdr Create",
+		outputSchema: envelopeOutputSchema,
 		description:
 			"开新位置：workspace / tab / 兄弟 pane。默认不动焦点（不加 --focus），避免把用户正在看的上下文切走。返回的新 pane id 才是后续操作要用的句柄。",
 		promptSnippet: "创建 workspace / tab / 兄弟 pane，并拿回新 pane id",
@@ -963,6 +987,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "herdr_agent_start",
 		label: "Herdr Agent Start",
+		outputSchema: envelopeOutputSchema,
 		description:
 			"在一个已经停在交互提示符的 shell pane 里启动 coding agent。它不创建 pane、不移动布局 —— 要新位置先用 herdr_create。注意 kind 列表里没有 dsh-tui（dsh-tui 靠自报被识别，不由 agent start 起出来）。",
 		promptSnippet: "在空闲 shell pane 里启动一个 coding agent",
@@ -1015,6 +1040,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "herdr_close",
 		label: "Herdr Close",
+		outputSchema: envelopeOutputSchema,
 		description:
 			"关 pane（会杀掉里面的进程）。默认 dryRun=true 只预览目标、不真关；确认目标无误后再显式传 dryRun=false。工具拒绝关闭自己所在的 pane，也绝不要关不是你创建的 pane。",
 		promptSnippet: "预览或关闭一个 pane（默认只预览）",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muzi3/herdr",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Herdr for pi: three independent extensions (agent + blocked state reporting, /pi-hot-restart, and the herdr_overview / herdr_read / herdr_wait / herdr_prompt / herdr_run / herdr_create / herdr_agent_start / herdr_close manager tools aligned with dsh's herdr-tools plugin) plus the herdr-guide skill.",
   "keywords": [
     "pi-package",