@zhushanwen/pi-subagent-workflow 0.1.0 → 0.2.0

package/src/execution/subagent-service.ts

@@ -14,6 +14,11 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+import type { AgentResult as WorkflowAgentResult } from "../orchestration/models/types.ts";
+// D-A10: workflow 侧 AgentResult 映射（executeAndAwait 出口）
+import { mapToWorkflowAgentResult } from "./agent-result-mapper.ts";
+import { removeAliveMarker } from "./alive-store.ts";
+import { bestEffort } from "./best-effort.ts";
 import { type ConcurrencyPool,DefaultConcurrencyPool } from "./concurrency-pool.ts";
 import {
   completeRecord,
@@ -22,10 +27,19 @@ import {
   snapshot,
   tryTransition,
 } from "./execution-record.ts";
+import { writeFinalized } from "./finalized-marker.ts";
+import type { ModelConfigService } from "./model-config-service.ts";
 import type { AgentConfig, ModelInfo, ResolvedModel } from "./model-resolver.ts";
+import type { BgNotifyRecord, NotifierHost } from "./notifier.ts";
+import { BgNotifier } from "./notifier.ts";
 import { getSubagentSessionDir } from "./path-encoding.ts";
+import type { StatusFilter } from "./record-store.ts";
+import { RecordStore } from "./record-store.ts";
 import { MAX_FORK_DEPTH } from "./session-context-resolver.ts";
 import { killAllSpawnedChildren, runSpawn, type SessionRunnerContext } from "./session-runner.ts";
+import type { StreamSink } from "./stream-sink.ts";
+import { SubagentStream } from "./stream-sink.ts";
+import { writeCancelledTombstone } from "./tombstone-store.ts";
 import type { WorktreeHandle } from "./types.ts";
 import type {
   AgentEvent,
@@ -40,20 +54,7 @@ import type {
 } from "./types.ts";
 import { ForkDepthExceededError } from "./types.ts";
 import { DEFAULT_AGENT_NAME } from "./types.ts";
-import { bestEffort } from "./best-effort.ts";
-import { removeAliveMarker } from "./alive-store.ts";
-import { writeFinalized } from "./finalized-marker.ts";
-import type { StatusFilter } from "./record-store.ts";
-import { RecordStore } from "./record-store.ts";
-import { writeCancelledTombstone } from "./tombstone-store.ts";
-
-// D-A10: workflow 侧 AgentResult 映射（executeAndAwait 出口）
-import { mapToWorkflowAgentResult } from "./agent-result-mapper.ts";
-import type { AgentResult as WorkflowAgentResult } from "../orchestration/models/types.ts";
-import type { ModelConfigService } from "./model-config-service.ts";
 import { WorktreeManager } from "./worktree-manager.ts";
-import { BgNotifier } from "./notifier.ts";
-import type { BgNotifyRecord, NotifierHost } from "./notifier.ts";
 
 /** Pi ExtensionAPI 的最小接口（duck-typed）。
  *  subagent-service 直接调 pi.sendMessage 发 background 完成通知（BgNotifier 滑动窗口合并），
@@ -67,6 +68,11 @@ interface PiLike {
   ): void;
 }
 
+/** UI streaming sink 的最小接口（ctx.ui.setWidget 的 duck-typed 子集）。
+ *  session_start 时从 ctx.ui 注入，background 执行期间用于把合并后的 text_delta
+ *  通过 setWidget 通道转发到 RPC stdout（不经 sendMessage 的持久化路径）。 */
+export type { StreamSink } from "./stream-sink.ts";
+
 /** pending-notifications 注册/注销 helper（避免重复代码）。 */
 function emitPendingRegister(pi: PiLike | null, id: string, name?: string): void {
   pi?.events.emit("pending:register", {
@@ -100,6 +106,8 @@ export interface SubagentServiceInit {
 export interface SubagentServiceSessionInit {
   pi: PiLike;
   sessionId: string;
+  /** UI streaming sink（ctx.ui.setWidget），用于 background text_delta 转发。 */
+  streamSink?: StreamSink;
 }
 
 /** background 优先级（保留 priority 排序机制，单一值）。 */
@@ -162,6 +170,9 @@ export class SubagentService {
   private pi: PiLike | null = null;
   /** 当前 Pi session ID（session 隔离过滤用）。initSession 时注入。 */
   private sessionId: string | null = null;
+  /** UI streaming sink（ctx.ui.setWidget）。workflow 域经 getStreamSink() 取用。 */
+  private streamSink: StreamSink | null = null;
+  getStreamSink(): StreamSink | null { return this.streamSink; }
   private _disposed = false;
   private _seq = 0;
   /** background 完成通知器（滑动窗口合并 + 去重）。session_start revive，shutdown dispose。 */
@@ -198,6 +209,7 @@ export class SubagentService {
   initSession(init: SubagentServiceSessionInit): void {
     this.pi = init.pi;
     this.sessionId = init.sessionId;
+    this.streamSink = init.streamSink ?? null;
     // [SPAWN fork depth 跨进程传递] 子进程被父 spawn 时，父通过 env
     // PI_SUBAGENT_FORK_DEPTH 传入当前 fork 链深度。子进程 session_start 时
     // 读取作为 forkDepthAls 基线，使后续嵌套 spawn fork 能从正确深度递增。
@@ -430,6 +442,7 @@ export class SubagentService {
     opts: ExecuteOptions,
     signal?: AbortSignal,
     onEvent?: (event: AgentEvent) => void,
+    stream?: SubagentStream,
   ): Promise<WorkflowAgentResult> {
     this.assertReady();
 
@@ -455,8 +468,7 @@ export class SubagentService {
     // ── 步骤 4: signal 决议 ──
     const effectiveSignal = signal ?? record.controller?.signal;
 
-    // ── 步骤 5: runAndFinalize（await，不 detached）──
-    // BC-11：onUpdate 置 undefined（不回流 tool UI 细节），onEvent 独立传（AgentEvent 透传 workflow）
+    // 步骤 5: runAndFinalize（await，不 detached）。onUpdate=undefined（BC-11），onEvent 独立传，stream 透传。
     const result = await this.runAndFinalize(
       record,
       { ...opts, onUpdate: undefined },
@@ -465,6 +477,7 @@ export class SubagentService {
       effectiveSignal,
       PRIORITY_BACKGROUND,
       onEvent,
+      stream,
     );
 
     // ── 步骤 6: D-A10 AgentResult 映射 ──
@@ -538,6 +551,7 @@ export class SubagentService {
       thinkingLevel: identity.resolved.thinkingLevel,
       mode,
       task: opts.task,
+      slug: opts.slug,
       startedAt: Date.now(),
       rootSessionId: this.sessionId ?? undefined,
       parentRecordId,
@@ -567,13 +581,20 @@ export class SubagentService {
     signal: AbortSignal | undefined,
     priority: number,
     rawOnEvent?: (event: AgentEvent) => void,
+    stream?: SubagentStream,
   ): Promise<AgentResult> {
-    // 仅 background 进并发池限流，分层配额：每层嵌套 depth 让有效配额 -1（下限 1）。
-    // 顶层 depth=0 拿满配额；嵌套越深有效并发越小，防子 agent fan-out 压垮主 agent 的 pool。
     const pooled = record.mode === "background";
+    let acquired = false;
     if (pooled) {
       const effectiveMaxConcurrent = Math.max(1, this.pool.maxConcurrent - record.depth);
-      await this.pool.acquire(priority, effectiveMaxConcurrent);
+      try {
+        await this.pool.acquire(priority, effectiveMaxConcurrent, signal);
+        acquired = true;
+      } catch {
+        // S1: 排队中被 abort（signal.aborted）走 cancelled，与已运行被 abort 一致。
+        if (signal?.aborted) return this.finalizeAborted(record);
+        return this.finalizeFailed(record, new Error("aborted"));
+      }
     }
     // onEvent 包装：AgentEvent → onUpdate(project(record)) 回流调用方
     const onEvent = rawOnEvent
@@ -581,16 +602,12 @@ export class SubagentService {
         ? (event: AgentEvent): void => this.onEventThrottled(record, event, opts.onUpdate!)
         : undefined);
 
-    // 解析 worktree 参数：boolean → WorktreeHandle | undefined
+    // 解析 worktree 参数：boolean → WorktreeHandle | undefined（true/undefined 由 run 内部处理）
     let worktreeHandle: WorktreeHandle | undefined;
     if (typeof opts.worktree === "object") {
       worktreeHandle = opts.worktree;
     }
-    // worktree=true 或 undefined 时不传递 handle，由 run 内部处理
-
-    // [MF#4][MF#2] fork 深度护栏：深度按 async 调用链传递（ALS），不再用共享实例计数器。
-    // parentDepth = 当前调用链的深度（主 session 链上无 store→0）；fork 时推进为 parentDepth+1，
-    // 包进 run() 的 ALS 作用域，使子 agent 在 prompt() 期间发起的嵌套 execute 能读到该深度。
+    // [MF#4][MF#2] fork 深度护栏：ALS 传递深度（主 session 链无 store→0，fork 推进 +1）。
     const parentDepth = this.forkDepthAls.getStore() ?? 0;
     const effectiveDepth = opts.fork ? parentDepth + 1 : parentDepth;
 
@@ -612,6 +629,7 @@ export class SubagentService {
             graceTurns: opts.graceTurns,
             signal,
             onEvent,
+            stream, // text_delta streaming（background 路径有值，workflow 路径 undefined）
             fork: opts.fork,
             worktree: worktreeHandle,
             parentForkDepth: parentDepth, // [MF#4] 父链深度，不从 opts 读
@@ -626,7 +644,9 @@ export class SubagentService {
       result = await this.finalizeFailed(record, err);
       return result;
     } finally {
-      if (pooled) this.pool.release();
+      if (pooled && acquired) this.pool.release();
+      // 清除 streaming widget（subagent 终态，幂等）
+      stream?.dispose();
     }
 
     // status 唯一判定点：success ? done : (aborted ? cancelled : failed)
@@ -650,7 +670,15 @@ export class SubagentService {
     signal: AbortSignal | undefined,
     priority: number,
   ): void {
-    void this.runAndFinalize(record, opts, ctx, identity, signal, priority)
+    // 创建 streaming 生命周期对象——streamSink 为 null（session_start 未注入）时降级为 undefined。
+    const stream = this.streamSink
+      ? new SubagentStream(record.id, this.streamSink)
+      : undefined;
+
+    void this.runAndFinalize(
+      record, opts, ctx, identity, signal, priority,
+      undefined, stream,
+    )
       .then(() => {
         // background 回注：仅当本路径抢到 CAS（status 已转 done/failed）才 notify。
         // cancel 抢先时 status=cancelled，cancelBackground 自己 notify，此处跳过。
@@ -732,10 +760,9 @@ export class SubagentService {
   ): Promise<void> {
     // 终态清节流状态：防 trailing timer 在 record 归档后误发陈旧 onUpdate
     this.clearThrottle(record.id);
-    // ── Step 0: collectPatch（best-effort，D-022 patchOk 守卫）──
+    // ── Step 0: collectPatch（best-effort）──
     // [MF#3] patchFile 写到 worktree 之外（sessionsDir/<branch>.patch），避免被 cleanup 删除；
     //        路径回填 record.patchFile，供调用方（tool result / /subagents list）应用。
-    let patchOk = true;
     if (record.worktreeHandle) {
       try {
         const sessionsDir = getSubagentSessionDir(
@@ -745,12 +772,9 @@ export class SubagentService {
         fs.mkdirSync(sessionsDir, { recursive: true });
         const patchFile = path.join(sessionsDir, `${record.worktreeHandle.branch}.patch`);
         const patch = this.worktreeManager.collectPatch(record.worktreeHandle, patchFile);
-        patchOk = !patch.failed;
-        // 仅 patch 实际写盘（非空 diff 且未失败）才回填，避免指向不存在文件的悬空路径——
-        // 否则 notifier/render/sync 路径会向 LLM 输出 `git apply <不存在>`（纯查询任务命中）。
         if (patch.written) record.patchFile = patchFile;
-      } catch {
-        patchOk = false;
+      } catch (pe: unknown) {
+        bestEffort(pe, "collectPatch (finalizeRecord Step0)");
       }
     }
 
@@ -787,7 +811,7 @@ export class SubagentService {
         bestEffort(err, "writeFinalized/tombstone (finalizeRecord Step3)");
       }
     }
-    if (record.worktreeHandle && patchOk) {
+    if (record.worktreeHandle) {
       try {
         this.worktreeManager.cleanup(record.worktreeHandle);
       } catch (err) {
@@ -816,15 +840,7 @@ export class SubagentService {
   private async finalizeFailed(record: ExecutionRecord, err: unknown): Promise<AgentResult> {
     const errMsg = err instanceof Error ? err.message : String(err);
     // durationMs 用真实耗时（startedAt → now），避免失败统计恒为 0 失真。
-    const failedResult: AgentResult = {
-      text: "",
-      turns: record.turnCount,
-      durationMs: Date.now() - record.startedAt,
-      success: false,
-      error: errMsg,
-      sessionId: record.id,
-      toolCalls: [],
-    };
+    const failedResult: AgentResult = { text: "", turns: record.turnCount, durationMs: Date.now() - record.startedAt, success: false, error: errMsg, sessionId: record.id, toolCalls: [] };
     // CAS 抢锁：抢到（status 仍 running）则完整收尾；没抢到（cancel 已先设 cancelled）跳过。
     if (tryTransition(record, "failed")) {
       await this.finalizeRecord(record, failedResult, "failed");
@@ -832,6 +848,15 @@ export class SubagentService {
     return failedResult;
   }
 
+  /** S1: 排队中被 abort 走 cancelled 终态（对齐已运行被 abort 的 cancelBackground）。 */
+  private async finalizeAborted(record: ExecutionRecord): Promise<AgentResult> {
+    const cancelledResult: AgentResult = { text: "", turns: record.turnCount, durationMs: Date.now() - record.startedAt, success: false, error: "cancelled by user", sessionId: record.id, toolCalls: [] };
+    if (tryTransition(record, "cancelled")) {
+      await this.finalizeRecord(record, cancelledResult, "cancelled");
+    }
+    return cancelledResult;
+  }
+
   // onUpdate 节流状态（per-record Map）。每条 record（每条 onUpdate 回流链）独立节流，
   // 避免嵌套（fork 链：主→A→B）多条 onUpdate 链争用同一份节流状态。
   // [HISTORICAL] 旧实现用单个实例字段，注释假设“fork 嵌套串行，同时只有一条链”——错误：

package/src/execution/subprocess-agent-runner.ts

@@ -14,13 +14,14 @@
 //   D-A2（映射归 adapter）/ D-A8（onEvent 桥接）/ D-A9（timeoutMs 合并 signal）/
 //   D-008（model 填底，不调 resolveModel）/ BC-9（timeoutMs 行为）/ BC-10（live-record 进度）
 
-import type { AgentEvent } from "../shared/agent-event.ts";
 import type { AgentRunner } from "../orchestration/models/ports.ts";
 import type { AgentCallOpts, AgentResult } from "../orchestration/models/types.ts";
+import type { AgentEvent } from "../shared/agent-event.ts";
+import { mapToExecuteOptions, mergeTimeoutSignal } from "./execute-options-mapper.ts";
 import type { ModelInfo } from "./model-resolver.ts";
+import type { SubagentStream } from "./stream-sink.ts";
 import type { SubagentService } from "./subagent-service.ts";
 import type { ExecuteOptions } from "./types.ts";
-import { mapToExecuteOptions, mergeTimeoutSignal } from "./execute-options-mapper.ts";
 
 // ── 构造依赖（per-session 注入）──
 
@@ -52,13 +53,23 @@ export interface SubprocessAgentRunnerDeps {
  */
 export class SubprocessAgentRunner implements AgentRunner {
   private readonly subagentService: SubagentService;
-  private readonly ctxModel: ModelInfo | undefined;
+  private ctxModel: ModelInfo | undefined;
 
   constructor(deps: SubprocessAgentRunnerDeps) {
     this.subagentService = deps.subagentService;
     this.ctxModel = deps.ctxModel;
   }
 
+  /**
+   * 刷新主 agent model 缓存。model_select 事件时由 index.ts 调用。
+   * H1 修复：旧实现 ctxModel 是 readonly，session_start 后固化，
+   * model_select 只刷新 ModelConfigService._ctxModel 不更新 SAR →
+   * workflow 路径用过期模型。
+   */
+  updateCtxModel(model: ModelInfo | undefined): void {
+    this.ctxModel = model;
+  }
+
   /**
    * 执行单次 agent 调用：委托 SubagentService.executeAndAwait。
    *
@@ -75,6 +86,7 @@ export class SubprocessAgentRunner implements AgentRunner {
     opts: AgentCallOpts,
     signal: AbortSignal,
     onEvent?: (event: AgentEvent) => void,
+    stream?: SubagentStream,
   ): Promise<AgentResult> {
     const startedAt = Date.now();
 
@@ -93,7 +105,7 @@ export class SubprocessAgentRunner implements AgentRunner {
       const bridgedOnEvent = onEvent;
 
       // ── 核心委托 ──
-      return await this.subagentService.executeAndAwait(mappedOpts, mergedSignal, bridgedOnEvent);
+      return await this.subagentService.executeAndAwait(mappedOpts, mergedSignal, bridgedOnEvent, stream);
     } catch (err) {
       // executeAndAwait throw（嵌套超限 ForkDepthExceededError，BC-12）或未预期异常 → 不 reject，入 error。
       const message = err instanceof Error ? err.message : String(err);

package/src/execution/types.ts

@@ -7,6 +7,8 @@
 //   - Runtime 编排 Core，产出 Details/Record 给 TUI
 //   - TUI 只读 Record/Details 快照，永不持有可变引用
 
+import type { GuiRenderResult } from "@xyz-agent/extension-protocol";
+
 import type { ModelInfo, ModelRegistryLike } from "./model-resolver.ts";
 
 // ============================================================
@@ -304,6 +306,11 @@ export interface ExecutionRecord {
   readonly thinkingLevel: string | undefined;
   readonly mode: ExecutionMode;
   readonly task: string;
+  /**
+   * 人类可读的短标签（≤20 字符），简述本次 subagent「在做什么」。
+   * 区别于 agent（类型名）/ task（完整 prompt）。旧持久化 record 反序列化时缺失兜底空串。
+   */
+  readonly slug: string;
   readonly startedAt: number;
   /** 根 Pi session ID（session 隔离过滤用）。递归链上所有层 record 同值。 */
   readonly rootSessionId: string | undefined;
@@ -360,6 +367,8 @@ export interface SubagentToolDetails {
   agent: string;
   model: string;
   thinkingLevel: string | undefined;
+  /** 短标签（≤20 字符），来自 record.slug。旧 record 反序列化时为空串。 */
+  slug: string;
   turns: number;
   totalTokens: number;
   elapsedSeconds: number;
@@ -385,6 +394,11 @@ export interface SubagentToolDetails {
 /** Hub.execute 的入参（sync/bg 共用）。mode 由 Hub 内部判定，不暴露给调用方。 */
 export interface ExecuteOptions {
   task: string;
+  /**
+   * 短标签（≤20 字符），简述本次执行用途，展示在 TUI。必填。
+   * workflow 内 agent() 调用时从 AgentCallOpts.description 透传而来。
+   */
+  slug: string;
   agent?: string;
   model?: string;
   thinkingLevel?: string;
@@ -434,6 +448,8 @@ export type ExecutionHandle = {
 export interface SubagentListItem {
   subagentId: string;
   agent: string;
+  /** 短标签（≤20 字符），来自 record.slug。旧 record 反序列化时为空串。 */
+  slug: string;
   status: ExecutionStatus;
   mode: ExecutionMode;
   /** 运行秒数（running 态实时计算，终态 endedAt-startedAt）。 */
@@ -473,9 +489,9 @@ export interface CancelResponse {
  *   - cancel → cancelResponse（subagentId 有值；sessionFile 无意义，可为 null）
  */
 export type SubagentToolResult =
-  | { action: "start"; subagentId: string; sessionFile: string | null; bgResponse: BgResponse }
-  | { action: "list"; subagentId: null; sessionFile: null; listResponse: ListResponse }
-  | { action: "cancel"; subagentId: string; sessionFile: null; cancelResponse: CancelResponse };
+  | { action: "start"; subagentId: string; sessionFile: string | null; slug: string; bgResponse: BgResponse; __gui__?: GuiRenderResult }
+  | { action: "list"; subagentId: null; sessionFile: null; listResponse: ListResponse; __gui__?: GuiRenderResult }
+  | { action: "cancel"; subagentId: string; sessionFile: null; cancelResponse: CancelResponse; __gui__?: GuiRenderResult };
 
 // ============================================================
 // TUI list 视图的合并 record（4 源 merge 后的形状）
@@ -487,6 +503,8 @@ export interface SubagentRecord {
   agent: string;
   /** 任务提示词（详情面板置顶展示）。磁盘/内存源均有。 */
   task: string;
+  /** 短标签（≤20 字符）。磁盘重建源旧文件可能缺失→兜底空串。 */
+  slug: string;
   status: ExecutionStatus;
   mode: ExecutionMode;
   startedAt: number;
@@ -552,6 +570,8 @@ export interface RecordSnapshot {
   readonly thinkingLevel: string | undefined;
   readonly mode: ExecutionMode;
   readonly task: string;
+  /** 短标签（≤20 字符）。来自 record.slug。 */
+  readonly slug: string;
   readonly status: ExecutionStatus;
   readonly turns: number;
   readonly totalTokens: number;

package/src/index.ts

@@ -38,6 +38,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 +169,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 +178,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;
@@ -214,6 +216,11 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     service.initSession({
       pi,
       sessionId: ctx.sessionManager.getSessionId(),
+      // 注入 ctx.ui.setWidget 作为 streaming sink（只绑方法，不持有整个 ctx）。
+      // background subagent 执行期间，text_delta 经 SubagentStream 合并后由此通道转发。
+      streamSink: {
+        setWidget: (key, lines) => ctx.ui.setWidget(key, lines),
+      },
     });
 
     if (!existingService) {
@@ -296,11 +303,17 @@ 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: { model: NonNullable<ExtensionContext["model"]> }, 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);
+    }
   });
 
   // ════════════════════════════════════════════════════════════

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);
+  });
+});