@muzi3/herdr 0.2.0 → 0.2.1

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

@@ -13,6 +13,16 @@
  * 经 parseHerdrError 抛出，所以真实失败照旧报错，只有那个不成立的“stdout 必须非空”
  * 约束被去掉。`pane close` / `pane wait-output` / `agent send-keys` 确实返回 JSON
  * envelope，保持 execHerdrJson。回归测试见 tests/pane-agent-tools.test.ts。
+ *
+ * 状态检测加固：
+ *   - herdr 的 error.code 会随错误一起抛出（herdrError/herdrErrorCode）。timeout 与
+ *     agent_prompt_stalled 表示“没观测到”，不是失败：前者降级为 matched:false +
+ *     pane 尾部输出，后者降级为 submitted:true + stalled:true，避免调用方误判为命令
+ *     失败，或因为一条假错误把 prompt 重复下发一遍。
+ *   - wait_output 的 match 未显式指定 regex 时，含正则元字符的 pattern 按正则处理。
+ *     字面量语义下 `a|b` / `log \$` 永远不可能命中，只会白等满 timeout。
+ *   - 命中行包含本进程刚下发的命令文本时标 echoedInput —— 那多半是命令回显行，而不是
+ *     命令产生的输出（回显在命令还没跑完时就已经存在）。
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -91,6 +101,12 @@ interface HerdrJsonEnvelope {
 	};
 }
 
+interface WaitOutputResult {
+	pane_id: string;
+	matched_line: string;
+	read?: { text?: string };
+}
+
 const StatusEnum = StringEnum(["idle", "working", "blocked", "done", "unknown"] as const, {
 	description: "Agent lifecycle state",
 });
@@ -134,17 +150,56 @@ const AgentKindEnum = StringEnum(
 	{ description: "Supported coding agent kind and canonical executable" },
 );
 
