@zhushanwen/pi-subagent-workflow 0.1.0 → 0.3.0

package/src/execution/ui-request-queue.ts

@@ -0,0 +1,168 @@
+// src/execution/ui-request-queue.ts
+//
+// W3/W2: 子进程 extension_ui_request 的 FIFO 串行队列 + 转发处理。
+//
+// 从 session-runner.ts 提取（保持文件 < 1000 行）。职责单一：
+//   - createUiRequestQueue：每个子进程一个队列，保证多个 UI 请求（ask_user 等）
+//     FIFO 串行处理，防止并发询问用户导致交错。
+//   - handleUiRequest：从 ExtensionUiRequest 构造 UiRequest → 调主 agent uiRequestHandler
+//     → 按 UiResponse 形状回写 stdin。
+//   - extractMethodFields：method-specific 字段类型安全复制。
+//
+// session-runner.runSpawn 在 stdout pump 中拿到 extension_ui_request 后调 enqueue 入队。
+
+import type { ChildProcess } from "node:child_process";
+
+import type { UiRequest } from "./dialog-queue.ts";
+// 类型再导出：dialog-queue.ts 是 UiRequest/UiResponse/UiRequestHandler 的规范来源，
+// 本模块再导出供测试 import（避免测试直接依赖 dialog-queue 内部实现）。
+export type { UiRequest, UiRequestHandler, UiResponse } from "./dialog-queue.ts";
+import type { SessionRunnerContext } from "./session-runner.ts";
+import type { ExtensionUiRequest } from "./spawn-event-adapter.ts";
+import { respond } from "./stdin-writer.ts";
+import { parseChannel } from "./ui-channels.ts";
+import { notifyMissingHandlerGlobal } from "./ui-request-observability.ts";
+
+/**
+ * 创建 UI 请求队列。返回 enqueue 函数，调用方将 extension_ui_request 入队。
+ *
+ * 多个 extension_ui_request 并发到达时，队列保证 FIFO 串行处理：
+ * 前一个请求的 uiRequestHandler resolve 后，才将下一个请求发给主 agent UI。
+ * 防止并发询问用户导致交错（用户同时看到多个问题）。
+ *
+ * 设计：队列是 runSpawn 生命周期内的闭包状态（非模块级），
+ * 每个子进程实例独立队列，无跨 session 泄漏。
+ *
+ * @param child 子进程（stdin 写入 extension_ui_response）
+ * @param ctx SessionRunnerContext（含 uiRequestHandler 回调）
+ * @returns enqueue 函数：(id, request) => void，将请求入队并触发顺序处理
+ */
+export function createUiRequestQueue(
+  child: ChildProcess,
+  ctx: SessionRunnerContext,
+): (id: string, request: ExtensionUiRequest) => void {
+  // [R3] AbortController 取消 pending handler——子进程退出时队列不再阻塞
+  const abortController = new AbortController();
+  const queue: Array<{ id: string; request: ExtensionUiRequest; signal: AbortSignal }> = [];
+  let processing = false;
+  let closed = false;
+
+  function processNext(): void {
+    if (processing || queue.length === 0 || closed) return;
+    processing = true;
+    const { id, request, signal } = queue.shift()!;
+    handleUiRequest(child, id, request, ctx, signal).finally(() => {
+      processing = false;
+      processNext();
+    });
+  }
+
+  // [R3] 子进程退出时 abort 所有 pending handler，队列不再阻塞
+  // [SR-4] 同步清理 L2 队列中该 child 的 pending dialog——child 在 dialog 等 L2 时退出，
+  //   L2 里该项永不 settle → processing 永远 true → 所有其他子进程 dialog 永久阻塞（全局死锁）。
+  //   pid 缺省（spawn 后极短窗口 child.pid 可能为 undefined）时跳过——此时该 child 还未在 L2
+  //   注册过任何 dialog（handleUiRequest 构造 UiRequest 时用同样的 child.pid，pid undefined 时
+  //   不填 _childPid，rejectChildDialogs 也匹配不到），无清理必要。
+  const onClose = (): void => {
+    // #19/#17 幂等守卫：close + error 可能都触发，二次调用会重复 rejectChildDialogs（虽依赖 L2 的 settled 幂等，
+    // 但 close 状态本身需守卫——避免 closed=true 后 queue.length=0 + abort 重复执行，以及重复 reject 导致语义噪声）。
+    if (closed) return;
+    closed = true;
+    abortController.abort();
+    queue.length = 0;
+    if (child.pid !== undefined) {
+      ctx.dialogQueue?.rejectChildDialogs({ pid: child.pid });
+    }
+  };
+  child.on("close", onClose);
+  child.on("error", onClose);
+
+  return function enqueue(id: string, request: ExtensionUiRequest): void {
+    if (closed) return;
+    queue.push({ id, request, signal: abortController.signal });
+    processNext();
+  };
+}
+
+/**
+ * 处理子进程发来的 extension_ui_request（ask_user 及其他 Pi UI method）。
+ *
+ * 流程：从 ExtensionUiRequest 构造 UiRequest（含 channel/channelPayload）
+ *  → 调用主 agent uiRequestHandler → 按 UiResponse 形状回写 stdin。
+ *
+ * handler 未设置时不再静默忽略——console.warn 兜底（FR-9 可观测性），
+ * W3 接入 SubagentService.notifyMissingHandler 的 appendEntry。
+ *
+ * @param child 子进程（stdin 写入响应）
+ * @param id 请求 id（子进程用它关联 response）
+ * @param request ExtensionUiRequest（method 平铺，从 enqueueUiRequest 传入）
+ * @param ctx SessionRunnerContext（含 uiRequestHandler 回调）
+ * @param signal abort signal（子进程退出时触发，取消正在等待的 handler）
+ * @returns Promise（队列等待用：resolve 表示响应已写入 stdin 或已放弃）
+ */
+async function handleUiRequest(
+  child: ChildProcess,
+  id: string,
+  request: ExtensionUiRequest,
+  ctx: SessionRunnerContext,
+  signal?: AbortSignal,
+): Promise<void> {
+  const handler = ctx.uiRequestHandler;
+  if (!handler) {
+    // #9 + #11：handler 缺失时不再静默 return（会让子进程永久挂起等 response）。
+    //   - notifyMissingHandlerGlobal：经 globalThis 桥接到 observability 单例做 per-session 去重告警
+    //     （FR-9 可观测性；未注册时走 fallback warn 不丢日志）
+    //   - respond(cancelled)：让子进程收到明确取消，不再永久挂起。等价于用户主动取消的语义。
+    // 去重 key 用 child.pid（队列内拿不到真实 sessionId；pid 是子进程会话的稳定标识，
+    // 去重粒度正确——同一子进程多次 handler 缺失只告警一次）。
+    notifyMissingHandlerGlobal(child.pid?.toString() ?? id);
+    respond(child, id, { cancelled: true }, signal);
+    return;
+  }
+
+  // 从 ExtensionUiRequest 构造 UiRequest（含 channel/channelPayload）
+  const { channel, channelPayload } = parseChannel(request);
+  // [SR-4] 填入 child.pid 作为内部元数据：L2 队列的 rejectChildDialogs 据此关联 child close
+  //   清理。factory 层 enqueue 时读 req._childPid 传给 opts.child。pid undefined（spawn 后极短
+  //   窗口）时不填——rejectChildDialogs 也匹配不到（onClose 同样用 child.pid 守卫），无副作用。
+  const uiReq: UiRequest = {
+    id,
+    method: request.method,
+    ...(child.pid !== undefined ? { _childPid: child.pid } : {}),
+    ...(channel !== undefined ? { channel } : {}),
+    ...(channelPayload !== undefined ? { channelPayload } : {}),
+    ...extractMethodFields(request),
+  };
+
+  try {
+    const result = await handler(uiReq);
+    // [R3] 子进程已退出，跳过写入
+    if (signal?.aborted) return;
+    respond(child, id, result, signal);
+  } catch (err) {
+    // [R3] 子进程已退出，跳过写入
+    if (signal?.aborted) return;
+    console.error("[subagents] uiRequestHandler threw:", err);
+    respond(child, id, { cancelled: true }, signal);
+  }
+}
+
+/** 从 ExtensionUiRequest 提取 method-specific 字段到 UiRequest（与 Pi rpc-types.ts 1:1）。
+ *  按 method 变体类型安全地复制对应字段；缺失字段不复制（保持 UiRequest 可选）。 */
+function extractMethodFields(req: ExtensionUiRequest): Partial<UiRequest> {
+  const out: Partial<UiRequest> = {};
+  if ("title" in req && typeof req.title === "string") out.title = req.title;
+  if ("options" in req && Array.isArray(req.options)) out.options = req.options;
+  if ("message" in req && typeof req.message === "string") out.message = req.message;
+  if ("placeholder" in req && typeof req.placeholder === "string") out.placeholder = req.placeholder;
+  if ("prefill" in req && typeof req.prefill === "string") out.prefill = req.prefill;
+  if ("notifyType" in req && typeof req.notifyType === "string") out.notifyType = req.notifyType;
+  if ("statusKey" in req && typeof req.statusKey === "string") out.statusKey = req.statusKey;
+  if ("statusText" in req) out.statusText = req.statusText;
+  if ("widgetKey" in req && typeof req.widgetKey === "string") out.widgetKey = req.widgetKey;
+  if ("widgetLines" in req) out.widgetLines = req.widgetLines;
+  if ("widgetPlacement" in req) out.widgetPlacement = req.widgetPlacement;
+  if ("text" in req && typeof req.text === "string") out.text = req.text;
+  if ("timeout" in req && typeof req.timeout === "number") out.timeout = req.timeout;
+  return out;
+}

