@zhushanwen/pi-subagent-workflow 0.1.0

package/src/orchestration/worker-handle.ts

@@ -0,0 +1,115 @@
+/**
+ * Workflow Extension — Worker Handle
+ *
+ * node:worker_threads.Worker 的线程句柄封装。技术资源，Infra 层具体类（D-12）。
+ * RunRuntime 直接持有，不经 interface（§domain-models 9）。
+ *
+ * 核心职责：竞态防护（G-025）。
+ *
+ * 背景：一个 run 可经历多个 WorkerHandle（pause/resume/retry 各换一个）。
+ * 需防止「terminate(old) → start(new) → old exit fires」竞态——
+ * WorkerHandle 把守卫内化：terminate 后 isCurrent=false，
+ * 已终止 handle 的 onMessage/onError/onExit 回调自动 no-op（无需调用方比对引用）。
+ *
+ * 层归属：Infra（D-12）。仅依赖 node:worker_threads（Node 原生）。
+ */
+
+import { type Worker } from "node:worker_threads";
+
+// ── Handler signatures ───────────────────────────────────────
+
+/** Worker → Main 业务消息回调。 */
+export type WorkerMessageHandler = (raw: unknown) => void;
+/** Worker 线程 uncaught error 回调。 */
+export type WorkerErrorHandler = (err: Error) => void;
+/** Worker 线程 exit 回调（code=0 正常退出，非 0 崩溃）。 */
+export type WorkerExitHandler = (code: number) => void;
+
+// ── WorkerHandle ──────────────────────────────────────────────
+
+export class WorkerHandle {
+  private readonly worker: Worker;
+ /**
+ * 竞态守卫。true = 此 handle 仍是当前活动 handle；false = 已 terminate，
+ * 后续事件（已终止 worker 延迟触发的 message/error/exit）必须忽略。
+ *
+ * 终止后置 false 并永不回升（幂等语义）。新 handle 由调用方（WorkerHost）
+ * 重新创建，已终止 handle 留在内存里直到 GC，但其回调全部 no-op。
+ */
+  private current = true;
+
+  constructor(worker: Worker) {
+    this.worker = worker;
+  }
+
+ /** 此 handle 是否仍是当前活动 handle（terminate 后 false，G-025）。 */
+  get isCurrent(): boolean {
+    return this.current;
+  }
+
+ /** 底层 Worker（WorkerHost/RunRuntime 偶尔需要直接访问，如 ref/href）。 */
+  get raw(): Worker {
+    return this.worker;
+  }
+
+ /**
+ * 向 worker 发送消息。terminate 后 no-op（已终止 handle 的 postMessage 无意义）。
+ */
+  postMessage(msg: unknown): void {
+    if (!this.current) return;
+    this.worker.postMessage(msg);
+  }
+
+ /**
+ * 终止 worker 线程。幂等——重复调用安全，第二次起 no-op。
+ * 置 isCurrent=false 后再 await worker.terminate，确保并发 exit 事件
+ * 在 terminate resolve 之前到达时也被守卫拦下。
+ */
+  async terminate(): Promise<void> {
+    if (!this.current) return;
+    this.current = false;
+    try {
+      await this.worker.terminate();
+    } catch (err) {
+ // terminate 失败不阻断（worker 可能已退出）。current 已 false，安全。
+ // 不向上抛——调用方（RunRuntime.release）不应被底层线程错误打断。
+      void err;
+    }
+  }
+
+ /**
+ * 绑定 message 回调。仅当 isCurrent 时触发——已终止 handle 的事件被吞掉。
+ * 返回 this 便于链式 onMessage(...).onError(...).onExit(...)。
+ */
+  onMessage(handler: WorkerMessageHandler): this {
+    this.worker.on("message", (raw: unknown) => {
+      if (!this.current) return;
+      handler(raw);
+    });
+    return this;
+  }
+
+ /**
+ * 绑定 error 回调。仅当 isCurrent 时触发。
+ */
+  onError(handler: WorkerErrorHandler): this {
+    this.worker.on("error", (err: Error) => {
+      if (!this.current) return;
+      handler(err);
+    });
+    return this;
+  }
+
+ /**
+ * 绑定 exit 回调。仅当 isCurrent 时触发——这是 G-025 的关键守卫：
+ * terminate(old) → startWorker(new) → old exit 触发时，old handle.current
+ * 已为 false，回调 no-op，不会误删 new worker。
+ */
+  onExit(handler: WorkerExitHandler): this {
+    this.worker.on("exit", (code: number) => {
+      if (!this.current) return;
+      handler(code);
+    });
+    return this;
+  }
+}