-function parseHerdrError(output: string): string | null {
+/**
+ * 字面量里带这些字符的 pattern（`a|b`、`log \$`）在字面量语义下永远不可能命中，
+ * 只会白等满 timeout，所以 wait_output 在未显式指定 regex 时按正则解释它们。
+ */
+const REGEX_METACHARS = /[|()[\]{}^$*+?\\]/;
+
+interface HerdrErrorDetail {
+	code?: string;
+	message: string;
+}
+
+function parseHerdrError(output: string): HerdrErrorDetail | null {
 	const trimmed = output.trim();
 	if (!trimmed) return null;
 	try {
 		const value = JSON.parse(trimmed) as HerdrJsonEnvelope;
-		return value.error?.message || value.error?.code || trimmed;
+		const message = value.error?.message || value.error?.code;
+		if (message) return { code: value.error?.code, message };
+		return { message: trimmed };
 	} catch {
-		return trimmed;
+		return { message: trimmed };
 	}
 }
 
+/** 构造带 herdr code 的错误，让调用方能区分“检测未达成”和真正的失败。 */
+function herdrError(message: string, code?: string): Error {
+	const error = new Error(message) as Error & { herdrCode?: string };
+	if (code) error.herdrCode = code;
+	return error;
+}
+
+function herdrErrorCode(error: unknown): string | undefined {
+	return error instanceof Error ? (error as Error & { herdrCode?: string }).herdrCode : undefined;
+}
+
+/**
+ * herdr 的 timeout / agent_prompt_stalled 表示“没观测到”，不是失败。
+ * code 是主要判据，文案匹配作为兜底（个别版本可能不带结构化 code）。
+ */
+function isHerdrTimeout(error: unknown): boolean {
+	return herdrErrorCode(error) === "timeout" || (error instanceof Error && /timed out waiting for/i.test(error.message));
+}
+
+function isPromptStalled(error: unknown): boolean {
+	return (
+		herdrErrorCode(error) === "agent_prompt_stalled" ||
+		(error instanceof Error && /no observed state change/i.test(error.message))
+	);
+}
+
 function isAbortError(error: unknown, signal?: AbortSignal): boolean {
 	return signal?.aborted === true || (error instanceof Error && error.message === "Aborted");
 }
@@ -274,15 +329,23 @@ function renderToolResult(result: any, options: { expanded: boolean; isPartial:
 export default function (pi: ExtensionAPI) {
 	if (process.env.HERDR_ENV !== "1" || !process.env.HERDR_PANE_ID) return;
 
+	/**
+	 * 本进程最近一次下发到某个 pane 的文本（`run` 的命令、`send_text` 的字面量）。
+	 * wait_output 用它识别“命中行其实就是刚敲下去的命令回显”，而不是命令产生的输出。
+	 */
+	const lastSubmitted = new Map<string, string>();
+
 	async function execHerdr(args: string[], signal?: AbortSignal) {
 		const result = await pi.exec("herdr", args, { signal });
 		if (signal?.aborted || result.killed) throw new Error("Aborted");
 		if (result.code !== 0) {
-			const message =
-				parseHerdrError(result.stderr) ||
-				parseHerdrError(result.stdout) ||
-				`herdr ${args.join(" ")} failed with exit code ${result.code}`;
-			throw new Error(message);
+			// herdr 把结构化错误写在 stderr（退出码 1）。带上 code，调用方才能区分
+			// timeout / agent_prompt_stalled 这类“没观测到”和真正的失败。
+			const detail = parseHerdrError(result.stderr) || parseHerdrError(result.stdout);
+			throw herdrError(
+				detail?.message || `herdr ${args.join(" ")} failed with exit code ${result.code}`,
+				detail?.code,
+			);
 		}
 		return result;
 	}
@@ -297,7 +360,9 @@ export default function (pi: ExtensionAPI) {
 		} catch {
 			throw new Error(`Failed to parse JSON from herdr ${args.join(" ")}`);
 		}
-		if (value.error) throw new Error(value.error.message || value.error.code || `herdr ${args.join(" ")} failed`);
+		if (value.error) {
+			throw herdrError(value.error.message || value.error.code || `herdr ${args.join(" ")} failed`, value.error.code);
+		}
 		return value as T;
 	}
 
@@ -305,6 +370,25 @@ export default function (pi: ExtensionAPI) {
 		return (await execHerdr(args, signal)).stdout;
 	}
 
+	/**
+	 * 读一次 pane 快照。失败时返回 null —— 读快照失败不能让 wait_output 本身失败。
+	 */
+	async function readPaneSnapshot(
+		paneId: string,
+		source: WaitOutputSource,
+		lines: number | undefined,
+		signal?: AbortSignal,
+	): Promise<string | null> {
+		const args = ["pane", "read", paneId, "--source", source];
+		if (lines != null) args.push("--lines", String(lines));
+		try {
+			return await execHerdrText(args, signal);
+		} catch (error) {
+			if (isAbortError(error, signal)) throw error;
+			return null;
+		}
+	}
+
 	async function getCurrentPane(signal?: AbortSignal): Promise<PaneInfo> {
 		const response = await execHerdrJson<{ result: { pane: PaneInfo } }>(["pane", "current", "--current"], signal);
 		return response.result.pane;
@@ -490,6 +574,9 @@ export default function (pi: ExtensionAPI) {
 		promptGuidelines: [
 			"Use herdr_pane for ordinary commands and raw terminal control; use herdr_agent for coding-agent prompts, lifecycle waits, reads, and interactive keys.",
 			"Use herdr_pane wait_output for tests, servers, builds, and watchers. It searches existing output immediately; use recent-unwrapped for logs and transcripts.",
+			"wait_output reports a timeout as matched:false with the pane tail instead of raising an error: a timeout means the pattern never appeared, not that the command failed.",
+			"Pick a wait_output pattern that only appears in the command output. Patterns that also occur in the command you sent (script names, function names, marker constants) match the echoed input line and can report success before the command produces anything; echoedInput flags such a hit.",
+			"Never use a shell prompt (❯, $, \\$) as a wait_output pattern; it is always present and therefore meaningless.",
 			"Do not close a Herdr pane you did not create unless the user explicitly asks. herdr_pane always refuses to close the pane running the current pi process.",
 		],
 		parameters: Type.Object({
@@ -502,8 +589,15 @@ export default function (pi: ExtensionAPI) {
 			keys: Type.Optional(
 				Type.Array(Type.String(), { description: "Logical terminal keys for send_keys, such as esc, enter, up, or ctrl+c" }),
 			),
-			match: Type.Optional(Type.String({ description: "Literal substring or Rust regular expression for wait_output" })),
-			regex: Type.Optional(Type.Boolean({ description: "Treat match as a Rust regular expression" })),
+			match: Type.Optional(
+				Type.String({
+					description:
+						"Pattern for wait_output. Patterns containing regex metacharacters (| ( ) [ ] { } ^ $ * + ? \\) are treated as Rust regular expressions unless regex is explicitly false",
+				}),
+			),
+			regex: Type.Optional(
+				Type.Boolean({ description: "Force match to be a literal string (false) or a Rust regular expression (true)" }),
+			),
 			source: Type.Optional(ReadSourceEnum),
 			lines: Type.Optional(Type.Integer({ minimum: 1, description: "Rendered terminal rows to read or search" })),
 			format: Type.Optional(OutputFormatEnum),
@@ -523,6 +617,7 @@ export default function (pi: ExtensionAPI) {
 					if (!params.command) throw new Error("'command' is required for run");
 					// pane run/send-text/send-keys report success with empty stdout, so only the exit code is meaningful.
 					await execHerdr(["pane", "run", params.pane, params.command], signal);
+					lastSubmitted.set(params.pane, params.command);
 					return {
 						content: [{ type: "text", text: `Submitted command to pane ${params.pane}` }],
 						details: { action: "run", pane: params.pane, command: params.command },
@@ -542,26 +637,92 @@ export default function (pi: ExtensionAPI) {
 					if (!params.match) throw new Error("'match' is required for wait_output");
 					if (params.source === "detection") throw new Error("wait_output does not support the detection source; use read");
 					const startedAt = Date.now();
+					const source: WaitOutputSource = (params.source as WaitOutputSource) || "recent-unwrapped";
+					// 未显式指定 regex 时，含正则元字符的 pattern 按正则解释：字面量语义下
+					// `a|b` / `log \$` 永远不可能命中，只会白等满 timeout。
+					const matchMode: "literal" | "regex" =
+						params.regex === true
+							? "regex"
+							: params.regex === false
+								? "literal"
+								: REGEX_METACHARS.test(params.match)
+									? "regex"
+									: "literal";
+					const notes: string[] = [];
+					if (matchMode === "literal" && REGEX_METACHARS.test(params.match)) {
+						notes.push(
+							`注意：${JSON.stringify(params.match)} 含正则元字符但按字面量匹配，很可能永远无法命中；需要正则请设 regex: true。`,
+						);
+					}
 					onUpdate?.({
 						content: [{ type: "text", text: `Waiting for output in ${params.pane}...` }],
 						details: { action: "wait_output", pane: params.pane, waiting: true },
 					});
-					const args = ["pane", "wait-output", params.pane, params.regex ? "--regex" : "--match", params.match];
-					if (params.source) args.push("--source", params.source as WaitOutputSource);
+					const args = ["pane", "wait-output", params.pane, matchMode === "regex" ? "--regex" : "--match", params.match];
+					args.push("--source", source);
 					if (params.lines != null) args.push("--lines", String(params.lines));
 					if (params.timeout != null) args.push("--timeout", String(params.timeout));
 					if (params.raw) args.push("--raw");
-					const response = await execHerdrJson<{
-						result: { pane_id: string; matched_line: string; read?: { text?: string } };
-					}>(args, signal);
+					let response: { result: WaitOutputResult } | null;
+					try {
+						response = await execHerdrJson<{ result: WaitOutputResult }>(args, signal);
+					} catch (error) {
+						if (!isHerdrTimeout(error)) throw error;
+						response = null;
+					}
+					if (response === null) {
+						// 超时是“没观测到”，不是失败：返回观测事实（含 pane 尾部输出）让调用方自己判断。
+						const tail = await readPaneSnapshot(params.pane, source, params.lines, signal);
+						const waitedMs = Date.now() - startedAt;
+						return {
+							content: [
+								{
+									type: "text",
+									text: [
+										`未匹配：${JSON.stringify(params.match)}（模式=${matchMode}, source=${source}）在 ${waitedMs}ms 内未出现。`,
+										"这既不表示命令失败，也不表示命令完成，只表示这个 pattern 没有出现。",
+										...notes,
+										tail ? `当前 pane 尾部输出：\n${formatOutput(tail)}` : "（未能读取 pane 尾部输出）",
+									].join("\n"),
+								},
+							],
+							details: {
+								action: "wait_output",
+								pane: params.pane,
+								matched: false,
+								waitedMs,
+								matchMode,
+								source,
+								tail,
+							},
+						};
+					}
 					const matched = response.result;
 					const output = matched.read?.text || matched.matched_line;
+					// 命中行可能来自刚下发的命令回显（`❯ <命令>`）而不是命令产生的输出，
+					// 回显在命令还没跑完时就已经存在。本进程自己记录的下发内容是最可靠的事实依据。
+					const submitted = lastSubmitted.get(params.pane);
+					const echoedInput = !!submitted && matched.matched_line.includes(submitted);
+					if (echoedInput) {
+						notes.push(
+							"注意：命中的是刚下发的命令回显行（❯ 后面那段），不是命令产生的输出；命令可能还没跑完。要等真正的输出，请改用只会出现在输出里的 pattern。",
+						);
+					}
 					return {
-						content: [{ type: "text", text: `Matched: ${matched.matched_line}\n\n${formatOutput(output)}` }],
+						content: [
+							{
+								type: "text",
+								text: [...notes, `Matched: ${matched.matched_line}`, "", formatOutput(output)].join("\n"),
+							},
+						],
 						details: {
 							action: "wait_output",
 							pane: params.pane,
+							matched: true,
 							matchedLine: matched.matched_line,
+							matchMode,
+							source,
+							echoedInput,
 							elapsedMs: Date.now() - startedAt,
 						},
 					};
@@ -569,6 +730,7 @@ export default function (pi: ExtensionAPI) {
 				case "send_text": {
 					if (!params.text) throw new Error("'text' is required for send_text");
 					await execHerdr(["pane", "send-text", params.pane, params.text], signal);
+					lastSubmitted.set(params.pane, params.text);
 					return {
 						content: [{ type: "text", text: `Sent literal text to pane ${params.pane}` }],
 						details: { action: "send_text", pane: params.pane },
@@ -691,7 +853,37 @@ export default function (pi: ExtensionAPI) {
 							details: { action: "prompt", target: params.target, waiting: true },
 						});
 					}
-					const response = await execHerdrJson<{ result: { agent: AgentInfo } }>(args, signal);
+					let response: { result: { agent: AgentInfo } } | null;
+					let stalledState: string | undefined;
+					try {
+						response = await execHerdrJson<{ result: { agent: AgentInfo } }>(args, signal);
+					} catch (error) {
+						if (!isPromptStalled(error)) throw error;
+						stalledState = /status is (\w+)/.exec(error instanceof Error ? error.message : "")?.[1];
+						response = null;
+					}
+					if (response === null) {
+						// herdr 在 submission accepted 后要求 5s 内观测到 working/blocked，观测不到就报
+						// agent_prompt_stalled —— 这是启发式，prompt 已经下发，不能当成“下发失败”。
+						return {
+							content: [
+								{
+									type: "text",
+									text:
+										`Prompt 已下发到 ${params.target}（submission accepted），但 5s 内未观测到进入 working/blocked` +
+										(stalledState ? `（当前状态 ${stalledState}）` : "") +
+										"。\n不要再下发一次；用 herdr_agent read 确认它是否已开始工作。",
+								},
+							],
+							details: {
+								action: "prompt",
+								target: params.target,
+								submitted: true,
+								stalled: true,
+								observedState: stalledState,
+							},
+						};
+					}
 					return {
 						content: [{ type: "text", text: `${shouldWait ? "Prompt settled" : "Prompt submitted"}: ${summarizeAgent(response.result.agent)}` }],
 						details: { action: "prompt", agent: response.result.agent },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muzi3/herdr",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",