qlogicagent 2.13.5 → 2.13.6

package/dist/cli/handlers/workflow-handler.js

@@ -1,1449 +0,0 @@
-/**
- * Workflow mode handlers — ACP surface for the automation workflow engine (plan M2 接入).
- * Exposes workflow.create/get/describe/patch/run/setActive/list/delete over the same RPC host
- * as product/solo. The engine (WorkflowController) lives in qlogicagent (D12); triggers live in
- * the gateway (D7/B) and drive `workflow.run` over ACP.
- *
- * fail-loud throughout (plan §1.5): unknown id / illegal patch / missing capability all throw.
- */
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { randomUUID } from "node:crypto";
-import { gzipSync } from "node:zlib";
-import { AgentProcessManager } from "../../runtime/infra/agent-process.js";
-import { getUserAgentHome } from "../../runtime/infra/agent-paths.js";
-import * as projectStore from "../../runtime/infra/project-store.js";
-import { AGENT_RPC_ERROR_CODES } from "../../protocol/wire/index.js";
-import { WorkflowController, defaultRuntimeFactory } from "../../orchestration/workflow/workflow-controller.js";
-import { WorkflowStore } from "../../orchestration/workflow/workflow-store.js";
-import { WorkflowRunHistoryStore } from "../../orchestration/workflow/run-history-store.js";
-import { FileRunCheckpoint } from "../../orchestration/workflow/run-checkpoint-store.js";
-import { NodeRegistry } from "../../orchestration/workflow/node-registry.js";
-import { hostExecutors } from "../../orchestration/workflow/host-executors.js";
-import { createQlaExecutorHost } from "../../orchestration/workflow/qla-executor-host.js";
-import { setWorkflowController } from "../../orchestration/workflow/workflow-service.js";
-import { WorkflowScheduler } from "../../orchestration/workflow/workflow-scheduler.js";
-import { toWorkflowBundle, fromWorkflowBundle } from "../../orchestration/workflow/workflow-bundle.js";
-import { WorkflowAuditStore } from "../../orchestration/workflow/workflow-audit-store.js";
-import { workflowsDir } from "../../orchestration/workflow/workflow-store.js";
-import { resolveActiveOwnerUserId } from "../../runtime/infra/agent-paths.js";
-import { convertN8nWorkflow } from "../../orchestration/workflow/n8n-import.js";
-import { buildCapabilityCatalog } from "../../orchestration/workflow/capability-catalog.js";
-import { item } from "../../orchestration/workflow/data-item.js";
-import { Memdir } from "../../skills/memory/memdir.js";
-import { CredentialVault, credentialToHeaders } from "../credential-vault.js";
-import { SENSITIVE_KINDS } from "../../orchestration/workflow/budget-permission-gate.js";
-import { classifyOperation } from "../../skills/permissions/operation-classifier.js";
-import { createDefaultCommunityConsentClient } from "../../runtime/community/community-consent-client.js";
-import { createFileCommunityConsentStore, hasMethodSharingConsent, METHOD_CONSENT_REQUIRED_MESSAGE } from "./community-handler.js";
-/** D15: per-run node-execution hard cap (plan §1.5 / D15 "循环硬上限 1000"). */
-const MAX_NODE_EXECUTIONS = 1000;
-/**
- * Resolve the project root an RPC addresses. `projectId` routes to that project's workspace
- * (fail-loud on unknown ids); without it the active project root is used — the legitimate
- * path for agent-tool/chat-built workflows in the current project (not a compat shim).
- */
-function resolveWorkflowTarget(p) {
-    if (p.projectId !== undefined && p.projectId !== null && p.projectId !== "") {
-        const project = projectStore.getProjectById(String(p.projectId));
-        if (!project)
-            throw new Error(`workflow: unknown projectId "${String(p.projectId)}"`);
-        return { cwd: project.workspaceDir, projectId: project.id };
-    }
-    const active = projectStore.getActiveProject();
-    return { cwd: this.getActiveProjectRoot(), projectId: active?.id };
-}
-/** Build (or fetch) the engine bundle for one project root, wired to real capabilities (§1.5). */
-export function ensureWorkflowRoot(target) {
-    if (!this.workflowRoots)
-        this.workflowRoots = new Map();
-    const key = path.resolve(target.cwd);
-    const existing = this.workflowRoots.get(key);
-    if (existing) {
-        // Project ids are stable per dir; backfill when a later call learns it.
-        if (!existing.projectId && target.projectId)
-            existing.projectId = target.projectId;
-        return existing;
-    }
-    const cwd = target.cwd;
-    const store = new WorkflowStore(cwd);
-    const pm = new AgentProcessManager({
-        log: {
-            info: (msg) => process.stderr.write(`[workflow:pm] ${msg}\n`),
-            warn: (msg) => process.stderr.write(`[workflow:pm] WARN ${msg}\n`),
-        },
-        onMcpToolCall: (memberId, tool, args) => this.handleMcpToolCall(memberId, tool, args),
-        sessionDir: path.join(getUserAgentHome(), "agent-logs"),
-    });
-    const execHost = createQlaExecutorHost({
-        findTool: (name) => this.toolCatalog.findTool(name),
-        // R5 multi-root:tool 节点(exec)钉在本根工作区,不跟随进程级活动项目 cwd。
-        workspaceCwd: cwd,
-        // D29: vault credential → headers, decrypted at execution time only (owner-scoped vault).
-        resolveCredentialHeaders: (credentialId) => {
-            const { summary, data } = new CredentialVault().get(credentialId);
-            return credentialToHeaders(summary.type, data);
-        },
-        // IT-7b 无人值守细粒度审计:统一权限引擎的 operation-classifier。D30 的授予是"种类级"
-        // (允许 tool 这一类),这里在"操作级"补刀 —— 破坏性 shell / 递归删除 / 写出工作区外,
-        // 即使种类被授予也一律拒(无人在场不冒这险;改 attended 跑或拆步骤)。
-        auditUnattendedTool: ({ tool, args }) => {
-            const c = classifyOperation({ toolName: tool, arguments: args }, { workspaceRoot: cwd });
-            if (c.isDestructive || c.isRecursiveDelete) {
-                throw new Error(`无人值守运行拒绝破坏性操作:工具「${tool}」被判定为破坏性(递归删除/危险 shell)。请改为手动/口令/表单触发执行,或拆掉该步骤。`);
-            }
-            if (c.crossWorkspace) {
-                throw new Error(`无人值守运行拒绝越界操作:工具「${tool}」的目标路径在项目工作区之外(${c.targetPaths.slice(0, 3).join("、")})。无人值守只允许操作本项目目录。`);
-            }
-        },
-        runAgent: async ({ agentId, prompt, signal }) => {
-            // Missing / "self" → run on 小智(qlogicagent)本体:buildExternalDescriptor("qlogicagent")
-            // 返回 self-descriptor(R1 自供给路径,从 owner profile 自解析模型),无需配置外部 agent。
-            const id = (!agentId || agentId === "self") ? "qlogicagent" : agentId;
-            const descriptor = this.acpDetector.buildExternalDescriptor(id);
-            if (!descriptor)
-                throw new Error(`workflow agent node: agent "${id}" is not available`);
-            const memberId = `workflow-agent-${randomUUID().slice(0, 8)}`;
-            if (signal?.aborted)
-                throw new Error("workflow agent node aborted before dispatch");
-            // Agent nodes execute inside the owning project's workspace (automation 产物归项目).
-            await pm.spawn({ memberId, name: `workflow-${id}`, cwd, prompt, external: descriptor });
-            try {
-                const result = await pm.sendTask(memberId, prompt);
-                // The reply payload is {content, stopReason} — downstream nodes want the TEXT,
-                // not a double-encoded JSON string (the old shape made `.json.text` undefined).
-                if (typeof result === "string")
-                    return result;
-                const content = result?.content;
-                return typeof content === "string" ? content : JSON.stringify(result);
-            }
-            finally {
-                // fail-loud cleanup: surface (not swallow) unexpected teardown errors (§1.5).
-                try {
-                    pm.kill(memberId);
-                    pm.remove(memberId);
-                }
-                catch (e) {
-                    process.stderr.write(`[workflow:pm] WARN cleanup of ${memberId} failed: ${e instanceof Error ? e.message : String(e)}\n`);
-                }
-            }
-        },
-        invokeMcp: ({ server, tool, args }) => this.handleMcpToolCall(`workflow-mcp:${server}`, tool, args),
-        // Channel send is fire-and-forget (plan §2.1 A): emit a one-way notification; the openclaw
-        // gateway (onLifecycleNotification) delivers via the channel layer. Many IM platforms have no
-        // delivery receipt, so the node does not wait for one — returns {queued} immediately.
-        sendChannel: async ({ channel, target: to, payload }) => {
-            this.sendNotification("workflow.channel.send", { channel, target: to, payload });
-            return { queued: true };
-        },
-        // D34 subworkflow:跨根可调;同步调用栈防环(A→B→A 立即拒,深度上限 8)。
-        // 顶层 run 不经此处,所以把 CALLER 也补入链 —— 否则 A↔B 的第二次 run(A) 会卡在
-        // controller 并发槽排队(死锁),而不是被守卫立即拒绝。
-        runSubworkflow: async ({ workflowId, callerWorkflowId, projectId, payload, signal }) => {
-            const target = projectId
-                ? ensureWorkflowRoot.call(this, resolveWorkflowTarget.call(this, { projectId }))
-                : bundle;
-            const callerFrame = callerWorkflowId ? `${path.resolve(bundle.cwd)}::${callerWorkflowId}` : null;
-            const addedCallerFrame = callerFrame !== null && !subworkflowStack.has(callerFrame);
-            if (addedCallerFrame)
-                subworkflowStack.add(callerFrame);
-            const frame = `${path.resolve(target.cwd)}::${workflowId}`;
-            try {
-                if (subworkflowStack.has(frame)) {
-                    throw new Error(`subworkflow cycle detected: "${workflowId}" is already running in this call chain`);
-                }
-                if (subworkflowStack.size >= 8) {
-                    throw new Error(`subworkflow depth limit (8) exceeded`);
-                }
-                subworkflowStack.add(frame);
-                try {
-                    if (signal?.aborted)
-                        throw new Error("subworkflow aborted before dispatch");
-                    const outcome = await target.controller.run(workflowId, { type: "manual", payload });
-                    if (outcome.status !== "completed") {
-                        throw new Error(`subworkflow "${workflowId}" ended with status "${outcome.status}"`);
-                    }
-                    const outputs = {};
-                    for (const [nodeId, portMap] of Object.entries(outcome.result?.outputs ?? {})) {
-                        outputs[nodeId] = Object.fromEntries(Object.entries(portMap).map(([port, items]) => [port, items.map((i) => i.json)]));
-                    }
-                    return [item({ status: outcome.status, runId: outcome.runId ?? null, outputs })];
-                }
-                finally {
-                    subworkflowStack.delete(frame);
-                }
-            }
-            finally {
-                if (addedCallerFrame)
-                    subworkflowStack.delete(callerFrame);
-            }
-        },
-        // D34 human-in-the-loop:通知 owner 并在内存中等待决定(run 保持 running)。
-        // 登记表带元数据,workflow.approvals 可随时拉取 —— 推送是快路径,拉取保证刷新/重连后仍可见。
-        // R2-E 跨重启:挂起同时持久登记到 pending-approvals.json;决定/超时/取消即删。重启后
-        // ensureWorkflowRoot 发现遗留 → 通知 owner「重启中断,重新运行即恢复(前置节点
-        // checkpoint 缓存命中秒过,审批会重新弹)」—— 恢复语义复用既有重放机制,无第二轨。
-        approval: ({ nodeId, workflowId, prompt, timeoutMs, signal }) => {
-            return new Promise((resolve, reject) => {
-                const key = randomUUID();
-                const meta = {
-                    approvalId: key,
-                    workflowId: workflowId ?? "",
-                    nodeId,
-                    prompt: prompt ?? "继续执行?",
-                    requestedAt: new Date().toISOString(),
-                    ...projectTag(bundle),
-                };
-                persistPendingSuspension(cwd, { kind: "approval", ...meta });
-                const settle = () => removePendingSuspension(cwd, key);
-                const deadline = setTimeout(() => {
-                    pendingApprovals.delete(key);
-                    settle();
-                    resolve({ approved: false, decidedAt: new Date().toISOString(), note: "超时未审批,自动拒绝" });
-                }, timeoutMs ?? 24 * 3600_000);
-                const onAbort = () => {
-                    clearTimeout(deadline);
-                    pendingApprovals.delete(key);
-                    settle();
-                    reject(new Error("approval wait canceled"));
-                };
-                signal?.addEventListener("abort", onAbort, { once: true });
-                pendingApprovals.set(key, {
-                    meta,
-                    resolve: (approved, note) => {
-                        clearTimeout(deadline);
-                        signal?.removeEventListener("abort", onAbort);
-                        pendingApprovals.delete(key);
-                        settle();
-                        resolve({ approved, decidedAt: new Date().toISOString(), ...(note ? { note } : {}) });
-                    },
-                });
-                this.sendNotification("workflow.approvalRequested", meta);
-            });
-        },
-        // D34 wait-until-webhook:挂起分支直到 path 被调用(approval 同款 await-in-memory 单轨;
-        // 持久登记同 R2-E,重启遗留同样提示重放恢复)。唤醒在 handleWorkflowOnWebhook。
-        waitWebhook: ({ path: hookPath, nodeId, workflowId, timeoutMs, signal }) => {
-            return new Promise((resolve, reject) => {
-                const key = randomUUID();
-                persistPendingSuspension(cwd, {
-                    kind: "webhook-wait", approvalId: key, workflowId: workflowId ?? "", nodeId,
-                    prompt: `等待 Webhook ${hookPath}`, requestedAt: new Date().toISOString(), ...projectTag(bundle),
-                });
-                const settle = () => removePendingSuspension(cwd, key);
-                const deadline = setTimeout(() => {
-                    dropWebhookWaiter(hookPath, key);
-                    settle();
-                    reject(new Error(`wait(until=webhook) 超时:${hookPath} 在限期内未被调用`));
-                }, timeoutMs ?? 24 * 3600_000);
-                const onAbort = () => {
-                    clearTimeout(deadline);
-                    dropWebhookWaiter(hookPath, key);
-                    settle();
-                    reject(new Error("webhook wait canceled"));
-                };
-                signal?.addEventListener("abort", onAbort, { once: true });
-                const waiters = pendingWebhookWaits.get(hookPath) ?? new Map();
-                waiters.set(key, (payload) => {
-                    clearTimeout(deadline);
-                    signal?.removeEventListener("abort", onAbort);
-                    dropWebhookWaiter(hookPath, key);
-                    settle();
-                    resolve(payload);
-                });
-                pendingWebhookWaits.set(hookPath, waiters);
-            });
-        },
-        // Project-scoped memdir backend for `memory` nodes (spec D25): the owning project's
-        // .qlogicagent/memory. Real store, fail-loud on op errors (§1.5). Topic keys are
-        // normalized to memdir's `.md` naming (storage detail users shouldn't have to know).
-        memory: async ({ op, key, value, query }) => {
-            const memdir = new Memdir(cwd);
-            memdir.ensureInitialized();
-            const fileKey = key && !key.endsWith(".md") ? `${key}.md` : key;
-            if (op === "read") {
-                if (fileKey) {
-                    const r = await memdir.readFile(fileKey);
-                    if (!r.ok)
-                        throw new Error(`memory read "${fileKey}": ${r.message}`);
-                    return [item({ key: fileKey, content: r.content ?? "" })];
-                }
-                return [item({ key: "INDEX", content: memdir.getIndexRaw() })];
-            }
-            if (op === "write") {
-                const text = typeof value === "string" ? value : value !== undefined ? JSON.stringify(value) : "";
-                if (!text)
-                    throw new Error(`memory write: empty value (provide params.value or upstream input)`);
-                const r = fileKey ? await memdir.writeFile(fileKey, text) : await memdir.addToIndex(text);
-                if (!r.ok)
-                    throw new Error(`memory write${fileKey ? ` "${fileKey}"` : ""}: ${r.message}`);
-                return [item({ ok: true, key: fileKey ?? "INDEX", bytes: text.length })];
-            }
-            if (!query)
-                throw new Error(`memory search requires "query"`);
-            const hits = await memdir.searchLocal(query);
-            return [item({ hits: hits })];
-        },
-    });
-    const registry = new NodeRegistry();
-    for (const [kind, exec] of Object.entries(hostExecutors)) {
-        registry.register(kind, exec);
-    }
-    const bundle = {
-        cwd,
-        projectId: target.projectId,
-        store,
-        pm,
-        runHistory: new WorkflowRunHistoryStore(cwd),
-        audit: new WorkflowAuditStore(workflowsDir(cwd)),
-        // controller/scheduler assigned below (need the bundle reference for projectId-tagged events).
-        controller: undefined,
-        scheduler: undefined,
-    };
-    const runtimeFactory = defaultRuntimeFactory({
-        registry,
-        host: execHost,
-        budget: { maxNodeExecutions: MAX_NODE_EXECUTIONS },
-        checkpoint: (workflowId, runId) => new FileRunCheckpoint(cwd, workflowId, runId),
-        // Per-node live status → canvas coloring (gateway auto-forwards via ALL_WS_EVENT_NAMES).
-        emitNodeStatus: (workflowId, nodeId, status) => this.sendNotification("workflow.nodeStatus", { workflowId, nodeId, status, ...projectTag(bundle) }),
-    });
-    bundle.controller = new WorkflowController(store, runtimeFactory, bundle.runHistory);
-    // Trigger layer (M3): reuse the tested scheduler in-process. The gateway owns activation
-    // (workflow.setActive) + IM/webhook sources; cron timing fires here via the existing scheduler.
-    bundle.scheduler = new WorkflowScheduler({
-        controller: bundle.controller,
-        onError: (err, workflowId) => {
-            // fail-loud: a timer-driven (cron) run has no caller to throw back to (§1.5).
-            const message = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`[workflow:scheduler] run error for ${workflowId}: ${message}\n`);
-        },
-        onRunStarted: (workflowId, triggerType) => this.sendNotification("workflow.runStarted", { workflowId, triggerType, ...projectTag(bundle) }),
-        onRunCompleted: (outcome, triggerType) => emitWorkflowRunCompleted.call(this, bundle, outcome, triggerType),
-        onRunFailed: (workflowId, triggerType, err) => this.sendNotification("workflow.runFailed", { workflowId, triggerType, error: errorMessage(err), ...projectTag(bundle) }),
-        // D32 防洪:同一工作流的无人值守触发(webhook/IM/cron)最小间隔(生产装配点显式开)。
-        minTriggerIntervalMs: 5_000,
-        // D32 防洪死信:被限流丢弃的触发必须可见(通知 + stderr),绝不静默丢。
-        onTriggerDropped: (workflowId, triggerType, detail) => {
-            process.stderr.write(`[workflow:scheduler] trigger dropped (rate-limit) wf=${workflowId} type=${triggerType} sinceLast=${detail.sinceLastMs}ms\n`);
-            this.sendNotification("workflow.triggerDropped", { workflowId, triggerType, ...detail, ...projectTag(bundle) });
-        },
-    });
-    this.workflowRoots.set(key, bundle);
-    // The agent-facing `workflow` tool operates on the ACTIVE project (single-track sharing):
-    // publish (and re-publish on later active-root ensures) only that root's controller.
-    if (path.resolve(this.getActiveProjectRoot()) === key) {
-        setWorkflowController(bundle.controller);
-    }
-    // Arm active workflows (spec §B4 restart re-registration). fail-loud on startup failure.
-    bundle.scheduler.start().catch(e => {
-        process.stderr.write(`[workflow:scheduler] start failed for ${cwd}: ${e instanceof Error ? e.message : String(e)}\n`);
-    });
-    // R2-E 重启遗留:上个进程留下的挂起(审批/等 webhook)等待者已死——告警引导重放恢复
-    // (重新运行时 checkpoint 让已完成节点缓存命中秒过,审批/等待会重新发起),并留审计痕。
-    const lost = readPendingSuspensions(cwd);
-    if (lost.length > 0) {
-        for (const rec of lost) {
-            this.sendNotification("workflow.alert", {
-                workflowId: rec.workflowId,
-                kind: "suspension-lost-on-restart",
-                suspensionKind: rec.kind,
-                nodeId: rec.nodeId,
-                prompt: rec.prompt,
-                ...projectTag(bundle),
-            });
-            bundle.audit.append({
-                ts: new Date().toISOString(),
-                actor: "system",
-                action: "suspensionLostOnRestart",
-                workflowId: rec.workflowId,
-                detail: { kind: rec.kind, nodeId: rec.nodeId, requestedAt: rec.requestedAt },
-            });
-        }
-        writePendingSuspensions(cwd, []);
-    }
-    return bundle;
-}
-/**
- * Ensure engine roots for the active project AND every automation project (spec D21).
- * Called by aggregate surfaces (list / IM / webhook): the gateway's arm-on-connect
- * workflow.list therefore arms cron triggers across ALL automation projects (§B4).
- */
-function ensureAllWorkflowRoots() {
-    const bundles = new Map();
-    const active = ensureWorkflowRoot.call(this, resolveWorkflowTarget.call(this, {}));
-    bundles.set(path.resolve(active.cwd), active);
-    for (const project of projectStore.listProjects()) {
-        if (project.type !== "automation")
-            continue;
-        const bundle = ensureWorkflowRoot.call(this, { cwd: project.workspaceDir, projectId: project.id });
-        bundles.set(path.resolve(bundle.cwd), bundle);
-    }
-    return [...bundles.values()];
-}
-/** Notification tag: which project a workflow event belongs to (multi-root routing for the UI). */
-/** D38 audit helper: stamp WHO (active owner) did WHAT to WHICH workflow. */
-function audit(bundle, action, workflowId, detail) {
-    bundle.audit.append({
-        ts: new Date().toISOString(),
-        actor: resolveActiveOwnerUserId(),
-        action,
-        workflowId,
-        ...(detail ? { detail } : {}),
-    });
-}
-function projectTag(bundle) {
-    return bundle.projectId ? { projectId: bundle.projectId } : {};
-}
-function params(msg) {
-    return msg.params ?? {};
-}
-function fail(msg, message) {
-    if (msg.id !== undefined) {
-        this.sendResponse(msg.id, undefined, { code: AGENT_RPC_ERROR_CODES.INVALID_PARAMS, message });
-    }
-}
-/** Resolve target root for an RPC, surfacing bad projectIds as INVALID_PARAMS (fail-loud). */
-function targetBundle(msg, p) {
-    try {
-        return ensureWorkflowRoot.call(this, resolveWorkflowTarget.call(this, p));
-    }
-    catch (err) {
-        fail.call(this, msg, errorMessage(err));
-        return undefined;
-    }
-}
-function workflowSnapshot(record, bundle) {
-    return {
-        id: record.id,
-        name: record.name,
-        ...(record.owner ? { owner: record.owner } : {}),
-        active: record.active,
-        concurrency: record.concurrency,
-        rev: record.rev,
-        createdAt: record.createdAt,
-        updatedAt: record.updatedAt,
-        ...(record.trigger !== undefined ? { trigger: record.trigger } : {}),
-        ...(record.permissionScope !== undefined ? { permissionScope: record.permissionScope } : {}),
-        ...(bundle?.projectId ? { projectId: bundle.projectId } : {}),
-        // D31 versioning: status is DERIVED (single truth = publishedDef/active/archived fields).
-        status: record.archived ? "archived" : record.active ? "active" : record.publishedDef ? "paused" : "draft",
-        ...(record.publishedRev !== undefined ? { publishedRev: record.publishedRev } : {}),
-        draftAhead: record.publishedRev !== undefined ? record.rev > record.publishedRev : record.publishedDef == null,
-        def: record.def,
-    };
-}
-function emitWorkflowRecord(method, record, bundle) {
-    this.sendNotification(method, { workflow: workflowSnapshot(record, bundle), ...projectTag(bundle) });
-}
-/** D33 连败告警:同一工作流连续失败计数(成功清零);阈值即告警(loud,经 inbox/活动日志可见)。 */
-const CONSECUTIVE_FAILURE_ALERT_THRESHOLD = 3;
-const consecutiveFailures = new Map();
-/** D34 子流程同步调用栈(防环/限深;同进程内跨根共享)。 */
-const subworkflowStack = new Set();
-/** D34 审批挂起表:approvalId → resolver + 展示元数据(workflow.approve 消费;重启即丢=run fail loud)。 */
-const pendingApprovals = new Map();
-/** D34 wait-until-webhook 唤醒表:path → (suspensionId → wake(payload))。 */
-const pendingWebhookWaits = new Map();
-function dropWebhookWaiter(hookPath, id) {
-    const waiters = pendingWebhookWaits.get(hookPath);
-    waiters?.delete(id);
-    if (waiters && waiters.size === 0)
-        pendingWebhookWaits.delete(hookPath);
-}
-function pendingSuspensionsFile(cwd) {
-    return path.join(workflowsDir(cwd), "pending-suspensions.json");
-}
-function readPendingSuspensions(cwd) {
-    try {
-        const raw = JSON.parse(fs.readFileSync(pendingSuspensionsFile(cwd), "utf8"));
-        return Array.isArray(raw) ? raw : [];
-    }
-    catch {
-        return [];
-    }
-}
-function writePendingSuspensions(cwd, list) {
-    try {
-        const file = pendingSuspensionsFile(cwd);
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, JSON.stringify(list, null, 2), "utf8");
-    }
-    catch (err) {
-        process.stderr.write(`[workflow:suspension] WRITE FAILED: ${err instanceof Error ? err.message : String(err)}\n`);
-    }
-}
-function persistPendingSuspension(cwd, rec) {
-    writePendingSuspensions(cwd, [...readPendingSuspensions(cwd), rec]);
-}
-function removePendingSuspension(cwd, approvalId) {
-    writePendingSuspensions(cwd, readPendingSuspensions(cwd).filter((r) => r.approvalId !== approvalId));
-}
-/** `workflow.approvals` — 列出全部挂起审批(刷新/重连后的拉取恢复路径;推送通知是快路径)。 */
-export async function handleWorkflowApprovals(msg) {
-    if (msg.id !== undefined) {
-        this.sendResponse(msg.id, { approvals: [...pendingApprovals.values()].map((p) => p.meta) });
-    }
-}
-/** `workflow.approve` — 人工审批决定(approved=false 即拒绝);未知/过期 id fail-loud。 */
-export async function handleWorkflowApprove(msg) {
-    const p = params(msg);
-    if (typeof p.approvalId !== "string" || typeof p.approved !== "boolean") {
-        return fail.call(this, msg, "workflow.approve requires `approvalId` and boolean `approved`");
-    }
-    const pending = pendingApprovals.get(p.approvalId);
-    if (!pending)
-        return fail.call(this, msg, `approval "${p.approvalId}" not found (已决定/超时/重启丢失)`);
-    pending.resolve(p.approved, typeof p.note === "string" && p.note ? p.note : undefined);
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { ok: true });
-}
-/**
- * `workflow.onForm` — form 触发(D34):校验活跃 form 触发 + 必填字段,以表单值为 $trigger 起 run。
- * attended(用户亲手填表提交)。
- */
-export async function handleWorkflowOnForm(msg) {
-    const p = params(msg);
-    if (!p.workflowId || typeof p.values !== "object" || p.values === null) {
-        return fail.call(this, msg, "workflow.onForm requires `workflowId` and `values` object");
-    }
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const workflowId = String(p.workflowId);
-    const record = await bundle.controller.get(workflowId);
-    // attended(用户亲手填表)= 跑草稿(D31),所以不要求 active —— 只要求表单定义在。
-    if (record.trigger?.type !== "form") {
-        return fail.call(this, msg, `workflow "${workflowId}" has no form trigger`);
-    }
-    const values = p.values;
-    for (const field of record.trigger.fields) {
-        if (field.required && (values[field.key] === undefined || values[field.key] === "")) {
-            return fail.call(this, msg, `表单缺少必填项「${field.label ?? field.key}」`);
-        }
-    }
-    this.sendNotification("workflow.runStarted", { workflowId, triggerType: "form", ...projectTag(bundle) });
-    let outcome;
-    try {
-        outcome = await bundle.controller.run(workflowId, { type: "form", payload: { type: "form", ...values } });
-        emitWorkflowRunCompleted.call(this, bundle, outcome, "form");
-    }
-    catch (err) {
-        this.sendNotification("workflow.runFailed", { workflowId, triggerType: "form", error: errorMessage(err), ...projectTag(bundle) });
-        throw err;
-    }
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, outcome);
-}
-function emitWorkflowRunCompleted(bundle, outcome, triggerType) {
-    if (outcome.status === "failed" || outcome.status === "canceled") {
-        this.sendNotification("workflow.runFailed", {
-            workflowId: outcome.workflowId,
-            triggerType,
-            error: outcome.status === "canceled" ? "Workflow run canceled" : "Workflow run failed",
-            outcome,
-            ...projectTag(bundle),
-        });
-        if (outcome.status === "failed") {
-            const n = (consecutiveFailures.get(outcome.workflowId) ?? 0) + 1;
-            consecutiveFailures.set(outcome.workflowId, n);
-            if (n >= CONSECUTIVE_FAILURE_ALERT_THRESHOLD) {
-                process.stderr.write(`[workflow:alert] "${outcome.workflowId}" failed ${n} consecutive runs\n`);
-                this.sendNotification("workflow.alert", {
-                    workflowId: outcome.workflowId,
-                    kind: "consecutive-failures",
-                    count: n,
-                    triggerType,
-                    ...projectTag(bundle),
-                });
-            }
-        }
-        return;
-    }
-    consecutiveFailures.delete(outcome.workflowId);
-    this.sendNotification("workflow.runCompleted", {
-        workflowId: outcome.workflowId,
-        status: outcome.status,
-        triggerType,
-        outcome,
-        ...projectTag(bundle),
-    });
-}
-function errorMessage(err) {
-    return err instanceof Error ? err.message : String(err);
-}
-export async function handleWorkflowCreate(msg) {
-    const p = params(msg);
-    if (!p.def)
-        return fail.call(this, msg, "workflow.create requires `def`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const id = String(p.id ?? `wf_${randomUUID().slice(0, 8)}`);
-    const record = await bundle.controller.create({
-        id,
-        name: String(p.name ?? id),
-        owner: resolveActiveOwnerUserId(),
-        def: p.def,
-        concurrency: p.concurrency,
-        active: p.active === true,
-    });
-    if (record.active)
-        await bundle.scheduler.refresh(record.id);
-    audit(bundle, "created", record.id, { name: record.name });
-    emitWorkflowRecord.call(this, "workflow.created", record, bundle);
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, workflowSnapshot(record, bundle));
-}
-export async function handleWorkflowGet(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.get requires `id`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const record = await bundle.controller.get(String(p.id));
-    const snap = workflowSnapshot(record, bundle);
-    // D31: the published snapshot is opt-in (diff preview) — list/update payloads stay lean.
-    if (p.includePublished === true && record.publishedDef)
-        snap.publishedDef = record.publishedDef;
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, snap);
-}
-export async function handleWorkflowDescribe(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.describe requires `id`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const rendered = await bundle.controller.describe(String(p.id));
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { rendered });
-}
-export async function handleWorkflowPatch(msg) {
-    const p = params(msg);
-    if (!p.id || !p.patch)
-        return fail.call(this, msg, "workflow.patch requires `id` and `patch`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const env = {
-        patch: p.patch,
-        baseRev: p.baseRev,
-        scope: p.scope,
-    };
-    const outcome = await bundle.controller.patch(String(p.id), env);
-    // A patch may set/clear the trigger or activation → re-arm the scheduler.
-    await bundle.scheduler.refresh(String(p.id));
-    if (outcome.ok) {
-        audit(bundle, "patched", String(p.id), { ops: (env.patch ?? []).map((op) => op.op) });
-        emitWorkflowRecord.call(this, "workflow.updated", await bundle.controller.get(String(p.id)), bundle);
-    }
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, outcome);
-}
-export async function handleWorkflowRun(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.run requires `id`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const trigger = p.trigger ?? { type: "manual" };
-    const workflowId = String(p.id);
-    this.sendNotification("workflow.runStarted", { workflowId, triggerType: trigger.type, ...projectTag(bundle) });
-    let outcome;
-    try {
-        // R5 reuseCache(D44):工作室画布显式跨 run 缓存(改参数只重跑下游);默认关。
-        outcome = await bundle.controller.run(workflowId, trigger, { reuseCache: p.reuseCache === true });
-        emitWorkflowRunCompleted.call(this, bundle, outcome, trigger.type);
-    }
-    catch (err) {
-        this.sendNotification("workflow.runFailed", { workflowId, triggerType: trigger.type, error: errorMessage(err), ...projectTag(bundle) });
-        throw err;
-    }
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, outcome);
-}
-/**
- * `workflow.update` — record-level meta/def update (rename, whole-def replacement from the
- * chat builder, concurrency). Graph micro-edits stay on workflow.patch; trigger stays a
- * set_trigger patch op (single track each).
- */
-export async function handleWorkflowUpdate(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.update requires `id`");
-    if (p.name === undefined && p.def === undefined && p.concurrency === undefined) {
-        return fail.call(this, msg, "workflow.update requires at least one of `name`/`def`/`concurrency`");
-    }
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const record = await bundle.controller.update(String(p.id), {
-        ...(p.name !== undefined ? { name: String(p.name) } : {}),
-        ...(p.def !== undefined ? { def: p.def } : {}),
-        ...(p.concurrency !== undefined ? { concurrency: p.concurrency } : {}),
-    });
-    await bundle.scheduler.refresh(record.id);
-    audit(bundle, "updated", record.id, { fields: ["name", "def", "concurrency"].filter((f) => p[f] !== undefined) });
-    emitWorkflowRecord.call(this, "workflow.updated", record, bundle);
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, workflowSnapshot(record, bundle));
-}
-export async function handleWorkflowSetActive(msg) {
-    const p = params(msg);
-    if (!p.id || typeof p.active !== "boolean")
-        return fail.call(this, msg, "workflow.setActive requires `id` and boolean `active`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    let record;
-    try {
-        record = await bundle.controller.setActive(String(p.id), p.active);
-    }
-    catch (err) {
-        // D31 lifecycle refusals (unpublished/archived) are caller-fixable → error response, not a crash.
-        return fail.call(this, msg, errorMessage(err));
-    }
-    await bundle.scheduler.refresh(record.id);
-    audit(bundle, p.active ? "activated" : "deactivated", record.id);
-    emitWorkflowRecord.call(this, "workflow.updated", record, bundle);
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, workflowSnapshot(record, bundle));
-}
-export async function handleWorkflowList(msg) {
-    const p = params(msg);
-    if (p.projectId) {
-        const bundle = targetBundle.call(this, msg, p);
-        if (!bundle)
-            return;
-        const records = await bundle.store.list();
-        if (msg.id !== undefined)
-            this.sendResponse(msg.id, { workflows: records.map(r => workflowSnapshot(r, bundle)) });
-        return;
-    }
-    // Aggregate across the active root + every automation project (spec D21). The gateway's
-    // arm-on-connect workflow.list lands here, which also arms every root's scheduler (§B4).
-    const bundles = ensureAllWorkflowRoots.call(this);
-    const workflows = [];
-    for (const bundle of bundles) {
-        const records = await bundle.store.list();
-        workflows.push(...records.map(r => workflowSnapshot(r, bundle)));
-    }
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { workflows });
-}
-export async function handleWorkflowDelete(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.delete requires `id`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    await bundle.controller.delete(String(p.id));
-    await bundle.scheduler.refresh(String(p.id)); // drop any armed trigger for the deleted workflow
-    audit(bundle, "deleted", String(p.id));
-    this.sendNotification("workflow.deleted", { workflowId: String(p.id), ...projectTag(bundle) });
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { ok: true });
-}
-/**
- * `workflow.cancelRun` — stop an in-flight run (D32; engine support landed with the teammate's
- * runId/AbortController work, this exposes it on the RPC face + a UI stop button). Cancels the
- * newest active run when runId is omitted. fail-loud when nothing is running.
- */
-export async function handleWorkflowCancelRun(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.cancelRun requires `id`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    let outcome;
-    try {
-        outcome = await bundle.controller.cancelRun(String(p.id), {
-            ...(typeof p.runId === "string" && p.runId ? { runId: p.runId } : {}),
-            reason: typeof p.reason === "string" && p.reason ? p.reason : "用户停止了运行",
-        });
-    }
-    catch (err) {
-        return fail.call(this, msg, errorMessage(err));
-    }
-    emitWorkflowRunCompleted.call(this, bundle, outcome, "manual");
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, outcome);
-}
-// ── Observability (spec D33/D36, IT-9) ─────────────────────────────────────────
-/**
- * `workflow.dryRun` — test-run the DRAFT with an optional simulated trigger payload, WITHOUT
- * recording into run history (D36: test runs stay out of production stats). Returns the full
- * outcome incl. per-node trace for inspection.
- */
-export async function handleWorkflowDryRun(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.dryRun requires `id`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const workflowId = String(p.id);
-    this.sendNotification("workflow.runStarted", { workflowId, triggerType: "manual", ...projectTag(bundle) });
-    let outcome;
-    try {
-        outcome = await bundle.controller.run(workflowId, { type: "manual", payload: p.payload }, { recordHistory: false });
-        emitWorkflowRunCompleted.call(this, bundle, outcome, "manual");
-    }
-    catch (err) {
-        this.sendNotification("workflow.runFailed", { workflowId, triggerType: "manual", error: errorMessage(err), ...projectTag(bundle) });
-        return fail.call(this, msg, errorMessage(err));
-    }
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { ...outcome, dryRun: true });
-}
-/** `workflow.metrics` — aggregate run history into success-rate/duration/trigger stats (D33). */
-export async function handleWorkflowMetrics(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.metrics requires `id`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const runs = await bundle.runHistory.list(String(p.id));
-    const settled = runs.filter((r) => r.status !== "running");
-    const completed = settled.filter((r) => r.status === "completed");
-    const failed = settled.filter((r) => r.status === "failed");
-    const durations = settled.map((r) => r.durationMs).filter((d) => typeof d === "number");
-    let consecutiveFailures = 0;
-    for (const r of settled) {
-        if (r.status === "failed")
-            consecutiveFailures++;
-        else
-            break;
-    }
-    const byTrigger = {};
-    for (const r of settled)
-        byTrigger[r.triggerType] = (byTrigger[r.triggerType] ?? 0) + 1;
-    if (msg.id !== undefined) {
-        this.sendResponse(msg.id, {
-            metrics: {
-                totalRuns: settled.length,
-                completed: completed.length,
-                failed: failed.length,
-                canceled: settled.filter((r) => r.status === "canceled").length,
-                successRate: settled.length > 0 ? completed.length / settled.length : null,
-                avgDurationMs: durations.length > 0 ? Math.round(durations.reduce((a, b) => a + b, 0) / durations.length) : null,
-                lastRunAt: settled[0]?.startedAt ?? null,
-                consecutiveFailures,
-                byTrigger,
-                windowSize: runs.length,
-            },
-        });
-    }
-}
-// ── Versioning lifecycle (spec D31, IT-8) ──────────────────────────────────────
-/** `workflow.publish` — snapshot the draft as the trigger-run version (D31). */
-export async function handleWorkflowPublish(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.publish requires `id`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    let record;
-    try {
-        record = await bundle.controller.publish(String(p.id));
-    }
-    catch (err) {
-        return fail.call(this, msg, errorMessage(err));
-    }
-    audit(bundle, "published", record.id, { rev: record.publishedRev });
-    emitWorkflowRecord.call(this, "workflow.updated", record, bundle);
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, workflowSnapshot(record, bundle));
-}
-/** `workflow.archive` — keep the data, kill the lifecycle (deactivate + refuse runs). */
-export async function handleWorkflowArchive(msg) {
-    const p = params(msg);
-    if (!p.id || typeof p.archived !== "boolean")
-        return fail.call(this, msg, "workflow.archive requires `id` and boolean `archived`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const record = await bundle.controller.archive(String(p.id), p.archived);
-    await bundle.scheduler.refresh(record.id); // archived ⇒ inactive ⇒ disarm
-    audit(bundle, p.archived ? "archived" : "unarchived", record.id);
-    emitWorkflowRecord.call(this, "workflow.updated", record, bundle);
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, workflowSnapshot(record, bundle));
-}
-// ── Credential vault (spec D29, IT-7) ──────────────────────────────────────────
-// Owner-scoped; list is secret-free; decrypted payloads NEVER cross the RPC face.
-export async function handleCredentialList(msg) {
-    const credentials = new CredentialVault().list();
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { credentials });
-}
-export async function handleCredentialCreate(msg) {
-    const p = params(msg);
-    if (!p.type || !p.label || typeof p.data !== "object" || p.data === null) {
-        return fail.call(this, msg, "credential.create requires `type`, `label`, and `data` object");
-    }
-    try {
-        const summary = new CredentialVault().create({
-            type: p.type,
-            label: String(p.label),
-            data: p.data,
-            meta: p.meta ?? undefined,
-        });
-        if (msg.id !== undefined)
-            this.sendResponse(msg.id, summary);
-    }
-    catch (err) {
-        return fail.call(this, msg, errorMessage(err));
-    }
-}
-export async function handleCredentialDelete(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "credential.delete requires `id`");
-    const deleted = new CredentialVault().delete(String(p.id));
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { ok: deleted });
-}
-/** Pending OAuth dances keyed by `state` (single-process; entries expire after 10 minutes). */
-const pendingOAuth = new Map();
-/**
- * `credential.oauthStart` — create an oauth2 credential (config persisted, token pending) and
- * return the authorize URL the UI opens in the browser. The gateway's /api/oauth/callback lands
- * the code on credential.oauthComplete.
- */
-export async function handleCredentialOauthStart(msg) {
-    const p = params(msg);
-    for (const key of ["label", "authUrl", "tokenUrl", "clientId", "redirectUri"]) {
-        if (typeof p[key] !== "string" || !p[key])
-            return fail.call(this, msg, `credential.oauthStart requires \`${key}\``);
-    }
-    try {
-        const vault = new CredentialVault();
-        const scopes = typeof p.scopes === "string" ? p.scopes : "";
-        const summary = vault.create({
-            type: "oauth2",
-            label: String(p.label),
-            data: {
-                tokenUrl: String(p.tokenUrl),
-                clientId: String(p.clientId),
-                ...(typeof p.clientSecret === "string" && p.clientSecret ? { clientSecret: p.clientSecret } : {}),
-                ...(scopes ? { scopes } : {}),
-            },
-            meta: { ...(scopes ? { scopes } : {}), pending: true },
-        });
-        const state = randomUUID();
-        // Expire stale dances so an abandoned state can't be replayed much later.
-        const now = Date.now();
-        for (const [s, entry] of pendingOAuth)
-            if (entry.expiresAt < now)
-                pendingOAuth.delete(s);
-        pendingOAuth.set(state, {
-            credentialId: summary.id,
-            tokenUrl: String(p.tokenUrl),
-            clientId: String(p.clientId),
-            ...(typeof p.clientSecret === "string" && p.clientSecret ? { clientSecret: p.clientSecret } : {}),
-            redirectUri: String(p.redirectUri),
-            expiresAt: now + 10 * 60_000,
-        });
-        const u = new URL(String(p.authUrl));
-        u.searchParams.set("response_type", "code");
-        u.searchParams.set("client_id", String(p.clientId));
-        u.searchParams.set("redirect_uri", String(p.redirectUri));
-        u.searchParams.set("state", state);
-        if (scopes)
-            u.searchParams.set("scope", scopes);
-        if (msg.id !== undefined)
-            this.sendResponse(msg.id, { credentialId: summary.id, authorizeUrl: u.toString(), state });
-    }
-    catch (err) {
-        return fail.call(this, msg, errorMessage(err));
-    }
-}
-/** `credential.oauthComplete` — exchange the authorization code and store tokens in the vault. */
-export async function handleCredentialOauthComplete(msg) {
-    const p = params(msg);
-    if (typeof p.state !== "string" || typeof p.code !== "string" || !p.state || !p.code) {
-        return fail.call(this, msg, "credential.oauthComplete requires `state` and `code`");
-    }
-    const pending = pendingOAuth.get(p.state);
-    if (!pending || pending.expiresAt < Date.now()) {
-        pendingOAuth.delete(p.state);
-        return fail.call(this, msg, "OAuth state unknown or expired — restart the authorization");
-    }
-    pendingOAuth.delete(p.state);
-    try {
-        const body = new URLSearchParams({
-            grant_type: "authorization_code",
-            code: p.code,
-            redirect_uri: pending.redirectUri,
-            client_id: pending.clientId,
-            ...(pending.clientSecret ? { client_secret: pending.clientSecret } : {}),
-        });
-        const res = await fetch(pending.tokenUrl, {
-            method: "POST",
-            headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
-            body: body.toString(),
-        });
-        const text = await res.text();
-        if (!res.ok)
-            throw new Error(`token exchange failed (${res.status}): ${text.slice(0, 200)}`);
-        const tok = JSON.parse(text);
-        if (!tok.access_token)
-            throw new Error(`token endpoint returned no access_token: ${text.slice(0, 200)}`);
-        const vault = new CredentialVault();
-        const { data } = vault.get(pending.credentialId);
-        vault.updateData(pending.credentialId, {
-            ...data,
-            accessToken: tok.access_token,
-            ...(tok.refresh_token ? { refreshToken: tok.refresh_token } : {}),
-            ...(tok.expires_in ? { expiresAt: new Date(Date.now() + tok.expires_in * 1000).toISOString() } : {}),
-        }, { pending: undefined }); // token 落地 → 不再「待授权」
-        if (msg.id !== undefined)
-            this.sendResponse(msg.id, { ok: true, credentialId: pending.credentialId });
-    }
-    catch (err) {
-        return fail.call(this, msg, errorMessage(err));
-    }
-}
-/**
- * `workflow.setPermissionScope` — the owner's explicit unattended capability grant (D30):
- * which sensitive kinds this workflow may run under schedule/im/webhook triggers.
- */
-export async function handleWorkflowSetPermissionScope(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.setPermissionScope requires `id`");
-    if (p.allowUnattendedKinds !== null && !Array.isArray(p.allowUnattendedKinds)) {
-        return fail.call(this, msg, "workflow.setPermissionScope requires `allowUnattendedKinds` array (or null to revoke)");
-    }
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const scope = p.allowUnattendedKinds === null
-        ? null
-        : {
-            allowUnattendedKinds: p.allowUnattendedKinds.filter((k) => typeof k === "string"),
-            grantedAt: new Date().toISOString(),
-        };
-    const record = await bundle.controller.update(String(p.id), { permissionScope: scope });
-    audit(bundle, scope ? "permissionGranted" : "permissionRevoked", record.id, scope ? { kinds: scope.allowUnattendedKinds } : undefined);
-    emitWorkflowRecord.call(this, "workflow.updated", record, bundle);
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, workflowSnapshot(record, bundle));
-}
-// ── Capability catalog (spec D24, IT-3) ────────────────────────────────────────
-/**
- * `workflow.capabilities` — enumerate the real agents/tools/skills/mcp/memory a workflow in the
- * target project can reference (single source of truth, five consumers: AI builder prompt,
- * "+" suggestions, advanced node library, config dropdowns, Hub requires checks). Channels are
- * gateway-owned: the gateway merges its channel registry into this response in ws-server.
- */
-export async function handleWorkflowCapabilities(msg) {
-    const p = params(msg);
-    let projectRoot;
-    try {
-        projectRoot = resolveWorkflowTarget.call(this, p).cwd;
-    }
-    catch (err) {
-        return fail.call(this, msg, errorMessage(err));
-    }
-    const capabilities = buildCapabilityCatalog({
-        getToolManifest: () => this.toolCatalog.getToolManifest(),
-        listAgentIds: () => [
-            { id: "qlogicagent", name: "小智(默认)" },
-            ...this.acpDetector.list().filter((a) => a.status === "available" && a.id !== "qlogicagent").map((a) => ({ id: a.id, name: a.name })),
-        ],
-        projectRoot,
-    });
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { capabilities });
-}
-// ── Portable bundles: export / import / duplicate (spec D23, IT-1) ─────────────
-/** `workflow.export` — serialize one workflow as a sanitized portable bundle (no credentials). */
-export async function handleWorkflowExport(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.export requires `id`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const record = await bundle.controller.get(String(p.id));
-    const exported = toWorkflowBundle(record);
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { bundle: exported });
-}
-/** Human trigger summary for the Hub gallery card (mirrors the UI's list summary). */
-function summarizeTriggerForHub(trigger) {
-    switch (trigger?.type) {
-        case "schedule": return trigger.cron ? `定时 ${trigger.cron}` : "定时";
-        case "intent": return trigger.phrases?.length ? `口令「${trigger.phrases[0]}」` : "口令触发";
-        case "im-message": return trigger.channel ? `IM 消息 · ${trigger.channel}` : "IM 消息";
-        case "webhook": return trigger.path ? `Webhook ${trigger.path}` : "Webhook";
-        case "form": return "表单触发";
-        case "manual": return "手动触发";
-        default: return undefined;
-    }
-}
-/**
- * `workflow.publishHub` — publish a workflow to the community Hub (IT-5, spec D35):
- * sanitized bundle (D23 — credential values already stripped) becomes the gzip payload;
- * the WorkflowManifest is DERIVED from the record (trigger summary, node count, sensitive
- * capability kinds as declaredPermissions, credential/capability requirements), so the
- * publisher only supplies presentation fields. Same consent + review pipeline as skills.
- */
-export async function handleWorkflowPublishHub(msg) {
-    const p = params(msg);
-    if (!p.id || typeof p.slug !== "string" || !p.slug || typeof p.summary !== "string" || !p.summary.trim()) {
-        return fail.call(this, msg, "workflow.publishHub requires `id`, `slug`, `summary`");
-    }
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const record = await bundle.controller.get(String(p.id));
-    const store = this.resolveCommunityConsentStore?.() ?? createFileCommunityConsentStore();
-    const consent = await store.read();
-    if (!hasMethodSharingConsent(consent)) {
-        return fail.call(this, msg, METHOD_CONSENT_REQUIRED_MESSAGE);
-    }
-    const client = this.resolveCommunityConsentClient ? this.resolveCommunityConsentClient() : createDefaultCommunityConsentClient();
-    if (!client) {
-        return fail.call(this, msg, "Community hub is unavailable (登录后才能发布).");
-    }
-    const exported = toWorkflowBundle(record);
-    const usedKinds = new Set(record.def.nodes.map((n) => n.kind));
-    const manifest = {
-        schema_version: 15,
-        kind: "executable",
-        name: record.name,
-        summary: String(p.summary).trim(),
-        description: typeof p.description === "string" && p.description.trim() ? p.description.trim() : String(p.summary).trim(),
-        entry: "bundle.json",
-        declaredPermissions: [...usedKinds].filter((k) => SENSITIVE_KINDS.has(k)).sort(),
-        ...(summarizeTriggerForHub(record.trigger) ? { triggerSummary: summarizeTriggerForHub(record.trigger) } : {}),
-        nodeCount: record.def.nodes.length,
-        ...(exported.credentialsRequired.length > 0 ? { credentialsRequired: exported.credentialsRequired.map((c) => c.label) } : {}),
-        ...(exported.requires.length > 0 ? { capabilityRequires: exported.requires.map((r) => `${r.category}:${r.ref}`) } : {}),
-        ...(Array.isArray(p.tags) && p.tags.length > 0 ? { tags: p.tags.filter((t) => typeof t === "string") } : {}),
-    };
-    try {
-        const result = await client.publishWorkflow({
-            id: String(p.slug),
-            title: record.name,
-            summary: String(p.summary).trim(),
-            visibility: p.visibility === "private" ? "private" : "public",
-            ...(typeof p.category === "string" && p.category ? { category: p.category } : {}),
-            ...(Array.isArray(p.tags) ? { tags: p.tags.filter((t) => typeof t === "string") } : {}),
-            manifest,
-            version: typeof p.version === "string" && p.version.trim() ? p.version.trim() : "1.0.0",
-            packageGzipBase64: gzipSync(Buffer.from(JSON.stringify(exported), "utf8")).toString("base64"),
-        });
-        audit(bundle, "publishedToHub", record.id, { slug: String(p.slug), visibility: p.visibility === "private" ? "private" : "public" });
-        if (msg.id !== undefined)
-            this.sendResponse(msg.id, { ok: true, ...result });
-    }
-    catch (err) {
-        return fail.call(this, msg, `workflow.publishHub: ${errorMessage(err)}`);
-    }
-}
-/**
- * `workflow.import` — materialize a portable bundle (or raw n8n JSON, format:"n8n") into a target
- * project. The caller creates/owns the project (frontend: WorkspaceStep → POST /api/projects);
- * this RPC only lands the workflow. fail-loud on malformed payloads (§1.5).
- */
-export async function handleWorkflowImport(msg) {
-    const p = params(msg);
-    if (!p.payload)
-        return fail.call(this, msg, "workflow.import requires `payload`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    // targetWorkflowId lands the import ONTO an existing record (an automation project's primary
-    // workflow, seeded empty at project birth) instead of creating a sibling — keeps "one
-    // automation = one project = one primary workflow" (D21) without orphaned empties.
-    const targetWorkflowId = typeof p.targetWorkflowId === "string" && p.targetWorkflowId ? p.targetWorkflowId : undefined;
-    const id = targetWorkflowId ?? String(p.id ?? `wf_${randomUUID().slice(0, 8)}`);
-    let record;
-    // IT-11:n8n 导入产转换报告(完全/部分/需人工,逐项降级明细)随响应返回给导入向导。
-    let n8nReport;
-    // Malformed payloads are caller input → INVALID_PARAMS response, not a dispatcher crash.
-    try {
-        if (p.format === "n8n") {
-            if (targetWorkflowId) {
-                const converted = convertN8nWorkflow(p.payload, id);
-                n8nReport = converted.report;
-                record = await bundle.controller.update(id, { name: String(p.name ?? converted.name), def: converted.def });
-            }
-            else {
-                const imported = await bundle.controller.importN8n(id, p.payload, { owner: resolveActiveOwnerUserId() });
-                record = imported.record;
-                n8nReport = imported.report;
-                if (p.name)
-                    record = await bundle.controller.update(id, { name: String(p.name) });
-            }
-        }
-        else {
-            const parsed = fromWorkflowBundle(p.payload);
-            if (targetWorkflowId) {
-                record = await bundle.controller.update(id, {
-                    name: String(p.name ?? parsed.name),
-                    def: { ...parsed.def, id },
-                    ...(parsed.concurrency ? { concurrency: parsed.concurrency } : {}),
-                });
-            }
-            else {
-                record = await bundle.controller.create({
-                    id,
-                    name: String(p.name ?? parsed.name),
-                    owner: resolveActiveOwnerUserId(),
-                    def: { ...parsed.def, id },
-                    concurrency: parsed.concurrency,
-                });
-            }
-            if (parsed.trigger) {
-                const outcome = await bundle.controller.patch(id, { patch: [{ op: "set_trigger", trigger: parsed.trigger }] });
-                if (!outcome.ok)
-                    throw new Error(`trigger rejected: ${JSON.stringify("errors" in outcome ? outcome.errors : outcome)}`);
-                record = await bundle.controller.get(id);
-            }
-        }
-    }
-    catch (err) {
-        return fail.call(this, msg, `workflow.import: ${errorMessage(err)}`);
-    }
-    audit(bundle, "imported", record.id, { format: p.format === "n8n" ? "n8n" : "bundle", ...(n8nReport ? { conversion: n8nReport.status } : {}) });
-    emitWorkflowRecord.call(this, targetWorkflowId ? "workflow.updated" : "workflow.created", record, bundle);
-    if (msg.id !== undefined) {
-        this.sendResponse(msg.id, { ...workflowSnapshot(record, bundle), ...(n8nReport ? { conversionReport: n8nReport } : {}) });
-    }
-}
-/**
- * `workflow.duplicate` — copy a workflow (same graph/trigger, fresh id, inactive) into a target
- * project: export→import in-process (one serialization path, spec D23). 复制/另存为 both land here.
- */
-export async function handleWorkflowDuplicate(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.duplicate requires `id`");
-    const source = targetBundle.call(this, msg, p);
-    if (!source)
-        return;
-    let target;
-    try {
-        target = p.targetProjectId
-            ? ensureWorkflowRoot.call(this, resolveWorkflowTarget.call(this, { projectId: p.targetProjectId }))
-            : source;
-    }
-    catch (err) {
-        return fail.call(this, msg, errorMessage(err));
-    }
-    const record = await source.controller.get(String(p.id));
-    const exported = toWorkflowBundle(record);
-    const newId = `wf_${randomUUID().slice(0, 8)}`;
-    let created = await target.controller.create({
-        id: newId,
-        name: String(p.name ?? `${record.name} 副本`),
-        owner: resolveActiveOwnerUserId(),
-        def: { ...exported.def, id: newId },
-        concurrency: record.concurrency,
-    });
-    if (exported.trigger) {
-        const outcome = await target.controller.patch(newId, { patch: [{ op: "set_trigger", trigger: exported.trigger }] });
-        if (!outcome.ok)
-            throw new Error(`workflow.duplicate: trigger rejected: ${JSON.stringify("errors" in outcome ? outcome.errors : outcome)}`);
-        created = await target.controller.get(newId);
-    }
-    audit(target, "duplicated", newId, { sourceWorkflowId: String(p.id) });
-    emitWorkflowRecord.call(this, "workflow.created", created, target);
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, workflowSnapshot(created, target));
-}
-// ── Trigger entry points (M3): driven by the openclaw gateway over ACP (D7/B) ──
-// The gateway owns the event sources (IM inbound pipeline, webhook HTTP routes) and forwards them
-// here; every root's scheduler runs its active workflows whose trigger matches (multi-root, D21).
-// Outcomes are returned for observability (the gateway does not block on them for delivery).
-export async function handleWorkflowOnImMessage(msg) {
-    const p = params(msg);
-    if (!p.channel || typeof p.text !== "string")
-        return fail.call(this, msg, "workflow.onImMessage requires `channel` and string `text`");
-    const bundles = ensureAllWorkflowRoots.call(this);
-    const outcomes = [];
-    const errors = [];
-    for (const bundle of bundles) {
-        // 单个 run 的失败(权限拒/图错)fail-loud 进响应 errors,绝不挂死整个分发 RPC。
-        try {
-            outcomes.push(...await bundle.scheduler.onImMessage(String(p.channel), p.text, p.payload));
-        }
-        catch (err) {
-            errors.push({ ...projectTag(bundle), error: errorMessage(err) });
-        }
-    }
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { outcomes, ...(errors.length > 0 ? { errors } : {}) });
-}
-export async function handleWorkflowOnWebhook(msg) {
-    const p = params(msg);
-    if (!p.path)
-        return fail.call(this, msg, "workflow.onWebhook requires `path`");
-    const hookPath = String(p.path).startsWith("/") ? String(p.path) : `/${String(p.path)}`;
-    const payload = p.payload ?? {};
-    // D34 wait-until-webhook:先唤醒挂起的等待分支(同一个 path 既能唤醒在飞 run,也能触发新 run
-    // —— 两个语义并存不冲突;唤醒数随响应返回供观测)。
-    const waiters = pendingWebhookWaits.get(hookPath);
-    const woken = waiters ? waiters.size : 0;
-    if (waiters)
-        for (const wake of [...waiters.values()])
-            wake(payload);
-    const bundles = ensureAllWorkflowRoots.call(this);
-    const outcomes = [];
-    const errors = [];
-    for (const bundle of bundles) {
-        // 单个 run 的失败(IT-7b 权限拒/图错)fail-loud 进响应 errors,绝不挂死整个分发 RPC。
-        try {
-            outcomes.push(...await bundle.scheduler.onWebhook(hookPath, p.payload));
-        }
-        catch (err) {
-            errors.push({ ...projectTag(bundle), error: errorMessage(err) });
-        }
-    }
-    if (msg.id !== undefined) {
-        this.sendResponse(msg.id, { outcomes, ...(errors.length > 0 ? { errors } : {}), ...(woken > 0 ? { wokenWaits: woken } : {}) });
-    }
-}
-/**
- * `workflow.onIntent` — fire an intent-triggered run (spec D22). The MATCH already happened
- * (deterministic phrases client-side; semantic fallback via x/workflow.matchIntent) and the user
- * confirmed; this entry point only verifies the workflow really has an ACTIVE intent trigger
- * (fail-loud otherwise — a stale client must not run a disarmed workflow) and starts the run with
- * the utterance as `$trigger` payload.
- */
-export async function handleWorkflowOnIntent(msg) {
-    const p = params(msg);
-    if (!p.workflowId || typeof p.text !== "string")
-        return fail.call(this, msg, "workflow.onIntent requires `workflowId` and string `text`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const workflowId = String(p.workflowId);
-    const record = await bundle.controller.get(workflowId);
-    if (!record.active || record.trigger?.type !== "intent") {
-        return fail.call(this, msg, `workflow "${workflowId}" has no active intent trigger (active=${record.active}, trigger=${record.trigger?.type ?? "none"})`);
-    }
-    const payload = {
-        type: "intent",
-        text: p.text,
-        ...(typeof p.surface === "string" ? { surface: p.surface } : {}),
-        ...(typeof p.matchedPhrase === "string" ? { matchedPhrase: p.matchedPhrase } : {}),
-    };
-    this.sendNotification("workflow.runStarted", { workflowId, triggerType: "intent", ...projectTag(bundle) });
-    let outcome;
-    try {
-        outcome = await bundle.controller.run(workflowId, { type: "intent", payload });
-        emitWorkflowRunCompleted.call(this, bundle, outcome, "intent");
-    }
-    catch (err) {
-        this.sendNotification("workflow.runFailed", { workflowId, triggerType: "intent", error: errorMessage(err), ...projectTag(bundle) });
-        throw err;
-    }
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, outcome);
-}
-/** All ACTIVE intent-triggered workflows across the active root + automation projects (D22 索引源). */
-export async function collectActiveIntentWorkflows() {
-    const bundles = ensureAllWorkflowRoots.call(this);
-    const out = [];
-    for (const bundle of bundles) {
-        for (const rec of await bundle.store.listActive()) {
-            if (rec.trigger?.type === "intent") {
-                out.push({ workflowId: rec.id, projectId: bundle.projectId, name: rec.name, trigger: rec.trigger });
-            }
-        }
-    }
-    return out;
-}
-/**
- * `workflow.intentIndex` — the deterministic-match index the CLIENT consumes (phrases/aliases/
- * confirm/surfaces per active intent workflow). The frontend matches utterances locally with zero
- * latency (spec D22); semantic fallback goes through x/workflow.matchIntent.
- */
-export async function handleWorkflowIntentIndex(msg) {
-    const intents = await collectActiveIntentWorkflows.call(this);
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { intents });
-}
-// ── Revision history + run history (闭环 "察/退" 半场) ──────────────────────
-/** `workflow.revisions` — newest-first def-revision summaries for the undo/history UI. */
-export async function handleWorkflowRevisions(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.revisions requires `id`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const revisions = await bundle.store.listRevisions(String(p.id));
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { revisions });
-}
-/** `workflow.revert` — re-apply a stored revision as a NEW rev (git-revert semantics). */
-export async function handleWorkflowRevert(msg) {
-    const p = params(msg);
-    if (!p.id || typeof p.rev !== "number")
-        return fail.call(this, msg, "workflow.revert requires `id` and numeric `rev`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const record = await bundle.controller.revertTo(String(p.id), p.rev);
-    // The reverted snapshot may carry a different trigger/active state → re-arm the scheduler.
-    await bundle.scheduler.refresh(record.id);
-    audit(bundle, "reverted", record.id, { toRev: p.rev });
-    emitWorkflowRecord.call(this, "workflow.updated", record, bundle);
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, workflowSnapshot(record, bundle));
-}
-/**
- * `workflow.audit` — newest-first config/lifecycle audit entries (D38: who did what when).
- * Runs are NOT here (runHistory is the run audit); a timeline UI merges both.
- */
-export async function handleWorkflowAudit(msg) {
-    const p = params(msg);
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const limit = typeof p.limit === "number" && p.limit > 0 ? Math.min(p.limit, 500) : 100;
-    const entries = bundle.audit.list(p.id ? String(p.id) : undefined, limit);
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { entries });
-}
-/** `workflow.runs` — newest-first run summaries (status/trigger/timing; outputs stay behind runDetail). */
-export async function handleWorkflowRuns(msg) {
-    const p = params(msg);
-    if (!p.id)
-        return fail.call(this, msg, "workflow.runs requires `id`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const runs = await bundle.runHistory.list(String(p.id));
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { runs });
-}
-/** `workflow.runDetail` — one run incl. per-node output previews (画布点节点看产出). */
-export async function handleWorkflowRunDetail(msg) {
-    const p = params(msg);
-    if (!p.id || !p.runId)
-        return fail.call(this, msg, "workflow.runDetail requires `id` and `runId`");
-    const bundle = targetBundle.call(this, msg, p);
-    if (!bundle)
-        return;
-    const run = await bundle.runHistory.get(String(p.id), String(p.runId));
-    if (!run)
-        return fail.call(this, msg, `run "${String(p.runId)}" not found for workflow "${String(p.id)}"`);
-    if (msg.id !== undefined)
-        this.sendResponse(msg.id, { run });
-}