@zhushanwen/pi-subagent-workflow 8.3.0 → 8.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.3.0",
+  "version": "8.4.0",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -47,9 +47,9 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "yaml": "^2.9.0",
-    "@xyz-agent/extension-protocol": "0.6.0",
     "@xyz-agent/session-delivery": "0.2.0",
     "@zhushanwen/pi-extension-logger": "0.3.0",
+    "@xyz-agent/extension-protocol": "0.6.0",
     "@zhushanwen/pi-file-lock": "0.1.2"
   },
   "peerDependencies": {

package/src/interface/command-actions.ts

@@ -8,10 +8,15 @@
  * 设计为纯函数（无 ctx / service 依赖），便于独立单测，handler 只做薄分发。
  */
 
-/** /subagents RPC action 判别联合。 */
+/** /subagents RPC action 判别联合。message/start 为 GUI 定向消息通道（设计 §3.3.3，
+ *  仅 RPC 分支消费；missing-args 携带 missing 字段供 handler 输出指明缺什么的 usage）。 */
 export type SubagentRpcAction =
   | { action: "cancel"; recordId: string }
   | { action: "cancel-missing-id" }
+  | { action: "message"; recordId: string; text: string }
+  | { action: "message-missing-args"; missing: "recordId" | "text" }
+  | { action: "start"; slug: string; task: string }
+  | { action: "start-missing-args"; missing: "slug" | "task" }
   | { action: "noop" };
 
 /** /workflows RPC action 判别联合。 */
@@ -46,25 +51,84 @@ function isRemovedLifecycleVerb(verb: string): verb is "pause" | "resume" {
   return REMOVED_LIFECYCLE_VERBS.has(verb as "pause" | "resume");
 }
 
+/**
+ * 还原转义协议（设计 §3.3.3 / 探针 P3）：字面 `\n`（反斜杠 + n 两字符）→ 真实换行、
+ * 字面 `\\`（两反斜杠）→ 单反斜杠。
+ *
+ * 与 runtime encodeDirectiveText（session-service.ts）互逆：composer 多行输入在
+ * client.prompt 传输前把真实换行编码为字面 \n、原生反斜杠编码为 \\（命令保持单行），
+ * extension 解析侧在此还原。反斜杠转义必须与换行转义在**单次遍历**里成对处理
+ * （交替分支 `\\\\|\\n`，两反斜杠优先匹配）——若只处理 \n，原文里的字面反斜杠+n
+ * （如路径 `C:\new`）会被误解码为换行，往返歧义。
+ */
+function decodeNewlineEscapes(s: string): string {
+  return s.replace(/\\\\|\\n/g, (m) => (m === "\\\\" ? "\\" : "\n"));
+}
+
+/**
+ * 提取首个非空白 token 与其后剩余原文。
+ *
+ * 与 split(/\s+/) 不同：rest 保留 token 之后的全部原文（含空格/引号/换行转义），
+ * 供 message text / start task 的「剩余全量到字符串末尾」语义使用（设计 §3.3.3——
+ * pi 以首个空格拆命令名后 args 为其后全文，文本内的空格/引号必须原样保留）。
+ * rest 跳过 token 后的分隔空白（分隔符不属文本），但保留其后全部内容原样。
+ */
+function splitFirstToken(s: string): { token: string; rest: string } | null {
+  const head = s.trimStart();
+  if (!head) return null;
+  const idx = head.search(/\s/);
+  if (idx === -1) return { token: head, rest: "" };
+  return { token: head.slice(0, idx), rest: head.slice(idx + 1).trimStart() };
+}
+
 /**
  * 解析 /subagents RPC 命令字符串。
  *
  * 支持格式：
  * - `cancel <id>` → { action: "cancel", recordId }
  * - `cancel`（无 id）→ { action: "cancel-missing-id" }
+ * - `message <recordId> <text...>` → { action: "message", recordId, text }
+ *   text 为第二 token 后的剩余全量（含空格/引号原样；字面 \n 还原为换行、字面 \\ 还原为
+ *   反斜杠——composer 定向消息经此协议编码，与 runtime encodeDirectiveText 互逆，设计 §3.3.3）
+ * - `message`（缺 recordId 或 text 为空白）→ { action: "message-missing-args", missing }
+ * - `start <slug> <task...>` → { action: "start", slug, task }（task 同 text 转义协议）
+ * - `start`（缺 slug 或 task 为空白）→ { action: "start-missing-args", missing }
  * - 其他（空 / 未知 action / 无参）→ { action: "noop" }
  *
- * noop 表示 GUI 端无对应程序化操作（GUI 已在 CommandPopover 屏蔽 /subagents 入口，
- * 此分支仅兜底手动 prompt）。
+ * missing-args 携带 missing 字段（缺哪个参数），handler 据此输出可操作的 usage
+ * 错误（全局规则：错误信息指向恢复动作）。noop 表示 GUI 端无对应程序化操作（GUI
+ * 已在 CommandPopover 屏蔽 /subagents 入口，此分支仅兜底手动 prompt）。
  */
 export function parseSubagentRpcCommand(argsStr: string): SubagentRpcAction {
-  const args = argsStr.trim().split(/\s+/).filter(Boolean);
-  if (args.length === 0) return { action: "noop" };
+  const first = splitFirstToken(argsStr);
+  if (!first) return { action: "noop" };
 
-  const [verb, recordId] = args;
+  const { token: verb, rest } = first;
   if (verb === "cancel") {
-    if (!recordId) return { action: "cancel-missing-id" };
-    return { action: "cancel", recordId };
+    const idToken = splitFirstToken(rest);
+    if (!idToken) return { action: "cancel-missing-id" };
+    return { action: "cancel", recordId: idToken.token };
+  }
+  if (verb === "message" || verb === "start") {
+    // message 与 start 共用解析骨架，仅结果字段名不同（recordId/text vs slug/task）
+    const isMessage = verb === "message";
+    // 第二 token：message→recordId / start→slug；其后剩余全量（还原换行转义）为 text/task
+    const second = splitFirstToken(rest);
+    if (!second) {
+      return isMessage
+        ? { action: "message-missing-args", missing: "recordId" }
+        : { action: "start-missing-args", missing: "slug" };
+    }
+    // 先还原再判空：纯字面 \n 还原后是真实换行（whitespace），应在解析层拦截为缺参
+    const payload = decodeNewlineEscapes(second.rest);
+    if (!payload.trim()) {
+      return isMessage
+        ? { action: "message-missing-args", missing: "text" }
+        : { action: "start-missing-args", missing: "task" };
+    }
+    return isMessage
+      ? { action: "message", recordId: second.token, text: payload }
+      : { action: "start", slug: second.token, task: payload };
   }
   return { action: "noop" };
 }

package/src/interface/subagent-actions.ts

@@ -329,10 +329,13 @@ export interface MessageHandlerInput {
   interrupt?: boolean;
 }
 
-/** message 领域对象（adapter 包成 messageResponse）。 */
+/** message 领域对象（adapter 包成 messageResponse）。
+ *  slug 来自 record（GUI /subagents message 通道的留痕 details 需要，设计 §3.3.3），
+ *  避免调用方二次 getRecordForAction 查询。 */
 export type MessageHandlerResult = {
   kind: "message";
   subagentId: string;
+  slug: string;
   response: MessageResponse;
 };
 
@@ -393,7 +396,7 @@ export async function messageHandler(
       `Recovery: use action:'close' to clean up, then action:'start' a new subagent.`,
     );
   }
