@zhushanwen/pi-subagent-workflow 0.3.2 → 0.4.0

package/src/interface/tool-workflow.ts

@@ -1,5 +1,5 @@
 /**
- * Workflow Extension — workflow tool（7 actions，FR-5 tool 收口）。
+ * Workflow Extension — workflow tool（5 actions，FR-5 tool 收口）。
  *
  * 合并原 tool-workflow.ts + tool-workflow-run.ts 为单 tool。
  *
@@ -9,12 +9,10 @@
  * - pause: 调 pauseRun
  * - resume: 调 resumeRun
  * - abort: 调 abortRun
- * - retry-node: 调 retryNode
- * - skip-node: 调 skipNode
  *
  * **restart 不包含**（D-9 废弃）。
  *
- * 层归属：Interface。依赖 Pi SDK + Engine lifecycle/node-ops/launcher + helpers。
+ * 层归属：Interface。依赖 Pi SDK + Engine lifecycle/launcher + helpers。
  *
  * 参考：domain-models.md §FR-5（tool 收口 4→2）。
  */
@@ -36,7 +34,6 @@ import type { LauncherDeps } from "../orchestration/launcher.ts";
 import { abortRun, pauseRun, resumeRun, runWorkflow } from "../orchestration/lifecycle.ts";
 import type { RunStore } from "../orchestration/models/ports.ts";
 import type { WorkflowRun } from "../orchestration/models/workflow-run.ts";
