taskmeld 0.1.1

package/dist/src/pipeline/execution/service.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createExecutionService = void 0;
+const run_state_helpers_1 = require("./run-state-helpers");
+const session_registry_1 = require("./session-registry");
+const route_item_manager_1 = require("./route-item-manager");
+const structured_node_runner_1 = require("./structured-node-runner");
+const state_1 = require("../state");
+const reject_handler_1 = require("./reject-handler");
+const run_abort_controller_1 = require("./run-abort-controller");
+const node_runner_1 = require("./node-runner");
+const group_item_executor_1 = require("./group-item-executor");
+const node_item_executor_1 = require("./node-item-executor");
+const ctx = (reason, extra) => ({ reason, ...extra });
+/**
+ * 流水线执行器。
+ * 负责：节点的具体执行逻辑、状态转换、产物管理。
+ * 不负责：调度决策、并发控制。
+ */
+const createExecutionService = (deps) => {
+    let activeBatchKeywordItems = null;
+    const runAbortController = (0, run_abort_controller_1.createRunAbortController)();
+    const state = (0, run_state_helpers_1.createRunStateHelpers)({
+        runtimeStore: deps.runtimeStore,
+        graph: deps.graph,
+        defaultItemKeys: deps.defaultItemKeys,
+    });
+    const { getRun, getNodeById, getGroupById, getItemRun, getGroupItemRun, computeInitialItemStatus, computeInitialGroupItemStatus, ensureGroupItemKeyInitialized, ensureItemRuns, ensureItemKeyInitialized, getEffectiveDependencyIdsForNodeItem, collectDownstreamSubgraph, resetNodeForReplay, } = state;
+    const routeItemManager = (0, route_item_manager_1.createRouteItemManager)({
+        runtimeStore: deps.runtimeStore,
+        graph: deps.graph,
+        state,
+    });
+    const structuredNodeRunner = (0, structured_node_runner_1.createStructuredNodeRunner)({
+        client: deps.client,
+        runtimeStore: deps.runtimeStore,
+        graph: deps.graph,
+        artifactDir: deps.artifactDir,
+        pipelineId: deps.pipelineId,
+        pipelineNodeExecutionTimeoutMs: deps.pipelineNodeExecutionTimeoutMs,
+        getNodeById,
+        getRun,
+        getActiveBatchKeywordItems: () => activeBatchKeywordItems,
+        getBatchRunId: deps.getBatchRunId,
+    });
+    const sessionRegistry = (0, session_registry_1.createSessionRegistry)({
+        client: deps.client,
+        pushTimeline: deps.runtimeStore.pushTimeline,
+        getKnownExecutorIds: () => {
+            const ids = new Set();
+            for (const node of getRun().nodes) {
+                ids.add(node.executor.agentId);
+                if (node.executor.fallbackAgentId)
+                    ids.add(node.executor.fallbackAgentId);
+            }
+            return ids;
+        },
+    });
+    // ====== Helper: 重置受影响的 downstream ======
+    const resetAffectedDownstreamNodes = (params) => {
+        const run = getRun();
+        const affected = collectDownstreamSubgraph(params.targetNodeId);
+        const skipSet = new Set(params.skipNodeIds ?? []);
+        for (const affectedNode of run.nodes) {
+            if (!affected.nodeIds.has(affectedNode.id))
+                continue;
+            if (skipSet.has(affectedNode.id))
+                continue;
+            resetNodeForReplay(affectedNode, { clearRejectFeedbacks: affectedNode.id !== params.targetNodeId });
+        }
+        for (const affectedGroup of run.groups ?? []) {
+            if (!affected.groupIds.has(affectedGroup.id))
+                continue;
+            (0, state_1.markGroupReset)(affectedGroup, computeInitialGroupItemStatus(affectedGroup.id), ctx("reset_downstream"));
+            affectedGroup.artifacts = [];
+        }
+        for (const affectedItem of run.itemRuns ?? []) {
+            if (!affected.nodeIds.has(affectedItem.nodeId))
+                continue;
+            if (skipSet.has(affectedItem.nodeId))
+                continue;
+            if (params.itemKey && affectedItem.itemKey !== params.itemKey)
+                continue;
+            (0, state_1.markItemReset)(affectedItem, computeInitialItemStatus(affectedItem.nodeId), ctx("reset_downstream"));
+            affectedItem.route = null;
+            affectedItem.artifacts = [];
+        }
+        for (const affectedGroupItem of run.groupItemRuns ?? []) {
+            if (!affected.groupIds.has(affectedGroupItem.groupId))
+                continue;
+            if (params.itemKey && affectedGroupItem.itemKey !== params.itemKey)
+                continue;
+            (0, state_1.markGroupItemReset)(affectedGroupItem, computeInitialGroupItemStatus(affectedGroupItem.groupId), ctx("reset_downstream"));
+            affectedGroupItem.artifacts = [];
+        }
+        return { affectedNodeCount: affected.nodeIds.size, affectedGroupCount: affected.groupIds.size };
+    };
+    // ====== Node runner ======
+    const nodeRunner = (0, node_runner_1.createNodeRunner)({
+        runtimeStore: deps.runtimeStore,
+        getRun,
+        structuredNodeRunner,
+        sessionRegistry,
+        runAbortController,
+        handleNodeReject: reject_handler_1.handleNodeReject,
+        resetAffectedDownstreamNodes,
+        artifactDir: deps.artifactDir,
+        pipelineId: deps.pipelineId,
+        getBatchRunId: deps.getBatchRunId,
+    });
+    // ====== Node item executor ======
+    const nodeItemExecutor = (0, node_item_executor_1.createNodeItemExecutor)({
+        runtimeStore: deps.runtimeStore,
+        graph: deps.graph,
+        nodeRunner,
+        routeItemManager,
+        getRun,
+        getNodeById,
+        getEffectiveDependencyIdsForNodeItem,
+    });
+    const executeNodeItem = nodeItemExecutor.executeNodeItem;
+    // ====== Group item executor ======
+    const groupItemExecutor = (0, group_item_executor_1.createGroupItemExecutor)({
+        runtimeStore: deps.runtimeStore,
+        graph: deps.graph,
+        artifactDir: deps.artifactDir,
+        pipelineId: deps.pipelineId,
+        getBatchRunId: deps.getBatchRunId,
+        getRun,
+        getNodeById,
+        getGroupById,
+        getItemRun,
+        ensureItemKeyInitialized,
+        getEffectiveDependencyIdsForNodeItem,
+        executeNodeItem,
+    });
+    return {
+        getExecutorSessionByAgentId: sessionRegistry.getExecutorSessionByAgentId,
+        getSessionCache: sessionRegistry.getSessionCache,
+        refreshSessionsFromGateway: sessionRegistry.refreshSessionsFromGateway,
+        setActiveBatchKeywordItems: (items) => {
+            activeBatchKeywordItems = items;
+        },
+        onGatewayFrame: (frame) => {
+            structuredNodeRunner.rememberGatewayFrame(frame);
+            sessionRegistry.onGatewayFrame(frame);
+        },
+        hasActiveSession: (sessionKey) => {
+            return structuredNodeRunner.hasActiveSession?.(sessionKey) ?? false;
+        },
+        dispose: () => {
+            sessionRegistry.dispose();
+        },
+        ensureItemKeyInitialized,
+        ensureGroupItemKeyInitialized,
+        getEffectiveDependencyIdsForNodeItem,
+        resetAffectedDownstreamNodes,
+        executeNode: nodeRunner.executeNode,
+        executeNodeItem,
+        executeGroupItem: groupItemExecutor.executeGroupItem,
+        abortRunControllers: (runId) => runAbortController.abortRunControllers(runId, deps.client),
+        getOrCreateDrainSignal: (runId) => runAbortController.getOrCreateDrainSignal(runId),
+    };
+};
+exports.createExecutionService = createExecutionService;