package/src/orchestration/worker-host.ts

@@ -0,0 +1,93 @@
+/**
+ * Workflow Extension — Worker Host
+ *
+ * WorkerHost port 的 Infra 实现。
+ *
+ * 职责：启动一个 Worker thread 运行 workflow 脚本，返回 WorkerHandle，
+ * 并把 worker 的 message/error/exit 事件绑定到调用方注入的 WorkerHandlers。
+ *
+ * 层归属：Infra（D-12）。implements Engine 层的 WorkerHost port。
+ *
+ * 设计：
+ * - WorkerHostImpl implements WorkerHost（而非散落的 free function）。
+ * - 返回 WorkerHandle（封装），而非裸 Worker——onExit 传 handle 给
+ * handlers.onExit(code, handle)，调用方用 handle.isCurrent 做竞态防护（C.3 + G-025）。
+ * - eval:true + 内联 buildWorkerScript 源码字符串（C.2：不用不存在的 bootstrap 文件）。
+ * - workerData: { scriptPath, args, workspace, meta }（不含 callCache/budget——
+ * 这些是 RunState 字段，由 lifecycle 在调用 start 前注入到 args 或独立处理）。
+ * - temp file 清理逻辑移到 Engine lifecycle，本处不管。
+ */
+
+import { Worker } from "node:worker_threads";
+
+import type { WorkerHandlers, WorkerHost } from "./models/ports.ts";
+import type { RunSpec } from "./models/run-spec.ts";
+import { WorkerHandle } from "./worker-handle.ts";
+import { buildWorkerScript } from "./worker-script-builder.ts";
+
+// ── WorkerHostImpl ───────────────────────────────────────────
+
+export class WorkerHostImpl implements WorkerHost {
+ /**
+ * 启动一个 Worker thread 运行 workflow 脚本。
+ *
+ * 1. 用 buildWorkerScript(spec.scriptSource) 包装用户脚本（注入 agent/parallel/
+ * pipeline/$ARGS/$BUDGET 等全局，AC-4 格式契约由 buildWorkerScript 保证）
+ * 2. new Worker(code, { eval: true, workerData })（C.2 修复：eval 内联源码，
+ * 不 require bootstrap 文件）
+ * 3. 包装为 WorkerHandle，绑定 onMessage/onError/onExit 回调到 handlers
+ * 4. onExit 传 handle 给 handlers.onExit(code, handle)（C.3 修复——调用方用
+ * handle.isCurrent 做竞态防护，G-025）
+ *
+ * 返回的 WorkerHandle 由调用方（lifecycle）保存到 RunRuntime.worker。
+ * 终止/pause/resume 时由 RunRuntime.release 接管。
+ */
+  start(
+    spec: RunSpec,
+    args: Record<string, unknown>,
+    handlers: WorkerHandlers,
+  ): WorkerHandle {
+    const workerCode = buildWorkerScript(spec.scriptSource);
+
+    const worker = new Worker(workerCode, {
+      eval: true,
+      workerData: {
+        scriptPath: spec.scriptPath,
+        args,
+        workspace: process.cwd(),
+        meta: {
+          name: spec.scriptName,
+          description: spec.description,
+        },
+ // D-12 regression fix (round-2 #1)：注入 budget，否则 worker 内 $BUDGET.total 恒为 0。
+ // 旧 agent-call-handler.ts 删除时同时丢失了 budget 注入和 budget-update 发送方，
+ // 导致依赖 $BUDGET 做动态预算分支的脚本静默得到全 0。
+        budget: {
+          maxTokens: spec.budgetTokens,
+          usedTokens: 0,
+          usedCost: 0,
+        },
+      },
+    });
+
+    const handle = new WorkerHandle(worker);
+
+ // 绑定事件——WorkerHandle 内部用 isCurrent 守卫，terminate 后回调 no-op（G-025）。
+ // handlers 的 onMessage/onError/onExit 都是 async，这里 void 掉 promise（worker 事件
+ // 不能 await，且 handler 内部错误由 lifecycle 统一捕获）。
+    handle.onMessage((raw) => {
+      void handlers.onMessage(raw);
+    });
+    handle.onError((err) => {
+      void handlers.onError(err);
+    });
+    handle.onExit((code) => {
+ // C.3 修复：传 handle 给 onExit，调用方用 handle.isCurrent 做竞态防护。
+ // 注意：此时 handle.isCurrent 仍为 true（onExit 回调仅在 isCurrent 时触发，
+ // WorkerHandle 的内部守卫已过滤掉 terminate 后的 stale exit）。
+      void handlers.onExit(code, handle);
+    });
+
+    return handle;
+  }
+}

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