-  return { kind: "message", subagentId: id, response: { delivered: true } };
+  return { kind: "message", subagentId: id, slug: record.slug, response: { delivered: true } };
 }
 
 // ============================================================

package/src/interface/subagents.ts

@@ -3,16 +3,211 @@
 // /subagents 命令。薄壳——打开 list overlay（等同原 /subagents list [<id>]）。
 //
 // 解析：args[0] 直接作可选 <id>（聚焦该 record）。
-// RPC 模式（xyz-agent GUI）：解析 cancel action 直接执行，不打开 TUI。
+// RPC 模式（xyz-agent GUI）：解析 cancel/message/start action 直接执行，不打开 TUI。
+// message/start 为 GUI 定向消息通道（设计 §3.3.3）：GUI 经 client.prompt 短路
+// extension 命令（不经主 agent LLM），TUI 分支不消费这两个 verb（行为零变化）。
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
 import { getSubagentService } from "../execution/subagent-service.ts";
+import type { SubagentService } from "../execution/subagent-service.ts";
 import { displayAgentName } from "../shared/agent-ref.ts";
+import { messageHandler, startHandler } from "./subagent-actions.ts";
 import { parseSubagentRpcCommand } from "./command-actions.ts";
+import type { SubagentRpcAction } from "./command-actions.ts";
 import { LIST_LIMIT } from "./list-shared.ts";
 import { createSubagentsView } from "./list-view.ts";
 