package/dist/src/pipeline/execution/session-registry.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSessionRegistry = void 0;
+const session_1 = require("../../utils/session");
+const array_1 = require("../../utils/array");
+const agent_activity_1 = require("../agent-activity");
+const tool_activity_1 = require("../tool-activity");
+const createSessionRegistry = (options) => {
+    const executorSessionByAgentId = new Map();
+    let sessionCache = [];
+    const envSessionMap = (0, session_1.parseAgentSessionMapFromEnv)();
+    for (const [agentId, sessionId] of Object.entries(envSessionMap)) {
+        executorSessionByAgentId.set(agentId, sessionId);
+    }
+    const inferAgentIdFromSessionId = (sessionId) => {
+        for (const [agentId, mappedSessionId] of executorSessionByAgentId.entries()) {
+            if (mappedSessionId === sessionId)
+                return agentId;
+        }
+        return null;
+    };
+    const agentActivityTracker = (0, agent_activity_1.createAgentActivityTracker)({
+        pushTimeline: options.pushTimeline,
+        resolveAgentBySessionId: inferAgentIdFromSessionId,
+    });
+    const toolActivityLogger = (0, tool_activity_1.createToolActivityLogger)({
+        pushTimeline: options.pushTimeline,
+        resolveAgentBySessionId: inferAgentIdFromSessionId,
+    });
+    const applySessionBindings = (items) => {
+        const known = options.getKnownExecutorIds();
+        for (const item of items) {
+            const agentIds = (0, session_1.inferSessionAgentIds)(item, known);
+            for (const agentId of agentIds) {
+                if (!executorSessionByAgentId.has(agentId)) {
+                    executorSessionByAgentId.set(agentId, item.id);
+                }
+            }
+        }
+        for (const [agentId, sessionId] of Object.entries(envSessionMap)) {
+            executorSessionByAgentId.set(agentId, sessionId);
+        }
+    };
+    const refreshSessionsFromGateway = async () => {
+        const payload = await options.client.sendReq("sessions.list");
+        const items = (0, array_1.pickArray)(payload)
+            .map((item, index) => (0, session_1.normalizeSession)(item, index))
+            .filter((item) => Boolean(item));
+        sessionCache = items;
+        applySessionBindings(items);
+        return { payload, items };
+    };
+    const resolveExecutorSession = async (node) => {
+        const pinnedSessionId = node.executor.sessionId?.trim();
+        if (pinnedSessionId) {
+            return { sessionId: pinnedSessionId, agentId: node.executor.agentId };
+        }
+        const primary = executorSessionByAgentId.get(node.executor.agentId);
+        if (primary) {
+            return { sessionId: primary, agentId: node.executor.agentId };
+        }
+        if (node.executor.fallbackAgentId) {
+            const fallback = executorSessionByAgentId.get(node.executor.fallbackAgentId);
+            if (fallback) {
+                return { sessionId: fallback, agentId: node.executor.fallbackAgentId };
+            }
+        }
+        await refreshSessionsFromGateway();
+        const refreshedPrimary = executorSessionByAgentId.get(node.executor.agentId);
+        if (refreshedPrimary) {
+            return { sessionId: refreshedPrimary, agentId: node.executor.agentId };
+        }
+        if (node.executor.fallbackAgentId) {
+            const refreshedFallback = executorSessionByAgentId.get(node.executor.fallbackAgentId);
+            if (refreshedFallback) {
+                return { sessionId: refreshedFallback, agentId: node.executor.fallbackAgentId };
+            }
+        }
+        return null;
+    };
+    const onGatewayFrame = (frame) => {
+        agentActivityTracker.handleFrame(frame);
+        toolActivityLogger.handleFrame(frame);
+    };
+    return {
+        getExecutorSessionByAgentId: () => executorSessionByAgentId,
+        getSessionCache: () => sessionCache,
+        resolveExecutorSession,
+        refreshSessionsFromGateway,
+        onGatewayFrame,
+        dispose: () => {
+            agentActivityTracker.dispose();
+        },
+    };
+};
+exports.createSessionRegistry = createSessionRegistry;