-import { retryNode, skipNode } from "../orchestration/node-ops.ts";
 import { mapRunIcon, mapRunStatus, toGuiCtx } from "./gui-mappers.ts";
 import {
   acquireReentryGuard,
@@ -54,9 +51,7 @@ export type WorkflowAction =
   | "status"
   | "pause"
   | "resume"
-  | "abort"
-  | "retry-node"
-  | "skip-node";
+  | "abort";
 
 const WORKFLOW_ACTIONS: readonly WorkflowAction[] = [
   "run",
@@ -64,8 +59,6 @@ const WORKFLOW_ACTIONS: readonly WorkflowAction[] = [
   "pause",
   "resume",
   "abort",
-  "retry-node",
-  "skip-node",
 ];
 
 const WorkflowParams = Type.Object({
@@ -82,10 +75,7 @@ const WorkflowParams = Type.Object({
     }),
   ),
   runId: Type.Optional(
-    Type.String({ description: "Workflow run ID (pause/resume/abort/retry-node/skip-node)" }),
-  ),
-  callId: Type.Optional(
-    Type.Number({ description: "Agent call ID (retry-node/skip-node)" }),
+    Type.String({ description: "Workflow run ID (pause/resume/abort)" }),
   ),
   args: Type.Optional(
     Type.Record(Type.String(), Type.Unknown(), {
@@ -151,8 +141,7 @@ interface RunSummary {
 export type WorkflowToolDetails =
   | { action: "run"; runId: string; status: "running" | "not_found"; name: string; slug?: string; stateFile?: string; __gui__?: GuiRenderResult }
   | { action: "status"; runs: RunSummary[]; __gui__?: GuiRenderResult }
-  | { action: "pause" | "resume" | "abort"; runId: string; status: string; reason?: string; __gui__?: GuiRenderResult }
-  | { action: "retry-node" | "skip-node"; runId: string; callId: number; __gui__?: GuiRenderResult };
+  | { action: "pause" | "resume" | "abort"; runId: string; status: string; reason?: string; __gui__?: GuiRenderResult };
 
 /** Result returned by the `workflow` tool's execute. */
 export interface ToolResult {
@@ -206,8 +195,8 @@ export function buildWorkflowGui(details: WorkflowToolDetails) {
       }),
     });
   }
-  // pause/resume/abort/retry-node/skip-node
-  // abort 是破坏性终止、pause 是挂起（非成功完成），用 warn 区分；resume/retry/skip 保留 ok
+  // pause/resume/abort
+  // abort 是破坏性终止、pause 是挂起（非成功完成），用 warn 区分；resume 保留 ok
   const severity = details.action === "abort" || details.action === "pause" ? "warn" as const : "ok" as const;
   return guiComponent("stats-line", {
     items: [{
@@ -221,7 +210,7 @@ export function buildWorkflowGui(details: WorkflowToolDetails) {
 // ── Tool registration ────────────────────────────────────────
 
 /**
- * 注册 workflow tool（7 actions）。
+ * 注册 workflow tool（5 actions: run / status / pause / resume / abort）。
  *
  * @param pi ExtensionAPI
  * @param deps LauncherDeps（LifecycleDeps + registry）
@@ -241,9 +230,7 @@ export function registerWorkflowTool(
     name: "workflow",
     label: "Workflow",
     description:
-      "Execute and control workflows: run (start), status, pause, resume, abort, " +
-      "retry-node (re-run a failed agent call to refresh its trace; does NOT resume the " +
-      "workflow script or change its output — see promptGuidelines), skip-node (mark a call as skipped).\n" +
+      "Execute and control workflows: run (start), status, pause, resume, abort.\n" +
       "Replaces workflow + workflow-run tools.",
     promptSnippet: "Run, pause, resume, abort, or check workflow status",
     promptGuidelines: [
@@ -259,15 +246,10 @@ export function registerWorkflowTool(
       "with source tags and descriptions. Then use this tool's run action to start one.",
       "run: discover by name/description, then start in background (no user confirmation needed).",
       "Do NOT poll status after starting — results appear automatically via notifyDone.",
-      "retry-node/skip-node: for specific failed agent calls (requires runId + callId). " +
-      "retry-node only re-runs the call and refreshes the trace — the workflow script has " +
-      "already moved past the failed call, so the new result does NOT feed back into the " +
-      "script flow. Use retry-node for diagnostics, not to resume the workflow.",
       "Call shapes (JSON): " +
       "- run: {\"action\":\"run\",\"name\":\"<script>\",\"args\":{...},\"tokens\":N,\"time\":N}. " +
       "- status: {\"action\":\"status\"}. " +
-      "- pause/resume/abort: {\"action\":\"pause\",\"runId\":\"<id>\"} (abort optional: ,\"error\":\"<reason>\"}). " +
-      "- retry-node/skip-node: {\"action\":\"retry-node\",\"runId\":\"<id>\",\"callId\":N}.",
+      "- pause/resume/abort: {\"action\":\"pause\",\"runId\":\"<id>\"} (abort optional: ,\"error\":\"<reason>\"}).",
       "Anti-patterns: Flattening args sub-fields (task/items/...) to the top level — they belong inside args. Calling {\"action\":\"run\"} without name.",
     ],
     parameters: WorkflowParams,
@@ -308,12 +290,6 @@ export function registerWorkflowTool(
           case "abort":
             result = await actionLifecycle("abort", params, deps);
             break;
-          case "retry-node":
-            result = await actionRetryNode(params, deps);
-            break;
-          case "skip-node":
-            result = await actionSkipNode(params, deps);
-            break;
           default: {
             // Exhaustiveness check — 新增 WorkflowAction 成员时未补 case，tsc 在此报错。
             const _exhaustive: never = action;
@@ -503,62 +479,6 @@ async function actionLifecycle(
   }
 }
 
-// ── retry-node / skip-node ───────────────────────────────────
-
-async function actionRetryNode(params: WorkflowToolParams, deps: LauncherDeps): Promise<ToolResult> {
-  const runId = params.runId;
-  const callId = params.callId;
-  if (!runId || callId === undefined) {
-    return textResult("retry-node requires 'runId' and 'callId'. Correct: {\"action\":\"retry-node\",\"runId\":\"<id>\",\"callId\":<number>}", true);
-  }
-  const run = deps.runs.get(runId);
-  if (!run) {
-    return textResult(
-      `Workflow '${runId}' not found. Use action:status to list active runs and their runIds.`,
-      true,
-    );
-  }
-  try {
-    await retryNode(run, callId, deps);
-    return {
-      content: [
-        { type: "text", text: `Retried call ${callId} in run ${runId.slice(0, RUNID_SHORT)}.` },
-      ],
-      details: { action: "retry-node", runId, callId },
-    };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return textResult(`Error: ${msg}`, true);
-  }
-}
-
-async function actionSkipNode(params: WorkflowToolParams, deps: LauncherDeps): Promise<ToolResult> {
-  const runId = params.runId;
-  const callId = params.callId;
-  if (!runId || callId === undefined) {
-    return textResult("skip-node requires 'runId' and 'callId'. Correct: {\"action\":\"skip-node\",\"runId\":\"<id>\",\"callId\":<number>}", true);
-  }
-  const run = deps.runs.get(runId);
-  if (!run) {
-    return textResult(
-      `Workflow '${runId}' not found. Use action:status to list active runs and their runIds.`,
-      true,
-    );
-  }
-  try {
-    await skipNode(run, callId, deps);
-    return {
-      content: [
-        { type: "text", text: `Skipped call ${callId} in run ${runId.slice(0, RUNID_SHORT)}.` },
-      ],
-      details: { action: "skip-node", runId, callId },
-    };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return textResult(`Error: ${msg}`, true);
-  }
-}
-
 // ── helpers ──────────────────────────────────────────────────
 
 /** WorkflowRun → 摘要（status action 用）。 */

package/src/orchestration/error-recovery.ts

@@ -492,8 +492,8 @@ function postAgentResult(
  * 更新 spent()/remaining()）。每次 agent 调用消费 usage 后发送，保持 worker 内 $BUDGET
  * 与主线程 Budget 值对象同步。
  *
- * D-12 regression fix (round-2 #1)：重建 budget-update 发送方。被 error-recovery（dispatch
- * 后）和 node-ops（retry/skip 后）共用——单一实现，避免消息形状漂移。
+ * D-12 regression fix (round-2 #1)：重建 budget-update 发送方。被 error-recovery 主路径调用
+ * （dispatch 后同步 worker $BUDGET）——单一实现，避免消息形状漂移。
  */
 export function postBudgetUpdate(run: WorkflowRun): void {
   run.runtime?.worker.postMessage({

package/src/orchestration/models/ports.ts

@@ -5,7 +5,7 @@
  * 是真需要 mock 测试的依赖（子进程/文件系统/线程）。
  *
  * 编排层共享类型（WorkerHandlers / LifecycleDeps）——打破 lifecycle ↔
- * error-recovery ↔ node-ops 循环依赖：3 个 engine 函数文件各自独立，共用同一组
+ * error-recovery 循环依赖：2 个 engine 函数文件各自独立，共用同一组
  * 依赖签名（D-12）。
  *
  * 层归属：Engine。零 infra 依赖（AC-1）。
@@ -72,7 +72,7 @@ export interface WorkerHost {
 
 /**
  * Worker 线程事件回调集合——WorkerHost.start 的入参，由 lifecycle
- * 构造并注入。3 个 engine 文件（lifecycle / error-recovery / node-ops）共用此签名，
+ * 构造并注入。2 个 engine 文件（lifecycle / error-recovery）共用此签名，
  * 避免各自定义形状不一致的 handler bag（打破循环依赖）。
  *
  * 所有回调返回 Promise——允许 engine 层在回调内做 await persistState 等异步操作。
@@ -89,7 +89,7 @@ export interface WorkerHandlers {
 // ── 编排层共享类型 2: LifecycleDeps ────────────────────────────
 
 /**
- * lifecycle / error-recovery / node-ops 3 个 engine 函数文件的共同依赖 bag。
+ * lifecycle / error-recovery 2 个 engine 函数文件的共同依赖 bag。
  *
  * 取代旧 4 个 Context factory（errorHandlerContext / agentCallContext /
  * budgetCallbacks / 旧 terminate bag，AC-2 目标）。函数签名 `(deps: LifecycleDeps, ...)`

package/src/orchestration/models/workflow-run.ts

@@ -23,7 +23,7 @@
  * （runtime=undefined）。AbortController 一次性无法复用。
  * - resume 走 assignRuntime(new RunRuntime(...))，重建 worker/gate/controller。
  *
- * retryNode / worker-error-retry（G5-001 + G6-001）：
+ * worker-error-retry（G5-001 + G6-001）：
  * - replaceRuntime(newRt): 前置 status==="running"（G6-001），原子释放前一个 runtime
  * + 绑定新 runtime，全程保持不变式 I1（中间不经过 runtime===undefined 的可见状态）。
  * - paused 状态下 retry 被拒（要 retry 先 resume）。
@@ -243,11 +243,11 @@ export class WorkflowRun {
     this.runtime.release("pause");
     this.runtime = undefined;
  // 不改 status——调用方（transition）负责。独立调用时调用方需自行确保
- // status 一致（如 retryNode 用 replaceRuntime 而非 release+assign）。
+ // status 一致（如 worker-error-retry 用 replaceRuntime 而非 release+assign）。
   }
 
  /**
- * 原地替换 runtime（G5-001：retryNode / worker-error-retry）。
+ * 原地替换 runtime（G5-001：worker-error-retry）。
  *
  * 前置：status==="running"（G6-001：paused 下拒绝，要 retry 先 resume）。
  * 原子地：释放旧 runtime（worker.terminate + abort）+ 绑定新 runtime，

package/src/orchestration/worker-script-builder.ts

@@ -116,7 +116,7 @@ export function buildWorkerScript(userScript: string): string {
     '        // 把单点失败放大成整批崩溃。改为始终 resolve（错误时回退到 content 文本），',
     '        // 让 parallel() 下的脚本容错循环（parseResult → null → skip）自然接管。',
     '        // 错误原因已由主线程 executeAgentCall → trace.update(result.error) 保留在 trace/TUI，',
-    '        // 不丢失。skipNode 的 SKIP_PLACEHOLDER（无 error，resolve 为 ""）已确立此先例。',
+    '        // 不丢失。失败 resolve 为空字符串是既定容错策略。',
     '        // parsedOutput: validated data object from structured-output execute().',
     '        // Fallback to content (raw text) when no schema was requested or on error.',
     '        pending.resolve(msg.result.parsedOutput ?? msg.result.content);',

package/src/orchestration/node-ops.ts

@@ -1,194 +0,0 @@
-/**
- * Workflow Extension — node-ops
- *
- * 单节点操作 free functions（D-12）。
- *
- * 2 个导出函数：
- * - retryNode(run, callId, deps) — 重置 call + 主线程重跑（不 replaceRuntime）
- * - skipNode(run, callId, deps) — 标记 call done + 占位 result
- *
- * **D.5（方案 A）**：retryNode 的语义是「重试单个失败 call」——只重置 call 状态 +
- * 主线程直接调 executeAgentCall，worker 不重启，已完成调用不受影响（worker 重启是
- * worker-error-retry handleWorkerError 的语义，不在本职责内）。
- *
- * **retryNode 不影响脚本流程**：worker 在首次失败结果被 postAgentResult 投递后即
- * resolve 并删除该 callId 的 pending Promise（worker-script-builder agent-result 分支）。
- * retryNode 的二次 postMessage 因此被 worker 丢弃——新结果只更新 trace/TUI，
- * 回不到脚本（脚本早已带着首次结果往下走）。这是 D.5「不重启 worker」的直接后果：
- * 要让新结果回到脚本必须重启 worker 重跑整个脚本（旧 orchestrator.ts 语义），
- * 与「不干扰已完成调用」的设计意图冲突。故 retryNode 定位为「失败节点的诊断性重跑
- * + trace 刷新」，不承诺改变脚本输出。tool-workflow 的描述已如实声明此语义。
- *
- * **G6-001**：retryNode 前置 status==="running"（paused 下拒绝，要 retry 先 resume）。
- *
- * 层归属：Engine。依赖 LifecycleDeps + WorkflowRun + executeAgentCall。
- *
- * 参考：domain-models.md §失败处理矩阵（retryNode 语义）、clarification.md D.5/G6-001。
- */
-
-import { postBudgetUpdate } from "./error-recovery.ts";
-import { executeAgentCall } from "./execute-agent-call.ts";
-import type { LifecycleDeps } from "./models/ports.ts";
-import type { AgentResult } from "./models/types.ts";
-import type { WorkflowRun } from "./models/workflow-run.ts";
-
-// ── skipNode 占位结果 ────────────────────────────────────────
-
-/** skipNode 注入的占位结果（零 usage，避免污染 budget）。 */
-const SKIP_PLACEHOLDER: AgentResult = {
-  content: "",
-  usage: {
-    input: 0,
-    output: 0,
-    cacheRead: 0,
-    cacheWrite: 0,
-    cost: 0,
-    contextTokens: 0,
-    turns: 0,
-  },
-};
-
-// ── retryNode ────────────────────────────────────────────────
-
-/**
- * 重试单个失败 agent call（诊断性重跑 + trace 刷新，不影响脚本流程）。
- *
- * **D.5 修复**：不 replaceRuntime、不重启 worker。只重置 call 状态（status=pending,
- * attempts=0, result=undefined）+ 同步 trace 节点 + 主线程直接调 executeAgentCall。
- * worker 仍在运行，已完成调用不受影响。
- *
- * **结果不回到脚本**：见文件头说明——worker 在首次失败结果投递后已 resolve 并删除
- * 该 callId 的 pending Promise，本函数末尾的 postMessage 通常被 worker 丢弃。新结果
- * 只反映在 trace/TUI，不改变脚本输出（若需让脚本拿新结果，须重启 worker 重跑整个
- * 脚本，与 D.5 冲突，未采用）。
- *
- * 与 worker-error-retry的区别：
- * - handleWorkerError：worker 本身崩溃 → replaceRuntime 重启整个 worker
- * - retryNode：单个 call 失败 → 主线程重跑该 call，worker 不动
- *
- * **G6-001**：前置 status==="running"。paused 下抛错（要 retry 先 resume）。
- *
- * @param run WorkflowRun 聚合根
- * @param callId 要重试的 call id（必须已存在于 run.state.calls）
- * @param deps LifecycleDeps（runner 用于重跑 call）
- * @throws run.state.status !== "running"（G6-001）
- * @throws callId 不存在
- */
-export async function retryNode(
-  run: WorkflowRun,
-  callId: number,
-  deps: LifecycleDeps,
-): Promise<void> {
- // G6-001：前置 status==="running"
-  if (run.state.status !== "running") {
-    throw new Error(
-      `retryNode: requires status==="running" (current: ${run.state.status}, runId=${run.runId})`,
-    );
-  }
-
-  const call = run.state.calls.get(callId);
-  if (!call) {
-    throw new Error(`retryNode: call ${callId} not found in run ${run.runId}`);
-  }
-
- // 重置 call 状态：done → pending（绕过 AgentCall 状态机守卫，因为是显式 reset 语义）
-  call.status = "pending";
-  call.attempts = 0;
-  call.result = undefined;
-  call.sessionId = undefined;
-  call.sessionFile = undefined;
-
- // 同步 trace 节点：回退到 pending
-  run.state.trace.update(callId, {
-    status: "pending",
-    result: undefined,
-    error: undefined,
-    completedAt: undefined,
-    sessionId: undefined,
-    sessionFile: undefined,
-  });
-
- // 主线程重跑（不重启 worker）——executeAgentCall 内部 markRunning + runner.run
- // G6-001 保证 status==="running" ⟺ runtime defined；retryNode 已守 status==="running"
- // 前置，故 run.runtime 必存在。非空断言，不再用 fallback 掩盖不变式违反。
-  const signal = run.runtime!.controller.signal;
-  await executeAgentCall(call, deps.runner, run.state.budget, signal, run.state.trace);
-
- // 回发结果给 worker（best-effort：worker 通常已在首次失败结果投递后 resolve 并删除
- // 该 callId 的 pending Promise，故本 postMessage 多被丢弃——见文件头 D.5 说明）。
- // 保留是为覆盖「executeAgentCall 已完成但 dispatchAgentCall.then 尚未投递结果」的
- // 极窄竞态窗口，以及与 skipNode 的回发路径对称。结果无论如何都已写入 trace/TUI。
-  if (call.result) {
-    run.runtime?.worker.postMessage({
-      type: "agent-result",
-      callId,
-      result: call.result,
-      cached: false,
-    });
-  }
-
- // D-12 regression fix (round-2 #1)：retry 重跑消费 usage 后同步 worker $BUDGET
-  postBudgetUpdate(run);
-
-  await deps.store.save(run);
-}
-
-// ── skipNode ─────────────────────────────────────────────────
-
-/**
- * 跳过单个 agent call（注入占位 result）。
- *
- * 标记 call.status="done" + 写入 SKIP_PLACEHOLDER result + 同步 trace 节点为 completed。
- * 若 worker 仍活着，立即回发 agent-result（解锁 worker pending await）。
- *
- * 与 retryNode 的区别：skipNode 不重跑——直接用占位结果「假装完成」。
- * 用于用户显式跳过失败节点继续执行的场景。
- *
- * 不要求 status==="running"——paused 下也可 skip（标记后 resume 时该 call 走 callCache
- * replay）。但若 worker 已 terminate（runtime undefined），只标记不回发。
- *
- * @param run WorkflowRun 聚合根
- * @param callId 要跳过的 call id（若不存在，仅注入到 calls Map 占位）
- * @param deps LifecycleDeps（store 持久化）
- */
-export async function skipNode(
-  run: WorkflowRun,
-  callId: number,
-  deps: LifecycleDeps,
-): Promise<void> {
-  const call = run.state.calls.get(callId);
-
-  if (call) {
- // 已有 call：标记 done + 占位 result（绕过状态机守卫，显式 skip 语义）
-    call.status = "done";
-    call.result = SKIP_PLACEHOLDER;
-  }
-
- // 同步 trace 节点
-  run.state.trace.update(callId, {
-    status: "completed",
-    result: SKIP_PLACEHOLDER,
-    completedAt: new Date().toISOString(),
-  });
-
- // 若 worker 仍活着，回发 agent-result（解锁 worker pending await）
-  if (run.runtime) {
-    try {
-      run.runtime.worker.postMessage({
-        type: "agent-result",
-        callId,
-        result: SKIP_PLACEHOLDER,
-        cached: true,
-      });
-    } catch (err) {
- // P1-8: worker 可能在 has 与 postMessage 间 exit——预期竞态，不恢复
-      void err;
-    }
-  }
-
- // D-12 regression fix (round-2 #1)：skip 后同步 worker $BUDGET（占位 result 零 usage，
- // 值不变，但保持 $BUDGET 与主线程一致）
-  postBudgetUpdate(run);
-
-  await deps.store.save(run);
-}