@@ -0,0 +1,281 @@
+/**
+ * Workflow Extension — Worker Script Builder
+ *
+ * 生成运行 workflow 脚本的 Worker 线程源码字符串：注入全局函数
+ * agent/parallel/pipeline/phase/log，并在 worker 内部处理
+ * parentPort 消息循环（agent-call / agent-result / abort / budget-update）。
+ *
+ * 层归属：Infra（源码字符串生成，纯文本拼接，无 Pi 依赖）。
+ *
+ * 设计：
+ * - WorkerLogEntry 类型来源 engine/models/types.js（不在本文件重复声明）。
+ * - **AC-4 不变式**：buildWorkerScript 生成的脚本格式逐字保留——
+ * 用户资产（workflow 脚本依赖 agent/parallel/pipeline/$ARGS/$BUDGET 等契约）。
+ *
+ * 兼容 Claude Code Workflow 脚本格式：
+ * - agent(promptString) / agent(promptString, { label?, schema?, model?, scene? }) /
+ * agent({ prompt, schema?, model?, scene?, description? })
+ * - parallel([agent(...), ...]) 或 parallel([{ task, agent }, ...])
+ * - pipeline([stageFn, ...])
+ * - phase(name), log(msg)
+ * - $ARGS, $WORKSPACE, $BUDGET
+ * - module.exports = { meta, execute } 自动调用
+ *
+ * 生成的源码通过 `new Worker(code, { eval: true, workerData })` 在隔离的 Worker 线程运行。
+ *
+ * 通信协议（AC-4 契约，逐字保留）：
+ * Worker → Main (postMessage):
+ * { type: "agent-call", callId: number, opts: AgentCallOpts }
+ * { type: "workflow-call", callId: number, name: string, args: Record<string, unknown> }
+ * { type: "return", runId: string, result: unknown }
+ * { type: "error", runId: string, error: string }
+ * { type: "log", phase: string, message: string }
+ *
+ * Main → Worker (parentPort.on("message")):
+ * { type: "agent-result", callId: number, result: AgentResult, cached: boolean }
+ * { type: "workflow-result", callId: number, result: unknown }
+ * { type: "budget-update", budget: unknown }
+ * { type: "abort", reason: string }
+ */
+
+// ── Build worker source ─────────────────────────────────────
+
+/**
+ * Build the complete worker source text by wrapping the user's workflow script
+ * with infrastructure code and injected global functions.
+ *
+ * AC-4：脚本格式不变（用户资产）。逐字保留旧 buildWorkerScript 的拼接逻辑。
+ */
+export function buildWorkerScript(userScript: string): string {
+  return [
+    '"use strict";',
+    '// Module-scope: accessible to the outer .catch() for surfacing logs on errors.',
+    'const _workerLogs = [];',
+    'function _pushWorkerLog(level, args) {',
+    '  try { _workerLogs.push({ level, message: args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ") }); } catch (e) { /* swallow */ }',
+    '}',
+    '(async () => {',
+    '  const { parentPort, workerData } = require("node:worker_threads");',
+    '',
+    '  if (!parentPort) {',
+    '    throw new Error("Workflow worker: parentPort is null — not running in a Worker thread");',
+    '  }',
+    '',
+    '  // ── Intercept console.* to avoid leaking worker diagnostics into the input area ──',
+    '  // _workerLogs + _pushWorkerLog are declared at module scope (above the IIFE)',
+    '  // so the outer .catch() can include them on script errors.',
+    '  console.log = function (...args) { _pushWorkerLog("log", args); };',
+    '  console.warn = function (...args) { _pushWorkerLog("warn", args); };',
+    '  console.error = function (...args) { _pushWorkerLog("error", args); };',
+    '  console.info = function (...args) { _pushWorkerLog("info", args); };',
+    '',
+    '  // ── Internal state ──',
+    '  let _callIdCounter = 0;',
+    '  let _agentCallCount = 0;',
+    '  const _pendingCalls = new Map();',
+    '  const _callCache = workerData.callCache instanceof Map',
+    '    ? workerData.callCache',
+    '    : new Map(Object.entries(workerData.callCache || {}).map(([k, v]) => [Number(k), v]));',
+    '',
+    '  // ── Injected globals ──',
+    '  const $ARGS = (workerData.args && typeof workerData.args === "object") ? workerData.args : {};\n' +
+      '  const args = $ARGS;',
+    '  const $WORKSPACE = typeof workerData.workspace === "string" ? workerData.workspace : "";',
+    '  const _budgetData = {',
+    '    total: (workerData.budget && workerData.budget.maxTokens) || 0,',
+    '    _spentTokens: (workerData.budget && workerData.budget.usedTokens) ?? 0,',
+    '    _spentCost: (workerData.budget && workerData.budget.usedCost) ?? 0,',
+    '  };',
+    '  const $BUDGET = {',
+    '    get total() { return _budgetData.total; },',
+    '    spent() { return _budgetData._spentTokens; },',
+    '    remaining() { return Math.max(0, _budgetData.total - _budgetData._spentTokens); },',
+    '  };',
+    '',
+    '  // ── WorkflowAbortedError ──',
+    '  class WorkflowAbortedError extends Error {',
+    '    constructor(reason) {',
+    '      super("Workflow aborted: " + (reason || "No reason"));',
+    '      this.name = "WorkflowAbortedError";',
+    '      this.reason = reason || "";',
+    '    }',
+    '  }',
+    '',
+    '  // ── Message handler (main thread → worker) ──',
+    '  parentPort.on("message", (msg) => {',
+    '    if (msg.type === "agent-result") {',
+    '      const pending = _pendingCalls.get(msg.callId);',
+    '      if (pending) {',
+    '        _pendingCalls.delete(msg.callId);',
+    '        if (typeof msg.result !== "undefined") {',
+    '          _callCache.set(msg.callId, msg.result);',
+    '        }',
+    '        // 失败不传播到 agent 外部：resolve 而非 reject。',
+    '        // 旧实现在 result.error 时 reject，单 agent 失败会冒到 worker 顶层 .catch()',
+    '        // → 发 type:"error" → handleScriptError → rebuildRuntime → SIGKILL 同伴进程，',
+    '        // 把单点失败放大成整批崩溃。改为始终 resolve（错误时回退到 content 文本），',
+    '        // 让 parallel() 下的脚本容错循环（parseResult → null → skip）自然接管。',
+    '        // 错误原因已由主线程 executeAgentCall → trace.update(result.error) 保留在 trace/TUI，',
+    '        // 不丢失。skipNode 的 SKIP_PLACEHOLDER（无 error，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);',
+    '      }',
+    '    } else if (msg.type === "workflow-result") {',
+    '      const pending = _pendingCalls.get(msg.callId);',
+    '      if (pending) {',
+    '        _pendingCalls.delete(msg.callId);',
+    '        pending.resolve(msg.result);',
+    '      }',
+    '    } else if (msg.type === "abort") {',
+    '      const err = new WorkflowAbortedError(msg.reason);',
+    '      _pendingCalls.forEach((p) => { p.reject(err); });',
+    '      _pendingCalls.clear();',
+    '    } else if (msg.type === "budget-update" && msg.budget) {',
+    '      _budgetData._spentTokens = msg.budget.usedTokens ?? _budgetData._spentTokens;',
+    '      _budgetData._spentCost = msg.budget.usedCost ?? _budgetData._spentCost;',
+    '    }',
+    '    // "budget-warning" is informational; no required handling',
+    '  });',
+    '',
+ // ── phase global ──
+    '  let _currentPhase = "";',
+    '  function phase(name) { _currentPhase = String(name); }',
+    '',
+ // ── log global ──
+    '  function log(msg) {',
+    '    try { parentPort.postMessage({ type: "log", phase: _currentPhase, message: String(msg) }); } catch(e) { /* swallow */ }',
+    '  }',
+    '',
+ // ── agent global — CC-compatible multi-signature ──
+    '  async function agent(firstArg, secondArg) {',
+    '    let opts;',
+    '    if (typeof firstArg === "string") {',
+    '      opts = {',
+    '        prompt: firstArg,',
+    '        description: (secondArg && typeof secondArg === "object" && secondArg.label) || undefined,',
+    '        schema: (secondArg && typeof secondArg === "object" && secondArg.schema) || undefined,',
+    '        model: (secondArg && typeof secondArg === "object" && secondArg.model) || undefined,',
+    '        scene: (secondArg && typeof secondArg === "object" && secondArg.scene) || undefined,\n' +
+      '        phase: (secondArg && typeof secondArg === "object" && secondArg.phase) || undefined,',
+    '      };',
+    '    } else if (typeof firstArg === "object" && firstArg !== null) {',
+    '      if (firstArg.prompt) {',
+    '        opts = firstArg;',
+    '      } else if (firstArg.task || firstArg.agent) {',
+    '        opts = {',
+    '          prompt: firstArg.task || firstArg.prompt || "",',
+    '          description: firstArg.label || firstArg.description,',
+    '          agent: firstArg.agent,',
+    '          schema: firstArg.schema,',
+    '          model: firstArg.model,',
+    '          scene: firstArg.scene,',
+    '          timeoutMs: firstArg.timeoutMs,',
+    '          cwd: firstArg.cwd,',
+    '        };',
+    '      } else {',
+    '        opts = firstArg;',
+    '      }',
+    '    } else {',
+    '      throw new Error("agent() requires a prompt string or options object as first argument");',
+    '    }',
+    '',
+    '    // Validate known agent() fields to catch API misuse early',
+    '    const _knownFields = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd"]);',
+    '    const _unknownFields = Object.keys(opts).filter((k) => !_knownFields.has(k));',
+    '    if (_unknownFields.length > 0) {',
+    '      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd"]);',
+    '    }',
+    '',
+    '    const callId = _callIdCounter;',
+    '    _callIdCounter++;',
+    '    _agentCallCount++;',
+    '    if (_callCache.has(callId)) {',
+    '      const cached = _callCache.get(callId);',
+    '      // 与 live handler 对齐：失败也 resolve（回退 content），不 throw。',
+    '      // 见 agent-result 消息处理的注释：拒绝传播失败到 agent 外部。',
+    '      return cached ? (cached.parsedOutput ?? cached.content) : undefined;',
+    '    }',
+    '',
+    '    const _effectivePhase = opts.phase || _currentPhase;\n' +
+      '    delete opts.phase;\n' +
+      '\n' +
+      '    parentPort.postMessage({ type: "agent-call", callId, opts, phase: _effectivePhase });',
+    '    return new Promise((resolve, reject) => {',
+    '      _pendingCalls.set(callId, { resolve, reject });',
+    '    });',
+    '  }',
+    '',
+ // ── parallel global — CC-compatible ──
+    // allSettled 语义：单个 agent 的意外 reject（postMessage 失败等基础设施异常、abort）
+    // 不拖垮整批。rejected 结果降级为错误消息字符串（与 agent() 的 error→content 回退一致，
+    // parseResult(string) → null → 脚本 soft-fail）。B1 之后 agent() 不再因 agent 失败 reject，
+    // 这里作为纵深防御保留。
+    '  async function parallel(calls) {',
+    '    if (typeof calls === "function") { return calls(); }',
+    '    const settled = await Promise.allSettled(calls.map((c) => {',
+    '      if (typeof c === "function") { return c(); }',
+    '      if (typeof c === "object" && c !== null && (c.task || c.agent)) { return agent(c); }',
+    '      return agent(c);',
+    '    }));',
+    '    return settled.map((r) => r.status === "fulfilled" ? r.value : (r.reason instanceof Error ? r.reason.message : String(r.reason)));',
+    '  }',
+    '',
+ // ── pipeline global ──
+    '  async function pipeline(firstArg, ...restStages) {',
+    '    // Single-arg mode: pipeline([stage1, stage2, ...])',
+    '    if (Array.isArray(firstArg) && restStages.length === 0) {',
+    '      let result;',
+    '      for (const stage of firstArg) { result = await stage(result); }',
+    '      return result;',
+    '    }',
+    '    // Cartesian product mode: pipeline([items], stage1, stage2, ...)',
+    '    if (Array.isArray(firstArg) && restStages.length > 0 && typeof restStages[0] === "function") {',
+    '      const results = [];',
+    '      for (const item of firstArg) {',
+    '        let val = item;',
+    '        let failed = false;',
+    '        for (const stage of restStages) {',
+    '          if (failed) break;',
+    '          try { val = await stage(val); }',
+    '          catch (e) { val = null; failed = true; }',
+    '        }',
+    '        results.push(val);',
+    '      }',
+    '      return results;',
+    '    }',
+    '    throw new Error("pipeline() expects pipeline([stage1, ...]) or pipeline([items], stage1, ...)");',
+    '  }',
+    '',
+    '  // ── workflow global — nested workflow invocation ──',
+    '  async function workflow(name, args) {',
+    '    if (typeof name !== "string" || name.length === 0) {',
+    '      throw new Error("workflow() requires a workflow name string as first argument");',
+    '    }',
+    '    const workflowArgs = (typeof args === "object" && args !== null) ? args : {};',
+    '    const callId = _callIdCounter;',
+    '    _callIdCounter++;',
+    '    parentPort.postMessage({ type: "workflow-call", callId, name, args: workflowArgs });',
+    '    return new Promise((resolve, reject) => {',
+    '      _pendingCalls.set(callId, { resolve, reject });',
+    '    });',
+    '  }',
+    '',
+    '  // ── User workflow script ──',
+    '  ' + userScript,
+    '',
+    '  // ── Auto-invoke execute() for module.exports pattern ──',
+    '  if (typeof module !== "undefined" && module.exports && typeof module.exports.execute === "function") {',
+    '    return await module.exports.execute({ agent, parallel, pipeline, phase, log, workflow, $ARGS, $WORKSPACE, $BUDGET });',
+    '  }',
+    '})().then((result) => {',
+    '  const { parentPort, workerData } = require("node:worker_threads");',
+    '  const runId = (workerData.args && typeof workerData.args === "object" && workerData.args._runId) || "";',
+    '  parentPort.postMessage({ type: "return", runId, result, workerLogs: _workerLogs });',
+    '}).catch((err) => {',
+    '  const { parentPort, workerData } = require("node:worker_threads");',
+    '  const runId = (workerData.args && typeof workerData.args === "object" && workerData.args._runId) || "";',
+    '  parentPort.postMessage({ type: "error", runId, error: err.message || String(err), workerLogs: _workerLogs });',
+    '});',
+  ].join("\n");
+}