package/dist/src/pipeline/execution/structured-node-runner.js

@@ -0,0 +1,411 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStructuredNodeRunner = exports.resolveActiveBatchKeywordsForInstruction = void 0;
+const node_events_1 = require("node:events");
+const node_crypto_1 = require("node:crypto");
+const artifact_storage_1 = require("../artifact-storage");
+const structured_output_1 = require("../structured-output");
+const routes_1 = require("../workflow/routes");
+const identity_1 = require("../identity");
+const RUNTIME_KEYWORDS_PLACEHOLDER = "{{RUNTIME_KEYWORDS_JSON}}";
+const injectRuntimeKeywordsToInstruction = (instruction, keywords) => {
+    if (keywords.length === 0)
+        return instruction;
+    const keywordJson = JSON.stringify(keywords, null, 2);
+    if (instruction.includes(RUNTIME_KEYWORDS_PLACEHOLDER)) {
+        return instruction.replaceAll(RUNTIME_KEYWORDS_PLACEHOLDER, keywordJson);
+    }
+    const arrayPattern = /\[\s*(?:"[^"\n]{1,400}"\s*,\s*){10,}"[^"\n]{1,400}"\s*\]/gs;
+    const matchedArray = instruction.match(arrayPattern);
+    if (matchedArray && matchedArray.length > 0) {
+        return instruction.replace(arrayPattern, keywordJson);
+    }
+    return `${instruction}\n\n本批次关键词(JSON数组)：\n${keywordJson}`;
+};
+const resolveActiveBatchKeywordsForInstruction = (activeBatchKeywordItems, isSourceEntryNode) => {
+    // 只有真正处于批跑中的入口节点，才允许把关键词池注入到提示词。
+    // 普通单运行虽然默认 itemKey 可能是 global，但它只是运行项标识，不应被当成批次关键词展示。
+    if (!isSourceEntryNode || !activeBatchKeywordItems || activeBatchKeywordItems.length === 0) {
+        return [];
+    }
+    return Array.from(new Set(activeBatchKeywordItems.map((item) => item.trim()).filter(Boolean)));
+};
+exports.resolveActiveBatchKeywordsForInstruction = resolveActiveBatchKeywordsForInstruction;
+const shouldParseFrameForEnvelope = (frame) => {
+    if (frame.type === "res")
+        return true;
+    if (frame.type === "req")
+        return false;
+    if (frame.type !== "event")
+        return false;
+    if (frame.event === "chat") {
+        const p = frame.payload;
+        const state = typeof p?.state === "string" ? p.state.toLowerCase() : "";
+        if (state === "final" || state === "done" || state === "end" || state === "completed")
+            return true;
+        if (typeof p?.data === "object" && p.data !== null)
+            return true;
+        return false;
+    }
+    if (frame.event === "agent") {
+        const p = frame.payload;
+        const stream = typeof p?.stream === "string" ? p.stream : "";
+        if (stream === "lifecycle")
+            return false;
+        if (stream === "tool" || stream === "item" || stream === "command_output") {
+            if (p && typeof p === "object") {
+                if (p.version === "2.0" && Array.isArray(p.artifacts))
+                    return true;
+                const data = p.data;
+                if (data && typeof data === "object") {
+                    const d = data;
+                    if (d.version === "2.0" && Array.isArray(d.artifacts))
+                        return true;
+                }
+            }
+            return false;
+        }
+        return true;
+    }
+    return false;
+};
+const createStructuredNodeRunner = (options) => {
+    const emitter = new node_events_1.EventEmitter();
+    emitter.setMaxListeners(32);
+    // 同一个 agent session 会复用多轮对话。
+    // 这里按 sessionId + agent runId 记录生命周期，避免上一轮尾部的 end/error 事件误伤下一轮新请求。
+    const sessionRuns = new Map();
+    const findStringByKeys = (value, keys, depth = 0) => {
+        if (depth > 5 || value === null || value === undefined)
+            return null;
+        if (typeof value === "string")
+            return value.trim() || null;
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                const found = findStringByKeys(item, keys, depth + 1);
+                if (found)
+                    return found;
+            }
+            return null;
+        }
+        if (typeof value !== "object")
+            return null;
+        const record = value;
+        for (const key of keys) {
+            const raw = record[key];
+            if (typeof raw === "string" && raw.trim())
+                return raw.trim();
+        }
+        for (const nested of Object.values(record)) {
+            const found = findStringByKeys(nested, keys, depth + 1);
+            if (found)
+                return found;
+        }
+        return null;
+    };
+    const inferLifecycle = (payload) => {
+        const marker = (findStringByKeys(payload, ["status", "state", "phase", "event", "type", "kind"]) ?? "").toLowerCase();
+        if (!marker)
+            return "unknown";
+        if (marker.includes("start") ||
+            marker.includes("running") ||
+            marker.includes("in_progress") ||
+            marker.includes("processing") ||
+            marker.includes("stream")) {
+            return "start";
+        }
+        if (marker.includes("done") ||
+            marker.includes("finish") ||
+            marker.includes("complete") ||
+            marker.includes("success") ||
+            marker.includes("failed") ||
+            marker.includes("error") ||
+            marker.includes("idle") ||
+            marker.includes("stop")) {
+            return "end";
+        }
+        return "unknown";
+    };
+    const rememberSessionRunEvent = (sessionId, runId, lifecycle) => {
+        if (!sessionId || !runId)
+            return;
+        const now = Date.now();
+        const runMap = sessionRuns.get(sessionId) ?? new Map();
+        const current = runMap.get(runId) ?? {
+            firstSeenAt: now,
+            lastSeenAt: now,
+            completedAt: null,
+        };
+        current.firstSeenAt = Math.min(current.firstSeenAt, now);
+        current.lastSeenAt = now;
+        if (lifecycle === "end") {
+            current.completedAt = now;
+        }
+        if (lifecycle === "start") {
+            current.completedAt = null;
+        }
+        runMap.set(runId, current);
+        // 每个 session 只保留最近少量 run 记录，避免长跑时无界增长。
+        // 驱逐前跳过仍在等待确认的活跃 run (completedAt 为 null)，
+        // 防止 resolveCompletedAtForRequest 锁定的 runId 被误删导致超时。
+        const MAX_RUNS_PER_SESSION = 48;
+        if (runMap.size > MAX_RUNS_PER_SESSION) {
+            const now = Date.now();
+            const STALE_GRACE_MS = 5 * 60 * 1000;
+            const staleEntries = [...runMap.entries()]
+                .filter(([, snapshot]) => {
+                if (snapshot.completedAt === null)
+                    return false;
+                return now - snapshot.completedAt > STALE_GRACE_MS;
+            })
+                .sort((a, b) => a[1].lastSeenAt - b[1].lastSeenAt);
+            const overflow = runMap.size - MAX_RUNS_PER_SESSION;
+            for (let i = 0; i < Math.min(overflow, staleEntries.length); i += 1) {
+                runMap.delete(staleEntries[i][0]);
+            }
+        }
+        sessionRuns.set(sessionId, runMap);
+    };
+    const resolveCompletedAtForRequest = (sessionId, requestStartedAt, watch) => {
+        const runMap = sessionRuns.get(sessionId);
+        if (!runMap || runMap.size === 0)
+            return null;
+        if (!watch.lockedRunId) {
+            // 优先锁定"首次出现时间晚于本次请求发出时间"的 runId。
+            // 这样可以避免上一轮请求的尾部 end/error 在新请求刚开始时被错认成当前轮次结束。
+            const currentRun = [...runMap.entries()]
+                .filter(([, snapshot]) => snapshot.firstSeenAt >= requestStartedAt)
+                .sort((a, b) => a[1].firstSeenAt - b[1].firstSeenAt)[0];
+            if (currentRun) {
+                watch.lockedRunId = currentRun[0];
+            }
+        }
+        if (!watch.lockedRunId)
+            return null;
+        const snapshot = runMap.get(watch.lockedRunId);
+        if (!snapshot)
+            return null;
+        if (snapshot.completedAt === null || snapshot.completedAt < requestStartedAt)
+            return null;
+        return snapshot.completedAt;
+    };
+    const rememberSessionCompletion = (frame) => {
+        if (frame.type !== "event")
+            return;
+        const payload = frame.payload;
+        if (!payload)
+            return;
+        const sessionId = findStringByKeys(payload, ["sessionKey", "sessionId", "key", "session"]);
+        const runId = findStringByKeys(payload, ["runId"]);
+        if (!sessionId)
+            return;
+        if (frame.event === "agent") {
+            const stream = typeof payload.stream === "string" ? payload.stream : "";
+            if (stream === "tool" || stream === "item" || stream === "command_output")
+                return;
+        }
+        if (frame.event === "agent") {
+            const stream = typeof payload.stream === "string" ? payload.stream : "";
+            if (stream === "lifecycle") {
+                rememberSessionRunEvent(sessionId, runId, inferLifecycle(payload.data));
+                return;
+            }
+            // assistant/tool/item 等流虽然不代表完成，但能提供当前轮次的 runId。
+            // 这里只做"看见过该 run"的记录，完成仍以 lifecycle/chat.final 为准。
+            rememberSessionRunEvent(sessionId, runId, "unknown");
+            return;
+        }
+        if (frame.event === "chat") {
+            rememberSessionRunEvent(sessionId, runId, "unknown");
+            const state = (findStringByKeys(payload, ["state"]) ?? "").toLowerCase();
+            if (state === "final" || state === "done" || state === "end" || state === "completed") {
+                rememberSessionRunEvent(sessionId, runId, "end");
+            }
+        }
+    };
+    const buildNodePrompt = async (node, sessionId, itemKey, dependencyIds) => {
+        const run = options.getRun();
+        const requestId = (0, identity_1.buildRequestId)(node.id);
+        const effectiveDependencyIds = dependencyIds?.length
+            ? Array.from(new Set(dependencyIds.map((id) => id.trim()).filter(Boolean)))
+            : node.dependsOn;
+        const workflowNode = options.graph.getWorkflowNodeById(node.id);
+        const retryBackoffMs = workflowNode?.retryPolicy.backoffMs ?? 0;
+        const parallelGroup = options.graph.getParallelGroupByMemberNodeId(node.id);
+        // 批处理关键词只应注入真正的入口节点。并行组成员虽然通常没有 direct incoming edge，
+        // 但它们的依赖挂在 group 上，只看 node 自身入边会把 group 成员误判为 source entry。
+        const isSourceEntryNode = options.graph.getIncomingEdges(node.id).length === 0 &&
+            (!parallelGroup || options.graph.getIncomingEdges(parallelGroup.id).length === 0);
+        const effectiveRuntimeKeywordItems = (0, exports.resolveActiveBatchKeywordsForInstruction)(options.getActiveBatchKeywordItems(), isSourceEntryNode);
+        const effectiveInstruction = effectiveRuntimeKeywordItems.length > 0
+            ? injectRuntimeKeywordsToInstruction(node.instruction, effectiveRuntimeKeywordItems)
+            : node.instruction;
+        const dependencyArtifacts = await (0, structured_output_1.buildDependencyArtifactInputs)(run, node, itemKey, effectiveDependencyIds);
+        // Load external pipeline artifact for pipeline_link triggered runs (entry nodes only)
+        let externalPipelineArtifact = null;
+        if (run.input?.trigger === "pipeline_link" && isSourceEntryNode) {
+            externalPipelineArtifact = await (0, structured_output_1.buildExternalPipelineArtifactInput)(run.input.upstreamOutput);
+            if (!externalPipelineArtifact) {
+                throw new Error("external_pipeline_artifact_read_failed");
+            }
+        }
+        if (effectiveDependencyIds.length > 0) {
+            options.runtimeStore.pushTimeline(`节点 ${node.id} 已加载上游产物 ${dependencyArtifacts.length} 条（来自: ${effectiveDependencyIds.join(",")}）`);
+        }
+        const allowedRoutes = workflowNode?.routePolicy?.allowed ?? [];
+        const routeTargets = options.graph.getOutgoingEdges(node.id)
+            .filter((edge) => edge.when && edge.when !== routes_1.MAINLINE_ROUTE_VALUE)
+            .map((edge) => {
+            const targetWorkflowNode = options.graph.getWorkflowNodeById(edge.to);
+            const targetWorkflowGroup = options.graph.getWorkflowGroupById(edge.to);
+            const targetNode = options.getNodeById(edge.to);
+            return {
+                route: edge.when ?? "",
+                targetNodeId: edge.to,
+                targetNodeTitle: targetWorkflowGroup
+                    ? `并行组 ${targetWorkflowGroup.id}`
+                    : targetNode?.title ?? targetWorkflowNode?.name ?? edge.to,
+                targetAgentId: targetWorkflowGroup
+                    ? targetWorkflowGroup.id
+                    : targetNode?.executor.agentId ?? targetWorkflowNode?.executor.agentId ?? "-",
+                lane: targetWorkflowGroup ? "group" : targetWorkflowNode?.lane ?? "main",
+            };
+        });
+        const ctx = {
+            runId: run.id, nodeId: node.id, nodeTitle: node.title,
+            requestId, sessionId,
+            dependencies: effectiveDependencyIds,
+            dependencyArtifacts,
+            externalPipelineArtifact,
+            outputSpec: node.outputSpec,
+            instruction: effectiveInstruction,
+            allowReject: node.allowReject,
+            maxRejectCount: node.maxRejectCount,
+            rejectFeedbacks: node.rejectFeedbacks ?? [],
+            allowedRoutes, routeTargets,
+        };
+        return { requestId, ctx, effectiveDependencyIds, dependencyArtifacts, allowedRoutes, routeTargets, retryBackoffMs };
+    };
+    const sendAndWaitForEnvelope = async (prompt, sessionId, nodeId, validationCtx, lastViolation, requestStartedAt, requestRunWatch, signal) => {
+        // DAG 节点发送只保留 chat.send 单一路径，避免不同发送 API 的兼容补发把同一 requestId 投递两次。
+        const idempotencyKey = (0, node_crypto_1.randomUUID)();
+        let payload;
+        try {
+            payload = await options.client.sendReq("chat.send", { sessionKey: sessionId, message: prompt }, {
+                sideEffect: true,
+                timeoutMs: options.pipelineNodeExecutionTimeoutMs,
+                idempotencyKey,
+            });
+        }
+        catch (error) {
+            options.runtimeStore.pushTimeline(`节点 ${nodeId} 发送失败(chat.send): ${String(error)}`, "error");
+            throw new Error(`openclaw_send_failed:chat.send:${String(error)}`);
+        }
+        options.runtimeStore.pushTimeline(`节点 ${nodeId} 已发送请求，等待结构化回执...`);
+        const envelope = await (0, structured_output_1.waitForStructuredEnvelope)(emitter, validationCtx, lastViolation, () => resolveCompletedAtForRequest(sessionId, requestStartedAt, requestRunWatch), signal);
+        return envelope;
+    };
+    const validateAndRetryEnvelope = async (ctx, sessionId, node, allowedRoutes, retryBackoffMs = 0, signal) => {
+        const validationCtx = {
+            runId: ctx.runId,
+            nodeId: node.id,
+            requestId: ctx.requestId,
+            sessionId,
+            outputSpec: node.outputSpec,
+            allowedRoutes,
+            requireRouteContent: allowedRoutes.length > 0,
+        };
+        let lastViolation = null;
+        // 纠错重试属于同一次节点请求的补正，不应更换 requestId。
+        // 否则模型即使按上一轮上下文修正成功，也会因为顶层 requestId 变化被误判为 mismatch。
+        for (let attemptIndex = 0; attemptIndex < 2; attemptIndex += 1) {
+            if (attemptIndex > 0 && retryBackoffMs > 0) {
+                await new Promise(resolve => setTimeout(resolve, retryBackoffMs));
+            }
+            try {
+                const requestStartedAt = Date.now();
+                const requestRunWatch = { lockedRunId: null };
+                const prompt = attemptIndex === 0 || !lastViolation
+                    ? (0, structured_output_1.createNodeExecutionPrompt)(ctx)
+                    : (0, structured_output_1.createNodeCorrectionPrompt)(ctx, lastViolation);
+                const envelope = await sendAndWaitForEnvelope(prompt, sessionId, node.id, validationCtx, lastViolation, requestStartedAt, requestRunWatch, signal);
+                return envelope;
+            }
+            catch (error) {
+                const violation = (0, structured_output_1.extractViolationCode)(error);
+                if (violation) {
+                    lastViolation = violation;
+                    if (attemptIndex === 0) {
+                        options.runtimeStore.pushTimeline(`节点 ${node.id} 回执校验失败(${violation})，自动纠正重试中...`, "warn");
+                        continue;
+                    }
+                    options.runtimeStore.pushTimeline(`节点 ${node.id} 回执校验失败(${violation})，纠正后仍未通过，标记失败`, "error");
+                }
+                throw error;
+            }
+        }
+        throw new Error(`contract_violation:${lastViolation ?? "result_envelope_missing"}`);
+    };
+    const persistEnvelopeArtifacts = async (envelope, runId, nodeId, requestId, sessionId) => {
+        const savedAt = new Date();
+        const status = envelope.status === "failed" ? "failed" : "success";
+        const batchRunId = options.getBatchRunId?.();
+        // envelope 文件通过 persistEnvelopeFile 写入并追加索引
+        await (0, artifact_storage_1.persistEnvelopeFile)(options.artifactDir, status, { runId, batchRunId, nodeId, requestId, pipelineId: options.pipelineId }, envelope, { savedAt });
+        const normalizedArtifacts = [];
+        for (let i = 0; i < envelope.artifacts.length; i += 1) {
+            const artifact = envelope.artifacts[i];
+            const safeType = artifact.type.replace(/[^a-zA-Z0-9._-]/g, "_");
+            const manifest = await (0, artifact_storage_1.persistArtifactFile)(options.artifactDir, status, {
+                runId,
+                pipelineId: options.pipelineId,
+                batchRunId,
+                nodeId,
+                requestId,
+                kind: "artifact",
+            }, {
+                type: artifact.type,
+                schemaVersion: artifact.schemaVersion,
+                name: artifact.name ?? `artifact-${i + 1}`,
+                content: artifact.content,
+                meta: artifact.meta,
+            }, { savedAt, fileNameSuffix: `${i + 1}-${safeType}` });
+            normalizedArtifacts.push(manifest);
+        }
+        return normalizedArtifacts;
+    };
+    const runNodeViaStructuredOutput = async (node, sessionId, itemKey, dependencyIds, signal) => {
+        const { requestId, ctx, allowedRoutes, retryBackoffMs } = await buildNodePrompt(node, sessionId, itemKey, dependencyIds);
+        const envelope = await validateAndRetryEnvelope(ctx, sessionId, node, allowedRoutes, retryBackoffMs, signal);
+        const artifacts = await persistEnvelopeArtifacts(envelope, ctx.runId, node.id, requestId, sessionId);
+        return { envelope, artifacts };
+    };
+    const rememberGatewayFrame = (frame) => {
+        if (frame.type === "req")
+            return;
+        if (shouldParseFrameForEnvelope(frame)) {
+            const source = frame.type === "event" ? `event:${frame.event}` : "res";
+            const candidates = (0, structured_output_1.collectEnvelopeCandidates)(frame.payload);
+            const now = Date.now();
+            for (const envelope of candidates) {
+                emitter.emit("candidate", { envelope, observedAt: now, source });
+            }
+        }
+        rememberSessionCompletion(frame);
+    };
+    return {
+        runNodeViaStructuredOutput,
+        rememberGatewayFrame,
+        hasActiveSession: (sessionKey) => {
+            const runMap = sessionRuns.get(sessionKey);
+            if (!runMap || runMap.size === 0)
+                return false;
+            for (const snapshot of runMap.values()) {
+                if (snapshot.completedAt === null)
+                    return true;
+            }
+            return false;
+        },
+    };
+};
+exports.createStructuredNodeRunner = createStructuredNodeRunner;