package/src/index.ts

@@ -17,12 +17,15 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import type { ExtensionAPI, ExtensionContext, ResourcesDiscoverEvent, ResourcesDiscoverResult, SessionShutdownEvent, SessionStartEvent } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ModelSelectEvent, ResourcesDiscoverEvent, ResourcesDiscoverResult, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@mariozechner/pi-coding-agent";
 import { getAgentDir } from "@mariozechner/pi-coding-agent";
 
 import type { AgentRegistry } from "./execution/agent-registry.ts";
 import { bestEffort } from "./execution/best-effort.ts";
 // ═══ execution/ 层（subagents 核心 + 运行时） ═══
+import { getOrCreateChannelRegistry } from "./execution/channel-registry-access.ts";
+import { DialogGlobalQueue } from "./execution/dialog-queue.ts";
+import { createUiRequestHandlerForMode } from "./execution/ui-request-handler-factory.ts";
 import {
   getModelConfigService,
   ModelConfigService,
@@ -38,6 +41,7 @@ import { SubprocessAgentRunner } from "./execution/subprocess-agent-runner.ts";
 import { WorktreeManager } from "./execution/worktree-manager.ts";
 import { renderBgNotifyMessage } from "./interface/bg-notify-render.ts";
 import { registerWorkflowsCommand } from "./interface/commands.ts";
+import { toGuiCtx } from "./interface/gui-mappers.ts";
 import { notifyDone } from "./interface/helpers.ts";
 import { registerSubagentTool } from "./interface/subagent-tool.ts";
 // ═══ interface/ 层（tools/commands/tui 合并） ═══
@@ -168,7 +172,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       runner: state.runner,
       runs: state.runs,
       registry,
-      onRunDone: (run: WorkflowRun) => notifyDone(pi, run.runId, run, notifiedRunIds, sessionCtx),
+      onRunDone: (run: WorkflowRun) => notifyDone(pi, run.runId, run, notifiedRunIds, toGuiCtx(sessionCtx)),
       agentRegistry: state.agentRegistry,
       sessionDir: state.sessionDir,
       activeTempFiles: state.activeTempFiles,
@@ -177,6 +181,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
         scheduleTimeBudget(runId, deps, budgetTimeMs),
       onWorkflowCall: (name: string, args: Record<string, unknown>, parentRun: WorkflowRun) =>
         executeNestedWorkflow(name, args, parentRun, deps),
+      streamSink: getSubagentService()?.getStreamSink() ?? undefined,
       log,
     };
     return deps;
