@muzi3/herdr 0.3.0 → 0.3.1

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.1",
   "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",