+/**
+ * subagent-directive custom_message 的 customType。
+ *
+ * 定向消息留痕载体（设计 §3.3.3）：message/start 成功派发后落主 session 的
+ * custom_message entry，一 entry 双消费——
+ * 1. 主 agent 上下文（custom_message 进 context，主 agent 下次 turn 可见定向对话）
+ * 2. renderer 定向气泡渲染源（§3.3.3a live/reload 双链路，后续 wave 消费）
+ * 字段形状是 GUI 契约，改动需与 renderer 侧同步。
+ */
+export const SUBAGENT_DIRECTIVE_CUSTOM_TYPE = "subagent-directive";
+
+/** subagent-directive entry 的 details 形状（GUI 定向气泡渲染契约）。 */
+export interface SubagentDirectiveDetails {
+  subagentId: string;
+  slug: string;
+  /** 消息方向：'user' = 用户 → subagent 定向（当前唯一方向，命名预留双向扩展）。 */
+  direction: "user";
+}
+
+/**
+ * 定向消息留痕：向主 session 落 subagent-directive custom_message entry。
+ *
+ * 按主 agent streaming 状态分流 sendMessage options。pi 0.84.1 sendCustomMessage
+ * 实装（agent-session.js）：isStreaming 且无 deliverAs 时默认 agent.steer()——会把
+ * 定向消息注入正在运行的主 agent LLM turn，违反「不经主 agent LLM 直达 subagent」。
+ * 故按调用时刻的权威 streaming 状态（ctx.isIdle()，与 sendCustomMessage 内部
+ * isStreaming 判据精确互补，含 agent_end 后 retry/continuation 窗口）分流：
+ * - streaming（isMainAgentIdle=false）：传 { deliverAs: "nextTurn" }——消息入
+ *   pi 内存 _pendingNextTurnMessages 队列，下个 turn 注入主 agent 上下文；不打断、
+ *   不 steer 当前 turn。注意：该队列不落 entry，留痕延迟到下个 turn
+ * - 非 streaming（isMainAgentIdle=true）：不传 options——立即 append entry 留痕
+ *   + message_start/end 双发（renderer live 链路即时可见，现状行为）
+ * 两者都不传 triggerTurn——不产生新 turn（§3.3.8「留痕 ≠ 处理」的结构性保证）；
+ * display:false 使 pi TUI 不渲染该 entry（GUI 侧由 §3.3.3a 定向气泡通路渲染）。
+ */
+function emitSubagentDirective(
+  pi: Pick<ExtensionAPI, "sendMessage">,
+  details: SubagentDirectiveDetails,
+  text: string,
+  isMainAgentIdle: boolean,
+): void {
+  pi.sendMessage(
+    {
+      customType: SUBAGENT_DIRECTIVE_CUSTOM_TYPE,
+      content: text,
+      display: false,
+      details,
+    },
+    isMainAgentIdle ? undefined : { deliverAs: "nextTurn" },
+  );
+}
+
+/** RPC cancel 执行体（行为等价拆分自 handler，复杂度治理）。 */
+async function rpcCancel(
+  service: SubagentService,
+  recordId: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  try {
+    const ok = service.cancel(recordId);
+    ctx.ui.notify(
+      ok ? `Cancelled subagent ${recordId}` : `Subagent ${recordId} not found or already finished`,
+      ok ? "info" : "warning",
+    );
+  } catch (err) {
+    // service.cancel 内部 assertReady 在 session_shutdown 并发 dispose 时会抛
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to cancel subagent ${recordId}: ${msg}`, "warning");
+  }
+}
+
+/** RPC message 执行体（行为等价拆分自 handler，复杂度治理）。 */
+async function rpcMessage(
+  pi: ExtensionAPI,
+  service: SubagentService,
+  recordId: string,
+  text: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  // GUI 定向消息（设计 §3.3.3）：不经主 agent LLM 直达 subagent。
+  // one-shot 首条 message 自动升级 chatMode 的机制在 messageHandler 内（勿在此重复）。
+  try {
+    const result = await messageHandler(service, {
+      subagentId: recordId,
+      text,
+    });
+    // 留痕（§3.3.3）：成功派发后才留痕——失败时不留痕，GUI 按 toast 错误重发。
+    // ctx.isIdle() 按调用时刻分流（streaming → nextTurn 队列延迟留痕，见
+    // emitSubagentDirective JSDoc），保证任何时刻都不 steer 主 agent 当前 turn
+    emitSubagentDirective(
+      pi,
+      { subagentId: result.subagentId, slug: result.slug, direction: "user" },
+      text,
+      ctx.isIdle(),
+    );
+    ctx.ui.notify(`Message delivered to subagent ${result.slug} (${result.subagentId})`, "info");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to message subagent ${recordId}: ${msg}`, "warning");
+  }
+}
+
+/** RPC start 执行体（行为等价拆分自 handler，复杂度治理）。 */
+async function rpcStart(
+  pi: ExtensionAPI,
+  service: SubagentService,
+  slug: string,
+  task: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  // GUI 定向新建（设计 §3.3.3）：conversation 固定 true（GUI 定向对话场景需要可续聊）
+  try {
+    const result = await startHandler(
+      service,
+      {
+        slug,
+        task,
+        conversation: true,
+      },
+      // RPC 命令无外层 AbortSignal（GUI 请求生命周期不映射到 subagent 取消——
+      // start 是 detached 后台语义，取消走 /subagents cancel）
+      undefined,
+    );
+    emitSubagentDirective(
+      pi,
+      { subagentId: result.subagentId, slug: result.slug, direction: "user" },
+      task,
+      ctx.isIdle(),
+    );
+    ctx.ui.notify(`Started subagent ${result.slug} (${result.subagentId})`, "info");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to start subagent ${slug}: ${msg}`, "warning");
+  }
+}
+
+/**
+ * RPC 模式（xyz-agent GUI）：解析后的 action 分发执行，不打开 TUI。
+ * 行为等价拆分自 handler（fallow 圈复杂度 21 > 15）：三个执行体
+ * （cancel/message/start）各自成函数，本函数只做 switch 分发 +
+ * usage notify + exhaustiveness 断言。
+ */
+async function executeRpcAction(
+  pi: ExtensionAPI,
+  service: SubagentService,
+  parsed: SubagentRpcAction,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  switch (parsed.action) {
+    case "cancel":
+      await rpcCancel(service, parsed.recordId, ctx);
+      return;
+    case "cancel-missing-id":
+      ctx.ui.notify("Usage: /subagents cancel <id>", "warning");
+      return;
+    case "message":
+      await rpcMessage(pi, service, parsed.recordId, parsed.text, ctx);
+      return;
+    case "message-missing-args":
+      // 错误可操作：指明缺什么 + 完整 usage（全局规则 16）
+      ctx.ui.notify(
+        parsed.missing === "recordId"
+          ? "Usage: /subagents message <recordId> <text> — recordId is missing"
+          : "Usage: /subagents message <recordId> <text> — text is missing",
+        "warning",
+      );
+      return;
+    case "start":
+      await rpcStart(pi, service, parsed.slug, parsed.task, ctx);
+      return;
+    case "start-missing-args":
+      ctx.ui.notify(
+        parsed.missing === "slug"
+          ? "Usage: /subagents start <slug> <task> — slug is missing"
+          : "Usage: /subagents start <slug> <task> — task is missing",
+        "warning",
+      );
+      return;
+    case "noop":
+      // 无 action 或未知 action：GUI 端已屏蔽此 command 入口，此处兜底
+      ctx.ui.notify("View subagents in the sidebar Agents tab", "info");
+      return;
+    default: {
+      // exhaustiveness 断言：未来新增 action verb 忘加 case 时 tsc 报错
+      const _exhaustive: never = parsed;
+      throw new Error(`Unhandled subagent RPC action: ${String(_exhaustive)}`);
+    }
+  }
+}
+
 /** 注册 /subagents 命令（= list overlay）。 */
 export function registerSubagentsCommand(pi: ExtensionAPI): void {
   pi.registerCommand("subagents", {
@@ -59,35 +254,8 @@ export function registerSubagentsCommand(pi: ExtensionAPI): void {
       // ── RPC 模式（xyz-agent GUI）：解析 action 直接执行，不打开 TUI ──
       // hasUI 在 TUI 和 RPC 都为 true，不能用于区分；用 ctx.mode === "rpc" 判定 GUI 通道。
       if (ctx.mode === "rpc") {
-        const parsed = parseSubagentRpcCommand(argsStr);
-        switch (parsed.action) {
-          case "cancel": {
-            try {
-              const ok = service.cancel(parsed.recordId);
-              ctx.ui.notify(
-                ok ? `Cancelled subagent ${parsed.recordId}` : `Subagent ${parsed.recordId} not found or already finished`,
-                ok ? "info" : "warning",
-              );
-            } catch (err) {
-              // service.cancel 内部 assertReady 在 session_shutdown 并发 dispose 时会抛
-              const msg = err instanceof Error ? err.message : String(err);
-              ctx.ui.notify(`Failed to cancel subagent ${parsed.recordId}: ${msg}`, "warning");
-            }
-            return;
-          }
-          case "cancel-missing-id":
-            ctx.ui.notify("Usage: /subagents cancel <id>", "warning");
-            return;
-          case "noop":
-            // 无 action 或未知 action：GUI 端已屏蔽此 command 入口，此处兜底
-            ctx.ui.notify("View subagents in the sidebar Agents tab", "info");
-            return;
-          default: {
-            // exhaustiveness 断言：未来新增 action verb 忘加 case 时 tsc 报错
-            const _exhaustive: never = parsed;
-            throw new Error(`Unhandled subagent RPC action: ${String(_exhaustive)}`);
-          }
-        }
+        await executeRpcAction(pi, service, parseSubagentRpcCommand(argsStr), ctx);
+        return;
       }
 
       // ── print/json 模式（headless）：不可交互 ──