@@ -211,9 +216,35 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       sessionId: ctx.sessionManager.getSessionId(),
       ctxModel: ctx.model ?? undefined,
     });
+
+    // ── W3: handler 注入链路接通 ──
+    // 进程级单例：channel registry + dialog queue 跨 session 复用
+    //（与 SubagentService 单例模式一致，globalThis Symbol 持有避免 jiti 多实例分裂）。
+    const channelRegistry = getOrCreateChannelRegistry();
+    const dialogQueue = getOrCreateDialogQueue();
+    const uiRequestHandler = createUiRequestHandlerForMode(ctx, channelRegistry, dialogQueue);
+    // SR-3: 无论 new 还是 existing（/resume /fork 复用），session_start 都必须注入 handler
+    service.setUiRequestHandler(uiRequestHandler);
+
     service.initSession({
       pi,
       sessionId: ctx.sessionManager.getSessionId(),
+      // 注入 ctx.ui.setWidget 作为 streaming sink（只绑方法，不持有整个 ctx）。
+      // background subagent 执行期间，text_delta 经 SubagentStream 合并后由此通道转发。
+      // [W1 修复] ctx.mode === 'rpc' 守卫：TUI/json/print 下 streamSink = undefined（无 widget 噪音），
+      // rpc mode（GUI/xyz-agent）下保持原行为（ctx.ui.setWidget → sidecar → chatStore）。
+      // streamSink API 不变（SubagentStream.onDelta 仍可调，只是 TUI 下 stream 不会被创建）。
+      streamSink: ctx.mode === "rpc"
+        ? { setWidget: (key, lines) => ctx.ui.setWidget(key, lines) }
+        : undefined,
+      // [#24] uiRequestHandler 单一注入入口：上方 setUiRequestHandler 已注入（SR-3 语义，
+      // new/existing service 均覆盖）。此处不再重复传 initSession.uiRequestHandler，避免
+      // 同一 handler 双路径注入造成的语义混淆与“哪一个是 source of truth”歧义。
+      // mode 仍需 session 级注入（uiObservability.setMode 依赖它，与 handler 无关）。
+      mode: ctx.mode,
+      // SR-4：注入 L2 dialog 队列——session-runner child close 时调 rejectChildDialogs
+      // 清理该 child 在 L2 的 pending dialog，防全局死锁（C1 修复：清理路径接通）。
+      dialogQueue,
     });
 
     if (!existingService) {
@@ -230,6 +261,18 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       console.warn("[subagents] expired session file cleanup failed:", err);
     }
 