package/src/orchestration/workflow-files.ts

@@ -0,0 +1,85 @@
+/**
+ * Workflow 文件持久化操作（save / delete）。
+ *
+ * 历史：saveWorkflow 曾有两套实现——commands.ts 用 renameSync 仅 project scope，
+ * WorkflowsView.ts 用 copyFileSync 支持 user scope。本次统一为 rename + 仅 project
+ * scope（决策 2）：tmp 文件保存后自动消失，保存位置固定 .pi/workflows/。
+ *
+ * 代价：TUI 失去 user scope Tab 切换（功能倒退，已接受）；
+ * Windows/跨设备 rename 可能失败（已知风险，接受）。
+ */
+
+import { existsSync, mkdirSync, renameSync, unlinkSync } from "node:fs";
+import { resolve } from "node:path";
+
+// ── Path helpers (computed at call time to respect cwd changes in tests) ──
+
+function getTmpDir(): string {
+  return resolve(".pi/workflows/.tmp");
+}
+
+function getSavedDir(): string {
+  return resolve(".pi/workflows");
+}
+
+// ── Save ──────────────────────────────────────────────────────
+
+/**
+ * 保存临时 workflow：.pi/workflows/.tmp/{name}.js → .pi/workflows/{newName||name}.js
+ * 用 rename（tmp 文件保存后消失）。仅 project scope。
+ *
+ * 直接按路径查找 tmp 文件，不调 config-loader 全扫——save 只需知道 tmp 文件
+ * 的路径，不需要 meta 提取或跨目录去重。
+ *
+ * @throws 若 tmp workflow 不存在、目标已存在、或 rename 失败
+ */
+export async function saveWorkflow(tmpName: string, newName?: string): Promise<string> {
+  const srcPath = resolve(getTmpDir(), `${tmpName}.js`);
+  if (!existsSync(srcPath)) {
+    throw new Error(`Temporary workflow '${tmpName}' not found`);
+  }
+
+  const destName = newName ?? tmpName;
+  const savedDir = getSavedDir();
+  const destPath = resolve(savedDir, `${destName}.js`);
+
+  if (existsSync(destPath)) {
+    throw new Error(`'${destName}' already exists in saved workflows. Use a different name.`);
+  }
+
+  mkdirSync(savedDir, { recursive: true });
+  renameSync(srcPath, destPath);
+  return `Saved '${tmpName}' → '${destName}' (${destPath})`;
+}
+
+// ── Delete ────────────────────────────────────────────────────
+
+/**
+ * 删除 workflow 脚本文件（tmp 或 saved）。
+ * @param isRunning 回调，判断某 name 是否正在运行（运行中拒绝删除）
+ * @throws 若正在运行、或文件不存在
+ */
+export function deleteWorkflow(
+  name: string,
+  isRunning: (name: string) => boolean,
+): string {
+  if (isRunning(name)) {
+    throw new Error(`Cannot delete '${name}': workflow is currently running. Abort it first.`);
+  }
+
+  const tmpDir = getTmpDir();
+  const savedDir = getSavedDir();
+  const candidates = [
+    resolve(tmpDir, `${name}.js`),
+    resolve(savedDir, `${name}.js`),
+  ];
+
+  for (const filePath of candidates) {
+    if (existsSync(filePath)) {
+      unlinkSync(filePath);
+      return `Deleted workflow '${name}' (${filePath})`;
+    }
+  }
+
+  throw new Error(`Workflow file '${name}' not found`);
+}