+    // ADR-035 启动恢复：扫描 manifest tmp 残留（崩溃打断的 writeManifest 留下），
+    // 每次 session_start 都调（与上方 maybeCleanupExpiredSessionFiles 一致）。
+    try {
+      const recovered = await service.recoverManifestTmpFiles();
+      if (recovered.recovered > 0 || recovered.deleted > 0) {
+        console.warn(`[subagents] manifest tmp recovery: ${recovered.recovered} promoted, ${recovered.deleted} deleted`);
+      }
+    } catch (err) {
+      void err;
+      console.warn("[subagents] manifest tmp recovery failed:", err);
+    }
+
     try {
       const wtm = new WorktreeManager(agentDir);
       wtm.scan();
@@ -296,17 +339,23 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // ════════════════════════════════════════════════════════════
   //  model_select：用户切换 model 时刷新缓存
   // ════════════════════════════════════════════════════════════
-  pi.on("model_select", (event: { model: NonNullable<ExtensionContext["model"]> }, _ctx: ExtensionContext) => {
+  pi.on("model_select", (event: ModelSelectEvent, ctx: ExtensionContext) => {
     const service = getModelConfigService();
     if (service && typeof service.setCtxModel === "function") {
       service.setCtxModel(event.model);
     }
+    // H1: 同步刷新所有 session 的 SAR ctxModel（旧实现只在 session_start 固化）
+    const sid = ctx.sessionManager.getSessionId();
+    const state = sessionState.get(sid);
+    if (state) {
+      state.runner.updateCtxModel(event.model);
+    }
   });
 
   // ════════════════════════════════════════════════════════════
   //  session_tree：切分支前 pause 所有 running run
   // ════════════════════════════════════════════════════════════
-  pi.on("session_tree", async (_event: Record<string, unknown>, ctx: ExtensionContext) => {
+  pi.on("session_tree", async (_event: SessionTreeEvent, ctx: ExtensionContext) => {
     const sessionId = ctx.sessionManager.getSessionId();
     lsRef.lastSessionId = sessionId;
 
@@ -342,6 +391,20 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       cleanupAllFiles(state.activeTempFiles);
       sessionState.delete(sessionId);
     }
+
+    // M2: 清理 dialog queue 运行时状态（queue/current/processing）。
+    // [#10] 先 rejectAll() settle 所有 pending dialog Promise（防闭包泄漏：未 settle 的
+    // Promise 持有 resolve/reject 闭包及 handler 上下文，session 退出后仍挂在全球队列上），
+    // 再 clear() 重置 queue/current/processing（防异常退出后 processing=true 卡死下次 session）。
+    // rejectAll() 由 dialog-queue.ts 提供（Group B 新增）；若其内部已 reset 状态，此处 clear() 为幂等兜底。
+    // 单 session 假设（M-2，同 lastSessionId）：rejectAll() 清空进程级单例的所有 pending，
+    // 依赖 Pi 单进程单 session 串行保证——不会误清其他 session。多 session 并发的迁移策略
+    // 见 DialogGlobalQueue 类注释（rejectAllForSession）。
+    // channel registry 不清：跨 session 持久是有意设计（ask-user 扩展注册的 channel handler
+    // 在 /new /resume /fork 时不丢失注册）。
+    const dialogQueue = getOrCreateDialogQueue();
+    dialogQueue.rejectAll();
+    dialogQueue.clear();
   });
 
   // ════════════════════════════════════════════════════════════
@@ -452,3 +515,37 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     lazyDeps,
   );
 }
+
+// ============================================================
+// 进程级单例（channel registry + dialog queue）
+// ============================================================
+
+// channel registry 经 channel-registry-access.ts 公开访问（跨扩展 API）。
+// dialog queue 仍为本模块私有——无外部消费者。
+const DIALOG_QUEUE_KEY = Symbol.for("@zhushanwen/pi-subagents.dialogQueue");
+
+/** 获取或创建进程级 dialog queue 单例。
+ *  L2 跨子进程串行队列——所有子进程的 dialog 类请求共享同一队列实例。 */
+function getOrCreateDialogQueue(): DialogGlobalQueue {
+  let queue = Reflect.get(globalThis, DIALOG_QUEUE_KEY) as DialogGlobalQueue | undefined;
+  if (!queue) {
+    queue = new DialogGlobalQueue();
+    Reflect.set(globalThis, DIALOG_QUEUE_KEY, queue);
+  }
+  return queue;
+}
+
+// ============================================================
+// Public cross-extension API（channel handler 注册入口）
+// ============================================================
+//
+// 跨扩展消费者（ask-user 等）通过包根 import 注册 channel handler，
+// 让 subagent 子进程的 UI 请求（ask_user 等）透传到主进程渲染。
+// 重新导出 channel-registry-access 的公开 API——稳定 surface，
+// 内部存储实现演进不影响消费者。
+
+export {
+  getOrCreateChannelRegistry,
+  type UiChannelRegistry,
+  type ChannelHandler,
+} from "./execution/channel-registry-access.ts";

package/src/interface/__tests__/subagent-tool-prompt.test.ts

@@ -0,0 +1,84 @@
+// 提示词质量回归：subagent tool description 必须是"行为约束器"而非"功能说明书"。
+//
+// agent（LLM）决策时唯一能看到的 tool 元信息就是 description。审查发现旧版
+// description 把篇幅花在功能说明上，缺乏调用信号（何时委派 vs 自己做）、
+// 能力边界（cannot）、反模式密度（高风险要求 ≥4 条）、以及对 auto-injected
+// completion message 的注入防御。
+//
+// 本测试用源码断言（读 .ts 文件文本）锁定这些约束，防止后续重构把约束措辞
+// 删掉或弱化。读源码而非 import，避免 mock 链（subagent-tool.ts 依赖 pi-ai/
+// typebox/pi-tui/ExtensionAPI 等值导入）。
+
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SUBAGENT_TOOL_SRC = readFileSync(
+  join(__dirname, "../subagent-tool.ts"),
+  "utf-8",
+);
+
+/** 提取 description: `...` 模板字符串的原始内容。 */
+function extractDescription(src: string): string {
+  const m = src.match(/description:\s*`([\s\S]*?)`,/);
+  if (!m) throw new Error("description template literal not found");
+  return m[1];
+}
+
+const DESCRIPTION = extractDescription(SUBAGENT_TOOL_SRC);
+
+describe("subagent tool description — 行为约束器（非功能说明书）", () => {
+  it("词数 ≤ 400（高风险 description 密度上限）", () => {
+    // 高风险 tool 的 description 应聚焦约束而非功能铺陈；过长会稀释信号。
+    const words = DESCRIPTION.trim().split(/\s+/).filter(Boolean).length;
+    expect(words).toBeLessThanOrEqual(400);
+  });
+
+  it("含 'When to delegate' 调用条件段（何时委派 vs 自己做）", () => {
+    // 开篇必须给信号驱动的调用条件，而非纯功能说明。
+    expect(DESCRIPTION).toMatch(/When to delegate/i);
+  });
+
+  it("Anti-patterns 段含 ≥ 4 条 bullet", () => {
+    // 高风险 tool 要求 ≥ 4 条反模式，密度才足以覆盖主要误用路径。
+    const apIdx = DESCRIPTION.indexOf("## Anti-patterns");
+    expect(apIdx).toBeGreaterThan(-1);
+    const afterAp = DESCRIPTION.slice(apIdx);
+    // 截到下一个 ## 段
+    const nextSection = afterAp.indexOf("##", "## Anti-patterns".length);
+    const apSection =
+      nextSection > -1 ? afterAp.slice(0, nextSection) : afterAp;
+    const bullets = apSection.match(/^- .+/gm) || [];
+    expect(bullets.length).toBeGreaterThanOrEqual(4);
+  });
+
+  it("含能力边界段 'You cannot'", () => {
+    // 必须显式声明 tool 做不到的事，阻止 LLM 错误假设。
+    expect(DESCRIPTION).toMatch(/You cannot/);
+    expect(DESCRIPTION.toLowerCase()).toContain("cannot");
+  });
+
+  it("含注入防御：声明 completion message 为不可信数据", () => {
+    // completion message 是 auto-injected（F14 注入面），必须告诉 LLM
+    // 把它当作不可信数据，校验其中的指令后再执行。
+    const lower = DESCRIPTION.toLowerCase();
+    expect(
+      lower.includes("untrusted") || lower.includes("verify"),
+    ).toBe(true);
+  });
+
+  it("保留 nested spawning 段（允许 sub-subagent，仅深度限制）", () => {
+    // 这段防止 LLM 错误拒绝合法的 nested delegation。
+    expect(DESCRIPTION).toMatch(/Nested spawning/);
+    expect(DESCRIPTION).toMatch(/Depth: N\/10/);
+  });
+
+  it("保留 executionMode sequential 的 CRITICAL 说明", () => {
+    // sequential 是关键执行语义，删了会导致 LLM 误以为并行可用。
+    expect(DESCRIPTION).toMatch(/CRITICAL/i);
+    expect(DESCRIPTION).toMatch(/sequential/);
+    expect(DESCRIPTION).toMatch(/SAME message/i);
+  });
+});

package/src/interface/__tests__/workflow-state-file-exposure.test.ts

@@ -0,0 +1,38 @@
+// src/interface/__tests__/workflow-state-file-exposure.test.ts
+//
+// W2: WorkflowToolDetails 携带 stateFile + toRunSummary 填充逻辑
+//
+// 防的 bug：workflow run 自身的状态文件路径（<sessionDir>/workflow-state/<runId>.jsonl）
+// 从未暴露到 tool details——overlay/GUI 拿不到，无法定位 run 状态文件做后续查看。
+// 本测试验证 toRunSummary 和 actionRun 的 details 包含 stateFile 字段。
+//
+// 使用源码断言（读 .ts 文件文本）避免 import 重 mock 链——与 workflow-tool-prompt.test.ts 同模式。
+
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TOOL_WORKFLOW_SRC = readFileSync(
+  join(__dirname, "../tool-workflow.ts"),
+  "utf-8",
+);
+
+describe("W2: workflow tool details 暴露 stateFile", () => {
+  it("RunSummary 类型声明含 stateFile 可选字段", () => {
+    // RunSummary 必须声明 stateFile，否则 toRunSummary 返回的对象类型不含此字段
+    expect(TOOL_WORKFLOW_SRC).toMatch(/stateFile\?\s*:\s*string/);
+  });
+
+  it("toRunSummary 调用 deps.store.stateFilePath 填充 stateFile", () => {
+    // toRunSummary 必须从 store.stateFilePath(runId) 取值——这是数据来源
+    expect(TOOL_WORKFLOW_SRC).toMatch(/stateFilePath/);
+  });
+
+  it("run action 的 details 含 stateFile 字段", () => {
+    // actionRun 返回的 details 必须携带 stateFile（run 启动时即暴露路径）
+    // 验证 actionRun 函数体中构造 details 时引用了 stateFilePath
+    expect(TOOL_WORKFLOW_SRC).toMatch(/action.*run[\s\S]*stateFilePath|stateFilePath[\s\S]*action.*run/i);
+  });
+});

package/src/interface/__tests__/workflow-tool-prompt.test.ts

@@ -0,0 +1,50 @@
+// U1: workflow tool 提示词包含内置 workflow 清单 + 交叉引用。
+//
+// agent（LLM）决策时唯一能看到的 tool 元信息就是 description + promptGuidelines。
+// 若这些文本里不提及内置 workflow（chain/parallel/scatter-gather/map-reduce），
+// LLM 无法知道有现成的编排工具可用，会倾向自己 generate 脚本或瞎猜 name。
+//
+// 本测试用源码断言（读 .ts 文件文本）验证提示词内容，避免 import 重 mock 链
+// （tool-workflow.ts 依赖 pi-ai/typebox/pi-tui/lifecycle 等值导入）。
+
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TOOL_WORKFLOW_SRC = readFileSync(
+  join(__dirname, "../tool-workflow.ts"),
+  "utf-8",
+);
+const TOOL_WORKFLOW_SCRIPT_SRC = readFileSync(
+  join(__dirname, "../tool-workflow-script.ts"),
+  "utf-8",
+);
+
+describe("U1: workflow tool prompt mentions built-in workflows", () => {
+  it("tool-workflow.ts description 或 promptGuidelines 含 4 个内置 workflow 名称", () => {
+    // 4 个内置通用编排 workflow 必须在提示词里出现，LLM 才能发现并使用。
+    expect(TOOL_WORKFLOW_SRC).toContain("chain");
+    expect(TOOL_WORKFLOW_SRC).toContain("parallel");
+    expect(TOOL_WORKFLOW_SRC).toContain("scatter-gather");
+    expect(TOOL_WORKFLOW_SRC).toContain("map-reduce");
+  });
+
+  it("tool-workflow.ts promptGuidelines 含 workflow-script list 交叉引用", () => {
+    // LLM 需要知道"先 list 再 run"的发现路径——两个 tool 之间必须有交叉引用。
+    // 文本可能跨字符串拼接行，分别断言两个关键词都存在。
+    expect(TOOL_WORKFLOW_SRC).toContain("workflow-script");
+    expect(TOOL_WORKFLOW_SRC).toMatch(/action.*list/i);
+  });
+
+  it("tool-workflow.ts promptGuidelines 含 run action 的正例", () => {
+    // 给出 workflow run <name> 的调用示例，LLM 才知道参数格式。
+    expect(TOOL_WORKFLOW_SRC).toMatch(/workflow run .+--args/i);
+  });
+
+  it("tool-workflow-script.ts list action 的 promptGuidelines 含 workflow run 交叉引用", () => {
+    // 反向交叉引用：list 的指引里要提到用 workflow tool 的 run action 启动脚本。
+    expect(TOOL_WORKFLOW_SCRIPT_SRC).toMatch(/workflow.*tool.*run|run.*workflow.*tool/i);
+  });
+});

package/src/interface/command-actions.ts

@@ -0,0 +1,77 @@
+/**
+ * command-actions — RPC 模式 slash command action 解析纯函数。
+ *
+ * xyz-agent GUI 通过 `client.prompt("/subagents cancel <id>")` 等触发生命周期操作，
+ * 不经 LLM（pi 的 _tryExecuteExtensionCommand 在 agent loop 前短路）。command handler
+ * 在 RPC 模式下用这两个函数解析 action 字符串，分发到对应 service/lifecycle 调用。
+ *
+ * 设计为纯函数（无 ctx / service 依赖），便于独立单测，handler 只做薄分发。
+ */
+
+/** /subagents RPC action 判别联合。 */
+export type SubagentRpcAction =
+  | { action: "cancel"; recordId: string }
+  | { action: "cancel-missing-id" }
+  | { action: "noop" };
+
+/** /workflows RPC action 判别联合。 */
+export type WorkflowRpcAction =
+  | { action: "pause"; runId: string }
+  | { action: "resume"; runId: string }
+  | { action: "abort"; runId: string }
+  | { action: "lifecycle-missing-id"; verb: "pause" | "resume" | "abort" }
+  | { action: "noop" };
+
+/** workflow lifecycle verb 类型。 */
+type LifecycleVerb = "pause" | "resume" | "abort";
+
+/** workflow lifecycle verb 集合。 */
+const LIFECYCLE_VERBS: ReadonlySet<LifecycleVerb> = new Set(["pause", "resume", "abort"]);
+
+/** verb 是否为 lifecycle action（类型守卫，收窄到 LifecycleVerb）。 */
+function isLifecycleVerb(verb: string): verb is LifecycleVerb {
+  return LIFECYCLE_VERBS.has(verb as LifecycleVerb);
+}
+
+/**
+ * 解析 /subagents RPC 命令字符串。
+ *
+ * 支持格式：
+ * - `cancel <id>` → { action: "cancel", recordId }
+ * - `cancel`（无 id）→ { action: "cancel-missing-id" }
+ * - 其他（空 / 未知 action / 无参）→ { action: "noop" }
+ *
+ * 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 [verb, recordId] = args;
+  if (verb === "cancel") {
+    if (!recordId) return { action: "cancel-missing-id" };
+    return { action: "cancel", recordId };
+  }
+  return { action: "noop" };
+}
+
+/**
+ * 解析 /workflows RPC 命令字符串。
+ *
+ * 支持格式：
+ * - `pause|resume|abort <runId>` → 对应 lifecycle action + runId
+ * - `pause|resume|abort`（无 runId）→ { action: "lifecycle-missing-id", verb }
+ * - 其他（空 / 未知 action / 无参）→ { action: "noop" }
+ */
+export function parseWorkflowRpcCommand(argsStr: string): WorkflowRpcAction {
+  const args = argsStr.trim().split(/\s+/).filter(Boolean);
+  if (args.length === 0) return { action: "noop" };
+
+  const [verb, runId] = args;
+  if (isLifecycleVerb(verb)) {
+    if (!runId) return { action: "lifecycle-missing-id", verb };
+    return { action: verb, runId };
+  }
+  return { action: "noop" };
+}

package/src/interface/commands.ts

@@ -24,6 +24,7 @@ import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@mariozechner
 import type { LauncherDeps } from "../orchestration/launcher.ts";
 import { abortRun, pauseRun, resumeRun } from "../orchestration/lifecycle.ts";
 import type { WorkflowRun } from "../orchestration/models/workflow-run.ts";
+import { parseWorkflowRpcCommand } from "./command-actions.ts";
 import { createWorkflowsView, type ViewActions } from "./views/WorkflowsView.ts";
 
 /** runId 截断长度（显示用）。 */
@@ -64,10 +65,45 @@ export function registerWorkflowsCommand(
   deps: LauncherDeps,
 ): void {
   api.registerCommand("workflows", {
-    description: "Open workflow interactive panel. /workflows [runId] to open a specific run.",
+    description: "Open workflow panel. /workflows [runId] | /workflows pause|resume|abort <runId>",
     handler: async (args: string, ctx: ExtensionCommandContext) => {
- // RPC/print/json 模式无 TUI——降级提示
-      if (!ctx.hasUI) {
+      // ── RPC 模式（xyz-agent GUI）：解析 lifecycle action 直接执行，不打开 TUI ──
+      // hasUI 在 TUI 和 RPC 都为 true，不能用于区分；用 ctx.mode === "rpc" 判定 GUI 通道。
+      if (ctx.mode === "rpc") {
+        const parsed = parseWorkflowRpcCommand(args);
+        switch (parsed.action) {
+          case "pause":
+          case "resume":
+          case "abort": {
+            try {
+              if (parsed.action === "pause") await pauseRun(parsed.runId, deps);
+              else if (parsed.action === "resume") await resumeRun(parsed.runId, deps);
+              else await abortRun(parsed.runId, deps);
+              const pastTense = parsed.action === "abort" ? "aborted" : `${parsed.action}d`;
+              ctx.ui.notify(`Workflow ${parsed.runId}: ${pastTense}`, "info");
+            } catch (err) {
+              const msg = err instanceof Error ? err.message : String(err);
+              ctx.ui.notify(`Failed to ${parsed.action} workflow ${parsed.runId}: ${msg}`, "warning");
+            }
+            return;
+          }
+          case "lifecycle-missing-id":
+            ctx.ui.notify(`Usage: /workflows ${parsed.verb} <runId>`, "warning");
+            return;
+          case "noop":
+            // 无 action 或未知 action：GUI 端已屏蔽此 command 入口，此处兜底
+            ctx.ui.notify("View workflows in the sidebar Flows tab", "info");
+            return;
+          default: {
+            // exhaustiveness 断言：未来新增 action verb 忘加 case 时 tsc 报错
+            const _exhaustive: never = parsed;
+            throw new Error(`Unhandled workflow RPC action: ${String(_exhaustive)}`);
+          }
+        }
+      }
+
+      // ── print/json 模式（headless）：不可交互 ──
+      if (ctx.mode !== "tui") {
         ctx.ui.notify("/workflows requires interactive mode", "error");
         return;
       }
@@ -153,5 +189,5 @@ async function openView(
     resume: (runId: string) => resumeRun(runId, deps),
     abort: (runId: string) => abortRun(runId, deps),
   };
-  await createWorkflowsView(run, theme, ctx, actions);
+  await createWorkflowsView(run, theme, ctx, actions, deps.store.stateFilePath(run.runId));
 }